Authorization model

Summary#

The platform has five credential types and two quota gates that also act as authorization. They are independent: a route uses one, several, or none. This page maps each gate to the resources it actually protects, states the exact denial it returns, and records what happens to authorization when the dependency behind it is unavailable.

Authentication and authorization flow is the request-level walkthrough of the same machinery. This page is the surface map and the risk register: what is protected, what is not, and what the blast radius of each failure is.

Purpose#

Three jobs need this page. Adding an endpoint means choosing the right gate and knowing what it returns. Reviewing the platform means knowing where the trust boundaries actually sit rather than where they are assumed to sit. Handling an incident means knowing whether a dependency outage opened a gate or closed it, because the answer is not the same at every gate.

The gates are deliberately not uniformly fail-closed. Entitlement gates fail closed because letting an unauthenticated caller into a paid feature costs money and trust. Abuse guards and configuration lookups fail open because refusing legitimate users to enforce a fair-use ceiling is the wrong trade. Each choice is documented next to the code that makes it.

Architecture#

The trust boundaries#

Two boundaries are weaker than they look and must be stated plainly.

The /dashboard document is not edge-gated. The worker maps the clean URL to the static asset and serves it to anyone; the sign-in overlay is client-side. The same is true of /admin. This leaks interface structure, not data, because every API behind both screens is gated server-side.

Most customer API handlers derive identity from the request body. The canonical sniffing helper mvActUserEmail(url, headers, body) takes the first address it finds in body.user_email, body.userId, body.email, the x-mv-user header, then ?user_email= or ?email=. That is the C1 class described under Failure modes.

mvC1Identity is live on main, and being in it is not the same as being closed. Every route that resolves a caller now calls mvC1Identity(request, env, claimed), which verifies the Supabase bearer token when one is present and returns:

MV_C1_ENFORCE is unset in production. So in warn mode denied is always null and email is whatever the caller typed, and a route whose only check is if (_c1.denied) return _c1.denied is trusting that value. The flag being off is the point of warn mode: it lets the programme be rolled out without moving behaviour for anyone. It also means the warn-mode fallback is itself the vulnerability on any route where the address chooses whose rows are read or whose allowance is spent.

mvC1Require(_c1, message) is the guard for those routes. It requires a proven session regardless of the flag, and it answers 503, not 401, when providerDown is true because a 401 tells the browser its session is dead and signs the user out, so a Supabase outage would otherwise become a mass logout that outlives the outage. Routes using it refuse a forged identity today, with the flag off.

Live on main with that guard:

• every /api/social/* route: connections, disconnect, publish, schedule, scheduled, scheduled/cancel (media reaches the same result through mvProfileIdentity)
• /api/usage
• /api/crawl/schedule, both GET and POST
• /api/responsive/get, /delete, /device and /chat, but only for a row that HAS an owner. A row created by the signed-out free tool has none, and stays reachable by its id because that id is the only handle its creator ever had. A verified caller who is not the owner still gets a 404 rather than a 401, so one customer cannot use the difference to confirm another row exists.
• every route that spends credits: /api/premium-ai (the whole premium tool surface, through mvPremiumAICore), /api/cited-sources, /api/rank-alerts/create, /api/rank-alerts/check-now, /api/image/analyze and /api/image/create, alongside Originality, Fact Check, Growth Actions, Specialist and the light-tool path, which carry the same requirement inline. Warn mode returns the claim with verified: false, so a route could resolve identity, look correct, and still charge the address the request named.

/api/analyst is the one charging route that does NOT demand a session, because it also answers the public marketing chat. It picks the payer off the flag instead — _c1.verified ? _c1.email : '' — so a forged or anonymous caller is billed to nobody while the chat still works. Either shape satisfies the rule; which one a route uses depends on whether anonymous use is part of the product.

Cost-free routes are deliberately outside it. /api/chatbot and the rank tracker's chat answer anonymous callers on purpose, capped per IP by mvAnonIpCap, and no credits move.

tests/billing-identity-sweep.mjs derives every charging call site from source and fails if one bills an address its own function never proved. Its header claimed that check for a fortnight before it made it: traces() demanded the word "verified" only on mvBillingEmail's workspace-redirect argument, so eight routes of exactly the shape described here reported green while charging the claim. Mutation-tested now, including the case where the guard is called and its refusal discarded.

The API reference already documented all of these as Verified session. The code was the half that did not agree.

The legitimate callers are unaffected because the dashboard's fetch wrapper attaches the Supabase bearer to every string /api/ URL once the session has loaded. Genuinely public routes, the /api/tools free tools among them, are deliberately NOT behind this guard and are bounded by per-IP caps instead.

tests/c1-sweep.mjs probes every derived route twice, once with MV_C1_ENFORCE=1 and once with the flag unset, and fails if a must-be-gated route answers a forged identity in either mode. The second pass is the one that describes production; before it existed the sweep reported /api/social/publish as gated while it was accepting posts to a stranger's connected accounts.

The five credential types#

Components#

Gate 1 — the verified session token#

verifySupabaseUser calls GET {SUPABASE_URL}/auth/v1/user with the token and an apikey header, then independently requires email_confirmed_at || confirmed_at. An unconfirmed address is never an identity, regardless of the Supabase project's own toggle. It returns null on any failure, so callers fail closed by construction. There is no local JWT signature check and no cache on main: every verification is a live round trip.

Four routes use it: POST /api/keys/create, POST /api/keys/list, POST /api/keys/revoke and POST /api/library/saved/delete.

handleSavedDelete is the model the rest of the platform is meant to follow. It reads Authorization: Bearer, verifies it, answers 401 {"ok":false,"deleted":0,"error":"unauthorized"} if that fails, caps the batch at 200 integer ids, and scopes the DELETE with AND user_email = ?, so a caller can only ever delete their own rows.

Gate 2 — the plan gate#

requirePlan resolves the plan through resolveUserPlan and compares it against PLAN_RANK = { free: -1, starter: 0, pro: 1, agency: 2, enterprise: 3, unlimited: 99 }. An unmapped plan ranks -1 and can never pass.

There are exactly four call sites: schedule creation (starter), API key creation (enterprise), the public analyze endpoint (enterprise, re-checked on every call so a downgraded key stops working), and branding save (pro). Everything else that is plan-sensitive is gated through the quota path instead.

Gate 3 — admin#

The authoritative store is the D1 table admin_users(email, role, status, …). A row wins: status = 'active' grants its role, anything else denies even for a seeded address. With no row, or if D1 throws, resolution falls back to the seed floor — two hardcoded addresses plus any comma-separated entries in ADMIN_EMAILS — which resolve to owner. That fallback is deliberate so a D1 outage cannot lock the owner out of the console needed to fix it, and it is reachable only after a valid, confirmed Supabase token has already been proven.

Two roles exist. Both read every admin data endpoint. Only owner mutates.

Every admin route answers an unauthorised caller with HTTP 403 and {"error":"Unauthorized"}, not 401. Guardrails on admin mutation refuse self-suspension (You cannot suspend or demote your own account.), self-removal (You cannot remove your own account.) and any action against a seeded owner (This is a protected owner account.).

Mutations are written to admin_audit_log(ts, actor, action, target, meta). The writer is best-effort by design and swallows its errors, so an audit write can fail silently while the privileged action still succeeds. Admin reads are not audited at all, and /api/admin/data is on the activity-logger quiet list. See Audit log.

Gate 4 — the internal secret#

mvVerifyInternalSecret returns 503 {"error":"Internal jobs are not configured (MV_INTERNAL_SECRET is not set)."} when the secret is unset, rather than falling back to a derivable value. It accepts the secret from the x-mv-internal-secret header, or from ?key= on a GET, and answers a mismatch with 401 {"error":"Unauthorized internal call"}. The comparison is a plain string compare, not constant-time; a timing-safe helper exists but is used only for Stripe signatures.

The diagnostic block at the top of the router is a separate inline check with a different shape: ?key= only, answering 403 {"ok":false,"error":"forbidden"} with Cache-Control: no-store. It covers /api/dbgdfs and every /api/diag/* route, because each probe hits a real billable upstream and can echo configuration state.

The secret must be identical in three places: the Cloudflare Pages environment, the cron-worker Worker secret, and the GitHub repository secrets. See Internal endpoints and Environment variables and secrets.

Gate 5 — customer API keys#

mv_live_ plus 48 hex characters from 24 CSPRNG bytes: 192 bits of entropy. Creation requires a verified session and the Enterprise plan, with a hard cap of five active keys (Key limit reached (5 active keys). Revoke one first.). Revocation is a flag scoped to the owner. There are no scopes and no expiry. Storage and the operational handling that follows are covered in API key security.

The quota gates, which are also authorization#

enforceAiQuota and enforceAiRecoQuota do more than count. They are where anonymous access, the Free-plan boundary and account suspension are enforced.

Suspension is a platform_config row keyed suspended:<lowercased email>, set and cleared only by an owner. It blocks metered work; it does not invalidate an existing session, and there is no force-logout anywhere in the product.

Workspace scoping#

resolveWorkspaceEmail(db, requesting_email, active_workspace) returns the requester unless a team_memberships row exists where member_email = requester AND owner_email = requested AND accepted_at IS NOT NULL. A forged active_workspace therefore gains nothing. Note that the workspace role column is display-only: an accepted member has the same access regardless of the badge shown. Only blog_role carries enforced capabilities. See Roles and what each can do.

Outbound request authorization#

mvAssertPublicUrl is the guard on every URL the platform will fetch on a caller's behalf. It rejects non-http(s) schemes and blocks private, loopback, link-local, CGNAT, multicast and cloud-metadata addresses in dotted, decimal, octal, hex and IPv6 notations, including IPv4-mapped forms. It is applied to /api/tools targets, competitor-monitor URLs and webhook destinations (Webhook host is not allowed). It does not resolve DNS, so a public name that resolves to a private address is not caught, and redirects are not re-validated after the fact. Both limits are acknowledged in the code.

Data flow#

A customer runs a tool. The browser posts {type, query, user_email} with a bearer token attached by the patched fetch. The handler reads user_email from the body. enforceAiQuota resolves the plan, checks suspension, applies the Free-plan block or the quota comparison, and returns either a Response or null. Metering follows at the call site.

An admin loads the console. admin.html posts the session token to /api/admin/me. mvResolveAdmin verifies it, requires a confirmed email, reads admin_users, stamps last_seen_at, and answers {ok, email, role} or 403. Every subsequent screen resends the token in its body. There is no admin session.

The scheduler fires. metricvault-cron POSTs /api/cron/run with x-mv-internal-secret. Jobs run inside ctx.waitUntil and the HTTP response returns immediately.

A script calls the API. The bearer key is looked up, checked for revocation, the owner's current plan is re-verified against Enterprise, and six credits are metered before the analysis runs.

Failure modes#

Dependency failure: open or closed#

Residual risk register#

These are true on main today. Document them as such and do not soften them.