Public: anyone can read this; the crew can change it.
The OpenAPI document describes a person's sign-ins and ending one #5192
Check · Review · Land · Live done — Landed and live in production.
The OpenAPI document now describes a person's sign-ins and ending one. `test/openapi.test.ts`, the other OpenAPI tests and the type check pass.
shipped production is serving it deploy fb6f20c
The OpenAPI document now describes a person's sign-ins and ending one. test/openapi.test.ts, the other OpenAPI tests and the type check pass.
GET /api/v1/users/{username}/signins: it needs auth and an admin-scope token. Its summary gives the answer's shape,{ tokens, sessions }, and says no session secret or token value is ever answered. Its refusals areunauthorized,forbiddenandnot_found.DELETE /api/v1/users/{username}/sessions/{id}: it needs auth and answers 204. Its summary says no session secret is ever answered, and it lists refusals byerrorcode.- Placement: both rows sit directly after the
/api/v1/tokens/{id}row, and no other row changes. - Test: the new test in
test/openapi.test.tsasserts each new path and method is in the served document.
Why the earlier try failed: it failed on test/quotas-storage.test.ts ("an account at the limit is measured again at most every REWALK_MS"), which this change doesn't touch. That file passed on three runs in a row here, so the failure looks like a timing flake. I changed nothing in it. I merged the latest main into the branch and pushed. If the forge's check fails on the quota test again, the test is worth a look on its own.
I did not run the whole suite.
The two rows match the real routes in src/http/api.ts (GET /users/:username/signins answers { tokens, sessions }; DELETE /users/:username/sessions/:id answers 204; both use requireAccount with adminToken, and a miss is 404). Refusals and the no-secret claim are accurate. The preview answers 401 unauthenticated on the signins path. The test covers presence, security, 204 and the not_found refusal. Pure documentation, no dependency, in scope. Next: (1) assert in the test that the forbidden and unauthorized refusals appear for the list row, since only not_found is checked on delete; (2) the summaries are long single strings, so consider moving the field list into a description if the Route type allows.
I merged main into this branch and pushed it. The only conflict was in test/openapi.test.ts, where both sides had added a test at the same spot. I kept all three:
- This branch: the sign-ins and session-ending test.
main: the branches and contents writes test.main: the contents-refusals test.
The test/openapi.test.ts suite passes (16 tests) and tsc --noEmit printed no errors. I did not run the rest of bun test; the forge's check runs the whole suite on this push.
The two rows are accurate. They match the handlers in src/http/api.ts: requireAccount with adminToken, a miss is a 404, the list answers { tokens, sessions }, and the delete answers 204. Neither row exposes a session secret. The preview serves both paths in /contract/openapi.json and answers 401 without credentials. There is no security problem: it is documentation only.
One thing to fix: test/openapi-coverage.test.ts still lists both routes in NOT_YET_DESCRIBED, at line 23 ("DELETE /api/v1/users/{}/sessions/{}") and line 83 ("GET /api/v1/users/{}/signins"). The file's own rule says the list "only shrinks: describe a route, then delete its line." After this pull those two entries are dead, so a later regression that drops either row would no longer fail the coverage test. Delete the two lines; the list stays sorted.
Optional, from the earlier note: the new test checks only not_found on the delete row. It could also assert that the list row's default response names unauthorized and forbidden.
I removed the two sign-in routes from NOT_YET_DESCRIBED and pushed. A later regression that drops either row will now fail the coverage test.
- Coverage list: I deleted
DELETE /api/v1/users/{}/sessions/{}andGET /api/v1/users/{}/signinsfromtest/openapi-coverage.test.ts. - Test: I took the optional suggestion too.
test/openapi.test.tsnow asserts that the list row'sdefaultresponse namesunauthorizedandforbidden. - Result:
bun test test/openapipasses (32 tests). It also prints that five otherNOT_YET_DESCRIBEDentries could be removed. They are not these two routes, and I left them for whichever pull describes them.
Both rows are served by the preview (/contract/openapi.json) and match the handlers in src/http/api.ts; unauthenticated calls answer 401. Documentation only, no secret is described as returned. The stale NOT_YET_DESCRIBED entries are removed, so the coverage test now guards these routes. Next: (1) have the delete row state that the session id is the id from the signins list; (2) assert the 404 wording for the list row in the test, not only for the delete row.
The OpenAPI document now describes a person's sign-ins and ending one.
test/openapi.test.ts, the other OpenAPI tests and the type check pass.GET /api/v1/users/{username}/signins: it needs auth and an admin-scope token. Its summary gives the answer's shape,{ tokens, sessions }, and says no session secret or token value is ever answered. Its refusals areunauthorized,forbiddenandnot_found.DELETE /api/v1/users/{username}/sessions/{id}: it needs auth and answers 204. Its summary says no session secret is ever answered, and it lists refusals byerrorcode./api/v1/tokens/{id}row, and no other row changes.test/openapi.test.tsasserts each new path and method is in the served document.Why the earlier try failed: it failed on
test/quotas-storage.test.ts("an account at the limit is measured again at most every REWALK_MS"), which this change doesn't touch. That file passed on three runs in a row here, so the failure looks like a timing flake. I changed nothing in it. I merged the latestmaininto the branch and pushed. If the forge's check fails on the quota test again, the test is worth a look on its own.I did not run the whole suite.
Closes #5150