|
| 1 | +# 001 — Management API route inventory |
| 2 | + |
| 3 | +Source: read of `src/server/management-api.ts`, `src/server/management/*`, |
| 4 | +`src/codex/auth-api.ts`, `src/codex/native-profile-api.ts` at `50e955604`. |
| 5 | + |
| 6 | +## How dispatch works |
| 7 | + |
| 8 | +There is no route table and no framework. Every route is a hand-written |
| 9 | +`if (url.pathname === … && req.method === …)` inside one of 17 handler functions, |
| 10 | +chained with `??` in `src/server/management-api.ts` around line 220. First handler |
| 11 | +returning non-`null` wins; a handler returning `null` falls through. **Dispatch is |
| 12 | +order-sensitive.** |
| 13 | + |
| 14 | +Auth is applied *before* dispatch, in `src/server/index.ts` near line 1010: every |
| 15 | +`/api/` path passes `requireManagementAuth`. No management route is unauthenticated. |
| 16 | +Individual routes then re-check the principal for consent. |
| 17 | + |
| 18 | +`pathInManagementNamespace` (management-api.ts:102) matches exact-or-child only, so |
| 19 | +`/api/labfoo` deliberately does not match `/api/lab`. |
| 20 | + |
| 21 | +## Totals |
| 22 | + |
| 23 | +- **183 reachable routes** across 19 files; **108 mutating**. |
| 24 | +- **1 dead route**: `GET /api/storage` at `logs-usage-routes.ts:346` is shadowed by |
| 25 | + the identical claim at `storage-log-guard-routes.ts:150`, which runs earlier in the |
| 26 | + chain and always returns. The live payload is the guard version (scan plus |
| 27 | + `codexLogs`/`codexLogsError`). Audit parity against the guard version. |
| 28 | +- `/api/codex-auth/*` is gated by a `startsWith("/api/codex-auth/")` check with a |
| 29 | + trailing slash, so a bare `/api/codex-auth` 404s. |
| 30 | + |
| 31 | +## Auth classes |
| 32 | + |
| 33 | +| Class | Meaning | Routes | |
| 34 | +|---|---|---| |
| 35 | +| admin | admin token or GUI session (default gate) | ~177 | |
| 36 | +| session | minted GUI session required; admin token gets 403 | `POST /api/github/star`, the 6 non-GET `/api/codex-prompt*` verbs | |
| 37 | +| cap | process-scoped HMAC capability principal | `POST /api/providers/reload`; read-cap for `/api/codex-auth/accounts` and `/api/system/memory` | |
| 38 | + |
| 39 | +The capability principals are narrow and replay-protected: local reads are limited |
| 40 | +to exactly those two paths with `url.search` required empty |
| 41 | +(`src/lib/local-management-capability.ts:10`). |
| 42 | + |
| 43 | +## Registration mechanisms a naive `rg '/api/'` misses |
| 44 | + |
| 45 | +| Mechanism | Where | What is missed | |
| 46 | +|---|---|---| |
| 47 | +| Lazy `import()` behind a namespace check | management-api.ts:115, :121 | all `/api/routing-profiles*` and `/api/lab*` — deliberate, eager mounting would pull ~70 `src/lab/` modules into every install | |
| 48 | +| Handlers mounted outside the `??` chain | management-api.ts:284, :289 | 10 `/api/native-main-profiles/*` and 22 `/api/codex-auth/*` routes, which live in `src/codex/` | |
| 49 | +| Path constants, not literals | `src/lib/codex-restart-contract.ts:17`, `system-restart-contract.ts:5`, `local-provider-reload-contract.ts:5` | `/api/system/codex-restart`, `/api/system/codex-app-server`, `/api/system/restart`, `/api/providers/reload` | |
| 50 | +| Prefix-decoded wildcard | integration-routes.ts:129 | `GET|PUT /api/client-integrations/{clientId}` | |
| 51 | +| Regex params | model-routes, lab-routes, lab-automation-routes | 7 routes | |
| 52 | +| Suffix matching | request-history-routes.ts:131 | `/route-decision` found via `endsWith` | |
| 53 | +| Namespace guards that swallow siblings | codex-prompt:278, request-history:47, lab:285 | unmatched children 404 from index.ts rather than falling through | |
| 54 | + |
| 55 | +**This table is the parity test's hard requirement.** A parity test that greps for |
| 56 | +`'/api/…'` string literals would miss 40+ routes and pass vacuously. The test must |
| 57 | +enumerate from a declared registry, not from source text. |
| 58 | + |
| 59 | +## Route families (grouped for CLI parity) |
| 60 | + |
| 61 | +| Family | Routes | Existing CLI reach | |
| 62 | +|---|---|---| |
| 63 | +| config/settings | `/api/config` (GET; PUT=405), `/api/settings` GET+PUT, `/api/diagnostics/project-config`, `/api/sync` | `ocx system`; `ocx config` is file-I/O only, never calls `/api/config` | |
| 64 | +| startup/tray | `/api/startup-health`, `/api/startup-action`, `/api/windows-tray` GET+POST | `ocx system` partial | |
| 65 | +| update | `/api/update/check`, `/run`, `/status`, `/badge` | `ocx system`, `ocx update` | |
| 66 | +| sidecar/shadow | `/api/sidecar-settings` GET+PUT, `/api/shadow-call-settings` GET+PUT | `ocx agent`, `ocx models` | |
| 67 | +| storage | `/api/storage`, `/cleanup`, `/cleanup/preview`, `/trash`, `/trash/restore`, `/cleanup-policy` GET+PUT, `/cleanup-policy/run`, `/codex-logs` +4 actions | `ocx observe storage` reaches only `/api/storage` and `/codex-logs*` | |
| 68 | +| logs/debug/usage | `/api/logs`, `/api/debug` GET+PUT, `/debug/logs`, `/debug/usage-logs`, `/debug/injection-logs`, `/api/claude/inbound-debug`, `/api/usage` | `ocx observe`, `ocx debug` | |
| 69 | +| request history | `/api/request-history`, `/{id}`, `/{id}/route-decision` | `ocx observe` partial | |
| 70 | +| routing | `/api/routing-profiles` GET+PUT+DELETE, `/dry-run`, `/api/routing-analytics` | `ocx route policy` | |
| 71 | +| providers | `/api/providers` GET+POST+PATCH+DELETE, `/test`, `/reload` (cap), `/api/provider-quotas`, `/api/provider-presets`, `/api/provider-context-caps` GET+PUT, `/api/provider-request-pacing` | `ocx provider`; pacing has no verb | |
| 72 | +| models | `/api/models`, `/api/catalog`, `/api/aliases`, `/api/default-aliases`, `/api/providers/{n}/alias`, `/model-aliases`, `/api/disabled-models`, `/api/model-visibility`, `/api/custom-models` +2, `/api/selected-models` GET+PUT, `/api/model-presets` GET+PUT, `/api/model-discovery` GET+PUT, `/acknowledge`, `/api/client-config` | `ocx models`, `ocx alias`, `ocx export`; `/api/client-config` has no verb | |
| 73 | +| combos | `/api/combos` GET+PUT+DELETE | `ocx combo` | |
| 74 | +| integrations | `/api/client-integrations` +journal +restore +`{clientId}` GET/PUT, `/api/native-integrations` +4 PUTs, `/api/claude-code` GET+PUT, `/api/claude-desktop` GET+PUT +apply +status, `/api/grok` +selection +apply | `ocx integration`, `ocx grok`, `ocx claude`; native-integrations has no verb | |
| 75 | +| agent settings | `/api/v2` GET+PUT, `/api/injection-model`, `/api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`, `/api/codex-auth/features/default-mode-request-user-input` | `ocx agent`, `ocx v2`; the feature flag has no verb | |
| 76 | +| access keys | `/api/keys` GET+POST+PATCH+DELETE | `ocx access key` list/create/remove; PATCH rename has no verb | |
| 77 | +| oauth accounts | `/api/oauth/providers`, `/api/key-providers`, `/api/oauth/login` +cancel +code, `/status`, `/logout`, `/api/oauth/accounts` GET+DELETE, `/active`, `/pool` GET+PUT, `/clear-cooldown`, `/import`, `/alias`, `/api/providers/keys` +active +alias | `ocx account`; `/pool` (strategy/sticky) has no verb | |
| 78 | +| codex auth | 22 routes: accounts GET/DELETE, `/alias`, `/pause`, `/priority`, `/pause-exhausted`, `/clear-cooldown`, `/active` GET+PUT, `/auto-switch`, `/pool-strategy`, `/failover`, `/quota`, `/reset-credits` +consume, `/login` +code +cancel, `/login-status` | `ocx account`; pause, pause-exhausted, pool-strategy, failover have no verb. `auto-switch` (account.ts:302 -> `cmdAutoSwitch`) and `reset-credits` (account.ts:313) DO have verbs — verified; an earlier draft wrongly listed them as gaps | |
| 79 | +| native main profiles | 10 routes under `/api/native-main-profiles` | `ocx account main` | |
| 80 | +| system | `/api/system/memory`, `/windows-replace-retries`, `/restart`, `/codex-app-server`, `/codex-restart`, `/api/stop` | `ocx restart`, `ocx stop`, `ocx observe memory` | |
| 81 | +| lab | 20 read routes + `/public/*` 4 + automation 5 | `ocx lab` reads local SQLite, never the HTTP routes | |
| 82 | +| sidebar | `/api/github/star` GET+POST(session) | GET has no verb; POST must never get one | |
| 83 | + |
| 84 | +## Cross-cutting error envelopes |
| 85 | + |
| 86 | +From management-api.ts:237 — a CLI client should encode these once: |
| 87 | + |
| 88 | +- `413 request body too large` (2 MB cap) |
| 89 | +- `403 cross-origin request blocked` |
| 90 | +- `503 oauth_mutation_busy`, `503 catalog_busy` (both with `Retry-After: 1`) |
| 91 | +- `503 CONFIG_MUTATION_LOCK_UNAVAILABLE` for the codex-auth family |
| 92 | +- `503` with `reason` + `hint` from `src/server/management-auth.ts:455` |
| 93 | + |
| 94 | +The last one is #2698: the fields exist and the CLI does not print them. |
0 commit comments