@zhin.js/database 1.1.7 → 1.2.0

package/lib/probe.js

@@ -0,0 +1,98 @@
+/**
+ * One-shot connection probe for setup wizards: connect, run the dialect health query, disconnect.
+ * Error text is stripped of credentials before it is returned.
+ */
+/** Driver package that must be importable for each dialect (`null`: built into Node). */
+export const DATABASE_DRIVER_PACKAGES = Object.freeze({
+    sqlite: null,
+    mysql: 'mysql2',
+    pg: 'pg',
+    mongodb: 'mongodb',
+});
+/** Whether the optional driver package for `dialect` can be loaded. */
+export async function isDatabaseDriverAvailable(dialect, importer = specifier => import(specifier)) {
+    const pkg = DATABASE_DRIVER_PACKAGES[dialect];
+    if (pkg === null)
+        return true;
+    try {
+        await importer(pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function createProbeTarget(dialect, config) {
+    switch (dialect) {
+        case 'sqlite': {
+            const { SQLiteDialect } = await import('./dialects/sqlite.js');
+            return new SQLiteDialect(config);
+        }
+        case 'mysql': {
+            const { MySQLDialect } = await import('./dialects/mysql.js');
+            return new MySQLDialect(config);
+        }
+        case 'pg': {
+            const { PostgreSQLDialect } = await import('./dialects/pg.js');
+            return new PostgreSQLDialect(config);
+        }
+        case 'mongodb': {
+            const { MongoDBDialect } = await import('./dialects/mongodb.js');
+            return new MongoDBDialect(config);
+        }
+        default:
+            throw new Error(`Unsupported dialect: ${String(dialect)}`);
+    }
+}
+/**
+ * Opens a temporary connection with `config` and closes it again.
+ * `factory` is a test seam; it defaults to the built-in dialects.
+ */
+export async function probeDatabaseConnection(dialect, config, options = {}) {
+    const secrets = collectSecrets(config);
+    const startedAt = Date.now();
+    let target;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error('connection timed out')), options.timeoutMs ?? 10_000);
+    });
+    try {
+        target = await (options.factory ?? createProbeTarget)(dialect, config);
+        await Promise.race([target.connect(), timeout]);
+        const healthy = await Promise.race([target.healthCheck(), timeout]);
+        if (!healthy)
+            return Object.freeze({ ok: false, error: 'probe query failed' });
+        return Object.freeze({ ok: true, latencyMs: Date.now() - startedAt });
+    }
+    catch (error) {
+        return Object.freeze({ ok: false, error: redactProbeError(error, secrets) });
+    }
+    finally {
+        clearTimeout(timer);
+        await target?.disconnect().catch(() => undefined);
+    }
+}
+function collectSecrets(config) {
+    const values = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        if (/pass|secret|token|key/iu.test(key))
+            values.push(value);
+        if (/url|uri|connectionString/iu.test(key)) {
+            const credentials = /\/\/([^@/]*)@/u.exec(value)?.[1];
+            if (credentials)
+                values.push(credentials, ...credentials.split(':').filter(Boolean));
+        }
+    }
+    return values.filter(value => value.length >= 3).sort((a, b) => b.length - a.length);
+}
+/** Removes credentials (configured secret values, URL userinfo) from a driver error. */
+export function redactProbeError(error, secrets = []) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const secret of secrets)
+        message = message.split(secret).join('***');
+    message = message.replace(/\/\/[^@\s/]*@/gu, '//***@');
+    message = message.replace(/(password|pwd)\s*[=:]\s*\S+/giu, '$1=***');
+    return message.slice(0, 300);
+}

package/lib/reserved-tables.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tables owned by the management gateway (ADR 0049 / 0054 §7). The gateway and the instance share
+ * one project database; the gateway's tables hold password hashes, session / token hashes and the
+ * audit log, so every instance-side path (plugin models, Console database page, raw SQL) must deny
+ * them. Deny by prefix so future gateway tables are covered without another list to update.
+ */
+export declare const GATEWAY_TABLE_PREFIX = "console_";
+/**
+ * The gateway's marker in the project database (ADR 0059 §3 修订): which `.zhin/gateway.db` holds
+ * the Console accounts. Gateway-owned like `console_*`: no instance path may read or drop it.
+ */
+export declare const GATEWAY_STORE_MARKER_TABLE = "zhin_gateway_store";
+/** `console_`-prefixed tables that the instance itself owns (historical names). */
+export declare const INSTANCE_CONSOLE_TABLES: readonly string[];
+/** True when `name` is a gateway-owned table (case-insensitive, quotes and schema ignored). */
+export declare function isGatewayOwnedTable(name: string): boolean;
+/**
+ * True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal),
+ * also when the name is spelled with escapes (`U&"\\0063onsole_users"`, `E'\\x63onsole_users'`).
+ * A custom `UESCAPE` character cannot be decoded reliably, so it counts as a reference.
+ */
+export declare function referencesGatewayOwnedTable(sql: string): boolean;
+export declare class GatewayOwnedTableError extends Error {
+    constructor(table?: string);
+}
+/** Throws {@link GatewayOwnedTableError} for a gateway-owned table name. */
+export declare function assertInstanceTable(name: string): void;

package/lib/reserved-tables.js

@@ -0,0 +1,78 @@
+/**
+ * Tables owned by the management gateway (ADR 0049 / 0054 §7). The gateway and the instance share
+ * one project database; the gateway's tables hold password hashes, session / token hashes and the
+ * audit log, so every instance-side path (plugin models, Console database page, raw SQL) must deny
+ * them. Deny by prefix so future gateway tables are covered without another list to update.
+ */
+export const GATEWAY_TABLE_PREFIX = 'console_';
+/**
+ * The gateway's marker in the project database (ADR 0059 §3 修订): which `.zhin/gateway.db` holds
+ * the Console accounts. Gateway-owned like `console_*`: no instance path may read or drop it.
+ */
+export const GATEWAY_STORE_MARKER_TABLE = 'zhin_gateway_store';
+/** `console_`-prefixed tables that the instance itself owns (historical names). */
+export const INSTANCE_CONSOLE_TABLES = Object.freeze(['console_conversations']);
+const instanceConsoleTables = new Set(INSTANCE_CONSOLE_TABLES);
+/** True when `name` is a gateway-owned table (case-insensitive, quotes and schema ignored). */
+export function isGatewayOwnedTable(name) {
+    const bare = String(name).trim().replace(/^[`"[]|[`"\]]$/g, '');
+    const table = (bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare)
+        .replace(/^[`"[]|[`"\]]$/g, '').toLowerCase();
+    if (table === GATEWAY_STORE_MARKER_TABLE)
+        return true;
+    return table.startsWith(GATEWAY_TABLE_PREFIX) && !instanceConsoleTables.has(table);
+}
+const IDENTIFIER = /(?<![A-Za-z0-9_$])(?:console_[A-Za-z0-9_$]*|zhin_gateway_store)(?![A-Za-z0-9_$])/gi;
+/**
+ * Spellings of the SQL text with escape sequences decoded: PostgreSQL `U&"\\0063…"` /
+ * `U&'\\+000063…'` and `E'\\x63…'` / octal / `\\u`, MySQL backslash escapes inside strings
+ * (`'con\\sole_users'`) and doubled quotes inside quoted names (`"console_""x"`).
+ */
+function decodedSpellings(sql) {
+    const hex = (code) => {
+        const value = Number.parseInt(code, 16);
+        return Number.isFinite(value) && value <= 0x10ffff ? String.fromCodePoint(value) : '';
+    };
+    // U& names and strings: \XXXX and \+XXXXXX.
+    const unicode = sql
+        .replace(/\\\+([0-9a-f]{6})/gi, (_, code) => hex(code))
+        .replace(/\\([0-9a-f]{4})/gi, (_, code) => hex(code));
+    // E'' strings: \xHH, \ooo, \uXXXX, \UXXXXXXXX.
+    const escaped = sql
+        .replace(/\\U([0-9a-f]{8})/g, (_, code) => hex(code))
+        .replace(/\\u([0-9a-f]{4})/g, (_, code) => hex(code))
+        .replace(/\\x([0-9a-f]{1,2})/gi, (_, code) => hex(code))
+        .replace(/\\([0-7]{1,3})/g, (_, code) => String.fromCharCode(Number.parseInt(code, 8) & 0xff));
+    const spellings = [sql, unicode, escaped].flatMap(text => [text, text.replace(/\\(.)/g, '$1')]);
+    return spellings.flatMap(text => [text, text.replace(/""|``/g, '')]);
+}
+/**
+ * True when SQL text mentions a gateway-owned table anywhere (identifiers, quoted or literal),
+ * also when the name is spelled with escapes (`U&"\\0063onsole_users"`, `E'\\x63onsole_users'`).
+ * A custom `UESCAPE` character cannot be decoded reliably, so it counts as a reference.
+ */
+export function referencesGatewayOwnedTable(sql) {
+    const text = String(sql);
+    if (/\bu&\s*['"]/i.test(text) && /\buescape\b/i.test(text))
+        return true;
+    for (const spelling of decodedSpellings(text)) {
+        for (const match of spelling.matchAll(IDENTIFIER)) {
+            if (isGatewayOwnedTable(match[0]))
+                return true;
+        }
+    }
+    return false;
+}
+export class GatewayOwnedTableError extends Error {
+    constructor(table) {
+        super(table
+            ? `Table '${table}' is owned by the management gateway and is not accessible from the instance`
+            : 'Statement references a table owned by the management gateway');
+        this.name = 'GatewayOwnedTableError';
+    }
+}
+/** Throws {@link GatewayOwnedTableError} for a gateway-owned table name. */
+export function assertInstanceTable(name) {
+    if (isGatewayOwnedTable(name))
+        throw new GatewayOwnedTableError(name);
+}

package/lib/types.d.ts

@@ -209,7 +209,7 @@ export interface DocumentQueryResult {
     limit?: number;
     skip?: number;
     projection?: Record<string, 1 | 0>;
-    operation?: 'find' | 'insertOne' | 'insertMany' | 'updateOne' | 'updateMany' | 'deleteOne' | 'deleteMany' | 'createCollection' | 'createIndex' | 'dropIndex' | 'dropCollection';
+    operation?: 'find' | 'insertOne' | 'insertMany' | 'updateOne' | 'updateMany' | 'deleteOne' | 'deleteMany' | 'createCollection' | 'createIndex' | 'dropIndex' | 'dropCollection' | 'listCollections';
 }
 /**
  * 键值查询结果类型
@@ -285,11 +285,31 @@ export type IsolationLevel = 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE
 export interface TransactionOptions {
     isolationLevel?: IsolationLevel;
     timeout?: number;
+    /**
+     * The transaction only reads. SQLite then opens it with `BEGIN DEFERRED` (no write lock, so it
+     * never waits for another connection's writer) and refuses writes inside it (`query_only`).
+     * PostgreSQL opens it `READ ONLY` and MySQL with `START TRANSACTION READ ONLY`.
+     */
+    readOnly?: boolean;
+}
+export interface StatementQueryOptions {
+    /**
+     * Keep at most this many rows. Drivers stop reading past it where they can (SQLite iterates,
+     * MySQL streams and discards); the returned array then carries a non-enumerable `truncated`.
+     */
+    readonly maxRows?: number;
 }
 export interface Transaction {
     commit(): Promise<void>;
     rollback(): Promise<void>;
     query<T = any>(sql: string, params?: any[]): Promise<T>;
+    /**
+     * Runs exactly one statement through a protocol that refuses a second one: PostgreSQL's
+     * extended protocol (`cannot insert multiple commands into a prepared statement`), MySQL
+     * prepared statements (never `multipleStatements`, whatever the connection config says) and
+     * SQLite `prepare()` (which compiles only the first statement). For SQL typed by a person.
+     */
+    queryStatement?<T = any>(sql: string, options?: StatementQueryOptions): Promise<T>;
 }
 /**
  * 增强的事务接口，支持链式调用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,14 +43,15 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "license": "MIT",
   "dependencies": {
-    "@zhin.js/logger": "1.1.2"
+    "@zhin.js/logger": "1.1.3"
   },
   "peerDependencies": {
     "mongodb": ">=3.1.13",
     "mysql2": ">=3.9.8",
     "pg": ">=2.11.2",
-    "redis": "latest"
+    "redis": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {