@dudousxd/nestjs-agent-data 0.3.3 → 0.3.4

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/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@dudousxd/nestjs-agent-data",
-  "version": "0.3.3",
+  "version": "0.3.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",
+    "directory": "packages/data"
+  },
   "description": "nestjs-agent data — governed read-only SQL satellite (single-SELECT validation, fail-closed table access, tenant scoping)",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -26,12 +31,12 @@
   "dependencies": {
     "node-sql-parser": "5.4.0",
     "zod": "3.25.76",
-    "@dudousxd/nestjs-agent-core": "0.3.3"
+    "@dudousxd/nestjs-agent-core": "0.4.0"
   },
   "devDependencies": {
     "tsup": "8.3.5",
     "typescript": "5.9.3",
-    "@dudousxd/nestjs-agent-core": "0.3.3"
+    "@dudousxd/nestjs-agent-core": "0.4.0"
   },
   "scripts": {
     "build": "tsup",