@adonis-agora/agent 0.1.0

package/dist/src/data/data-tool.d.ts

@@ -0,0 +1,64 @@
+import type { BrandedFunctionalTool } from '../ai-tool-ref.js';
+import type { LucidDatabaseLike } from '../stores/lucid.js';
+import { type GroupTableAccessConfig, type TableAccessPolicy } from './table-access.js';
+import { type TenantScopeConfig } from './tenant-scope.js';
+/** App-supplied runner over a read-only connection. The package never opens a DB itself. */
+export interface QueryRunner {
+    run(sql: string): Promise<Record<string, unknown>[]>;
+}
+/**
+ * Configuration for {@link dataTool} — the governed read-only SQL agent tool. Mirrors the reference
+ * `ExecuteSqlDeps`, adapted to the AdonisJS `defineConfig`/factory idiom. Supply the DB handle as a
+ * structural {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer) or a custom
+ * {@link QueryRunner}.
+ */
+export interface DataToolConfig {
+    /**
+     * Read-only Lucid DB handle (structural). Queries run through `db.rawQuery(sql)`. Point it at a
+     * read-only connection/replica. Provide this OR {@link DataToolConfig.runner}.
+     */
+    db?: LucidDatabaseLike;
+    /** Custom query runner. Overrides {@link DataToolConfig.db} when both are given. */
+    runner?: QueryRunner;
+    /**
+     * Coarse table-level allowlist checked for every referenced table. Pass a {@link TableAccessPolicy}
+     * instance, or a {@link GroupTableAccessConfig} to build the default {@link GroupTableAccessPolicy}.
+     * **Required** — there is no implicit allow-all (fail-closed).
+     */
+    tableAccess: TableAccessPolicy | GroupTableAccessConfig;
+    /** Optional per-row tenant constraint injected before the query runs. */
+    tenant?: TenantScopeConfig;
+    /** Row cap injected when the query has no LIMIT. Default 100. */
+    maxRows?: number;
+    /**
+     * Reject the query if the runner has not resolved within this many ms — a soft statement-timeout
+     * guard (the query may keep running server-side; the model gets a timeout error to re-plan). Off by
+     * default; pair with a DB-level statement timeout for a hard cap.
+     */
+    statementTimeoutMs?: number;
+    /** Tool name the model sees. Default `executeSql`. */
+    name?: string;
+    /** Roles allowed to invoke the tool (spec-level gate). Omit → config defaults (ADMIN-only). */
+    roles?: string[];
+    /** Authz ability checked by an ability-aware `RolesPolicy`. */
+    ability?: string;
+}
+export interface DataToolResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    sql: string;
+    truncated?: true;
+}
+/**
+ * Builds the governed `executeSql` read tool as a branded functional tool ({@link defineTool}) the agent
+ * registry auto-discovers. Register it in `config/agent.ts` (`defineConfig({ tools: [dataTool({ ... })] })`)
+ * or export it from an `app/agent_tools/` module.
+ *
+ * The pipeline per call (identical to the reference satellite) 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. `node-sql-parser` is imported lazily on the first
+ * call, so it stays an optional peer.
+ */
+export declare function dataTool(config: DataToolConfig): BrandedFunctionalTool;
+//# sourceMappingURL=data-tool.d.ts.map

package/dist/src/data/data-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-tool.d.ts","sourceRoot":"","sources":["../../../src/data/data-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,EACL,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,iBAAiB,EAAuB,MAAM,mBAAmB,CAAC;AAEhF,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,WAAW,EAAE,iBAAiB,GAAG,sBAAsB,CAAC;IACxD,yEAAyE;IACzE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AA4DD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,qBAAqB,CA0DtE"}

package/dist/src/data/data-tool.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { defineTool } from '../ai-tool-ref.js';
+import { injectLimit } from './limit.js';
+import { loadSqlParser } from './parser.js';
+import { SqlValidator } from './sql-validator.js';
+import { GroupTableAccessPolicy, } from './table-access.js';
+import { TenantScopeRewriter } from './tenant-scope.js';
+const DEFAULT_MAX_ROWS = 100;
+const DEFAULT_TOOL_NAME = 'executeSql';
+/** Serialized rows above this size are truncated so a single tool result can't blow the context. */
+const MAX_RESULT_BYTES = 256 * 1024;
+const inputSchema = z.object({
+    sql: z.string().min(1).describe('A single read-only MySQL SELECT statement'),
+});
+const 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 isTableAccessPolicy(value) {
+    return typeof value.canAccess === 'function';
+}
+/** Normalize whatever a Lucid `rawQuery` returns (SQLite array, PG `{rows}`, MySQL `[rows,fields]`). */
+function normalizeRows(raw) {
+    if (Array.isArray(raw)) {
+        // mysql2 returns `[rows, fields]`; the first element is itself the rows array.
+        if (raw.length > 0 && Array.isArray(raw[0])) {
+            return raw[0];
+        }
+        return raw;
+    }
+    if (raw !== null && typeof raw === 'object' && Array.isArray(raw.rows)) {
+        return raw.rows;
+    }
+    return [];
+}
+function withTimeout(promise, ms) {
+    if (ms === undefined)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Query exceeded the ${ms}ms statement timeout.`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Builds the governed `executeSql` read tool as a branded functional tool ({@link defineTool}) the agent
+ * registry auto-discovers. Register it in `config/agent.ts` (`defineConfig({ tools: [dataTool({ ... })] })`)
+ * or export it from an `app/agent_tools/` module.
+ *
+ * The pipeline per call (identical to the reference satellite) 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. `node-sql-parser` is imported lazily on the first
+ * call, so it stays an optional peer.
+ */
+export function dataTool(config) {
+    const maxRows = config.maxRows ?? DEFAULT_MAX_ROWS;
+    const tableAccess = isTableAccessPolicy(config.tableAccess)
+        ? config.tableAccess
+        : new GroupTableAccessPolicy(config.tableAccess);
+    const runner = resolveRunner(config);
+    // Lazily built once from the lazily-imported parser, then reused across calls.
+    let pipeline = null;
+    const getPipeline = () => {
+        if (pipeline === null) {
+            pipeline = loadSqlParser().then((parser) => ({
+                validator: new SqlValidator(parser),
+                ...(config.tenant !== undefined
+                    ? { tenantScope: new TenantScopeRewriter(config.tenant, parser) }
+                    : {}),
+            }));
+        }
+        return pipeline;
+    };
+    return defineTool({
+        name: config.name ?? DEFAULT_TOOL_NAME,
+        kind: 'read',
+        description: DESCRIPTION,
+        input: inputSchema,
+        ...(config.roles !== undefined ? { roles: config.roles } : {}),
+        ...(config.ability !== undefined ? { ability: config.ability } : {}),
+    }, async (input, ctx) => {
+        const { validator, tenantScope } = await getPipeline();
+        const { tables } = validator.validate(input.sql);
+        const roles = ctx.actor.roles ?? [];
+        const forbidden = tables.filter((table) => !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 (tenantScope) {
+            // CRITICAL: pass ctx.actor.tenantRef through UNTOUCHED. A strictly-`undefined` tenantRef is the
+            // privileged pass-through; a `null`/empty one must NOT be coerced to undefined (that would leak
+            // every tenant's rows), so never `?? undefined` here.
+            sql = tenantScope.rewrite(sql, ctx.actor.tenantRef);
+        }
+        const parser = await loadSqlParser();
+        sql = injectLimit(parser, sql, maxRows);
+        const rows = await withTimeout(runner.run(sql), config.statementTimeoutMs);
+        return buildResult(rows, sql);
+    });
+}
+function resolveRunner(config) {
+    if (config.runner !== undefined)
+        return config.runner;
+    const db = config.db;
+    if (db === undefined) {
+        throw new Error('dataTool: provide either `db` (a Lucid database handle) or a custom `runner`.');
+    }
+    return {
+        async run(sql) {
+            const raw = await db.rawQuery(sql);
+            return normalizeRows(raw);
+        },
+    };
+}
+function buildResult(rows, sql) {
+    const rowCount = rows.length;
+    if (byteLength(rows) <= MAX_RESULT_BYTES) {
+        return { rows, rowCount, sql };
+    }
+    // Keep prefix rows until the serialized payload would exceed the cap.
+    const kept = [];
+    let size = 2; // opening + closing bracket of the JSON array
+    for (const row of rows) {
+        const rowSize = byteLength(row) + 1; // +1 for the joining comma
+        if (size + rowSize > MAX_RESULT_BYTES)
+            break;
+        kept.push(row);
+        size += rowSize;
+    }
+    return { rows: kept, rowCount, sql, truncated: true };
+}
+function byteLength(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+}
+//# sourceMappingURL=data-tool.js.map

package/dist/src/data/data-tool.js.map

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

package/dist/src/data/index.d.ts

@@ -0,0 +1,7 @@
+export { loadSqlParser, type SqlParserLike } from './parser.js';
+export { SqlValidator, SqlValidationError, type SqlValidationResult } from './sql-validator.js';
+export { type TableAccessPolicy, type GroupTableAccessConfig, GroupTableAccessPolicy, } from './table-access.js';
+export { TenantScopeRewriter, type TenantScopeConfig } from './tenant-scope.js';
+export { injectLimit } from './limit.js';
+export { dataTool, type DataToolConfig, type DataToolResult, type QueryRunner, } from './data-tool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,QAAQ,EACR,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/src/data/index.js

@@ -0,0 +1,7 @@
+export { loadSqlParser } from './parser.js';
+export { SqlValidator, SqlValidationError } from './sql-validator.js';
+export { GroupTableAccessPolicy, } from './table-access.js';
+export { TenantScopeRewriter } from './tenant-scope.js';
+export { injectLimit } from './limit.js';
+export { dataTool, } from './data-tool.js';
+//# sourceMappingURL=index.js.map

package/dist/src/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAA4B,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAGL,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAA0B,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,QAAQ,GAIT,MAAM,gBAAgB,CAAC"}

package/dist/src/data/limit.d.ts

@@ -0,0 +1,12 @@
+import type { SqlParserLike } from './parser.js';
+/**
+ * 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.
+ *
+ * The `node-sql-parser` `Parser` is injected (see {@link loadSqlParser}) so this file never imports the
+ * optional peer at module load.
+ */
+export declare function injectLimit(parser: SqlParserLike, sql: string, max: number): string;
+//# sourceMappingURL=limit.d.ts.map

package/dist/src/data/limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.d.ts","sourceRoot":"","sources":["../../../src/data/limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInF"}

package/dist/src/data/limit.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ *
+ * The `node-sql-parser` `Parser` is injected (see {@link loadSqlParser}) so this file never imports the
+ * optional peer at module load.
+ */
+export function injectLimit(parser, sql, max) {
+    const trimmed = sql.trim().replace(/;\s*$/, '');
+    if (hasLimit(parser, trimmed))
+        return trimmed;
+    return `SELECT * FROM (${trimmed}) AS subq LIMIT ${max}`;
+}
+function hasLimit(parser, 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 {
+        // If we can't parse it here, fall back to wrapping — the validator already
+        // ran and accepted it, so wrapping is the safe choice.
+        return false;
+    }
+}
+//# sourceMappingURL=limit.js.map

package/dist/src/data/limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.js","sourceRoot":"","sources":["../../../src/data/limit.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,GAAW,EAAE,GAAW;IACzE,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC9C,OAAO,kBAAkB,OAAO,mBAAmB,GAAG,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,QAAQ,CAAC,MAAqB,EAAE,GAAW;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAEhD,CAAC;QACd,MAAM,KAAK,GAAG,SAAS,EAAE,KAAK,CAAC;QAC/B,OAAO,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,uDAAuD;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/src/data/parser.d.ts

@@ -0,0 +1,27 @@
+import type { AST } from 'node-sql-parser';
+/**
+ * The slice of `node-sql-parser`'s `Parser` the data satellite uses. Typed structurally so the guardrail
+ * files (`sql-validator`, `tenant-scope`, `limit`) never import the package at module load — they take a
+ * parser instance. `node-sql-parser` stays an **optional lazy peer**: only {@link loadSqlParser} imports it,
+ * and only when the `data` tool is actually built.
+ */
+export interface SqlParserLike {
+    astify(sql: string, opt?: {
+        database?: string;
+    }): AST | AST[];
+    sqlify(ast: AST, opt?: {
+        database?: string;
+    }): string;
+    tableList(sql: string, opt?: {
+        database?: string;
+    }): string[];
+}
+/** Re-export the parser AST type for the guardrail files (type-only — erased at compile). */
+export type { AST } from 'node-sql-parser';
+/**
+ * Lazily import `node-sql-parser` and build a single shared {@link SqlParserLike}. The import lives here
+ * (not at any module's top level) so the package is only pulled in when the `data` tool is configured —
+ * keeping `node-sql-parser` an optional peer, exactly like `@adonisjs/lucid` is for the stores.
+ */
+export declare function loadSqlParser(): Promise<SqlParserLike>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/src/data/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/data/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;IAC9D,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IACtD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,CAAC;CAC/D;AAED,6FAA6F;AAC7F,YAAY,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAI3C;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAgBtD"}

package/dist/src/data/parser.js

@@ -0,0 +1,18 @@
+let cached = null;
+/**
+ * Lazily import `node-sql-parser` and build a single shared {@link SqlParserLike}. The import lives here
+ * (not at any module's top level) so the package is only pulled in when the `data` tool is configured —
+ * keeping `node-sql-parser` an optional peer, exactly like `@adonisjs/lucid` is for the stores.
+ */
+export function loadSqlParser() {
+    if (cached === null) {
+        cached = import('node-sql-parser').then((mod) => {
+            // `node-sql-parser` is CJS: under Node ESM the named `Parser` export isn't surfaced, so reach it
+            // through the interop default. Fall back to a real named export for bundlers that do surface it.
+            const ParserCtor = mod.default?.Parser ?? mod.Parser;
+            return new ParserCtor();
+        });
+    }
+    return cached;
+}
+//# sourceMappingURL=parser.js.map

package/dist/src/data/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/data/parser.ts"],"names":[],"mappings":"AAiBA,IAAI,MAAM,GAAkC,IAAI,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;YAC9C,iGAAiG;YACjG,iGAAiG;YACjG,MAAM,UAAU,GAEZ,GAID,CAAC,OAAO,EAAE,MAAM,IAAK,GAAsD,CAAC,MAAM,CAAC;YACtF,OAAO,IAAI,UAAU,EAA8B,CAAC;QACtD,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/data/sql-validator.d.ts

@@ -0,0 +1,37 @@
+import type { SqlParserLike } from './parser.js';
+/**
+ * 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.
+ */
+export declare class SqlValidationError extends Error {
+    constructor(message: string);
+}
+export 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.
+ *
+ * The `node-sql-parser` `Parser` is injected (see {@link loadSqlParser}) so this file never imports the
+ * optional peer at module load.
+ */
+export declare class SqlValidator {
+    private readonly parser;
+    constructor(parser: SqlParserLike);
+    /**
+     * 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;
+}
+//# sourceMappingURL=sql-validator.d.ts.map

package/dist/src/data/sql-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-validator.d.ts","sourceRoot":"","sources":["../../../src/data/sql-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAwBD,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB;IAiC1C;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAUhC"}

package/dist/src/data/sql-validator.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+export class SqlValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SqlValidationError';
+    }
+}
+/** Statement types that are categorically rejected (anything that writes or runs code). */
+const FORBIDDEN_AST_TYPES = new Set([
+    'insert',
+    'update',
+    'delete',
+    'replace',
+    'create',
+    'drop',
+    'alter',
+    'truncate',
+    'rename',
+    'load_data',
+    'lock',
+    'unlock',
+    'set',
+    'call',
+    'handler',
+    'use',
+    'grant',
+    'revoke',
+]);
+/**
+ * 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.
+ *
+ * The `node-sql-parser` `Parser` is injected (see {@link loadSqlParser}) so this file never imports the
+ * optional peer at module load.
+ */
+export class SqlValidator {
+    parser;
+    constructor(parser) {
+        this.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 = 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);
+    }
+}
+//# sourceMappingURL=sql-validator.js.map

package/dist/src/data/sql-validator.js.map

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

package/dist/src/data/table-access.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export 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. */
+export 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.
+ */
+export 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;
+}
+//# sourceMappingURL=table-access.d.ts.map

package/dist/src/data/table-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-access.d.ts","sourceRoot":"","sources":["../../../src/data/table-access.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,kGAAkG;IAClG,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7D;AAED,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;gBAE7C,MAAM,EAAE,sBAAsB;IAK1C,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAO3D,kFAAkF;IAClF,OAAO,CAAC,YAAY;CAQrB"}

package/dist/src/data/table-access.js

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export class GroupTableAccessPolicy {
+    roleGroups;
+    tablesByGroup;
+    constructor(config) {
+        this.roleGroups = config.roleGroups;
+        this.tablesByGroup = config.tablesByGroup;
+    }
+    canAccess(roles, table) {
+        const group = this.resolveGroup(table);
+        if (group === undefined)
+            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 undefined;
+    }
+}
+function matchesPattern(table, pattern) {
+    if (pattern.endsWith('*')) {
+        return table.startsWith(pattern.slice(0, -1));
+    }
+    return table === pattern;
+}
+//# sourceMappingURL=table-access.js.map

package/dist/src/data/table-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-access.js","sourceRoot":"","sources":["../../../src/data/table-access.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAsB;IAChB,UAAU,CAA2B;IACrC,aAAa,CAA2B;IAEzD,YAAY,MAA8B;QACxC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC5C,CAAC;IAED,SAAS,CAAC,KAAwB,EAAE,KAAa;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAEtC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC;IAC/E,CAAC;IAED,kFAAkF;IAC1E,YAAY,CAAC,KAAa;QAChC,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YACnE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC;oBAAE,OAAO,KAAK,CAAC;YACnD,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,OAAe;IACpD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,KAAK,OAAO,CAAC;AAC3B,CAAC"}

package/dist/src/data/tenant-scope.d.ts

@@ -0,0 +1,39 @@
+import type { SqlParserLike } from './parser.js';
+/** Configuration for {@link TenantScopeRewriter}. */
+export 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.
+ *
+ * CRITICAL: only a strictly `=== undefined` tenantRef is privileged. A `null`
+ * or empty-string tenantRef is NOT privileged — it flows into the rewrite and
+ * injects a predicate that matches nothing (fail-closed), so a missing tenant
+ * can never accidentally read every tenant's rows.
+ *
+ * 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.
+ *
+ * The `node-sql-parser` `Parser` is injected (see {@link loadSqlParser}) so this file never imports the
+ * optional peer at module load.
+ */
+export declare class TenantScopeRewriter {
+    private readonly parser;
+    private readonly tenantColumn;
+    private readonly scopedTables;
+    constructor(config: TenantScopeConfig, parser: SqlParserLike);
+    /** Rewrite `sql` to constrain scoped tables to `tenantRef`. Strictly-`undefined` → pass through. */
+    rewrite(sql: string, tenantRef: string | undefined): string;
+    private collectTenantPredicates;
+    private buildTenantEquality;
+    private andCondition;
+}
+//# sourceMappingURL=tenant-scope.d.ts.map

package/dist/src/data/tenant-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-scope.d.ts","sourceRoot":"","sources":["../../../src/data/tenant-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtD,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,+FAA+F;IAC/F,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAqCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAmB;IAM5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;gBAGzC,MAAM,EAAE,iBAAiB,EACR,MAAM,EAAE,aAAa;IAMxC,oGAAoG;IACpG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAyD3D,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,YAAY;CASrB"}