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

scout/forge:scout/5150-the-openapi-document-describes-a-person → main 2 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
2 files changed +35 −0
src/contract/openapi.ts +23
@@ -280,6 +280,29 @@ export const ROUTES: readonly Route[] = [
280280 status: 204,
281281 refusals: { forbidden: "the caller holds a bearer token, which cannot manage tokens" },
282282 },
283 {
outdated

The summary says the forge owner may list any person's sign-ins. In whose() (src/actions/signins.ts) the owner cannot see another admin, an agent or a removed account. Add that to the not_found text so a client knows why a 404 comes back.

284 method: "get",
285 path: "/api/v1/users/{username}/signins",
286 summary: "List where a person is signed in: answers { tokens, sessions }, each token { id, name, scope, createdAt, lastUsedAt, expiresAt } and each live browser session { id, createdAt, lastSeenAt, expiresAt, current }; a session's secret and a token's value are never answered; the person themself or the forge's owner, with a browser session, a password or an admin-scope token",
287 auth: true,
288 refusals: {
289 unauthorized: "no credentials were sent",
290 forbidden: "the caller holds a token below admin scope",
291 not_found: "no such account, or it is not one the caller may see",
292 },
293 },
294 {
295 method: "delete",
296 path: "/api/v1/users/{username}/sessions/{id}",
297 summary: "End one browser session of a person, as when a device is lost; the person themself or the forge's owner, with a browser session, a password or an admin-scope token; answers 204 and never a session secret",
298 auth: true,
299 status: 204,
300 refusals: {
301 unauthorized: "no credentials were sent",
302 forbidden: "the caller holds a token below admin scope",
303 not_found: "no such account or session, or it is not one the caller may end",
304 },
305 },
283306 { method: "get", path: "/api/v1/telemetry/system", summary: "Read the forge's system view; the owner or an agent holding telemetry:read, with a ro token; every agent read is logged", auth: true },
284307 { method: "get", path: "/api/v1/telemetry/flow", summary: "Read the forge's flow view; the owner or an agent holding telemetry:read, with a ro token; every agent read is logged", auth: true },
285308 { method: "get", path: "/api/v1/telemetry/sources", summary: "List telemetry sources; answers { sources }; the owner or an agent holding telemetry:read", auth: true },
test/openapi.test.ts +12
@@ -201,3 +201,15 @@ test("an app's routes are described, and env values are never read back", () =>
201201 expect(doc.paths[`${A}/env`].get.summary).toContain("never read back");
202202 expect(doc.paths[`${A}/{env}/redeploy`].post.responses["202"]).toBeDefined();
203203 });
204
205 test("a person's sign-ins and ending one are described, with no session secret", () => {
206 const doc = openapi("https://f.test", "1") as any;
207 const list = doc.paths["/api/v1/users/{username}/signins"]?.get;
208 const end = doc.paths["/api/v1/users/{username}/sessions/{id}"]?.delete;
209 expect(list).toBeDefined();
210 expect(end).toBeDefined();
211 expect(list.security).toBeDefined();
212 expect(list.summary).toContain("admin-scope");
213 expect(end.responses["204"]).toBeDefined();
214 expect(end.responses.default.description).toContain("not_found");
215 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs