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.
12 declarations
auth/grant_path_schema.ts view source
ReadonlyMap<string, GrantPathMeta> 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.
auth/grant_path_schema.ts view source
readonly ["admin", "self_service", "system", "bootstrap"] The builtin grant-path names as a const tuple.
auth/grant_path_schema.ts view source
ZodEnum<{ admin: "admin"; bootstrap: "bootstrap"; self_service: "self_service"; system: "system"; }> Zod enum for builtin grant paths only.
auth/grant_path_schema.ts view source
(consumer_paths?: Record<string, GrantPathMeta>): GrantPathSchemaResult 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_pathsoptional consumer-declared grant-path set with optional metadata
Record<string, GrantPathMeta>{}GrantPathSchemaResult {GrantPath, grant_paths} — Zod schema and metadata map
Error - if any `consumer_paths` key fails the `GrantPathName` regex, collides with a builtin name, or appears more than once// 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.'},
});auth/grant_path_schema.ts view source
"admin" Admin-mediated grant — role_grant_offer_create plus admin-direct flows.
auth/grant_path_schema.ts view source
"bootstrap" Bootstrap grant — one-shot flow during the keep's first-run bootstrap.
auth/grant_path_schema.ts view source
RegExp 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.
auth/grant_path_schema.ts view source
"self_service" Self-service grant — caller toggles their own role_grant via self_service_role_set.
auth/grant_path_schema.ts view source
"system" System-mediated grant — signup hooks, automation, internal service flows.
auth/grant_path_schema.ts view source
GrantPathMeta 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.
descriptionstringauth/grant_path_schema.ts view source
ZodString Zod schema for valid grant-path name strings.
auth/grant_path_schema.ts view source
GrantPathSchemaResult The result of create_grant_path_schema — a Zod schema and metadata map.
GrantPathZod 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.
z.ZodType<string>grant_pathsMap of every registered grant-path to its metadata. Keyed by name. Read at startup by admin / codegen surfaces.
ReadonlyMap<string, GrantPathMeta>