@zhin.js/gateway 1.1.2 → 1.3.0

package/lib/iam/index.d.ts

@@ -1,7 +1,8 @@
 export { installConsoleIam, projectEnvironment, type ConsoleIamInstallation, type InstallConsoleIamOptions } from './install.js';
-export { accountInputProblem, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
-export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
-export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { accountInputProblem, IAM_UNAVAILABLE_PUBLIC_MESSAGE, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
+export { ConsoleSetupService, SETUP_CONSOLE_ROLE_NOTICE, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_TABLE_DEFINITIONS, IAM_TABLES, type IamTableHost } from './tables.js';
+export { importLegacyIamTables, ensureGatewayStoreMarker, isTransientLegacyImportError, LEGACY_IMPORT_FAILURE_KEY, resetGatewayStore, type LegacyImportFailure, inspectLegacyIamImport, LEGACY_IMPORT_KEY, LegacyImportError, legacyImportSettled, readLegacyImportRecord, revertLegacyIamImport, tableChecksum, type LegacyIamSource, type LegacyImportErrorCode, type LegacyImportInspection, type LegacyImportOptions, type LegacyImportRecord, type LegacySourceSummary, type RevertLegacyImportResult, } from './legacy-import.js';
 export { dispatchIamRpc, isIamRpc } from './rpc.js';
 export { registerConsoleAuthRoutes } from './routes.js';
 export { LoginRateLimiter } from './rate-limit.js';

package/lib/iam/index.js

@@ -1,7 +1,8 @@
 export { installConsoleIam, projectEnvironment } from './install.js';
-export { accountInputProblem, ConsoleIamService, IamError, } from './service.js';
-export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
-export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { accountInputProblem, IAM_UNAVAILABLE_PUBLIC_MESSAGE, ConsoleIamService, IamError, } from './service.js';
+export { ConsoleSetupService, SETUP_CONSOLE_ROLE_NOTICE, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { importLegacyIamTables, ensureGatewayStoreMarker, isTransientLegacyImportError, LEGACY_IMPORT_FAILURE_KEY, resetGatewayStore, inspectLegacyIamImport, LEGACY_IMPORT_KEY, LegacyImportError, legacyImportSettled, readLegacyImportRecord, revertLegacyIamImport, tableChecksum, } from './legacy-import.js';
 export { dispatchIamRpc, isIamRpc } from './rpc.js';
 export { registerConsoleAuthRoutes } from './routes.js';
 export { LoginRateLimiter } from './rate-limit.js';

package/lib/iam/install.d.ts

@@ -1,16 +1,23 @@
 import type { HttpHost } from '@zhin.js/host-http';
-import { ConsoleIamService, type IamDatabase } from './service.js';
+import type { ProjectDatabaseConfig } from '../database/config.js';
+import { type GatewayStore } from '../database/gateway-store.js';
+import { ConsoleIamService } from './service.js';
 import { ConsoleSetupService, type SetupConfigPort } from './setup-service.js';
-import { type IamTableHost } from './tables.js';
 export interface InstallConsoleIamOptions {
-    /** Process database; tables are defined here, so call before it starts. */
-    readonly database: IamDatabase & IamTableHost;
     /** Config file writer (ConsoleConfigurationStore). */
     readonly configStore: SetupConfigPort;
     readonly projectRoot: string;
+    /**
+     * The project database the old `console_*` tables are imported from (ADR 0059 §3), opened on a
+     * connection of its own — never the process DatabaseHost.
+     */
+    readonly projectDatabase: () => Promise<ProjectDatabaseConfig>;
+    /** Opens the gateway store (default `.zhin/gateway.db` of the project; tests pass their own). */
+    readonly openStore?: () => Promise<GatewayStore>;
     readonly apiBase?: string;
     readonly logger?: Readonly<{
         warn(message: string): void;
+        info?(message: string): void;
     }>;
     /** Process restart after the setup wizard changed the database. */
     readonly requestRestart?: () => void;
@@ -20,16 +27,15 @@ export interface InstallConsoleIamOptions {
 export interface ConsoleIamInstallation {
     readonly service: ConsoleIamService;
     readonly setup: ConsoleSetupService;
-    /** Whether this database dialect can hold accounts. */
-    readonly supported: boolean;
-    /** Call once the database has started (idempotent). */
+    /** Opens the gateway store, imports the old tables, starts the service (idempotent). */
     activate(): Promise<void>;
-    dispose(): void;
+    dispose(): Promise<void>;
 }
 /**
- * The single wiring point of Console access control (ADR 0049) into a Host process:
- * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
- * Depends only on host-http, the database port and config/env file IO.
+ * Console access control (ADR 0049) inside one process — a standalone instance (`zhin start
+ * --standalone`, development and tests) that has no gateway. It opens `.zhin/gateway.db` itself,
+ * so there is no process isolation from plugins there; under the gateway the instance never
+ * calls this. Wires the session resolver behind `http.tokenRegistry`, `/auth/*` and the setup flow.
  */
 export declare function installConsoleIam(http: HttpHost, options: InstallConsoleIamOptions): ConsoleIamInstallation;
 /** process env overlaid with the project `.env` (what `${…}` in config resolves against). */

package/lib/iam/install.js

@@ -1,23 +1,33 @@
 import { join } from 'node:path';
 import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { openGatewayStore } from '../database/gateway-store.js';
 import { normalizeBase } from '../http-response.js';
+import { importLegacyIamTables, LegacyImportError } from './legacy-import.js';
 import { registerConsoleAuthRoutes } from './routes.js';
 import { ConsoleIamService } from './service.js';
 import { ConsoleSetupService } from './setup-service.js';
-import { defineConsoleIamTables } from './tables.js';
 /**
- * The single wiring point of Console access control (ADR 0049) into a Host process:
- * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
- * Depends only on host-http, the database port and config/env file IO.
+ * Console access control (ADR 0049) inside one process — a standalone instance (`zhin start
+ * --standalone`, development and tests) that has no gateway. It opens `.zhin/gateway.db` itself,
+ * so there is no process isolation from plugins there; under the gateway the instance never
+ * calls this. Wires the session resolver behind `http.tokenRegistry`, `/auth/*` and the setup flow.
  */
 export function installConsoleIam(http, options) {
-    const supported = defineConsoleIamTables(options.database);
+    let store;
+    let pending = 'Console 访问控制正在启动';
+    let pendingCode = 'starting';
+    const database = Object.freeze({
+        get started() { return store?.started ?? false; },
+        models: Object.freeze({ get: (name) => store?.models.get(name) }),
+    });
     const service = new ConsoleIamService({
-        database: options.database,
+        database,
         projectRoot: options.projectRoot,
         onError: error => options.logger?.warn(`console iam: ${error instanceof Error ? error.message : String(error)}`),
         // Installed on the token registry by the runtime composition root; empty until then.
         pluginPermissions: () => http.tokenRegistry.pluginPermissions(),
+        unavailable: () => pending,
+        unavailableCode: () => pendingCode,
     });
     const setup = new ConsoleSetupService({
         projectRoot: options.projectRoot,
@@ -26,18 +36,14 @@ export function installConsoleIam(http, options) {
             read: () => readEnvFile(options.projectRoot, '.env'),
             write: content => writeEnvFile(options.projectRoot, '.env', content),
         },
-        iam: () => (supported ? service : undefined),
+        iam: () => service,
         environment: options.environment ?? (() => projectEnvironment(options.projectRoot)),
     });
-    const disposers = [];
-    if (supported)
-        disposers.push(http.tokenRegistry.useAccessProvider(service));
-    else
-        options.logger?.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
+    const disposers = [http.tokenRegistry.useAccessProvider(service)];
     disposers.push(...registerConsoleAuthRoutes({
         http,
         base: normalizeBase(options.apiBase ?? '/api'),
-        iam: () => (supported ? service : undefined),
+        iam: () => service,
         setup,
         ...(options.requestRestart ? { requestRestart: options.requestRestart } : {}),
     }));
@@ -45,17 +51,32 @@ export function installConsoleIam(http, options) {
     return Object.freeze({
         service,
         setup,
-        supported,
         activate() {
-            if (!supported)
-                return Promise.resolve();
-            activation ??= service.start();
+            activation ??= (async () => {
+                try {
+                    store = await (options.openStore ?? (() => openGatewayStore(options.projectRoot)))();
+                    await importLegacyIamTables({
+                        store,
+                        projectRoot: options.projectRoot,
+                        projectDatabase: options.projectDatabase,
+                        logger: { info: message => options.logger?.info?.(message), warn: message => options.logger?.warn(message) },
+                    });
+                    await service.start();
+                    pending = undefined;
+                }
+                catch (error) {
+                    pending = `Console 访问控制不可用：${error instanceof Error ? error.message : String(error)}`;
+                    pendingCode = error instanceof LegacyImportError && (error.code === 'store_lost' || error.code === 'store_mismatch') ? error.code : 'migration_failed';
+                    options.logger?.warn(`console iam: ${pending}`);
+                }
+            })();
             return activation;
         },
-        dispose() {
+        async dispose() {
             service.stop();
             for (const dispose of disposers.reverse())
                 dispose();
+            await store?.close().catch(() => undefined);
         },
     });
 }

package/lib/iam/legacy-import.d.ts

@@ -0,0 +1,151 @@
+import type { ProjectDatabaseConfig } from '../database/config.js';
+import type { GatewayStore } from '../database/gateway-store.js';
+import { type ProjectDatabaseTransaction, type StoreMarker, type TableRows } from '../database/project-database.js';
+export declare const LEGACY_IMPORT_KEY = "legacy_import";
+/** Where the rows came from, without secrets. */
+export interface LegacySourceSummary {
+    readonly dialect: string;
+    readonly location: string;
+}
+export type LegacyImportRecord = Readonly<{
+    status: 'fresh';
+    at: number;
+    source: LegacySourceSummary;
+    reason: 'no-tables' | 'no-database-file' | 'non-relational' | 'reset-store';
+}> | Readonly<{
+    status: 'copied';
+    at: number;
+    source: LegacySourceSummary;
+    counts: Readonly<Record<string, number>>;
+    checksums: Readonly<Record<string, string>>;
+    /** Columns each checksum covers. */
+    columns: Readonly<Record<string, readonly string[]>>;
+    /** Project-relative directory of `console-tables.json`. */
+    backup: string;
+}> | Readonly<{
+    status: 'done';
+    at: number;
+    copiedAt: number;
+    source: LegacySourceSummary;
+    counts: Readonly<Record<string, number>>;
+    checksums: Readonly<Record<string, string>>;
+    columns: Readonly<Record<string, readonly string[]>>;
+    backup: string;
+    /** The old tables changed between copy and drop; `changedExport` holds them as they were dropped. */
+    changed: boolean;
+    changedExport?: string;
+}>;
+/**
+ * `unavailable` (project database unreachable or busy, and every error a driver reports — a
+ * unique-key violation while copying included: retried with backoff); the rest need the
+ * operator and are not retried automatically: `conflict` (gateway.db holds data without a record,
+ * or the project database already holds rows on revert), `mismatch` (copy did not read back
+ * identically), `invalid` (the old rows cannot be copied: a table without an `id` column),
+ * `unsupported`, `store_lost` (the project database's marker says the accounts are in another
+ * gateway.db: the store was lost or replaced) and `store_mismatch` (marker of a different store).
+ */
+export type LegacyImportErrorCode = 'unavailable' | 'conflict' | 'mismatch' | 'invalid' | 'unsupported' | 'store_lost' | 'store_mismatch';
+export declare class LegacyImportError extends Error {
+    readonly code: LegacyImportErrorCode;
+    constructor(code: LegacyImportErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Whether retrying later may help (the gateway backs off); otherwise the operator must act. */
+export declare function isTransientLegacyImportError(error: unknown): boolean;
+/** `gateway_meta` key of the last non-transient failure (for `zhin doctor`; cleared on success). */
+export declare const LEGACY_IMPORT_FAILURE_KEY = "legacy_import_failure";
+export interface LegacyImportFailure {
+    readonly code: LegacyImportErrorCode;
+    readonly message: string;
+    readonly at: number;
+}
+/** What the import reads and drops (ProjectDatabase satisfies it). */
+export interface LegacyIamSource {
+    readonly dialect: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    tableExists(names: readonly string[]): Promise<string[]>;
+    readSnapshot(tables: readonly string[]): Promise<TableRows>;
+    dropTables(tables: readonly string[]): Promise<void>;
+    /** The marker (ADR 0059 §3 修订); a source without these methods has no marker. */
+    readStoreMarker?(): Promise<StoreMarker | undefined>;
+    writeStoreMarker?(marker: StoreMarker): Promise<void>;
+    deleteStoreMarker?(): Promise<void>;
+}
+export interface LegacyImportOptions {
+    readonly store: GatewayStore;
+    readonly projectRoot: string;
+    /** The project database block (resolved only when the state is still undecided). */
+    readonly projectDatabase: () => Promise<ProjectDatabaseConfig>;
+    /** Opens the project database (default: a ProjectDatabase that defines no table). */
+    readonly openSource?: (config: ProjectDatabaseConfig) => LegacyIamSource;
+    readonly now?: () => number;
+    readonly logger?: Readonly<{
+        info?(message: string): void;
+        warn?(message: string): void;
+    }>;
+}
+export declare function readLegacyImportRecord(store: GatewayStore, trx?: ProjectDatabaseTransaction): Promise<LegacyImportRecord | undefined>;
+/** True when the record lets Console access control open. */
+export declare function legacyImportSettled(record: LegacyImportRecord | undefined): boolean;
+/**
+ * SHA-256 of the rows ordered by `id` (code-unit order), as canonical JSON of `[columns, rows]`
+ * with integers as decimal strings and null kept: the same rows read from any dialect hash equal.
+ */
+export declare function tableChecksum(table: string, rows: readonly Record<string, unknown>[], columns?: readonly string[]): string;
+/**
+ * Brings `gateway_meta.legacy_import` to `fresh` or `done` (or throws). Runs under the gateway
+ * store's write lock (`BEGIN IMMEDIATE`), so the gateway and the CLI never import twice. Once
+ * settled, it writes the marker (`zhin_gateway_store`) into the project database: a later empty or
+ * foreign gateway.db is refused (`store_lost` / `store_mismatch`) instead of reopening setup.
+ * Non-transient failures are recorded in `gateway_meta.legacy_import_failure` for `zhin doctor`.
+ */
+export declare function importLegacyIamTables(options: LegacyImportOptions): Promise<LegacyImportRecord>;
+/**
+ * Settled store: the marker in the project database must name this store. Missing → written (best
+ * effort; also for a SQLite file that did not exist at the first start). A different store id →
+ * `store_mismatch`. An unreachable project database is not an error here: this gateway.db is
+ * intact, and the marker is checked again on the next start.
+ */
+/**
+ * Writes the marker if it is missing for a settled store (the gateway calls it again after the
+ * first owner was created and after the supervised instance first reported ready). A store whose
+ * import has not settled is left alone; errors are logged, never thrown, except `store_mismatch`.
+ */
+export declare function ensureGatewayStoreMarker(options: LegacyImportOptions): Promise<void>;
+/**
+ * `zhin console init --reset-store`: the operator accepts that the Console accounts of the
+ * previous gateway.db are gone (ADR 0059 §3 修订). Marks this store as settled (`fresh`, reason
+ * `reset-store`) when it has no record, rewrites the project database's marker to this store and
+ * records the reset in this store's audit log. Run only while no gateway runs.
+ */
+export declare function resetGatewayStore(options: LegacyImportOptions): Promise<{
+    readonly previousStoreId?: string;
+    readonly storeId: string;
+}>;
+export interface LegacyImportInspection {
+    readonly record: LegacyImportRecord | undefined;
+    /** The last failure that needs the operator (not retried automatically). */
+    readonly failure?: LegacyImportFailure;
+    /** Gateway tables present in the project database again (undefined: not checked or unreachable). */
+    readonly reappeared?: readonly string[];
+    /** Why the project database could not be checked. */
+    readonly problem?: string;
+}
+/** For `zhin doctor`: the record, and whether old tables showed up again in the project database. */
+export declare function inspectLegacyIamImport(options: LegacyImportOptions): Promise<LegacyImportInspection>;
+export interface RevertLegacyImportResult {
+    readonly counts: Readonly<Record<string, number>>;
+    /** What the operator still has to do (e.g. drop the restricted Console account). */
+    readonly warnings: readonly string[];
+    /** Project-relative directory with the gateway.db copy taken before the revert. */
+    readonly backup: string;
+}
+/**
+ * `zhin console migrate --revert` (before installing a version older than ADR 0059): writes the
+ * gateway's tables back into the project database, verifies them, then empties them in
+ * gateway.db and clears the record. The project database must not hold rows in those tables.
+ * Run only while no gateway runs.
+ */
+export declare function revertLegacyIamImport(options: LegacyImportOptions): Promise<RevertLegacyImportResult>;