feat(tokens): mint a workouts:write token for headless workout ingest

A bridge that pushes workouts from a watch vendor had no credential that
reached POST /api/workouts/batch: the route called requireAuth() with no
scope, so under the fail-closed default only a cookie session or a
wildcard token got through, and a measurements:write token was refused
403. The route's header still described the pre-fail-closed behaviour.

Add a separate workouts:write scope rather than widening
measurements:write, so a token already handed to a scale does not start
accepting workouts.

- POST /api/tokens/workouts mints it, mirroring the measurement and
  document mints: cookie session plus a fresh proof, a literal permission
  array, 10 mints a minute, at most 10 live tokens (409
  tokens.workouts.ceiling_reached), a one-year default lifetime, audited.
- POST /api/workouts/batch names the scope. Sessions and wildcard tokens
  behave as before. A scoped caller's workouts are stored as EXTERNAL,
  resolved from the credential, and a batch in which any entry names a
  source is refused 422 (workout.batch.source_not_permitted), the same
  rule the measurement batch applies. EXTERNAL is on no source ladder, so
  when the phone recorded the same session the phone's copy is shown.
- Settings > API offers a workout token card next to the measurement one,
  and the endpoint list shows the batch route.
- Guards: the mint site, the declared scope vocabulary, the recent-proof
  routes, and a new check that only the batch declares the scope.
- OpenAPI documents the mint, the batch's narrow-token behaviour and both
  error codes; docs/api/README.md lists the workout and document mints.

Refs #1054
This commit is contained in:
Marc-André Bombeck committed 2026-09-30 22:21:46 +02:00
1 parent ae6a5ac693
commit e7166cb3c6
25 files changed
+1340 -32

No files matched your search

@@ -152,6 +152,9 @@ describe("T3 — the mint sites are frozen", () => {
// Document upload from another system (#1038). Same shape as the
// measurement mint: a literal, one scope, one route that accepts it.
"app/api/tokens/documents/route.ts": "[DOCUMENTS_WRITE_SCOPE]",
// Workout ingest from a bridge (#1054). Same shape again: a literal, one
// scope, one route that accepts it.
"app/api/tokens/workouts/route.ts": "[WORKOUTS_WRITE_SCOPE]",
// MCP, audience-bound to `/mcp`. `health:write` requires explicit consent.
"app/api/mcp/tokens/route.ts": "SCOPE_HEALTH_READ / SCOPE_HEALTH_WRITE",
"app/api/mcp/oauth/token/route.ts":
@@ -179,6 +182,7 @@ describe("T3 — the mint sites are frozen", () => {
"app/api/medications/[id]/api-endpoint/route.ts",
"app/api/tokens/measurements/route.ts",
"app/api/tokens/documents/route.ts",
"app/api/tokens/workouts/route.ts",
"app/api/mcp/tokens/route.ts",
"app/api/mcp/oauth/token/route.ts",
];
@@ -234,6 +238,7 @@ describe("T4 — declared scopes are exported constants, never string literals",
"DOCUMENTS_WRITE_SCOPE",
"FHIR_READ_SCOPE",
"MEASUREMENTS_WRITE_SCOPE",
"WORKOUTS_WRITE_SCOPE",
];
const used = new Set<string>();
for (const rel of sourceFiles()) {
@@ -284,6 +289,27 @@ describe("T4b — `documents:write` opens exactly two doors", () => {
});
});
describe("T4c — `workouts:write` opens exactly one door", () => {
it("only the workout batch declares the scope, and only on its POST", () => {
// The set of files naming the scope IS its reach. The batch ingest and
// nothing else: not the workout list or detail, which would hand a
// bridge the history it has no business reading back.
const declaring = filesMatching(
/requireAuth\(\s*WORKOUTS_WRITE_SCOPE\s*\)|requireRecordAuth\([^)]*\bscope:\s*WORKOUTS_WRITE_SCOPE\b/,
);
expect(declaring).toEqual(["app/api/workouts/batch/route.ts"]);
const batch = read("app/api/workouts/batch/route.ts");
expect(
batch.match(/requireAuth\(\s*WORKOUTS_WRITE_SCOPE\s*\)/g),
).toHaveLength(1);
expect(
[...batch.matchAll(/export const (GET|POST|PUT|PATCH|DELETE)\b/g)].map(
(m) => m[1],
),
).toEqual(["POST"]);
});
});
describe("T5 — a delegable route naming a Bearer scope is frozen", () => {
/**
* Routes that admit a narrow token on a DELEGABLE surface, and the scope each
@@ -114,6 +114,7 @@ const COOKIE_PROOF_ROUTES = [
"app/api/auth/reproof/route.ts",
"app/api/tokens/documents/route.ts",
"app/api/tokens/measurements/route.ts",
"app/api/tokens/workouts/route.ts",
].sort();
describe("the recent-proof gate", () => {