@fuzdev/fuz_app 0.59.0 → 0.60.0

package/dist/auth/actor_search_queries.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Prefix-based actor search.
+ *
+ * Sibling to `actor_lookup_queries.ts` — that resolves a batch of ids to
+ * labels; this resolves a partial name to candidate actors. Same row
+ * shape (`ActorLookupRow`) so the labels arc on the consumer side stays
+ * uniform.
+ *
+ * Case-insensitive LIKE-prefix on `actor.name` backed by the
+ * `idx_actor_name_lower` functional index. LIKE wildcards (`%`, `_`,
+ * `\`) in the query string are escaped at the JS layer so the
+ * prefix-only contract is enforceable — an unescaped `%xyz` would
+ * widen the surface to full-LIKE and defeat the per-call cap as a
+ * binding bound.
+ *
+ * ## Auth filtering — `scope_ids`
+ *
+ * When `scope_ids` is non-empty, the result is filtered to actors
+ * holding an **active** role_grant on one of the supplied scopes. Active
+ * means `revoked_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())`.
+ * Stale (revoked / expired) role_grants do **not** confer membership for
+ * search-visibility purposes — otherwise a removed student would
+ * remain visible to teachers indefinitely.
+ *
+ * The `DISTINCT` on `actor.id` collapses the case where an actor holds
+ * multiple matching role_grants in the supplied scope set into one row.
+ *
+ * When `scope_ids` is omitted (admin-only global path; the handler
+ * gates), no role_grant join — every actor with a matching prefix is
+ * returned.
+ *
+ * ## Info-leak posture (see `actor_search_action_specs.ts` § audit)
+ *
+ * - Row shape **omits** `account_id` — the join is control-plane, not
+ *   wire-visible. Identical to `actor_lookup_queries.ts`.
+ * - Hard-deleted actors (cascade-orphaned via `actor.account_id` FK)
+ *   drop out silently.
+ * - No `created_at` / `updated_at` projected (timing-oracle avoidance).
+ * - Scope-membership uses ANY on the supplied `scope_ids` array but
+ *   never surfaces "which scope matched" — the result row carries only
+ *   the actor's wire shape. An attacker passing a random scope_id
+ *   learns at most "this scope has at least one member matching X"
+ *   if a match exists, indistinguishable from a no-match search; the
+ *   caller-passes-scope_ids design (handler trusts the array as a
+ *   filter, not as authority) means the attacker had to obtain the
+ *   scope_id from somewhere else first.
+ *
+ * Caller bounds `limit` (the action-spec layer enforces
+ * `ACTOR_SEARCH_LIMIT_MAX`); SQL clamps to that cap on the call site
+ * before reaching this query.
+ *
+ * @module
+ */
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import type { ActorLookupRow } from './actor_lookup_queries.js';
+/** Inputs for `query_actor_search`. */
+export interface ActorSearchQueryInput {
+    /** Case-insensitive prefix string. Must be non-empty (action layer enforces `min(1)`). */
+    query: string;
+    /**
+     * When non-empty, restrict to actors holding an active role_grant on one
+     * of these scope ids. When empty / omitted, no scope filter is applied —
+     * the handler is responsible for the admin gate.
+     */
+    scope_ids?: ReadonlyArray<Uuid>;
+    /** Maximum rows to return. The handler clamps to `ACTOR_SEARCH_LIMIT_MAX`. */
+    limit: number;
+}
+/**
+ * Search actors by case-insensitive prefix on `actor.name`, optionally
+ * filtered to those holding an active role_grant on one of `scope_ids`.
+ */
+export declare const query_actor_search: (deps: QueryDeps, input: ActorSearchQueryInput) => Promise<Array<ActorLookupRow>>;
+//# sourceMappingURL=actor_search_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_search_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_search_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE9D,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IACrC,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;CACd;AASD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,qBAAqB,KAC1B,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAmC/B,CAAC"}

package/dist/auth/actor_search_queries.js

@@ -0,0 +1,91 @@
+/**
+ * Prefix-based actor search.
+ *
+ * Sibling to `actor_lookup_queries.ts` — that resolves a batch of ids to
+ * labels; this resolves a partial name to candidate actors. Same row
+ * shape (`ActorLookupRow`) so the labels arc on the consumer side stays
+ * uniform.
+ *
+ * Case-insensitive LIKE-prefix on `actor.name` backed by the
+ * `idx_actor_name_lower` functional index. LIKE wildcards (`%`, `_`,
+ * `\`) in the query string are escaped at the JS layer so the
+ * prefix-only contract is enforceable — an unescaped `%xyz` would
+ * widen the surface to full-LIKE and defeat the per-call cap as a
+ * binding bound.
+ *
+ * ## Auth filtering — `scope_ids`
+ *
+ * When `scope_ids` is non-empty, the result is filtered to actors
+ * holding an **active** role_grant on one of the supplied scopes. Active
+ * means `revoked_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())`.
+ * Stale (revoked / expired) role_grants do **not** confer membership for
+ * search-visibility purposes — otherwise a removed student would
+ * remain visible to teachers indefinitely.
+ *
+ * The `DISTINCT` on `actor.id` collapses the case where an actor holds
+ * multiple matching role_grants in the supplied scope set into one row.
+ *
+ * When `scope_ids` is omitted (admin-only global path; the handler
+ * gates), no role_grant join — every actor with a matching prefix is
+ * returned.
+ *
+ * ## Info-leak posture (see `actor_search_action_specs.ts` § audit)
+ *
+ * - Row shape **omits** `account_id` — the join is control-plane, not
+ *   wire-visible. Identical to `actor_lookup_queries.ts`.
+ * - Hard-deleted actors (cascade-orphaned via `actor.account_id` FK)
+ *   drop out silently.
+ * - No `created_at` / `updated_at` projected (timing-oracle avoidance).
+ * - Scope-membership uses ANY on the supplied `scope_ids` array but
+ *   never surfaces "which scope matched" — the result row carries only
+ *   the actor's wire shape. An attacker passing a random scope_id
+ *   learns at most "this scope has at least one member matching X"
+ *   if a match exists, indistinguishable from a no-match search; the
+ *   caller-passes-scope_ids design (handler trusts the array as a
+ *   filter, not as authority) means the attacker had to obtain the
+ *   scope_id from somewhere else first.
+ *
+ * Caller bounds `limit` (the action-spec layer enforces
+ * `ACTOR_SEARCH_LIMIT_MAX`); SQL clamps to that cap on the call site
+ * before reaching this query.
+ *
+ * @module
+ */
+/**
+ * Escape LIKE wildcards in a user-supplied query string so the SQL
+ * prefix-match cannot be widened by user input. The `\` escape char is
+ * declared on the LIKE expression via `ESCAPE '\'`.
+ */
+const escape_like_pattern = (s) => s.replace(/[\\%_]/g, '\\$&');
+/**
+ * Search actors by case-insensitive prefix on `actor.name`, optionally
+ * filtered to those holding an active role_grant on one of `scope_ids`.
+ */
+export const query_actor_search = async (deps, input) => {
+    const escaped_prefix = escape_like_pattern(input.query.toLowerCase());
+    const scope_ids = input.scope_ids ?? [];
+    if (scope_ids.length === 0) {
+        // Admin-global path — no role_grant join. Handler enforces admin.
+        return deps.db.query(`SELECT act.id, a.username, act.name AS display_name
+			 FROM actor act
+			 JOIN account a ON a.id = act.account_id
+			 WHERE LOWER(act.name) LIKE $1 || '%' ESCAPE '\\'
+			 ORDER BY display_name, id
+			 LIMIT $2`, [escaped_prefix, input.limit]);
+    }
+    // Scoped path — filter to actors with an active role_grant on any of
+    // `scope_ids`. DISTINCT collapses actors holding multiple matching
+    // role_grants in the supplied scope set into one row. ORDER BY must
+    // reference SELECT-listed columns under DISTINCT, so we sort by the
+    // `display_name` alias rather than `LOWER(act.name)`.
+    return deps.db.query(`SELECT DISTINCT act.id, a.username, act.name AS display_name
+		 FROM actor act
+		 JOIN account a ON a.id = act.account_id
+		 JOIN role_grant rg ON rg.actor_id = act.id
+		   AND rg.scope_id = ANY($2)
+		   AND rg.revoked_at IS NULL
+		   AND (rg.expires_at IS NULL OR rg.expires_at > NOW())
+		 WHERE LOWER(act.name) LIKE $1 || '%' ESCAPE '\\'
+		 ORDER BY display_name, id
+		 LIMIT $3`, [escaped_prefix, scope_ids, input.limit]);
+};

package/dist/auth/admin_actions.js

@@ -29,7 +29,7 @@
  */
 import { rpc_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { BUILTIN_ROLE_SPECS_BY_NAME, list_roles_with_grant_path, } from './role_schema.js';
+import { builtin_role_specs_by_name, list_roles_with_grant_path, } from './role_schema.js';
 import { GRANT_PATH_ADMIN } from './grant_path_schema.js';
 import { query_account_by_email, query_account_by_id, query_account_by_username, query_admin_account_list, } from './account_queries.js';
 import { query_session_list_all_active, query_session_revoke_all_for_account, } from './session_queries.js';
@@ -54,7 +54,7 @@ import { admin_account_list_action_spec, admin_session_list_action_spec, admin_s
  * @mutates `options.app_settings` ref - `app_settings_update` writes `open_signup`, `updated_at`, and `updated_by` so signup middleware reads without a DB round trip
  */
 export const create_admin_actions = (deps, options = {}) => {
-    const role_specs = options.roles?.role_specs ?? BUILTIN_ROLE_SPECS_BY_NAME;
+    const role_specs = options.roles?.role_specs ?? builtin_role_specs_by_name;
     const grantable_roles = list_roles_with_grant_path(role_specs, GRANT_PATH_ADMIN);
     const account_list_handler = async (input, ctx) => {
         const accounts = await query_admin_account_list(ctx, {

package/dist/auth/all_action_spec_registries.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Canonical list of every fuz_auth action-spec registry — **for cross-cutting
+ * walkers and codegen only**. Not a mounting surface; consumers continue to
+ * import individual `all_*_action_specs` bundles (and `create_*_actions`
+ * factories) per registration site.
+ *
+ * The "one main bundle" alternative is an antipattern for mounting:
+ * `create_standard_rpc_actions` (admin + role_grant_offer + account) is the
+ * canonical surface, and opt-in registries (`self_service_role`,
+ * `actor_lookup`) are deliberately opt-in because their eligibility
+ * (`eligible_roles`) or coverage (byline labels) is app-specific. Spreading
+ * everything into a single mount would silently widen the dispatch surface
+ * the moment a new opt-in landed — the exact failure mode this module is
+ * built to detect, not propagate. See `./CLAUDE.md` §RPC actions
+ * (`standard_rpc_actions.ts`).
+ *
+ * Use cases for this registry:
+ *
+ * - Cross-registry walker tests (input-invariants, auth-shape
+ *   biconditional) — iterate the spec arrays once, fail when a new
+ *   registry slips by without an entry here.
+ * - Codegen that needs to see every fuz_auth surface at once
+ *   (typed-client filters, attack-surface reports). For typed-client
+ *   wiring of the standard surface, prefer `all_standard_action_specs`
+ *   in `./standard_action_specs.ts` — it mirrors the
+ *   `create_standard_rpc_actions` mount and stays narrower than this
+ *   registry-of-registries (no opt-in bundles).
+ *
+ * `protocol_action_specs` (heartbeat / cancel) is **not** included —
+ * those are transport-level wire-protocol concerns shipped by fuz_app
+ * and spread by every consumer at registration via `protocol_actions`
+ * from `../actions/protocol.ts`. Walker tests that need protocol
+ * coverage spread `protocol_action_specs` separately.
+ *
+ * @module
+ */
+import type { RequestResponseActionSpec } from '../actions/action_spec.js';
+/** One named entry in the registry-of-registries. */
+export interface FuzAuthActionSpecRegistry {
+    /** Stable identifier matching the source bundle name (`'admin'`, `'role_grant_offer'`, etc.). */
+    name: string;
+    /** The bundle's spec array — kept readonly here even when the source declares it mutable. */
+    specs: ReadonlyArray<RequestResponseActionSpec>;
+}
+/**
+ * Every fuz_auth action-spec registry, in dependency-stable order.
+ *
+ * Update this list when a new fuz_auth registry lands. The walker tests
+ * (`action_spec_input_invariants.test.ts`,
+ * `all_action_spec_registries.acting_biconditional.test.ts`) iterate
+ * over it — a missing entry silently skips coverage, which is the
+ * failure mode the registry-of-registries shape exists to prevent.
+ */
+export declare const all_fuz_auth_action_spec_registries: ReadonlyArray<FuzAuthActionSpecRegistry>;
+//# sourceMappingURL=all_action_spec_registries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"all_action_spec_registries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/all_action_spec_registries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAQzE,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACzC,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,KAAK,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,EAAE,aAAa,CAAC,yBAAyB,CAOxF,CAAC"}

package/dist/auth/all_action_spec_registries.js

@@ -0,0 +1,59 @@
+/**
+ * Canonical list of every fuz_auth action-spec registry — **for cross-cutting
+ * walkers and codegen only**. Not a mounting surface; consumers continue to
+ * import individual `all_*_action_specs` bundles (and `create_*_actions`
+ * factories) per registration site.
+ *
+ * The "one main bundle" alternative is an antipattern for mounting:
+ * `create_standard_rpc_actions` (admin + role_grant_offer + account) is the
+ * canonical surface, and opt-in registries (`self_service_role`,
+ * `actor_lookup`) are deliberately opt-in because their eligibility
+ * (`eligible_roles`) or coverage (byline labels) is app-specific. Spreading
+ * everything into a single mount would silently widen the dispatch surface
+ * the moment a new opt-in landed — the exact failure mode this module is
+ * built to detect, not propagate. See `./CLAUDE.md` §RPC actions
+ * (`standard_rpc_actions.ts`).
+ *
+ * Use cases for this registry:
+ *
+ * - Cross-registry walker tests (input-invariants, auth-shape
+ *   biconditional) — iterate the spec arrays once, fail when a new
+ *   registry slips by without an entry here.
+ * - Codegen that needs to see every fuz_auth surface at once
+ *   (typed-client filters, attack-surface reports). For typed-client
+ *   wiring of the standard surface, prefer `all_standard_action_specs`
+ *   in `./standard_action_specs.ts` — it mirrors the
+ *   `create_standard_rpc_actions` mount and stays narrower than this
+ *   registry-of-registries (no opt-in bundles).
+ *
+ * `protocol_action_specs` (heartbeat / cancel) is **not** included —
+ * those are transport-level wire-protocol concerns shipped by fuz_app
+ * and spread by every consumer at registration via `protocol_actions`
+ * from `../actions/protocol.ts`. Walker tests that need protocol
+ * coverage spread `protocol_action_specs` separately.
+ *
+ * @module
+ */
+import { all_admin_action_specs } from './admin_action_specs.js';
+import { all_role_grant_offer_action_specs } from './role_grant_offer_action_specs.js';
+import { all_account_action_specs } from './account_action_specs.js';
+import { all_self_service_role_action_specs } from './self_service_role_action_specs.js';
+import { all_actor_lookup_action_specs } from './actor_lookup_action_specs.js';
+import { all_actor_search_action_specs } from './actor_search_action_specs.js';
+/**
+ * Every fuz_auth action-spec registry, in dependency-stable order.
+ *
+ * Update this list when a new fuz_auth registry lands. The walker tests
+ * (`action_spec_input_invariants.test.ts`,
+ * `all_action_spec_registries.acting_biconditional.test.ts`) iterate
+ * over it — a missing entry silently skips coverage, which is the
+ * failure mode the registry-of-registries shape exists to prevent.
+ */
+export const all_fuz_auth_action_spec_registries = [
+    { name: 'admin', specs: all_admin_action_specs },
+    { name: 'role_grant_offer', specs: all_role_grant_offer_action_specs },
+    { name: 'account', specs: all_account_action_specs },
+    { name: 'self_service_role', specs: all_self_service_role_action_specs },
+    { name: 'actor_lookup', specs: all_actor_lookup_action_specs },
+    { name: 'actor_search', specs: all_actor_search_action_specs },
+];

package/dist/auth/audit_emitter.d.ts

@@ -144,7 +144,7 @@ export interface CreateAuditEmitterOptions {
      */
     on_audit_event?: ((event: AuditLogEvent) => void) | null;
     /**
-     * Audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`. Consumer-
+     * Audit-log config. Defaults to `builtin_audit_log_config`. Consumer-
      * extended configs from `create_audit_log_config({extra_events})` get
      * registered here once at backend assembly.
      */

package/dist/auth/audit_emitter.js

@@ -33,7 +33,7 @@
  * @module
  */
 import { query_audit_log } from './audit_log_queries.js';
-import { BUILTIN_AUDIT_LOG_CONFIG, } from './audit_log_schema.js';
+import { builtin_audit_log_config, } from './audit_log_schema.js';
 /**
  * Build a bound `AuditEmitter`. Called once at `create_app_backend` time.
  *
@@ -41,7 +41,7 @@ import { BUILTIN_AUDIT_LOG_CONFIG, } from './audit_log_schema.js';
  * @returns the bound emitter; closes over the pool + config + listener chain
  */
 export const create_audit_emitter = (options) => {
-    const { db, log, audit_log_config = BUILTIN_AUDIT_LOG_CONFIG } = options;
+    const { db, log, audit_log_config = builtin_audit_log_config } = options;
     const on_event_chain = [];
     if (options.on_audit_event)
         on_event_chain.push(options.on_audit_event);

package/dist/auth/audit_log_queries.d.ts

@@ -38,7 +38,7 @@ export declare const reset_audit_unknown_event_type_failures: () => void;
  *
  * @param deps - query dependencies
  * @param input - the audit event to record
- * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * @param config - audit-log config. Defaults to `builtin_audit_log_config`.
  * @returns the inserted audit log row
  * @mutates `audit_log` table - inserts the new row
  * @mutates drift counters - bumps `audit_unknown_event_type_failures` and/or `audit_metadata_validation_failures` on mismatch

package/dist/auth/audit_log_queries.js

@@ -12,7 +12,7 @@
  * @module
  */
 import { assert_row } from '../db/assert_row.js';
-import { AUDIT_LOG_DEFAULT_LIMIT, BUILTIN_AUDIT_LOG_CONFIG, } from './audit_log_schema.js';
+import { AUDIT_LOG_DEFAULT_LIMIT, builtin_audit_log_config, } from './audit_log_schema.js';
 /**
  * Process-wide counter for audit metadata validation failures. `query_audit_log`
  * increments on `safeParse` mismatch and writes the row anyway (fail-open —
@@ -61,12 +61,12 @@ export const reset_audit_unknown_event_type_failures = () => {
  *
  * @param deps - query dependencies
  * @param input - the audit event to record
- * @param config - audit-log config. Defaults to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * @param config - audit-log config. Defaults to `builtin_audit_log_config`.
  * @returns the inserted audit log row
  * @mutates `audit_log` table - inserts the new row
  * @mutates drift counters - bumps `audit_unknown_event_type_failures` and/or `audit_metadata_validation_failures` on mismatch
  */
-export const query_audit_log = async (deps, input, config = BUILTIN_AUDIT_LOG_CONFIG) => {
+export const query_audit_log = async (deps, input, config = builtin_audit_log_config) => {
     if (!config.event_types.includes(input.event_type)) {
         audit_unknown_event_type_failures++;
         console.error(`[audit_log] unknown event_type '${input.event_type}' — register via create_audit_log_config({extra_events})`);

package/dist/auth/audit_log_routes.d.ts

@@ -6,7 +6,7 @@
  * `admin_session_list` on the same file. What remains here is the optional
  * `GET /audit/stream` SSE route — streams aren't an action-kind, so they
  * stay on REST. The event payload broadcast on the stream surfaces via
- * `AUDIT_LOG_EVENT_SPECS` (one `EventSpec` per audit event type) declared
+ * `audit_log_event_specs` (one `EventSpec` per audit event type) declared
  * alongside the broadcaster in `../realtime/sse_auth_guard.ts`.
  *
  * @module

package/dist/auth/audit_log_routes.js

@@ -6,7 +6,7 @@
  * `admin_session_list` on the same file. What remains here is the optional
  * `GET /audit/stream` SSE route — streams aren't an action-kind, so they
  * stay on REST. The event payload broadcast on the stream surfaces via
- * `AUDIT_LOG_EVENT_SPECS` (one `EventSpec` per audit event type) declared
+ * `audit_log_event_specs` (one `EventSpec` per audit event type) declared
  * alongside the broadcaster in `../realtime/sse_auth_guard.ts`.
  *
  * @module

package/dist/auth/audit_log_schema.d.ts

@@ -64,7 +64,7 @@ export type AuditOutcome = z.infer<typeof AuditOutcome>;
  * stub schema); the Zod schemas themselves are reachable and mutable —
  * freeze isn't a security boundary.
  */
-export declare const AUDIT_METADATA_SCHEMAS: Readonly<{
+export declare const audit_metadata_schemas: Readonly<{
     login: z.ZodNullable<z.ZodObject<{
         username: z.ZodString;
     }, z.core.$loose>>;
@@ -175,7 +175,7 @@ export declare const AUDIT_METADATA_SCHEMAS: Readonly<{
 }>;
 /** Mapped type of metadata shapes per event type, derived from Zod schemas. */
 export type AuditMetadataMap = {
-    [K in AuditEventType]: z.infer<(typeof AUDIT_METADATA_SCHEMAS)[K]>;
+    [K in AuditEventType]: z.infer<(typeof audit_metadata_schemas)[K]>;
 };
 /** Audit log row from the database. See `AuditLogEventJson` for `event_type` widening rationale. */
 export interface AuditLogEvent {
@@ -270,7 +270,7 @@ export interface AuditLogInput<T extends string = AuditEventType> {
  * Lets consumers extend the closed `AUDIT_EVENT_TYPES` enum with their own
  * event strings (and metadata Zod schemas) without forking. Pass to
  * `create_audit_emitter` (or `query_audit_log` for in-tx call sites) as the
- * optional `config` argument; both default to `BUILTIN_AUDIT_LOG_CONFIG`.
+ * optional `config` argument; both default to `builtin_audit_log_config`.
  *
  * The DB column is `TEXT NOT NULL` and never enforced an enum, so consumer
  * event types round-trip through `query_audit_log_list` and SSE identically
@@ -291,7 +291,7 @@ export interface AuditLogConfig {
     readonly metadata_schemas: Readonly<Record<string, z.ZodType>>;
 }
 /** Builtin fuz_app audit-log config — every existing event type and its metadata schema. */
-export declare const BUILTIN_AUDIT_LOG_CONFIG: AuditLogConfig;
+export declare const builtin_audit_log_config: AuditLogConfig;
 /** Options for `create_audit_log_config`. */
 export interface CreateAuditLogConfigOptions {
     /**
@@ -313,7 +313,7 @@ export interface CreateAuditLogConfigOptions {
  *
  * Call once at startup; pass the result to `create_app_backend` (which
  * threads it into `AppDeps.audit`). Builtin handlers omit the
- * `audit_log_config` slot and pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ * `audit_log_config` slot and pick up `builtin_audit_log_config`.
  *
  * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */

package/dist/auth/audit_log_schema.js

@@ -64,7 +64,7 @@ export const AuditOutcome = z.enum(['success', 'failure']);
  * stub schema); the Zod schemas themselves are reachable and mutable —
  * freeze isn't a security boundary.
  */
-export const AUDIT_METADATA_SCHEMAS = Object.freeze({
+export const audit_metadata_schemas = Object.freeze({
     login: z
         .looseObject({
         username: z.string().meta({ description: 'Username submitted with the login attempt.' }),
@@ -265,9 +265,9 @@ export const get_audit_metadata = (event) => {
     return event.metadata;
 };
 /** Builtin fuz_app audit-log config — every existing event type and its metadata schema. */
-export const BUILTIN_AUDIT_LOG_CONFIG = Object.freeze({
+export const builtin_audit_log_config = Object.freeze({
     event_types: AUDIT_EVENT_TYPES,
-    metadata_schemas: AUDIT_METADATA_SCHEMAS,
+    metadata_schemas: audit_metadata_schemas,
 });
 /**
  * Build an `AuditLogConfig` by merging fuz_app builtins with consumer extras.
@@ -277,20 +277,20 @@ export const BUILTIN_AUDIT_LOG_CONFIG = Object.freeze({
  *
  * Call once at startup; pass the result to `create_app_backend` (which
  * threads it into `AppDeps.audit`). Builtin handlers omit the
- * `audit_log_config` slot and pick up `BUILTIN_AUDIT_LOG_CONFIG`.
+ * `audit_log_config` slot and pick up `builtin_audit_log_config`.
  *
  * @throws Error when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation
  */
 export const create_audit_log_config = (options) => {
     const extras = options?.extra_events;
     if (!extras)
-        return BUILTIN_AUDIT_LOG_CONFIG;
+        return builtin_audit_log_config;
     const extra_entries = Object.entries(extras);
     if (extra_entries.length === 0)
-        return BUILTIN_AUDIT_LOG_CONFIG;
+        return builtin_audit_log_config;
     const builtin_set = new Set(AUDIT_EVENT_TYPES);
     const extra_keys = [];
-    const metadata_schemas = { ...AUDIT_METADATA_SCHEMAS };
+    const metadata_schemas = { ...audit_metadata_schemas };
     for (const [t, schema] of extra_entries) {
         if (builtin_set.has(t)) {
             throw new Error(`extra_events key "${t}" collides with a builtin event type — pick a distinct string (e.g. "app_${t}")`);

package/dist/auth/auth_ddl.d.ts

@@ -12,6 +12,13 @@
 export declare const ACCOUNT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS account (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  username TEXT UNIQUE NOT NULL,\n  email TEXT,\n  email_verified BOOLEAN NOT NULL DEFAULT false,\n  password_hash TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  created_by UUID,\n  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_by UUID\n)";
 export declare const ACTOR_SCHEMA = "\nCREATE TABLE IF NOT EXISTS actor (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  name TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at TIMESTAMPTZ,\n  updated_by UUID REFERENCES actor(id) ON DELETE SET NULL\n)";
 export declare const ACTOR_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_actor_account ON actor(account_id)";
+/**
+ * Functional index on `LOWER(actor.name)` supporting case-insensitive
+ * prefix search by `actor_search` (`LOWER(name) LIKE LOWER(query) || '%'`).
+ * `text_pattern_ops` keeps the LIKE-prefix pattern index-eligible — without
+ * it the planner falls back to a sequential scan once the table grows.
+ */
+export declare const ACTOR_NAME_LOWER_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_actor_name_lower ON actor (LOWER(name) text_pattern_ops)";
 export declare const ROLE_GRANT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS role_grant (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,\n  role TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ,\n  revoked_at TIMESTAMPTZ,\n  revoked_by UUID REFERENCES actor(id) ON DELETE SET NULL,\n  granted_by UUID REFERENCES actor(id) ON DELETE SET NULL\n)";
 export declare const ROLE_GRANT_INDEXES: string[];
 export declare const AUTH_SESSION_SCHEMA = "\nCREATE TABLE IF NOT EXISTS auth_session (\n  id TEXT PRIMARY KEY,\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ NOT NULL,\n  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)";

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

@@ -1 +1 @@
-{"version":3,"file":"auth_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/auth_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc,8WAWzB,CAAC;AAEH,eAAO,MAAM,YAAY,mUAQvB,CAAC;AAEH,eAAO,MAAM,WAAW,wEAC0C,CAAC;AAEnE,eAAO,MAAM,iBAAiB,2ZAU5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,UAI9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,0RAO9B,CAAC;AAEH,eAAO,MAAM,oBAAoB,UAGhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,iUAU3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,4GACsE,CAAC;AAEvG,eAAO,MAAM,yBAAyB,6FACiD,CAAC;AAExF,eAAO,MAAM,eAAe,gFAC8C,CAAC;AAE3E,eAAO,MAAM,qBAAqB,wJAIhC,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,yHAGP,CAAC;AAE1B,eAAO,MAAM,aAAa,6ZAUxB,CAAC;AAEH,eAAO,MAAM,cAAc,UAI1B,CAAC;AAEF,eAAO,MAAM,mBAAmB,oMAM9B,CAAC;AAEH,eAAO,MAAM,iBAAiB,sEACkC,CAAC"}
+{"version":3,"file":"auth_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/auth_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc,8WAWzB,CAAC;AAEH,eAAO,MAAM,YAAY,mUAQvB,CAAC;AAEH,eAAO,MAAM,WAAW,wEAC0C,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,8FACqD,CAAC;AAEzF,eAAO,MAAM,iBAAiB,2ZAU5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,UAI9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,0RAO9B,CAAC;AAEH,eAAO,MAAM,oBAAoB,UAGhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,iUAU3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,4GACsE,CAAC;AAEvG,eAAO,MAAM,yBAAyB,6FACiD,CAAC;AAExF,eAAO,MAAM,eAAe,gFAC8C,CAAC;AAE3E,eAAO,MAAM,qBAAqB,wJAIhC,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,yHAGP,CAAC;AAE1B,eAAO,MAAM,aAAa,6ZAUxB,CAAC;AAEH,eAAO,MAAM,cAAc,UAI1B,CAAC;AAEF,eAAO,MAAM,mBAAmB,oMAM9B,CAAC;AAEH,eAAO,MAAM,iBAAiB,sEACkC,CAAC"}

package/dist/auth/auth_ddl.js

@@ -32,6 +32,14 @@ CREATE TABLE IF NOT EXISTS actor (
 )`;
 export const ACTOR_INDEX = `
 CREATE INDEX IF NOT EXISTS idx_actor_account ON actor(account_id)`;
+/**
+ * Functional index on `LOWER(actor.name)` supporting case-insensitive
+ * prefix search by `actor_search` (`LOWER(name) LIKE LOWER(query) || '%'`).
+ * `text_pattern_ops` keeps the LIKE-prefix pattern index-eligible — without
+ * it the planner falls back to a sequential scan once the table grows.
+ */
+export const ACTOR_NAME_LOWER_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_actor_name_lower ON actor (LOWER(name) text_pattern_ops)`;
 export const ROLE_GRANT_SCHEMA = `
 CREATE TABLE IF NOT EXISTS role_grant (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

package/dist/auth/credential_type_schema.d.ts

@@ -67,7 +67,7 @@ export interface CredentialTypeMeta {
  * here. Read once at startup by `create_credential_type_schema`;
  * runtime mutation has no effect on already-built schemas.
  */
-export declare const BUILTIN_CREDENTIAL_TYPE_META: ReadonlyMap<string, CredentialTypeMeta>;
+export declare const builtin_credential_type_meta: ReadonlyMap<string, CredentialTypeMeta>;
 /** The result of `create_credential_type_schema` — a Zod schema and metadata map. */
 export interface CredentialTypeSchemaResult {
     /**

package/dist/auth/credential_type_schema.js

@@ -60,7 +60,7 @@ export const BuiltinCredentialType = z.enum(BUILTIN_CREDENTIAL_TYPES);
  * here. Read once at startup by `create_credential_type_schema`;
  * runtime mutation has no effect on already-built schemas.
  */
-export const BUILTIN_CREDENTIAL_TYPE_META = new Map([
+export const builtin_credential_type_meta = new Map([
     [
         CREDENTIAL_TYPE_SESSION,
         { description: 'Cookie-based session credential, signed and validated server-side.' },
@@ -109,7 +109,7 @@ export const create_credential_type_schema = (consumer_types = {}) => {
         if (!parsed.success) {
             throw new Error(`Invalid credential-type name "${name}": ${parsed.error.issues[0].message}`);
         }
-        if (BUILTIN_CREDENTIAL_TYPE_META.has(name)) {
+        if (builtin_credential_type_meta.has(name)) {
             throw new Error(`Consumer credential-type "${name}" collides with builtin credential-type`);
         }
         if (seen.has(name)) {
@@ -119,7 +119,7 @@ export const create_credential_type_schema = (consumer_types = {}) => {
     }
     const all_names = [...BUILTIN_CREDENTIAL_TYPES, ...consumer_names];
     const CredentialType = z.enum(all_names);
-    const credential_types = new Map(BUILTIN_CREDENTIAL_TYPE_META);
+    const credential_types = new Map(builtin_credential_type_meta);
     for (const name of consumer_names) {
         credential_types.set(name, consumer_types[name]);
     }

package/dist/auth/grant_path_schema.d.ts

@@ -70,7 +70,7 @@ export interface GrantPathMeta {
  * here. Read once at startup by `create_grant_path_schema`; runtime
  * mutation has no effect on already-built schemas.
  */
-export declare const BUILTIN_GRANT_PATH_META: ReadonlyMap<string, GrantPathMeta>;
+export declare const builtin_grant_path_meta: ReadonlyMap<string, GrantPathMeta>;
 /** The result of `create_grant_path_schema` — a Zod schema and metadata map. */
 export interface GrantPathSchemaResult {
     /**

package/dist/auth/grant_path_schema.js

@@ -63,7 +63,7 @@ export const BuiltinGrantPath = z.enum(BUILTIN_GRANT_PATHS);
  * 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([
+export const builtin_grant_path_meta = new Map([
     [
         GRANT_PATH_ADMIN,
         {
@@ -119,7 +119,7 @@ export const create_grant_path_schema = (consumer_paths = {}) => {
         if (!parsed.success) {
             throw new Error(`Invalid grant-path name "${name}": ${parsed.error.issues[0].message}`);
         }
-        if (BUILTIN_GRANT_PATH_META.has(name)) {
+        if (builtin_grant_path_meta.has(name)) {
             throw new Error(`Consumer grant-path "${name}" collides with builtin grant-path`);
         }
         if (seen.has(name)) {
@@ -129,7 +129,7 @@ export const create_grant_path_schema = (consumer_paths = {}) => {
     }
     const all_names = [...BUILTIN_GRANT_PATHS, ...consumer_names];
     const GrantPath = z.enum(all_names);
-    const grant_paths = new Map(BUILTIN_GRANT_PATH_META);
+    const grant_paths = new Map(builtin_grant_path_meta);
     for (const name of consumer_names) {
         grant_paths.set(name, consumer_paths[name]);
     }

package/dist/auth/migrations.d.ts

@@ -17,7 +17,7 @@
  *
  * To add a migration in the pre-stable phase, prefer extending an existing
  * entry's body (consumers will re-bootstrap on upgrade). If you do append
- * a new entry to `AUTH_MIGRATIONS`, the runner will apply it on existing
+ * a new entry to `auth_migrations`, the runner will apply it on existing
  * tracker rows — the same shape that will become mandatory once the
  * schema stabilizes:
  *
@@ -46,7 +46,7 @@ export declare const AUTH_MIGRATION_NAMESPACE = "fuz_auth";
  * 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>;
+export declare const reserved_migration_namespaces: ReadonlyArray<string>;
 /**
  * Auth schema migrations in order.
  *
@@ -67,7 +67,7 @@ export declare const RESERVED_MIGRATION_NAMESPACES: ReadonlyArray<string>;
  *   (registry-membership validation against `create_scope_kind_schema`);
  *   v2 may add INSERT-time `(role, scope_kind)` enforcement.
  */
-export declare const AUTH_MIGRATIONS: Array<Migration>;
+export declare const auth_migrations: Array<Migration>;
 /** Pre-composed migration namespace for auth tables. */
-export declare const AUTH_MIGRATION_NS: MigrationNamespace;
+export declare const auth_migration_ns: MigrationNamespace;
 //# sourceMappingURL=migrations.d.ts.map

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;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"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA+BH,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,CAsF5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}