dsh-db-tool 0.1.0

package/dist/script/worker.cjs

@@ -0,0 +1,104 @@
+/**
+ * run_script 子进程 worker（纯 JS，CommonJS，父进程 fork 直接加载）。
+ *
+ * 安全模型：
+ *  - 脚本运行在 worker 进程的 vm.runInNewContext 新 realm 中，仅注入 db/console；
+ *  - worker 进程以 Node permission model 启动（无文件系统权限），即使脚本逃逸
+ *    vm realm，也读不到 secrets.json 等宿主文件；
+ *  - db 调用经 IPC 回父进程，走完整 guard/challenge/审计链路；
+ *  - 超时由父进程 SIGKILL 强杀（vm timeout 管不到异步，进程级才是真强杀）。
+ *
+ * IPC 协议：
+ *  父→worker {type:'run', code}
+ *  worker→父 {type:'db', reqId, method, args}
+ *  父→worker {type:'dbResult', reqId, ok, result, error}
+ *  worker→父 {type:'done', ok, result, error}
+ */
+'use strict';
+
+const vm = require('node:vm');
+
+process.on('message', (msg) => {
+  if (!msg || msg.type !== 'run') return;
+  runScript(String(msg.code ?? ''));
+});
+
+async function runScript(code) {
+  /** db 请求队列：reqId → resolve */
+  const pending = new Map();
+  let reqSeq = 0;
+
+  const dbCall = (method) => (statement, params) =>
+    new Promise((resolve, reject) => {
+      const reqId = ++reqSeq;
+      pending.set(reqId, { resolve, reject });
+      process.send({ type: 'db', reqId, method, args: [statement, params] });
+    });
+
+  const db = {
+    query: dbCall('query'),
+    execute: dbCall('execute'),
+  };
+
+  const consoleBridge = {
+    log: (...a) => process.send({ type: 'log', level: 'log', text: a.map(fmt).join(' ') }),
+    error: (...a) => process.send({ type: 'log', level: 'error', text: a.map(fmt).join(' ') }),
+  };
+
+  function fmt(v) {
+    if (typeof v === 'string') return v;
+    try {
+      return JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+
+  // 父进程回包分发
+  const onMessage = (msg) => {
+    if (!msg) return;
+    if (msg.type === 'dbResult') {
+      const p = pending.get(msg.reqId);
+      if (!p) return;
+      pending.delete(msg.reqId);
+      if (msg.ok) p.resolve(msg.result);
+      else {
+        const e = new Error(msg.error?.message ?? 'db 调用失败');
+        if (msg.error?.code) e.code = msg.error.code;
+        if (msg.error?.payload !== undefined) e.payload = msg.error.payload;
+        p.reject(e);
+      }
+    }
+  };
+  process.on('message', onMessage);
+
+  let sandbox;
+  try {
+    sandbox = vm.createContext({ db, console: consoleBridge });
+    const script = new vm.Script(`(async () => {\n${code}\n})()`, { filename: 'db-script.js' });
+    const result = await script.runInContext(sandbox, { timeout: 60000 });
+    process.send({ type: 'done', ok: true, result: safeClone(result) });
+  } catch (e) {
+    process.send({
+      type: 'done',
+      ok: false,
+      error: {
+        name: e instanceof Error ? e.name : 'Error',
+        message: e instanceof Error ? e.message : String(e),
+        code: e && typeof e === 'object' && e.code !== undefined ? String(e.code) : undefined,
+        payload: e && typeof e === 'object' && e.payload !== undefined ? safeClone(e.payload) : undefined,
+      },
+    });
+  } finally {
+    process.off('message', onMessage);
+  }
+}
+
+function safeClone(v) {
+  if (v === undefined) return null;
+  try {
+    return JSON.parse(JSON.stringify(v));
+  } catch {
+    return String(v);
+  }
+}

package/dist/store/audit.js

@@ -0,0 +1,41 @@
+/**
+ * audit.jsonl：追加式审计日志。每行一条 JSON，供侧边栏 tail 查看。
+ * 追加写天然原子（单行 < 4KB 时 POSIX/Windows 均保证不交错），
+ * tail 解析时跳过损坏行，单行损坏不影响其余历史。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class AuditLog {
+    file;
+    constructor(dir) {
+        this.file = path.join(dir, 'audit.jsonl');
+    }
+    /** 追加一条审计；ts 省略时自动填充当前 UTC 时间 */
+    append(entry) {
+        const full = { ...entry, ts: entry.ts ?? new Date().toISOString() };
+        fs.appendFileSync(this.file, JSON.stringify(full) + '\n', 'utf8');
+        return full;
+    }
+    /** 最近 n 条（时间正序）。文件不存在返回空数组；损坏行跳过。
+     *  设计取舍：tail 全量读入后取尾。审计日志不轮转（保留完整历史是审计语义），
+     *  单用户桌面工具的量级（数十万行 ≈ 数十 MB）一次性读取在可接受范围；
+     *  反向块读的复杂度不值得。若未来出现服务端长驻场景再优化。 */
+    tail(n) {
+        if (!fs.existsSync(this.file))
+            return [];
+        const lines = fs.readFileSync(this.file, 'utf8').split('\n');
+        const out = [];
+        for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+            const line = lines[i]?.trim();
+            if (!line)
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // 跳过损坏行
+            }
+        }
+        return out.reverse();
+    }
+}

package/dist/store/connections.js

@@ -0,0 +1,167 @@
+/**
+ * connections.json：连接元数据（绝不含密码）。
+ *
+ * create/update 时自动做机密拆分：
+ *  - url → 完整 URL 进 secrets.json，脱敏副本（密码段 ***）留在本文件 urlSafe；
+ *  - fields.password → 进 secrets.json，本文件的 fields 不再含有。
+ * remove 级联清理 secrets 与该连接的全部项目授权。
+ */
+import * as path from 'node:path';
+import { readJson, writeJsonAtomic } from './io.js';
+/** fields 中被视为机密的键，落盘前拆出到 secrets.json */
+const PASSWORD_KEY = 'password';
+/** 将 URL 中的密码段替换为 ***：scheme://user:pass@host → scheme://user:***@host。
+ *  密码可能包含 / ? # @ 等字符：先取 scheme:// 到首个 /?#  的 authority 段，
+ *  在 authority 内以最后一个 @ 分界取 userinfo，再以最后一个 : 分界取密码。 */
+export function redactUrl(url) {
+    const m = url.match(/^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)/i);
+    if (!m)
+        return url;
+    const authority = m[2] ?? '';
+    const at = authority.lastIndexOf('@');
+    if (at < 0)
+        return url; // 无 userinfo
+    const userinfo = authority.slice(0, at);
+    const colon = userinfo.lastIndexOf(':');
+    if (colon < 0)
+        return url; // 只有用户名，无密码段
+    const redacted = m[1] + userinfo.slice(0, colon + 1) + '***@' + authority.slice(at + 1);
+    return redacted + url.slice(m[0].length);
+}
+function splitPassword(fields) {
+    if (!fields || typeof fields[PASSWORD_KEY] !== 'string') {
+        return { clean: fields, password: undefined };
+    }
+    const { [PASSWORD_KEY]: password, ...clean } = fields;
+    return { clean, password: password };
+}
+/** ConnRecord → 用户可见的 ConnectionMeta（契约见 lib/adapters/types.ts） */
+function toMeta(rec) {
+    const meta = { id: rec.id, kind: rec.kind };
+    if (rec.name !== undefined)
+        meta.name = rec.name;
+    if (rec.urlSafe !== undefined)
+        meta.safeUrl = rec.urlSafe;
+    if (rec.fields) {
+        const { host, port, database } = rec.fields;
+        if (typeof host === 'string')
+            meta.host = host;
+        if (typeof port === 'number')
+            meta.port = port;
+        if (typeof database === 'string')
+            meta.database = database;
+    }
+    return meta;
+}
+export class ConnectionStore {
+    secrets;
+    grants;
+    file;
+    constructor(dir, secrets, grants) {
+        this.secrets = secrets;
+        this.grants = grants;
+        this.file = path.join(dir, 'connections.json');
+    }
+    load() {
+        return readJson(this.file, { connections: [] });
+    }
+    save(data) {
+        writeJsonAtomic(this.file, data);
+    }
+    findRec(data, id) {
+        return data.connections.find((c) => c.id === id);
+    }
+    list() {
+        return this.load().connections.map(toMeta);
+    }
+    get(id) {
+        const rec = this.findRec(this.load(), id);
+        return rec ? toMeta(rec) : undefined;
+    }
+    /** 新建连接；id 已存在时抛错 */
+    create(input) {
+        const data = this.load();
+        if (this.findRec(data, input.id)) {
+            throw new Error(`连接已存在: ${input.id}`);
+        }
+        const rec = { id: input.id, kind: input.kind };
+        if (input.name !== undefined)
+            rec.name = input.name;
+        if (input.ssl !== undefined)
+            rec.ssl = input.ssl;
+        const { clean, password } = splitPassword(input.fields);
+        if (clean !== undefined)
+            rec.fields = clean;
+        const secretPatch = {};
+        if (input.url !== undefined) {
+            rec.urlSafe = redactUrl(input.url);
+            secretPatch.url = input.url;
+        }
+        if (password !== undefined)
+            secretPatch.password = password;
+        if (Object.keys(secretPatch).length > 0)
+            this.secrets.set(input.id, secretPatch);
+        data.connections.push(rec);
+        this.save(data);
+        return toMeta(rec);
+    }
+    /** 部分更新；不存在返回 undefined。url/fields 变更时同步拆分 secrets */
+    update(id, patch) {
+        const data = this.load();
+        const rec = this.findRec(data, id);
+        if (!rec)
+            return undefined;
+        if (patch.name !== undefined)
+            rec.name = patch.name;
+        if (patch.ssl !== undefined)
+            rec.ssl = patch.ssl;
+        if (patch.fields !== undefined) {
+            const { clean, password } = splitPassword(patch.fields);
+            rec.fields = clean;
+            if (password !== undefined)
+                this.secrets.set(id, { password });
+        }
+        if (patch.url !== undefined) {
+            rec.urlSafe = redactUrl(patch.url);
+            this.secrets.set(id, { url: patch.url });
+        }
+        this.save(data);
+        return toMeta(rec);
+    }
+    /** 删除连接，级联删除 secrets 与该连接的所有项目授权。
+     *  顺序按"失败开放"原则：先删权限（grants），再删机密（secrets），最后改
+     *  连接表——中途崩溃最多残留垃圾机密，绝不残留可用授权。 */
+    remove(id) {
+        const data = this.load();
+        const idx = data.connections.findIndex((c) => c.id === id);
+        if (idx < 0)
+            return false;
+        this.grants.removeConn(id);
+        this.secrets.delete(id);
+        data.connections.splice(idx, 1);
+        this.save(data);
+        return true;
+    }
+    /**
+     * 组装适配器工厂所需的 ResolvedConnection（含真实密码，绝不返回给模型/HTTP）。
+     * 不存在抛错——调用方（工具服务层）应先 get() 展示层校验。
+     */
+    testTarget(id) {
+        const rec = this.findRec(this.load(), id);
+        if (!rec)
+            throw new Error(`连接不存在: ${id}`);
+        const meta = toMeta(rec);
+        const rc = { meta };
+        const sec = this.secrets.get(id);
+        if (sec?.url !== undefined)
+            rc.url = sec.url;
+        let fields = rec.fields ? { ...rec.fields } : undefined;
+        if (sec?.password !== undefined)
+            (fields ??= {}).password = sec.password;
+        if (fields !== undefined)
+            rc.fields = fields;
+        if (rec.ssl !== undefined)
+            rc.ssl = rec.ssl;
+        return rc;
+    }
+}

package/dist/store/grants.js

@@ -0,0 +1,82 @@
+/**
+ * grants.json：项目级连接授权（ro/rw）。
+ * 键是 normalizeProjectKey 归一化后的项目路径。
+ */
+import * as path from 'node:path';
+import { readJson, writeJsonAtomic } from './io.js';
+export class GrantStore {
+    file;
+    constructor(dir) {
+        this.file = path.join(dir, 'grants.json');
+    }
+    load() {
+        return readJson(this.file, { grants: {} });
+    }
+    save(data) {
+        // 0600 对齐 dsh-ssh-tunnel：授权关系本身也是敏感面（泄露项目↔库映射）
+        writeJsonAtomic(this.file, data, 0o600);
+    }
+    /** 某项目的全部授权（不含 grantedAt，展示层无需时间戳） */
+    grantsFor(projectKey) {
+        return (this.load().grants[projectKey] ?? []).map(({ connId, mode }) => ({ connId, mode }));
+    }
+    /** 授权或改授权（同连接重复授权视为更新模式） */
+    grant(projectKey, connId, mode) {
+        const data = this.load();
+        const list = data.grants[projectKey] ?? [];
+        const existing = list.find((g) => g.connId === connId);
+        if (existing) {
+            existing.mode = mode;
+            existing.grantedAt = new Date().toISOString();
+        }
+        else {
+            list.push({ connId, mode, grantedAt: new Date().toISOString() });
+        }
+        data.grants[projectKey] = list;
+        this.save(data);
+    }
+    /** 撤销某项目对某连接的授权。不存在时静默返回 */
+    revoke(projectKey, connId) {
+        const data = this.load();
+        const list = data.grants[projectKey];
+        if (!list)
+            return;
+        const next = list.filter((g) => g.connId !== connId);
+        if (next.length === list.length)
+            return;
+        if (next.length === 0)
+            delete data.grants[projectKey];
+        else
+            data.grants[projectKey] = next;
+        this.save(data);
+    }
+    /** 检查授权模式；未授权返回 undefined（ro < rw，rw 覆盖 ro） */
+    check(projectKey, connId) {
+        const modes = (this.load().grants[projectKey] ?? [])
+            .filter((g) => g.connId === connId)
+            .map((g) => g.mode);
+        if (modes.includes('rw'))
+            return 'rw';
+        return modes.includes('ro') ? 'ro' : undefined;
+    }
+    /** 级联清理：删除某连接在全项目范围的授权（由 ConnectionStore.remove 调用） */
+    removeConn(connId) {
+        const data = this.load();
+        let dirty = false;
+        for (const key of Object.keys(data.grants)) {
+            const list = data.grants[key];
+            if (!list)
+                continue;
+            const next = list.filter((g) => g.connId !== connId);
+            if (next.length !== list.length) {
+                dirty = true;
+                if (next.length === 0)
+                    delete data.grants[key];
+                else
+                    data.grants[key] = next;
+            }
+        }
+        if (dirty)
+            this.save(data);
+    }
+}

package/dist/store/index.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-db-tool 存储层顶层入口。
+ *
+ * 四类持久化数据位于 `$DSH_HOME/db-tool/`（DSH_HOME 环境变量，缺省 ~/.dsh）：
+ *  - connections.json  连接元数据（不含密码，权限跟随目录 0700）
+ *  - secrets.json      机密（密码/完整 URL，权限 0600）
+ *  - grants.json       项目级连接授权
+ *  - audit.jsonl       追加式审计日志
+ *
+ * 构造参数 homeDir 仅供测试注入临时目录。
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { AuditLog } from './audit.js';
+import { ConnectionStore } from './connections.js';
+import { GrantStore } from './grants.js';
+import { chmodBestEffort } from './io.js';
+import { SecretsBox } from './secrets.js';
+export { normalizeProjectKey } from './normalize.js';
+export { redactUrl } from './connections.js';
+export { AuditLog, ConnectionStore, GrantStore, SecretsBox };
+export class DbToolStore {
+    /** 数据目录：$DSH_HOME/db-tool */
+    dir;
+    connections;
+    secrets;
+    grants;
+    audit;
+    constructor(homeDir) {
+        // || 而非 ??: DSH_HOME=""（空串）视为未设置，避免产出相对路径 'db-tool/'
+        const home = homeDir ?? (process.env['DSH_HOME'] || path.join(os.homedir(), '.dsh'));
+        this.dir = path.join(home, 'db-tool');
+        fs.mkdirSync(this.dir, { recursive: true });
+        chmodBestEffort(this.dir, 0o700);
+        this.secrets = new SecretsBox(this.dir);
+        this.grants = new GrantStore(this.dir);
+        this.audit = new AuditLog(this.dir);
+        this.connections = new ConnectionStore(this.dir, this.secrets, this.grants);
+    }
+}

package/dist/store/io.js

@@ -0,0 +1,66 @@
+/**
+ * 存储层文件 IO 基础设施：原子写 + 损坏容错读 + 尽力而为的权限设置。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * 尽力而为地设置 POSIX 权限。
+ * Windows 的 chmod 仅支持只读位，失败时静默忽略，绝不崩溃。
+ */
+export function chmodBestEffort(target, mode) {
+    try {
+        fs.chmodSync(target, mode);
+    }
+    catch {
+        // 权限设置失败（Windows 等）不影响功能
+    }
+}
+/**
+ * 原子写 JSON：先写同目录临时文件，再 rename 覆盖目标。
+ * rename 在同一文件系统内是原子操作，进程崩溃也不会留下半个 JSON。
+ * fileMode 提供时写完设置文件权限（secrets.json 传 0o600）。
+ */
+export function writeJsonAtomic(file, value, fileMode) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    // tmp 以目标权限创建：机密文件（0600）在 rename 前的窗口期/失败残留时不暴露宽权限内容
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf8', mode: fileMode ?? 0o666 });
+    try {
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // 清理失败不掩盖原始错误
+        }
+        throw err;
+    }
+    if (fileMode !== undefined)
+        chmodBestEffort(file, fileMode);
+}
+/**
+ * 容错读 JSON：
+ *  - 文件不存在 → 返回 fallback（不创建文件，首次写时才落盘）；
+ *  - 解析失败（文件损坏/被截断）→ 将原文件备份为 `<file>.bak` 后返回 fallback，
+ *    让调用方以空数据继续工作，损坏现场保留在 .bak 供人工恢复。
+ */
+export function readJson(file, fallback) {
+    if (!fs.existsSync(file))
+        return fallback;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        try {
+            fs.rmSync(`${file}.bak`, { force: true });
+            fs.renameSync(file, `${file}.bak`);
+        }
+        catch {
+            // 备份失败也要继续重建
+        }
+        return fallback;
+    }
+}

package/dist/store/normalize.js

@@ -0,0 +1,22 @@
+/**
+ * projectPathKey 规范化。
+ *
+ * 授权记录以项目路径为键，同一项目可能以不同写法出现：
+ * 大小写不同的盘符、正/反斜杠、尾分隔符、相对路径。
+ * 所有入口（授权、检查、审计）必须先经本函数归一化，
+ * 否则同一项目会产生多条授权记录，ro/rw 检查会漏判。
+ *
+ * 规则（按序）：
+ *  1. path.resolve → 转为绝对路径（相对路径基于 cwd 解析）
+ *  2. 分隔符统一为 '/'
+ *  3. Windows 盘符小写（'C:/' 与 'c:/' 是同一目录）
+ *  4. 去尾分隔符（'c:/code/proj/' → 'c:/code/proj'）
+ */
+import * as path from 'node:path';
+export function normalizeProjectKey(p) {
+    let key = path.resolve(p).replace(/\\/g, '/');
+    key = key.replace(/^([A-Z]):/, (_m, drive) => `${drive.toLowerCase()}:`);
+    if (key.length > 1)
+        key = key.replace(/\/+$/, '');
+    return key;
+}

package/dist/store/secrets.js

@@ -0,0 +1,42 @@
+/**
+ * secrets.json：连接级机密存储（密码、完整 URL、其余敏感键值）。
+ *
+ * 硬性约束：
+ *  - 文件落盘后设置权限 0600（Windows 上尽力而为，失败不崩溃）；
+ *  - 本类的任何返回值都是浅拷贝，外部改动不污染内部状态；
+ *  - 机密绝不进入 connections.json / grants.json / 审计等其它文件。
+ */
+import * as path from 'node:path';
+import { readJson, writeJsonAtomic } from './io.js';
+const FILE_MODE = 0o600;
+export class SecretsBox {
+    file;
+    constructor(dir) {
+        this.file = path.join(dir, 'secrets.json');
+    }
+    load() {
+        return readJson(this.file, { secrets: {} });
+    }
+    save(data) {
+        writeJsonAtomic(this.file, data, FILE_MODE);
+    }
+    /** 读取某连接的机密（浅拷贝）。不存在返回 undefined。 */
+    get(connId) {
+        const entry = this.load().secrets[connId];
+        return entry ? { ...entry } : undefined;
+    }
+    /** 合并写入机密（保留未提及的旧键） */
+    set(connId, patch) {
+        const data = this.load();
+        data.secrets[connId] = { ...(data.secrets[connId] ?? {}), ...patch };
+        this.save(data);
+    }
+    /** 删除某连接的全部机密。不存在时静默返回。 */
+    delete(connId) {
+        const data = this.load();
+        if (!(connId in data.secrets))
+            return;
+        delete data.secrets[connId];
+        this.save(data);
+    }
+}

package/docs/api-contract.md

@@ -0,0 +1,76 @@
+# dsh-db-tool HTTP API 契约（v1）
+
+侧边栏 client 与 lib/http 实现共同遵守。API 仅监听 loopback（127.0.0.1），校验 `Origin`/`Referer` 必须来自 DSH 本地 web（同源 fenced）。所有请求/响应 JSON。
+
+## 通用约定
+
+- 成功：`200 { "ok": true, "data": ... }`
+- 失败：`{ "ok": false, "error": string, "code": string }`，code ∈ `UNAUTHORIZED_PROJECT`（项目未授权该连接）/ `READ_ONLY`（ro 连接拒绝 execute）/ `NEEDS_CONFIRMATION`（危险操作待确认）/ `INVALID_CHALLENGE` / `NOT_FOUND` / `INVALID_ARGUMENT`（参数非法；插件 dispose 后的新请求同样返回此 code，error 为「服务已关闭」）/ `DRIVER_ERROR`
+- `projectPath`：前端传入当前 workspace 绝对路径，服务端用 `normalizeProjectKey` 归一后校验 grants；**不传视为匿名项目**（仅连接管理可用，业务操作一律拒）
+- 人工确认通道：SQL 控制台是人工操作，危险语句同样走 challenge 流程——前端展示确认对话框后携 `challengeId` 重发
+- 除注明外，业务端点均需 projectPath 且该连接已授权
+
+## 路由
+
+### 连接管理（无需 projectPath）
+
+| 方法/路径 | 说明 |
+|---|---|
+| `GET /api/connections` | 全量连接列表（脱敏 ConnectionMeta[]，含每库 kind） |
+| `POST /api/connections` | 创建 `{ id, kind, name?, url?, fields?, ssl? }`；密码自动拆入 secrets |
+| `PUT /api/connections/:id` | 更新（同上字段可选） |
+| `DELETE /api/connections/:id` | 删除（级联 secrets + 全项目 grants） |
+| `POST /api/connections/:id/test` | 测试连接 → `TestConnectResult` |
+
+### 项目授权
+
+| 方法/路径 | 说明 |
+|---|---|
+| `GET /api/grants?project=<path>` | 该项目授权列表 `{ connId, mode }[]` |
+| `PUT /api/grants` | `{ projectPath, connId, mode: "ro"\|"rw" }` 授权/改模式 |
+| `DELETE /api/grants` | `{ projectPath, connId }` 撤销 |
+
+### 浏览（需授权，ro 即可）
+
+| 方法/路径 | 说明 |
+|---|---|
+| `GET /api/databases?project=<path>&connId=` | 库/schema 清单 string[] |
+| `GET /api/tables?project=<path>&connId=&database=` | TableInfo[] |
+| `GET /api/schema?project=<path>&connId=&database=&table=` | ColumnInfo[] |
+| `GET /api/preview?project=<path>&connId=&database=&table=&limit=&offset=` | QueryResult（limit≤50 强制；offset 为行偏移，翻页用，默认 0） |
+
+### SQL 控制台 / 脚本（需授权，execute 需 rw）
+
+| 方法/路径 | 说明 |
+|---|---|
+| `POST /api/query` | `{ projectPath, connId, sql, params?, challengeId? }` → QueryResult；危险读（如 KEYS）同样触发 NEEDS_CONFIRMATION |
+| `POST /api/execute` | `{ projectPath, connId, statement, params?, challengeId? }` → ExecResult 或 `NEEDS_CONFIRMATION { challengeId, statement, danger, reason }` |
+| `POST /api/script` | `{ projectPath, connId, code, challengeId? }` → 子进程沙箱执行（Node permission model 禁 fs + 新 vm realm 双层隔离），60s 强超时；db 句柄经 IPC 走完整 guard/审计链路 |
+
+### 审计
+
+| 方法/路径 | 说明 |
+|---|---|
+| `GET /api/audit?project=<path>&limit=` | AuditEntry[]（最近 n 条，默认 50） |
+
+### 状态
+
+| 方法/路径 | 说明 |
+|---|---|
+| `GET /api/state?project=<path>` | 面板初始化：`{ connections, grants, auditTail }` |
+
+## NEEDS_CONFIRMATION 语义
+
+```json
+{
+  "ok": false,
+  "code": "NEEDS_CONFIRMATION",
+  "challengeId": "c_9f3a…",
+  "statement": "DROP TABLE users",
+  "danger": "danger",
+  "reason": "DDL 不可回滚（隐式提交）"
+}
+```
+
+- `challengeId` 一次性、绑定语句 hash、5 分钟过期；重发请求带同 `challengeId` 且语句 hash 一致才放行
+- 模型工具（对话内）用同一 guard/challenge 实现，确认经 ask_user 完成