[vaind]

Porting Sentry and Seer to the Ed25519 grants from #170 found gaps that should be fixed before 3.0.0:

• A bad key raised plain ValueError/TypeError from the same calls that parse untrusted grants, so callers couldn't tell their own misconfiguration apart from a bad or oversized grant.
• There was no helper to make a key, so bin/git-server and every test suite copied the same cryptography calls.
• Three permanent failures answered 502, which Seer's checkout (getsentry/seer#9229) retries for about a minute before failing.

Follow-up to #170 (CW-2334).

Approach

• New scm.errors.GitGrantKeyError(SCMError, ValueError) for every bad key, on both sides. It isn't an SCMCodedError, because a bad key is the server's fault: GitServer raises it from its constructor rather than answering requests with a 403. An oversized grant still raises a plain ValueError.
• New require_private_key(Secret) -> Secret, the signer's counterpart to require_public_keys, to check a key at startup.
• New generate_private_key() -> Secret, which replaces the copied cryptography calls in bin/git-server and make_key_pair.
• GitServer answers git_remote_not_https, git_remote_refused and resource_certificate_invalid with a 500 instead of a 502. The integration or host is misconfigured, so no retry helps. 502 still means the provider or the token failed; 503 and 504 still mean a retry can succeed.
• GetToken and GitServer now document that get_token may raise a coded error, which GitServer answers by its code. Sentry relies on this to answer an unreachable control silo with a 503.

Not included, as decided: a public key_id(), or reporting which key matched a grant.

Release notes

Craft uses this section for the changelog in place of the title. The last item covers earlier PRs whose titles don't show a breaking change.

Changelog Entry

• Raise GitGrantKeyError for a missing or unusable git grant key, so callers can tell their own misconfiguration apart from a bad grant
  • It's a ValueError, not an SCMCodedError. A public key that isn't a string used to raise TypeError.
  • verify_grant([], token) raises it. 2.x refused the grant with GitInvalidGrant (a 403 from GitServer).
• Add require_private_key to check a signing key at startup, and generate_private_key to make one for tests
• Answer a remote that isn't https, a refused remote host and an untrusted TLS certificate with a 500 instead of a 502, since no retry can fix them
• Document that get_token may raise a coded error, which GitServer answers by its code, e.g. ResourceServiceUnavailable as a 503
• Upgrade notes for earlier 3.0.0 changes
  • GitServer's get_token must return an scm.Secret, or every relayed request fails with TypeError (#167).
  • Once Sentry maps RestrictedIPAddress to GitRemoteRefused with GitRelay(map_error=...), its refusal of internal addresses changes from a 503 to a 500 (#168).

Tests

Each bad-key case raises GitGrantKeyError on both sides, and no message quotes the key. That check also now works for multi-line keys: it used to join the lines, so it never matched RSA, EC or Ed448 keys. A generated key round-trips through sign_grant, public_key_of and verify_grant. New GitServer tests cover the three 500s and a coded and an uncoded error from get_token. The suite, ruff, mypy and prek pass, and I smoke-tested bin/git-server's key loading.

🤖 Generated with Claude Code