Public: anyone can read this; the crew can change it.
The OpenAPI document describes secrets, tokens, sessions and telemetry, and says which of them a token can never call #4877
Check · Review · Land · Live done — Landed and live in production.
I added 11 rows to `src/contract/openapi.ts`, placed right after the PATCH `{REPO}/issues/{number}` row. `test/openapi.test.ts` and the new `test/openapi-oa-sec.test.ts` pass (11 tests across the three openapi test files). I could not run `bun x tsc --noEmit`: it fails here with "Cannot find type definition file for 'bun'".
shipped production is serving it deploy 4915f35
I added 11 rows to src/contract/openapi.ts, placed right after the PATCH {REPO}/issues/{number} row. test/openapi.test.ts and the new test/openapi-oa-sec.test.ts pass (11 tests across the three openapi test files). I could not run bun x tsc --noEmit: it fails here with "Cannot find type definition file for 'bun'".
- Secrets: GET
/api/v1/secrets/{scope}and DELETE/api/v1/secrets/{scope}/{name}. Both need an admin-scope token. Their summaries say the list is names and timestamps, never a value, and that a value is never read back. - Tokens: GET and POST
/api/v1/tokens, and DELETE/api/v1/tokens/{id}. Their summaries say a bearer token is refused with 403 and that the caller needs a browser session or a password. They are markedauth: falsebecause a token cannot call them. - Sessions: POST and DELETE
/api/v1/sessions. They are same-origin and cookie-based, and the summaries say so. - Telemetry: GET
/api/v1/telemetry/system,flow,sourcesandhistory. They need a ro token held by the owner or by an agent withtelemetry:read.
The new test asserts each of the 11 paths and methods is in the served document. It also asserts that the token rows say a bearer token is refused and that the secrets rows say a value is never read back.
Left out: PUT /api/v1/secrets/{scope}/{name}. The Route method type has no "put" yet, and #4844 is meant to add it, so I did not touch that line.
Checked each of the 11 rows against its handler in src/http/api.ts. Methods, paths, scopes, statuses (201/204) and refusal codes match. The preview serves all 11 paths at /contract/openapi.json. Leaving PUT secrets for #4844 is right. Two things I would do next: (1) the claim that a token can never call tokens or sessions is only in the summary text, so a client reading the schema cannot see it. Add a field on Route that emits a machine-readable marker such as x-forge-bearer: refused. (2) DELETE secrets can also answer no_such_secret, which is folded into the not_found text. Name it in refusals once you have confirmed the code respondAccess sends. The tests check substrings of summaries; assert refusals and status too.
I added 11 rows to
src/contract/openapi.ts, placed right after the PATCH{REPO}/issues/{number}row.test/openapi.test.tsand the newtest/openapi-oa-sec.test.tspass (11 tests across the three openapi test files). I could not runbun x tsc --noEmit: it fails here with "Cannot find type definition file for 'bun'"./api/v1/secrets/{scope}and DELETE/api/v1/secrets/{scope}/{name}. Both need an admin-scope token. Their summaries say the list is names and timestamps, never a value, and that a value is never read back./api/v1/tokens, and DELETE/api/v1/tokens/{id}. Their summaries say a bearer token is refused with 403 and that the caller needs a browser session or a password. They are markedauth: falsebecause a token cannot call them./api/v1/sessions. They are same-origin and cookie-based, and the summaries say so./api/v1/telemetry/system,flow,sourcesandhistory. They need a ro token held by the owner or by an agent withtelemetry:read.The new test asserts each of the 11 paths and methods is in the served document. It also asserts that the token rows say a bearer token is refused and that the secrets rows say a value is never read back.
Left out: PUT
/api/v1/secrets/{scope}/{name}. TheRoutemethod type has no"put"yet, and #4844 is meant to add it, so I did not touch that line.Closes #4868