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

package/lib/http/gateway-console.js

@@ -0,0 +1,309 @@
+/**
+ * Console access control in the gateway (ADR 0054 §3 / §7, ADR 0049, ADR 0053 §4): the gateway
+ * opens the project database itself, owns the `console_*` tables, authenticates sessions / API
+ * tokens / the bootstrap token locally, and serves `/auth/*`, `iam.*`, `onboarding.update`, the
+ * setup wizard, the terminal and the audit log — all without an instance.
+ *
+ * The instance contributes what only it knows over the bridge: the plugin permission catalog
+ * (`catalog`) and its own audit entries (`audit`); the gateway tells it when a user's credentials
+ * were revoked (`principal-revoked`) so it closes that user's SSE / WebSocket connections.
+ */
+import { join } from 'node:path';
+import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
+import { ONBOARDING_RPC } from '@zhin.js/console-protocol';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { ConsoleConfigurationStore } from '../config/configuration.js';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from '../database/config.js';
+import { ProjectDatabase } from '../database/project-database.js';
+import { projectEnvironment } from '../iam/install.js';
+import { createLocalConsoleAdmin } from '../iam/local-admin.js';
+import { registerConsoleAuthRoutes } from '../iam/routes.js';
+import { dispatchIamRpc, isIamRpc } from '../iam/rpc.js';
+import { ConsoleIamService } from '../iam/service.js';
+import { ConsoleSetupService } from '../iam/setup-service.js';
+import { defineConsoleIamTables } from '../iam/tables.js';
+import { OnboardingError } from '../onboarding/errors.js';
+import { OnboardingService } from '../onboarding/service.js';
+import { findConfigFile } from '../project/config-file.js';
+import { installHostConsoleTerminal } from '../terminal/host.js';
+const logger = getLogger('gateway');
+const DEFAULT_RETRY_MS = 10_000;
+/** A database that never starts: the IAM service then fails closed on its setup marker. */
+const UNAVAILABLE_DATABASE = Object.freeze({ started: false, models: Object.freeze({ get: () => undefined }) });
+export async function startGatewayConsole(options) {
+    const { server, projectRoot } = options;
+    const failClosed = () => ({
+        service: new ConsoleIamService({ database: UNAVAILABLE_DATABASE, projectRoot }),
+        supported: true,
+        dispose: [],
+    });
+    const environment = options.environment ?? 'development';
+    const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+    const registry = server.tokenRegistry;
+    const settings = await loadExpandedProjectConfig(projectRoot, environment).catch((error) => {
+        logger.warn(formatCompact({ op: 'gateway_config_read_failed', error: errorText(error) }));
+        return Object.freeze({});
+    });
+    // Until (and while re-) connecting, fail closed: the owner state comes from the setup marker.
+    let connection = failClosed();
+    let closed = false;
+    let retryTimer;
+    let opening;
+    const iam = () => (connection.supported ? connection.service : undefined);
+    const disposers = [];
+    // Level grants need the catalog of the instance's loaded plugins (kept across restarts).
+    disposers.push(registry.usePluginPermissions(() => options.instance?.pluginPermissions?.() ?? []));
+    const access = Object.freeze({
+        initialized: () => connection.service?.initialized() ?? false,
+        authenticate: async (token, meta) => (await iam()?.authenticate(token, meta)) ?? null,
+        audit: (entry) => { iam()?.audit(entry); },
+    });
+    disposers.push(registry.useAccessProvider(access));
+    const stopInstanceAudit = options.instance?.onAudit?.((entry) => { iam()?.audit(entry); });
+    if (stopInstanceAudit)
+        disposers.push(stopInstanceAudit);
+    const terminal = installHostConsoleTerminal(server, {
+        config: options.terminal !== undefined ? options.terminal : readTerminalBlock(settings),
+        projectRoot,
+        base: server.apiBase,
+        iam,
+        logger: { warn: (message) => logger.warn(message), info: (message) => logger.info(message) },
+    });
+    const revoke = (userId, reason) => {
+        terminal.terminatePrincipal(`user:${userId}`, 'revoked');
+        try {
+            options.instance?.revokePrincipal?.(userId, reason);
+        }
+        catch { /* bridge gone */ }
+    };
+    async function connect() {
+        let config;
+        try {
+            config = options.database ?? await resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
+        }
+        catch (error) {
+            logger.warn(formatCompact({ op: 'gateway_database_config_invalid', error: errorText(error) }));
+            connection = failClosed();
+            return;
+        }
+        let database;
+        try {
+            database = new ProjectDatabase(config);
+        }
+        catch (error) {
+            logger.warn(formatCompact({ op: 'gateway_database_driver_failed', dialect: config.dialect, error: errorText(error) }));
+            connection = failClosed();
+            return;
+        }
+        const supported = defineConsoleIamTables(database);
+        if (!supported) {
+            logger.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
+            connection = { database, supported: false, dispose: [] };
+            return;
+        }
+        const service = new ConsoleIamService({
+            database,
+            projectRoot,
+            onError: (error) => logger.warn(`console iam: ${errorText(error)}`),
+            pluginPermissions: () => registry.pluginPermissions(),
+        });
+        const dispose = [service.onCredentialsRevoked(({ userId, reason }) => revoke(userId, reason))];
+        connection = { database, service, supported: true, dispose };
+        try {
+            await database.start();
+            await service.start();
+            logger.info(formatCompact({ op: 'gateway_database_open', dialect: config.dialect }));
+        }
+        catch (error) {
+            // Not ready: `/auth/*` answers 503 and the owner state comes from the setup marker.
+            logger.warn(formatCompact({ op: 'gateway_database_open_failed', dialect: config.dialect, error: errorText(error) }));
+            scheduleRetry();
+        }
+    }
+    function scheduleRetry() {
+        if (closed || retryTimer)
+            return;
+        retryTimer = setTimeout(() => {
+            retryTimer = undefined;
+            if (closed)
+                return;
+            void reopen();
+        }, retryMs);
+        retryTimer.unref?.();
+    }
+    async function disconnect() {
+        const current = connection;
+        connection = failClosed();
+        for (const dispose of current.dispose.splice(0))
+            dispose();
+        current.service?.stop();
+        await current.database?.stop().catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_database_close_failed', error: errorText(error) }));
+        });
+    }
+    function reopen() {
+        opening = (opening ?? Promise.resolve()).then(async () => {
+            if (closed)
+                return;
+            clearTimeout(retryTimer);
+            retryTimer = undefined;
+            await disconnect();
+            if (!closed)
+                await connect();
+        });
+        return opening;
+    }
+    const configFile = join(projectRoot, findConfigFile(projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME);
+    const setup = new ConsoleSetupService({
+        projectRoot,
+        config: new ConsoleConfigurationStore({ projectRoot, document: createConfigDocument(configFile) }),
+        envFile: {
+            read: () => readEnvFile(projectRoot, '.env'),
+            write: (content) => writeEnvFile(projectRoot, '.env', content),
+        },
+        iam,
+        environment: () => projectEnvironment(projectRoot),
+    });
+    const onboarding = options.onboarding ?? new OnboardingService({
+        projectRoot,
+        hasOwner: () => connection.service?.initialized() ?? false,
+    });
+    const restartInstance = () => {
+        void options.restartInstance?.().catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_database_switch_failed', error: errorText(error) }));
+        });
+    };
+    const localAdmin = createLocalConsoleAdmin({
+        setup,
+        iam,
+        // ADR 0054 §7, as for the web wizard: the gateway uses the new database before it answers.
+        switchDatabase: async () => {
+            await reopen();
+            restartInstance();
+            return { restarting: options.restartInstance !== undefined };
+        },
+    });
+    disposers.push(...registerConsoleAuthRoutes({
+        http: server,
+        base: server.apiBase,
+        iam,
+        setup,
+        onboarding: () => onboarding.status(),
+        // ADR 0054 §7: close the gateway's connection, open the new database, restart the instance.
+        requestRestart: () => {
+            void reopen()
+                .then(() => options.restartInstance?.())
+                .catch((error) => logger.warn(formatCompact({ op: 'gateway_database_switch_failed', error: errorText(error) })));
+        },
+    }));
+    // `/auth/*` belongs to the gateway alone: nothing under it is forwarded to the instance.
+    disposers.push(server.route('ALL', `${server.apiBase}/auth/*`, () => jsonResponse(404, { success: false, code: 'not_found', error: 'Not found' }), { summary: 'Unknown /auth route', tags: ['auth'] }));
+    disposers.push(server.useConsoleRpc(createGatewayAccountRpc({ iam, onboarding })));
+    const ready = reopen().catch((error) => {
+        logger.warn(formatCompact({ op: 'gateway_database_open_failed', error: errorText(error) }));
+    });
+    let closeResult;
+    return Object.freeze({
+        ready,
+        iam,
+        database: () => connection.database,
+        setup,
+        onboarding,
+        terminal,
+        reopenDatabase: reopen,
+        localAdmin,
+        close() {
+            closeResult ??= (async () => {
+                closed = true;
+                clearTimeout(retryTimer);
+                terminal.close();
+                for (const dispose of disposers.splice(0).reverse()) {
+                    try {
+                        dispose();
+                    }
+                    catch { /* keep closing */ }
+                }
+                await opening?.catch(() => undefined);
+                await disconnect();
+            })();
+            return closeResult;
+        },
+    });
+}
+/** `console.terminal` of the expanded root config. */
+function readTerminalBlock(document) {
+    const block = document.console;
+    return block && typeof block === 'object' && !Array.isArray(block) ? block.terminal : undefined;
+}
+const ONBOARDING_STEPS = new Set(['ai', 'adapters', 'finish']);
+/**
+ * `iam.*` (ADR 0049 §5) and `onboarding.update` (ADR 0053 §4) on the gateway's
+ * `POST {base}/console/request`. Authorization uses the shared permission map
+ * (`CONSOLE_RPC_PERMISSIONS`); denials and writes are audited like in the instance dispatcher.
+ */
+export function createGatewayAccountRpc(options) {
+    return Object.freeze({
+        owns: (type) => isIamRpc(type) || type === ONBOARDING_RPC.UPDATE,
+        async handle(message, context, registry) {
+            const noStore = { 'cache-control': 'no-store' };
+            const requestId = message.requestId;
+            const principal = context.principal;
+            if (!principal) {
+                return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
+            }
+            const decision = authorizeConsoleRpc(principal, message);
+            const audit = (outcome) => {
+                try {
+                    registry.accessProvider?.audit?.({
+                        actor: auditActor(principal),
+                        action: `rpc:${String(message.type ?? '')}`.slice(0, 256),
+                        ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
+                        outcome,
+                        detail: rpcAuditDetail(message),
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            };
+            if (!decision.allowed) {
+                audit('denied');
+                return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
+            }
+            const result = isIamRpc(message.type)
+                ? await dispatchIamRpc(message, options.iam(), principal)
+                : await updateOnboarding(options.onboarding, message, principal);
+            if (decision.write)
+                audit(result.status < 400 && result.body.success !== false ? 'ok' : 'error');
+            else if (result.status === 403)
+                audit('denied');
+            return jsonResponse(result.status, result.body, { ...noStore, ...result.headers });
+        },
+    });
+}
+async function updateOnboarding(onboarding, message, principal) {
+    const type = String(message.type ?? '');
+    const requestId = message.requestId;
+    // The Console sends `{ type, step, status }`; `data` is accepted as well.
+    const payload = (message.data && typeof message.data === 'object' && !Array.isArray(message.data) ? message.data : message);
+    try {
+        const step = payload.step;
+        if (typeof step !== 'string' || !ONBOARDING_STEPS.has(step))
+            throw new OnboardingError('invalid_input', 'step 只能是 ai / adapters / finish');
+        const status = step === 'finish'
+            ? await onboarding.complete({ principal })
+            : await onboarding.markStep(step, payload.status, { principal });
+        return { status: 200, body: { success: true, data: status, type, requestId } };
+    }
+    catch (error) {
+        if (error instanceof OnboardingError) {
+            return { status: error.status, body: { success: false, code: error.code, error: error.message, requestId } };
+        }
+        return { status: 500, body: { success: false, code: 'failed', error: '引导状态更新失败', requestId } };
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Gateway events on the Console event stream (ADR 0054 §4): package transaction progress
+ * (`gateway.packages.progress`) must reach the Console while the instance is stopped for the
+ * transaction, so the gateway owns `GET {base}/events`:
+ *
+ * - instance ready: the instance's SSE stream is forwarded and gateway frames are spliced in
+ *   between its frames (gateway frames carry no `id:`, so the resumable cursor stays the
+ *   instance's); the stream ends with the instance's;
+ * - instance offline: a gateway-only stream, closed as soon as the instance is ready again so the
+ *   Console reconnects to the merged stream. `GET {base}/events/history` then answers an empty
+ *   page that keeps the caller's cursor.
+ *
+ * `GET {base}/gateway/packages/progress` serves the progress frames alone.
+ */
+import type { GatewayPackageEvent } from '@zhin.js/console-protocol';
+import type { GatewayHttpServer } from './gateway-http-server.js';
+export interface GatewayEventSource {
+    /** Package transaction events (`GatewayPackageService.subscribe`). */
+    subscribe(listener: (event: GatewayPackageEvent) => void): () => void;
+}
+export interface GatewayInstanceReadiness {
+    /** Called whenever the instance's route table changes (ready, reload, gone). */
+    onChange(listener: () => void): () => void;
+}
+export interface RegisterGatewayEventRoutesOptions {
+    readonly server: GatewayHttpServer;
+    readonly packages?: GatewayEventSource;
+    readonly instance?: GatewayInstanceReadiness;
+    readonly keepAliveMs?: number;
+}
+export declare function gatewayEventFrame(type: string, data: unknown): string;
+/** Registers the gateway's event routes; returns the unregister function. */
+export declare function registerGatewayEventRoutes(options: RegisterGatewayEventRoutesOptions): () => void;
+/** The text after the last complete SSE frame (empty when the buffer ends on a frame boundary). */
+export declare function trailingPartialFrame(buffer: string): string;

package/lib/http/gateway-events.js

@@ -0,0 +1,172 @@
+import { GATEWAY_PACKAGES_PROGRESS, GATEWAY_PACKAGES_PROGRESS_PATH } from '@zhin.js/console-protocol';
+import { jsonResponse } from '@zhin.js/host-http';
+const KEEPALIVE_MS = 15_000;
+/** Gateway frames held while an instance frame is half written. */
+const MAX_PENDING_FRAMES = 1_024;
+/** Chunks queued for a client that does not read; beyond it the stream ends (the client resumes). */
+const MAX_QUEUED_CHUNKS = 4_096;
+const SSE_HEADERS = Object.freeze({
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache, no-transform',
+    'x-accel-buffering': 'no',
+});
+export function gatewayEventFrame(type, data) {
+    return `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/** Registers the gateway's event routes; returns the unregister function. */
+export function registerGatewayEventRoutes(options) {
+    const { server } = options;
+    const base = server.apiBase;
+    const keepAliveMs = options.keepAliveMs ?? KEEPALIVE_MS;
+    const encoder = new TextEncoder();
+    /** A client stream fed with gateway frames (plus, when merging, the instance's). */
+    const open = (request) => {
+        let controller;
+        let finished = false;
+        const cleanups = [];
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            for (const cleanup of cleanups.splice(0)) {
+                try {
+                    cleanup();
+                }
+                catch { /* keep closing */ }
+            }
+            try {
+                controller.close();
+            }
+            catch { /* already closed */ }
+        };
+        const stream = new ReadableStream({
+            start(value) { controller = value; },
+            cancel() { finish(); },
+        });
+        const write = (text) => {
+            if (finished)
+                return;
+            try {
+                if ((controller.desiredSize ?? 1) < -MAX_QUEUED_CHUNKS) {
+                    finish();
+                    return;
+                }
+                controller.enqueue(encoder.encode(text));
+            }
+            catch {
+                finish();
+            }
+        };
+        request.signal.addEventListener('abort', finish, { once: true });
+        const timer = setInterval(() => write(': keepalive\n\n'), keepAliveMs);
+        timer.unref?.();
+        cleanups.push(() => clearInterval(timer));
+        return { stream, write, finish, cleanups, get finished() { return finished; } };
+    };
+    const subscribeProgress = (deliver) => options.packages?.subscribe((event) => deliver(gatewayEventFrame(GATEWAY_PACKAGES_PROGRESS, event)));
+    const events = async (request, context) => {
+        if (!server.instanceReady)
+            return offlineStream(request);
+        const upstream = await server.forward(request, context);
+        const type = upstream.headers.get('content-type') ?? '';
+        // Errors (401 / 403 / 503 …) and non-SSE answers pass through unchanged.
+        if (!upstream.ok || !upstream.body || !type.includes('text/event-stream')) {
+            if (upstream.status === 503 && !server.instanceReady) {
+                await upstream.body?.cancel().catch(() => undefined);
+                return offlineStream(request);
+            }
+            return upstream;
+        }
+        const client = open(request);
+        const reader = upstream.body.getReader();
+        client.cleanups.push(() => { void reader.cancel().catch(() => undefined); });
+        // Gateway frames wait while an instance frame is half written.
+        const pending = [];
+        let partial = '';
+        const decoder = new TextDecoder();
+        const flushPending = () => {
+            for (const frame of pending.splice(0))
+                client.write(frame);
+        };
+        const stop = subscribeProgress((frame) => {
+            if (partial) {
+                if (pending.length < MAX_PENDING_FRAMES)
+                    pending.push(frame);
+                return;
+            }
+            client.write(frame);
+        });
+        if (stop)
+            client.cleanups.push(stop);
+        void (async () => {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done || client.finished)
+                        break;
+                    const text = decoder.decode(value, { stream: true });
+                    client.write(text);
+                    partial = trailingPartialFrame(partial + text);
+                    if (!partial)
+                        flushPending();
+                }
+            }
+            catch { /* instance side ended */ }
+            client.finish();
+        })();
+        const headers = new Headers(upstream.headers);
+        headers.delete('content-length');
+        return new Response(client.stream, { status: upstream.status, headers });
+    };
+    const offlineStream = (request) => {
+        const client = open(request);
+        client.write(': gateway\n\n');
+        const stop = subscribeProgress((frame) => client.write(frame));
+        if (stop)
+            client.cleanups.push(stop);
+        // Reconnect to the merged stream once the instance is back.
+        const unwatch = options.instance?.onChange(() => { if (server.instanceReady)
+            client.finish(); });
+        if (unwatch)
+            client.cleanups.push(unwatch);
+        return new Response(client.stream, { status: 200, headers: SSE_HEADERS });
+    };
+    const history = async (request, context) => {
+        if (server.instanceReady)
+            return server.forward(request, context);
+        const runtimeId = context.url.searchParams.get('runtimeId') ?? 'gateway';
+        const after = Number(context.url.searchParams.get('after') ?? 0);
+        const cursor = Number.isSafeInteger(after) && after >= 0 ? after : 0;
+        const page = Object.freeze({
+            runtimeId,
+            items: Object.freeze([]),
+            oldestAvailableEventId: null,
+            latestEventId: cursor,
+            nextAfter: cursor,
+            hasMore: false,
+            gap: false,
+        });
+        return jsonResponse(200, { success: true, data: page }, { 'cache-control': 'no-store' });
+    };
+    const progress = (request) => {
+        const client = open(request);
+        client.write(': gateway packages\n\n');
+        const stop = subscribeProgress((frame) => client.write(frame));
+        if (stop)
+            client.cleanups.push(stop);
+        return new Response(client.stream, { status: 200, headers: SSE_HEADERS });
+    };
+    const registrations = [
+        server.route('GET', `${base}/events`, events, { summary: 'Console SSE stream (instance events merged with gateway events)', tags: ['console'] }),
+        server.route('GET', `${base}/events/history`, history, { summary: 'Console event history (empty while the instance is offline)', tags: ['console'] }),
+        server.route('GET', `${base}${GATEWAY_PACKAGES_PROGRESS_PATH}`, progress, { summary: 'Package transaction progress (SSE)', tags: ['gateway'] }),
+    ];
+    return () => { for (const unregister of registrations)
+        unregister(); };
+}
+/** The text after the last complete SSE frame (empty when the buffer ends on a frame boundary). */
+export function trailingPartialFrame(buffer) {
+    const normalized = buffer.replace(/\r\n/gu, '\n');
+    const boundary = normalized.lastIndexOf('\n\n');
+    return boundary < 0 ? normalized : normalized.slice(boundary + 2);
+}

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

@@ -0,0 +1,95 @@
+/**
+ * The gateway's HTTP server (ADR 0054 §2 / §3): the project's only listener.
+ *
+ * Request flow:
+ * 1. gateway-owned routes ({@link GatewayHttpServer.route} / `ws`) — health, `/auth/*`,
+ *    terminal, the merged Console event stream, package progress; gateway-owned Console RPC
+ *    (`gateway.*`, `iam.*`, `onboarding.update`) inside `POST {base}/console/request`;
+ * 2. `{base}/…` — authenticated and authorized here, then forwarded with the principal;
+ * 3. anything else (plugin webhooks, adapter reverse WebSockets, static pages) — forwarded as-is;
+ *    those routes authenticate themselves.
+ *
+ * The instance being offline never takes gateway-owned routes down: forwarded requests get
+ * `503 { code: 'instance_unavailable', state }` with `Retry-After`; an instance that does not
+ * answer in time gives `504 { code: 'instance_timeout' }`, any other bridge failure
+ * `502 { code: 'instance_error' }` (mapped from {@link InstanceTransportError}).
+ */
+import { TokenRegistry, type HttpHandler, type HttpHostAddress, type HttpRouteRegistration, type ResolvedHttpConfig, type RouteContext, type RouteMeta, type WsHandle, type WsRouteOptions } from '@zhin.js/host-http';
+import { type InstanceTransport } from '@zhin.js/host-http/bridge';
+import { type GatewayConsoleRpc, type GatewayRpcHandler } from './console-rpc.js';
+export declare const DEFAULT_GATEWAY_RETRY_AFTER_SECONDS = 5;
+/** Default cap on a forwarded request body (uploads go through the instance). */
+export declare const DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES: number;
+/** Where the server finds the instance; both are read per request. */
+export interface GatewayInstanceSource {
+    /** Current transport; undefined while no instance process exists. */
+    transport(): InstanceTransport | undefined;
+    /** Supervisor state reported in 503 bodies and `/pub/health` (e.g. `starting`, `crashed`). */
+    state(): string;
+}
+export interface GatewayHttpServerOptions {
+    /** Resolved `http.*` config: the primary listener plus `listeners` (extra ports, TLS). */
+    readonly http?: ResolvedHttpConfig;
+    readonly instance: GatewayInstanceSource;
+    /**
+     * Console authentication. The access provider (users, sessions, API tokens) is installed on it
+     * by the IAM module; defaults to a registry over `http.token`.
+     */
+    readonly tokenRegistry?: TokenRegistry;
+    readonly retryAfterSeconds?: number;
+    readonly maxRequestBodyBytes?: number;
+    /**
+     * Gateway-owned Console RPC (`gateway.*`) answered on `POST {base}/console/request`; every other
+     * RPC type on that route is forwarded to the instance unchanged.
+     */
+    readonly consoleRpc?: GatewayConsoleRpc;
+}
+/** One router, many listeners: every listener serves the same surface. */
+export declare class GatewayHttpServer {
+    #private;
+    readonly tokenRegistry: TokenRegistry;
+    readonly apiBase: string;
+    constructor(options: GatewayHttpServerOptions);
+    /** Registers a gateway-owned route; it takes precedence over the instance's routes. */
+    route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
+    /** Registers a gateway-owned WebSocket route. */
+    ws(path: string, options?: WsRouteOptions): WsHandle;
+    /**
+     * Answers further RPC types on `POST {base}/console/request` (e.g. `iam.*`); the handler checks
+     * the per-RPC permission itself. Returns an unregister function.
+     */
+    useConsoleRpc(handler: GatewayRpcHandler): () => void;
+    /** Whether an instance is connected and serving its route table. */
+    get instanceReady(): boolean;
+    /**
+     * Forwards one request to the instance (the router already authenticated and authorized it):
+     * the instance's response, or the documented 502 / 503 / 504 / 413 gateway responses.
+     */
+    forward(request: Request, context: RouteContext): Promise<Response>;
+    /** Handles one request without a socket (tests, local socket bridge). */
+    handle(request: Request, info?: {
+        readonly remoteAddress?: string;
+    }): Promise<Response>;
+    /** Primary listener address. */
+    get address(): HttpHostAddress | undefined;
+    /** Addresses of every bound listener, primary first. */
+    get addresses(): readonly HttpHostAddress[];
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+    /**
+     * A `{base}/…` request from the local control socket (`gateway.http.request`, ADR 0054 §6).
+     * Without `token` the socket's owner check is the authentication: the request runs as
+     * {@link LOCAL_OWNER_PRINCIPAL}. With `token` (an explicit `ZHIN_CONSOLE_TOKEN`) it is
+     * authenticated like an HTTP request with that Bearer credential and runs — and is audited — as
+     * its principal. Either way the request takes the HTTP route table: gateway-owned routes (e.g.
+     * `{base}/auth/me`), the `POST {base}/console/request` split, then the instance. Event streams
+     * cannot be carried in one socket reply; the socket handler refuses them. Only the path and query
+     * of `path` are used; paths outside `{base}` are refused.
+     */
+    localRequest(input: {
+        readonly method: string;
+        readonly path: string;
+        readonly body?: string;
+        readonly token?: string;
+    }): Promise<Response>;
+}