@negusdev/dbask 0.0.0-stage → 0.1.8

package/dist/safety/sql-tokenizer.js

@@ -0,0 +1,240 @@
+/**
+ * Minimal SQL tokenizer used by the safety validator. It understands the
+ * lexical rules of MySQL/MariaDB and PostgreSQL.
+ *
+ * It is not a full SQL parser. Its only job is to separate the parts of a
+ * statement that carry meaning (keywords, identifiers, punctuation) from the
+ * parts that do not (string literals, quoted identifiers, comments), so safety
+ * rules are applied to real SQL tokens instead of raw text. Getting the lexical
+ * rules of the *target* database exactly right matters: if this tokenizer and
+ * the server disagree about where a string or comment ends, a second statement
+ * can hide inside what the validator thinks is a literal.
+ *
+ * MySQL/MariaDB (defaults assumed):
+ * - `-- ` and `#` line comments, non-nested block comments
+ * - backslash escapes inside '...' and "..." strings (no NO_BACKSLASH_ESCAPES)
+ * - double quotes delimit strings, not identifiers (no ANSI_QUOTES)
+ * - executable comments (`/*! ... *\/`, `/*M! ... *\/`) are rejected outright
+ *   because the server executes their contents
+ *
+ * PostgreSQL:
+ * - `--` line comments (no whitespace needed); `#` is an operator, not a comment
+ * - nested block comments
+ * - '...' strings only escape quotes by doubling; backslash escapes apply only
+ *   to E'...' strings (the adapter pins standard_conforming_strings = on)
+ * - "..." delimits identifiers
+ * - dollar-quoted strings ($$...$$ and $tag$...$tag$)
+ * - U&'...' and U&"..." are rejected: their escapes can spell any name
+ */
+const WORD_CHAR = /[A-Za-z0-9_$\u0080-￿]/;
+const DOLLAR_TAG = /\$(?:[A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$/y;
+/**
+ * Tokenizes SQL using the lexical rules of `dialect`. Dialects other than
+ * PostgreSQL use the MySQL rules (no other adapter exists yet).
+ */
+export function tokenizeSql(sql, dialect = 'mysql') {
+    const pg = dialect === 'postgres';
+    const tokens = [];
+    const n = sql.length;
+    let i = 0;
+    while (i < n) {
+        const c = sql[i];
+        const next = sql[i + 1];
+        // Whitespace.
+        if (/\s/.test(c)) {
+            i += 1;
+            continue;
+        }
+        // `--` line comment. PostgreSQL always treats `--` as a comment. MySQL
+        // requires whitespace or a control character after the two dashes; `--x`
+        // is two minus signs there, not a comment.
+        if (c === '-' && next === '-') {
+            const after = sql[i + 2];
+            if (pg || after === undefined || /[\s\u0000-\u001f]/.test(after)) {
+                const eol = sql.indexOf('\n', i + 2);
+                i = eol === -1 ? n : eol + 1;
+                continue;
+            }
+        }
+        // `#` line comment (MySQL only; in PostgreSQL `#` starts operators like #>).
+        if (c === '#' && !pg) {
+            const eol = sql.indexOf('\n', i + 1);
+            i = eol === -1 ? n : eol + 1;
+            continue;
+        }
+        // Block comment.
+        if (c === '/' && next === '*') {
+            if (!pg && (sql[i + 2] === '!' || (sql[i + 2] === 'M' && sql[i + 3] === '!'))) {
+                return {
+                    tokens,
+                    error: 'Executable comments (/*! ... */) are not allowed.',
+                };
+            }
+            if (pg) {
+                // PostgreSQL block comments nest.
+                let depth = 1;
+                let j = i + 2;
+                while (j < n && depth > 0) {
+                    if (sql[j] === '/' && sql[j + 1] === '*') {
+                        depth += 1;
+                        j += 2;
+                    }
+                    else if (sql[j] === '*' && sql[j + 1] === '/') {
+                        depth -= 1;
+                        j += 2;
+                    }
+                    else {
+                        j += 1;
+                    }
+                }
+                if (depth > 0) {
+                    return { tokens, error: 'The query contains an unterminated comment.' };
+                }
+                i = j;
+                continue;
+            }
+            const close = sql.indexOf('*/', i + 2);
+            if (close === -1) {
+                return { tokens, error: 'The query contains an unterminated comment.' };
+            }
+            i = close + 2;
+            continue;
+        }
+        // PostgreSQL dollar-quoted strings: $$...$$ or $tag$...$tag$.
+        // `$1` is a parameter placeholder and falls through to the word rule.
+        if (pg && c === '$') {
+            DOLLAR_TAG.lastIndex = i;
+            const match = DOLLAR_TAG.exec(sql);
+            if (match) {
+                const tag = match[0];
+                const close = sql.indexOf(tag, i + tag.length);
+                if (close === -1) {
+                    return { tokens, error: 'The query contains an unterminated dollar-quoted string.' };
+                }
+                const end = close + tag.length;
+                tokens.push({ type: 'string', value: sql.slice(i, end), start: i, end });
+                i = end;
+                continue;
+            }
+        }
+        // Quoted strings ('...', and "..." in MySQL) and, in PostgreSQL,
+        // double-quoted identifiers.
+        if (c === "'" || c === '"') {
+            const start = i;
+            if (pg) {
+                const previous = tokens[tokens.length - 1];
+                const beforePrevious = tokens[tokens.length - 2];
+                // U&'...' / U&"..." (Unicode escapes can spell any identifier).
+                if (previous?.type === 'punct' &&
+                    previous.value === '&' &&
+                    previous.end === i &&
+                    beforePrevious?.type === 'word' &&
+                    beforePrevious.value === 'U' &&
+                    beforePrevious.end === previous.start) {
+                    return {
+                        tokens,
+                        error: 'Unicode escape strings and identifiers (U&"...") are not allowed.',
+                    };
+                }
+            }
+            // E'...' strings treat backslash as an escape character.
+            let backslashEscapes = !pg;
+            let tokenStart = start;
+            if (pg && c === "'") {
+                const previous = tokens[tokens.length - 1];
+                if (previous?.type === 'word' && previous.value === 'E' && previous.end === i) {
+                    backslashEscapes = true;
+                    tokenStart = previous.start;
+                    tokens.pop();
+                }
+            }
+            let j = i + 1;
+            let closed = false;
+            while (j < n) {
+                const d = sql[j];
+                if (backslashEscapes && d === '\\') {
+                    j += 2;
+                    continue;
+                }
+                if (d === c) {
+                    if (sql[j + 1] === c) {
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    j += 1;
+                    break;
+                }
+                j += 1;
+            }
+            if (!closed) {
+                return {
+                    tokens,
+                    error: pg && c === '"'
+                        ? 'The query contains an unterminated quoted identifier.'
+                        : 'The query contains an unterminated string.',
+                };
+            }
+            tokens.push({
+                type: pg && c === '"' ? 'quoted-identifier' : 'string',
+                value: sql.slice(tokenStart, j),
+                start: tokenStart,
+                end: j,
+            });
+            i = j;
+            continue;
+        }
+        // Backtick-quoted identifiers (MySQL only).
+        if (c === '`' && !pg) {
+            const start = i;
+            let j = i + 1;
+            let closed = false;
+            while (j < n) {
+                if (sql[j] === '`') {
+                    if (sql[j + 1] === '`') {
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    j += 1;
+                    break;
+                }
+                j += 1;
+            }
+            if (!closed) {
+                return {
+                    tokens,
+                    error: 'The query contains an unterminated quoted identifier.',
+                };
+            }
+            tokens.push({
+                type: 'quoted-identifier',
+                value: sql.slice(start, j),
+                start,
+                end: j,
+            });
+            i = j;
+            continue;
+        }
+        // Words: keywords, identifiers, and numbers.
+        if (WORD_CHAR.test(c)) {
+            const start = i;
+            let j = i + 1;
+            while (j < n && WORD_CHAR.test(sql[j]))
+                j += 1;
+            tokens.push({
+                type: 'word',
+                value: sql.slice(start, j).toUpperCase(),
+                start,
+                end: j,
+            });
+            i = j;
+            continue;
+        }
+        // Everything else is single-character punctuation.
+        tokens.push({ type: 'punct', value: c, start: i, end: i + 1 });
+        i += 1;
+    }
+    return { tokens };
+}
+//# sourceMappingURL=sql-tokenizer.js.map

package/dist/safety/sql-tokenizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-tokenizer.js","sourceRoot":"","sources":["../../src/safety/sql-tokenizer.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,34 @@
+import type { SqlDialect, SqlSafetyPolicy } from '../core/types/index.js';
+export interface SqlValidationResult {
+    valid: boolean;
+    sql?: string;
+    reason?: string;
+}
+/**
+ * First-stage SQL safety boundary.
+ *
+ * The SQL is tokenized with the target dialect's lexical rules so string
+ * literals, quoted identifiers, and comments are never mistaken for SQL, then
+ * these rules are applied:
+ *
+ * - exactly one statement (a single trailing semicolon is accepted)
+ * - the statement must start with a read-oriented keyword
+ * - executable comments (MySQL) and Unicode-escaped names (PostgreSQL) are
+ *   rejected
+ * - when `policy.readOnly` is set: write/DDL/locking keywords, `INTO`, and
+ *   locking reads (`FOR SHARE` / `FOR UPDATE`, ...) are rejected
+ * - functions that read files, block the connection, take locks, or run
+ *   dynamic SQL are rejected wherever they appear, including schema-qualified
+ *   (`pg_catalog.pg_sleep(...)`) and quoted (`"pg_sleep"(...)`) forms
+ *
+ * This is not a complete SQL parser. MySQL rules assume the default sql_mode
+ * (backslash escapes on, ANSI_QUOTES off); PostgreSQL rules assume
+ * standard_conforming_strings = on, which the PostgreSQL adapter enforces.
+ * User-defined functions cannot be recognized as side-effecting. The database
+ * account must still be read-only; the PostgreSQL adapter additionally runs
+ * every statement in a READ ONLY transaction.
+ *
+ * @param dialect SQL dialect of the target database. Defaults to MySQL.
+ */
+export declare function validateSql(sql: string, policy: SqlSafetyPolicy, dialect?: SqlDialect): SqlValidationResult;
+//# sourceMappingURL=sql-validator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sql-validator.d.ts","sourceRoot":"","sources":["../../src/safety/sql-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4J1E,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,UAAoB,GAC5B,mBAAmB,CAgHrB"}

package/dist/safety/sql-validator.js

@@ -0,0 +1,270 @@
+import { tokenizeSql } from './sql-tokenizer.js';
+const MYSQL_RULES = {
+    allowedFirstKeywords: new Set(['SELECT', 'WITH', 'EXPLAIN', 'SHOW', 'DESCRIBE', 'DESC']),
+    blockedKeywords: new Set([
+        'INSERT',
+        'UPDATE',
+        'DELETE',
+        'DROP',
+        'ALTER',
+        'TRUNCATE',
+        'CREATE',
+        'REPLACE',
+        'MERGE',
+        'GRANT',
+        'REVOKE',
+        'CALL',
+        'SET',
+        'USE',
+        'LOAD',
+        'HANDLER',
+        'LOCK',
+        'UNLOCK',
+        'PREPARE',
+        'EXECUTE',
+        'DEALLOCATE',
+        'RENAME',
+        'KILL',
+        'FLUSH',
+        // Writes query output to the server filesystem or into variables.
+        'INTO',
+    ]),
+    // INSERT(), REPLACE() and TRUNCATE() are also ordinary string/math functions.
+    functionLikeKeywords: new Set(['INSERT', 'REPLACE', 'TRUNCATE']),
+    // Functions that read server files, block, take locks, or are commonly used
+    // to tie up a connection.
+    blockedFunctions: new Set([
+        'LOAD_FILE',
+        'SLEEP',
+        'BENCHMARK',
+        'GET_LOCK',
+        'RELEASE_LOCK',
+        'RELEASE_ALL_LOCKS',
+        'IS_FREE_LOCK',
+        'IS_USED_LOCK',
+        'MASTER_POS_WAIT',
+        'SOURCE_POS_WAIT',
+        'WAIT_FOR_EXECUTED_GTID_SET',
+        'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS',
+    ]),
+    blockedFunctionPrefixes: [],
+    lockingWords: new Set(['SHARE', 'UPDATE']),
+};
+/**
+ * PostgreSQL. Only words that can occur *inside* a single SELECT/WITH/EXPLAIN/
+ * SHOW statement matter here: the statement-starting rule already rejects
+ * everything else (COPY, DO, VACUUM, LOCK, ...). Words that are common column
+ * names (LOAD, LOCK, USE, KILL, ...) are deliberately not blocked.
+ */
+const POSTGRES_RULES = {
+    allowedFirstKeywords: new Set(['SELECT', 'WITH', 'EXPLAIN', 'SHOW']),
+    blockedKeywords: new Set([
+        // Data-modifying CTEs and statements nested in EXPLAIN.
+        'INSERT',
+        'UPDATE',
+        'DELETE',
+        'MERGE',
+        'CREATE',
+        'DROP',
+        'ALTER',
+        'TRUNCATE',
+        'GRANT',
+        'REVOKE',
+        'CALL',
+        'SET',
+        'COPY',
+        'DO',
+        'PREPARE',
+        'EXECUTE',
+        'DEALLOCATE',
+        // SELECT ... INTO creates a table.
+        'INTO',
+    ]),
+    functionLikeKeywords: new Set(),
+    blockedFunctions: new Set([
+        // Block the connection or change the session's safety settings.
+        'PG_SLEEP',
+        'PG_SLEEP_FOR',
+        'PG_SLEEP_UNTIL',
+        'SET_CONFIG',
+        // Sequences are state.
+        'NEXTVAL',
+        'SETVAL',
+        // Notifications and backend control.
+        'PG_NOTIFY',
+        'PG_TERMINATE_BACKEND',
+        'PG_CANCEL_BACKEND',
+        'PG_RELOAD_CONF',
+        'PG_ROTATE_LOGFILE',
+        'PG_SWITCH_WAL',
+        'PG_PROMOTE',
+        'PG_IMPORT_SYSTEM_COLLATIONS',
+        // Read server files.
+        'PG_STAT_FILE',
+        // Server-side dynamic SQL: runs query text that the validator never sees.
+        'QUERY_TO_XML',
+        'QUERY_TO_XML_AND_XMLSCHEMA',
+        'QUERY_TO_XMLSCHEMA',
+        'CURSOR_TO_XML',
+        'CURSOR_TO_XMLSCHEMA',
+    ]),
+    blockedFunctionPrefixes: [
+        'PG_LS_', // pg_ls_dir, pg_ls_logdir, ...
+        'PG_READ_', // pg_read_file, pg_read_binary_file
+        'PG_FILE_',
+        'PG_ADVISORY_', // pg_advisory_lock*, pg_advisory_unlock*, pg_advisory_xact_lock*
+        'PG_TRY_ADVISORY_',
+        'PG_CREATE_', // replication slots, restore points
+        'PG_DROP_',
+        'PG_REPLICATION_',
+        'PG_LOGICAL_',
+        'PG_COPY_',
+        'PG_BACKUP_',
+        'PG_WAL_REPLAY_',
+        'LO_', // large objects: lo_import / lo_export touch the server filesystem
+        'DBLINK', // other databases, arbitrary remote SQL
+    ],
+    lockingWords: new Set(['SHARE', 'UPDATE', 'NO', 'KEY']),
+};
+function rulesFor(dialect) {
+    // Dialects without an adapter yet fall back to the MySQL rules.
+    return dialect === 'postgres' ? POSTGRES_RULES : MYSQL_RULES;
+}
+function isPunct(token, value) {
+    return token?.type === 'punct' && token.value === value;
+}
+/**
+ * Upper-cased function name when `token` is a (possibly quoted) identifier,
+ * otherwise undefined. Quoted identifiers are unquoted first so that
+ * "pg_sleep"(10) cannot hide a blocked function.
+ */
+function identifierName(token) {
+    if (token.type === 'word')
+        return token.value;
+    if (token.type === 'quoted-identifier') {
+        const quote = token.value[0];
+        const inner = token.value.slice(1, -1).split(quote + quote).join(quote);
+        return inner.toUpperCase();
+    }
+    return undefined;
+}
+function isBlockedFunction(name, rules) {
+    return (rules.blockedFunctions.has(name) ||
+        rules.blockedFunctionPrefixes.some((prefix) => name.startsWith(prefix)));
+}
+/**
+ * First-stage SQL safety boundary.
+ *
+ * The SQL is tokenized with the target dialect's lexical rules so string
+ * literals, quoted identifiers, and comments are never mistaken for SQL, then
+ * these rules are applied:
+ *
+ * - exactly one statement (a single trailing semicolon is accepted)
+ * - the statement must start with a read-oriented keyword
+ * - executable comments (MySQL) and Unicode-escaped names (PostgreSQL) are
+ *   rejected
+ * - when `policy.readOnly` is set: write/DDL/locking keywords, `INTO`, and
+ *   locking reads (`FOR SHARE` / `FOR UPDATE`, ...) are rejected
+ * - functions that read files, block the connection, take locks, or run
+ *   dynamic SQL are rejected wherever they appear, including schema-qualified
+ *   (`pg_catalog.pg_sleep(...)`) and quoted (`"pg_sleep"(...)`) forms
+ *
+ * This is not a complete SQL parser. MySQL rules assume the default sql_mode
+ * (backslash escapes on, ANSI_QUOTES off); PostgreSQL rules assume
+ * standard_conforming_strings = on, which the PostgreSQL adapter enforces.
+ * User-defined functions cannot be recognized as side-effecting. The database
+ * account must still be read-only; the PostgreSQL adapter additionally runs
+ * every statement in a READ ONLY transaction.
+ *
+ * @param dialect SQL dialect of the target database. Defaults to MySQL.
+ */
+export function validateSql(sql, policy, dialect = 'mysql') {
+    const rules = rulesFor(dialect);
+    const normalized = sql.trim();
+    if (!normalized) {
+        return { valid: false, reason: 'SQL query is empty.' };
+    }
+    const { tokens: allTokens, error } = tokenizeSql(normalized, dialect);
+    if (error) {
+        return { valid: false, reason: error };
+    }
+    // Split on the first semicolon outside strings, quoted identifiers, and
+    // comments. Anything after it, other than comments, is a second statement.
+    let tokens = allTokens;
+    let output = normalized;
+    const semicolon = allTokens.findIndex((token) => isPunct(token, ';'));
+    if (semicolon !== -1) {
+        if (semicolon < allTokens.length - 1) {
+            return { valid: false, reason: 'Multiple SQL statements are not allowed.' };
+        }
+        tokens = allTokens.slice(0, semicolon);
+        output = normalized.slice(0, allTokens[semicolon].start).trimEnd();
+    }
+    if (tokens.length === 0) {
+        return { valid: false, reason: 'SQL query is empty.' };
+    }
+    // Allow leading parentheses, e.g. (SELECT ...) UNION (SELECT ...).
+    let first = 0;
+    while (isPunct(tokens[first], '('))
+        first += 1;
+    const head = tokens[first];
+    if (!head ||
+        head.type !== 'word' ||
+        !rules.allowedFirstKeywords.has(head.value)) {
+        return { valid: false, reason: 'Only read-oriented SQL statements are allowed.' };
+    }
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        const following = tokens[index + 1];
+        const isCall = isPunct(following, '(');
+        // Blocked functions are matched wherever they appear: a name after a dot
+        // (pg_catalog.pg_sleep) or in quotes ("pg_sleep") is still that function.
+        if (isCall) {
+            const name = identifierName(token);
+            if (name !== undefined && isBlockedFunction(name, rules)) {
+                return {
+                    valid: false,
+                    reason: `The function ${name.toLowerCase()}() is not allowed.`,
+                };
+            }
+        }
+        if (token.type !== 'word')
+            continue;
+        // A word after a dot is part of a qualified name (t.update), not a keyword.
+        if (isPunct(tokens[index - 1], '.'))
+            continue;
+        if (!policy.readOnly)
+            continue;
+        if (rules.blockedKeywords.has(token.value)) {
+            if (rules.functionLikeKeywords.has(token.value) && isCall)
+                continue;
+            // CHARACTER SET utf8 (in CAST/CONVERT, SHOW CHARACTER SET).
+            if (dialect !== 'postgres' &&
+                token.value === 'SET' &&
+                tokens[index - 1]?.value === 'CHARACTER') {
+                continue;
+            }
+            // Index hints: USE INDEX (...) / USE KEY (...).
+            if (dialect !== 'postgres' &&
+                token.value === 'USE' &&
+                following?.type === 'word' &&
+                (following.value === 'INDEX' || following.value === 'KEY')) {
+                continue;
+            }
+            return {
+                valid: false,
+                reason: `The query contains a blocked SQL operation (${token.value}).`,
+            };
+        }
+        if (token.value === 'FOR' &&
+            following?.type === 'word' &&
+            rules.lockingWords.has(following.value)) {
+            return {
+                valid: false,
+                reason: 'Locking reads (FOR SHARE / FOR UPDATE) are not allowed.',
+            };
+        }
+    }
+    return { valid: true, sql: output };
+}
+//# sourceMappingURL=sql-validator.js.map

package/dist/safety/sql-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-validator.js","sourceRoot":"","sources":["../../src/safety/sql-validator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAiB,MAAM,oBAAoB,CAAC;AAqBhE,MAAM,WAAW,GAAiB;IAChC,oBAAoB,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACxF,eAAe,EAAE,IAAI,GAAG,CAAC;QACvB,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,MAAM;QACN,OAAO;QACP,UAAU;QACV,QAAQ;QACR,SAAS;QACT,OAAO;QACP,OAAO;QACP,QAAQ;QACR,MAAM;QACN,KAAK;QACL,KAAK;QACL,MAAM;QACN,SAAS;QACT,MAAM;QACN,QAAQ;QACR,SAAS;QACT,SAAS;QACT,YAAY;QACZ,QAAQ;QACR,MAAM;QACN,OAAO;QACP,kEAAkE;QAClE,MAAM;KACP,CAAC;IACF,8EAA8E;IAC9E,oBAAoB,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAChE,4EAA4E;IAC5E,0BAA0B;IAC1B,gBAAgB,EAAE,IAAI,GAAG,CAAC;QACxB,WAAW;QACX,OAAO;QACP,WAAW;QACX,UAAU;QACV,cAAc;QACd,mBAAmB;QACnB,cAAc;QACd,cAAc;QACd,iBAAiB;QACjB,iBAAiB;QACjB,4BAA4B;QAC5B,mCAAmC;KACpC,CAAC;IACF,uBAAuB,EAAE,EAAE;IAC3B,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,cAAc,GAAiB;IACnC,oBAAoB,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACpE,eAAe,EAAE,IAAI,GAAG,CAAC;QACvB,wDAAwD;QACxD,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,MAAM;QACN,OAAO;QACP,UAAU;QACV,OAAO;QACP,QAAQ;QACR,MAAM;QACN,KAAK;QACL,MAAM;QACN,IAAI;QACJ,SAAS;QACT,SAAS;QACT,YAAY;QACZ,mCAAmC;QACnC,MAAM;KACP,CAAC;IACF,oBAAoB,EAAE,IAAI,GAAG,EAAE;IAC/B,gBAAgB,EAAE,IAAI,GAAG,CAAC;QACxB,gEAAgE;QAChE,UAAU;QACV,cAAc;QACd,gBAAgB;QAChB,YAAY;QACZ,uBAAuB;QACvB,SAAS;QACT,QAAQ;QACR,qCAAqC;QACrC,WAAW;QACX,sBAAsB;QACtB,mBAAmB;QACnB,gBAAgB;QAChB,mBAAmB;QACnB,eAAe;QACf,YAAY;QACZ,6BAA6B;QAC7B,qBAAqB;QACrB,cAAc;QACd,0EAA0E;QAC1E,cAAc;QACd,4BAA4B;QAC5B,oBAAoB;QACpB,eAAe;QACf,qBAAqB;KACtB,CAAC;IACF,uBAAuB,EAAE;QACvB,QAAQ,EAAE,+BAA+B;QACzC,UAAU,EAAE,oCAAoC;QAChD,UAAU;QACV,cAAc,EAAE,iEAAiE;QACjF,kBAAkB;QAClB,YAAY,EAAE,oCAAoC;QAClD,UAAU;QACV,iBAAiB;QACjB,aAAa;QACb,UAAU;QACV,YAAY;QACZ,gBAAgB;QAChB,KAAK,EAAE,mEAAmE;QAC1E,QAAQ,EAAE,wCAAwC;KACnD;IACD,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;CACxD,CAAC;AAEF,SAAS,QAAQ,CAAC,OAAmB;IACnC,gEAAgE;IAChE,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/D,CAAC;AAQD,SAAS,OAAO,CAAC,KAA2B,EAAE,KAAa;IACzD,OAAO,KAAK,EAAE,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAe;IACrC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAmB;IAC1D,OAAO,CACL,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAChC,KAAK,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,MAAuB,EACvB,OAAO,GAAe,OAAO;IAE7B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAE9B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAEtE,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,wEAAwE;IACxE,2EAA2E;IAC3E,IAAI,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,MAAM,GAAG,UAAU,CAAC;IACxB,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAEtE,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,IAAI,SAAS,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;QAC9E,CAAC;QAED,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACvC,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAG,SAAS,CAAC,SAAS,CAAc,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IACnF,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IACzD,CAAC;IAED,mEAAmE;IACnE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IAE/C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,IACE,CAAC,IAAI;QACL,IAAI,CAAC,IAAI,KAAK,MAAM;QACpB,CAAC,KAAK,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAC3C,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gDAAgD,EAAE,CAAC;IACpF,CAAC;IAED,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAa,CAAC;QACxC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAEvC,yEAAyE;QACzE,0EAA0E;QAC1E,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YAEnC,IAAI,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;gBACzD,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,gBAAgB,IAAI,CAAC,WAAW,EAAE,oBAAoB;iBAC/D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAEpC,4EAA4E;QAC5E,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;YAAE,SAAS;QAE9C,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,SAAS;QAE/B,IAAI,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM;gBAAE,SAAS;YAEpE,4DAA4D;YAC5D,IACE,OAAO,KAAK,UAAU;gBACtB,KAAK,CAAC,KAAK,KAAK,KAAK;gBACrB,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,KAAK,KAAK,WAAW,EACxC,CAAC;gBACD,SAAS;YACX,CAAC;YAED,gDAAgD;YAChD,IACE,OAAO,KAAK,UAAU;gBACtB,KAAK,CAAC,KAAK,KAAK,KAAK;gBACrB,SAAS,EAAE,IAAI,KAAK,MAAM;gBAC1B,CAAC,SAAS,CAAC,KAAK,KAAK,OAAO,IAAI,SAAS,CAAC,KAAK,KAAK,KAAK,CAAC,EAC1D,CAAC;gBACD,SAAS;YACX,CAAC;YAED,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,+CAA+C,KAAK,CAAC,KAAK,IAAI;aACvE,CAAC;QACJ,CAAC;QAED,IACE,KAAK,CAAC,KAAK,KAAK,KAAK;YACrB,SAAS,EAAE,IAAI,KAAK,MAAM;YAC1B,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,EACvC,CAAC;YACD,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,yDAAyD;aAClE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC"}

package/dist/schema/cache.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseAdapter, TableInfo, TableSchema, RelationshipInfo } from '../core/types/index.js';
+export interface SchemaCacheOptions {
+    ttlMs?: number;
+}
+/**
+ * Process-local cache for database metadata. It never caches query results.
+ * A short TTL keeps repeated agent schema discovery from repeatedly hitting
+ * information_schema while allowing schema changes to become visible.
+ */
+export declare class SchemaCache {
+    private readonly ttlMs;
+    private tables?;
+    private relationships?;
+    private readonly tableSchemas;
+    constructor(options?: SchemaCacheOptions);
+    listTables(database: DatabaseAdapter): Promise<TableInfo[]>;
+    describeTable(database: DatabaseAdapter, table: string): Promise<TableSchema>;
+    describeTables(database: DatabaseAdapter, tables: string[]): Promise<TableSchema[]>;
+    getRelationships(database: DatabaseAdapter): Promise<RelationshipInfo[]>;
+    clear(): void;
+    private entry;
+    private get;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/schema/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/schema/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAExG,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAC,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8C;IAE3E,YAAY,OAAO,GAAE,kBAAuB,EAE3C;IAEK,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAOhE;IAEK,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CASlF;IAEK,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAExF;IAEK,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAO7E;IAED,KAAK,IAAI,IAAI,CAIZ;IAED,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,GAAG;CAIZ"}

package/dist/schema/cache.js

@@ -0,0 +1,57 @@
+/**
+ * Process-local cache for database metadata. It never caches query results.
+ * A short TTL keeps repeated agent schema discovery from repeatedly hitting
+ * information_schema while allowing schema changes to become visible.
+ */
+export class SchemaCache {
+    ttlMs;
+    tables;
+    relationships;
+    tableSchemas = new Map();
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 300_000;
+    }
+    async listTables(database) {
+        const cached = this.get(this.tables);
+        if (cached)
+            return cached;
+        const value = await database.listTables();
+        this.tables = this.entry(value);
+        return value;
+    }
+    async describeTable(database, table) {
+        // PostgreSQL names are case-sensitive when quoted; MySQL table names are not portable anyway.
+        const key = database.dialect === 'postgres' ? table : table.toLowerCase();
+        const cached = this.get(this.tableSchemas.get(key));
+        if (cached)
+            return cached;
+        const value = await database.describeTable(table);
+        this.tableSchemas.set(key, this.entry(value));
+        return value;
+    }
+    async describeTables(database, tables) {
+        return Promise.all(tables.map((table) => this.describeTable(database, table)));
+    }
+    async getRelationships(database) {
+        const cached = this.get(this.relationships);
+        if (cached)
+            return cached;
+        const value = await database.getRelationships();
+        this.relationships = this.entry(value);
+        return value;
+    }
+    clear() {
+        this.tables = undefined;
+        this.relationships = undefined;
+        this.tableSchemas.clear();
+    }
+    entry(value) {
+        return { value, expiresAt: Date.now() + this.ttlMs };
+    }
+    get(entry) {
+        if (!entry || entry.expiresAt <= Date.now())
+            return undefined;
+        return entry.value;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/schema/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/schema/cache.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACL,KAAK,CAAS;IACvB,MAAM,CAA2B;IACjC,aAAa,CAAkC;IACtC,YAAY,GAAG,IAAI,GAAG,EAAmC,CAAC;IAE3E,YAAY,OAAO,GAAuB,EAAE;QAC1C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAyB;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,QAAyB,EAAE,KAAa;QAC1D,8FAA8F;QAC9F,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,QAAyB,EAAE,MAAgB;QAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,QAAyB;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5C,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAEO,KAAK,CAAI,KAAQ;QACvB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC;IAEO,GAAG,CAAI,KAAgC;QAC7C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,SAAS,CAAC;QAC9D,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;CACF"}