dsh-db-tool 0.1.0

package/dist/http/index.js

@@ -0,0 +1,396 @@
+/**
+ * lib/http：数据库工具 HTTP API（docs/api-contract.md v1）。
+ *
+ * 默认挂载方式：由插件入口经 DSH webServer（kind:'prefix'，/dsh-db-tool/api）
+ * 调用 handleDbToolRequest——前端同源相对路径 fetch 即可达。
+ *
+ * trust 校验（等价移植 dsh-ssh-tunnel lib/shared/http-trust.js，自包含）：
+ *  - Host 必须是 loopback（或 ctx.webRuntime.trustedHosts 中的条目）；
+ *  - 带 Origin/Referer 时其 host 必须是 loopback（且同端口）或受信条目。
+ *  - 0.0.0.0 不是 loopback。违者 403 FORBIDDEN。
+ *
+ * 统一响应：成功 {ok:true,data}；失败 {ok:false,error,code}（业务错 HTTP 200，
+ * code 供前端分支）；协议级错误（403/404/405/400）用 HTTP 状态码。
+ * NEEDS_CONFIRMATION 返回扁平 {ok:false,code,challengeId,statement,danger,reason}。
+ */
+import * as http from 'node:http';
+import { DbToolError } from '../manager.js';
+export const MAX_JSON_BODY_BYTES = 2 * 1024 * 1024;
+/* ---------------- trust 校验（自包含，逻辑等价 dsh-ssh-tunnel http-trust.js） ---------------- */
+export function isLoopbackHostname(hostname) {
+    const h = String(hostname ?? '')
+        .replace(/^\[|\]$/g, '')
+        .toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+}
+function originHostPort(originHeader) {
+    try {
+        const u = new URL(String(originHeader));
+        const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        const port = u.port || (u.protocol === 'https:' ? '443' : u.protocol === 'http:' ? '80' : '');
+        return { host, port, hostHeaderLike: port !== '' ? `${host}:${port}` : host };
+    }
+    catch {
+        return null;
+    }
+}
+/** Host 必须 loopback 或在 trustedHosts；Origin/Referer 存在时必须 loopback 同端口或受信 */
+export function isTrustedRequest(req, trustedHosts) {
+    try {
+        const hostHeader = req.headers?.host;
+        if (!hostHeader)
+            return false;
+        const url = new URL(`http://${hostHeader}`);
+        const reqHost = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        const list = Array.isArray(trustedHosts) ? trustedHosts : [];
+        const hostOk = isLoopbackHostname(reqHost) ||
+            list.some((entry) => {
+                const e = String(entry);
+                return e === hostHeader || e === url.hostname || e === url.host;
+            });
+        if (!hostOk)
+            return false;
+        const origin = req.headers?.origin ?? req.headers?.referer ?? '';
+        if (origin === '')
+            return true;
+        const parsed = originHostPort(origin);
+        if (!parsed)
+            return false;
+        if (isLoopbackHostname(parsed.host) && isLoopbackHostname(reqHost)) {
+            const reqPort = url.port || '80';
+            if (parsed.port !== '' && parsed.port !== reqPort)
+                return false;
+            return true;
+        }
+        return list.some((entry) => {
+            const e = String(entry);
+            return e === parsed.hostHeaderLike || e === parsed.host || e === origin;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 处理一个数据库工具 API 请求（可在 webServer prefix handler 中直接调用）。
+ * 兼容两种路径形态：独立挂载 /api/...，prefix 挂载 /dsh-db-tool/api/...
+ * （取 pathname 中 /api 起的路由段匹配）。
+ */
+export async function handleDbToolRequest(req, res, service, opts) {
+    try {
+        // 1) trust 校验（DNS rebinding / 跨站防护）
+        if (!isTrustedRequest(req, opts?.trustedHosts)) {
+            send(res, 403, { ok: false, error: '非本机来源，已拒绝', code: 'FORBIDDEN' });
+            return;
+        }
+        const hostHeader = req.headers.host ?? '';
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, { 'Access-Control-Max-Age': '600' });
+            res.end();
+            return;
+        }
+        // 2) 路径规范化：截取 /api 起的路由段
+        const url = new URL(req.url ?? '/', `http://${hostHeader || '127.0.0.1'}`);
+        let rawPath = url.pathname;
+        if (!rawPath.endsWith('/api') && !rawPath.includes('/api/')) {
+            send(res, 404, { ok: false, error: `未知路由: ${req.method} ${rawPath}`, code: 'NOT_FOUND' });
+            return;
+        }
+        const apiIdx = rawPath.indexOf('/api/');
+        if (rawPath.endsWith('/api')) {
+            rawPath = '/api';
+        }
+        else if (apiIdx >= 0) {
+            rawPath = rawPath.slice(apiIdx);
+        }
+        const path = rawPath.replace(/\/+$/, '') || '/';
+        const q = url.searchParams;
+        await route(req, res, service, path, q, opts);
+    }
+    catch (e) {
+        sendError(res, e);
+    }
+}
+async function route(req, res, service, path, q, opts) {
+    // 项目上下文权威解析：host 端会话 header.cwd 优先（对齐 ssh-tunnel getProjectContext 语义）
+    if (path === '/api/project-context' && req.method === 'POST') {
+        const b = await readBody(req);
+        const sessionId = str(b['sessionId'] ?? b['session_id']);
+        const fallbackCwd = str(b['cwd'] ?? b['projectPath'] ?? '');
+        if (!opts?.resolveProject) {
+            // 未提供解析器（如独立测试挂载）：仅归一化回退值
+            const key = fallbackCwd ? service.projectKey(fallbackCwd) : '';
+            return sendOk(res, { sessionId, projectPathKey: key, hasProject: key !== '' });
+        }
+        return sendOk(res, { sessionId, ...opts.resolveProject(sessionId, fallbackCwd) });
+    }
+    if (path === '/api/connections') {
+        if (req.method === 'GET')
+            return sendOk(res, service.listConnections());
+        if (req.method === 'POST') {
+            const b = await readBody(req);
+            // id 留空自动生成（前端提示「留空则自动生成」）
+            const id = str(b['id']) || `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+            const kind = str(b['kind']);
+            if (!kind)
+                return send(res, 400, { ok: false, error: '缺少 kind', code: 'INVALID_ARGUMENT' });
+            const ssl = parseSsl(b['ssl']);
+            if (ssl === 'invalid')
+                return send(res, 400, { ok: false, error: 'ssl 必须是布尔值', code: 'INVALID_ARGUMENT' });
+            return sendOk(res, service.createConnection({
+                id, kind: kind,
+                ...(b['name'] !== undefined ? { name: str(b['name']) } : {}),
+                ...(b['url'] !== undefined ? { url: str(b['url']) } : {}),
+                ...(b['fields'] !== undefined ? { fields: b['fields'] } : {}),
+                ...(ssl !== undefined ? { ssl } : {}),
+            }));
+        }
+    }
+    // 测试未保存的连接草稿（保存前测试；不落库）
+    if (path === '/api/test-draft' && req.method === 'POST') {
+        const b = await readBody(req);
+        const kind = str(b['kind']);
+        if (!kind)
+            return send(res, 400, { ok: false, error: '缺少 kind', code: 'INVALID_ARGUMENT' });
+        const ssl = parseSsl(b['ssl']);
+        if (ssl === 'invalid')
+            return send(res, 400, { ok: false, error: 'ssl 必须是布尔值', code: 'INVALID_ARGUMENT' });
+        return sendMaybeConfirm(res, service.testDraft({
+            kind: kind,
+            ...(b['url'] !== undefined ? { url: str(b['url']) } : {}),
+            ...(b['fields'] !== undefined ? { fields: b['fields'] } : {}),
+            ...(ssl !== undefined ? { ssl } : {}),
+        }));
+    }
+    const connMatch = /^\/api\/connections\/([^/]+)(\/test)?$/.exec(path);
+    if (connMatch) {
+        const id = decodeURIComponent(connMatch[1] ?? '');
+        if (connMatch[2] === '/test' && req.method === 'POST') {
+            return sendMaybeConfirm(res, service.testConnection(id));
+        }
+        if (req.method === 'PUT') {
+            const b = await readBody(req);
+            const ssl = parseSsl(b['ssl']);
+            if (ssl === 'invalid')
+                return send(res, 400, { ok: false, error: 'ssl 必须是布尔值', code: 'INVALID_ARGUMENT' });
+            return sendOk(res, service.updateConnection(id, {
+                ...(b['name'] !== undefined ? { name: str(b['name']) } : {}),
+                ...(b['url'] !== undefined ? { url: str(b['url']) } : {}),
+                ...(b['fields'] !== undefined ? { fields: b['fields'] } : {}),
+                ...(ssl !== undefined ? { ssl } : {}),
+            }));
+        }
+        if (req.method === 'DELETE') {
+            service.removeConnection(id);
+            return sendOk(res, { removed: id });
+        }
+    }
+    if (path === '/api/grants') {
+        if (req.method === 'GET') {
+            const project = q.get('project') ?? '';
+            return sendOk(res, service.grantsFor(project));
+        }
+        if (req.method === 'PUT') {
+            const b = await readBody(req);
+            const mode = str(b['mode']);
+            if (mode !== 'ro' && mode !== 'rw')
+                return send(res, 400, { ok: false, error: 'mode 必须是 ro 或 rw', code: 'INVALID_ARGUMENT' });
+            service.grant(str(b['projectPath'] ?? b['project'] ?? ''), str(b['connId']), mode);
+            return sendOk(res, { granted: true });
+        }
+        if (req.method === 'DELETE') {
+            const b = await readBody(req);
+            service.revokeGrant(str(b['projectPath'] ?? b['project'] ?? ''), str(b['connId']));
+            return sendOk(res, { revoked: true });
+        }
+    }
+    if (path === '/api/databases' && req.method === 'GET') {
+        return sendOk(res, await service.databases(projectOf(q), required(q, 'connId')));
+    }
+    if (path === '/api/tables' && req.method === 'GET') {
+        return sendOk(res, await service.tables(projectOf(q), required(q, 'connId'), q.get('database') ?? undefined));
+    }
+    if (path === '/api/schema' && req.method === 'GET') {
+        return sendOk(res, await service.schema(projectOf(q), required(q, 'connId'), required(q, 'table'), q.get('database') ?? undefined));
+    }
+    if (path === '/api/preview' && req.method === 'GET') {
+        const limit = q.get('limit') !== null ? Number(q.get('limit')) : undefined;
+        return sendOk(res, await service.preview(projectOf(q), required(q, 'connId'), required(q, 'table'), limit, q.get('database') ?? undefined, q.get('offset') ? Number(q.get('offset')) : undefined));
+    }
+    if (path === '/api/query' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.query(projectOfBody(b), str(b['connId']), str(b['sql']), b['params'], optStr(b['challengeId'])));
+    }
+    if (path === '/api/execute' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.execute(projectOfBody(b), str(b['connId']), str(b['statement']), b['params'], optStr(b['challengeId'])));
+    }
+    if (path === '/api/script' && req.method === 'POST') {
+        const b = await readBody(req);
+        return await sendMaybeConfirm(res, service.runScript(projectOfBody(b), str(b['connId']), str(b['code']), optStr(b['challengeId'])));
+    }
+    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));
+    }
+    if (path === '/api/state' && req.method === 'GET') {
+        return sendOk(res, service.state(q.get('project') ?? undefined));
+    }
+    send(res, 404, { ok: false, error: `未知路由: ${req.method} ${path}`, code: 'NOT_FOUND' });
+}
+export class DbToolHttpServer {
+    service;
+    opts;
+    server = null;
+    actualPort = 0;
+    actualHost = '';
+    constructor(service, opts) {
+        this.service = service;
+        this.opts = opts;
+    }
+    /** 启动并解析端口；返回实际监听地址 */
+    start() {
+        if (this.server)
+            return Promise.resolve(this.address());
+        const server = http.createServer((req, res) => {
+            void handleDbToolRequest(req, res, this.service, { trustedHosts: this.opts?.trustedHosts }).catch(() => {
+                send(res, 500, { ok: false, error: 'internal error', code: 'DRIVER_ERROR' });
+            });
+        });
+        this.server = server;
+        return new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(this.opts?.port ?? 0, this.opts?.host ?? '127.0.0.1', () => {
+                const addr = server.address();
+                if (addr && typeof addr === 'object') {
+                    this.actualPort = addr.port;
+                    this.actualHost = addr.address;
+                }
+                resolve(this.address());
+            });
+        });
+    }
+    address() {
+        const host = this.actualHost || this.opts?.host || '127.0.0.1';
+        const port = this.actualPort || this.opts?.port || 0;
+        return { host, port, url: `http://${host}:${port}` };
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        if (!server)
+            return;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}
+/* ---------------- 辅助 ---------------- */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_JSON_BODY_BYTES) {
+                reject(new DbToolError('INVALID_ARGUMENT', '请求体超过 2MB 上限'));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf8').trim();
+            if (text === '')
+                return resolve({});
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    resolve(parsed);
+                }
+                else {
+                    reject(new DbToolError('INVALID_ARGUMENT', '请求体必须是 JSON 对象'));
+                }
+            }
+            catch {
+                reject(new DbToolError('INVALID_ARGUMENT', '请求体不是合法 JSON'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function send(res, status, body) {
+    if (!res.headersSent)
+        res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+function sendOk(res, data) {
+    send(res, 200, { ok: true, data });
+}
+/** service 结果可能是值或 NeedConfirm（script 则以 NEEDS_CONFIRMATION DbToolError 抛出） */
+async function sendMaybeConfirm(res, p) {
+    try {
+        const r = await p;
+        if (isNeedConfirm(r)) {
+            send(res, 200, { ok: false, code: 'NEEDS_CONFIRMATION', ...r });
+        }
+        else {
+            sendOk(res, r);
+        }
+    }
+    catch (e) {
+        sendError(res, e);
+    }
+}
+function sendError(res, e) {
+    // 脚本内危险语句以 DbToolError('NEEDS_CONFIRMATION', JSON) 抛出 → 还原为扁平响应
+    if (e instanceof DbToolError && e.code === 'NEEDS_CONFIRMATION') {
+        try {
+            const nc = JSON.parse(e.message);
+            if (isNeedConfirm(nc)) {
+                send(res, 200, { ok: false, code: 'NEEDS_CONFIRMATION', ...nc });
+                return;
+            }
+        }
+        catch {
+            // fallthrough
+        }
+    }
+    if (e instanceof DbToolError) {
+        send(res, 200, { ok: false, error: e.message, code: e.code });
+        return;
+    }
+    send(res, 200, { ok: false, error: e instanceof Error ? e.message : String(e), code: 'DRIVER_ERROR' });
+}
+function isNeedConfirm(v) {
+    return Boolean(v && typeof v === 'object' && v.needConfirmation === true);
+}
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** ssl 字段严格布尔解析：防 Boolean("false") === true 的坑。非法值返回 'invalid' */
+function parseSsl(v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v === 'boolean')
+        return v;
+    if (v === 'true')
+        return true;
+    if (v === 'false')
+        return false;
+    return 'invalid';
+}
+function optStr(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+function projectOf(q) {
+    return q.has('project') ? (q.get('project') ?? undefined) : undefined;
+}
+function projectOfBody(b) {
+    const v = b['projectPath'] ?? b['project'];
+    return typeof v === 'string' ? v : undefined;
+}
+function required(q, name) {
+    const v = q.get(name);
+    if (!v)
+        throw new DbToolError('INVALID_ARGUMENT', `缺少查询参数: ${name}`);
+    return v;
+}

package/dist/index.js

@@ -0,0 +1,130 @@
+/**
+ * dsh-db-tool 插件入口（形态对齐 dsh-ssh-tunnel：apply(ctx) + inject + ctx.effect）。
+ *
+ *  - 注册 DatabaseManager 模型工具（单工具多 action），projectPath 取自
+ *    session header.cwd（不信任模型自报），业务操作经 GrantStore 授权。
+ *  - HTTP API 挂载在 DSH webServer（prefix /dsh-db-tool/api）：前端同源
+ *    相对路径 fetch('/dsh-db-tool/api/...') 即可达；trust 校验移植
+ *    http-trust 逻辑（Host loopback / trustedHosts + Origin 同源校验）。
+ *  - ctx.effect 收尾：注销 HTTP 路由、关适配器、停 challenge 清理。
+ */
+import { DbToolStore, normalizeProjectKey } from './store/index.js';
+import { DbToolService, handleToolAction } from './manager.js';
+import { handleDbToolRequest } from './http/index.js';
+/** cordis 注入清单（服务名以 dsh-ssh-tunnel 为准） */
+export const inject = ['webServer', 'sessions', 'tools', 'webRuntime'];
+const TOOL_DESCRIPTION = `数据库管理工具（dsh-db-tool）：在已配置的数据库连接上执行查询/写操作/脚本。
+
+权限模型（务必遵守）：
+- 每个连接对当前项目有 ro（只读）或 rw（读写）授权；未授权连接的一切业务操作被拒绝。
+- ro 连接上 execute / run_script 直接被拒（READ_ONLY）；适配器层另有会话级只读双保险。
+- 危险操作（DDL、删库、FLUSHALL 等）不会直接执行：返回 NEEDS_CONFIRMATION 与 challengeId。
+  此时你必须先向用户说明语句与风险并征得明确同意，然后带着同一 challengeId 与原语句重试；
+  challenge 一次性、绑定语句、5 分钟内有效。绝不要在未获用户同意时重试。
+
+action 说明：
+- list_connections：列出连接（脱敏，含各连接的 kind 与授权信息需另经 HTTP 面板查看）。
+- query：只读 SQL/命令（conn_id, sql, params?）。
+- execute：写操作/DDL（conn_id, statement, params?）。
+- schema：结构浏览（conn_id；给 table 查列、给 database 查表、都不给列库）。
+- preview：预览行，limit≤50（conn_id, table, database?, limit?）。
+- run_script：子进程沙箱脚本（conn_id, code），60s 超时强杀，permission model 禁文件
+  访问 + 新 vm realm 双层隔离，仅注入受限 db.query/db.execute 句柄（经完整
+  guard/审计链路），rw 连接才有写能力。`;
+export function apply(ctx) {
+    const log = ctx.logger ?? { info: () => { }, error: () => { } };
+    const store = new DbToolStore();
+    const service = new DbToolService(store);
+    // HTTP API：挂在 DSH webServer 的 /dsh-db-tool/api 前缀下（同源访问）
+    const trustedHosts = () => {
+        try {
+            return ctx.webRuntime?.trustedHosts ?? [];
+        }
+        catch {
+            return [];
+        }
+    };
+    ctx.effect?.(() => ctx.webServer?.register({
+        kind: 'prefix',
+        path: '/dsh-db-tool/api',
+        handler: async (req, res) => {
+            await handleDbToolRequest(req, res, service, {
+                trustedHosts: trustedHosts(),
+                // 项目上下文权威解析：会话 header.cwd 优先，回退前端 cwd（对齐 ssh-tunnel getProjectContext）
+                resolveProject: (sessionId, fallbackCwd) => {
+                    let cwd = '';
+                    try {
+                        cwd = sessionId !== '' ? ctx.sessions?.get?.(sessionId)?.header?.cwd ?? '' : '';
+                    }
+                    catch {
+                        // 会话不可得时用前端回退值
+                    }
+                    const key = service.projectKey(cwd || fallbackCwd || '');
+                    return { projectPathKey: key, hasProject: key !== '' };
+                },
+            });
+        },
+    }) ?? (() => { }), 'db-tool-api');
+    // 收尾：适配器连接与 challenge 清理定时器
+    ctx.effect?.(() => () => service.dispose(), 'db-tool-dispose');
+    // 模型工具
+    ctx.tools?.register({
+        name: 'DatabaseManager',
+        timeoutMs: 90_000,
+        description: TOOL_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list_connections', 'query', 'execute', 'schema', 'preview', 'run_script'],
+                    description: '要执行的操作',
+                },
+                conn_id: { type: 'string', description: '连接 id（query/execute/schema/preview/run_script 必填）' },
+                sql: { type: 'string', description: 'query 的只读 SQL/命令' },
+                statement: { type: 'string', description: 'execute 的语句' },
+                params: { type: 'array', items: {}, description: '占位符参数' },
+                database: { type: 'string', description: '库/schema（可选）' },
+                table: { type: 'string', description: '表/集合/键（schema/preview 用）' },
+                limit: { type: 'number', description: 'preview 行数上限（≤50）' },
+                offset: { type: 'number', description: 'preview 行偏移（翻页用，默认 0）' },
+                code: { type: 'string', description: 'run_script 的脚本源码' },
+                challenge_id: {
+                    type: 'string',
+                    description: '危险操作确认凭据：向用户确认后原样带回重试',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    text: { type: 'string', description: 'JSON 结果文本' },
+                    isError: { type: 'boolean', description: 'true 表示操作被拒或失败' },
+                },
+                required: ['text'],
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        execute: async (args, exec) => {
+            // projectPath 从 session header.cwd 取，不信任模型自报
+            let projectPath = '';
+            try {
+                const sid = exec.agent?.session?.id ?? '';
+                const cwd = sid !== '' ? ctx.sessions?.get(sid)?.header?.cwd : undefined;
+                if (cwd)
+                    projectPath = normalizeProjectKey(cwd);
+            }
+            catch {
+                // 取不到 cwd 视为匿名项目（业务操作会被拒，连接管理仍可用）
+            }
+            return handleToolAction(service, args, projectPath);
+        },
+    });
+    log.info?.('[db-tool] 插件已加载（DatabaseManager 工具 + /dsh-db-tool/api 挂载）');
+}
+// 注意：不要提供 default export。
+// cordis-plugin-loader 的 unwrapExports() 会优先取 exports.default，
+// 裸函数形态会丢失 named export 的 inject 声明，导致
+// "cannot get property "webServer" without inject" 且插件无法激活。