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

package/lib/iam/setup-service.d.ts

@@ -0,0 +1,83 @@
+import { type DatabaseProbeResult, type ProbeDialect } from '@zhin.js/database';
+import { type ConsoleIamService, type ConsoleUserView } from './service.js';
+export type SetupDialect = ProbeDialect;
+export interface SetupDatabaseField {
+    readonly name: string;
+    readonly type: 'string' | 'integer' | 'enum';
+    readonly required: boolean;
+    readonly secret: boolean;
+    readonly default?: string | number;
+    readonly options?: readonly string[];
+    /** Env variable a secret is written to. */
+    readonly env?: string;
+}
+export interface SetupDriver {
+    readonly dialect: SetupDialect;
+    readonly label: string;
+    readonly description: string;
+    readonly available: boolean;
+    readonly missingPackage?: string;
+    readonly fields: readonly SetupDatabaseField[];
+}
+export interface SetupDatabaseSummary {
+    readonly dialect: string;
+    readonly source: 'default' | 'config';
+    /** Connection facts without secrets. */
+    readonly summary: Readonly<Record<string, string | number>>;
+}
+export interface SetupStatus {
+    readonly setupRequired: boolean;
+    readonly database: SetupDatabaseSummary;
+}
+export interface SetupDatabaseInput {
+    readonly dialect: unknown;
+    /** Field values; a secret may be a `${VAR}` reference to an existing variable instead. */
+    readonly connection?: unknown;
+}
+/** Config-file and dotenv access the setup flow needs (ConsoleConfigurationStore satisfies `config`). */
+export interface SetupConfigPort {
+    readDocument(): Promise<Record<string, unknown>>;
+    setKey(key: string, value: unknown): Promise<unknown>;
+}
+export interface SetupEnvFilePort {
+    read(): Promise<string>;
+    write(content: string): Promise<void>;
+}
+export interface ConsoleSetupServiceOptions {
+    readonly projectRoot: string;
+    readonly config: SetupConfigPort;
+    readonly envFile: SetupEnvFilePort;
+    /** The access-control service bound to the database currently in use. */
+    readonly iam: () => ConsoleIamService | undefined;
+    /** Variables for `${…}` expansion (process env + project dotenv layers). */
+    readonly environment?: () => Promise<Readonly<Record<string, string | undefined>>>;
+    readonly probe?: (dialect: SetupDialect, config: Record<string, unknown>) => Promise<DatabaseProbeResult>;
+    readonly driverAvailable?: (dialect: SetupDialect) => Promise<boolean>;
+}
+export declare const SETUP_NO_MIGRATION_NOTICE = "\u5207\u6362\u6570\u636E\u5E93\u4E0D\u4F1A\u8FC1\u79FB\u65E7\u5E93\u6570\u636E\uFF1A\u63D2\u4EF6\u6570\u636E\u4ECD\u7559\u5728\u539F\u6570\u636E\u5E93\u3002";
+/**
+ * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
+ * Database changes are written to the config file / `.env`; restarting is the caller's job.
+ */
+export declare class ConsoleSetupService {
+    #private;
+    constructor(options: ConsoleSetupServiceOptions);
+    setupRequired(): boolean;
+    status(): Promise<SetupStatus>;
+    drivers(): Promise<readonly SetupDriver[]>;
+    testDatabase(input: SetupDatabaseInput): Promise<DatabaseProbeResult>;
+    /** Tests, then writes `database` (secrets as `${…}` into `.env`). */
+    applyDatabase(input: SetupDatabaseInput): Promise<{
+        restartRequired: true;
+        notice: string;
+    }>;
+    createOwner(input: Readonly<{
+        username: unknown;
+        password: unknown;
+        displayName?: unknown;
+    }>): Promise<{
+        user: ConsoleUserView;
+    }>;
+}
+/** Sets `KEY=value` lines in dotenv text, keeping every other line. */
+export declare function upsertDotenv(source: string, updates: Readonly<Record<string, string>>): string;

package/lib/iam/setup-service.js

@@ -0,0 +1,206 @@
+import { isAbsolute, resolve } from 'node:path';
+import { isDatabaseDriverAvailable, probeDatabaseConnection, } from '@zhin.js/database';
+import { expandEnvironmentValue } from '@zhin.js/plugin-runtime';
+import { DATABASE_DIALECT_DEFINITIONS, validateDatabaseConfig, } from '@zhin.js/scaffold-wizard';
+import { IamError } from './service.js';
+import { IAM_DIALECTS } from './tables.js';
+const DEFAULT_SQLITE_FILE = '.zhin/data.sqlite';
+const SECRET_FIELDS = new Set(['password']);
+const ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/u;
+export const SETUP_NO_MIGRATION_NOTICE = '切换数据库不会迁移旧库数据：插件数据仍留在原数据库。';
+function envNameFor(field) {
+    return `ZHIN_DATABASE_${field.replace(/([a-z0-9])([A-Z])/gu, '$1_$2').toUpperCase()}`;
+}
+function fieldsOf(definition) {
+    const schema = definition.schema;
+    const required = new Set(schema.required ?? []);
+    return Object.freeze(Object.entries(schema.properties ?? {}).filter(([name]) => name !== 'dialect').flatMap(([name, property]) => {
+        if (property.type === 'object')
+            return [];
+        const options = Array.isArray(property.enum) ? property.enum : undefined;
+        // A MongoDB URL may embed credentials, so it is treated as a secret.
+        const secret = SECRET_FIELDS.has(name) || (definition.dialect === 'mongodb' && name === 'url');
+        let defaultValue = property.default;
+        if (definition.dialect === 'sqlite' && name === 'filename')
+            defaultValue = DEFAULT_SQLITE_FILE;
+        return [Object.freeze({
+                name,
+                type: options ? 'enum' : property.type === 'integer' ? 'integer' : 'string',
+                required: required.has(name) || property.minLength !== undefined,
+                secret,
+                ...(defaultValue === undefined ? {} : { default: defaultValue }),
+                ...(options ? { options: Object.freeze([...options]) } : {}),
+                ...(secret ? { env: envNameFor(name) } : {}),
+            })];
+    }));
+}
+const SETUP_DEFINITIONS = DATABASE_DIALECT_DEFINITIONS.filter(definition => IAM_DIALECTS.has(definition.dialect));
+/**
+ * The one setup flow (ADR 0049 §7): `/auth/setup*` and `zhin console init` are thin wrappers.
+ * Database changes are written to the config file / `.env`; restarting is the caller's job.
+ */
+export class ConsoleSetupService {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    setupRequired() {
+        const iam = this.#options.iam();
+        return !(iam?.initialized() ?? false);
+    }
+    async status() {
+        return Object.freeze({ setupRequired: this.setupRequired(), database: await this.#currentDatabase() });
+    }
+    async drivers() {
+        const available = this.#options.driverAvailable ?? ((dialect) => isDatabaseDriverAvailable(dialect));
+        return Promise.all(SETUP_DEFINITIONS.map(async (definition) => {
+            const dialect = definition.dialect;
+            const ok = await available(dialect);
+            return Object.freeze({
+                dialect,
+                label: definition.name,
+                description: definition.description,
+                available: ok,
+                ...(ok || !definition.driver ? {} : { missingPackage: definition.driver.package }),
+                fields: fieldsOf(definition),
+            });
+        }));
+    }
+    async testDatabase(input) {
+        this.#assertSetupOpen();
+        const prepared = await this.#prepare(input);
+        return this.#probe(prepared);
+    }
+    /** Tests, then writes `database` (secrets as `${…}` into `.env`). */
+    async applyDatabase(input) {
+        this.#assertSetupOpen();
+        const prepared = await this.#prepare(input);
+        const probe = await this.#probe(prepared);
+        if (!probe.ok)
+            throw new IamError('invalid_input', `数据库连接失败：${probe.error ?? 'unknown error'}`);
+        const envUpdates = {};
+        const block = { dialect: prepared.dialect };
+        for (const field of prepared.fields) {
+            const value = prepared.raw[field.name];
+            if (value === undefined || value === '')
+                continue;
+            if (field.secret && typeof value === 'string' && !ENV_REFERENCE.test(value)) {
+                envUpdates[field.env] = value;
+                block[field.name] = `\${${field.env}}`;
+            }
+            else {
+                block[field.name] = value;
+            }
+        }
+        if (Object.keys(envUpdates).length) {
+            await this.#options.envFile.write(upsertDotenv(await this.#options.envFile.read(), envUpdates));
+        }
+        await this.#options.config.setKey('database', block);
+        return Object.freeze({ restartRequired: true, notice: SETUP_NO_MIGRATION_NOTICE });
+    }
+    async createOwner(input) {
+        const iam = this.#options.iam();
+        if (!iam?.ready)
+            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+        if (iam.initialized())
+            throw new IamError('conflict', '已初始化：请改用 zhin console user 管理用户');
+        return { user: await iam.createOwner(input) };
+    }
+    #assertSetupOpen() {
+        if (!this.setupRequired())
+            throw new IamError('conflict', '已初始化：数据库已在使用中');
+    }
+    async #environment() {
+        return this.#options.environment ? this.#options.environment() : process.env;
+    }
+    async #prepare(input) {
+        const definition = SETUP_DEFINITIONS.find(candidate => candidate.dialect === input.dialect);
+        if (!definition)
+            throw new IamError('invalid_input', '不支持的数据库：可选 sqlite / mysql / pg / mongodb');
+        const connection = input.connection === undefined ? {} : input.connection;
+        if (!connection || typeof connection !== 'object' || Array.isArray(connection))
+            throw new IamError('invalid_input', 'connection 必须是对象');
+        const fields = fieldsOf(definition);
+        const raw = {};
+        for (const field of fields) {
+            let value = connection[field.name];
+            if (value === undefined || value === null || value === '')
+                value = field.default;
+            if (value === undefined)
+                continue;
+            if (field.type === 'integer') {
+                const number = typeof value === 'number' ? value : Number(String(value).trim());
+                if (!Number.isSafeInteger(number))
+                    throw new IamError('invalid_input', `${field.name} 必须是整数`);
+                value = number;
+            }
+            else if (typeof value !== 'string') {
+                throw new IamError('invalid_input', `${field.name} 必须是字符串`);
+            }
+            else {
+                value = field.secret ? value : value.trim();
+                if (typeof value === 'string' && /[\r\n]/u.test(value))
+                    throw new IamError('invalid_input', `${field.name} 不能包含换行`);
+            }
+            raw[field.name] = value;
+        }
+        const env = await this.#environment();
+        const expanded = expandEnvironmentValue({ dialect: definition.dialect, ...raw }, key => env[key]);
+        const issues = validateDatabaseConfig(expanded, env);
+        if (issues.length)
+            throw new IamError('invalid_input', issues.map(issue => issue.message).join('; ').slice(0, 500));
+        return { dialect: definition.dialect, fields, raw, expanded };
+    }
+    #probe(prepared) {
+        const { dialect: _dialect, ...config } = prepared.expanded;
+        if (prepared.dialect === 'sqlite' && typeof config.filename === 'string' && !isAbsolute(config.filename)) {
+            config.filename = resolve(this.#options.projectRoot, config.filename);
+        }
+        return (this.#options.probe ?? probeDatabaseConnection)(prepared.dialect, config);
+    }
+    async #currentDatabase() {
+        const document = await this.#options.config.readDocument();
+        const configured = document.database;
+        if (!configured || typeof configured !== 'object' || Array.isArray(configured)) {
+            return Object.freeze({ dialect: 'sqlite', source: 'default', summary: Object.freeze({ filename: DEFAULT_SQLITE_FILE }) });
+        }
+        const value = configured;
+        const dialect = typeof value.dialect === 'string' ? value.dialect : 'sqlite';
+        const summary = {};
+        for (const key of ['filename', 'host', 'port', 'user', 'database', 'dbName']) {
+            const item = value[key];
+            if (typeof item === 'string' || typeof item === 'number')
+                summary[key] = item;
+        }
+        if (typeof value.url === 'string')
+            summary.url = value.url.replace(/\/\/[^@/]*@/u, '//***@');
+        return Object.freeze({ dialect, source: 'config', summary: Object.freeze(summary) });
+    }
+}
+/** Sets `KEY=value` lines in dotenv text, keeping every other line. */
+export function upsertDotenv(source, updates) {
+    const lines = source.length ? source.split(/\r?\n/u) : [];
+    if (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    const pending = new Map(Object.entries(updates));
+    const next = lines.map(line => {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u.exec(line);
+        if (!match || !pending.has(match[1]))
+            return line;
+        const value = pending.get(match[1]);
+        pending.delete(match[1]);
+        return `${match[1]}=${quoteDotenv(value)}`;
+    });
+    for (const [key, value] of pending)
+        next.push(`${key}=${quoteDotenv(value)}`);
+    return `${next.join('\n')}\n`;
+}
+function quoteDotenv(value) {
+    if (/[\r\n]/u.test(value))
+        throw new IamError('invalid_input', '机密值不能包含换行');
+    if (!value.includes("'"))
+        return `'${value}'`;
+    if (!value.includes('"') && !value.includes('\\'))
+        return `"${value}"`;
+    throw new IamError('invalid_input', '机密值不能同时包含单引号与双引号；请改用 --database-password-env 引用已有变量');
+}

package/lib/iam/tables.d.ts

@@ -0,0 +1,20 @@
+/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+export declare const IAM_TABLES: Readonly<{
+    readonly users: "console_users";
+    readonly roles: "console_roles";
+    readonly bindings: "console_role_bindings";
+    readonly sessions: "console_sessions";
+    readonly tokens: "console_api_tokens";
+    readonly audit: "console_audit_log";
+}>;
+export declare const IAM_TABLE_DEFINITIONS: Readonly<Record<string, Record<string, unknown>>>;
+/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
+export declare const IAM_DIALECTS: ReadonlySet<string>;
+export interface IamTableHost {
+    readonly dialect: string;
+    readonly started: boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+}
+/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
+export declare function defineConsoleIamTables(host: IamTableHost): boolean;

package/lib/iam/tables.js

@@ -0,0 +1,82 @@
+/** Console access-control tables (ADR 0049 §2). Defined by the composition root before DB start. */
+export const IAM_TABLES = Object.freeze({
+    users: 'console_users',
+    roles: 'console_roles',
+    bindings: 'console_role_bindings',
+    sessions: 'console_sessions',
+    tokens: 'console_api_tokens',
+    audit: 'console_audit_log',
+});
+const id = { type: 'text', length: 64, primary: true, nullable: false };
+const text = (nullable = false) => ({ type: 'text', nullable });
+const time = (nullable = false) => ({ type: 'bigint', nullable });
+export const IAM_TABLE_DEFINITIONS = Object.freeze({
+    [IAM_TABLES.users]: {
+        id,
+        username: { type: 'text', length: 64, unique: true, nullable: false },
+        display_name: text(),
+        password_hash: text(),
+        disabled: { type: 'integer', nullable: false, default: 0 },
+        password_changed_at: time(),
+        created_at: time(),
+        updated_at: time(),
+    },
+    [IAM_TABLES.roles]: {
+        id,
+        name: { type: 'text', length: 64, unique: true, nullable: false },
+        description: text(),
+        builtin: { type: 'integer', nullable: false, default: 0 },
+        permissions: text(),
+    },
+    [IAM_TABLES.bindings]: {
+        id,
+        user_id: { type: 'text', length: 64, nullable: false },
+        role_id: { type: 'text', length: 64, nullable: false },
+        scope_kind: { type: 'text', length: 16, nullable: false },
+        scope_key: text(true),
+    },
+    [IAM_TABLES.sessions]: {
+        id,
+        user_id: { type: 'text', length: 64, nullable: false },
+        created_at: time(),
+        expires_at: time(),
+        last_seen_at: time(),
+        ip: text(true),
+        user_agent: text(true),
+    },
+    [IAM_TABLES.tokens]: {
+        id,
+        user_id: { type: 'text', length: 64, nullable: false },
+        name: text(),
+        token_hash: { type: 'text', length: 64, unique: true, nullable: false },
+        permissions: text(true),
+        expires_at: time(true),
+        last_used_at: time(true),
+        created_at: time(),
+    },
+    [IAM_TABLES.audit]: {
+        id,
+        at: time(),
+        actor: text(),
+        action: text(),
+        target: text(true),
+        outcome: { type: 'text', length: 16, nullable: false },
+        detail: text(true),
+        ip: text(true),
+    },
+});
+/** Dialects that can hold accounts (redis / memory cannot, ADR 0049 §8). */
+export const IAM_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
+/** Idempotent; must run before the database starts. Returns false for unsupported dialects. */
+export function defineConsoleIamTables(host) {
+    if (!IAM_DIALECTS.has(host.dialect))
+        return false;
+    if (host.started)
+        return true;
+    const existing = new Set(host.tables());
+    for (const [name, definition] of Object.entries(IAM_TABLE_DEFINITIONS)) {
+        if (!existing.has(name))
+            host.define(name, definition);
+    }
+    return true;
+}

package/lib/iam.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/iam` — Console access control (ADR 0049). */
+export * from './iam/index.js';

package/lib/iam.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/iam` — Console access control (ADR 0049). */
+export * from './iam/index.js';

package/lib/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zhin.js management gateway (ADR 0054). It must not import `zhin.js` or any IM layer.
+ *
+ * Until the gateway process exists (B1.1–B1.4) this package is a library: the Zhin instance
+ * (`zhin.js/instance`) still installs Console access control and the terminal into its in-process
+ * HTTP host, and both the instance and `@zhin.js/cli` share the project-file services below.
+ * Import the narrow subpaths (`@zhin.js/gateway/<area>`) to avoid loading unrelated areas.
+ * @module @zhin.js/gateway
+ */
+export * from './iam.js';
+export * from './terminal.js';
+export * from './config.js';
+export * from './plugin-management.js';
+export * from './project.js';
+export * from './supervisor.js';
+export * from './usage.js';
+export * from './onboarding.js';
+export * from './http.js';
+export * from './packages.js';
+export * from './database.js';
+export * from './local.js';
+export * from './server.js';

package/lib/index.js

@@ -0,0 +1,22 @@
+/**
+ * Zhin.js management gateway (ADR 0054). It must not import `zhin.js` or any IM layer.
+ *
+ * Until the gateway process exists (B1.1–B1.4) this package is a library: the Zhin instance
+ * (`zhin.js/instance`) still installs Console access control and the terminal into its in-process
+ * HTTP host, and both the instance and `@zhin.js/cli` share the project-file services below.
+ * Import the narrow subpaths (`@zhin.js/gateway/<area>`) to avoid loading unrelated areas.
+ * @module @zhin.js/gateway
+ */
+export * from './iam.js';
+export * from './terminal.js';
+export * from './config.js';
+export * from './plugin-management.js';
+export * from './project.js';
+export * from './supervisor.js';
+export * from './usage.js';
+export * from './onboarding.js';
+export * from './http.js';
+export * from './packages.js';
+export * from './database.js';
+export * from './local.js';
+export * from './server.js';

package/lib/local/client.d.ts

@@ -0,0 +1,71 @@
+import type { GatewayPackageEvent, GatewayRpcErrorDetails } from '@zhin.js/console-protocol';
+import { type LocalGatewayErrorCode, type LocalGatewayInfoResult } from './protocol.js';
+/**
+ * - `not_running`: no socket, or a stale one nobody listens on;
+ * - `not_owner`: the socket belongs to (or is only accessible by) another user;
+ * - `unreachable`: a socket exists but the gateway does not answer;
+ * - `protocol`: the peer sent something that is not the gateway protocol.
+ */
+export type LocalGatewayClientErrorCode = 'not_running' | 'not_owner' | 'unreachable' | 'protocol';
+export declare class LocalGatewayClientError extends Error {
+    readonly code: LocalGatewayClientErrorCode;
+    constructor(code: LocalGatewayClientErrorCode, message: string, options?: ErrorOptions);
+}
+/** The gateway answered `{ ok: false }`. */
+export declare class LocalGatewayRpcError extends Error {
+    readonly code: LocalGatewayErrorCode;
+    readonly status: number;
+    readonly details: GatewayRpcErrorDetails;
+    constructor(code: LocalGatewayErrorCode, message: string, status: number, details?: GatewayRpcErrorDetails);
+}
+export interface LocalGatewayClientOptions {
+    readonly root: string;
+    /** Overrides the endpoint (default: `gateway.json#socket`, else {@link gatewaySocketPath}). */
+    readonly path?: string;
+    /**
+     * Handshake key the endpoint must prove (default: `gateway.json#handshakeKey` when the endpoint
+     * is the one recorded there). An endpoint that cannot prove it is refused (`not_owner`).
+     */
+    readonly handshakeKey?: string;
+    /** Current user id; `undefined` skips the owner check. Default `process.getuid()`. */
+    readonly uid?: () => number | undefined;
+    readonly connectTimeoutMs?: number;
+}
+export interface LocalRequestOptions {
+    readonly onEvent?: (event: GatewayPackageEvent) => void;
+    /** Default: none (package transactions can take minutes). */
+    readonly timeoutMs?: number;
+}
+export declare class LocalGatewayClient {
+    #private;
+    readonly path: string;
+    private constructor();
+    /** Connects to the project's gateway; see {@link LocalGatewayClientErrorCode} for failures. */
+    static connect(options: LocalGatewayClientOptions): Promise<LocalGatewayClient>;
+    request<T = unknown>(type: string, data?: unknown, options?: LocalRequestOptions): Promise<T>;
+    info(timeoutMs?: number): Promise<LocalGatewayInfoResult>;
+    close(): void;
+}
+/**
+ * The running gateway's info, or `undefined` when no gateway runs for `root`. Ownership and
+ * reachability problems are thrown (a caller must not fall back to working on the files then).
+ */
+export declare function probeLocalGateway(options: LocalGatewayClientOptions): Promise<LocalGatewayInfoResult | undefined>;
+/** The subset of `fetch` the CLI's Host clients use. */
+export type LocalGatewayFetch = (input: string | URL, init?: Readonly<{
+    method?: string;
+    body?: string | null;
+    signal?: AbortSignal | null;
+    headers?: unknown;
+}>) => Promise<Response>;
+/** The Bearer credential of `Authorization` in `headers` (a `Headers`, record or entry list). */
+export declare function bearerFromHeaders(headers: unknown): string | undefined;
+/**
+ * A `fetch` that sends `{base}/…` requests over the local control socket
+ * (`gateway.http.request`) instead of HTTP (ADR 0054 §6). Only the path and query of the URL are
+ * used. Without an `Authorization: Bearer` header the gateway runs the request as the local
+ * owner, so no Console token is needed; with one (an explicit `ZHIN_CONSOLE_TOKEN`), the gateway
+ * authenticates that credential and runs — and audits — the request as its principal. A gateway
+ * that is not running rejects like a refused connection (`cause.code === 'ECONNREFUSED'`).
+ */
+export declare function createLocalGatewayFetch(options: LocalGatewayClientOptions): LocalGatewayFetch;