auth/grant_path_schema.ts

Grant-path registry — the surfaces through which a role can be granted to an actor.

Four builtins:

admin — granted by an admin via role_grant_offer_create (subject to the consumer's authorize callback) or admin-side direct grant.
self_service — toggled by the holder themselves via self_service_role_set (allowlisted by eligible_roles).
system — granted by system code paths (signup, automation, etc.) that don't fit either of the above.
bootstrap — granted exactly once during the bootstrap flow (keeper, admin on a fresh install).

Open registry on top so consumers can declare additional paths (e.g. 'invite_only', 'sso_assertion') without an upstream release. RoleSpec.grant_paths references entries from this registry; the default for admin_actions.grantable_roles is grant_paths.includes('admin'), the default for self_service_role_actions eligibility is grant_paths.includes('self_service'). Mirrors the open-registry pattern used for RoleName, ScopeKindName, CredentialTypeName, and AuditEventTypeName.

view source

Declarations
#

12 declarations

builtin_grant_path_meta
#

auth/grant_path_schema.ts view source

ReadonlyMap<string, GrantPathMeta> import {builtin_grant_path_meta} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Builtin grant-path metadata. Not overridable by consumers.

Typed ReadonlyMap for the contract — but JS Maps don't honor Object.freeze for .set / .delete / .clear (they mutate internal slots, not own properties), so freeze adds no runtime guard here. Read once at startup by create_grant_path_schema; runtime mutation has no effect on already-built schemas.

BUILTIN_GRANT_PATHS
#

auth/grant_path_schema.ts view source

readonly ["admin", "self_service", "system", "bootstrap"] import {BUILTIN_GRANT_PATHS} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

The builtin grant-path names as a const tuple.

BuiltinGrantPath
#

auth/grant_path_schema.ts view source

ZodEnum<{ admin: "admin"; bootstrap: "bootstrap"; self_service: "self_service"; system: "system"; }> import type {BuiltinGrantPath} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Zod enum for builtin grant paths only.

create_grant_path_schema
#

auth/grant_path_schema.ts view source

(consumer_paths?: Record<string, GrantPathMeta>): GrantPathSchemaResult import {create_grant_path_schema} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Create a grant-path schema from the builtin set plus optional consumer-declared additions.

Builtins (admin, self_service, system, bootstrap) are always present; consumer entries that collide with a builtin name throw at construction. Pass the result into create_role_schema's optional grant_paths parameter so each role's grant_paths entries are validated against this set at construction time.

`consumer_paths`

optional consumer-declared grant-path set with optional metadata

type Record<string, GrantPathMeta>

default {}

returns

GrantPathSchemaResult

{GrantPath, grant_paths} — Zod schema and metadata map

throws

Error - if any `consumer_paths` key fails the `GrantPathName` regex, collides with a builtin name, or appears more than once

examples

// simple — builtins only
const {GrantPath, grant_paths} = create_grant_path_schema();

// with consumer extensions
const {GrantPath} = create_grant_path_schema({
  invite_only: {description: 'Granted by claiming a consumer-issued invite.'},
});

GRANT_PATH_ADMIN
#

auth/grant_path_schema.ts view source

"admin" import {GRANT_PATH_ADMIN} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Admin-mediated grant — role_grant_offer_create plus admin-direct flows.

GRANT_PATH_BOOTSTRAP
#

auth/grant_path_schema.ts view source

"bootstrap" import {GRANT_PATH_BOOTSTRAP} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Bootstrap grant — one-shot flow during the keep's first-run bootstrap.

GRANT_PATH_NAME_REGEX
#

auth/grant_path_schema.ts view source

RegExp import {GRANT_PATH_NAME_REGEX} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Letter (lowercase a-z) start and end (or single letter), with letters and underscores in between. Mirrors RoleName, ScopeKindName, CredentialTypeName. Rejects empty strings, leading or trailing underscores, uppercase, and digits.

GRANT_PATH_SELF_SERVICE
#

auth/grant_path_schema.ts view source

"self_service" import {GRANT_PATH_SELF_SERVICE} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Self-service grant — caller toggles their own role_grant via self_service_role_set.

GRANT_PATH_SYSTEM
#

auth/grant_path_schema.ts view source

"system" import {GRANT_PATH_SYSTEM} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

System-mediated grant — signup hooks, automation, internal service flows.

GrantPathMeta
#

auth/grant_path_schema.ts view source

GrantPathMeta import type {GrantPathMeta} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Per-grant-path metadata. description is admin-UI-facing copy (mirrors RoleSpec.description and ScopeKindMeta.description). Open shape so v2 can extend without a breaking change.

`description?`

type string

GrantPathName
#

auth/grant_path_schema.ts view source

ZodString import type {GrantPathName} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

Zod schema for valid grant-path name strings.

GrantPathSchemaResult
#

auth/grant_path_schema.ts view source

GrantPathSchemaResult import type {GrantPathSchemaResult} from '@fuzdev/fuz_app/auth/grant_path_schema.js';

The result of create_grant_path_schema — a Zod schema and metadata map.

`GrantPath`

Zod schema that validates grant-path name strings against the registered set (builtins + consumer-declared). Use at I/O boundaries (admin UIs, codegen) and as the construction-time check inside create_role_schema for every RoleSpec.grant_paths entry.

type z.ZodType<string>

`grant_paths`

Map of every registered grant-path to its metadata. Keyed by name. Read at startup by admin / codegen surfaces.

type ReadonlyMap<string, GrantPathMeta>