dsh-db-tool 0.1.0

package/dist/adapters/sql-shared/pg-like.js

@@ -0,0 +1,170 @@
+import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell, quoteIdent } from './common.js';
+function poolConfig(conn) {
+    const base = {
+        max: 10,
+        idleTimeoutMillis: 30000,
+        connectionTimeoutMillis: 5000,
+    };
+    if (conn.url) {
+        base.connectionString = conn.url;
+    }
+    else if (conn.fields) {
+        const f = conn.fields;
+        base.host = String(f.host ?? '127.0.0.1');
+        base.port = Number(f.port ?? 5432);
+        base.user = String(f.user ?? f.username ?? 'postgres');
+        if (f.password != null)
+            base.password = String(f.password);
+        if (f.database != null)
+            base.database = String(f.database);
+    }
+    else {
+        throw new Error(`${conn.meta.kind} 连接缺少 url 或 fields 配置`);
+    }
+    if (conn.ssl)
+        base.ssl = { rejectUnauthorized: false };
+    return base;
+}
+export async function createPgLikeAdapter(kind, Driver, conn, opts) {
+    const pool = new Driver.Pool(poolConfig(conn));
+    const readOnly = opts?.mode === 'ro';
+    if (readOnly) {
+        // 服务器级 ro 强制（官方手段）：每个新连接会话设为只读事务。
+        // fail-closed：SET 失败时 release(err) 让驱动销毁该连接、等待的 acquire 收到错误——
+        // 会话级只读是 ro 的最后防线，不允许静默降级成可写连接。
+        pool.on('connect', (c) => {
+            void c.query('SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY').catch((err) => {
+                c.release(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+        // pg 约定：release(err) 若无等待者会 emit pool 'error'，不监听会崩进程
+        pool.on('error', () => { });
+    }
+    // 事务激活期间所有 query/execute 路由到同一 client
+    let txClient = null;
+    const run = (sql, params) => txClient ? txClient.query(sql, params) : pool.query(sql, params);
+    const defaultSchema = () => {
+        const f = conn.fields;
+        return f && typeof f.schema === 'string' && f.schema ? f.schema : 'public';
+    };
+    function toQueryResult(res) {
+        let columns = (res.fields ?? []).map((f) => f.name);
+        if (columns.length === 0 && res.rows.length > 0) {
+            columns = Object.keys(res.rows[0]);
+        }
+        const rows = res.rows.map((r) => columns.map((c) => normalizeCell(r[c])));
+        return { columns, rows, rowCount: rows.length };
+    }
+    const tx = {
+        begin: () => humanize(`${kind} 事务开启`, async () => {
+            if (txClient)
+                throw new Error('事务已开启，请勿重复 begin');
+            txClient = await pool.connect();
+            try {
+                await txClient.query('BEGIN');
+            }
+            catch (e) {
+                txClient.release();
+                txClient = null;
+                throw e;
+            }
+        }),
+        commit: () => humanize(`${kind} 事务提交`, async () => {
+            const c = txClient;
+            if (!c)
+                throw new Error('没有进行中的事务');
+            txClient = null;
+            try {
+                await c.query('COMMIT');
+            }
+            finally {
+                c.release();
+            }
+        }),
+        rollback: () => humanize(`${kind} 事务回滚`, async () => {
+            const c = txClient;
+            if (!c)
+                throw new Error('没有进行中的事务');
+            txClient = null;
+            try {
+                await c.query('ROLLBACK');
+            }
+            finally {
+                c.release();
+            }
+        }),
+    };
+    return {
+        kind,
+        connId: conn.meta.id,
+        tx,
+        testConnect: () => humanize(`${kind} 连接测试`, async () => {
+            const res = await pool.query('SELECT version() AS v');
+            const v = res.rows[0]?.v;
+            return { ok: true, serverInfo: v == null ? kind : String(v) };
+        }),
+        query: (sql, params) => humanize(`${kind} 查询失败`, async () => toQueryResult(await run(sql, params ?? []))),
+        execute: (statement, params) => humanize(`${kind} 执行失败`, async () => {
+            const res = await run(statement, params ?? []);
+            const n = res.rowCount;
+            return {
+                affectedRows: typeof n === 'number' ? n : undefined,
+                message: typeof n === 'number' ? `执行成功，受影响 ${n} 行` : '执行成功',
+            };
+        }),
+        listDatabases: () => humanize(`${kind} 列出数据库`, async () => {
+            const res = await pool.query('SELECT datname FROM pg_database WHERE datistemplate = false AND datallowconn = true ORDER BY datname');
+            return res.rows.map((r) => String(r.datname));
+        }),
+        listTables: (database) => humanize(`${kind} 列出表`, async () => {
+            const schema = database ? assertIdent(database, 'schema') : defaultSchema();
+            const res = await pool.query(`SELECT table_name, table_type FROM information_schema.tables
+           WHERE table_schema = $1 ORDER BY table_name`, [schema]);
+            return res.rows.map((r) => {
+                const rawType = String(r.table_type);
+                return {
+                    name: String(r.table_name),
+                    type: rawType === 'BASE TABLE' ? 'TABLE' : rawType,
+                    database: schema,
+                };
+            });
+        }),
+        describeTable: (table, database) => humanize(`${kind} 查看表结构`, async () => {
+            const schema = database ? assertIdent(database, 'schema') : defaultSchema();
+            const tbl = assertIdent(table, '表名');
+            const res = await pool.query(`SELECT c.column_name, c.data_type, c.is_nullable, c.column_default, c.character_maximum_length,
+                  col_description((quote_ident($1) || '.' || quote_ident($2))::regclass, c.ordinal_position) AS col_comment
+           FROM information_schema.columns c
+           WHERE c.table_schema = $1 AND c.table_name = $2
+           ORDER BY c.ordinal_position`, [schema, tbl]);
+            if (res.rows.length === 0)
+                throw new Error(`表不存在: ${schema}.${tbl}`);
+            const pks = await pool.query(`SELECT kcu.column_name FROM information_schema.table_constraints tc
+           JOIN information_schema.key_column_usage kcu
+             ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+           WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1 AND tc.table_name = $2`, [schema, tbl]);
+            const pkSet = new Set(pks.rows.map((r) => String(r.column_name)));
+            return res.rows.map((r) => {
+                const len = r.character_maximum_length;
+                const base = String(r.data_type);
+                return {
+                    name: String(r.column_name),
+                    dataType: len != null ? `${base}(${String(len)})` : base,
+                    nullable: r.is_nullable === 'YES',
+                    key: pkSet.has(String(r.column_name)) ? 'PRI' : undefined,
+                    default: r.column_default == null ? null : String(r.column_default),
+                    comment: r.col_comment == null ? undefined : String(r.col_comment),
+                };
+            });
+        }),
+        previewRows: (table, limit, database, offset) => humanize(`${kind} 预览行`, async () => {
+            const schema = database ? assertIdent(database, 'schema') : defaultSchema();
+            const tbl = assertIdent(table, '表名');
+            const lim = clampLimit(limit);
+            const off = clampOffset(offset);
+            const res = await run(`SELECT * FROM ${quoteIdent(schema)}.${quoteIdent(tbl)} LIMIT $1 OFFSET $2`, [lim, off]);
+            return toQueryResult(res);
+        }),
+        close: () => humanize(`${kind} 关闭连接`, () => pool.end()),
+    };
+}

package/dist/adapters/sqlite/index.js

@@ -0,0 +1,106 @@
+/**
+ * SQLite 适配器（better-sqlite3，同步 API 包装 Promise）。
+ * fields.database / fields.path 为文件路径；ro 模式 readonly + fileMustExist 打开。
+ */
+import Database from 'better-sqlite3';
+import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell, quoteIdent } from '../sql-shared/common.js';
+function resolveFile(conn) {
+    if (conn.fields) {
+        const f = conn.fields;
+        const path = f.database ?? f.path ?? f.file;
+        if (path != null && String(path) !== '')
+            return String(path);
+    }
+    if (conn.url) {
+        return conn.url.startsWith('file://') ? conn.url.slice('file://'.length) : conn.url;
+    }
+    throw new Error('sqlite 连接缺少文件路径（fields.database / fields.path 或 url）');
+}
+function toQueryResult(raw, columns) {
+    return {
+        columns,
+        rows: raw.map((r) => columns.map((c) => normalizeCell(r[c]))),
+        rowCount: raw.length,
+    };
+}
+export async function createSqliteAdapter(conn, opts) {
+    const file = resolveFile(conn);
+    const readOnly = opts?.mode === 'ro';
+    let db;
+    try {
+        db = readOnly
+            ? new Database(file, { readonly: true, fileMustExist: true })
+            : new Database(file);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`sqlite 打开失败 (${file}): ${msg}`);
+    }
+    return {
+        kind: 'sqlite',
+        connId: conn.meta.id,
+        testConnect: () => humanize('sqlite 连接测试', async () => {
+            const row = db.prepare('SELECT sqlite_version() AS v').get();
+            return { ok: true, serverInfo: `SQLite ${String(row?.v ?? '')}` };
+        }),
+        query: (sql, params) => humanize('sqlite 查询失败', async () => {
+            const stmt = db.prepare(sql);
+            const columns = stmt.columns().map((c) => c.name);
+            const raw = stmt.all(...(params ?? []));
+            return toQueryResult(raw, columns);
+        }),
+        execute: (statement, params) => humanize('sqlite 执行失败', async () => {
+            const stmt = db.prepare(statement);
+            const info = stmt.run(...(params ?? []));
+            const n = Number(info.changes);
+            return {
+                affectedRows: Number.isFinite(n) ? n : undefined,
+                message: `执行成功，受影响 ${n} 行`,
+            };
+        }),
+        listDatabases: () => humanize('sqlite 列出数据库', async () => ['main']),
+        listTables: () => humanize('sqlite 列出表', async () => {
+            const raw = db
+                .prepare(`SELECT name, type FROM sqlite_master
+             WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+                .all();
+            return raw.map((r) => ({
+                name: String(r.name),
+                type: String(r.type).toUpperCase(),
+            }));
+        }),
+        describeTable: (table) => humanize('sqlite 查看表结构', async () => {
+            const tbl = assertIdent(table, '表名');
+            const raw = db
+                .prepare(`PRAGMA table_info(${quoteIdent(tbl)})`)
+                .all();
+            if (raw.length === 0)
+                throw new Error(`表不存在: ${tbl}`);
+            return raw.map((r) => {
+                const dflt = r.dflt_value;
+                const pk = Number(r.pk) > 0;
+                return {
+                    name: String(r.name),
+                    dataType: String(r.type ?? ''),
+                    // 主键按非空展示（SQLite INTEGER PRIMARY KEY 即便 notnull=0 也不可存 NULL）
+                    nullable: Number(r.notnull) === 0 && !pk,
+                    key: pk ? 'PRI' : undefined,
+                    default: dflt == null ? null : String(dflt),
+                };
+            });
+        }),
+        previewRows: (table, limit, _database, offset) => humanize('sqlite 预览行', async () => {
+            const tbl = quoteIdent(assertIdent(table, '表名'));
+            const lim = clampLimit(limit);
+            const off = clampOffset(offset);
+            const stmt = db.prepare(`SELECT * FROM ${tbl} LIMIT ? OFFSET ?`);
+            const columns = stmt.columns().map((c) => c.name);
+            const raw = stmt.all(lim, off);
+            return toQueryResult(raw, columns);
+        }),
+        close: () => humanize('sqlite 关闭连接', async () => {
+            db.close();
+        }),
+    };
+}
+export const factory = (conn) => createSqliteAdapter(conn);

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/guard/index.js

@@ -0,0 +1,221 @@
+/**
+ * 语句风险分级 + 一次性挑战（用户确认）凭据存储。
+ *
+ * classifyStatement：把任意 kind 的一条语句分为 'danger' | 'warning' | 'none'，
+ * 并给出中文原因。Redis/Mongo 危险清单直接复用各适配器导出的官方清单；
+ * SQL 系按首个关键字 + 语句内危险片段识别。
+ */
+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([
+    'select', 'with', 'show', 'describe', 'desc', 'explain', 'use', 'set', 'help', 'table',
+]);
+/** DDL：隐式提交、不可回滚 */
+const SQL_DDL_RE = /^\s*(drop|truncate|alter|create|rename|comment|grant|revoke|flashback|purge)\b/i;
+/** DML：修改数据 */
+const SQL_DML_RE = /^\s*(insert|update|delete|merge|replace|upsert|call|do)\b/i;
+/** 维护类（oracle/dm 等：shutdown/startup/analyze 等） */
+const SQL_MAINT_RE = /^\s*(shutdown|startup|archive\s+log|recover|analyze|optimize|check\s+table|repair|lock|unlock|kill|flush)\b/i;
+/** 读取语句内出现即 danger 的片段（多语句、文件读写、全局设置、跨行锁读） */
+const SQL_HIDDEN_DANGER_RE = /[;]\s*\S|into\s+(outfile|dumpfile)|load_file\s*\(|set\s+(global|persist)|select\s+[\s\S]*\bfor\s+update\b/i;
+/** 读语句体内出现写关键字即 danger（WITH...DELETE / EXPLAIN ANALYZE DELETE 等） */
+const SQL_WRITE_BODY_RE = /\b(insert|update|delete|merge|drop|alter|truncate)\b/i;
+/** MongoDB 读操作白名单（复用 mongodb 适配器导出的 READ_OPS，单一事实来源） */
+const MONGO_READ_OPS = READ_OPS;
+/** MongoDB 写操作清单（适配器未导出，此处按 DANGEROUS_OPS 之外的写命令复述；含命令文档形式 insert/update/delete/create） */
+const MONGO_WRITE_OPS = new Set([
+    'insert', 'insertOne', 'insertMany',
+    'updateOne', 'updateMany', 'update', 'replaceOne', 'findOneAndUpdate', 'findAndModify', 'bulkWrite',
+    'deleteOne', 'deleteMany', 'delete',
+    'createCollection', 'create', 'renameCollection', 'mapReduce',
+]);
+/**
+ * 命令文档形式的删集合：{ drop: 'coll' } 语义等同 dropCollection（删整个集合），
+ * 但适配器导出的 DANGEROUS_OPS 只含 helper 形式（dropCollection），故此处按 danger 补位。
+ */
+const MONGO_DANGEROUS_EXTRA = new Set(['drop']);
+/** 剥掉块注释/行注释（sqlHead 与语句体分析共用；写词藏在注释里不应触发分级） */
+function stripSqlComments(statement) {
+    return statement
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/--[^\n]*/g, ' ')
+        .replace(/#[^\n]*/g, ' ');
+}
+/** 首个 SQL 关键字（剥掉注释与括号） */
+export function sqlHead(statement) {
+    const s = stripSqlComments(statement).trim();
+    const m = /^[\s(]*([a-zA-Z_]+)/.exec(s);
+    return m?.[1]?.toLowerCase() ?? '';
+}
+/** 语句 SHA256（challenge 绑定用；trim 后哈希） */
+export function statementHash(statement) {
+    return createHash('sha256').update(statement.trim(), 'utf8').digest('hex');
+}
+/**
+ * 语句风险分级。op 指明调用通道：query 通道收到任何写语句一律 danger
+ * （只读通道混入写）；execute 通道 SELECT 类放行（如 SELECT ... INTO 之外
+ * 的合法场景由各适配器会话级只读兜底）。
+ */
+export function classifyStatement(kind, statement, op) {
+    if (kind === 'redis')
+        return classifyRedis(statement, op);
+    if (kind === 'mongodb')
+        return classifyMongo(statement, op);
+    return classifySql(statement, op);
+}
+/* ---------------- SQL 系（mysql/postgresql/gaussdb/sqlite/oracle/dmdb） ---------------- */
+function classifySql(statement, op) {
+    const head = sqlHead(statement);
+    if (head === '')
+        return { level: 'danger', reason: '无法解析语句关键字，按危险语句处理' };
+    // 语句体分析一律基于剥注释后的文本：写词藏在注释里不应触发分级（误报），
+    // 前导注释也不能使 DDL/DML 锚定失效（漏报——否则 /* x */ DROP 绕过确认）
+    const body = stripSqlComments(statement);
+    const isRead = SQL_READ_HEADS.has(head);
+    if (isRead) {
+        if (SQL_HIDDEN_DANGER_RE.test(body)) {
+            return { level: 'danger', reason: '读语句包含危险片段（多语句 / 文件读写 / 全局设置 / 锁读），需要确认' };
+        }
+        // 读头不等于只读：WITH...DELETE / EXPLAIN ANALYZE DELETE 语句体内含写关键字
+        if (SQL_WRITE_BODY_RE.test(body)) {
+            return { level: 'danger', reason: '读语句体内包含写操作关键字（如 WITH...DELETE / EXPLAIN 写语句），需要确认' };
+        }
+        return { level: 'none' };
+    }
+    if (SQL_DDL_RE.test(body))
+        return { level: 'danger', reason: 'DDL 不可回滚（隐式提交），可能破坏表结构或数据' };
+    if (SQL_DML_RE.test(body)) {
+        if (op === 'query')
+            return { level: 'danger', reason: '只读通道（query）出现写语句，需要确认' };
+        return { level: 'warning', reason: '写操作将修改数据' };
+    }
+    if (SQL_MAINT_RE.test(body))
+        return { level: 'danger', reason: '维护/管理命令影响服务器状态，需要确认' };
+    // 未知关键字：execute 通道 warning（适配器只读兜底），query 通道 danger
+    if (op === 'query')
+        return { level: 'danger', reason: `只读通道（query）出现非读取语句（${head}），需要确认` };
+    return { level: 'warning', reason: `未识别的语句类型（${head}），请确认后执行` };
+}
+/* ---------------- Redis ---------------- */
+function classifyRedis(statement, op) {
+    const parts = parseRedisCommand(statement);
+    const head = (parts[0] ?? '').toUpperCase();
+    if (head === '')
+        return { level: 'danger', reason: '无法解析 Redis 命令，按危险命令处理' };
+    if (DANGEROUS_COMMANDS.has(head)) {
+        return { level: 'danger', reason: `Redis 危险命令 ${head}，可能清空/重配置实例，需要确认` };
+    }
+    if (WRITE_COMMANDS.has(head)) {
+        if (op === 'query')
+            return { level: 'danger', reason: `只读通道（query）出现 Redis 写命令 ${head}，需要确认` };
+        return { level: 'warning', reason: `Redis 写命令 ${head} 将修改数据` };
+    }
+    if (READ_COMMANDS.has(head))
+        return { level: 'none' };
+    if (op === 'query')
+        return { level: 'danger', reason: `只读通道（query）出现未识别的 Redis 命令（${head}），需要确认` };
+    return { level: 'warning', reason: `未识别的 Redis 命令（${head}），请确认后执行` };
+}
+/* ---------------- MongoDB ---------------- */
+/** MongoDB 命令：JSON 对象，首键为操作名 */
+function classifyMongo(statement, op) {
+    let head = '';
+    try {
+        const parsed = JSON.parse(statement);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            head = Object.keys(parsed)[0] ?? '';
+        }
+    }
+    catch {
+        return { level: 'danger', reason: 'MongoDB 命令不是合法 JSON 对象，按危险命令处理' };
+    }
+    if (head === '')
+        return { level: 'danger', reason: '无法解析 MongoDB 命令，按危险命令处理' };
+    if (DANGEROUS_OPS.has(head)) {
+        return { level: 'danger', reason: `MongoDB 危险操作 ${head}，可能删库/删集合，需要确认` };
+    }
+    if (MONGO_DANGEROUS_EXTRA.has(head)) {
+        return { level: 'danger', reason: `MongoDB 危险操作 ${head}（删除整个集合，等同 dropCollection），需要确认` };
+    }
+    if (MONGO_WRITE_OPS.has(head)) {
+        if (op === 'query')
+            return { level: 'danger', reason: `只读通道（query）出现 MongoDB 写操作 ${head}，需要确认` };
+        return { level: 'warning', reason: `MongoDB 写操作 ${head} 将修改数据` };
+    }
+    if (MONGO_READ_OPS.has(head))
+        return { level: 'none' };
+    if (op === 'query')
+        return { level: 'danger', reason: `只读通道（query）出现未识别的 MongoDB 操作（${head}），需要确认` };
+    // fail-closed：未识别的操作在 execute 通道也不静默放行（与 SQL/Redis 未识别语义对齐）
+    return { level: 'warning', reason: `未识别的 MongoDB 操作（${head}），请确认后执行` };
+}
+/**
+ * 一次性确认凭据：绑定语句 SHA256、5 分钟过期、定期清理。
+ * consume(id, statement)：存在 + 未过期 + hash 一致才通过，且立即失效（一次性）。
+ */
+export class ChallengeStore {
+    ttl;
+    nowFn;
+    map = new Map();
+    timer;
+    disposed = false;
+    constructor(opts) {
+        this.ttl = opts?.ttlMs ?? 5 * 60 * 1000;
+        this.nowFn = opts?.now ?? (() => Date.now());
+        const interval = opts?.sweepIntervalMs ?? 60 * 1000;
+        if (interval > 0) {
+            this.timer = setInterval(() => this.sweep(), interval);
+            this.timer.unref?.();
+        }
+    }
+    /** 生成绑定语句+作用域的一次性 challenge */
+    create(statement, scope) {
+        if (this.disposed)
+            throw new Error('ChallengeStore 已关闭');
+        const now = this.nowFn();
+        const ch = {
+            id: 'c_' + randomBytes(12).toString('hex'),
+            statementHash: statementHash(statement),
+            createdAt: now,
+            expiresAt: now + this.ttl,
+            ...(scope ? { connId: scope.connId, projectKey: scope.projectKey } : {}),
+        };
+        this.map.set(ch.id, ch);
+        return ch;
+    }
+    /** 一次性消费：存在 + 未过期 + hash 与作用域一致才通过，且立即失效；否则 false（不改状态） */
+    consume(id, statement, scope) {
+        const ch = this.map.get(id);
+        if (!ch)
+            return false;
+        this.map.delete(id); // 无论成败都取走，防重放探测
+        if (this.nowFn() > ch.expiresAt)
+            return false;
+        if (ch.statementHash !== statementHash(statement))
+            return false;
+        // 作用域绑定：创建时带 scope 则消费时必须完全一致（防同语句跨连接/跨项目重放）
+        if (ch.connId !== undefined && ch.connId !== scope?.connId)
+            return false;
+        if (ch.projectKey !== undefined && ch.projectKey !== scope?.projectKey)
+            return false;
+        return true;
+    }
+    /** 清理过期项 */
+    sweep() {
+        const now = this.nowFn();
+        for (const [id, ch] of this.map) {
+            if (now > ch.expiresAt)
+                this.map.delete(id);
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.map.clear();
+    }
+}