@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/auth/role_grant_queries.js

@@ -0,0 +1,320 @@
+/**
+ * Role grant database queries.
+ *
+ * Role grants are time-bounded, revocable grants of a role to an actor.
+ * The system is safe by default — no role_grant, no capability.
+ *
+ * @module
+ */
+import { assert_row } from '../db/assert_row.js';
+import { ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN, ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID, } from './role_grant_offer_schema.js';
+/**
+ * Grant a role_grant to an actor.
+ * Idempotent — if an active role_grant already exists for this actor, role, and
+ * scope, returns the existing role_grant instead of creating a duplicate.
+ *
+ * The `ON CONFLICT` target and the fallback `SELECT` both collapse `NULL`
+ * scopes via the same sentinel + index-side `'GLOBAL'` token used by the
+ * partial unique index (`role_grant_actor_role_scope_active_unique`). The
+ * `IS NOT DISTINCT FROM` form on the fallback is deliberate — plain `=`
+ * would miss the NULL-scope case where the conflict fired.
+ *
+ * `scope_kind` is paired-null with `scope_id` per the
+ * `role_grant_scope_kind_paired` CHECK; mismatched pairs raise at the DB
+ * layer rather than producing silent rows.
+ *
+ * @param deps - query dependencies
+ * @param input - the role_grant fields
+ * @returns the created or existing active role_grant
+ * @mutates `role_grant` table - inserts a row when no active role_grant matches `(actor_id, role, scope_kind, scope_id)`
+ */
+export const query_create_role_grant = async (deps, input) => {
+    const inserted = await deps.db.query_one(`INSERT INTO role_grant (actor_id, role, scope_kind, scope_id, expires_at, granted_by, source_offer_id)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7)
+		 ON CONFLICT (
+		   actor_id,
+		   role,
+		   COALESCE(scope_kind, '${ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN}'),
+		   COALESCE(scope_id, '${ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID}'::uuid)
+		 )
+		   WHERE revoked_at IS NULL
+		 DO NOTHING
+		 RETURNING *`, [
+        input.actor_id,
+        input.role,
+        input.scope_kind ?? null,
+        input.scope_id ?? null,
+        input.expires_at?.toISOString() ?? null,
+        input.granted_by ?? null,
+        input.source_offer_id ?? null,
+    ]);
+    if (inserted)
+        return inserted;
+    // Active role_grant already exists — return it (idempotent grant).
+    const existing = await deps.db.query_one(`SELECT * FROM role_grant
+		 WHERE actor_id = $1
+		   AND role = $2
+		   AND scope_kind IS NOT DISTINCT FROM $3
+		   AND scope_id IS NOT DISTINCT FROM $4
+		   AND revoked_at IS NULL`, [input.actor_id, input.role, input.scope_kind ?? null, input.scope_id ?? null]);
+    return assert_row(existing, 'idempotent role_grant grant');
+};
+/**
+ * Look up the role of an active role_grant (constrained to a specific
+ * actor) plus the actor's `account_id`.
+ *
+ * Used by admin routes to inspect the role_grant's role before acting
+ * (e.g., enforcing the admin-grant-path gate on revoke). The actor constraint
+ * mirrors `query_revoke_role_grant` so IDOR protection is consistent:
+ * a caller can only see role_grants belonging to the target actor.
+ *
+ * The JOIN to `actor` collapses what used to be a second
+ * `query_actor_by_id` round-trip in the revoke handler into one read,
+ * which closes the small TOCTOU window where the actor row could be
+ * deleted between the IDOR check and the actor lookup. The `account_id`
+ * is needed by the audit envelope's `target_account_id` field and the
+ * SSE/WS socket-close fan-out targeting.
+ *
+ * Returns `null` if the role_grant is not found, already revoked, or
+ * belongs to a different actor.
+ *
+ * @param deps - query dependencies
+ * @param role_grant_id - the role_grant id to look up
+ * @param actor_id - the actor that must own the role_grant
+ * @returns `{role, account_id}` on a match, or `null`
+ */
+export const query_role_grant_find_active_role_for_actor = async (deps, role_grant_id, actor_id) => {
+    const row = await deps.db.query_one(`SELECT role_grant.role, actor.account_id
+		   FROM role_grant
+		   JOIN actor ON actor.id = role_grant.actor_id
+		  WHERE role_grant.id = $1 AND role_grant.actor_id = $2 AND role_grant.revoked_at IS NULL`, [role_grant_id, actor_id]);
+    return row ?? null;
+};
+/**
+ * Revoke a role_grant by id, constrained to a specific actor.
+ *
+ * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
+ * Returns `null` if the role_grant is not found, already revoked, or belongs
+ * to a different actor.
+ *
+ * Supersedes any pending offers for the revoked role_grant's
+ * `(to_account, role, scope)` in the same transaction. Prevents the
+ * "accept a pre-revoke offer to bypass the revoke" path — any stale
+ * offer becomes terminal at revoke time. A fresh post-revoke grant
+ * requires the grantor to call `query_role_grant_offer_create` again.
+ *
+ * @param deps - query dependencies
+ * @param role_grant_id - the role_grant to revoke
+ * @param actor_id - the actor that must own the role_grant
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason` and surfaced to the revokee notification.
+ * @mutates `role_grant` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
+ * @mutates `role_grant_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
+ */
+export const query_revoke_role_grant = async (deps, role_grant_id, actor_id, revoked_by, reason) => {
+    const rows = await deps.db.query(`UPDATE role_grant SET revoked_at = NOW(), revoked_by = $3, revoked_reason = $4
+		 WHERE id = $1 AND actor_id = $2 AND revoked_at IS NULL
+		 RETURNING id, role, scope_kind, scope_id`, [role_grant_id, actor_id, revoked_by ?? null, reason ?? null]);
+    const revoked = rows[0];
+    if (!revoked)
+        return null;
+    // CTE joins `actor` after the UPDATE so each superseded row carries the
+    // grantor's `account_id` — callers fan out `role_grant_offer_supersede`
+    // notifications to that account without a second round-trip. The match
+    // keys on `scope_id` only because the (scope_kind, scope_id) pair-CHECK
+    // makes scope_kind a function of scope_id; matching on both adds no
+    // new selectivity in v1.
+    const superseded_offers = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant_offer o
+			SET superseded_at = NOW()
+			FROM actor a
+			WHERE a.id = $1
+			  AND o.to_account_id = a.account_id
+			  AND o.role = $2
+			  AND o.scope_id IS NOT DISTINCT FROM $3
+			  AND o.accepted_at IS NULL
+			  AND o.declined_at IS NULL
+			  AND o.retracted_at IS NULL
+			  AND o.superseded_at IS NULL
+			RETURNING o.*
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [actor_id, revoked.role, revoked.scope_id]);
+    return {
+        id: revoked.id,
+        role: revoked.role,
+        scope_kind: revoked.scope_kind,
+        scope_id: revoked.scope_id,
+        superseded_offers,
+    };
+};
+/**
+ * Find all active (non-revoked, non-expired) role_grants for an actor.
+ */
+export const query_role_grant_find_active_for_actor = async (deps, actor_id) => {
+    return deps.db.query(`SELECT * FROM role_grant
+		 WHERE actor_id = $1
+		   AND revoked_at IS NULL
+		   AND (expires_at IS NULL OR expires_at > NOW())
+		 ORDER BY created_at`, [actor_id]);
+};
+/**
+ * Check if an actor has an active role_grant for a given role.
+ *
+ * The `scope_id` parameter selects between global and scoped checks:
+ * - Omitted or `null` — matches a global role_grant (`scope_id IS NULL`).
+ *   Pre-scope callers keep their existing semantics.
+ * - A scope uuid — matches a role_grant bound to that exact scope.
+ *
+ * The `IS NOT DISTINCT FROM` comparison handles the NULL case uniformly.
+ */
+export const query_role_grant_has_role = async (deps, actor_id, role, scope_id) => {
+    const row = await deps.db.query_one(`SELECT EXISTS(
+			SELECT 1 FROM role_grant
+			WHERE actor_id = $1
+			  AND role = $2
+			  AND scope_id IS NOT DISTINCT FROM $3
+			  AND revoked_at IS NULL
+			  AND (expires_at IS NULL OR expires_at > NOW())
+		 ) AS exists`, [actor_id, role, scope_id ?? null]);
+    return row?.exists ?? false;
+};
+/**
+ * List all role_grants for an actor (including revoked/expired).
+ */
+export const query_role_grant_list_for_actor = async (deps, actor_id) => {
+    return deps.db.query(`SELECT * FROM role_grant WHERE actor_id = $1 ORDER BY created_at DESC`, [actor_id]);
+};
+/**
+ * Find the account ID of an account that holds an active role_grant for a given role.
+ *
+ * Joins role_grant → actor → account. Returns the first match, or `null` if none.
+ *
+ * @param deps - query dependencies
+ * @param role - the role to search for
+ * @returns the account ID, or `null`
+ */
+export const query_role_grant_find_account_id_for_role = async (deps, role) => {
+    const row = await deps.db.query_one(`SELECT a.id AS account_id
+		 FROM role_grant p
+		 JOIN actor act ON act.id = p.actor_id
+		 JOIN account a ON a.id = act.account_id
+		 WHERE p.role = $1
+		   AND p.revoked_at IS NULL
+		   AND (p.expires_at IS NULL OR p.expires_at > NOW())
+		 LIMIT 1`, [role]);
+    return row?.account_id ?? null;
+};
+/**
+ * Revoke every active role_grant bound to a scope and supersede every pending
+ * offer at the scope, in one cascade.
+ *
+ * Use this from a consumer's parent-scope delete handler (e.g., classroom
+ * deletion) — `role_grant.scope_id` and `role_grant_offer.scope_id` are polymorphic
+ * with no FK constraint by design, so a parent row deletion would otherwise
+ * orphan role_grants and offers. The cascade is **role-agnostic**: anything
+ * attached to the destroyed scope is cleaned up.
+ *
+ * Both updates run as separate statements inside the caller's transaction
+ * (mirrors `query_role_grant_revoke_role`'s shape). The two halves are
+ * independent — orphan pending offers can exist at a scope with no active
+ * role_grants, so the supersede half always runs even when no role_grant was
+ * revoked.
+ *
+ * @param deps - query dependencies
+ * @param scope_id - the scope whose role_grants and offers to terminate
+ * @param revoked_by - the actor performing the cascade (audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason`.
+ * @returns the revoked role_grants (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
+ * @mutates `role_grant` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
+ * @mutates `role_grant_offer` table - stamps `superseded_at` on every pending row at `scope_id`
+ */
+export const query_role_grant_revoke_for_scope = async (deps, scope_id, revoked_by, reason) => {
+    // Revoke every active role_grant at the scope. CTE returns `actor_id` directly
+    // from the role_grant row (drives `target_actor_id` audit envelopes); a join
+    // against `actor` resolves `account_id` for `target_account_id`
+    // + WS/SSE socket-close fan-out, all in one round-trip.
+    const revoked = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant
+			SET revoked_at = NOW(), revoked_by = $2, revoked_reason = $3
+			WHERE scope_id = $1 AND revoked_at IS NULL
+			RETURNING id, role, scope_kind, scope_id, actor_id
+		)
+		SELECT u.id AS role_grant_id, u.role, u.scope_kind, u.scope_id, u.actor_id, a.account_id
+		FROM updated u
+		JOIN actor a ON a.id = u.actor_id`, [scope_id, revoked_by ?? null, reason ?? null]);
+    // Supersede every pending offer at the scope — tuple-matched or orphan,
+    // no distinction. The cause of every supersede in this cascade is the
+    // scope deletion; offers tuple-matched to a revoked role_grant are not
+    // tagged separately because the revoke is itself a consequence of the
+    // scope going away.
+    const superseded_offers = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant_offer o
+			SET superseded_at = NOW()
+			WHERE o.scope_id = $1
+			  AND o.accepted_at IS NULL
+			  AND o.declined_at IS NULL
+			  AND o.retracted_at IS NULL
+			  AND o.superseded_at IS NULL
+			RETURNING o.*
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [scope_id]);
+    return { revoked, superseded_offers };
+};
+/**
+ * Revoke every active role_grant an actor holds for a given role.
+ *
+ * With scoped role_grants a single actor+role tuple can hold several active
+ * role_grants (one per scope), so this revokes all of them. Pass
+ * `query_revoke_role_grant(role_grant_id, ...)` when a single scoped role_grant
+ * is the target.
+ *
+ * Also supersedes pending offers for the actor's account across every
+ * scope of this role (the actor can no longer hold the role, so any
+ * pending offer of the same role is a bypass vector).
+ *
+ * @param deps - query dependencies
+ * @param actor_id - the actor whose role_grants to revoke
+ * @param role - the role to revoke
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason`.
+ * @returns the list of revoked role_grants (empty if none were active) and superseded pending offers
+ * @mutates `role_grant` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
+ * @mutates `role_grant_offer` table - stamps `superseded_at` on every matching pending offer
+ */
+export const query_role_grant_revoke_role = async (deps, actor_id, role, revoked_by, reason) => {
+    // CTE pulls the revokee's `account_id` via a join on `actor` so callers
+    // can address the revokee without an extra round-trip.
+    const revoked = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant
+			SET revoked_at = NOW(), revoked_by = $3, revoked_reason = $4
+			WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL
+			RETURNING id, role, scope_kind, scope_id, actor_id
+		)
+		SELECT u.id AS role_grant_id, u.role, u.scope_kind, u.scope_id, a.account_id
+		FROM updated u
+		JOIN actor a ON a.id = u.actor_id`, [actor_id, role, revoked_by ?? null, reason ?? null]);
+    if (revoked.length === 0) {
+        return { revoked: [], superseded_offers: [] };
+    }
+    const superseded_offers = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant_offer o
+			SET superseded_at = NOW()
+			FROM actor a
+			WHERE a.id = $1
+			  AND o.to_account_id = a.account_id
+			  AND o.role = $2
+			  AND o.accepted_at IS NULL
+			  AND o.declined_at IS NULL
+			  AND o.retracted_at IS NULL
+			  AND o.superseded_at IS NULL
+			RETURNING o.*
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [actor_id, role]);
+    return { revoked, superseded_offers };
+};

package/dist/auth/role_schema.d.ts

@@ -1,80 +1,190 @@
 /**
- * Role system — builtin roles, role options, and extensible role schema factory.
+ * Role system — builtin roles, role specs, and extensible role schema factory.
  *
- * Defines the authorization policy vocabulary: which roles exist, what
- * capabilities they require (daemon token, web grantability), and a factory
- * for extending with app-defined roles.
+ * Defines the authorization policy vocabulary: which roles exist, their
+ * required credential types, the scope kinds each role applies to, and
+ * the grant paths through which each role can be granted. Each role
+ * gets a structured `RoleSpec`; the factory `create_role_schema` merges
+ * builtins with consumer-declared specs and validates every cross-axis
+ * field against the corresponding open registries
+ * (`create_credential_type_schema`, `create_scope_kind_schema`,
+ * `create_grant_path_schema`) at construction time so misconfigurations
+ * fire at server startup, not at first call.
+ *
+ * `RoleSpec` carries the four cross-axis fields that the dispatcher
+ * branches on: credential type, scope kind, grant path, and the
+ * role-name itself. v1 keeps the cross-axis fields informative-only
+ * (registry-membership validation, no INSERT-time enforcement); v2 may
+ * add `(role, scope_kind)` enforcement once the shape is clear from
+ * real consumer usage.
  *
  * @module
  */
 import { z } from 'zod';
+import { type CredentialTypeSchemaResult } from './credential_type_schema.js';
+import { type GrantPathSchemaResult } from './grant_path_schema.js';
+import type { ScopeKindSchemaResult } from './scope_kind_schema.js';
 /** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
 export declare const RoleName: z.ZodString;
 export type RoleName = z.infer<typeof RoleName>;
 /** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
 export declare const ROLE_KEEPER = "keeper";
-/** App-level administrative role. Web-grantable, manages users and content. */
+/** App-level administrative role. Granted via the admin path. */
 export declare const ROLE_ADMIN = "admin";
 /** The builtin role names as a const tuple. */
 export declare const BUILTIN_ROLES: readonly ["keeper", "admin"];
 /** Zod schema for builtin roles only. */
 export declare const BuiltinRole: z.ZodEnum<{
-    keeper: "keeper";
     admin: "admin";
+    keeper: "keeper";
 }>;
 export type BuiltinRole = z.infer<typeof BuiltinRole>;
 /**
  * Configuration for a role.
  *
- * Builtin roles have fixed configs. App-defined roles get sensible defaults
- * (`requires_daemon_token: false`, `web_grantable: true`).
+ * Each role declares the credential types its holders must use, the
+ * scope kinds it applies to, and the grant paths through which it can
+ * be granted. Every cross-axis field is an open-registry string array —
+ * `required_credential_types` against `create_credential_type_schema`,
+ * `applicable_scope_kinds` against `create_scope_kind_schema`,
+ * `grant_paths` against `create_grant_path_schema`. Pass the registry
+ * results to `create_role_schema` and every entry is checked at
+ * construction time.
+ *
+ * Empty arrays carry meaning:
+ *
+ * - `required_credential_types: []` — any authenticated credential type
+ *   may exercise the role (the default for app-defined roles).
+ * - `applicable_scope_kinds: []` — the role applies at the global scope
+ *   only (no `scope_kind` / `scope_id` set on its role_grants). This is the
+ *   default for app-defined roles; consumers add scope kinds explicitly.
+ * - `grant_paths: []` — the role has no grant path declared in this
+ *   registry; it is unreachable through admin / self-service / system
+ *   flows. Only useful for diagnostic snapshotting.
+ *
+ * Builtins (`keeper`, `admin`) ship preconfigured in
+ * `BUILTIN_ROLE_SPECS_BY_NAME`.
  */
-export interface RoleOptions {
-    /** If true, exercising this role requires daemon token authentication. Only `keeper` for now. */
-    requires_daemon_token?: boolean;
-    /** If true, admins can grant this role via the web UI. Default `true`. */
-    web_grantable?: boolean;
+export interface RoleSpec {
+    /** Unique role name. Must match `RoleName` regex; collisions with builtins throw. */
+    name: string;
+    /** Admin-UI-facing copy describing the role's intent. */
+    description?: string;
+    /**
+     * Credential types whose holders are permitted to exercise this
+     * role. Each entry is checked at construction time against the
+     * `credential_types` registry passed to `create_role_schema`. Empty
+     * array = any authenticated credential type.
+     */
+    required_credential_types?: ReadonlyArray<string>;
+    /**
+     * Scope kinds at which this role's role_grants may be granted. Each
+     * entry is checked at construction time against the `scope_kinds`
+     * registry passed to `create_role_schema`. Empty array = global only.
+     * v1 keeps this informative-only (no INSERT-time enforcement).
+     */
+    applicable_scope_kinds?: ReadonlyArray<string>;
+    /**
+     * Grant paths through which this role can be granted. Each entry is
+     * checked at construction time against the `grant_paths` registry
+     * passed to `create_role_schema`. Drives downstream defaults:
+     *
+     * - `admin_actions.grantable_roles` ⊇ {role : `'admin'` ∈ grant_paths}
+     * - `self_service_role_actions` default eligibility ⊇ {role : `'self_service'` ∈ grant_paths}
+     *
+     * Empty array = role is not granted via any registered path (only
+     * exists for diagnostic / future use).
+     */
+    grant_paths?: ReadonlyArray<string>;
 }
 /**
- * Builtin role configs. 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_role_schema` and the admin / permit-offer
- * action factories; runtime mutation has no effect on already-built role
- * schemas.
+ * Builtin role specs, keyed by role name. Not overridable by consumers
+ * — read once at startup by `create_role_schema` and the action
+ * factories that fall back to builtins when no consumer `roles` is
+ * supplied. `ReadonlyMap` encodes the contract; runtime mutation has
+ * no effect on already-built role schemas (the factory copies entries
+ * into a fresh `Map`).
  */
-export declare const BUILTIN_ROLE_OPTIONS: ReadonlyMap<string, Required<RoleOptions>>;
-/** The result of `create_role_schema` — a Zod schema and config map for all roles. */
+export declare const BUILTIN_ROLE_SPECS_BY_NAME: ReadonlyMap<string, RoleSpec>;
+/** Optional registries to validate `RoleSpec` cross-axis fields against at construction time. */
+export interface CreateRoleSchemaOptions {
+    /** Pass `create_credential_type_schema()` to validate `RoleSpec.required_credential_types` entries. */
+    credential_types?: CredentialTypeSchemaResult;
+    /** Pass `create_scope_kind_schema()` to validate `RoleSpec.applicable_scope_kinds` entries. */
+    scope_kinds?: ScopeKindSchemaResult;
+    /** Pass `create_grant_path_schema()` to validate `RoleSpec.grant_paths` entries. */
+    grant_paths?: GrantPathSchemaResult;
+}
+/** The result of `create_role_schema` — a Zod schema and spec map for all roles. */
 export interface RoleSchemaResult {
-    /** Zod schema that validates role strings. Use at I/O boundaries (grant endpoint, permit queries). */
+    /** Zod schema that validates role strings. Use at I/O boundaries (grant endpoint, role_grant queries). */
     Role: z.ZodType<string>;
-    /** Options for every role (builtins + app-defined). Keyed by role name. */
-    role_options: ReadonlyMap<string, Required<RoleOptions>>;
+    /** Specs for every role (builtins + app-defined). Keyed by role name. */
+    role_specs: ReadonlyMap<string, RoleSpec>;
 }
 /**
- * Create a role schema and config map that extends the builtins with app-defined roles.
+ * Create a role schema and spec map that extends the builtins with
+ * app-defined roles.
+ *
+ * Call once at server init. The returned `Role` schema validates role
+ * strings at I/O boundaries (grant endpoint, role_grant queries). The
+ * `role_specs` map is read by middleware for `required_credential_types`
+ * checks and by admin / self-service factories to derive their default
+ * eligibility filters from `RoleSpec.grant_paths`.
+ *
+ * Construction-time guards (all fire on misconfiguration):
  *
- * Call once at server init. The returned `Role` schema validates role strings
- * at I/O boundaries (grant endpoint, permit queries). The `role_options` map
- * is used by middleware to check `requires_daemon_token` and by admin UI to
- * filter `web_grantable` roles.
+ * 1. Every `consumer_roles[i].name` matches `RoleName` regex.
+ * 2. No two consumer roles share a name.
+ * 3. No consumer role collides with a builtin (`keeper` / `admin`).
+ * 4. When `options.credential_types` is supplied, every entry in
+ *    `required_credential_types` is registered in that map.
+ * 5. When `options.scope_kinds` is supplied, every entry in
+ *    `applicable_scope_kinds` is registered in that map. (Builtins
+ *    declare empty `applicable_scope_kinds`, so they pass any registry.)
+ * 6. When `options.grant_paths` is supplied, every entry in
+ *    `grant_paths` is registered in that map. (Builtins use only
+ *    `'admin'` and `'bootstrap'`, both of which are builtin grant
+ *    paths, so they pass the default registry from
+ *    `create_grant_path_schema()`.)
  *
- * @param app_roles - app-defined roles with optional config overrides
- * @returns `{Role, role_options}` — Zod schema and full config map
+ * @param consumer_roles - app-defined role specs
+ * @param options - optional registries for cross-axis validation
+ * @returns `{Role, role_specs}` — Zod schema and full spec map
  *
- * @throws Error if any `app_roles` key fails the `RoleName` regex or collides with a builtin role
+ * @throws Error if any `consumer_roles` entry fails any of the construction-time guards above
  *
  * @example
  * ```ts
- * // visiones
- * const {Role, role_options} = create_role_schema({
- *   teacher: {},
+ * // visiones — opt into all four registries for full construction-time validation
+ * const credential_types = create_credential_type_schema();
+ * const scope_kinds = create_scope_kind_schema({
+ *   classroom: {description: 'A classroom — teacher and student role_grants scope here.'},
  * });
- * // Role validates 'keeper' | 'admin' | 'teacher'
- * // role_options has all 3 entries with defaults applied
+ * const grant_paths = create_grant_path_schema();
+ *
+ * const {Role, role_specs} = create_role_schema(
+ *   [
+ *     {
+ *       name: 'teacher',
+ *       description: 'Educator role. Web-grantable; applies at classroom scope.',
+ *       grant_paths: ['admin'],
+ *       applicable_scope_kinds: ['classroom'],
+ *     },
+ *   ],
+ *   {credential_types, scope_kinds, grant_paths},
+ * );
  * ```
  */
-export declare const create_role_schema: <T extends string>(app_roles: Record<T, RoleOptions>) => RoleSchemaResult;
+export declare const create_role_schema: (consumer_roles: ReadonlyArray<RoleSpec>, options?: CreateRoleSchemaOptions) => RoleSchemaResult;
+/**
+ * Predicate over a `RoleSpec` map: does the named role include the given
+ * grant path? Returns `false` for unknown roles. Used by
+ * `admin_actions.create_admin_actions` (path = `'admin'`) and
+ * `self_service_role_actions.create_self_service_role_actions` (path =
+ * `'self_service'`) to derive their default eligibility filters.
+ */
+export declare const role_has_grant_path: (role_specs: ReadonlyMap<string, RoleSpec>, role: string, grant_path: string) => boolean;
+/** Filter helper: list every role whose `grant_paths` includes the given path. */
+export declare const list_roles_with_grant_path: (role_specs: ReadonlyMap<string, RoleSpec>, grant_path: string) => Array<string>;
 //# sourceMappingURL=role_schema.d.ts.map

package/dist/auth/role_schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAItD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAG1E,CAAC;AAEH,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAChC,sGAAsG;IACtG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,EAClD,WAAW,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,KAC/B,gBAwBF,CAAC"}
+{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,wBAAwB,CAAC;AAElE,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,iEAAiE;AACjE,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAuBnE,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACvC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,+FAA+F;IAC/F,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oFAAoF;IACpF,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,kBAAkB,GAC9B,gBAAgB,aAAa,CAAC,QAAQ,CAAC,EACvC,UAAS,uBAA4B,KACnC,gBA2CF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,MAAM,MAAM,EACZ,YAAY,MAAM,KAChB,OAGF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,GACtC,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,YAAY,MAAM,KAChB,KAAK,CAAC,MAAM,CAMd,CAAC"}