[vaind]

Coding-job pods need to git clone a branch, and Seer needs to fetch and push, without either holding a provider credential (Git transport for coding jobs, CW-2221). Both sides of Sentry's new git endpoint depend on sentry-scm, so what they share goes in a new scm.git module: Seer signs grants with it, and Sentry's endpoint (CW-2222) verifies them and relays with it.

Third of three stacked PRs, after #157 and #158; this diff is only scm.git.

Flow

flowchart LR
    pod[git client] -->|git request| proxy[Credential proxy]
    proxy -->|same request + grant| server["Sentry git endpoint (GitServer)"]
    server -->|same request + token| provider[GitHub, GitLab or Origin]

Loading

The pod holds neither the grant nor a token: the credential proxy adds the grant (getsentry/sandbox-router#153, getsentry/sandbox-router#154), and the endpoint swaps it for a token. The response streams back the same way.

For each request, GitServer:

1. verifies the grant, and checks the route and repository against it;
2. looks up the repository and asks its provider for the clone URL;
3. gets a token from Sentry and relays the request with it.

A request the grant doesn't allow is refused at step 1, so it never reaches the database, a credential or the provider. Refusals are plain text and never a 401, because git asks for credentials on a 401.

Approach

• Grants (grant.py): HS256 JWTs, the format Sentry and Seer already sign viewer contexts with, naming an organization, a referrer, one operation (fetch or push), RepositoryIds, an expiry and a version. The referrer says who the grant is for, e.g. a coding job or Seer itself, and tags the endpoint's metrics, since git requests carry nothing else that tells callers apart. The aud keeps other tokens signed with the same secret from passing as grants, and the kid header lets secrets rotate. Unknown claims or versions are refused, so an older verifier never reads a newer grant as allowing more. sign_grant refuses a grant over 4096 characters (GRANT_MAX_LENGTH), the limit getsentry/sandbox-router#153 enforces because the grant travels in a request header, so an oversized grant fails in Seer's tests rather than at the router. Adds PyJWT.
• Relay (relay.py): maps the four smart-HTTP routes to fetch or push and refuses anything else (authorize_request), then streams both bodies without buffering or parsing them, passes only git's own headers, accepts only https remotes, never follows redirects, and drops requests' exceptions so the Authorization header can't reach an error report. Each request gets its own connection, so nothing one organization leaves on a connection, such as a cookie or an unread response, reaches another's. The caller passes an adapter factory, so Sentry can use BlacklistAdapter to refuse internal addresses. Proxy, CA and .netrc settings aren't read from the environment, since through a proxy that check would see the proxy's address; ca_bundle replaces REQUESTS_CA_BUNDLE.
• GitServer (server.py): runs the steps above, as RpcServer does for the RPC endpoint, and counts each request and its bytes when its response stream ends. Refusals and provider failures are also passed to emit_error, with what the request had resolved (organization, repository, operation, provider, remote host) as tags, since the message the client sees leaves out where the request was going. The token comes from a GetToken callable, so Sentry's token getters now and a central token mint later plug in unchanged.

Not in this PR

• Sentry's endpoint (CW-2222).
• Honouring verify_ssl=False (CW-2224): certificates are always verified.
• Git LFS, and caps on size, duration and concurrency (CW-2225).

Tests

• Grants that are expired, tampered with, signed with another or a rotated secret, or malformed.
• Every route and grant combination.
• The relay against a local HTTPS server: headers and streamed bodies in each direction, a connection per request, cookies, redirects, timeouts, untrusted certificates, plain-http remotes, and no token in any error. The streaming and connection tests were checked to fail when the relay buffers, shares a session or leaves a connection open.
• The server's check order and metrics.

The starting point was grant.py and parts of scm_git_endpoint.py in getsentry/sandbox-router#145.

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f21a127. Configure here.}

[cmanallen]

Initial review. I'll review again in the AM.

[cmanallen]

Any reason not to require now and always dependency inject it?

[vaind]

I kept it optional. Every production caller wants the wall clock, and making now required puts time.time() at each Sentry and Seer call site, where passing milliseconds or a stale value would quietly mint bad grants. The grant tests now pin now everywhere, since the new iat check would otherwise break them once the real clock passed their fixed NOW. Happy to make it required if you'd rather.

🤖 Addressed by Claude Code

[cmanallen]

I'll may not be able to make another pass until tomorrow. Depends on how quick the feedback turnaround is.

[cmanallen]

Because of HTTP header limits, consider abbreviating these fields. For example oid for organization_id, op for operation, etc. The repositories field is arbitrary size so this limit is possible to hit regardless but its typical to shorten field names in JWTs. Up to you.

[vaind]

I'd keep the names. Each appears once per grant, so shortening all of them saves about 70 characters after base64, roughly one repository's worth out of the 4096 limit. A grant grows with its repositories, about 50 characters each for a typical path, so the names don't move how many repositories fit, and the full names keep a decoded grant readable when debugging.

🤖 Addressed by Claude Code

[cmanallen]

How much does this map matter? Since git is the client we only need to honor its contract. If git doesn't care about a status code we could simplify this. This isn't a blocking request but it would simplify the file for later viewers.

[vaind]

For git itself, only one thing matters: never a 401, which makes git ask for credentials. Any other error status just fails the command and shows our text body as remote: .... The separate codes are there for the people and tools around it: access logs and dashboards can tell a refused grant (403) from a missing repository (404) or a provider failure (502), and a caller deciding whether to retry can treat 503/504 as transient and 403 as final. So I'd keep the map, but it could collapse to one refusal status and one failure status if you'd rather have fewer lines.

🤖 Addressed by Claude Code

[cmanallen]

A docstring is not a contract. If check_request must be called before entering this method we should enforce the request's correctness here.

[vaind]

The relay can't check the grant itself: it never sees one, since GitServer verifies the grant a layer up and passes only the remote and the token. What the relay does enforce in forward, whatever the caller did, is what keeps the token safe: an https remote and one of the four git routes. In 7c8dd13 the docstring says that instead of reading like a precondition, and names GitServer as the one that authorizes the request first.

🤖 Addressed by Claude Code

[cmanallen]

This is better named map_request_to_operation or similar.

[vaind]

Renamed to authorize_request in 7c8dd13. It returns the operation, but it also refuses the request unless the grant allows the operation and the repository, so a name that only says "map" would undersell it. The docstring now leads with both.

🤖 Addressed by Claude Code

[cmanallen]

If these values aren't configurable why bother making them constants? They could be inlined into the function.

[vaind]

Inlined the clock skew, which had one use, as PyJWT's leeway with its comment (7c8dd13). I kept the other three, because each is used in two places that must agree: GRANT_AUDIENCE and _ALGORITHM by both signing and verifying, and _JWT_CLAIMS as the claims PyJWT requires and the ones kept out of the Grant.

🤖 Addressed by Claude Code