@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/auth/role_schema.js

@@ -1,13 +1,28 @@
 /**
- * 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 { CREDENTIAL_TYPE_DAEMON_TOKEN, } from './credential_type_schema.js';
+import { GRANT_PATH_ADMIN, GRANT_PATH_BOOTSTRAP, } from './grant_path_schema.js';
 /** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
 export const RoleName = z
     .string()
@@ -15,67 +30,151 @@ export const RoleName = z
 // Builtin roles — provided by fuz_app, always available.
 /** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
 export const ROLE_KEEPER = 'keeper';
-/** App-level administrative role. Web-grantable, manages users and content. */
+/** App-level administrative role. Granted via the admin path. */
 export const ROLE_ADMIN = 'admin';
 /** The builtin role names as a const tuple. */
 export const BUILTIN_ROLES = [ROLE_KEEPER, ROLE_ADMIN];
 /** Zod schema for builtin roles only. */
 export const BuiltinRole = z.enum(BUILTIN_ROLES);
 /**
- * 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 const BUILTIN_ROLE_OPTIONS = new Map([
-    [ROLE_KEEPER, { requires_daemon_token: true, web_grantable: false }],
-    [ROLE_ADMIN, { requires_daemon_token: false, web_grantable: true }],
+export const BUILTIN_ROLE_SPECS_BY_NAME = new Map([
+    [
+        ROLE_KEEPER,
+        {
+            name: ROLE_KEEPER,
+            description: 'System-level role; controls the keep. Requires the daemon-token credential and lands via the bootstrap grant path.',
+            required_credential_types: [CREDENTIAL_TYPE_DAEMON_TOKEN],
+            applicable_scope_kinds: [],
+            grant_paths: [GRANT_PATH_BOOTSTRAP],
+        },
+    ],
+    [
+        ROLE_ADMIN,
+        {
+            name: ROLE_ADMIN,
+            description: 'App-level administrative role. Web-grantable through the admin path; manages users and content.',
+            required_credential_types: [],
+            applicable_scope_kinds: [],
+            grant_paths: [GRANT_PATH_ADMIN],
+        },
+    ],
 ]);
+const validate_registry_membership = (role_name, field, values, registry) => {
+    if (!registry || !values)
+        return;
+    for (const value of values) {
+        if (!registry.has(value)) {
+            throw new Error(`Role "${role_name}" declares ${field}="${value}" which is not a registered ${field.replace(/s$/, '')}`);
+        }
+    }
+};
 /**
- * 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`.
  *
- * 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.
+ * Construction-time guards (all fire on misconfiguration):
  *
- * @param app_roles - app-defined roles with optional config overrides
- * @returns `{Role, role_options}` — Zod schema and full config map
+ * 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()`.)
  *
- * @throws Error if any `app_roles` key fails the `RoleName` regex or collides with a builtin role
+ * @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 `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 const create_role_schema = (app_roles) => {
-    const app_role_names = Object.keys(app_roles);
-    // Validate role names and no collisions with builtins
-    for (const name of app_role_names) {
-        RoleName.parse(name);
-        if (BUILTIN_ROLE_OPTIONS.has(name)) {
-            throw new Error(`App role "${name}" collides with builtin role`);
+export const create_role_schema = (consumer_roles, options = {}) => {
+    const credential_types_registry = options.credential_types?.credential_types ?? null;
+    const scope_kinds_registry = options.scope_kinds?.scope_kinds ?? null;
+    const grant_paths_registry = options.grant_paths?.grant_paths ?? null;
+    const seen = new Set();
+    for (const spec of consumer_roles) {
+        const parsed = RoleName.safeParse(spec.name);
+        if (!parsed.success) {
+            throw new Error(`Invalid role name "${spec.name}": ${parsed.error.issues[0].message}`);
         }
+        if (BUILTIN_ROLE_SPECS_BY_NAME.has(spec.name)) {
+            throw new Error(`App role "${spec.name}" collides with builtin role`);
+        }
+        if (seen.has(spec.name)) {
+            throw new Error(`Duplicate role name "${spec.name}"`);
+        }
+        seen.add(spec.name);
+        validate_registry_membership(spec.name, 'required_credential_types', spec.required_credential_types, credential_types_registry);
+        validate_registry_membership(spec.name, 'applicable_scope_kinds', spec.applicable_scope_kinds, scope_kinds_registry);
+        validate_registry_membership(spec.name, 'grant_paths', spec.grant_paths, grant_paths_registry);
     }
-    const all_names = [...BUILTIN_ROLES, ...app_role_names];
+    const role_specs = new Map(BUILTIN_ROLE_SPECS_BY_NAME);
+    for (const spec of consumer_roles) {
+        role_specs.set(spec.name, spec);
+    }
+    const all_names = [...role_specs.keys()];
     const Role = z.enum(all_names);
-    const role_options = new Map(BUILTIN_ROLE_OPTIONS);
-    for (const name of app_role_names) {
-        const config = app_roles[name];
-        role_options.set(name, {
-            requires_daemon_token: config.requires_daemon_token ?? false,
-            web_grantable: config.web_grantable ?? true,
-        });
+    return { Role, role_specs };
+};
+/**
+ * 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 const role_has_grant_path = (role_specs, role, grant_path) => {
+    const spec = role_specs.get(role);
+    return !!spec?.grant_paths?.includes(grant_path);
+};
+/** Filter helper: list every role whose `grant_paths` includes the given path. */
+export const list_roles_with_grant_path = (role_specs, grant_path) => {
+    const out = [];
+    for (const [name, spec] of role_specs) {
+        if (spec.grant_paths?.includes(grant_path))
+            out.push(name);
     }
-    return { Role, role_options };
+    return out;
 };

package/dist/auth/scope_kind_schema.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Scope-kind registry for role_grants and role_grant offers.
+ *
+ * Role grants have a polymorphic `scope_id` that references whatever entity
+ * the consumer chooses (a classroom, a tenant, a workspace, etc.); the
+ * `scope_kind` column tags each row with a machine-readable kind so
+ * admin UIs, codegen, and (in v2) registry-time `(role, scope_kind)`
+ * compatibility checks can read it without re-deriving from `scope_id`.
+ *
+ * `scope_kind` is encoded as nullable paired with the existing nullable
+ * `scope_id` — both null for global, both non-null for scoped, mismatch
+ * rejected at the DB layer by the `role_grant_scope_kind_paired` /
+ * `role_grant_offer_scope_kind_paired` CHECK constraints. There is no
+ * `'global'` magic-string value; the global case is unambiguously
+ * `(scope_kind=NULL, scope_id=NULL)`.
+ *
+ * Open registry, no builtins. Consumers declare their kinds via
+ * `create_scope_kind_schema(consumer_kinds)` and pass the result to
+ * `create_role_schema` so `RoleSpec.applicable_scope_kinds` can be
+ * validated at construction time. Mirrors the open-string registry
+ * pattern used for `RoleName`, `AuditEventTypeName`, and `CredentialType`.
+ *
+ * The literal `'GLOBAL'` (uppercase) appears as an index expression
+ * inside the partial unique indexes on `role_grant` and `role_grant_offer`
+ * (`COALESCE(scope_kind, 'GLOBAL')`) — never as a column value, never
+ * as a registry entry. The uppercase form is structurally distinct
+ * from any consumer-declared kind (which match the lowercase
+ * `ScopeKindName` regex), so it cannot collide.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Letter (lowercase a-z) start and end (or single letter), with letters
+ * and underscores in between. Mirrors `RoleName`. Rejects empty strings,
+ * leading or trailing underscores, uppercase, digits, and the index-side
+ * `'GLOBAL'` token.
+ */
+export declare const SCOPE_KIND_NAME_REGEX: RegExp;
+/** Zod schema for valid scope-kind name strings. */
+export declare const ScopeKindName: z.ZodString;
+export type ScopeKindName = z.infer<typeof ScopeKindName>;
+/**
+ * Per-scope-kind metadata. `description` is admin-UI-facing copy
+ * (mirrors `RoleSpec.description`). Open shape so v2 can extend without
+ * a breaking change.
+ */
+export interface ScopeKindMeta {
+    description?: string;
+}
+/** The result of `create_scope_kind_schema` — a Zod schema and metadata map. */
+export interface ScopeKindSchemaResult {
+    /**
+     * Zod schema that validates scope-kind name strings against the
+     * registered set. Use at I/O boundaries (admin UIs, codegen) and as
+     * the construction-time check inside `create_role_schema` for every
+     * `RoleSpec.applicable_scope_kinds` entry.
+     */
+    ScopeKind: z.ZodType<string>;
+    /**
+     * Map of every registered scope-kind to its metadata. Keyed by name.
+     * Read at startup by admin / codegen surfaces.
+     */
+    scope_kinds: ReadonlyMap<string, ScopeKindMeta>;
+}
+/**
+ * Create a scope-kind schema from a consumer-declared registry.
+ *
+ * Open registry — no builtins. The `'GLOBAL'` token used inside the
+ * partial unique indexes on `role_grant` and `role_grant_offer` is not a
+ * registry entry (it's an index expression only) and cannot collide
+ * with consumer-declared kinds because the regex rejects uppercase.
+ *
+ * Call once at server init. Pass the result into `create_role_schema`'s
+ * optional `scope_kinds` parameter so each role's
+ * `applicable_scope_kinds` entries are validated against this set at
+ * construction time. v1 keeps `applicable_scope_kinds` informative-only
+ * (registry-membership validation only); v2 may add INSERT-time
+ * `(role, scope_kind)` enforcement once the shape is clear from real
+ * consumer usage.
+ *
+ * @param consumer_kinds - the consumer-declared scope-kind set with optional metadata
+ * @returns `{ScopeKind, scope_kinds}` — Zod schema and metadata map
+ *
+ * @throws Error if any `consumer_kinds` key fails the `ScopeKindName` regex or appears more than once
+ *
+ * @example
+ * ```ts
+ * // visiones
+ * const {ScopeKind, scope_kinds} = create_scope_kind_schema({
+ *   classroom: {description: 'A classroom — teacher and student role_grants scope here.'},
+ * });
+ * ```
+ */
+export declare const create_scope_kind_schema: (consumer_kinds: Record<string, ScopeKindMeta>) => ScopeKindSchemaResult;
+//# sourceMappingURL=scope_kind_schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope_kind_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/scope_kind_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAgC,CAAC;AAEnE,oDAAoD;AACpD,eAAO,MAAM,aAAa,aAKxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACrC;;;;;OAKG;IACH,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB,GACpC,gBAAgB,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KAC3C,qBA0BF,CAAC"}

package/dist/auth/scope_kind_schema.js

@@ -0,0 +1,94 @@
+/**
+ * Scope-kind registry for role_grants and role_grant offers.
+ *
+ * Role grants have a polymorphic `scope_id` that references whatever entity
+ * the consumer chooses (a classroom, a tenant, a workspace, etc.); the
+ * `scope_kind` column tags each row with a machine-readable kind so
+ * admin UIs, codegen, and (in v2) registry-time `(role, scope_kind)`
+ * compatibility checks can read it without re-deriving from `scope_id`.
+ *
+ * `scope_kind` is encoded as nullable paired with the existing nullable
+ * `scope_id` — both null for global, both non-null for scoped, mismatch
+ * rejected at the DB layer by the `role_grant_scope_kind_paired` /
+ * `role_grant_offer_scope_kind_paired` CHECK constraints. There is no
+ * `'global'` magic-string value; the global case is unambiguously
+ * `(scope_kind=NULL, scope_id=NULL)`.
+ *
+ * Open registry, no builtins. Consumers declare their kinds via
+ * `create_scope_kind_schema(consumer_kinds)` and pass the result to
+ * `create_role_schema` so `RoleSpec.applicable_scope_kinds` can be
+ * validated at construction time. Mirrors the open-string registry
+ * pattern used for `RoleName`, `AuditEventTypeName`, and `CredentialType`.
+ *
+ * The literal `'GLOBAL'` (uppercase) appears as an index expression
+ * inside the partial unique indexes on `role_grant` and `role_grant_offer`
+ * (`COALESCE(scope_kind, 'GLOBAL')`) — never as a column value, never
+ * as a registry entry. The uppercase form is structurally distinct
+ * from any consumer-declared kind (which match the lowercase
+ * `ScopeKindName` regex), so it cannot collide.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Letter (lowercase a-z) start and end (or single letter), with letters
+ * and underscores in between. Mirrors `RoleName`. Rejects empty strings,
+ * leading or trailing underscores, uppercase, digits, and the index-side
+ * `'GLOBAL'` token.
+ */
+export const SCOPE_KIND_NAME_REGEX = /^[a-z][a-z_]*[a-z]$|^[a-z]$/;
+/** Zod schema for valid scope-kind name strings. */
+export const ScopeKindName = z
+    .string()
+    .regex(SCOPE_KIND_NAME_REGEX, 'Scope-kind names must be lowercase letters and underscores (a-z_), no leading/trailing underscore');
+/**
+ * Create a scope-kind schema from a consumer-declared registry.
+ *
+ * Open registry — no builtins. The `'GLOBAL'` token used inside the
+ * partial unique indexes on `role_grant` and `role_grant_offer` is not a
+ * registry entry (it's an index expression only) and cannot collide
+ * with consumer-declared kinds because the regex rejects uppercase.
+ *
+ * Call once at server init. Pass the result into `create_role_schema`'s
+ * optional `scope_kinds` parameter so each role's
+ * `applicable_scope_kinds` entries are validated against this set at
+ * construction time. v1 keeps `applicable_scope_kinds` informative-only
+ * (registry-membership validation only); v2 may add INSERT-time
+ * `(role, scope_kind)` enforcement once the shape is clear from real
+ * consumer usage.
+ *
+ * @param consumer_kinds - the consumer-declared scope-kind set with optional metadata
+ * @returns `{ScopeKind, scope_kinds}` — Zod schema and metadata map
+ *
+ * @throws Error if any `consumer_kinds` key fails the `ScopeKindName` regex or appears more than once
+ *
+ * @example
+ * ```ts
+ * // visiones
+ * const {ScopeKind, scope_kinds} = create_scope_kind_schema({
+ *   classroom: {description: 'A classroom — teacher and student role_grants scope here.'},
+ * });
+ * ```
+ */
+export const create_scope_kind_schema = (consumer_kinds) => {
+    const names = Object.keys(consumer_kinds);
+    const seen = new Set();
+    for (const name of names) {
+        const parsed = ScopeKindName.safeParse(name);
+        if (!parsed.success) {
+            throw new Error(`Invalid scope-kind name "${name}": ${parsed.error.issues[0].message}`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`Duplicate scope-kind name "${name}"`);
+        }
+        seen.add(name);
+    }
+    const ScopeKind = names.length === 0
+        ? z.never()
+        : z.enum(names);
+    const scope_kinds = new Map();
+    for (const name of names) {
+        scope_kinds.set(name, consumer_kinds[name]);
+    }
+    return { ScopeKind, scope_kinds };
+};

package/dist/auth/self_service_role_action_specs.d.ts

@@ -15,6 +15,7 @@ export declare const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE: "role_not_self_servic
 export declare const SelfServiceRoleSetInput: z.ZodObject<{
     role: z.ZodString;
     enabled: z.ZodBoolean;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
 }, z.core.$strict>;
 export type SelfServiceRoleSetInput = z.infer<typeof SelfServiceRoleSetInput>;
 /**
@@ -32,11 +33,15 @@ export declare const self_service_role_set_action_spec: {
     method: string;
     kind: "request_response";
     initiator: "frontend";
-    auth: "authenticated";
+    auth: {
+        account: "required";
+        actor: "required";
+    };
     side_effects: true;
     input: z.ZodObject<{
         role: z.ZodString;
         enabled: z.ZodBoolean;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
     }, z.core.$strict>;
     output: z.ZodObject<{
         ok: z.ZodLiteral<true>;

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAGzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,yCAAyC;AACzC,eAAO,MAAM,uBAAuB;;;kBAMlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;kBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;CAWT,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,aAAa,CAAC,yBAAyB,CAEvF,CAAC"}
+{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAIzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,yCAAyC;AACzC,eAAO,MAAM,uBAAuB;;;;kBAOlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;kBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;CAWT,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,aAAa,CAAC,yBAAyB,CAEvF,CAAC"}

package/dist/auth/self_service_role_action_specs.js

@@ -9,6 +9,7 @@
  */
 import { z } from 'zod';
 import { RoleName } from './role_schema.js';
+import { ActingActor } from '../http/auth_shape.js';
 /** Error reason — caller asked to self-toggle a role outside the configured allowlist. */
 export const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE = 'role_not_self_service_eligible';
 /** Input for `self_service_role_set`. */
@@ -17,6 +18,7 @@ export const SelfServiceRoleSetInput = z.strictObject({
     enabled: z.boolean().meta({
         description: 'Desired post-call state. `true` grants if not held; `false` revokes if held. Idempotent in both directions.',
     }),
+    acting: ActingActor,
 });
 /**
  * Output for `self_service_role_set`. `enabled` echoes the post-call state
@@ -32,7 +34,7 @@ export const self_service_role_set_action_spec = {
     method: 'self_service_role_set',
     kind: 'request_response',
     initiator: 'frontend',
-    auth: 'authenticated',
+    auth: { account: 'required', actor: 'required' },
     side_effects: true,
     input: SelfServiceRoleSetInput,
     output: SelfServiceRoleSetOutput,

package/dist/auth/self_service_role_actions.d.ts

@@ -2,19 +2,24 @@
  * Unified self-service role toggle RPC action.
  *
  * One static `request_response` action — `self_service_role_set` — that
- * takes `{role, enabled}` and toggles a global permit on the caller for an
+ * takes `{role, enabled}` and toggles a global role_grant on the caller for an
  * allowlisted role. Idempotent in both directions: re-enabling an
  * already-held role returns `changed: false`; disabling a role the caller
  * doesn't hold returns `changed: false`.
  *
- * The factory takes an `eligible_roles` allowlist (validated against the
- * supplied `roles.role_options` at factory time so typos surface at startup
- * instead of at first call). Roles outside the allowlist are rejected
- * with `forbidden` + reason `role_not_self_service_eligible`.
+ * Eligibility is derived by default from `RoleSpec.grant_paths` —
+ * every role whose `grant_paths` includes `'self_service'`
+ * (`GRANT_PATH_SELF_SERVICE`) is eligible. The factory accepts an
+ * optional `eligible_roles` override (validated against the supplied
+ * `roles.role_specs` at factory time so typos surface at startup
+ * instead of at first call) for deployments that want to lock the
+ * surface down further than the role spec declares. Roles outside
+ * the eligible set are rejected with `forbidden` + reason
+ * `role_not_self_service_eligible`.
  *
  * Audit metadata carries `self_service: true` so admin reviewers can
- * distinguish self-toggled permits from admin grants/offers. The
- * `permit_grant` / `permit_revoke` metadata schemas declare
+ * distinguish self-toggled role_grants from admin grants/offers. The
+ * `role_grant_create` / `role_grant_revoke` metadata schemas declare
  * `self_service: z.boolean().optional()` explicitly, so the field is
  * part of the documented schema surface and is round-trip-validated by
  * `query_audit_log`.
@@ -22,7 +27,7 @@
  * Static method name — `role` lives in the input, not the method name —
  * so the spec is codegen-compatible (`satisfies RequestResponseActionSpec`)
  * and the surface stays constant as consumers add eligible roles. Mirrors
- * the existing `permit_offer_create({role})` precedent rather than
+ * the existing `role_grant_offer_create({role})` precedent rather than
  * generating per-role methods.
  *
  * Specs and schemas live in `auth/self_service_role_action_specs.ts` so
@@ -32,37 +37,39 @@
  * @module
  */
 import { type RpcAction } from '../actions/action_rpc.js';
-import type { RoleSchemaResult } from './role_schema.js';
+import { type RoleSchemaResult } from './role_schema.js';
 import type { RouteFactoryDeps } from './deps.js';
 /** Options for `create_self_service_role_actions`. */
 export interface SelfServiceRoleActionsOptions {
     /**
-     * Allowlist of role strings eligible for self-service. Empty array
-     * effectively disables the surface — every call comes back as
-     * `forbidden` with reason `role_not_self_service_eligible`.
+     * Optional override allowlist of role strings eligible for
+     * self-service. When omitted, eligibility is derived from
+     * `roles.role_specs` (or `BUILTIN_ROLE_SPECS_BY_NAME` when `roles`
+     * is also omitted) by selecting every role whose
+     * `RoleSpec.grant_paths` includes `'self_service'`. Pass an empty
+     * array to lock the surface down (every call comes back as
+     * `forbidden` with reason `role_not_self_service_eligible`).
+     *
+     * When supplied alongside `roles`, every entry is checked against
+     * `roles.role_specs` at factory time so typos throw at startup.
      */
-    eligible_roles: ReadonlyArray<string>;
+    eligible_roles?: ReadonlyArray<string>;
     /**
-     * Optional role schema. When supplied, `eligible_roles` entries are
-     * checked against `roles.role_options` at factory time so typos throw
-     * at startup instead of at first call.
+     * Optional role schema. Drives default eligibility derivation from
+     * `RoleSpec.grant_paths` and validates the `eligible_roles` override
+     * (when supplied) against the registered role set.
      */
     roles?: RoleSchemaResult;
 }
-/**
- * Dependencies for `create_self_service_role_actions`. Same shape as the
- * peer factories so consumers thread one deps object through all three.
- * `audit_log_config` flows from `AppDeps` and is consumed by
- * `audit_log_fire_and_forget`.
- */
-export type SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
 /**
  * Build the unified self-service role toggle RPC action.
  *
- * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
- * @param options - eligible-role allowlist plus optional role schema for typo-checking
+ * @param deps - `RouteFactoryDeps` (`log`, `audit`, …); `audit.emit` writes
+ *   audit rows via the captured pool. The bound emitter encapsulates
+ *   `on_audit_event` fan-out and the optional `AuditLogConfig`.
+ * @param options - optional eligible-role override plus optional role schema for default-eligibility derivation
  * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
- * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_options`
+ * @throws Error at factory time if any `eligible_roles` entry is missing from `options.roles.role_specs`
  */
-export declare const create_self_service_role_actions: (deps: SelfServiceRoleActionDeps, options: SelfServiceRoleActionsOptions) => Array<RpcAction>;
+export declare const create_self_service_role_actions: (deps: Pick<RouteFactoryDeps, "log" | "audit">, options?: SelfServiceRoleActionsOptions) => Array<RpcAction>;
 //# sourceMappingURL=self_service_role_actions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAYhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA+GjB,CAAC"}
+{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAsC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAE7F,OAAO,EAGN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAWhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,CAAC,EAC7C,UAAS,6BAAkC,KACzC,KAAK,CAAC,SAAS,CAyHjB,CAAC"}