taurusdb-core 0.1.0

package/dist/safety/parser/features.js

@@ -0,0 +1,113 @@
+import { getFunctionName, isObject, toLimitNode, toWhereNode } from "./ast-utils.js";
+const AGGREGATE_FUNCTIONS = new Set([
+    "COUNT",
+    "SUM",
+    "AVG",
+    "MIN",
+    "MAX",
+    "GROUP_CONCAT",
+    "STRING_AGG",
+    "JSON_AGG",
+    "ARRAY_AGG",
+]);
+export function scanAst(statements) {
+    let hasAggregate = false;
+    let hasSubquery = false;
+    const visit = (node, isTopLevelStatement, parentType, parentKey) => {
+        if (Array.isArray(node)) {
+            for (const entry of node) {
+                visit(entry, false, parentType, parentKey);
+            }
+            return;
+        }
+        if (!isObject(node)) {
+            return;
+        }
+        const nodeType = typeof node.type === "string" ? node.type.toLowerCase() : undefined;
+        if (nodeType === "aggr_func") {
+            hasAggregate = true;
+        }
+        else if (nodeType === "function") {
+            const fn = getFunctionName(node.name);
+            if (fn && AGGREGATE_FUNCTIONS.has(fn.toUpperCase())) {
+                hasAggregate = true;
+            }
+        }
+        if (nodeType === "select" && !isTopLevelStatement) {
+            const isExplainPayload = parentType === "explain" && parentKey === "expr";
+            if (!isExplainPayload) {
+                hasSubquery = true;
+            }
+        }
+        const currentType = typeof node.type === "string" ? node.type.toLowerCase() : undefined;
+        for (const [key, value] of Object.entries(node)) {
+            visit(value, false, currentType, key);
+        }
+    };
+    for (const statement of statements) {
+        visit(statement, true);
+    }
+    return { hasAggregate, hasSubquery };
+}
+export function collectStructuredFeatures(statements) {
+    let where;
+    let limit;
+    const joins = [];
+    const orderBy = [];
+    const groupBy = [];
+    const roots = [];
+    for (const statement of statements) {
+        roots.push(statement);
+        const statementType = typeof statement.type === "string" ? statement.type.toLowerCase() : "";
+        if (statementType === "explain" && isObject(statement.expr)) {
+            roots.push(statement.expr);
+        }
+    }
+    for (const node of roots) {
+        if (!where && node.where !== null && node.where !== undefined) {
+            where = toWhereNode(node.where);
+        }
+        if (!limit && node.limit !== null && node.limit !== undefined) {
+            limit = toLimitNode(node.limit);
+        }
+        if (Array.isArray(node.from)) {
+            for (const fromEntry of node.from) {
+                if (!isObject(fromEntry)) {
+                    continue;
+                }
+                const joinType = typeof fromEntry.join === "string" ? fromEntry.join : undefined;
+                if (!joinType) {
+                    continue;
+                }
+                const tableName = typeof fromEntry.table === "string" ? fromEntry.table : undefined;
+                const schemaName = typeof fromEntry.db === "string" ? fromEntry.db : undefined;
+                joins.push({
+                    type: joinType,
+                    table: tableName ? { name: tableName, schema: schemaName ?? undefined } : undefined,
+                    hasOn: fromEntry.on !== undefined && fromEntry.on !== null,
+                });
+            }
+        }
+        if (Array.isArray(node.orderby)) {
+            for (const orderItem of node.orderby) {
+                let direction;
+                if (isObject(orderItem) && typeof orderItem.type === "string") {
+                    direction = orderItem.type.toUpperCase();
+                }
+                orderBy.push({
+                    direction,
+                    raw: orderItem,
+                });
+            }
+        }
+        if (isObject(node.groupby) && Array.isArray(node.groupby.columns)) {
+            for (const groupItem of node.groupby.columns) {
+                groupBy.push({ raw: groupItem });
+            }
+        }
+        else if (node.groupby !== null && node.groupby !== undefined) {
+            groupBy.push({ raw: node.groupby });
+        }
+    }
+    return { where, limit, joins, orderBy, groupBy };
+}

package/dist/safety/parser/index.d.ts

@@ -0,0 +1,2 @@
+export type { ColumnRef, GroupByNode, JoinNode, LimitNode, NormalizedSql, OrderByNode, ParseError, ParseResult, SqlAst, SqlParser, StatementType, TableRef, WhereNode, } from "./types.js";
+export { NodeSqlParserAdapter, createSqlParser } from "./adapter.js";

package/dist/safety/parser/index.js

@@ -0,0 +1 @@
+export { NodeSqlParserAdapter, createSqlParser } from "./adapter.js";

package/dist/safety/parser/types.d.ts

@@ -0,0 +1,76 @@
+export type AstNode = Record<string, unknown>;
+export type StatementType = "select" | "show" | "explain" | "describe" | "insert" | "update" | "delete" | "alter" | "drop" | "create" | "grant" | "revoke" | "truncate" | "set" | "use" | "unknown";
+export interface TableRef {
+    name: string;
+    schema?: string;
+}
+export interface ColumnRef {
+    name: string;
+    table?: string;
+}
+export interface WhereNode {
+    kind: "binary" | "expression";
+    raw: unknown;
+}
+export interface LimitNode {
+    raw: unknown;
+    rowCount?: number;
+    offset?: number;
+}
+export interface JoinNode {
+    type?: string;
+    table?: TableRef;
+    hasOn?: boolean;
+}
+export interface OrderByNode {
+    direction?: string;
+    raw: unknown;
+}
+export interface GroupByNode {
+    raw: unknown;
+}
+export interface SqlAst {
+    kind: StatementType;
+    tables: TableRef[];
+    columns: ColumnRef[];
+    where?: WhereNode;
+    limit?: LimitNode;
+    joins?: JoinNode[];
+    orderBy?: OrderByNode[];
+    groupBy?: GroupByNode[];
+    hasAggregate: boolean;
+    hasSubquery: boolean;
+    isMultiStatement: boolean;
+}
+export interface NormalizedSql {
+    normalizedSql: string;
+    sqlHash: string;
+}
+export interface ParseError {
+    code: "SQL_PARSE_ERROR";
+    message: string;
+    position?: {
+        line: number;
+        column: number;
+    };
+}
+export type ParseResult = {
+    ok: true;
+    ast: SqlAst;
+    isMultiStatement: boolean;
+} | {
+    ok: false;
+    error: ParseError;
+};
+export interface SqlParser {
+    normalize(sql: string): NormalizedSql;
+    parse(sql: string): ParseResult;
+}
+export type ParserErrorLike = Error & {
+    location?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+    };
+};

package/dist/safety/parser/types.js

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

package/dist/safety/redaction.d.ts

@@ -0,0 +1,34 @@
+export type SensitiveStrategy = "mask" | "drop" | "hash";
+export interface RedactionColumn {
+    name: string;
+    type?: string;
+}
+export interface RawQueryResult {
+    columns: RedactionColumn[];
+    rows: unknown[][];
+    rowCount: number;
+}
+export interface RedactionPolicy {
+    maxRows: number;
+    maxColumns: number;
+    maxFieldChars: number;
+    sensitiveColumns?: Iterable<string>;
+    sensitiveStrategy?: SensitiveStrategy;
+}
+export interface RedactedQueryResult {
+    columns: RedactionColumn[];
+    rows: unknown[][];
+    rowCount: number;
+    originalRowCount: number;
+    truncated: boolean;
+    rowTruncated: boolean;
+    columnTruncated: boolean;
+    fieldTruncated: boolean;
+    redactedColumns: string[];
+    droppedColumns: string[];
+    truncatedColumns: string[];
+}
+export interface ResultRedactor {
+    redact(raw: RawQueryResult, policy: RedactionPolicy): RedactedQueryResult;
+}
+export declare function createResultRedactor(): ResultRedactor;

package/dist/safety/redaction.js

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+const DEFAULT_MAX_ROWS = 200;
+const DEFAULT_MAX_COLUMNS = 50;
+const DEFAULT_MAX_FIELD_CHARS = 2048;
+const DEFAULT_SENSITIVE_STRATEGY = "mask";
+const SENSITIVE_COLUMN_PATTERNS = [
+    /password|passwd|secret/i,
+    /token|api_?key|access_?key|refresh_?token/i,
+    /phone|mobile|tel/i,
+    /email/i,
+    /id_?card|passport|ssn/i,
+    /bank|card_?no|account/i,
+];
+function asPositiveInt(value, fallback) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    return fallback;
+}
+function asNonNegativeInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    return fallback;
+}
+function normalizeColumnName(name) {
+    return name.trim().replace(/^[`'"]+|[`'"]+$/g, "").toLowerCase();
+}
+function columnCandidates(name) {
+    const normalized = normalizeColumnName(name);
+    const dotIndex = normalized.lastIndexOf(".");
+    if (dotIndex < 0) {
+        return [normalized];
+    }
+    return [normalized, normalized.slice(dotIndex + 1)];
+}
+function buildSensitiveSet(input) {
+    const set = new Set();
+    if (!input) {
+        return set;
+    }
+    for (const value of input) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const normalized = normalizeColumnName(value);
+        if (normalized) {
+            set.add(normalized);
+        }
+    }
+    return set;
+}
+function isSensitiveColumn(name, explicitSensitive) {
+    const candidates = columnCandidates(name);
+    if (candidates.some((candidate) => explicitSensitive.has(candidate))) {
+        return true;
+    }
+    const base = candidates[candidates.length - 1];
+    return SENSITIVE_COLUMN_PATTERNS.some((pattern) => pattern.test(base));
+}
+function maskValue(columnName, value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const baseName = columnCandidates(columnName).at(-1) ?? "";
+    const text = typeof value === "string" ? value : String(value);
+    if (/phone|mobile|tel/i.test(baseName)) {
+        return text.replace(/(\d{3})\d+(\d{4})/, "$1****$2");
+    }
+    if (/email/i.test(baseName)) {
+        return text.replace(/(.{2}).*(@.*)/, "$1***$2");
+    }
+    if (/id_?card|passport|ssn/i.test(baseName)) {
+        if (text.length <= 10) {
+            return "***";
+        }
+        return `${text.slice(0, 6)}********${text.slice(-4)}`;
+    }
+    return "***";
+}
+function hashValue(value) {
+    const plain = typeof value === "string"
+        ? value
+        : value === null || value === undefined
+            ? ""
+            : JSON.stringify(value);
+    const digest = createHash("sha256").update(plain).digest("hex").slice(0, 12);
+    return `[HASH:${digest}]`;
+}
+function truncateFieldValue(value, maxFieldChars) {
+    if (typeof value !== "string") {
+        return { value, truncated: false };
+    }
+    if (value.length <= maxFieldChars) {
+        return { value, truncated: false };
+    }
+    return {
+        value: `${value.slice(0, maxFieldChars)}...[TRUNCATED]`,
+        truncated: true,
+    };
+}
+class DefaultResultRedactor {
+    redact(raw, policy) {
+        const maxRows = asPositiveInt(policy.maxRows, DEFAULT_MAX_ROWS);
+        const maxColumns = asPositiveInt(policy.maxColumns, DEFAULT_MAX_COLUMNS);
+        const maxFieldChars = asPositiveInt(policy.maxFieldChars, DEFAULT_MAX_FIELD_CHARS);
+        const sensitiveStrategy = policy.sensitiveStrategy ?? DEFAULT_SENSITIVE_STRATEGY;
+        const explicitSensitive = buildSensitiveSet(policy.sensitiveColumns);
+        const sourceColumns = Array.isArray(raw.columns) ? raw.columns : [];
+        const sourceRows = Array.isArray(raw.rows) ? raw.rows : [];
+        const originalRowCount = asNonNegativeInt(raw.rowCount, sourceRows.length);
+        const rowTruncated = sourceRows.length > maxRows || originalRowCount > maxRows;
+        const columnTruncated = sourceColumns.length > maxColumns;
+        const rowLimited = sourceRows.slice(0, maxRows);
+        const columnLimited = sourceColumns.slice(0, maxColumns);
+        const keepColumnIndexes = [];
+        const keepColumns = [];
+        const keepColumnSensitiveFlags = [];
+        const redactedColumns = new Set();
+        const droppedColumns = [];
+        for (let index = 0; index < columnLimited.length; index += 1) {
+            const column = columnLimited[index];
+            const sensitive = isSensitiveColumn(column.name, explicitSensitive);
+            if (sensitive && sensitiveStrategy === "drop") {
+                droppedColumns.push(column.name);
+                continue;
+            }
+            keepColumnIndexes.push(index);
+            keepColumns.push(column);
+            keepColumnSensitiveFlags.push(sensitive);
+            if (sensitive) {
+                redactedColumns.add(column.name);
+            }
+        }
+        const truncatedColumns = new Set();
+        const outputRows = rowLimited.map((row) => {
+            const sourceRow = Array.isArray(row) ? row : [row];
+            const outputRow = [];
+            for (let outputIndex = 0; outputIndex < keepColumns.length; outputIndex += 1) {
+                const sourceIndex = keepColumnIndexes[outputIndex];
+                const column = keepColumns[outputIndex];
+                const isSensitive = keepColumnSensitiveFlags[outputIndex];
+                const rawValue = sourceRow[sourceIndex];
+                let value;
+                if (isSensitive) {
+                    if (sensitiveStrategy === "hash") {
+                        value = hashValue(rawValue);
+                    }
+                    else {
+                        value = maskValue(column.name, rawValue);
+                    }
+                }
+                else {
+                    const truncated = truncateFieldValue(rawValue, maxFieldChars);
+                    value = truncated.value;
+                    if (truncated.truncated) {
+                        truncatedColumns.add(column.name);
+                    }
+                }
+                outputRow.push(value);
+            }
+            return outputRow;
+        });
+        const fieldTruncated = truncatedColumns.size > 0;
+        return {
+            columns: keepColumns,
+            rows: outputRows,
+            rowCount: originalRowCount,
+            originalRowCount,
+            truncated: rowTruncated || columnTruncated || fieldTruncated,
+            rowTruncated,
+            columnTruncated,
+            fieldTruncated,
+            redactedColumns: keepColumns
+                .map((column) => column.name)
+                .filter((name) => redactedColumns.has(name)),
+            droppedColumns,
+            truncatedColumns: keepColumns
+                .map((column) => column.name)
+                .filter((name) => truncatedColumns.has(name)),
+        };
+    }
+}
+export function createResultRedactor() {
+    return new DefaultResultRedactor();
+}

package/dist/safety/sql-classifier.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseEngine } from "../auth/sql-profile-loader.js";
+import type { NormalizedSql, SqlAst, StatementType } from "./parser/index.js";
+export type GuardrailEngine = DatabaseEngine | "unknown";
+export interface SqlClassification {
+    engine: GuardrailEngine;
+    statementType: StatementType;
+    normalizedSql: string;
+    sqlHash: string;
+    isMultiStatement: boolean;
+    referencedTables: string[];
+    referencedColumns: string[];
+    hasWhere: boolean;
+    hasLimit: boolean;
+    hasJoin: boolean;
+    hasSubquery: boolean;
+    hasOrderBy: boolean;
+    hasAggregate: boolean;
+}
+export declare function classifySql(ast: SqlAst, normalized: NormalizedSql, engine: GuardrailEngine): SqlClassification;

package/dist/safety/sql-classifier.js

@@ -0,0 +1,43 @@
+function dedupeCaseInsensitive(values) {
+    const output = [];
+    const seen = new Set();
+    for (const value of values) {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const key = trimmed.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        output.push(trimmed);
+    }
+    return output;
+}
+function extractTables(ast) {
+    return dedupeCaseInsensitive(ast.tables.map((table) => (table.schema ? `${table.schema}.${table.name}` : table.name)));
+}
+function extractColumns(ast) {
+    return dedupeCaseInsensitive(ast.columns.map((column) => (column.table ? `${column.table}.${column.name}` : column.name)));
+}
+function extractStatementType(ast) {
+    return ast.kind;
+}
+export function classifySql(ast, normalized, engine) {
+    return {
+        engine,
+        statementType: extractStatementType(ast),
+        normalizedSql: normalized.normalizedSql,
+        sqlHash: normalized.sqlHash,
+        isMultiStatement: ast.isMultiStatement,
+        referencedTables: extractTables(ast),
+        referencedColumns: extractColumns(ast),
+        hasWhere: ast.where !== undefined,
+        hasLimit: ast.limit !== undefined,
+        hasJoin: (ast.joins?.length ?? 0) > 0,
+        hasSubquery: ast.hasSubquery,
+        hasOrderBy: (ast.orderBy?.length ?? 0) > 0,
+        hasAggregate: ast.hasAggregate,
+    };
+}

package/dist/safety/sql-validator.d.ts

@@ -0,0 +1,19 @@
+import type { SqlClassification } from "./sql-classifier.js";
+export type RiskLevel = "low" | "medium" | "high" | "blocked";
+export type ValidationAction = "allow" | "confirm" | "block";
+export interface ValidationResult {
+    action: ValidationAction;
+    riskLevel: RiskLevel;
+    reasonCodes: string[];
+    riskHints: string[];
+}
+export interface ExplainRiskSummary {
+    fullTableScanLikely: boolean;
+    indexHitLikely: boolean;
+    estimatedRows: number | null;
+    usesTempStructure: boolean;
+    usesFilesort: boolean;
+    riskHints: string[];
+}
+export declare function validateToolScope(toolName: string, cls: SqlClassification): ValidationResult;
+export declare function validateStaticRules(cls: SqlClassification): ValidationResult;

package/dist/safety/sql-validator.js

@@ -0,0 +1,143 @@
+const READONLY_STATEMENTS = new Set(["select", "show", "explain", "describe"]);
+const MUTATION_STATEMENTS = new Set(["insert", "update", "delete"]);
+const STAR_COLUMN_PATTERN = /(^|\.)(\*|\(\.\*\))$/;
+function allow(riskLevel = "low") {
+    return {
+        action: "allow",
+        riskLevel,
+        reasonCodes: [],
+        riskHints: [],
+    };
+}
+function confirm(riskLevel = "high", reasonCodes, riskHints) {
+    return {
+        action: "confirm",
+        riskLevel,
+        reasonCodes: dedupeCaseInsensitive(reasonCodes),
+        riskHints: dedupeCaseInsensitive(riskHints),
+    };
+}
+function block(reasonCodes, riskHints) {
+    return {
+        action: "block",
+        riskLevel: "blocked",
+        reasonCodes: dedupeCaseInsensitive(reasonCodes),
+        riskHints: dedupeCaseInsensitive(riskHints),
+    };
+}
+function dedupeCaseInsensitive(values) {
+    const output = [];
+    const seen = new Set();
+    for (const raw of values) {
+        const value = raw.trim();
+        if (!value) {
+            continue;
+        }
+        const key = value.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        output.push(value);
+    }
+    return output;
+}
+function containsSelectStar(cls) {
+    if (cls.statementType !== "select") {
+        return false;
+    }
+    return cls.referencedColumns.some((column) => STAR_COLUMN_PATTERN.test(column.trim()));
+}
+export function validateToolScope(toolName, cls) {
+    if (toolName === "execute_readonly_sql") {
+        if (!READONLY_STATEMENTS.has(cls.statementType)) {
+            return block(["T001"], [
+                `Tool execute_readonly_sql only allows SELECT/SHOW/EXPLAIN/DESCRIBE, got ${cls.statementType}.`,
+                "Use execute_sql for controlled mutations.",
+            ]);
+        }
+        return allow("low");
+    }
+    if (toolName === "execute_sql") {
+        if (!MUTATION_STATEMENTS.has(cls.statementType)) {
+            return block(["T002"], [
+                `Tool execute_sql only allows INSERT/UPDATE/DELETE, got ${cls.statementType}.`,
+                "Use execute_readonly_sql for read statements.",
+            ]);
+        }
+        return allow("low");
+    }
+    if (toolName === "explain_sql") {
+        if (cls.statementType === "unknown") {
+            return block(["T003"], ["Tool explain_sql could not classify the statement type. Provide a single supported SQL statement."]);
+        }
+        return allow("low");
+    }
+    return allow("low");
+}
+export function validateStaticRules(cls) {
+    const reasonCodes = [];
+    const riskHints = [];
+    let hasBlock = false;
+    let hasConfirm = false;
+    let hasMedium = false;
+    const escalateToBlock = (code, hint) => {
+        hasBlock = true;
+        reasonCodes.push(code);
+        riskHints.push(hint);
+    };
+    const escalateToConfirm = (code, hint) => {
+        hasConfirm = true;
+        reasonCodes.push(code);
+        riskHints.push(hint);
+    };
+    const escalateToMediumAllow = (code, hint) => {
+        hasMedium = true;
+        reasonCodes.push(code);
+        riskHints.push(hint);
+    };
+    if (cls.isMultiStatement) {
+        escalateToBlock("R001", "Multi-statement SQL is blocked.");
+    }
+    if (cls.statementType === "grant" || cls.statementType === "revoke") {
+        escalateToBlock("R002", "DCL statements (GRANT/REVOKE) are blocked.");
+    }
+    if (cls.statementType === "truncate" ||
+        (cls.statementType === "drop" && /^DROP\s+DATABASE\b/i.test(cls.normalizedSql))) {
+        escalateToBlock("R003", "DROP DATABASE and TRUNCATE are blocked.");
+    }
+    if (cls.statementType === "set" && /^SET\s+GLOBAL\b/i.test(cls.normalizedSql)) {
+        escalateToBlock("R004", "SET GLOBAL is blocked.");
+    }
+    if (cls.statementType === "update" || cls.statementType === "delete") {
+        if (!cls.hasWhere) {
+            escalateToBlock("R005", "UPDATE/DELETE without WHERE is blocked.");
+        }
+        else {
+            escalateToConfirm("R006", "Mutation SQL with WHERE requires confirmation.");
+        }
+    }
+    if (cls.statementType === "select") {
+        if (!cls.hasLimit && !cls.hasAggregate) {
+            escalateToMediumAllow("R007", "Detail SELECT without LIMIT has medium risk.");
+        }
+        if (containsSelectStar(cls)) {
+            escalateToMediumAllow("R008", "SELECT * may return excessive columns.");
+        }
+    }
+    if (hasBlock) {
+        return block(reasonCodes, riskHints);
+    }
+    if (hasConfirm) {
+        return confirm("high", reasonCodes, riskHints);
+    }
+    if (hasMedium) {
+        return {
+            action: "allow",
+            riskLevel: "medium",
+            reasonCodes: dedupeCaseInsensitive(reasonCodes),
+            riskHints: dedupeCaseInsensitive(riskHints),
+        };
+    }
+    return allow("low");
+}

package/dist/schema/adapters/mysql.d.ts

@@ -0,0 +1,16 @@
+import type { ConnectionPool } from "../../executor/connection-pool.js";
+import type { SessionContext } from "../../context/session-context.js";
+import type { DatabaseInfo, SchemaAdapter, TableInfo, TableSchema } from "../introspector.js";
+export type MySqlSchemaAdapterOptions = {
+    connectionPool: ConnectionPool;
+};
+export declare class MySqlSchemaAdapter implements SchemaAdapter {
+    private readonly connectionPool;
+    constructor(options: MySqlSchemaAdapterOptions);
+    listDatabases(ctx: SessionContext): Promise<DatabaseInfo[]>;
+    listTables(ctx: SessionContext, database: string): Promise<TableInfo[]>;
+    describeTable(ctx: SessionContext, database: string, table: string): Promise<TableSchema>;
+    private mapIndexes;
+    private queryObjects;
+}
+export declare function createMySqlSchemaAdapter(options: MySqlSchemaAdapterOptions): SchemaAdapter;