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

package/lib/http/console-rpc.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gateway-owned Console RPC on `POST {base}/console/request` (ADR 0054 §4 / §5): the Console
+ * sends `{ type, requestId?, data? }`; `gateway.*` types are answered here with the same reply
+ * envelope the instance uses (`{ success, data, type, requestId }` / `{ success: false, code,
+ * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
+ * type is forwarded to the instance by the HTTP server.
+ */
+import { type RouteContext, type TokenRegistry } from '@zhin.js/host-http';
+import type { GatewayRpcDispatcher } from '../packages/rpc.js';
+/** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
+export declare const GATEWAY_RPC_PREFIX = "gateway.";
+export interface GatewayConsoleRpc {
+    handle(message: Readonly<Record<string, unknown>>, context: RouteContext, tokenRegistry: TokenRegistry): Promise<Response>;
+}
+/**
+ * Further gateway-owned RPC types (`iam.*`, `onboarding.update`, the global plugin switch), see
+ * `GatewayHttpServer.useConsoleRpc`.
+ */
+export interface GatewayRpcHandler extends GatewayConsoleRpc {
+    owns(type: string): boolean;
+    /**
+     * Narrows {@link owns} by payload: when present and false for the parsed message, the request
+     * is forwarded to the instance untouched (e.g. `feature.set-enabled` below the global level).
+     */
+    claims?(message: Readonly<Record<string, unknown>>): boolean;
+}
+export declare function createGatewayConsoleRpc(dispatch: GatewayRpcDispatcher): GatewayConsoleRpc;

package/lib/http/console-rpc.js

@@ -0,0 +1,51 @@
+/**
+ * Gateway-owned Console RPC on `POST {base}/console/request` (ADR 0054 §4 / §5): the Console
+ * sends `{ type, requestId?, data? }`; `gateway.*` types are answered here with the same reply
+ * envelope the instance uses (`{ success, data, type, requestId }` / `{ success: false, code,
+ * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
+ * type is forwarded to the instance by the HTTP server.
+ */
+import { auditActor, jsonResponse, } from '@zhin.js/host-http';
+import { GATEWAY_RPC } from '@zhin.js/console-protocol';
+/** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
+export const GATEWAY_RPC_PREFIX = 'gateway.';
+const READ_ONLY_TYPES = new Set([
+    GATEWAY_RPC.LIST,
+    GATEWAY_RPC.PLAN,
+    GATEWAY_RPC.STATUS,
+    GATEWAY_RPC.LOGS,
+]);
+export function createGatewayConsoleRpc(dispatch) {
+    return Object.freeze({
+        async handle(message, context, tokenRegistry) {
+            const type = typeof message.type === 'string' ? message.type : '';
+            const requestId = message.requestId;
+            const principal = context.principal;
+            const result = await dispatch({ type, data: message.data }, principal);
+            const write = !READ_ONLY_TYPES.has(type);
+            const outcome = result.ok ? 'ok' : result.error.code === 'forbidden' ? 'denied' : 'error';
+            if (write || outcome === 'denied') {
+                try {
+                    tokenRegistry.accessProvider?.audit?.({
+                        actor: auditActor(principal),
+                        action: `rpc:${type}`.slice(0, 256),
+                        outcome,
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            }
+            const noStore = { 'cache-control': 'no-store' };
+            if (result.ok)
+                return jsonResponse(200, { success: true, data: result.data, type, requestId }, noStore);
+            return jsonResponse(result.error.status, {
+                success: false,
+                code: result.error.code,
+                error: result.error.message,
+                requestId,
+                ...(result.error.errors ? { errors: result.error.errors } : {}),
+                ...(result.error.missingEnv ? { missingEnv: result.error.missingEnv } : {}),
+            }, noStore);
+        },
+    });
+}

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

@@ -0,0 +1,63 @@
+import { type ConsoleAuditEntry } from '@zhin.js/host-http';
+import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import { type ProjectDatabaseConfig } from '../database/config.js';
+import { ProjectDatabase } from '../database/project-database.js';
+import { type LocalConsoleAdmin } from '../iam/local-admin.js';
+import { ConsoleIamService } from '../iam/service.js';
+import { ConsoleSetupService } from '../iam/setup-service.js';
+import { OnboardingService } from '../onboarding/service.js';
+import type { ConsoleTerminalHandle } from '../terminal/index.js';
+import type { GatewayRpcHandler } from './console-rpc.js';
+import type { GatewayHttpServer } from './gateway-http-server.js';
+/** What the Console module needs from the instance bridge (`IpcInstanceTransport` has all of it). */
+export interface GatewayConsoleInstancePort {
+    /** Plugin permission catalog the instance last reported. */
+    pluginPermissions?(): readonly ConsolePluginPermissionInfo[];
+    /** Sends `principal-revoked` (the instance closes that user's live connections). */
+    revokePrincipal?(principalId: string, reason?: string): void;
+    /** Audit entries written by the instance. */
+    onAudit?(listener: (entry: ConsoleAuditEntry) => void): () => void;
+}
+export interface GatewayConsoleOptions {
+    readonly server: GatewayHttpServer;
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `${…}` in `database` / `console.terminal`. Default `development`. */
+    readonly environment?: string;
+    readonly instance?: GatewayConsoleInstancePort;
+    /** Restarts the instance after the setup wizard switched databases (ADR 0054 §7). */
+    readonly restartInstance?: () => Promise<void>;
+    /** Overrides the project `database` block (tests). */
+    readonly database?: ProjectDatabaseConfig;
+    /** Overrides the project `console.terminal` block. */
+    readonly terminal?: unknown;
+    readonly onboarding?: OnboardingService;
+    /** Retry interval while the database cannot be opened. Default 10 s. */
+    readonly retryMs?: number;
+}
+export interface GatewayConsole {
+    /** Settles once the first database open attempt finished (never rejects). */
+    readonly ready: Promise<void>;
+    /** The IAM service bound to the open database; undefined when the dialect cannot hold accounts. */
+    iam(): ConsoleIamService | undefined;
+    /** The gateway's database connection (undefined before the first open). */
+    database(): ProjectDatabase | undefined;
+    readonly setup: ConsoleSetupService;
+    readonly onboarding: OnboardingService;
+    readonly terminal: ConsoleTerminalHandle;
+    /** Closes the gateway's connection and opens the configured database again (setup wizard). */
+    reopenDatabase(): Promise<void>;
+    /** Socket-only `gateway.console.*` (`zhin console init` / `zhin console user` beside the gateway). */
+    readonly localAdmin: LocalConsoleAdmin;
+    close(): Promise<void>;
+}
+export declare function startGatewayConsole(options: GatewayConsoleOptions): Promise<GatewayConsole>;
+export interface GatewayAccountRpcOptions {
+    readonly iam: () => ConsoleIamService | undefined;
+    readonly onboarding: OnboardingService;
+}
+/**
+ * `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 declare function createGatewayAccountRpc(options: GatewayAccountRpcOptions): GatewayRpcHandler;

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,40 @@
+/**
+ * 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.
+ *
+ * A succeeded plugin enable / disable that changed `disable_plugins` also sends
+ * `plugin:lifecycle-updated` on `{base}/events` (the Console reloads its entries on it).
+ *
+ * `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';
+/** Console event the client reloads its entries on (`CONSOLE_ENTRY_LIFECYCLE_EVENTS`). */
+export declare const PLUGIN_LIFECYCLE_UPDATED = "plugin:lifecycle-updated";
+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;