@fuzdev/fuz_app 0.58.0 → 0.60.0

package/dist/auth/actor_lookup_action_specs.js

@@ -0,0 +1,93 @@
+/**
+ * `actor_lookup` RPC spec — authenticated batched id → username/display_name
+ * resolver, keyed by actor id.
+ *
+ * Powers the labels arc for surfaces that stamp an actor id (bylines,
+ * owner columns, grantor labels, audit-log "by" cells). One round trip
+ * resolves an array of ids to display strings.
+ *
+ * ## Auth + rate-limit posture
+ *
+ * `{account: 'required', actor: 'none'}` + `rate_limit: 'account'`.
+ * Account-grain — only that the caller is signed in matters, not which
+ * actor is calling, so resolution skips the actor phase. The auth gate
+ * + per-account rate limit (default 1200/15min) + the
+ * {@link ACTOR_LOOKUP_IDS_MAX | per-call cap} bound the batched
+ * username-enumeration surface that the `cell_list` ↔ `actor_lookup`
+ * pair would otherwise present.
+ *
+ * If a public-surface byline ever lands (e.g. an unauthenticated
+ * gallery), it should resolve via a separate public-safe mechanism
+ * (SSR-stamped labels or a per-cell embedded actor label), **not** by
+ * loosening this gate.
+ *
+ * ## Wire shape — info-leak audit
+ *
+ * Output: `{actors: [{id, username, display_name?}]}`. Deliberately
+ * omitted:
+ *
+ * - `account_id` — the actor↔account join is a control-plane detail
+ * - `email`, password/credential fields — never queried
+ * - `created_at` / `updated_at` — timing-oracle avoidance
+ * - role / role_grants / session state — separation of concern
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank, so
+ * clients see `undefined` rather than a sentinel string. Unknown ids are
+ * silently absent from the response — by construction this is an
+ * existence-oracle (the caller can diff response ids against request
+ * ids), bounded by:
+ *
+ * 1. rate-limit (per-account, see above),
+ * 2. {@link ACTOR_LOOKUP_IDS_MAX} cap per call,
+ * 3. actor-uuid intractability (122-bit random),
+ * 4. hard-deleted actors are indistinguishable from never-existed (no
+ *    tombstone oracle — see `actor_lookup_queries.ts`).
+ *
+ * Response order is unspecified — callers index by `id` when needed.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+/**
+ * Hard cap on the number of ids resolvable in one call. Bounds the
+ * batched username-enumeration surface.
+ */
+export const ACTOR_LOOKUP_IDS_MAX = 50;
+/** One resolved actor row. `display_name` omitted when blank. */
+export const ActorLookupEntryJson = z.strictObject({
+    id: Uuid,
+    username: z.string(),
+    display_name: z.string().optional(),
+});
+export const ActorLookupInput = z.strictObject({
+    ids: z
+        .array(Uuid)
+        .min(1)
+        .max(ACTOR_LOOKUP_IDS_MAX)
+        .meta({
+        description: `Actor ids to resolve. Capped at ${ACTOR_LOOKUP_IDS_MAX}; unknown ids are silently absent from the response.`,
+    }),
+});
+export const ActorLookupOutput = z.strictObject({
+    actors: z.array(ActorLookupEntryJson),
+});
+export const actor_lookup_action_spec = {
+    method: 'actor_lookup',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'none' },
+    side_effects: false,
+    input: ActorLookupInput,
+    output: ActorLookupOutput,
+    async: true,
+    rate_limit: 'account',
+    description: `Batched id → (username, display_name) resolver, keyed by actor id. Powers the labels arc for surfaces that stamp an actor id (e.g. cell owners, grant grantors). Authenticated + per-account rate-limited to bound batched username enumeration. Cap ${ACTOR_LOOKUP_IDS_MAX}; unknown ids absent from response.`,
+};
+/**
+ * All actor_lookup action specs — independent opt-in registry. Consumers
+ * spread alongside `all_standard_action_specs` if they want the labels
+ * arc; not folded into the standard bundle because consumers without a
+ * byline surface can skip it.
+ */
+export const all_actor_lookup_action_specs = [actor_lookup_action_spec];

package/dist/auth/actor_lookup_actions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `actor_lookup` RPC handler.
+ *
+ * Pure read — no audit, no side effects. Auth (`account: 'required'`) +
+ * rate-limit (`account`-grain) enforced at the spec layer; see
+ * `./actor_lookup_action_specs.ts` for the info-leak audit.
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank,
+ * matching the wire shape `display_name?` so the typed client sees an
+ * `undefined` rather than a sentinel string.
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+import type { RouteFactoryDeps } from './deps.js';
+/** Dependencies for `create_actor_lookup_actions`. */
+export type ActorLookupActionDeps = Pick<RouteFactoryDeps, 'log'>;
+export declare const create_actor_lookup_actions: (_deps: ActorLookupActionDeps) => Array<RpcAction>;
+//# sourceMappingURL=actor_lookup_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_lookup_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_lookup_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAShD,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;AAElE,eAAO,MAAM,2BAA2B,GAAI,OAAO,qBAAqB,KAAG,KAAK,CAAC,SAAS,CAkBzF,CAAC"}

package/dist/auth/actor_lookup_actions.js

@@ -0,0 +1,32 @@
+/**
+ * `actor_lookup` RPC handler.
+ *
+ * Pure read — no audit, no side effects. Auth (`account: 'required'`) +
+ * rate-limit (`account`-grain) enforced at the spec layer; see
+ * `./actor_lookup_action_specs.ts` for the info-leak audit.
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank,
+ * matching the wire shape `display_name?` so the typed client sees an
+ * `undefined` rather than a sentinel string.
+ *
+ * @module
+ */
+import { rpc_action } from '../actions/action_rpc.js';
+import { query_actors_by_ids } from './actor_lookup_queries.js';
+import { actor_lookup_action_spec, } from './actor_lookup_action_specs.js';
+export const create_actor_lookup_actions = (_deps) => {
+    const handler = async (input, ctx) => {
+        const rows = await query_actors_by_ids(ctx, input.ids);
+        return {
+            actors: rows.map((row) => {
+                const display_name = row.display_name?.trim();
+                return {
+                    id: row.id,
+                    username: row.username,
+                    ...(display_name ? { display_name } : {}),
+                };
+            }),
+        };
+    };
+    return [rpc_action(actor_lookup_action_spec, handler)];
+};

package/dist/auth/actor_lookup_queries.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Batched actor-by-id resolver.
+ *
+ * Joins `actor` ⨝ `account` so callers see `(username, display_name)` for
+ * each actor row. The byline / owner-column / grantor surfaces stamp an
+ * actor id, so resolving "who is this actor?" lands the human label in
+ * one round trip.
+ *
+ * Accounts may host multiple actors (multi-actor shipped in v0.55.0).
+ * The inner join still resolves one row per actor — `actor.account_id`
+ * is `NOT NULL` so every actor has exactly one account.
+ *
+ * Info-leak posture (see `actor_lookup_action_specs.ts` § audit):
+ *
+ * - Row shape **omits** `account_id` — the join is control-plane,
+ *   not wire-visible.
+ * - Hard-deleted actors (or account-cascade-orphaned rows) drop out
+ *   silently — indistinguishable from never-existed (no tombstone
+ *   oracle).
+ * - No `created_at` / `updated_at` projected (timing-oracle avoidance).
+ * - Response order is unspecified — `WHERE id = ANY(...)` returns
+ *   index-scan order in practice but callers must not depend on it.
+ *
+ * Caller is responsible for capping `ids.length` — the SQL itself does
+ * not enforce a bound; the action-spec layer surfaces `invalid_params`
+ * via `ACTOR_LOOKUP_IDS_MAX`.
+ *
+ * @module
+ */
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { QueryDeps } from '../db/query_deps.js';
+/** Row shape returned to handlers — wire mapping happens at the action layer. */
+export interface ActorLookupRow {
+    id: Uuid;
+    username: string;
+    display_name: string | null;
+}
+/**
+ * Resolve a batch of actor ids to `(id, username, display_name)`. Empty
+ * input fast-paths to `[]`. Hard-deleted actors (or account-cascade-
+ * orphaned rows) drop out of the result silently.
+ */
+export declare const query_actors_by_ids: (deps: QueryDeps, ids: ReadonlyArray<Uuid>) => Promise<Array<ActorLookupRow>>;
+//# sourceMappingURL=actor_lookup_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_lookup_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_lookup_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,KAAK,aAAa,CAAC,IAAI,CAAC,KACtB,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAS/B,CAAC"}

package/dist/auth/actor_lookup_queries.js

@@ -0,0 +1,42 @@
+/**
+ * Batched actor-by-id resolver.
+ *
+ * Joins `actor` ⨝ `account` so callers see `(username, display_name)` for
+ * each actor row. The byline / owner-column / grantor surfaces stamp an
+ * actor id, so resolving "who is this actor?" lands the human label in
+ * one round trip.
+ *
+ * Accounts may host multiple actors (multi-actor shipped in v0.55.0).
+ * The inner join still resolves one row per actor — `actor.account_id`
+ * is `NOT NULL` so every actor has exactly one account.
+ *
+ * Info-leak posture (see `actor_lookup_action_specs.ts` § audit):
+ *
+ * - Row shape **omits** `account_id` — the join is control-plane,
+ *   not wire-visible.
+ * - Hard-deleted actors (or account-cascade-orphaned rows) drop out
+ *   silently — indistinguishable from never-existed (no tombstone
+ *   oracle).
+ * - No `created_at` / `updated_at` projected (timing-oracle avoidance).
+ * - Response order is unspecified — `WHERE id = ANY(...)` returns
+ *   index-scan order in practice but callers must not depend on it.
+ *
+ * Caller is responsible for capping `ids.length` — the SQL itself does
+ * not enforce a bound; the action-spec layer surfaces `invalid_params`
+ * via `ACTOR_LOOKUP_IDS_MAX`.
+ *
+ * @module
+ */
+/**
+ * Resolve a batch of actor ids to `(id, username, display_name)`. Empty
+ * input fast-paths to `[]`. Hard-deleted actors (or account-cascade-
+ * orphaned rows) drop out of the result silently.
+ */
+export const query_actors_by_ids = async (deps, ids) => {
+    if (ids.length === 0)
+        return [];
+    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 act.id = ANY($1)`, [ids]);
+};

package/dist/auth/actor_search_action_specs.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `actor_search` RPC spec — authenticated case-insensitive prefix search
+ * over `actor.name`, returning the same `{id, username, display_name?}`
+ * wire shape as `actor_lookup`.
+ *
+ * Powers person-target pickers — visiones' `CellGrantsEditor.svelte`
+ * teacher-picks-student flow replaces the deferred `actor_by_name` arm of
+ * `cell_grant_create` with a debounced search against this method. Sibling
+ * to `actor_lookup`: that resolves a known batch of ids → labels; this
+ * resolves a partial name → candidate actors.
+ *
+ * ## Auth + rate-limit posture
+ *
+ * `{account: 'required', actor: 'none'}` + `rate_limit: 'account'`. Same
+ * shape as `actor_lookup`: only that the caller is signed in matters, not
+ * which actor is calling. The auth gate, the per-account rate limit
+ * (default 1200/15min), and the `ACTOR_SEARCH_LIMIT_MAX` per-call cap
+ * bound the enumeration surface this method would otherwise present.
+ *
+ * The handler additionally requires the caller to be admin when
+ * `scope_ids` is empty (the unbounded global-search arm). Non-admin
+ * callers must always pass at least one scope_id — the SQL filters
+ * actors to those holding a role_grant on one of the supplied scopes, so
+ * a non-admin caller is restricted to actors they share a scope with.
+ * The admin check is account-grain (any actor on the caller's account
+ * holds a global `admin` role_grant), matching the `actor: 'none'` posture.
+ *
+ * ## Caller-passes-scope_ids design
+ *
+ * `scope_ids` is trusted as a filter, not as an authority claim — the
+ * SQL filters to actors with role_grants on those scopes regardless of
+ * whether the caller has authority over them. Consumers are responsible
+ * for pre-filtering `scope_ids` against their own authority before
+ * calling. Visiones passes the set of classrooms the teacher teaches,
+ * sourced client-side from the teacher's role_grant list; the teacher
+ * predicate stays in the visiones layer rather than baked into fuz_app.
+ *
+ * Crucially, this does **not** widen the scope-existence oracle: an
+ * attacker passing a random scope_id cannot learn "this scope has
+ * members matching X" because the join filters to actors holding a
+ * role_grant on the scope, and the SQL surfaces neither "did the scope
+ * exist" nor "did the scope have non-matching members" — only the
+ * matching subset is returned.
+ *
+ * ## Wire shape — info-leak audit
+ *
+ * Output `{actors: [{id, username, display_name?}]}` is identical to
+ * `actor_lookup`'s — see `./actor_lookup_action_specs.ts` for the full
+ * field-by-field audit. Same omissions (`account_id`, email,
+ * timestamps, role / role_grants / session state), same `display_name`
+ * omitted-not-null contract, same response-order-unspecified rule.
+ *
+ * Additional `actor_search`-specific posture:
+ *
+ * - Prefix match (`LOWER(name) LIKE LOWER(query) || '%'`), not full
+ *   `%query%`. Full-LIKE would let a single call enumerate one
+ *   alphabetical bucket spread across many starting letters, which
+ *   defeats the per-call cap as an enumeration bound.
+ * - Hard-deleted actors silently drop (cascade through `actor.account_id`
+ *   FK) — no tombstone oracle, same posture as `actor_lookup`.
+ * - Empty result set on no-match — fail-soft like `cell_list`. No
+ *   "no actor matches" error message that would leak an existence
+ *   boundary on the search-term axis.
+ *
+ * ## Why not extend `actor_lookup`?
+ *
+ * Splitting the methods keeps the wire contracts independent: `actor_lookup`'s
+ * input is `{ids}`, `actor_search`'s is `{query}` + optional filters.
+ * Both surface the same `ActorLookupEntryJson` row shape (re-used here),
+ * so the labels arc on the consumer side stays uniform.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on the number of rows returned per call. Bounds the search-result
+ * enumeration surface. Default limit (`ACTOR_SEARCH_LIMIT_DEFAULT`) is
+ * smaller — most pickers render fewer rows than the cap.
+ */
+export declare const ACTOR_SEARCH_LIMIT_MAX = 50;
+/** Default `limit` when the caller omits it. */
+export declare const ACTOR_SEARCH_LIMIT_DEFAULT = 20;
+/**
+ * Hard cap on the query string length. Long inputs offer no extra search
+ * value once they exceed `actor.name` realistic lengths, and a low cap
+ * keeps the per-request work bounded for pathological inputs.
+ */
+export declare const ACTOR_SEARCH_QUERY_LENGTH_MAX = 50;
+/**
+ * Reason: `scope_ids` was empty and the caller is not admin. Distinct from
+ * standard `invalid_params` issues so the visiones picker can surface a
+ * specific "pick a scope first" message rather than echoing Zod issues.
+ */
+export declare const ERROR_ACTOR_SEARCH_SCOPE_REQUIRED: "actor_search_scope_required";
+export declare const ActorSearchInput: z.ZodObject<{
+    query: z.ZodString;
+    scope_ids: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ActorSearchInput = z.infer<typeof ActorSearchInput>;
+export declare const ActorSearchOutput: z.ZodObject<{
+    actors: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        username: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ActorSearchOutput = z.infer<typeof ActorSearchOutput>;
+export declare const actor_search_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        query: z.ZodString;
+        scope_ids: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        actors: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            username: z.ZodString;
+            display_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    rate_limit: "account";
+    error_reasons: "actor_search_scope_required"[];
+    description: string;
+};
+/**
+ * All actor_search action specs — independent opt-in registry. Like
+ * `all_actor_lookup_action_specs`, not folded into `all_standard_action_specs`
+ * because consumers without a person-target picker can skip it.
+ */
+export declare const all_actor_search_action_specs: readonly [{
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        query: z.ZodString;
+        scope_ids: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        actors: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            username: z.ZodString;
+            display_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    async: true;
+    rate_limit: "account";
+    error_reasons: "actor_search_scope_required"[];
+    description: string;
+}];
+//# sourceMappingURL=actor_search_action_specs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_search_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_search_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAG,6BAAsC,CAAC;AAExF,eAAO,MAAM,gBAAgB;;;;kBAqB3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,iBAAiB;;;;;;kBAE5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;CAYA,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC"}

package/dist/auth/actor_search_action_specs.js

@@ -0,0 +1,139 @@
+/**
+ * `actor_search` RPC spec — authenticated case-insensitive prefix search
+ * over `actor.name`, returning the same `{id, username, display_name?}`
+ * wire shape as `actor_lookup`.
+ *
+ * Powers person-target pickers — visiones' `CellGrantsEditor.svelte`
+ * teacher-picks-student flow replaces the deferred `actor_by_name` arm of
+ * `cell_grant_create` with a debounced search against this method. Sibling
+ * to `actor_lookup`: that resolves a known batch of ids → labels; this
+ * resolves a partial name → candidate actors.
+ *
+ * ## Auth + rate-limit posture
+ *
+ * `{account: 'required', actor: 'none'}` + `rate_limit: 'account'`. Same
+ * shape as `actor_lookup`: only that the caller is signed in matters, not
+ * which actor is calling. The auth gate, the per-account rate limit
+ * (default 1200/15min), and the `ACTOR_SEARCH_LIMIT_MAX` per-call cap
+ * bound the enumeration surface this method would otherwise present.
+ *
+ * The handler additionally requires the caller to be admin when
+ * `scope_ids` is empty (the unbounded global-search arm). Non-admin
+ * callers must always pass at least one scope_id — the SQL filters
+ * actors to those holding a role_grant on one of the supplied scopes, so
+ * a non-admin caller is restricted to actors they share a scope with.
+ * The admin check is account-grain (any actor on the caller's account
+ * holds a global `admin` role_grant), matching the `actor: 'none'` posture.
+ *
+ * ## Caller-passes-scope_ids design
+ *
+ * `scope_ids` is trusted as a filter, not as an authority claim — the
+ * SQL filters to actors with role_grants on those scopes regardless of
+ * whether the caller has authority over them. Consumers are responsible
+ * for pre-filtering `scope_ids` against their own authority before
+ * calling. Visiones passes the set of classrooms the teacher teaches,
+ * sourced client-side from the teacher's role_grant list; the teacher
+ * predicate stays in the visiones layer rather than baked into fuz_app.
+ *
+ * Crucially, this does **not** widen the scope-existence oracle: an
+ * attacker passing a random scope_id cannot learn "this scope has
+ * members matching X" because the join filters to actors holding a
+ * role_grant on the scope, and the SQL surfaces neither "did the scope
+ * exist" nor "did the scope have non-matching members" — only the
+ * matching subset is returned.
+ *
+ * ## Wire shape — info-leak audit
+ *
+ * Output `{actors: [{id, username, display_name?}]}` is identical to
+ * `actor_lookup`'s — see `./actor_lookup_action_specs.ts` for the full
+ * field-by-field audit. Same omissions (`account_id`, email,
+ * timestamps, role / role_grants / session state), same `display_name`
+ * omitted-not-null contract, same response-order-unspecified rule.
+ *
+ * Additional `actor_search`-specific posture:
+ *
+ * - Prefix match (`LOWER(name) LIKE LOWER(query) || '%'`), not full
+ *   `%query%`. Full-LIKE would let a single call enumerate one
+ *   alphabetical bucket spread across many starting letters, which
+ *   defeats the per-call cap as an enumeration bound.
+ * - Hard-deleted actors silently drop (cascade through `actor.account_id`
+ *   FK) — no tombstone oracle, same posture as `actor_lookup`.
+ * - Empty result set on no-match — fail-soft like `cell_list`. No
+ *   "no actor matches" error message that would leak an existence
+ *   boundary on the search-term axis.
+ *
+ * ## Why not extend `actor_lookup`?
+ *
+ * Splitting the methods keeps the wire contracts independent: `actor_lookup`'s
+ * input is `{ids}`, `actor_search`'s is `{query}` + optional filters.
+ * Both surface the same `ActorLookupEntryJson` row shape (re-used here),
+ * so the labels arc on the consumer side stays uniform.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { ActorLookupEntryJson } from './actor_lookup_action_specs.js';
+/**
+ * Hard cap on the number of rows returned per call. Bounds the search-result
+ * enumeration surface. Default limit (`ACTOR_SEARCH_LIMIT_DEFAULT`) is
+ * smaller — most pickers render fewer rows than the cap.
+ */
+export const ACTOR_SEARCH_LIMIT_MAX = 50;
+/** Default `limit` when the caller omits it. */
+export const ACTOR_SEARCH_LIMIT_DEFAULT = 20;
+/**
+ * Hard cap on the query string length. Long inputs offer no extra search
+ * value once they exceed `actor.name` realistic lengths, and a low cap
+ * keeps the per-request work bounded for pathological inputs.
+ */
+export const ACTOR_SEARCH_QUERY_LENGTH_MAX = 50;
+/**
+ * Reason: `scope_ids` was empty and the caller is not admin. Distinct from
+ * standard `invalid_params` issues so the visiones picker can surface a
+ * specific "pick a scope first" message rather than echoing Zod issues.
+ */
+export const ERROR_ACTOR_SEARCH_SCOPE_REQUIRED = 'actor_search_scope_required';
+export const ActorSearchInput = z.strictObject({
+    query: z
+        .string()
+        .min(1)
+        .max(ACTOR_SEARCH_QUERY_LENGTH_MAX)
+        .meta({
+        description: `Case-insensitive prefix match against \`actor.name\`. Length 1–${ACTOR_SEARCH_QUERY_LENGTH_MAX}.`,
+    }),
+    scope_ids: z.array(Uuid).optional().meta({
+        description: 'Restrict results to actors holding a role_grant on any of these scopes. Required (non-empty) for non-admin callers; admin callers may omit or pass empty for unbounded search. Caller is responsible for pre-filtering against their own authority — the SQL filter does not enforce it.',
+    }),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ACTOR_SEARCH_LIMIT_MAX)
+        .optional()
+        .meta({
+        description: `Maximum rows to return. Defaults to ${ACTOR_SEARCH_LIMIT_DEFAULT}, hard cap ${ACTOR_SEARCH_LIMIT_MAX}.`,
+    }),
+});
+export const ActorSearchOutput = z.strictObject({
+    actors: z.array(ActorLookupEntryJson),
+});
+export const actor_search_action_spec = {
+    method: 'actor_search',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'none' },
+    side_effects: false,
+    input: ActorSearchInput,
+    output: ActorSearchOutput,
+    async: true,
+    rate_limit: 'account',
+    error_reasons: [ERROR_ACTOR_SEARCH_SCOPE_REQUIRED],
+    description: `Case-insensitive prefix search over actor.name, returning {id, username, display_name?} rows. Authenticated + per-account rate-limited; non-admin callers must pass at least one scope_id. Default limit ${ACTOR_SEARCH_LIMIT_DEFAULT}, hard cap ${ACTOR_SEARCH_LIMIT_MAX}.`,
+};
+/**
+ * All actor_search action specs — independent opt-in registry. Like
+ * `all_actor_lookup_action_specs`, not folded into `all_standard_action_specs`
+ * because consumers without a person-target picker can skip it.
+ */
+export const all_actor_search_action_specs = [actor_search_action_spec];

package/dist/auth/actor_search_actions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `actor_search` RPC handler.
+ *
+ * Pure read — no audit, no side effects. Auth (`account: 'required'`,
+ * `actor: 'none'`) + rate-limit (`account`-grain) enforced at the spec
+ * layer; see `./actor_search_action_specs.ts` for the info-leak audit
+ * and threat model.
+ *
+ * The handler adds two checks the spec layer can't express:
+ *
+ * - **Admin gate on empty `scope_ids`** — unbounded global search is
+ *   admin-only. Non-admin callers without a `scope_ids` filter are
+ *   rejected with `invalid_params` carrying `actor_search_scope_required`.
+ *   The admin check is account-grain (any actor on the caller's account
+ *   holds a global `admin` role_grant) since the `actor: 'none'` posture
+ *   doesn't load `auth.role_grants` for an in-memory check.
+ * - **Limit clamp** — input is bounded by `ACTOR_SEARCH_LIMIT_MAX` at
+ *   the schema; the handler picks the default when omitted.
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank,
+ * matching the wire shape `ActorLookupEntryJson.display_name?` — same
+ * convention as `actor_lookup_actions.ts`.
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+import type { RouteFactoryDeps } from './deps.js';
+/** Dependencies for `create_actor_search_actions`. */
+export type ActorSearchActionDeps = Pick<RouteFactoryDeps, 'log'>;
+export declare const create_actor_search_actions: (_deps: ActorSearchActionDeps) => Array<RpcAction>;
+//# sourceMappingURL=actor_search_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_search_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_search_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAqC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAE5F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAahD,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;AAElE,eAAO,MAAM,2BAA2B,GAAI,OAAO,qBAAqB,KAAG,KAAK,CAAC,SAAS,CAiCzF,CAAC"}

package/dist/auth/actor_search_actions.js

@@ -0,0 +1,61 @@
+/**
+ * `actor_search` RPC handler.
+ *
+ * Pure read — no audit, no side effects. Auth (`account: 'required'`,
+ * `actor: 'none'`) + rate-limit (`account`-grain) enforced at the spec
+ * layer; see `./actor_search_action_specs.ts` for the info-leak audit
+ * and threat model.
+ *
+ * The handler adds two checks the spec layer can't express:
+ *
+ * - **Admin gate on empty `scope_ids`** — unbounded global search is
+ *   admin-only. Non-admin callers without a `scope_ids` filter are
+ *   rejected with `invalid_params` carrying `actor_search_scope_required`.
+ *   The admin check is account-grain (any actor on the caller's account
+ *   holds a global `admin` role_grant) since the `actor: 'none'` posture
+ *   doesn't load `auth.role_grants` for an in-memory check.
+ * - **Limit clamp** — input is bounded by `ACTOR_SEARCH_LIMIT_MAX` at
+ *   the schema; the handler picks the default when omitted.
+ *
+ * `display_name` is omitted (not `null`) when `actor.name` is blank,
+ * matching the wire shape `ActorLookupEntryJson.display_name?` — same
+ * convention as `actor_lookup_actions.ts`.
+ *
+ * @module
+ */
+import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
+import { rpc_action } from '../actions/action_rpc.js';
+import { query_actor_search } from './actor_search_queries.js';
+import { query_account_has_global_role } from './role_grant_queries.js';
+import { ROLE_ADMIN } from './role_schema.js';
+import { ACTOR_SEARCH_LIMIT_DEFAULT, ERROR_ACTOR_SEARCH_SCOPE_REQUIRED, actor_search_action_spec, } from './actor_search_action_specs.js';
+export const create_actor_search_actions = (_deps) => {
+    const handler = async (input, ctx) => {
+        if (!input.scope_ids || input.scope_ids.length === 0) {
+            // Unbounded global search is admin-only. Account-grain admin
+            // check — any actor on the caller's account holds the role.
+            const is_admin = await query_account_has_global_role(ctx, ctx.auth.account.id, ROLE_ADMIN);
+            if (!is_admin) {
+                throw jsonrpc_errors.invalid_params('scope_ids required for non-admin callers', {
+                    reason: ERROR_ACTOR_SEARCH_SCOPE_REQUIRED,
+                });
+            }
+        }
+        const rows = await query_actor_search(ctx, {
+            query: input.query,
+            scope_ids: input.scope_ids,
+            limit: input.limit ?? ACTOR_SEARCH_LIMIT_DEFAULT,
+        });
+        return {
+            actors: rows.map((row) => {
+                const display_name = row.display_name?.trim();
+                return {
+                    id: row.id,
+                    username: row.username,
+                    ...(display_name ? { display_name } : {}),
+                };
+            }),
+        };
+    };
+    return [rpc_action(actor_search_action_spec, handler)];
+};