auth/token_scope.ts

Is value one of the surfaces the spine mounts?

Membership, not well-formedness — parse_token_scope_capability is the format check the guard resolver runs on a declaration, and it is deliberately looser. Used where the *spine's* own surfaces are the question: the direct-call denial helpers, and the census assertion that fuz_app declares no surface it doesn't mount.

Serialized-document cap. Matches the Rust MAX_TOKEN_SCOPE_BYTES and fuz_forge's MAX_POLICY_BYTES.

Read a stored api_token.scope value back into a TokenScope, or null when the document is unreadable.

The DB driver may hand scope back already-parsed (JSONB → object) or as text depending on backend, so both are normalized here rather than at each call site. Lives here rather than beside the queries so the pure scope module owns every parse — and so mocking the query module doesn't drag this along.

Parse a stored document, enforcing the size cap and the schema.

Fail-closed: returns null on an unreadable document, and every caller on the enforcement path treats null as "refuse the credential" rather than "allow everything". fuz_forge's hydrate path deliberately widens on a DB blip — safe there only because a role gate still applies. Here the scope *is* the gate, so widening on a parse failure would hand a narrowed token full authority exactly when something is already wrong.

Parse a capability string into the question it asks, or null when it is not a capability at all.

Callers turn null into a registration-time throw: RouteAuth.required_scope is typed as a plain string so http/ needs no auth/ import, and this is the single point where that string becomes a mounted guard, so it is where the value gets checked. Refusing an unknown prefix is what keeps the surface: namespace fuz_app's own — a route cannot mint an rpc:-looking capability out of a surface gate, which would put a method name in front of a whole-surface refusal.

Serialize for storage, enforcing the size cap.

Throws on an over-cap document — the mint path maps that to a 400, matching the Rust side's TokenScopeError::TooLarge.

Does scope admit capability?

The one place the two arms of the vocabulary meet their two predicates, so a surface: capability can never be answered by a method-list membership test (which would let a narrowed token onto a surface by listing a method named after it) and an rpc: capability can never be answered by rule 3 (which would refuse a token the method it was minted for).

Does scope admit dispatching method?

Consulted by perform_action between the credential gate and the role gate.

Does scope admit a non-RPC spine surface?

A narrowed token reaches no non-RPC surface at all — the load-bearing half of token scoping, and what "rule 3" names wherever this module's callers and the Rust twin use that shorthand. See docs/security.md §Token scoping.

A method-name allowlist alone would have been a false promise: the db-admin browser serves paginated rows of any public table (including account.password_hash, auth_session, and api_token) plus row DELETE, gated on a global role a bearer credential satisfies. A token whose UI badge read "scoped to cell_get" could still delete an account row.

Denying every non-RPC surface outright is strictly more restrictive than naming each one, keeps no vocabulary to maintain, and fits in one sentence a user can hold: *a scoped token is RPC-only*.

Build the flat denial body a non-RPC route returns when a narrowed token reaches a capability it lacks: {error: 'token_scope_required', required_scope: '<section>:<id>'} at 403.

One shape for every capability, matching the Rust token_scope_surface_denied_response. These are REST-ish routes whose sibling denials are already flat, so the JSON-RPC envelope stays with the dispatcher's per-method gate and stops there.

Build the stored scope from a mint-time input.

A deliberately-minted full-authority scope.

Stable label for the token list / UI.

The capability string an action method is refused under: rpc:<method>.

Exported because two sites *compute* one — the dispatcher's per-method gate and the REST bridge, which must agree — where a surface: capability is always written as a literal on a route spec, so nothing computes one.

A narrowed scope over methods.

Current TokenScope document version. Must match the Rust TOKEN_SCOPE_VERSION.

Name format for the identifier half of a capability string. Mirrors RoleName / CredentialTypeName / ScopeKindName.

Applied to the surface: arm only. The rpc: arm's identifier is an action method name, whose vocabulary belongs to ActionSpec (and includes shapes like peer/ping this regex would refuse) — the capability parser checks it is non-empty and leaves the rest to the registry that owns it.

The non-RPC surfaces the spine itself mounts (rule 3). Twin of the Rust TokenSurface enum, name for name.

Not a registry a consumer registers into. RouteAuth.required_scope accepts any well-formed surface:<name> (see parse_token_scope_capability), so a consumer names its own non-RPC surface without an upstream release. This tuple is what the *spine* may declare, and what its surface census iterates — the closure is a check on fuz_app's own routes, not a vocabulary consumers have to ask permission to extend.

A surface name never decides anything: rule 3 is all-or-nothing (token_scope_admits_non_rpc), so the name only labels *which* surface refused, in the required_scope a denial reports. That is the same field whose rpc:<method> arm has always carried arbitrary consumer method names.

The stored api_token.scope document.

grandfathered is a fact about the *row* — the api_token_scope migration wrote it; no minter chose it — that only the token list cares about. The enforcement path never branches on it, which is what stops "grandfathered" from becoming a third authority level.

Strict on both arms so a v2 document carrying a grant arm a v1 reader doesn't understand is refused rather than parsed as permissively-narrower-than-stored. The discriminated union also refuses the contradiction {kind: 'full', methods: [...]}.

A parsed required_scope capability — what a route demands of the calling credential's TokenScope.

capability is the wire string verbatim, carried rather than re-derived so a denial reports exactly what the route declared. The arms are asymmetric on purpose, and the asymmetry is the whole design: the rpc: identifier is consumed by a predicate (token_scope_admits_method), so it is kept; the surface: identifier is pure label, because rule 3 is all-or-nothing (token_scope_admits_non_rpc never looks at which surface). That is why one half of the vocabulary needs no registry.

The scope input accepted by account_token_create — the stored shape minus the row-owned fields.

A minter cannot set version or grandfathered: the first is stamped by token_scope_full / token_scope_methods, and the second is the migration's mark for tokens that predate scoping. Letting a caller forge grandfathered would turn a tracked debt into a laundered one.