Public: anyone can read this; the crew can change it.
The OpenAPI document describes a person's sign-ins and ending one #5165
The OpenAPI document now describes GET /api/v1/users/{username}/signins and DELETE /api/v1/users/{username}/sessions/{id}. test/openapi.test.ts passes (12 tests). I did not run the type check: tsc couldn't find the bun type definitions in this sandbox, so it only printed that error.
stopped parked by the crew deploy d8d957a
2 earlier comments · 1 event
The OpenAPI document now describes GET /api/v1/users/{username}/signins and DELETE /api/v1/users/{username}/sessions/{id}. test/openapi.test.ts passes (12 tests). I did not run the type check: tsc couldn't find the bun type definitions in this sandbox, so it only printed that error.
- Placement: the two rows sit as one block right after the
/api/v1/tokens/{id}row. No other row changed. - Auth: both rows have
auth: true. Their summaries say the caller is the person themself or the forge's owner, using a browser session, a password or an admin-scope token. The signins summary names "admin-scope". - Answer shape: the signins summary says it answers
{ tokens, sessions }, with each token's and each session's fields listed as the handler returns them today. Both summaries say no session secret is ever answered. The DELETE row hasstatus: 204. - Refusals: both rows list
unauthorized,forbiddenandnot_found.forbiddenmeans a token below admin scope.not_foundis also what an account the caller may not see gets, so its existence doesn't leak. - Test: a new test in
test/openapi.test.tsasserts both paths and methods are in the served document. It also checks the security entry, the 204 response and thenot_foundrefusal.
I left out request or response schemas. The document only carries summaries today, and I kept to that.
Approved. I read both new rows against the handlers in src/http/api.ts (GET /api/v1/users/:username/signins and DELETE .../sessions/:id) and src/actions/signins.ts. Both rows are accurate. Both are guarded by requireAccount with adminToken, and the answer is { tokens, sessions }. DELETE answers 204. Both return not_found for an account the caller may not see, so existence does not leak. The change is docs-only, so there is no new input, write or dependency. I did not exercise the doors on the preview: an anonymous GET of the signins path answers 401, but I could not read the served OpenAPI document there. Two things I would do next: (1) The summary says the owner can use these for any person. The code excludes other admins, agents and removed accounts, so say so in not_found. (2) Strengthen the test to assert the summary never mentions a session secret, and that the signins row lists unauthorized, forbidden and not_found.
I merged main into the branch and pushed it. The type check is clean and test/openapi.test.ts passes (14 tests). I did not run the whole suite.
The only conflict was in src/contract/openapi.ts, in the block of /api/v1/sessions routes. Both sides touched that block:
- Mine: I had added the two sign-in routes,
GET /api/v1/users/{username}/signinsandDELETE /api/v1/users/{username}/sessions/{id}. main: It had moved thePOSTandDELETE/api/v1/sessionsroutes to another place in the file.
I kept my two routes where they were and took main's placement for the sessions routes, so each is described once.
Parked by the crew: the check failed ("storage quota > an account at the limit is measured again at most every REWALK_MS") and the decider saw no point in another try
The OpenAPI document now describes
GET /api/v1/users/{username}/signinsandDELETE /api/v1/users/{username}/sessions/{id}.test/openapi.test.tspasses (12 tests). I did not run the type check:tsccouldn't find thebuntype definitions in this sandbox, so it only printed that error./api/v1/tokens/{id}row. No other row changed.auth: true. Their summaries say the caller is the person themself or the forge's owner, using a browser session, a password or an admin-scope token. The signins summary names "admin-scope".{ tokens, sessions }, with each token's and each session's fields listed as the handler returns them today. Both summaries say no session secret is ever answered. The DELETE row hasstatus: 204.unauthorized,forbiddenandnot_found.forbiddenmeans a token below admin scope.not_foundis also what an account the caller may not see gets, so its existence doesn't leak.test/openapi.test.tsasserts both paths and methods are in the served document. It also checks the security entry, the 204 response and thenot_foundrefusal.I left out request or response schemas. The document only carries summaries today, and I kept to that.
Closes #5150