What
src/openapi/orb-and-control-route-specs.ts:339 and src/openapi/internal-and-public-route-specs.ts:603 each export their full spec table with a comment naming the consumer:
/** Exported for the meta-test that asserts every entry's declared auth matches the middleware that
* actually gates it. */
export const ORB_AND_CONTROL_ROUTE_SPECS: readonly SpecEntry[] = [...ORB_ROUTES, ...INTERNAL_ORB_ROUTES, ...APP_ROUTES, ...REPO_ROUTES];
/** Exported for the auth-parity meta-test. */
export const INTERNAL_AND_PUBLIC_ROUTE_SPECS: readonly SpecEntry[] = [ ... ];
That meta-test does not exist. Neither symbol is referenced anywhere outside its own file:
grep -rn "ORB_AND_CONTROL_ROUTE_SPECS\|INTERNAL_AND_PUBLIC_ROUTE_SPECS" test/ scripts/ # no output
The routes themselves are registered into the document (registerOrbAndControlRouteSpecs / registerInternalAndPublicRouteSpecs, both called from spec.ts), so the spec is not missing routes. What is missing is the check that the auth each entry declares is the auth the middleware actually applies.
Why it matters
This is the security-relevant half of the route seam. A spec entry can claim auth: "admin-bearer" on a route the middleware leaves open, or claim public on one that is gated, and nothing fails — the document is the thing operators and integrators read to decide what is protected. #9707 is the precedent for the general class (a published 401 that nothing could produce); this is the same class one level up, across every ORB, internal-ORB, app and repo route.
Two exports are also being maintained purely to feed a consumer that was never written, which is its own small drift: a reader reasonably assumes the guarantee exists.
Scope
- A meta-test that, for every entry in both tables, resolves the middleware chain the route is actually mounted under in
createApp() and asserts the declared auth matches it.
- Derive both sides — no hand-listed route→auth table, or this becomes another thing to forget. The route specs are already data; the middleware mounting is the other half to read.
- Where a genuine exception exists, it carries a one-line reason in the same style as the repo's other allowlists (
check-import-specifiers.ts's ALLOWED_FILENAMES, check-dead-source-files.ts's ENTRY_POINT_FILES).
- Any disagreement the new test finds is fixed in the same PR — a declared auth that does not match reality is either a doc bug or an auth bug, and both are worth knowing about immediately.
Acceptance
Changing a route's middleware without changing its spec entry (or vice versa) fails CI.
What
src/openapi/orb-and-control-route-specs.ts:339andsrc/openapi/internal-and-public-route-specs.ts:603each export their full spec table with a comment naming the consumer:That meta-test does not exist. Neither symbol is referenced anywhere outside its own file:
The routes themselves are registered into the document (
registerOrbAndControlRouteSpecs/registerInternalAndPublicRouteSpecs, both called fromspec.ts), so the spec is not missing routes. What is missing is the check that theautheach entry declares is the auth the middleware actually applies.Why it matters
This is the security-relevant half of the route seam. A spec entry can claim
auth: "admin-bearer"on a route the middleware leaves open, or claim public on one that is gated, and nothing fails — the document is the thing operators and integrators read to decide what is protected. #9707 is the precedent for the general class (a published 401 that nothing could produce); this is the same class one level up, across every ORB, internal-ORB, app and repo route.Two exports are also being maintained purely to feed a consumer that was never written, which is its own small drift: a reader reasonably assumes the guarantee exists.
Scope
createApp()and asserts the declaredauthmatches it.check-import-specifiers.ts'sALLOWED_FILENAMES,check-dead-source-files.ts'sENTRY_POINT_FILES).Acceptance
Changing a route's middleware without changing its spec entry (or vice versa) fails CI.