screentinker/docs/billing-authz-plan.md

Billing-read authorization — findings, options, recommendation

Status: PLAN. No code changed. Goal: a least-privilege way to read GET /api/billing/usage that does NOT require platform-admin, while platform-admin can still read it.

---

Phase 0 — how authz actually works here

1. Roles = a fixed, hardcoded enum on users.role. There is NO role→permission mapping. Authz is Array.includes(role) against hardcoded sets in middleware/auth.js: PLATFORM_ROLES = ['superadmin','platform_admin'], ELEVATED_ROLES = ['admin','superadmin', 'platform_admin'], PLATFORM_STAFF = [...,'platform_operator']. Guards are hardcoded functions: requireAuth, requireAdmin, requireSuperAdmin (requirePlatformAdmin is an alias). The enum is threaded through ~20 server files plus the frontend role dropdown (PLATFORM_ROLE_OPTIONS in frontend/js/views/admin.js) and the #14 role-normalization migration. Adding a role is a wide change.

2. The authz seam is per-route middleware, not centralized. Billing today: server.js:582 → app.use('/api/billing', requireAuth, require('./routes/billing')), and routes/billing.js gates the handler with requirePlatformAdmin. Other endpoints declare their guard at mount or per-handler. Note: this billing mount is bespoke — it is NOT in config/api-surface.js (the partition source of truth) and is therefore not covered by the firewall test (test/api.test.js). Fixing that is a side-benefit of Option C.

3. Identity: JWT sessions AND scoped API tokens. middleware/apiToken.js implements a Bearer st_… token front door (api_tokens table, SHA-256 hash, scope column). Its security model is the important part:

• A token authenticates as its owner but with role forced to 'user' (line 63) — every PLATFORM_ROLES/ELEVATED_ROLES check downstream is false. So a token can never pass requirePlatformAdmin; billing is unreachable by any token today.
• Routers are partitioned in config/api-surface.js: PUBLIC_ROUTERS (token + JWT, gated by tokenScopeGate read<write<full), JWT_ONLY_ROUTERS (/api/admin, etc. — tokens jwt.verify-fail → 401), and AGENCY_ROUTERS — an off-ladder capability scope (agencyGate: token must be exactly scope==='agency', tied to no role, reaches only /api/agency). This #73 agency pattern is a working precedent for exactly what we want.
• Token creation (routes/tokens.js) is JWT-only, workspace-scoped; SCOPES = ['read','write','full','agency']; any workspace member can mint read/write/full tokens for their workspace.

4. Smallest change that grants ONLY billing-read: a new off-ladder token scope billing, mirroring agency — additive, isolated from the shared role checks.

---

The three options

A. New ROLE (billing_viewer)

Add a role to the enum and let the billing route accept it. Effort: MEDIUM–LARGE.

• Touches: middleware/auth.js (role set + a guard), routes/billing.js, the frontend role dropdown (PLATFORM_ROLE_OPTIONS), the #14 role-normalization migration/comments, and an audit of the ~20 files that assume the closed role set. Migration: likely (role normalization). Tests: new guard + regression across role checks.
• Blast radius: HIGH — modifies the shared role model every endpoint depends on, right before release. And a role lives on a human users row (one role column), so it doesn't cleanly serve the real consumer (tooling / invoice-time pulls) and is coarse to revoke.
• Least privilege: mediocre (a human login, not a scoped credential).

B. New PERMISSION / CAPABILITY (billing:read)

Gate billing on a permission granted independently of role. Effort: LARGE.

• There is no permission seam to hang this on — no permissions table, no role→permission map. Option B means introducing one (table + checker) or faking it with a bespoke billing:read flag on users. Either way it adds a new concept to the shared auth path. Migration: yes (new table/column). Tests: a whole new permission surface.
• Blast radius: MEDIUM–HIGH — new seam in shared auth; not additive/isolated.
• Least privilege: good in principle, but the effort/risk is disproportionate for one route.

C. Dedicated scoped BILLING TOKEN ✅ RECOMMENDED

A revocable, read-only billing-scoped API token that authorizes ONLY the billing route — mirroring the existing off-ladder agency scope (#73). Effort: SMALL–MEDIUM. No migration.

• Changes, all additive and isolated (do NOT touch PLATFORM_ROLES/requireAuth/shared checks):
  1. middleware/apiToken.js — add billingGate (mirror agencyGate), but allow the JWT platform-admin too: req.viaToken ? req.tokenScope==='billing' : isPlatformRole(req.user.role). ~6 lines, export it.
  2. config/api-surface.js — add BILLING_ROUTERS = [{ path:'/api/billing', mod:'./routes/billing' }]; server.js mounts it with bearerAuth + billingGate (mirroring the AGENCY mount) and the bespoke app.use('/api/billing', requireAuth, …) at server.js:582 is removed. This also brings billing under the firewall-test partition (closes the current gap).
  3. routes/tokens.js — add 'billing' to SCOPES; because a billing token grants global billing-read, gate its creation on platform-admin: if (scope==='billing' && !isPlatformRole(req.user.role)) return 403. ~3 lines.
  4. routes/billing.js — drop requirePlatformAdmin from the handler (the mount-level billingGate now authorizes both a billing token and a platform-admin JWT).
  5. db/schema.sql — update the api_tokens.scope comment to include billing (doc only; column is free-text TEXT — no migration).
  • Tests: billing token → 200; a read/write/full/agency token → 403 (off-ladder, tokenScopeGate already rejects it everywhere else); platform-admin JWT → 200; non-admin JWT → 403; anon → 401; a non-platform-admin cannot MINT a billing token (403); firewall partition test extended.
• Blast radius: LOW / isolated. The billing scope is off the read/write/full ladder, so tokenScopeGate rejects it on every other router — billingGate is its only door. Nothing the rest of the app depends on is modified.
• Least privilege: EXCELLENT. Grants billing-read and nothing else; tied to no human role; revocable (revoked_at); minted only by platform-admin. Fits the real consumer — tooling / invoice-time pulls / the agreement's §4.2 verification access.
• Platform-admin still reads billing via the JWT branch of billingGate — allowed, not required.

Two nuances to document when built: (a) a billing token's workspace_id binding is vestigial — billing is platform-global, so the read ignores it (unlike agency's per-target binding); (b) if per-tenant billing ever lands, a billing token could then be workspace-scoped.

---

Recommendation: Option C

It is the only option that is simultaneously least-privilege (billing-read only, revocable, no human role), lowest effort (no migration; reuses the proven #73 agency pattern), and — decisively for a pre-release change — additive and isolated: it never touches the shared role/permission checks every other endpoint depends on. Options A and B both modify or extend the shared auth path, which is exactly the destabilization we want to avoid before beta7 ships.

Next step: Dan picks A / B / C. If C, the build is a separate task (~4–5 files, no migration, one new test file + a firewall-test line).