@dudousxd/nestjs-agent-data 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# `@dudousxd/nestjs-agent-data`
+
+> 🪺 Part of the [Aviary](https://davidecarvalho.github.io/aviary) · a governed SQL tool for [`@dudousxd/nestjs-agent`](https://www.npmjs.com/package/@dudousxd/nestjs-agent).
+
+Give the model **read-only SQL access without handing it the database**. Every query is:
+
+1. **AST-validated** — single `SELECT` only (rejects writes/DDL/multi-statement), via `node-sql-parser`.
+2. **Authorized** — checked against a **fail-closed** table-access policy (a table in no allowed group is denied).
+3. **Tenant-scoped** (optional) — rewritten to add `tenantColumn = tenantRef` for scoped tables; rejects CTE/UNION/subquery-in-FROM.
+4. **Capped** — a `LIMIT` is injected before your runner ever touches the DB.
+
+The package never opens a connection — you inject a `QueryRunner` over your read-only pool.
+
+## Install
+
+```bash
+pnpm add @dudousxd/nestjs-agent-data
+```
+
+## Use
+
+```ts
+import {
+  createExecuteSqlTool,
+  GroupTableAccessPolicy,
+  TenantScopeRewriter,
+} from '@dudousxd/nestjs-agent-data';
+
+const { spec, handler } = createExecuteSqlTool({
+  runner: { run: (sql) => readOnlyPool.query(sql) },
+  tableAccess: new GroupTableAccessPolicy({ roleGroups, tablesByGroup }),
+  tenantScope: new TenantScopeRewriter({ tenantColumn: 'tenant_id', scopedTables: ['orders'] }),
+  maxRows: 100,
+});
+// register `spec` + `handler` with the agent's ToolRegistry (or wrap in an @AiTool provider)
+```
+
+## License
+
+MIT © Davide Carvalho

package/dist/index.cjs

@@ -0,0 +1,383 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GroupTableAccessPolicy: () => GroupTableAccessPolicy,
+  SqlValidationError: () => SqlValidationError,
+  SqlValidator: () => SqlValidator,
+  TenantScopeRewriter: () => TenantScopeRewriter,
+  createExecuteSqlTool: () => createExecuteSqlTool,
+  injectLimit: () => injectLimit
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sql-validator.ts
+var import_node_sql_parser = require("node-sql-parser");
+var SqlValidationError = class extends Error {
+  static {
+    __name(this, "SqlValidationError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "SqlValidationError";
+  }
+};
+var FORBIDDEN_AST_TYPES = /* @__PURE__ */ new Set([
+  "insert",
+  "update",
+  "delete",
+  "replace",
+  "create",
+  "drop",
+  "alter",
+  "truncate",
+  "rename",
+  "load_data",
+  "lock",
+  "unlock",
+  "set",
+  "call",
+  "handler",
+  "use",
+  "grant",
+  "revoke"
+]);
+var SqlValidator = class {
+  static {
+    __name(this, "SqlValidator");
+  }
+  parser = new import_node_sql_parser.Parser();
+  /**
+  * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.
+  * On success returns the distinct base table names referenced.
+  */
+  validate(sql) {
+    let parsed;
+    try {
+      parsed = this.parser.astify(sql, {
+        database: "MySQL"
+      });
+    } catch (err) {
+      throw new SqlValidationError(`Parse error: ${err.message}`);
+    }
+    const statements = Array.isArray(parsed) ? parsed : [
+      parsed
+    ];
+    if (statements.length !== 1) {
+      throw new SqlValidationError("Only a single statement is allowed");
+    }
+    const statement = statements[0];
+    const type = (statement?.type ?? "").toLowerCase();
+    if (type !== "select") {
+      if ([
+        "create",
+        "drop",
+        "alter",
+        "truncate",
+        "rename"
+      ].includes(type)) {
+        throw new SqlValidationError("DDL is not allowed; only SELECT statements are accepted");
+      }
+      if (FORBIDDEN_AST_TYPES.has(type)) {
+        throw new SqlValidationError(`${type.toUpperCase()} is not allowed; only SELECT statements are accepted`);
+      }
+      throw new SqlValidationError(`Statement type "${type || "unknown"}" is not allowed; only SELECT statements are accepted`);
+    }
+    return {
+      tables: this.extractReferencedTables(sql)
+    };
+  }
+  /**
+  * Distinct base table names a statement touches — walking CTEs, subqueries,
+  * and joins. Backed by `node-sql-parser`'s `tableList`, which emits
+  * `mode::db::table` strings; the table name is the last segment.
+  */
+  extractReferencedTables(sql) {
+    const raw = this.parser.tableList(sql, {
+      database: "MySQL"
+    });
+    const tables = /* @__PURE__ */ new Set();
+    for (const entry of raw) {
+      const parts = entry.split("::");
+      const table = parts[parts.length - 1];
+      if (table && table !== "null") tables.add(table);
+    }
+    return Array.from(tables);
+  }
+};
+
+// src/table-access.ts
+var GroupTableAccessPolicy = class {
+  static {
+    __name(this, "GroupTableAccessPolicy");
+  }
+  roleGroups;
+  tablesByGroup;
+  constructor(config) {
+    this.roleGroups = config.roleGroups;
+    this.tablesByGroup = config.tablesByGroup;
+  }
+  canAccess(roles, table) {
+    const group = this.resolveGroup(table);
+    if (group === void 0) return false;
+    return roles.some((role) => this.roleGroups[role]?.includes(group) ?? false);
+  }
+  /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */
+  resolveGroup(table) {
+    for (const [group, patterns] of Object.entries(this.tablesByGroup)) {
+      for (const pattern of patterns) {
+        if (matchesPattern(table, pattern)) return group;
+      }
+    }
+    return void 0;
+  }
+};
+function matchesPattern(table, pattern) {
+  if (pattern.endsWith("*")) {
+    return table.startsWith(pattern.slice(0, -1));
+  }
+  return table === pattern;
+}
+__name(matchesPattern, "matchesPattern");
+
+// src/tenant-scope.ts
+var import_node_sql_parser2 = require("node-sql-parser");
+var STRING_LITERAL_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "single_quote_string",
+  "double_quote_string"
+]);
+var TenantScopeRewriter = class {
+  static {
+    __name(this, "TenantScopeRewriter");
+  }
+  parser = new import_node_sql_parser2.Parser();
+  tenantColumn;
+  scopedTables;
+  constructor(config) {
+    this.tenantColumn = config.tenantColumn;
+    this.scopedTables = new Set(config.scopedTables);
+  }
+  /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */
+  rewrite(sql, tenantRef) {
+    if (tenantRef === void 0) return sql;
+    const parsed = this.parser.astify(sql, {
+      database: "MySQL"
+    });
+    const ast = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (ast.type !== "select") {
+      throw new Error("tenant scope: only SELECT is supported");
+    }
+    if (ast.with) {
+      throw new Error("tenant scope: WITH (CTE) is not supported in scoped mode \u2014 rewrite using JOINs/subqueries in FROM");
+    }
+    if (ast._next) {
+      throw new Error("tenant scope: UNION/INTERSECT/EXCEPT is not supported in scoped mode \u2014 run each branch as a separate query");
+    }
+    const fromEntries = ast.from ?? [];
+    for (const entry of fromEntries) {
+      if (!entry.table && entry.expr?.ast) {
+        throw new Error("tenant scope: subqueries in FROM are not supported in scoped mode");
+      }
+    }
+    const scopedFrom = fromEntries.filter((entry) => typeof entry.table === "string" && this.scopedTables.has(entry.table));
+    if (scopedFrom.length === 0) return sql;
+    const existing = this.collectTenantPredicates(ast.where);
+    for (const predicate of existing) {
+      if (predicate.value !== tenantRef) {
+        throw new Error("tenant scope: tenant mismatch \u2014 query targets a tenant other than the current session");
+      }
+    }
+    const coveredAliases = new Set(existing.map((predicate) => predicate.tableAlias));
+    for (const entry of scopedFrom) {
+      const alias = entry.as ?? entry.table;
+      const isAmbiguous = scopedFrom.length > 1;
+      const covered = coveredAliases.has(alias) || !isAmbiguous && coveredAliases.has(null);
+      if (covered) continue;
+      ast.where = this.andCondition(ast.where, this.buildTenantEquality(isAmbiguous ? alias : null, tenantRef));
+    }
+    return this.parser.sqlify(ast, {
+      database: "MySQL"
+    });
+  }
+  collectTenantPredicates(where) {
+    if (!isBinaryExpr(where)) return [];
+    if (where.operator === "AND" || where.operator === "OR") {
+      return [
+        ...this.collectTenantPredicates(where.left),
+        ...this.collectTenantPredicates(where.right)
+      ];
+    }
+    if (where.operator !== "=") return [];
+    const lhs = where.left;
+    const rhs = where.right;
+    if (!isColumnRef(lhs) || lhs.column !== this.tenantColumn) return [];
+    if (!isStringLiteral(rhs)) return [];
+    return [
+      {
+        tableAlias: lhs.table ?? null,
+        value: rhs.value
+      }
+    ];
+  }
+  buildTenantEquality(tableAlias, tenantRef) {
+    return {
+      type: "binary_expr",
+      operator: "=",
+      left: {
+        type: "column_ref",
+        table: tableAlias,
+        column: this.tenantColumn
+      },
+      right: {
+        type: "single_quote_string",
+        value: tenantRef
+      }
+    };
+  }
+  andCondition(existing, added) {
+    if (existing == null) return added;
+    return {
+      type: "binary_expr",
+      operator: "AND",
+      left: existing,
+      right: added
+    };
+  }
+};
+function isBinaryExpr(value) {
+  return typeof value === "object" && value !== null && value.type === "binary_expr";
+}
+__name(isBinaryExpr, "isBinaryExpr");
+function isColumnRef(value) {
+  return typeof value === "object" && value !== null && value.type === "column_ref";
+}
+__name(isColumnRef, "isColumnRef");
+function isStringLiteral(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string" && STRING_LITERAL_TYPES.has(value.type) && typeof value.value === "string";
+}
+__name(isStringLiteral, "isStringLiteral");
+
+// src/limit.ts
+var import_node_sql_parser3 = require("node-sql-parser");
+var parser = new import_node_sql_parser3.Parser();
+function injectLimit(sql, max) {
+  const trimmed = sql.trim().replace(/;\s*$/, "");
+  if (hasLimit(trimmed)) return trimmed;
+  return `SELECT * FROM (${trimmed}) AS subq LIMIT ${max}`;
+}
+__name(injectLimit, "injectLimit");
+function hasLimit(sql) {
+  try {
+    const parsed = parser.astify(sql, {
+      database: "MySQL"
+    });
+    const statement = Array.isArray(parsed) ? parsed[0] : parsed;
+    const limit = statement?.limit;
+    return Boolean(limit && Array.isArray(limit.value) && limit.value.length > 0);
+  } catch {
+    return false;
+  }
+}
+__name(hasLimit, "hasLimit");
+
+// src/execute-sql.tool.ts
+var import_zod = require("zod");
+var DEFAULT_MAX_ROWS = 100;
+var MAX_RESULT_BYTES = 256 * 1024;
+var inputSchema = import_zod.z.object({
+  sql: import_zod.z.string().min(1).describe("A single read-only MySQL SELECT statement")
+});
+var DESCRIPTION = "Execute a single read-only MySQL SELECT statement. Use this to answer questions about real data. Only SELECT is allowed (no INSERT/UPDATE/DELETE/DDL). Access is restricted to the tables your role is permitted to read, results are capped, and tenant-scoped tables are automatically constrained to your current tenant.";
+function createExecuteSqlTool(deps) {
+  const validator = deps.validator ?? new SqlValidator();
+  const maxRows = deps.maxRows ?? DEFAULT_MAX_ROWS;
+  const spec = {
+    name: "executeSql",
+    kind: "read",
+    description: DESCRIPTION,
+    inputSchema
+  };
+  const handler = {
+    async execute(input, ctx) {
+      const { tables } = validator.validate(input.sql);
+      const roles = ctx.actor.roles ?? [];
+      const forbidden = tables.filter((table) => !deps.tableAccess.canAccess(roles, table));
+      if (forbidden.length > 0) {
+        const formatted = forbidden.map((table) => `\`${table}\``).join(", ");
+        const rolesLabel = roles.length > 0 ? roles.join(", ") : "none";
+        throw new Error(`Your roles (${rolesLabel}) are not allowed to query ${formatted}.`);
+      }
+      let sql = input.sql;
+      if (deps.tenantScope) {
+        sql = deps.tenantScope.rewrite(sql, ctx.actor.tenantRef);
+      }
+      sql = injectLimit(sql, maxRows);
+      const rows = await deps.runner.run(sql);
+      return buildResult(rows, sql);
+    }
+  };
+  return {
+    spec,
+    handler
+  };
+}
+__name(createExecuteSqlTool, "createExecuteSqlTool");
+function buildResult(rows, sql) {
+  const rowCount = rows.length;
+  if (byteLength(rows) <= MAX_RESULT_BYTES) {
+    return {
+      rows,
+      rowCount,
+      sql
+    };
+  }
+  const kept = [];
+  let size = 2;
+  for (const row of rows) {
+    const rowSize = byteLength(row) + 1;
+    if (size + rowSize > MAX_RESULT_BYTES) break;
+    kept.push(row);
+    size += rowSize;
+  }
+  return {
+    rows: kept,
+    rowCount,
+    sql,
+    truncated: true
+  };
+}
+__name(buildResult, "buildResult");
+function byteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+}
+__name(byteLength, "byteLength");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GroupTableAccessPolicy,
+  SqlValidationError,
+  SqlValidator,
+  TenantScopeRewriter,
+  createExecuteSqlTool,
+  injectLimit
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sql-validator.ts","../src/table-access.ts","../src/tenant-scope.ts","../src/limit.ts","../src/execute-sql.tool.ts"],"sourcesContent":["export { SqlValidator, SqlValidationError, type SqlValidationResult } from './sql-validator.js';\nexport {\n  type TableAccessPolicy,\n  type GroupTableAccessConfig,\n  GroupTableAccessPolicy,\n} from './table-access.js';\nexport {\n  TenantScopeRewriter,\n  type TenantScopeConfig,\n} from './tenant-scope.js';\nexport { injectLimit } from './limit.js';\nexport {\n  createExecuteSqlTool,\n  type QueryRunner,\n  type ExecuteSqlDeps,\n  type ExecuteSqlResult,\n} from './execute-sql.tool.js';\n","import { Parser } from 'node-sql-parser';\n\n/**\n * Thrown when a statement is not a single, read-only SELECT — i.e. it is an\n * INSERT/UPDATE/DELETE, DDL, a CALL, a multi-statement string, or it fails to\n * parse. The handler surfaces `.message` to the model so it can re-plan.\n */\nexport class SqlValidationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SqlValidationError';\n  }\n}\n\n/** Statement types that are categorically rejected (anything that writes or runs code). */\nconst FORBIDDEN_AST_TYPES = new Set([\n  'insert',\n  'update',\n  'delete',\n  'replace',\n  'create',\n  'drop',\n  'alter',\n  'truncate',\n  'rename',\n  'load_data',\n  'lock',\n  'unlock',\n  'set',\n  'call',\n  'handler',\n  'use',\n  'grant',\n  'revoke',\n]);\n\nexport interface SqlValidationResult {\n  /** Every base table the statement references (CTEs, joins, subqueries walked). */\n  tables: string[];\n}\n\n/**\n * Parses SQL (MySQL dialect) and asserts it is a single SELECT, returning the\n * set of tables it touches. Domain-agnostic: it knows nothing about which\n * tables a caller may read — that is the `TableAccessPolicy`'s job.\n */\nexport class SqlValidator {\n  private readonly parser = new Parser();\n\n  /**\n   * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.\n   * On success returns the distinct base table names referenced.\n   */\n  validate(sql: string): SqlValidationResult {\n    let parsed: unknown;\n    try {\n      parsed = this.parser.astify(sql, { database: 'MySQL' });\n    } catch (err) {\n      throw new SqlValidationError(`Parse error: ${(err as Error).message}`);\n    }\n\n    const statements = Array.isArray(parsed) ? parsed : [parsed];\n    if (statements.length !== 1) {\n      throw new SqlValidationError('Only a single statement is allowed');\n    }\n\n    const statement = statements[0] as { type?: string } | undefined;\n    const type = (statement?.type ?? '').toLowerCase();\n\n    if (type !== 'select') {\n      if (['create', 'drop', 'alter', 'truncate', 'rename'].includes(type)) {\n        throw new SqlValidationError('DDL is not allowed; only SELECT statements are accepted');\n      }\n      if (FORBIDDEN_AST_TYPES.has(type)) {\n        throw new SqlValidationError(\n          `${type.toUpperCase()} is not allowed; only SELECT statements are accepted`,\n        );\n      }\n      throw new SqlValidationError(\n        `Statement type \"${type || 'unknown'}\" is not allowed; only SELECT statements are accepted`,\n      );\n    }\n\n    return { tables: this.extractReferencedTables(sql) };\n  }\n\n  /**\n   * Distinct base table names a statement touches — walking CTEs, subqueries,\n   * and joins. Backed by `node-sql-parser`'s `tableList`, which emits\n   * `mode::db::table` strings; the table name is the last segment.\n   */\n  private extractReferencedTables(sql: string): string[] {\n    const raw = this.parser.tableList(sql, { database: 'MySQL' });\n    const tables = new Set<string>();\n    for (const entry of raw) {\n      const parts = entry.split('::');\n      const table = parts[parts.length - 1];\n      if (table && table !== 'null') tables.add(table);\n    }\n    return Array.from(tables);\n  }\n}\n","/**\n * Decides whether a role may read a given table at all. This is the coarse,\n * table-level gate; per-row scoping (see `TenantScopeRewriter`) is a separate\n * layer applied at query time.\n *\n * Domain-agnostic: the host app supplies the role→group and group→table maps.\n */\nexport interface TableAccessPolicy {\n  /** True iff any of the caller's `roles` is permitted to read `table`. Fail-closed by contract. */\n  canAccess(roles: readonly string[], table: string): boolean;\n}\n\n/** Inputs for {@link GroupTableAccessPolicy}: roles map to groups, groups to tables. */\nexport interface GroupTableAccessConfig {\n  /** Role name → the table groups that role may read. */\n  roleGroups: Record<string, string[]>;\n  /**\n   * Group name → the tables in that group. Entries are exact table names or\n   * `prefix_*` patterns (e.g. `pribuy_*`).\n   */\n  tablesByGroup: Record<string, string[]>;\n}\n\n/**\n * Two-layer, data-driven table allowlist:\n *\n *   1. Every table is classified into a group (`tablesByGroup`).\n *   2. Every role lists the groups it can read (`roleGroups`).\n *\n * `canAccess(roles, table)` is then \"is the table's group in ANY of the roles'\n * group lists?\". **Fail-closed:** an unclassified table, unknown roles, or an\n * empty role set is denied — a forgotten table never accidentally leaks.\n */\nexport class GroupTableAccessPolicy implements TableAccessPolicy {\n  private readonly roleGroups: Record<string, string[]>;\n  private readonly tablesByGroup: Record<string, string[]>;\n\n  constructor(config: GroupTableAccessConfig) {\n    this.roleGroups = config.roleGroups;\n    this.tablesByGroup = config.tablesByGroup;\n  }\n\n  canAccess(roles: readonly string[], table: string): boolean {\n    const group = this.resolveGroup(table);\n    if (group === undefined) return false;\n\n    return roles.some((role) => this.roleGroups[role]?.includes(group) ?? false);\n  }\n\n  /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */\n  private resolveGroup(table: string): string | undefined {\n    for (const [group, patterns] of Object.entries(this.tablesByGroup)) {\n      for (const pattern of patterns) {\n        if (matchesPattern(table, pattern)) return group;\n      }\n    }\n    return undefined;\n  }\n}\n\nfunction matchesPattern(table: string, pattern: string): boolean {\n  if (pattern.endsWith('*')) {\n    return table.startsWith(pattern.slice(0, -1));\n  }\n  return table === pattern;\n}\n","import type { AST } from 'node-sql-parser';\nimport { Parser } from 'node-sql-parser';\n\n/** Configuration for {@link TenantScopeRewriter}. */\nexport interface TenantScopeConfig {\n  /** The column that carries the tenant key on every scoped table (e.g. `base_id`, `org_id`). */\n  tenantColumn: string;\n  /** Tables that must be constrained to the caller's tenant when referenced. */\n  scopedTables: string[];\n}\n\ninterface FromEntry {\n  table?: string;\n  as?: string | null;\n  join?: string;\n  expr?: { ast?: unknown };\n}\n\ninterface SelectAst {\n  type: string;\n  with?: unknown;\n  from?: FromEntry[];\n  where?: unknown;\n  _next?: unknown;\n}\n\ninterface BinaryExpr {\n  type: 'binary_expr';\n  operator: string;\n  left: unknown;\n  right: unknown;\n}\n\ninterface ColumnRef {\n  type: 'column_ref';\n  table: string | null;\n  column: string;\n}\n\ninterface ExtractedPredicate {\n  tableAlias: string | null;\n  value: string;\n}\n\nconst STRING_LITERAL_TYPES = new Set(['string', 'single_quote_string', 'double_quote_string']);\n\n/**\n * Rewrites a SELECT so every reference to a scoped table is constrained to a\n * single tenant: `<tenantColumn> = '<tenantRef>'` is AND-ed into the WHERE for\n * each scoped table in the FROM. An existing predicate for a different tenant\n * is rejected (no cross-tenant reads). `tenantRef === undefined` is the\n * privileged path and passes the SQL through unchanged.\n *\n * Scoped mode rejects CTEs, UNION/INTERSECT/EXCEPT, and subqueries in FROM:\n * those make it impossible to statically guarantee every tenant-bearing source\n * is constrained, so we fail closed and ask the caller to rephrase.\n */\nexport class TenantScopeRewriter {\n  private readonly parser = new Parser();\n  private readonly tenantColumn: string;\n  private readonly scopedTables: Set<string>;\n\n  constructor(config: TenantScopeConfig) {\n    this.tenantColumn = config.tenantColumn;\n    this.scopedTables = new Set(config.scopedTables);\n  }\n\n  /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */\n  rewrite(sql: string, tenantRef: string | undefined): string {\n    if (tenantRef === undefined) return sql;\n\n    const parsed = this.parser.astify(sql, { database: 'MySQL' });\n    const ast = (Array.isArray(parsed) ? parsed[0] : parsed) as SelectAst;\n\n    if (ast.type !== 'select') {\n      throw new Error('tenant scope: only SELECT is supported');\n    }\n    if (ast.with) {\n      throw new Error(\n        'tenant scope: WITH (CTE) is not supported in scoped mode — rewrite using JOINs/subqueries in FROM',\n      );\n    }\n    if (ast._next) {\n      throw new Error(\n        'tenant scope: UNION/INTERSECT/EXCEPT is not supported in scoped mode — run each branch as a separate query',\n      );\n    }\n\n    const fromEntries = ast.from ?? [];\n    for (const entry of fromEntries) {\n      if (!entry.table && entry.expr?.ast) {\n        throw new Error('tenant scope: subqueries in FROM are not supported in scoped mode');\n      }\n    }\n\n    const scopedFrom = fromEntries.filter(\n      (entry): entry is FromEntry & { table: string } =>\n        typeof entry.table === 'string' && this.scopedTables.has(entry.table),\n    );\n    if (scopedFrom.length === 0) return sql;\n\n    const existing = this.collectTenantPredicates(ast.where);\n    for (const predicate of existing) {\n      if (predicate.value !== tenantRef) {\n        throw new Error(\n          'tenant scope: tenant mismatch — query targets a tenant other than the current session',\n        );\n      }\n    }\n\n    const coveredAliases = new Set(existing.map((predicate) => predicate.tableAlias));\n    for (const entry of scopedFrom) {\n      const alias = entry.as ?? entry.table;\n      const isAmbiguous = scopedFrom.length > 1;\n      const covered = coveredAliases.has(alias) || (!isAmbiguous && coveredAliases.has(null));\n      if (covered) continue;\n      ast.where = this.andCondition(\n        ast.where,\n        this.buildTenantEquality(isAmbiguous ? alias : null, tenantRef),\n      );\n    }\n\n    return this.parser.sqlify(ast as unknown as AST, { database: 'MySQL' });\n  }\n\n  private collectTenantPredicates(where: unknown): ExtractedPredicate[] {\n    if (!isBinaryExpr(where)) return [];\n    if (where.operator === 'AND' || where.operator === 'OR') {\n      return [\n        ...this.collectTenantPredicates(where.left),\n        ...this.collectTenantPredicates(where.right),\n      ];\n    }\n    if (where.operator !== '=') return [];\n    const lhs = where.left;\n    const rhs = where.right;\n    if (!isColumnRef(lhs) || lhs.column !== this.tenantColumn) return [];\n    if (!isStringLiteral(rhs)) return [];\n    return [{ tableAlias: lhs.table ?? null, value: rhs.value }];\n  }\n\n  private buildTenantEquality(tableAlias: string | null, tenantRef: string): BinaryExpr {\n    return {\n      type: 'binary_expr',\n      operator: '=',\n      left: { type: 'column_ref', table: tableAlias, column: this.tenantColumn },\n      right: { type: 'single_quote_string', value: tenantRef },\n    };\n  }\n\n  private andCondition(existing: unknown, added: BinaryExpr): BinaryExpr {\n    if (existing == null) return added;\n    return {\n      type: 'binary_expr',\n      operator: 'AND',\n      left: existing,\n      right: added,\n    };\n  }\n}\n\nfunction isBinaryExpr(value: unknown): value is BinaryExpr {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { type?: unknown }).type === 'binary_expr'\n  );\n}\n\nfunction isColumnRef(value: unknown): value is ColumnRef {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { type?: unknown }).type === 'column_ref'\n  );\n}\n\nfunction isStringLiteral(value: unknown): value is { type: string; value: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { type?: unknown }).type === 'string' &&\n    STRING_LITERAL_TYPES.has((value as { type: string }).type) &&\n    typeof (value as { value?: unknown }).value === 'string'\n  );\n}\n","import { Parser } from 'node-sql-parser';\n\nconst parser = new Parser();\n\n/**\n * Ensures a SELECT returns at most `max` rows. If the statement already carries\n * a LIMIT it is returned unchanged; otherwise it is wrapped in a bounding\n * subquery (`SELECT * FROM (<sql>) AS subq LIMIT <max>`) so any ORDER BY /\n * GROUP BY / UNION inside `sql` is preserved.\n */\nexport function injectLimit(sql: string, max: number): string {\n  const trimmed = sql.trim().replace(/;\\s*$/, '');\n  if (hasLimit(trimmed)) return trimmed;\n  return `SELECT * FROM (${trimmed}) AS subq LIMIT ${max}`;\n}\n\nfunction hasLimit(sql: string): boolean {\n  try {\n    const parsed = parser.astify(sql, { database: 'MySQL' });\n    const statement = (Array.isArray(parsed) ? parsed[0] : parsed) as\n      | { limit?: { value?: unknown[] } | null }\n      | undefined;\n    const limit = statement?.limit;\n    return Boolean(limit && Array.isArray(limit.value) && limit.value.length > 0);\n  } catch {\n    // If we can't parse it here, fall back to wrapping — the validator already\n    // ran and accepted it, so wrapping is the safe choice.\n    return false;\n  }\n}\n","import type { AiToolCtx, ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport { z } from 'zod';\nimport { injectLimit } from './limit.js';\nimport { SqlValidator } from './sql-validator.js';\nimport type { TableAccessPolicy } from './table-access.js';\nimport type { TenantScopeRewriter } from './tenant-scope.js';\n\n/** App-supplied runner over a read-only connection pool. The package never opens a DB. */\nexport interface QueryRunner {\n  run(sql: string): Promise<Record<string, unknown>[]>;\n}\n\n/** Dependencies for {@link createExecuteSqlTool}. */\nexport interface ExecuteSqlDeps {\n  /** Runs the (already validated, scoped, and limited) SQL against the read-only pool. */\n  runner: QueryRunner;\n  /** Single-SELECT validator. Defaults to a fresh {@link SqlValidator}. */\n  validator?: SqlValidator;\n  /** Coarse table-level allowlist, checked for every referenced table. */\n  tableAccess: TableAccessPolicy;\n  /** Optional per-row tenant constraint applied before the query runs. */\n  tenantScope?: TenantScopeRewriter;\n  /** Row cap injected when the query has no LIMIT. Defaults to 100. */\n  maxRows?: number;\n}\n\nexport interface ExecuteSqlResult {\n  rows: Record<string, unknown>[];\n  rowCount: number;\n  sql: string;\n  truncated?: true;\n}\n\nconst DEFAULT_MAX_ROWS = 100;\n\n/** Serialized rows above this size are truncated so a single tool result can't blow the context. */\nconst MAX_RESULT_BYTES = 256 * 1024;\n\nconst inputSchema = z.object({\n  sql: z.string().min(1).describe('A single read-only MySQL SELECT statement'),\n});\n\ntype ExecuteSqlInput = z.infer<typeof inputSchema>;\n\nconst DESCRIPTION =\n  'Execute a single read-only MySQL SELECT statement. Use this to answer questions about real ' +\n  'data. Only SELECT is allowed (no INSERT/UPDATE/DELETE/DDL). Access is restricted to the ' +\n  'tables your role is permitted to read, results are capped, and tenant-scoped tables are ' +\n  'automatically constrained to your current tenant.';\n\n/**\n * Builds the governed `executeSql` read tool. The pipeline per call is:\n * validate (single SELECT) → assert table access for every referenced table →\n * tenant-scope rewrite (if configured) → inject LIMIT → run → return rows,\n * truncating the payload if it would exceed ~256KB.\n */\nexport function createExecuteSqlTool(deps: ExecuteSqlDeps): {\n  spec: ToolSpec;\n  handler: ToolHandler<ExecuteSqlInput>;\n} {\n  const validator = deps.validator ?? new SqlValidator();\n  const maxRows = deps.maxRows ?? DEFAULT_MAX_ROWS;\n\n  const spec: ToolSpec = {\n    name: 'executeSql',\n    kind: 'read',\n    description: DESCRIPTION,\n    inputSchema,\n  };\n\n  const handler: ToolHandler<ExecuteSqlInput> = {\n    async execute(input: ExecuteSqlInput, ctx: AiToolCtx): Promise<ExecuteSqlResult> {\n      const { tables } = validator.validate(input.sql);\n\n      const roles = ctx.actor.roles ?? [];\n      const forbidden = tables.filter((table) => !deps.tableAccess.canAccess(roles, table));\n      if (forbidden.length > 0) {\n        const formatted = forbidden.map((table) => `\\`${table}\\``).join(', ');\n        const rolesLabel = roles.length > 0 ? roles.join(', ') : 'none';\n        throw new Error(`Your roles (${rolesLabel}) are not allowed to query ${formatted}.`);\n      }\n\n      let sql = input.sql;\n      if (deps.tenantScope) {\n        sql = deps.tenantScope.rewrite(sql, ctx.actor.tenantRef);\n      }\n      sql = injectLimit(sql, maxRows);\n\n      const rows = await deps.runner.run(sql);\n      return buildResult(rows, sql);\n    },\n  };\n\n  return { spec, handler };\n}\n\nfunction buildResult(rows: Record<string, unknown>[], sql: string): ExecuteSqlResult {\n  const rowCount = rows.length;\n  if (byteLength(rows) <= MAX_RESULT_BYTES) {\n    return { rows, rowCount, sql };\n  }\n\n  // Keep prefix rows until the serialized payload would exceed the cap.\n  const kept: Record<string, unknown>[] = [];\n  let size = 2; // opening + closing bracket of the JSON array\n  for (const row of rows) {\n    const rowSize = byteLength(row) + 1; // +1 for the joining comma\n    if (size + rowSize > MAX_RESULT_BYTES) break;\n    kept.push(row);\n    size += rowSize;\n  }\n\n  return { rows: kept, rowCount, sql, truncated: true };\n}\n\nfunction byteLength(value: unknown): number {\n  return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');\n}\n"],"mappings":"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","names":["SqlValidationError","Error","message","name","FORBIDDEN_AST_TYPES","Set","SqlValidator","parser","Parser","validate","sql","parsed","astify","database","err","statements","Array","isArray","length","statement","type","toLowerCase","includes","has","toUpperCase","tables","extractReferencedTables","raw","tableList","entry","parts","split","table","add","from","GroupTableAccessPolicy","roleGroups","tablesByGroup","config","canAccess","roles","table","group","resolveGroup","undefined","some","role","includes","patterns","Object","entries","pattern","matchesPattern","endsWith","startsWith","slice","import_node_sql_parser","STRING_LITERAL_TYPES","Set","TenantScopeRewriter","parser","Parser","tenantColumn","scopedTables","config","rewrite","sql","tenantRef","undefined","parsed","astify","database","ast","Array","isArray","type","Error","with","_next","fromEntries","from","entry","table","expr","scopedFrom","filter","has","length","existing","collectTenantPredicates","where","predicate","value","coveredAliases","map","tableAlias","alias","as","isAmbiguous","covered","andCondition","buildTenantEquality","sqlify","isBinaryExpr","operator","left","right","lhs","rhs","isColumnRef","column","isStringLiteral","added","import_node_sql_parser","parser","Parser","injectLimit","sql","max","trimmed","trim","replace","hasLimit","parsed","astify","database","statement","Array","isArray","limit","Boolean","value","length","DEFAULT_MAX_ROWS","MAX_RESULT_BYTES","inputSchema","z","object","sql","string","min","describe","DESCRIPTION","createExecuteSqlTool","deps","validator","SqlValidator","maxRows","spec","name","kind","description","handler","execute","input","ctx","tables","validate","roles","actor","forbidden","filter","table","tableAccess","canAccess","length","formatted","map","join","rolesLabel","Error","tenantScope","rewrite","tenantRef","injectLimit","rows","runner","run","buildResult","rowCount","byteLength","kept","size","row","rowSize","push","truncated","value","Buffer","JSON","stringify"]}

package/dist/index.d.cts

@@ -0,0 +1,156 @@
+import { ToolSpec, ToolHandler } from '@dudousxd/nestjs-agent-core';
+import { z } from 'zod';
+
+/**
+ * Thrown when a statement is not a single, read-only SELECT — i.e. it is an
+ * INSERT/UPDATE/DELETE, DDL, a CALL, a multi-statement string, or it fails to
+ * parse. The handler surfaces `.message` to the model so it can re-plan.
+ */
+declare class SqlValidationError extends Error {
+    constructor(message: string);
+}
+interface SqlValidationResult {
+    /** Every base table the statement references (CTEs, joins, subqueries walked). */
+    tables: string[];
+}
+/**
+ * Parses SQL (MySQL dialect) and asserts it is a single SELECT, returning the
+ * set of tables it touches. Domain-agnostic: it knows nothing about which
+ * tables a caller may read — that is the `TableAccessPolicy`'s job.
+ */
+declare class SqlValidator {
+    private readonly parser;
+    /**
+     * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.
+     * On success returns the distinct base table names referenced.
+     */
+    validate(sql: string): SqlValidationResult;
+    /**
+     * Distinct base table names a statement touches — walking CTEs, subqueries,
+     * and joins. Backed by `node-sql-parser`'s `tableList`, which emits
+     * `mode::db::table` strings; the table name is the last segment.
+     */
+    private extractReferencedTables;
+}
+
+/**
+ * Decides whether a role may read a given table at all. This is the coarse,
+ * table-level gate; per-row scoping (see `TenantScopeRewriter`) is a separate
+ * layer applied at query time.
+ *
+ * Domain-agnostic: the host app supplies the role→group and group→table maps.
+ */
+interface TableAccessPolicy {
+    /** True iff any of the caller's `roles` is permitted to read `table`. Fail-closed by contract. */
+    canAccess(roles: readonly string[], table: string): boolean;
+}
+/** Inputs for {@link GroupTableAccessPolicy}: roles map to groups, groups to tables. */
+interface GroupTableAccessConfig {
+    /** Role name → the table groups that role may read. */
+    roleGroups: Record<string, string[]>;
+    /**
+     * Group name → the tables in that group. Entries are exact table names or
+     * `prefix_*` patterns (e.g. `pribuy_*`).
+     */
+    tablesByGroup: Record<string, string[]>;
+}
+/**
+ * Two-layer, data-driven table allowlist:
+ *
+ *   1. Every table is classified into a group (`tablesByGroup`).
+ *   2. Every role lists the groups it can read (`roleGroups`).
+ *
+ * `canAccess(roles, table)` is then "is the table's group in ANY of the roles'
+ * group lists?". **Fail-closed:** an unclassified table, unknown roles, or an
+ * empty role set is denied — a forgotten table never accidentally leaks.
+ */
+declare class GroupTableAccessPolicy implements TableAccessPolicy {
+    private readonly roleGroups;
+    private readonly tablesByGroup;
+    constructor(config: GroupTableAccessConfig);
+    canAccess(roles: readonly string[], table: string): boolean;
+    /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */
+    private resolveGroup;
+}
+
+/** Configuration for {@link TenantScopeRewriter}. */
+interface TenantScopeConfig {
+    /** The column that carries the tenant key on every scoped table (e.g. `base_id`, `org_id`). */
+    tenantColumn: string;
+    /** Tables that must be constrained to the caller's tenant when referenced. */
+    scopedTables: string[];
+}
+/**
+ * Rewrites a SELECT so every reference to a scoped table is constrained to a
+ * single tenant: `<tenantColumn> = '<tenantRef>'` is AND-ed into the WHERE for
+ * each scoped table in the FROM. An existing predicate for a different tenant
+ * is rejected (no cross-tenant reads). `tenantRef === undefined` is the
+ * privileged path and passes the SQL through unchanged.
+ *
+ * Scoped mode rejects CTEs, UNION/INTERSECT/EXCEPT, and subqueries in FROM:
+ * those make it impossible to statically guarantee every tenant-bearing source
+ * is constrained, so we fail closed and ask the caller to rephrase.
+ */
+declare class TenantScopeRewriter {
+    private readonly parser;
+    private readonly tenantColumn;
+    private readonly scopedTables;
+    constructor(config: TenantScopeConfig);
+    /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */
+    rewrite(sql: string, tenantRef: string | undefined): string;
+    private collectTenantPredicates;
+    private buildTenantEquality;
+    private andCondition;
+}
+
+/**
+ * Ensures a SELECT returns at most `max` rows. If the statement already carries
+ * a LIMIT it is returned unchanged; otherwise it is wrapped in a bounding
+ * subquery (`SELECT * FROM (<sql>) AS subq LIMIT <max>`) so any ORDER BY /
+ * GROUP BY / UNION inside `sql` is preserved.
+ */
+declare function injectLimit(sql: string, max: number): string;
+
+/** App-supplied runner over a read-only connection pool. The package never opens a DB. */
+interface QueryRunner {
+    run(sql: string): Promise<Record<string, unknown>[]>;
+}
+/** Dependencies for {@link createExecuteSqlTool}. */
+interface ExecuteSqlDeps {
+    /** Runs the (already validated, scoped, and limited) SQL against the read-only pool. */
+    runner: QueryRunner;
+    /** Single-SELECT validator. Defaults to a fresh {@link SqlValidator}. */
+    validator?: SqlValidator;
+    /** Coarse table-level allowlist, checked for every referenced table. */
+    tableAccess: TableAccessPolicy;
+    /** Optional per-row tenant constraint applied before the query runs. */
+    tenantScope?: TenantScopeRewriter;
+    /** Row cap injected when the query has no LIMIT. Defaults to 100. */
+    maxRows?: number;
+}
+interface ExecuteSqlResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    sql: string;
+    truncated?: true;
+}
+declare const inputSchema: z.ZodObject<{
+    sql: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sql: string;
+}, {
+    sql: string;
+}>;
+type ExecuteSqlInput = z.infer<typeof inputSchema>;
+/**
+ * Builds the governed `executeSql` read tool. The pipeline per call is:
+ * validate (single SELECT) → assert table access for every referenced table →
+ * tenant-scope rewrite (if configured) → inject LIMIT → run → return rows,
+ * truncating the payload if it would exceed ~256KB.
+ */
+declare function createExecuteSqlTool(deps: ExecuteSqlDeps): {
+    spec: ToolSpec;
+    handler: ToolHandler<ExecuteSqlInput>;
+};
+
+export { type ExecuteSqlDeps, type ExecuteSqlResult, type GroupTableAccessConfig, GroupTableAccessPolicy, type QueryRunner, SqlValidationError, type SqlValidationResult, SqlValidator, type TableAccessPolicy, type TenantScopeConfig, TenantScopeRewriter, createExecuteSqlTool, injectLimit };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { ToolSpec, ToolHandler } from '@dudousxd/nestjs-agent-core';
+import { z } from 'zod';
+
+/**
+ * Thrown when a statement is not a single, read-only SELECT — i.e. it is an
+ * INSERT/UPDATE/DELETE, DDL, a CALL, a multi-statement string, or it fails to
+ * parse. The handler surfaces `.message` to the model so it can re-plan.
+ */
+declare class SqlValidationError extends Error {
+    constructor(message: string);
+}
+interface SqlValidationResult {
+    /** Every base table the statement references (CTEs, joins, subqueries walked). */
+    tables: string[];
+}
+/**
+ * Parses SQL (MySQL dialect) and asserts it is a single SELECT, returning the
+ * set of tables it touches. Domain-agnostic: it knows nothing about which
+ * tables a caller may read — that is the `TableAccessPolicy`'s job.
+ */
+declare class SqlValidator {
+    private readonly parser;
+    /**
+     * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.
+     * On success returns the distinct base table names referenced.
+     */
+    validate(sql: string): SqlValidationResult;
+    /**
+     * Distinct base table names a statement touches — walking CTEs, subqueries,
+     * and joins. Backed by `node-sql-parser`'s `tableList`, which emits
+     * `mode::db::table` strings; the table name is the last segment.
+     */
+    private extractReferencedTables;
+}
+
+/**
+ * Decides whether a role may read a given table at all. This is the coarse,
+ * table-level gate; per-row scoping (see `TenantScopeRewriter`) is a separate
+ * layer applied at query time.
+ *
+ * Domain-agnostic: the host app supplies the role→group and group→table maps.
+ */
+interface TableAccessPolicy {
+    /** True iff any of the caller's `roles` is permitted to read `table`. Fail-closed by contract. */
+    canAccess(roles: readonly string[], table: string): boolean;
+}
+/** Inputs for {@link GroupTableAccessPolicy}: roles map to groups, groups to tables. */
+interface GroupTableAccessConfig {
+    /** Role name → the table groups that role may read. */
+    roleGroups: Record<string, string[]>;
+    /**
+     * Group name → the tables in that group. Entries are exact table names or
+     * `prefix_*` patterns (e.g. `pribuy_*`).
+     */
+    tablesByGroup: Record<string, string[]>;
+}
+/**
+ * Two-layer, data-driven table allowlist:
+ *
+ *   1. Every table is classified into a group (`tablesByGroup`).
+ *   2. Every role lists the groups it can read (`roleGroups`).
+ *
+ * `canAccess(roles, table)` is then "is the table's group in ANY of the roles'
+ * group lists?". **Fail-closed:** an unclassified table, unknown roles, or an
+ * empty role set is denied — a forgotten table never accidentally leaks.
+ */
+declare class GroupTableAccessPolicy implements TableAccessPolicy {
+    private readonly roleGroups;
+    private readonly tablesByGroup;
+    constructor(config: GroupTableAccessConfig);
+    canAccess(roles: readonly string[], table: string): boolean;
+    /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */
+    private resolveGroup;
+}
+
+/** Configuration for {@link TenantScopeRewriter}. */
+interface TenantScopeConfig {
+    /** The column that carries the tenant key on every scoped table (e.g. `base_id`, `org_id`). */
+    tenantColumn: string;
+    /** Tables that must be constrained to the caller's tenant when referenced. */
+    scopedTables: string[];
+}
+/**
+ * Rewrites a SELECT so every reference to a scoped table is constrained to a
+ * single tenant: `<tenantColumn> = '<tenantRef>'` is AND-ed into the WHERE for
+ * each scoped table in the FROM. An existing predicate for a different tenant
+ * is rejected (no cross-tenant reads). `tenantRef === undefined` is the
+ * privileged path and passes the SQL through unchanged.
+ *
+ * Scoped mode rejects CTEs, UNION/INTERSECT/EXCEPT, and subqueries in FROM:
+ * those make it impossible to statically guarantee every tenant-bearing source
+ * is constrained, so we fail closed and ask the caller to rephrase.
+ */
+declare class TenantScopeRewriter {
+    private readonly parser;
+    private readonly tenantColumn;
+    private readonly scopedTables;
+    constructor(config: TenantScopeConfig);
+    /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */
+    rewrite(sql: string, tenantRef: string | undefined): string;
+    private collectTenantPredicates;
+    private buildTenantEquality;
+    private andCondition;
+}
+
+/**
+ * Ensures a SELECT returns at most `max` rows. If the statement already carries
+ * a LIMIT it is returned unchanged; otherwise it is wrapped in a bounding
+ * subquery (`SELECT * FROM (<sql>) AS subq LIMIT <max>`) so any ORDER BY /
+ * GROUP BY / UNION inside `sql` is preserved.
+ */
+declare function injectLimit(sql: string, max: number): string;
+
+/** App-supplied runner over a read-only connection pool. The package never opens a DB. */
+interface QueryRunner {
+    run(sql: string): Promise<Record<string, unknown>[]>;
+}
+/** Dependencies for {@link createExecuteSqlTool}. */
+interface ExecuteSqlDeps {
+    /** Runs the (already validated, scoped, and limited) SQL against the read-only pool. */
+    runner: QueryRunner;
+    /** Single-SELECT validator. Defaults to a fresh {@link SqlValidator}. */
+    validator?: SqlValidator;
+    /** Coarse table-level allowlist, checked for every referenced table. */
+    tableAccess: TableAccessPolicy;
+    /** Optional per-row tenant constraint applied before the query runs. */
+    tenantScope?: TenantScopeRewriter;
+    /** Row cap injected when the query has no LIMIT. Defaults to 100. */
+    maxRows?: number;
+}
+interface ExecuteSqlResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    sql: string;
+    truncated?: true;
+}
+declare const inputSchema: z.ZodObject<{
+    sql: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sql: string;
+}, {
+    sql: string;
+}>;
+type ExecuteSqlInput = z.infer<typeof inputSchema>;
+/**
+ * Builds the governed `executeSql` read tool. The pipeline per call is:
+ * validate (single SELECT) → assert table access for every referenced table →
+ * tenant-scope rewrite (if configured) → inject LIMIT → run → return rows,
+ * truncating the payload if it would exceed ~256KB.
+ */
+declare function createExecuteSqlTool(deps: ExecuteSqlDeps): {
+    spec: ToolSpec;
+    handler: ToolHandler<ExecuteSqlInput>;
+};
+
+export { type ExecuteSqlDeps, type ExecuteSqlResult, type GroupTableAccessConfig, GroupTableAccessPolicy, type QueryRunner, SqlValidationError, type SqlValidationResult, SqlValidator, type TableAccessPolicy, type TenantScopeConfig, TenantScopeRewriter, createExecuteSqlTool, injectLimit };

package/dist/index.js

@@ -0,0 +1,353 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/sql-validator.ts
+import { Parser } from "node-sql-parser";
+var SqlValidationError = class extends Error {
+  static {
+    __name(this, "SqlValidationError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "SqlValidationError";
+  }
+};
+var FORBIDDEN_AST_TYPES = /* @__PURE__ */ new Set([
+  "insert",
+  "update",
+  "delete",
+  "replace",
+  "create",
+  "drop",
+  "alter",
+  "truncate",
+  "rename",
+  "load_data",
+  "lock",
+  "unlock",
+  "set",
+  "call",
+  "handler",
+  "use",
+  "grant",
+  "revoke"
+]);
+var SqlValidator = class {
+  static {
+    __name(this, "SqlValidator");
+  }
+  parser = new Parser();
+  /**
+  * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.
+  * On success returns the distinct base table names referenced.
+  */
+  validate(sql) {
+    let parsed;
+    try {
+      parsed = this.parser.astify(sql, {
+        database: "MySQL"
+      });
+    } catch (err) {
+      throw new SqlValidationError(`Parse error: ${err.message}`);
+    }
+    const statements = Array.isArray(parsed) ? parsed : [
+      parsed
+    ];
+    if (statements.length !== 1) {
+      throw new SqlValidationError("Only a single statement is allowed");
+    }
+    const statement = statements[0];
+    const type = (statement?.type ?? "").toLowerCase();
+    if (type !== "select") {
+      if ([
+        "create",
+        "drop",
+        "alter",
+        "truncate",
+        "rename"
+      ].includes(type)) {
+        throw new SqlValidationError("DDL is not allowed; only SELECT statements are accepted");
+      }
+      if (FORBIDDEN_AST_TYPES.has(type)) {
+        throw new SqlValidationError(`${type.toUpperCase()} is not allowed; only SELECT statements are accepted`);
+      }
+      throw new SqlValidationError(`Statement type "${type || "unknown"}" is not allowed; only SELECT statements are accepted`);
+    }
+    return {
+      tables: this.extractReferencedTables(sql)
+    };
+  }
+  /**
+  * Distinct base table names a statement touches — walking CTEs, subqueries,
+  * and joins. Backed by `node-sql-parser`'s `tableList`, which emits
+  * `mode::db::table` strings; the table name is the last segment.
+  */
+  extractReferencedTables(sql) {
+    const raw = this.parser.tableList(sql, {
+      database: "MySQL"
+    });
+    const tables = /* @__PURE__ */ new Set();
+    for (const entry of raw) {
+      const parts = entry.split("::");
+      const table = parts[parts.length - 1];
+      if (table && table !== "null") tables.add(table);
+    }
+    return Array.from(tables);
+  }
+};
+
+// src/table-access.ts
+var GroupTableAccessPolicy = class {
+  static {
+    __name(this, "GroupTableAccessPolicy");
+  }
+  roleGroups;
+  tablesByGroup;
+  constructor(config) {
+    this.roleGroups = config.roleGroups;
+    this.tablesByGroup = config.tablesByGroup;
+  }
+  canAccess(roles, table) {
+    const group = this.resolveGroup(table);
+    if (group === void 0) return false;
+    return roles.some((role) => this.roleGroups[role]?.includes(group) ?? false);
+  }
+  /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */
+  resolveGroup(table) {
+    for (const [group, patterns] of Object.entries(this.tablesByGroup)) {
+      for (const pattern of patterns) {
+        if (matchesPattern(table, pattern)) return group;
+      }
+    }
+    return void 0;
+  }
+};
+function matchesPattern(table, pattern) {
+  if (pattern.endsWith("*")) {
+    return table.startsWith(pattern.slice(0, -1));
+  }
+  return table === pattern;
+}
+__name(matchesPattern, "matchesPattern");
+
+// src/tenant-scope.ts
+import { Parser as Parser2 } from "node-sql-parser";
+var STRING_LITERAL_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "single_quote_string",
+  "double_quote_string"
+]);
+var TenantScopeRewriter = class {
+  static {
+    __name(this, "TenantScopeRewriter");
+  }
+  parser = new Parser2();
+  tenantColumn;
+  scopedTables;
+  constructor(config) {
+    this.tenantColumn = config.tenantColumn;
+    this.scopedTables = new Set(config.scopedTables);
+  }
+  /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */
+  rewrite(sql, tenantRef) {
+    if (tenantRef === void 0) return sql;
+    const parsed = this.parser.astify(sql, {
+      database: "MySQL"
+    });
+    const ast = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (ast.type !== "select") {
+      throw new Error("tenant scope: only SELECT is supported");
+    }
+    if (ast.with) {
+      throw new Error("tenant scope: WITH (CTE) is not supported in scoped mode \u2014 rewrite using JOINs/subqueries in FROM");
+    }
+    if (ast._next) {
+      throw new Error("tenant scope: UNION/INTERSECT/EXCEPT is not supported in scoped mode \u2014 run each branch as a separate query");
+    }
+    const fromEntries = ast.from ?? [];
+    for (const entry of fromEntries) {
+      if (!entry.table && entry.expr?.ast) {
+        throw new Error("tenant scope: subqueries in FROM are not supported in scoped mode");
+      }
+    }
+    const scopedFrom = fromEntries.filter((entry) => typeof entry.table === "string" && this.scopedTables.has(entry.table));
+    if (scopedFrom.length === 0) return sql;
+    const existing = this.collectTenantPredicates(ast.where);
+    for (const predicate of existing) {
+      if (predicate.value !== tenantRef) {
+        throw new Error("tenant scope: tenant mismatch \u2014 query targets a tenant other than the current session");
+      }
+    }
+    const coveredAliases = new Set(existing.map((predicate) => predicate.tableAlias));
+    for (const entry of scopedFrom) {
+      const alias = entry.as ?? entry.table;
+      const isAmbiguous = scopedFrom.length > 1;
+      const covered = coveredAliases.has(alias) || !isAmbiguous && coveredAliases.has(null);
+      if (covered) continue;
+      ast.where = this.andCondition(ast.where, this.buildTenantEquality(isAmbiguous ? alias : null, tenantRef));
+    }
+    return this.parser.sqlify(ast, {
+      database: "MySQL"
+    });
+  }
+  collectTenantPredicates(where) {
+    if (!isBinaryExpr(where)) return [];
+    if (where.operator === "AND" || where.operator === "OR") {
+      return [
+        ...this.collectTenantPredicates(where.left),
+        ...this.collectTenantPredicates(where.right)
+      ];
+    }
+    if (where.operator !== "=") return [];
+    const lhs = where.left;
+    const rhs = where.right;
+    if (!isColumnRef(lhs) || lhs.column !== this.tenantColumn) return [];
+    if (!isStringLiteral(rhs)) return [];
+    return [
+      {
+        tableAlias: lhs.table ?? null,
+        value: rhs.value
+      }
+    ];
+  }
+  buildTenantEquality(tableAlias, tenantRef) {
+    return {
+      type: "binary_expr",
+      operator: "=",
+      left: {
+        type: "column_ref",
+        table: tableAlias,
+        column: this.tenantColumn
+      },
+      right: {
+        type: "single_quote_string",
+        value: tenantRef
+      }
+    };
+  }
+  andCondition(existing, added) {
+    if (existing == null) return added;
+    return {
+      type: "binary_expr",
+      operator: "AND",
+      left: existing,
+      right: added
+    };
+  }
+};
+function isBinaryExpr(value) {
+  return typeof value === "object" && value !== null && value.type === "binary_expr";
+}
+__name(isBinaryExpr, "isBinaryExpr");
+function isColumnRef(value) {
+  return typeof value === "object" && value !== null && value.type === "column_ref";
+}
+__name(isColumnRef, "isColumnRef");
+function isStringLiteral(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string" && STRING_LITERAL_TYPES.has(value.type) && typeof value.value === "string";
+}
+__name(isStringLiteral, "isStringLiteral");
+
+// src/limit.ts
+import { Parser as Parser3 } from "node-sql-parser";
+var parser = new Parser3();
+function injectLimit(sql, max) {
+  const trimmed = sql.trim().replace(/;\s*$/, "");
+  if (hasLimit(trimmed)) return trimmed;
+  return `SELECT * FROM (${trimmed}) AS subq LIMIT ${max}`;
+}
+__name(injectLimit, "injectLimit");
+function hasLimit(sql) {
+  try {
+    const parsed = parser.astify(sql, {
+      database: "MySQL"
+    });
+    const statement = Array.isArray(parsed) ? parsed[0] : parsed;
+    const limit = statement?.limit;
+    return Boolean(limit && Array.isArray(limit.value) && limit.value.length > 0);
+  } catch {
+    return false;
+  }
+}
+__name(hasLimit, "hasLimit");
+
+// src/execute-sql.tool.ts
+import { z } from "zod";
+var DEFAULT_MAX_ROWS = 100;
+var MAX_RESULT_BYTES = 256 * 1024;
+var inputSchema = z.object({
+  sql: z.string().min(1).describe("A single read-only MySQL SELECT statement")
+});
+var DESCRIPTION = "Execute a single read-only MySQL SELECT statement. Use this to answer questions about real data. Only SELECT is allowed (no INSERT/UPDATE/DELETE/DDL). Access is restricted to the tables your role is permitted to read, results are capped, and tenant-scoped tables are automatically constrained to your current tenant.";
+function createExecuteSqlTool(deps) {
+  const validator = deps.validator ?? new SqlValidator();
+  const maxRows = deps.maxRows ?? DEFAULT_MAX_ROWS;
+  const spec = {
+    name: "executeSql",
+    kind: "read",
+    description: DESCRIPTION,
+    inputSchema
+  };
+  const handler = {
+    async execute(input, ctx) {
+      const { tables } = validator.validate(input.sql);
+      const roles = ctx.actor.roles ?? [];
+      const forbidden = tables.filter((table) => !deps.tableAccess.canAccess(roles, table));
+      if (forbidden.length > 0) {
+        const formatted = forbidden.map((table) => `\`${table}\``).join(", ");
+        const rolesLabel = roles.length > 0 ? roles.join(", ") : "none";
+        throw new Error(`Your roles (${rolesLabel}) are not allowed to query ${formatted}.`);
+      }
+      let sql = input.sql;
+      if (deps.tenantScope) {
+        sql = deps.tenantScope.rewrite(sql, ctx.actor.tenantRef);
+      }
+      sql = injectLimit(sql, maxRows);
+      const rows = await deps.runner.run(sql);
+      return buildResult(rows, sql);
+    }
+  };
+  return {
+    spec,
+    handler
+  };
+}
+__name(createExecuteSqlTool, "createExecuteSqlTool");
+function buildResult(rows, sql) {
+  const rowCount = rows.length;
+  if (byteLength(rows) <= MAX_RESULT_BYTES) {
+    return {
+      rows,
+      rowCount,
+      sql
+    };
+  }
+  const kept = [];
+  let size = 2;
+  for (const row of rows) {
+    const rowSize = byteLength(row) + 1;
+    if (size + rowSize > MAX_RESULT_BYTES) break;
+    kept.push(row);
+    size += rowSize;
+  }
+  return {
+    rows: kept,
+    rowCount,
+    sql,
+    truncated: true
+  };
+}
+__name(buildResult, "buildResult");
+function byteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+}
+__name(byteLength, "byteLength");
+export {
+  GroupTableAccessPolicy,
+  SqlValidationError,
+  SqlValidator,
+  TenantScopeRewriter,
+  createExecuteSqlTool,
+  injectLimit
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sql-validator.ts","../src/table-access.ts","../src/tenant-scope.ts","../src/limit.ts","../src/execute-sql.tool.ts"],"sourcesContent":["import { Parser } from 'node-sql-parser';\n\n/**\n * Thrown when a statement is not a single, read-only SELECT — i.e. it is an\n * INSERT/UPDATE/DELETE, DDL, a CALL, a multi-statement string, or it fails to\n * parse. The handler surfaces `.message` to the model so it can re-plan.\n */\nexport class SqlValidationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SqlValidationError';\n  }\n}\n\n/** Statement types that are categorically rejected (anything that writes or runs code). */\nconst FORBIDDEN_AST_TYPES = new Set([\n  'insert',\n  'update',\n  'delete',\n  'replace',\n  'create',\n  'drop',\n  'alter',\n  'truncate',\n  'rename',\n  'load_data',\n  'lock',\n  'unlock',\n  'set',\n  'call',\n  'handler',\n  'use',\n  'grant',\n  'revoke',\n]);\n\nexport interface SqlValidationResult {\n  /** Every base table the statement references (CTEs, joins, subqueries walked). */\n  tables: string[];\n}\n\n/**\n * Parses SQL (MySQL dialect) and asserts it is a single SELECT, returning the\n * set of tables it touches. Domain-agnostic: it knows nothing about which\n * tables a caller may read — that is the `TableAccessPolicy`'s job.\n */\nexport class SqlValidator {\n  private readonly parser = new Parser();\n\n  /**\n   * Throws `SqlValidationError` unless `sql` is exactly one SELECT statement.\n   * On success returns the distinct base table names referenced.\n   */\n  validate(sql: string): SqlValidationResult {\n    let parsed: unknown;\n    try {\n      parsed = this.parser.astify(sql, { database: 'MySQL' });\n    } catch (err) {\n      throw new SqlValidationError(`Parse error: ${(err as Error).message}`);\n    }\n\n    const statements = Array.isArray(parsed) ? parsed : [parsed];\n    if (statements.length !== 1) {\n      throw new SqlValidationError('Only a single statement is allowed');\n    }\n\n    const statement = statements[0] as { type?: string } | undefined;\n    const type = (statement?.type ?? '').toLowerCase();\n\n    if (type !== 'select') {\n      if (['create', 'drop', 'alter', 'truncate', 'rename'].includes(type)) {\n        throw new SqlValidationError('DDL is not allowed; only SELECT statements are accepted');\n      }\n      if (FORBIDDEN_AST_TYPES.has(type)) {\n        throw new SqlValidationError(\n          `${type.toUpperCase()} is not allowed; only SELECT statements are accepted`,\n        );\n      }\n      throw new SqlValidationError(\n        `Statement type \"${type || 'unknown'}\" is not allowed; only SELECT statements are accepted`,\n      );\n    }\n\n    return { tables: this.extractReferencedTables(sql) };\n  }\n\n  /**\n   * Distinct base table names a statement touches — walking CTEs, subqueries,\n   * and joins. Backed by `node-sql-parser`'s `tableList`, which emits\n   * `mode::db::table` strings; the table name is the last segment.\n   */\n  private extractReferencedTables(sql: string): string[] {\n    const raw = this.parser.tableList(sql, { database: 'MySQL' });\n    const tables = new Set<string>();\n    for (const entry of raw) {\n      const parts = entry.split('::');\n      const table = parts[parts.length - 1];\n      if (table && table !== 'null') tables.add(table);\n    }\n    return Array.from(tables);\n  }\n}\n","/**\n * Decides whether a role may read a given table at all. This is the coarse,\n * table-level gate; per-row scoping (see `TenantScopeRewriter`) is a separate\n * layer applied at query time.\n *\n * Domain-agnostic: the host app supplies the role→group and group→table maps.\n */\nexport interface TableAccessPolicy {\n  /** True iff any of the caller's `roles` is permitted to read `table`. Fail-closed by contract. */\n  canAccess(roles: readonly string[], table: string): boolean;\n}\n\n/** Inputs for {@link GroupTableAccessPolicy}: roles map to groups, groups to tables. */\nexport interface GroupTableAccessConfig {\n  /** Role name → the table groups that role may read. */\n  roleGroups: Record<string, string[]>;\n  /**\n   * Group name → the tables in that group. Entries are exact table names or\n   * `prefix_*` patterns (e.g. `pribuy_*`).\n   */\n  tablesByGroup: Record<string, string[]>;\n}\n\n/**\n * Two-layer, data-driven table allowlist:\n *\n *   1. Every table is classified into a group (`tablesByGroup`).\n *   2. Every role lists the groups it can read (`roleGroups`).\n *\n * `canAccess(roles, table)` is then \"is the table's group in ANY of the roles'\n * group lists?\". **Fail-closed:** an unclassified table, unknown roles, or an\n * empty role set is denied — a forgotten table never accidentally leaks.\n */\nexport class GroupTableAccessPolicy implements TableAccessPolicy {\n  private readonly roleGroups: Record<string, string[]>;\n  private readonly tablesByGroup: Record<string, string[]>;\n\n  constructor(config: GroupTableAccessConfig) {\n    this.roleGroups = config.roleGroups;\n    this.tablesByGroup = config.tablesByGroup;\n  }\n\n  canAccess(roles: readonly string[], table: string): boolean {\n    const group = this.resolveGroup(table);\n    if (group === undefined) return false;\n\n    return roles.some((role) => this.roleGroups[role]?.includes(group) ?? false);\n  }\n\n  /** Resolve a table to its group, or `undefined` if unclassified (fail-closed). */\n  private resolveGroup(table: string): string | undefined {\n    for (const [group, patterns] of Object.entries(this.tablesByGroup)) {\n      for (const pattern of patterns) {\n        if (matchesPattern(table, pattern)) return group;\n      }\n    }\n    return undefined;\n  }\n}\n\nfunction matchesPattern(table: string, pattern: string): boolean {\n  if (pattern.endsWith('*')) {\n    return table.startsWith(pattern.slice(0, -1));\n  }\n  return table === pattern;\n}\n","import type { AST } from 'node-sql-parser';\nimport { Parser } from 'node-sql-parser';\n\n/** Configuration for {@link TenantScopeRewriter}. */\nexport interface TenantScopeConfig {\n  /** The column that carries the tenant key on every scoped table (e.g. `base_id`, `org_id`). */\n  tenantColumn: string;\n  /** Tables that must be constrained to the caller's tenant when referenced. */\n  scopedTables: string[];\n}\n\ninterface FromEntry {\n  table?: string;\n  as?: string | null;\n  join?: string;\n  expr?: { ast?: unknown };\n}\n\ninterface SelectAst {\n  type: string;\n  with?: unknown;\n  from?: FromEntry[];\n  where?: unknown;\n  _next?: unknown;\n}\n\ninterface BinaryExpr {\n  type: 'binary_expr';\n  operator: string;\n  left: unknown;\n  right: unknown;\n}\n\ninterface ColumnRef {\n  type: 'column_ref';\n  table: string | null;\n  column: string;\n}\n\ninterface ExtractedPredicate {\n  tableAlias: string | null;\n  value: string;\n}\n\nconst STRING_LITERAL_TYPES = new Set(['string', 'single_quote_string', 'double_quote_string']);\n\n/**\n * Rewrites a SELECT so every reference to a scoped table is constrained to a\n * single tenant: `<tenantColumn> = '<tenantRef>'` is AND-ed into the WHERE for\n * each scoped table in the FROM. An existing predicate for a different tenant\n * is rejected (no cross-tenant reads). `tenantRef === undefined` is the\n * privileged path and passes the SQL through unchanged.\n *\n * Scoped mode rejects CTEs, UNION/INTERSECT/EXCEPT, and subqueries in FROM:\n * those make it impossible to statically guarantee every tenant-bearing source\n * is constrained, so we fail closed and ask the caller to rephrase.\n */\nexport class TenantScopeRewriter {\n  private readonly parser = new Parser();\n  private readonly tenantColumn: string;\n  private readonly scopedTables: Set<string>;\n\n  constructor(config: TenantScopeConfig) {\n    this.tenantColumn = config.tenantColumn;\n    this.scopedTables = new Set(config.scopedTables);\n  }\n\n  /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Undefined → pass through. */\n  rewrite(sql: string, tenantRef: string | undefined): string {\n    if (tenantRef === undefined) return sql;\n\n    const parsed = this.parser.astify(sql, { database: 'MySQL' });\n    const ast = (Array.isArray(parsed) ? parsed[0] : parsed) as SelectAst;\n\n    if (ast.type !== 'select') {\n      throw new Error('tenant scope: only SELECT is supported');\n    }\n    if (ast.with) {\n      throw new Error(\n        'tenant scope: WITH (CTE) is not supported in scoped mode — rewrite using JOINs/subqueries in FROM',\n      );\n    }\n    if (ast._next) {\n      throw new Error(\n        'tenant scope: UNION/INTERSECT/EXCEPT is not supported in scoped mode — run each branch as a separate query',\n      );\n    }\n\n    const fromEntries = ast.from ?? [];\n    for (const entry of fromEntries) {\n      if (!entry.table && entry.expr?.ast) {\n        throw new Error('tenant scope: subqueries in FROM are not supported in scoped mode');\n      }\n    }\n\n    const scopedFrom = fromEntries.filter(\n      (entry): entry is FromEntry & { table: string } =>\n        typeof entry.table === 'string' && this.scopedTables.has(entry.table),\n    );\n    if (scopedFrom.length === 0) return sql;\n\n    const existing = this.collectTenantPredicates(ast.where);\n    for (const predicate of existing) {\n      if (predicate.value !== tenantRef) {\n        throw new Error(\n          'tenant scope: tenant mismatch — query targets a tenant other than the current session',\n        );\n      }\n    }\n\n    const coveredAliases = new Set(existing.map((predicate) => predicate.tableAlias));\n    for (const entry of scopedFrom) {\n      const alias = entry.as ?? entry.table;\n      const isAmbiguous = scopedFrom.length > 1;\n      const covered = coveredAliases.has(alias) || (!isAmbiguous && coveredAliases.has(null));\n      if (covered) continue;\n      ast.where = this.andCondition(\n        ast.where,\n        this.buildTenantEquality(isAmbiguous ? alias : null, tenantRef),\n      );\n    }\n\n    return this.parser.sqlify(ast as unknown as AST, { database: 'MySQL' });\n  }\n\n  private collectTenantPredicates(where: unknown): ExtractedPredicate[] {\n    if (!isBinaryExpr(where)) return [];\n    if (where.operator === 'AND' || where.operator === 'OR') {\n      return [\n        ...this.collectTenantPredicates(where.left),\n        ...this.collectTenantPredicates(where.right),\n      ];\n    }\n    if (where.operator !== '=') return [];\n    const lhs = where.left;\n    const rhs = where.right;\n    if (!isColumnRef(lhs) || lhs.column !== this.tenantColumn) return [];\n    if (!isStringLiteral(rhs)) return [];\n    return [{ tableAlias: lhs.table ?? null, value: rhs.value }];\n  }\n\n  private buildTenantEquality(tableAlias: string | null, tenantRef: string): BinaryExpr {\n    return {\n      type: 'binary_expr',\n      operator: '=',\n      left: { type: 'column_ref', table: tableAlias, column: this.tenantColumn },\n      right: { type: 'single_quote_string', value: tenantRef },\n    };\n  }\n\n  private andCondition(existing: unknown, added: BinaryExpr): BinaryExpr {\n    if (existing == null) return added;\n    return {\n      type: 'binary_expr',\n      operator: 'AND',\n      left: existing,\n      right: added,\n    };\n  }\n}\n\nfunction isBinaryExpr(value: unknown): value is BinaryExpr {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { type?: unknown }).type === 'binary_expr'\n  );\n}\n\nfunction isColumnRef(value: unknown): value is ColumnRef {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { type?: unknown }).type === 'column_ref'\n  );\n}\n\nfunction isStringLiteral(value: unknown): value is { type: string; value: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { type?: unknown }).type === 'string' &&\n    STRING_LITERAL_TYPES.has((value as { type: string }).type) &&\n    typeof (value as { value?: unknown }).value === 'string'\n  );\n}\n","import { Parser } from 'node-sql-parser';\n\nconst parser = new Parser();\n\n/**\n * Ensures a SELECT returns at most `max` rows. If the statement already carries\n * a LIMIT it is returned unchanged; otherwise it is wrapped in a bounding\n * subquery (`SELECT * FROM (<sql>) AS subq LIMIT <max>`) so any ORDER BY /\n * GROUP BY / UNION inside `sql` is preserved.\n */\nexport function injectLimit(sql: string, max: number): string {\n  const trimmed = sql.trim().replace(/;\\s*$/, '');\n  if (hasLimit(trimmed)) return trimmed;\n  return `SELECT * FROM (${trimmed}) AS subq LIMIT ${max}`;\n}\n\nfunction hasLimit(sql: string): boolean {\n  try {\n    const parsed = parser.astify(sql, { database: 'MySQL' });\n    const statement = (Array.isArray(parsed) ? parsed[0] : parsed) as\n      | { limit?: { value?: unknown[] } | null }\n      | undefined;\n    const limit = statement?.limit;\n    return Boolean(limit && Array.isArray(limit.value) && limit.value.length > 0);\n  } catch {\n    // If we can't parse it here, fall back to wrapping — the validator already\n    // ran and accepted it, so wrapping is the safe choice.\n    return false;\n  }\n}\n","import type { AiToolCtx, ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport { z } from 'zod';\nimport { injectLimit } from './limit.js';\nimport { SqlValidator } from './sql-validator.js';\nimport type { TableAccessPolicy } from './table-access.js';\nimport type { TenantScopeRewriter } from './tenant-scope.js';\n\n/** App-supplied runner over a read-only connection pool. The package never opens a DB. */\nexport interface QueryRunner {\n  run(sql: string): Promise<Record<string, unknown>[]>;\n}\n\n/** Dependencies for {@link createExecuteSqlTool}. */\nexport interface ExecuteSqlDeps {\n  /** Runs the (already validated, scoped, and limited) SQL against the read-only pool. */\n  runner: QueryRunner;\n  /** Single-SELECT validator. Defaults to a fresh {@link SqlValidator}. */\n  validator?: SqlValidator;\n  /** Coarse table-level allowlist, checked for every referenced table. */\n  tableAccess: TableAccessPolicy;\n  /** Optional per-row tenant constraint applied before the query runs. */\n  tenantScope?: TenantScopeRewriter;\n  /** Row cap injected when the query has no LIMIT. Defaults to 100. */\n  maxRows?: number;\n}\n\nexport interface ExecuteSqlResult {\n  rows: Record<string, unknown>[];\n  rowCount: number;\n  sql: string;\n  truncated?: true;\n}\n\nconst DEFAULT_MAX_ROWS = 100;\n\n/** Serialized rows above this size are truncated so a single tool result can't blow the context. */\nconst MAX_RESULT_BYTES = 256 * 1024;\n\nconst inputSchema = z.object({\n  sql: z.string().min(1).describe('A single read-only MySQL SELECT statement'),\n});\n\ntype ExecuteSqlInput = z.infer<typeof inputSchema>;\n\nconst DESCRIPTION =\n  'Execute a single read-only MySQL SELECT statement. Use this to answer questions about real ' +\n  'data. Only SELECT is allowed (no INSERT/UPDATE/DELETE/DDL). Access is restricted to the ' +\n  'tables your role is permitted to read, results are capped, and tenant-scoped tables are ' +\n  'automatically constrained to your current tenant.';\n\n/**\n * Builds the governed `executeSql` read tool. The pipeline per call is:\n * validate (single SELECT) → assert table access for every referenced table →\n * tenant-scope rewrite (if configured) → inject LIMIT → run → return rows,\n * truncating the payload if it would exceed ~256KB.\n */\nexport function createExecuteSqlTool(deps: ExecuteSqlDeps): {\n  spec: ToolSpec;\n  handler: ToolHandler<ExecuteSqlInput>;\n} {\n  const validator = deps.validator ?? new SqlValidator();\n  const maxRows = deps.maxRows ?? DEFAULT_MAX_ROWS;\n\n  const spec: ToolSpec = {\n    name: 'executeSql',\n    kind: 'read',\n    description: DESCRIPTION,\n    inputSchema,\n  };\n\n  const handler: ToolHandler<ExecuteSqlInput> = {\n    async execute(input: ExecuteSqlInput, ctx: AiToolCtx): Promise<ExecuteSqlResult> {\n      const { tables } = validator.validate(input.sql);\n\n      const roles = ctx.actor.roles ?? [];\n      const forbidden = tables.filter((table) => !deps.tableAccess.canAccess(roles, table));\n      if (forbidden.length > 0) {\n        const formatted = forbidden.map((table) => `\\`${table}\\``).join(', ');\n        const rolesLabel = roles.length > 0 ? roles.join(', ') : 'none';\n        throw new Error(`Your roles (${rolesLabel}) are not allowed to query ${formatted}.`);\n      }\n\n      let sql = input.sql;\n      if (deps.tenantScope) {\n        sql = deps.tenantScope.rewrite(sql, ctx.actor.tenantRef);\n      }\n      sql = injectLimit(sql, maxRows);\n\n      const rows = await deps.runner.run(sql);\n      return buildResult(rows, sql);\n    },\n  };\n\n  return { spec, handler };\n}\n\nfunction buildResult(rows: Record<string, unknown>[], sql: string): ExecuteSqlResult {\n  const rowCount = rows.length;\n  if (byteLength(rows) <= MAX_RESULT_BYTES) {\n    return { rows, rowCount, sql };\n  }\n\n  // Keep prefix rows until the serialized payload would exceed the cap.\n  const kept: Record<string, unknown>[] = [];\n  let size = 2; // opening + closing bracket of the JSON array\n  for (const row of rows) {\n    const rowSize = byteLength(row) + 1; // +1 for the joining comma\n    if (size + rowSize > MAX_RESULT_BYTES) break;\n    kept.push(row);\n    size += rowSize;\n  }\n\n  return { rows: kept, rowCount, sql, truncated: true };\n}\n\nfunction byteLength(value: unknown): number {\n  return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');\n}\n"],"mappings":"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","names":["Parser","SqlValidationError","Error","message","name","FORBIDDEN_AST_TYPES","Set","SqlValidator","parser","Parser","validate","sql","parsed","astify","database","err","statements","Array","isArray","length","statement","type","toLowerCase","includes","has","toUpperCase","tables","extractReferencedTables","raw","tableList","entry","parts","split","table","add","from","GroupTableAccessPolicy","roleGroups","tablesByGroup","config","canAccess","roles","table","group","resolveGroup","undefined","some","role","includes","patterns","Object","entries","pattern","matchesPattern","endsWith","startsWith","slice","Parser","STRING_LITERAL_TYPES","Set","TenantScopeRewriter","parser","Parser","tenantColumn","scopedTables","config","rewrite","sql","tenantRef","undefined","parsed","astify","database","ast","Array","isArray","type","Error","with","_next","fromEntries","from","entry","table","expr","scopedFrom","filter","has","length","existing","collectTenantPredicates","where","predicate","value","coveredAliases","map","tableAlias","alias","as","isAmbiguous","covered","andCondition","buildTenantEquality","sqlify","isBinaryExpr","operator","left","right","lhs","rhs","isColumnRef","column","isStringLiteral","added","Parser","parser","Parser","injectLimit","sql","max","trimmed","trim","replace","hasLimit","parsed","astify","database","statement","Array","isArray","limit","Boolean","value","length","z","DEFAULT_MAX_ROWS","MAX_RESULT_BYTES","inputSchema","z","object","sql","string","min","describe","DESCRIPTION","createExecuteSqlTool","deps","validator","SqlValidator","maxRows","spec","name","kind","description","handler","execute","input","ctx","tables","validate","roles","actor","forbidden","filter","table","tableAccess","canAccess","length","formatted","map","join","rolesLabel","Error","tenantScope","rewrite","tenantRef","injectLimit","rows","runner","run","buildResult","rowCount","byteLength","kept","size","row","rowSize","push","truncated","value","Buffer","JSON","stringify"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dudousxd/nestjs-agent-data",
+  "version": "0.1.0",
+  "description": "nestjs-agent data — governed read-only SQL satellite (single-SELECT validation, fail-closed table access, tenant scoping)",
+  "license": "MIT",
+  "author": "Davide Carvalho",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "node-sql-parser": "5.4.0",
+    "zod": "3.25.76",
+    "@dudousxd/nestjs-agent-core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "8.3.5",
+    "typescript": "5.9.3",
+    "@dudousxd/nestjs-agent-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}