@fuzdev/fuz_app 0.65.0 → 0.66.0

package/dist/auth/CLAUDE.md

@@ -16,13 +16,11 @@ documents the cross-cutting invariants that don't fit on any single symbol.
 
 ## AppDeps split
 
-| Bucket            | Type               | Lifetime                                                                                                            |
-| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| **Capabilities**  | `AppDeps`          | Stateless, injectable per env: `stat`, `read_text_file`, `delete_file`, `keyring`, `password`, `db`, `log`, `audit` |
-| **Route caps**    | `RouteFactoryDeps` | `Omit<AppDeps, 'db'>` — handlers get `db` via `RouteContext`                                                        |
-| **Action caps**   | inline             | Action factories take `Pick<RouteFactoryDeps, 'log' \| 'audit'>` (role-grant-offer adds `notification_sender?`)     |
-| **Parameters**    | `*Options`         | Static startup values, per-factory                                                                                  |
-| **Runtime state** | inline ref         | Mutable values: `bootstrap_status`, `app_settings` ref, `DaemonTokenState` — NOT in deps or options                 |
+- **Capabilities** — `AppDeps` — stateless, injectable per env: `stat`, `read_text_file`, `delete_file`, `keyring`, `password`, `db`, `log`, `audit`.
+- **Route caps** — `RouteFactoryDeps` — `Omit<AppDeps, 'db'>`; handlers get `db` via `RouteContext`.
+- **Action caps** — inline — action factories take `Pick<RouteFactoryDeps, 'log' | 'audit'>` (role-grant-offer adds `notification_sender?`).
+- **Parameters** — `*Options` — static startup values, per-factory.
+- **Runtime state** — inline ref — mutable values: `bootstrap_status`, `app_settings` ref, `DaemonTokenState`. NOT in deps or options.
 
 `audit: AuditEmitter` is the bound emitter built once at backend assembly by
 the consumer's `audit_factory` callback over `create_audit_emitter`; closes
@@ -33,15 +31,13 @@ over the pool so rows persist when request transactions roll back. See root
 
 ### Crypto primitives (pure, I/O-free)
 
-| Module                      | Exports                                                                                                                                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth/keyring.ts`           | `Keyring`, `create_keyring`, `validate_keyring`, `create_validated_keyring`                                                                                     |
-| `auth/session_cookie.ts`    | `SessionOptions<T>`, `parse_session`, `process_session_cookie`, `create_session_config`, `fuz_session_config`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S` |
-| `auth/password.ts`          | `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300)                                              |
-| `auth/password_argon2.ts`   | `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`                                                                                      |
-| `auth/api_token.ts`         | `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`                                                                                |
-| `auth/daemon_token.ts`      | `DaemonToken`, `DAEMON_TOKEN_HEADER` (`X-Daemon-Token`), `generate_daemon_token`, `validate_daemon_token`, `DaemonTokenState`                                   |
-| `auth/bootstrap_account.ts` | `bootstrap_account` (one-shot, `bootstrap_lock`-protected)                                                                                                      |
+- `auth/keyring.ts` — `Keyring`, `create_keyring`, `validate_keyring`, `create_validated_keyring`.
+- `auth/session_cookie.ts` — `SessionOptions<T>`, `parse_session`, `process_session_cookie`, `create_session_config`, `fuz_session_config`, `SESSION_AGE_MAX`, `SESSION_REFRESH_THRESHOLD_S`.
+- `auth/password.ts` — `Password`, `PasswordProvided`, `PasswordHashDeps`, `PASSWORD_LENGTH_MIN` (12, OWASP), `PASSWORD_LENGTH_MAX` (300).
+- `auth/password_argon2.ts` — `hash_password`, `verify_password`, `verify_dummy`, `argon2_password_deps`.
+- `auth/api_token.ts` — `API_TOKEN_PREFIX` (`secret_fuz_token_`), `hash_api_token`, `generate_api_token`.
+- `auth/daemon_token.ts` — `DaemonToken`, `DAEMON_TOKEN_HEADER` (`X-Daemon-Token`), `generate_daemon_token`, `validate_daemon_token`, `DaemonTokenState`.
+- `auth/bootstrap_account.ts` — `bootstrap_account` (one-shot, `bootstrap_lock`-protected).
 
 Cross-cutting notes that don't live on any single symbol:
 
@@ -60,43 +56,40 @@ Cross-cutting notes that don't live on any single symbol:
 
 Convention — `*_schema.ts` is Zod-only; `*_ddl.ts` holds DDL strings.
 
-| Module                                   | What's inside                                                                                                                                                                                      |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth/account_schema.ts`                 | `Account`, `Actor`, `RoleGrant`, `AuthSession`, `ApiToken` + client-safe JSON shapes                                                                                                               |
-| `auth/role_schema.ts`                    | `RoleName`, `RoleSpec`, `ROLE_KEEPER`, `ROLE_ADMIN`, `create_role_schema`, `builtin_role_specs_by_name`, `role_has_grant_path`, `list_roles_with_grant_path`                                       |
-| `auth/scope_kind_schema.ts`              | `ScopeKindName`, `create_scope_kind_schema` (open registry, no builtins)                                                                                                                           |
-| `auth/credential_type_schema.ts`         | `CredentialTypeName`, `CREDENTIAL_TYPE_SESSION` / `_API_TOKEN` / `_DAEMON_TOKEN`, `create_credential_type_schema`                                                                                  |
-| `auth/grant_path_schema.ts`              | `GrantPathName`, `GRANT_PATH_ADMIN` / `_SELF_SERVICE` / `_SYSTEM` / `_BOOTSTRAP`, `create_grant_path_schema`                                                                                       |
-| `auth/auth_ddl.ts`                       | `CREATE TABLE` / index / seed strings for the core identity tables                                                                                                                                 |
-| `auth/audit_log_schema.ts`               | `AUDIT_EVENT_TYPES` (21 builtins), `AuditEventType` / `AuditEventTypeName`, `audit_metadata_schemas`, `AuditLogEvent`, `AuditLogInput`, `AuditLogConfig`, `create_audit_log_config`                |
-| `auth/audit_log_ddl.ts`                  | `audit_log` table DDL with `seq BIGSERIAL` for cursor-based gap fill (BIGSERIAL converges with the Rust spine; `create_db` registers a `pg.types` int8 parser so `seq` still reads as a JS number) |
-| `auth/invite_schema.ts`                  | `Invite`, `CreateInviteInput`                                                                                                                                                                      |
-| `auth/app_settings_schema.ts`            | `AppSettings`, `UpdateAppSettingsInput` (single-row via `CHECK (id = 1)`)                                                                                                                          |
-| `auth/role_grant_offer_schema.ts`        | `RoleGrantOffer`, `RoleGrantOfferJson`, `to_role_grant_offer_json`, scope-sentinel constants                                                                                                       |
-| `auth/role_grant_offer_ddl.ts`           | `role_grant_offer` table + indexes + `ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID` / `_GLOBAL_TOKEN`                                                                                                      |
-| `auth/role_grant_offer_notifications.ts` | Six WS notification specs for the consentful-grant lifecycle                                                                                                                                       |
+- `auth/account_schema.ts` — `Account`, `Actor`, `RoleGrant`, `AuthSession`, `ApiToken` + client-safe JSON shapes.
+- `auth/role_schema.ts` — `RoleName`, `RoleSpec`, `ROLE_KEEPER`, `ROLE_ADMIN`, `create_role_schema`, `builtin_role_specs_by_name`, `role_has_grant_path`, `list_roles_with_grant_path`.
+- `auth/scope_kind_schema.ts` — `ScopeKindName`, `create_scope_kind_schema` (open registry, no builtins).
+- `auth/credential_type_schema.ts` — `CredentialTypeName`, `CREDENTIAL_TYPE_SESSION` / `_API_TOKEN` / `_DAEMON_TOKEN`, `create_credential_type_schema`.
+- `auth/grant_path_schema.ts` — `GrantPathName`, `GRANT_PATH_ADMIN` / `_SELF_SERVICE` / `_SYSTEM` / `_BOOTSTRAP`, `create_grant_path_schema`.
+- `auth/auth_ddl.ts` — `CREATE TABLE` / index / seed strings for the core identity tables.
+- `auth/audit_log_schema.ts` — `AUDIT_EVENT_TYPES` (21 builtins), `AuditEventType` / `AuditEventTypeName`, `audit_metadata_schemas`, `AuditLogEvent`, `AuditLogInput`, `AuditLogConfig`, `create_audit_log_config`.
+- `auth/audit_log_ddl.ts` — `audit_log` table DDL with `seq BIGSERIAL` for cursor-based gap fill (BIGSERIAL converges with the Rust spine; `create_db` registers a `pg.types` int8 parser so `seq` still reads as a JS number).
+- `auth/invite_schema.ts` — `Invite`, `CreateInviteInput`.
+- `auth/app_settings_schema.ts` — `AppSettings`, `UpdateAppSettingsInput` (single-row via `CHECK (id = 1)`).
+- `auth/role_grant_offer_schema.ts` — `RoleGrantOffer`, `RoleGrantOfferJson`, `to_role_grant_offer_json`, scope-sentinel constants.
+- `auth/role_grant_offer_ddl.ts` — `role_grant_offer` table + indexes + `ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID` / `_GLOBAL_TOKEN`.
+- `auth/role_grant_offer_notifications.ts` — six WS notification specs for the consentful-grant lifecycle.
 
 ### Queries
 
 All take `deps: QueryDeps = {db}` first; `query_validate_api_token` adds `log`.
 
-| Module                             | Coverage                                                                                                                                                                                                                                                                 |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `auth/account_queries.ts`          | Account CRUD, actor resolution, password update with verify-write race guard, paged `query_admin_account_list`                                                                                                                                                           |
-| `auth/actor_lookup_queries.ts`     | Batched `actor` ⨝ `account` for the labels arc                                                                                                                                                                                                                           |
-| `auth/actor_search_queries.ts`     | Case-insensitive prefix search on `actor.name`, scope-filtered when not admin                                                                                                                                                                                            |
-| `auth/role_grant_queries.ts`       | Idempotent create, IDOR-guarded revoke (with in-tx supersede), scope-aware lookup, role/account predicates, `query_role_grant_revoke_for_scope` parent-scope cascade                                                                                                     |
-| `auth/role_grant_offer_queries.ts` | Offer create/decline/retract/list/history/sweep, atomic `query_accept_offer` with sibling supersede; error classes `RoleGrantOfferSelfTargetError` / `_AlreadyTerminalError` / `_ExpiredError` / `_NotFoundError` / `_ActorAccountMismatchError` / `_ActorMismatchError` |
-| `auth/session_queries.ts`          | Server-side sessions (blake3-hashed), `query_session_revoke_by_hash_unscoped` (logout only), `query_session_enforce_limit` (transaction-required)                                                                                                                        |
-| `auth/api_token_queries.ts`        | Token validation with fire-and-forget usage tracking, IDOR-guarded revoke, `query_api_token_enforce_limit` (transaction-required)                                                                                                                                        |
-| `auth/invite_queries.ts`           | Invite create/find/claim/list/delete; `query_invite_claim_unscoped` (scoping enforced upstream by `_find_unclaimed_match`)                                                                                                                                               |
-| `auth/app_settings_queries.ts`     | Load/update for the single-row settings table                                                                                                                                                                                                                            |
-| `auth/audit_log_queries.ts`        | `query_audit_log` (in-tx insert), `_list` / `_list_with_usernames` / `_list_role_grant_history` / `_cleanup_before`, drift counters (`get_audit_metadata_validation_failures` / `get_audit_unknown_event_type_failures`)                                                 |
+- `auth/account_queries.ts` — account CRUD, actor resolution, password update with verify-write race guard, paged `query_admin_account_list`.
+- `auth/actor_lookup_queries.ts` — batched `actor` ⨝ `account` for the labels arc.
+- `auth/actor_search_queries.ts` — case-insensitive prefix search on `actor.name`, scope-filtered when not admin.
+- `auth/role_grant_queries.ts` — idempotent create, IDOR-guarded revoke (with in-tx supersede), scope-aware lookup, role/account predicates, `query_role_grant_revoke_for_scope` parent-scope cascade.
+- `auth/role_grant_offer_queries.ts` — offer create/decline/retract/list/history/sweep, atomic `query_accept_offer` with sibling supersede; error classes `RoleGrantOfferSelfTargetError` / `_AlreadyTerminalError` / `_ExpiredError` / `_NotFoundError` / `_ActorAccountMismatchError` / `_ActorMismatchError`.
+- `auth/session_queries.ts` — server-side sessions (blake3-hashed), `query_session_revoke_by_hash_unscoped` (logout only), `query_session_enforce_limit` (transaction-required).
+- `auth/api_token_queries.ts` — token validation with fire-and-forget usage tracking, IDOR-guarded revoke, `query_api_token_enforce_limit` (transaction-required).
+- `auth/invite_queries.ts` — invite create/find/claim/list/delete; `query_invite_claim_unscoped` (scoping enforced upstream by `_find_unclaimed_match_for_update`, which runs inside the signup tx with `FOR UPDATE` so find + claim are atomic).
+- `auth/app_settings_queries.ts` — load/update for the single-row settings table.
+- `auth/audit_log_queries.ts` — `query_audit_log` (in-tx insert), `_list` / `_list_with_usernames` / `_list_role_grant_history` / `_cleanup_before`, drift counters (`get_audit_metadata_validation_failures` / `get_audit_unknown_event_type_failures`).
 
 `_unscoped` suffix on `query_session_revoke_by_hash_unscoped` and
 `query_invite_claim_unscoped` is the safety signal: SQL only checks row state,
 caller is responsible for scoping. Production scoping for invites is enforced
-upstream in `auth/signup_routes.ts` via `query_invite_find_unclaimed_match`.
+upstream in `auth/signup_routes.ts` via `query_invite_find_unclaimed_match_for_update`
+(SELECT … FOR UPDATE inside the signup tx — find + claim atomic on the row lock).
 
 ### Audit emitter
 
@@ -122,13 +115,11 @@ they track the same config. Sample via `get_*`; `reset_*` are test-only.
 
 ### Routes
 
-| Module                        | Surface                                                                                                                                                                                                                                                   |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth/account_routes.ts`      | `POST /login` / `/logout` / `/password`, `GET /verify` (nginx `auth_request` shim), `GET /api/account/status`. Constants: `DEFAULT_MAX_SESSIONS = 5`, `DEFAULT_MAX_TOKENS = 10`, `DEFAULT_LOGIN_FAIL_FLOOR_MS = 250`, `DEFAULT_LOGIN_FAIL_JITTER_MS = 25` |
-| `auth/bootstrap_routes.ts`    | `POST /bootstrap` + `check_bootstrap_status`; `BootstrapStatus` runtime ref                                                                                                                                                                               |
-| `auth/signup_routes.ts`       | `POST /signup` (open or invite-gated)                                                                                                                                                                                                                     |
-| `auth/audit_log_routes.ts`    | Optional `GET /audit/stream` (SSE) — list/history are on the RPC surface                                                                                                                                                                                  |
-| `auth/auth_guard_resolver.ts` | `fuz_auth_guard_resolver` injected into `apply_route_specs` so the framework stays auth-agnostic                                                                                                                                                          |
+- `auth/account_routes.ts` — `POST /login` / `/logout` / `/password`, `GET /verify` (nginx `auth_request` shim), `GET /api/account/status`. Constants: `DEFAULT_MAX_SESSIONS = 5`, `DEFAULT_MAX_TOKENS = 10`, `DEFAULT_LOGIN_FAIL_FLOOR_MS = 250`, `DEFAULT_LOGIN_FAIL_JITTER_MS = 25`.
+- `auth/bootstrap_routes.ts` — `POST /bootstrap` + `check_bootstrap_status`; `BootstrapStatus` runtime ref.
+- `auth/signup_routes.ts` — `POST /signup` (open or invite-gated).
+- `auth/audit_log_routes.ts` — optional `GET /audit/stream` (SSE); list/history are on the RPC surface.
+- `auth/auth_guard_resolver.ts` — `fuz_auth_guard_resolver` injected into `apply_route_specs` so the framework stays auth-agnostic.
 
 **`POST /login` timing floor.** Login 401s are floored to
 `DEFAULT_LOGIN_FAIL_FLOOR_MS` (250ms) + uniform jitter (±25ms) via
@@ -147,13 +138,11 @@ Everything else listed under §RPC action surfaces.
 
 ### Middleware
 
-| Module                            | Role                                                                                                                                                                                                                             |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth/middleware.ts`              | `create_auth_middleware_specs(deps, options)` — assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token`                                                                                            |
-| `auth/request_context.ts`         | `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role`), guards (`require_auth`, `require_role`, `require_credential_types`), `refresh_role_grants` |
-| `auth/session_middleware.ts`      | `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap)                                                                                                                     |
-| `auth/bearer_auth.ts`             | Soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context)                                                                                                                                        |
-| `auth/daemon_token_middleware.ts` | `start_daemon_token_rotation` + `create_daemon_token_middleware` (atomic file write, fail-closed validation, keeper account resolution)                                                                                          |
+- `auth/middleware.ts` — `create_auth_middleware_specs(deps, options)` assembles `[origin, session, request_context, bearer_auth]` + optional `daemon_token`.
+- `auth/request_context.ts` — `RequestContext`, `resolve_acting_actor`, `build_request_context`, predicates (`has_role`, `has_scoped_role`, `has_any_scoped_role`), guards (`require_auth`, `require_role`, `require_credential_types`), `refresh_role_grants`.
+- `auth/session_middleware.ts` — `process_session_cookie` integration, `create_session_and_set_cookie` (shared by login / signup / bootstrap).
+- `auth/bearer_auth.ts` — soft-fail bearer middleware; rejects when `Origin` or `Referer` present (browser context).
+- `auth/daemon_token_middleware.ts` — `start_daemon_token_rotation` + `create_daemon_token_middleware` (atomic file write, fail-closed validation, keeper account resolution).
 
 See root ../../../CLAUDE.md §Middleware Ordering for canonical assembly
 order. The auth-specific invariants are described below in §Cross-cutting
@@ -304,14 +293,12 @@ codegen-importable) and `*_actions.ts` (`create_*_actions(deps, options)`
 factory with handlers). Client codegen imports the specs and skips the
 handler module's transitive query-layer deps.
 
-| Factory                            | Registry                             | Bundle in `create_standard_rpc_actions` |
-| ---------------------------------- | ------------------------------------ | --------------------------------------- |
-| `create_admin_actions`             | `all_admin_action_specs`             | yes                                     |
-| `create_role_grant_offer_actions`  | `all_role_grant_offer_action_specs`  | yes                                     |
-| `create_account_actions`           | `all_account_action_specs`           | yes                                     |
-| `create_self_service_role_actions` | `all_self_service_role_action_specs` | no — `eligible_roles` is app-specific   |
-| `create_actor_lookup_actions`      | `all_actor_lookup_action_specs`      | no — opt-in batched id → label resolver |
-| `create_actor_search_actions`      | `all_actor_search_action_specs`      | no — opt-in prefix-search picker        |
+- `create_admin_actions` — registry `all_admin_action_specs` — bundled in `create_standard_rpc_actions`.
+- `create_role_grant_offer_actions` — registry `all_role_grant_offer_action_specs` — bundled.
+- `create_account_actions` — registry `all_account_action_specs` — bundled.
+- `create_self_service_role_actions` — registry `all_self_service_role_action_specs` — not bundled (`eligible_roles` is app-specific).
+- `create_actor_lookup_actions` — registry `all_actor_lookup_action_specs` — not bundled (opt-in batched id → label resolver).
+- `create_actor_search_actions` — registry `all_actor_search_action_specs` — not bundled (opt-in prefix-search picker).
 
 `auth/all_action_spec_registries.ts` exposes `all_fuz_auth_action_spec_registries`
 for registry-wide invariant tests. Not a mounting surface; protocol specs
@@ -353,19 +340,17 @@ are excluded.
 
 `create_admin_actions(deps, options?)` in `auth/admin_actions.ts`.
 
-| Spec                                       | Side effects | Input                                                     | Output                        |
-| ------------------------------------------ | ------------ | --------------------------------------------------------- | ----------------------------- |
-| `admin_account_list_action_spec`           | false        | `{limit?, offset?}`                                       | `{accounts, grantable_roles}` |
-| `admin_session_list_action_spec`           | false        | `z.void()`                                                | `{sessions}`                  |
-| `admin_session_revoke_all_action_spec`     | true         | `{account_id}`                                            | `{ok, count}`                 |
-| `admin_token_revoke_all_action_spec`       | true         | `{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}`                    |
-| `invite_create_action_spec`                | true         | `{email?, username?}`                                     | `{ok, invite}`                |
-| `invite_list_action_spec`                  | false        | `z.void()`                                                | `{invites}`                   |
-| `invite_delete_action_spec`                | true         | `{invite_id}`                                             | `{ok}`                        |
-| `app_settings_get_action_spec`             | false        | `z.void()`                                                | `{settings}`                  |
-| `app_settings_update_action_spec`          | true         | `{open_signup}`                                           | `{ok, settings}`              |
+- `admin_account_list_action_spec` — read; input `{limit?, offset?}`; output `{accounts, grantable_roles}`.
+- `admin_session_list_action_spec` — read; input `z.void()`; output `{sessions}`.
+- `admin_session_revoke_all_action_spec` — mutation; input `{account_id}`; output `{ok, count}`.
+- `admin_token_revoke_all_action_spec` — mutation; input `{account_id}`; output `{ok, count}`.
+- `audit_log_list_action_spec` — read; input `{event_type?, account_id?, limit?, offset?, since_seq?}`; output `{events}`.
+- `audit_log_role_grant_history_action_spec` — read; input `{limit?, offset?}`; output `{events}`.
+- `invite_create_action_spec` — mutation; input `{email?, username?}`; output `{ok, invite}`.
+- `invite_list_action_spec` — read; input `z.void()`; output `{invites}`.
+- `invite_delete_action_spec` — mutation; input `{invite_id}`; output `{ok}`.
+- `app_settings_get_action_spec` — read; input `z.void()`; output `{settings}`.
+- `app_settings_update_action_spec` — mutation; input `{open_signup}`; output `{ok, settings}`.
 
 Constants: `AUDIT_LOG_LIST_LIMIT_MAX = 200`, `ADMIN_ACCOUNT_LIST_DEFAULT_LIMIT = 50`,
 `ADMIN_ACCOUNT_LIST_LIMIT_MAX = 200`.
@@ -413,15 +398,13 @@ event additionally records `credential_type` in metadata (defense in depth).
 > suite assume auto-accept and have to redesign their tests when they
 > discover otherwise.
 
-| 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}`                                |
+- `role_grant_offer_create_action_spec` — input `{to_account_id, to_actor_id?, role, scope_id?, message?}`; output `{offer}`.
+- `role_grant_offer_accept_action_spec` — input `{offer_id}`; output `{role_grant_id, offer, superseded_offer_ids}`.
+- `role_grant_offer_decline_action_spec` — input `{offer_id, reason?}`; output `{ok}`.
+- `role_grant_offer_retract_action_spec` — input `{offer_id}`; output `{ok}`.
+- `role_grant_offer_list_action_spec` — input `{account_id?}`; output `{offers}`.
+- `role_grant_offer_history_action_spec` — input `{account_id?, limit?, offset?}`; output `{offers}`.
+- `role_grant_revoke_action_spec` — input `{actor_id, role_grant_id, reason?}`; output `{ok, revoked}`.
 
 Every input carries `acting?: ActingActor` (registry-time invariant 2).
 `role_grant_revoke` keys on **`actor_id`**, not `account_id` — role_grants
@@ -462,13 +445,11 @@ matching the middleware auth-guard precedent.
 
 Post-commit via `emit_after_commit` (see `http/CLAUDE.md` §Pending Effects):
 
-| Event   | Fan-out                                                             |
-| ------- | ------------------------------------------------------------------- |
-| Create  | `role_grant_offer_received` → recipient                             |
-| Retract | `role_grant_offer_retracted` → recipient                            |
-| Accept  | `role_grant_offer_accepted` → grantor + `_supersede` per sibling    |
-| Decline | `role_grant_offer_declined` → grantor                               |
-| Revoke  | `role_grant_revoke` → revokee + `_supersede` per superseded sibling |
+- Create — `role_grant_offer_received` → recipient.
+- Retract — `role_grant_offer_retracted` → recipient.
+- Accept — `role_grant_offer_accepted` → grantor + `_supersede` per sibling.
+- Decline — `role_grant_offer_declined` → grantor.
+- Revoke — `role_grant_revoke` → revokee + `_supersede` per superseded sibling.
 
 Spec module is `auth/role_grant_offer_notifications.ts` — six
 `RemoteNotificationActionSpec`s with Zod params schemas and notification
@@ -492,15 +473,13 @@ Options: `roles?: RoleSchemaResult` (drives admin-grant-path lookup),
 
 `create_account_actions(deps, options?)` in `auth/account_actions.ts`.
 
-| 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}`         |
+- `account_verify_action_spec` — read; input `z.void()`; output `SessionAccountJson`.
+- `account_session_list_action_spec` — read; input `z.void()`; output `{sessions}`.
+- `account_session_revoke_action_spec` — mutation; input `{session_id}`; output `{ok, revoked}`.
+- `account_session_revoke_all_action_spec` — mutation; input `z.void()`; output `{ok, count}`.
+- `account_token_create_action_spec` — mutation; input `{name?}`; output `{ok, token, id, name}`.
+- `account_token_list_action_spec` — read; input `z.void()`; output `{tokens}`.
+- `account_token_revoke_action_spec` — mutation; input `{token_id}`; output `{ok, revoked}`.
 
 `account_verify` is intentionally on both surfaces: the REST `GET /verify`
 shim is a status-only nginx probe; the RPC action returns

package/dist/auth/audit_log_schema.js

@@ -90,13 +90,13 @@ export const audit_metadata_schemas = Object.freeze({
     signup: z.looseObject({
         username: z.string().meta({ description: 'Username submitted at signup.' }),
         invite_id: Uuid.optional().meta({
-            description: 'Invite consumed by this signup. Set on success and on `race_lost` / `signup_conflict` failure rows when an invite was matched at attempt time.',
+            description: 'Invite consumed by this signup. Set on success and on `signup_conflict` failure rows when an invite was matched at attempt time.',
         }),
         open_signup: z.boolean().optional().meta({
             description: 'True when the signup occurred via the `open_signup` setting (no invite required). Set on success rows under `open_signup` and on failure rows when the attempt was made under `open_signup`.',
         }),
         reason: z.string().optional().meta({
-            description: 'Failure category: `no_match` (no unclaimed invite matched), `race_lost` (invite was claimed between find and claim), `signup_conflict` (username/email already exists). Set only on `outcome=failure`.',
+            description: 'Failure category: `no_match` (no unclaimed invite matched), `signup_conflict` (username/email already exists, raised by the DB unique constraint), `internal_error` (catch-all for non-classified tx failures — Argon2 fault, session create error, DB outage mid-tx). Set only on `outcome=failure`.',
         }),
         email: Email.optional().meta({
             description: 'Email submitted at signup — recorded on failure rows for forensic correlation. Omitted on success rows because the email is already tied to the resulting account.',

package/dist/auth/daemon_token_middleware.d.ts

@@ -34,6 +34,11 @@ export declare const get_daemon_token_path: (runtime: Pick<EnvDeps, "env_get">,
  *
  * Uses `write_file_atomic` (temp file + rename) and optionally sets mode 0600.
  *
+ * On-disk format is JSON `{"token": "..."}` — the wrapper leaves room for
+ * future fields (rotated_at, version) without changing every reader. Both
+ * the TS cross-backend harness reader (`spawn_backend.read_daemon_token`)
+ * and the Rust daemon-token writer match this shape.
+ *
  * @param runtime - runtime with file write capabilities
  * @param token_path - path to write the token
  * @param token - the raw token string
@@ -58,8 +63,14 @@ export declare const write_daemon_token: (runtime: DaemonTokenWriteDeps, token_p
 export declare const resolve_keeper_account_id: (deps: QueryDeps) => Promise<string | null>;
 /** Options for daemon token rotation. */
 export interface DaemonTokenRotationOptions {
-    /** Application name (for `~/.{name}/run/daemon_token`). */
-    app_name: string;
+    /**
+     * Absolute path the token file is written to. Caller computes from
+     * its own conventions — e.g. `get_daemon_token_path(runtime, app_name)`
+     * for the standard `~/.{name}/run/daemon_token` layout, or a path
+     * derived from `PUBLIC_<APP>_DIR` for cross-process test setups that
+     * isolate the app dir to a tmpdir.
+     */
+    token_path: string;
     /** Rotation interval in ms. Default: `30000` (30s). */
     rotation_interval_ms?: number;
 }
@@ -76,13 +87,12 @@ export interface DaemonTokenRotation {
  * Generates an initial token, writes it to disk, resolves the keeper account,
  * and sets up periodic rotation. Returns the mutable state object and a stop function.
  *
- * @param runtime - runtime with file, env, and remove capabilities
+ * @param runtime - runtime with file and remove capabilities
  * @param deps - query dependencies for resolving keeper account
  * @param options - rotation configuration
  * @param log - the logger instance
  * @returns rotation state and stop function
  * @mutates filesystem - writes the token file on each rotation; `stop` removes it
- * @throws Error if `$HOME` is not set so the daemon token path cannot be resolved
  */
 export declare const start_daemon_token_rotation: (runtime: DaemonTokenWriteDeps & FsRemoveDeps, deps: QueryDeps, options: DaemonTokenRotationOptions, log: Logger) => Promise<DaemonTokenRotation>;
 /**
@@ -105,5 +115,5 @@ export declare const start_daemon_token_rotation: (runtime: DaemonTokenWriteDeps
  * @param state - the daemon token runtime state
  * @mutates Hono context - sets `ACCOUNT_ID_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on a valid token
  */
-export declare const create_daemon_token_middleware: (state: DaemonTokenState, _deps: QueryDeps) => MiddlewareHandler;
+export declare const create_daemon_token_middleware: (state: DaemonTokenState, deps: QueryDeps) => MiddlewareHandler;
 //# sourceMappingURL=daemon_token_middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"daemon_token_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AASrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAC1D,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,GAAG;IAC3D,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,oBAAoB,EAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACX,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAEtF,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,gBAAgB,CAAC;IACxB,kGAAkG;IAClG,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,oBAAoB,GAAG,YAAY,EAC5C,MAAM,SAAS,EACf,SAAS,0BAA0B,EACnC,KAAK,MAAM,KACT,OAAO,CAAC,mBAAmB,CAwD7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,gBAAgB,EACvB,OAAO,SAAS,KACd,iBA+BF,CAAC"}
+{"version":3,"file":"daemon_token_middleware.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/daemon_token_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AASrF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAKN,KAAK,gBAAgB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAC1D,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,GAAG;IAC3D,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS,oBAAoB,EAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACX,OAAO,CAAC,IAAI,CAKd,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAEtF,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IAC1C;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,gBAAgB,CAAC;IACxB,kGAAkG;IAClG,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,GACvC,SAAS,oBAAoB,GAAG,YAAY,EAC5C,MAAM,SAAS,EACf,SAAS,0BAA0B,EACnC,KAAK,MAAM,KACT,OAAO,CAAC,mBAAmB,CAqD7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,8BAA8B,GAC1C,OAAO,gBAAgB,EACvB,MAAM,SAAS,KACb,iBAsCF,CAAC"}

package/dist/auth/daemon_token_middleware.js

@@ -35,13 +35,18 @@ export const get_daemon_token_path = (runtime, name) => {
  *
  * Uses `write_file_atomic` (temp file + rename) and optionally sets mode 0600.
  *
+ * On-disk format is JSON `{"token": "..."}` — the wrapper leaves room for
+ * future fields (rotated_at, version) without changing every reader. Both
+ * the TS cross-backend harness reader (`spawn_backend.read_daemon_token`)
+ * and the Rust daemon-token writer match this shape.
+ *
  * @param runtime - runtime with file write capabilities
  * @param token_path - path to write the token
  * @param token - the raw token string
  * @mutates filesystem - writes `token_path` atomically and `chmod 0600` when supported
  */
 export const write_daemon_token = async (runtime, token_path, token) => {
-    await write_file_atomic(runtime, token_path, token + '\n');
+    await write_file_atomic(runtime, token_path, JSON.stringify({ token }) + '\n');
     if (runtime.chmod) {
         await runtime.chmod(token_path, 0o600);
     }
@@ -70,26 +75,23 @@ export const resolve_keeper_account_id = async (deps) => {
  * Generates an initial token, writes it to disk, resolves the keeper account,
  * and sets up periodic rotation. Returns the mutable state object and a stop function.
  *
- * @param runtime - runtime with file, env, and remove capabilities
+ * @param runtime - runtime with file and remove capabilities
  * @param deps - query dependencies for resolving keeper account
  * @param options - rotation configuration
  * @param log - the logger instance
  * @returns rotation state and stop function
  * @mutates filesystem - writes the token file on each rotation; `stop` removes it
- * @throws Error if `$HOME` is not set so the daemon token path cannot be resolved
  */
 export const start_daemon_token_rotation = async (runtime, deps, options, log) => {
-    const { app_name, rotation_interval_ms = DEFAULT_ROTATION_INTERVAL_MS } = options;
-    const token_path = get_daemon_token_path(runtime, app_name);
-    if (!token_path) {
-        throw new Error('$HOME not set — cannot determine daemon token path');
-    }
-    // ensure run directory exists
-    const app_dir = get_app_dir(runtime, app_name);
-    if (app_dir) {
-        await runtime.mkdir(`${app_dir}/run`, { recursive: true });
+    const { token_path, rotation_interval_ms = DEFAULT_ROTATION_INTERVAL_MS } = options;
+    // ensure parent directory exists
+    const last_slash = token_path.lastIndexOf('/');
+    if (last_slash > 0) {
+        await runtime.mkdir(token_path.slice(0, last_slash), { recursive: true });
     }
-    // resolve keeper account (may be null pre-bootstrap)
+    // resolve keeper account (may be null pre-bootstrap; the middleware
+    // lazily refreshes on the first null hit to cover the
+    // rotation-starts-before-bootstrap case)
     const keeper_account_id = await resolve_keeper_account_id(deps);
     // generate initial token and write to disk
     const initial_token = generate_daemon_token();
@@ -150,7 +152,7 @@ export const start_daemon_token_rotation = async (runtime, deps, options, log) =
  * @param state - the daemon token runtime state
  * @mutates Hono context - sets `ACCOUNT_ID_KEY`, `CREDENTIAL_TYPE_KEY`, and `AUTH_API_TOKEN_ID_KEY` on a valid token
  */
-export const create_daemon_token_middleware = (state, _deps) => {
+export const create_daemon_token_middleware = (state, deps) => {
     return async (c, next) => {
         const token_header = c.req.header(DAEMON_TOKEN_HEADER);
         if (!token_header) {
@@ -166,7 +168,14 @@ export const create_daemon_token_middleware = (state, _deps) => {
         if (!validate_daemon_token(parse_result.data, state)) {
             return c.json({ error: ERROR_INVALID_DAEMON_TOKEN }, 401);
         }
-        // daemon token valid — resolve keeper account
+        // daemon token valid — resolve keeper account. `start_daemon_token_rotation`
+        // resolves the keeper once at startup, but rotation often starts before the
+        // keeper account exists (e.g. cross-process test harnesses spawn the binary
+        // then POST /bootstrap). Lazily refresh from the DB on the first null hit
+        // so the post-bootstrap state lands without a separate hook.
+        if (!state.keeper_account_id) {
+            state.keeper_account_id = await resolve_keeper_account_id(deps);
+        }
         if (!state.keeper_account_id) {
             return c.json({ error: ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED }, 503);
         }

package/dist/auth/invite_queries.d.ts

@@ -26,27 +26,37 @@ export declare const query_invite_find_unclaimed_by_email: (deps: QueryDeps, ema
  */
 export declare const query_invite_find_unclaimed_by_username: (deps: QueryDeps, username: string) => Promise<Invite | undefined>;
 /**
- * Find an unclaimed invite matching email and/or username using three scoping modes:
+ * Find an unclaimed invite matching email and/or username, taking a
+ * row-level write lock on the matched row.
+ *
+ * Three scoping modes:
  *
  * - **Email-only invite** (email set, username NULL) → matches only if signup provides matching email.
  * - **Username-only invite** (username set, email NULL) → matches only if signup provides matching username.
  * - **Both-field invite** (both set) → requires BOTH email and username to match.
  *
- * @param deps - query dependencies
+ * Must run inside the same transaction as `query_invite_claim_unscoped`:
+ * `FOR UPDATE` makes find + claim atomic, so a concurrent signup that
+ * matched the same invite blocks on the lock until this transaction
+ * commits/rolls back. After commit, the loser's `find_for_update`
+ * returns no row (the winner flipped `claimed_at`) and falls through to
+ * `ERROR_NO_MATCHING_INVITE` — no race window between find and claim.
+ *
+ * @param deps - query dependencies — `deps.db` MUST be a transaction
  * @param email - email to match (or null if signup provides none)
  * @param username - username to match
- * @returns the matching invite, or `undefined`
+ * @returns the matching invite (locked), or `undefined`
  */
-export declare const query_invite_find_unclaimed_match: (deps: QueryDeps, email: string | null, username: string) => Promise<Invite | undefined>;
+export declare const query_invite_find_unclaimed_match_for_update: (deps: QueryDeps, email: string | null, username: string) => Promise<Invite | undefined>;
 /**
  * Claim an invite by setting the claimed_by and claimed_at fields.
  *
  * The `_unscoped` suffix is the safety signal — the SQL only checks the
  * row state (`claimed_at IS NULL`), not whether the claiming account's
  * email or username matches the invite. Callers must scope the lookup
- * upstream via `query_invite_find_unclaimed_match`; the production caller
- * (`auth/signup_routes.ts`) does this. Skipping the find step lets a
- * caller claim any unclaimed invite by id.
+ * upstream via one of the `_find_unclaimed_match*` siblings (production
+ * uses `_for_update` to make find + claim atomic). Skipping the find
+ * step lets a caller claim any unclaimed invite by id.
  *
  * Mirrors the `query_session_revoke_by_hash_unscoped` precedent — there
  * is no scoped sibling because the scoping is provided by a separate

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

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

package/dist/auth/invite_queries.js

@@ -34,18 +34,28 @@ export const query_invite_find_unclaimed_by_username = async (deps, username) =>
     return deps.db.query_one(`SELECT * FROM invite WHERE LOWER(username) = LOWER($1) AND claimed_at IS NULL`, [username]);
 };
 /**
- * Find an unclaimed invite matching email and/or username using three scoping modes:
+ * Find an unclaimed invite matching email and/or username, taking a
+ * row-level write lock on the matched row.
+ *
+ * Three scoping modes:
  *
  * - **Email-only invite** (email set, username NULL) → matches only if signup provides matching email.
  * - **Username-only invite** (username set, email NULL) → matches only if signup provides matching username.
  * - **Both-field invite** (both set) → requires BOTH email and username to match.
  *
- * @param deps - query dependencies
+ * Must run inside the same transaction as `query_invite_claim_unscoped`:
+ * `FOR UPDATE` makes find + claim atomic, so a concurrent signup that
+ * matched the same invite blocks on the lock until this transaction
+ * commits/rolls back. After commit, the loser's `find_for_update`
+ * returns no row (the winner flipped `claimed_at`) and falls through to
+ * `ERROR_NO_MATCHING_INVITE` — no race window between find and claim.
+ *
+ * @param deps - query dependencies — `deps.db` MUST be a transaction
  * @param email - email to match (or null if signup provides none)
  * @param username - username to match
- * @returns the matching invite, or `undefined`
+ * @returns the matching invite (locked), or `undefined`
  */
-export const query_invite_find_unclaimed_match = async (deps, email, username) => {
+export const query_invite_find_unclaimed_match_for_update = async (deps, email, username) => {
     return deps.db.query_one(`SELECT * FROM invite WHERE claimed_at IS NULL AND (
 			(email IS NOT NULL AND username IS NULL
 			 AND $1::text IS NOT NULL AND LOWER(email) = LOWER($1::text))
@@ -56,7 +66,8 @@ export const query_invite_find_unclaimed_match = async (deps, email, username) =
 			(email IS NOT NULL AND username IS NOT NULL
 			 AND $1::text IS NOT NULL AND LOWER(email) = LOWER($1::text)
 			 AND LOWER(username) = LOWER($2))
-		) ORDER BY created_at ASC, id ASC LIMIT 1`, [email, username]);
+		) ORDER BY created_at ASC, id ASC LIMIT 1
+		FOR UPDATE`, [email, username]);
 };
 /**
  * Claim an invite by setting the claimed_by and claimed_at fields.
@@ -64,9 +75,9 @@ export const query_invite_find_unclaimed_match = async (deps, email, username) =
  * The `_unscoped` suffix is the safety signal — the SQL only checks the
  * row state (`claimed_at IS NULL`), not whether the claiming account's
  * email or username matches the invite. Callers must scope the lookup
- * upstream via `query_invite_find_unclaimed_match`; the production caller
- * (`auth/signup_routes.ts`) does this. Skipping the find step lets a
- * caller claim any unclaimed invite by id.
+ * upstream via one of the `_find_unclaimed_match*` siblings (production
+ * uses `_for_update` to make find + claim atomic). Skipping the find
+ * step lets a caller claim any unclaimed invite by id.
  *
  * Mirrors the `query_session_revoke_by_hash_unscoped` precedent — there
  * is no scoped sibling because the scoping is provided by a separate