heater-appb-auth-billing

name	heater-appb-auth-billing
description	Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.

App B Auth & Billing — seams, dormancy, fail-closed

Everything here is ADDITIVE + DORMANT: built, shipped, inert until env vars flip it on. Absent Stripe env on the live beta is intentional (friends are free) — do not "fix" it.

The verifier seam (api/auth.py)

AuthVerifier Protocol (one method: verify(authorization) -> Principal). get_auth_verifier() (auth.py:173-184) returns:

• ClerkVerifier (auth.py:99-163) when clerk_configured() — local RS256 via PyJWKClient JWKS (10s timeout), requires exp/iss/sub, fail-closed: ANY error → 401. JWKS outage logs WARNING (operator problem), bad user token logs debug.
• EnvTokenVerifier (auth.py:70-93) otherwise — deny-by-default (HEATER_API_WRITE_TOKEN unset → 401), and compares bytes: hmac.compare_digest(token.encode(), expected.encode()) (auth.py:87) because str/str compare_digest raises TypeError on non-ASCII — a hostile header would 500 instead of deny.

clerk_configured() (auth.py:166-170, reads CLERK_ISSUER at call time) is the SINGLE predicate for "auth is live" — get_auth_verifier, require_login, and the tenancy read-gate all share it so they can't disagree. Never invent a second "is auth on" check.

Billing (M2, $7.99/mo Pro, 7-day trial)

• billing_env_configured() (api/billing_config.py:13-18): true only when BOTH STRIPE_SECRET_KEY and STRIPE_PRO_PRICE_ID set — the same predicate the checkout service uses, so the paywall can't activate before checkout works (a half-configured deploy must not lock users out).
• require_pro (api/gating.py:34-49): no-op while billing dormant; live → verify Clerk (401), then subscription store tier != "pro" → 402. Attached to the 7 heavy endpoints (lineup/optimize, trade/evaluate, trade-finder, playoff-odds, draft/*). Structural guard: tests/api/test_api_pro_gating.py introspects router objects (_route_map/_dep_calls, lines 105-116) because FastAPI 0.137's lazy include_router hides nested routes from app.routes.
• Webhook (POST /api/billing/webhook): signature-verified fail-closed 400; checkout.session.completed is link-only (out-of-order events can't re-activate a canceled user); event-id dedup via api_processed_events. stripe==15.2.1 pinned (webhook schema drift).
• AI caps: get_managed_ai_cap (api/gating.py:52-80) never raises — unverifiable caller or store failure → None = admin default cap (bounded, WARNING-logged over-grant beats a hard failure in chat).

Frontend half

web/src/lib/api/client.ts: authToken() (client.ts:43-54) awaits clerkReady() — polls window.Clerk?.loaded (50ms, 5s timeout, client.ts:30-37) — and calls getToken() as a method (destructuring loses the this receiver). Every apiGet/apiPost/... attaches Authorization: Bearer.

Failure story (M-2/M-3, 2026-06-26): on hard page load the app decided "no token" before the Clerk script finished loading → spurious 401 → bounce to /sign-in for signed-in users. Root cause: reading Clerk.session before Clerk.loaded. The await-loaded gate is the fix; don't remove it to "simplify".

Quick diagnosis

Symptom	Check
401 on reads locally	CLERK_ISSUER set locally flips the read gate — unset it for open local reads
401 on live reads with a real login	token audience/issuer vs CLERK_ISSUER/CLERK_AUDIENCE; JWKS WARNING in logs = misconfig, not user error
402 anywhere	billing env got set — is that intended?
409 TEAM_NOT_LINKED	not auth — tenancy assignment (heater-appb-two-dbs-tenancy)
writes 401 on live	expected: Yahoo fspt-w scope unavailable + write token unset by design

When NOT to apply

Owner-gated activations (Clerk PROD instance needs a custom domain; Stripe live keys) — flag to owner, don't flip. Identity/team resolution beyond auth → heater-appb-two-dbs-tenancy.