dsh-db-tool 1.5.9 → 1.6.0

package/dist/adapters/dmdb/index.js

@@ -16,6 +16,7 @@
  *  - 返回 { metaData, rows, rowsAffected } 与 oracledb 兼容。
  */
 import db from 'dmdb';
+import { sqlHead, SQL_READ_HEADS } from '../../guard/index.js';
 const ROWS_MAX = 500;
 const CELL_TRUNC = 1000;
 const DDL_KEYWORDS = new Set([
@@ -199,14 +200,19 @@ export async function createDmAdapter(conn, opts) {
                 throw humanizeDmError(e);
             }
         },
-        /** 事务：专用连接多条语句，成功 commit、异常 rollback。DM 事务隐式开始，无需 SET TRANSACTION。 */
+        /**
+         * 事务：专用连接多条语句，成功 commit、异常 rollback。DM 事务隐式开始，无需 SET TRANSACTION。
+         * exec 回调按语句头分流：读语句（SQL_READ_HEADS 命中首词，如 SELECT/WITH）在
+         * 本事务连接上执行并返回结果集（事务内读未提交数据是官方标准用法）；
+         * 其余语句返回执行回执。所有语句同处一个事务，随 commit/rollback 收口。
+         */
         async tx(fn) {
             requireRw('事务(tx)');
             const c = await pool.getConnection();
             try {
                 const exec = async (sql, binds) => {
                     const r = await c.execute(sql, binds ?? [], execOptsTx);
-                    return toExecResult(sql, r);
+                    return SQL_READ_HEADS.has(sqlHead(sql)) ? rowsToQueryResult(r) : toExecResult(sql, r);
                 };
                 const out = await fn(exec);
                 await c.commit();

package/dist/adapters/oracle/index.js

@@ -13,6 +13,7 @@
  *  - 锁号/密码验证器等常见连接错误转人类可读提示（见 ORA_HINTS）。
  */
 import oracledb from 'oracledb';
+import { sqlHead, SQL_READ_HEADS } from '../../guard/index.js';
 // CLOB 统一按字符串返回（BLOB 不能走 fetchAsString，须用 execute 的 fetchInfo）
 if (!oracledb.fetchAsString.includes(oracledb.CLOB)) {
     oracledb.fetchAsString = [...oracledb.fetchAsString, oracledb.CLOB];
@@ -153,6 +154,17 @@ export async function createOracleAdapter(conn, opts) {
             message: `${sql.trim().split(/\s+/)[0]?.toUpperCase() ?? 'SQL'} 完成${r.rowsAffected ? `，影响 ${r.rowsAffected} 行` : ''}${ddlNote}`,
         };
     }
+    /** 执行结果 → QueryResult（行值规范化 + 超限截断）；query 与事务内读语句共用 */
+    async function rowsToQueryResult(r) {
+        const allRows = r.rows ?? [];
+        const truncated = allRows.length > ROWS_MAX;
+        const columns = (r.metaData ?? []).map((m) => m.name);
+        const rows = [];
+        for (const row of allRows.slice(0, ROWS_MAX)) {
+            rows.push(await Promise.all(Object.values(row).map(normalizeCell)));
+        }
+        return { columns, rows, rowCount: rows.length, truncated: truncated || undefined };
+    }
     // autoCommit 默认 true：query/元数据 SELECT 结束隐式事务避免 ro 事务悬挂；tx 专用连接显式 autoCommit:false 覆盖
     const execOpts = { outFormat: oracledb.OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true, ...BLOB_FETCH };
     /**
@@ -211,15 +223,7 @@ export async function createOracleAdapter(conn, opts) {
             }
             try {
                 const r = await withConn((c) => c.execute(sql, params ?? [], execOpts));
-                const allRows = r.rows ?? [];
-                const truncated = allRows.length > ROWS_MAX;
-                const rows = allRows.slice(0, ROWS_MAX);
-                const columns = (r.metaData ?? []).map((m) => m.name);
-                const normRows = [];
-                for (const row of rows) {
-                    normRows.push(await Promise.all(Object.values(row).map(normalizeCell)));
-                }
-                return { columns, rows: normRows, rowCount: normRows.length, truncated: truncated || undefined };
+                return await rowsToQueryResult(r);
             }
             catch (e) {
                 throw humanizeOraError(e);
@@ -238,6 +242,9 @@ export async function createOracleAdapter(conn, opts) {
         /**
          * 事务：从池取专用连接执行多条语句，成功 commit、异常 rollback。
          * Oracle 无 BEGIN，用 SET TRANSACTION READ WRITE 开始显式事务。
+         * exec 回调按语句头分流：读语句（SQL_READ_HEADS 命中首词，如 SELECT/WITH）在
+         * 本事务连接上执行并返回结果集（事务内读未提交数据是官方标准用法）；
+         * 其余语句返回执行回执。所有语句同处一个事务，随 commit/rollback 收口。
          */
         async tx(fn) {
             requireRw('事务(tx)');
@@ -246,7 +253,7 @@ export async function createOracleAdapter(conn, opts) {
                 await c.execute('SET TRANSACTION READ WRITE');
                 const exec = async (sql, binds) => {
                     const r = await c.execute(sql, binds ?? [], { ...execOpts, autoCommit: false });
-                    return toExecResult(sql, r);
+                    return SQL_READ_HEADS.has(sqlHead(sql)) ? rowsToQueryResult(r) : toExecResult(sql, r);
                 };
                 const out = await fn(exec);
                 await c.commit();

package/dist/guard/index.js

@@ -8,8 +8,10 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { DANGEROUS_COMMANDS, READ_COMMANDS, WRITE_COMMANDS, parseRedisCommand } from '../adapters/redis/index.js';
 import { DANGEROUS_OPS, READ_OPS } from '../adapters/mongodb/index.js';
-/** SQL 读取类首词白名单（大小写不敏感；首词必须命中，否则视为非读） */
-const SQL_READ_HEADS = new Set([
+/** SQL 读取类首词白名单（大小写不敏感；首词必须命中，否则视为非读）。
+ *  导出供控制台事务会话 exec 通道复用：读语句走 query 通道保留结果集。
+ *  类型收紧为 ReadonlySet——security 原语不允许调用方增删条目（编译期保证，运行时不变）。 */
+export const SQL_READ_HEADS = new Set([
     'select', 'with', 'show', 'describe', 'desc', 'explain', 'use', 'set', 'help', 'table',
 ]);
 /** DDL：隐式提交、不可回滚 */

package/dist/http/index.js

@@ -148,6 +148,27 @@ async function route(req, res, service, path, q, opts) {
             }));
         }
     }
+    // 连接导出/导入（口令加密包）。必须置于 connMatch 之前：
+    // /api/connections/export 与 /api/connections/import 都是单层路径，
+    // 若落到 connMatch 会被当作连接 id 匹配（DELETE 无分支静默 404、PUT 误更新）。
+    if (path === '/api/connections/export' && req.method === 'POST') {
+        const b = await readBody(req);
+        const passphrase = str(b['passphrase']);
+        if (!passphrase)
+            return send(res, 400, { ok: false, error: '缺少 passphrase', code: 'INVALID_ARGUMENT' });
+        const count = service.listConnections().length; // 权威条数，前端不再用可能过期的本地列表
+        return sendOk(res, { json: service.exportConnections(passphrase), count });
+    }
+    if (path === '/api/connections/import' && req.method === 'POST') {
+        const b = await readBody(req);
+        const json = str(b['json']);
+        const passphrase = str(b['passphrase']);
+        if (!json)
+            return send(res, 400, { ok: false, error: '缺少 json', code: 'INVALID_ARGUMENT' });
+        if (!passphrase)
+            return send(res, 400, { ok: false, error: '缺少 passphrase', code: 'INVALID_ARGUMENT' });
+        return sendOk(res, service.importConnections(json, passphrase));
+    }
     // 测试未保存的连接草稿（保存前测试；不落库）
     if (path === '/api/test-draft' && req.method === 'POST') {
         const b = await readBody(req);
@@ -241,6 +262,25 @@ async function route(req, res, service, path, q, opts) {
         const b = await readBody(req);
         return await sendMaybeConfirm(res, service.runScript(projectOfBody(b), str(b['connId']), str(b['code']), optStr(b['challengeId'])));
     }
+    // 控制台事务会话（粘性连接）：begin 发 token；exec 语义等同 execute（可能
+    // NEEDS_CONFIRMATION）；commit/rollback 提交/回滚后销毁会话。trust 与 body
+    // 校验复用入口层既有链路。
+    if (path === '/api/console/begin' && req.method === 'POST') {
+        const b = await readBody(req);
+        return sendOk(res, await service.consoleBegin(projectOfBody(b), str(b['connId']), optStr(b['database'])));
+    }
+    if (path === '/api/console/exec' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.consoleExec(str(b['sessionToken']), str(b['statement']), b['params'], optStr(b['challengeId'])));
+    }
+    if (path === '/api/console/commit' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.consoleCommit(str(b['sessionToken'])));
+    }
+    if (path === '/api/console/rollback' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.consoleRollback(str(b['sessionToken'])));
+    }
     if (path === '/api/audit' && req.method === 'GET') {
         const limit = q.get('limit') !== null ? Number(q.get('limit')) : undefined;
         return sendOk(res, service.auditTail(q.get('project') ?? undefined, limit));

package/dist/manager.js

@@ -1,7 +1,9 @@
+import { randomBytes } from 'node:crypto';
 import { getAdapter } from './adapters/index.js';
-import { ChallengeStore, classifyStatement, } from './guard/index.js';
-import { mergeUrlCredentials, normalizeProjectKey, } from './store/index.js';
+import { ChallengeStore, classifyStatement, sqlHead, SQL_READ_HEADS, } from './guard/index.js';
+import { mergeUrlCredentials, normalizeProjectKey, DECRYPT_FAIL_MESSAGE, } from './store/index.js';
 import { runScriptInChild } from './script/runner.js';
+import { decryptPayload, encryptPayload } from './store/export-crypto.js';
 /* ---------------- 错误与结果类型 ---------------- */
 /** 携带机器可读 code 的业务错误（HTTP 层直接映射 {ok:false,error,code}） */
 export class DbToolError extends Error {
@@ -12,16 +14,28 @@ export class DbToolError extends Error {
         this.name = 'DbToolError';
     }
 }
+/** 粘性通道的语句串行队列：前序失败不阻塞后续，但执行严格按到达顺序 */
+function enqueue(chain, task) {
+    const next = chain.p.then(task, task);
+    chain.p = next.catch(() => { });
+    return next;
+}
 function assertNonEmpty(v, label) {
     const s = typeof v === 'string' ? v.trim() : '';
     if (s === '')
         throw new DbToolError('INVALID_ARGUMENT', `缺少必填参数: ${label}`);
     return s;
 }
+/** 单连接并发控制台事务会话上限（每会话独占驱动池 + checkout 连接，防连接耗尽） */
+const MAX_CONSOLE_SESSIONS_PER_CONN = 4;
 /* ---------------- 服务核心 ---------------- */
 export class DbToolService {
     store;
     adapterCache = new Map();
+    /** 控制台事务会话注册表（token → 会话） */
+    consoleSessions = new Map();
+    consoleTtlMs;
+    consoleSweepTimer;
     challenges;
     resolver;
     disposed = false;
@@ -29,6 +43,12 @@ export class DbToolService {
         this.store = store;
         this.resolver = opts?.adapterResolver ?? getAdapter;
         this.challenges = opts?.challenges ?? new ChallengeStore();
+        this.consoleTtlMs = opts?.consoleTx?.ttlMs ?? 5 * 60 * 1000;
+        const sweep = opts?.consoleTx?.sweepIntervalMs ?? 30 * 1000;
+        if (sweep > 0) {
+            this.consoleSweepTimer = setInterval(() => this.consoleSweep(), sweep);
+            this.consoleSweepTimer.unref?.();
+        }
     }
     /* -- 连接管理（无需授权） -- */
     listConnections() {
@@ -43,8 +63,10 @@ export class DbToolService {
         const meta = this.store.connections.update(id, patch);
         if (!meta)
             throw new DbToolError('NOT_FOUND', `连接不存在: ${id}`);
-        // url/凭证/ssl 变更后旧适配器仍持旧连接串，必须作废重建
+        // url/凭证/ssl 变更后旧适配器仍持旧连接串，必须作废重建；
+        // 控制台事务会话的专用适配器不在缓存里，单独回收（否则旧凭据最长存活到空闲 TTL）
         void this.dropAdapters(id);
+        void this.dropConsoleSessions(id);
         this.audit('', id, 'update_connection', id, 'none', false, true);
         return meta;
     }
@@ -53,6 +75,7 @@ export class DbToolService {
         if (!ok)
             throw new DbToolError('NOT_FOUND', `连接不存在: ${id}`);
         void this.dropAdapters(id);
+        void this.dropConsoleSessions(id);
         this.audit('', id, 'remove_connection', id, 'none', false, true);
         return ok;
     }
@@ -122,6 +145,60 @@ export class DbToolService {
             throw this.toDriverError(e);
         }
     }
+    /* -- 连接导出/导入（口令加密，无需授权；口令不落审计） -- */
+    /** 口令下限：导出包含全部连接机密（明文密码/完整 URL），安全边界在服务端而非 UI */
+    static PASSPHRASE_MIN = 8;
+    /**
+     * 导出全部连接（含机密）为口令加密的 JSON 密文。
+     * 审计只记连接条数，绝不落口令与密文内容。
+     */
+    exportConnections(passphrase) {
+        const pp = assertNonEmpty(passphrase, 'passphrase');
+        if (pp.length < DbToolService.PASSPHRASE_MIN) {
+            throw new DbToolError('INVALID_ARGUMENT', `口令长度至少 ${DbToolService.PASSPHRASE_MIN} 位`);
+        }
+        const bundle = this.store.connections.exportBundle();
+        const json = encryptPayload(bundle, pp);
+        this.audit('', '', 'export_connections', `导出 ${bundle.connections.length} 个连接`, 'none', false, true);
+        return json;
+    }
+    /**
+     * 从口令加密的 JSON 密文导入连接。口令错误或密文损坏统一报
+     * INVALID_ARGUMENT(DECRYPT_FAIL_MESSAGE)（不区分原因，防口令探测）。
+     */
+    importConnections(encryptedJson, passphrase) {
+        const enc = assertNonEmpty(encryptedJson, 'json');
+        const pp = assertNonEmpty(passphrase, 'passphrase');
+        if (pp.length < DbToolService.PASSPHRASE_MIN) {
+            throw new DbToolError('INVALID_ARGUMENT', `口令长度至少 ${DbToolService.PASSPHRASE_MIN} 位`);
+        }
+        let bundle;
+        try {
+            bundle = decryptPayload(enc, pp);
+        }
+        catch {
+            // 口令错误/密文损坏/非合法 JSON 统一归一（decryptPayload 已统一文案，这里兜底）
+            throw new DbToolError('INVALID_ARGUMENT', DECRYPT_FAIL_MESSAGE);
+        }
+        // 结构校验：必须是含 connections 数组的对象，且每个元素为带非空 string id/kind 的对象。
+        // 畸形元素会让 importBundle 在 try 之外抛 TypeError（绕开统一文案），
+        // 或以 undefined id 静默落库成 UI 删不掉的幽灵记录
+        const conns = bundle?.connections;
+        if (!bundle ||
+            typeof bundle !== 'object' ||
+            !Array.isArray(conns) ||
+            conns.some((c) => c === null ||
+                typeof c !== 'object' ||
+                typeof c.id !== 'string' ||
+                c.id === '' ||
+                typeof c.kind !== 'string' ||
+                c.kind === '')) {
+            throw new DbToolError('INVALID_ARGUMENT', DECRYPT_FAIL_MESSAGE);
+        }
+        const summary = this.store.connections.importBundle(bundle);
+        this.audit('', '', 'import_connections', `导入 ${summary.imported} 个连接，跳过 ${summary.skipped.length} 个，失败 ${summary.errors.length} 个`, 'none', false, true);
+        return summary;
+    }
     /* -- 授权管理 -- */
     /** 项目路径归一化（/api/project-context 无会话解析器时的回退路径） */
     projectKey(projectPath) {
@@ -133,14 +210,17 @@ export class DbToolService {
     grant(projectPath, connId, mode) {
         const key = normalizeProjectKey(projectPath);
         this.store.grants.grant(key, connId, mode);
-        // 授权模式变更（含 rw→ro 降级）必须作废旧会话适配器，否则降级不生效
+        // 授权模式变更（含 rw→ro 降级）必须作废旧会话适配器，否则降级不生效；
+        // 控制台事务会话的粘性适配器不在缓存里，单独回收（回滚未提交事务并 close）
         void this.dropAdapters(connId);
+        void this.dropConsoleSessions(connId);
         this.audit(key, connId, 'grant', `${connId} -> ${mode}`, 'none', false, true);
     }
     revokeGrant(projectPath, connId) {
         const key = normalizeProjectKey(projectPath);
         this.store.grants.revoke(key, connId);
         void this.dropAdapters(connId);
+        void this.dropConsoleSessions(connId);
         this.audit(key, connId, 'revoke', connId, 'none', false, true);
     }
     /* -- 浏览（ro 即可） -- */
@@ -280,6 +360,113 @@ export class DbToolService {
             await sessionAdapter.close().catch(() => { });
         }
     }
+    /* -- 控制台事务会话（粘性连接；语义对齐 runGuarded） -- */
+    /**
+     * 开始控制台事务：authorize(needWrite=true)（ro 直接 READ_ONLY 拒）→ 创建会话专用
+     * 适配器并打开粘性事务通道 → 返回 sessionToken。database 入参显式拒绝：粘性事务
+     * 绑定连接默认库、无法跨库，客户端切了非默认库时静默跑错库比报错更危险。
+     */
+    async consoleBegin(projectPath, connId, database) {
+        if (database !== undefined) {
+            throw new DbToolError('INVALID_ARGUMENT', '事务会话暂不支持指定数据库（粘性事务绑定连接默认库），请清空库选择后再开始事务');
+        }
+        // authorize(needWrite=true) 已拒绝 ro 授权（与 runScript 同构；顺带建立缓存适配器）
+        const { key, mode } = await this.authorize(projectPath, connId, true);
+        const rc = this.requireConn(connId);
+        // 每会话独占一个驱动池 + checkout 连接，放任创建会耗尽数据库连接（ponytail: 固定上限，不做 LRU）
+        const live = [...this.consoleSessions.values()].filter((s) => s.connId === connId).length;
+        if (live >= MAX_CONSOLE_SESSIONS_PER_CONN) {
+            throw new DbToolError('INVALID_ARGUMENT', `该连接并发事务会话已达上限（${MAX_CONSOLE_SESSIONS_PER_CONN}），请先提交或回滚既有事务`);
+        }
+        const factory = await this.resolver(rc.meta.kind);
+        const sessionAdapter = await factory(rc, { mode }).catch((e) => {
+            throw e instanceof DbToolError ? e : this.toDriverError(e);
+        });
+        try {
+            const session = await this.openConsoleSession(key, connId, sessionAdapter);
+            try {
+                // 注册前复核授权：authorize → 注册之间有多次 await，窗口内 revoke/降级触发的
+                // dropConsoleSessions 扫不到本会话（TOCTOU）；授权已变更则回滚并经外层审计后抛
+                this.recheckConsoleAuth(session);
+            }
+            catch (e) {
+                await session.finish('rollback').catch(() => { });
+                throw e;
+            }
+            this.consoleSessions.set(session.token, session);
+            this.audit(key, connId, 'console_begin', 'BEGIN', 'none', false, true);
+            return { sessionToken: session.token };
+        }
+        catch (e) {
+            await sessionAdapter.close().catch(() => { });
+            this.audit(key, connId, 'console_begin', 'BEGIN', 'none', false, false, this.errText(e));
+            throw this.toDriverError(e);
+        }
+    }
+    /**
+     * 会话内执行一条语句：语义等同 execute——classifyStatement + challenge + 审计，
+     * 在粘性通道串行执行。读语句走适配器 query 通道保留结果集（事务内 SELECT 看
+     * 未提交数据是核心场景）；写/管理语句走 execute 通道。
+     */
+    async consoleExec(sessionToken, statement, params, challengeId) {
+        const stmt = assertNonEmpty(statement, 'statement');
+        if (params !== undefined && !Array.isArray(params)) {
+            throw new DbToolError('INVALID_ARGUMENT', 'params 必须是数组（绑定参数）');
+        }
+        const s = this.requireConsoleSession(sessionToken);
+        s.lastAccess = Date.now();
+        // 授权复核：会话适配器不在 adapterCache，dropAdapters 管不到——revoke/rw→ro 降级必须即时生效
+        this.recheckConsoleAuth(s);
+        const kind = s.adapter.kind;
+        const verdict = classifyStatement(kind, stmt, 'execute');
+        if (verdict.level === 'danger') {
+            const scope = { connId: s.connId, projectKey: s.projectKey };
+            if (!challengeId) {
+                const { id: cid } = this.challenges.create(stmt, scope);
+                this.audit(s.projectKey, s.connId, 'console_exec', stmt, 'danger', false, false, 'NEEDS_CONFIRMATION');
+                return { needConfirmation: true, challengeId: cid, statement: stmt, danger: 'danger', reason: verdict.reason ?? '危险操作，需要用户确认' };
+            }
+            if (!this.challenges.consume(challengeId, stmt, scope)) {
+                this.audit(s.projectKey, s.connId, 'console_exec', stmt, 'danger', false, false, 'INVALID_CHALLENGE');
+                throw new DbToolError('INVALID_CHALLENGE', '确认凭据无效（不存在、已使用、已过期或语句已变更），请重新发起');
+            }
+        }
+        try {
+            const result = await s.run(stmt, params);
+            this.audit(s.projectKey, s.connId, 'console_exec', stmt, verdict.level, verdict.level === 'danger', true, undefined, 'rowCount' in result ? result.rowCount : result.affectedRows);
+            return result;
+        }
+        catch (e) {
+            this.audit(s.projectKey, s.connId, 'console_exec', stmt, verdict.level, verdict.level === 'danger', false, this.errText(e));
+            throw this.toDriverError(e);
+        }
+    }
+    /** 粘性连接提交 → 销毁会话并 close 适配器（对应官方 finally release 语义）；审计照落 */
+    consoleCommit(sessionToken) {
+        return this.consoleTeardown(sessionToken, 'commit');
+    }
+    /** 粘性连接回滚 → 销毁会话并 close 适配器；审计照落 */
+    consoleRollback(sessionToken) {
+        return this.consoleTeardown(sessionToken, 'rollback');
+    }
+    /** commit/rollback 共用结算：授权复核 → 摘除会话 → finish → 审计（verb 参数化，两路镜像合一） */
+    async consoleTeardown(sessionToken, how) {
+        const s = this.requireConsoleSession(sessionToken);
+        s.lastAccess = Date.now();
+        this.recheckConsoleAuth(s);
+        this.consoleSessions.delete(sessionToken); // 先摘除防并发重入；成败都销毁
+        const action = how === 'commit' ? 'console_commit' : 'console_rollback';
+        const verb = how.toUpperCase();
+        try {
+            await s.finish(how);
+            this.audit(s.projectKey, s.connId, action, verb, 'none', false, true);
+            return { message: how === 'commit' ? '事务已提交' : '事务已回滚' };
+        }
+        catch (e) {
+            this.audit(s.projectKey, s.connId, action, verb, 'none', false, false, this.errText(e));
+            throw this.toDriverError(e);
+        }
+    }
     /* -- 审计与状态 -- */
     auditTail(projectPath, limit) {
         const n = Math.max(1, Math.min(500, Math.floor(Number(limit) || 50)));
@@ -296,10 +483,24 @@ export class DbToolService {
             auditTail: this.auditTail(projectPath, 50),
         };
     }
-    /** 关闭缓存的适配器并停止 challenge 清理 */
+    /** 关闭缓存的适配器、回收控制台事务会话并停止 challenge/TTL 清理 */
     async dispose() {
         this.disposed = true;
         this.challenges.dispose();
+        if (this.consoleSweepTimer) {
+            clearInterval(this.consoleSweepTimer);
+            this.consoleSweepTimer = undefined;
+        }
+        const sessions = [...this.consoleSessions.values()];
+        this.consoleSessions.clear();
+        for (const s of sessions) {
+            try {
+                await s.finish('rollback'); // 服务关闭：未提交事务一律回滚，不留悬挂连接
+            }
+            catch {
+                // 已断开等场景忽略
+            }
+        }
         const pending = [...this.adapterCache.values()];
         this.adapterCache.clear();
         for (const p of pending) {
@@ -355,6 +556,162 @@ export class DbToolService {
             }
         }
     }
+    /* -- 控制台事务会话内部 -- */
+    requireConsoleSession(token) {
+        const s = this.consoleSessions.get(token);
+        if (!s)
+            throw new DbToolError('NOT_FOUND', '事务会话不存在（已提交/回滚或空闲超时回收）');
+        return s;
+    }
+    /** 会话存活期间的授权复核（语义与 authorize 一致，但不取适配器） */
+    recheckConsoleAuth(s) {
+        const mode = this.store.grants.check(s.projectKey, s.connId);
+        if (!mode)
+            throw new DbToolError('UNAUTHORIZED_PROJECT', `项目未授权该连接: ${s.connId}`);
+        if (mode === 'ro')
+            throw new DbToolError('READ_ONLY', '该连接对本项目为只读授权（ro），拒绝写操作');
+    }
+    /**
+     * 打开粘性事务通道。按适配器 tx 可选成员的两种运行时形态分派
+     * （见 ConsoleTxSession 注释）。不支持事务的 kind（无 tx）报 INVALID_ARGUMENT。
+     */
+    async openConsoleSession(key, connId, adapter) {
+        const token = 't_' + randomBytes(12).toString('hex');
+        const tx = adapter.tx;
+        if (!tx) {
+            throw new DbToolError('INVALID_ARGUMENT', `连接类型 ${adapter.kind} 不支持控制台事务会话`);
+        }
+        const chain = { p: Promise.resolve() };
+        // 结算标志：commit/rollback/sweep/drop/dispose 并发到达时首个 finisher 生效，后续 no-op
+        // （finish 一律经 enqueue 排到链尾，等在途语句完成再提交/回滚，避免 exec 跑在事务外）
+        let settled = false;
+        const lastAccess = Date.now();
+        if (typeof tx === 'function') {
+            // —— tx(fn) 形态（oracle/dmdb）：挂起 fn 模式。fn 第一段同步登记 exec 通道并
+            //    触发 ready；commit 以 resolve 结束 fn、rollback 以 reject 结束 fn，提交/
+            //    回滚与异常回滚由适配器 tx 原子实现完成。opened 已把 reject 归一为
+            //    { txError }（rollback 属正常路径，不算失败）。exec 通道按语句头返回
+            //    双形状（读语句 QueryResult / 其余 ExecResult，分流在适配器内完成）；
+            //    契约侧（types.ts）exec 返回 unknown，落地形状在 run 处收窄断言。
+            let channel = null;
+            let settle;
+            const done = new Promise((resolve, reject) => {
+                settle = { resolve, reject };
+            });
+            let ready;
+            const readyP = new Promise((r) => {
+                ready = r;
+            });
+            const opened = tx(async (exec) => {
+                channel = exec;
+                ready();
+                await done;
+                return null;
+            })
+                .then(() => ({}), (e) => ({ txError: e }));
+            // begin 等待：fn 被调用（通道就绪）或 tx 开启失败（getConnection/SET TRANSACTION 失败）
+            const outcome = await Promise.race([
+                readyP.then(() => ({ ok: true })),
+                opened.then((v) => ({ ok: false, err: v.txError })),
+            ]);
+            if (!outcome.ok)
+                throw this.toDriverError(outcome.err);
+            return {
+                token,
+                projectKey: key,
+                connId,
+                adapter,
+                lastAccess,
+                run: (stmt, params) => enqueue(chain, async () => {
+                    if (!channel)
+                        throw new DbToolError('DRIVER_ERROR', '事务通道已关闭');
+                    return (await channel(stmt, params));
+                }),
+                finish: (how) => {
+                    // 首个 finisher 生效；任务排到链尾等在途语句完成后才提交/回滚
+                    if (settled)
+                        return Promise.resolve();
+                    settled = true;
+                    return enqueue(chain, async () => {
+                        try {
+                            if (how === 'commit') {
+                                settle.resolve();
+                                const v = await opened;
+                                // commit 路径的 txError 是真实提交失败，必须上抛供审计
+                                if (v.txError !== undefined)
+                                    throw v.txError;
+                            }
+                            else {
+                                // rollback 以 reject 结束 fn：tx 原子实现执行 ROLLBACK 并吞掉回滚自身的
+                                // 次生错误（适配器语义），占位 reject 原因不是真实故障，不上抛
+                                settle.reject(new Error('控制台事务回滚'));
+                                await opened;
+                            }
+                        }
+                        finally {
+                            await adapter.close().catch(() => { });
+                        }
+                    });
+                },
+            };
+        }
+        // —— TxHandle 形态（mysql/pg 系）：begin 即 checkout 粘性连接并执行 BEGIN；
+        //    之后适配器把 query/execute 路由到同一连接，exec 直接透传即可。
+        await tx.begin();
+        return {
+            token,
+            projectKey: key,
+            connId,
+            adapter,
+            lastAccess,
+            run: (stmt, params) => enqueue(chain, () => SQL_READ_HEADS.has(sqlHead(stmt)) ? adapter.query(stmt, params) : adapter.execute(stmt, params)),
+            finish: (how) => {
+                // 首个 finisher 生效；任务排到链尾等在途语句完成后才提交/回滚
+                if (settled)
+                    return Promise.resolve();
+                settled = true;
+                return enqueue(chain, async () => {
+                    try {
+                        if (how === 'commit')
+                            await tx.commit();
+                        else
+                            await tx.rollback();
+                    }
+                    finally {
+                        await adapter.close().catch(() => { });
+                    }
+                });
+            },
+        };
+    }
+    /** 空闲 TTL 扫描：超时会话强制回滚（close 适配器）并审计一条超时回滚 */
+    consoleSweep() {
+        const now = Date.now();
+        for (const [token, s] of this.consoleSessions) {
+            if (now - s.lastAccess <= this.consoleTtlMs)
+                continue;
+            this.consoleSessions.delete(token);
+            void s
+                .finish('rollback')
+                // 回收原因放 statement 说明槽：ok:true 的记录不得带 error 槽（矛盾审计）
+                .then(() => this.audit(s.projectKey, s.connId, 'console_rollback', 'ROLLBACK（空闲超时自动回收）', 'none', false, true))
+                .catch((e) => this.audit(s.projectKey, s.connId, 'console_rollback', 'ROLLBACK', 'none', false, false, `空闲超时自动回滚失败: ${this.errText(e)}`));
+        }
+    }
+    /** 授权变更时回收指定连接的全部控制台事务会话（回滚并 close，不审计——非业务事件） */
+    async dropConsoleSessions(connId) {
+        for (const [token, s] of this.consoleSessions) {
+            if (s.connId !== connId)
+                continue;
+            this.consoleSessions.delete(token);
+            try {
+                await s.finish('rollback');
+            }
+            catch {
+                // 已断开等场景忽略
+            }
+        }
+    }
     adapterFor(connId, mode) {
         const cacheKey = `${connId}@mode=${mode}`;
         let p = this.adapterCache.get(cacheKey);