@fuzdev/fuz_app 0.30.0 → 0.32.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/admin_rpc_actions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Combined admin + permit-offer RPC actions for fuz_app consumers.
+ *
+ * Consumers that want the stock fuz_app admin surface spread into their
+ * JSON-RPC endpoint import this helper instead of hand-wiring
+ * `create_admin_actions` + `create_permit_offer_actions`. The shared `roles`
+ * schema flows to both factories; `app_settings` goes to admin only;
+ * `default_ttl_ms` and `authorize` go to permit-offer only;
+ * `notification_sender` reaches permit-offer transparently (admin ignores it).
+ *
+ * Paired with `create_admin_rpc_adapters` on the UI side — same "admin RPC
+ * surface" concept expressed on each wire endpoint.
+ *
+ * @module
+ */
+import { type AdminActionOptions } from './admin_actions.js';
+import { type PermitOfferActionDeps, type PermitOfferActionOptions } from './permit_offer_actions.js';
+import type { RpcAction } from '../actions/action_rpc.js';
+/**
+ * Options for `create_admin_rpc_actions`.
+ *
+ * Composes `AdminActionOptions` (`roles`, `app_settings`) with
+ * `PermitOfferActionOptions` (`roles`, `default_ttl_ms`, `authorize`). `roles`
+ * is shared between both factories — the caller supplies it once and the
+ * helper threads the same reference to both.
+ */
+export interface AdminRpcActionsOptions extends AdminActionOptions, PermitOfferActionOptions {
+}
+/**
+ * Dependencies for `create_admin_rpc_actions`.
+ *
+ * Same shape as `PermitOfferActionDeps` — `log`, `on_audit_event`, and an
+ * optional `notification_sender` for permit-offer WS fan-out. The admin
+ * factory only reads `log` + `on_audit_event`; the extra field is harmless.
+ */
+export type AdminRpcActionsDeps = PermitOfferActionDeps;
+/**
+ * Build the combined admin + permit-offer RPC action set.
+ *
+ * Spreads `create_admin_actions(deps, {roles, app_settings})` and
+ * `create_permit_offer_actions(deps, {roles, default_ttl_ms, authorize})`.
+ * The shared `roles` option flows to both.
+ *
+ * @param deps - stateless capabilities (log, on_audit_event, optional notification_sender)
+ * @param options - role schema, optional app-settings ref, permit-offer TTL and authorize
+ * @returns RPC actions to pass as `rpc_endpoints` or spread into `create_rpc_endpoint`
+ */
+export declare const create_admin_rpc_actions: (deps: AdminRpcActionsDeps, options?: AdminRpcActionsOptions) => Array<RpcAction>;
+//# sourceMappingURL=admin_rpc_actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"admin_rpc_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/admin_rpc_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAuB,KAAK,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAEN,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB,EAAE,wBAAwB;CAAG;AAE/F;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,mBAAmB,EACzB,UAAS,sBAA2B,KAClC,KAAK,CAAC,SAAS,CAGjB,CAAC"}