feat(api-keys): self-usage status with limits, shared quota providers, anthropic header policy, and key details page

[fouadSalkini]

Summary

Makes GET /v1/me/status a complete self-service view for an API key holder, lets the admin decide which providers' account quota a key may see, adds a per-key policy for the upstream anthropic-ratelimit-* headers, and gives the dashboard the matching controls plus a per-key details page.

GET /v1/me/status (additive — every existing field keeps its shape)

• usage.daily / usage.weekly (UTC calendar day / ISO week): USD cost (same recorded-cost source as budgets), request count, and a token breakdown (input / output / cache read / cache creation / reasoning / total).
• limits[]: one entry per enforced per-key limit — daily/weekly USD usage limits, budget, token limits (global / provider / model), key quota (tpm / rpm / monthly USD). Each entry carries used, limit, remaining, utilization (0..1), exceeded, and periodStartAt / resetAt taken from that enforcer's own window, so the numbers match what actually blocks the key. A source that fails to read is omitted and logged instead of failing the response.
• accountQuotas (scope self:account-quota):
  • limited to the providers the admin shares with the key (sharedQuotaProviders: null = all reachable providers, the default; [] = none);
  • each account has a label — the connection's display name, with email-like values masked (a raw email is never returned);
  • quotas are served from the provider-limits cache (refresh only when older than 5 min, at most once per connection per 60 s, in-flight deduped), with fetchedAt and stale.
• generatedAt, and the endpoint now accepts x-api-key as well as Authorization: Bearer.

Per-key settings

New table api_key_self_service_settings (migration 190) with sharedQuotaProviders and anthropicRateLimitHeaders. Missing row/table reads as the defaults (null, "auto"); a corrupt stored list fails closed to []. Managed through PATCH /api/keys/[id] and the new management routes GET / PUT /api/keys/[id]/self-service (the GET also returns an admin preview of the key's status body and the providers the key can reach).

Upstream anthropic-ratelimit-* header policy

Streaming responses forward every upstream header not on the denylist, so pooled Claude accounts' anthropic-ratelimit-unified-* utilization/status headers and anthropic-organization-id currently reach any API key holder. In gateway mode Claude Code acts on those headers (limit warnings, blocking), even though they describe whichever pooled account happened to serve the request.

Per key, anthropicRateLimitHeaders:

• auto (default): forward only when the key shares account quota (self:account-quota), the serving provider is in its shared providers, and the key is pinned to exactly one connection; otherwise strip.
• forward / strip: always / never.

Requests without an API key and the env key (OMNIROUTE_API_KEY / ROUTER_API_KEY, the deployment owner) keep forwarding. Non-streaming and error paths are unchanged (they never forwarded these headers).

Behavior change: under the default auto, keys that reach several connections no longer receive the upstream Anthropic rate-limit headers on streaming responses. Set the key to forward to keep the old behavior.

Dashboard

• API key permissions modal: provider picker for shared account quota (shown while the scope is on) and the header mode (always editable).
• Each key row links to a new details page /dashboard/api-manager/[id]: today's and this week's usage, every limit with a utilization bar and reset time, shared account quota cards (masked label, plan, windows, last update, stale badge), and immediate-save editors for key-holder visibility, shared providers + header mode, the USD usage limit, key quota (tpm / rpm / monthly USD) and token limits (add / edit / delete). The token-limit and key-quota APIs existed without any UI before.
• 123 new strings, translated into all 66 locales (additive diff).

Tests

• New: tests/unit/api-key-self-service-limits.test.ts, tests/unit/api-key-self-service-accounts.test.ts, tests/unit/api-key-self-service-settings.test.ts, tests/unit/anthropic-account-header-policy.test.ts, tests/unit/api-key-self-usage-dashboard-data.test.ts, tests/unit/ui/api-key-self-usage-dashboard.test.tsx; extended tests/unit/api-key-self-service.test.ts and tests/unit/api-key-policy.test.ts (settings merged into apiKeyInfo; env key keeps forwarding — written red first).
• Focused node suites (self-service, policy, api-manager, /v1/me/status route, streaming header strip / budget / fix(sse): Codex quota headers leak the selected pool/combo account's quota to the caller #14116 leak tests): 155/155 pass. Vitest UI (api-key-self-usage-dashboard, api-manager-loading-status-12066): 9/9. Migration suites (numbering, uniqueness, runner): 77/77.
• npm run typecheck:core, check-dashboard-typecheck, ESLint (with suppressions), Prettier, check:cycles, check-db-rules, check:openapi-routes, check:openapi-coverage (702/718 → documents the new routes), check:any-budget:t11, check-docs-sync, check-migration-numbering: clean.
• i18n: check-ui-keys-coverage, check-translation-ratio, check-ui-value-drift, check-new-key-coverage, zh-CN glossary: pass.

Inherited failures (reproduced on a clean worktree of the base tip 3bfe5fe8a2, same counts — not introduced here)

• Unit fast-path: settings-i18n-keys (1), proxyfetch-upstream-status-capture (1), chatcore-upstream-timeouts (1), combo-responses-sse-failure-fallback (4), i18n-glossary-consistency-check (2), check-docs-counts-sync (1); CI-only build/mcp-bundle-startup and pack-artifact-policy.
• Docs Gates: README / AGENTS.md / llm.txt say "183 migrations"; the base already has 185 (this PR adds one more).
• check:mutation-test-coverage --strict: open-sse/handlers/chatCore/passthroughHelpers.ts → tests/unit/claude-passthrough-empty-response.test.ts missing from stryker.conf.json.
• check-file-size: src/sse/handlers/chat.ts, src/sse/services/auth.ts, open-sse/executors/default.ts, open-sse/translator/response/openai-responses.ts (same sizes on the base tip 66f5b2aa0f).
• check-key-completeness: bs is missing 16 combos.* keys; zh-TW glossary: combos.advancedHelp.connectionAwareExpansion uses 供應商.

Fixed in this PR after the first CI run: complexity ratchet (dashboard editors split into components/hooks, normalizeDeps reduced to a loader table — per-file violations on touched files are now ≤ base), stryker.conf.json entry for the new header-policy test, and check:agent-skills-sync.

Agent-instruction surface: skills/omni-api-keys/SKILL.md and skills/omni-inference/SKILL.md are regenerated by scripts/skills/generate-agent-skills.mjs --apply from the new OpenAPI operations (two /api/keys/{id}/self-service entries and the updated /v1/me/status description) — generator output only, no hand edits. Per AGENTS.md this needs explicit operator approval before merge.

Notes for reviewers

• usage.daily/weekly.requests counts every usage_history row (failures included), matching the existing token totals.
• An unrestricted key (no allowedConnections) reaches every active connection, so with account quota shared it still sees every reachable account; sharedQuotaProviders narrows that by provider.
• Settings changes apply immediately in the writing process; other processes pick them up within the 30 s settings cache TTL.

Live validation (Hard Rule #18)

Deployed ahead of merge to both operator nodes. They run a v3.8.50-based tree, so the deploy variant omits the key_quota limit source and editor (that module arrives in migration 182 / v3.8.51); everything else is this PR.

• One Linux release build (14,778 files), shipped byte-identical to the second node (tarball sha256 662b73588ff14117d87d7417c58f2f2aa3a5c51ff59d5512ba85e757d81397d0). Both came up healthy 4 s after the swap; migration applied on each (the prod deploy tree names it 9189_…, a prod-only number, so upstream 189/190 are never shadowed) (api_key_self_service_settings).
• With a temporary key (self:usage + self:account-quota, pinned to one Claude OAuth connection), deleted afterwards:
  • GET /v1/me/status via x-api-key → 200 with generatedAt, usage.daily (2026-09-24T00:00Z → 2026-09-25T00:00Z), usage.weekly (Monday 2026-09-21T00:00Z), limits: [], and one account quota: a masked account label, windows session (5h) / weekly (7d), fetchedAt set.
  • Streaming POST /v1/messages (cc/claude-haiku-4-5-20251001, max_tokens: 1): auto mode → 12 anthropic-ratelimit-unified-* headers forwarded; after switching the key to strip → 0.
• Unauthenticated: /v1/me/status → 401, /api/keys/{id}/self-service → 401; /dashboard/api-manager/{id} → 307 to login.

⚠️ base-red inherited: #15306

[diegosouzapw]

Thanks @fouadSalkini — this is a thoughtful design (own settings table, fail-closed parsing, masked labels, bounded quota refresh). A few things before we can merge: (1) migration 190 collides with #14801, so whichever lands second must move to 191; (2) with the default auto mode every existing key stops receiving anthropic-ratelimit-* / anthropic-organization-id unless it has self:account-quota and exactly one allowed connection — that's a behaviour change for current clients, so we'd like to confirm it as the default (and check the non-streaming path); (3) the diff touches skills/**/SKILL.md, which needs explicit maintainer sign-off; (4) at 15k lines / 132 files this would be much easier to review split into backend, header policy and dashboard UI — could you consider that? Thanks again!

One coordination note on the migration number: several open PRs claim 190, and the release tip is already at 189. To avoid a duplicate version, please renumber this PR's migration to 194. Slots are handed out in PR age order and merged in ascending order.

[fouadSalkini]

Thanks @diegosouzapw! Addressed all points and split into 3 stacked PRs:

1. Renumbered migration 190 → 194 as assigned.
2. The default for keys without an explicit setting is now "forward", preserving exact legacy behavior for existing keys without changes. The "auto" and "strip" modes are opt-in per key.
3. Reverted the SKILL.md changes to match base.
4. Split into 3 independent, stacked PRs:
   • Backend (feat(api-keys): self-usage status with limits, shared quota providers, anthropic header policy, and key details page #14771, this PR): migration 194, settings DB module, /v1/me/status endpoints and schemas, shared quota providers, unit tests.
   • Header policy (feat(api): anthropic rate limit headers forwarding policy for streaming and non-streaming #14862): streaming and non-streaming Anthropic rate limit header forwarding policy and tests.
   • Dashboard UI (feat(dashboard): API key details view and self-service quota settings #14863): Key Details view, quota & settings controls, preview, and 66-locale i18n.

[fouadSalkini]

Fixed a stale reference: the settings schema comment in src/shared/validation/schemas/keys.ts now points at migration 194 (194_api_key_self_service_settings.sql). No other references to the old number remain in this PR. api-key-self-service-settings passes 16/16.

[fouadSalkini]

Fixed a split artifact: slice 1/3 was cut from an older snapshot of the monolith branch and silently undid some base changes that landed afterwards. Restored:

• src/shared/utils/apiKeyPolicy.ts — the fix(api): expose quota reset timing #14188 reset timing is back (the "Resets in …" suffixes and retry_after on the budget, token-limit and request-limit 429s), with its tests in tests/unit/api-key-policy.test.ts.
• stryker.conf.json — back to the base list (the fix(api): expose quota reset timing #14188, fix(resilience): a request-translation failure no longer cools the account or trips the provider breaker (#14815) #14830 and fix(security): never let the sudo password reach the elevated command's stdin (GHSA-cqwr-7mqw-chr9) #14836 test entries); the header-policy test entry now lives in feat(api): anthropic rate limit headers forwarding policy for streaming and non-streaming #14862, which is where that test is added.
• config/quality/eslint-suppressions.json — no longer drops entries for files this PR doesn't touch. Only the apiKeySelfService.ts entry is removed, because this PR rewrites that file and the suppressed pattern no longer exists (a suppression that matches nothing fails ESLint).

Every remaining deletion against the base is this PR's own change (the apiKeySelfService.ts split into …Accounts/Limits/Shared, and one-line extensions). Focused suites plus the reset-timing tests pass (143/143) and the branch merges cleanly with release/v3.8.51.

[diegosouzapw]

Re-homed to release/v3.8.52: v3.8.51 entered its release freeze, so the branch now belongs to the release captain and development continues on the next cycle. Nothing is wrong with this PR — it just needed a live base. No action needed from you; CI will re-run against the new base.