control-plane-api: capability_token grant mints masked access tokens

[bbartman]

Task 5 of #3376 (stacked on #3422): POST /api/v1/auth/token gains the capability_token grant, the first production path that mints masked tokens.

What this does

{"grant_type": "capability_token", "capability_mask": ["CatalogRead", "Viewer"]}

An unmasked, human bearer mints a one-hour access token that copies the caller's verified identity claims and carries capability_mask as a claim. Enforcement (landed in #3406) intersects the mask with the user's live grants at use time.

Per Gregor's revision on the issue, there is no upgrade_token parameter: a client wanting more capabilities requests the full list in a fresh mint. This removes the planned signature-only verify variant in the tokens crate, the mask-union semantics, and the expired-token re-mint rules from the original decision 4.

Decisions implemented

• Copy-through claim set. sub, role, aud, and email (when present) are copied verbatim from the caller's claims; fresh iat; exp = iat + 1h. Aside from email and capability_mask this is exactly the SQL generate_access_token claim set (pinned by pgTAP in supabase/tests/), so the two mint paths cannot drift, and a masked token remains a fully functional Supabase/PostgREST token during the GraphQL migration: PostgREST reads sub (RLS via auth.uid()) and role (SET ROLE) and carries unknown claims inertly in request.jwt.claims.
• The mask is stamped verbatim — bundle-name vocabulary, unknown names and duplicates included, empty list valid (identity-only token). Enforcement, not the mint, decides what a name enables; unrecognized names can never widen.
• Rust-side signing with the control plane's existing HMAC encoding key, following the authorize_dekaf precedent. The SQL function is untouched and keeps serving the refresh_token grant and PostgREST clients.
• Masked callers are refused with the structured unmasked_token_required 403 — a reduced token cannot widen or re-mint itself (the issue's open question).
• Service-account callers are refused with a new structured service_account_forbidden 403 (decision 11). The internal.service_accounts lookup is shared with the refresh-token mutations via a new is_service_account predicate and is paid only at the mint, never per-request.
• The handler extracts Authority<NoRequirement>, so a presented bearer is verified regardless of grant: a broken bearer now 401s even for the refresh_token grant, which previously ignored the Authorization header entirely. Bearer-less refresh_token requests are byte-identical. No known client sends a bearer to this endpoint (flowctl authenticates via PostgREST; the dashboard via the Supabase library).

Tests

test_capability_token_mint drives the real router end-to-end: the copy-through claim set and 1-hour expiry of a successful mint (presenting the minted token back as a bearer proves the signature through production Envelope verification); verbatim mask stamping including unknown names and duplicates; the identity-only empty mask, which is still refused as a mint caller ("masked" is claim presence, not value); an email-less caller minting an email-less token; missing-bearer 401; masked-caller and service-account-caller 403 bodies (insta-pinned); invalid-bearer 401 on the refresh_token grant; and the typed extractor's 422 for an unknown grant. Note the last: axum's Json rejects a well-formed body with an unknown grant_type as 422, not the 400 named in plan decision 6 — the tests pin actual behavior.

Closes nothing on its own; tasks 6 (guards) and 7 (no-amplification suite) follow.

Revision (2026-08-28): configurable validity window

The mint's validity window is deploy-configurable (initially opened as #3433 and folded into this PR): a new agent setting --capability-token-validity / CAPABILITY_TOKEN_VALIDITY (humantime syntax, following the controller duration settings' pattern) feeds an App field into the signer, which stays pure. The default is the shared DEFAULT_CAPABILITY_TOKEN_VALIDITY constant — one hour, matching the SQL mint — consumed by the test builders and the mint test, with a weld test in agent pinning the clap default string to the constant (which also proves the default parses before the first production boot). An override deliberately diverges from the SQL mint's fixed hour (claim-set parity is unaffected), and a longer window widens leaked-masked-token exposure — the flag docs carry both warnings. A unit test pins a non-default window at the signing seam.