@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/http/start-gateway.js

@@ -0,0 +1,226 @@
+/**
+ * Gateway composition (ADR 0054 §1): the HTTP server and the instance supervisor, joined by a
+ * pluggable instance transport (the bridge supplies the IPC one). CLI wiring lives elsewhere.
+ */
+import { isLoopbackHost, resolveHttpConfig } from '@zhin.js/host-http';
+import { join } from 'node:path';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
+import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
+import { GatewayPackageService } from '../packages/service.js';
+import { createGatewayRpcDispatcher } from '../packages/rpc.js';
+import { createGatewayConsoleRpc } from './console-rpc.js';
+import { createGatewayPluginSwitchRpc } from './plugin-switch-rpc.js';
+import { startGatewayConsole } from './gateway-console.js';
+import { registerGatewayEventRoutes } from './gateway-events.js';
+import { GatewayHttpServer } from './gateway-http-server.js';
+const logger = getLogger('gateway');
+/**
+ * Reads and resolves the project's `http` config the same way the instance used to. Only the
+ * `http` block is read: plugin declarations are not validated here, so a config the instance
+ * rejects still leaves the Console reachable.
+ */
+export async function loadGatewayHttpConfig(projectRoot, environment = 'development') {
+    const file = findConfigFile(projectRoot);
+    if (!file)
+        return {};
+    const [document, layers] = await Promise.all([
+        createConfigDocument(join(projectRoot, file)).read().then((snapshot) => snapshot.document),
+        loadRuntimeEnvironmentLayers(projectRoot, environment),
+    ]);
+    return resolveHttpConfig(document, layers.environments?.[environment], projectRoot);
+}
+/**
+ * Reads the `gateway` block. An invalid value is logged and ignored (the instance rejects the
+ * config on its own); like {@link loadGatewayHttpConfig}, it never keeps the gateway down.
+ */
+export async function loadGatewaySettings(projectRoot) {
+    const file = findConfigFile(projectRoot);
+    if (!file)
+        return {};
+    let block;
+    try {
+        block = (await createConfigDocument(join(projectRoot, file)).read()).document.gateway;
+    }
+    catch {
+        return {};
+    }
+    if (block === undefined || block === null)
+        return {};
+    const readyTimeout = typeof block === 'object' && !Array.isArray(block) ? block.readyTimeout : undefined;
+    if (readyTimeout === undefined)
+        return {};
+    if (typeof readyTimeout === 'number' && Number.isInteger(readyTimeout) && readyTimeout >= 1 && readyTimeout <= 3600) {
+        return Object.freeze({ readyTimeoutMs: readyTimeout * 1000 });
+    }
+    logger.warn(formatCompact({ op: 'gateway_config_invalid', key: 'gateway.readyTimeout', hint: 'integer seconds 1-3600; using 60' }));
+    return {};
+}
+export async function startGateway(options) {
+    const http = options.http ?? await loadGatewayHttpConfig(options.projectRoot, options.environment);
+    const supervisor = options.supervisor instanceof InstanceSupervisor
+        ? options.supervisor
+        : new InstanceSupervisor(options.supervisor);
+    const transport = options.transport({ supervisor, projectRoot: options.projectRoot });
+    // `tokenRegistry` is read lazily: the server creates the default one.
+    let registry = options.tokenRegistry;
+    // gateway.readyTimeout is re-read before each start and transaction (ADR 0054 §4).
+    const readSettings = options.settings === false ? undefined : options.settings ?? (() => loadGatewaySettings(options.projectRoot));
+    let configuredReadyTimeoutMs;
+    const refreshSettings = async () => {
+        if (!readSettings)
+            return;
+        try {
+            configuredReadyTimeoutMs = (await readSettings()).readyTimeoutMs;
+        }
+        catch {
+            return; // keep the previous value
+        }
+        supervisor.setReadyTimeout(configuredReadyTimeoutMs);
+    };
+    // Automatic restarts wait in `backoff` (crash) or for the old process to stop (`restart-request`,
+    // e.g. after a config change): refresh meanwhile.
+    supervisor.on('state', (status) => { if (status.state === 'backoff')
+        void refreshSettings(); });
+    supervisor.on('restart-request', () => { void refreshSettings(); });
+    const packages = options.packages === false
+        ? undefined
+        : options.packages ?? new GatewayPackageService({
+            projectRoot: options.projectRoot,
+            instance: supervisor,
+            readyTimeoutMs: () => configuredReadyTimeoutMs ?? options.readyTimeoutMs,
+            beforeTransaction: refreshSettings,
+            hasOwner: () => registry?.initialized() ?? true,
+        });
+    let consoleStopped = false;
+    const lifecycle = {
+        start: async () => { await refreshSettings(); await supervisor.start(); consoleStopped = false; },
+        stop: async (stopOptions) => { consoleStopped = true; await supervisor.stop(stopOptions); },
+        restart: async (restartOptions) => { await refreshSettings(); await supervisor.restart(restartOptions); consoleStopped = false; },
+        status: () => supervisor.status(),
+        logs: supervisor.logs,
+    };
+    const rpc = createGatewayRpcDispatcher({
+        ...(packages ? { packages } : {}),
+        instance: lifecycle,
+    });
+    const server = new GatewayHttpServer({
+        http,
+        instance: { transport: () => transport, state: () => supervisor.state },
+        ...(options.tokenRegistry ? { tokenRegistry: options.tokenRegistry } : {}),
+        ...(options.retryAfterSeconds !== undefined ? { retryAfterSeconds: options.retryAfterSeconds } : {}),
+        ...(options.maxRequestBodyBytes !== undefined ? { maxRequestBodyBytes: options.maxRequestBodyBytes } : {}),
+        consoleRpc: createGatewayConsoleRpc(rpc),
+    });
+    registry = server.tokenRegistry;
+    // The Console's global plugin switch is a gateway transaction (stop → write → start, rollback);
+    // registered even without package management so it is never forwarded to the instance.
+    const disposePluginSwitch = server.useConsoleRpc(createGatewayPluginSwitchRpc({ projectRoot: options.projectRoot, packages }));
+    const disposeEvents = registerGatewayEventRoutes({
+        server,
+        ...(packages ? { packages } : {}),
+        instance: { onChange: (listener) => transport.onRoutes(() => listener()) },
+    });
+    let gatewayConsole;
+    try {
+        // ADR 0054 §7: Console accounts live in the gateway's own connection to the project database.
+        if (options.console !== false) {
+            gatewayConsole = await startGatewayConsole({
+                ...(options.console ?? {}),
+                server,
+                projectRoot: options.projectRoot,
+                ...(options.environment ? { environment: options.environment } : {}),
+                instance: transport,
+                restartInstance: async () => {
+                    if (supervisor.state === 'stopped')
+                        return;
+                    await refreshSettings();
+                    await supervisor.restart({ reason: 'database' });
+                },
+            });
+            await settleWithin(gatewayConsole.ready, options.databaseWaitMs ?? 10_000);
+        }
+        assertNotOpenOnNetwork(http, server.tokenRegistry);
+        // Settings for the first instance start, read before listening so it starts right away.
+        if (options.startInstance !== false)
+            await refreshSettings();
+        await server.listen();
+    }
+    catch (error) {
+        disposeEvents();
+        disposePluginSwitch();
+        await gatewayConsole?.close().catch(() => undefined);
+        await transport.dispose?.();
+        supervisor.dispose();
+        throw error;
+    }
+    transport.setAddresses?.(server.addresses);
+    const instanceStarted = options.startInstance === false
+        ? Promise.resolve()
+        : supervisor.start().catch((error) => {
+            // The Console stays reachable to show the failure and the logs.
+            logger.warn(formatCompact({
+                op: 'gateway_instance_start_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    let closeResult;
+    return Object.freeze({
+        http: server,
+        supervisor,
+        transport,
+        packages,
+        console: gatewayConsole,
+        rpc,
+        ownsInstanceLifecycle: () => consoleStopped || packages?.activeTransaction !== undefined,
+        instanceStarted,
+        close() {
+            closeResult ??= (async () => {
+                try {
+                    await supervisor.stop({ reason: 'gateway-stop' }).catch(() => undefined);
+                    await transport.dispose?.();
+                }
+                finally {
+                    disposeEvents();
+                    disposePluginSwitch();
+                    await gatewayConsole?.close().catch(() => undefined);
+                    supervisor.dispose();
+                    await server.close();
+                }
+            })();
+            return closeResult;
+        },
+    });
+}
+/** Thrown when the gateway would serve an open Host on a network address. */
+export class OpenHostOnNetworkError extends Error {
+    host;
+    code = 'ZHIN_OPEN_HOST_ON_NETWORK';
+    constructor(host) {
+        super(`http.host 为 ${host}（可从网络访问），但既没有初始化令牌（http.token），Console 也还没有所有者：`
+            + '开放模式拥有全部权限，只允许监听本机地址。请运行 zhin doctor --fix 在 .env 生成 HTTP_TOKEN 并在配置里用 '
+            + 'http.token: ${HTTP_TOKEN} 引用，或先运行 zhin console init 创建所有者；也可以把 http.host 改为 127.0.0.1。');
+        this.host = host;
+        this.name = 'OpenHostOnNetworkError';
+    }
+}
+/**
+ * An open Host (no bootstrap token, no owner yet) holds every permission and is only meant for
+ * this machine. The per-request loopback check cannot see through a same-host reverse proxy that
+ * adds no forwarding header, so a network-facing `http.host` must not start open (ADR 0049 §1).
+ */
+export function assertNotOpenOnNetwork(http, registry) {
+    if (registry.hasAnyToken() || isLoopbackHost(http.host))
+        return;
+    throw new OpenHostOnNetworkError(http.host ?? '');
+}
+/** Waits for `promise` at most `ms` (the gateway listens anyway; the work continues). */
+function settleWithin(promise, ms) {
+    let timer;
+    return Promise.race([
+        promise.then(() => undefined, () => undefined),
+        new Promise((resolve) => { timer = setTimeout(resolve, ms); timer.unref?.(); }),
+    ]).finally(() => clearTimeout(timer));
+}

package/lib/http-response.d.ts

@@ -0,0 +1,6 @@
+export declare function parseBoundedInteger(value: string | null, fallback: number, minimum: number, maximum: number): number;
+/** A complete HTML page response. */
+export declare function htmlResponse(html: string, status?: number): Response;
+/** One Server-Sent Events frame. */
+export declare function sseFrame(type: string, data: unknown, id?: string): string;
+export declare function normalizeBase(value: string): string;

package/lib/http-response.js

@@ -0,0 +1,25 @@
+export function parseBoundedInteger(value, fallback, minimum, maximum) {
+    if (value == null || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        return fallback;
+    return Math.min(maximum, Math.max(minimum, parsed));
+}
+/** A complete HTML page response. */
+export function htmlResponse(html, status = 200) {
+    return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8' } });
+}
+/** One Server-Sent Events frame. */
+export function sseFrame(type, data, id) {
+    return `${id ? `id: ${id}\n` : ''}event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+export function normalizeBase(value) {
+    if (!value.startsWith('/'))
+        return `/${value}`;
+    // Linear trim instead of /\/+$/ (polynomial backtracking on long runs of '/').
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0x2f)
+        end -= 1;
+    return value.slice(0, end) || '/api';
+}

package/lib/http.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@zhin.js/gateway/http` — HTML / SSE response helpers shared by gateway and instance routes
+ * (JSON: `jsonResponse` from `@zhin.js/host-http`). The instance imports this subpath, so it must
+ * not load the Node HTTP stack; the gateway HTTP server is `@zhin.js/gateway/server`.
+ */
+export * from './http-response.js';

package/lib/http.js

@@ -0,0 +1,6 @@
+/**
+ * `@zhin.js/gateway/http` — HTML / SSE response helpers shared by gateway and instance routes
+ * (JSON: `jsonResponse` from `@zhin.js/host-http`). The instance imports this subpath, so it must
+ * not load the Node HTTP stack; the gateway HTTP server is `@zhin.js/gateway/server`.
+ */
+export * from './http-response.js';

package/lib/iam/crypto.d.ts

@@ -0,0 +1,12 @@
+export declare const PASSWORD_MIN_LENGTH = 10;
+export declare const PASSWORD_MAX_LENGTH = 1024;
+export declare function passwordProblem(password: unknown): string | null;
+/** `scrypt$N$r$p$salt$hash` (base64url). */
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+/** Burns the same work as a real check so unknown usernames are not faster. */
+export declare function verifyAgainstDummy(password: string): Promise<false>;
+/** 32 random bytes, base64url (ADR 0049 §2). */
+export declare function generateToken(): string;
+export declare function sha256(value: string): string;
+export declare function newId(): string;

package/lib/iam/crypto.js

@@ -0,0 +1,58 @@
+import { createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+/** ADR 0049 §2: scrypt N=2^15, r=8, p=1, 32-byte salt. */
+const SCRYPT = Object.freeze({ N: 2 ** 15, r: 8, p: 1, keyLength: 32, maxmem: 64 * 1024 * 1024 });
+export const PASSWORD_MIN_LENGTH = 10;
+export const PASSWORD_MAX_LENGTH = 1024;
+export function passwordProblem(password) {
+    if (typeof password !== 'string')
+        return '密码必须是字符串';
+    if (password.length < PASSWORD_MIN_LENGTH)
+        return `密码至少 ${PASSWORD_MIN_LENGTH} 位`;
+    if (password.length > PASSWORD_MAX_LENGTH)
+        return '密码过长';
+    return null;
+}
+function derive(password, salt, params) {
+    return new Promise((resolve, reject) => {
+        scrypt(password.normalize('NFKC'), salt, params.keyLength, {
+            N: params.N, r: params.r, p: params.p, maxmem: SCRYPT.maxmem,
+        }, (error, key) => (error ? reject(error) : resolve(key)));
+    });
+}
+/** `scrypt$N$r$p$salt$hash` (base64url). */
+export async function hashPassword(password) {
+    const salt = randomBytes(32);
+    const key = await derive(password, salt, SCRYPT);
+    return ['scrypt', SCRYPT.N, SCRYPT.r, SCRYPT.p, salt.toString('base64url'), key.toString('base64url')].join('$');
+}
+export async function verifyPassword(password, encoded) {
+    const parts = encoded.split('$');
+    if (parts.length !== 6 || parts[0] !== 'scrypt')
+        return false;
+    const [N, r, p] = parts.slice(1, 4).map(Number);
+    if (![N, r, p].every(value => Number.isSafeInteger(value) && value > 0) || N > 2 ** 20)
+        return false;
+    const salt = Buffer.from(parts[4], 'base64url');
+    const expected = Buffer.from(parts[5], 'base64url');
+    if (salt.length < 16 || expected.length < 16)
+        return false;
+    const actual = await derive(password, salt, { N: N, r: r, p: p, keyLength: expected.length });
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+let dummyHash;
+/** Burns the same work as a real check so unknown usernames are not faster. */
+export async function verifyAgainstDummy(password) {
+    dummyHash ??= hashPassword('dummy-password-for-timing');
+    await verifyPassword(password, await dummyHash);
+    return false;
+}
+/** 32 random bytes, base64url (ADR 0049 §2). */
+export function generateToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+export function newId() {
+    return randomBytes(16).toString('hex');
+}

package/lib/iam/index.d.ts

@@ -0,0 +1,8 @@
+export { installConsoleIam, projectEnvironment, type ConsoleIamInstallation, type InstallConsoleIamOptions } from './install.js';
+export { accountInputProblem, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
+export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { dispatchIamRpc, isIamRpc } from './rpc.js';
+export { registerConsoleAuthRoutes } from './routes.js';
+export { LoginRateLimiter } from './rate-limit.js';
+export { createLocalConsoleAdmin, type LocalConsoleAdmin, type LocalConsoleAdminOptions, type LocalConsoleAdminResult } from './local-admin.js';

package/lib/iam/index.js

@@ -0,0 +1,8 @@
+export { installConsoleIam, projectEnvironment } from './install.js';
+export { accountInputProblem, ConsoleIamService, IamError, } from './service.js';
+export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { dispatchIamRpc, isIamRpc } from './rpc.js';
+export { registerConsoleAuthRoutes } from './routes.js';
+export { LoginRateLimiter } from './rate-limit.js';
+export { createLocalConsoleAdmin } from './local-admin.js';

package/lib/iam/install.d.ts

@@ -0,0 +1,36 @@
+import type { HttpHost } from '@zhin.js/host-http';
+import { ConsoleIamService, type IamDatabase } from './service.js';
+import { ConsoleSetupService, type SetupConfigPort } from './setup-service.js';
+import { type IamTableHost } from './tables.js';
+export interface InstallConsoleIamOptions {
+    /** Process database; tables are defined here, so call before it starts. */
+    readonly database: IamDatabase & IamTableHost;
+    /** Config file writer (ConsoleConfigurationStore). */
+    readonly configStore: SetupConfigPort;
+    readonly projectRoot: string;
+    readonly apiBase?: string;
+    readonly logger?: Readonly<{
+        warn(message: string): void;
+    }>;
+    /** Process restart after the setup wizard changed the database. */
+    readonly requestRestart?: () => void;
+    /** `${…}` lookup for setup validation (defaults to process env + project `.env`). */
+    readonly environment?: () => Promise<Readonly<Record<string, string | undefined>>>;
+}
+export interface ConsoleIamInstallation {
+    readonly service: ConsoleIamService;
+    readonly setup: ConsoleSetupService;
+    /** Whether this database dialect can hold accounts. */
+    readonly supported: boolean;
+    /** Call once the database has started (idempotent). */
+    activate(): Promise<void>;
+    dispose(): void;
+}
+/**
+ * The single wiring point of Console access control (ADR 0049) into a Host process:
+ * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
+ * Depends only on host-http, the database port and config/env file IO.
+ */
+export declare function installConsoleIam(http: HttpHost, options: InstallConsoleIamOptions): ConsoleIamInstallation;
+/** process env overlaid with the project `.env` (what `${…}` in config resolves against). */
+export declare function projectEnvironment(projectRoot: string): Promise<Readonly<Record<string, string | undefined>>>;

package/lib/iam/install.js

@@ -0,0 +1,74 @@
+import { join } from 'node:path';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { normalizeBase } from '../http-response.js';
+import { registerConsoleAuthRoutes } from './routes.js';
+import { ConsoleIamService } from './service.js';
+import { ConsoleSetupService } from './setup-service.js';
+import { defineConsoleIamTables } from './tables.js';
+/**
+ * The single wiring point of Console access control (ADR 0049) into a Host process:
+ * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
+ * Depends only on host-http, the database port and config/env file IO.
+ */
+export function installConsoleIam(http, options) {
+    const supported = defineConsoleIamTables(options.database);
+    const service = new ConsoleIamService({
+        database: options.database,
+        projectRoot: options.projectRoot,
+        onError: error => options.logger?.warn(`console iam: ${error instanceof Error ? error.message : String(error)}`),
+        // Installed on the token registry by the runtime composition root; empty until then.
+        pluginPermissions: () => http.tokenRegistry.pluginPermissions(),
+    });
+    const setup = new ConsoleSetupService({
+        projectRoot: options.projectRoot,
+        config: options.configStore,
+        envFile: {
+            read: () => readEnvFile(options.projectRoot, '.env'),
+            write: content => writeEnvFile(options.projectRoot, '.env', content),
+        },
+        iam: () => (supported ? service : undefined),
+        environment: options.environment ?? (() => projectEnvironment(options.projectRoot)),
+    });
+    const disposers = [];
+    if (supported)
+        disposers.push(http.tokenRegistry.useAccessProvider(service));
+    else
+        options.logger?.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
+    disposers.push(...registerConsoleAuthRoutes({
+        http,
+        base: normalizeBase(options.apiBase ?? '/api'),
+        iam: () => (supported ? service : undefined),
+        setup,
+        ...(options.requestRestart ? { requestRestart: options.requestRestart } : {}),
+    }));
+    let activation;
+    return Object.freeze({
+        service,
+        setup,
+        supported,
+        activate() {
+            if (!supported)
+                return Promise.resolve();
+            activation ??= service.start();
+            return activation;
+        },
+        dispose() {
+            service.stop();
+            for (const dispose of disposers.reverse())
+                dispose();
+        },
+    });
+}
+/** process env overlaid with the project `.env` (what `${…}` in config resolves against). */
+export async function projectEnvironment(projectRoot) {
+    const { parse } = await import('dotenv');
+    const values = { ...process.env };
+    for (const file of ['.env', `.env.${process.env.NODE_ENV === 'production' ? 'production' : 'development'}`]) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            Object.assign(values, parse(await readFile(join(projectRoot, file), 'utf8')));
+        }
+        catch { /* missing layers are fine */ }
+    }
+    return values;
+}

package/lib/iam/local-admin.d.ts

@@ -0,0 +1,27 @@
+import { type LocalGatewayError } from '../local/protocol.js';
+import { type ConsoleIamService } from './service.js';
+import type { ConsoleSetupService } from './setup-service.js';
+export type LocalConsoleAdminResult = Readonly<{
+    ok: true;
+    data: unknown;
+}> | Readonly<{
+    ok: false;
+    error: LocalGatewayError;
+}>;
+export interface LocalConsoleAdmin {
+    owns(type: string): boolean;
+    handle(type: string, data: unknown): Promise<LocalConsoleAdminResult>;
+}
+export interface LocalConsoleAdminOptions {
+    readonly setup: ConsoleSetupService;
+    readonly iam: () => ConsoleIamService | undefined;
+    /**
+     * After the setup database was written: reconnect the gateway to it (awaited, so the next
+     * request already uses it) and restart the instance (not awaited). Returns whether the instance
+     * is being restarted.
+     */
+    readonly switchDatabase: () => Promise<{
+        restarting: boolean;
+    }>;
+}
+export declare function createLocalConsoleAdmin(options: LocalConsoleAdminOptions): LocalConsoleAdmin;

package/lib/iam/local-admin.js

@@ -0,0 +1,102 @@
+/**
+ * Socket-only Console administration (`gateway.console.*`, principal `'local'`): what
+ * `zhin console init` / `zhin console user …` do when a gateway runs (ADR 0049 §7, ADR 0053 §5).
+ * The gateway's own {@link ConsoleSetupService} and {@link ConsoleIamService} answer, so the CLI
+ * and the web wizard share one flow, a database switch is applied by the gateway itself and the
+ * owner state changes at once. Never reachable over HTTP (the local socket's owner check is the
+ * authentication).
+ */
+import { DATABASE_BUSY_RETRY_AFTER_SECONDS, isDatabaseBusyError } from '../database/project-database.js';
+import { LOCAL_GATEWAY_RPC } from '../local/protocol.js';
+import { IamError } from './service.js';
+const TYPES = new Set([
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_STATUS,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DRIVERS,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE_TEST,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_OWNER,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_LIST,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_CREATE,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_PASSWD,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_DISABLE,
+]);
+const ACTOR = 'local';
+export function createLocalConsoleAdmin(options) {
+    const { setup } = options;
+    const requireIam = () => {
+        const iam = options.iam();
+        if (!iam?.ready)
+            throw new IamError('unavailable', '当前数据库不能存储 Console 用户，或尚未就绪；请先运行 zhin console init 选择 sqlite/mysql/pg/mongodb');
+        return iam;
+    };
+    const requireUser = async (iam, username) => {
+        const user = typeof username === 'string' ? await iam.findUser(username) : null;
+        if (!user)
+            throw new IamError('not_found', `用户不存在：${typeof username === 'string' ? username : ''}`);
+        return user;
+    };
+    const audit = (action, target) => {
+        options.iam()?.audit({ actor: ACTOR, action, ...(target ? { target } : {}), outcome: 'ok' });
+    };
+    async function run(type, input) {
+        switch (type) {
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_STATUS: return setup.status();
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DRIVERS: return setup.drivers();
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE_TEST:
+                return setup.testDatabase({ dialect: input.dialect, connection: input.connection });
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE: {
+                const applied = await setup.applyDatabase({ dialect: input.dialect, connection: input.connection });
+                const { restarting } = await options.switchDatabase();
+                audit('auth.setup.database');
+                return { notice: applied.notice, switched: true, restarting };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_OWNER: {
+                const { user } = await setup.createOwner({ username: input.username, password: input.password, displayName: input.displayName });
+                audit('auth.setup', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_LIST: return { users: await requireIam().listUsers() };
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_CREATE: {
+                const role = typeof input.role === 'string' && input.role ? input.role : 'viewer';
+                const user = await requireIam().createUser({
+                    username: input.username, password: input.password, displayName: input.displayName,
+                    bindings: [{ role, scopeKind: 'global' }],
+                });
+                audit('iam.users.create', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_PASSWD: {
+                const iam = requireIam();
+                const user = await requireUser(iam, input.username);
+                await iam.resetPassword(user.id, input.password);
+                audit('iam.users.resetPassword', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_DISABLE: {
+                const iam = requireIam();
+                const user = await requireUser(iam, input.username);
+                const updated = await iam.setDisabled(user.id, input.disabled !== false);
+                audit(updated.disabled ? 'iam.users.disable' : 'iam.users.enable', `user:${user.id}`);
+                return { user: updated };
+            }
+            default: throw new IamError('invalid_input', `Unknown RPC type: ${type}`);
+        }
+    }
+    return Object.freeze({
+        owns: (type) => TYPES.has(type),
+        async handle(type, data) {
+            const input = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+            try {
+                return { ok: true, data: await run(type, input) };
+            }
+            catch (error) {
+                if (error instanceof IamError)
+                    return { ok: false, error: { code: error.code, message: error.message, status: error.status } };
+                if (isDatabaseBusyError(error)) {
+                    return { ok: false, error: { code: 'database_busy', message: `数据库正忙，请 ${DATABASE_BUSY_RETRY_AFTER_SECONDS} 秒后重试`, status: 503 } };
+                }
+                return { ok: false, error: { code: 'internal', message: error instanceof Error ? error.message : String(error), status: 500 } };
+            }
+        },
+    });
+}

package/lib/iam/rate-limit.d.ts

@@ -0,0 +1,15 @@
+/** Login throttling: 5 failures / 15 minutes per IP and per username, then exponential lockout. */
+export interface LoginRateLimitOptions {
+    readonly maxFailures?: number;
+    readonly windowMs?: number;
+    readonly maxLockMs?: number;
+    readonly now?: () => number;
+}
+export declare class LoginRateLimiter {
+    #private;
+    constructor(options?: LoginRateLimitOptions);
+    /** Milliseconds until any of `keys` may try again; 0 when allowed. */
+    retryAfter(keys: readonly string[]): number;
+    fail(keys: readonly string[]): void;
+    succeed(keys: readonly string[]): void;
+}