feat(auth): scope and expire system API tokens, and fix two secret-handling bugs (fixes #217)

[mikeknight85]

Implements #217, following @stevene1919's decision on that thread exactly: backfill-as-* with a deprecation grace period rather than a hard break.

Two real bugs found beyond the brief

1. The token creation response was returning the token's bcrypt hash. system_api_token.repository.ts does INSERT ... RETURNING *, and routes/admin/tokens.ts sends systemToken: result.systemToken straight to the client. So every token creation leaked token_hash. CLAUDE.md is explicit that secrets are write-only over the API — this was a direct violation sitting in main.

2. || 1 had a real caller. I expected to find none. backend/src/scripts/generate-api-token.ts passed admin_id: undefined, so every token minted by the documented CLI route relied on the fallback to silently become user 1. Rather than just breaking that script, it now takes --user <email> (validated as an admin) or links to the longest-standing administrator and prints which. createSystemToken's admin_id is now a required parameter, so the invariant is type-enforced rather than hoped for. Unlinked tokens already in a database are refused with a 401 and a logged warning naming the label.

Scope vocabulary

Seven entries. mcp:read / mcp:write / mcp:extract come straight from ADR 001 §4.1 rather than being invented around it. The three admin:* entries exist because the ADR's list has nothing expressing "read the admin tree but do not run migrations" — which is the exact harm described in the issue.

scope	covers
*	everything; what legacy tokens hold, deprecated for new ones
mcp:read	read-only product/price/history plus admin diagnostics
mcp:write	mutating the tracked catalogue
mcp:extract	POST /api/admin/debug/* — the arbitrary-URL SSRF surface from #165
admin:read / admin:write	reading / mutating instance config
admin:system	POST /api/admin/command including run-migration

Namespace wildcards like admin:* are deliberately not grantable — a grant that widens as the vocabulary grows hands a token privileges nobody consented to at issue time. Routes accepting more than one scope list them as an OR, so mcp:read satisfies admin reads without any implication logic.

Two judgement calls:

• requireScope is a no-op for non-system tokens. Scopes describe machine credentials; a JWT grants none, so enforcing them on browser sessions would lock out every user. Pinned by a test.
• It is applied beyond /api/admin, method-aware. Otherwise mcp:read would be a lie: a "read-only" token could DELETE /api/products/:id, or PUT /api/profile to change the linked admin's email and then trigger a password reset to it. Profile writes require * for that reason. Legacy * tokens and human sessions are unaffected.

Prefix design, with the security reasoning

token_prefix varchar(16) holding ps_ plus 8 hex, partial index WHERE token_prefix IS NOT NULL. The prefix narrows the candidate set; bcrypt still decides every match.

• Secrecy: 8 hex is 32 bits of a 256-bit crypto.randomBytes(32) secret. 224 bits remain, still behind bcrypt. A prefix lets an operator identify a token they already hold — which is the point, the same job ghp_ does — and does not help guess one. Safe to show in the UI; token_hash still never leaves the service.
• Collisions: no UNIQUE constraint, on purpose. A unique index would turn a 1-in-8600-at-1000-tokens event into randomly failing token creation. findByPrefix returns a set and bcrypt-compares each; tested with two rows sharing a prefix.
• Timing: an indexed equality on a non-secret substring reveals only whether some token with that prefix exists, and you need a valid prefix to probe it. The meaningful win runs the other way: a bogus token previously cost one bcrypt per row in the table — a CPU-exhaustion vector on an unauthenticated path. The fallback scan is now restricted to token_prefix IS NULL rows only, so the cost of garbage input shrinks to zero as legacy tokens are replaced.

Also included: expiry

The binding comment asked for it. The column already existed but was never surfaced; it is now settable (30/90/365/never), and refused in authMiddleware before scopes or admin status, with a clear Token expired. NULL for existing rows.

Migration 023, tested against real Postgres

PostgreSQL 16.15 on a throwaway Homebrew cluster. Full 000→023 chain applies clean; down drops both columns and the index; a legacy row inserted before the migration backfills to {*} with a null prefix; re-running with the columns present reports 0 backfilled and — importantly — does not promote a post-migration {mcp:read} row to *, because the guard is token_prefix IS NULL AND cardinality(scopes) = 0. Down-then-up with data present works and tokens keep authenticating. The real service was also round-tripped against that database, confirming no token_hash in any response.

Renumbered from 022 to 023 — #249 took 022 and merged first. The runner tracks by filename so both would have run, but sequence matters and this had not shipped.

Admin UI

Legacy tokens (token_prefix === null) render a DEPRECATED / UNSCOPED / FULL ACCESS badge with "Issued before scopes. Regenerate to restrict it.", and a banner above the table counts them and explains they cannot be narrowed in place. Status now distinguishes EXPIRED from ACTIVE. Creation fetches the vocabulary from the API as a single source of truth, defaults to mcp:read, and the token is still shown exactly once.

Verification

tsc clean. 877 backend tests (836 on main, +41) and 66 frontend. Playwright 20 passed on private port 4403, bundle freshness proved by grepping the built admin chunk for the deprecation badge text. No as any added — the only one in the diff is the deleted listAll() as any[].

For whoever picks up #163

ADR 001 §4.1 and §4.2 are now implemented. I left the ADR untouched, but its status line and those two sections could use a "landed in #217" marker.