feat(runner): persistent API tokens, verified in the Worker (DEV-2583)

[demtario]

Closes DEV-2583.

Why

The nightly live canary has one secret-gated step: the authed share round-trip, which is the only test that drives the builder, R2 and D1 end to end against production. Its credential is secrets.E2E_BROKER_TOKEN — a per-user browser session JWT copied by hand out of sessionStorage.hot_token, which expires in about an hour. The workflow knows this and treats a dead token as a notice and a green run, because "the secret rots by design and rot is not a product failure". The honest reading is that the step is skipped every night and the coverage is theoretical.

There was no mint path to automate. authenticate() does not verify a JWT at all — it forwards the bearer to the login broker's /broker/userinfo and trusts the address that comes back (ADR-0007). Nothing in the system could issue a credential, and nothing could validate one it had not been handed by the broker.

What

A first-party credential, hot_pat_<id>_<secret>, minted from a new API tokens page, stored as a SHA-256 digest, verified inside the Worker, and revocable by anyone on the team. Full reasoning in ADR-0037; the decisions worth knowing before reading the diff:

• The prefix is checked before anything touches the network, and the two paths never fall through to one another. This is a security property rather than a latency win: a bearer that reached the broker because the local lookup missed would have shipped our own permanent credential to a third-party host on Render, and the failure would have looked like a slow success.
• Only a digest is stored. SHA-256, not bcrypt/argon2, and the ADR says why out loud because it is the reflex objection: this is a 256-bit random secret rather than a password, so there is no dictionary to run and no low-entropy guess space to grind, and the id makes the lookup a primary-key hit. A work factor would cost every authenticated request and defend nothing.
• A token acts as its creator's address. sameOwner(), created_by, ?scope=mine and "My demos" are untouched, and no new address shape enters a system whose only membership check is endsWith("@handsontable.com"). Identity gains via (the token id) for the fence and the audit trail.
• A capability fence, because this credential lives in a public repository's secrets and any team identity is currently a full admin. No admin writes, no session kills, no /api/chat or /api/theme, and no token management at all — reads included. So a leaked token cannot raise the spend ceiling, turn enforcement off, burn AI budget, mint itself a successor, or enumerate the credentials it would need to revoke. Admin reads stay open, which the session-leak spec needs. Fixed rule, not a scope field: this repo has never had a permission model and one consumer exists.
• Every token is visible to, and revocable by, the whole team. This knowingly sets aside the standing warning that ?scope=all is visibility and must never quietly become permission — a permanent credential only its author can kill is worse than one anybody can, because the author will eventually be on holiday and the token will not expire on their behalf.
• last_used_at is coarsened to the hour by a single conditional UPDATE, so the hot auth path cannot generate more than one write per token per hour and there is no read-then-write race to reason about.
• The client accepts a token too, resolving identity against our own GET /api/profile instead of the broker. That is what keeps the live spec driving the real Share button rather than being rewritten into an API script. The cost is stated in the ADR: such a token is a browser session in a string, which is why the fence exists and why the workflow's trace scrubbing matters more than it used to.

Three things the build caught that reasoning would not have

• The vite dev proxy's /api key is a bare prefix, so /api-tokens was proxied to the Worker and 500'd. That key was always wider than the demos.handsontable.com/api/* route it stands in for — the same bug /d had already been regex'd for. Fixed the same way.
• A token_hash that is not a usable string 500'd out of the auth path instead of refusing. NOT NULL in the schema, so this only reaches a hand-edited row or one caught mid-backfill, but a 500 there would be reported as an outage. Guarded, with a test.
• The DEV_AUTH_EMAIL loopback bypass ran ahead of the token branch. Every developer is told to put that in .dev.vars, so a presented token was accepted as a person — via never set, fence never engaged, wrangler dev behaving as the exact opposite of production on the one thing this feature is careful about. The token check now runs first, wherever the Worker is running.

Verification

• pnpm test — 879 tests, 0 failures. Two new specs: pipeline/api-token.test.mjs (the credential's own rules) and pipeline/token-routes.test.mjs (the real router, not a re-declared copy of its checks).
• pnpm -r typecheck — clean, run through raw pnpm rather than the token-filtering proxy, which has reported a false green before.
• Playwright — 92 passed, exit 0, across the deterministic specs plus the new e2e/api-tokens.spec.ts. Run on a dedicated port, because another worktree already owned 4173 and would have silently served the wrong build.
• The tests were checked against a neutered implementation, not just watched to pass: deleting the chat fence reddens one case, disabling the auth branch reddens eight, and disabling the token-session gate on the new page reddens its own.
• The shared D1 fake models api_tokens including both conditional UPDATEs, so the idempotent revoke and the hour coarsening are actually exercised rather than assumed. fakeKV gained the list() shape adminSessions() reads.

Before this ships

• wrangler d1 migrations apply for 0006_api_tokens.sql (the deploy workflow does this; the hand-run lists in run-and-deploy.md are updated too).
• The GitHub secret is renamed E2E_BROKER_TOKEN -> E2E_API_TOKEN. It needs creating from a token minted on /api-tokens after deploy, and the old secret can then be deleted. Absent, the step still skips with a notice; present and not validating now fails the run, because a credential with no expiry that stops working means revoked or broken.

🤖 Generated with Claude Code

---

Note

High Risk
Adds a new never-expiring credential class, changes Worker authentication, and fences token capabilities. A leak or fence miss is security-critical; CI now fails if the GitHub secret is present but invalid.

Overview
Adds persistent first-party API tokens (hot_pat_<id>_<secret>) so the nightly authed share canary can run without a hand-copied, hourly-expiring broker JWT (ADR-0037).

The Worker now prefix-branches before any network call: tokens are verified locally against a SHA-256 digest in D1 and act as the creator’s email (Identity.via). They cannot manage tokens, spend AI budget, change guardrail settings, or kill sessions. Listing and revoke are org-wide. The SPA gets /api-tokens (one-time plaintext reveal, team list, confirm-to-revoke) and treats a token session as signed-in via /api/profile, hiding Ask AI / Style.

Live E2E switches E2E_BROKER_TOKEN → E2E_API_TOKEN. Absent still skips; a present token that fails /api/profile fails the run. Vite’s /api proxy is regex-scoped so /api-tokens is not swallowed.

^{Reviewed by Cursor Bugbot for commit 3b227f3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 98d00b1. Configure here.}