@zhin.js/gateway 1.1.2 → 1.2.0

package/lib/iam/legacy-import.js

@@ -0,0 +1,600 @@
+/**
+ * Importing the Console access-control tables an earlier version kept in the project database
+ * into `.zhin/gateway.db` (ADR 0059 §3), and putting them back (`zhin console migrate --revert`,
+ * required before a downgrade). One function serves the gateway (while it connects), `zhin console
+ * …` while no gateway runs, and a standalone instance.
+ *
+ * `gateway_meta.legacy_import` records the state: absent (not decided yet) → `fresh` (nothing to
+ * import) | `copied` (rows are in gateway.db, old tables not dropped yet) → `done`. Until the
+ * state is `fresh` or `done`, Console access control stays closed: an empty gateway.db must never
+ * be taken for "no owner yet".
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { ProjectDatabase, quoteTableName, } from '../database/project-database.js';
+import { defineConsoleIamTables, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export const LEGACY_IMPORT_KEY = 'legacy_import';
+const TABLES = Object.freeze(Object.values(IAM_TABLES));
+/** Dialects that may hold the old tables (redis / memory never could). */
+const SOURCE_DIALECTS = new Set(['sqlite', 'mysql', 'pg', 'mongodb']);
+const INSERT_BATCH = 500;
+export class LegacyImportError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'LegacyImportError';
+    }
+}
+/** Whether retrying later may help (the gateway backs off); otherwise the operator must act. */
+export function isTransientLegacyImportError(error) {
+    return !(error instanceof LegacyImportError) || error.code === 'unavailable';
+}
+/** `gateway_meta` key of the last non-transient failure (for `zhin doctor`; cleared on success). */
+export const LEGACY_IMPORT_FAILURE_KEY = 'legacy_import_failure';
+/** A `LegacyImportError` for whatever went wrong while copying / dropping. */
+function classify(error) {
+    if (error instanceof LegacyImportError)
+        return error;
+    // Only what this module decided is permanent (conflict, mismatch, invalid rows, store_lost /
+    // store_mismatch). Any driver error — connection terminated, statement / lock timeout,
+    // serialization failure, deadlock, too many connections, a network error — may pass: retried.
+    return new LegacyImportError('unavailable', `项目数据库暂时不可用：${errorText(error)}`, { cause: error });
+}
+export async function readLegacyImportRecord(store, trx) {
+    return store.getMeta(LEGACY_IMPORT_KEY, trx);
+}
+/** True when the record lets Console access control open. */
+export function legacyImportSettled(record) {
+    return record?.status === 'fresh' || record?.status === 'done';
+}
+function summarize(projectRoot, config) {
+    const value = config;
+    if (config.dialect === 'sqlite') {
+        const filename = String(value.filename ?? '');
+        return Object.freeze({ dialect: 'sqlite', location: isAbsolute(filename) ? relative(projectRoot, filename) || filename : filename });
+    }
+    if (config.dialect === 'mongodb') {
+        const url = typeof value.url === 'string' ? value.url.replace(/\/\/[^@/]*@/u, '//') : '';
+        return Object.freeze({ dialect: 'mongodb', location: `${url}/${String(value.dbName ?? '')}` });
+    }
+    const host = value.host ?? (typeof value.connectionString === 'string' || typeof value.uri === 'string' ? '(connection string)' : 'localhost');
+    return Object.freeze({ dialect: config.dialect, location: `${String(host)}${value.port ? `:${String(value.port)}` : ''}/${String(value.database ?? '')}` });
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const columnType = (table, column) => {
+    const definition = (IAM_TABLE_DEFINITIONS[table] ?? {})[column];
+    return definition?.type;
+};
+/** A cell as the checksum sees it: integers as decimal strings, text as strings, null kept. */
+function canonicalCell(table, column, value) {
+    if (value === null || value === undefined)
+        return null;
+    const type = columnType(table, column);
+    if (type === 'integer' || type === 'bigint') {
+        if (typeof value === 'boolean')
+            return value ? '1' : '0';
+        const text = typeof value === 'bigint' ? value.toString() : String(value).trim();
+        if (/^-?\d+$/u.test(text))
+            return BigInt(text).toString();
+        if (typeof value === 'number' && Number.isFinite(value))
+            return String(value);
+        return text;
+    }
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/** A cell as written to the target (integers as numbers, or bigint past 2^53). */
+function targetCell(table, column, value) {
+    const canonical = canonicalCell(table, column, value);
+    if (canonical === null)
+        return null;
+    const type = columnType(table, column);
+    if ((type === 'integer' || type === 'bigint') && /^-?\d+$/u.test(canonical)) {
+        const number = Number(canonical);
+        return Number.isSafeInteger(number) ? number : BigInt(canonical);
+    }
+    return canonical;
+}
+/** Target columns the source rows carry (`id` required). */
+function sharedColumns(table, rows) {
+    const present = new Set(rows.flatMap(row => Object.keys(row)));
+    return Object.keys(IAM_TABLE_DEFINITIONS[table] ?? {}).filter(column => present.has(column));
+}
+function canonicalRows(table, rows, columns) {
+    return rows.map(row => columns.map(column => canonicalCell(table, column, row[column])))
+        .sort((left, right) => {
+        const a = String(left[columns.indexOf('id')] ?? '');
+        const b = String(right[columns.indexOf('id')] ?? '');
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+/**
+ * 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 function tableChecksum(table, rows, columns = sharedColumns(table, rows)) {
+    const sorted = [...columns].sort();
+    return createHash('sha256').update(JSON.stringify([sorted, canonicalRows(table, rows, sorted)])).digest('hex');
+}
+function jsonReplacer(_key, value) {
+    return typeof value === 'bigint' ? value.toString() : value;
+}
+/**
+ * The backup directory of a legacy snapshot, named after its content: a retried import of the
+ * same rows reuses it instead of writing another full copy every retry.
+ */
+function snapshotBackupDirectory(projectRoot, rows) {
+    const digest = createHash('sha256').update(JSON.stringify(rows, jsonReplacer)).digest('hex').slice(0, 16);
+    const directory = join('.zhin', 'backups', `gateway-db-legacy-${digest}`);
+    const existing = existsSync(join(projectRoot, directory, 'console-tables.json'));
+    if (!existing)
+        mkdirSync(join(projectRoot, directory), { recursive: true, mode: 0o700 });
+    return { directory, existing };
+}
+function backupDirectory(projectRoot, now) {
+    const stamp = new Date(now).toISOString().replace(/[:.]/gu, '-');
+    let directory = join('.zhin', 'backups', `gateway-db-${stamp}`);
+    for (let suffix = 1; existsSync(join(projectRoot, directory)); suffix += 1)
+        directory = join('.zhin', 'backups', `gateway-db-${stamp}-${suffix}`);
+    mkdirSync(join(projectRoot, directory), { recursive: true, mode: 0o700 });
+    return directory;
+}
+/** Writes `rows` as JSON (owner-only, never overwriting); returns the project-relative path. */
+function exportRows(projectRoot, directory, file, source, rows, now) {
+    const path = join(directory, file);
+    writeFileSync(join(projectRoot, path), `${JSON.stringify({ exportedAt: new Date(now).toISOString(), source, tables: rows }, jsonReplacer, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    return path;
+}
+function defaultSource(config) {
+    return new ProjectDatabase(config);
+}
+async function withSource(options, config, use) {
+    let source;
+    try {
+        source = (options.openSource ?? defaultSource)(config);
+        await source.start();
+    }
+    catch (error) {
+        throw new LegacyImportError('unavailable', `无法连接项目数据库（${config.dialect}）：${errorText(error)}`, { cause: error });
+    }
+    try {
+        return await use(source);
+    }
+    finally {
+        await source.stop().catch(() => undefined);
+    }
+}
+async function insertRows(trx, dialect, table, columns, rows) {
+    const quoted = columns.map(column => quoteTableName(dialect, column)).join(', ');
+    for (let offset = 0; offset < rows.length; offset += INSERT_BATCH) {
+        for (const row of rows.slice(offset, offset + INSERT_BATCH)) {
+            const values = columns.map(column => targetCell(table, column, row[column]));
+            const placeholders = columns.map((_, index) => (dialect === 'pg' ? `$${index + 1}` : '?')).join(', ');
+            await trx.query(`INSERT INTO ${quoteTableName(dialect, table)} (${quoted}) VALUES (${placeholders})`, values);
+        }
+    }
+}
+async function readStoreTable(trx, table, columns) {
+    if (!columns.length)
+        return [];
+    return trx.query(`SELECT ${columns.map(column => quoteTableName('sqlite', column)).join(', ')} FROM ${quoteTableName('sqlite', table)}`);
+}
+/** Dialects the marker can live in (a table, or a MongoDB collection). */
+function markerCapable(config) {
+    if (!SOURCE_DIALECTS.has(config.dialect))
+        return false;
+    const filename = config.filename;
+    // A SQLite project file that does not exist yet is created (directory included, as the instance
+    // would) for the marker: the instance creates it only after the gateway's first connect, and a
+    // first run without a marker would let a later loss of gateway.db reopen setup.
+    return !(config.dialect === 'sqlite' && (filename === ':memory:' || filename === '' || (typeof filename === 'string' && filename.startsWith('file::memory:'))));
+}
+function storeLostMessage(marker, storeId) {
+    return `项目数据库记录 Console 账号存在另一个 gateway.db（store ${marker.storeId}，${new Date(marker.migratedAt).toISOString()} 迁入），当前 .zhin/gateway.db（store ${storeId}）是新的或不同的：`
+        + '为防止重新打开初始化（初始化令牌重新生效），Console 访问控制保持关闭。请从备份恢复 .zhin/gateway.db；确认要重新开始时运行 zhin console init --reset-store。';
+}
+/**
+ * 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 async function importLegacyIamTables(options) {
+    try {
+        const record = await importOnce(options);
+        await options.store.deleteMeta(LEGACY_IMPORT_FAILURE_KEY).catch(() => undefined);
+        return record;
+    }
+    catch (error) {
+        const failure = classify(error);
+        if (!isTransientLegacyImportError(failure)) {
+            const value = { code: failure.code, message: failure.message, at: (options.now ?? Date.now)() };
+            await options.store.setMeta(LEGACY_IMPORT_FAILURE_KEY, value).catch(() => undefined);
+        }
+        throw failure;
+    }
+}
+async function importOnce(options) {
+    const now = options.now ?? Date.now;
+    const { store, projectRoot } = options;
+    const current = await readLegacyImportRecord(store);
+    if (legacyImportSettled(current)) {
+        await verifyStoreMarker(options, now);
+        return current;
+    }
+    const copied = current?.status === 'copied' ? current : await copyLegacyTables(now);
+    if (copied.status === 'copied') {
+        const done = await dropLegacyTables(options, now);
+        await verifyStoreMarker(options, now);
+        return done;
+    }
+    await verifyStoreMarker(options, now);
+    return copied;
+    async function copyLegacyTables(clock) {
+        let config;
+        try {
+            config = await options.projectDatabase();
+        }
+        catch (error) {
+            throw new LegacyImportError('unavailable', `无法读取项目数据库配置：${errorText(error)}`, { cause: error });
+        }
+        const source = summarize(projectRoot, config);
+        return store.transaction(async (trx) => {
+            const record = await readLegacyImportRecord(store, trx);
+            if (record)
+                return record;
+            const counts = await store.counts(trx);
+            if (Object.values(counts).some(count => count > 0)) {
+                throw new LegacyImportError('conflict', 'gateway.db 已有 Console 数据却没有迁移记录；不合并，请检查 .zhin/gateway.db（或删除它后重新迁移）');
+            }
+            const fresh = async (reason) => {
+                const value = Object.freeze({ status: 'fresh', at: clock(), source, reason });
+                await store.setMeta(LEGACY_IMPORT_KEY, value, trx);
+                return value;
+            };
+            if (!SOURCE_DIALECTS.has(config.dialect))
+                return fresh('non-relational');
+            const filename = config.filename;
+            // Never create the project SQLite file just to look into it.
+            if (config.dialect === 'sqlite' && typeof filename === 'string' && filename !== ':memory:' && !existsSync(filename))
+                return fresh('no-database-file');
+            return withSource(options, config, async (legacy) => {
+                // An empty gateway.db beside a project database that already handed its accounts to a
+                // gateway.db: the store was lost. Never treat that as "no owner yet".
+                const marker = await legacy.readStoreMarker?.();
+                if (marker)
+                    throw new LegacyImportError(marker.storeId === store.storeId ? 'store_mismatch' : 'store_lost', storeLostMessage(marker, store.storeId));
+                const present = await legacy.tableExists(TABLES);
+                if (!present.length)
+                    return fresh('no-tables');
+                const rows = await legacy.readSnapshot(present);
+                const at = clock();
+                const { directory: backup, existing } = snapshotBackupDirectory(projectRoot, rows);
+                if (!existing)
+                    exportRows(projectRoot, backup, 'console-tables.json', source, rows, at);
+                const countsOut = {};
+                const checksums = {};
+                const columnsOut = {};
+                for (const table of present) {
+                    const tableRows = rows[table] ?? [];
+                    const columns = sharedColumns(table, tableRows);
+                    if (tableRows.length && !columns.includes('id'))
+                        throw new LegacyImportError('invalid', `${table} 没有 id 列，无法迁移`);
+                    await insertRows(trx, 'sqlite', table, columns, tableRows);
+                    const expected = tableChecksum(table, tableRows, columns);
+                    const written = tableChecksum(table, await readStoreTable(trx, table, columns), columns);
+                    if (written !== expected)
+                        throw new LegacyImportError('mismatch', `${table} 复制后校验和不一致，已回滚`);
+                    countsOut[table] = tableRows.length;
+                    checksums[table] = expected;
+                    columnsOut[table] = Object.freeze(columns);
+                }
+                const value = Object.freeze({
+                    status: 'copied', at, source, backup,
+                    counts: Object.freeze(countsOut), checksums: Object.freeze(checksums), columns: Object.freeze(columnsOut),
+                });
+                await store.setMeta(LEGACY_IMPORT_KEY, value, trx);
+                options.logger?.info?.(`console iam: copied ${Object.entries(countsOut).map(([table, count]) => `${table}=${count}`).join(' ')} from the project database into .zhin/gateway.db (backup ${backup})`);
+                return value;
+            }).catch((error) => { throw classify(error); });
+        });
+    }
+}
+/**
+ * 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 async function ensureGatewayStoreMarker(options) {
+    if (!legacyImportSettled(await readLegacyImportRecord(options.store)))
+        return;
+    try {
+        await verifyStoreMarker(options, options.now ?? Date.now);
+    }
+    catch (error) {
+        if (error instanceof LegacyImportError && error.code === 'store_mismatch')
+            throw error;
+        options.logger?.warn?.(`console iam: cannot check the gateway store marker in the project database: ${errorText(error)}`);
+    }
+}
+async function verifyStoreMarker(options, now) {
+    let config;
+    try {
+        config = await options.projectDatabase();
+    }
+    catch {
+        return;
+    }
+    if (!markerCapable(config))
+        return;
+    let source;
+    try {
+        source = (options.openSource ?? defaultSource)(config);
+        await source.start();
+    }
+    catch (error) {
+        options.logger?.warn?.(`console iam: cannot check the gateway store marker in the project database: ${errorText(error)}`);
+        return;
+    }
+    try {
+        if (!source.readStoreMarker || !source.writeStoreMarker)
+            return;
+        const marker = await source.readStoreMarker();
+        if (marker && marker.storeId !== options.store.storeId)
+            throw new LegacyImportError('store_mismatch', storeLostMessage(marker, options.store.storeId));
+        if (!marker) {
+            await source.writeStoreMarker({ storeId: options.store.storeId, migratedAt: now() }).catch((error) => {
+                options.logger?.warn?.(`console iam: cannot write the gateway store marker into the project database: ${errorText(error)}`);
+            });
+        }
+    }
+    finally {
+        await source.stop().catch(() => undefined);
+    }
+}
+async function dropLegacyTables(options, now) {
+    const { store, projectRoot } = options;
+    let config;
+    try {
+        config = await options.projectDatabase();
+    }
+    catch (error) {
+        throw new LegacyImportError('unavailable', `无法读取项目数据库配置：${errorText(error)}`, { cause: error });
+    }
+    return store.transaction(async (trx) => {
+        const record = await readLegacyImportRecord(store, trx);
+        if (!record || record.status !== 'copied') {
+            if (record)
+                return record;
+            throw new LegacyImportError('unavailable', '迁移记录丢失，稍后重试');
+        }
+        return withSource(options, config, async (legacy) => {
+            const present = await legacy.tableExists(TABLES);
+            let changed = false;
+            let changedExport;
+            if (present.length) {
+                const rows = await legacy.readSnapshot(present);
+                changed = present.some((table) => {
+                    const tableRows = rows[table] ?? [];
+                    const expected = record.checksums[table];
+                    if (expected === undefined)
+                        return tableRows.length > 0;
+                    return tableChecksum(table, tableRows, record.columns[table] ?? []) !== expected;
+                });
+                if (changed) {
+                    mkdirSync(join(projectRoot, record.backup), { recursive: true, mode: 0o700 });
+                    const name = `console-tables-changed-${createHash('sha256').update(JSON.stringify(rows, jsonReplacer)).digest('hex').slice(0, 12)}.json`;
+                    changedExport = join(record.backup, name);
+                    if (!existsSync(join(projectRoot, changedExport)))
+                        exportRows(projectRoot, record.backup, name, record.source, rows, now());
+                    options.logger?.warn?.(`console iam: the old console_* tables changed after they were copied; their rows as dropped are in ${changedExport} (gateway.db keeps the copy)`);
+                }
+                await legacy.dropTables(present);
+            }
+            const value = Object.freeze({
+                status: 'done',
+                at: now(),
+                copiedAt: record.at,
+                source: record.source,
+                counts: record.counts,
+                checksums: record.checksums,
+                columns: record.columns,
+                backup: record.backup,
+                changed,
+                ...(changedExport ? { changedExport } : {}),
+            });
+            await store.setMeta(LEGACY_IMPORT_KEY, value, trx);
+            return value;
+        }).catch((error) => { throw classify(error); });
+    });
+}
+/**
+ * `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 async function resetGatewayStore(options) {
+    const now = options.now ?? Date.now;
+    const { store, projectRoot } = options;
+    let config;
+    try {
+        config = await options.projectDatabase();
+    }
+    catch (error) {
+        throw new LegacyImportError('unavailable', `无法读取项目数据库配置：${errorText(error)}`, { cause: error });
+    }
+    let previous;
+    if (markerCapable(config)) {
+        previous = await withSource(options, config, async (source) => {
+            // Old account tables still there: migrate instead of resetting.
+            if ((await source.tableExists(TABLES)).length)
+                throw new LegacyImportError('conflict', '项目数据库里还有旧版 Console 账号表：请运行 zhin console migrate，而不是重置');
+            const marker = await source.readStoreMarker?.();
+            await source.writeStoreMarker?.({ storeId: store.storeId, migratedAt: now() });
+            return marker;
+        });
+    }
+    await store.transaction(async (trx) => {
+        if (!(await readLegacyImportRecord(store, trx))) {
+            await store.setMeta(LEGACY_IMPORT_KEY, Object.freeze({ status: 'fresh', at: now(), source: summarize(projectRoot, config), reason: 'reset-store' }), trx);
+        }
+        await store.deleteMeta(LEGACY_IMPORT_FAILURE_KEY, trx);
+        await trx.query(`INSERT INTO ${quoteTableName('sqlite', IAM_TABLES.audit)} (id, at, actor, action, target, outcome, detail, ip) VALUES (?, ?, 'local', 'auth.store.reset', ?, 'ok', ?, NULL)`, [
+            randomUUID(), now(), `store:${store.storeId}`, JSON.stringify({ previousStoreId: previous?.storeId ?? null, previousMigratedAt: previous?.migratedAt ?? null }),
+        ]);
+    });
+    return Object.freeze({ ...(previous ? { previousStoreId: previous.storeId } : {}), storeId: store.storeId });
+}
+/** For `zhin doctor`: the record, and whether old tables showed up again in the project database. */
+export async function inspectLegacyIamImport(options) {
+    const record = await readLegacyImportRecord(options.store);
+    const failure = await options.store.getMeta(LEGACY_IMPORT_FAILURE_KEY);
+    if (!legacyImportSettled(record))
+        return Object.freeze({ record, ...(failure ? { failure } : {}) });
+    try {
+        const config = await options.projectDatabase();
+        if (!SOURCE_DIALECTS.has(config.dialect))
+            return Object.freeze({ record, reappeared: Object.freeze([]) });
+        const filename = config.filename;
+        if (config.dialect === 'sqlite' && typeof filename === 'string' && !existsSync(filename))
+            return Object.freeze({ record, reappeared: Object.freeze([]) });
+        const reappeared = await withSource(options, config, legacy => legacy.tableExists(TABLES));
+        return Object.freeze({ record, reappeared: Object.freeze(reappeared) });
+    }
+    catch (error) {
+        return Object.freeze({ record, problem: errorText(error) });
+    }
+}
+/**
+ * `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 async function revertLegacyIamImport(options) {
+    const now = options.now ?? Date.now;
+    const { store, projectRoot } = options;
+    let config;
+    try {
+        config = await options.projectDatabase();
+    }
+    catch (error) {
+        throw new LegacyImportError('unavailable', `无法读取项目数据库配置：${errorText(error)}`, { cause: error });
+    }
+    if (!SOURCE_DIALECTS.has(config.dialect)) {
+        throw new LegacyImportError('unsupported', `项目数据库是 ${config.dialect}：旧版本无法在这里存放 Console 账号，不能回退`);
+    }
+    // A copy of gateway.db first (SQLite cannot back up a connection inside its own write transaction).
+    const at = now();
+    const backup = backupDirectory(projectRoot, at);
+    await store.backupTo(join(projectRoot, backup, 'gateway.db'));
+    return store.transaction(async (trx) => {
+        const rows = {};
+        for (const table of TABLES)
+            rows[table] = await readStoreTable(trx, table, Object.keys(IAM_TABLE_DEFINITIONS[table] ?? {}));
+        exportRows(projectRoot, backup, 'gateway-tables.json', { dialect: 'sqlite', location: '.zhin/gateway.db' }, rows, at);
+        const target = new ProjectDatabase(config);
+        defineConsoleIamTables(target);
+        try {
+            await target.start();
+        }
+        catch (error) {
+            throw new LegacyImportError('unavailable', `无法连接项目数据库（${config.dialect}）：${errorText(error)}`, { cause: error });
+        }
+        const counts = {};
+        const warnings = [];
+        try {
+            const existing = await target.readSnapshot(TABLES);
+            const occupied = TABLES.filter(table => (existing[table]?.length ?? 0) > 0);
+            if (occupied.length)
+                throw new LegacyImportError('conflict', `项目数据库里这些表已有数据，不覆盖：${occupied.join(', ')}`);
+            if (target.relational) {
+                await target.transaction(async (project) => {
+                    for (const table of TABLES)
+                        await insertRows(project, config.dialect, table, Object.keys(IAM_TABLE_DEFINITIONS[table] ?? {}), rows[table] ?? []);
+                });
+            }
+            else {
+                for (const table of TABLES) {
+                    const model = target.models.get(table);
+                    if (!model)
+                        throw new LegacyImportError('unavailable', `项目数据库缺少 ${table}`);
+                    for (const row of rows[table] ?? []) {
+                        await model.insert(Object.fromEntries(Object.keys(IAM_TABLE_DEFINITIONS[table] ?? {}).map(column => [column, targetCell(table, column, row[column])])));
+                    }
+                }
+            }
+            const written = await target.readSnapshot(TABLES);
+            for (const table of TABLES) {
+                const columns = Object.keys(IAM_TABLE_DEFINITIONS[table] ?? {});
+                if (tableChecksum(table, written[table] ?? [], columns) !== tableChecksum(table, rows[table] ?? [], columns)) {
+                    throw new LegacyImportError('mismatch', `${table} 写回项目数据库后校验和不一致；请检查项目数据库里的 console_* 表（gateway.db 未改动，备份在 ${backup}）`);
+                }
+                counts[table] = rows[table]?.length ?? 0;
+            }
+            // The older version knows no marker; a later upgrade migrates again.
+            await target.deleteStoreMarker().catch((error) => { warnings.push(`无法删除项目数据库里的标记表 zhin_gateway_store：${errorText(error)}`); });
+            warnings.push(...await revokeConsoleRoleAccess(target, config));
+        }
+        finally {
+            await target.stop().catch(() => undefined);
+        }
+        for (const table of TABLES)
+            await trx.query(`DELETE FROM ${quoteTableName('sqlite', table)}`);
+        await store.deleteMeta(LEGACY_IMPORT_KEY, trx);
+        await store.deleteMeta(LEGACY_IMPORT_FAILURE_KEY, trx);
+        return Object.freeze({ counts: Object.freeze(counts), backup, warnings: Object.freeze(warnings) });
+    });
+}
+/**
+ * After a revert the account tables are back in the project database, where the restricted
+ * Console account (`database.console`) would reach them: PostgreSQL's default privileges grant it
+ * every new table of the main account, MySQL grants it the whole database. Revoke what can be
+ * revoked and tell the operator to drop the account (an older version does not use it).
+ */
+async function revokeConsoleRoleAccess(target, config) {
+    const consoleUser = config.console?.user;
+    if (typeof consoleUser !== 'string' || !consoleUser || (config.dialect !== 'pg' && config.dialect !== 'mysql'))
+        return [];
+    const warnings = [];
+    const attempt = async (sql, params) => {
+        await target.query(sql, params).catch((error) => { warnings.push(`${sql.split(' ').slice(0, 6).join(' ')}… 失败：${errorText(error)}`); });
+    };
+    if (config.dialect === 'pg') {
+        const role = quoteTableName('pg', consoleUser);
+        for (const table of TABLES)
+            await attempt(`REVOKE ALL ON TABLE ${quoteTableName('pg', table)} FROM ${role}`);
+        await attempt(`ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM ${role}`);
+        await attempt(`ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON SEQUENCES FROM ${role}`);
+        warnings.push(`旧版本不使用受限账号 ${consoleUser}：请删除它（DROP OWNED BY ${role}; DROP ROLE ${role};）并从配置删除 database.console`);
+    }
+    else {
+        const grantees = await target.query('SELECT DISTINCT GRANTEE AS grantee FROM information_schema.SCHEMA_PRIVILEGES WHERE GRANTEE LIKE ?', [`'${consoleUser.replace(/'/gu, "''")}'@%`])
+            .catch(() => []);
+        for (const { grantee } of grantees)
+            await attempt(`REVOKE ALL PRIVILEGES, GRANT OPTION FROM ${grantee}`);
+        if (!grantees.length)
+            warnings.push(`无法确认受限账号 ${consoleUser} 的授权已撤销`);
+        warnings.push(`旧版本不使用受限账号 ${consoleUser}：请删除它（DROP USER '${consoleUser}'@'<主机>';）并从配置删除 database.console`);
+    }
+    return warnings;
+}

package/lib/iam/local-admin.d.ts

@@ -23,5 +23,7 @@ export interface LocalConsoleAdminOptions {
     readonly switchDatabase: () => Promise<{
         restarting: boolean;
     }>;
+    /** `gateway.console.migration.status`: the import state and whether old tables reappeared. */
+    readonly migration?: () => Promise<unknown>;
 }
 export declare function createLocalConsoleAdmin(options: LocalConsoleAdminOptions): LocalConsoleAdmin;

package/lib/iam/local-admin.js

@@ -19,6 +19,7 @@ const TYPES = new Set([
     LOCAL_GATEWAY_RPC.CONSOLE_USER_CREATE,
     LOCAL_GATEWAY_RPC.CONSOLE_USER_PASSWD,
     LOCAL_GATEWAY_RPC.CONSOLE_USER_DISABLE,
+    LOCAL_GATEWAY_RPC.CONSOLE_MIGRATION_STATUS,
 ]);
 const ACTOR = 'local';
 export function createLocalConsoleAdmin(options) {
@@ -26,7 +27,7 @@ export function createLocalConsoleAdmin(options) {
     const requireIam = () => {
         const iam = options.iam();
         if (!iam?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储 Console 用户，或尚未就绪；请先运行 zhin console init 选择 sqlite/mysql/pg/mongodb');
+            throw new IamError('unavailable', iam?.unavailableReason() ?? 'Console 访问控制尚未就绪');
         return iam;
     };
     const requireUser = async (iam, username) => {
@@ -79,6 +80,10 @@ export function createLocalConsoleAdmin(options) {
                 audit(updated.disabled ? 'iam.users.disable' : 'iam.users.enable', `user:${user.id}`);
                 return { user: updated };
             }
+            case LOCAL_GATEWAY_RPC.CONSOLE_MIGRATION_STATUS:
+                if (!options.migration)
+                    throw new IamError('unavailable', '迁移状态不可用');
+                return options.migration();
             default: throw new IamError('invalid_input', `Unknown RPC type: ${type}`);
         }
     }

package/lib/iam/routes.js

@@ -9,6 +9,13 @@ export function registerConsoleAuthRoutes(options) {
     const { http, base } = options;
     const route = (method, path, handler, summary) => http.route(method, `${base}${path}`, async (request, { principal, remoteAddress }) => {
         const noStore = { 'cache-control': 'no-store' };
+        // ADR 0059 §3: closed until gateway.db is open and the old tables are imported (`/auth/me`
+        // still answers, anonymously and with `setupRequired: false`, so the Console can say why).
+        // The reason itself (paths, driver messages) is for the logs and the local owner only.
+        const closed = path === CONSOLE_AUTH_ROUTES.ME ? undefined : options.iam()?.publicUnavailable();
+        if (closed !== undefined) {
+            return jsonResponse(503, { success: false, code: 'iam_unavailable', reason: closed.code, error: closed.message }, { ...noStore, 'retry-after': String(DATABASE_BUSY_RETRY_AFTER_SECONDS) });
+        }
         try {
             const result = await handler({
                 request,
@@ -37,7 +44,7 @@ export function registerConsoleAuthRoutes(options) {
     const requireIam = () => {
         const iam = options.iam();
         if (!iam?.ready)
-            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+            throw new IamError('unavailable', iam?.publicUnavailable()?.message ?? 'Console 访问控制尚未就绪');
         return iam;
     };
     const requireUser = (principal) => {
@@ -76,8 +83,9 @@ export function registerConsoleAuthRoutes(options) {
         }, 'Console logout'),
         route('GET', CONSOLE_AUTH_ROUTES.ME, async ({ principal }) => {
             const setupRequired = options.setup.setupRequired();
+            const closed = options.iam()?.publicUnavailable();
             if (!principal)
-                return ok({ kind: 'anonymous', permissions: [], bindings: [], setupRequired });
+                return ok({ kind: 'anonymous', permissions: [], bindings: [], setupRequired, ...(closed ? { unavailable: closed.message, unavailableCode: closed.code } : {}) });
             if (principal.kind === 'bootstrap') {
                 const permissions = globalPermissions(principal);
                 return ok({