apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-07-07 11:02:11 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat: query_policy semantic-layer-only restricts agents to predefined semantic-layer measures (#334)

Browse source 
* feat(sl): add predefined_measures_only guard to semantic query planning

SemanticQuery gains a predefined_measures_only flag; the planner rejects
any measure resolved with Provenance.COMPOSED (runtime aggregate
expressions and query-time derivations) while predefined measures,
predefined derived chains, dimensions, filters, and segments pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(config): add per-connection query_policy to warehouse connections

query_policy: semantic-layer-only | read-only-sql (default) on the
warehouse connection schema, plus a policy module with the raw-SQL
guard, federated member restriction lookup, and the project-level
predicate used to gate sql_execution registration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(cli): enforce query_policy on raw SQL through one shared executor

ktx sql and the MCP sql_execution tool now share executeProjectRawSql
(resolve, policy check, read-only validation, execute), collapsing
their duplicated validate-then-execute paths. Restricted connections
are rejected before validation; federated raw SQL is rejected when any
member is restricted. sql_execution is not registered when every SQL
connection is restricted, and connection_list marks restricted
connections so agents route to sl_query. executeProjectReadOnlySql
stays generic for ktx-internal SQL (scan, ingest, SL-generated).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(sl): compile queries with predefined_measures_only from query_policy

compileLocalSlQuery injects the flag from the connection's query_policy,
never from caller input, covering both ktx sl query and the MCP
sl_query tool through the daemon compile path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: document query_policy semantic-layer-only

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sl): close semantic-layer-only bypasses via filters and federated hint

The predefined_measures_only guard only inspected query.measures, so a
composed aggregate written into `filters` slipped through _classify_filters
into a HAVING clause untouched — letting a restricted agent evaluate
arbitrary aggregates (e.g. threshold-probing `sum(x) BETWEEN a AND b`).
Reject filter clauses that compose an aggregate function; a HAVING that
compares a predefined measure by name (`orders.revenue > 100`) still works.

Also make the federated sl_query error policy-aware: when a member is
restricted, raw federated SQL is disabled too, so stop directing the agent
to `ktx sql -c _ktx_federated` / sql_execution (a guaranteed failure) and
point to per-connection semantic-layer queries instead.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Andrey Avtomonov <andreybavt@gmail.com>
This commit is contained in:
Luca Martial 2026-07-03 01:54:17 -07:00 • committed by GitHub
parent 66768fe009
commit a651b82e2f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
21 changed files with 887 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

61
packages/cli/src/context/connections/query-policy.ts Normal file
View file

@ -0,0 +1,61 @@
import { KtxQueryError } from '../../errors.js';
import type { KtxProjectConfig, KtxProjectConnectionConfig } from '../project/config.js';
import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './federation.js';
import { isSqlQueryableDriver } from './dialects.js';
export type KtxConnectionQueryPolicy = 'read-only-sql' | 'semantic-layer-only';
export function connectionQueryPolicy(
connection: KtxProjectConnectionConfig | undefined,
): KtxConnectionQueryPolicy {
return connection !== undefined && connection.query_policy === 'semantic-layer-only'
? 'semantic-layer-only'
: 'read-only-sql';
}
/** Member ids whose policy blocks raw SQL through the federated connection. */
export function restrictedFederatedMemberIds(config: KtxProjectConfig, projectDir: string): string[] {
const descriptor = deriveFederatedConnection(config.connections, projectDir);
if (!descriptor) {
return [];
}
return descriptor.members
.filter((member) => connectionQueryPolicy(member.connection) === 'semantic-layer-only')
.map((member) => member.connectionId);
}
export function assertRawSqlAllowed(config: KtxProjectConfig, projectDir: string, connectionId: string): void {
if (connectionId === FEDERATED_CONNECTION_ID) {
const restricted = restrictedFederatedMemberIds(config, projectDir);
if (restricted.length > 0) {
throw new KtxQueryError(
`Federated SQL execution is disabled: member connection(s) ${restricted
.map((id) => `"${id}"`)
.join(', ')} are restricted to semantic-layer queries (query_policy: semantic-layer-only in ktx.yaml).`,
);
}
return;
}
if (connectionQueryPolicy(config.connections[connectionId]) === 'semantic-layer-only') {
throw new KtxQueryError(
`Connection "${connectionId}" is restricted to semantic-layer queries (query_policy: semantic-layer-only in ktx.yaml); ` +
'raw SQL execution is disabled. Query it through the semantic layer with predefined measures instead ' +
'(the sl_query tool or `ktx sl query`).',
);
}
}
/**
* False only when the project has SQL-queryable connections and every one of
* them is restricted — then no raw-SQL surface can succeed and the
* sql_execution tool should not be offered at all.
*/
export function projectAllowsRawSql(config: KtxProjectConfig): boolean {
const sqlConnections = Object.values(config.connections).filter((connection) =>
isSqlQueryableDriver(connection.driver),
);
if (sqlConnections.length === 0) {
return true;
}
return sqlConnections.some((connection) => connectionQueryPolicy(connection) === 'read-only-sql');
}