@fuzdev/fuz_app 0.58.0 → 0.60.0

package/dist/auth/CLAUDE.md

@@ -21,7 +21,7 @@ sections.
 | Module                 | Exports                                                                                                                                                                                                                                                                                   |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `keyring.ts`           | `Keyring`, `create_keyring`, `validate_keyring`, `create_validated_keyring`, `ValidatedKeyringResult`                                                                                                                                                                                     |
-| `session_cookie.ts`    | `SessionOptions<T>`, `SessionCookieOptions`, `SESSION_COOKIE_OPTIONS`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S`, `ParsedSession`, `ProcessSessionResult`, `parse_session`, `create_session_cookie_value`, `process_session_cookie`, `create_session_config`, `fuz_session_config` |
+| `session_cookie.ts`    | `SessionOptions<T>`, `SessionCookieOptions`, `session_cookie_options`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S`, `ParsedSession`, `ProcessSessionResult`, `parse_session`, `create_session_cookie_value`, `process_session_cookie`, `create_session_config`, `fuz_session_config` |
 | `password.ts`          | `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300)                                                                                                                                                                        |
 | `password_argon2.ts`   | `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`                                                                                                                                                                                                                |
 | `api_token.ts`         | `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`                                                                                                                                                                                                          |
@@ -179,7 +179,7 @@ those three. Mirrors the open-registry pattern used for `RoleName` /
   constant is named `_API_TOKEN` (not `_BEARER`) so wire literal and
   the `api_token` storage table stay in lockstep.
 - `BUILTIN_CREDENTIAL_TYPES` const tuple, `BuiltinCredentialType` Zod
-  enum, `BUILTIN_CREDENTIAL_TYPE_META` admin-UI-facing descriptions.
+  enum, `builtin_credential_type_meta` admin-UI-facing descriptions.
 - `create_credential_type_schema(consumer_types?)`
   → `{CredentialType, credential_types: ReadonlyMap}`. Builtins always
   present; consumer collisions / regex failures / duplicates throw at
@@ -197,7 +197,7 @@ granted. Four builtins (`admin`, `self_service`, `system`, `bootstrap`).
 - `GRANT_PATH_ADMIN` / `_SELF_SERVICE` / `_SYSTEM` / `_BOOTSTRAP` —
   builtin literal constants.
 - `BUILTIN_GRANT_PATHS` const tuple, `BuiltinGrantPath` Zod enum,
-  `BUILTIN_GRANT_PATH_META` descriptions.
+  `builtin_grant_path_meta` descriptions.
 - `create_grant_path_schema(consumer_paths?)`
   → `{GrantPath, grant_paths: ReadonlyMap}`. Same construction-time
   guards as the credential-type schema. Pass the result into
@@ -224,7 +224,7 @@ against the corresponding open registries at construction time.
 - `ROLE_KEEPER = 'keeper'` — bootstrap-only via daemon token; `grant_paths: ['bootstrap']`,
   `required_credential_types: ['daemon_token']`.
 - `ROLE_ADMIN = 'admin'` — admin-grantable; `grant_paths: ['admin']`.
-- `BUILTIN_ROLES`, `BuiltinRole` (Zod enum), `BUILTIN_ROLE_SPECS_BY_NAME`
+- `BUILTIN_ROLES`, `BuiltinRole` (Zod enum), `builtin_role_specs_by_name`
   (`ReadonlyMap<string, RoleSpec>`) — not overridable by consumers.
 - `RoleSpec`: `{name, description?, required_credential_types?, applicable_scope_kinds?, grant_paths?}`
   — every cross-axis field is an open-registry string array. Empty
@@ -302,7 +302,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
 
 #### Metadata schemas
 
-- `AUDIT_METADATA_SCHEMAS` — per-type `z.looseObject`. Notable shapes:
+- `audit_metadata_schemas` — per-type `z.looseObject`. Notable shapes:
   - `role_grant_create` — `scope_id`, optional `role_grant_id` (failed grants
     omit — admin-grant-path denial never produces a row), optional
     `source_offer_id`, optional `self_service` (set by
@@ -376,7 +376,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
   without validation). Pass the result to `create_app_backend({audit_log_config})`
   — it gets captured inside the bound `AppDeps.audit` emitter, and every
   call to `audit.emit` validates against it (defaults to
-  `BUILTIN_AUDIT_LOG_CONFIG` when absent). `query_audit_log` still accepts
+  `builtin_audit_log_config` when absent). `query_audit_log` still accepts
   the trailing `config` positional arg for in-transaction emit sites that
   hold a transaction-scoped DB only. Builtin collisions and
   `AuditEventTypeName` format failures throw at construction. The DB
@@ -396,7 +396,7 @@ Zod enum; `AuditOutcome` is `'success' | 'failure'`.
   factory they track the same config, but a hand-rolled `AuditLogConfig`
   (or a cast escape) can fire both on a single emission. Sample via
   `get_*` getters; `reset_*` are test-only. `AUDIT_EVENT_TYPES`,
-  `AUDIT_METADATA_SCHEMAS`, `BUILTIN_AUDIT_LOG_CONFIG`, and the configs
+  `audit_metadata_schemas`, `builtin_audit_log_config`, and the configs
   returned by `create_audit_log_config` are `Object.freeze`'d to convert
   accidental mutation (bugs, test cross-contamination, cast escapes)
   into loud TypeErrors — not a security boundary.
@@ -470,7 +470,7 @@ exports: `RoleGrantOfferReceivedParams`, `_RetractedParams`, `_AcceptedParams`,
 `_DeclinedParams`, `_SupersedeParams`, `RoleGrantRevokeParams`. Notification
 builders: `build_role_grant_offer_received_notification(params)` etc.
 
-`ROLE_GRANT_OFFER_NOTIFICATION_SPECS: Array<EventSpec>` — pass to
+`role_grant_offer_notification_specs: Array<EventSpec>` — pass to
 `create_app_server`'s `event_specs` so the attack surface reflects them
 and DEV-mode `create_validated_broadcaster` catches payload drift.
 
@@ -521,6 +521,31 @@ account_id = ANY(...))` so `actor.id`s never round-trip back to the
   visibility). Returns `Array<AdminAccountEntryJson>`, sorted by
   `created_at`.
 
+### `actor_lookup_queries.ts`
+
+- `query_actors_by_ids(deps, ids) → Array<ActorLookupRow>` — batched
+  `actor` ⨝ `account` INNER JOIN, returns
+  `{id, username, display_name}` per resolved actor. Empty input
+  fast-paths to `[]`; hard-deleted (or cascade-orphaned) rows silently
+  drop. Row shape omits `account_id` — the join is control-plane, not
+  wire-visible. Caller bounds `ids.length` (the action spec enforces
+  `ACTOR_LOOKUP_IDS_MAX`); SQL does not.
+
+### `actor_search_queries.ts`
+
+- `query_actor_search(deps, {query, scope_ids?, limit}) → Array<ActorLookupRow>` —
+  case-insensitive LIKE-prefix on `actor.name`, backed by the
+  `idx_actor_name_lower` functional index in `auth_ddl.ts`. Returns the
+  same `{id, username, display_name}` row shape as `query_actors_by_ids`
+  so the labels arc stays uniform. LIKE wildcards (`%`, `_`, `\`) in
+  the user-supplied `query` are escaped before substitution so the
+  prefix-only contract is enforceable. When `scope_ids` is non-empty,
+  the result is filtered to actors holding an **active** role_grant
+  (`revoked_at IS NULL AND (expires_at IS NULL OR expires_at > NOW())`)
+  on one of the supplied scopes; `DISTINCT` collapses multi-grant
+  duplicates. When `scope_ids` is empty, no role_grant join — the handler
+  enforces admin for that path.
+
 ### `role_grant_queries.ts`
 
 - `query_create_role_grant` — idempotent; `ON CONFLICT` target and fallback
@@ -551,6 +576,12 @@ account_id = ANY(...))` so `actor.id`s never round-trip back to the
   that isn't the request actor (e.g., post-mutation verification, scripts,
   audit-time checks). For the request actor, prefer `has_scoped_role` /
   `has_any_scoped_role` on the in-memory `auth.role_grants` snapshot.
+- `query_account_has_global_role(deps, account_id, role)` — account-grain
+  sibling: does any actor on `account_id` hold an active **global**
+  (`scope_id IS NULL`) role_grant for `role`? For surfaces with
+  `auth: actor: 'none'` that don't load `auth.role_grants` and can't use
+  `has_scoped_role`. EXISTS over the `idx_role_grant_actor`-backed
+  subquery, stops at the first match.
 - `query_role_grant_find_account_id_for_role(deps, role)` — joins
   role_grant → actor → account, returns first match. Used by daemon token
   middleware to resolve the keeper account.
@@ -701,7 +732,7 @@ run'` if the seed somehow missed (defensive — migrations always seed).
 ### `audit_log_queries.ts`
 
 - `query_audit_log<T>(deps, input, config?)` — `config` defaults to
-  `BUILTIN_AUDIT_LOG_CONFIG`. Membership check runs against
+  `builtin_audit_log_config`. Membership check runs against
   `config.event_types`; metadata validation runs independently against
   `config.metadata_schemas[event_type]` when present. Mismatches and
   unknown types log + bump their counters (see schema section);
@@ -769,8 +800,8 @@ without rebuilding `AppDeps`.
 
 ### `migrations.ts`
 
-- `AUTH_MIGRATION_NAMESPACE = 'fuz_auth'`, `AUTH_MIGRATION_NS` (pre-composed), `RESERVED_MIGRATION_NAMESPACES: ReadonlyArray<string>` (membership list `create_app_backend` rejects on; consumer-discoverable instead of probing the runtime throw).
-- `AUTH_MIGRATIONS`:
+- `AUTH_MIGRATION_NAMESPACE = 'fuz_auth'`, `auth_migration_ns` (pre-composed), `reserved_migration_namespaces: ReadonlyArray<string>` (membership list `create_app_backend` rejects on; consumer-discoverable instead of probing the runtime throw).
+- `auth_migrations`:
   - **v0 `full_auth_schema`** — every table + index + seed for the v1
     identity system (account, actor, role_grant, auth_session, api_token,
     audit_log, bootstrap_lock, invite, app_settings). All
@@ -1232,26 +1263,30 @@ acting?: ActingActor` biconditional).
 
 | Spec                                       | Side effects | Rate limit  | Input                                                     | Output                        |
 | ------------------------------------------ | ------------ | ----------- | --------------------------------------------------------- | ----------------------------- |
-| `admin_account_list_action_spec`           | false        |             | `{limit?, offset?}`                                       | `{accounts, grantable_roles}` |
-| `admin_session_list_action_spec`           | false        |             | `z.void()`                                                | `{sessions}`                  |
+| `admin_account_list_action_spec`           | false        | `'account'` | `{limit?, offset?}`                                       | `{accounts, grantable_roles}` |
+| `admin_session_list_action_spec`           | false        | `'account'` | `z.void()`                                                | `{sessions}`                  |
 | `admin_session_revoke_all_action_spec`     | true         | `'account'` | `{account_id}`                                            | `{ok, count}`                 |
 | `admin_token_revoke_all_action_spec`       | true         | `'account'` | `{account_id}`                                            | `{ok, count}`                 |
-| `audit_log_list_action_spec`               | false        |             | `{event_type?, account_id?, limit?, offset?, since_seq?}` | `{events}`                    |
-| `audit_log_role_grant_history_action_spec` | false        |             | `{limit?, offset?}`                                       | `{events}`                    |
+| `audit_log_list_action_spec`               | false        | `'account'` | `{event_type?, account_id?, limit?, offset?, since_seq?}` | `{events}`                    |
+| `audit_log_role_grant_history_action_spec` | false        | `'account'` | `{limit?, offset?}`                                       | `{events}`                    |
 | `invite_create_action_spec`                | true         | `'account'` | `{email?, username?}`                                     | `{ok, invite}`                |
-| `invite_list_action_spec`                  | false        |             | `z.void()`                                                | `{invites}`                   |
+| `invite_list_action_spec`                  | false        | `'account'` | `z.void()`                                                | `{invites}`                   |
 | `invite_delete_action_spec`                | true         | `'account'` | `{invite_id}`                                             | `{ok}`                        |
 | `app_settings_get_action_spec`             | false        |             | `z.void()`                                                | `{settings}`                  |
 | `app_settings_update_action_spec`          | true         | `'account'` | `{open_signup}`                                           | `{ok, settings}`              |
 
-Mutating admin specs declare `rate_limit: 'account'` — keyed on the
-admin's `request_context.actor.id`. The dispatcher's per-action hook
-(shared by HTTP RPC + WS) records every invocation regardless of
-outcome so successful probes (e.g. `invite_create`'s account-existence
-oracle on the `LOWER()` lookup in `query_account_by_username/_by_email`)
-consume budget. Default `DEFAULT_ACTION_ACCOUNT_RATE_LIMIT` is 1200/15min
-per actor — permissive enough for any human admin workflow, slow enough
-that scripted oracles surface in audit. Tighten downstream via
+Every admin spec declares `rate_limit: 'account'` — keyed on the
+admin's `request_context.actor.id`. Mutations cap the
+`invite_create`-style account-existence oracle (`LOWER()` lookup in
+`query_account_by_username/_by_email`); reads cap admin-side scraping
+of paginated cross-account listings (`admin_account_list`,
+`audit_log_list`, `audit_log_role_grant_history`) and unbounded
+cross-account reads (`admin_session_list`, `invite_list`). The
+dispatcher's per-action hook (shared by HTTP RPC + WS) records every
+invocation regardless of outcome so successful probes consume budget.
+Default `default_action_account_rate_limit` is 1200/15min per actor —
+permissive enough for any human admin workflow, slow enough that
+scripted oracles surface in audit. Tighten downstream via
 `AppServerOptions.action_account_rate_limiter`.
 
 `AUDIT_LOG_LIST_LIMIT_MAX = 200` — page size clamp. `ADMIN_ACCOUNT_LIST_DEFAULT_LIMIT = 50` / `ADMIN_ACCOUNT_LIST_LIMIT_MAX = 200` — same shape on `admin_account_list`.
@@ -1282,7 +1317,7 @@ self-service `account_actions.ts` surface):
 
 Closure state:
 
-- `grantable_roles` is derived once from `options.roles?.role_specs ?? BUILTIN_ROLE_SPECS_BY_NAME`
+- `grantable_roles` is derived once from `options.roles?.role_specs ?? builtin_role_specs_by_name`
   via `list_roles_with_grant_path(_, GRANT_PATH_ADMIN)` and closed over
   by the `admin_account_list` handler.
 - `options.app_settings` — when provided, captured by the
@@ -1344,15 +1379,25 @@ Every input row below also carries the shared `acting?: ActingActor`
 field that the dispatcher's authorization phase reads off the raw
 params (omitted from the table for brevity).
 
-| Spec                                   | Input                                                      | Output                                         |
-| -------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
-| `role_grant_offer_create_action_spec`  | `{to_account_id, to_actor_id?, role, scope_id?, message?}` | `{offer}`                                      |
-| `role_grant_offer_accept_action_spec`  | `{offer_id}`                                               | `{role_grant_id, offer, superseded_offer_ids}` |
-| `role_grant_offer_decline_action_spec` | `{offer_id, reason?}`                                      | `{ok}`                                         |
-| `role_grant_offer_retract_action_spec` | `{offer_id}`                                               | `{ok}`                                         |
-| `role_grant_offer_list_action_spec`    | `{account_id?}`                                            | `{offers}`                                     |
-| `role_grant_offer_history_action_spec` | `{account_id?, limit?, offset?}`                           | `{offers}`                                     |
-| `role_grant_revoke_action_spec`        | `{actor_id, role_grant_id, reason?}`                       | `{ok, revoked}`                                |
+| Spec                                   | Rate limit  | Input                                                      | Output                                         |
+| -------------------------------------- | ----------- | ---------------------------------------------------------- | ---------------------------------------------- |
+| `role_grant_offer_create_action_spec`  | `'account'` | `{to_account_id, to_actor_id?, role, scope_id?, message?}` | `{offer}`                                      |
+| `role_grant_offer_accept_action_spec`  |             | `{offer_id}`                                               | `{role_grant_id, offer, superseded_offer_ids}` |
+| `role_grant_offer_decline_action_spec` |             | `{offer_id, reason?}`                                      | `{ok}`                                         |
+| `role_grant_offer_retract_action_spec` |             | `{offer_id}`                                               | `{ok}`                                         |
+| `role_grant_offer_list_action_spec`    |             | `{account_id?}`                                            | `{offers}`                                     |
+| `role_grant_offer_history_action_spec` |             | `{account_id?, limit?, offset?}`                           | `{offers}`                                     |
+| `role_grant_revoke_action_spec`        | `'account'` | `{actor_id, role_grant_id, reason?}`                       | `{ok, revoked}`                                |
+
+`role_grant_offer_create` carries the same shape as `invite_create` —
+hostile authed callers can iterate `to_account_id` to spam offers and
+probe `ERROR_ACCOUNT_NOT_FOUND` /
+`ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH` as account-existence
+oracles, so the rate cap fires on the same threat model the admin
+`invite_create` spec addresses upstream. `role_grant_revoke` keeps its
+cap because it's an admin mutation. The accept / decline / retract /
+list / history specs are recipient-side or caller-own-data — no
+enumeration vector, no rate cap.
 
 Error reason constants (exported as `as const` literals):
 
@@ -1416,7 +1461,7 @@ Options:
 
 - `roles?: RoleSchemaResult` — drives the admin-grant-path lookup
   (`role_has_grant_path(_, role, GRANT_PATH_ADMIN)`); defaults to
-  `BUILTIN_ROLE_SPECS_BY_NAME`.
+  `builtin_role_specs_by_name`.
 - `default_ttl_ms?: number` — applied to new offers (defaults to
   `ROLE_GRANT_OFFER_DEFAULT_TTL_MS`).
 - `authorize?: RoleGrantOfferCreateAuthorize` — custom policy for
@@ -1481,6 +1526,14 @@ and `create_frontend_rpc_client({specs})` wiring. Self-service role
 specs are not included (opt-in, app-specific `eligible_roles`) —
 spread `all_self_service_role_action_specs` separately when needed.
 
+### `all_action_spec_registries.ts` — walker-only registry-of-registries
+
+`all_fuz_auth_action_spec_registries` — walker/codegen entry for every
+fuz-auth action-spec bundle (`admin`, `role_grant_offer`, `account`,
+`self_service_role`, `actor_lookup`). Not a mounting surface; protocol
+specs are excluded. Iterated by `../../test/auth/action_spec_input_invariants.test.ts`
+and `../../test/auth/all_action_spec_registries.acting_biconditional.test.ts`.
+
 ### `account_action_specs.ts` + `account_actions.ts` — seven self-service RPC actions
 
 Counterpart to `account_routes.ts`. Cookie-lifecycle flows (`login`,
@@ -1500,15 +1553,23 @@ operations are account-scoped via `query_session_revoke_for_account` /
 or token id returns `revoked: false` rather than revealing whether the id
 exists.
 
-| Spec                                     | Side effects | Input          | Output                  |
-| ---------------------------------------- | ------------ | -------------- | ----------------------- |
-| `account_verify_action_spec`             | false        | `z.void()`     | `SessionAccountJson`    |
-| `account_session_list_action_spec`       | false        | `z.void()`     | `{sessions}`            |
-| `account_session_revoke_action_spec`     | true         | `{session_id}` | `{ok, revoked}`         |
-| `account_session_revoke_all_action_spec` | true         | `z.void()`     | `{ok, count}`           |
-| `account_token_create_action_spec`       | true         | `{name?}`      | `{ok, token, id, name}` |
-| `account_token_list_action_spec`         | false        | `z.void()`     | `{tokens}`              |
-| `account_token_revoke_action_spec`       | true         | `{token_id}`   | `{ok, revoked}`         |
+| Spec                                     | Side effects | Rate limit  | Input          | Output                  |
+| ---------------------------------------- | ------------ | ----------- | -------------- | ----------------------- |
+| `account_verify_action_spec`             | false        |             | `z.void()`     | `SessionAccountJson`    |
+| `account_session_list_action_spec`       | false        |             | `z.void()`     | `{sessions}`            |
+| `account_session_revoke_action_spec`     | true         |             | `{session_id}` | `{ok, revoked}`         |
+| `account_session_revoke_all_action_spec` | true         |             | `z.void()`     | `{ok, count}`           |
+| `account_token_create_action_spec`       | true         | `'account'` | `{name?}`      | `{ok, token, id, name}` |
+| `account_token_list_action_spec`         | false        |             | `z.void()`     | `{tokens}`              |
+| `account_token_revoke_action_spec`       | true         |             | `{token_id}`   | `{ok, revoked}`         |
+
+`account_token_create` declares `rate_limit: 'account'` to bound the
+_rate_ of token churn. The outstanding-token count is already capped by
+`max_tokens` via `query_api_token_enforce_limit`, but the per-account
+burn rate is not — without this cap a caller could rotate tokens in a
+tight loop to amplify `token_create` audit churn. The other six specs
+are IDOR-guarded reads/revokes of caller-own state with no enumeration
+vector, so rate caps are symmetry-only and skipped.
 
 `session_id` validates as `Blake3Hash`; `token_id` validates as
 `ApiTokenId` (`tok_[A-Za-z0-9_-]{12}`).
@@ -1546,6 +1607,12 @@ distinguish self-toggled role_grants from admin grants/offers. The
 part of the documented surface rather than riding on `z.looseObject`
 permissiveness.
 
+Declares `rate_limit: 'account'` — every call writes a
+`role_grant_create` / `role_grant_revoke` audit row regardless of
+`changed`, so a flapping loop could inflate the log and obscure
+unrelated activity. The toggle's idempotency doesn't bound the burn
+rate; the dispatcher's per-action hook does.
+
 Method name is static — `role` lives in the input, not the method
 name. Mirrors the `role_grant_offer_create({role})` precedent. Per-role
 parameterized methods would break the `satisfies RequestResponseActionSpec`
@@ -1555,7 +1622,7 @@ codegen invariant and grow the surface linearly per role.
 
 - `eligible_roles?: ReadonlyArray<string>` — optional override
   allowlist. When omitted, eligibility is derived from
-  `roles.role_specs` (or `BUILTIN_ROLE_SPECS_BY_NAME` when `roles` is
+  `roles.role_specs` (or `builtin_role_specs_by_name` when `roles` is
   also omitted) by selecting every role whose `RoleSpec.grant_paths`
   includes `'self_service'` (`GRANT_PATH_SELF_SERVICE`). Roles outside
   the eligible set are rejected with `forbidden` + reason
@@ -1582,6 +1649,109 @@ Deps: `Pick<RouteFactoryDeps, 'log' | 'audit'>`.
 `all_self_service_role_action_specs: ReadonlyArray<RequestResponseActionSpec>` —
 codegen-ready registry of the single unified spec.
 
+### `actor_lookup_action_specs.ts` + `actor_lookup_actions.ts` — opt-in batched actor → label resolver
+
+One static `request_response` action — `actor_lookup({ids}) → {actors:
+[{id, username, display_name?}]}` — powers the labels arc for surfaces
+that stamp an actor id (bylines, owner columns, grantor labels, audit
+"by" cells). One round trip resolves a batch to display strings;
+`ACTOR_LOOKUP_IDS_MAX = 50` cap per call.
+
+**Auth + rate-limit posture.** `{account: 'required', actor: 'none'}` +
+`rate_limit: 'account'`. Account-grain — the caller need only be signed
+in; resolution skips the actor phase. The auth gate + per-account rate
+limit + per-call cap bound the batched username-enumeration surface that
+a `cell_list` ↔ `actor_lookup` pair would otherwise present. Don't loosen
+to public — a public-surface byline should resolve via SSR-stamped labels
+or per-cell embedded actor labels, not by widening this gate.
+
+**Wire shape — info-leak audit.** Deliberately omitted from
+`ActorLookupEntryJson`:
+
+- `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 — by construction this is an existence-oracle (caller
+diffs response ids against request ids), bounded by rate-limit, the
+50-id cap, actor-uuid intractability (122-bit random), and the
+hard-delete-cascade indistinguishability from never-existed (no
+tombstone oracle). Response order is unspecified — callers index by
+`id` when needed.
+
+`create_actor_lookup_actions(deps)` — `deps:
+Pick<RouteFactoryDeps, 'log'>`. Pure read; no audit, no side effects.
+Backed by `query_actors_by_ids` (see Queries §
+[`actor_lookup_queries.ts`](#actor_lookup_queriests)).
+
+Bundle is **not** included in `create_standard_rpc_actions` — consumers
+without a byline surface can skip it. Spread
+`all_actor_lookup_action_specs` alongside the standard bundle when the
+labels arc is needed.
+
+### `actor_search_action_specs.ts` + `actor_search_actions.ts` — opt-in prefix-search picker
+
+One static `request_response` action — `actor_search({query, scope_ids?, limit?}) → {actors: [{id, username, display_name?}]}` —
+powers person-target pickers. Sibling to `actor_lookup`: that resolves a
+batch of known ids to labels; this resolves a partial name to candidate
+actors. Reuses `ActorLookupEntryJson` from
+`./actor_lookup_action_specs.ts` so the labels arc on the consumer side
+stays uniform. Default limit `ACTOR_SEARCH_LIMIT_DEFAULT = 20`, hard cap
+`ACTOR_SEARCH_LIMIT_MAX = 50`. Query string capped at
+`ACTOR_SEARCH_QUERY_LENGTH_MAX = 50`.
+
+**Auth + rate-limit posture.** `{account: 'required', actor: 'none'}` +
+`rate_limit: 'account'`. Same shape as `actor_lookup`. The handler
+additionally requires the caller to be admin when `scope_ids` is empty —
+unbounded global search is the admin-only arm; non-admin callers must
+always pass at least one scope_id and get filtered to actors with active
+role_grants on those scopes. The admin check is **account-grain** (any
+actor on the caller's account holds a global `admin` role_grant) via
+`query_account_has_global_role` — the `actor: 'none'` posture means
+`auth.role_grants` is empty and the in-memory `has_scoped_role` helper
+doesn't apply.
+
+**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 (e.g. visiones' `CellGrantsEditor.svelte`) pre-filter
+`scope_ids` against their own authority (the teacher-predicate stays in
+the consumer layer, not in fuz_app). This does **not** widen the
+scope-existence oracle: an attacker passing a random scope_id never
+learns the scope existed if no member happens to match the query, and
+even on a match the result row only carries the matching actor — never
+"which scope matched".
+
+**Wire shape — additional info-leak posture beyond `actor_lookup`'s.**
+
+- Prefix match (`LOWER(name) LIKE LOWER(query) || '%' ESCAPE '\\'`),
+  **not** full `%query%`. LIKE wildcards in the user-supplied query are
+  escaped at the JS layer so a `%xyz` input can't widen to full LIKE
+  and defeat the per-call cap.
+- Empty result set on no-match — fail-soft like `cell_list`. No "no
+  actor matches" error that would leak an existence boundary on the
+  search-term axis.
+- Hard-deleted actors silently drop (same `account_id` cascade as
+  `actor_lookup`).
+
+Reason constant exported for failed-arm matching: `ERROR_ACTOR_SEARCH_SCOPE_REQUIRED`
+(`'actor_search_scope_required'`) — fired with `invalid_params` when a
+non-admin caller omits `scope_ids` or passes `[]`. Surfaced on
+`spec.error_reasons` so codegen + form-state matching can read it
+declaratively.
+
+`create_actor_search_actions(deps)` — `deps:
+Pick<RouteFactoryDeps, 'log'>`. Pure read; no audit, no side effects.
+Backed by `query_actor_search` (see Queries §`actor_search_queries.ts`).
+
+Bundle is **not** included in `create_standard_rpc_actions` — consumers
+without a person-target picker can skip it. Spread
+`all_actor_search_action_specs` alongside the standard bundle when the
+picker is needed.
+
 ## Cleanup
 
 `cleanup.ts` — periodic auth maintenance:

package/dist/auth/account_action_specs.d.ts

@@ -164,6 +164,14 @@ export declare const account_session_revoke_all_action_spec: {
     async: true;
     description: string;
 };
+/**
+ * `rate_limit: 'account'` bounds the burn rate of API-token creates. The
+ * outstanding-token count is already capped by `max_tokens` (via
+ * `query_api_token_enforce_limit`), but the per-account *rate* of churn
+ * is not — without this cap, a caller could rotate tokens in a tight
+ * loop to amplify `token_create` audit churn or attempt to provoke
+ * downstream rate-limit hot spots.
+ */
 export declare const account_token_create_action_spec: {
     method: string;
     kind: "request_response";
@@ -184,6 +192,7 @@ export declare const account_token_create_action_spec: {
     }, z.core.$strict>;
     async: true;
     description: string;
+    rate_limit: "account";
 };
 export declare const account_token_list_action_spec: {
     method: string;

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

@@ -1 +1 @@
-{"version":3,"file":"account_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_action_specs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"account_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_action_specs.ts"],"names":[],"mappings":"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"}

package/dist/auth/account_action_specs.js

@@ -112,6 +112,14 @@ export const account_session_revoke_all_action_spec = {
     async: true,
     description: 'Revoke every auth session for the current account.',
 };
+/**
+ * `rate_limit: 'account'` bounds the burn rate of API-token creates. The
+ * outstanding-token count is already capped by `max_tokens` (via
+ * `query_api_token_enforce_limit`), but the per-account *rate* of churn
+ * is not — without this cap, a caller could rotate tokens in a tight
+ * loop to amplify `token_create` audit churn or attempt to provoke
+ * downstream rate-limit hot spots.
+ */
 export const account_token_create_action_spec = {
     method: 'account_token_create',
     kind: 'request_response',
@@ -122,6 +130,7 @@ export const account_token_create_action_spec = {
     output: TokenCreateOutput,
     async: true,
     description: 'Create an API token for the current account. Raw token is returned once.',
+    rate_limit: 'account',
 };
 export const account_token_list_action_spec = {
     method: 'account_token_list',

package/dist/auth/actor_lookup_action_specs.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `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';
+/**
+ * Hard cap on the number of ids resolvable in one call. Bounds the
+ * batched username-enumeration surface.
+ */
+export declare const ACTOR_LOOKUP_IDS_MAX = 50;
+/** One resolved actor row. `display_name` omitted when blank. */
+export declare const ActorLookupEntryJson: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    username: z.ZodString;
+    display_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ActorLookupEntryJson = z.infer<typeof ActorLookupEntryJson>;
+export declare const ActorLookupInput: z.ZodObject<{
+    ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type ActorLookupInput = z.infer<typeof ActorLookupInput>;
+export declare const ActorLookupOutput: 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 ActorLookupOutput = z.infer<typeof ActorLookupOutput>;
+export declare const actor_lookup_action_spec: {
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, 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";
+    description: string;
+};
+/**
+ * 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 declare const all_actor_lookup_action_specs: readonly [{
+    method: string;
+    kind: "request_response";
+    initiator: "frontend";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
+    side_effects: false;
+    input: z.ZodObject<{
+        ids: z.ZodArray<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    }, 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";
+    description: string;
+}];
+//# sourceMappingURL=actor_lookup_action_specs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actor_lookup_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/actor_lookup_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAKtB;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;kBAI/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,gBAAgB;;kBAQ3B,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;;;;;;;;;;;;;;;;;;;;;;CAWA,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC"}