@fuzdev/fuz_app 0.29.0 → 0.31.0

package/dist/auth/admin_action_specs.js

@@ -0,0 +1,287 @@
+/**
+ * Admin RPC action specs — declarative contract for admin-only operations.
+ *
+ * Import this module for the specs, Input/Output schemas, and the
+ * `all_admin_action_specs` registry. Handlers live in `./admin_actions.js`.
+ *
+ * Authorization is declared at the spec level (`auth: {role: ROLE_ADMIN}`)
+ * so the RPC dispatcher enforces admin before the handler runs and the
+ * generated surface accurately reports the requirement.
+ *
+ * The registry always includes `app_settings_get` / `app_settings_update` —
+ * the runtime factory only wires their handlers when
+ * `AdminActionOptions.app_settings` is provided; dispatch falls back to
+ * `method_not_found` when absent.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { ROLE_ADMIN, RoleName } from './role_schema.js';
+import { AdminAccountEntryJson, Email, Username } from './account_schema.js';
+import { AdminSessionJson, AuditEventType, AuditLogEventWithUsernamesJson, AuditOutcome, PermitHistoryEventJson, } from './audit_log_schema.js';
+import { InviteJson, InviteWithUsernamesJson } from './invite_schema.js';
+import { AppSettingsWithUsernameJson } from './app_settings_schema.js';
+import { AUDIT_LOG_DEFAULT_LIMIT } from './audit_log_queries.js';
+import { Uuid } from '../uuid.js';
+/** Max audit-log page size. Mirrors the former REST route's clamp. */
+export const AUDIT_LOG_LIST_LIMIT_MAX = 200;
+// -- Input/output schemas ---------------------------------------------------
+/** Input for `admin_account_list`. No parameters — the caller is the subject. */
+export const AdminAccountListInput = z.null();
+/** Output for `admin_account_list`. */
+export const AdminAccountListOutput = z.strictObject({
+    accounts: z.array(AdminAccountEntryJson),
+    grantable_roles: z.array(RoleName),
+});
+/** Input for `admin_session_list`. No parameters — reads every active session. */
+export const AdminSessionListInput = z.null();
+/** Output for `admin_session_list`. Cross-account listing; fan-out already scoped by role auth. */
+export const AdminSessionListOutput = z.strictObject({
+    sessions: z.array(AdminSessionJson),
+});
+/** Input for `admin_session_revoke_all`. */
+export const AdminSessionRevokeAllInput = z.strictObject({
+    account_id: Uuid.meta({ description: 'Account whose sessions to revoke.' }),
+});
+/** Output for `admin_session_revoke_all`. */
+export const AdminSessionRevokeAllOutput = z.strictObject({
+    ok: z.literal(true),
+    count: z.number(),
+});
+/** Input for `admin_token_revoke_all`. */
+export const AdminTokenRevokeAllInput = z.strictObject({
+    account_id: Uuid.meta({ description: 'Account whose API tokens to revoke.' }),
+});
+/** Output for `admin_token_revoke_all`. */
+export const AdminTokenRevokeAllOutput = z.strictObject({
+    ok: z.literal(true),
+    count: z.number(),
+});
+/**
+ * Input for `audit_log_list`. All filter fields are optional — omit for the
+ * default newest-first page. `since_seq` exists for SSE reconnection gap
+ * fill (caller supplies the highest seq seen; server returns everything
+ * after).
+ */
+export const AuditLogListInput = z.strictObject({
+    event_type: AuditEventType.nullish().meta({ description: 'Filter by event type.' }),
+    outcome: AuditOutcome.nullish().meta({
+        description: 'Filter by outcome (`success` or `failure`).',
+    }),
+    account_id: Uuid.nullish().meta({ description: 'Filter by actor account id.' }),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(AUDIT_LOG_LIST_LIMIT_MAX)
+        .nullish()
+        .meta({
+        description: `Max rows to return (default ${AUDIT_LOG_DEFAULT_LIMIT}, max ${AUDIT_LOG_LIST_LIMIT_MAX}).`,
+    }),
+    offset: z.number().int().min(0).nullish().meta({ description: 'Pagination offset.' }),
+    since_seq: z.number().int().min(0).nullish().meta({
+        description: 'Gap-fill from this seq forward. Used for SSE reconnection.',
+    }),
+});
+/** Output for `audit_log_list`. */
+export const AuditLogListOutput = z.strictObject({
+    events: z.array(AuditLogEventWithUsernamesJson),
+});
+/** Input for `audit_log_permit_history`. */
+export const AuditLogPermitHistoryInput = z.strictObject({
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(AUDIT_LOG_LIST_LIMIT_MAX)
+        .nullish()
+        .meta({
+        description: `Max rows to return (default ${AUDIT_LOG_DEFAULT_LIMIT}, max ${AUDIT_LOG_LIST_LIMIT_MAX}).`,
+    }),
+    offset: z.number().int().min(0).nullish().meta({ description: 'Pagination offset.' }),
+});
+/** Output for `audit_log_permit_history`. */
+export const AuditLogPermitHistoryOutput = z.strictObject({
+    events: z.array(PermitHistoryEventJson),
+});
+/** Input for `invite_create`. At least one of `email` / `username` must be provided. */
+export const InviteCreateInput = z.strictObject({
+    email: Email.nullish().meta({ description: 'Invitee email.' }),
+    username: Username.nullish().meta({ description: 'Invitee username.' }),
+});
+/** Output for `invite_create`. */
+export const InviteCreateOutput = z.strictObject({
+    ok: z.literal(true),
+    invite: InviteJson,
+});
+/** Input for `invite_list`. */
+export const InviteListInput = z.null();
+/** Output for `invite_list`. Uses the enriched row including creator/claimer usernames. */
+export const InviteListOutput = z.strictObject({
+    invites: z.array(InviteWithUsernamesJson),
+});
+/** Input for `invite_delete`. */
+export const InviteDeleteInput = z.strictObject({
+    invite_id: Uuid.meta({ description: 'Invite to delete. Must be unclaimed.' }),
+});
+/** Output for `invite_delete`. */
+export const InviteDeleteOutput = z.strictObject({
+    ok: z.literal(true),
+});
+/** Input for `app_settings_get`. No parameters. */
+export const AppSettingsGetInput = z.null();
+/** Output for `app_settings_get`. */
+export const AppSettingsGetOutput = z.strictObject({
+    settings: AppSettingsWithUsernameJson,
+});
+/** Input for `app_settings_update`. */
+export const AppSettingsUpdateInput = z.strictObject({
+    open_signup: z.boolean().meta({ description: 'New value for the open signup toggle.' }),
+});
+/** Output for `app_settings_update`. */
+export const AppSettingsUpdateOutput = z.strictObject({
+    ok: z.literal(true),
+    settings: AppSettingsWithUsernameJson,
+});
+// -- Action specs -----------------------------------------------------------
+export const admin_account_list_action_spec = {
+    method: 'admin_account_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: AdminAccountListInput,
+    output: AdminAccountListOutput,
+    async: true,
+    description: 'List all accounts with their actors, permits, and pending offers. Admin-only.',
+};
+export const admin_session_list_action_spec = {
+    method: 'admin_session_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: AdminSessionListInput,
+    output: AdminSessionListOutput,
+    async: true,
+    description: 'List every active auth session across all accounts. Admin-only.',
+};
+export const admin_session_revoke_all_action_spec = {
+    method: 'admin_session_revoke_all',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: true,
+    input: AdminSessionRevokeAllInput,
+    output: AdminSessionRevokeAllOutput,
+    async: true,
+    description: 'Revoke all sessions for an account. Admin-only.',
+};
+export const admin_token_revoke_all_action_spec = {
+    method: 'admin_token_revoke_all',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: true,
+    input: AdminTokenRevokeAllInput,
+    output: AdminTokenRevokeAllOutput,
+    async: true,
+    description: 'Revoke all API tokens for an account. Admin-only.',
+};
+export const audit_log_list_action_spec = {
+    method: 'audit_log_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: AuditLogListInput,
+    output: AuditLogListOutput,
+    async: true,
+    description: 'List audit log events with optional filters. Admin-only.',
+};
+export const audit_log_permit_history_action_spec = {
+    method: 'audit_log_permit_history',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: AuditLogPermitHistoryInput,
+    output: AuditLogPermitHistoryOutput,
+    async: true,
+    description: 'List permit grant and revoke events with usernames. Admin-only.',
+};
+export const invite_create_action_spec = {
+    method: 'invite_create',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: true,
+    input: InviteCreateInput,
+    output: InviteCreateOutput,
+    async: true,
+    description: 'Create an invite addressed to an email, username, or both. Admin-only.',
+};
+export const invite_list_action_spec = {
+    method: 'invite_list',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: InviteListInput,
+    output: InviteListOutput,
+    async: true,
+    description: 'List all invites with creator and claimer usernames. Admin-only.',
+};
+export const invite_delete_action_spec = {
+    method: 'invite_delete',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: true,
+    input: InviteDeleteInput,
+    output: InviteDeleteOutput,
+    async: true,
+    description: 'Delete an unclaimed invite. Admin-only.',
+};
+export const app_settings_get_action_spec = {
+    method: 'app_settings_get',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: false,
+    input: AppSettingsGetInput,
+    output: AppSettingsGetOutput,
+    async: true,
+    description: 'Read global app settings. Admin-only.',
+};
+export const app_settings_update_action_spec = {
+    method: 'app_settings_update',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { role: ROLE_ADMIN },
+    side_effects: true,
+    input: AppSettingsUpdateInput,
+    output: AppSettingsUpdateOutput,
+    async: true,
+    description: 'Update global app settings (currently just the open signup toggle). Admin-only.',
+};
+/**
+ * All admin action specs — a codegen-ready registry. Consumers spread this
+ * into their own action-spec array to include admin methods in a typed
+ * client surface. Always includes the two app-settings specs; the runtime
+ * factory only wires their handlers when `AdminActionOptions.app_settings`
+ * is provided.
+ */
+export const all_admin_action_specs = [
+    admin_account_list_action_spec,
+    admin_session_list_action_spec,
+    admin_session_revoke_all_action_spec,
+    admin_token_revoke_all_action_spec,
+    audit_log_list_action_spec,
+    audit_log_permit_history_action_spec,
+    invite_create_action_spec,
+    invite_list_action_spec,
+    invite_delete_action_spec,
+    app_settings_get_action_spec,
+    app_settings_update_action_spec,
+];

package/dist/auth/admin_actions.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Admin RPC action handlers — admin-only operations exposed on the JSON-RPC surface.
+ *
+ * Four action categories:
+ *
+ * - Account management: `admin_account_list`, `admin_session_list`,
+ *   `admin_session_revoke_all`, `admin_token_revoke_all`.
+ * - Audit log reads: `audit_log_list`, `audit_log_permit_history`.
+ * - Invite CRUD: `invite_create`, `invite_list`, `invite_delete`.
+ * - App settings: `app_settings_get`, `app_settings_update` (registered only
+ *   when `AdminActionOptions.app_settings` is provided — the mutable ref is
+ *   owned by the server context and shared with signup middleware).
+ *
+ * The action specs themselves live in `./admin_action_specs.js`. Mutations
+ * emit matching audit events via `audit_log_fire_and_forget`.
+ *
+ * Authorization is declared at the spec level (`auth: {role: 'admin'}`) so
+ * the RPC dispatcher enforces it before the handler runs and the generated
+ * surface accurately reports the requirement. `permit_revoke` in
+ * `permit_offer_actions.ts` uses the same spec-level pattern even though its
+ * sibling methods are authenticated-but-not-admin — the dispatcher checks
+ * auth per-spec, so mixed-auth endpoints compose cleanly. Handler-level
+ * gates are reserved for input-dependent elevation (e.g.
+ * `permit_offer_list`/`_history` elevate to admin only when the caller
+ * passes an `account_id` other than their own — an input-dependent check
+ * the spec can't express).
+ *
+ * @module
+ */
+import { type RpcAction } from '../actions/action_rpc.js';
+import { type RoleSchemaResult } from './role_schema.js';
+import { type AppSettings } from './app_settings_schema.js';
+import type { RouteFactoryDeps } from './deps.js';
+/** Options for `create_admin_actions`. */
+export interface AdminActionOptions {
+    /**
+     * Role schema result from `create_role_schema()`. Defaults to builtin
+     * roles only. Used to derive `grantable_roles` (the `web_grantable`
+     * subset) returned by `admin_account_list`.
+     */
+    roles?: RoleSchemaResult;
+    /**
+     * Mutable in-memory app settings ref — typically `ctx.app_settings` from
+     * `AppServerContext`. When provided, the factory wires the
+     * `app_settings_get` and `app_settings_update` handlers; the update
+     * handler mutates this ref so signup middleware reads the new value
+     * without a DB round trip. When omitted, those two methods have no
+     * handler and RPC dispatch returns `method_not_found`.
+     */
+    app_settings?: AppSettings;
+}
+/**
+ * Dependencies for `create_admin_actions`.
+ *
+ * Shares shape with `PermitOfferActionDeps` so consumers can pass the same
+ * deps to both factories. `log` drives RPC-internal error logging;
+ * `on_audit_event` is wired by the two revoke-all mutations so SSE fan-out
+ * mirrors the former REST-route behavior.
+ */
+export type AdminActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event'>;
+/**
+ * Create the admin-only RPC actions.
+ *
+ * @param deps - stateless capabilities (log, on_audit_event)
+ * @param options - role schema for `grantable_roles` derivation
+ * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ */
+export declare const create_admin_actions: (deps: AdminActionDeps, options?: AdminActionOptions) => Array<RpcAction>;
+//# sourceMappingURL=admin_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"admin_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAuB,KAAK,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAuB7E,OAAO,EAAC,KAAK,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAK1D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AA8ChD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,gBAAgB,CAAC,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,eAAe,EACrB,UAAS,kBAAuB,KAC9B,KAAK,CAAC,SAAS,CA2SjB,CAAC"}

package/dist/auth/admin_actions.js

@@ -0,0 +1,256 @@
+/**
+ * Admin RPC action handlers — admin-only operations exposed on the JSON-RPC surface.
+ *
+ * Four action categories:
+ *
+ * - Account management: `admin_account_list`, `admin_session_list`,
+ *   `admin_session_revoke_all`, `admin_token_revoke_all`.
+ * - Audit log reads: `audit_log_list`, `audit_log_permit_history`.
+ * - Invite CRUD: `invite_create`, `invite_list`, `invite_delete`.
+ * - App settings: `app_settings_get`, `app_settings_update` (registered only
+ *   when `AdminActionOptions.app_settings` is provided — the mutable ref is
+ *   owned by the server context and shared with signup middleware).
+ *
+ * The action specs themselves live in `./admin_action_specs.js`. Mutations
+ * emit matching audit events via `audit_log_fire_and_forget`.
+ *
+ * Authorization is declared at the spec level (`auth: {role: 'admin'}`) so
+ * the RPC dispatcher enforces it before the handler runs and the generated
+ * surface accurately reports the requirement. `permit_revoke` in
+ * `permit_offer_actions.ts` uses the same spec-level pattern even though its
+ * sibling methods are authenticated-but-not-admin — the dispatcher checks
+ * auth per-spec, so mixed-auth endpoints compose cleanly. Handler-level
+ * gates are reserved for input-dependent elevation (e.g.
+ * `permit_offer_list`/`_history` elevate to admin only when the caller
+ * passes an `account_id` other than their own — an input-dependent check
+ * the spec can't express).
+ *
+ * @module
+ */
+import { rpc_action } from '../actions/action_rpc.js';
+import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
+import { BUILTIN_ROLE_OPTIONS } from './role_schema.js';
+import { query_account_by_email, query_account_by_id, query_account_by_username, query_admin_account_list, } from './account_queries.js';
+import { query_session_list_all_active, query_session_revoke_all_for_account, } from './session_queries.js';
+import { query_revoke_all_api_tokens_for_account } from './api_token_queries.js';
+import { AUDIT_LOG_DEFAULT_LIMIT, audit_log_fire_and_forget, query_audit_log_list_permit_history, query_audit_log_list_with_usernames, } from './audit_log_queries.js';
+import { query_create_invite, query_invite_delete_unclaimed, query_invite_list_all_with_usernames, } from './invite_queries.js';
+import {} from './app_settings_schema.js';
+import { query_app_settings_load_with_username, query_app_settings_update, } from './app_settings_queries.js';
+import { is_pg_unique_violation } from '../db/pg_error.js';
+import { ERROR_ACCOUNT_NOT_FOUND, ERROR_INVITE_ACCOUNT_EXISTS_EMAIL, ERROR_INVITE_ACCOUNT_EXISTS_USERNAME, ERROR_INVITE_DUPLICATE, ERROR_INVITE_MISSING_IDENTIFIER, ERROR_INVITE_NOT_FOUND, } from '../http/error_schemas.js';
+import { admin_account_list_action_spec, admin_session_list_action_spec, admin_session_revoke_all_action_spec, admin_token_revoke_all_action_spec, audit_log_list_action_spec, audit_log_permit_history_action_spec, invite_create_action_spec, invite_list_action_spec, invite_delete_action_spec, app_settings_get_action_spec, app_settings_update_action_spec, } from './admin_action_specs.js';
+/**
+ * Create the admin-only RPC actions.
+ *
+ * @param deps - stateless capabilities (log, on_audit_event)
+ * @param options - role schema for `grantable_roles` derivation
+ * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ */
+export const create_admin_actions = (deps, options = {}) => {
+    const { log, on_audit_event } = deps;
+    const role_options = options.roles?.role_options ?? BUILTIN_ROLE_OPTIONS;
+    const grantable_roles = [];
+    for (const [name, rc] of role_options) {
+        if (rc.web_grantable)
+            grantable_roles.push(name);
+    }
+    const account_list_handler = async (_input, ctx) => {
+        const accounts = await query_admin_account_list(ctx);
+        return { accounts, grantable_roles };
+    };
+    const session_list_handler = async (_input, ctx) => {
+        const sessions = await query_session_list_all_active(ctx);
+        return { sessions };
+    };
+    const session_revoke_all_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const account = await query_account_by_id(ctx, input.account_id);
+        if (!account) {
+            void audit_log_fire_and_forget(ctx, {
+                event_type: 'session_revoke_all',
+                outcome: 'failure',
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                // `target_account_id` is null: the FK to `account` would reject
+                // a probe for a non-existent id. The probed value is preserved
+                // under `metadata.attempted_account_id` for forensics.
+                target_account_id: null,
+                ip: ctx.client_ip,
+                metadata: {
+                    reason: ERROR_ACCOUNT_NOT_FOUND,
+                    attempted_account_id: input.account_id,
+                },
+            }, log, on_audit_event);
+            throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
+        }
+        const count = await query_session_revoke_all_for_account(ctx, input.account_id);
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'session_revoke_all',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            target_account_id: input.account_id,
+            ip: ctx.client_ip,
+            metadata: { count },
+        }, log, on_audit_event);
+        return { ok: true, count };
+    };
+    const token_revoke_all_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const account = await query_account_by_id(ctx, input.account_id);
+        if (!account) {
+            void audit_log_fire_and_forget(ctx, {
+                event_type: 'token_revoke_all',
+                outcome: 'failure',
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                // See `session_revoke_all_handler` — FK forces null here; the
+                // probed id lives under `metadata.attempted_account_id`.
+                target_account_id: null,
+                ip: ctx.client_ip,
+                metadata: {
+                    reason: ERROR_ACCOUNT_NOT_FOUND,
+                    attempted_account_id: input.account_id,
+                },
+            }, log, on_audit_event);
+            throw jsonrpc_errors.not_found('account', { reason: ERROR_ACCOUNT_NOT_FOUND });
+        }
+        const count = await query_revoke_all_api_tokens_for_account(ctx, input.account_id);
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'token_revoke_all',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            target_account_id: input.account_id,
+            ip: ctx.client_ip,
+            metadata: { count },
+        }, log, on_audit_event);
+        return { ok: true, count };
+    };
+    const audit_log_list_handler = async (input, ctx) => {
+        const events = await query_audit_log_list_with_usernames(ctx, {
+            event_type: input.event_type ?? undefined,
+            outcome: input.outcome ?? undefined,
+            account_id: input.account_id ?? undefined,
+            limit: input.limit ?? AUDIT_LOG_DEFAULT_LIMIT,
+            offset: input.offset ?? 0,
+            since_seq: input.since_seq ?? undefined,
+        });
+        return { events };
+    };
+    const audit_log_permit_history_handler = async (input, ctx) => {
+        const events = await query_audit_log_list_permit_history(ctx, input.limit ?? AUDIT_LOG_DEFAULT_LIMIT, input.offset ?? 0);
+        return { events };
+    };
+    const invite_create_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const email = input.email ?? null;
+        const username = input.username ?? null;
+        if (!email && !username) {
+            throw jsonrpc_errors.invalid_params('invite must specify email or username', {
+                reason: ERROR_INVITE_MISSING_IDENTIFIER,
+            });
+        }
+        if (username) {
+            const existing = await query_account_by_username(ctx, username);
+            if (existing) {
+                throw jsonrpc_errors.conflict('an account already exists with that username', {
+                    reason: ERROR_INVITE_ACCOUNT_EXISTS_USERNAME,
+                });
+            }
+        }
+        if (email) {
+            const existing = await query_account_by_email(ctx, email);
+            if (existing) {
+                throw jsonrpc_errors.conflict('an account already exists with that email', {
+                    reason: ERROR_INVITE_ACCOUNT_EXISTS_EMAIL,
+                });
+            }
+        }
+        let invite;
+        try {
+            invite = await query_create_invite(ctx, {
+                email,
+                username,
+                created_by: auth.actor.id,
+            });
+        }
+        catch (err) {
+            if (is_pg_unique_violation(err)) {
+                throw jsonrpc_errors.conflict('an unclaimed invite already exists', {
+                    reason: ERROR_INVITE_DUPLICATE,
+                });
+            }
+            throw err;
+        }
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'invite_create',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: { invite_id: invite.id, email, username },
+        }, log, on_audit_event);
+        return { ok: true, invite };
+    };
+    const invite_list_handler = async (_input, ctx) => {
+        const invites = await query_invite_list_all_with_usernames(ctx);
+        return { invites };
+    };
+    const invite_delete_handler = async (input, ctx) => {
+        const auth = ctx.auth;
+        const deleted = await query_invite_delete_unclaimed(ctx, input.invite_id);
+        if (!deleted) {
+            throw jsonrpc_errors.not_found('invite', { reason: ERROR_INVITE_NOT_FOUND });
+        }
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'invite_delete',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: { invite_id: input.invite_id },
+        }, log, on_audit_event);
+        return { ok: true };
+    };
+    const actions = [
+        rpc_action(admin_account_list_action_spec, account_list_handler),
+        rpc_action(admin_session_list_action_spec, session_list_handler),
+        rpc_action(admin_session_revoke_all_action_spec, session_revoke_all_handler),
+        rpc_action(admin_token_revoke_all_action_spec, token_revoke_all_handler),
+        rpc_action(audit_log_list_action_spec, audit_log_list_handler),
+        rpc_action(audit_log_permit_history_action_spec, audit_log_permit_history_handler),
+        rpc_action(invite_create_action_spec, invite_create_handler),
+        rpc_action(invite_list_action_spec, invite_list_handler),
+        rpc_action(invite_delete_action_spec, invite_delete_handler),
+    ];
+    const { app_settings } = options;
+    if (app_settings) {
+        const app_settings_get_handler = async (_input, ctx) => {
+            const settings = await query_app_settings_load_with_username(ctx);
+            return { settings };
+        };
+        const app_settings_update_handler = async (input, ctx) => {
+            const auth = ctx.auth;
+            const old_value = app_settings.open_signup;
+            const updated = await query_app_settings_update(ctx, input.open_signup, auth.actor.id);
+            // Mutate the in-memory ref so signup middleware reads the new value
+            // without a DB round trip.
+            app_settings.open_signup = updated.open_signup;
+            app_settings.updated_at = updated.updated_at;
+            app_settings.updated_by = updated.updated_by;
+            void audit_log_fire_and_forget(ctx, {
+                event_type: 'app_settings_update',
+                actor_id: auth.actor.id,
+                account_id: auth.account.id,
+                ip: ctx.client_ip,
+                metadata: {
+                    setting: 'open_signup',
+                    old_value,
+                    new_value: input.open_signup,
+                },
+            }, log, on_audit_event);
+            const settings = await query_app_settings_load_with_username(ctx);
+            return { ok: true, settings };
+        };
+        actions.push(rpc_action(app_settings_get_action_spec, app_settings_get_handler), rpc_action(app_settings_update_action_spec, app_settings_update_handler));
+    }
+    return actions;
+};

package/dist/auth/api_token.d.ts

@@ -8,8 +8,18 @@
  *
  * @module
  */
+import { z } from 'zod';
 /** Prefix for all fuz API tokens (enables secret scanning). */
 export declare const API_TOKEN_PREFIX = "secret_fuz_token_";
+/**
+ * Regex for the public API token id (e.g. `tok_abC0_d-3xyzA`). Twelve
+ * base64url characters after the `tok_` prefix. Matches the format produced
+ * by `generate_api_token`.
+ */
+export declare const API_TOKEN_ID_REGEX: RegExp;
+/** Zod schema for the public API token id. */
+export declare const ApiTokenId: z.ZodString;
+export type ApiTokenId = z.infer<typeof ApiTokenId>;
 /**
  * Hash an API token for storage using blake3.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"api_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA4B,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAMnF,CAAC"}
+{"version":3,"file":"api_token.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/api_token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAKtB,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAA4B,CAAC;AAE5D,8CAA8C;AAC9C,eAAO,MAAM,UAAU,aAAuC,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA4B,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAMnF,CAAC"}

package/dist/auth/api_token.js

@@ -8,10 +8,19 @@
  *
  * @module
  */
+import { z } from 'zod';
 import { hash_blake3 } from '@fuzdev/fuz_util/hash_blake3.js';
 import { generate_random_base64url } from '../crypto.js';
 /** Prefix for all fuz API tokens (enables secret scanning). */
 export const API_TOKEN_PREFIX = 'secret_fuz_token_';
+/**
+ * Regex for the public API token id (e.g. `tok_abC0_d-3xyzA`). Twelve
+ * base64url characters after the `tok_` prefix. Matches the format produced
+ * by `generate_api_token`.
+ */
+export const API_TOKEN_ID_REGEX = /^tok_[A-Za-z0-9_-]{12}$/;
+/** Zod schema for the public API token id. */
+export const ApiTokenId = z.string().regex(API_TOKEN_ID_REGEX);
 /**
  * Hash an API token for storage using blake3.
  *

package/dist/auth/api_token_queries.d.ts

@@ -66,9 +66,9 @@ export declare const query_api_token_list_for_account: (deps: QueryDeps, account
  * Enforce a per-account token limit by evicting the oldest tokens.
  *
  * Race safety: this function must run inside a transaction alongside the
- * INSERT that created the new token. The caller (`POST /tokens/create`)
- * uses the default `transaction: true` (framework-managed transaction
- * wrapping in `apply_route_specs`), ensuring the INSERT + enforce_limit
+ * INSERT that created the new token. The caller (the `account_token_create`
+ * RPC handler) runs under the dispatcher's transaction path because the
+ * spec declares `side_effects: true`, ensuring the INSERT + enforce_limit
  * pair is atomic — concurrent token creation cannot interleave.
  *
  * @param deps - query dependencies (must be transaction-scoped)