feat(git): Add git grants and a streaming git relay

README.md

@@ -12,10 +12,11 @@ The SCM (Source Code Management) platform is a vendor-agnostic abstraction layer
 
 ### Features
 
-The platform exposes three subsystems:
+The platform exposes four subsystems:
 
 - **Actions** — outbound SCM operations initiated by Sentry code. The `SourceCodeManager` class provides 70+ methods covering comments, reactions, pull requests, branches, git objects, reviews, and check runs. With more actions planned to be added as we port more use cases.
 - **Actions RPC** - outbound SCM commands exposed over the network. The `SourceCodeManager` is fully available over the network. This enables usage of the SCM for services outside the monolith.
+- **Git relay** - `git` fetches and pushes for services that hold no provider credentials. Seer signs a grant naming the organization, operation and repositories with `scm.git.grant.sign_grant`, and `scm.git.server.GitServer` checks each git smart-HTTP request against it before relaying the request to the provider with a token, streaming both bodies.
 - **Event Stream** — inbound webhook processing. SCM service-providers push events which are deserialized into typed, provider-neutral dataclasses (`CheckRunEvent`, `CommentEvent`, `PullRequestEvent`) which are then dispatched to registered listener functions.
 
 ### Why

pyproject.toml

@@ -11,7 +11,11 @@ authors = [
 requires-python = ">=3.13"
 dependencies = [
     "msgspec>=0.19.0",
+    "pyjwt>=2.9.0",
     "requests>=2.32.4",
+    # The git relay streams responses through urllib3 directly. Before 2.8.0, a server could make its chunked
+    # reader buffer without limit (GHSA-vxq7-64xx-v4gw).
+    "urllib3>=2.8.0",
 ]
 
 [build-system]
@@ -50,6 +54,7 @@ select = [
 
 [dependency-groups]
 dev = [
+    "cryptography>=48.0.1",
     "mypy>=1.20.0",
     "prek>=0.3.6",
     "pyjwt[crypto]>=2.9.0",

src/scm/errors.py

@@ -1,6 +1,15 @@
 from typing import ClassVar, Literal
 
 type ErrorCode = Literal[
+    "git_grant_expired",
+    "git_invalid_grant",
+    "git_operation_not_granted",
+    "git_provider_not_supported",
+    "git_remote_not_https",
+    "git_repository_not_granted",
+    "git_route_not_supported",
+    "git_token_rejected",
+    "git_token_unavailable",
     "malformed_external_id",
     "missing_repository_path",
     "path_is_directory",
@@ -26,6 +35,7 @@
     "resource_unprocessable_content",
     "resource_server_error",
     "resource_bad_gateway",
+    "resource_certificate_invalid",
     "resource_service_unavailable",
     "resource_gateway_timeout",
     "unexpected_response_format",
@@ -38,6 +48,15 @@
 ]
 
 ERROR_CODES: dict[ErrorCode, str] = {
+    "git_grant_expired": "The git grant has expired.",
+    "git_invalid_grant": "The git grant was missing, malformed or forged.",
+    "git_operation_not_granted": "The git grant does not allow this operation.",
+    "git_provider_not_supported": "The repository's provider has no git remote.",
+    "git_remote_not_https": "The repository's git remote is not an https URL.",
+    "git_repository_not_granted": "The git grant does not cover this repository.",
+    "git_route_not_supported": "The request is not a git fetch or push.",
+    "git_token_rejected": "The provider rejected Sentry's credentials for the repository.",
+    "git_token_unavailable": "No provider token could be obtained for the repository.",
     "malformed_external_id": "The repository's external ID was malformed.",
     "missing_repository_path": "No path was given for the repository.",
     "path_is_directory": "The requested path is a directory, not a file.",
@@ -63,6 +82,7 @@
     "resource_unprocessable_content": "Request could not be processed.",
     "resource_server_error": "The service-provider encountered an internal error.",
     "resource_bad_gateway": "The service-provider returned an invalid response from an upstream gateway.",
+    "resource_certificate_invalid": "The service-provider's TLS certificate could not be verified.",
     "resource_service_unavailable": "The service-provider is temporarily unavailable. The request can be retried.",
     "resource_gateway_timeout": "The service-provider did not respond in time. The request can be retried.",
     "unexpected_response_format": "The response format was in an unexpected format.",
@@ -125,6 +145,46 @@ def from_code(cls, code: ErrorCode, detail: str | None = None) -> "SCMCodedError
         return error_cls(detail=detail)
 
 
+class GitSCMCodedError(SCMCodedError):
+    """Base class for the errors of the git endpoint (``scm.git``), so a caller can catch them all at once."""
+
+
+class GitGrantExpired(GitSCMCodedError):
+    code = "git_grant_expired"
+
+
+class GitInvalidGrant(GitSCMCodedError):
+    code = "git_invalid_grant"
+
+
+class GitOperationNotGranted(GitSCMCodedError):
+    code = "git_operation_not_granted"
+
+
+class GitProviderNotSupported(GitSCMCodedError):
+    code = "git_provider_not_supported"
+
+
+class GitRemoteNotHttps(GitSCMCodedError):
+    code = "git_remote_not_https"
+
+
+class GitRepositoryNotGranted(GitSCMCodedError):
+    code = "git_repository_not_granted"
+
+
+class GitRouteNotSupported(GitSCMCodedError):
+    code = "git_route_not_supported"
+
+
+class GitTokenRejected(GitSCMCodedError):
+    code = "git_token_rejected"
+
+
+class GitTokenUnavailable(GitSCMCodedError):
+    code = "git_token_unavailable"
+
+
 class MalformedExternalId(SCMCodedError):
     code = "malformed_external_id"
 
@@ -233,6 +293,10 @@ class ResourceBadGateway(SCMCodedError):
     code = "resource_bad_gateway"
 
 
+class ResourceCertificateInvalid(SCMCodedError):
+    code = "resource_certificate_invalid"
+
+
 class ResourceServiceUnavailable(SCMCodedError):
     code = "resource_service_unavailable"
 

src/scm/git/grant.py

@@ -0,0 +1,102 @@
+"""Signing and verifying git grants.
+
+A grant travels as an HS256 JWT, the format Sentry and Seer already sign viewer contexts with. The grant's fields
+are claims, alongside ``exp``, ``iat`` and an ``aud`` of ``scm-git-grant``. The verifier requires that audience,
+so no other token signed with the same secret, such as a viewer context, passes as a grant. A ``kid`` header
+names the secret that signed the grant, as in Sentry's viewer contexts, so the verifier can hold several secrets
+while they rotate.
+"""
+
+import hashlib
+import time
+from typing import Any
+
+import jwt
+import msgspec
+
+from scm.errors import GitGrantExpired, GitInvalidGrant
+from scm.git.types import GRANT_MAX_LENGTH, Grant
+
+GRANT_AUDIENCE = "scm-git-grant"
+_ALGORITHM = "HS256"
+# Claims the JWT layer owns. Every other claim must be a Grant field.
+_JWT_CLAIMS = frozenset({"aud", "exp", "iat"})
+
+
+def sign_grant(secret: str, grant: Grant, *, now: float | None = None) -> str:
+    # HMAC accepts an empty key, so an empty secret, say from an unset setting, would let anyone sign a grant.
+    if not secret:
+        raise ValueError("A git grant secret is empty.")
+    claims: dict[str, Any] = msgspec.to_builtins(grant)
+    claims["exp"] = claims.pop("expires_at")
+    claims["iat"] = int(time.time() if now is None else now)
+    claims["aud"] = GRANT_AUDIENCE
+    token = jwt.encode(claims, secret, algorithm=_ALGORITHM, headers={"kid": _key_id(secret)})
+    # Refused here, the signer's tests catch a grant that is too long, rather than the sandbox router in production.
+    if len(token) > GRANT_MAX_LENGTH:
+        raise ValueError(
+            f"The git grant is {len(token)} characters, over GRANT_MAX_LENGTH ({GRANT_MAX_LENGTH}). It travels in a "
+            "request header, and sandbox-router refuses a longer one."
+        )
+    return token
+
+
+def verify_grant(secrets: list[str], token: str, *, now: float | None = None) -> Grant:
+    """Return the grant if one of ``secrets`` signed it and it has not expired.
+
+    Verification takes a list of secrets, as ``RpcServer`` does, so a new secret can be added before signers
+    switch to it and the old one removed after their grants expire.
+    """
+    # As in sign_grant: a grant signed with an empty secret proves nothing.
+    if not all(secrets):
+        raise ValueError("A git grant secret is empty.")
+    now = time.time() if now is None else now
+    if not token:
+        raise GitInvalidGrant(detail="The git grant is missing.")
+    try:
+        kid = jwt.get_unverified_header(token).get("kid")
+    except jwt.DecodeError:
+        raise GitInvalidGrant(detail="The git grant is malformed.") from None
+    secret = next((secret for secret in secrets if _key_id(secret) == kid), None)
+    if secret is None:
+        raise GitInvalidGrant(detail="The git grant was not signed with a known secret.")
+
+    try:
+        claims = jwt.decode(
+            token,
+            secret,
+            algorithms=[_ALGORITHM],
+            audience=GRANT_AUDIENCE,
+            # exp is checked below against an injectable clock, so tests can pin it. PyJWT checks iat, which it
+            # also requires to be a number.
+            options={"require": sorted(_JWT_CLAIMS), "verify_exp": False},
+            # How far in the future iat may be, in seconds. Seer signs grants on other hosts than the one verifying
+            # them, and a clock running a little ahead should not get its grants refused.
+            leeway=60,
+        )
+    except jwt.InvalidSignatureError:
+        raise GitInvalidGrant(detail="The git grant's signature does not match.") from None
+    except jwt.DecodeError:
+        raise GitInvalidGrant(detail="The git grant is malformed.") from None
+    except jwt.InvalidTokenError as e:
+        # The signature matched or was never reached, and PyJWT's reasons name only claims, not values.
+        raise GitInvalidGrant(detail=f"The git grant is invalid: {e}") from None
+
+    fields = {name: value for name, value in claims.items() if name not in _JWT_CLAIMS}
+    try:
+        grant = msgspec.convert({**fields, "expires_at": claims["exp"]}, type=Grant, strict=True)
+    except msgspec.ValidationError as e:
+        # The signature matched, so a holder of the secret wrote these claims; telling them why they are invalid
+        # gives nothing away.
+        raise GitInvalidGrant(detail=f"The git grant's payload is invalid: {e}") from None
+
+    if grant.expires_at <= now:
+        raise GitGrantExpired(detail="The git grant has expired.")
+    if not grant.repositories:
+        raise GitInvalidGrant(detail="The git grant names no repositories.")
+    return grant
+
+
+def _key_id(secret: str) -> str:
+    # The first 8 hex characters of the secret's SHA-256, the same key id Sentry's viewer contexts use.
+    return hashlib.sha256(secret.encode()).hexdigest()[:8]