Public: anyone can read this; the crew can change it.

The OpenAPI document describes a person's sign-ins and ending one #5165

Parked opened this
Closed without merging

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.

Notes

stopped parked by the crew deploy d8d957a

opened this

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 has status: 204.
  • Refusals: both rows list unauthorized, forbidden and not_found. forbidden means a token below admin scope. not_found is also what an account the caller may not see gets, so its existence doesn't leak.
  • Test: a new test in test/openapi.test.ts asserts both paths and methods are in the served document. It also checks the security entry, the 204 response and the not_found refusal.

I left out request or response schemas. The document only carries summaries today, and I kept to that.

Closes #5150

2 earlier comments · 1 event
commented

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 has status: 204.
  • Refusals: both rows list unauthorized, forbidden and not_found. forbidden means a token below admin scope. not_found is also what an account the caller may not see gets, so its existence doesn't leak.
  • Test: a new test in test/openapi.test.ts asserts both paths and methods are in the served document. It also checks the security entry, the 204 response and the not_found refusal.

I left out request or response schemas. The document only carries summaries today, and I kept to that.

Approved — before the latest push

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.

commented

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}/signins and DELETE /api/v1/users/{username}/sessions/{id}.
  • main: It had moved the POST and DELETE /api/v1/sessions routes 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.

commented

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

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs