@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/supervisor/terminal-state.js

@@ -0,0 +1,57 @@
+/**
+ * The foreground gateway's terminal, shared with the instance when it inherits stdin (terminal
+ * adapters, login assist). Node has no `tcgetpgrp` / termios API, so this uses `/proc` and
+ * `stty` / `ps` (Unix only; Windows consoles are left as they are).
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+/**
+ * Whether this process is in the terminal's foreground process group. A background job
+ * (`zhin start --foreground &`) must not hand its TTY stdin to the instance: reading it would
+ * stop the instance with SIGTTIN. Unknown (no controlling terminal, probe failed) counts as
+ * foreground, the previous behaviour.
+ */
+export function isForegroundProcessGroup(probe = {}) {
+    const platform = probe.platform ?? process.platform;
+    if (platform === 'win32')
+        return true;
+    const pid = probe.pid ?? process.pid;
+    try {
+        if (platform === 'linux') {
+            const stat = (probe.readStat ?? ((id) => readFileSync(`/proc/${id}/stat`, 'utf8')))(pid);
+            // `pid (comm) state ppid pgrp session tty_nr tpgid …`; comm may contain spaces and ')'.
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/u);
+            const pgrp = Number(fields[2]);
+            const tpgid = Number(fields[5]);
+            if (!Number.isInteger(pgrp) || !Number.isInteger(tpgid) || tpgid <= 0)
+                return true;
+            return pgrp === tpgid;
+        }
+        const output = (probe.ps ?? ((id) => spawnSync('ps', ['-o', 'pgid=,tpgid=', '-p', String(id)], { encoding: 'utf8' }).stdout ?? ''))(pid);
+        const [pgid, tpgid] = output.trim().split(/\s+/u).map(Number);
+        if (!Number.isInteger(pgid) || !Number.isInteger(tpgid) || tpgid <= 0)
+            return true;
+        return pgid === tpgid;
+    }
+    catch {
+        return true;
+    }
+}
+const runStty = (args) => {
+    const result = spawnSync('stty', [...args], { stdio: ['inherit', 'pipe', 'ignore'], encoding: 'utf8' });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+};
+/**
+ * Saves the terminal settings (`stty -g`) so they can be restored once the instance that shares
+ * the TTY exits — a crashed terminal adapter can leave it in raw / no-echo mode. Undefined on
+ * Windows or without a usable `stty`.
+ */
+export function captureTerminalState(options = {}) {
+    if ((options.platform ?? process.platform) === 'win32')
+        return undefined;
+    const stty = options.stty ?? runStty;
+    const saved = stty(['-g']);
+    if (!saved)
+        return undefined;
+    return Object.freeze({ restore: () => { stty([saved]); } });
+}

package/lib/supervisor.d.ts

@@ -0,0 +1,4 @@
+/** `@zhin.js/gateway/supervisor` — instance process supervision over the IPC control channel (ADR 0054 §3 / §5). */
+export * from './supervisor/instance-supervisor.js';
+export * from './supervisor/instance-logs.js';
+export * from './supervisor/run-instance.js';

package/lib/supervisor.js

@@ -0,0 +1,4 @@
+/** `@zhin.js/gateway/supervisor` — instance process supervision over the IPC control channel (ADR 0054 §3 / §5). */
+export * from './supervisor/instance-supervisor.js';
+export * from './supervisor/instance-logs.js';
+export * from './supervisor/run-instance.js';

package/lib/terminal/backends.d.ts

@@ -0,0 +1,38 @@
+import { type SshCredentials, type TerminalSshTargetConfig } from './config.js';
+import type { PtyModule, SshModule } from './modules.js';
+export interface TerminalSize {
+    readonly cols: number;
+    readonly rows: number;
+}
+export interface TerminalExit {
+    readonly code: number | null;
+    readonly signal?: string | number;
+}
+export interface TerminalBackendEvents {
+    onData(chunk: Buffer | string): void;
+    onExit(exit: TerminalExit): void;
+}
+/** A running shell (local PTY or SSH channel). `kill()` is idempotent. */
+export interface TerminalBackend {
+    write(data: Buffer): void;
+    resize(size: TerminalSize): void;
+    kill(): void;
+    pause(): void;
+    resume(): void;
+}
+export declare class TerminalStartError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function startLocalBackend(pty: PtyModule, options: {
+    shell: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}, size: TerminalSize, events: TerminalBackendEvents): TerminalBackend;
+export interface SshStartOptions {
+    readonly readyTimeoutMs?: number;
+    /** Receives the observed host fingerprint (not secret) so operators can pin it. */
+    readonly onHostKey?: (fingerprint: string) => void;
+}
+/** Connects and opens an interactive shell. Resolves once the channel is open. */
+export declare function startSshBackend(ssh: SshModule, target: TerminalSshTargetConfig, credentials: SshCredentials, size: TerminalSize, events: TerminalBackendEvents, options?: SshStartOptions): Promise<TerminalBackend>;

package/lib/terminal/backends.js

@@ -0,0 +1,193 @@
+import { hostKeyFingerprint } from './config.js';
+export class TerminalStartError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TerminalStartError';
+    }
+}
+const TERM = 'xterm-256color';
+export function startLocalBackend(pty, options, size, events) {
+    const env = {};
+    for (const [key, value] of Object.entries(options.env ?? process.env)) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    env.TERM = TERM;
+    let proc;
+    try {
+        proc = pty.spawn(options.shell, [], { name: TERM, cols: size.cols, rows: size.rows, cwd: options.cwd, env });
+    }
+    catch (error) {
+        throw new TerminalStartError('spawn-failed', `无法启动 Shell：${error instanceof Error ? error.message : String(error)}`);
+    }
+    let exited = false;
+    proc.onData((data) => {
+        if (!exited)
+            events.onData(data);
+    });
+    proc.onExit(({ exitCode, signal }) => {
+        if (exited)
+            return;
+        exited = true;
+        events.onExit({ code: exitCode, ...(signal ? { signal } : {}) });
+    });
+    return {
+        write(data) {
+            if (!exited)
+                proc.write(data.toString('utf8'));
+        },
+        resize({ cols, rows }) {
+            if (!exited)
+                proc.resize(cols, rows);
+        },
+        kill() {
+            if (exited)
+                return;
+            try {
+                proc.kill();
+            }
+            catch {
+                /* already gone */
+            }
+        },
+        pause() {
+            proc.pause?.();
+        },
+        resume() {
+            proc.resume?.();
+        },
+    };
+}
+/** Connects and opens an interactive shell. Resolves once the channel is open. */
+export function startSshBackend(ssh, target, credentials, size, events, options = {}) {
+    return new Promise((resolve, reject) => {
+        const client = new ssh.Client();
+        let channel;
+        let settled = false;
+        let finished = false;
+        let fingerprintMismatch = false;
+        let exit = { code: null };
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                client.end();
+            }
+            catch {
+                /* ignore */
+            }
+            if (settled)
+                events.onExit(exit);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            finished = true;
+            try {
+                client.end();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(error);
+        };
+        client.on('error', (error) => {
+            if (!settled) {
+                fail(fingerprintMismatch
+                    ? new TerminalStartError('host-fingerprint-mismatch', `SSH 主机指纹与配置不符（${target.name}）`)
+                    : new TerminalStartError('ssh-connect-failed', `SSH 连接失败（${target.name}）：${error.message}`));
+                return;
+            }
+            finish();
+        });
+        client.on('close', () => {
+            if (!settled) {
+                fail(fingerprintMismatch
+                    ? new TerminalStartError('host-fingerprint-mismatch', `SSH 主机指纹与配置不符（${target.name}）`)
+                    : new TerminalStartError('ssh-connect-failed', `SSH 连接已关闭（${target.name}）`));
+                return;
+            }
+            finish();
+        });
+        client.on('ready', () => {
+            client.shell({ term: TERM, cols: size.cols, rows: size.rows }, (error, opened) => {
+                if (error) {
+                    fail(new TerminalStartError('ssh-shell-failed', `无法打开远程 Shell（${target.name}）：${error.message}`));
+                    return;
+                }
+                if (finished) {
+                    opened.close?.();
+                    return;
+                }
+                channel = opened;
+                opened.on('data', (data) => {
+                    if (!finished)
+                        events.onData(data);
+                });
+                opened.stderr?.on('data', (data) => {
+                    if (!finished)
+                        events.onData(data);
+                });
+                opened.on('exit', (code, signal) => {
+                    exit = { code: code ?? null, ...(signal ? { signal } : {}) };
+                });
+                opened.on('close', finish);
+                settled = true;
+                resolve({
+                    write(data) {
+                        if (!finished)
+                            opened.write(data);
+                    },
+                    resize({ cols, rows }) {
+                        if (!finished)
+                            opened.setWindow(rows, cols, 0, 0);
+                    },
+                    kill() {
+                        if (finished)
+                            return;
+                        try {
+                            channel?.close?.();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                        finish();
+                    },
+                    pause() {
+                        opened.pause?.();
+                    },
+                    resume() {
+                        opened.resume?.();
+                    },
+                });
+            });
+        });
+        try {
+            client.connect({
+                host: target.host,
+                port: target.port,
+                username: target.username,
+                ...credentials,
+                readyTimeout: options.readyTimeoutMs ?? 20_000,
+                keepaliveInterval: 30_000,
+                hostVerifier: (key) => {
+                    const observed = hostKeyFingerprint(key);
+                    options.onHostKey?.(observed);
+                    // Deny by default: only an explicit opt-out skips the pin.
+                    if (target.insecureAcceptAnyHostKey !== true && observed !== target.hostFingerprint) {
+                        fingerprintMismatch = true;
+                        return false;
+                    }
+                    return true;
+                },
+            });
+        }
+        catch (error) {
+            fail(new TerminalStartError('ssh-connect-failed', `SSH 连接失败（${target.name}）：${error instanceof Error ? error.message : String(error)}`));
+        }
+    });
+}

package/lib/terminal/config.d.ts

@@ -0,0 +1,63 @@
+/** Host top-level `console.terminal` block (ADR 0051). */
+export interface TerminalSshTargetConfig {
+    readonly name: string;
+    readonly host: string;
+    readonly port: number;
+    readonly username: string;
+    readonly label?: string;
+    readonly privateKeyPath?: string;
+    readonly privateKeyEnv?: string;
+    readonly passwordEnv?: string;
+    readonly passphraseEnv?: string;
+    /** Normalized `SHA256:<base64 without padding>`; required unless {@link insecureAcceptAnyHostKey}. */
+    readonly hostFingerprint?: string;
+    /** Explicit opt-out of host key verification (MITM-able); the Console marks the target unsafe. */
+    readonly insecureAcceptAnyHostKey?: true;
+}
+export interface TerminalConfig {
+    readonly enabled: boolean;
+    readonly shell: string;
+    /** Absolute working directory for local shells. */
+    readonly cwd: string;
+    /** Seconds without input before the session is closed. */
+    readonly idleTimeout: number;
+    readonly maxSessions: number;
+    readonly ssh: readonly TerminalSshTargetConfig[];
+}
+export declare class TerminalConfigError extends Error {
+    constructor(path: string, message: string);
+}
+export interface ParseTerminalConfigOptions {
+    readonly projectRoot: string;
+    readonly platform?: NodeJS.Platform;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function defaultShell(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string;
+/** Parses and validates the raw `console.terminal` value. Missing or `enabled: false` → disabled. */
+export declare function parseTerminalConfig(raw: unknown, options: ParseTerminalConfigOptions): TerminalConfig;
+/** `SHA256:abc=` / `sha256:abc` → `SHA256:abc`; undefined when not a SHA256 base64 fingerprint. */
+export declare function normalizeFingerprint(value: string): string | undefined;
+/** OpenSSH-style fingerprint of a raw host key blob. */
+export declare function hostKeyFingerprint(key: Uint8Array): string;
+export interface SshCredentials {
+    readonly privateKey?: Buffer | string;
+    readonly passphrase?: string;
+    readonly password?: string;
+}
+export declare class SshCredentialError extends Error {
+    constructor(message: string);
+}
+export interface CredentialSources {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly projectRoot: string;
+    readonly readFile?: (path: string) => Promise<Buffer>;
+    readonly homedir?: () => string;
+}
+export declare function resolveKeyPath(path: string, projectRoot: string, home?: () => string): string;
+/**
+ * Loads SSH credentials from env / local key file. Error messages name the
+ * variable or file, never its value.
+ */
+export declare function resolveSshCredentials(target: TerminalSshTargetConfig, sources: CredentialSources): Promise<SshCredentials>;
+/** Cheap availability check for the targets list (no file contents are read). */
+export declare function sshCredentialProblem(target: TerminalSshTargetConfig, env: NodeJS.ProcessEnv): string | undefined;

package/lib/terminal/config.js

@@ -0,0 +1,237 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+export class TerminalConfigError extends Error {
+    constructor(path, message) {
+        super(`console.terminal${path ? `.${path}` : ''}: ${message}`);
+        this.name = 'TerminalConfigError';
+    }
+}
+const TARGET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const KNOWN_KEYS = new Set(['enabled', 'shell', 'cwd', 'idleTimeout', 'maxSessions', 'ssh']);
+const KNOWN_SSH_KEYS = new Set([
+    'name', 'label', 'host', 'port', 'username', 'privateKeyPath', 'privateKeyEnv',
+    'passwordEnv', 'passphraseEnv', 'hostFingerprint', 'insecureAcceptAnyHostKey',
+]);
+const FINGERPRINT_HINT = 'run `ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -` on a trusted network and copy the SHA256:… value';
+export function defaultShell(platform, env) {
+    if (platform === 'win32')
+        return 'powershell.exe';
+    return env.SHELL?.trim() || '/bin/sh';
+}
+/** Parses and validates the raw `console.terminal` value. Missing or `enabled: false` → disabled. */
+export function parseTerminalConfig(raw, options) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    if (raw === undefined || raw === null)
+        return disabledConfig(options.projectRoot, platform, env);
+    const value = record(raw, '');
+    for (const key of Object.keys(value)) {
+        if (!KNOWN_KEYS.has(key))
+            throw new TerminalConfigError(key, 'unknown key');
+    }
+    const enabled = optionalBoolean(value.enabled, 'enabled') ?? false;
+    const shell = optionalString(value.shell, 'shell') ?? defaultShell(platform, env);
+    const cwdRaw = optionalString(value.cwd, 'cwd') ?? '.';
+    const idleTimeout = optionalInteger(value.idleTimeout, 'idleTimeout', 0, 7 * 24 * 3600) ?? 900;
+    const maxSessions = optionalInteger(value.maxSessions, 'maxSessions', 1, 256) ?? 4;
+    const sshRaw = value.ssh ?? [];
+    if (!Array.isArray(sshRaw))
+        throw new TerminalConfigError('ssh', 'must be an array');
+    const names = new Set();
+    const ssh = sshRaw.map((entry, index) => {
+        const target = parseSshTarget(entry, `ssh[${index}]`);
+        if (names.has(target.name))
+            throw new TerminalConfigError(`ssh[${index}].name`, `duplicate target "${target.name}"`);
+        names.add(target.name);
+        return target;
+    });
+    return Object.freeze({
+        enabled,
+        shell,
+        cwd: resolve(options.projectRoot, cwdRaw),
+        idleTimeout,
+        maxSessions,
+        ssh: Object.freeze(ssh),
+    });
+}
+function disabledConfig(projectRoot, platform, env) {
+    return Object.freeze({
+        enabled: false,
+        shell: defaultShell(platform, env),
+        cwd: resolve(projectRoot),
+        idleTimeout: 900,
+        maxSessions: 4,
+        ssh: Object.freeze([]),
+    });
+}
+function parseSshTarget(raw, path) {
+    const value = record(raw, path);
+    for (const key of Object.keys(value)) {
+        if (!KNOWN_SSH_KEYS.has(key))
+            throw new TerminalConfigError(`${path}.${key}`, 'unknown key');
+    }
+    const name = requiredString(value.name, `${path}.name`);
+    if (!TARGET_NAME.test(name) || name === 'local') {
+        throw new TerminalConfigError(`${path}.name`, 'must match [A-Za-z0-9._-] (max 64) and must not be "local"');
+    }
+    const host = requiredString(value.host, `${path}.host`);
+    const port = optionalInteger(value.port, `${path}.port`, 1, 65535) ?? 22;
+    const username = requiredString(value.username, `${path}.username`);
+    const label = optionalString(value.label, `${path}.label`);
+    const privateKeyPath = optionalString(value.privateKeyPath, `${path}.privateKeyPath`);
+    const privateKeyEnv = optionalEnvName(value.privateKeyEnv, `${path}.privateKeyEnv`);
+    const passwordEnv = optionalEnvName(value.passwordEnv, `${path}.passwordEnv`);
+    const passphraseEnv = optionalEnvName(value.passphraseEnv, `${path}.passphraseEnv`);
+    if (privateKeyPath && privateKeyEnv) {
+        throw new TerminalConfigError(path, 'privateKeyPath and privateKeyEnv are mutually exclusive');
+    }
+    if (!privateKeyPath && !privateKeyEnv && !passwordEnv) {
+        throw new TerminalConfigError(path, 'one of privateKeyPath, privateKeyEnv or passwordEnv is required');
+    }
+    const fingerprintRaw = optionalString(value.hostFingerprint, `${path}.hostFingerprint`);
+    const hostFingerprint = fingerprintRaw === undefined ? undefined : normalizeFingerprint(fingerprintRaw);
+    if (fingerprintRaw !== undefined && !hostFingerprint) {
+        throw new TerminalConfigError(`${path}.hostFingerprint`, `must be "SHA256:<base64>"; ${FINGERPRINT_HINT}`);
+    }
+    const insecure = optionalBoolean(value.insecureAcceptAnyHostKey, `${path}.insecureAcceptAnyHostKey`) ?? false;
+    if (insecure && hostFingerprint) {
+        throw new TerminalConfigError(path, 'hostFingerprint and insecureAcceptAnyHostKey are mutually exclusive');
+    }
+    if (!hostFingerprint && !insecure) {
+        throw new TerminalConfigError(`${path}.hostFingerprint`, `is required to verify the SSH host key; ${FINGERPRINT_HINT} (or set insecureAcceptAnyHostKey: true to accept any key, unsafe)`);
+    }
+    return Object.freeze({
+        name, host, port, username,
+        ...(label ? { label } : {}),
+        ...(privateKeyPath ? { privateKeyPath } : {}),
+        ...(privateKeyEnv ? { privateKeyEnv } : {}),
+        ...(passwordEnv ? { passwordEnv } : {}),
+        ...(passphraseEnv ? { passphraseEnv } : {}),
+        ...(hostFingerprint ? { hostFingerprint } : {}),
+        ...(insecure ? { insecureAcceptAnyHostKey: true } : {}),
+    });
+}
+/** `SHA256:abc=` / `sha256:abc` → `SHA256:abc`; undefined when not a SHA256 base64 fingerprint. */
+export function normalizeFingerprint(value) {
+    const match = /^sha256:([A-Za-z0-9+/]+)=*$/iu.exec(value.trim());
+    if (!match)
+        return undefined;
+    const body = match[1];
+    // A SHA-256 digest is 32 bytes → 43 base64 chars without padding.
+    if (body.length !== 43)
+        return undefined;
+    return `SHA256:${body}`;
+}
+/** OpenSSH-style fingerprint of a raw host key blob. */
+export function hostKeyFingerprint(key) {
+    return `SHA256:${createHash('sha256').update(key).digest('base64').replace(/=+$/u, '')}`;
+}
+export class SshCredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SshCredentialError';
+    }
+}
+export function resolveKeyPath(path, projectRoot, home = homedir) {
+    if (path === '~')
+        return home();
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return resolve(home(), path.slice(2));
+    return isAbsolute(path) ? path : resolve(projectRoot, path);
+}
+/**
+ * Loads SSH credentials from env / local key file. Error messages name the
+ * variable or file, never its value.
+ */
+export async function resolveSshCredentials(target, sources) {
+    const env = sources.env ?? process.env;
+    const read = sources.readFile ?? ((path) => readFile(path));
+    let privateKey;
+    if (target.privateKeyPath) {
+        const path = resolveKeyPath(target.privateKeyPath, sources.projectRoot, sources.homedir);
+        try {
+            privateKey = await read(path);
+        }
+        catch {
+            throw new SshCredentialError(`无法读取私钥文件 ${target.privateKeyPath}`);
+        }
+    }
+    else if (target.privateKeyEnv) {
+        const value = env[target.privateKeyEnv];
+        if (!value)
+            throw new SshCredentialError(`环境变量 ${target.privateKeyEnv} 未设置`);
+        privateKey = value;
+    }
+    let passphrase;
+    if (target.passphraseEnv) {
+        passphrase = env[target.passphraseEnv];
+        if (!passphrase)
+            throw new SshCredentialError(`环境变量 ${target.passphraseEnv} 未设置`);
+    }
+    let password;
+    if (target.passwordEnv) {
+        password = env[target.passwordEnv] || undefined;
+        // With a key configured too, the password is only a fallback.
+        if (!password && privateKey === undefined)
+            throw new SshCredentialError(`环境变量 ${target.passwordEnv} 未设置`);
+    }
+    return Object.freeze({
+        ...(privateKey !== undefined ? { privateKey } : {}),
+        ...(passphrase ? { passphrase } : {}),
+        ...(password ? { password } : {}),
+    });
+}
+/** Cheap availability check for the targets list (no file contents are read). */
+export function sshCredentialProblem(target, env) {
+    if (target.privateKeyEnv && !env[target.privateKeyEnv])
+        return `环境变量 ${target.privateKeyEnv} 未设置`;
+    if (target.passphraseEnv && !env[target.passphraseEnv])
+        return `环境变量 ${target.passphraseEnv} 未设置`;
+    if (target.passwordEnv && !target.privateKeyPath && !target.privateKeyEnv && !env[target.passwordEnv]) {
+        return `环境变量 ${target.passwordEnv} 未设置`;
+    }
+    return undefined;
+}
+function record(value, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TerminalConfigError(path, 'must be an object');
+    }
+    return value;
+}
+function optionalBoolean(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new TerminalConfigError(path, 'must be a boolean');
+    return value;
+}
+function optionalString(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim())
+        throw new TerminalConfigError(path, 'must be a non-empty string');
+    return value.trim();
+}
+function requiredString(value, path) {
+    const result = optionalString(value, path);
+    if (result === undefined)
+        throw new TerminalConfigError(path, 'is required');
+    return result;
+}
+function optionalEnvName(value, path) {
+    const name = optionalString(value, path);
+    if (name !== undefined && !ENV_NAME.test(name))
+        throw new TerminalConfigError(path, 'must be an environment variable name');
+    return name;
+}
+function optionalInteger(value, path, min, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw new TerminalConfigError(path, `must be an integer between ${min} and ${max}`);
+    }
+    return value;
+}

package/lib/terminal/host.d.ts

@@ -0,0 +1,26 @@
+import { type TokenRegistry } from '@zhin.js/host-http';
+import type { ConsoleIamService } from '../iam/service.js';
+import { type ConsoleTerminalHandle, type InstallConsoleTerminalOptions, type TerminalHttpHost } from './index.js';
+/** The gateway's HTTP server, or an in-process `HttpHost`. */
+export interface ConsoleTerminalHost extends TerminalHttpHost {
+    readonly tokenRegistry: TokenRegistry;
+}
+export interface InstallHostConsoleTerminalOptions {
+    /** Raw host config `console.terminal`. */
+    readonly config: unknown;
+    readonly projectRoot: string;
+    readonly base?: string;
+    /** IAM service of this process; `undefined` when the database cannot hold accounts. */
+    readonly iam: () => ConsoleIamService | undefined;
+    readonly logger?: InstallConsoleTerminalOptions['logger'];
+    /** Test seams forwarded to {@link installConsoleTerminal}. */
+    readonly modules?: InstallConsoleTerminalOptions['modules'];
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * 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 declare function installHostConsoleTerminal(http: ConsoleTerminalHost, options: InstallHostConsoleTerminalOptions): ConsoleTerminalHandle;