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

package/lib/terminal/host.js

@@ -0,0 +1,76 @@
+import { globalPermissions, isUserPrincipal, requestMeta } from '@zhin.js/host-http';
+import { installConsoleTerminal } from './index.js';
+const TERMINAL_PERMISSION = 'ops.terminal';
+/**
+ * Wires the Console terminal (ADR 0051) to Console access control (ADR 0049): only user
+ * sessions and user API tokens holding a global `ops.terminal` may use it (the bootstrap
+ * token never), terminal events land in the IAM audit log, and revoking a user's
+ * credentials ends their terminal sessions.
+ */
+export function installHostConsoleTerminal(http, options) {
+    // The Console principal behind each terminal principal, for authorization decisions.
+    const grantsOf = new WeakMap();
+    const handle = installConsoleTerminal(http, {
+        config: options.config,
+        projectRoot: options.projectRoot,
+        ...(options.base ? { base: options.base } : {}),
+        resolvePrincipal: async (token, context) => {
+            if (!token)
+                return null;
+            const principal = await http.tokenRegistry.authenticate(token, requestMeta(context, context.remoteAddress)) ?? undefined;
+            // Bootstrap (setup token or open Host) is not a person: terminal access needs a user.
+            if (!isUserPrincipal(principal))
+                return null;
+            const resolved = Object.freeze({ id: `user:${principal.userId}`, kind: principal.kind });
+            grantsOf.set(resolved, principal);
+            return resolved;
+        },
+        authorize: async (principal) => {
+            const resolved = grantsOf.get(principal);
+            // Global grant only (API tokens are already narrowed to their permission list).
+            if (!resolved || !globalPermissions(resolved).includes(TERMINAL_PERMISSION))
+                return false;
+            // The user may have been disabled or deleted since the credential was resolved.
+            const user = await options.iam()?.getUser(resolved.userId);
+            return user !== null && user !== undefined && !user.disabled;
+        },
+        audit: (event) => {
+            options.iam()?.audit({
+                actor: event.actor,
+                action: event.action,
+                ...(event.target ? { target: `terminal:${event.target}` } : {}),
+                outcome: event.outcome,
+                detail: event.detail,
+                ...(event.ip ? { ip: event.ip } : {}),
+            });
+        },
+        ...(options.logger ? { logger: options.logger } : {}),
+        ...(options.modules ? { modules: options.modules } : {}),
+        ...(options.env ? { env: options.env } : {}),
+    });
+    if (!handle.enabled)
+        return handle;
+    let stopRevocations;
+    const subscribe = () => {
+        if (stopRevocations)
+            return;
+        const iam = options.iam();
+        if (!iam)
+            return;
+        stopRevocations = iam.onCredentialsRevoked(({ userId }) => {
+            handle.terminatePrincipal(`user:${userId}`, 'revoked');
+        });
+    };
+    subscribe();
+    return Object.freeze({
+        enabled: handle.enabled,
+        config: handle.config,
+        terminatePrincipal: handle.terminatePrincipal,
+        sessions: handle.sessions,
+        close: () => {
+            stopRevocations?.();
+            stopRevocations = undefined;
+            handle.close();
+        },
+    });
+}

package/lib/terminal/index.d.ts

@@ -0,0 +1,60 @@
+import { type ConsolePrincipal } from '@zhin.js/host-http';
+import { type TerminalConfig } from './config.js';
+import type { TerminalModuleLoaders } from './modules.js';
+import { type TerminalAuditEvent, type TerminalEndReason, type TerminalLogger, type TerminalPrincipal, type TerminalConnection, type TerminalSessionInfo } from './service.js';
+export * from './config.js';
+export * from './tickets.js';
+export * from './service.js';
+export type { TerminalModuleLoaders, PtyModule, SshModule } from './modules.js';
+/** Structural subset of `HttpHost` (`@zhin.js/host-http`). */
+export interface TerminalHttpHost {
+    route(method: string, path: string, handler: (request: Request, context: {
+        readonly url: URL;
+        readonly principal?: ConsolePrincipal;
+        readonly remoteAddress?: string;
+    }) => Response | Promise<Response>, meta?: {
+        summary?: string;
+        tags?: string[];
+    }): () => void;
+    ws(path: string, options?: {
+        readonly auth?: 'host' | 'protocol';
+    }): {
+        onConnection(listener: (connection: TerminalConnection & {
+            readonly headers: Headers;
+        }) => void): () => void;
+        close(): void;
+    };
+}
+export interface TerminalPrincipalContext {
+    readonly headers: Headers;
+    readonly remoteAddress?: string;
+    /** Principal the Host already authenticated (HTTP routes); absent on WebSocket upgrades. */
+    readonly principal?: ConsolePrincipal;
+}
+export interface InstallConsoleTerminalOptions {
+    /** Raw `console.terminal` block, or an already parsed config. */
+    readonly config: unknown;
+    readonly projectRoot: string;
+    /** API base the Console uses (default `/api`). */
+    readonly base?: string;
+    /** Must return true only for principals holding `ops.terminal`. Errors deny. */
+    readonly authorize: (principal: TerminalPrincipal) => boolean | Promise<boolean>;
+    /** Maps a bearer credential to a principal; `null` → 401. */
+    readonly resolvePrincipal: (bearerToken: string, context: TerminalPrincipalContext) => TerminalPrincipal | null | Promise<TerminalPrincipal | null>;
+    readonly audit?: (event: TerminalAuditEvent) => void;
+    readonly logger?: TerminalLogger;
+    /** Test seam for `node-pty` / `ssh2`. */
+    readonly modules?: TerminalModuleLoaders;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly readFile?: (path: string) => Promise<Buffer>;
+}
+export interface ConsoleTerminalHandle {
+    readonly enabled: boolean;
+    readonly config: TerminalConfig;
+    /** Ends every session and pending ticket of a principal (credential revoked, user disabled…). */
+    terminatePrincipal(principalId: string, reason?: TerminalEndReason): number;
+    sessions(): TerminalSessionInfo[];
+    /** Unregisters routes and ends all sessions (`exit` reason `disabled`). Idempotent. */
+    close(): void;
+}
+export declare function installConsoleTerminal(host: TerminalHttpHost, options: InstallConsoleTerminalOptions): ConsoleTerminalHandle;

package/lib/terminal/index.js

@@ -0,0 +1,135 @@
+import { jsonResponse, readJsonBody } from '@zhin.js/host-http';
+import { parseTerminalConfig } from './config.js';
+import { TerminalRequestError, TerminalService, } from './service.js';
+export * from './config.js';
+export * from './tickets.js';
+export * from './service.js';
+export function installConsoleTerminal(host, options) {
+    // Parsing is idempotent, so an already parsed TerminalConfig is accepted too.
+    const config = parseTerminalConfig(options.config, {
+        projectRoot: options.projectRoot,
+        ...(options.env ? { env: options.env } : {}),
+    });
+    if (!config.enabled) {
+        // ADR 0051: disabled → no routes, optional modules never loaded.
+        return Object.freeze({
+            enabled: false,
+            config,
+            terminatePrincipal: () => 0,
+            sessions: () => [],
+            close: () => undefined,
+        });
+    }
+    const base = normalizeBase(options.base ?? '/api');
+    const service = new TerminalService({
+        config,
+        projectRoot: options.projectRoot,
+        authorize: options.authorize,
+        ...(options.audit ? { audit: options.audit } : {}),
+        ...(options.logger ? { logger: options.logger } : {}),
+        ...(options.modules ? { modules: options.modules } : {}),
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.readFile ? { readFile: options.readFile } : {}),
+    });
+    const authenticate = async (request, context) => {
+        const token = bearerToken(request.headers, context.url);
+        let principal = null;
+        try {
+            principal = await options.resolvePrincipal(token, {
+                headers: request.headers,
+                ...(context.remoteAddress ? { remoteAddress: context.remoteAddress } : {}),
+                ...(context.principal ? { principal: context.principal } : {}),
+            });
+        }
+        catch {
+            principal = null;
+        }
+        return service.requireAuthorized(principal, context.remoteAddress);
+    };
+    const fail = (error) => {
+        if (error instanceof TerminalRequestError) {
+            return jsonResponse(error.status, { success: false, code: error.code, error: error.message });
+        }
+        throw error;
+    };
+    const unregister = [];
+    unregister.push(host.route('GET', `${base}/console/terminal/targets`, async (request, context) => {
+        try {
+            await authenticate(request, context);
+            return jsonResponse(200, { success: true, data: await service.listTargets() });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }, { summary: 'List Console terminal targets', tags: ['console', 'terminal'] }));
+    unregister.push(host.route('POST', `${base}/console/terminal/tickets`, async (request, context) => {
+        try {
+            const principal = await authenticate(request, context);
+            const body = await readJsonBody(request, { limit: 4096 });
+            return jsonResponse(200, { success: true, data: await service.issueTicket(principal, body, context.remoteAddress) });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }, { summary: 'Issue a one-time Console terminal WebSocket ticket', tags: ['console', 'terminal'] }));
+    // Browsers cannot set Authorization on WebSocket upgrades: the ticket is the credential.
+    const ws = host.ws(`${base}/console/terminal`, { auth: 'protocol' });
+    const stopWs = ws.onConnection((connection) => {
+        void (async () => {
+            let presented;
+            const header = connection.headers.get('authorization');
+            if (typeof header === 'string' && header.startsWith('Bearer ')) {
+                try {
+                    presented = await options.resolvePrincipal(header.slice(7).trim(), {
+                        headers: connection.headers,
+                        ...(connection.remoteAddress ? { remoteAddress: connection.remoteAddress } : {}),
+                    });
+                }
+                catch {
+                    presented = null;
+                }
+                // A bearer that resolves to nobody must not fall back to ticket-only auth.
+                if (!presented)
+                    presented = { id: '\u0000invalid' };
+            }
+            await service.handleConnection(connection, presented);
+        })().catch((error) => {
+            options.logger?.warn?.(`terminal connection failed: ${error instanceof Error ? error.message : String(error)}`);
+            try {
+                connection.close(1011, 'internal-error');
+            }
+            catch {
+                /* ignore */
+            }
+        });
+    });
+    unregister.push(stopWs, () => ws.close());
+    let closed = false;
+    return Object.freeze({
+        enabled: true,
+        config,
+        terminatePrincipal: (principalId, reason) => service.terminatePrincipal(principalId, reason),
+        sessions: () => service.sessions(),
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const stop of unregister)
+                stop();
+            service.closeAll('disabled', true);
+        },
+    });
+}
+function bearerToken(headers, url) {
+    const header = headers.get('authorization');
+    if (typeof header === 'string' && header.startsWith('Bearer '))
+        return header.slice(7).trim();
+    return url.searchParams.get('token')?.trim() ?? '';
+}
+function normalizeBase(value) {
+    const withSlash = value.startsWith('/') ? value : `/${value}`;
+    let end = withSlash.length;
+    while (end > 1 && withSlash[end - 1] === '/')
+        end -= 1;
+    return withSlash.slice(0, end);
+}

package/lib/terminal/modules.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Minimal structural views of `node-pty` and `ssh2`. Both are optional
+ * dependencies, loaded with `import()` only when a terminal is actually used.
+ */
+export interface PtyDisposable {
+    dispose(): void;
+}
+export interface PtyProcess {
+    readonly pid: number;
+    onData(listener: (data: string) => void): PtyDisposable | void;
+    onExit(listener: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): PtyDisposable | void;
+    write(data: string | Buffer): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    pause?(): void;
+    resume?(): void;
+}
+export interface PtySpawnOptions {
+    readonly name: string;
+    readonly cols: number;
+    readonly rows: number;
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+export interface PtyModule {
+    spawn(file: string, args: string[], options: PtySpawnOptions): PtyProcess;
+}
+export interface SshChannel {
+    on(event: 'data', listener: (data: Buffer) => void): unknown;
+    on(event: 'exit', listener: (code: number | null, signal?: string) => void): unknown;
+    on(event: 'close', listener: () => void): unknown;
+    readonly stderr?: {
+        on(event: 'data', listener: (data: Buffer) => void): unknown;
+    };
+    write(data: Buffer | string): unknown;
+    setWindow(rows: number, cols: number, height: number, width: number): unknown;
+    close?(): unknown;
+    pause?(): unknown;
+    resume?(): unknown;
+}
+export interface SshConnectConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly privateKey?: Buffer | string;
+    readonly passphrase?: string;
+    readonly password?: string;
+    readonly readyTimeout?: number;
+    readonly keepaliveInterval?: number;
+    readonly hostVerifier?: (key: Buffer) => boolean;
+}
+export interface SshClient {
+    on(event: 'ready', listener: () => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'close', listener: () => void): unknown;
+    connect(config: SshConnectConfig): unknown;
+    shell(window: {
+        term: string;
+        cols: number;
+        rows: number;
+    }, callback: (error: Error | undefined, channel: SshChannel) => void): unknown;
+    end(): unknown;
+}
+export interface SshModule {
+    readonly Client: new () => SshClient;
+}
+export interface TerminalModuleLoaders {
+    readonly loadPty?: () => Promise<PtyModule>;
+    readonly loadSsh?: () => Promise<SshModule>;
+}
+export type ModuleLoadResult<T> = {
+    readonly ok: true;
+    readonly module: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function importNodePty(): Promise<PtyModule>;
+export declare function importSsh2(): Promise<SshModule>;
+/** Caches one load attempt per module; a failure is reported as an install hint. */
+export declare function createModuleCache(loaders?: TerminalModuleLoaders): {
+    pty(): Promise<ModuleLoadResult<PtyModule>>;
+    ssh(): Promise<ModuleLoadResult<SshModule>>;
+};

package/lib/terminal/modules.js

@@ -0,0 +1,44 @@
+/**
+ * Minimal structural views of `node-pty` and `ssh2`. Both are optional
+ * dependencies, loaded with `import()` only when a terminal is actually used.
+ */
+// Non-literal specifiers keep TypeScript and bundlers from requiring the packages.
+const PTY_SPECIFIER = 'node-pty';
+const SSH_SPECIFIER = 'ssh2';
+export async function importNodePty() {
+    const mod = await import(/* @vite-ignore */ PTY_SPECIFIER);
+    const spawn = typeof mod.spawn === 'function' ? mod.spawn : mod.default?.spawn;
+    if (typeof spawn !== 'function')
+        throw new Error('node-pty does not export spawn()');
+    return { spawn: spawn };
+}
+export async function importSsh2() {
+    const mod = await import(/* @vite-ignore */ SSH_SPECIFIER);
+    const Client = typeof mod.Client === 'function' ? mod.Client : mod.default?.Client;
+    if (typeof Client !== 'function')
+        throw new Error('ssh2 does not export Client');
+    return { Client: Client };
+}
+/** Caches one load attempt per module; a failure is reported as an install hint. */
+export function createModuleCache(loaders = {}) {
+    let pty;
+    let ssh;
+    return {
+        pty() {
+            pty ??= settle(loaders.loadPty ?? importNodePty, 'node-pty');
+            return pty;
+        },
+        ssh() {
+            ssh ??= settle(loaders.loadSsh ?? importSsh2, 'ssh2');
+            return ssh;
+        },
+    };
+}
+async function settle(load, name) {
+    try {
+        return { ok: true, module: await load() };
+    }
+    catch {
+        return { ok: false, reason: `${name} 不可用（可选依赖未安装或原生模块构建失败）：在项目中执行 pnpm add ${name} 后重启` };
+    }
+}

package/lib/terminal/service.d.ts

@@ -0,0 +1,101 @@
+import { type TerminalConfig } from './config.js';
+import { type TerminalModuleLoaders } from './modules.js';
+import { type IssuedTerminalTicket } from './tickets.js';
+/** Authenticated caller. `id` binds tickets and is the revocation key (e.g. `user:<id>`). */
+export interface TerminalPrincipal {
+    readonly id: string;
+    /** Informational (e.g. `user`, `api-token`); authorization is decided by `authorize()` only. */
+    readonly kind?: string;
+}
+export type TerminalAuditAction = 'terminal.session.start' | 'terminal.session.end' | 'terminal.ticket.issue' | 'terminal.denied';
+/** Shaped after `console_audit_log` (ADR 0049). Never carries terminal io or credentials. */
+export interface TerminalAuditEvent {
+    readonly action: TerminalAuditAction;
+    /** Principal id, or `anonymous` when unauthenticated. */
+    readonly actor: string;
+    readonly target: string;
+    readonly outcome: 'ok' | 'denied' | 'error';
+    readonly ip?: string;
+    readonly detail: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface TerminalLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+    debug?(message: string): void;
+}
+export type TerminalEndReason = 'disconnect' | 'idle-timeout' | 'process-exit' | 'revoked' | 'disabled' | 'error';
+export interface TerminalTarget {
+    readonly id: string;
+    readonly kind: 'local' | 'ssh';
+    readonly label: string;
+    readonly available: boolean;
+    readonly reason?: string;
+    /** SSH target configured with `insecureAcceptAnyHostKey`: the host key is not verified. */
+    readonly insecureHostKey?: true;
+}
+export interface TerminalSessionInfo {
+    readonly sessionId: string;
+    readonly principalId: string;
+    readonly target: string;
+    readonly kind: 'local' | 'ssh';
+    readonly startedAt: number;
+}
+/** Structural subset of a `WsConnection` (`@zhin.js/host-http`). */
+export interface TerminalSocket {
+    /** Text frames as strings, binary frames as bytes. */
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onMessage(listener: (data: string | Uint8Array) => void): () => void;
+    onClose(listener: (code: number, reason: string) => void): () => void;
+    readonly bufferedAmount: number;
+}
+/** The accepted upgrade a terminal session runs on. */
+export interface TerminalConnection extends TerminalSocket {
+    readonly url: URL;
+    readonly remoteAddress?: string;
+}
+export interface TerminalServiceOptions {
+    readonly config: TerminalConfig;
+    readonly projectRoot: string;
+    readonly authorize: (principal: TerminalPrincipal) => boolean | Promise<boolean>;
+    readonly audit?: (event: TerminalAuditEvent) => void;
+    readonly logger?: TerminalLogger;
+    readonly modules?: TerminalModuleLoaders;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: () => number;
+    /** Override key file reads (tests). */
+    readonly readFile?: (path: string) => Promise<Buffer>;
+}
+export declare class TerminalRequestError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare const TERMINAL_CLOSE_CODES: Readonly<{
+    normal: 1000;
+    startFailed: 1011;
+    badRequest: 4400;
+    invalidTicket: 4401;
+    forbidden: 4403;
+    tooManySessions: 4429;
+}>;
+/** Terminal tickets, targets and live sessions (ADR 0051). Transport-agnostic. */
+export declare class TerminalService {
+    #private;
+    constructor(options: TerminalServiceOptions);
+    get config(): TerminalConfig;
+    /** Throws `TerminalRequestError(403)` unless the principal may use the terminal. */
+    requireAuthorized(principal: TerminalPrincipal | null, ip?: string): Promise<TerminalPrincipal>;
+    listTargets(): Promise<TerminalTarget[]>;
+    issueTicket(principal: TerminalPrincipal, body: unknown, ip?: string): Promise<IssuedTerminalTicket>;
+    /**
+     * Handles one accepted WebSocket. `presentedPrincipal` is set when the upgrade
+     * also carried a bearer credential; it must then match the ticket's principal.
+     */
+    handleConnection(socket: TerminalConnection, presentedPrincipal?: TerminalPrincipal | null): Promise<void>;
+    /** Ends every session (and pending ticket) of a principal. Returns the number of sessions ended. */
+    terminatePrincipal(principalId: string, reason?: TerminalEndReason): number;
+    /** Ends all sessions; with `final`, refuses further tickets and connections. */
+    closeAll(reason?: TerminalEndReason, final?: boolean): void;
+    sessions(): TerminalSessionInfo[];
+}