feat: support online gateway sandbox JWT key rotation
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 8.7k
- Forks
- 1.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 253
Description
Problem Statement
Gateway-minted sandbox JWTs include a kid, but the gateway currently loads one signing key and one matching public verification key at startup. Rotation today requires replacing or deleting the JWT key Secret, letting certgen recreate key material, and restarting gateway pods. That invalidates outstanding supervisor tokens and gives operators no online rotation window.
Proposed Design
Add first-class online rotation support for gateway sandbox JWT keys:
- Load multiple verification keys keyed by
kid. - Mark one key as the active signing key.
- Accept still-valid sandbox JWTs signed by configured verify-only keys during a bounded rotation window.
- Provide an operator-facing rotation flow, such as a
rotate-jwttask, command, or Helm hook, that creates a new active key without deleting the old verification key immediately. - Document the rotation procedure, rollback behavior, and expected impact on active supervisors.
Alternatives Considered
The current delete-Secret-and-restart approach is simple, but it is disruptive and invalidates all active supervisor tokens at once. Keeping only short TTLs limits exposure but does not provide a safe operational rotation path. A multi-key verifier keyed by kid matches the existing JWT header shape and allows deliberate overlap between old and new keys.
Agent Investigation
PR #1404 added gateway-minted per-sandbox JWTs. Follow-up review noted that crates/openshell-server/src/auth/sandbox_jwt.rs and certgen currently support only one active keypair despite emitting kid. architecture/gateway.md now documents the current offline rotation behavior; this issue tracks the long-term online rotation implementation.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with crates/openshell-server/src/auth/sandbox_jwt.rs, certgen, and architecture/gateway.md to understand the current single-key loading and offline rotation flow. Trace how the gateway selects signing and verification keys, then define an operator rotation path with bounded overlap, rollback behavior, and documented supervisor-token impact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- authentication, backend-api-design, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100