docs(mcp): decide stateless profile context

[mohanagy]

Resolves #364
Parent: #362
Follow-ups: #376, #377

Outcome

Records the fail-closed design for modern stateless profile routing and adds a non-shipping executable prototype.

• Rejects mutable defaults, clientInfo identity, sticky sessions, and unvalidated routing metadata.
• Selects an opaque short-lived profile-context handle bound to verified issuer, subject, audience, per-chat context, and deployment.
• Requires cross-instance key/revocation consistency, bearer-free audit correlation, and a documented locked/profile-scoped fallback.
• Inventories current session-owned profile, approval, OAuth/identity, routing, audit, subscription, and upstream state.
• Tracks the trusted auth boundary in [Security] Bind stateless profile context to trusted per-chat authentication claims #376 and production handle implementation in [Profiles] Implement opaque cross-instance stateless profile-context handles #377.

The prototype stays under tests and is excluded by the npm files allowlist.

Validation

• npm exec vitest run tests/stateless-profile-context-prototype.test.ts tests/stateless-profile-context-docs-contract.test.ts
• npm test: 148 files, 1,853 passed, 34 skipped
• npm run typecheck
• npm run lint
• npm run build
• npm run check:pack: 52 files
• npm ci audit: 0 vulnerabilities

External contract

• https://blog.modelcontextprotocol.io/posts/2026-07-28/
• SEP-2575: Make MCP Stateless modelcontextprotocol/modelcontextprotocol#2575
• SEP-2567: Sessionless MCP via Explicit State Handles modelcontextprotocol/modelcontextprotocol#2567

Summary by CodeRabbit

• New Features

  • Added a prototype for encrypted, short-lived profile access handles.
  • Added support for profile switching, renewal, and cross-instance revocation.
  • Added validation for identity, deployment, profile, expiration, and revocation constraints.

• Security

  • Invalid, expired, or revoked handles fail safely with distinct errors.
  • Sensitive handles and details are protected from exposure in results and errors.

• Tests

  • Added coverage for isolation, binding, expiration boundaries, revocation, and documented security requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 296ded57-389e-4c08-84eb-1055bb13f17d

📥 Commits

Reviewing files that changed from the base of the PR and between f1c8cca and 3fd4343.

📒 Files selected for processing (4)

• docs/plans/2026-08-11-stateless-profile-context-decision.md
• tests/prototypes/stateless-profile-context.ts
• tests/stateless-profile-context-docs-contract.test.ts
• tests/stateless-profile-context-prototype.test.ts

---

📝 Walkthrough

Walkthrough

This change documents a stateless profile-context decision, adds an AES-256-GCM prototype for authenticated profile handles, and adds contract and behavior tests for binding, isolation, expiry, revocation, redaction, and rollout requirements.

Changes

Stateless profile context

Layer / File(s)	Summary
Decision and rollout contract docs/plans/2026-08-11-stateless-profile-context-decision.md	Defines encrypted profile handles, authenticated chat binding, lifecycle and revocation rules, rejected alternatives, compatibility behavior, follow-ups, required tests, and a rollout stop rule.
Prototype contracts and lifecycle tests/prototypes/stateless-profile-context.ts	Adds context, error, revocation, option, and result contracts. Adds APIs to mint, resolve, and revoke profile handles.
Handle sealing and validation tests/prototypes/stateless-profile-context.ts	Adds AES-256-GCM sealing, HMAC identity binding, strict payload validation, base64url handling, constant-time comparison, and sanitized invalid-context errors.
Contract and prototype validation tests/stateless-profile-context-docs-contract.test.ts, tests/stateless-profile-context-prototype.test.ts	Tests documented security and compatibility requirements, cross-instance and cross-chat isolation, identity and deployment binding, expiry, revocation, redaction, audit correlation, backend failure normalization, and tamper handling.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AuthenticatedRequest
  participant StatelessProfileContextPrototype
  participant ProfileContextRevocations
  AuthenticatedRequest->>StatelessProfileContextPrototype: mint profile handle
  StatelessProfileContextPrototype-->>AuthenticatedRequest: encrypted handle
  AuthenticatedRequest->>StatelessProfileContextPrototype: resolve handle with authenticated context
  StatelessProfileContextPrototype->>ProfileContextRevocations: check revocation
  ProfileContextRevocations-->>StatelessProfileContextPrototype: status
  StatelessProfileContextPrototype-->>AuthenticatedRequest: resolved profile and audit correlation

Loading

Possibly related issues

• #377: The changes implement opaque cross-instance profile-context handles with binding, expiry, revocation, isolation, and fail-closed validation.
• #376: The prototype implements authenticated per-chat binding, revocation, and cross-chat isolation.
• #362: The decision and prototype address stateless-request account isolation, profile binding, cross-instance routing, and legacy compatibility.

Poem

A rabbit guards each context tight,
With encrypted handles out of sight.
Across two chats, profiles stay,
Expired paths are turned away.
Revoked keys no longer spring,
Safe stateless requests now sing. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the outcome and validation, but it omits the required Security impact section and several required validation results.	Add a Security impact section and record exact results for every required validation item, including applicable checklist entries.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation decision for stateless profile context, which is the main change.
Linked Issues check	✅ Passed	The decision, prototype, and tests address [#364]'s routing safety, binding, redaction, compatibility, UX, and follow-up requirements.
Out of Scope Changes check	✅ Passed	All changes support [#364] through decision documentation, a non-shipping prototype, and targeted contract and behavior tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/364-stateless-profile-context

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/plans/2026-08-11-stateless-profile-context-decision.md`:
- Around line 15-23: Define an authenticated key-epoch field or envelope header
for the selected handle format, and specify how instances select keys from the
keyring during rotation. Document the active and previously valid epochs,
overlap period, and validation rules so unexpired handles remain resolvable
while new handles use the current epoch.

In `@tests/prototypes/stateless-profile-context.ts`:
- Around line 150-170: Update resolvePayload and revoke to normalize all
unexpected failures to the fixed PROFILE_CONTEXT_INVALID error. Wrap
authentication validation, payload opening and validation, and
revocations.isRevoked/revocations.revoke calls so empty or non-string inputs and
backend exceptions cannot escape unchanged; preserve only the explicit
PROFILE_CONTEXT_EXPIRED and PROFILE_CONTEXT_REVOKED errors.

In `@tests/stateless-profile-context-prototype.test.ts`:
- Around line 58-83: Add issuer and audience mismatch rejection cases alongside
the existing identity and deployment checks in the “binds every resolution…”
test, using modified authenticated contexts and expecting
PROFILE_CONTEXT_INVALID. Add a cross-chat revoke attempt for a handle owned by
another chat, assert that revoke is rejected, then resolve that handle
successfully to verify the shared revocation state was unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a5691fff-04dd-4e36-a094-6f3771e469df

📥 Commits

Reviewing files that changed from the base of the PR and between 3940383 and f1c8cca.

📒 Files selected for processing (4)

• docs/plans/2026-08-11-stateless-profile-context-decision.md
• tests/prototypes/stateless-profile-context.ts
• tests/stateless-profile-context-docs-contract.test.ts
• tests/stateless-profile-context-prototype.test.ts