@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/auth/grant_path_schema.js

@@ -0,0 +1,137 @@
+/**
+ * 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`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * 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.
+ */
+export const GRANT_PATH_NAME_REGEX = /^[a-z][a-z_]*[a-z]$|^[a-z]$/;
+/** Zod schema for valid grant-path name strings. */
+export const GrantPathName = z
+    .string()
+    .regex(GRANT_PATH_NAME_REGEX, 'Grant-path names must be lowercase letters and underscores (a-z_), no leading/trailing underscore');
+// Builtin grant paths — provided by fuz_app, always available.
+/** Admin-mediated grant — `role_grant_offer_create` plus admin-direct flows. */
+export const GRANT_PATH_ADMIN = 'admin';
+/** Self-service grant — caller toggles their own role_grant via `self_service_role_set`. */
+export const GRANT_PATH_SELF_SERVICE = 'self_service';
+/** System-mediated grant — signup hooks, automation, internal service flows. */
+export const GRANT_PATH_SYSTEM = 'system';
+/** Bootstrap grant — one-shot flow during the keep's first-run bootstrap. */
+export const GRANT_PATH_BOOTSTRAP = 'bootstrap';
+/** The builtin grant-path names as a const tuple. */
+export const BUILTIN_GRANT_PATHS = [
+    GRANT_PATH_ADMIN,
+    GRANT_PATH_SELF_SERVICE,
+    GRANT_PATH_SYSTEM,
+    GRANT_PATH_BOOTSTRAP,
+];
+/** Zod enum for builtin grant paths only. */
+export const BuiltinGrantPath = z.enum(BUILTIN_GRANT_PATHS);
+/**
+ * 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.
+ */
+export const BUILTIN_GRANT_PATH_META = new Map([
+    [
+        GRANT_PATH_ADMIN,
+        {
+            description: 'Admin-mediated grant — admin offers via `role_grant_offer_create` or direct grant.',
+        },
+    ],
+    [
+        GRANT_PATH_SELF_SERVICE,
+        {
+            description: 'Self-service grant — caller toggles their own role_grant via `self_service_role_set`.',
+        },
+    ],
+    [
+        GRANT_PATH_SYSTEM,
+        { description: 'System-mediated grant — signup, automation, or internal service flows.' },
+    ],
+    [
+        GRANT_PATH_BOOTSTRAP,
+        { description: 'Bootstrap grant — one-shot flow during the keep’s first-run bootstrap.' },
+    ],
+]);
+/**
+ * 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.
+ *
+ * @param consumer_paths - optional consumer-declared grant-path set with optional metadata
+ * @returns `{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
+ *
+ * @example
+ * ```ts
+ * // 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.'},
+ * });
+ * ```
+ */
+export const create_grant_path_schema = (consumer_paths = {}) => {
+    const consumer_names = Object.keys(consumer_paths);
+    const seen = new Set();
+    for (const name of consumer_names) {
+        const parsed = GrantPathName.safeParse(name);
+        if (!parsed.success) {
+            throw new Error(`Invalid grant-path name "${name}": ${parsed.error.issues[0].message}`);
+        }
+        if (BUILTIN_GRANT_PATH_META.has(name)) {
+            throw new Error(`Consumer grant-path "${name}" collides with builtin grant-path`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`Duplicate grant-path name "${name}"`);
+        }
+        seen.add(name);
+    }
+    const all_names = [...BUILTIN_GRANT_PATHS, ...consumer_names];
+    const GrantPath = z.enum(all_names);
+    const grant_paths = new Map(BUILTIN_GRANT_PATH_META);
+    for (const name of consumer_names) {
+        grant_paths.set(name, consumer_paths[name]);
+    }
+    return { GrantPath, grant_paths };
+};

package/dist/auth/invite_queries.d.ts

@@ -41,13 +41,24 @@ export declare const query_invite_find_unclaimed_match: (deps: QueryDeps, email:
 /**
  * Claim an invite by setting the claimed_by and claimed_at fields.
  *
+ * The `_unscoped` suffix is the safety signal — the SQL only checks the
+ * row state (`claimed_at IS NULL`), not whether the claiming account's
+ * email or username matches the invite. Callers must scope the lookup
+ * upstream via `query_invite_find_unclaimed_match`; the production caller
+ * (`auth/signup_routes.ts`) does this. Skipping the find step lets a
+ * caller claim any unclaimed invite by id.
+ *
+ * Mirrors the `query_session_revoke_by_hash_unscoped` precedent — there
+ * is no scoped sibling because the scoping is provided by a separate
+ * find query, not by an alternate variant of this query.
+ *
  * @param deps - query dependencies
  * @param invite_id - the invite to claim
  * @param account_id - the account claiming the invite
  * @returns true if the invite was claimed, false if already claimed or not found
  * @mutates `invite` row - sets `claimed_by` and `claimed_at` when still unclaimed
  */
-export declare const query_invite_claim: (deps: QueryDeps, invite_id: string, account_id: string) => Promise<boolean>;
+export declare const query_invite_claim_unscoped: (deps: QueryDeps, invite_id: string, account_id: string) => Promise<boolean>;
 /**
  * List all invites, newest first.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"invite_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAE3F;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,OAAO,MAAM,GAAG,IAAI,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAe5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAElF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAUxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,CAMjB,CAAC"}
+{"version":3,"file":"invite_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAE3F;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAK5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,OAAO,MAAM,GAAG,IAAI,EACpB,UAAU,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAe5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAElF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAUxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,CAMjB,CAAC"}

package/dist/auth/invite_queries.js

@@ -61,13 +61,24 @@ export const query_invite_find_unclaimed_match = async (deps, email, username) =
 /**
  * Claim an invite by setting the claimed_by and claimed_at fields.
  *
+ * The `_unscoped` suffix is the safety signal — the SQL only checks the
+ * row state (`claimed_at IS NULL`), not whether the claiming account's
+ * email or username matches the invite. Callers must scope the lookup
+ * upstream via `query_invite_find_unclaimed_match`; the production caller
+ * (`auth/signup_routes.ts`) does this. Skipping the find step lets a
+ * caller claim any unclaimed invite by id.
+ *
+ * Mirrors the `query_session_revoke_by_hash_unscoped` precedent — there
+ * is no scoped sibling because the scoping is provided by a separate
+ * find query, not by an alternate variant of this query.
+ *
  * @param deps - query dependencies
  * @param invite_id - the invite to claim
  * @param account_id - the account claiming the invite
  * @returns true if the invite was claimed, false if already claimed or not found
  * @mutates `invite` row - sets `claimed_by` and `claimed_at` when still unclaimed
  */
-export const query_invite_claim = async (deps, invite_id, account_id) => {
+export const query_invite_claim_unscoped = async (deps, invite_id, account_id) => {
     const rows = await deps.db.query(`UPDATE invite SET claimed_by = $1, claimed_at = NOW()
 		 WHERE id = $2 AND claimed_at IS NULL
 		 RETURNING id`, [account_id, invite_id]);

package/dist/auth/invite_schema.d.ts

@@ -8,7 +8,7 @@
  */
 import { z } from 'zod';
 import { Uuid } from '@fuzdev/fuz_util/id.js';
-import { Username, Email } from './account_schema.js';
+import { Username, Email } from '../primitive_schemas.js';
 /** Invite row from the database. */
 export interface Invite {
     id: Uuid;

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

@@ -1 +1 @@
-{"version":3,"file":"invite_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAE5C,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAC,MAAM,qBAAqB,CAAC;AAEpD,oCAAoC;AACpC,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;;kBAQrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB;;;;;;;;;;kBAGlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB"}
+{"version":3,"file":"invite_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/invite_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAE5C,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAC,MAAM,yBAAyB,CAAC;AAExD,oCAAoC;AACpC,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;;kBAQrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB;;;;;;;;;;kBAGlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IACjC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB"}

package/dist/auth/invite_schema.js

@@ -8,7 +8,7 @@
  */
 import { z } from 'zod';
 import { Uuid } from '@fuzdev/fuz_util/id.js';
-import { Username, Email } from './account_schema.js';
+import { Username, Email } from '../primitive_schemas.js';
 /** Zod schema for client-safe invite data. */
 export const InviteJson = z.strictObject({
     id: Uuid,

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

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IACtC,oFAAoF;IACpF,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,OAAO,EACb,SAAS,qBAAqB,KAC5B,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAqE/B,CAAC"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IACtC,oFAAoF;IACpF,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,OAAO,EACb,SAAS,qBAAqB,KAC5B,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAwE/B,CAAC"}

package/dist/auth/middleware.js

@@ -23,8 +23,11 @@ export const create_auth_middleware_specs = async (deps, options) => {
     const { keyring, db } = deps;
     const { allowed_origins, session_options, path = '/api/*', daemon_token_state, bearer_ip_rate_limiter, } = options;
     const query_deps = { db };
-    // Dynamic imports to avoid pulling heavy dependencies into this module
-    // when consumers only need types (MiddlewareSpec, RouteSpec, etc.)
+    // Dynamic imports preserve the bundle-split for type-only consumers of
+    // this module (`MiddlewareSpec`, `AuthMiddlewareOptions`, etc.). The
+    // runtime chain pulls session_queries + blake3 transitively via
+    // session_middleware.js, but type-only imports are erased at compile
+    // time and stay free.
     const [{ verify_request_source }, { create_session_middleware }, { create_request_context_middleware }, { create_bearer_auth_middleware },] = await Promise.all([
         import('../http/origin.js'),
         import('./session_middleware.js'),

package/dist/auth/migrations.d.ts

@@ -39,18 +39,33 @@
 import type { Migration, MigrationNamespace } from '../db/migrate.js';
 /** Namespace identifier for fuz_app auth migrations. */
 export declare const AUTH_MIGRATION_NAMESPACE = "fuz_auth";
+/**
+ * Migration namespaces reserved by fuz_app. Consumers passing
+ * `migration_namespaces` to `create_app_backend` must choose a name not in
+ * this list — the runtime check rejects matches with a thrown error. Typed
+ * as `ReadonlyArray<string>` (not a literal tuple) so `.includes()` accepts
+ * any consumer-supplied namespace string without a cast.
+ */
+export declare const RESERVED_MIGRATION_NAMESPACES: ReadonlyArray<string>;
 /**
  * Auth schema migrations in order.
  *
- * - v0: Full auth schema — account (with email_verified), actor, permit,
+ * - v0: Full auth schema — account (with email_verified), actor, role_grant,
  *   auth_session, api_token, audit_log (with seq), bootstrap_lock, invite,
  *   app_settings, plus all indexes and seeds.
- * - v1: `permit_offer` table for consentful grants; adds `scope_id` /
- *   `source_offer_id` / `revoked_reason` to `permit` and swaps the
- *   `(actor_id, role)` partial unique index for a scope-aware variant using
- *   the all-zeros sentinel UUID. The `permit_offer` table carries a
- *   `superseded_at` terminal state; its partial unique index is scoped by
- *   `(to_account, role, scope, from_actor)` so multiple grantors may coexist.
+ * - v1: `role_grant_offer` table for consentful grants; adds `scope_id` /
+ *   `scope_kind` / `source_offer_id` / `revoked_reason` to `role_grant` and
+ *   swaps the `(actor_id, role)` partial unique index for a scope-aware
+ *   variant using the index-side `'GLOBAL'` token + all-zeros sentinel
+ *   UUID. The `(scope_kind, scope_id)` pair is enforced paired-null by
+ *   `role_grant_scope_kind_paired` / `role_grant_offer_scope_kind_paired` CHECK
+ *   constraints — both null for global, both non-null for scoped. The
+ *   `role_grant_offer` table carries a `superseded_at` terminal state; its
+ *   partial unique index is scoped by
+ *   `(to_account, role, scope_kind, scope, from_actor)` so multiple
+ *   grantors may coexist. `scope_kind` is informative-only in v1
+ *   (registry-membership validation against `create_scope_kind_schema`);
+ *   v2 may add INSERT-time `(role, scope_kind)` enforcement.
  */
 export declare const AUTH_MIGRATIONS: Array<Migration>;
 /** Pre-composed migration namespace for auth tables. */

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

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA6BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA6D5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA8BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAqF5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -36,23 +36,38 @@
  *
  * @module
  */
-import { ACCOUNT_SCHEMA, ACCOUNT_EMAIL_INDEX, ACCOUNT_USERNAME_CI_INDEX, ACTOR_SCHEMA, ACTOR_INDEX, PERMIT_SCHEMA, PERMIT_INDEXES, AUTH_SESSION_SCHEMA, AUTH_SESSION_INDEXES, API_TOKEN_SCHEMA, API_TOKEN_INDEX, BOOTSTRAP_LOCK_SCHEMA, BOOTSTRAP_LOCK_SEED, INVITE_SCHEMA, INVITE_INDEXES, APP_SETTINGS_SCHEMA, APP_SETTINGS_SEED, } from './ddl.js';
+import { ACCOUNT_SCHEMA, ACCOUNT_EMAIL_INDEX, ACCOUNT_USERNAME_CI_INDEX, ACTOR_SCHEMA, ACTOR_INDEX, ROLE_GRANT_SCHEMA, ROLE_GRANT_INDEXES, AUTH_SESSION_SCHEMA, AUTH_SESSION_INDEXES, API_TOKEN_SCHEMA, API_TOKEN_INDEX, BOOTSTRAP_LOCK_SCHEMA, BOOTSTRAP_LOCK_SEED, INVITE_SCHEMA, INVITE_INDEXES, APP_SETTINGS_SCHEMA, APP_SETTINGS_SEED, } from './ddl.js';
 import { AUDIT_LOG_SCHEMA, AUDIT_LOG_INDEXES } from './audit_log_schema.js';
-import { PERMIT_OFFER_SCHEMA, PERMIT_OFFER_PENDING_UNIQUE_INDEX, PERMIT_OFFER_INBOX_INDEX, PERMIT_OFFER_SCOPE_SENTINEL_UUID, } from './permit_offer_schema.js';
+import { ROLE_GRANT_OFFER_SCHEMA, ROLE_GRANT_OFFER_PENDING_UNIQUE_INDEX, ROLE_GRANT_OFFER_INBOX_INDEX, ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID, ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN, } from './role_grant_offer_schema.js';
 /** Namespace identifier for fuz_app auth migrations. */
 export const AUTH_MIGRATION_NAMESPACE = 'fuz_auth';
+/**
+ * Migration namespaces reserved by fuz_app. Consumers passing
+ * `migration_namespaces` to `create_app_backend` must choose a name not in
+ * this list — the runtime check rejects matches with a thrown error. Typed
+ * as `ReadonlyArray<string>` (not a literal tuple) so `.includes()` accepts
+ * any consumer-supplied namespace string without a cast.
+ */
+export const RESERVED_MIGRATION_NAMESPACES = [AUTH_MIGRATION_NAMESPACE];
 /**
  * Auth schema migrations in order.
  *
- * - v0: Full auth schema — account (with email_verified), actor, permit,
+ * - v0: Full auth schema — account (with email_verified), actor, role_grant,
  *   auth_session, api_token, audit_log (with seq), bootstrap_lock, invite,
  *   app_settings, plus all indexes and seeds.
- * - v1: `permit_offer` table for consentful grants; adds `scope_id` /
- *   `source_offer_id` / `revoked_reason` to `permit` and swaps the
- *   `(actor_id, role)` partial unique index for a scope-aware variant using
- *   the all-zeros sentinel UUID. The `permit_offer` table carries a
- *   `superseded_at` terminal state; its partial unique index is scoped by
- *   `(to_account, role, scope, from_actor)` so multiple grantors may coexist.
+ * - v1: `role_grant_offer` table for consentful grants; adds `scope_id` /
+ *   `scope_kind` / `source_offer_id` / `revoked_reason` to `role_grant` and
+ *   swaps the `(actor_id, role)` partial unique index for a scope-aware
+ *   variant using the index-side `'GLOBAL'` token + all-zeros sentinel
+ *   UUID. The `(scope_kind, scope_id)` pair is enforced paired-null by
+ *   `role_grant_scope_kind_paired` / `role_grant_offer_scope_kind_paired` CHECK
+ *   constraints — both null for global, both non-null for scoped. The
+ *   `role_grant_offer` table carries a `superseded_at` terminal state; its
+ *   partial unique index is scoped by
+ *   `(to_account, role, scope_kind, scope, from_actor)` so multiple
+ *   grantors may coexist. `scope_kind` is informative-only in v1
+ *   (registry-membership validation against `create_scope_kind_schema`);
+ *   v2 may add INSERT-time `(role, scope_kind)` enforcement.
  */
 export const AUTH_MIGRATIONS = [
     // v0: full auth schema — all IF NOT EXISTS, safe for existing databases
@@ -64,8 +79,8 @@ export const AUTH_MIGRATIONS = [
             await db.query(ACCOUNT_USERNAME_CI_INDEX);
             await db.query(ACTOR_SCHEMA);
             await db.query(ACTOR_INDEX);
-            await db.query(PERMIT_SCHEMA);
-            for (const sql of PERMIT_INDEXES) {
+            await db.query(ROLE_GRANT_SCHEMA);
+            for (const sql of ROLE_GRANT_INDEXES) {
                 await db.query(sql);
             }
             await db.query(AUTH_SESSION_SCHEMA);
@@ -88,24 +103,48 @@ export const AUTH_MIGRATIONS = [
             await db.query(APP_SETTINGS_SEED);
         },
     },
-    // v1: consentful permits — permit_offer table + scoped permits
+    // v1: consentful role_grants — role_grant_offer table + scoped role_grants
     {
         name: 'permit_offer_and_scoped_permits',
         up: async (db) => {
-            await db.query(PERMIT_OFFER_SCHEMA);
-            await db.query(PERMIT_OFFER_PENDING_UNIQUE_INDEX);
-            await db.query(PERMIT_OFFER_INBOX_INDEX);
-            await db.query('ALTER TABLE permit ADD COLUMN IF NOT EXISTS scope_id UUID NULL');
-            await db.query('ALTER TABLE permit ADD COLUMN IF NOT EXISTS source_offer_id UUID NULL REFERENCES permit_offer(id) ON DELETE SET NULL');
-            await db.query('ALTER TABLE permit ADD COLUMN IF NOT EXISTS revoked_reason TEXT NULL');
-            // swap the (actor_id, role) partial unique for a scope-aware variant.
-            // Existing rows have `scope_id = NULL` and collapse to the sentinel.
-            await db.query('DROP INDEX IF EXISTS permit_actor_role_active_unique');
-            await db.query(`CREATE UNIQUE INDEX IF NOT EXISTS permit_actor_role_scope_active_unique
-				   ON permit (actor_id, role, COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid))
+            await db.query(ROLE_GRANT_OFFER_SCHEMA);
+            await db.query(ROLE_GRANT_OFFER_PENDING_UNIQUE_INDEX);
+            await db.query(ROLE_GRANT_OFFER_INBOX_INDEX);
+            await db.query('ALTER TABLE role_grant ADD COLUMN IF NOT EXISTS scope_id UUID NULL');
+            await db.query('ALTER TABLE role_grant ADD COLUMN IF NOT EXISTS scope_kind TEXT NULL');
+            await db.query('ALTER TABLE role_grant ADD COLUMN IF NOT EXISTS source_offer_id UUID NULL REFERENCES role_grant_offer(id) ON DELETE SET NULL');
+            await db.query('ALTER TABLE role_grant ADD COLUMN IF NOT EXISTS revoked_reason TEXT NULL');
+            // Paired-null CHECK on `(scope_kind, scope_id)` — both null encodes
+            // the global case; both non-null encodes a scoped grant. The DO
+            // block makes constraint addition idempotent across migration
+            // re-runs (Postgres has no `ADD CONSTRAINT IF NOT EXISTS` for
+            // CHECK constraints — `pg_constraint` lookup is the established
+            // shape).
+            await db.query(`DO $$ BEGIN
+				IF NOT EXISTS (
+					SELECT 1 FROM pg_constraint WHERE conname = 'role_grant_scope_kind_paired'
+				) THEN
+					ALTER TABLE role_grant
+						ADD CONSTRAINT role_grant_scope_kind_paired
+						CHECK ((scope_kind IS NULL) = (scope_id IS NULL));
+				END IF;
+			END $$`);
+            // Swap the (actor_id, role) partial unique for a scope-aware variant.
+            // Existing rows have `scope_id = NULL` (and `scope_kind = NULL` per
+            // the pair invariant) and collapse to the index-side `'GLOBAL'`
+            // token + all-zeros sentinel UUID.
+            await db.query('DROP INDEX IF EXISTS role_grant_actor_role_active_unique');
+            await db.query('DROP INDEX IF EXISTS role_grant_actor_role_scope_active_unique');
+            await db.query(`CREATE UNIQUE INDEX IF NOT EXISTS role_grant_actor_role_scope_active_unique
+				   ON role_grant (
+				     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`);
-            await db.query(`CREATE INDEX IF NOT EXISTS permit_scope_active
-				   ON permit (actor_id, role, scope_id)
+            await db.query(`CREATE INDEX IF NOT EXISTS role_grant_scope_active
+				   ON role_grant (actor_id, role, scope_id)
 				   WHERE revoked_at IS NULL`);
         },
     },