Add Cloudmux-scoped session credential leases

[lawrencecchen]

Summary

• Add an admin-authenticated Cloudmux session-lease endpoint that selects a concrete Subrouter account, provider, and model.
• Return a 15-minute opaque broker capability plus the Pi provider configuration needed for openai-codex-responses.
• Pin leased traffic to the selected account and model, restrict it to the provider model endpoint, and exchange the broker token for the provider credential only inside Subrouter.
• Support Codex subscription and API-key accounts plus Claude, Kimi, and ZAI API-compatible routes without exposing provider credentials.

Lease contract

POST /internal/v1/session-leases requires the configured Subrouter admin bearer token for network callers. Loopback remains available for local self-hosting.

Request:

{
  "organizationId": "organization-1",
  "workspaceId": "workspace-1",
  "conversationId": "conversation-1",
  "invocationId": "invocation-1",
  "agentSessionId": "agent-session-1",
  "agent": "pi",
  "provider": "codex",
  "model": "openai/gpt-5.4",
  "proxyBaseUrl": "http://subrouter:31415"
}

provider, model, and proxyBaseUrl are optional. Provider aliases are normalized, provider-prefixed models are normalized, and conflicting provider/model prefixes are rejected.

Codex response shape:

{
  "leaseId": "lease_<random>",
  "sessionKey": "agent-session-1",
  "expiresAt": "2026-07-11T12:15:00Z",
  "environment": {
    "CLOUDMUX_SUBROUTER_LEASE_TOKEN": "<three-segment SRLEASE capability>",
    "OPENAI_API_KEY": "<same capability>",
    "OPENAI_BASE_URL": "http://subrouter:31415/v1"
  },
  "assignment": {
    "accountId": "<selected Subrouter account>",
    "provider": "codex",
    "authMode": "oauth",
    "model": "gpt-5.4",
    "reason": "subrouter_scheduler"
  },
  "pi": {
    "provider": "cloudmux-subrouter",
    "api": "openai-codex-responses",
    "baseUrl": "http://subrouter:31415/backend-api",
    "apiKeyEnvironmentVariable": "CLOUDMUX_SUBROUTER_LEASE_TOKEN",
    "model": "gpt-5.4"
  }
}

Anthropic-compatible assignments return ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_BASE_URL instead. DELETE /internal/v1/session-leases/<leaseId> is authenticated and idempotent.

The capability is accepted as an OpenAI-compatible bearer token, an Anthropic-compatible X-Api-Key, or an explicit X-Subrouter-Lease header.

Security model

• The capability has three JWT-shaped segments only because Pi decodes a ChatGPT account claim before sending a request.
• The header marker is typ: "SRLEASE". The payload marker is cloudmux_session_lease: true.
• The ChatGPT claim is the constant synthetic value cloudmux-broker. The selected upstream account ID and provider credentials never appear in the token.
• Each token contains a random 144-bit nonce and a random 256-bit signature segment.
• Public fields are identification hints, not authorization. Subrouter authorizes only an exact SHA-256 token-hash lookup in its in-memory lease store.
• Header and payload segments use unpadded standard base64 because Pi currently calls atob directly. The random third segment uses base64url.
• Broker capabilities expire after 15 minutes, are revoked by DELETE, and disappear on Subrouter restart.
• Network mint and revoke operations fail closed when no admin token is configured.
• A leased request is pinned to its account, provider, session, and assigned model. It can call only the matching model API endpoint.
• Tokens and provider credentials are neither persisted nor logged.

Testing

• go test ./...
• go vet ./...
• go test -race ./internal/proxy -run 'SessionLease|PresentedSessionLease' -count=1

All checks pass. Behavior coverage includes admin authentication, OAuth and API-key proxy exchange, Pi-compatible claim decoding, credential and upstream-account non-disclosure, idempotent minting, random nonce/signature uniqueness, forged-signature rejection, ordinary provider JWT pass-through, endpoint/model restriction, revocation, and expiration.

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

---

Summary by cubic

Add Cloudmux session credential leases to broker 15‑minute, invocation-scoped tokens that pin traffic to a selected account/provider/model without exposing provider credentials. Enables Pi to use codex and Anthropic-compatible routes safely.

• New Features

  • Admin-only POST /internal/v1/session-leases mints a lease and returns env vars + Pi config; optional provider, model, proxyBaseUrl; normalizes aliases; idempotent per invocation scope.
  • DELETE /internal/v1/session-leases/{leaseId} revokes (idempotent); leases expire after 15 minutes and are cleared on restart.
  • Proxy accepts the lease via Authorization bearer, X-Api-Key, or X-Subrouter-Lease; swaps it for the selected account credential inside Subrouter, pins account/provider/model, and restricts calls to the provider’s model endpoint.
  • Supported routes: codex OpenAI-compatible /v1/* and Anthropic-compatible messages for Claude, Kimi, and ZAI.

• Migration

  • Set AdminToken, call POST to mint a lease, keep the returned env in memory, use the provided baseUrl and model, and send DELETE on cleanup.
  • Reacquire a lease after 15 minutes or on Subrouter restart; existing non-lease traffic continues to work.

^{Written for commit ae7b593. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c461836c-8227-443a-8af5-dfa48cc09c62

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat-cloudmux-leases

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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