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

package/lib/http/run-gateway.js

@@ -0,0 +1,268 @@
+/**
+ * The gateway process (ADR 0054 §1 / §5 / §6): `zhin start` / `zhin runtime start` / `pnpm dev`.
+ * Long-lived: the instance crashing, entering `crashed` after a restart storm, or being stopped
+ * from the Console / CLI does not end it. It ends on SIGINT / SIGTERM (both processes stop) or
+ * `gateway.shutdown` on the local control socket. Only `--once` (CI) still ends with the instance.
+ */
+import { randomBytes } from 'node:crypto';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { REMOTE_CONSOLE_ORIGIN } from '@zhin.js/host-http';
+import { GATEWAY_SOCKET_ENV } from '@zhin.js/host-http/bridge';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { instanceStatus } from '../packages/rpc.js';
+import { createLocalRpcHandler } from '../local/handler.js';
+import { LocalControlServer, LocalSocketError, probeLocalSocket } from '../local/local-socket.js';
+import { gatewayInfoFile, gatewaySocketPath, isNamedPipe } from '../local/paths.js';
+import { readGatewayInfo, removeGatewayInfo, writeGatewayInfo } from '../local/state-file.js';
+import { isNodeVersionSupported, NODE_ENGINES_HINT } from '../project/node-requirements.js';
+import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
+import { defaultInstanceLogFile, supervisedNodeArguments } from '../supervisor/run-instance.js';
+import { captureTerminalState, isForegroundProcessGroup } from '../supervisor/terminal-state.js';
+import { startGateway } from './start-gateway.js';
+/** Set on the instance when its output is echoed to an interactive terminal (TTY-style logging). */
+export const INSTANCE_INTERACTIVE_ENV = 'ZHIN_INSTANCE_INTERACTIVE';
+let cachedVersion;
+/** `@zhin.js/gateway` version. */
+export function gatewayVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        cachedVersion = typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+    }
+    catch {
+        cachedVersion = '0.0.0';
+    }
+    return cachedVersion;
+}
+/** Console link in the ADR 0053 format: `?apiBaseUrl=`, the token only after `#`. */
+export function consoleLink(origin, token) {
+    const url = `${REMOTE_CONSOLE_ORIGIN}/?apiBaseUrl=${encodeURIComponent(origin)}`;
+    return token ? `${url}#token=${encodeURIComponent(token)}` : url;
+}
+/**
+ * Whether the instance gets the gateway's stdin: a foreground gateway whose stdin is a TTY and
+ * that is the terminal's foreground job (a background job's child reading the TTY gets SIGTTIN).
+ */
+export function foregroundStdin(daemon, stdin = process.stdin, foregroundGroup = isForegroundProcessGroup) {
+    return !daemon && stdin.isTTY === true && foregroundGroup();
+}
+/**
+ * The local control endpoint of this run. Windows named pipes get a fresh random name component
+ * (Node cannot set a DACL on them; see `windowsPipeName`), so a second gateway on the project is
+ * detected through the pipe the state file records instead of a name clash.
+ */
+async function localEndpoint(root, platform = process.platform) {
+    if (platform !== 'win32')
+        return gatewaySocketPath(root, { platform });
+    const recorded = await readGatewayInfo(root);
+    if (recorded && isNamedPipe(recorded.socket) && await probeLocalSocket(recorded.socket).catch(() => 'live') === 'live') {
+        throw new LocalSocketError('in_use', `另一个网关正在使用 ${recorded.socket}`);
+    }
+    return gatewaySocketPath(root, { platform, nonce: randomBytes(8).toString('hex') });
+}
+/** Strips the `zhin runtime start` / `zhin start` prefix of the instance arguments. */
+function startArguments(args) {
+    if (args[0] === 'runtime' && args[1] === 'start')
+        return args.slice(2);
+    if (args[0] === 'start')
+        return args.slice(1);
+    return args;
+}
+/** Runs the gateway until it is shut down; resolves with the exit code for this process. */
+export async function runGateway(input) {
+    if (!isNodeVersionSupported()) {
+        throw new Error(`zhin start requires Node ${NODE_ENGINES_HINT}; found ${process.versions.node}`);
+    }
+    const entry = input.entry ?? process.argv[1];
+    if (!entry)
+        throw new Error('Cannot determine the zhin executable path');
+    const { root, options } = input;
+    const logger = getLogger('gateway');
+    const args = [...(input.args ?? process.argv.slice(2))];
+    const daemon = options.daemon;
+    const echo = input.echo ?? !daemon;
+    const interactive = echo && process.stdout.isTTY === true;
+    const logFile = options.logFile ?? defaultInstanceLogFile(root);
+    await mkdir(dirname(logFile), { recursive: true });
+    const socketPath = input.localSocket === false ? undefined : input.localSocket?.path ?? await localEndpoint(root);
+    // Keyed proof the CLI checks before it talks to the endpoint (only in the 0600 state file).
+    const handshakeKey = randomBytes(32).toString('hex');
+    const shareTerminal = foregroundStdin(daemon);
+    // The instance may leave the shared terminal raw / without echo when it exits or crashes.
+    const terminal = shareTerminal ? captureTerminalState() : undefined;
+    // gateway.readyTimeout: startGateway re-reads it before every start, restart and transaction.
+    const supervisor = new InstanceSupervisor({
+        spawn: {
+            command: process.execPath,
+            args: [...supervisedNodeArguments(), entry, ...args],
+            cwd: root,
+            env: {
+                ...process.env,
+                // The instance keeps the Agent's file / shell tools away from the owner endpoint.
+                ...(socketPath ? { [GATEWAY_SOCKET_ENV]: socketPath } : {}),
+                ...(interactive ? { [INSTANCE_INTERACTIVE_ENV]: '1', FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}),
+            },
+        },
+        output: 'pipe',
+        // Foreground on a TTY: the instance reads the terminal (terminal adapters); never in the background.
+        input: shareTerminal ? 'inherit' : 'ignore',
+        logs: { ...input.logs, file: logFile },
+        // The gateway outlives the instance (ADR 0054 §5); `--once` is a single check run.
+        restart: { onCrash: !options.once, onRequest: !options.once, ...input.restart },
+    });
+    if (echo) {
+        supervisor.on('log', (line) => {
+            (line.stream === 'stderr' ? process.stderr : process.stdout).write(`${line.line}\n`);
+        });
+    }
+    supervisor.on('state', (status) => {
+        if (terminal && (status.state === 'stopped' || status.state === 'crashed' || status.state === 'backoff'))
+            terminal.restore();
+        logger.info(formatCompact({ op: 'instance_state', state: status.state, ...(status.pid ? { pid: status.pid } : {}) }));
+    });
+    supervisor.on('failure', (failure) => {
+        logger.warn(formatCompact({ op: 'instance_failure', reason: failure.reason, message: failure.message }));
+    });
+    supervisor.on('restart-request', (request) => {
+        logger.info(formatCompact({ op: 'instance_restart_request', reason: request.reason }));
+    });
+    const control = socketPath
+        ? await LocalControlServer.open({
+            path: socketPath,
+            handshakeKey,
+            // No other gateway serves the project: a state file left by a dead one is stale.
+            beforeListen: () => rm(gatewayInfoFile(root), { force: true }),
+            ...(input.localSocket && input.localSocket.uid ? { uid: input.localSocket.uid } : {}),
+        }).catch((error) => { supervisor.dispose(); throw error; })
+        : undefined;
+    let gateway;
+    try {
+        gateway = await startGateway({
+            projectRoot: root,
+            environment: options.environment,
+            ...(input.http ? { http: input.http } : {}),
+            supervisor,
+            transport: () => supervisor.transport,
+        });
+    }
+    catch (error) {
+        await control?.close();
+        supervisor.dispose();
+        throw error;
+    }
+    let resolveEnd;
+    const ended = new Promise((resolve) => { resolveEnd = resolve; });
+    let ending = false;
+    const shutdown = (exitCode = 0) => {
+        if (ending)
+            return;
+        ending = true;
+        logger.info(formatCompact({ op: 'gateway_stop' }));
+        resolveEnd(exitCode);
+    };
+    const addresses = gateway.http.addresses;
+    const info = Object.freeze({
+        pid: process.pid,
+        ports: Object.freeze(addresses.map((address) => address.port)),
+        origins: Object.freeze(addresses.map((address) => address.origin)),
+        socket: socketPath ?? '',
+        startedAt: Date.now(),
+        version: gatewayVersion(),
+        mode: daemon ? 'daemon' : 'foreground',
+        args: Object.freeze([...startArguments(args)]),
+        logFile,
+    });
+    const infoResult = () => Object.freeze({
+        gateway: info,
+        instance: instanceStatus(supervisor.status()),
+        consoleInitialized: gateway.http.tokenRegistry.initialized(),
+    });
+    control?.setHandler(createLocalRpcHandler({
+        dispatch: gateway.rpc,
+        ...(gateway.packages ? { packages: gateway.packages } : {}),
+        ...(gateway.console ? { console: gateway.console.localAdmin } : {}),
+        info: infoResult,
+        shutdown: () => shutdown(0),
+        http: (request) => gateway.http.localRequest(request),
+    }));
+    const pidFile = join(root, '.zhin.pid');
+    try {
+        writeFileSync(pidFile, String(process.pid));
+    }
+    catch { /* informational */ }
+    if (socketPath) {
+        await writeGatewayInfo(root, { ...info, handshakeKey }).catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_info_write_failed', error: error instanceof Error ? error.message : String(error) }));
+        });
+    }
+    const origin = info.origins[0];
+    logger.info(formatCompact({
+        op: 'gateway_listening', pid: process.pid, ...(origin ? { http: origin } : {}),
+        ...(socketPath ? { socket: socketPath } : {}), log: logFile,
+    }));
+    if (origin && !options.once)
+        logger.info(`Console: ${consoleLink(origin)}`);
+    let interrupted = 0;
+    const onSignal = (signal) => {
+        interrupted += 1;
+        // A second signal kills the instance without waiting for its graceful stop.
+        if (interrupted > 1)
+            void supervisor.stop({ reason: 'signal', force: true });
+        shutdown(signal === 'SIGINT' ? 130 : 0);
+    };
+    const onSighup = () => { if (!daemon)
+        onSignal('SIGHUP'); };
+    const onExit = () => {
+        supervisor.dispose();
+        terminal?.restore();
+        removePidFile();
+    };
+    const removePidFile = () => {
+        try {
+            if (readFileSync(pidFile, 'utf8').trim() === String(process.pid))
+                rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+    };
+    const signals = input.signals !== false;
+    if (signals) {
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        process.on('SIGHUP', onSighup);
+    }
+    process.on('exit', onExit);
+    // `--once`: the run ends with the instance's single generation (CI check).
+    if (options.once) {
+        const check = (status = supervisor.status()) => {
+            if ((status.state === 'stopped' || status.state === 'crashed') && !gateway.ownsInstanceLifecycle()) {
+                shutdown(status.state === 'crashed' ? status.lastExitCode || 1 : status.lastExitCode ?? 0);
+            }
+        };
+        void gateway.instanceStarted.then(() => {
+            supervisor.on('state', check);
+            check();
+        });
+    }
+    input.onReady?.({ gateway, info, shutdown });
+    try {
+        return await ended;
+    }
+    finally {
+        await gateway.close().catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_close_failed', error: error instanceof Error ? error.message : String(error) }));
+        });
+        await control?.close().catch(() => undefined);
+        if (socketPath)
+            await removeGatewayInfo(root).catch(() => undefined);
+        if (signals) {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            process.off('SIGHUP', onSighup);
+        }
+        process.off('exit', onExit);
+        removePidFile();
+    }
+}

package/lib/http/start-gateway.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 { type ResolvedHttpConfig, type TokenRegistry } from '@zhin.js/host-http';
+import type { InstanceTransport } from '@zhin.js/host-http/bridge';
+import { InstanceSupervisor, type InstanceSupervisorOptions } from '../supervisor/instance-supervisor.js';
+import { GatewayPackageService } from '../packages/service.js';
+import { type GatewayRpcDispatcher } from '../packages/rpc.js';
+import { type GatewayConsole, type GatewayConsoleInstancePort, type GatewayConsoleOptions } from './gateway-console.js';
+import { GatewayHttpServer } from './gateway-http-server.js';
+/**
+ * A transport the gateway owns; `dispose` runs on gateway close. The Console module also uses the
+ * optional {@link GatewayConsoleInstancePort} methods (plugin catalog, instance audit,
+ * `principal-revoked`) when the transport has them (`IpcInstanceTransport` does).
+ */
+export interface GatewayInstanceTransport extends InstanceTransport, GatewayConsoleInstancePort {
+    dispose?(): void | Promise<void>;
+    /** Told the bound listener addresses after listen (the instance's `HttpHost.address`). */
+    setAddresses?(addresses: readonly import('@zhin.js/host-http').HttpHostAddress[]): void;
+}
+export interface InstanceTransportFactoryContext {
+    readonly supervisor: InstanceSupervisor;
+    readonly projectRoot: string;
+}
+export type InstanceTransportFactory = (context: InstanceTransportFactoryContext) => GatewayInstanceTransport;
+export interface StartGatewayOptions {
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `http.*` placeholders. Default `development`. */
+    readonly environment?: string;
+    /** Overrides the `http` block of the project config. */
+    readonly http?: ResolvedHttpConfig;
+    /** Instance supervision; pass a supervisor to own its construction. */
+    readonly supervisor: InstanceSupervisorOptions | InstanceSupervisor;
+    readonly transport: InstanceTransportFactory;
+    /** Console authentication registry (the Console module installs its access provider on it). */
+    readonly tokenRegistry?: TokenRegistry;
+    /**
+     * Console access control in the gateway (project database, `/auth/*`, `iam.*`, setup,
+     * onboarding, terminal, audit). Default on; `false` leaves only the bootstrap token (tests).
+     */
+    readonly console?: false | Omit<GatewayConsoleOptions, 'server' | 'projectRoot' | 'environment' | 'instance' | 'restartInstance'>;
+    /** Longest wait for the project database before listening anyway (default 10 s). */
+    readonly databaseWaitMs?: number;
+    readonly retryAfterSeconds?: number;
+    readonly maxRequestBodyBytes?: number;
+    /** Start the instance after the server listens. Default true; a failed start keeps the gateway up. */
+    readonly startInstance?: boolean;
+    /**
+     * Dependency transactions (`gateway.packages.*`). Default: a {@link GatewayPackageService} on
+     * the project root over the supervisor; `false` disables the package RPC.
+     */
+    readonly packages?: GatewayPackageService | false;
+    /**
+     * `gateway.readyTimeout` for dependency transactions when the project sets none (see
+     * {@link loadGatewaySettings}). Default 60 s.
+     */
+    readonly readyTimeoutMs?: number;
+    /**
+     * Reads the project's `gateway` block. Called before every instance start / restart (Console,
+     * CLI, automatic restart after a crash) and every dependency transaction, so a changed
+     * `gateway.readyTimeout` applies without restarting the gateway. Default
+     * {@link loadGatewaySettings} on the project root; `false` reads nothing.
+     */
+    readonly settings?: false | (() => Promise<GatewaySettings>);
+}
+export interface RunningGateway {
+    readonly http: GatewayHttpServer;
+    readonly supervisor: InstanceSupervisor;
+    readonly transport: GatewayInstanceTransport;
+    readonly packages: GatewayPackageService | undefined;
+    /** Console access control; undefined with `console: false`. */
+    readonly console: GatewayConsole | undefined;
+    /** The gateway RPC (`gateway.packages.*`, `gateway.instance.*`), shared with the local socket. */
+    readonly rpc: GatewayRpcDispatcher;
+    /**
+     * True while the gateway owns the instance's lifecycle: a dependency transaction runs, or the
+     * Console stopped the instance (a run must not end because of it).
+     */
+    ownsInstanceLifecycle(): boolean;
+    /** Resolves when the first instance start attempt settled (never rejects). */
+    readonly instanceStarted: Promise<void>;
+    /** Stops the instance, then closes the listeners. */
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function loadGatewayHttpConfig(projectRoot: string, environment?: string): Promise<ResolvedHttpConfig>;
+/** The project's `gateway` block (ADR 0054 §4 / §5). */
+export interface GatewaySettings {
+    /** `gateway.readyTimeout` (seconds) in ms; undefined: the built-in 60 s. */
+    readonly readyTimeoutMs?: number;
+}
+/**
+ * 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 declare function loadGatewaySettings(projectRoot: string): Promise<GatewaySettings>;
+export declare function startGateway(options: StartGatewayOptions): Promise<RunningGateway>;
+/** Thrown when the gateway would serve an open Host on a network address. */
+export declare class OpenHostOnNetworkError extends Error {
+    readonly host: string;
+    readonly code = "ZHIN_OPEN_HOST_ON_NETWORK";
+    constructor(host: string);
+}
+/**
+ * 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 declare function assertNotOpenOnNetwork(http: ResolvedHttpConfig, registry: TokenRegistry): void;

package/lib/http/start-gateway.js

@@ -0,0 +1,220 @@
+/**
+ * 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 { 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;
+    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();
+        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();
+                    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;