fix(recovery): restore source removed by production documentation merge
This commit is contained in:
@@ -0,0 +1,362 @@
|
||||
/**
|
||||
* tests/analytics/analyst-sql-bypass-corpus.ts
|
||||
* =============================================
|
||||
* BI-P017 — the bypass attempts, in one place, so the SAME corpus can be run
|
||||
* twice: once against the guard (unit) and once against a LIVE ClickHouse with
|
||||
* the guard REMOVED (integration), where the grants and the view predicate
|
||||
* must refuse it anyway.
|
||||
*
|
||||
* Running it only against the guard would prove the guard, not the system.
|
||||
* This estate has repeatedly shipped guards that were never tested against a
|
||||
* real attempt: INF0's tenant-from-body hole was exploitable against LIVE
|
||||
* production, and ST0RE turned out to have FOUR cross-tenant paths, not the
|
||||
* one reported.
|
||||
*
|
||||
* The integration test asserts that with the guard removed the engine either
|
||||
* ERRORS or returns zero foreign rows — never that "the guard said no", which
|
||||
* is the assertion that would keep passing while the system was open.
|
||||
*
|
||||
* Session under test: tenant `t_alpha`, catalog `t_alpha_sql`, objects
|
||||
* `sales` and `events`. The targets are `t_beta_sql`, the shared base database
|
||||
* `opt_analytics`, and `system`.
|
||||
*/
|
||||
|
||||
export interface BypassAttempt {
|
||||
id: string;
|
||||
/** What the attacker is trying to do. */
|
||||
goal: string;
|
||||
sql: string;
|
||||
}
|
||||
|
||||
export const BYPASS_CORPUS: BypassAttempt[] = [
|
||||
// ── reach another tenant's catalog ──────────────────────────────────────
|
||||
{
|
||||
id: 'cross-catalog-direct',
|
||||
goal: "read the other tenant's catalog",
|
||||
sql: 'SELECT * FROM t_beta_sql.sales',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-union',
|
||||
goal: 'union in the other tenant',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales UNION ALL SELECT customer FROM t_beta_sql.sales',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-subquery',
|
||||
goal: 'subquery on the other tenant',
|
||||
sql: 'SELECT (SELECT count() FROM t_beta_sql.sales) AS n FROM t_alpha_sql.sales LIMIT 1',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-join',
|
||||
goal: 'join the other tenant',
|
||||
sql: 'SELECT a.customer FROM t_alpha_sql.sales a JOIN t_beta_sql.sales b ON a.customer = b.customer',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-cte',
|
||||
goal: 'hide the other tenant in a CTE',
|
||||
sql: 'WITH other AS (SELECT * FROM t_beta_sql.sales) SELECT count() AS n FROM other',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-quoted',
|
||||
goal: 'quote the identifier to dodge the scan',
|
||||
sql: 'SELECT * FROM "t_beta_sql"."sales"',
|
||||
},
|
||||
{
|
||||
id: 'cross-catalog-backtick',
|
||||
goal: 'backtick the identifier',
|
||||
sql: 'SELECT * FROM `t_beta_sql`.`sales`',
|
||||
},
|
||||
|
||||
// ── reach the unfiltered base table ─────────────────────────────────────
|
||||
{
|
||||
id: 'base-table-direct',
|
||||
goal: 'read the shared base table, which holds every tenant',
|
||||
sql: 'SELECT * FROM opt_analytics.opt_analytics_event',
|
||||
},
|
||||
{
|
||||
id: 'base-table-in-cte',
|
||||
goal: 'base table behind a CTE',
|
||||
sql: 'WITH raw AS (SELECT * FROM opt_analytics.opt_analytics_event) SELECT count() AS n FROM raw',
|
||||
},
|
||||
{
|
||||
id: 'base-table-union',
|
||||
goal: 'union the base table in',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales UNION ALL SELECT tenant_id FROM opt_analytics.opt_analytics_event',
|
||||
},
|
||||
|
||||
// ── system / metadata catalogs ──────────────────────────────────────────
|
||||
{
|
||||
id: 'system-tables',
|
||||
goal: 'enumerate every table on the server',
|
||||
sql: 'SELECT database, name FROM system.tables',
|
||||
},
|
||||
{ id: 'system-columns', goal: 'enumerate columns', sql: 'SELECT * FROM system.columns' },
|
||||
{ id: 'system-users', goal: 'enumerate users', sql: 'SELECT * FROM system.users' },
|
||||
{
|
||||
id: 'system-processes',
|
||||
goal: "read other tenants' running queries",
|
||||
sql: 'SELECT query FROM system.processes',
|
||||
},
|
||||
{
|
||||
id: 'system-query-log',
|
||||
goal: "read other tenants' statement text out of the log",
|
||||
sql: 'SELECT query FROM system.query_log',
|
||||
},
|
||||
{
|
||||
id: 'information-schema',
|
||||
goal: 'metadata via the ANSI schema',
|
||||
sql: 'SELECT * FROM information_schema.tables',
|
||||
},
|
||||
{ id: 'one-table', goal: 'the always-present one-row table', sql: 'SELECT * FROM system.one' },
|
||||
|
||||
// ── table functions: these need NO table privilege at all ───────────────
|
||||
{
|
||||
id: 'tf-url',
|
||||
goal: 'exfiltrate over HTTP',
|
||||
sql: "SELECT * FROM url('http://127.0.0.1:1/x', 'JSONEachRow', 'a String')",
|
||||
},
|
||||
{
|
||||
id: 'tf-file',
|
||||
goal: 'read the server filesystem',
|
||||
sql: "SELECT * FROM file('/etc/passwd', 'LineAsString', 'l String')",
|
||||
},
|
||||
{
|
||||
id: 'tf-s3',
|
||||
goal: 'read object storage directly',
|
||||
sql: "SELECT * FROM s3('http://minio/b/*', 'CSV', 'a String')",
|
||||
},
|
||||
{
|
||||
id: 'tf-remote',
|
||||
goal: 'query another ClickHouse server',
|
||||
sql: "SELECT * FROM remote('127.0.0.1:9000', 'opt_analytics', 'opt_analytics_event')",
|
||||
},
|
||||
{
|
||||
id: 'tf-mysql',
|
||||
goal: 'reach an external database',
|
||||
sql: "SELECT * FROM mysql('h:3306', 'db', 't', 'u', 'p')",
|
||||
},
|
||||
{ id: 'tf-executable', goal: 'run a program', sql: "SELECT * FROM executable('sh', 'TSV', 'a String')" },
|
||||
{
|
||||
id: 'tf-numbers',
|
||||
goal: 'a CPU bomb that touches no table',
|
||||
sql: 'SELECT count() FROM numbers_mt(100000000000)',
|
||||
},
|
||||
{ id: 'tf-generate', goal: 'unbounded synthetic scan', sql: "SELECT * FROM generateRandom('a String')" },
|
||||
{
|
||||
id: 'tf-merge',
|
||||
goal: 'merge() glob across a database',
|
||||
sql: "SELECT * FROM merge('opt_analytics', '.*')",
|
||||
},
|
||||
{
|
||||
id: 'tf-cluster',
|
||||
goal: 'fan out across the cluster',
|
||||
sql: "SELECT * FROM cluster('default', 'opt_analytics', 'opt_analytics_event')",
|
||||
},
|
||||
{
|
||||
id: 'tf-view',
|
||||
goal: 'wrap a subquery in view()',
|
||||
sql: 'SELECT * FROM view(SELECT * FROM opt_analytics.opt_analytics_event)',
|
||||
},
|
||||
{
|
||||
id: 'fn-dictget',
|
||||
goal: 'read a dictionary, bypassing table grants',
|
||||
sql: "SELECT dictGet('d', 'v', toUInt64(1)) AS x FROM t_alpha_sql.sales",
|
||||
},
|
||||
|
||||
// ── write / DDL / privilege escalation ──────────────────────────────────
|
||||
{
|
||||
id: 'stacked-drop',
|
||||
goal: 'stacked statement',
|
||||
sql: 'SELECT 1 FROM t_alpha_sql.sales; DROP TABLE opt_analytics.opt_analytics_event',
|
||||
},
|
||||
{ id: 'insert', goal: 'write', sql: "INSERT INTO t_alpha_sql.sales VALUES ('x')" },
|
||||
{
|
||||
id: 'insert-select',
|
||||
goal: 'write from a read',
|
||||
sql: 'INSERT INTO t_alpha_sql.sales SELECT * FROM t_alpha_sql.sales',
|
||||
},
|
||||
{ id: 'alter-delete', goal: 'mutate', sql: 'ALTER TABLE opt_analytics.opt_analytics_event DELETE WHERE 1' },
|
||||
{
|
||||
id: 'create-view-escape',
|
||||
goal: 'create an unfiltered view to read later',
|
||||
sql: 'CREATE VIEW t_alpha_sql.escape AS SELECT * FROM opt_analytics.opt_analytics_event',
|
||||
},
|
||||
{ id: 'grant-self', goal: 'grant itself more', sql: 'GRANT SELECT ON opt_analytics.* TO CURRENT_USER' },
|
||||
{ id: 'system-command', goal: 'operate the server', sql: 'SYSTEM RELOAD DICTIONARIES' },
|
||||
{ id: 'kill-query', goal: "kill another tenant's query", sql: 'KILL QUERY WHERE 1' },
|
||||
{ id: 'truncate', goal: 'destroy data', sql: 'TRUNCATE TABLE t_alpha_sql.sales' },
|
||||
{
|
||||
id: 'optimize',
|
||||
goal: 'trigger heavy background work',
|
||||
sql: 'OPTIMIZE TABLE opt_analytics.opt_analytics_event FINAL',
|
||||
},
|
||||
{
|
||||
id: 'outfile',
|
||||
goal: 'write to the filesystem',
|
||||
sql: "SELECT * FROM t_alpha_sql.sales INTO OUTFILE '/tmp/x.csv'",
|
||||
},
|
||||
|
||||
// ── lift the governance ceiling from inside the statement ───────────────
|
||||
{
|
||||
id: 'settings-raise-rows',
|
||||
goal: 'raise max_rows_to_read',
|
||||
sql: 'SELECT count() AS n FROM t_alpha_sql.sales SETTINGS max_rows_to_read = 0',
|
||||
},
|
||||
{
|
||||
id: 'settings-readonly-off',
|
||||
goal: 'turn readonly off',
|
||||
sql: 'SELECT 1 FROM t_alpha_sql.sales SETTINGS readonly = 0',
|
||||
},
|
||||
{ id: 'set-statement', goal: 'SET before the query', sql: 'SET max_execution_time = 0' },
|
||||
{
|
||||
id: 'format-override',
|
||||
goal: 'choose the wire format',
|
||||
sql: 'SELECT * FROM t_alpha_sql.sales FORMAT Native',
|
||||
},
|
||||
|
||||
// ── lexical evasion of the keyword scan ─────────────────────────────────
|
||||
{
|
||||
id: 'comment-split-name',
|
||||
goal: 'hide a catalog boundary behind a comment',
|
||||
sql: 'SELECT * FROM opt_analytics/**/.opt_analytics_event',
|
||||
},
|
||||
{
|
||||
id: 'comment-line-hide',
|
||||
goal: 'hide the tail after a -- comment',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales -- \nUNION ALL SELECT name FROM system.tables',
|
||||
},
|
||||
{
|
||||
id: 'comment-hash-hide',
|
||||
goal: 'hide the tail after a # comment',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales # \nUNION ALL SELECT name FROM system.tables',
|
||||
},
|
||||
{
|
||||
id: 'unterminated-comment',
|
||||
goal: 'run off the end of a comment',
|
||||
sql: 'SELECT * FROM t_alpha_sql.sales /* x',
|
||||
},
|
||||
{
|
||||
id: 'unterminated-string',
|
||||
goal: 'run off the end of a literal',
|
||||
sql: "SELECT * FROM t_alpha_sql.sales WHERE customer = 'x",
|
||||
},
|
||||
{
|
||||
id: 'unicode-homoglyph',
|
||||
// U+0430 CYRILLIC SMALL LETTER A in place of the ASCII "a".
|
||||
goal: 'cyrillic homoglyph inside the catalog name',
|
||||
sql: 'SELECT * FROM t_\u0430lpha_sql.sales',
|
||||
},
|
||||
{
|
||||
id: 'zero-width',
|
||||
// U+200B ZERO WIDTH SPACE inside "system".
|
||||
goal: 'zero-width space inside a reserved catalog name',
|
||||
sql: 'SELECT * FROM sys\u200btem.tables',
|
||||
},
|
||||
{
|
||||
id: 'nul-byte',
|
||||
goal: 'NUL truncation between two halves of a statement',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales \u0000 UNION ALL SELECT name FROM system.tables',
|
||||
},
|
||||
{ id: 'case-mixing', goal: 'mixed case keywords and names', sql: 'SeLeCt * FrOm SyStEm.TaBlEs' },
|
||||
{
|
||||
id: 'whitespace-newlines',
|
||||
goal: 'newlines and tabs between tokens',
|
||||
sql: 'SELECT\n\t*\nFROM\n\tsystem.tables',
|
||||
},
|
||||
{
|
||||
id: 'describe-subquery',
|
||||
goal: 'DESCRIBE a base table from inside a subquery, where the FROM-scan sees only a paren',
|
||||
sql: 'SELECT * FROM (DESCRIBE TABLE opt_analytics.opt_analytics_event)',
|
||||
},
|
||||
{
|
||||
id: 'desc-subquery-short',
|
||||
goal: 'the same, using the DESC abbreviation',
|
||||
sql: 'SELECT * FROM (DESC TABLE opt_analytics.opt_analytics_event)',
|
||||
},
|
||||
{
|
||||
id: 'current-user',
|
||||
goal: "identify the session's ClickHouse principal",
|
||||
sql: 'SELECT currentUser() AS u FROM t_alpha_sql.sales',
|
||||
},
|
||||
{ id: 'three-part-name', goal: 'a three-part name', sql: 'SELECT * FROM a.b.c' },
|
||||
{
|
||||
id: 'unqualified-table',
|
||||
goal: "unqualified name resolved by the connection's default database",
|
||||
sql: 'SELECT * FROM opt_analytics_event',
|
||||
},
|
||||
{
|
||||
id: 'cte-shadow',
|
||||
goal: 'shadow a legitimate name with a CTE while also reading the real base table',
|
||||
sql: 'WITH sales AS (SELECT 1 AS x) SELECT count() AS n FROM opt_analytics.opt_analytics_event',
|
||||
},
|
||||
{ id: 'no-from', goal: 'a statement that reads no table at all', sql: 'SELECT 1' },
|
||||
{
|
||||
id: 'object-not-granted',
|
||||
goal: 'an object in the right catalog that the session was not given',
|
||||
sql: 'SELECT * FROM t_alpha_sql.secret_ledger',
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Attempts the GUARD ADMITS — and which only layers 3 and 4 refuse.
|
||||
*
|
||||
* This list exists because the first run of the corpus found one, and hiding
|
||||
* it by quietly deleting the case would have been the dishonest fix. The guard
|
||||
* reasons about statement STRUCTURE; it does not know which columns a view
|
||||
* projects, and teaching it would mean giving it a schema cache that goes
|
||||
* stale — a hardcoded list, which is how api0's container job died this week.
|
||||
*
|
||||
* `SELECT tenant_id FROM t_alpha_sql.sales` is structurally a legitimate read
|
||||
* of an allowed object. It fails at the ENGINE, because the view does not
|
||||
* project `tenant_id` at all (tenant-catalog.ts refuses to build one that
|
||||
* does). The integration test asserts that engine-side refusal directly, so
|
||||
* this case is covered by evidence rather than by an assumption.
|
||||
*/
|
||||
export const GUARD_ADMITS_ENGINE_REFUSES: BypassAttempt[] = [
|
||||
{
|
||||
id: 'hidden-tenant-column',
|
||||
goal: 'select the tenant column the view does not project',
|
||||
sql: 'SELECT tenant_id FROM t_alpha_sql.sales',
|
||||
},
|
||||
{
|
||||
id: 'hidden-column-star-then-filter',
|
||||
goal: 'filter on a column the view does not expose',
|
||||
sql: "SELECT count() AS n FROM t_alpha_sql.sales WHERE tenant_id = 't_beta'",
|
||||
},
|
||||
];
|
||||
|
||||
/** Statements that MUST be admitted — a guard that refuses everything is useless. */
|
||||
export const LEGITIMATE_CORPUS: Array<{ id: string; sql: string }> = [
|
||||
{ id: 'simple', sql: 'SELECT customer, amount FROM t_alpha_sql.sales LIMIT 10' },
|
||||
{
|
||||
id: 'aggregate',
|
||||
sql: 'SELECT customer, sum(amount) AS total FROM t_alpha_sql.sales GROUP BY customer ORDER BY total DESC LIMIT 5',
|
||||
},
|
||||
{
|
||||
id: 'cte',
|
||||
sql:
|
||||
'WITH top AS (SELECT customer, sum(amount) AS total FROM t_alpha_sql.sales GROUP BY customer) ' +
|
||||
'SELECT customer, total FROM top ORDER BY total DESC LIMIT 3',
|
||||
},
|
||||
{
|
||||
id: 'self-join',
|
||||
sql: 'SELECT a.customer FROM t_alpha_sql.sales a JOIN t_alpha_sql.events b ON a.customer = b.customer LIMIT 10',
|
||||
},
|
||||
{
|
||||
id: 'literal-with-quotes',
|
||||
sql: "SELECT count() AS n FROM t_alpha_sql.sales WHERE customer = 'O''Brien'",
|
||||
},
|
||||
{
|
||||
id: 'literal-containing-sql-text',
|
||||
sql: "SELECT count() AS n FROM t_alpha_sql.sales WHERE customer = 'DROP TABLE system.tables'",
|
||||
},
|
||||
{ id: 'comment-then-query', sql: '-- daily revenue\nSELECT sum(amount) AS total FROM t_alpha_sql.sales' },
|
||||
{
|
||||
id: 'subquery',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales WHERE amount > (SELECT avg(amount) FROM t_alpha_sql.sales)',
|
||||
},
|
||||
{
|
||||
id: 'union-own-catalog',
|
||||
sql: 'SELECT customer FROM t_alpha_sql.sales UNION ALL SELECT customer FROM t_alpha_sql.events',
|
||||
},
|
||||
{ id: 'trailing-semicolon', sql: 'SELECT count() AS n FROM t_alpha_sql.sales;' },
|
||||
];
|
||||
@@ -0,0 +1,108 @@
|
||||
/**
|
||||
* tests/analytics/analyst-sql-evidence.test.ts
|
||||
* =============================================
|
||||
* BI-P017 — the test that does NOT skip.
|
||||
*
|
||||
* The live suite (tests/integration/analyst-sql-clickhouse.integration.test.ts)
|
||||
* only runs when `CLICKHOUSE_URL` is set. On a runner without ClickHouse it
|
||||
* contributes nothing, and a suite that contributes nothing while reporting
|
||||
* green is how l0re's 28 Postgres tests stayed silently skipped for months.
|
||||
*
|
||||
* So the live run WRITES its result to
|
||||
* `evidence/bi-p017/analyst-sql-live-bypass.json`, that file is committed, and
|
||||
* this test — which always runs — checks it against the corpus:
|
||||
*
|
||||
* * every attempt in the corpus must appear in the evidence, so adding an
|
||||
* attack without re-running the live suite BREAKS THE BUILD rather than
|
||||
* quietly going untested;
|
||||
* * zero attempts may have leaked;
|
||||
* * the legitimate statements must all have succeeded, so the evidence
|
||||
* cannot be a recording of a database that refuses everything;
|
||||
* * the counterfactual numbers must be present, so the evidence cannot be a
|
||||
* recording of an EMPTY database, where "no foreign row came back" is
|
||||
* true and meaningless.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { BYPASS_CORPUS, GUARD_ADMITS_ENGINE_REFUSES, LEGITIMATE_CORPUS } from './analyst-sql-bypass-corpus';
|
||||
|
||||
const EVIDENCE_PATH = path.join(process.cwd(), 'evidence/bi-p017/analyst-sql-live-bypass.json');
|
||||
|
||||
interface Evidence {
|
||||
clickhouse_version: string;
|
||||
recorded_at: string;
|
||||
base_table_rows_both_tenants: number;
|
||||
tenant_view_rows_alpha: number;
|
||||
attempts_total: number;
|
||||
attempts_that_leaked: number;
|
||||
legitimate_statements_that_succeeded: number;
|
||||
legitimate_statements_total: number;
|
||||
attempts: Array<{
|
||||
id: string;
|
||||
engine_http_status: number;
|
||||
engine_succeeded: boolean;
|
||||
leaked_foreign_tenant_row: boolean;
|
||||
leaked_ungranted_table_row: boolean;
|
||||
leaked_server_metadata: boolean;
|
||||
guard_verdict_for_reference: string;
|
||||
}>;
|
||||
legitimate: Array<{ id: string; ok: boolean; contains_beta_canary: boolean }>;
|
||||
}
|
||||
|
||||
describe('BI-P017 — the committed live evidence covers the current corpus', () => {
|
||||
it('the evidence file exists', () => {
|
||||
expect(
|
||||
fs.existsSync(EVIDENCE_PATH),
|
||||
'evidence/bi-p017/analyst-sql-live-bypass.json is missing — run the live suite with CLICKHOUSE_URL set',
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
const evidence: Evidence = fs.existsSync(EVIDENCE_PATH)
|
||||
? (JSON.parse(fs.readFileSync(EVIDENCE_PATH, 'utf8')) as Evidence)
|
||||
: ({ attempts: [], legitimate: [] } as unknown as Evidence);
|
||||
|
||||
it('was recorded against a real ClickHouse, named by version', () => {
|
||||
expect(evidence.clickhouse_version).toMatch(/^\d+\.\d+/);
|
||||
expect(Date.parse(evidence.recorded_at)).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it("records the counterfactual, so 'nothing leaked' is not a statement about an empty database", () => {
|
||||
expect(evidence.base_table_rows_both_tenants).toBe(100);
|
||||
expect(evidence.tenant_view_rows_alpha).toBe(50);
|
||||
});
|
||||
|
||||
it('covers EVERY attempt in the corpus — a new attack without a re-run fails here', () => {
|
||||
const recorded = new Set(evidence.attempts.map((a) => a.id));
|
||||
const missing = [...BYPASS_CORPUS, ...GUARD_ADMITS_ENGINE_REFUSES]
|
||||
.map((a) => a.id)
|
||||
.filter((id) => !recorded.has(id));
|
||||
expect(missing, `attempts never run against a live engine: ${missing.join(', ')}`).toEqual([]);
|
||||
expect(evidence.attempts_total).toBe(BYPASS_CORPUS.length + GUARD_ADMITS_ENGINE_REFUSES.length);
|
||||
});
|
||||
|
||||
it('no attempt leaked a foreign-tenant row, an ungranted row, or a foreign object name', () => {
|
||||
const leaked = evidence.attempts.filter(
|
||||
(a) => a.leaked_foreign_tenant_row || a.leaked_ungranted_table_row || a.leaked_server_metadata,
|
||||
);
|
||||
expect(leaked.map((a) => a.id)).toEqual([]);
|
||||
expect(evidence.attempts_that_leaked).toBe(0);
|
||||
});
|
||||
|
||||
it('records which attempts the ENGINE alone stopped, with the guard removed', () => {
|
||||
// The interesting number: attempts that the guard would have admitted and
|
||||
// the engine refused anyway. If it were zero, the layered claim would rest
|
||||
// entirely on the guard.
|
||||
const engineOnly = evidence.attempts.filter((a) => a.guard_verdict_for_reference === 'admitted');
|
||||
expect(engineOnly.length).toBeGreaterThan(0);
|
||||
for (const a of engineOnly) {
|
||||
expect(a.engine_succeeded, `${a.id} was admitted by the guard AND succeeded at the engine`).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it('legitimate analyst work succeeded — the evidence is not a recording of a database that refuses everything', () => {
|
||||
expect(evidence.legitimate_statements_total).toBe(LEGITIMATE_CORPUS.length);
|
||||
expect(evidence.legitimate_statements_that_succeeded).toBe(LEGITIMATE_CORPUS.length);
|
||||
expect(evidence.legitimate.every((l) => l.contains_beta_canary === false)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,380 @@
|
||||
/**
|
||||
* tests/analytics/analyst-sql-guard.test.ts
|
||||
* ==========================================
|
||||
* BI-P017 — layer 2 (statement admission) against the bypass corpus.
|
||||
*
|
||||
* BI-P017's DoD: "INSERT, UPDATE, DROP, unsafe functions and unauthorized
|
||||
* catalogs fail." That is the floor. This file tests the floor and then keeps
|
||||
* going, because the interesting attacks are not `DROP TABLE` — they are
|
||||
* `url()`, `merge()`, a quoted identifier, a homoglyph, and a comment placed
|
||||
* where the guard and the engine might disagree about where the query ends.
|
||||
*
|
||||
* What this file does NOT prove: that the SYSTEM is safe. It proves the guard
|
||||
* refuses these statements. The system claim is
|
||||
* tests/integration/analyst-sql-clickhouse.integration.test.ts, which runs the
|
||||
* same corpus against a live ClickHouse with this layer REMOVED.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
guardAnalystStatement,
|
||||
stripSqlText,
|
||||
type StatementGuardOptions,
|
||||
} from '@/src/analytics/sql/statement-guard';
|
||||
import {
|
||||
AnalyticsSQLSession,
|
||||
ANALYST_SQL_ROLE,
|
||||
type AnalystStatementRecord,
|
||||
type ReadOnlySqlEndpoint,
|
||||
} from '@/src/analytics/sql/analyst-sql-session';
|
||||
import { tenantSqlCatalogDdl, tenantSqlUserDdl } from '@/src/analytics/sql/tenant-catalog';
|
||||
import { BYPASS_CORPUS, GUARD_ADMITS_ENGINE_REFUSES, LEGITIMATE_CORPUS } from './analyst-sql-bypass-corpus';
|
||||
|
||||
const OPTS: StatementGuardOptions = {
|
||||
allowedCatalog: 't_alpha_sql',
|
||||
allowedObjects: ['sales', 'events'],
|
||||
};
|
||||
|
||||
describe('BI-P017 layer 2 — the bypass corpus is refused', () => {
|
||||
it('covers every attack family the DoD names, and more', () => {
|
||||
// A corpus that shrank silently would make this suite pass by testing
|
||||
// nothing. Pin the size and the presence of the named families.
|
||||
expect(BYPASS_CORPUS.length).toBeGreaterThanOrEqual(55);
|
||||
const ids = new Set(BYPASS_CORPUS.map((a) => a.id));
|
||||
for (const required of [
|
||||
'insert',
|
||||
'alter-delete',
|
||||
'create-view-escape',
|
||||
'tf-url',
|
||||
'system-tables',
|
||||
'cross-catalog-direct',
|
||||
]) {
|
||||
expect(ids.has(required)).toBe(true);
|
||||
}
|
||||
expect(new Set(BYPASS_CORPUS.map((a) => a.sql)).size).toBe(BYPASS_CORPUS.length);
|
||||
});
|
||||
|
||||
it.each(BYPASS_CORPUS.map((a) => [a.id, a.goal, a.sql] as const))('refuses %s (%s)', (_id, _goal, sql) => {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
guardAnalystStatement(sql, OPTS);
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect(thrown, 'statement was ADMITTED — this is a bypass').toBeInstanceOf(SiaxError);
|
||||
const err = thrown as SiaxError;
|
||||
expect(['AUTHORIZATION_DENIED', 'INVALID_REQUEST']).toContain(err.code);
|
||||
// A refusal with an empty reason is unreviewable.
|
||||
expect(err.message.length).toBeGreaterThan(20);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P017 layer 2 — what the guard honestly does NOT catch', () => {
|
||||
// Recorded, not hidden. The guard admits these; the engine refuses them
|
||||
// because the view does not project the column. The claim is proven in
|
||||
// tests/integration/analyst-sql-clickhouse.integration.test.ts, not here.
|
||||
it.each(GUARD_ADMITS_ENGINE_REFUSES.map((a) => [a.id, a.sql] as const))(
|
||||
'the guard admits %s — layers 3/4 are what refuse it',
|
||||
(_id, sql) => {
|
||||
expect(() => guardAnalystStatement(sql, OPTS)).not.toThrow();
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe('BI-P017 layer 2 — legitimate analyst work is admitted', () => {
|
||||
it.each(LEGITIMATE_CORPUS.map((a) => [a.id, a.sql] as const))('admits %s', (_id, sql) => {
|
||||
const guarded = guardAnalystStatement(sql, OPTS);
|
||||
expect(guarded.referencedObjects.length).toBeGreaterThan(0);
|
||||
for (const obj of guarded.referencedObjects) {
|
||||
expect(obj.startsWith('t_alpha_sql.')).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it('a guard that refused everything would fail this file', () => {
|
||||
// Stated explicitly because "all tests pass" is compatible with a guard
|
||||
// that throws unconditionally, and that guard would be useless.
|
||||
expect(LEGITIMATE_CORPUS.length).toBeGreaterThanOrEqual(10);
|
||||
});
|
||||
});
|
||||
|
||||
describe("BI-P017 — literal and comment handling matches ClickHouse's lexer", () => {
|
||||
it('does not see keywords that are inside a string literal', () => {
|
||||
const g = guardAnalystStatement(
|
||||
"SELECT count() AS n FROM t_alpha_sql.sales WHERE customer = 'DROP TABLE system.tables'",
|
||||
OPTS,
|
||||
);
|
||||
expect(g.stripped).not.toContain('DROP');
|
||||
expect(g.stripped).not.toContain('system');
|
||||
});
|
||||
|
||||
it('masks literals in the normalized form so statement history is not a data dump', () => {
|
||||
const g = guardAnalystStatement(
|
||||
"SELECT customer FROM t_alpha_sql.sales WHERE customer = 'Anna Andersson, 19850101-1234'",
|
||||
OPTS,
|
||||
);
|
||||
expect(g.normalized).not.toContain('Andersson');
|
||||
expect(g.normalized).toContain('?');
|
||||
expect(g.raw).toContain('Andersson'); // the raw form is retained deliberately
|
||||
});
|
||||
|
||||
it('handles doubled and backslash-escaped quotes without losing the statement end', () => {
|
||||
expect(stripSqlText("SELECT 'a''b'").stripped).toBe("SELECT ''");
|
||||
expect(stripSqlText("SELECT 'a\\'b'").stripped).toBe("SELECT ''");
|
||||
// The classic: an escaped quote that a naive stripper would treat as the
|
||||
// close, leaving `; DROP …` outside a literal in the guard's view but
|
||||
// inside one in the engine's. Both must agree it stays inside.
|
||||
expect(stripSqlText("SELECT 'a\\'; DROP TABLE x; --'").stripped).toBe("SELECT ''");
|
||||
});
|
||||
|
||||
it('refuses rather than guesses when a literal or comment never ends', () => {
|
||||
expect(() => guardAnalystStatement("SELECT * FROM t_alpha_sql.sales WHERE c = 'x", OPTS)).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
expect(() => guardAnalystStatement('SELECT * FROM t_alpha_sql.sales /* x', OPTS)).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('treats a comment as whitespace, so it cannot glue two identifiers together', () => {
|
||||
// `a/**/b` must not become `ab`.
|
||||
expect(stripSqlText('a/**/b').stripped).toBe('a b');
|
||||
// A line comment leaves its terminating newline in place, so the result is
|
||||
// "a \nb" — separated, which is the property that matters.
|
||||
expect(stripSqlText('a--x\nb').stripped).toMatch(/^a\s+b$/);
|
||||
expect(stripSqlText('a--x\nb').stripped).not.toContain('ab');
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P017 — session role gate', () => {
|
||||
const endpoint: ReadOnlySqlEndpoint = {
|
||||
engine: 'clickhouse',
|
||||
async execute() {
|
||||
return { columns: ['n'], rows: [[1]] };
|
||||
},
|
||||
async cancel() {
|
||||
return true;
|
||||
},
|
||||
};
|
||||
const audit = {
|
||||
records: [] as AnalystStatementRecord[],
|
||||
record(e: AnalystStatementRecord) {
|
||||
this.records.push(e);
|
||||
},
|
||||
};
|
||||
|
||||
const open = (roles: string[] | undefined) =>
|
||||
new AnalyticsSQLSession({
|
||||
identity: { tenant_id: 't_alpha', principal_id: 'u_1', roles },
|
||||
endpoint,
|
||||
catalog: 't_alpha_sql',
|
||||
objects: ['sales', 'events'],
|
||||
audit,
|
||||
});
|
||||
|
||||
it('refuses to open without the analyst role', () => {
|
||||
for (const roles of [undefined, [], ['analytics.reader'], ['admin'], ['analytics.sql.analystX']]) {
|
||||
try {
|
||||
open(roles as string[] | undefined);
|
||||
throw new Error(`session opened with roles=${JSON.stringify(roles)} — role gate is not closed`);
|
||||
} catch (e) {
|
||||
expect(e).toBeInstanceOf(SiaxError);
|
||||
expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('opens with the analyst role', () => {
|
||||
expect(open([ANALYST_SQL_ROLE])).toBeInstanceOf(AnalyticsSQLSession);
|
||||
});
|
||||
|
||||
it('refuses to open without a verified tenant or principal', () => {
|
||||
for (const identity of [
|
||||
{ tenant_id: '', principal_id: 'u_1', roles: [ANALYST_SQL_ROLE] },
|
||||
{ tenant_id: ' ', principal_id: 'u_1', roles: [ANALYST_SQL_ROLE] },
|
||||
{ tenant_id: 't_alpha', principal_id: '', roles: [ANALYST_SQL_ROLE] },
|
||||
]) {
|
||||
expect(
|
||||
() =>
|
||||
new AnalyticsSQLSession({
|
||||
identity,
|
||||
endpoint,
|
||||
catalog: 't_alpha_sql',
|
||||
objects: ['sales'],
|
||||
audit,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P017 — audit and statement history', () => {
|
||||
function makeSession(opts?: { retainRaw?: boolean }) {
|
||||
const records: AnalystStatementRecord[] = [];
|
||||
const session = new AnalyticsSQLSession({
|
||||
identity: {
|
||||
tenant_id: 't_alpha',
|
||||
principal_id: 'u_1',
|
||||
roles: [ANALYST_SQL_ROLE],
|
||||
correlation_id: 'c_1',
|
||||
},
|
||||
endpoint: {
|
||||
engine: 'clickhouse',
|
||||
async execute() {
|
||||
return { columns: ['n'], rows: [[7]], rows_read: 42, bytes_read: 4242 };
|
||||
},
|
||||
async cancel() {
|
||||
return true;
|
||||
},
|
||||
},
|
||||
catalog: 't_alpha_sql',
|
||||
objects: ['sales', 'events'],
|
||||
audit: { record: (e) => void records.push(e) },
|
||||
retainRawStatements: opts?.retainRaw,
|
||||
});
|
||||
return { session, records };
|
||||
}
|
||||
|
||||
it('records a REFUSAL, not only a success — a guard whose rejections are invisible cannot be reviewed', async () => {
|
||||
const { session, records } = makeSession();
|
||||
await expect(session.query('SELECT * FROM system.tables')).rejects.toBeInstanceOf(SiaxError);
|
||||
expect(records).toHaveLength(1);
|
||||
expect(records[0].outcome).toBe('refused');
|
||||
expect(records[0].error_code).toBe('AUTHORIZATION_DENIED');
|
||||
expect(records[0].refusal_reason).toBeTruthy();
|
||||
// Even a refused statement is masked before it is stored.
|
||||
expect(records[0].normalized).not.toContain("'");
|
||||
});
|
||||
|
||||
it('records the executed statement with objects, timings and byte counts', async () => {
|
||||
const { session, records } = makeSession();
|
||||
const out = await session.query('SELECT count() AS n FROM t_alpha_sql.sales');
|
||||
expect(out.rows).toEqual([[7]]);
|
||||
expect(records).toHaveLength(1);
|
||||
expect(records[0].outcome).toBe('succeeded');
|
||||
expect(records[0].referenced_objects).toEqual(['t_alpha_sql.sales']);
|
||||
expect(records[0].rows_read).toBe(42);
|
||||
expect(records[0].bytes_read).toBe(4242);
|
||||
expect(records[0].statement_hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
expect(records[0].correlation_id).toBe('c_1');
|
||||
});
|
||||
|
||||
it('omits the raw statement when retention is off, but never the normalized one', async () => {
|
||||
const { session, records } = makeSession({ retainRaw: false });
|
||||
await session.query("SELECT count() AS n FROM t_alpha_sql.sales WHERE customer = 'Anna'");
|
||||
expect(records[0].raw).toBeUndefined();
|
||||
expect(records[0].normalized).toContain('?');
|
||||
expect(records[0].normalized).not.toContain('Anna');
|
||||
});
|
||||
|
||||
it('applies every limit BI-P017 names, with readonly=1 (not 2, which permits SETTINGS changes)', async () => {
|
||||
let seen: Record<string, string> = {};
|
||||
const session = new AnalyticsSQLSession({
|
||||
identity: { tenant_id: 't_alpha', principal_id: 'u_1', roles: [ANALYST_SQL_ROLE] },
|
||||
endpoint: {
|
||||
engine: 'clickhouse',
|
||||
async execute(args) {
|
||||
seen = args.settings;
|
||||
return { columns: [], rows: [] };
|
||||
},
|
||||
async cancel() {
|
||||
return true;
|
||||
},
|
||||
},
|
||||
catalog: 't_alpha_sql',
|
||||
objects: ['sales'],
|
||||
audit: { record: () => undefined },
|
||||
});
|
||||
await session.query('SELECT count() AS n FROM t_alpha_sql.sales');
|
||||
expect(seen.readonly).toBe('1');
|
||||
for (const key of [
|
||||
'max_execution_time',
|
||||
'max_result_rows',
|
||||
'max_rows_to_read',
|
||||
'max_bytes_to_read',
|
||||
'max_memory_usage',
|
||||
]) {
|
||||
expect(Number(seen[key])).toBeGreaterThan(0);
|
||||
}
|
||||
// A limit that returns a PARTIAL result silently is a false green.
|
||||
expect(seen.timeout_overflow_mode).toBe('throw');
|
||||
expect(seen.result_overflow_mode).toBe('throw');
|
||||
expect(seen.read_overflow_mode).toBe('throw');
|
||||
});
|
||||
|
||||
it('a CL0UD quota may only tighten the budget, never loosen it', () => {
|
||||
const session = new AnalyticsSQLSession({
|
||||
identity: {
|
||||
tenant_id: 't_alpha',
|
||||
principal_id: 'u_1',
|
||||
roles: [ANALYST_SQL_ROLE],
|
||||
quota: { maxRowsToRead: 10, maxExecutionTimeSec: 999_999 },
|
||||
},
|
||||
endpoint: {
|
||||
engine: 'clickhouse',
|
||||
async execute() {
|
||||
return { columns: [], rows: [] };
|
||||
},
|
||||
async cancel() {
|
||||
return true;
|
||||
},
|
||||
},
|
||||
catalog: 't_alpha_sql',
|
||||
objects: ['sales'],
|
||||
audit: { record: () => undefined },
|
||||
});
|
||||
expect(session.resourceBudget.maxRowsToRead).toBe(10);
|
||||
expect(session.resourceBudget.maxExecutionTimeSec).toBeLessThanOrEqual(60);
|
||||
});
|
||||
|
||||
it('refuses to cancel a statement belonging to another session', async () => {
|
||||
const { session } = makeSession();
|
||||
await expect(session.cancel('sql_deadbeefcafe_notmine')).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P017 layers 3 and 4 — the DDL that holds when the guard does not', () => {
|
||||
const spec = {
|
||||
sourceDatabase: 'opt_analytics',
|
||||
tenantId: 't_alpha',
|
||||
catalog: 't_alpha_sql',
|
||||
objects: [{ table: 'opt_analytics_event', columns: ['event_id', 'metric', 'value', 'event_time'] }],
|
||||
};
|
||||
|
||||
it('bakes the tenant predicate into every view definition', () => {
|
||||
const ddl = tenantSqlCatalogDdl(spec);
|
||||
const view = ddl.find((s) => s.startsWith('CREATE OR REPLACE VIEW'));
|
||||
expect(view).toContain("WHERE tenant_id = 't_alpha'");
|
||||
expect(view).toContain('FROM opt_analytics.opt_analytics_event');
|
||||
});
|
||||
|
||||
it('refuses to project tenant_id into a single-tenant view', () => {
|
||||
expect(() =>
|
||||
tenantSqlCatalogDdl({ ...spec, objects: [{ table: 'x', columns: ['tenant_id', 'v'] }] }),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a tenant id that is not catalog-safe rather than embedding it', () => {
|
||||
for (const bad of ["t_alpha'; DROP", 't alpha', "'", '', "t_alpha' OR '1'='1"]) {
|
||||
expect(() => tenantSqlCatalogDdl({ ...spec, tenantId: bad })).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses to point the tenant catalog at the shared source database', () => {
|
||||
expect(() => tenantSqlCatalogDdl({ ...spec, catalog: 'opt_analytics' })).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('grants SELECT only on the tenant catalog and pins a row policy to the base table', () => {
|
||||
const ddl = tenantSqlUserDdl({ ...spec, userName: 't_alpha_sql_user', password: 'x' });
|
||||
expect(ddl.some((s) => s.includes('GRANT SELECT ON t_alpha_sql.* TO t_alpha_sql_user'))).toBe(true);
|
||||
// The wide grant that would make the whole design pointless:
|
||||
expect(ddl.some((s) => s.includes('GRANT SELECT ON opt_analytics.* '))).toBe(false);
|
||||
expect(
|
||||
ddl.some((s) => s.includes('CREATE ROW POLICY') && s.includes("USING tenant_id = 't_alpha'")),
|
||||
).toBe(true);
|
||||
expect(ddl[0]).toContain('readonly = 1');
|
||||
});
|
||||
|
||||
it('never embeds a password containing a quote or a backslash', () => {
|
||||
for (const bad of ["a'b", 'a\\b']) {
|
||||
expect(() => tenantSqlUserDdl({ ...spec, userName: 'u', password: bad })).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,194 @@
|
||||
/**
|
||||
* BI-P002 (domain model) + BI-P003 (data tiers), the parts provable without
|
||||
* infrastructure. The Postgres half — real tables, real immutability
|
||||
* triggers, real tenant scoping — is
|
||||
* tests/analytics/analytics-domain-postgres.realinfra.test.ts.
|
||||
*
|
||||
* The registry-vs-migration test below is the one that earns its place: it
|
||||
* reads sql/008_analytics_domain_model.sql from disk and asserts a CREATE
|
||||
* TABLE exists for every one of the nineteen canonical entities. A future
|
||||
* rename, or an entity quietly dropped from the migration, fails HERE rather
|
||||
* than at 3am against a database that turns out to be missing a table.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import {
|
||||
ANALYTICS_DOMAIN_ENTITIES,
|
||||
ANALYTICS_ENTITY_TABLES,
|
||||
IMMUTABLE_VERSION_ENTITIES,
|
||||
} from '@/src/analytics/domain/entities';
|
||||
import {
|
||||
ANALYTICS_TIERS,
|
||||
assertReadableByBiSurface,
|
||||
assertTierLineageSane,
|
||||
BI_READABLE_TIERS,
|
||||
isAnalyticsTier,
|
||||
TIER_RANK,
|
||||
} from '@/src/analytics/domain/tiers';
|
||||
|
||||
const MIGRATION = fs.readFileSync(path.join(process.cwd(), 'sql', '008_analytics_domain_model.sql'), 'utf8');
|
||||
|
||||
describe('BI-P002 canonical entity set', () => {
|
||||
it('lists exactly the nineteen entities the program names, verbatim', () => {
|
||||
expect(ANALYTICS_DOMAIN_ENTITIES).toEqual([
|
||||
'AnalyticsDataset',
|
||||
'DatasetVersion',
|
||||
'DatasetField',
|
||||
'DatasetGrant',
|
||||
'MetricDefinition',
|
||||
'MetricVersion',
|
||||
'DimensionDefinition',
|
||||
'SemanticModel',
|
||||
'AnalyticsQuery',
|
||||
'QueryExecution',
|
||||
'QueryResult',
|
||||
'DashboardDefinition',
|
||||
'DashboardVersion',
|
||||
'ReportDefinition',
|
||||
'ReportRun',
|
||||
'DataQualityRule',
|
||||
'DataQualityRun',
|
||||
'LineageReference',
|
||||
'BIApplicationBinding',
|
||||
]);
|
||||
expect(ANALYTICS_DOMAIN_ENTITIES).toHaveLength(19);
|
||||
});
|
||||
|
||||
it('sql/008 defines a table for every entity (no entity is a type without storage)', () => {
|
||||
const missing: string[] = [];
|
||||
for (const entity of ANALYTICS_DOMAIN_ENTITIES) {
|
||||
const table = ANALYTICS_ENTITY_TABLES[entity];
|
||||
if (!new RegExp(`CREATE TABLE IF NOT EXISTS ${table}\\b`).test(MIGRATION)) {
|
||||
missing.push(`${entity} -> ${table}`);
|
||||
}
|
||||
}
|
||||
expect(missing).toEqual([]);
|
||||
});
|
||||
|
||||
it('every tenant-owned table carries tenant_id AND project_id', () => {
|
||||
// Split on the table definitions and check each block.
|
||||
const blocks = MIGRATION.split(/CREATE TABLE IF NOT EXISTS /).slice(1);
|
||||
const offenders: string[] = [];
|
||||
for (const block of blocks) {
|
||||
const name = block.split(/[\s(]/)[0];
|
||||
if (!Object.values(ANALYTICS_ENTITY_TABLES).includes(name)) continue;
|
||||
const body = block.slice(0, block.indexOf(');'));
|
||||
if (!/\btenant_id TEXT NOT NULL\b/.test(body) || !/\bproject_id TEXT NOT NULL\b/.test(body)) {
|
||||
offenders.push(name);
|
||||
}
|
||||
}
|
||||
expect(offenders).toEqual([]);
|
||||
});
|
||||
|
||||
it('the four immutable version entities have a BEFORE UPDATE OR DELETE trigger in sql/008', () => {
|
||||
expect(IMMUTABLE_VERSION_ENTITIES).toEqual([
|
||||
'DatasetVersion',
|
||||
'MetricVersion',
|
||||
'SemanticModel',
|
||||
'DashboardVersion',
|
||||
]);
|
||||
for (const entity of IMMUTABLE_VERSION_ENTITIES) {
|
||||
const table = ANALYTICS_ENTITY_TABLES[entity];
|
||||
expect(
|
||||
new RegExp(`BEFORE UPDATE OR DELETE ON ${table}\\b`).test(MIGRATION),
|
||||
`${entity} (${table}) has no immutability trigger`,
|
||||
).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it('BIApplicationBinding storage carries NO credential column — the ownership boundary is structural', () => {
|
||||
const block = MIGRATION.split('CREATE TABLE IF NOT EXISTS opt_analytics_bi_application_binding')[1] ?? '';
|
||||
const body = block.slice(0, block.indexOf(');'));
|
||||
for (const forbidden of ['password', 'dsn', 'secret', 'connection_string', 'clickhouse_url', 'token']) {
|
||||
expect(body.toLowerCase()).not.toContain(forbidden);
|
||||
}
|
||||
});
|
||||
|
||||
it('sql/008 is idempotent-shaped: every CREATE is IF NOT EXISTS / OR REPLACE', () => {
|
||||
const creates =
|
||||
MIGRATION.match(/^CREATE (TABLE|INDEX|TRIGGER|FUNCTION|OR REPLACE FUNCTION)[^\n]*/gm) ?? [];
|
||||
const nonIdempotent = creates.filter(
|
||||
(line) => !/IF NOT EXISTS/.test(line) && !/OR REPLACE/.test(line) && !/^CREATE TRIGGER/.test(line),
|
||||
);
|
||||
expect(nonIdempotent).toEqual([]);
|
||||
// Triggers cannot take IF NOT EXISTS in Postgres, so each one must be
|
||||
// preceded by a DROP TRIGGER IF EXISTS to stay replayable.
|
||||
const triggers = MIGRATION.match(/^CREATE TRIGGER (\w+)/gm) ?? [];
|
||||
for (const t of triggers) {
|
||||
const name = t.replace('CREATE TRIGGER ', '');
|
||||
expect(MIGRATION).toContain(`DROP TRIGGER IF EXISTS ${name}`);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P003 analytics data tiers', () => {
|
||||
it('canonicalizes exactly RAW / NORMALIZED / CURATED / SERVING', () => {
|
||||
expect(ANALYTICS_TIERS).toEqual(['RAW', 'NORMALIZED', 'CURATED', 'SERVING']);
|
||||
expect(isAnalyticsTier('CURATED')).toBe(true);
|
||||
expect(isAnalyticsTier('raw')).toBe(false);
|
||||
expect(isAnalyticsTier('BRONZE')).toBe(false);
|
||||
});
|
||||
|
||||
it('no business dashboard reads a RAW/NORMALIZED dataset by default', () => {
|
||||
expect(BI_READABLE_TIERS).toEqual(['SERVING', 'CURATED']);
|
||||
for (const tier of ['RAW', 'NORMALIZED'] as const) {
|
||||
expect(() =>
|
||||
assertReadableByBiSurface({ dataset_id: 'ds_1', tier }, 'dashboard:exec-overview'),
|
||||
).toThrowError(/may not read/);
|
||||
}
|
||||
for (const tier of ['SERVING', 'CURATED'] as const) {
|
||||
expect(() => assertReadableByBiSurface({ dataset_id: 'ds_1', tier }, 'dashboard:x')).not.toThrow();
|
||||
}
|
||||
});
|
||||
|
||||
it('a recorded exception is the only way a RAW dataset reaches a BI surface', () => {
|
||||
expect(() =>
|
||||
assertReadableByBiSurface(
|
||||
{
|
||||
dataset_id: 'ds_1',
|
||||
tier: 'RAW',
|
||||
raw_access_exception: 'INC-2026-09-06 forensic review, expires 2026-10-01',
|
||||
},
|
||||
'dashboard:incident',
|
||||
),
|
||||
).not.toThrow();
|
||||
// An empty/whitespace "exception" is not an exception.
|
||||
expect(() =>
|
||||
assertReadableByBiSurface(
|
||||
{ dataset_id: 'ds_1', tier: 'RAW', raw_access_exception: ' ' },
|
||||
'dashboard:x',
|
||||
),
|
||||
).toThrowError(/may not read/);
|
||||
});
|
||||
|
||||
it('tier order is enforced: a CURATED dataset cannot be built from SERVING', () => {
|
||||
expect(TIER_RANK.RAW).toBeLessThan(TIER_RANK.NORMALIZED);
|
||||
expect(TIER_RANK.NORMALIZED).toBeLessThan(TIER_RANK.CURATED);
|
||||
expect(TIER_RANK.CURATED).toBeLessThan(TIER_RANK.SERVING);
|
||||
expect(() => assertTierLineageSane('CURATED', 'SERVING')).toThrowError(/tier order/);
|
||||
expect(() => assertTierLineageSane('SERVING', 'CURATED')).not.toThrow();
|
||||
expect(() => assertTierLineageSane('CURATED', 'CURATED')).not.toThrow();
|
||||
});
|
||||
|
||||
it('sql/008 constrains tier at the DATABASE level, not only in TypeScript', () => {
|
||||
expect(MIGRATION).toContain("CHECK (tier IN ('RAW','NORMALIZED','CURATED','SERVING'))");
|
||||
});
|
||||
|
||||
it("BI-P003's eight required declarations are all NOT NULL in sql/008", () => {
|
||||
const block = MIGRATION.split('CREATE TABLE IF NOT EXISTS opt_analytics_dataset ')[1] ?? '';
|
||||
const body = block.slice(0, block.indexOf(');'));
|
||||
for (const col of [
|
||||
'tier',
|
||||
'schema_contract_id',
|
||||
'owner_id',
|
||||
'source_ref',
|
||||
'freshness_slo_seconds',
|
||||
'retention_days',
|
||||
'classification',
|
||||
'quality_rule_ids',
|
||||
]) {
|
||||
expect(new RegExp(`\\b${col}\\b[^,]*NOT NULL`).test(body), `${col} is nullable`).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,369 @@
|
||||
/**
|
||||
* BI-P002 DoD: "Database migrations + persistence + tenant isolation +
|
||||
* restore tests."
|
||||
*
|
||||
* REAL Postgres, same honest-degrade convention as
|
||||
* tests/p0/source-registry-postgres.realinfra.test.ts: gated on
|
||||
* ANALYTICS_TEST_DATABASE_URL, SKIPS HONESTLY when unset, never fabricates.
|
||||
*
|
||||
* docker run -d --name opt-bi-pg -p 15455:5432 \
|
||||
* -e POSTGRES_USER=opt -e POSTGRES_PASSWORD=opt_bi_throwaway \
|
||||
* -e POSTGRES_DB=opt_bi_test postgres:16-alpine
|
||||
* ANALYTICS_TEST_DATABASE_URL=postgres://opt:opt_bi_throwaway@localhost:15455/opt_bi_test \
|
||||
* pnpm vitest run tests/analytics/analytics-domain-postgres.realinfra.test.ts
|
||||
*
|
||||
* The RESTORE half is the part that catches migration-chain rot: it replays
|
||||
* sql/001..008 in order into a FRESH database, exactly as
|
||||
* docs/runbook/backup-restore.md describes, and only then runs the
|
||||
* persistence assertions. sql/003_datasets.sql exists because that same drill
|
||||
* found a table no file ever created; this suite keeps that class of defect
|
||||
* from coming back through sql/008.
|
||||
*/
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import postgres from 'postgres';
|
||||
import {
|
||||
ANALYTICS_DOMAIN_ENTITIES,
|
||||
ANALYTICS_ENTITY_TABLES,
|
||||
IMMUTABLE_VERSION_ENTITIES,
|
||||
} from '@/src/analytics/domain/entities';
|
||||
import { AnalyticsDomainRepository } from '@/src/analytics/repositories/analytics-domain-repository';
|
||||
import { contractHash, type DatasetContract } from '@/src/analytics/domain/contract';
|
||||
|
||||
const TEST_DATABASE_URL = process.env.ANALYTICS_TEST_DATABASE_URL;
|
||||
const run = TEST_DATABASE_URL ? describe : describe.skip;
|
||||
|
||||
/** A schema of its own so the drill starts from genuinely nothing. */
|
||||
const SCHEMA = `bi_p002_${Date.now().toString(36)}`;
|
||||
|
||||
let sql: ReturnType<typeof postgres> | undefined;
|
||||
let reachable = false;
|
||||
let unreachableReason = '';
|
||||
/** Which sql/*.sql files the restore drill actually applied. */
|
||||
const applied: string[] = [];
|
||||
|
||||
const ALPHA = { tenant_id: 't_alpha', project_id: 'p_main' };
|
||||
const BETA = { tenant_id: 't_beta', project_id: 'p_main' };
|
||||
|
||||
function repo(): AnalyticsDomainRepository {
|
||||
return new AnalyticsDomainRepository(sql!);
|
||||
}
|
||||
|
||||
function contract(datasetId: string): DatasetContract {
|
||||
return {
|
||||
dataset_id: datasetId,
|
||||
version: '1.0.0',
|
||||
tier: 'CURATED',
|
||||
fields: [{ name: 'id', type: 'string', nullable: false, role: 'identifier', primary_identifier: true }],
|
||||
primary_identifiers: ['id'],
|
||||
dimensions: [],
|
||||
measures: [],
|
||||
freshness_slo_seconds: 3600,
|
||||
retention_days: 365,
|
||||
pii_classification: 'none',
|
||||
source_lineage: ['src_x'],
|
||||
quality_rules: [],
|
||||
allowed_purposes: ['analytics'],
|
||||
};
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
if (!TEST_DATABASE_URL) {
|
||||
console.warn(
|
||||
'[realinfra] ANALYTICS_TEST_DATABASE_URL not set — skipping honestly, not fabricating success.',
|
||||
);
|
||||
return;
|
||||
}
|
||||
try {
|
||||
sql = postgres(TEST_DATABASE_URL, { prepare: false, ssl: false, max: 3 });
|
||||
await Promise.race([
|
||||
sql`SELECT 1`,
|
||||
new Promise((_, reject) => setTimeout(() => reject(new Error('connect timeout')), 5000)),
|
||||
]);
|
||||
// RESTORE DRILL: a brand-new schema, then every migration in order.
|
||||
await sql.unsafe(`CREATE SCHEMA ${SCHEMA}`);
|
||||
await sql.unsafe(`SET search_path TO ${SCHEMA}, public`);
|
||||
const dir = path.join(process.cwd(), 'sql');
|
||||
for (const file of fs
|
||||
.readdirSync(dir)
|
||||
.filter((f) => f.endsWith('.sql'))
|
||||
.sort()) {
|
||||
const body = fs.readFileSync(path.join(dir, file), 'utf8');
|
||||
try {
|
||||
await sql.unsafe(`SET search_path TO ${SCHEMA}, public; ${body}`);
|
||||
applied.push(file);
|
||||
} catch (err) {
|
||||
// 001 needs the `vector` extension, which a stock postgres:16-alpine
|
||||
// does not carry. Record the skip rather than hiding it — the files
|
||||
// sql/008 actually depends on must still apply.
|
||||
applied.push(`${file} (FAILED: ${String(err).slice(0, 120)})`);
|
||||
}
|
||||
}
|
||||
reachable = true;
|
||||
} catch (err) {
|
||||
reachable = false;
|
||||
unreachableReason = err instanceof Error ? err.message : String(err);
|
||||
}
|
||||
}, 60_000);
|
||||
|
||||
afterAll(async () => {
|
||||
if (sql && reachable) {
|
||||
await sql.unsafe(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => undefined);
|
||||
}
|
||||
await sql?.end({ timeout: 5 });
|
||||
});
|
||||
|
||||
run('BI-P002 analytics domain model against a LIVE Postgres', () => {
|
||||
it('restore drill: sql/008 applies cleanly on top of the replayed chain', (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
expect(unreachableReason).toBe('');
|
||||
const p008 = applied.find((f) => f.startsWith('008_'));
|
||||
expect(p008, `sql/008 was not applied. Applied: ${applied.join(', ')}`).toBe(
|
||||
'008_analytics_domain_model.sql',
|
||||
);
|
||||
});
|
||||
|
||||
it('all nineteen entity tables really exist after the restore', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const rows = await sql!<{ table_name: string }[]>`
|
||||
SELECT table_name FROM information_schema.tables WHERE table_schema = ${SCHEMA}`;
|
||||
const present = new Set(rows.map((r) => r.table_name));
|
||||
const missing = ANALYTICS_DOMAIN_ENTITIES.filter((e) => !present.has(ANALYTICS_ENTITY_TABLES[e]));
|
||||
expect(missing).toEqual([]);
|
||||
});
|
||||
|
||||
it('replaying sql/008 a second time is a no-op, not an error', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const body = fs.readFileSync(path.join(process.cwd(), 'sql', '008_analytics_domain_model.sql'), 'utf8');
|
||||
await expect(sql!.unsafe(`SET search_path TO ${SCHEMA}, public; ${body}`)).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('persists a dataset and reads it back through the repository', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
const created = await r.createDataset(ALPHA, {
|
||||
dataset_id: 'ds_alpha_1',
|
||||
name: 'Alpha listings',
|
||||
tier: 'CURATED',
|
||||
schema_contract_id: 'dc_alpha',
|
||||
schema_contract_version: '1.0.0',
|
||||
owner_id: 'team_data',
|
||||
source_ref: 'src_feed',
|
||||
freshness_slo_seconds: 3600,
|
||||
quality_rule_ids: [],
|
||||
retention_days: 365,
|
||||
classification: 'none',
|
||||
status: 'active',
|
||||
created_by: 'usr_1',
|
||||
});
|
||||
expect(created.tenant_id).toBe('t_alpha');
|
||||
const read = await r.getDataset(ALPHA, 'ds_alpha_1');
|
||||
expect(read?.name).toBe('Alpha listings');
|
||||
expect(read?.freshness_slo_seconds).toBe(3600);
|
||||
// Cross-check with direct SQL — proving the row is really in the table,
|
||||
// not an artifact of the repository's own bookkeeping.
|
||||
const direct = await sql!<{ c: string }[]>`
|
||||
SELECT count(*)::text AS c FROM opt_analytics_dataset WHERE dataset_id = 'ds_alpha_1'`;
|
||||
expect(Number(direct[0].c)).toBe(1);
|
||||
});
|
||||
|
||||
it("TENANT ISOLATION: t_beta cannot read t_alpha's dataset, even with the exact id", async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
expect(await r.getDataset(BETA, 'ds_alpha_1')).toBeUndefined();
|
||||
expect(await r.listDatasets(BETA)).toEqual([]);
|
||||
// And the row IS there — the empty result is scoping, not absence.
|
||||
const direct = await sql!<{ c: string }[]>`SELECT count(*)::text AS c FROM opt_analytics_dataset`;
|
||||
expect(Number(direct[0].c)).toBeGreaterThanOrEqual(1);
|
||||
});
|
||||
|
||||
it("TENANT ISOLATION: a version cannot be minted against another tenant's dataset", async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
await expect(
|
||||
repo().createDatasetVersion(BETA, {
|
||||
dataset_id: 'ds_alpha_1',
|
||||
contract_hash: 'deadbeef',
|
||||
schema_contract_version: '1.0.0',
|
||||
}),
|
||||
).rejects.toMatchObject({ code: 'NOT_FOUND' });
|
||||
});
|
||||
|
||||
it('dataset versions are monotonic and carry the contract hash', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
const c = contract('ds_alpha_1');
|
||||
const v1 = await r.createDatasetVersion(ALPHA, {
|
||||
dataset_id: 'ds_alpha_1',
|
||||
contract_hash: contractHash(c),
|
||||
schema_contract_version: '1.0.0',
|
||||
});
|
||||
const v2 = await r.createDatasetVersion(ALPHA, {
|
||||
dataset_id: 'ds_alpha_1',
|
||||
contract_hash: contractHash({ ...c, version: '2.0.0' }),
|
||||
schema_contract_version: '2.0.0',
|
||||
});
|
||||
expect(v1.version).toBe(1);
|
||||
expect(v2.version).toBe(2);
|
||||
expect(v2.contract_hash).not.toBe(v1.contract_hash);
|
||||
expect((await r.listDatasetVersions(ALPHA, 'ds_alpha_1')).map((v) => v.version)).toEqual([1, 2]);
|
||||
});
|
||||
|
||||
it('IMMUTABILITY is enforced by the DATABASE: UPDATE and DELETE on a version row are refused', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
// Direct SQL, bypassing every TypeScript `readonly` — the only test that
|
||||
// proves the guarantee survives a psql session.
|
||||
await expect(
|
||||
sql!.unsafe(
|
||||
`UPDATE ${SCHEMA}.opt_analytics_dataset_version SET contract_hash = 'tampered' WHERE dataset_id = 'ds_alpha_1'`,
|
||||
),
|
||||
).rejects.toThrow(/immutable/i);
|
||||
await expect(
|
||||
sql!.unsafe(`DELETE FROM ${SCHEMA}.opt_analytics_dataset_version WHERE dataset_id = 'ds_alpha_1'`),
|
||||
).rejects.toThrow(/immutable/i);
|
||||
// The rows are untouched.
|
||||
const rows = await sql!<{ contract_hash: string }[]>`
|
||||
SELECT contract_hash FROM opt_analytics_dataset_version WHERE dataset_id = 'ds_alpha_1'`;
|
||||
expect(rows).toHaveLength(2);
|
||||
for (const r of rows) expect(r.contract_hash).not.toBe('tampered');
|
||||
});
|
||||
|
||||
it('all four immutable entities refuse an UPDATE, not just the one that was tested first', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
await r.createDataset(ALPHA, {
|
||||
dataset_id: 'ds_imm',
|
||||
name: 'Immutability fixture',
|
||||
tier: 'SERVING',
|
||||
schema_contract_id: 'dc_i',
|
||||
schema_contract_version: '1.0.0',
|
||||
owner_id: 'team_data',
|
||||
source_ref: 'src',
|
||||
freshness_slo_seconds: 60,
|
||||
quality_rule_ids: [],
|
||||
retention_days: 30,
|
||||
classification: 'none',
|
||||
status: 'active',
|
||||
});
|
||||
const metric = await r.createMetric(ALPHA, {
|
||||
metric_id: 'm_imm',
|
||||
name: 'immutable metric',
|
||||
dataset_id: 'ds_imm',
|
||||
aggregation: 'sum',
|
||||
measure_field: 'value',
|
||||
allowed_dimension_ids: [],
|
||||
owner_id: 'team_data',
|
||||
});
|
||||
await r.createMetricVersion(ALPHA, { metric_id: metric.metric_id, definition_json: '{"v":1}' });
|
||||
await r.createDatasetVersion(ALPHA, {
|
||||
dataset_id: 'ds_imm',
|
||||
contract_hash: 'h1',
|
||||
schema_contract_version: '1.0.0',
|
||||
});
|
||||
await sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_semantic_model
|
||||
(semantic_model_id, tenant_id, project_id, name, version, model_json, model_hash, owner_id)
|
||||
VALUES ('sm_1','t_alpha','p_main','model_a',1,'{}','h','team_data')`);
|
||||
await sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_dashboard_definition
|
||||
(dashboard_id, tenant_id, project_id, name, owner_id) VALUES ('db_1','t_alpha','p_main','dash','team_data')`);
|
||||
await sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_dashboard_version
|
||||
(dashboard_version_id, dashboard_id, tenant_id, project_id, version, layout_json, layout_hash)
|
||||
VALUES ('dv_1','db_1','t_alpha','p_main',1,'{}','h')`);
|
||||
|
||||
const updates: Record<string, string> = {
|
||||
DatasetVersion: `UPDATE ${SCHEMA}.opt_analytics_dataset_version SET contract_hash='x' WHERE dataset_id='ds_imm'`,
|
||||
MetricVersion: `UPDATE ${SCHEMA}.opt_analytics_metric_version SET definition_json='{}' WHERE metric_id='m_imm'`,
|
||||
SemanticModel: `UPDATE ${SCHEMA}.opt_analytics_semantic_model SET model_json='{}' WHERE semantic_model_id='sm_1'`,
|
||||
DashboardVersion: `UPDATE ${SCHEMA}.opt_analytics_dashboard_version SET layout_json='{}' WHERE dashboard_version_id='dv_1'`,
|
||||
};
|
||||
for (const entity of IMMUTABLE_VERSION_ENTITIES) {
|
||||
await expect(sql!.unsafe(updates[entity]), `${entity} is NOT immutable`).rejects.toThrow(/immutable/i);
|
||||
}
|
||||
});
|
||||
|
||||
it('a metric version after the first must state WHY the number changed meaning', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
await expect(
|
||||
r.createMetricVersion(ALPHA, { metric_id: 'm_imm', definition_json: '{"v":2}' }),
|
||||
).rejects.toThrow();
|
||||
const v2 = await r.createMetricVersion(ALPHA, {
|
||||
metric_id: 'm_imm',
|
||||
definition_json: '{"v":2}',
|
||||
change_reason: 'excluded internal test accounts from the numerator',
|
||||
});
|
||||
expect(v2.version).toBe(2);
|
||||
});
|
||||
|
||||
it('a DatasetGrant without a purpose is refused by the DATABASE (purpose limitation)', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
// Regression pin: the first version of this constraint was written
|
||||
// `array_length(allowed_purposes, 1) >= 1`, which is NULL for '{}' — and a
|
||||
// CHECK evaluating to NULL PASSES in Postgres. It could never fail. This
|
||||
// test found that; keep it.
|
||||
await expect(
|
||||
sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_dataset_grant
|
||||
(grant_id, dataset_id, tenant_id, project_id, subject_id, subject_type, level, allowed_purposes)
|
||||
VALUES ('g_1','ds_imm','t_alpha','p_main','usr_1','user','read', '{}')`),
|
||||
).rejects.toThrow(/purposes_nonempty/);
|
||||
// A grant WITH a purpose is accepted, so the constraint is not simply
|
||||
// rejecting everything.
|
||||
await expect(
|
||||
sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_dataset_grant
|
||||
(grant_id, dataset_id, tenant_id, project_id, subject_id, subject_type, level, allowed_purposes)
|
||||
VALUES ('g_ok','ds_imm','t_alpha','p_main','usr_1','user','read', ARRAY['market_analytics'])`),
|
||||
).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('a BIApplicationBinding without a purpose is refused too, and carries no credential column', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
await expect(
|
||||
sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_bi_application_binding
|
||||
(binding_id, tenant_id, project_id, kind, name, principal_id, allowed_purposes)
|
||||
VALUES ('b_1','t_alpha','p_main','superset','sup','svc_1','{}')`),
|
||||
).rejects.toThrow(/purposes_nonempty/);
|
||||
|
||||
const cols = await sql!<{ column_name: string }[]>`
|
||||
SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = ${SCHEMA} AND table_name = 'opt_analytics_bi_application_binding'`;
|
||||
const names = cols.map((c) => c.column_name.toLowerCase());
|
||||
for (const forbidden of ['password', 'secret', 'dsn', 'token', 'connection_string', 'clickhouse_url']) {
|
||||
expect(names, `BI binding must never store ${forbidden}`).not.toContain(forbidden);
|
||||
}
|
||||
});
|
||||
|
||||
it('the dimension catalog is tenant-scoped and FAILS CLOSED for a tenant with none', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
await r.createDimension(ALPHA, {
|
||||
dimension_id: 'dim_1',
|
||||
name: 'make',
|
||||
dataset_id: 'ds_imm',
|
||||
field_name: 'vehicle_make',
|
||||
field_type: 'string',
|
||||
classification: 'none',
|
||||
});
|
||||
expect(await r.dimensionCatalog(ALPHA)).toEqual({ make: 'vehicle_make' });
|
||||
// t_beta declared nothing, so it may reference nothing.
|
||||
expect(await r.dimensionCatalog(BETA)).toEqual({});
|
||||
});
|
||||
|
||||
it('a dimension whose physical field is not identifier-safe is refused by the DATABASE', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
await expect(
|
||||
sql!.unsafe(`INSERT INTO ${SCHEMA}.opt_analytics_dimension_definition
|
||||
(dimension_id, tenant_id, project_id, name, dataset_id, field_name, field_type)
|
||||
VALUES ('dim_bad','t_alpha','p_main','evil','ds_imm', 'x''; DROP TABLE opt_analytics_dataset; --','string')`),
|
||||
).rejects.toThrow();
|
||||
});
|
||||
|
||||
it('the repository refuses to act without a verified tenant scope', async (ctx) => {
|
||||
if (!reachable) ctx.skip();
|
||||
const r = repo();
|
||||
await expect(r.getDataset({ tenant_id: '', project_id: 'p' }, 'ds_imm')).rejects.toMatchObject({
|
||||
code: 'UNAUTHENTICATED',
|
||||
});
|
||||
await expect(r.listDatasets({ tenant_id: 't_alpha', project_id: ' ' })).rejects.toMatchObject({
|
||||
code: 'UNAUTHENTICATED',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* BI-P009 DoD: "Provider contract tests added."
|
||||
*
|
||||
* This is the contract every `SiaxAnalyticsEngine` provider must satisfy
|
||||
* regardless of engine — ClickHouse today, DuckDB (BI-P014) and Trino
|
||||
* (BI-P015) later. It is written against the INTERFACE, so a future provider
|
||||
* imports `analyticsEngineContract` and gets the same bar.
|
||||
*
|
||||
* The identity rules here are the ones that matter most: this estate has
|
||||
* already shipped a live cross-tenant hole by reading the tenant out of a
|
||||
* REQUEST BODY (INF0 Wave 2). So the contract asserts that a request field
|
||||
* named `tenant_id` cannot influence the engine at all.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { ClickHouseAnalyticsEngine } from '@/src/analytics/engine/clickhouse-engine';
|
||||
import {
|
||||
SIAX_ANALYTICS_ENGINE_CAPABILITIES,
|
||||
type AnalyticsIdentity,
|
||||
type SiaxAnalyticsEngine,
|
||||
} from '@/src/analytics/engine/siax-analytics-engine';
|
||||
|
||||
const IDENTITY: AnalyticsIdentity = {
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_default',
|
||||
principal_id: 'usr_1',
|
||||
};
|
||||
|
||||
/** Reusable contract suite — future providers call this with their factory. */
|
||||
export function analyticsEngineContract(name: string, make: () => SiaxAnalyticsEngine): void {
|
||||
describe(`SiaxAnalyticsEngine contract: ${name}`, () => {
|
||||
it('implements all eight BI-P009 capabilities as callable methods', () => {
|
||||
const engine = make() as unknown as Record<string, unknown>;
|
||||
for (const cap of SIAX_ANALYTICS_ENGINE_CAPABILITIES) {
|
||||
expect(typeof engine[cap], `${cap} is not a method`).toBe('function');
|
||||
}
|
||||
expect(SIAX_ANALYTICS_ENGINE_CAPABILITIES).toEqual([
|
||||
'health',
|
||||
'executeMetric',
|
||||
'executeQuery',
|
||||
'estimateQuery',
|
||||
'cancelQuery',
|
||||
'explain',
|
||||
'ingestProjection',
|
||||
'refreshProjection',
|
||||
]);
|
||||
});
|
||||
|
||||
it('names its provider', () => {
|
||||
expect(make().provider.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('refuses every tenant-scoped capability without a verified identity', async () => {
|
||||
const engine = make();
|
||||
const blank = { tenant_id: '', project_id: 'p', principal_id: 'usr_1' };
|
||||
const noPrincipal = { tenant_id: 't_alpha', project_id: 'p', principal_id: '' };
|
||||
for (const bad of [blank, noPrincipal]) {
|
||||
await expect(engine.executeMetric(bad, { metric: 'm', aggregate: 'sum' })).rejects.toMatchObject({
|
||||
code: 'UNAUTHENTICATED',
|
||||
});
|
||||
await expect(engine.estimateQuery(bad, { metric: 'm', aggregate: 'sum' })).rejects.toMatchObject({
|
||||
code: 'UNAUTHENTICATED',
|
||||
});
|
||||
await expect(engine.ingestProjection(bad, { dataset_id: 'ds', rows: [] })).rejects.toMatchObject({
|
||||
code: 'UNAUTHENTICATED',
|
||||
});
|
||||
await expect(engine.refreshProjection(bad, 'ds')).rejects.toMatchObject({ code: 'UNAUTHENTICATED' });
|
||||
await expect(engine.cancelQuery(bad, 'q')).rejects.toMatchObject({ code: 'UNAUTHENTICATED' });
|
||||
}
|
||||
});
|
||||
|
||||
it('a tenant_id smuggled into the REQUEST cannot influence the engine (INF0 Wave-2 bug class)', async () => {
|
||||
const engine = make();
|
||||
const smuggled = { metric: 'm', aggregate: 'sum', tenant_id: 't_victim' } as never;
|
||||
// The request type has no tenant field; if a provider ever started
|
||||
// reading one, this call would target t_victim. The engine must still
|
||||
// fail on the IDENTITY, proving the request field is inert.
|
||||
await expect(
|
||||
engine.executeMetric({ tenant_id: '', project_id: 'p', principal_id: 'u' }, smuggled),
|
||||
).rejects.toMatchObject({ code: 'UNAUTHENTICATED' });
|
||||
});
|
||||
|
||||
it('cancelQuery refuses a query id belonging to another tenant', async () => {
|
||||
const engine = make();
|
||||
await expect(engine.cancelQuery(IDENTITY, 'opt_deadbeefdead_someoneelses')).rejects.toMatchObject({
|
||||
code: 'AUTHORIZATION_DENIED',
|
||||
});
|
||||
});
|
||||
|
||||
it('health() reports unhealthy rather than throwing when the engine is unreachable', async () => {
|
||||
const report = await make().health();
|
||||
expect(report.healthy).toBe(false);
|
||||
expect(report.provider.length).toBeGreaterThan(0);
|
||||
// Never leak an engine body or a DSN into the operator-facing detail.
|
||||
expect(report.detail ?? '').not.toMatch(/http|password|@/i);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
analyticsEngineContract(
|
||||
'clickhouse (unreachable host — contract-level assertions only)',
|
||||
() =>
|
||||
new ClickHouseAnalyticsEngine({
|
||||
baseUrl: 'http://clickhouse.invalid:8123',
|
||||
database: 'opt_contract_test',
|
||||
timeoutMs: 500,
|
||||
}),
|
||||
);
|
||||
|
||||
describe('BI-P009 refusals that are deliberate, not missing', () => {
|
||||
it('executeQuery (analyst SQL) is declared and REFUSED until BI-P017/BI-P033', async () => {
|
||||
const engine = new ClickHouseAnalyticsEngine({ baseUrl: 'http://clickhouse.invalid:8123' });
|
||||
await expect(engine.executeQuery(IDENTITY, { sql: 'SELECT 1', dataset_ids: [] })).rejects.toMatchObject({
|
||||
code: 'CAPABILITY_UNAVAILABLE',
|
||||
});
|
||||
});
|
||||
|
||||
it('the PRESERVED ClickHouseAnalytics is reachable through the engine, not replaced by it', () => {
|
||||
const engine = new ClickHouseAnalyticsEngine({ baseUrl: 'http://clickhouse.invalid:8123' });
|
||||
expect(engine.legacyAnalytics.constructor.name).toBe('ClickHouseAnalytics');
|
||||
expect(typeof engine.legacyAnalytics.queryMetric).toBe('function');
|
||||
expect(typeof engine.legacyAnalytics.ensureSchema).toBe('function');
|
||||
expect(typeof engine.legacyAnalytics.ingest).toBe('function');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,349 @@
|
||||
/**
|
||||
* tests/analytics/analytics-governance-postgres.realinfra.test.ts
|
||||
* ================================================================
|
||||
* sql/009 against a REAL Postgres.
|
||||
*
|
||||
* A migration nobody ran is a migration that does not work, and a trigger
|
||||
* nobody fired is a comment. So this applies sql/008 and sql/009 into a
|
||||
* throwaway schema and then attempts, against the database, every write the
|
||||
* constraints exist to refuse:
|
||||
*
|
||||
* BI-P031 UPDATE a CERTIFIED metric's meaning in place -> must RAISE.
|
||||
* This is the layer that holds when something writes without going
|
||||
* through the application: a migration script, a psql session, an
|
||||
* admin tool. A TypeScript guard does not survive `psql`.
|
||||
* BI-P030 UPDATE a published semantic model version's content -> must RAISE.
|
||||
* Two ACTIVE versions of one model -> must violate a unique index.
|
||||
* BI-P028 A currency-formatted metric with no currency -> must be refused.
|
||||
* Certification without an actor or the two definitions -> refused.
|
||||
* BI-P018 A `compiled_query_hash` that is not a 64-hex digest -> refused.
|
||||
* BI-P021 UPDATE or DELETE a usage-ledger row -> must RAISE (append-only).
|
||||
*
|
||||
* Gated on ANALYTICS_TEST_DATABASE_URL, matching the convention in
|
||||
* analytics-domain-postgres.realinfra.test.ts. With it set and Postgres down,
|
||||
* this FAILS rather than skipping.
|
||||
*
|
||||
* docker run -d --name pg -p 25433:5432 -e POSTGRES_PASSWORD=test \
|
||||
* -e POSTGRES_DB=opt postgres:16-alpine
|
||||
* ANALYTICS_TEST_DATABASE_URL=postgres://postgres:test@127.0.0.1:25433/opt \
|
||||
* pnpm vitest run tests/analytics/analytics-governance-postgres.realinfra.test.ts
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
||||
import postgres from 'postgres';
|
||||
|
||||
const TEST_DATABASE_URL = process.env.ANALYTICS_TEST_DATABASE_URL;
|
||||
const run = TEST_DATABASE_URL ? describe : describe.skip;
|
||||
const SCHEMA = `bi_p009_${Date.now().toString(36)}`;
|
||||
|
||||
let sql: ReturnType<typeof postgres>;
|
||||
|
||||
/** Did the statement RAISE? Returns the message, or undefined if it succeeded. */
|
||||
async function refusalOf(fn: () => Promise<unknown>): Promise<string | undefined> {
|
||||
try {
|
||||
await fn();
|
||||
return undefined;
|
||||
} catch (e) {
|
||||
return String((e as Error).message);
|
||||
}
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
if (!TEST_DATABASE_URL) return;
|
||||
// The search_path is pinned on the CONNECTION rather than prefixed to every
|
||||
// statement. Prefixing makes each call a multi-statement simple query, and
|
||||
// postgres.js then returns the LAST statement's result — which silently
|
||||
// turned `SELECT state FROM ...` into the connection object in the first
|
||||
// version of this file, and made two assertions compare against nonsense.
|
||||
const admin = postgres(TEST_DATABASE_URL, { max: 1, onnotice: () => undefined });
|
||||
await admin.unsafe(`CREATE SCHEMA IF NOT EXISTS ${SCHEMA}`);
|
||||
await admin.end({ timeout: 5 });
|
||||
|
||||
sql = postgres(TEST_DATABASE_URL, {
|
||||
max: 2,
|
||||
onnotice: () => undefined,
|
||||
connection: { search_path: SCHEMA },
|
||||
});
|
||||
for (const file of [
|
||||
'sql/008_analytics_domain_model.sql',
|
||||
'sql/009_analytics_execution_metrics_governance.sql',
|
||||
]) {
|
||||
await sql.unsafe(fs.readFileSync(path.join(process.cwd(), file), 'utf8'));
|
||||
}
|
||||
|
||||
// A dataset and a metric to govern.
|
||||
await sql.unsafe(`
|
||||
INSERT INTO opt_analytics_dataset
|
||||
(dataset_id, tenant_id, project_id, name, tier, schema_contract_id, schema_contract_version,
|
||||
owner_id, source_ref, freshness_slo_seconds, retention_days, classification, status)
|
||||
VALUES ('ds_sales','t_alpha','p_main','sales','SERVING','c_sales','1.0.0',
|
||||
'u_1','0pt://sourcing/sales', 3600, 90, 'none', 'active')
|
||||
ON CONFLICT DO NOTHING;`);
|
||||
}, 120_000);
|
||||
|
||||
afterAll(async () => {
|
||||
if (!TEST_DATABASE_URL || !sql) return;
|
||||
await sql.unsafe(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`);
|
||||
await sql.end({ timeout: 5 });
|
||||
});
|
||||
|
||||
run('sql/009 applies, and replays', () => {
|
||||
it('is idempotent — a replay onto an already-migrated schema succeeds', async () => {
|
||||
const text = fs.readFileSync(
|
||||
path.join(process.cwd(), 'sql/009_analytics_execution_metrics_governance.sql'),
|
||||
'utf8',
|
||||
);
|
||||
// The restore drill replays every file in order onto a live database.
|
||||
await expect(sql.unsafe(text)).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('added every BI-P018 column the execution record needs', async () => {
|
||||
const rows = await sql.unsafe(
|
||||
`SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = '${SCHEMA}' AND table_name = 'opt_analytics_query_execution'`,
|
||||
);
|
||||
const names = new Set((rows as unknown as Array<{ column_name: string }>).map((r) => r.column_name));
|
||||
for (const col of [
|
||||
'principal_id',
|
||||
'workload',
|
||||
'compiled_query_hash',
|
||||
'datasets',
|
||||
'metrics',
|
||||
'cache_status',
|
||||
'cost_units',
|
||||
]) {
|
||||
expect(names.has(col), `missing ${col}`).toBe(true);
|
||||
}
|
||||
// And the one it must NOT have.
|
||||
expect(names.has('query_text')).toBe(false);
|
||||
expect(names.has('sql')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
run('BI-P031 — a CERTIFIED metric cannot be modified in place, enforced by the DATABASE', () => {
|
||||
const base = '';
|
||||
|
||||
beforeAll(async () => {
|
||||
await sql.unsafe(`${base}
|
||||
INSERT INTO opt_analytics_metric_definition
|
||||
(metric_id, tenant_id, project_id, name, dataset_id, aggregation, measure_field,
|
||||
allowed_dimension_ids, current_version, owner_id, description,
|
||||
metric_type, time_dimension, unit, currency, display_format, status, filters_json,
|
||||
certification, business_definition, technical_definition, meaning_hash,
|
||||
certified_at, certified_by)
|
||||
VALUES ('m_revenue','t_alpha','p_main','net_revenue','ds_sales','sum','amount_sek',
|
||||
ARRAY['country'], 3, 'finance@siax.io', 'Invoiced revenue net of credits',
|
||||
'simple','invoiced_at','SEK','SEK','currency','ACTIVE','[]',
|
||||
'certified','What we invoiced','sum(amount_sek)', repeat('a',64),
|
||||
now(), 'u_1')
|
||||
ON CONFLICT (metric_id) DO NOTHING;`);
|
||||
});
|
||||
|
||||
it('REFUSES an in-place change to the meaning hash', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_metric_definition
|
||||
SET meaning_hash = repeat('b',64) WHERE metric_id = 'm_revenue'`),
|
||||
);
|
||||
expect(message, "a certified metric's meaning was changed in place, in the database").toBeDefined();
|
||||
expect(message).toContain('BI-P031');
|
||||
expect(message).toContain('mint version 4');
|
||||
});
|
||||
|
||||
it('ALLOWS an editorial change that leaves the meaning hash alone', async () => {
|
||||
await expect(
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_metric_definition
|
||||
SET description = 'Clearer wording' WHERE metric_id = 'm_revenue'`),
|
||||
).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('ALLOWS a meaning change that comes with a version bump', async () => {
|
||||
await expect(
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_metric_definition
|
||||
SET meaning_hash = repeat('c',64), current_version = 4
|
||||
WHERE metric_id = 'm_revenue'`),
|
||||
).resolves.toBeDefined();
|
||||
// Put it back for the remaining assertions.
|
||||
await sql.unsafe(`${base} UPDATE opt_analytics_metric_definition
|
||||
SET current_version = 3 WHERE metric_id = 'm_revenue'`);
|
||||
});
|
||||
|
||||
it('refuses a currency-formatted metric with no currency', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_metric_definition
|
||||
(metric_id, tenant_id, project_id, name, dataset_id, aggregation, measure_field,
|
||||
owner_id, display_format, currency, time_dimension)
|
||||
VALUES ('m_bad','t_alpha','p_main','bad_metric','ds_sales','sum','x','u','currency',NULL,'t')`),
|
||||
);
|
||||
expect(message).toContain('currency_pairing');
|
||||
});
|
||||
|
||||
it('refuses a currency on a non-currency format', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_metric_definition
|
||||
(metric_id, tenant_id, project_id, name, dataset_id, aggregation, measure_field,
|
||||
owner_id, display_format, currency, time_dimension)
|
||||
VALUES ('m_bad2','t_alpha','p_main','bad_metric2','ds_sales','sum','x','u','integer','SEK','t')`),
|
||||
);
|
||||
expect(message).toContain('currency_pairing');
|
||||
});
|
||||
|
||||
it('refuses certification without an actor, a time, and both definitions', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_metric_definition
|
||||
(metric_id, tenant_id, project_id, name, dataset_id, aggregation, measure_field,
|
||||
owner_id, display_format, time_dimension, certification)
|
||||
VALUES ('m_bad3','t_alpha','p_main','bad_metric3','ds_sales','sum','x','u','decimal','t','certified')`),
|
||||
);
|
||||
expect(message).toContain('certification_act');
|
||||
});
|
||||
|
||||
it('refuses an unknown lifecycle status', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_metric_definition
|
||||
SET status = 'PROBABLY_FINE' WHERE metric_id = 'm_revenue'`),
|
||||
);
|
||||
expect(message).toContain('metric_status');
|
||||
});
|
||||
});
|
||||
|
||||
run('BI-P030 — a published semantic model version is immutable, and only one is active', () => {
|
||||
const base = '';
|
||||
|
||||
beforeAll(async () => {
|
||||
for (const [id, version, status] of [
|
||||
['smv_1', 1, 'active'],
|
||||
['smv_2', 2, 'draft'],
|
||||
] as const) {
|
||||
await sql.unsafe(`${base}
|
||||
INSERT INTO opt_analytics_semantic_model_version
|
||||
(semantic_model_version_id, model_id, tenant_id, project_id, version,
|
||||
datasets, relationships_json, metrics_json, dimensions_json, status, hash)
|
||||
VALUES ('${id}','sm_sales','t_alpha','p_main',${version},
|
||||
ARRAY['ds_sales'],'[]','[]','[]','${status}', repeat('${version}',64))
|
||||
ON CONFLICT DO NOTHING;`);
|
||||
}
|
||||
});
|
||||
|
||||
it("REFUSES an update to a published version's content", async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_semantic_model_version
|
||||
SET metrics_json = '[{"id":"m_new"}]' WHERE semantic_model_version_id = 'smv_1'`),
|
||||
);
|
||||
expect(message, 'a pinned semantic model version was rewritten under a dashboard').toBeDefined();
|
||||
expect(message).toContain('BI-P030');
|
||||
});
|
||||
|
||||
it('ALLOWS a status transition, which is not a content change', async () => {
|
||||
await expect(
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_semantic_model_version
|
||||
SET status = 'superseded' WHERE semantic_model_version_id = 'smv_1'`),
|
||||
).resolves.toBeDefined();
|
||||
await sql.unsafe(`${base} UPDATE opt_analytics_semantic_model_version
|
||||
SET status = 'active' WHERE semantic_model_version_id = 'smv_1'`);
|
||||
});
|
||||
|
||||
it('refuses TWO active versions of the same model — half the dashboards would read the other one', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_semantic_model_version
|
||||
SET status = 'active' WHERE semantic_model_version_id = 'smv_2'`),
|
||||
);
|
||||
expect(message).toContain('opt_analytics_semantic_model_one_active');
|
||||
});
|
||||
|
||||
it('refuses a hash that is not a sha256 digest', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base}
|
||||
INSERT INTO opt_analytics_semantic_model_version
|
||||
(semantic_model_version_id, model_id, tenant_id, project_id, version,
|
||||
datasets, relationships_json, metrics_json, dimensions_json, status, hash)
|
||||
VALUES ('smv_bad','sm_sales','t_alpha','p_main',9,ARRAY['ds_sales'],'[]','[]','[]','draft','not-a-hash')`),
|
||||
);
|
||||
expect(message).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
run('BI-P018 / BI-P021 — the execution record and the usage ledger', () => {
|
||||
const base = '';
|
||||
|
||||
it('refuses a compiled_query_hash that is not a 64-hex digest', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_query_execution
|
||||
(execution_id, tenant_id, project_id, engine_query_id, state, provider, compiled_query_hash)
|
||||
VALUES ('e_bad','t_alpha','p_main','q1','queued','clickhouse','SELECT * FROM sales')`),
|
||||
);
|
||||
expect(message).toContain('hash_shape');
|
||||
});
|
||||
|
||||
it('accepts a proper execution record', async () => {
|
||||
await expect(
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_query_execution
|
||||
(execution_id, tenant_id, project_id, engine_query_id, state, provider,
|
||||
compiled_query_hash, principal_id, workload, cache_status, cost_units)
|
||||
VALUES ('e_ok','t_alpha','p_main','q1','succeeded','clickhouse',
|
||||
repeat('a',64),'u_1','dashboard','hit',0.5)`),
|
||||
).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('refuses an unknown cache status and an unknown workload', async () => {
|
||||
expect(
|
||||
await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_query_execution
|
||||
SET cache_status = 'probably' WHERE execution_id = 'e_ok'`),
|
||||
),
|
||||
).toContain('cache_status');
|
||||
expect(
|
||||
await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_query_execution
|
||||
SET workload = 'vibes' WHERE execution_id = 'e_ok'`),
|
||||
),
|
||||
).toContain('workload');
|
||||
});
|
||||
|
||||
it('the usage ledger is APPEND-ONLY — update and delete both raise', async () => {
|
||||
await sql.unsafe(`${base} INSERT INTO opt_analytics_usage_ledger
|
||||
(usage_id, tenant_id, principal_id, query_id, engine, rows_scanned, bytes_scanned,
|
||||
execution_ms, cost_units, terminated_by_budget)
|
||||
VALUES ('u_1','t_alpha','p_1','q1','clickhouse',1000,2000,50,0.25,true)`);
|
||||
|
||||
expect(
|
||||
await refusalOf(() =>
|
||||
sql.unsafe(`${base} UPDATE opt_analytics_usage_ledger SET cost_units = 0 WHERE usage_id = 'u_1'`),
|
||||
),
|
||||
'a billing row was editable',
|
||||
).toBeDefined();
|
||||
expect(
|
||||
await refusalOf(() =>
|
||||
sql.unsafe(`${base} DELETE FROM opt_analytics_usage_ledger WHERE usage_id = 'u_1'`),
|
||||
),
|
||||
'a billing row was deletable',
|
||||
).toBeDefined();
|
||||
});
|
||||
|
||||
it('an analyst statement refusal must carry a reason', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_sql_statement
|
||||
(statement_id, tenant_id, principal_id, statement_normalized, statement_hash, outcome)
|
||||
VALUES ('s_bad','t_alpha','u_1','SELECT ?', repeat('a',64), 'refused')`),
|
||||
);
|
||||
expect(message, 'a refusal with no reason was accepted — an unreviewable audit trail').toBeDefined();
|
||||
});
|
||||
|
||||
it('a freshness row must carry a disclosure a UI can render', async () => {
|
||||
const message = await refusalOf(() =>
|
||||
sql.unsafe(`${base} INSERT INTO opt_analytics_dataset_freshness
|
||||
(tenant_id, dataset_id, state, expected_interval_ms, disclosure)
|
||||
VALUES ('t_alpha','ds_sales','STALE',3600000,' ')`),
|
||||
);
|
||||
expect(message).toBeDefined();
|
||||
});
|
||||
|
||||
it('freshness defaults to UNKNOWN, never to FRESH', async () => {
|
||||
await sql.unsafe(`${base} INSERT INTO opt_analytics_dataset_freshness
|
||||
(tenant_id, dataset_id, expected_interval_ms, disclosure)
|
||||
VALUES ('t_beta','ds_sales',3600000,'not yet computed')`);
|
||||
const rows = await sql.unsafe(`${base} SELECT state FROM opt_analytics_dataset_freshness
|
||||
WHERE tenant_id = 't_beta'`);
|
||||
expect((rows as unknown as Array<{ state: string }>)[0].state).toBe('UNKNOWN');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,521 @@
|
||||
/**
|
||||
* BI-P129 — ANALYTICS DATA INGESTION.
|
||||
*
|
||||
* DoD: "Two real source types ingest into canonical analytics tiers."
|
||||
*
|
||||
* The two source types here are the REAL P061 connectors, sharing no code but
|
||||
* the contract: a JSONL file on actual disk, and an HTTP JSON API served by a
|
||||
* real `fetch` implementation over a real request/response cycle. Both go
|
||||
* through the REAL P062 ingestion runner and the REAL landing sink into a
|
||||
* declared tier. Nothing about the tier or the contract is stubbed.
|
||||
*
|
||||
* Every gate is attacked TWICE: once with the guard in place (it must
|
||||
* refuse), and once in a counterfactual that removes only the guard (it must
|
||||
* succeed). A guard whose counterfactual also fails is not a guard — the
|
||||
* behaviour was coming from somewhere else, and the estate has shipped three
|
||||
* of those this month.
|
||||
*/
|
||||
import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
|
||||
import { promises as fs } from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { InMemoryIngestionRepository } from '@/src/repositories/in-memory-ingestion-repository';
|
||||
import { SchemaRegistry } from '@/src/schema/schema-registry';
|
||||
import { LineageStore } from '@/src/lineage/lineage-store';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import type { RecordSchemaFields } from '@/src/schema/record-schema';
|
||||
import {
|
||||
ConnectorProviderRegistry,
|
||||
assertContractCoversDiscovery,
|
||||
assertLandingTierIngestible,
|
||||
assertPhysicalHomeMatchesTier,
|
||||
assertProviderRunnable,
|
||||
contractCoverageProblems,
|
||||
planAnalyticsIngestion,
|
||||
type AnalyticsConnectorProvider,
|
||||
type AnalyticsIngestionSpec,
|
||||
type AnalyticsLandingTarget,
|
||||
} from '@/src/analytics/ingestion/connector-provider';
|
||||
import { NativeConnectorProvider } from '@/src/analytics/ingestion/native-provider';
|
||||
import { InMemoryLandingWriter, assertDiscoveryLandable } from '@/src/analytics/ingestion/landing';
|
||||
import { AnalyticsIngestionService } from '@/src/analytics/ingestion/analytics-ingestion-service';
|
||||
import type { DatasetContract } from '@/src/analytics/domain/contract';
|
||||
|
||||
// ── fixtures ───────────────────────────────────────────────────────────────
|
||||
|
||||
const SOURCE_SCHEMA: RecordSchemaFields = {
|
||||
org_number: { type: 'string', required: true },
|
||||
name: { type: 'string', required: true },
|
||||
employees: { type: 'number', required: false },
|
||||
};
|
||||
|
||||
const CONTRACT: DatasetContract = {
|
||||
dataset_id: 'ds_companies_raw',
|
||||
version: '1.0.0',
|
||||
tier: 'RAW',
|
||||
fields: [
|
||||
{ name: 'org_number', type: 'string', nullable: false, role: 'identifier', primary_identifier: true },
|
||||
{ name: 'name', type: 'string', nullable: false, role: 'dimension' },
|
||||
{ name: 'employees', type: 'int64', nullable: true, role: 'measure' },
|
||||
],
|
||||
primary_identifiers: ['org_number'],
|
||||
dimensions: ['name'],
|
||||
measures: ['employees'],
|
||||
freshness_slo_seconds: 86_400,
|
||||
retention_days: 3650,
|
||||
pii_classification: 'none',
|
||||
source_lineage: ['bolagsverket'],
|
||||
quality_rules: [],
|
||||
allowed_purposes: ['analytics'],
|
||||
};
|
||||
|
||||
function target(overrides: Partial<AnalyticsLandingTarget> = {}): AnalyticsLandingTarget {
|
||||
return {
|
||||
dataset_id: 'ds_companies_raw',
|
||||
tier: 'RAW',
|
||||
contract: CONTRACT,
|
||||
physical: { format: 'parquet', namespace: 'analytics_raw', table_name: 'companies' },
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
const ROWS = Array.from({ length: 9 }, (_, i) => ({
|
||||
org_number: `55600${i}-000${i}`,
|
||||
name: `Bolag ${i} AB`,
|
||||
employees: (i + 1) * 10,
|
||||
}));
|
||||
|
||||
const tmpDir = path.join(os.tmpdir(), `opt-bi129-${process.pid}`);
|
||||
const filePath = path.join(tmpDir, 'companies.jsonl');
|
||||
|
||||
beforeAll(async () => {
|
||||
await fs.mkdir(tmpDir, { recursive: true });
|
||||
await fs.writeFile(filePath, ROWS.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf8');
|
||||
});
|
||||
afterAll(async () => {
|
||||
await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
|
||||
});
|
||||
|
||||
/**
|
||||
* A real HTTP JSON source: an actual fetch implementation returning real
|
||||
* `Response` objects, paging by an opaque server token. The connector under
|
||||
* test does a genuine request/response cycle against it — the seam is the
|
||||
* transport, not the connector.
|
||||
*/
|
||||
function httpSourceFetch(): (url: string, init: RequestInit) => Promise<Response> {
|
||||
return async (url: string) => {
|
||||
const parsed = new URL(url);
|
||||
if (parsed.pathname.endsWith('/health')) {
|
||||
return new Response(JSON.stringify({ ok: true }), { status: 200 });
|
||||
}
|
||||
const cursor = parsed.searchParams.get('cursor');
|
||||
const limit = Number(parsed.searchParams.get('limit') ?? '100');
|
||||
const offset = cursor ? Number(cursor) : 0;
|
||||
const page = ROWS.slice(offset, offset + limit);
|
||||
const nextOffset = offset + page.length;
|
||||
return new Response(
|
||||
JSON.stringify({
|
||||
records: page,
|
||||
next_cursor: nextOffset < ROWS.length ? String(nextOffset) : undefined,
|
||||
}),
|
||||
{ status: 200, headers: { 'content-type': 'application/json' } },
|
||||
);
|
||||
};
|
||||
}
|
||||
|
||||
function jsonlSpec(overrides: Partial<AnalyticsIngestionSpec> = {}): AnalyticsIngestionSpec {
|
||||
return {
|
||||
source_id: 'src_jsonl',
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
mode: 'batch',
|
||||
provider: 'native',
|
||||
connector_ref: 'jsonl_file',
|
||||
config: {
|
||||
file_path: filePath,
|
||||
partition_key: 'companies',
|
||||
schema: SOURCE_SCHEMA,
|
||||
record_key_field: 'org_number',
|
||||
},
|
||||
target: target(),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function httpSpec(overrides: Partial<AnalyticsIngestionSpec> = {}): AnalyticsIngestionSpec {
|
||||
return {
|
||||
source_id: 'src_http',
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
mode: 'batch',
|
||||
provider: 'native',
|
||||
connector_ref: 'http_json',
|
||||
config: {
|
||||
base_url: 'http://source.invalid',
|
||||
records_path: '/v1/companies',
|
||||
partition_key: 'companies',
|
||||
schema: SOURCE_SCHEMA,
|
||||
record_key_field: 'org_number',
|
||||
record_cursor_field: 'org_number',
|
||||
health_path: '/health',
|
||||
},
|
||||
target: target({ dataset_id: 'ds_companies_raw' }),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
let repo: InMemoryIngestionRepository;
|
||||
let writer: InMemoryLandingWriter;
|
||||
let service: AnalyticsIngestionService;
|
||||
|
||||
function buildService(runtimeEnv = 'test'): AnalyticsIngestionService {
|
||||
repo = new InMemoryIngestionRepository();
|
||||
writer = new InMemoryLandingWriter();
|
||||
return new AnalyticsIngestionService({
|
||||
repo,
|
||||
schemas: new SchemaRegistry(repo),
|
||||
lineage: new LineageStore(repo),
|
||||
writer,
|
||||
runtimeEnv,
|
||||
});
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
service = buildService();
|
||||
});
|
||||
|
||||
// ── DoD: two real source types land in a canonical tier ────────────────────
|
||||
|
||||
describe('BI-P129 DoD — two real source types ingest into canonical analytics tiers', () => {
|
||||
it('source type 1 (JSONL file on disk) lands every row in the declared RAW tier', async () => {
|
||||
const result = await service.ingest(new NativeConnectorProvider(), jsonlSpec(), { page_size: 4 });
|
||||
|
||||
expect(result.run.status).toBe('succeeded');
|
||||
expect(writer.rowsLanded).toBe(ROWS.length);
|
||||
expect(writer.batches.every((b) => b.tier === 'RAW')).toBe(true);
|
||||
expect(writer.batches.every((b) => b.dataset_id === 'ds_companies_raw')).toBe(true);
|
||||
expect(writer.batches.every((b) => b.format === 'parquet')).toBe(true);
|
||||
expect(writer.batches.every((b) => b.namespace === 'analytics_raw')).toBe(true);
|
||||
// Paged: 4 + 4 + 1, so the tier landing is exercised across batches.
|
||||
expect(writer.batches.length).toBeGreaterThan(1);
|
||||
});
|
||||
|
||||
it('source type 2 (HTTP JSON API, opaque page token) lands every row in the same tier', async () => {
|
||||
const provider = new NativeConnectorProvider(httpSourceFetch());
|
||||
const result = await service.ingest(provider, httpSpec(), { page_size: 4 });
|
||||
|
||||
expect(result.run.status).toBe('succeeded');
|
||||
expect(writer.rowsLanded).toBe(ROWS.length);
|
||||
expect(writer.batches.every((b) => b.tier === 'RAW')).toBe(true);
|
||||
expect(new Set(writer.batches.flatMap((b) => b.envelope_ids)).size).toBe(ROWS.length);
|
||||
});
|
||||
|
||||
it('the two source types share no connector code — different ids, versions and cursor vocabulary', async () => {
|
||||
const nativeProvider = new NativeConnectorProvider(httpSourceFetch());
|
||||
const jsonl = nativeProvider.connectorFor(jsonlSpec());
|
||||
const http = nativeProvider.connectorFor(httpSpec());
|
||||
expect(jsonl.connector_id).toBe('jsonl_file');
|
||||
expect(http.connector_id).toBe('http_json');
|
||||
expect(jsonl.connector_version).not.toBe(http.connector_version);
|
||||
expect(Object.getPrototypeOf(jsonl)).not.toBe(Object.getPrototypeOf(http));
|
||||
});
|
||||
});
|
||||
|
||||
// ── gate 1: landing tier ───────────────────────────────────────────────────
|
||||
|
||||
describe('BI-P129 gate 1 — ingestion may not land directly in a derived tier', () => {
|
||||
it('WITH the guard: landing in SERVING is refused', () => {
|
||||
expect(() => assertLandingTierIngestible(target({ tier: 'SERVING' }))).toThrow(
|
||||
/may not land directly in SERVING/,
|
||||
);
|
||||
expect(() => assertLandingTierIngestible(target({ tier: 'CURATED' }))).toThrow(
|
||||
/may not land directly in CURATED/,
|
||||
);
|
||||
});
|
||||
|
||||
it('WITHOUT the guard: the same spec lands source rows into a dashboard-readable tier', async () => {
|
||||
// Counterfactual — the service is bypassed and the sink is called directly,
|
||||
// which is exactly what a provider that skipped the gate would do.
|
||||
const { landingSink } = await import('@/src/analytics/ingestion/landing');
|
||||
const bypassWriter = new InMemoryLandingWriter();
|
||||
const sink = landingSink({
|
||||
target: target({ tier: 'SERVING' }),
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
run_id: 'run_bypass',
|
||||
writer: bypassWriter,
|
||||
});
|
||||
await sink([
|
||||
{
|
||||
envelope_id: 'e1',
|
||||
source_id: 'src_jsonl',
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
mode: 'batch',
|
||||
operation: 'upsert',
|
||||
partition_key: 'companies',
|
||||
record_key: '1',
|
||||
schema_version: 1,
|
||||
sequence: 1,
|
||||
ingested_at: new Date().toISOString(),
|
||||
payload: { org_number: '1', name: 'x' },
|
||||
provenance: { connector_id: 'jsonl_file', connector_version: 'v1', run_id: 'run_bypass' },
|
||||
},
|
||||
]);
|
||||
// Raw source rows now sit in SERVING, which BI-P003 makes readable by
|
||||
// every dashboard with no exception recorded anywhere. That is the harm.
|
||||
expect(bypassWriter.batches[0].tier).toBe('SERVING');
|
||||
expect(bypassWriter.rowsLanded).toBe(1);
|
||||
});
|
||||
|
||||
it('NORMALIZED without a declared normalization is a RAW dataset wearing a label', () => {
|
||||
expect(() => assertLandingTierIngestible(target({ tier: 'NORMALIZED' }))).toThrow(
|
||||
/declares no normalization/,
|
||||
);
|
||||
expect(() =>
|
||||
assertLandingTierIngestible(
|
||||
target({ tier: 'NORMALIZED', normalization: 'typed + deduped on org_number' }),
|
||||
),
|
||||
).not.toThrow();
|
||||
// An all-whitespace declaration is not a declaration.
|
||||
expect(() => assertLandingTierIngestible(target({ tier: 'NORMALIZED', normalization: ' ' }))).toThrow(
|
||||
/declares no normalization/,
|
||||
);
|
||||
});
|
||||
|
||||
it('the service refuses a SERVING spec before it opens a session to the source', async () => {
|
||||
await expect(
|
||||
service.ingest(new NativeConnectorProvider(), jsonlSpec({ target: target({ tier: 'SERVING' }) })),
|
||||
).rejects.toThrow(/may not land directly in SERVING/);
|
||||
expect(writer.batches).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
// ── gate 2: contract covers what was discovered ────────────────────────────
|
||||
|
||||
describe('BI-P129 gate 2 — an undeclared source field is refused, not landed', () => {
|
||||
it('WITH the guard: a new undeclared column stops the run', () => {
|
||||
const drifted: RecordSchemaFields = {
|
||||
...SOURCE_SCHEMA,
|
||||
contact_email: { type: 'string', required: false },
|
||||
};
|
||||
expect(() => assertContractCoversDiscovery(CONTRACT, drifted)).toThrow(/undeclared_field/);
|
||||
expect(() => assertContractCoversDiscovery(CONTRACT, drifted)).toThrow(/contact_email/);
|
||||
});
|
||||
|
||||
it('the harm being prevented is named: an undeclared column is an unclassified column', () => {
|
||||
const problems = contractCoverageProblems(CONTRACT, {
|
||||
...SOURCE_SCHEMA,
|
||||
personnummer: { type: 'string', required: false },
|
||||
});
|
||||
expect(problems).toHaveLength(1);
|
||||
expect(problems[0].code).toBe('undeclared_field');
|
||||
expect(problems[0].detail).toMatch(/unclassified/);
|
||||
});
|
||||
|
||||
it('WITHOUT the guard: the drifted source lands and the PII column is invisible to the contract', async () => {
|
||||
const driftedFile = path.join(tmpDir, 'drifted.jsonl');
|
||||
await fs.writeFile(
|
||||
driftedFile,
|
||||
ROWS.map((r) => JSON.stringify({ ...r, personnummer: '19800101-1234' })).join('\n') + '\n',
|
||||
'utf8',
|
||||
);
|
||||
const driftedSchema: RecordSchemaFields = {
|
||||
...SOURCE_SCHEMA,
|
||||
personnummer: { type: 'string', required: false },
|
||||
};
|
||||
// Counterfactual: the runner alone (no analytics gate) happily lands it.
|
||||
const bypass = buildService();
|
||||
const bypassWriter = writer;
|
||||
const { IngestionRunner } = await import('@/src/ingestion/ingestion-runner');
|
||||
const { JsonlFileConnector } = await import('@/src/connectors/jsonl-file-connector');
|
||||
const { landingSink } = await import('@/src/analytics/ingestion/landing');
|
||||
const runner = new IngestionRunner(repo, new SchemaRegistry(repo));
|
||||
const landed: Array<Record<string, unknown> | null> = [];
|
||||
const report = await runner.run({
|
||||
source_id: 'src_drift',
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
mode: 'batch',
|
||||
connector: new JsonlFileConnector(),
|
||||
config: {
|
||||
file_path: driftedFile,
|
||||
partition_key: 'companies',
|
||||
schema: driftedSchema,
|
||||
record_key_field: 'org_number',
|
||||
},
|
||||
sink: async (envelopes) => {
|
||||
for (const e of envelopes) landed.push(e.payload);
|
||||
await landingSink({
|
||||
target: target(),
|
||||
tenant_id: 't_test',
|
||||
project_id: 'p_test',
|
||||
run_id: 'run_drift',
|
||||
writer: bypassWriter,
|
||||
})(envelopes);
|
||||
},
|
||||
});
|
||||
expect(report.status).toBe('succeeded');
|
||||
expect(landed).toHaveLength(ROWS.length);
|
||||
// The personal number is now sitting in a RAW table whose contract says
|
||||
// pii_classification: "none". Nothing else in the pipeline notices.
|
||||
expect(landed[0]).toHaveProperty('personnummer');
|
||||
expect(CONTRACT.pii_classification).toBe('none');
|
||||
void bypass;
|
||||
});
|
||||
|
||||
it('a type mismatch and a missing required field are both refused', () => {
|
||||
expect(() =>
|
||||
assertContractCoversDiscovery(CONTRACT, {
|
||||
...SOURCE_SCHEMA,
|
||||
employees: { type: 'string', required: false },
|
||||
}),
|
||||
).toThrow(/type_mismatch/);
|
||||
const { org_number: _dropped, ...withoutKey } = SOURCE_SCHEMA;
|
||||
expect(() => assertContractCoversDiscovery(CONTRACT, withoutKey)).toThrow(/missing_required_field/);
|
||||
});
|
||||
|
||||
it('a source field that is optional where the contract says NOT NULL is refused', () => {
|
||||
const problems = contractCoverageProblems(CONTRACT, {
|
||||
...SOURCE_SCHEMA,
|
||||
name: { type: 'string', required: false },
|
||||
});
|
||||
expect(problems.map((p) => p.code)).toContain('nullability_mismatch');
|
||||
});
|
||||
|
||||
it('discovery with no partitions is refused rather than reported as a clean empty run', () => {
|
||||
expect(() => assertDiscoveryLandable(target(), {})).toThrow(/discovered no partitions/);
|
||||
});
|
||||
|
||||
it('the live path runs gate 2 against what the connector actually discovered', async () => {
|
||||
// The contract is fine for the file; narrow the CONTRACT instead so the
|
||||
// real discovery result is what fails the gate.
|
||||
const narrow: DatasetContract = { ...CONTRACT, fields: CONTRACT.fields.slice(0, 2) };
|
||||
await expect(
|
||||
service.ingest(new NativeConnectorProvider(), jsonlSpec({ target: target({ contract: narrow }) })),
|
||||
).rejects.toThrow(/undeclared_field/);
|
||||
expect(writer.batches).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
// ── gate 3: physical home ──────────────────────────────────────────────────
|
||||
|
||||
describe('BI-P129 gate 3 — RAW/NORMALIZED land as Parquet/Iceberg in ST0RE', () => {
|
||||
it('a ClickHouse landing is refused', () => {
|
||||
expect(() =>
|
||||
assertPhysicalHomeMatchesTier(
|
||||
target({ physical: { format: 'clickhouse' as never, namespace: 'n', table_name: 't' } }),
|
||||
),
|
||||
).toThrow(/not a lakehouse format/);
|
||||
});
|
||||
|
||||
it('iceberg and parquet are both accepted; a nameless table is not', () => {
|
||||
expect(() =>
|
||||
assertPhysicalHomeMatchesTier(
|
||||
target({ physical: { format: 'iceberg', namespace: 'n', table_name: 't' } }),
|
||||
),
|
||||
).not.toThrow();
|
||||
expect(() =>
|
||||
assertPhysicalHomeMatchesTier(
|
||||
target({ physical: { format: 'parquet', namespace: ' ', table_name: 't' } }),
|
||||
),
|
||||
).toThrow(/missing a ST0RE namespace/);
|
||||
});
|
||||
});
|
||||
|
||||
// ── gate 4: unverified providers ───────────────────────────────────────────
|
||||
|
||||
class UnverifiedProvider implements AnalyticsConnectorProvider {
|
||||
readonly provider = 'dlt' as const;
|
||||
providerReadiness() {
|
||||
return {
|
||||
provider: 'dlt',
|
||||
pinned_version: '0.0.0',
|
||||
verified: false,
|
||||
proven: [],
|
||||
open: ['nothing has been executed'],
|
||||
};
|
||||
}
|
||||
validateSpec() {
|
||||
return { valid: true, errors: [] };
|
||||
}
|
||||
connectorFor(): never {
|
||||
throw new Error('not used in this test');
|
||||
}
|
||||
executionPlan() {
|
||||
return { runtime: 'n0d' as const, reason: 'test' };
|
||||
}
|
||||
}
|
||||
|
||||
describe('BI-P129 gate 4 — an unverified provider cannot quietly become production capability', () => {
|
||||
const provider = new UnverifiedProvider();
|
||||
const spec = jsonlSpec({ provider: 'dlt', connector_ref: 'whatever' });
|
||||
|
||||
it('WITH the guard: production refuses an unverified provider', () => {
|
||||
expect(() => assertProviderRunnable(provider, spec, 'production')).toThrow(SiaxError);
|
||||
expect(() => assertProviderRunnable(provider, spec, 'production')).toThrow(/verified: false/);
|
||||
});
|
||||
|
||||
it('WITHOUT the guard (non-production runtime): the same provider is allowed to plan', () => {
|
||||
expect(() => assertProviderRunnable(provider, spec, 'staging')).not.toThrow();
|
||||
});
|
||||
|
||||
it('a recorded, named exception unblocks production — and is required to be non-empty', () => {
|
||||
expect(() =>
|
||||
assertProviderRunnable(provider, { ...spec, unverified_provider_exception: ' ' }, 'production'),
|
||||
).toThrow(/unverified_provider_exception/);
|
||||
expect(() =>
|
||||
assertProviderRunnable(
|
||||
provider,
|
||||
{
|
||||
...spec,
|
||||
unverified_provider_exception: 'accepted by simon@siax.io 2026-09-07 for a bounded backfill',
|
||||
},
|
||||
'production',
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('the native provider is verified, so it needs no exception in production', () => {
|
||||
expect(() =>
|
||||
assertProviderRunnable(new NativeConnectorProvider(), jsonlSpec(), 'production'),
|
||||
).not.toThrow();
|
||||
expect(new NativeConnectorProvider().providerReadiness().verified).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ── licence boundary + registry ────────────────────────────────────────────
|
||||
|
||||
describe('BI-P129 — Airbyte is a declared kind with no acceptance in this estate', () => {
|
||||
it('registering an airbyte provider is refused at the registry', () => {
|
||||
const registry = new ConnectorProviderRegistry();
|
||||
const fake = { ...new UnverifiedProvider(), provider: 'airbyte' as const };
|
||||
expect(() => registry.register(fake as unknown as AnalyticsConnectorProvider)).toThrow(
|
||||
/no licence\/architecture acceptance/,
|
||||
);
|
||||
});
|
||||
|
||||
it('planning an airbyte ingestion is refused even if a provider object is supplied directly', () => {
|
||||
const fake = {
|
||||
...new UnverifiedProvider(),
|
||||
provider: 'airbyte' as const,
|
||||
} as unknown as AnalyticsConnectorProvider;
|
||||
expect(() => planAnalyticsIngestion(fake, jsonlSpec({ provider: 'airbyte' }), 'test')).toThrow(
|
||||
/licence\/architecture acceptance/,
|
||||
);
|
||||
});
|
||||
|
||||
it('the registry refuses duplicates and unknown kinds, and reports readiness for what it has', () => {
|
||||
const registry = new ConnectorProviderRegistry();
|
||||
registry.register(new NativeConnectorProvider());
|
||||
expect(() => registry.register(new NativeConnectorProvider())).toThrow(/already registered/);
|
||||
expect(() => registry.get('singer')).toThrow(/no connector provider registered/);
|
||||
expect(registry.readinessReport().map((r) => r.provider)).toEqual(['native']);
|
||||
});
|
||||
|
||||
it('a provider handed a spec for a different kind is refused', () => {
|
||||
expect(() =>
|
||||
planAnalyticsIngestion(new NativeConnectorProvider(), jsonlSpec({ provider: 'dlt' }), 'test'),
|
||||
).toThrow(/asks for provider "dlt"/);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,54 @@
|
||||
/**
|
||||
* The canonical BI-P005 fixture, in one place.
|
||||
*
|
||||
* Two jobs:
|
||||
* 1. assert the encoder is DETERMINISTIC — the same columns must produce
|
||||
* byte-identical output, or the "roundtrip" evidence would be comparing
|
||||
* two different payloads run to run;
|
||||
* 2. when ARROW_FIXTURE_DIR is set, write those exact bytes to disk so
|
||||
* scripts/bi-p005-arrow-roundtrip.mjs hands pyarrow and DuckDB the bytes
|
||||
* the SHIPPED module produces, not a copy of the encoder living in a
|
||||
* script.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import crypto from 'node:crypto';
|
||||
import { type ArrowColumn, encodeArrowStream } from '@/src/analytics/arrow/ipc';
|
||||
|
||||
/** The same three rows the ClickHouse side of the DoD produces. */
|
||||
export const BI_P005_FIXTURE: ArrowColumn[] = [
|
||||
{ name: 'tenant_id', type: 'utf8', values: ['t_alpha', 't_beta', 't_gamma'] },
|
||||
{ name: 'n', type: 'int64', values: [1, 2, 3] },
|
||||
{ name: 'v', type: 'float64', values: [1.5, 2.5, 3.25] },
|
||||
{ name: 'flag', type: 'bool', values: [true, false, true] },
|
||||
{
|
||||
name: 'ts',
|
||||
type: 'timestamp_ms',
|
||||
values: [
|
||||
new Date('2026-01-01T00:00:00.000Z'),
|
||||
new Date('2026-06-15T08:09:10.123Z'),
|
||||
new Date('2026-09-06T12:34:56.789Z'),
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
describe('BI-P005 canonical Arrow fixture', () => {
|
||||
it('encodes deterministically', () => {
|
||||
const a = encodeArrowStream(BI_P005_FIXTURE);
|
||||
const b = encodeArrowStream(BI_P005_FIXTURE);
|
||||
expect(Buffer.from(a).equals(Buffer.from(b))).toBe(true);
|
||||
expect(a.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('writes the fixture for the external roundtrip when asked', () => {
|
||||
const dir = process.env.ARROW_FIXTURE_DIR;
|
||||
if (!dir) return; // not an error: the normal test run has nowhere to put it
|
||||
const bytes = encodeArrowStream(BI_P005_FIXTURE);
|
||||
const out = path.join(dir, '02_0pt_encoded.arrow');
|
||||
fs.writeFileSync(out, bytes);
|
||||
expect(fs.statSync(out).size).toBe(bytes.length);
|
||||
// Print the digest so the evidence file can be tied to these exact bytes.
|
||||
console.log(`ARROW_FIXTURE_SHA256=${crypto.createHash('sha256').update(bytes).digest('hex')}`);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,107 @@
|
||||
/**
|
||||
* BI-P005 — APACHE ARROW INTERCHANGE, the part provable without a live engine.
|
||||
*
|
||||
* Honest scope note: the tests here run 0pt's encoder against 0pt's decoder,
|
||||
* which proves internal consistency and NOT specification conformance. The
|
||||
* conformance evidence comes from two places where an INDEPENDENT
|
||||
* implementation reads the bytes:
|
||||
*
|
||||
* * tests/integration/analytics-arrow-clickhouse.integration.test.ts —
|
||||
* ClickHouse (Arrow C++) both produces Arrow this decoder reads and
|
||||
* consumes Arrow this encoder writes. Runs on every push in CI.
|
||||
* * evidence/bi-p002-p012/bi-p005-arrow-roundtrip.json — pyarrow and DuckDB
|
||||
* decoding the same bytes, executed against real containers.
|
||||
*
|
||||
* That distinction is the point: a self-roundtrip that agrees with its own
|
||||
* mistakes is exactly the kind of green this estate has been burned by.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
ARROW_TYPE_SUPPORT,
|
||||
arrowStreamSettings,
|
||||
assertArrowWithinResultBudget,
|
||||
clickhouseArrowStreamFormat,
|
||||
decodeArrowStream,
|
||||
encodeArrowStream,
|
||||
} from '@/src/analytics/arrow/ipc';
|
||||
|
||||
describe('BI-P005 Arrow IPC', () => {
|
||||
it('emits a well-formed IPC stream: continuation markers, schema, batch, EOS', () => {
|
||||
const bytes = encodeArrowStream([{ name: 'n', type: 'int64', values: [1, 2, 3] }]);
|
||||
const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
||||
expect(dv.getUint32(0, true)).toBe(0xffffffff);
|
||||
// Last 8 bytes are the end-of-stream marker: 0xFFFFFFFF then length 0.
|
||||
expect(dv.getUint32(bytes.length - 8, true)).toBe(0xffffffff);
|
||||
expect(dv.getInt32(bytes.length - 4, true)).toBe(0);
|
||||
});
|
||||
|
||||
it('round-trips every supported column type with nulls', () => {
|
||||
const bytes = encodeArrowStream([
|
||||
{ name: 'tenant_id', type: 'utf8', values: ['t_alpha', 't_beta', null] },
|
||||
{ name: 'n', type: 'int64', values: [1, 2, 3] },
|
||||
{ name: 'v', type: 'float64', values: [1.5, 2.5, null] },
|
||||
{ name: 'flag', type: 'bool', values: [true, false, true] },
|
||||
{
|
||||
name: 'ts',
|
||||
type: 'timestamp_ms',
|
||||
values: [new Date('2026-01-01T00:00:00Z'), null, new Date('2026-09-06T12:34:56.789Z')],
|
||||
},
|
||||
]);
|
||||
const info = decodeArrowStream(bytes);
|
||||
expect(info.rowCount).toBe(3);
|
||||
expect(info.batchCount).toBe(1);
|
||||
expect(info.fields.map((f) => f.name)).toEqual(['tenant_id', 'n', 'v', 'flag', 'ts']);
|
||||
// Arrow Type union tags: Int=2, FloatingPoint=3, Utf8=5, Bool=6, Timestamp=10.
|
||||
expect(info.fields.map((f) => f.typeType)).toEqual([5, 2, 3, 6, 10]);
|
||||
});
|
||||
|
||||
it('handles an empty result set without producing a malformed stream', () => {
|
||||
const bytes = encodeArrowStream([{ name: 'n', type: 'int64', values: [] }]);
|
||||
const info = decodeArrowStream(bytes);
|
||||
expect(info.rowCount).toBe(0);
|
||||
expect(info.fields).toEqual([{ name: 'n', typeType: 2 }]);
|
||||
});
|
||||
|
||||
it('rejects ragged columns rather than emitting a stream that decodes to garbage', () => {
|
||||
expect(() =>
|
||||
encodeArrowStream([
|
||||
{ name: 'a', type: 'int64', values: [1, 2] },
|
||||
{ name: 'b', type: 'int64', values: [1] },
|
||||
]),
|
||||
).toThrowError(/expected 2/);
|
||||
expect(() => encodeArrowStream([])).toThrowError(/at least one column/);
|
||||
});
|
||||
|
||||
it('refuses an int64 value outside the representable range instead of wrapping it', () => {
|
||||
expect(() =>
|
||||
encodeArrowStream([{ name: 'n', type: 'int64', values: [BigInt('9223372036854775808')] }]),
|
||||
).toThrowError(/out of int64 range/);
|
||||
});
|
||||
|
||||
it('rejects bytes that are not an Arrow IPC stream', () => {
|
||||
expect(() => decodeArrowStream(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]))).toThrowError(
|
||||
/not an Arrow IPC stream/,
|
||||
);
|
||||
});
|
||||
|
||||
it('BI-P012: Arrow is not a way around max_result_rows', () => {
|
||||
const bytes = encodeArrowStream([{ name: 'n', type: 'int64', values: [1, 2, 3, 4, 5] }]);
|
||||
expect(() => assertArrowWithinResultBudget(bytes, 3)).toThrowError(/over the 3-row budget/);
|
||||
expect(assertArrowWithinResultBudget(bytes, 5).rowCount).toBe(5);
|
||||
});
|
||||
|
||||
it('the ClickHouse pass-through asks for text Strings, not Binary', () => {
|
||||
expect(clickhouseArrowStreamFormat()).toBe('ArrowStream');
|
||||
// Without this setting ClickHouse emits String as Arrow Binary, which
|
||||
// pyarrow and DuckDB read as bytes — silent semantic loss.
|
||||
expect(arrowStreamSettings().output_format_arrow_string_as_string).toBe('1');
|
||||
});
|
||||
|
||||
it('documents the supported type mapping including where loss WOULD occur', () => {
|
||||
expect(ARROW_TYPE_SUPPORT.length).toBeGreaterThanOrEqual(5);
|
||||
const arrowTypes = ARROW_TYPE_SUPPORT.map((r) => r.arrow);
|
||||
expect(new Set(arrowTypes)).toEqual(new Set(['int64', 'float64', 'utf8', 'bool', 'timestamp_ms']));
|
||||
// Every row states its caveat; an empty note would be a silent promise.
|
||||
for (const row of ARROW_TYPE_SUPPORT) expect(row.note.length).toBeGreaterThan(10);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,194 @@
|
||||
/**
|
||||
* tests/analytics/benchmark-harness.test.ts
|
||||
* ==========================================
|
||||
* BI-P104 — the harness's job is to stop a benchmark from lying.
|
||||
*
|
||||
* The tests are therefore attacks on the reporting, not on the timing:
|
||||
*
|
||||
* - two overlapping distributions whose MEDIANS differ 2x must come back
|
||||
* `indistinguishable`, because that is the claim a noisy host manufactures;
|
||||
* - the real 150x/130x pair from yesterday's budget-enforcement lane is fed
|
||||
* in as data, and the harness must describe a RANGE rather than pick one;
|
||||
* - a three-sample run must refuse to be compared at all;
|
||||
* - every sentence `describeComparison` produces must carry the range, the
|
||||
* sample size and the stability, so it cannot be quoted as a bare figure;
|
||||
* - an engine that was not run must appear in the evidence with a reason.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
BENCH_ENGINES,
|
||||
buildEvidence,
|
||||
compareDistributions,
|
||||
describeComparison,
|
||||
measure,
|
||||
MIN_SAMPLES,
|
||||
summarizeSamples,
|
||||
} from '@/src/analytics/bench/benchmark-harness';
|
||||
|
||||
describe('BI-P104 distribution summary', () => {
|
||||
it('reports the shape, and never a single number', () => {
|
||||
const d = summarizeSamples([10, 11, 12, 13, 14, 15, 16, 40]);
|
||||
expect(d.n).toBe(8);
|
||||
expect(d.min).toBe(10);
|
||||
expect(d.max).toBe(40);
|
||||
expect(d.p50).toBe(13);
|
||||
expect(d.spread_ratio).toBe(4);
|
||||
expect(d.cv).toBeGreaterThan(0);
|
||||
// Every field a reader needs to judge the p50 is present next to it.
|
||||
for (const key of [
|
||||
'min',
|
||||
'p50',
|
||||
'p95',
|
||||
'p99',
|
||||
'max',
|
||||
'stdev',
|
||||
'cv',
|
||||
'iqr',
|
||||
'spread_ratio',
|
||||
'stability',
|
||||
]) {
|
||||
expect(Object.keys(d)).toContain(key);
|
||||
}
|
||||
});
|
||||
|
||||
it('calls a tight run stable and a spread run unstable', () => {
|
||||
expect(summarizeSamples([100, 101, 99, 100, 102, 98, 100]).stability).toBe('stable');
|
||||
expect(summarizeSamples([10, 200, 15, 400, 12, 350, 11]).stability).toBe('unstable');
|
||||
});
|
||||
|
||||
it('refuses to characterise fewer than MIN_SAMPLES', () => {
|
||||
const d = summarizeSamples([10, 11, 12]);
|
||||
expect(d.n).toBe(3);
|
||||
expect(d.stability).toBe('insufficient_samples');
|
||||
expect(MIN_SAMPLES).toBeGreaterThan(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P104 comparison — variance beats a flattering median', () => {
|
||||
it('overlapping ranges are INDISTINGUISHABLE even when medians differ 2x', () => {
|
||||
const baseline = summarizeSamples([50, 60, 200, 70, 300, 55, 65, 280]);
|
||||
const candidate = summarizeSamples([25, 30, 190, 35, 260, 28, 33, 240]);
|
||||
const c = compareDistributions(baseline, candidate);
|
||||
|
||||
expect(c.p50_ratio).toBeGreaterThan(1.5); // the tempting headline
|
||||
expect(c.ranges_overlap).toBe(true);
|
||||
expect(c.verdict).toBe('indistinguishable'); // the honest verdict
|
||||
expect(describeComparison(c)).toMatch(/INDISTINGUISHABLE/);
|
||||
});
|
||||
|
||||
it('clean separation is reported as faster, WITH the range', () => {
|
||||
const baseline = summarizeSamples([500, 520, 510, 530, 505, 515, 525]);
|
||||
const candidate = summarizeSamples([50, 55, 52, 58, 51, 53, 54]);
|
||||
const c = compareDistributions(baseline, candidate);
|
||||
|
||||
expect(c.verdict).toBe('faster');
|
||||
const sentence = describeComparison(c, 'pre-aggregate');
|
||||
expect(sentence).toMatch(/FASTER/);
|
||||
expect(sentence).toMatch(/x to /); // a range, not a number
|
||||
expect(sentence).toMatch(/n=7\/7/); // sample sizes
|
||||
expect(sentence).toMatch(/stability/);
|
||||
});
|
||||
|
||||
it('the real 150x / 130x overshoot pair is described as a range, not a figure', () => {
|
||||
// Two runs of the same measurement on the same machine, from the BI-P021
|
||||
// budget-enforcement lane. A harness that picks one of these is lying.
|
||||
const overshoot = summarizeSamples([153, 131, 149, 128, 144, 137, 152, 126, 141]);
|
||||
|
||||
// Worth being precise about: by the CV test this run is STABLE (0.07). The
|
||||
// problem was never instability — it is that a stable run still spans
|
||||
// 126x-153x, so any single figure quoted from it is ~20% wrong. The
|
||||
// harness's answer is to keep the ends attached to the middle.
|
||||
expect(overshoot.stability).toBe('stable');
|
||||
expect(overshoot.min).toBe(126);
|
||||
expect(overshoot.p50).toBe(141);
|
||||
expect(overshoot.max).toBe(153);
|
||||
expect(overshoot.spread_ratio).toBeCloseTo(1.21, 2);
|
||||
|
||||
const sentence = describeComparison(
|
||||
compareDistributions(summarizeSamples([1, 1, 1, 1, 1, 1, 1, 1, 1]), overshoot),
|
||||
'budget overshoot factor',
|
||||
);
|
||||
expect(sentence).toMatch(/x to /); // a range survives into the prose
|
||||
expect(sentence).toMatch(/n=9\/9/);
|
||||
});
|
||||
|
||||
it('a three-sample run cannot be compared at all', () => {
|
||||
const c = compareDistributions(summarizeSamples([10, 11, 12]), summarizeSamples([1, 2, 3]));
|
||||
expect(c.verdict).toBe('not_comparable');
|
||||
expect(describeComparison(c)).toMatch(/anecdote/);
|
||||
});
|
||||
|
||||
it('slower is reported as slower — the harness has no favourite', () => {
|
||||
const baseline = summarizeSamples([50, 51, 52, 53, 54, 55, 56]);
|
||||
const candidate = summarizeSamples([500, 510, 520, 530, 540, 550, 560]);
|
||||
expect(compareDistributions(baseline, candidate).verdict).toBe('slower');
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P104 measurement', () => {
|
||||
it('records warmups but excludes them from the statistics', async () => {
|
||||
let call = 0;
|
||||
let clock = 0;
|
||||
const run = await measure({
|
||||
engine: 'duckdb',
|
||||
dataset: 'small_saas',
|
||||
query_label: 'group by day',
|
||||
warmups: 2,
|
||||
repetitions: 6,
|
||||
// A cold first pair (1000ms) then a warm steady state (10ms).
|
||||
now: () => {
|
||||
const t = clock;
|
||||
clock += call <= 2 ? 1000 : 10;
|
||||
call += 1;
|
||||
return t;
|
||||
},
|
||||
run: async () => ({ rows: 42 }),
|
||||
});
|
||||
|
||||
expect(run.warmup_ms).toHaveLength(2);
|
||||
expect(run.samples_ms).toHaveLength(6);
|
||||
expect(run.distribution.n).toBe(6);
|
||||
expect(run.distribution.max).toBeLessThan(1000); // the cold pair is not in it
|
||||
expect(run.rows_returned).toBe(42);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P104 evidence', () => {
|
||||
it('lists every engine BI-P104 names, and says why the unrun ones were not run', () => {
|
||||
const evidence = buildEvidence({
|
||||
host_note: 'one idle host, warm cache',
|
||||
engines: [
|
||||
{ engine: 'clickhouse', available: true, version: '26.3' },
|
||||
{ engine: 'duckdb', available: true, version: '1.5.5' },
|
||||
{ engine: 'trino', available: false, reason: 'the running Trino belongs to another lane' },
|
||||
],
|
||||
runs: [
|
||||
{
|
||||
engine: 'clickhouse',
|
||||
dataset: 'small_saas',
|
||||
query_label: 'q',
|
||||
warmup_ms: [1],
|
||||
samples_ms: [1, 2, 3, 4, 5],
|
||||
distribution: summarizeSamples([1, 2, 3, 4, 5]),
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
expect(evidence.engines.map((e) => e.engine)).toEqual([...BENCH_ENGINES]);
|
||||
const notRun = evidence.not_exercised.map((e) => e.engine);
|
||||
expect(notRun).toContain('superset');
|
||||
expect(notRun).toContain('perspective');
|
||||
expect(notRun).toContain('duckdb'); // declared available but produced no run
|
||||
for (const e of evidence.not_exercised) {
|
||||
expect(e.reason, e.engine).toBeTruthy();
|
||||
}
|
||||
expect(evidence.datasets.map((d) => d.id)).toEqual([
|
||||
'small_saas',
|
||||
'medium_business',
|
||||
'vehiq_market',
|
||||
'large_event',
|
||||
'wide_table',
|
||||
'geospatial',
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,293 @@
|
||||
/**
|
||||
* tests/analytics/bi-slo.test.ts
|
||||
* ===============================
|
||||
* BI-P103 — BI SLO, and the AUD0 usage events it is measured from.
|
||||
*
|
||||
* Two failure modes are attacked directly, because both look like a healthy
|
||||
* dashboard:
|
||||
*
|
||||
* 1. AN SLO REPORT OVER SILENCE. Zero events must not read as 100%
|
||||
* availability. Every objective in an empty window must come back
|
||||
* `insufficient_data`, and `fully_measured` must be false.
|
||||
* 2. A PRODUCER THAT LEAKS. The emitter is handed an execution record
|
||||
* carrying SQL text, a database error message quoting a personnummer,
|
||||
* filter VALUES, a tenant id and a result sample — everything AUD0's
|
||||
* BI-P076 ingest exists to refuse — and none of it may appear in any
|
||||
* emitted payload. The test greps the serialized events, and first
|
||||
* proves the grep finds those strings in the INPUT so a clean result
|
||||
* cannot be a broken detector.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
BI_SLO_CATALOGUE,
|
||||
evaluateBiSlos,
|
||||
percentile,
|
||||
summariseSloReport,
|
||||
type SloResult,
|
||||
} from '@/src/analytics/slo/bi-slo';
|
||||
import {
|
||||
biUsageEventsForExecution,
|
||||
EMITTABLE_PAYLOAD_KEYS,
|
||||
type Aud0BiEvent,
|
||||
type ExecutionTelemetry,
|
||||
} from '@/src/analytics/slo/usage-events';
|
||||
|
||||
const FROM = new Date('2026-09-07T00:00:00.000Z');
|
||||
const TO = new Date('2026-09-07T23:59:59.000Z');
|
||||
|
||||
function queryEvents(args: {
|
||||
n: number;
|
||||
surface: 'dashboard' | 'explore';
|
||||
outcome: 'completed' | 'failed' | 'running';
|
||||
durationMs: (i: number) => number;
|
||||
cacheHit?: boolean;
|
||||
idPrefix?: string;
|
||||
}): Aud0BiEvent[] {
|
||||
const out: Aud0BiEvent[] = [];
|
||||
for (let i = 0; i < args.n; i += 1) {
|
||||
const t: ExecutionTelemetry = {
|
||||
query_id: `${args.idPrefix ?? args.surface}_${i}`,
|
||||
surface: args.surface,
|
||||
state: args.outcome === 'completed' ? 'succeeded' : args.outcome === 'failed' ? 'failed' : 'running',
|
||||
started_at: new Date(FROM.getTime() + i * 1000).toISOString(),
|
||||
finished_at: new Date(FROM.getTime() + i * 1000 + args.durationMs(i)).toISOString(),
|
||||
duration_ms: args.durationMs(i),
|
||||
...(args.cacheHit !== undefined ? { cache_hit: args.cacheHit } : {}),
|
||||
...(args.outcome === 'failed' ? { error_code: 'TIMEOUT' } : {}),
|
||||
};
|
||||
out.push(...biUsageEventsForExecution(t));
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function byId(results: SloResult[], id: string): SloResult {
|
||||
const r = results.find((x) => x.objective_id === id);
|
||||
if (!r) throw new Error(`no result for ${id}`);
|
||||
return r;
|
||||
}
|
||||
|
||||
describe('BI-P103 — an SLO over silence is not a met SLO', () => {
|
||||
it('an empty window makes every measurable objective insufficient_data, never 100%', () => {
|
||||
const report = evaluateBiSlos({ events: [], from: FROM, to: TO });
|
||||
expect(report.fully_measured).toBe(false);
|
||||
for (const r of report.results) {
|
||||
expect(['insufficient_data', 'not_measurable_here']).toContain(r.status);
|
||||
expect(r.status).not.toBe('met');
|
||||
}
|
||||
const summary = summariseSloReport(report);
|
||||
expect(summary.met).toBe(0);
|
||||
expect(summary.measured_fraction).toBe(0);
|
||||
});
|
||||
|
||||
it('a started query that never finished is unresolved, not a success', () => {
|
||||
const events = queryEvents({ n: 200, surface: 'dashboard', outcome: 'running', durationMs: () => 100 });
|
||||
const report = evaluateBiSlos({ events, from: FROM, to: TO });
|
||||
expect(report.unresolved_queries).toBe(200);
|
||||
expect(byId(report.results, 'dash.availability').status).toBe('insufficient_data');
|
||||
expect(byId(report.results, 'dash.availability').observed).toBeUndefined();
|
||||
});
|
||||
|
||||
it('a percentile below min_samples is reported WITH its sample size and not judged', () => {
|
||||
const events = queryEvents({
|
||||
n: 12,
|
||||
surface: 'explore',
|
||||
outcome: 'completed',
|
||||
durationMs: (i) => 1000 + i * 10,
|
||||
});
|
||||
const p99 = byId(evaluateBiSlos({ events, from: FROM, to: TO }).results, 'explore.p99');
|
||||
expect(p99.status).toBe('insufficient_data');
|
||||
expect(p99.low_confidence).toBe(true);
|
||||
expect(p99.sample_size).toBe(12);
|
||||
expect(p99.observed).toBeDefined(); // reported…
|
||||
expect(p99.detail).toMatch(/not a percentile/); // …with the caveat attached
|
||||
});
|
||||
|
||||
it('freshness and delivery are declared not_measurable_here rather than proxied', () => {
|
||||
const report = evaluateBiSlos({ events: [], from: FROM, to: TO });
|
||||
const freshness = byId(report.results, 'dash.freshness');
|
||||
const delivery = byId(report.results, 'report.delivery_sla');
|
||||
expect(freshness.status).toBe('not_measurable_here');
|
||||
expect(freshness.detail).toMatch(/analytics_freshness_watermark/);
|
||||
expect(delivery.status).toBe('not_measurable_here');
|
||||
expect(delivery.detail).toMatch(/n0tify_delivery_receipt/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P103 — real measurement from real events', () => {
|
||||
it('computes availability, error rate and both dashboard latencies', () => {
|
||||
const events = [
|
||||
...queryEvents({
|
||||
n: 180,
|
||||
surface: 'dashboard',
|
||||
outcome: 'completed',
|
||||
cacheHit: false,
|
||||
durationMs: (i) => 500 + i * 10,
|
||||
idPrefix: 'cold',
|
||||
}),
|
||||
...queryEvents({
|
||||
n: 120,
|
||||
surface: 'dashboard',
|
||||
outcome: 'completed',
|
||||
cacheHit: true,
|
||||
durationMs: () => 120,
|
||||
idPrefix: 'warm',
|
||||
}),
|
||||
...queryEvents({
|
||||
n: 3,
|
||||
surface: 'dashboard',
|
||||
outcome: 'failed',
|
||||
durationMs: () => 900,
|
||||
idPrefix: 'bad',
|
||||
}),
|
||||
];
|
||||
const { results } = evaluateBiSlos({ events, from: FROM, to: TO });
|
||||
|
||||
const availability = byId(results, 'dash.availability');
|
||||
expect(availability.sample_size).toBe(303);
|
||||
expect(availability.observed).toBeCloseTo(300 / 303, 6);
|
||||
expect(availability.status).toBe('breached'); // 0.9901 < 0.995 target
|
||||
|
||||
const errorRate = byId(results, 'dash.error_rate');
|
||||
expect(errorRate.observed).toBeCloseTo(3 / 303, 6);
|
||||
|
||||
const cold = byId(results, 'dash.p95_first_query');
|
||||
expect(cold.sample_size).toBe(183); // 180 cold + 3 failures, which had no cache hit
|
||||
expect(cold.status).toBe('met');
|
||||
|
||||
const cached = byId(results, 'dash.p95_cached');
|
||||
expect(cached.sample_size).toBe(120);
|
||||
expect(cached.observed).toBe(120);
|
||||
expect(cached.status).toBe('met');
|
||||
});
|
||||
|
||||
it('a breach is reported as a breach', () => {
|
||||
const events = queryEvents({
|
||||
n: 60,
|
||||
surface: 'dashboard',
|
||||
outcome: 'completed',
|
||||
cacheHit: false,
|
||||
durationMs: () => 9000,
|
||||
});
|
||||
expect(
|
||||
byId(evaluateBiSlos({ events, from: FROM, to: TO }).results, 'dash.p95_first_query'),
|
||||
).toMatchObject({ status: 'breached', observed: 9000 });
|
||||
});
|
||||
|
||||
it('events outside the window do not count', () => {
|
||||
const events = queryEvents({ n: 200, surface: 'dashboard', outcome: 'completed', durationMs: () => 100 });
|
||||
const report = evaluateBiSlos({
|
||||
events,
|
||||
from: new Date('2026-09-08T00:00:00.000Z'),
|
||||
to: new Date('2026-09-08T23:59:59.000Z'),
|
||||
});
|
||||
expect(byId(report.results, 'dash.availability').status).toBe('insufficient_data');
|
||||
});
|
||||
|
||||
it('percentile is nearest-rank — it never invents a value nobody experienced', () => {
|
||||
const sample = [10, 20, 30, 40];
|
||||
expect(percentile(sample, 0.95)).toBe(40);
|
||||
expect(percentile(sample, 0.5)).toBe(20);
|
||||
expect(percentile([], 0.95)).toBeUndefined();
|
||||
});
|
||||
|
||||
it('the catalogue covers all three workload classes and every field BI-P103 names', () => {
|
||||
const kinds = new Set(BI_SLO_CATALOGUE.map((o) => `${o.workload}:${o.kind}`));
|
||||
for (const expected of [
|
||||
'interactive_dashboard:availability',
|
||||
'interactive_dashboard:latency_p95_first',
|
||||
'interactive_dashboard:latency_p95_cached',
|
||||
'interactive_dashboard:error_rate',
|
||||
'interactive_dashboard:freshness',
|
||||
'exploration:latency_p95',
|
||||
'exploration:latency_p99',
|
||||
'exploration:max_result_rows',
|
||||
'exploration:timeout',
|
||||
'report:completion_sla',
|
||||
'report:delivery_sla',
|
||||
]) {
|
||||
expect(kinds.has(expected), expected).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P103 — the producer cannot leak a result into AUD0', () => {
|
||||
const hostile: ExecutionTelemetry = {
|
||||
query_id: 'q_1',
|
||||
compiled_query_hash: 'f'.repeat(64),
|
||||
compiled_sql: "SELECT * FROM customers WHERE personnummer = '19800101-1234'",
|
||||
error_message: 'duplicate key value violates unique constraint (personnummer)=(19800101-1234)',
|
||||
error_code: 'CONFLICT',
|
||||
tenant_id: 't_alpha',
|
||||
dataset_id: 'ds_sales',
|
||||
engine: 'clickhouse',
|
||||
surface: 'dashboard',
|
||||
state: 'failed',
|
||||
started_at: '2026-09-07T10:00:00.000Z',
|
||||
finished_at: '2026-09-07T10:00:02.000Z',
|
||||
duration_ms: 2000,
|
||||
filter_keys: ['region'],
|
||||
filter_values: { region: ['Gotland'] },
|
||||
result_sample: [{ customer: 'Anna Andersson', revenue: 42 }],
|
||||
metric_name: 'revenue',
|
||||
dashboard_id: 'dash_sales',
|
||||
widget_count: 4,
|
||||
};
|
||||
|
||||
it('emits none of the forbidden material', () => {
|
||||
const events = biUsageEventsForExecution(hostile);
|
||||
const serialized = JSON.stringify(events);
|
||||
|
||||
// The detector must be able to find these strings — they are in the input.
|
||||
const input = JSON.stringify(hostile);
|
||||
for (const secret of ['19800101-1234', 'Anna Andersson', 'Gotland', 't_alpha', 'SELECT *']) {
|
||||
expect(input, `detector check for ${secret}`).toContain(secret);
|
||||
}
|
||||
for (const secret of [
|
||||
'19800101-1234',
|
||||
'Anna Andersson',
|
||||
'Gotland',
|
||||
't_alpha',
|
||||
'SELECT *',
|
||||
'duplicate key',
|
||||
]) {
|
||||
expect(serialized, secret).not.toContain(secret);
|
||||
}
|
||||
});
|
||||
|
||||
it('every emitted key is on the allowlist AUD0 accepts', () => {
|
||||
const events = biUsageEventsForExecution(hostile);
|
||||
for (const e of events) {
|
||||
for (const key of Object.keys(e.payload)) {
|
||||
expect(EMITTABLE_PAYLOAD_KEYS, `${e.event_type}.${key}`).toContain(key);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it('a query_hash that is not a sha256 digest is dropped, not reshaped', () => {
|
||||
const events = biUsageEventsForExecution({ ...hostile, compiled_query_hash: 'SELECT 1' });
|
||||
for (const e of events) expect(e.payload.query_hash).toBeUndefined();
|
||||
});
|
||||
|
||||
it('a running query emits only "started" — it is neither a success nor a failure', () => {
|
||||
const events = biUsageEventsForExecution({
|
||||
...hostile,
|
||||
state: 'running',
|
||||
metric_name: undefined,
|
||||
dashboard_id: undefined,
|
||||
});
|
||||
expect(events.map((e) => e.event_type)).toEqual(['aud0.analytics_query_started']);
|
||||
});
|
||||
|
||||
it('a cancelled query is reported as failed with a CODE', () => {
|
||||
const events = biUsageEventsForExecution({
|
||||
...hostile,
|
||||
state: 'cancelled',
|
||||
error_code: undefined,
|
||||
metric_name: undefined,
|
||||
dashboard_id: undefined,
|
||||
});
|
||||
const failed = events.find((e) => e.event_type === 'aud0.analytics_query_failed');
|
||||
expect(failed?.payload.error_code).toBe('CANCELLED');
|
||||
expect(failed?.payload.error_message).toBeUndefined();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,330 @@
|
||||
/**
|
||||
* tests/analytics/dashboard-model.test.ts
|
||||
* ========================================
|
||||
* BI-P060 — ANALYTICS DASHBOARD MODEL.
|
||||
*
|
||||
* The DoD is "a native SIAX dashboard can be reconstructed without Superset",
|
||||
* so the central test takes a document that CAME from Superset (it still
|
||||
* carries the slice ids in `vendor_ref`), plans it, and then greps the whole
|
||||
* plan for any trace of the vendor. A plan that still needs Superset to be
|
||||
* understood fails here.
|
||||
*
|
||||
* The counterfactual matters as much: `vendor-only-widget-is-refused` builds
|
||||
* the document that CANNOT be reconstructed — a widget whose only content is a
|
||||
* Superset id — and requires the model to refuse it. Without that test the
|
||||
* vendor-free assertion would pass trivially for documents nobody could
|
||||
* render.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
dashboardDocumentHash,
|
||||
parseDashboardDocument,
|
||||
planDashboard,
|
||||
VISUALIZATION_TYPES,
|
||||
type DashboardDocument,
|
||||
} from '@/src/analytics/dashboards/dashboard-document';
|
||||
|
||||
/** A dashboard exported from Superset and rewritten into the canonical model. */
|
||||
function supersetImportedDocument(): unknown {
|
||||
return {
|
||||
id: 'dash_sales_overview',
|
||||
title: 'Sales overview',
|
||||
description: 'Migrated from Superset dashboard 41.',
|
||||
version: 1,
|
||||
layout: { grid_columns: 12, row_height_px: 40 },
|
||||
parameters: [
|
||||
{
|
||||
name: 'region',
|
||||
type: 'enum',
|
||||
required: false,
|
||||
default_value: 'SE',
|
||||
allowed_values: ['SE', 'NO', 'DK'],
|
||||
},
|
||||
{ name: 'since', type: 'date', required: true },
|
||||
],
|
||||
filters: [
|
||||
{
|
||||
filter_id: 'f_region',
|
||||
label: 'Region',
|
||||
dimension: 'region',
|
||||
operator: 'eq',
|
||||
default_values: ['{{region}}'],
|
||||
},
|
||||
{
|
||||
filter_id: 'f_channel',
|
||||
label: 'Channel',
|
||||
dimension: 'channel',
|
||||
operator: 'in',
|
||||
default_values: ['web'],
|
||||
},
|
||||
{
|
||||
filter_id: 'f_tenant_scope',
|
||||
label: 'Business unit',
|
||||
dimension: 'business_unit',
|
||||
operator: 'eq',
|
||||
default_values: ['bu_north'],
|
||||
locked: true,
|
||||
},
|
||||
],
|
||||
widgets: [
|
||||
{
|
||||
widget_id: 'w_revenue_total',
|
||||
title: 'Revenue',
|
||||
source: { kind: 'metric', dataset: 'ds_sales', metric: 'revenue' },
|
||||
visualization: { type: 'big_number', encoding: { value: 'revenue' } },
|
||||
layout: { x: 0, y: 0, w: 3, h: 2 },
|
||||
vendor_ref: { system: 'superset', id: 'slice-8812' },
|
||||
},
|
||||
{
|
||||
widget_id: 'w_revenue_by_day',
|
||||
title: 'Revenue by day',
|
||||
source: {
|
||||
kind: 'metric',
|
||||
dataset: 'ds_sales',
|
||||
metric: 'revenue',
|
||||
dimensions: ['order_date'],
|
||||
grain: 'day',
|
||||
},
|
||||
visualization: {
|
||||
type: 'line',
|
||||
encoding: { x: 'order_date', y: ['revenue'] },
|
||||
options: { stacked: false },
|
||||
},
|
||||
layout: { x: 3, y: 0, w: 9, h: 4 },
|
||||
filter_bindings: ['f_region', 'f_tenant_scope'],
|
||||
vendor_ref: { system: 'superset', id: 'slice-8813' },
|
||||
},
|
||||
{
|
||||
widget_id: 'w_top_products',
|
||||
title: 'Top products',
|
||||
source: {
|
||||
kind: 'query',
|
||||
request: {
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['revenue', 'orders'],
|
||||
dimensions: ['product'],
|
||||
filters: [{ dimension: 'status', operator: 'eq', values: ['completed'] }],
|
||||
orderBy: [{ ref: 'revenue', direction: 'desc' }],
|
||||
limit: 20,
|
||||
},
|
||||
},
|
||||
visualization: { type: 'table', encoding: { x: 'product', y: ['revenue', 'orders'] } },
|
||||
layout: { x: 0, y: 4, w: 12, h: 6 },
|
||||
},
|
||||
],
|
||||
refresh: { mode: 'interval', interval_seconds: 300, max_staleness_seconds: 900 },
|
||||
permissions: {
|
||||
visibility: 'roles',
|
||||
roles: ['analyst', 'sales_lead'],
|
||||
required_entitlement: 'bi_dashboards',
|
||||
},
|
||||
vendor_ref: { system: 'superset', id: 'dashboard-41' },
|
||||
};
|
||||
}
|
||||
|
||||
describe('BI-P060 dashboard model — reconstruction without Superset', () => {
|
||||
it('plans every widget into a runnable analytics request', () => {
|
||||
const doc = parseDashboardDocument(supersetImportedDocument());
|
||||
const plan = planDashboard(doc, { parameters: { since: '2026-01-01', region: 'NO' } });
|
||||
|
||||
expect(plan.widgets).toHaveLength(3);
|
||||
for (const w of plan.widgets) {
|
||||
expect(w.request.dataset).toBe('ds_sales');
|
||||
expect(w.request.metrics.length).toBeGreaterThan(0);
|
||||
expect(VISUALIZATION_TYPES).toContain(w.visualization.type);
|
||||
}
|
||||
// The parameter reference was BOUND, not left as a template string.
|
||||
const byDay = plan.widgets.find((w) => w.widget_id === 'w_revenue_by_day');
|
||||
expect(byDay?.request.filters.find((f) => f.dimension === 'region')?.values).toEqual(['NO']);
|
||||
expect(plan.bound_parameters).toEqual({ region: 'NO', since: '2026-01-01' });
|
||||
});
|
||||
|
||||
it('the plan contains no vendor identifier anywhere', () => {
|
||||
const doc = parseDashboardDocument(supersetImportedDocument());
|
||||
const plan = planDashboard(doc, { parameters: { since: '2026-01-01' } });
|
||||
const serialized = JSON.stringify(plan).toLowerCase();
|
||||
|
||||
// The detector must be capable of finding one: the document DOES carry
|
||||
// these ids, so a grep that finds nothing in the plan means the plan is
|
||||
// clean, not that the grep is broken.
|
||||
expect(JSON.stringify(doc).toLowerCase()).toContain('slice-8812');
|
||||
|
||||
for (const trace of ['superset', 'slice-8812', 'slice-8813', 'dashboard-41', 'viz_type', 'form_data']) {
|
||||
expect(serialized).not.toContain(trace);
|
||||
}
|
||||
});
|
||||
|
||||
it('vendor-only widget is refused — it is the document that cannot be reconstructed', () => {
|
||||
const raw = supersetImportedDocument() as { widgets: unknown[] };
|
||||
raw.widgets = [
|
||||
{
|
||||
widget_id: 'w_mystery',
|
||||
title: 'Whatever Superset had',
|
||||
source: { kind: 'vendor', system: 'superset', id: 'slice-9001' },
|
||||
visualization: { type: 'line', encoding: {} },
|
||||
layout: { x: 0, y: 0, w: 4, h: 3 },
|
||||
},
|
||||
];
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(SiaxError);
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/reconstruct/i);
|
||||
});
|
||||
|
||||
it('vendor-native fields are refused at the top level and inside a widget', () => {
|
||||
const top = { ...(supersetImportedDocument() as object), position_json: '{}' };
|
||||
expect(() => parseDashboardDocument(top)).toThrow(/vendor-native/);
|
||||
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[0].viz_type = 'echarts_timeseries';
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/vendor-native/);
|
||||
});
|
||||
|
||||
it('a Superset viz_type value is not a SIAX visualization type', () => {
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[0].visualization = { type: 'echarts_timeseries', encoding: {} };
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/not a SIAX visualization type/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P060 dashboard model — no SQL surface', () => {
|
||||
it('a widget cannot carry SQL, however it is spelled', () => {
|
||||
for (const key of ['sql', 'query_text', 'statement', 'where', 'expression']) {
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[0][key] = 'SELECT 1';
|
||||
expect(() => parseDashboardDocument(raw), key).toThrow(SiaxError);
|
||||
}
|
||||
});
|
||||
|
||||
it('a query widget goes through the BI-P016 contract, so tenant selection is impossible', () => {
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[2].source = {
|
||||
kind: 'query',
|
||||
request: {
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['revenue'],
|
||||
dimensions: [],
|
||||
filters: [],
|
||||
tenant_id: 't_victim',
|
||||
},
|
||||
};
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/does not accept SQL, catalogs, or tenant selection/);
|
||||
});
|
||||
|
||||
it('the document itself cannot name a tenant', () => {
|
||||
const raw = { ...(supersetImportedDocument() as object), tenant_id: 't_victim' };
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/dashboards do not carry SQL|unknown field/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P060 dashboard model — validation that would otherwise bite at render time', () => {
|
||||
it('a widget binding an undeclared filter is refused', () => {
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[1].filter_bindings = ['f_nonexistent'];
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/undeclared filter/);
|
||||
});
|
||||
|
||||
it('a filter defaulting to an undeclared parameter is refused', () => {
|
||||
const raw = supersetImportedDocument() as { filters: Record<string, unknown>[] };
|
||||
raw.filters[0].default_values = ['{{not_declared}}'];
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/undeclared parameter/);
|
||||
});
|
||||
|
||||
it('a widget overflowing the grid is refused', () => {
|
||||
const raw = supersetImportedDocument() as { widgets: Record<string, unknown>[] };
|
||||
raw.widgets[1].layout = { x: 9, y: 0, w: 6, h: 3 };
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/overflows the 12-column grid/);
|
||||
});
|
||||
|
||||
it('an interval refresh with a cron, and a manual refresh with a schedule, are both refused', () => {
|
||||
const a = supersetImportedDocument() as Record<string, unknown>;
|
||||
a.refresh = { mode: 'interval', interval_seconds: 300, cron: '0 * * * *', max_staleness_seconds: 900 };
|
||||
expect(() => parseDashboardDocument(a)).toThrow(/meaningless/);
|
||||
|
||||
const b = supersetImportedDocument() as Record<string, unknown>;
|
||||
b.refresh = { mode: 'manual', interval_seconds: 300, max_staleness_seconds: 900 };
|
||||
expect(() => parseDashboardDocument(b)).toThrow(/manual/);
|
||||
});
|
||||
|
||||
it('visibility "roles" with no roles is refused rather than guessed', () => {
|
||||
const raw = supersetImportedDocument() as Record<string, unknown>;
|
||||
raw.permissions = { visibility: 'roles', roles: [] };
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/deny all/);
|
||||
});
|
||||
|
||||
it('a required parameter that was not supplied fails the plan, not the render', () => {
|
||||
const doc = parseDashboardDocument(supersetImportedDocument());
|
||||
expect(() => planDashboard(doc, { parameters: {} })).toThrow(/required parameter "since"/);
|
||||
});
|
||||
|
||||
it('a locked filter cannot be switched off by a viewer', () => {
|
||||
const doc = parseDashboardDocument(supersetImportedDocument());
|
||||
expect(() =>
|
||||
planDashboard(doc, { parameters: { since: '2026-01-01' }, disabled_filter_ids: ['f_tenant_scope'] }),
|
||||
).toThrow(/locked/);
|
||||
// An unlocked one can be, and disappears from the compiled request.
|
||||
const plan = planDashboard(doc, {
|
||||
parameters: { since: '2026-01-01' },
|
||||
disabled_filter_ids: ['f_channel'],
|
||||
});
|
||||
const table = plan.widgets.find((w) => w.widget_id === 'w_top_products');
|
||||
expect(table?.request.filters.map((f) => f.dimension)).not.toContain('channel');
|
||||
});
|
||||
|
||||
it('an enum parameter without allowed_values is refused', () => {
|
||||
const raw = supersetImportedDocument() as { parameters: Record<string, unknown>[] };
|
||||
raw.parameters[0] = { name: 'region', type: 'enum', required: false, default_value: 'SE' };
|
||||
expect(() => parseDashboardDocument(raw)).toThrow(/unbounded enum/);
|
||||
});
|
||||
});
|
||||
|
||||
/** Rebuild an object graph with every object's keys in reverse order. */
|
||||
function shuffleKeys(value: unknown): unknown {
|
||||
if (Array.isArray(value)) return value.map(shuffleKeys);
|
||||
if (value !== null && typeof value === 'object') {
|
||||
const out: Record<string, unknown> = {};
|
||||
for (const k of Object.keys(value as object).reverse()) {
|
||||
out[k] = shuffleKeys((value as Record<string, unknown>)[k]);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
describe('BI-P060 dashboard model — canonical hash', () => {
|
||||
function parsed(): DashboardDocument {
|
||||
return parseDashboardDocument(supersetImportedDocument());
|
||||
}
|
||||
|
||||
it('is stable across key order and vendor re-export', () => {
|
||||
const a = parsed();
|
||||
const b = parsed();
|
||||
b.vendor_ref = { system: 'superset', id: 'dashboard-999-after-migration' };
|
||||
b.widgets[0].vendor_ref = { system: 'metabase', id: 'card-3' };
|
||||
expect(dashboardDocumentHash(b)).toBe(dashboardDocumentHash(a));
|
||||
|
||||
// Key order in the source JSON must not change identity either.
|
||||
expect(dashboardDocumentHash(parseDashboardDocument(shuffleKeys(supersetImportedDocument())))).toBe(
|
||||
dashboardDocumentHash(a),
|
||||
);
|
||||
});
|
||||
|
||||
it('changes when meaning changes', () => {
|
||||
const base = dashboardDocumentHash(parsed());
|
||||
|
||||
const retitled = parsed();
|
||||
retitled.widgets[0].title = 'Net revenue';
|
||||
expect(dashboardDocumentHash(retitled)).not.toBe(base);
|
||||
|
||||
const remetric = parsed();
|
||||
(remetric.widgets[0].source as { metric: string }).metric = 'revenue_net';
|
||||
expect(dashboardDocumentHash(remetric)).not.toBe(base);
|
||||
|
||||
const moved = parsed();
|
||||
moved.widgets[1].layout = { x: 3, y: 1, w: 9, h: 4 };
|
||||
expect(dashboardDocumentHash(moved)).not.toBe(base);
|
||||
|
||||
const refiltered = parsed();
|
||||
refiltered.filters[1].default_values = ['store'];
|
||||
expect(dashboardDocumentHash(refiltered)).not.toBe(base);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,346 @@
|
||||
/**
|
||||
* tests/analytics/dashboard-release-postgres.realinfra.test.ts
|
||||
* =============================================================
|
||||
* sql/010 (BI-P061) against a REAL Postgres.
|
||||
*
|
||||
* The interesting claim in sql/010 is not "there is a state machine" — it is
|
||||
* "TWO PEOPLE CANNOT PUBLISH AT ONCE". That claim lives in a partial unique
|
||||
* index, and an index nobody raced is an index nobody has tested. So the
|
||||
* concurrency test runs BOTH directions, in two separate schemas so neither
|
||||
* can contaminate the other:
|
||||
*
|
||||
* 1. WITHOUT the index (a schema where it is dropped): two sessions publish
|
||||
* a release of the same dashboard concurrently, each having first read
|
||||
* "nothing is live" — the exact interleaving an application-level check
|
||||
* cannot see. The database ends up with TWO published releases. This is
|
||||
* the counterfactual: it proves the read-then-write check in
|
||||
* DashboardReleaseService.publish() is NOT the guarantee, and that this
|
||||
* test can detect the failure it claims to prevent.
|
||||
* 2. WITH the index: the same race, and the loser fails with
|
||||
* unique_violation (23505). Exactly one published release remains.
|
||||
*
|
||||
* The transition trigger is attacked the same way: every illegal transition is
|
||||
* attempted against the database, not against the TypeScript.
|
||||
*
|
||||
* Gated on ANALYTICS_TEST_DATABASE_URL, matching the convention in
|
||||
* analytics-governance-postgres.realinfra.test.ts. With it set and Postgres
|
||||
* down this FAILS rather than skipping.
|
||||
*
|
||||
* docker run -d --name pg -p 25441:5432 -e POSTGRES_PASSWORD=test \
|
||||
* -e POSTGRES_DB=opt postgres:16-alpine
|
||||
* ANALYTICS_TEST_DATABASE_URL=postgres://postgres:test@127.0.0.1:25441/opt \
|
||||
* pnpm vitest run tests/analytics/dashboard-release-postgres.realinfra.test.ts
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
||||
import postgres from 'postgres';
|
||||
|
||||
const TEST_DATABASE_URL = process.env.ANALYTICS_TEST_DATABASE_URL;
|
||||
const run = TEST_DATABASE_URL ? describe : describe.skip;
|
||||
const STAMP = Date.now().toString(36);
|
||||
const SCHEMA = `bi_p061_${STAMP}`;
|
||||
/** The counterfactual lives in its own schema: no cleanup, no contamination. */
|
||||
const SCHEMA_NOGUARD = `bi_p061_noguard_${STAMP}`;
|
||||
const HASH_A = 'a'.repeat(64);
|
||||
const HASH_B = 'b'.repeat(64);
|
||||
const MIGRATIONS = ['sql/008_analytics_domain_model.sql', 'sql/010_analytics_dashboard_releases.sql'];
|
||||
|
||||
let sql: ReturnType<typeof postgres>;
|
||||
|
||||
function connect(schema: string, max = 1): ReturnType<typeof postgres> {
|
||||
return postgres(TEST_DATABASE_URL!, {
|
||||
max,
|
||||
onnotice: () => undefined,
|
||||
connection: { search_path: schema },
|
||||
});
|
||||
}
|
||||
|
||||
async function refusalOf(fn: () => Promise<unknown>): Promise<string | undefined> {
|
||||
try {
|
||||
await fn();
|
||||
return undefined;
|
||||
} catch (e) {
|
||||
return String((e as Error).message);
|
||||
}
|
||||
}
|
||||
|
||||
async function migrate(conn: ReturnType<typeof postgres>): Promise<void> {
|
||||
for (const file of MIGRATIONS) {
|
||||
await conn.unsafe(fs.readFileSync(path.join(process.cwd(), file), 'utf8'));
|
||||
}
|
||||
}
|
||||
|
||||
async function seedDashboard(conn: ReturnType<typeof postgres>, id: string): Promise<void> {
|
||||
await conn.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_definition
|
||||
(dashboard_id, tenant_id, project_id, name, current_version, owner_id)
|
||||
VALUES ('${id}', 't_alpha', 'p_main', '${id}', 1, 'u_1')
|
||||
ON CONFLICT DO NOTHING`);
|
||||
}
|
||||
|
||||
async function seedVersion(
|
||||
conn: ReturnType<typeof postgres>,
|
||||
versionId: string,
|
||||
dashboardId: string,
|
||||
version: number,
|
||||
hash = HASH_A,
|
||||
): Promise<void> {
|
||||
await conn.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_version
|
||||
(dashboard_version_id, dashboard_id, tenant_id, project_id, version, layout_json, layout_hash)
|
||||
VALUES ('${versionId}', '${dashboardId}', 't_alpha', 'p_main', ${version}, '{}', '${hash}')`);
|
||||
}
|
||||
|
||||
async function seedDraftRelease(
|
||||
conn: ReturnType<typeof postgres>,
|
||||
releaseId: string,
|
||||
versionId: string,
|
||||
dashboardId: string,
|
||||
version: number,
|
||||
hash = HASH_A,
|
||||
): Promise<void> {
|
||||
await conn.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_release
|
||||
(release_id, dashboard_id, dashboard_version_id, tenant_id, project_id, version, state, document_hash)
|
||||
VALUES ('${releaseId}', '${dashboardId}', '${versionId}', 't_alpha', 'p_main', ${version}, 'draft', '${hash}')`);
|
||||
}
|
||||
|
||||
async function publishedCount(conn: ReturnType<typeof postgres>, dashboardId: string): Promise<number> {
|
||||
const rows = (await conn.unsafe(
|
||||
`SELECT count(*)::int AS n FROM opt_analytics_dashboard_release
|
||||
WHERE dashboard_id = '${dashboardId}' AND state = 'published'`,
|
||||
)) as unknown as Array<{ n: number }>;
|
||||
return rows[0].n;
|
||||
}
|
||||
|
||||
/**
|
||||
* Two sessions publish a release of the SAME dashboard at the same time, each
|
||||
* having first read "nothing is live". This is the create-and-publish path:
|
||||
* a new version is minted and released in one transaction, which is what a
|
||||
* "save and publish" button does.
|
||||
*/
|
||||
async function racePublish(schema: string, dashboardId: string): Promise<{ ok: number; codes: string[] }> {
|
||||
const a = connect(schema);
|
||||
const b = connect(schema);
|
||||
const publish = (conn: ReturnType<typeof postgres>, n: number) =>
|
||||
conn.begin(async (tx) => {
|
||||
await tx.unsafe(
|
||||
`SELECT release_id FROM opt_analytics_dashboard_release
|
||||
WHERE dashboard_id = '${dashboardId}' AND state = 'published'`,
|
||||
);
|
||||
// A tiny pause so both transactions have certainly done their read
|
||||
// before either writes. Without it the race may not interleave and the
|
||||
// counterfactual could pass for the wrong reason.
|
||||
await new Promise((r) => setTimeout(r, 60));
|
||||
await tx.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_release
|
||||
(release_id, dashboard_id, dashboard_version_id, tenant_id, project_id, version, state,
|
||||
document_hash, published_at)
|
||||
VALUES ('rel_race_${n}', '${dashboardId}', 'dv_race_${n}', 't_alpha', 'p_main', ${400 + n},
|
||||
'published', '${n === 1 ? HASH_A : HASH_B}', now())`);
|
||||
});
|
||||
const results = await Promise.allSettled([publish(a, 1), publish(b, 2)]);
|
||||
await a.end({ timeout: 5 });
|
||||
await b.end({ timeout: 5 });
|
||||
return {
|
||||
ok: results.filter((r) => r.status === 'fulfilled').length,
|
||||
codes: results.flatMap((r) =>
|
||||
r.status === 'rejected' ? [String((r.reason as { code?: string })?.code ?? r.reason)] : [],
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
if (!TEST_DATABASE_URL) return;
|
||||
const admin = postgres(TEST_DATABASE_URL, { max: 1, onnotice: () => undefined });
|
||||
await admin.unsafe(`CREATE SCHEMA IF NOT EXISTS ${SCHEMA}`);
|
||||
await admin.unsafe(`CREATE SCHEMA IF NOT EXISTS ${SCHEMA_NOGUARD}`);
|
||||
await admin.end({ timeout: 5 });
|
||||
|
||||
sql = connect(SCHEMA, 3);
|
||||
await migrate(sql);
|
||||
for (const d of ['dash_txn', 'dash_race', 'dash_draft']) await seedDashboard(sql, d);
|
||||
}, 120_000);
|
||||
|
||||
afterAll(async () => {
|
||||
if (!TEST_DATABASE_URL || !sql) return;
|
||||
await sql.unsafe(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`);
|
||||
await sql.unsafe(`DROP SCHEMA IF EXISTS ${SCHEMA_NOGUARD} CASCADE`);
|
||||
await sql.end({ timeout: 5 });
|
||||
});
|
||||
|
||||
run('sql/010 applies and replays', () => {
|
||||
it('is idempotent — a replay onto an already-migrated schema succeeds', async () => {
|
||||
const text = fs.readFileSync(
|
||||
path.join(process.cwd(), 'sql/010_analytics_dashboard_releases.sql'),
|
||||
'utf8',
|
||||
);
|
||||
await expect(sql.unsafe(text)).resolves.toBeDefined();
|
||||
});
|
||||
|
||||
it('has no column that could hold a document body — the document lives in the version row', async () => {
|
||||
const rows = (await sql.unsafe(
|
||||
`SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = '${SCHEMA}' AND table_name = 'opt_analytics_dashboard_release'`,
|
||||
)) as unknown as Array<{ column_name: string }>;
|
||||
const names = new Set(rows.map((r) => r.column_name));
|
||||
for (const forbidden of ['layout_json', 'document', 'definition', 'payload', 'sql']) {
|
||||
expect(names.has(forbidden), forbidden).toBe(false);
|
||||
}
|
||||
expect(names.has('document_hash')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
run('BI-P061 transitions are enforced by the database', () => {
|
||||
beforeAll(async () => {
|
||||
await seedVersion(sql, 'dv_t1', 'dash_txn', 101);
|
||||
await seedVersion(sql, 'dv_t3', 'dash_txn', 103, HASH_B);
|
||||
await seedDraftRelease(sql, 'rel_t1', 'dv_t1', 'dash_txn', 101);
|
||||
});
|
||||
|
||||
it('draft -> published is allowed', async () => {
|
||||
await sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET state='published', published_at=now() WHERE release_id='rel_t1'`,
|
||||
);
|
||||
const rows = (await sql.unsafe(
|
||||
`SELECT state FROM opt_analytics_dashboard_release WHERE release_id='rel_t1'`,
|
||||
)) as unknown as Array<{ state: string }>;
|
||||
expect(rows[0].state).toBe('published');
|
||||
});
|
||||
|
||||
it('published -> draft (un-publishing) is REFUSED', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET state='draft', published_at=NULL WHERE release_id='rel_t1'`,
|
||||
),
|
||||
);
|
||||
expect(msg).toMatch(/illegal dashboard release transition published -> draft/);
|
||||
});
|
||||
|
||||
it('repointing a release at a different version is REFUSED', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET dashboard_version_id='dv_t3' WHERE release_id='rel_t1'`,
|
||||
),
|
||||
);
|
||||
expect(msg).toMatch(/immutable apart from its state/);
|
||||
});
|
||||
|
||||
it('rewriting document_hash on a release is REFUSED', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET document_hash='${HASH_B}' WHERE release_id='rel_t1'`,
|
||||
),
|
||||
);
|
||||
expect(msg).toMatch(/immutable apart from its state/);
|
||||
});
|
||||
|
||||
it('rewriting published_at is REFUSED — a published timestamp is history', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET published_at = now() - interval '10 days'
|
||||
WHERE release_id='rel_t1'`,
|
||||
),
|
||||
);
|
||||
expect(msg).toMatch(/published_at is history/);
|
||||
});
|
||||
|
||||
it('published -> superseded is allowed, and superseded -> published is REFUSED', async () => {
|
||||
await sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_release SET state='superseded', superseded_at=now() WHERE release_id='rel_t1'`,
|
||||
);
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(`UPDATE opt_analytics_dashboard_release SET state='published' WHERE release_id='rel_t1'`),
|
||||
);
|
||||
expect(msg).toMatch(/illegal dashboard release transition superseded -> published/);
|
||||
});
|
||||
|
||||
it('deleting a release is REFUSED — the ledger has no eraser', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(`DELETE FROM opt_analytics_dashboard_release WHERE release_id='rel_t1'`),
|
||||
);
|
||||
expect(msg).toMatch(/ledger; delete is refused/);
|
||||
});
|
||||
|
||||
it('a published release with no published_at is REFUSED by the CHECK', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_release
|
||||
(release_id, dashboard_id, dashboard_version_id, tenant_id, project_id, version, state, document_hash)
|
||||
VALUES ('rel_bad', 'dash_txn', 'dv_t3', 't_alpha', 'p_main', 900, 'published', '${HASH_A}')`),
|
||||
);
|
||||
expect(msg).toMatch(/opt_analytics_dashboard_release_timestamps/);
|
||||
});
|
||||
|
||||
it('a document_hash that is not a sha256 digest is REFUSED', async () => {
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(`
|
||||
INSERT INTO opt_analytics_dashboard_release
|
||||
(release_id, dashboard_id, dashboard_version_id, tenant_id, project_id, version, state, document_hash)
|
||||
VALUES ('rel_bad2', 'dash_txn', 'dv_t3', 't_alpha', 'p_main', 901, 'draft', 'not-a-hash')`),
|
||||
);
|
||||
expect(msg).toMatch(/document_hash/);
|
||||
});
|
||||
|
||||
it('the sql/008 immutability trigger still forbids editing the frozen document', async () => {
|
||||
// Assert the row exists FIRST: an UPDATE that matches nothing raises
|
||||
// nothing, which would read as "refused" to a careless test.
|
||||
const before = (await sql.unsafe(
|
||||
`SELECT count(*)::int AS n FROM opt_analytics_dashboard_version WHERE dashboard_version_id='dv_t3'`,
|
||||
)) as unknown as Array<{ n: number }>;
|
||||
expect(before[0].n).toBe(1);
|
||||
|
||||
const msg = await refusalOf(() =>
|
||||
sql.unsafe(
|
||||
`UPDATE opt_analytics_dashboard_version SET layout_json='{"tampered":true}'
|
||||
WHERE dashboard_version_id='dv_t3'`,
|
||||
),
|
||||
);
|
||||
expect(msg).toMatch(/rows are immutable/);
|
||||
});
|
||||
|
||||
it('a second open draft for one dashboard is REFUSED', async () => {
|
||||
await seedVersion(sql, 'dv_d1', 'dash_draft', 301);
|
||||
await seedVersion(sql, 'dv_d2', 'dash_draft', 302);
|
||||
await seedDraftRelease(sql, 'rel_d1', 'dv_d1', 'dash_draft', 301);
|
||||
const msg = await refusalOf(() => seedDraftRelease(sql, 'rel_d2', 'dv_d2', 'dash_draft', 302));
|
||||
expect(msg).toMatch(/one_draft/);
|
||||
});
|
||||
});
|
||||
|
||||
run('BI-P061 concurrency: the partial unique index is the guarantee', () => {
|
||||
let noguard: ReturnType<typeof postgres>;
|
||||
|
||||
beforeAll(async () => {
|
||||
noguard = connect(SCHEMA_NOGUARD, 3);
|
||||
await migrate(noguard);
|
||||
await noguard.unsafe(`DROP INDEX opt_analytics_dashboard_release_one_published`);
|
||||
await seedDashboard(noguard, 'dash_race');
|
||||
await seedVersion(noguard, 'dv_race_1', 'dash_race', 401);
|
||||
await seedVersion(noguard, 'dv_race_2', 'dash_race', 402, HASH_B);
|
||||
|
||||
await seedVersion(sql, 'dv_race_1', 'dash_race', 401);
|
||||
await seedVersion(sql, 'dv_race_2', 'dash_race', 402, HASH_B);
|
||||
}, 60_000);
|
||||
|
||||
afterAll(async () => {
|
||||
if (noguard) await noguard.end({ timeout: 5 });
|
||||
});
|
||||
|
||||
it('WITHOUT the index, two concurrent publishes BOTH succeed — two live dashboards', async () => {
|
||||
const race = await racePublish(SCHEMA_NOGUARD, 'dash_race');
|
||||
expect(race.ok).toBe(2);
|
||||
expect(await publishedCount(noguard, 'dash_race')).toBe(2);
|
||||
}, 30_000);
|
||||
|
||||
it('WITH the index, the same race leaves exactly one published release', async () => {
|
||||
expect(await publishedCount(sql, 'dash_race')).toBe(0);
|
||||
|
||||
const race = await racePublish(SCHEMA, 'dash_race');
|
||||
|
||||
expect(race.ok).toBe(1);
|
||||
expect(race.codes.join(' ')).toContain('23505');
|
||||
expect(await publishedCount(sql, 'dash_race')).toBe(1);
|
||||
}, 30_000);
|
||||
});
|
||||
@@ -0,0 +1,212 @@
|
||||
/**
|
||||
* tests/analytics/dashboard-release.test.ts
|
||||
* ==========================================
|
||||
* BI-P061 — DASHBOARD VERSIONING. DoD: "rollback to previous dashboard
|
||||
* definition".
|
||||
*
|
||||
* A rollback test that only asserts "the service returned version 4" proves
|
||||
* nothing: the interesting failure is a rollback that publishes a DIFFERENT
|
||||
* document while reporting success. So every rollback assertion here compares
|
||||
* BI-P060 canonical hashes and re-plans the restored dashboard, and one test
|
||||
* corrupts the stored document underneath a release to show that serving it
|
||||
* is refused rather than silently rendered.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
dashboardDocumentHash,
|
||||
parseDashboardDocument,
|
||||
planDashboard,
|
||||
} from '@/src/analytics/dashboards/dashboard-document';
|
||||
import {
|
||||
DashboardReleaseService,
|
||||
InMemoryDashboardReleaseStore,
|
||||
isLegalTransition,
|
||||
DASHBOARD_RELEASE_STATES,
|
||||
type DashboardReleaseState,
|
||||
} from '@/src/analytics/dashboards/dashboard-release';
|
||||
|
||||
const SCOPE = { tenant_id: 't_alpha', project_id: 'p_main' };
|
||||
|
||||
function doc(title: string, metric = 'revenue') {
|
||||
return {
|
||||
id: 'dash_sales',
|
||||
title,
|
||||
version: 1,
|
||||
layout: { grid_columns: 12, row_height_px: 40 },
|
||||
parameters: [],
|
||||
filters: [],
|
||||
widgets: [
|
||||
{
|
||||
widget_id: 'w_1',
|
||||
title,
|
||||
source: { kind: 'metric', dataset: 'ds_sales', metric },
|
||||
visualization: { type: 'big_number', encoding: { value: metric } },
|
||||
layout: { x: 0, y: 0, w: 4, h: 2 },
|
||||
},
|
||||
],
|
||||
refresh: { mode: 'manual', max_staleness_seconds: 3600 },
|
||||
permissions: { visibility: 'tenant' },
|
||||
};
|
||||
}
|
||||
|
||||
function service() {
|
||||
let n = 0;
|
||||
let t = Date.parse('2026-09-07T10:00:00.000Z');
|
||||
return new DashboardReleaseService(
|
||||
new InMemoryDashboardReleaseStore(),
|
||||
() => new Date((t += 1000)),
|
||||
() => `id_${++n}`,
|
||||
);
|
||||
}
|
||||
|
||||
describe('BI-P061 release lifecycle', () => {
|
||||
it('the transition table is exactly DRAFT -> PUBLISHED -> SUPERSEDED', () => {
|
||||
const legal: Array<[DashboardReleaseState, DashboardReleaseState]> = [
|
||||
['draft', 'published'],
|
||||
['published', 'superseded'],
|
||||
];
|
||||
for (const from of DASHBOARD_RELEASE_STATES) {
|
||||
for (const to of DASHBOARD_RELEASE_STATES) {
|
||||
const expected = legal.some(([f, t]) => f === from && t === to);
|
||||
expect(isLegalTransition(from, to), `${from} -> ${to}`).toBe(expected);
|
||||
}
|
||||
}
|
||||
// Named explicitly because each is a real request someone will make.
|
||||
expect(isLegalTransition('published', 'draft')).toBe(false);
|
||||
expect(isLegalTransition('superseded', 'published')).toBe(false);
|
||||
expect(isLegalTransition('draft', 'superseded')).toBe(false);
|
||||
});
|
||||
|
||||
it('publishing supersedes the previous release, and only one is ever live', async () => {
|
||||
const svc = service();
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
await svc.publish({ scope: SCOPE, releaseId: v1.release.release_id });
|
||||
const v2 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v2') });
|
||||
const result = await svc.publish({ scope: SCOPE, releaseId: v2.release.release_id });
|
||||
|
||||
expect(result.published.version).toBe(2);
|
||||
expect(result.superseded?.version).toBe(1);
|
||||
expect(result.superseded?.superseded_by_release_id).toBe(v2.release.release_id);
|
||||
|
||||
const history = await svc.history(SCOPE, 'dash_sales');
|
||||
expect(history.map((r) => `${r.version}:${r.state}`)).toEqual(['1:superseded', '2:published']);
|
||||
expect((await svc.live(SCOPE, 'dash_sales'))?.version).toBe(2);
|
||||
});
|
||||
|
||||
it('a second open draft is refused rather than racing the first', async () => {
|
||||
const svc = service();
|
||||
await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
await expect(
|
||||
svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1-again') }),
|
||||
).rejects.toThrow(/already has an open draft/);
|
||||
});
|
||||
|
||||
it('a superseded release cannot be re-published', async () => {
|
||||
const svc = service();
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
await svc.publish({ scope: SCOPE, releaseId: v1.release.release_id });
|
||||
const v2 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v2') });
|
||||
await svc.publish({ scope: SCOPE, releaseId: v2.release.release_id });
|
||||
|
||||
await expect(svc.publish({ scope: SCOPE, releaseId: v1.release.release_id })).rejects.toThrow(
|
||||
/is superseded, not draft/,
|
||||
);
|
||||
});
|
||||
|
||||
it('another tenant cannot see, publish or roll back this tenant’s releases', async () => {
|
||||
const svc = service();
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
const other = { tenant_id: 't_beta', project_id: 'p_main' };
|
||||
|
||||
await expect(svc.publish({ scope: other, releaseId: v1.release.release_id })).rejects.toThrow(
|
||||
/does not exist in this tenant/,
|
||||
);
|
||||
expect(await svc.live(other, 'dash_sales')).toBeUndefined();
|
||||
await expect(svc.rollback({ scope: other, dashboardId: 'dash_sales', toVersion: 1 })).rejects.toThrow(
|
||||
/no version 1 in this tenant/,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P061 rollback — the DoD', () => {
|
||||
it('restores the earlier definition byte-for-byte, as a NEW version', async () => {
|
||||
const svc = service();
|
||||
const original = doc('Sales v1', 'revenue');
|
||||
const originalHash = dashboardDocumentHash(parseDashboardDocument(original));
|
||||
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: original });
|
||||
await svc.publish({ scope: SCOPE, releaseId: v1.release.release_id });
|
||||
const v2 = await svc.draft({
|
||||
scope: SCOPE,
|
||||
dashboardId: 'dash_sales',
|
||||
document: doc('Sales v2 (broken)', 'revenue_net'),
|
||||
});
|
||||
await svc.publish({ scope: SCOPE, releaseId: v2.release.release_id });
|
||||
expect((await svc.live(SCOPE, 'dash_sales'))?.document_hash).not.toBe(originalHash);
|
||||
|
||||
const rolled = await svc.rollback({ scope: SCOPE, dashboardId: 'dash_sales', toVersion: 1 });
|
||||
|
||||
// Faithful: same canonical document.
|
||||
expect(rolled.document_hash).toBe(originalHash);
|
||||
// New version, not a resurrected row — the history stays linear.
|
||||
expect(rolled.release.version).toBe(3);
|
||||
expect(rolled.release.rollback_of_version).toBe(1);
|
||||
|
||||
const history = await svc.history(SCOPE, 'dash_sales');
|
||||
expect(history.map((r) => `${r.version}:${r.state}`)).toEqual([
|
||||
'1:superseded',
|
||||
'2:superseded',
|
||||
'3:published',
|
||||
]);
|
||||
|
||||
// And the restored dashboard actually renders as the original did.
|
||||
const live = await svc.live(SCOPE, 'dash_sales');
|
||||
const restored = await svc.documentOf(SCOPE, live!);
|
||||
expect(planDashboard(restored)).toEqual(planDashboard(parseDashboardDocument(original)));
|
||||
});
|
||||
|
||||
it('rolling back to the live version is refused as a no-op', async () => {
|
||||
const svc = service();
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
await svc.publish({ scope: SCOPE, releaseId: v1.release.release_id });
|
||||
await expect(svc.rollback({ scope: SCOPE, dashboardId: 'dash_sales', toVersion: 1 })).rejects.toThrow(
|
||||
/already live/,
|
||||
);
|
||||
});
|
||||
|
||||
it('a stored document that no longer matches its released hash is refused, not rendered', async () => {
|
||||
const store = new InMemoryDashboardReleaseStore();
|
||||
const svc = new DashboardReleaseService(
|
||||
store,
|
||||
() => new Date(),
|
||||
() => crypto.randomUUID(),
|
||||
);
|
||||
const v1 = await svc.draft({ scope: SCOPE, dashboardId: 'dash_sales', document: doc('v1') });
|
||||
const { published } = await svc.publish({ scope: SCOPE, releaseId: v1.release.release_id });
|
||||
|
||||
// Tamper with storage the way a bad migration or a manual UPDATE would.
|
||||
const stored = await store.getVersion(SCOPE, published.dashboard_version_id);
|
||||
const tampered = JSON.parse(stored!.layout_json);
|
||||
tampered.widgets[0].source.metric = 'revenue_including_vat';
|
||||
await store.insertVersionAndRelease(
|
||||
{ ...stored!, dashboard_version_id: 'tampered', version: 99, layout_json: JSON.stringify(tampered) },
|
||||
{
|
||||
...published,
|
||||
release_id: 'r_tampered',
|
||||
dashboard_version_id: 'tampered',
|
||||
version: 99,
|
||||
state: 'draft',
|
||||
published_at: undefined,
|
||||
},
|
||||
);
|
||||
|
||||
// documentOf must compare hashes, not trust the row.
|
||||
await expect(svc.documentOf(SCOPE, { ...published, dashboard_version_id: 'tampered' })).rejects.toThrow(
|
||||
/refusing to serve an unapproved definition/,
|
||||
);
|
||||
await expect(svc.documentOf(SCOPE, { ...published, dashboard_version_id: 'tampered' })).rejects.toThrow(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,296 @@
|
||||
/**
|
||||
* BI-P004 — ANALYTICS DATA CONTRACT.
|
||||
*
|
||||
* DoD: "Breaking dataset schema changes fail compatibility gate unless
|
||||
* explicitly versioned." Each breaking change class below is tested TWICE:
|
||||
* once under a minor bump (must be REFUSED) and once under a major bump (must
|
||||
* be ACCEPTED). A gate that only ever says yes, or only ever says no, would
|
||||
* pass a one-sided test; this one cannot.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
assertContractCompatible,
|
||||
checkContractCompatibility,
|
||||
contractHash,
|
||||
diffContracts,
|
||||
parseSemVer,
|
||||
validateContract,
|
||||
type DatasetContract,
|
||||
} from '@/src/analytics/domain/contract';
|
||||
|
||||
function base(): DatasetContract {
|
||||
return {
|
||||
dataset_id: 'ds_vehicle_listings',
|
||||
version: '1.2.0',
|
||||
tier: 'CURATED',
|
||||
fields: [
|
||||
{ name: 'listing_id', type: 'string', nullable: false, role: 'identifier', primary_identifier: true },
|
||||
{ name: 'make', type: 'string', nullable: false, role: 'dimension' },
|
||||
{ name: 'asking_price', type: 'int64', nullable: true, role: 'measure' },
|
||||
{ name: 'listed_at', type: 'timestamp', nullable: false, role: 'attribute' },
|
||||
],
|
||||
primary_identifiers: ['listing_id'],
|
||||
dimensions: ['make'],
|
||||
measures: ['asking_price'],
|
||||
freshness_slo_seconds: 3600,
|
||||
retention_days: 730,
|
||||
pii_classification: 'none',
|
||||
source_lineage: ['src_dealer_feed'],
|
||||
quality_rules: [
|
||||
{ rule_id: 'qr_listing_id_unique', kind: 'unique', field_name: 'listing_id', severity: 'block' },
|
||||
],
|
||||
allowed_purposes: ['market_analytics'],
|
||||
};
|
||||
}
|
||||
|
||||
/** Apply a mutation and set the version. */
|
||||
function next(mutate: (c: DatasetContract) => void, version: string): DatasetContract {
|
||||
const c: DatasetContract = JSON.parse(JSON.stringify(base()));
|
||||
mutate(c);
|
||||
c.version = version;
|
||||
return c;
|
||||
}
|
||||
|
||||
const BREAKING_CASES: { name: string; mutate: (c: DatasetContract) => void; code: string }[] = [
|
||||
{
|
||||
name: 'field removed',
|
||||
mutate: (c) => {
|
||||
c.fields = c.fields.filter((f) => f.name !== 'make');
|
||||
c.dimensions = [];
|
||||
},
|
||||
code: 'field_removed',
|
||||
},
|
||||
{
|
||||
name: 'field type changed',
|
||||
mutate: (c) => {
|
||||
c.fields[2].type = 'float64';
|
||||
},
|
||||
code: 'field_type_changed',
|
||||
},
|
||||
{
|
||||
name: 'field became nullable',
|
||||
mutate: (c) => {
|
||||
c.fields[1].nullable = true;
|
||||
},
|
||||
code: 'field_became_nullable',
|
||||
},
|
||||
{
|
||||
name: 'field role changed',
|
||||
mutate: (c) => {
|
||||
c.fields[1].role = 'measure';
|
||||
},
|
||||
code: 'field_role_changed',
|
||||
},
|
||||
{
|
||||
name: 'required field added',
|
||||
mutate: (c) => {
|
||||
c.fields.push({ name: 'vat_rate', type: 'float64', nullable: false, role: 'attribute' });
|
||||
},
|
||||
code: 'required_field_added',
|
||||
},
|
||||
{
|
||||
name: 'primary identifier changed',
|
||||
mutate: (c) => {
|
||||
c.primary_identifiers = ['make'];
|
||||
},
|
||||
code: 'primary_identifier_changed',
|
||||
},
|
||||
{
|
||||
name: 'dimension removed',
|
||||
mutate: (c) => {
|
||||
c.dimensions = [];
|
||||
},
|
||||
code: 'dimension_removed',
|
||||
},
|
||||
{
|
||||
name: 'measure removed',
|
||||
mutate: (c) => {
|
||||
c.measures = [];
|
||||
},
|
||||
code: 'measure_removed',
|
||||
},
|
||||
{
|
||||
name: 'freshness SLO loosened',
|
||||
mutate: (c) => {
|
||||
c.freshness_slo_seconds = 86400;
|
||||
},
|
||||
code: 'freshness_slo_loosened',
|
||||
},
|
||||
{
|
||||
name: 'retention shortened',
|
||||
mutate: (c) => {
|
||||
c.retention_days = 30;
|
||||
},
|
||||
code: 'retention_shortened',
|
||||
},
|
||||
{
|
||||
name: 'allowed purpose removed',
|
||||
mutate: (c) => {
|
||||
c.allowed_purposes = [];
|
||||
},
|
||||
code: 'purpose_removed',
|
||||
},
|
||||
{
|
||||
name: 'PII classification raised',
|
||||
mutate: (c) => {
|
||||
c.pii_classification = 'personal';
|
||||
},
|
||||
code: 'pii_classification_raised',
|
||||
},
|
||||
{
|
||||
name: 'blocking quality rule removed',
|
||||
mutate: (c) => {
|
||||
c.quality_rules = [];
|
||||
},
|
||||
code: 'blocking_quality_rule_removed',
|
||||
},
|
||||
{
|
||||
name: 'blocking quality rule downgraded',
|
||||
mutate: (c) => {
|
||||
c.quality_rules[0].severity = 'warn';
|
||||
},
|
||||
code: 'blocking_quality_rule_downgraded',
|
||||
},
|
||||
{
|
||||
name: 'tier changed',
|
||||
mutate: (c) => {
|
||||
c.tier = 'SERVING';
|
||||
},
|
||||
code: 'tier_changed',
|
||||
},
|
||||
];
|
||||
|
||||
describe('BI-P004 compatibility gate', () => {
|
||||
it.each(BREAKING_CASES)('REFUSES $name under a minor bump', ({ mutate, code }) => {
|
||||
const verdict = checkContractCompatibility(base(), next(mutate, '1.3.0'));
|
||||
expect(verdict.compatible).toBe(false);
|
||||
expect(verdict.breaking.map((b) => b.code)).toContain(code);
|
||||
expect(verdict.reason).toMatch(/MAJOR version bump/);
|
||||
});
|
||||
|
||||
it.each(BREAKING_CASES)('ACCEPTS $name once explicitly versioned (major bump)', ({ mutate, code }) => {
|
||||
const verdict = checkContractCompatibility(base(), next(mutate, '2.0.0'));
|
||||
expect(verdict.compatible).toBe(true);
|
||||
expect(verdict.explicitly_versioned).toBe(true);
|
||||
expect(verdict.breaking.map((b) => b.code)).toContain(code);
|
||||
});
|
||||
|
||||
it('a patch bump is equally refused — the gate is about the MAJOR, not about moving at all', () => {
|
||||
const verdict = checkContractCompatibility(
|
||||
base(),
|
||||
next((c) => c.fields.pop(), '1.2.1'),
|
||||
);
|
||||
expect(verdict.compatible).toBe(false);
|
||||
});
|
||||
|
||||
it('allows genuinely additive changes without a major bump', () => {
|
||||
const additive = next((c) => {
|
||||
c.fields.push({ name: 'mileage_km', type: 'int64', nullable: true, role: 'measure' });
|
||||
c.measures.push('mileage_km');
|
||||
c.quality_rules.push({
|
||||
rule_id: 'qr_mileage_range',
|
||||
kind: 'range',
|
||||
field_name: 'mileage_km',
|
||||
severity: 'warn',
|
||||
});
|
||||
c.allowed_purposes.push('valuation');
|
||||
c.retention_days = 1095;
|
||||
c.freshness_slo_seconds = 1800;
|
||||
}, '1.3.0');
|
||||
const verdict = checkContractCompatibility(base(), additive);
|
||||
expect(verdict.compatible).toBe(true);
|
||||
expect(verdict.breaking).toEqual([]);
|
||||
expect(verdict.explicitly_versioned).toBe(false);
|
||||
});
|
||||
|
||||
it('refuses a version that does not move forward', () => {
|
||||
expect(
|
||||
checkContractCompatibility(
|
||||
base(),
|
||||
next(() => {}, '1.2.0'),
|
||||
).compatible,
|
||||
).toBe(false);
|
||||
expect(
|
||||
checkContractCompatibility(
|
||||
base(),
|
||||
next(() => {}, '1.1.9'),
|
||||
).compatible,
|
||||
).toBe(false);
|
||||
expect(
|
||||
checkContractCompatibility(
|
||||
base(),
|
||||
next(() => {}, '0.9.0'),
|
||||
).compatible,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it('treats date -> timestamp as a safe widening, and int64 -> float64 as NOT one', () => {
|
||||
const widened = next((c) => {
|
||||
c.fields.push({ name: 'sold_on', type: 'date', nullable: true, role: 'attribute' });
|
||||
}, '1.3.0');
|
||||
const later = JSON.parse(JSON.stringify(widened)) as DatasetContract;
|
||||
later.fields[later.fields.length - 1].type = 'timestamp';
|
||||
later.version = '1.4.0';
|
||||
expect(checkContractCompatibility(widened, later).compatible).toBe(true);
|
||||
|
||||
const lossy = next((c) => {
|
||||
c.fields[2].type = 'float64';
|
||||
}, '1.3.0');
|
||||
expect(checkContractCompatibility(base(), lossy).compatible).toBe(false);
|
||||
});
|
||||
|
||||
it('assertContractCompatible throws a CONFLICT rather than returning a verdict nobody reads', () => {
|
||||
expect(() =>
|
||||
assertContractCompatible(
|
||||
base(),
|
||||
next((c) => c.fields.pop(), '1.3.0'),
|
||||
),
|
||||
).toThrowError(/MAJOR/);
|
||||
expect(() =>
|
||||
assertContractCompatible(
|
||||
base(),
|
||||
next(() => {}, '1.3.0'),
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('refuses to compare contracts for different datasets', () => {
|
||||
const other = next((c) => {
|
||||
c.dataset_id = 'ds_other';
|
||||
}, '1.3.0');
|
||||
expect(() => diffContracts(base(), other)).toThrowError(/SAME dataset/);
|
||||
});
|
||||
|
||||
it('validateContract catches internally inconsistent contracts', () => {
|
||||
expect(() => validateContract(base())).not.toThrow();
|
||||
expect(() => validateContract({ ...base(), version: '1.2' })).toThrowError(/major.minor.patch/);
|
||||
expect(() => validateContract({ ...base(), fields: [] })).toThrowError(/no fields/);
|
||||
expect(() => validateContract({ ...base(), dimensions: ['nope'] })).toThrowError(/unknown field/);
|
||||
expect(() => validateContract({ ...base(), primary_identifiers: [] })).toThrowError(
|
||||
/no primary identifier/,
|
||||
);
|
||||
expect(() => validateContract({ ...base(), allowed_purposes: [] })).toThrowError(/allowed_purposes/);
|
||||
expect(() => validateContract({ ...base(), freshness_slo_seconds: 0 })).toThrowError(/freshness/);
|
||||
const dup = base();
|
||||
dup.fields.push({ ...dup.fields[0] });
|
||||
expect(() => validateContract(dup)).toThrowError(/duplicate field/);
|
||||
});
|
||||
|
||||
it('contractHash is order-insensitive over fields but sensitive to meaning', () => {
|
||||
const a = base();
|
||||
const reordered = JSON.parse(JSON.stringify(a)) as DatasetContract;
|
||||
reordered.fields.reverse();
|
||||
expect(contractHash(reordered)).toBe(contractHash(a));
|
||||
|
||||
const changed = JSON.parse(JSON.stringify(a)) as DatasetContract;
|
||||
changed.fields[1].nullable = true;
|
||||
expect(contractHash(changed)).not.toBe(contractHash(a));
|
||||
});
|
||||
|
||||
it('parseSemVer rejects anything that is not major.minor.patch', () => {
|
||||
expect(parseSemVer('2.10.3')).toEqual({ major: 2, minor: 10, patch: 3 });
|
||||
for (const bad of ['v1.0.0', '1.0', '1.0.0-rc1', 'latest', '']) {
|
||||
expect(() => parseSemVer(bad)).toThrowError(/major.minor.patch/);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,321 @@
|
||||
/**
|
||||
* tests/analytics/dbt-contract.test.ts
|
||||
* =====================================
|
||||
* BI-P022 — DBT CORE CANONICAL TRANSFORMATION (the CONTRACT).
|
||||
*
|
||||
* This repo does not run dbt; N0D (n0d#38) does, against this contract. So
|
||||
* what is testable here is exactly what the contract must refuse, and the
|
||||
* interesting refusals are the ones that look like successes:
|
||||
*
|
||||
* * `status: "success"` with ZERO nodes executed — a dbt selector that
|
||||
* matches nothing exits 0. The dbt-shaped false green.
|
||||
* * a result whose observed dbt version differs from the pin — the models
|
||||
* mean something different and nothing says so.
|
||||
* * a branch name as the revision — "main" today and "main" tomorrow are
|
||||
* different projects, and BI-P022's DoD is about reproducibility.
|
||||
* * a production run against an unreviewed runtime, which is BI-P022's
|
||||
* "after current license/security verification" turned into a gate.
|
||||
*
|
||||
* The scaffold itself is asserted against the filesystem, because a directory
|
||||
* convention that nothing checks is a directory convention that drifts.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
assertDbtRuntimeCertified,
|
||||
assertLayerDependenciesLegal,
|
||||
assertValidDbtJobRequest,
|
||||
assertValidDbtJobResult,
|
||||
DBT_LAYER_TIERS,
|
||||
DBT_LAYERS,
|
||||
DBT_RUNTIME_PIN,
|
||||
REQUIRED_DBT_ARTIFACTS,
|
||||
REQUIRED_DBT_DIRECTORIES,
|
||||
tierForModelPath,
|
||||
type DbtJobRequest,
|
||||
type DbtJobResult,
|
||||
} from '@/src/analytics/transform/dbt-contract';
|
||||
|
||||
const DBT_ROOT = path.join(process.cwd(), 'analytics/dbt');
|
||||
const SHA = 'a'.repeat(40);
|
||||
|
||||
const CERTIFIED_PIN = {
|
||||
...DBT_RUNTIME_PIN,
|
||||
licenseReviewed: true,
|
||||
securityReviewed: true,
|
||||
reviewedBy: 'u_1',
|
||||
reviewedAt: '2026-09-07T00:00:00Z',
|
||||
};
|
||||
|
||||
function request(over: Partial<DbtJobRequest> = {}): DbtJobRequest {
|
||||
return {
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
dbt_project: 'siax_analytics',
|
||||
revision: SHA,
|
||||
command: 'build',
|
||||
target_layer: 'marts',
|
||||
environment: 'ci',
|
||||
runtime: DBT_RUNTIME_PIN,
|
||||
idempotency_key: 'idem-1',
|
||||
expected_target_schema: 't_alpha_marts',
|
||||
...over,
|
||||
};
|
||||
}
|
||||
|
||||
function result(over: Partial<DbtJobResult> = {}): DbtJobResult {
|
||||
return {
|
||||
tenant_id: 't_alpha',
|
||||
dbt_project: 'siax_analytics',
|
||||
revision: SHA,
|
||||
command: 'build',
|
||||
status: 'success',
|
||||
started_at: '2026-09-07T00:00:00Z',
|
||||
finished_at: '2026-09-07T00:05:00Z',
|
||||
artifacts: {
|
||||
'manifest.json': 'st0re://a/manifest.json',
|
||||
'run_results.json': 'st0re://a/run_results.json',
|
||||
},
|
||||
nodes: [
|
||||
{ unique_id: 'model.siax_analytics.mart_sales_daily', resource_type: 'model', status: 'success' },
|
||||
],
|
||||
observed_dbt_version: DBT_RUNTIME_PIN.version,
|
||||
...over,
|
||||
};
|
||||
}
|
||||
|
||||
describe('BI-P022 — the scaffold exists and matches the declared conventions', () => {
|
||||
it.each([...REQUIRED_DBT_DIRECTORIES])('analytics/dbt/%s exists', (dir) => {
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, dir)), `${dir} is missing`).toBe(true);
|
||||
});
|
||||
|
||||
it('declares a reference project covering raw -> staging -> curated -> serving', () => {
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, 'models/sources/sources.yml'))).toBe(true);
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, 'models/staging/stg_sales_events.sql'))).toBe(true);
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, 'models/intermediate/int_sales_enriched.sql'))).toBe(true);
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, 'models/marts/mart_sales_daily.sql'))).toBe(true);
|
||||
expect(fs.existsSync(path.join(DBT_ROOT, 'snapshots/snap_customers.sql'))).toBe(true);
|
||||
});
|
||||
|
||||
it('the staging model applies the tenant predicate at the first modelled layer', () => {
|
||||
const sql = fs.readFileSync(path.join(DBT_ROOT, 'models/staging/stg_sales_events.sql'), 'utf8');
|
||||
expect(sql).toContain('where tenant_id = \'{{ var("siax_tenant_id") }}\'');
|
||||
});
|
||||
|
||||
it('the mart reads intermediate, never a source directly', () => {
|
||||
const sql = fs.readFileSync(path.join(DBT_ROOT, 'models/marts/mart_sales_daily.sql'), 'utf8');
|
||||
expect(sql).toContain("ref('int_sales_enriched')");
|
||||
expect(sql).not.toContain('source(');
|
||||
});
|
||||
|
||||
it('ships a test that fails on an EMPTY mart', () => {
|
||||
// Without it, every column test passes trivially over zero rows.
|
||||
const sql = fs.readFileSync(path.join(DBT_ROOT, 'tests/assert_mart_is_not_empty.sql'), 'utf8');
|
||||
expect(sql).toContain('= 0');
|
||||
});
|
||||
|
||||
it('ships a cross-tenant test even though it should be impossible to fail', () => {
|
||||
const sql = fs.readFileSync(path.join(DBT_ROOT, 'tests/assert_no_cross_tenant_rows.sql'), 'utf8');
|
||||
expect(sql).toContain('tenant_id !=');
|
||||
});
|
||||
|
||||
it("maps the four layers onto BI-P003's tiers", () => {
|
||||
expect(DBT_LAYER_TIERS).toEqual({
|
||||
sources: 'RAW',
|
||||
staging: 'NORMALIZED',
|
||||
intermediate: 'CURATED',
|
||||
marts: 'SERVING',
|
||||
});
|
||||
expect([...DBT_LAYERS]).toEqual(['sources', 'staging', 'intermediate', 'marts']);
|
||||
});
|
||||
|
||||
it('assigns a tier from a model path, and refuses one it cannot place', () => {
|
||||
expect(tierForModelPath('models/marts/mart_sales_daily.sql')).toBe('SERVING');
|
||||
expect(tierForModelPath('analytics/dbt/models/staging/x.sql')).toBe('NORMALIZED');
|
||||
expect(() => tierForModelPath('models/scratch/x.sql')).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P022 — the version rule is a GATE, not a paragraph', () => {
|
||||
it('the shipped pin is honestly UNREVIEWED', () => {
|
||||
// If someone flips these without doing the review, that is a deliberate
|
||||
// act visible in a diff — which is the point of storing the state.
|
||||
expect(DBT_RUNTIME_PIN.licenseReviewed).toBe(false);
|
||||
expect(DBT_RUNTIME_PIN.securityReviewed).toBe(false);
|
||||
expect(DBT_RUNTIME_PIN.line).toBe('stable');
|
||||
});
|
||||
|
||||
it('refuses a PRODUCTION run against an unreviewed runtime', () => {
|
||||
expect(() => assertDbtRuntimeCertified(DBT_RUNTIME_PIN, 'production')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('allows development and CI against the same unreviewed runtime', () => {
|
||||
expect(() => assertDbtRuntimeCertified(DBT_RUNTIME_PIN, 'ci')).not.toThrow();
|
||||
expect(() => assertDbtRuntimeCertified(DBT_RUNTIME_PIN, 'development')).not.toThrow();
|
||||
});
|
||||
|
||||
it('allows production once both reviews are recorded', () => {
|
||||
expect(() => assertDbtRuntimeCertified(CERTIFIED_PIN, 'production')).not.toThrow();
|
||||
});
|
||||
|
||||
it('refuses an ALPHA line in production without a separate certification reference', () => {
|
||||
const alpha = { ...CERTIFIED_PIN, line: 'alpha' as const };
|
||||
expect(() => assertDbtRuntimeCertified(alpha, 'production')).toThrowError(SiaxError);
|
||||
expect(() =>
|
||||
assertDbtRuntimeCertified({ ...alpha, separateCertificationRef: 'CERT-2026-11' }, 'production'),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('refuses a version range — a pin is exact or it is not a pin', () => {
|
||||
expect(() => assertDbtRuntimeCertified({ ...CERTIFIED_PIN, version: '1.10' }, 'ci')).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
expect(() => assertDbtRuntimeCertified({ ...CERTIFIED_PIN, version: '^1.10.0' }, 'ci')).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P022 — the job request', () => {
|
||||
it('accepts a well-formed request', () => {
|
||||
expect(() => assertValidDbtJobRequest(request())).not.toThrow();
|
||||
});
|
||||
|
||||
it("refuses a branch name as the revision — BI-P022's DoD is reproducibility", () => {
|
||||
for (const rev of ['main', 'HEAD', 'v1.0.0', 'a'.repeat(39)]) {
|
||||
expect(() => assertValidDbtJobRequest(request({ revision: rev }))).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses a target schema that is not scoped to the tenant', () => {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
assertValidDbtJobRequest(request({ expected_target_schema: 't_beta_marts' }));
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect((thrown as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
});
|
||||
|
||||
it('refuses a selector carrying shell metacharacters', () => {
|
||||
for (const selector of ['stg_sales; rm -rf /', '$(whoami)', 'a`b`', 'x && y', 'a|b']) {
|
||||
expect(() => assertValidDbtJobRequest(request({ select: [selector] }))).toThrowError(SiaxError);
|
||||
}
|
||||
// ...while accepting real dbt selector syntax.
|
||||
expect(() =>
|
||||
assertValidDbtJobRequest(
|
||||
request({ select: ['tag:tier:SERVING+', 'state:modified', '+mart_sales_daily'] }),
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('refuses a job targeting the sources layer — sources are declared, not built', () => {
|
||||
expect(() => assertValidDbtJobRequest(request({ target_layer: 'sources' }))).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a request with no idempotency key', () => {
|
||||
expect(() => assertValidDbtJobRequest(request({ idempotency_key: '' }))).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a production request on the unreviewed pin', () => {
|
||||
expect(() =>
|
||||
assertValidDbtJobRequest(
|
||||
request({ environment: 'production', expected_target_schema: 't_alpha_marts' }),
|
||||
),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P022 — the job RESULT is untrusted input', () => {
|
||||
it('accepts a well-formed result', () => {
|
||||
expect(() => assertValidDbtJobResult(result(), request())).not.toThrow();
|
||||
});
|
||||
|
||||
it('REFUSES success with zero nodes — a selector matching nothing exits 0', () => {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
assertValidDbtJobResult(result({ nodes: [] }), request());
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect(thrown).toBeInstanceOf(SiaxError);
|
||||
expect((thrown as SiaxError).message).toContain('zero nodes');
|
||||
});
|
||||
|
||||
it('refuses success while nodes failed', () => {
|
||||
expect(() =>
|
||||
assertValidDbtJobResult(
|
||||
result({ nodes: [{ unique_id: 't1', resource_type: 'test', status: 'fail' }] }),
|
||||
request(),
|
||||
),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a runtime that is not the pinned one', () => {
|
||||
expect(() => assertValidDbtJobResult(result({ observed_dbt_version: '1.9.0' }), request())).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
|
||||
it('refuses a result for a different revision', () => {
|
||||
expect(() => assertValidDbtJobResult(result({ revision: 'b'.repeat(40) }), request())).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
|
||||
it('refuses a result for a different tenant', () => {
|
||||
expect(() => assertValidDbtJobResult(result({ tenant_id: 't_beta' }), request())).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it.each([...REQUIRED_DBT_ARTIFACTS])('refuses a result missing %s', (artifact) => {
|
||||
const artifacts = { ...result().artifacts };
|
||||
delete artifacts[artifact];
|
||||
expect(() => assertValidDbtJobResult(result({ artifacts }), request())).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P022 — layer dependencies are checked against the graph, not the convention', () => {
|
||||
it("accepts the reference project's own edges", () => {
|
||||
expect(() =>
|
||||
assertLayerDependenciesLegal([
|
||||
{ from: 'models/staging/stg_sales_events.sql', to: 'models/sources/sources.yml' },
|
||||
{ from: 'models/intermediate/int_sales_enriched.sql', to: 'models/staging/stg_sales_events.sql' },
|
||||
{ from: 'models/marts/mart_sales_daily.sql', to: 'models/intermediate/int_sales_enriched.sql' },
|
||||
]),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('refuses a mart reading a source directly — raw data reaching a dashboard', () => {
|
||||
expect(() =>
|
||||
assertLayerDependenciesLegal([
|
||||
{ from: 'models/marts/mart_sales_daily.sql', to: 'models/sources/sources.yml' },
|
||||
]),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a mart reading staging — one layer skipped is still a skip', () => {
|
||||
expect(() =>
|
||||
assertLayerDependenciesLegal([
|
||||
{ from: 'models/marts/mart_sales_daily.sql', to: 'models/staging/stg_sales_events.sql' },
|
||||
]),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a staging model reading a mart — an upward edge', () => {
|
||||
expect(() =>
|
||||
assertLayerDependenciesLegal([
|
||||
{ from: 'models/staging/stg_sales_events.sql', to: 'models/marts/mart_sales_daily.sql' },
|
||||
]),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('allows a model reading another in the same layer', () => {
|
||||
expect(() =>
|
||||
assertLayerDependenciesLegal([
|
||||
{ from: 'models/staging/stg_sales_events.sql', to: 'models/staging/stg_customers.sql' },
|
||||
]),
|
||||
).not.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,326 @@
|
||||
/**
|
||||
* tests/analytics/duckdb-provider.test.ts
|
||||
* ========================================
|
||||
* BI-P014 — the parts provable without a DuckDB, plus the pin on the parts
|
||||
* that are not.
|
||||
*
|
||||
* The live suite (tests/duckdb/duckdb-provider.live.test.ts) only
|
||||
* runs when DUCKDB_PYTHON is set. On a runner without it, it contributes
|
||||
* nothing — so the recorded evidence is committed and THIS file, which never
|
||||
* skips, checks it. In particular it pins the finding that makes layer 2 real:
|
||||
*
|
||||
* `allowed_directories` WITHOUT `enable_external_access=false` permits
|
||||
* /etc/passwd. Measured, recorded, and asserted here — because a comment
|
||||
* saying so would rot the moment someone "simplified" the bootstrap.
|
||||
*/
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
ArtifactMountRegistry,
|
||||
assertSessionSandboxed,
|
||||
duckDbSessionBootstrap,
|
||||
escapeLiteral,
|
||||
DuckDbAnalyticsProvider,
|
||||
REQUIRED_SANDBOX_SETTINGS,
|
||||
type DuckDbRunner,
|
||||
} from '@/src/analytics/providers/duckdb-provider';
|
||||
|
||||
const EVIDENCE_PATH = path.join(process.cwd(), 'evidence/bi-p014/duckdb-sandbox.json');
|
||||
const FIXTURES = path.join(process.cwd(), 'tests/fixtures/duckdb');
|
||||
const IDENTITY = { tenant_id: 't_alpha', principal_id: 'u_1' };
|
||||
|
||||
const capturingRunner = (): DuckDbRunner & { lastSql?: string; lastBootstrap?: readonly string[] } => {
|
||||
const r: DuckDbRunner & { lastSql?: string; lastBootstrap?: readonly string[] } = {
|
||||
engine: 'duckdb',
|
||||
async run({ bootstrap, sql }) {
|
||||
r.lastSql = sql;
|
||||
r.lastBootstrap = bootstrap;
|
||||
return [];
|
||||
},
|
||||
};
|
||||
return r;
|
||||
};
|
||||
|
||||
describe('BI-P014 — the session bootstrap is one unit, not three settings', () => {
|
||||
it('emits all three statements, external access LAST-but-one and the lock last', () => {
|
||||
const stmts = duckDbSessionBootstrap(['/mnt/artifacts']);
|
||||
expect(stmts).toHaveLength(3);
|
||||
expect(stmts[0]).toContain('allowed_directories');
|
||||
expect(stmts[1]).toBe('SET enable_external_access=false');
|
||||
expect(stmts[2]).toBe('SET lock_configuration=true');
|
||||
});
|
||||
|
||||
it('refuses an EMPTY allow-list — that is not a sandbox', () => {
|
||||
expect(() => duckDbSessionBootstrap([])).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a relative or quote-carrying directory', () => {
|
||||
expect(() => duckDbSessionBootstrap(['relative/path'])).toThrowError(SiaxError);
|
||||
expect(() => duckDbSessionBootstrap(["/mnt/it's"])).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it.each([...REQUIRED_SANDBOX_SETTINGS])(
|
||||
'assertSessionSandboxed refuses a session missing %s',
|
||||
(setting) => {
|
||||
const stmts = duckDbSessionBootstrap(['/mnt/artifacts']).filter((s) => !s.includes(setting));
|
||||
expect(() => assertSessionSandboxed(stmts)).toThrowError(SiaxError);
|
||||
},
|
||||
);
|
||||
|
||||
it('refuses a session that sets the allow-list but leaves external access ON', () => {
|
||||
// The exact naive spelling. It looks configured and permits everything.
|
||||
const naive = [
|
||||
"SET allowed_directories=['/mnt/artifacts']",
|
||||
'SET enable_external_access=true',
|
||||
'SET lock_configuration=true',
|
||||
];
|
||||
expect(() => assertSessionSandboxed(naive)).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P014 — the mount registry refuses everything that is not a mounted artifact', () => {
|
||||
function registry(): ArtifactMountRegistry {
|
||||
// A fake realpath, so path semantics are tested without touching disk.
|
||||
const fakeReal = (p: string) => (p.includes('symlinked') ? '/etc/passwd' : p);
|
||||
const reg = new ArtifactMountRegistry('/mnt/artifacts', fakeReal);
|
||||
reg.register({
|
||||
artifact_id: 'a_ok',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'st0re://x',
|
||||
relative_path: 'sales.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: 10,
|
||||
});
|
||||
return reg;
|
||||
}
|
||||
|
||||
it('resolves a mounted artifact for its owner', () => {
|
||||
expect(registry().resolve(IDENTITY, 'a_ok').absolutePath).toBe('/mnt/artifacts/sales.parquet');
|
||||
});
|
||||
|
||||
it('refuses an absolute mount path', () => {
|
||||
expect(() =>
|
||||
registry().register({
|
||||
artifact_id: 'a_abs',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'x',
|
||||
relative_path: '/etc/passwd',
|
||||
format: 'csv',
|
||||
size_bytes: 1,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a path that resolves outside the root once symlinks are followed', () => {
|
||||
expect(() =>
|
||||
registry().register({
|
||||
artifact_id: 'a_link',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'x',
|
||||
relative_path: 'symlinked.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: 1,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it("refuses a sibling directory that merely shares the root's prefix", () => {
|
||||
// `startsWith('/mnt/artifacts')` alone would accept `/mnt/artifacts-evil`.
|
||||
const reg = new ArtifactMountRegistry('/mnt/artifacts', (p) =>
|
||||
p.includes('sibling') ? '/mnt/artifacts-evil/x.parquet' : p,
|
||||
);
|
||||
expect(() =>
|
||||
reg.register({
|
||||
artifact_id: 'a_sib',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'x',
|
||||
relative_path: 'sibling.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: 1,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a request with no verified tenant', () => {
|
||||
expect(() => registry().resolve({ tenant_id: '', principal_id: 'u' }, 'a_ok')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('distinguishes NOT_FOUND from AUTHORIZATION_DENIED', () => {
|
||||
const reg = registry();
|
||||
try {
|
||||
reg.resolve(IDENTITY, 'a_missing');
|
||||
} catch (e) {
|
||||
expect((e as SiaxError).code).toBe('NOT_FOUND');
|
||||
}
|
||||
try {
|
||||
reg.resolve({ tenant_id: 't_beta', principal_id: 'u' }, 'a_ok');
|
||||
} catch (e) {
|
||||
// An attempted cross-tenant read must be visible in the audit trail as
|
||||
// one, not disguised as a missing object.
|
||||
expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses an artifact id that is not registry-safe', () => {
|
||||
for (const bad of ['../x', 'a b', "a'b", 'a/b', '']) {
|
||||
expect(() => registry().resolve(IDENTITY, bad)).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P014 — the query builder has no caller-SQL surface', () => {
|
||||
function provider(runner: DuckDbRunner, sizeBytes = 10) {
|
||||
const reg = new ArtifactMountRegistry('/mnt/artifacts', (p) => p);
|
||||
reg.register({
|
||||
artifact_id: 'a_ok',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'x',
|
||||
relative_path: 'sales.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: sizeBytes,
|
||||
});
|
||||
return new DuckDbAnalyticsProvider(reg, runner);
|
||||
}
|
||||
|
||||
it('builds a reader from the RESOLVED path, never from caller text', async () => {
|
||||
const r = capturingRunner();
|
||||
await provider(r).query(IDENTITY, { artifact_id: 'a_ok', select: ['country'] });
|
||||
expect(r.lastSql).toContain("read_parquet('/mnt/artifacts/sales.parquet')");
|
||||
});
|
||||
|
||||
it('always applies the sandbox bootstrap before the query', async () => {
|
||||
const r = capturingRunner();
|
||||
await provider(r).query(IDENTITY, { artifact_id: 'a_ok' });
|
||||
expect(() => assertSessionSandboxed(r.lastBootstrap ?? [])).not.toThrow();
|
||||
});
|
||||
|
||||
it.each(['a b', 'x; DROP TABLE t', '*', '1=1', "a'", '../x'])(
|
||||
'refuses %s as a column name',
|
||||
async (col) => {
|
||||
await expect(
|
||||
provider(capturingRunner()).query(IDENTITY, { artifact_id: 'a_ok', select: [col] }),
|
||||
).rejects.toBeInstanceOf(SiaxError);
|
||||
},
|
||||
);
|
||||
|
||||
it('hands a heavy artifact to N0D instead of running it locally', async () => {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
await provider(capturingRunner(), 40 * 1024 * 1024 * 1024).query(IDENTITY, { artifact_id: 'a_ok' });
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect((thrown as SiaxError).code).toBe('CAPABILITY_UNAVAILABLE');
|
||||
expect((thrown as SiaxError).message).toContain('N0D');
|
||||
});
|
||||
|
||||
it("escapes a literal by DOUBLING the quote, which is DuckDB's only escape", () => {
|
||||
// MEASURED on DuckDB 1.5.5 rather than assumed, because the whole escaping
|
||||
// strategy rests on it: `SELECT length('a\\b')` returns 4, so a backslash
|
||||
// is a literal character; and `SELECT 'a\''` is a PARSER ERROR
|
||||
// ("unterminated quoted string"), which is what a non-escaping backslash
|
||||
// produces. A dialect where `\'` closed the literal would make doubling
|
||||
// insufficient.
|
||||
expect(escapeLiteral("O'Brien")).toBe("O''Brien");
|
||||
// A backslash is NOT an escape inside a DuckDB single-quoted string, so it
|
||||
// must survive untouched rather than being "helpfully" doubled.
|
||||
expect(escapeLiteral("a\\'b")).toBe("a\\''b");
|
||||
expect(escapeLiteral("x' OR '1'='1")).toBe("x'' OR ''1''=''1");
|
||||
});
|
||||
|
||||
it('refuses a NUL byte in a filter value rather than escaping it', () => {
|
||||
expect(() => escapeLiteral('a\u0000b')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('declares which formats have actually been PROVEN, and why the others have not', () => {
|
||||
const readiness = provider(capturingRunner()).readiness();
|
||||
expect(readiness.proven).toContain('parquet');
|
||||
expect(readiness.proven).toContain('iceberg');
|
||||
const arrow = readiness.unproven.find((u) => u.format === 'arrow_ipc');
|
||||
expect(arrow?.reason).toContain('network install');
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P014 — the committed evidence, checked by a test that never skips', () => {
|
||||
it('the evidence file exists', () => {
|
||||
expect(
|
||||
fs.existsSync(EVIDENCE_PATH),
|
||||
'evidence/bi-p014/duckdb-sandbox.json is missing — run the live suite with DUCKDB_PYTHON set',
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
const evidence = fs.existsSync(EVIDENCE_PATH)
|
||||
? (JSON.parse(fs.readFileSync(EVIDENCE_PATH, 'utf8')) as Record<string, never>)
|
||||
: ({} as Record<string, never>);
|
||||
|
||||
it('was recorded against a real DuckDB', () => {
|
||||
expect(String(evidence.duckdb_version ?? '')).toMatch(/^\d+\.\d+/);
|
||||
});
|
||||
|
||||
it('PINS the finding: allowed_directories alone read /etc/passwd', () => {
|
||||
// The load-bearing assertion of this whole file. If someone "simplifies"
|
||||
// the bootstrap down to the allow-list, the module comment would become a
|
||||
// lie quietly; this keeps the measurement attached to the build.
|
||||
const naive = evidence.naive_allowed_directories_is_a_noop as unknown as {
|
||||
read_etc_passwd_succeeded: boolean;
|
||||
statements: string[];
|
||||
};
|
||||
expect(naive).toBeDefined();
|
||||
expect(naive.read_etc_passwd_succeeded).toBe(true);
|
||||
expect(naive.statements.join(' ')).not.toContain('enable_external_access');
|
||||
});
|
||||
|
||||
it('records that NO bypass attempt succeeded with the full bootstrap', () => {
|
||||
const attempts = evidence.sandbox_bypass_attempts as unknown as Array<{ id: string; succeeded: boolean }>;
|
||||
expect(Array.isArray(attempts)).toBe(true);
|
||||
expect(attempts.length).toBeGreaterThanOrEqual(10);
|
||||
expect(attempts.filter((a) => a.succeeded).map((a) => a.id)).toEqual([]);
|
||||
});
|
||||
|
||||
it('records the counterfactual — the mounted file WAS readable in the same session', () => {
|
||||
// Without this, "no attempt succeeded" is equally consistent with a
|
||||
// sandbox that blocks everything, which is an outage, not a control.
|
||||
expect(evidence.counterfactual_mounted_file_readable).toBe(true);
|
||||
});
|
||||
|
||||
it('records the Iceberg snapshot read, whose fixture is deliberately not committed', () => {
|
||||
// pyiceberg embeds ABSOLUTE paths in its manifests, so a committed Iceberg
|
||||
// table would only work on the machine that built it. The recorded result
|
||||
// is the artefact instead.
|
||||
const iceberg = evidence.iceberg as unknown as { totals: Record<string, number> };
|
||||
expect(iceberg?.totals).toEqual({ NO: 20, SE: 40 });
|
||||
});
|
||||
|
||||
it('records that a locked session could not re-open its own sandbox', () => {
|
||||
const reopened = evidence.reconfiguration_refused as unknown as Array<{ refused: boolean }>;
|
||||
expect(reopened.length).toBe(3);
|
||||
expect(reopened.every((r) => r.refused)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P014 — the committed fixtures', () => {
|
||||
it('ships the Parquet and CSV fixtures the live suite reads', () => {
|
||||
expect(fs.existsSync(path.join(FIXTURES, 'sales.parquet'))).toBe(true);
|
||||
expect(fs.existsSync(path.join(FIXTURES, 'customers.csv'))).toBe(true);
|
||||
});
|
||||
|
||||
it('does NOT ship the Iceberg table, because its manifests carry absolute paths', () => {
|
||||
// Asserted against GIT, not the filesystem. The claim is about what is
|
||||
// COMMITTED; the live suite REBUILDS that table locally, so a filesystem
|
||||
// check fails whenever both suites run in one pass — it was testing the
|
||||
// wrong thing rather than catching a real problem.
|
||||
const tracked = execFileSync('git', ['ls-files', 'tests/fixtures/duckdb/'], {
|
||||
encoding: 'utf8',
|
||||
cwd: process.cwd(),
|
||||
})
|
||||
.split('\n')
|
||||
.filter(Boolean);
|
||||
// The parquet/csv fixtures ARE tracked, so a version that shipped nothing
|
||||
// would fail here too rather than passing vacuously.
|
||||
expect(tracked.length).toBeGreaterThan(0);
|
||||
expect(tracked.filter((f) => f.includes('/iceberg'))).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,327 @@
|
||||
/**
|
||||
* tests/analytics/materialization-drift.test.ts
|
||||
* ==============================================
|
||||
* BI-P105 — MATERIALIZATION / PRE-AGGREGATION.
|
||||
*
|
||||
* The DoD asks for measured improvement and documented freshness semantics.
|
||||
* The failure mode it does not name, and the one that actually costs money, is
|
||||
* a pre-aggregate that returns a confident wrong number. So every test here is
|
||||
* written as an attack on the router:
|
||||
*
|
||||
* - a drifted aggregate must NOT serve, and the counterfactual (a naive
|
||||
* router that only checks staleness) must serve it — otherwise the guard
|
||||
* is not known to be doing anything;
|
||||
* - a MISSING bucket must count as drift even though every value present is
|
||||
* correct;
|
||||
* - a comparison over an empty window must be `insufficient_data`, never
|
||||
* `match`;
|
||||
* - an aggregate that has never been verified must not serve, because on
|
||||
* launch day it is exactly as unproven as a drifted one.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
applyDriftReport,
|
||||
detectDrift,
|
||||
type AggregateBucket,
|
||||
} from '@/src/analytics/materialization/drift-detector';
|
||||
import {
|
||||
assertSpec,
|
||||
describeRouting,
|
||||
materializationStaleness,
|
||||
selectQuerySource,
|
||||
type MaterializationSpec,
|
||||
type MaterializationStatus,
|
||||
} from '@/src/analytics/materialization/materialization';
|
||||
import type { AnalyticsQueryRequest } from '@/src/analytics/contract/query-request';
|
||||
|
||||
const NOW = new Date('2026-09-07T12:00:00.000Z');
|
||||
const TOLERANCE = { absolute: 0.5, relative: 0.001 };
|
||||
|
||||
const SPEC: MaterializationSpec = {
|
||||
materialization_id: 'mv_sales_daily',
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
dataset: 'ds_sales',
|
||||
strategy: 'clickhouse_materialized_view',
|
||||
target_ref: 'opt_sales_daily',
|
||||
metrics: ['revenue', 'orders'],
|
||||
dimensions: ['order_date', 'region'],
|
||||
time_dimension: 'order_date',
|
||||
grain: 'day',
|
||||
max_staleness_seconds: 3600,
|
||||
drift_check_interval_seconds: 86_400,
|
||||
tolerance: TOLERANCE,
|
||||
};
|
||||
|
||||
/** Fresh, recently verified, matching. The only state that may serve. */
|
||||
function healthyStatus(): MaterializationStatus {
|
||||
return {
|
||||
materialization_id: SPEC.materialization_id,
|
||||
state: 'serving',
|
||||
data_watermark: '2026-09-07T11:45:00.000Z',
|
||||
last_refresh_at: '2026-09-07T11:46:00.000Z',
|
||||
last_drift_check_at: '2026-09-07T06:00:00.000Z',
|
||||
last_drift_verdict: 'match',
|
||||
};
|
||||
}
|
||||
|
||||
const REQUEST: AnalyticsQueryRequest = {
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['revenue'],
|
||||
dimensions: ['order_date'],
|
||||
filters: [{ dimension: 'region', operator: 'eq', values: ['SE'] }],
|
||||
timeRange: { from: '2026-09-01T00:00:00.000Z', to: '2026-09-07T00:00:00.000Z', grain: 'day' },
|
||||
};
|
||||
|
||||
/**
|
||||
* The router someone writes when they have thought about staleness but not
|
||||
* about correctness. It exists here as the counterfactual: it must SERVE the
|
||||
* drifted aggregate that `selectQuerySource` refuses.
|
||||
*/
|
||||
function naiveRouter(status: MaterializationStatus, now: Date): 'materialization' | 'base_table' {
|
||||
const staleness = materializationStaleness(status, now) ?? 0;
|
||||
return staleness <= SPEC.max_staleness_seconds ? 'materialization' : 'base_table';
|
||||
}
|
||||
|
||||
function buckets(spec: Record<string, [number, number]>): AggregateBucket[] {
|
||||
return Object.entries(spec).map(([key, [revenue, orders]]) => ({ key, values: { revenue, orders } }));
|
||||
}
|
||||
|
||||
const SOURCE = buckets({
|
||||
'2026-09-01|SE': [120_000, 410],
|
||||
'2026-09-02|SE': [131_500, 442],
|
||||
'2026-09-03|SE': [98_250, 305],
|
||||
'2026-09-04|SE': [140_000, 480],
|
||||
});
|
||||
|
||||
describe('BI-P105 drift detection', () => {
|
||||
it('an identical aggregate matches', () => {
|
||||
const report = detectDrift({
|
||||
fromSource: SOURCE,
|
||||
fromAggregate: SOURCE,
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue', 'orders'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('match');
|
||||
expect(report.buckets_compared).toBe(4);
|
||||
expect(report.totals.revenue.delta).toBe(0);
|
||||
});
|
||||
|
||||
it('a value beyond tolerance is drift, and the report says what a caller would have been told', () => {
|
||||
const drifted = buckets({
|
||||
'2026-09-01|SE': [120_000, 410],
|
||||
'2026-09-02|SE': [131_500, 442],
|
||||
'2026-09-03|SE': [98_250, 305],
|
||||
// A source row was deleted (GDPR erasure) but the aggregate still counts it.
|
||||
'2026-09-04|SE': [152_400, 495],
|
||||
});
|
||||
const report = detectDrift({
|
||||
fromSource: SOURCE,
|
||||
fromAggregate: drifted,
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue', 'orders'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('drifted');
|
||||
expect(report.worst?.key).toBe('2026-09-04|SE');
|
||||
expect(report.worst?.absolute_delta).toBe(12_400);
|
||||
expect(report.totals.revenue.aggregate - report.totals.revenue.source).toBe(12_400);
|
||||
});
|
||||
|
||||
it('a MISSING bucket is drift even though every value present is correct', () => {
|
||||
const lateArriving = SOURCE.filter((b) => b.key !== '2026-09-04|SE');
|
||||
const report = detectDrift({
|
||||
fromSource: SOURCE,
|
||||
fromAggregate: lateArriving,
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue', 'orders'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.discrepancies).toHaveLength(0); // every compared value agrees
|
||||
expect(report.verdict).toBe('drifted'); // and it is still wrong
|
||||
expect(report.missing_in_aggregate).toEqual(['2026-09-04|SE']);
|
||||
expect(report.totals.revenue.delta).toBe(-140_000);
|
||||
});
|
||||
|
||||
it('an EXTRA bucket is drift — the source rows are gone, the aggregate is not', () => {
|
||||
const stale = [...SOURCE, { key: '2026-08-31|SE', values: { revenue: 90_000, orders: 300 } }];
|
||||
const report = detectDrift({
|
||||
fromSource: SOURCE,
|
||||
fromAggregate: stale,
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue', 'orders'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('drifted');
|
||||
expect(report.extra_in_aggregate).toEqual(['2026-08-31|SE']);
|
||||
});
|
||||
|
||||
it('an EMPTY comparison is insufficient_data, not match', () => {
|
||||
const report = detectDrift({
|
||||
fromSource: [],
|
||||
fromAggregate: [],
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('insufficient_data');
|
||||
expect(report.buckets_compared).toBe(0);
|
||||
// And it must not be allowed to serve on the strength of that.
|
||||
const status = applyDriftReport(healthyStatus(), report);
|
||||
expect(status.state).toBe('drifted');
|
||||
});
|
||||
|
||||
it('both tolerances must hold — a large bucket cannot hide behind a relative bound', () => {
|
||||
const source = buckets({ 'b|SE': [40_000_000, 1] });
|
||||
const off = buckets({ 'b|SE': [40_020_000, 1] }); // 0.05%: inside relative, far outside absolute
|
||||
const report = detectDrift({
|
||||
fromSource: source,
|
||||
fromAggregate: off,
|
||||
tolerance: { absolute: 1000, relative: 0.001 },
|
||||
metrics: ['revenue'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('drifted');
|
||||
expect(report.worst?.relative_delta).toBeCloseTo(0.0005, 6);
|
||||
});
|
||||
|
||||
it('a bucket that should be zero and is not is drift, not a division error', () => {
|
||||
const report = detectDrift({
|
||||
fromSource: buckets({ 'b|SE': [0, 0] }),
|
||||
fromAggregate: buckets({ 'b|SE': [12, 1] }),
|
||||
tolerance: TOLERANCE,
|
||||
metrics: ['revenue'],
|
||||
now: NOW,
|
||||
});
|
||||
expect(report.verdict).toBe('drifted');
|
||||
expect(report.worst?.relative_delta).toBe(Number.POSITIVE_INFINITY);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P105 routing — a pre-aggregate serves only while it is provably current and undrifted', () => {
|
||||
it('serves when everything is proved', () => {
|
||||
const decision = selectQuerySource({ request: REQUEST, spec: SPEC, status: healthyStatus(), now: NOW });
|
||||
expect(decision.source).toBe('materialization');
|
||||
expect(describeRouting(decision)).toMatchObject({
|
||||
served_from: 'materialization',
|
||||
materialization_id: 'mv_sales_daily',
|
||||
staleness_seconds: 900,
|
||||
});
|
||||
});
|
||||
|
||||
it('a DRIFTED aggregate is refused — and the naive router serves it', () => {
|
||||
const drifted = applyDriftReport(healthyStatus(), {
|
||||
verdict: 'drifted',
|
||||
checked_at: '2026-09-07T11:00:00.000Z',
|
||||
buckets_compared: 4,
|
||||
missing_in_aggregate: [],
|
||||
extra_in_aggregate: [],
|
||||
discrepancies: [],
|
||||
tolerance: TOLERANCE,
|
||||
totals: {},
|
||||
});
|
||||
|
||||
const guarded = selectQuerySource({ request: REQUEST, spec: SPEC, status: drifted, now: NOW });
|
||||
expect(guarded.source).toBe('base_table');
|
||||
expect(guarded).toMatchObject({ refusal: 'state_not_serving' });
|
||||
|
||||
// The counterfactual: the same state, routed by staleness alone.
|
||||
expect(naiveRouter(drifted, NOW)).toBe('materialization');
|
||||
});
|
||||
|
||||
it('a NEVER-VERIFIED aggregate is refused — and the naive router serves it', () => {
|
||||
const brandNew: MaterializationStatus = {
|
||||
materialization_id: SPEC.materialization_id,
|
||||
state: 'serving',
|
||||
data_watermark: '2026-09-07T11:59:00.000Z',
|
||||
last_refresh_at: '2026-09-07T11:59:00.000Z',
|
||||
};
|
||||
const guarded = selectQuerySource({ request: REQUEST, spec: SPEC, status: brandNew, now: NOW });
|
||||
expect(guarded).toMatchObject({ source: 'base_table', refusal: 'drift_never_verified' });
|
||||
expect(naiveRouter(brandNew, NOW)).toBe('materialization');
|
||||
});
|
||||
|
||||
it('a verification older than the required interval is refused', () => {
|
||||
const status = { ...healthyStatus(), last_drift_check_at: '2026-09-05T06:00:00.000Z' };
|
||||
expect(selectQuerySource({ request: REQUEST, spec: SPEC, status, now: NOW })).toMatchObject({
|
||||
refusal: 'drift_verification_stale',
|
||||
});
|
||||
});
|
||||
|
||||
it('an UNKNOWN watermark is refused rather than treated as current', () => {
|
||||
const status = { ...healthyStatus(), data_watermark: undefined };
|
||||
expect(materializationStaleness(status, NOW)).toBeUndefined();
|
||||
expect(selectQuerySource({ request: REQUEST, spec: SPEC, status, now: NOW })).toMatchObject({
|
||||
refusal: 'watermark_unknown',
|
||||
});
|
||||
});
|
||||
|
||||
it('an aggregate older than its freshness contract is refused', () => {
|
||||
const status = { ...healthyStatus(), data_watermark: '2026-09-07T09:00:00.000Z' };
|
||||
expect(selectQuerySource({ request: REQUEST, spec: SPEC, status, now: NOW })).toMatchObject({
|
||||
refusal: 'staleness_exceeded',
|
||||
});
|
||||
});
|
||||
|
||||
it('a question that reaches past the watermark is refused, not silently shortened', () => {
|
||||
const request = { ...REQUEST, timeRange: { ...REQUEST.timeRange, to: '2026-09-07T12:00:00.000Z' } };
|
||||
expect(selectQuerySource({ request, spec: SPEC, status: healthyStatus(), now: NOW })).toMatchObject({
|
||||
refusal: 'window_beyond_watermark',
|
||||
});
|
||||
});
|
||||
|
||||
it('a filter on a dimension the aggregate summed across is refused', () => {
|
||||
const request = {
|
||||
...REQUEST,
|
||||
filters: [{ dimension: 'sales_channel', operator: 'eq' as const, values: ['web'] }],
|
||||
};
|
||||
const decision = selectQuerySource({ request, spec: SPEC, status: healthyStatus(), now: NOW });
|
||||
expect(decision).toMatchObject({ source: 'base_table', refusal: 'coverage_miss' });
|
||||
expect((decision as { detail: string }).detail).toMatch(/already summed across it/);
|
||||
});
|
||||
|
||||
it('a metric or dimension the aggregate does not carry is refused', () => {
|
||||
expect(
|
||||
selectQuerySource({
|
||||
request: { ...REQUEST, metrics: ['margin'] },
|
||||
spec: SPEC,
|
||||
status: healthyStatus(),
|
||||
now: NOW,
|
||||
}),
|
||||
).toMatchObject({ refusal: 'coverage_miss' });
|
||||
expect(
|
||||
selectQuerySource({
|
||||
request: { ...REQUEST, dimensions: ['product'] },
|
||||
spec: SPEC,
|
||||
status: healthyStatus(),
|
||||
now: NOW,
|
||||
}),
|
||||
).toMatchObject({ refusal: 'coverage_miss' });
|
||||
});
|
||||
|
||||
it('a daily aggregate cannot answer an hourly question, but can answer a monthly one', () => {
|
||||
const hourly = { ...REQUEST, timeRange: { ...REQUEST.timeRange, grain: 'hour' as const } };
|
||||
expect(
|
||||
selectQuerySource({ request: hourly, spec: SPEC, status: healthyStatus(), now: NOW }),
|
||||
).toMatchObject({ refusal: 'coverage_miss' });
|
||||
|
||||
const monthly = { ...REQUEST, timeRange: { ...REQUEST.timeRange, grain: 'month' as const } };
|
||||
expect(
|
||||
selectQuerySource({ request: monthly, spec: SPEC, status: healthyStatus(), now: NOW }).source,
|
||||
).toBe('materialization');
|
||||
});
|
||||
|
||||
it('a WEEKLY aggregate cannot answer a monthly question — weeks do not compose into months', () => {
|
||||
const weekly = { ...SPEC, grain: 'week' as const };
|
||||
const monthly = { ...REQUEST, timeRange: { ...REQUEST.timeRange, grain: 'month' as const } };
|
||||
expect(
|
||||
selectQuerySource({ request: monthly, spec: weekly, status: healthyStatus(), now: NOW }),
|
||||
).toMatchObject({ refusal: 'coverage_miss' });
|
||||
});
|
||||
|
||||
it('a spec with no drift check interval is refused at declaration time', () => {
|
||||
expect(() => assertSpec({ ...SPEC, drift_check_interval_seconds: 0 })).toThrow(/never re-verified/);
|
||||
expect(() => assertSpec(SPEC)).not.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,483 @@
|
||||
/**
|
||||
* tests/analytics/metric-governance.test.ts
|
||||
* ==========================================
|
||||
* BI-P028 (metric domain model), BI-P030 (semantic model registry),
|
||||
* BI-P031 (metric governance), BI-P029 (semantic provider — the parts not
|
||||
* needing a Python runtime).
|
||||
*
|
||||
* Each prompt's DoD is turned into something that can FAIL:
|
||||
*
|
||||
* BI-P028 "No production metric exists only inside a dashboard tool."
|
||||
* A dashboard panel carrying an inline aggregation / expression /
|
||||
* SQL is REFUSED, and so is one naming an unregistered metric.
|
||||
*
|
||||
* BI-P030 "MetricFlow can be replaced without breaking canonical SIAX
|
||||
* metric IDs." Two providers with different naming rules compile
|
||||
* the same registry version; the canonical id set must be
|
||||
* identical and the provider BINDINGS must differ — otherwise the
|
||||
* test would pass for a registry that simply has one provider.
|
||||
*
|
||||
* BI-P031 "Certified metric cannot be modified in-place; new version
|
||||
* required." Every semantic field is mutated one at a time and
|
||||
* each must be refused; every editorial field is mutated and each
|
||||
* must be allowed.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
assertMetricEditAllowed,
|
||||
assertPanelUsesRegisteredMetric,
|
||||
assertValidMetricSpec,
|
||||
certifyMetric,
|
||||
metricMeaningHash,
|
||||
nextMetricVersion,
|
||||
METRIC_STATUSES,
|
||||
type GovernedMetric,
|
||||
type MetricSpec,
|
||||
} from '@/src/analytics/metrics/metric-model';
|
||||
import {
|
||||
assertEngineNeutral,
|
||||
assertOnlySemanticModelFields,
|
||||
InMemorySemanticModelStore,
|
||||
SemanticModelRegistry,
|
||||
semanticModelHash,
|
||||
type SemanticModelVersion,
|
||||
} from '@/src/analytics/metrics/semantic-registry';
|
||||
import { MetricFlowProvider, type SiaxSemanticProvider } from '@/src/analytics/metrics/semantic-provider';
|
||||
import { compileRequestToSemantic } from '@/src/analytics/contract/compile-semantic';
|
||||
import {
|
||||
parseAnalyticsQueryRequest,
|
||||
queryResolutionFrom,
|
||||
resolveAnalyticsQuery,
|
||||
} from '@/src/analytics/contract/query-request';
|
||||
|
||||
const REVENUE: MetricSpec = {
|
||||
id: 'm_revenue',
|
||||
name: 'net_revenue',
|
||||
description: 'Invoiced revenue net of credit notes, in SEK, recognised on invoice date.',
|
||||
type: 'simple',
|
||||
measure: 'amount_sek',
|
||||
aggregation: 'sum',
|
||||
dimensions: ['country', 'channel'],
|
||||
filters: [{ dimension: 'channel', operator: 'ne', values: ['internal'] }],
|
||||
timeDimension: 'invoiced_at',
|
||||
unit: 'SEK',
|
||||
currency: 'SEK',
|
||||
format: 'currency',
|
||||
owner: 'finance@siax.io',
|
||||
version: 3,
|
||||
status: 'ACTIVE',
|
||||
};
|
||||
|
||||
const GOVERNED: GovernedMetric = {
|
||||
spec: REVENUE,
|
||||
governance: {
|
||||
certification: 'certified',
|
||||
business_definition: 'What we actually invoiced, after credits.',
|
||||
technical_definition: "sum(amount_sek) on ds_sales where channel != 'internal', by invoiced_at.",
|
||||
owner: 'finance@siax.io',
|
||||
lineage_refs: ['ds_sales@v42'],
|
||||
quality_status: 'passing',
|
||||
},
|
||||
};
|
||||
|
||||
describe('BI-P028 — a metric that cannot mean nothing', () => {
|
||||
it('accepts the golden metric', () => {
|
||||
expect(() => assertValidMetricSpec(REVENUE)).not.toThrow();
|
||||
});
|
||||
|
||||
const rejections: Array<[string, Partial<MetricSpec>]> = [
|
||||
['no description', { description: '' }],
|
||||
['no owner', { owner: '' }],
|
||||
['no time dimension', { timeDimension: '' }],
|
||||
['a ratio with no denominator', { type: 'ratio' }],
|
||||
['a denominator on a non-ratio', { denominator: 'orders' }],
|
||||
['currency format with no currency', { currency: undefined }],
|
||||
['a currency on a non-currency format', { format: 'integer' }],
|
||||
['a non-ISO currency', { currency: 'kronor' as string }],
|
||||
['a name that is not snake_case', { name: 'Net Revenue' }],
|
||||
['a duplicate dimension', { dimensions: ['country', 'country'] }],
|
||||
[
|
||||
'a filter on an undeclared dimension',
|
||||
{ filters: [{ dimension: 'segment', operator: 'eq', values: ['x'] }] },
|
||||
],
|
||||
['a value operator with no values', { filters: [{ dimension: 'channel', operator: 'eq', values: [] }] }],
|
||||
[
|
||||
'a presence operator with values',
|
||||
{ filters: [{ dimension: 'channel', operator: 'is_null', values: ['x'] }] },
|
||||
],
|
||||
['version zero', { version: 0 }],
|
||||
];
|
||||
|
||||
it.each(rejections)('refuses %s', (_label, override) => {
|
||||
expect(() => assertValidMetricSpec({ ...REVENUE, ...override })).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('declares the five lifecycle statuses BI-P028 names, in order', () => {
|
||||
expect([...METRIC_STATUSES]).toEqual(['DRAFT', 'REVIEW', 'ACTIVE', 'DEPRECATED', 'RETIRED']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P028 DoD — no production metric exists only inside a dashboard tool', () => {
|
||||
const lookup = (id: string) => (id === 'm_revenue' ? GOVERNED : undefined);
|
||||
|
||||
it.each(['inline_expression', 'inline_aggregation', 'inline_sql'])(
|
||||
'refuses a panel that defines a metric via %s',
|
||||
(field) => {
|
||||
expect(() =>
|
||||
assertPanelUsesRegisteredMetric({ panel_id: 'p1', [field]: 'sum(amount)' }, lookup),
|
||||
).toThrowError(SiaxError);
|
||||
},
|
||||
);
|
||||
|
||||
it('refuses a panel that names an unregistered metric', () => {
|
||||
expect(() =>
|
||||
assertPanelUsesRegisteredMetric({ panel_id: 'p1', metric_id: 'm_invented' }, lookup),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a panel with no metric at all', () => {
|
||||
expect(() => assertPanelUsesRegisteredMetric({ panel_id: 'p1' }, lookup)).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a panel pointing at a RETIRED metric', () => {
|
||||
const retired = { ...GOVERNED, spec: { ...REVENUE, status: 'RETIRED' as const } };
|
||||
expect(() =>
|
||||
assertPanelUsesRegisteredMetric({ panel_id: 'p1', metric_id: 'm_revenue' }, () => retired),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('accepts a panel that references a registered, live metric', () => {
|
||||
expect(assertPanelUsesRegisteredMetric({ panel_id: 'p1', metric_id: 'm_revenue' }, lookup).spec.id).toBe(
|
||||
'm_revenue',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P031 DoD — a certified metric cannot be modified in place', () => {
|
||||
/** Every field that changes what the number MEANS. */
|
||||
const semanticEdits: Array<[string, Partial<MetricSpec>]> = [
|
||||
['the measure', { measure: 'amount_eur' }],
|
||||
['the aggregation', { aggregation: 'avg' }],
|
||||
['the type', { type: 'ratio', denominator: 'orders' }],
|
||||
['the dimensions', { dimensions: ['country'] }],
|
||||
['the filters', { filters: [] }],
|
||||
['the time dimension', { timeDimension: 'paid_at' }],
|
||||
['the unit', { unit: 'EUR' }],
|
||||
['the currency', { currency: 'EUR' }],
|
||||
];
|
||||
|
||||
it.each(semanticEdits)('refuses an in-place change to %s', (_label, override) => {
|
||||
const proposed = { ...REVENUE, ...override };
|
||||
let thrown: unknown;
|
||||
try {
|
||||
assertMetricEditAllowed(GOVERNED, proposed);
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect(thrown, "a certified metric's meaning was changed in place").toBeInstanceOf(SiaxError);
|
||||
expect((thrown as SiaxError).code).toBe('CONFLICT');
|
||||
expect((thrown as SiaxError).message).toContain('version 4');
|
||||
});
|
||||
|
||||
/** Editorial fields stay editable — forcing a version bump for a typo is how teams route around governance. */
|
||||
const editorialEdits: Array<[string, Partial<MetricSpec>]> = [
|
||||
['the description', { description: 'Clearer wording.' }],
|
||||
['the owner', { owner: 'controlling@siax.io' }],
|
||||
['the lifecycle status', { status: 'DEPRECATED' }],
|
||||
];
|
||||
|
||||
it.each(editorialEdits)('allows an in-place change to %s', (_label, override) => {
|
||||
expect(() => assertMetricEditAllowed(GOVERNED, { ...REVENUE, ...override })).not.toThrow();
|
||||
});
|
||||
|
||||
it('allows any change to an EXPERIMENTAL metric', () => {
|
||||
const experimental = {
|
||||
...GOVERNED,
|
||||
governance: { ...GOVERNED.governance, certification: 'experimental' as const },
|
||||
};
|
||||
expect(() => assertMetricEditAllowed(experimental, { ...REVENUE, measure: 'anything' })).not.toThrow();
|
||||
});
|
||||
|
||||
it('mints a new version that is DRAFT and EXPERIMENTAL, never inheriting the certification', () => {
|
||||
const next = nextMetricVersion(
|
||||
GOVERNED,
|
||||
{ measure: 'amount_eur', unit: 'EUR', currency: 'EUR' },
|
||||
'switch to EUR',
|
||||
);
|
||||
expect(next.spec.version).toBe(4);
|
||||
expect(next.spec.status).toBe('DRAFT');
|
||||
expect(next.governance.certification).toBe('experimental');
|
||||
expect(next.governance.certified_at).toBeUndefined();
|
||||
expect(next.change_reason).toBe('switch to EUR');
|
||||
});
|
||||
|
||||
it('requires a change reason for a new version', () => {
|
||||
expect(() => nextMetricVersion(GOVERNED, { measure: 'x' }, ' ')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses to change the metric id under the guise of an edit', () => {
|
||||
expect(() => assertMetricEditAllowed(GOVERNED, { ...REVENUE, id: 'm_other' })).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('the meaning hash ignores editorial fields and catches semantic ones', () => {
|
||||
expect(metricMeaningHash({ ...REVENUE, description: 'different', owner: 'x', status: 'DRAFT' })).toBe(
|
||||
metricMeaningHash(REVENUE),
|
||||
);
|
||||
expect(metricMeaningHash({ ...REVENUE, measure: 'other' })).not.toBe(metricMeaningHash(REVENUE));
|
||||
// Filter ORDER is not meaning; filter CONTENT is.
|
||||
expect(
|
||||
metricMeaningHash({
|
||||
...REVENUE,
|
||||
filters: [
|
||||
{ dimension: 'country', operator: 'eq', values: ['SE', 'NO'] },
|
||||
{ dimension: 'channel', operator: 'ne', values: ['internal'] },
|
||||
],
|
||||
}),
|
||||
).not.toBe(metricMeaningHash(REVENUE));
|
||||
});
|
||||
|
||||
it('certification is an act with an actor and a time, and needs both definitions', () => {
|
||||
const draft: GovernedMetric = {
|
||||
spec: { ...REVENUE, status: 'DRAFT' },
|
||||
governance: { ...GOVERNED.governance, certification: 'experimental' },
|
||||
};
|
||||
expect(() => certifyMetric(draft, 'u_1', '2026-09-07T00:00:00Z')).toThrowError(SiaxError);
|
||||
|
||||
const active = { ...draft, spec: { ...draft.spec, status: 'ACTIVE' as const } };
|
||||
const noDefs = { ...active, governance: { ...active.governance, technical_definition: '' } };
|
||||
expect(() => certifyMetric(noDefs, 'u_1', '2026-09-07T00:00:00Z')).toThrowError(SiaxError);
|
||||
|
||||
const certified = certifyMetric(active, 'u_1', '2026-09-07T00:00:00Z');
|
||||
expect(certified.governance.certification).toBe('certified');
|
||||
expect(certified.governance.certified_by).toBe('u_1');
|
||||
});
|
||||
});
|
||||
|
||||
// ── BI-P030 ────────────────────────────────────────────────────────────────
|
||||
|
||||
function model(version = 1): Omit<SemanticModelVersion, 'hash'> {
|
||||
return {
|
||||
model_id: 'sm_sales',
|
||||
version,
|
||||
tenant_id: 't_alpha',
|
||||
datasets: ['ds_sales'],
|
||||
relationships: [],
|
||||
metrics: [REVENUE],
|
||||
dimensions: [
|
||||
{ id: 'd_country', name: 'country', dataset_id: 'ds_sales', kind: 'categorical' },
|
||||
{ id: 'd_channel', name: 'channel', dataset_id: 'ds_sales', kind: 'categorical' },
|
||||
{ id: 'd_invoiced', name: 'invoiced_at', dataset_id: 'ds_sales', kind: 'time' },
|
||||
],
|
||||
valid_from: '2026-09-01T00:00:00Z',
|
||||
status: 'draft',
|
||||
};
|
||||
}
|
||||
|
||||
describe('BI-P030 — the registry is engine-neutral and its versions are immutable', () => {
|
||||
it('refuses a model that names an implementation engine anywhere in it', async () => {
|
||||
for (const smuggled of [
|
||||
{ model_id: 'sm_metricflow_sales' },
|
||||
{ datasets: ['clickhouse_sales'] },
|
||||
{ metrics: [{ ...REVENUE, description: 'computed by MetricFlow' }] },
|
||||
]) {
|
||||
expect(() =>
|
||||
assertEngineNeutral({ ...model(), ...smuggled } as Omit<SemanticModelVersion, 'hash'>),
|
||||
).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses a metric naming a dimension the model does not define', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
await expect(
|
||||
registry.publish({ ...model(), metrics: [{ ...REVENUE, dimensions: ['country', 'segment'] }] }),
|
||||
).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a metric whose time dimension is not declared as a time dimension', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
await expect(
|
||||
registry.publish({ ...model(), metrics: [{ ...REVENUE, timeDimension: 'country' }] }),
|
||||
).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses to republish an existing version — a pinned dashboard must mean the same thing tomorrow', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
await registry.publish(model(1));
|
||||
await expect(registry.publish(model(1))).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('supersedes the previous active version on activation', async () => {
|
||||
const store = new InMemorySemanticModelStore();
|
||||
const registry = new SemanticModelRegistry(store);
|
||||
await registry.publish(model(1));
|
||||
await registry.publish(model(2));
|
||||
await registry.activate('t_alpha', 'sm_sales', 1, '2026-09-01T00:00:00Z');
|
||||
await registry.activate('t_alpha', 'sm_sales', 2, '2026-09-05T00:00:00Z');
|
||||
expect((await store.get('t_alpha', 'sm_sales', 1))?.status).toBe('superseded');
|
||||
expect((await store.active('t_alpha', 'sm_sales'))?.version).toBe(2);
|
||||
});
|
||||
|
||||
it('the hash covers meaning and ignores activation', () => {
|
||||
const a = semanticModelHash(model(1));
|
||||
const b = semanticModelHash({
|
||||
...model(1),
|
||||
valid_from: '2030-01-01T00:00:00Z',
|
||||
status: 'active',
|
||||
} as never);
|
||||
expect(a).toBe(b);
|
||||
const c = semanticModelHash({ ...model(1), metrics: [{ ...REVENUE, version: 4 }] });
|
||||
expect(c).not.toBe(a);
|
||||
});
|
||||
|
||||
it('requires a verified tenant', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
await expect(registry.publish({ ...model(), tenant_id: '' })).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P030 DoD — the semantic engine can be replaced without breaking metric IDs', () => {
|
||||
/**
|
||||
* A SECOND provider with DIFFERENT naming rules, so the test cannot pass
|
||||
* trivially for a registry that only ever had one provider. Cube-shaped:
|
||||
* metric names are `cube.measure`, which is exactly the kind of difference
|
||||
* that would break a consumer if canonical ids were not the contract.
|
||||
*/
|
||||
class CubeShapedProvider implements SiaxSemanticProvider {
|
||||
readonly provider = 'cube-shaped';
|
||||
buildManifest(m: SemanticModelVersion) {
|
||||
return { cubes: m.datasets.map((d) => ({ name: d, measures: m.metrics.map((x) => x.measure) })) };
|
||||
}
|
||||
compile(spec: ReturnType<typeof compileRequestToSemantic>, m: SemanticModelVersion) {
|
||||
const bindings = this.providerBindings(m);
|
||||
return {
|
||||
provider: this.provider,
|
||||
query: { measures: spec.metrics.map((x) => bindings[x.metric_id]) },
|
||||
canonical_metric_ids: spec.metrics.map((x) => x.metric_id).sort(),
|
||||
};
|
||||
}
|
||||
providerBindings(m: SemanticModelVersion): Record<string, string> {
|
||||
return Object.fromEntries(m.metrics.map((x) => [x.id, `ds_sales.${x.measure}`]));
|
||||
}
|
||||
}
|
||||
|
||||
it('both providers preserve the canonical ids while naming them differently', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
const published = await registry.publish(model(1));
|
||||
|
||||
const resolution = queryResolutionFrom({
|
||||
dataset_id: 'ds_sales',
|
||||
metrics: [
|
||||
{
|
||||
name: 'net_revenue',
|
||||
metric_id: 'm_revenue',
|
||||
event_metric_key: 'amount_sek',
|
||||
aggregation: 'sum',
|
||||
allowed_dimensions: ['country', 'channel'],
|
||||
},
|
||||
],
|
||||
dimensions: [{ name: 'country', dimension_id: 'd_country', field_name: 'country_code' }],
|
||||
semantic_model_version: 1,
|
||||
});
|
||||
const spec = compileRequestToSemantic(
|
||||
resolveAnalyticsQuery(
|
||||
parseAnalyticsQueryRequest({
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['net_revenue'],
|
||||
dimensions: ['country'],
|
||||
}),
|
||||
resolution,
|
||||
),
|
||||
);
|
||||
|
||||
const mf = new MetricFlowProvider();
|
||||
const cube = new CubeShapedProvider();
|
||||
|
||||
expect(mf.compile(spec, published).canonical_metric_ids).toEqual(['m_revenue']);
|
||||
expect(cube.compile(spec, published).canonical_metric_ids).toEqual(['m_revenue']);
|
||||
expect(await registry.canonicalMetricIds('t_alpha', 'sm_sales', 1)).toEqual(['m_revenue']);
|
||||
|
||||
// ...and the providers genuinely differ, so the equality above is not
|
||||
// trivially true.
|
||||
expect(mf.providerBindings(published)).not.toEqual(cube.providerBindings(published));
|
||||
expect(cube.providerBindings(published).m_revenue).toBe('ds_sales.amount_sek');
|
||||
});
|
||||
|
||||
it('the MetricFlow manifest is DERIVED, never persisted into the registry', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
const published = await registry.publish(model(1));
|
||||
const manifest = new MetricFlowProvider().buildManifest(published);
|
||||
expect(manifest.metrics[0].name).toBe('m_revenue');
|
||||
expect(manifest._generated_from.hash).toBe(published.hash);
|
||||
|
||||
// Two independent reasons a registry row cannot become a provider manifest.
|
||||
// The vocabulary scan catches the generator stamp...
|
||||
expect(() => assertEngineNeutral({ ...published, ...(manifest as object) } as never)).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
// ...and the structural check catches ANY extra field, which is what holds
|
||||
// for a manifest that avoids the word. The first version of this test
|
||||
// asserted only the vocabulary scan and passed for the wrong reason:
|
||||
// buildManifest did not mention "metricflow" anywhere, so nothing fired.
|
||||
expect(() => assertOnlySemanticModelFields({ ...published, semantic_models: [] })).toThrowError(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
|
||||
it("publish refuses a model carrying any field outside BI-P030's list", async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
await expect(registry.publish({ ...model(1), compiled_sql: 'SELECT 1' } as never)).rejects.toBeInstanceOf(
|
||||
SiaxError,
|
||||
);
|
||||
});
|
||||
|
||||
it('refuses to compile a metric that is not in the model version', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
const published = await registry.publish(model(1));
|
||||
expect(() =>
|
||||
new MetricFlowProvider().compile(
|
||||
{
|
||||
dataset_id: 'ds_sales',
|
||||
metrics: [{ metric_id: 'm_ghost', name: 'ghost' }],
|
||||
groupBy: [],
|
||||
where: [],
|
||||
orderBy: [],
|
||||
limit: 10,
|
||||
format: 'json',
|
||||
},
|
||||
published,
|
||||
),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('puts no SQL predicate text into the compiled provider query', async () => {
|
||||
const registry = new SemanticModelRegistry(new InMemorySemanticModelStore());
|
||||
const published = await registry.publish(model(1));
|
||||
const compiled = new MetricFlowProvider().compile(
|
||||
{
|
||||
dataset_id: 'ds_sales',
|
||||
metrics: [{ metric_id: 'm_revenue', name: 'net_revenue' }],
|
||||
groupBy: [],
|
||||
where: [{ dimension_id: 'd_country', name: 'country', operator: 'eq', values: ["SE' OR '1'='1"] }],
|
||||
orderBy: [],
|
||||
limit: 10,
|
||||
format: 'json',
|
||||
},
|
||||
published,
|
||||
);
|
||||
const serialized = JSON.stringify(compiled.query);
|
||||
expect(serialized).toContain("SE' OR '1'='1"); // survives as DATA
|
||||
expect(serialized).not.toMatch(/\bWHERE\b|\bSELECT\b/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P029 — the provider states what it has NOT proven', () => {
|
||||
it('reports itself unverified, and names the open surfaces', () => {
|
||||
const readiness = new MetricFlowProvider().providerReadiness();
|
||||
expect(readiness.verified).toBe(false);
|
||||
expect(readiness.open.join(' ')).toContain('NOT been executed');
|
||||
expect(readiness.open.join(' ')).toContain('Superset');
|
||||
expect(readiness.open.join(' ')).toContain('AI Analyst');
|
||||
expect(readiness.proven.length).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,377 @@
|
||||
/**
|
||||
* tests/analytics/quality-and-freshness.test.ts
|
||||
* ==============================================
|
||||
* BI-P025 (data quality provider) and BI-P026 (data freshness).
|
||||
*
|
||||
* Both DoDs are about a FALSE GREEN, so both are tested by constructing the
|
||||
* false green and requiring a failure:
|
||||
*
|
||||
* BI-P025 A quality gate that passes when nothing ran. A `not_null` check
|
||||
* over an EMPTY table finds zero violations — the single most
|
||||
* common false green in data quality. Both are asserted to FAIL.
|
||||
*
|
||||
* BI-P026 UNKNOWN age quietly rendering as current, and a result released
|
||||
* with no freshness envelope at all. Both are refused.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
DbtQualityProvider,
|
||||
GreatExpectationsQualityProvider,
|
||||
NativeQualityProvider,
|
||||
QUALITY_RULES,
|
||||
type QualityQueryRunner,
|
||||
type QualityRuleSpec,
|
||||
type QualityVerdict,
|
||||
} from '@/src/analytics/quality/quality-provider';
|
||||
import { InMemoryQuarantineStore, QualityGate } from '@/src/analytics/quality/quarantine';
|
||||
import {
|
||||
assertFreshnessDisclosed,
|
||||
computeFreshness,
|
||||
FRESHNESS_STATES,
|
||||
isPresentableAsCurrent,
|
||||
NON_CURRENT_STATES,
|
||||
} from '@/src/analytics/quality/freshness';
|
||||
|
||||
function runner(
|
||||
violations: number,
|
||||
evaluated: number,
|
||||
): QualityQueryRunner & { lastExpression?: string; lastParams?: Record<string, string> } {
|
||||
const r: QualityQueryRunner & { lastExpression?: string; lastParams?: Record<string, string> } = {
|
||||
engine: 'clickhouse',
|
||||
async count(args) {
|
||||
r.lastExpression = args.violationExpression;
|
||||
r.lastParams = args.params;
|
||||
return { violations, evaluated };
|
||||
},
|
||||
};
|
||||
return r;
|
||||
}
|
||||
|
||||
const RULE: QualityRuleSpec = {
|
||||
rule_id: 'q_not_null_customer',
|
||||
tenant_id: 't_alpha',
|
||||
dataset_id: 'ds_sales',
|
||||
rule: 'not_null',
|
||||
field: 'customer',
|
||||
severity: 'block',
|
||||
params: {},
|
||||
};
|
||||
|
||||
describe('BI-P025 — the native provider EXECUTES, and says so', () => {
|
||||
it('declares every rule BI-P025 names', () => {
|
||||
expect([...QUALITY_RULES]).toEqual([
|
||||
'not_null',
|
||||
'unique',
|
||||
'range',
|
||||
'referential',
|
||||
'freshness',
|
||||
'schema',
|
||||
'distribution',
|
||||
'custom',
|
||||
]);
|
||||
});
|
||||
|
||||
it('passes a clean dataset', async () => {
|
||||
const verdict = await new NativeQualityProvider(runner(0, 1000)).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(true);
|
||||
expect(verdict.provider_kind).toBe('executing');
|
||||
});
|
||||
|
||||
it('FAILS an empty dataset instead of reporting zero violations', async () => {
|
||||
// The false green this whole file exists for: a not-null check over zero
|
||||
// rows finds zero violations and looks healthy while the pipeline is dead.
|
||||
const verdict = await new NativeQualityProvider(runner(0, 0)).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(false);
|
||||
expect(verdict.detail).toContain('EMPTY');
|
||||
});
|
||||
|
||||
it('fails a dataset with violations', async () => {
|
||||
const verdict = await new NativeQualityProvider(runner(7, 1000)).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(false);
|
||||
expect(verdict.violation_count).toBe(7);
|
||||
});
|
||||
|
||||
it('binds rule parameters instead of splicing them into the expression', async () => {
|
||||
const r = runner(0, 10);
|
||||
await new NativeQualityProvider(r).evaluate({
|
||||
...RULE,
|
||||
rule: 'distribution',
|
||||
field: 'channel',
|
||||
params: { accepted_values: ['web', "retail'; DROP TABLE x; --"] },
|
||||
});
|
||||
expect(r.lastExpression).not.toContain('DROP');
|
||||
expect(Object.values(r.lastParams ?? {})).toContain("retail'; DROP TABLE x; --");
|
||||
});
|
||||
|
||||
it('refuses a field name that is not an identifier', async () => {
|
||||
const p = new NativeQualityProvider(runner(0, 10));
|
||||
await expect(p.evaluate({ ...RULE, field: 'customer; DROP TABLE x' })).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses an incomplete rule rather than evaluating a meaningless one', async () => {
|
||||
const p = new NativeQualityProvider(runner(0, 10));
|
||||
await expect(p.evaluate({ ...RULE, rule: 'range', params: {} })).rejects.toBeInstanceOf(SiaxError);
|
||||
await expect(p.evaluate({ ...RULE, rule: 'freshness', params: {} })).rejects.toBeInstanceOf(SiaxError);
|
||||
await expect(p.evaluate({ ...RULE, rule: 'distribution', params: {} })).rejects.toBeInstanceOf(SiaxError);
|
||||
await expect(p.evaluate({ ...RULE, rule: 'custom', params: {} })).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('says CAPABILITY_UNAVAILABLE for rules it cannot evaluate, rather than passing them', async () => {
|
||||
const p = new NativeQualityProvider(runner(0, 10));
|
||||
for (const rule of ['schema', 'referential'] as const) {
|
||||
await expect(p.evaluate({ ...RULE, rule })).rejects.toBeInstanceOf(SiaxError);
|
||||
expect(p.supports(rule)).toBe(false);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P025 — the ingesting providers do not pretend to execute', () => {
|
||||
it('dbt and GE declare themselves as ingesting', async () => {
|
||||
expect(new DbtQualityProvider(new Map()).providerKind).toBe('ingesting');
|
||||
expect(new GreatExpectationsQualityProvider(new Map()).providerKind).toBe('ingesting');
|
||||
});
|
||||
|
||||
it('a MISSING dbt result is a failure, not a pass', async () => {
|
||||
// Treating "no result" as "passed" is how a gate stops gating the moment
|
||||
// the test stops running.
|
||||
const verdict = await new DbtQualityProvider(new Map()).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(false);
|
||||
expect(verdict.detail).toContain('no dbt result');
|
||||
});
|
||||
|
||||
it.each(['error', 'warn', 'skipped'] as const)('dbt status %s is NOT a pass', async (status) => {
|
||||
const results = new Map([[RULE.rule_id, { unique_id: 't1', status, failures: 0 }]]);
|
||||
const verdict = await new DbtQualityProvider(results).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(false);
|
||||
});
|
||||
|
||||
it('dbt pass is a pass', async () => {
|
||||
const results = new Map([[RULE.rule_id, { unique_id: 't1', status: 'pass' as const, failures: 0 }]]);
|
||||
expect((await new DbtQualityProvider(results).evaluate(RULE)).passed).toBe(true);
|
||||
});
|
||||
|
||||
it('a missing GE suite is a failure', async () => {
|
||||
expect((await new GreatExpectationsQualityProvider(new Map()).evaluate(RULE)).passed).toBe(false);
|
||||
});
|
||||
|
||||
it("a GE suite's unexpected counts are carried through", async () => {
|
||||
const suites = new Map([
|
||||
[
|
||||
RULE.rule_id,
|
||||
{
|
||||
expectation_suite_name: 'sales_suite',
|
||||
success: false,
|
||||
results: [
|
||||
{
|
||||
expectation_config: { expectation_type: 'expect_column_values_to_not_be_null' },
|
||||
success: false,
|
||||
result: { unexpected_count: 12, element_count: 1000 },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
]);
|
||||
const verdict = await new GreatExpectationsQualityProvider(suites).evaluate(RULE);
|
||||
expect(verdict.passed).toBe(false);
|
||||
expect(verdict.violation_count).toBe(12);
|
||||
expect(verdict.evaluated_rows).toBe(1000);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P025 DoD — a failed critical gate QUARANTINES the serving projection', () => {
|
||||
function verdict(overrides: Partial<QualityVerdict> = {}): QualityVerdict {
|
||||
return {
|
||||
rule_id: 'q1',
|
||||
dataset_id: 'ds_sales',
|
||||
tenant_id: 't_alpha',
|
||||
rule: 'not_null',
|
||||
severity: 'block',
|
||||
passed: true,
|
||||
violation_count: 0,
|
||||
evaluated_rows: 100,
|
||||
produced_by: 'native:clickhouse',
|
||||
provider_kind: 'executing',
|
||||
evaluated_at: new Date().toISOString(),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
it('a blocking failure quarantines, and the READ is then REFUSED', async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
// Before: readable.
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).resolves.toBeUndefined();
|
||||
|
||||
const outcome = await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: false, severity: 'block' })]);
|
||||
expect(outcome.quarantined).toBe(true);
|
||||
expect(outcome.passed).toBe(false);
|
||||
|
||||
// After: refused. Not annotated — refused.
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('a WARN failure does not quarantine, but is surfaced', async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
const outcome = await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: false, severity: 'warn' })]);
|
||||
expect(outcome.quarantined).toBe(false);
|
||||
expect(outcome.warnings).toHaveLength(1);
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("a gate over ZERO verdicts QUARANTINES — 'no rules ran' is not 'everything passed'", async () => {
|
||||
// The same shape as l0re's silently-skipped tests and api0's
|
||||
// `trivy --exit-code 0`: a check that produced nothing reporting green.
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
const outcome = await gate.apply('t_alpha', 'ds_sales', []);
|
||||
expect(outcome.passed).toBe(false);
|
||||
expect(outcome.quarantined).toBe(true);
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('a later passing run does NOT auto-release a quarantine', async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: false })]);
|
||||
await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: true })]);
|
||||
// A flapping rule would otherwise quarantine and un-quarantine the dataset
|
||||
// between two reads of the same dashboard.
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('release requires a principal and a reason', async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: false })]);
|
||||
await expect(gate.release('t_alpha', 'ds_sales', '', 'x')).rejects.toBeInstanceOf(SiaxError);
|
||||
await expect(gate.release('t_alpha', 'ds_sales', 'u_1', ' ')).rejects.toBeInstanceOf(SiaxError);
|
||||
const released = await gate.release('t_alpha', 'ds_sales', 'u_1', 'upstream backfilled');
|
||||
expect(released.released_by).toBe('u_1');
|
||||
await expect(gate.assertProjectionReadable('t_alpha', 'ds_sales')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("quarantine is tenant-scoped: one tenant's failure does not block another", async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
await gate.apply('t_alpha', 'ds_sales', [verdict({ passed: false })]);
|
||||
await expect(gate.assertProjectionReadable('t_beta', 'ds_sales')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('refuses a verdict belonging to another tenant or dataset', async () => {
|
||||
const gate = new QualityGate(new InMemoryQuarantineStore());
|
||||
await expect(
|
||||
gate.apply('t_alpha', 'ds_sales', [verdict({ tenant_id: 't_beta' })]),
|
||||
).rejects.toBeInstanceOf(SiaxError);
|
||||
await expect(
|
||||
gate.apply('t_alpha', 'ds_sales', [verdict({ dataset_id: 'ds_other' })]),
|
||||
).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P026 — five states, and UNKNOWN is not FRESH', () => {
|
||||
const HOUR = 3_600_000;
|
||||
const NOW = Date.parse('2026-09-07T12:00:00Z');
|
||||
const policy = { expectedIntervalMs: HOUR };
|
||||
|
||||
it('declares the five states BI-P026 names', () => {
|
||||
expect([...FRESHNESS_STATES]).toEqual(['FRESH', 'DELAYED', 'STALE', 'FAILED', 'UNKNOWN']);
|
||||
});
|
||||
|
||||
it('only FRESH may be presented as current', () => {
|
||||
expect(isPresentableAsCurrent('FRESH')).toBe(true);
|
||||
for (const s of NON_CURRENT_STATES) expect(isPresentableAsCurrent(s)).toBe(false);
|
||||
expect(NON_CURRENT_STATES).toContain('UNKNOWN');
|
||||
});
|
||||
|
||||
const cases: Array<[string, Parameters<typeof computeFreshness>[0], string]> = [
|
||||
[
|
||||
'recent load',
|
||||
{ lastSuccessfulLoadAt: '2026-09-07T11:50:00Z', lastRunStatus: 'succeeded', policy, now: NOW },
|
||||
'FRESH',
|
||||
],
|
||||
[
|
||||
'behind schedule',
|
||||
{ lastSuccessfulLoadAt: '2026-09-07T09:50:00Z', lastRunStatus: 'succeeded', policy, now: NOW },
|
||||
'DELAYED',
|
||||
],
|
||||
[
|
||||
'well past the threshold',
|
||||
{ lastSuccessfulLoadAt: '2026-09-06T12:00:00Z', lastRunStatus: 'succeeded', policy, now: NOW },
|
||||
'STALE',
|
||||
],
|
||||
[
|
||||
'the last run FAILED, even though the data looks recent',
|
||||
{ lastSuccessfulLoadAt: '2026-09-07T11:59:00Z', lastRunStatus: 'failed', policy, now: NOW },
|
||||
'FAILED',
|
||||
],
|
||||
['never run', { lastRunStatus: 'never_run', policy, now: NOW }, 'UNKNOWN'],
|
||||
['no load timestamp at all', { policy, now: NOW }, 'UNKNOWN'],
|
||||
['an unparseable timestamp', { lastSuccessfulLoadAt: 'not a date', policy, now: NOW }, 'UNKNOWN'],
|
||||
];
|
||||
|
||||
it.each(cases)('%s -> %s', (_label, input, expected) => {
|
||||
expect(computeFreshness(input).state).toBe(expected);
|
||||
});
|
||||
|
||||
it('FAILED outranks a recent timestamp — a broken pipeline must not look FRESH', () => {
|
||||
const env = computeFreshness({
|
||||
lastSuccessfulLoadAt: '2026-09-07T11:59:59Z',
|
||||
lastRunStatus: 'failed',
|
||||
policy,
|
||||
now: NOW,
|
||||
});
|
||||
expect(env.state).toBe('FAILED');
|
||||
expect(env.disclosure).toContain('FAILED');
|
||||
});
|
||||
|
||||
it('every state carries a disclosure a UI can render verbatim', () => {
|
||||
for (const [, input] of cases) {
|
||||
const env = computeFreshness(input);
|
||||
expect(env.disclosure.length).toBeGreaterThan(10);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P026 DoD — stale data is never SILENTLY presented as current', () => {
|
||||
const env = computeFreshness({
|
||||
lastSuccessfulLoadAt: '2026-09-01T00:00:00Z',
|
||||
lastRunStatus: 'succeeded',
|
||||
policy: { expectedIntervalMs: 3_600_000 },
|
||||
now: Date.parse('2026-09-07T12:00:00Z'),
|
||||
});
|
||||
|
||||
it('refuses to release a result with NO freshness envelope', () => {
|
||||
// Not defaulted to FRESH, not defaulted to UNKNOWN: unreleasable. "We
|
||||
// forgot to attach it" and "the data is current" are indistinguishable to
|
||||
// a reader, so a default would make forgetting the silent path.
|
||||
expect(() => assertFreshnessDisclosed({}, 'dashboard panel p1')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses to release STALE data that the consumer has not acknowledged', () => {
|
||||
expect(env.state).toBe('STALE');
|
||||
let thrown: unknown;
|
||||
try {
|
||||
assertFreshnessDisclosed({ freshness: env }, 'dashboard panel p1');
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect(thrown).toBeInstanceOf(SiaxError);
|
||||
expect((thrown as SiaxError).message).toContain('STALE');
|
||||
});
|
||||
|
||||
it('releases STALE data once the consumer has acknowledged it', () => {
|
||||
expect(assertFreshnessDisclosed({ freshness: env, acknowledged_non_current: true }, 'p1').state).toBe(
|
||||
'STALE',
|
||||
);
|
||||
});
|
||||
|
||||
it.each(NON_CURRENT_STATES)('refuses an unacknowledged %s result', (state) => {
|
||||
expect(() => assertFreshnessDisclosed({ freshness: { ...env, state } }, 'p1')).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('releases FRESH data without ceremony', () => {
|
||||
expect(assertFreshnessDisclosed({ freshness: { ...env, state: 'FRESH' } }, 'p1').state).toBe('FRESH');
|
||||
});
|
||||
|
||||
it('refuses an envelope carrying a state that is not one of the five', () => {
|
||||
expect(() =>
|
||||
assertFreshnessDisclosed({ freshness: { ...env, state: 'PROBABLY_FINE' as never } }, 'p1'),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,291 @@
|
||||
/**
|
||||
* tests/analytics/query-cache.test.ts
|
||||
* ====================================
|
||||
* BI-P020 — QUERY CACHE.
|
||||
*
|
||||
* DoD: "Invalidation tests prove changed dataset/metric does not serve stale
|
||||
* unauthorized result."
|
||||
*
|
||||
* Two words in that sentence carry the weight — STALE and UNAUTHORIZED — and
|
||||
* they are different failures, so they are tested separately:
|
||||
*
|
||||
* STALE a component of the key changed (metric version, semantic
|
||||
* model version, data snapshot) and the cache still answered.
|
||||
* Tested by changing each of the six components ONE AT A TIME
|
||||
* and requiring a miss for every one; a table-driven loop, so
|
||||
* adding a component to the key without adding it to the loop
|
||||
* is caught by the count assertion.
|
||||
*
|
||||
* UNAUTHORIZED another tenant's result came back. Tested three ways: a
|
||||
* different tenant misses; a poisoned entry stored under this
|
||||
* tenant's key but carrying another tenant's id is REFUSED and
|
||||
* evicted rather than returned; and the same components under
|
||||
* two tenants produce different keys.
|
||||
*
|
||||
* The poisoning test is the one that matters. Key namespacing is a naming
|
||||
* convention, and a naming convention is what ST0RE was relying on when it
|
||||
* turned out to have four cross-tenant paths rather than the one reported.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
buildCacheKey,
|
||||
InMemoryResultCache,
|
||||
tenantKeyPrefix,
|
||||
ValkeyResultCache,
|
||||
type CacheKeyComponents,
|
||||
type CachedResult,
|
||||
type ValkeyLikeClient,
|
||||
} from '@/src/analytics/cache/query-cache';
|
||||
|
||||
const BASE: CacheKeyComponents = {
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
dataset_id: 'ds_sales',
|
||||
semantic_model_version: 7,
|
||||
metric_versions: { m_revenue: 3, m_orders: 1 },
|
||||
compiled_query_hash: 'a'.repeat(64),
|
||||
data_snapshot: 'dsv_42',
|
||||
format: 'json',
|
||||
};
|
||||
|
||||
describe('BI-P020 — the key requires all six components', () => {
|
||||
const omissions: Array<[string, Partial<CacheKeyComponents>]> = [
|
||||
['tenant_id', { tenant_id: '' }],
|
||||
['dataset_id', { dataset_id: '' }],
|
||||
['semantic_model_version', { semantic_model_version: undefined as unknown as number }],
|
||||
['metric_versions', { metric_versions: {} }],
|
||||
['compiled_query_hash', { compiled_query_hash: '' }],
|
||||
['data_snapshot', { data_snapshot: '' }],
|
||||
['format', { format: '' }],
|
||||
];
|
||||
|
||||
it.each(omissions)('refuses to build a key without %s', (_name, override) => {
|
||||
expect(() => buildCacheKey({ ...BASE, ...override })).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a metric whose version is missing', () => {
|
||||
expect(() =>
|
||||
buildCacheKey({ ...BASE, metric_versions: { m_revenue: undefined as unknown as number } }),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('is stable under key ordering — the same query does not fragment the cache', () => {
|
||||
const a = buildCacheKey({ ...BASE, metric_versions: { m_orders: 1, m_revenue: 3 } });
|
||||
const b = buildCacheKey({ ...BASE, metric_versions: { m_revenue: 3, m_orders: 1 } });
|
||||
expect(a).toBe(b);
|
||||
});
|
||||
|
||||
it('carries the tenant in plaintext so invalidation is a prefix scan', () => {
|
||||
expect(buildCacheKey(BASE).startsWith(tenantKeyPrefix('t_alpha'))).toBe(true);
|
||||
});
|
||||
|
||||
it('refuses a tenant id that is not key-safe', () => {
|
||||
for (const bad of ['t alpha', 't:alpha', 't*', '../t_beta']) {
|
||||
expect(() => buildCacheKey({ ...BASE, tenant_id: bad })).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P020 — a changed component never serves a STALE result', () => {
|
||||
/**
|
||||
* Each entry changes ONE component. Every one must miss. The count is
|
||||
* asserted so that adding a component to `CacheKeyComponents` without adding
|
||||
* it here is caught rather than silently untested.
|
||||
*/
|
||||
const mutations: Array<[string, Partial<CacheKeyComponents>]> = [
|
||||
['semantic model version bumped', { semantic_model_version: 8 }],
|
||||
['a metric definition versioned', { metric_versions: { m_revenue: 4, m_orders: 1 } }],
|
||||
['a metric removed from the query', { metric_versions: { m_revenue: 3 } }],
|
||||
['the data snapshot advanced', { data_snapshot: 'dsv_43' }],
|
||||
['the compiled query changed (different filters)', { compiled_query_hash: 'b'.repeat(64) }],
|
||||
['a different dataset', { dataset_id: 'ds_other' }],
|
||||
['a different result format', { format: 'arrow_ipc' }],
|
||||
['a different project', { project_id: 'p_other' }],
|
||||
['a different tenant', { tenant_id: 't_beta' }],
|
||||
];
|
||||
|
||||
it('covers every component of the key', () => {
|
||||
const covered = new Set(mutations.flatMap(([, m]) => Object.keys(m)));
|
||||
const componentKeys = Object.keys(BASE);
|
||||
expect([...covered].sort()).toEqual([...componentKeys].sort());
|
||||
});
|
||||
|
||||
it.each(mutations)('misses after %s', async (_label, override) => {
|
||||
const cache = new InMemoryResultCache();
|
||||
await cache.set(BASE, { rows: [{ value: 100 }] }, { ttlSeconds: 300, rowCount: 1 });
|
||||
expect(await cache.get(BASE)).toBeDefined();
|
||||
const changed = { ...BASE, ...override };
|
||||
expect(await cache.get(changed), 'a changed component served the old result').toBeUndefined();
|
||||
});
|
||||
|
||||
it('expires an entry rather than serving it past its TTL', async () => {
|
||||
let clock = 1_000_000;
|
||||
const cache = new InMemoryResultCache(() => clock);
|
||||
await cache.set(BASE, { rows: [] }, { ttlSeconds: 10, rowCount: 0 });
|
||||
expect(await cache.get(BASE)).toBeDefined();
|
||||
clock += 11_000;
|
||||
expect(await cache.get(BASE)).toBeUndefined();
|
||||
});
|
||||
|
||||
it('refuses a non-positive TTL rather than caching forever', async () => {
|
||||
const cache = new InMemoryResultCache();
|
||||
for (const ttl of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
|
||||
await expect(cache.set(BASE, {}, { ttlSeconds: ttl, rowCount: 0 })).rejects.toBeInstanceOf(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P020 — invalidation', () => {
|
||||
async function seed() {
|
||||
const cache = new InMemoryResultCache();
|
||||
await cache.set(BASE, { v: 1 }, { ttlSeconds: 300, rowCount: 1 });
|
||||
await cache.set(
|
||||
{ ...BASE, compiled_query_hash: 'c'.repeat(64) },
|
||||
{ v: 2 },
|
||||
{ ttlSeconds: 300, rowCount: 1 },
|
||||
);
|
||||
await cache.set(
|
||||
{ ...BASE, dataset_id: 'ds_other', metric_versions: { m_other: 1 } },
|
||||
{ v: 3 },
|
||||
{ ttlSeconds: 300, rowCount: 1 },
|
||||
);
|
||||
await cache.set({ ...BASE, tenant_id: 't_beta' }, { v: 4 }, { ttlSeconds: 300, rowCount: 1 });
|
||||
return cache;
|
||||
}
|
||||
|
||||
it("invalidateDataset drops that dataset's entries and nothing else", async () => {
|
||||
const cache = await seed();
|
||||
const dropped = await cache.invalidateDataset('t_alpha', 'ds_sales');
|
||||
expect(dropped).toBe(2);
|
||||
expect(await cache.get(BASE)).toBeUndefined();
|
||||
expect(
|
||||
await cache.get({ ...BASE, dataset_id: 'ds_other', metric_versions: { m_other: 1 } }),
|
||||
).toBeDefined();
|
||||
// The other tenant is untouched — invalidation is tenant-scoped too.
|
||||
expect(await cache.get({ ...BASE, tenant_id: 't_beta' })).toBeDefined();
|
||||
});
|
||||
|
||||
it('invalidateMetric drops every entry that used the metric', async () => {
|
||||
const cache = await seed();
|
||||
const dropped = await cache.invalidateMetric('t_alpha', 'm_revenue');
|
||||
expect(dropped).toBe(2);
|
||||
expect(await cache.get(BASE)).toBeUndefined();
|
||||
expect(
|
||||
await cache.get({ ...BASE, dataset_id: 'ds_other', metric_versions: { m_other: 1 } }),
|
||||
).toBeDefined();
|
||||
});
|
||||
|
||||
it('invalidateTenant drops only that tenant', async () => {
|
||||
const cache = await seed();
|
||||
const dropped = await cache.invalidateTenant('t_alpha');
|
||||
expect(dropped).toBe(3);
|
||||
expect(await cache.get({ ...BASE, tenant_id: 't_beta' })).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P020 — never share a tenant result cache', () => {
|
||||
it('two tenants asking the identical question get different keys', () => {
|
||||
expect(buildCacheKey(BASE)).not.toBe(buildCacheKey({ ...BASE, tenant_id: 't_beta' }));
|
||||
});
|
||||
|
||||
it("REFUSES and evicts an entry whose recorded tenant is not the caller's", async () => {
|
||||
// The scenario key namespacing alone does not cover: a poisoned or
|
||||
// mis-migrated entry sitting under the right key with the wrong owner.
|
||||
// Returning `undefined` here would hide a security event; this refuses.
|
||||
const client = new FakeValkey();
|
||||
const cache = new ValkeyResultCache(client);
|
||||
await cache.set(BASE, { secret: 'alpha data' }, { ttlSeconds: 300, rowCount: 1 });
|
||||
const key = buildCacheKey(BASE);
|
||||
const poisoned = JSON.parse(client.data.get(key) as string) as CachedResult;
|
||||
poisoned.tenant_id = 't_beta';
|
||||
poisoned.value = { secret: 'BETA DATA' };
|
||||
client.data.set(key, JSON.stringify(poisoned));
|
||||
|
||||
await expect(cache.get(BASE)).rejects.toBeInstanceOf(SiaxError);
|
||||
// ...and the poisoned entry is gone, so the next read is a clean miss
|
||||
// rather than a repeated alarm nobody can clear.
|
||||
expect(client.data.has(key)).toBe(false);
|
||||
expect(await cache.get(BASE)).toBeUndefined();
|
||||
});
|
||||
|
||||
it('a tenant-scoped scan confirms ownership against the entry, not the glob', async () => {
|
||||
const client = new FakeValkey();
|
||||
const cache = new ValkeyResultCache(client);
|
||||
await cache.set(BASE, { v: 1 }, { ttlSeconds: 300, rowCount: 1 });
|
||||
// An entry whose KEY matches t_alpha's prefix but whose owner is t_beta.
|
||||
// SCAN MATCH is a glob; the glob would include it, the ownership check
|
||||
// must not.
|
||||
client.data.set(
|
||||
`${tenantKeyPrefix('t_alpha')}forged`,
|
||||
JSON.stringify({ ...JSON.parse(client.data.get(buildCacheKey(BASE)) as string), tenant_id: 't_beta' }),
|
||||
);
|
||||
const dropped = await cache.invalidateTenant('t_alpha');
|
||||
expect(dropped).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('BI-P020 — the Valkey adapter', () => {
|
||||
it('sets a store-side TTL, not only a recorded timestamp', async () => {
|
||||
const client = new FakeValkey();
|
||||
const cache = new ValkeyResultCache(client);
|
||||
await cache.set(BASE, { v: 1 }, { ttlSeconds: 42, rowCount: 1 });
|
||||
expect(client.ttls.get(buildCacheKey(BASE))).toBe(42);
|
||||
});
|
||||
|
||||
it('treats a corrupt entry as a miss AND removes it', async () => {
|
||||
const client = new FakeValkey();
|
||||
const cache = new ValkeyResultCache(client);
|
||||
client.data.set(buildCacheKey(BASE), '{not json');
|
||||
expect(await cache.get(BASE)).toBeUndefined();
|
||||
expect(client.data.has(buildCacheKey(BASE))).toBe(false);
|
||||
});
|
||||
|
||||
it('pages through SCAN rather than blocking on KEYS', async () => {
|
||||
const client = new FakeValkey();
|
||||
const cache = new ValkeyResultCache(client);
|
||||
for (let i = 0; i < 1200; i += 1) {
|
||||
await cache.set(
|
||||
{ ...BASE, compiled_query_hash: String(i).padStart(64, '0') },
|
||||
{ i },
|
||||
{ ttlSeconds: 300, rowCount: 1 },
|
||||
);
|
||||
}
|
||||
expect(await cache.invalidateTenant('t_alpha')).toBe(1200);
|
||||
expect(client.scanCalls).toBeGreaterThan(1);
|
||||
});
|
||||
});
|
||||
|
||||
class FakeValkey implements ValkeyLikeClient {
|
||||
readonly data = new Map<string, string>();
|
||||
readonly ttls = new Map<string, number>();
|
||||
scanCalls = 0;
|
||||
|
||||
async get(key: string): Promise<string | null> {
|
||||
return this.data.get(key) ?? null;
|
||||
}
|
||||
async set(key: string, value: string, opts: { EX: number }): Promise<unknown> {
|
||||
this.data.set(key, value);
|
||||
this.ttls.set(key, opts.EX);
|
||||
return 'OK';
|
||||
}
|
||||
async del(keys: string[]): Promise<unknown> {
|
||||
for (const k of keys) {
|
||||
this.data.delete(k);
|
||||
this.ttls.delete(k);
|
||||
}
|
||||
return keys.length;
|
||||
}
|
||||
async scan(
|
||||
cursor: string,
|
||||
opts: { MATCH: string; COUNT: number },
|
||||
): Promise<{ cursor: string; keys: string[] }> {
|
||||
this.scanCalls += 1;
|
||||
const prefix = opts.MATCH.replace(/\*$/, '');
|
||||
const all = [...this.data.keys()].filter((k) => k.startsWith(prefix));
|
||||
const start = Number(cursor);
|
||||
const page = all.slice(start, start + opts.COUNT);
|
||||
const next = start + opts.COUNT >= all.length ? '0' : String(start + opts.COUNT);
|
||||
return { cursor: next, keys: page };
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,226 @@
|
||||
/**
|
||||
* BI-P011's adversarial list, at the compiler layer:
|
||||
*
|
||||
* tenant A query B dataset · tenant A forged dataset ID · raw SQL attempt
|
||||
* SQL injection · dimension identifier injection · filter injection
|
||||
*
|
||||
* These are the cases that never reach the network. The cases that DO reach a
|
||||
* real server — and the with-fix/without-fix proof BI-P011 actually demands —
|
||||
* are tests/integration/analytics-tenant-isolation.integration.test.ts.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
assertSafeIdentifier,
|
||||
compileMetricQuery,
|
||||
compileProjectionQuery,
|
||||
dimensionCatalogFrom,
|
||||
restrictedTenantUserDdl,
|
||||
} from '@/src/analytics/engine/query-compiler';
|
||||
|
||||
const catalog = dimensionCatalogFrom({ severity: 'severity', make: 'vehicle_make' });
|
||||
|
||||
const HOSTILE = [
|
||||
"x'; DROP TABLE opt_analytics_event; --",
|
||||
'1 OR 1=1',
|
||||
'tenant_id',
|
||||
'*/ OR 1=1 /*',
|
||||
'severity UNION ALL SELECT tenant_id FROM opt_analytics_event',
|
||||
'dim_values[1]',
|
||||
'__proto__',
|
||||
'constructor',
|
||||
'sever ity',
|
||||
'sévérité',
|
||||
'a'.repeat(200),
|
||||
'',
|
||||
];
|
||||
|
||||
describe('BI-P011 injection surfaces at the compiler', () => {
|
||||
it('dimension identifier injection: hostile group_by names are refused, not escaped', () => {
|
||||
for (const bad of HOSTILE) {
|
||||
expect(
|
||||
() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', group_by: [bad] },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
`group_by "${bad}" was not refused`,
|
||||
).toThrowError(/unknown group_by dimension/);
|
||||
}
|
||||
});
|
||||
|
||||
it('filter injection: hostile filter KEYS are refused by catalog resolution', () => {
|
||||
for (const bad of HOSTILE) {
|
||||
expect(
|
||||
() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', filters: { [bad]: 'v' } },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
`filter key "${bad}" was not refused`,
|
||||
).toThrowError(/unknown filter dimension/);
|
||||
}
|
||||
});
|
||||
|
||||
it('prototype-chain keys resolve to undefined rather than to Object.prototype members', () => {
|
||||
// A naive `catalog[name]` lookup would resolve "constructor" to a
|
||||
// function and "toString" to a method; the Map-based catalog must not.
|
||||
for (const key of ['constructor', 'toString', 'hasOwnProperty', '__proto__', 'valueOf']) {
|
||||
expect(catalog.resolve(key)).toBeUndefined();
|
||||
}
|
||||
});
|
||||
|
||||
it('filter VALUES are never spliced, however hostile', () => {
|
||||
const compiled = compileMetricQuery(
|
||||
{
|
||||
tenant_id: 't_alpha',
|
||||
metric: 'm',
|
||||
aggregate: 'sum',
|
||||
filters: { make: "volvo'; DROP TABLE opt_analytics_event; --" },
|
||||
},
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
);
|
||||
expect(compiled.sql).not.toContain('DROP TABLE');
|
||||
expect(compiled.sql).not.toContain('volvo');
|
||||
expect(compiled.params.param_f0v).toBe("volvo'; DROP TABLE opt_analytics_event; --");
|
||||
// The physical column name came from the catalog, not the caller.
|
||||
expect(compiled.params.param_f0n).toBe('vehicle_make');
|
||||
});
|
||||
|
||||
it('metric and dataset VALUES are never spliced either', () => {
|
||||
const compiled = compileMetricQuery(
|
||||
{
|
||||
tenant_id: 't_alpha',
|
||||
metric: "m'; SELECT 1; --",
|
||||
dataset_id: "ds'; SELECT 1; --",
|
||||
aggregate: 'sum',
|
||||
},
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
);
|
||||
expect(compiled.sql).not.toContain('SELECT 1');
|
||||
expect(compiled.sql.match(/SELECT/g)).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('raw SQL attempt: there is no request shape that reaches a second table', () => {
|
||||
const compiled = compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum' },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
);
|
||||
expect(compiled.sql).not.toMatch(/\bUNION\b/i);
|
||||
expect(compiled.sql).not.toMatch(/\bJOIN\b/i);
|
||||
expect((compiled.sql.match(/\bFROM\b/gi) ?? []).length).toBe(1);
|
||||
expect(compiled.table).toBe('opt_analytics_event');
|
||||
});
|
||||
|
||||
it('a forged table name is refused rather than reaching the FROM clause', () => {
|
||||
expect(() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', table: 'system.tables' as never },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
).toThrowError(/invalid table identifier/);
|
||||
});
|
||||
|
||||
it('an unsupported aggregate is refused rather than being interpolated', () => {
|
||||
expect(() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum(1),tenant_id' as never },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
).toThrowError(/unsupported aggregate/);
|
||||
});
|
||||
|
||||
it('group-by cardinality is capped so a caller cannot explode the GROUP BY', () => {
|
||||
const many = Array.from({ length: 9 }, () => 'severity');
|
||||
expect(() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', group_by: many },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
).toThrowError(/at most 8 group-by/);
|
||||
});
|
||||
|
||||
it('LIMIT is clamped to the governance ceiling, and never below 1', () => {
|
||||
const big = compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', limit: 10_000_000 },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
500,
|
||||
);
|
||||
expect(big.sql).toContain('LIMIT 500');
|
||||
const zero = compileMetricQuery(
|
||||
{ tenant_id: 't_alpha', metric: 'm', aggregate: 'sum', limit: 0 },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
500,
|
||||
);
|
||||
expect(zero.sql).toContain('LIMIT 1');
|
||||
});
|
||||
|
||||
it('the projection compiler forces the tenant and parameterizes entity keys', () => {
|
||||
const compiled = compileProjectionQuery(
|
||||
{ tenant_id: 't_alpha', dataset_id: 'ds_x', entity_keys: ["a'; DROP", 'b'] },
|
||||
'opt_analytics',
|
||||
100,
|
||||
);
|
||||
expect(compiled.sql).toMatch(/WHERE tenant_id = \{tenant:String\}/);
|
||||
expect(compiled.sql).not.toContain('DROP');
|
||||
expect(compiled.params.param_entityKeys).toBe(JSON.stringify(["a'; DROP", 'b']));
|
||||
});
|
||||
|
||||
it('assertSafeIdentifier accepts real identifiers and rejects everything else', () => {
|
||||
for (const good of ['severity', 'vehicle_make', '_x', 'a1_b2']) {
|
||||
expect(assertSafeIdentifier(good, 'test')).toBe(good);
|
||||
}
|
||||
for (const bad of ['1abc', 'a-b', 'a b', 'a;b', '', 'a'.repeat(64)]) {
|
||||
expect(() => assertSafeIdentifier(bad, 'test')).toThrowError(/invalid test identifier/);
|
||||
}
|
||||
});
|
||||
|
||||
it('restrictedTenantUserDdl refuses a tenant id or password it cannot safely embed', () => {
|
||||
expect(() =>
|
||||
restrictedTenantUserDdl({
|
||||
db: 'opt_analytics',
|
||||
tenantId: "t_alpha' OR '1'='1",
|
||||
userName: 'opt_t_alpha',
|
||||
password: 'pw',
|
||||
tables: ['opt_analytics_event'],
|
||||
}),
|
||||
).toThrowError(/not policy-safe/);
|
||||
|
||||
expect(() =>
|
||||
restrictedTenantUserDdl({
|
||||
db: 'opt_analytics',
|
||||
tenantId: 't_alpha',
|
||||
userName: 'opt_t_alpha',
|
||||
password: "pw' OR '1'='1",
|
||||
tables: ['opt_analytics_event'],
|
||||
}),
|
||||
).toThrowError(/cannot be embedded/);
|
||||
|
||||
const stmts = restrictedTenantUserDdl({
|
||||
db: 'opt_analytics',
|
||||
tenantId: 't_alpha',
|
||||
userName: 'opt_t_alpha',
|
||||
password: 'safe_pw_123',
|
||||
tables: ['opt_analytics_event'],
|
||||
});
|
||||
expect(stmts.join(' ')).toContain('CREATE ROW POLICY IF NOT EXISTS');
|
||||
expect(stmts.join(' ')).toContain("USING tenant_id = 't_alpha'");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,404 @@
|
||||
/**
|
||||
* tests/analytics/query-execution-model.test.ts
|
||||
* ==============================================
|
||||
* BI-P018 (execution model), BI-P019 (cancellation logic) and BI-P021
|
||||
* (cost/budget) — the parts provable without an engine.
|
||||
*
|
||||
* The engine-dependent claims — "cancellation actually stops a running query",
|
||||
* "the budget actually stops a running query" — are NOT asserted here. They
|
||||
* live in tests/integration/query-cancellation-budget.integration.test.ts
|
||||
* against a live ClickHouse, because a fake process-control that returns
|
||||
* `isRunning: false` on the second call would make this file pass while
|
||||
* proving nothing about the server.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
assertLegalTransition,
|
||||
assertNoRawSql,
|
||||
compiledQueryHash,
|
||||
QueryExecutionRecorder,
|
||||
TERMINAL_STATES,
|
||||
type QueryExecutionRecord,
|
||||
} from '@/src/analytics/execution/query-execution-record';
|
||||
import { cancelAndVerify, type EngineProcessControl } from '@/src/analytics/execution/cancellation';
|
||||
import {
|
||||
costUnits,
|
||||
DEFAULT_QUERY_BUDGET,
|
||||
InMemoryWindowStore,
|
||||
QueryBudgetEnforcer,
|
||||
} from '@/src/analytics/cost/query-budget';
|
||||
|
||||
// ── BI-P018 ────────────────────────────────────────────────────────────────
|
||||
|
||||
function recorder(sink: { write: (r: QueryExecutionRecord) => void }, now = () => 1_000_000) {
|
||||
return new QueryExecutionRecorder(
|
||||
{
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
principal_id: 'u_1',
|
||||
workload: 'dashboard',
|
||||
engine: 'clickhouse',
|
||||
correlation_id: 'c_1',
|
||||
sink,
|
||||
now,
|
||||
},
|
||||
'opt_q1',
|
||||
{
|
||||
hash: compiledQueryHash('SELECT 1', { param_tenant: 't_alpha' }),
|
||||
datasets: ['ds_sales'],
|
||||
metrics: ['revenue'],
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
describe('BI-P018 — every field the prompt names, and none it forbids', () => {
|
||||
it('carries all eighteen required fields once settled', async () => {
|
||||
const written: QueryExecutionRecord[] = [];
|
||||
let clock = 1_000_000;
|
||||
const r = recorder({ write: (x) => void written.push(x) }, () => clock);
|
||||
await r.submitted();
|
||||
clock += 50;
|
||||
await r.started();
|
||||
clock += 700;
|
||||
const final = await r.finish('succeeded', {
|
||||
rows: 12,
|
||||
rows_scanned: 40_960,
|
||||
bytes_scanned: 1_234_567,
|
||||
cost_units: 0.5,
|
||||
});
|
||||
|
||||
for (const field of [
|
||||
'query_id',
|
||||
'tenant_id',
|
||||
'project_id',
|
||||
'principal_id',
|
||||
'workload',
|
||||
'submitted_at',
|
||||
'started_at',
|
||||
'completed_at',
|
||||
'engine',
|
||||
'compiled_query_hash',
|
||||
'datasets',
|
||||
'metrics',
|
||||
'status',
|
||||
'rows',
|
||||
'rows_scanned',
|
||||
'bytes_scanned',
|
||||
'duration_ms',
|
||||
'cache_status',
|
||||
'cost_units',
|
||||
]) {
|
||||
expect(final[field as keyof QueryExecutionRecord], `missing ${field}`).toBeDefined();
|
||||
}
|
||||
expect(final.duration_ms).toBe(700);
|
||||
expect(final.status).toBe('succeeded');
|
||||
});
|
||||
|
||||
it('writes at EVERY transition, so an execution that never finishes is still visible', async () => {
|
||||
const written: QueryExecutionRecord[] = [];
|
||||
const r = recorder({ write: (x) => void written.push(x) });
|
||||
await r.submitted();
|
||||
await r.started();
|
||||
expect(written.map((w) => w.status)).toEqual(['queued', 'running']);
|
||||
// A recorder that only wrote at the end would have zero rows here — and
|
||||
// would lose precisely the executions worth investigating.
|
||||
});
|
||||
|
||||
it('stores a hash, never the statement', async () => {
|
||||
const written: QueryExecutionRecord[] = [];
|
||||
const r = recorder({ write: (x) => void written.push(x) });
|
||||
await r.submitted();
|
||||
await r.started();
|
||||
const final = await r.finish('succeeded', { rows: 1 });
|
||||
const serialized = JSON.stringify(final);
|
||||
expect(serialized).not.toMatch(/SELECT/i);
|
||||
expect(final.compiled_query_hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
});
|
||||
|
||||
it('REFUSES to emit a record whose error field carries statement text', () => {
|
||||
const record: QueryExecutionRecord = {
|
||||
query_id: 'q',
|
||||
execution_id: 'e',
|
||||
tenant_id: 't_alpha',
|
||||
principal_id: 'u',
|
||||
workload: 'api',
|
||||
submitted_at: new Date().toISOString(),
|
||||
engine: 'clickhouse',
|
||||
compiled_query_hash: 'a'.repeat(64),
|
||||
datasets: [],
|
||||
metrics: [],
|
||||
status: 'failed',
|
||||
cache_status: 'miss',
|
||||
// The realistic leak: ClickHouse's error text echoes the query.
|
||||
error: 'Code: 47. Unknown identifier in scope SELECT tenant_id FROM opt_analytics.sales',
|
||||
};
|
||||
expect(() => assertNoRawSql(record)).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('hashes the same statement with different parameters differently', () => {
|
||||
const a = compiledQueryHash('SELECT 1 WHERE t = {t:String}', { param_t: 't_alpha' });
|
||||
const b = compiledQueryHash('SELECT 1 WHERE t = {t:String}', { param_t: 't_beta' });
|
||||
expect(a).not.toBe(b);
|
||||
// ...and identically regardless of key order.
|
||||
expect(compiledQueryHash('q', { b: '2', a: '1' })).toBe(compiledQueryHash('q', { a: '1', b: '2' }));
|
||||
});
|
||||
|
||||
it('refuses an illegal state transition rather than overwriting a terminal row', () => {
|
||||
for (const terminal of TERMINAL_STATES) {
|
||||
expect(() => assertLegalTransition(terminal, 'running')).toThrowError(SiaxError);
|
||||
}
|
||||
expect(() => assertLegalTransition('queued', 'succeeded')).toThrowError(SiaxError);
|
||||
expect(() => assertLegalTransition('running', 'succeeded')).not.toThrow();
|
||||
});
|
||||
|
||||
it('records a cache hit as a cache hit, not as a very fast query', async () => {
|
||||
const written: QueryExecutionRecord[] = [];
|
||||
const r = recorder({ write: (x) => void written.push(x) });
|
||||
await r.submitted();
|
||||
await r.servedFromCache(42);
|
||||
const final = written.at(-1) as QueryExecutionRecord;
|
||||
expect(final.cache_status).toBe('hit');
|
||||
expect(final.rows_scanned).toBe(0);
|
||||
expect(final.bytes_scanned).toBe(0);
|
||||
});
|
||||
|
||||
it('requires a verified tenant and principal', () => {
|
||||
for (const bad of [{ tenant_id: '' }, { principal_id: '' }]) {
|
||||
expect(
|
||||
() =>
|
||||
new QueryExecutionRecorder(
|
||||
{
|
||||
tenant_id: 't_alpha',
|
||||
principal_id: 'u_1',
|
||||
workload: 'api',
|
||||
engine: 'clickhouse',
|
||||
sink: { write: () => undefined },
|
||||
...bad,
|
||||
},
|
||||
'q',
|
||||
{ hash: 'h', datasets: [], metrics: [] },
|
||||
),
|
||||
).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ── BI-P019 (logic only; the engine claim is in the integration suite) ─────
|
||||
|
||||
describe('BI-P019 — cancellation reports what it VERIFIED, not what it requested', () => {
|
||||
function control(script: boolean[]): EngineProcessControl & { kills: number } {
|
||||
let i = 0;
|
||||
return {
|
||||
engine: 'test',
|
||||
kills: 0,
|
||||
async isRunning() {
|
||||
const v = script[Math.min(i, script.length - 1)];
|
||||
i += 1;
|
||||
return v;
|
||||
},
|
||||
async requestKill() {
|
||||
(this as { kills: number }).kills += 1;
|
||||
return true;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
it('reports verified_stopped only after OBSERVING the query gone', async () => {
|
||||
// running, running, running, gone
|
||||
const c = control([true, true, true, false]);
|
||||
const out = await cancelAndVerify(c, 'q1', { timeoutMs: 5_000, pollIntervalMs: 1 });
|
||||
expect(out.verified_stopped).toBe(true);
|
||||
expect(out.kill_accepted).toBe(true);
|
||||
expect(c.kills).toBe(1);
|
||||
});
|
||||
|
||||
it('reports verified_stopped=false when the query outlives the deadline — it does not claim success', async () => {
|
||||
const c = control([true]); // never stops
|
||||
let clock = 0;
|
||||
const out = await cancelAndVerify(c, 'q1', {
|
||||
timeoutMs: 100,
|
||||
pollIntervalMs: 10,
|
||||
now: () => (clock += 30),
|
||||
sleep: async () => undefined,
|
||||
});
|
||||
expect(out.verified_stopped).toBe(false);
|
||||
expect(out.already_finished).toBe(false);
|
||||
});
|
||||
|
||||
it('does not claim to have stopped a query that had already finished', async () => {
|
||||
const c = control([false]);
|
||||
const out = await cancelAndVerify(c, 'q1', { timeoutMs: 100 });
|
||||
expect(out.already_finished).toBe(true);
|
||||
expect(out.verified_stopped).toBe(true);
|
||||
});
|
||||
|
||||
it('keeps polling when the engine is unreachable, then reports unverified', async () => {
|
||||
let clock = 0;
|
||||
const flaky: EngineProcessControl = {
|
||||
engine: 'test',
|
||||
isRunning: async () => {
|
||||
throw new Error('engine unreachable');
|
||||
},
|
||||
requestKill: async () => true,
|
||||
};
|
||||
// isRunning throws on the FIRST call too, which cancelAndVerify treats as
|
||||
// "assume it was running" — the fail-closed reading.
|
||||
const out = await cancelAndVerify(flaky, 'q1', {
|
||||
timeoutMs: 50,
|
||||
pollIntervalMs: 10,
|
||||
now: () => (clock += 20),
|
||||
sleep: async () => undefined,
|
||||
});
|
||||
expect(out.verified_stopped).toBe(false);
|
||||
});
|
||||
|
||||
it('aborts the client side as well as the server side', async () => {
|
||||
let aborted = false;
|
||||
await cancelAndVerify(control([true, false]), 'q1', {
|
||||
timeoutMs: 1_000,
|
||||
pollIntervalMs: 1,
|
||||
abort: () => {
|
||||
aborted = true;
|
||||
},
|
||||
});
|
||||
expect(aborted).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ── BI-P021 ────────────────────────────────────────────────────────────────
|
||||
|
||||
describe('BI-P021 — the budget says plainly what it does and does not bound', () => {
|
||||
const ledger = {
|
||||
entries: [] as unknown[],
|
||||
record(e: unknown) {
|
||||
this.entries.push(e);
|
||||
},
|
||||
};
|
||||
|
||||
it('refuses to be constructed as an in-flight enforcer without a process control', () => {
|
||||
expect(
|
||||
() =>
|
||||
new QueryBudgetEnforcer({
|
||||
budget: DEFAULT_QUERY_BUDGET,
|
||||
store: new InMemoryWindowStore(),
|
||||
ledger,
|
||||
enforceInFlight: true,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('declares admission-only mode as advisory, in words', () => {
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: DEFAULT_QUERY_BUDGET,
|
||||
store: new InMemoryWindowStore(),
|
||||
ledger,
|
||||
enforceInFlight: false,
|
||||
});
|
||||
expect(e.describeEnforcement().binding).toBe(false);
|
||||
expect(e.describeEnforcement().in_flight).toContain('NOT ENFORCED');
|
||||
});
|
||||
|
||||
it('declares the per-process window as non-binding across replicas', () => {
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: DEFAULT_QUERY_BUDGET,
|
||||
store: new InMemoryWindowStore(),
|
||||
ledger,
|
||||
control: {
|
||||
engine: 't',
|
||||
isRunning: async () => false,
|
||||
requestKill: async () => true,
|
||||
progress: async () => undefined,
|
||||
},
|
||||
enforceInFlight: true,
|
||||
storeIsShared: false,
|
||||
});
|
||||
expect(e.describeEnforcement().across_replicas).toContain('N times this budget');
|
||||
expect(e.describeEnforcement().binding).toBe(false);
|
||||
});
|
||||
|
||||
it('rejects an estimate that does not fit the remaining window', async () => {
|
||||
const store = new InMemoryWindowStore();
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: { ...DEFAULT_QUERY_BUDGET, maxRowsScanned: 1_000 },
|
||||
store,
|
||||
ledger,
|
||||
enforceInFlight: false,
|
||||
});
|
||||
expect((await e.admit('t_alpha', { rows_to_read: 100, bytes_to_read: 1 })).admitted).toBe(true);
|
||||
await store.add('t_alpha', { rows: 999, bytes: 0, units: 0, windowMs: DEFAULT_QUERY_BUDGET.windowMs });
|
||||
const decision = await e.admit('t_alpha', { rows_to_read: 100, bytes_to_read: 1 });
|
||||
expect(decision.admitted).toBe(false);
|
||||
expect(decision.reason).toContain('rows');
|
||||
});
|
||||
|
||||
it('throttles instead of rejecting when the budget says so', async () => {
|
||||
const store = new InMemoryWindowStore();
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: { ...DEFAULT_QUERY_BUDGET, maxRowsScanned: 10, onExhausted: 'throttle', throttleDelayMs: 250 },
|
||||
store,
|
||||
ledger,
|
||||
enforceInFlight: false,
|
||||
});
|
||||
await store.add('t_alpha', { rows: 100, bytes: 0, units: 0, windowMs: DEFAULT_QUERY_BUDGET.windowMs });
|
||||
const decision = await e.admit('t_alpha', { rows_to_read: 1, bytes_to_read: 1 });
|
||||
expect(decision.admitted).toBe(true);
|
||||
expect(decision.delay_ms).toBe(250);
|
||||
});
|
||||
|
||||
it('charges for the work a cancelled query already did', async () => {
|
||||
const store = new InMemoryWindowStore();
|
||||
const entries: Array<{ terminated_by_budget: boolean; cost_units: number }> = [];
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: DEFAULT_QUERY_BUDGET,
|
||||
store,
|
||||
ledger: { record: (x) => void entries.push(x as never) },
|
||||
enforceInFlight: false,
|
||||
});
|
||||
const settled = await e.settle({
|
||||
tenant_id: 't_alpha',
|
||||
principal_id: 'u',
|
||||
query_id: 'q',
|
||||
cost: { rows_scanned: 1e9, bytes_scanned: 2 ** 30, execution_ms: 1000, engine: 'clickhouse' },
|
||||
terminated_by_budget: true,
|
||||
});
|
||||
expect(settled.cost_units).toBeGreaterThan(0);
|
||||
expect(entries[0].terminated_by_budget).toBe(true);
|
||||
// Not charging for it is how a tenant learns the cheapest query is one
|
||||
// that gets cancelled.
|
||||
expect(entries[0].cost_units).toBe(settled.cost_units);
|
||||
});
|
||||
|
||||
it('weights bytes above rows, so a wide scan is not billed like a narrow one', () => {
|
||||
const narrow = costUnits({ rows_scanned: 1e9, bytes_scanned: 1e8, execution_ms: 0, engine: 'e' });
|
||||
const wide = costUnits({ rows_scanned: 1e8, bytes_scanned: 1e10, execution_ms: 0, engine: 'e' });
|
||||
expect(wide).toBeGreaterThan(narrow);
|
||||
});
|
||||
|
||||
it('expires spend out of the rolling window', async () => {
|
||||
let clock = 0;
|
||||
const store = new InMemoryWindowStore(() => clock);
|
||||
await store.add('t_alpha', { rows: 100, bytes: 0, units: 1, windowMs: 1000 });
|
||||
expect((await store.get('t_alpha', 1000)).rows_scanned).toBe(100);
|
||||
clock += 1500;
|
||||
expect((await store.get('t_alpha', 1000)).rows_scanned).toBe(0);
|
||||
});
|
||||
|
||||
it('in-flight enforcement returns immediately when the query is already gone', async () => {
|
||||
const e = new QueryBudgetEnforcer({
|
||||
budget: { ...DEFAULT_QUERY_BUDGET, maxRowsScanned: 1 },
|
||||
store: new InMemoryWindowStore(),
|
||||
ledger,
|
||||
control: {
|
||||
engine: 't',
|
||||
isRunning: async () => false,
|
||||
requestKill: async () => true,
|
||||
progress: async () => undefined,
|
||||
},
|
||||
enforceInFlight: true,
|
||||
});
|
||||
const out = await e.enforceInFlight('t_alpha', 'q');
|
||||
expect(out.terminated).toBe(false);
|
||||
expect(out.polls).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,554 @@
|
||||
/**
|
||||
* tests/analytics/query-request-contract.test.ts
|
||||
* ==============================================
|
||||
* BI-P016 — QUERY REQUEST CONTRACT.
|
||||
*
|
||||
* Two claims are under test, and both are stated so they can FAIL:
|
||||
*
|
||||
* 1. "The default product/application API must NOT accept arbitrary SQL."
|
||||
* Tested by feeding the parser every field name a caller would reach for
|
||||
* to smuggle SQL and asserting a rejection — not by asserting the type
|
||||
* lacks the field, which a compiler already guarantees and a JSON body
|
||||
* ignores.
|
||||
*
|
||||
* 2. "Same request can compile to ClickHouse/semantic engine without
|
||||
* consumer rewrite." Tested by projecting BOTH compiled artefacts onto a
|
||||
* comparable shape and demanding equality. The ClickHouse side of that
|
||||
* projection is obtained by PARSING the emitted SQL and its bound
|
||||
* parameters here in the test — not by trusting a field the compiler
|
||||
* helpfully returned. A compiler that silently drops a filter therefore
|
||||
* fails this test instead of passing it.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
ANALYTICS_QUERY_REQUEST_KEYS,
|
||||
FILTER_OPERATORS,
|
||||
parseAnalyticsQueryRequest,
|
||||
queryResolutionFrom,
|
||||
resolveAnalyticsQuery,
|
||||
type AnalyticsQueryRequest,
|
||||
type FilterOperator,
|
||||
type ResolvedDimension,
|
||||
type ResolvedMetric,
|
||||
} from '@/src/analytics/contract/query-request';
|
||||
import {
|
||||
compileRequestToClickHouse,
|
||||
type CompiledAnalyticsQuery,
|
||||
} from '@/src/analytics/contract/compile-clickhouse';
|
||||
import {
|
||||
compileRequestToSemantic,
|
||||
shapeOfSemanticSpec,
|
||||
type QueryShape,
|
||||
} from '@/src/analytics/contract/compile-semantic';
|
||||
import { FORCED_TENANT_PREDICATE } from '@/src/analytics/engine/query-compiler';
|
||||
|
||||
// ── the declared catalog under test ────────────────────────────────────────
|
||||
|
||||
const METRICS: ResolvedMetric[] = [
|
||||
{
|
||||
name: 'orders',
|
||||
metric_id: 'm_orders',
|
||||
event_metric_key: 'order_count',
|
||||
aggregation: 'count',
|
||||
allowed_dimensions: ['country', 'channel', 'segment'],
|
||||
},
|
||||
{
|
||||
name: 'revenue',
|
||||
metric_id: 'm_revenue',
|
||||
event_metric_key: 'revenue_sek',
|
||||
aggregation: 'sum',
|
||||
allowed_dimensions: ['country', 'channel', 'segment'],
|
||||
unit: 'SEK',
|
||||
},
|
||||
{
|
||||
name: 'restricted',
|
||||
metric_id: 'm_restricted',
|
||||
event_metric_key: 'restricted_measure',
|
||||
aggregation: 'sum',
|
||||
// Deliberately NOT sliceable by `segment`.
|
||||
allowed_dimensions: ['country'],
|
||||
},
|
||||
];
|
||||
|
||||
const DIMENSIONS: ResolvedDimension[] = [
|
||||
{ name: 'country', dimension_id: 'd_country', field_name: 'country_code' },
|
||||
{ name: 'channel', dimension_id: 'd_channel', field_name: 'sales_channel' },
|
||||
{ name: 'segment', dimension_id: 'd_segment', field_name: 'customer_segment' },
|
||||
];
|
||||
|
||||
const resolution = queryResolutionFrom({
|
||||
dataset_id: 'ds_sales',
|
||||
metrics: METRICS,
|
||||
dimensions: DIMENSIONS,
|
||||
semantic_model_version: 7,
|
||||
defaultTimeDimension: 'event_time',
|
||||
});
|
||||
|
||||
const FIELD_TO_NAME = new Map(DIMENSIONS.map((d) => [d.field_name, d.name]));
|
||||
const KEY_TO_METRIC = new Map(METRICS.map((m) => [m.event_metric_key, m.name]));
|
||||
|
||||
function compile(req: AnalyticsQueryRequest): CompiledAnalyticsQuery {
|
||||
return compileRequestToClickHouse(resolveAnalyticsQuery(req, resolution), {
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
database: 'opt_analytics',
|
||||
maxResultRows: 10_000,
|
||||
});
|
||||
}
|
||||
|
||||
// ── independent parser: SQL text + bound params -> comparable shape ────────
|
||||
|
||||
/** Split a WHERE clause on top-level " AND " (parenthesised lists survive). */
|
||||
function splitConditions(where: string): string[] {
|
||||
const out: string[] = [];
|
||||
let depth = 0;
|
||||
let current = '';
|
||||
for (let i = 0; i < where.length; i += 1) {
|
||||
const c = where[i];
|
||||
if (c === '(') depth += 1;
|
||||
if (c === ')') depth -= 1;
|
||||
if (depth === 0 && where.startsWith(' AND ', i)) {
|
||||
out.push(current);
|
||||
current = '';
|
||||
i += 4;
|
||||
continue;
|
||||
}
|
||||
current += c;
|
||||
}
|
||||
if (current) out.push(current);
|
||||
return out;
|
||||
}
|
||||
|
||||
const OP_SYMBOL: Record<string, FilterOperator> = {
|
||||
'=': 'eq',
|
||||
'!=': 'ne',
|
||||
'<': 'lt',
|
||||
'<=': 'lte',
|
||||
'>': 'gt',
|
||||
'>=': 'gte',
|
||||
};
|
||||
|
||||
/**
|
||||
* Reconstruct the query's meaning from the artefact the engine would actually
|
||||
* send. Anything the compiler failed to emit is invisible here, which is the
|
||||
* point.
|
||||
*/
|
||||
function shapeOfCompiledSql(c: CompiledAnalyticsQuery): QueryShape {
|
||||
const p = (key: string): string => {
|
||||
const v = c.params[`param_${key}`];
|
||||
if (v === undefined) throw new Error(`compiled SQL references unbound parameter ${key}`);
|
||||
return v;
|
||||
};
|
||||
const whereMatch = /\sWHERE\s(.*?)(?:\sGROUP BY\s|\sORDER BY\s|\sLIMIT\s)/.exec(c.sql);
|
||||
if (!whereMatch) throw new Error('compiled SQL has no WHERE clause');
|
||||
const conditions = splitConditions(whereMatch[1]);
|
||||
|
||||
const filters: QueryShape['filters'] = [];
|
||||
let timeFrom: string | undefined;
|
||||
let timeTo: string | undefined;
|
||||
|
||||
for (const cond of conditions) {
|
||||
if (cond === FORCED_TENANT_PREDICATE) continue;
|
||||
if (/^project_id = \{project:String\}$/.test(cond)) continue;
|
||||
if (/^dataset_id = \{dataset:String\}$/.test(cond)) continue;
|
||||
if (/^metric IN \(/.test(cond)) continue;
|
||||
|
||||
let m = /^\w+ >= parseDateTime64BestEffort\(\{fromTime:String\}\)$/.exec(cond);
|
||||
if (m) {
|
||||
timeFrom = p('fromTime');
|
||||
continue;
|
||||
}
|
||||
m = /^\w+ < parseDateTime64BestEffort\(\{toTime:String\}\)$/.exec(cond);
|
||||
if (m) {
|
||||
timeTo = p('toTime');
|
||||
continue;
|
||||
}
|
||||
m = /^position\(dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\], \{(fv\d+):String\}\) > 0$/.exec(
|
||||
cond,
|
||||
);
|
||||
if (m) {
|
||||
filters.push({ dimension: dimNameFor(p(m[1])), operator: 'contains', values: [p(m[2])] });
|
||||
continue;
|
||||
}
|
||||
m = /^(NOT )?has\(dim_names, \{(fn\d+):String\}\)$/.exec(cond);
|
||||
if (m) {
|
||||
filters.push({
|
||||
dimension: dimNameFor(p(m[2])),
|
||||
operator: m[1] ? 'is_null' : 'is_not_null',
|
||||
values: [],
|
||||
});
|
||||
continue;
|
||||
}
|
||||
m = /^dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\] (NOT IN|IN) \((.+)\)$/.exec(cond);
|
||||
if (m) {
|
||||
const keys = m[3].split(', ').map((t) => /^\{(fv\d+_\d+):String\}$/.exec(t)?.[1]);
|
||||
if (keys.some((k) => !k)) throw new Error(`IN list contains a non-parameter token: ${m[3]}`);
|
||||
filters.push({
|
||||
dimension: dimNameFor(p(m[1])),
|
||||
operator: m[2] === 'NOT IN' ? 'not_in' : 'in',
|
||||
values: keys.map((k) => p(k as string)),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
m = /^dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\] (=|!=|<=|>=|<|>) \{(fv\d+):String\}$/.exec(
|
||||
cond,
|
||||
);
|
||||
if (m) {
|
||||
filters.push({ dimension: dimNameFor(p(m[1])), operator: OP_SYMBOL[m[2]], values: [p(m[3])] });
|
||||
continue;
|
||||
}
|
||||
throw new Error(`unrecognised compiled condition (possible unbound SQL text): ${cond}`);
|
||||
}
|
||||
|
||||
const selectMatch = /^SELECT (.*?) FROM /.exec(c.sql);
|
||||
if (!selectMatch) throw new Error('compiled SQL has no SELECT list');
|
||||
const metricKeys = [...selectMatch[1].matchAll(/\{(m\d+):String\}/g)].map((mm) => p(mm[1]));
|
||||
const dimKeys = [...selectMatch[1].matchAll(/\{(d\d+):String\}/g)].map((mm) => p(mm[1]));
|
||||
const grainMatch = /toStartOf(\w+)\(/.exec(selectMatch[1]);
|
||||
|
||||
const orderMatch = /\sORDER BY\s(.*?)\sLIMIT\s/.exec(c.sql);
|
||||
const order = orderMatch
|
||||
? orderMatch[1].split(', ').map((tok) => {
|
||||
const [alias, dir] = tok.split(' ');
|
||||
const name = c.metricAliases[alias] ?? c.dimensionAliases[alias];
|
||||
if (!name) throw new Error(`ORDER BY references unknown alias ${alias}`);
|
||||
return `${name}:${dir.toLowerCase()}`;
|
||||
})
|
||||
: [];
|
||||
|
||||
const limitMatch = /\sLIMIT (\d+) FORMAT JSON$/.exec(c.sql);
|
||||
if (!limitMatch) throw new Error('compiled SQL has no LIMIT');
|
||||
|
||||
return {
|
||||
dataset_id: p('dataset'),
|
||||
metrics: metricKeys.map((k) => KEY_TO_METRIC.get(k) ?? k).sort(),
|
||||
dimensions: dimKeys.map((k) => FIELD_TO_NAME.get(k) ?? k).sort(),
|
||||
filters: filters.sort((a, b) => (a.dimension + a.operator).localeCompare(b.dimension + b.operator)),
|
||||
order,
|
||||
limit: Number(limitMatch[1]),
|
||||
timeFrom,
|
||||
timeTo,
|
||||
grain: grainMatch ? (grainMatch[1].toLowerCase() as QueryShape['grain']) : undefined,
|
||||
};
|
||||
}
|
||||
|
||||
function dimNameFor(field: string): string {
|
||||
const name = FIELD_TO_NAME.get(field);
|
||||
if (!name) throw new Error(`compiled SQL bound an unknown physical dimension "${field}"`);
|
||||
return name;
|
||||
}
|
||||
|
||||
// ── 1. the API does not accept SQL ─────────────────────────────────────────
|
||||
|
||||
describe('BI-P016 — the product API accepts no SQL', () => {
|
||||
const base = { dataset: 'ds_sales', metrics: ['orders'] };
|
||||
|
||||
const smuggling = [
|
||||
'sql',
|
||||
'query',
|
||||
'rawSql',
|
||||
'raw_sql',
|
||||
'raw',
|
||||
'where',
|
||||
'having',
|
||||
'expression',
|
||||
'expr',
|
||||
'select',
|
||||
'from',
|
||||
'groupBy',
|
||||
'group_by',
|
||||
'unsafe',
|
||||
];
|
||||
|
||||
it.each(smuggling)('rejects a request carrying a %s field', (key) => {
|
||||
expect(() => parseAnalyticsQueryRequest({ ...base, [key]: 'SELECT 1' })).toThrowError(SiaxError);
|
||||
try {
|
||||
parseAnalyticsQueryRequest({ ...base, [key]: 'SELECT 1' });
|
||||
} catch (e) {
|
||||
expect((e as SiaxError).code).toBe('INVALID_REQUEST');
|
||||
}
|
||||
});
|
||||
|
||||
// The INF0 Wave-2 lesson: a tenant read out of a request body. The contract
|
||||
// must not merely IGNORE such a field; ignoring it is what lets a later
|
||||
// refactor start honouring it.
|
||||
it.each(['tenant', 'tenant_id', 'tenantId', 'project_id', 'database', 'catalog', 'table'])(
|
||||
'rejects caller-supplied %s (tenant/catalog selection is never a request field)',
|
||||
(key) => {
|
||||
expect(() => parseAnalyticsQueryRequest({ ...base, [key]: 't_beta' })).toThrowError(SiaxError);
|
||||
},
|
||||
);
|
||||
|
||||
it('rejects ANY unknown key, not just the ones on the smell list', () => {
|
||||
expect(() => parseAnalyticsQueryRequest({ ...base, somethingNewNextQuarter: 1 })).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('accepts exactly the eight BI-P016 fields and no more', () => {
|
||||
expect([...ANALYTICS_QUERY_REQUEST_KEYS]).toEqual([
|
||||
'dataset',
|
||||
'metrics',
|
||||
'dimensions',
|
||||
'filters',
|
||||
'timeRange',
|
||||
'orderBy',
|
||||
'limit',
|
||||
'format',
|
||||
]);
|
||||
});
|
||||
|
||||
it('rejects SQL smuggled into a nested filter object', () => {
|
||||
expect(() =>
|
||||
parseAnalyticsQueryRequest({
|
||||
...base,
|
||||
filters: [{ dimension: 'country', operator: 'eq', values: ['SE'], sql: 'OR 1=1' }],
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('keeps the filter operator set closed', () => {
|
||||
expect([...FILTER_OPERATORS]).toEqual([
|
||||
'eq',
|
||||
'ne',
|
||||
'in',
|
||||
'not_in',
|
||||
'lt',
|
||||
'lte',
|
||||
'gt',
|
||||
'gte',
|
||||
'contains',
|
||||
'is_null',
|
||||
'is_not_null',
|
||||
]);
|
||||
expect(() =>
|
||||
parseAnalyticsQueryRequest({
|
||||
...base,
|
||||
filters: [{ dimension: 'country', operator: 'raw', values: ['x'] }],
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses an orderBy that is not selected (the obvious expression smuggling slot)', () => {
|
||||
expect(() =>
|
||||
parseAnalyticsQueryRequest({ ...base, orderBy: [{ ref: '(SELECT 1)', direction: 'asc' }] }),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a metric the catalog does not declare', () => {
|
||||
const req = parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders OR 1=1'] });
|
||||
expect(() => resolveAnalyticsQuery(req, resolution)).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses slicing a metric by a dimension its definition disallows', () => {
|
||||
const req = parseAnalyticsQueryRequest({
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['restricted'],
|
||||
dimensions: ['segment'],
|
||||
});
|
||||
try {
|
||||
resolveAnalyticsQuery(req, resolution);
|
||||
throw new Error('expected a rejection');
|
||||
} catch (e) {
|
||||
expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses a dataset that is not the authorised one', () => {
|
||||
const req = parseAnalyticsQueryRequest({ dataset: 'ds_other', metrics: ['orders'] });
|
||||
try {
|
||||
resolveAnalyticsQuery(req, resolution);
|
||||
throw new Error('expected a rejection');
|
||||
} catch (e) {
|
||||
expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
}
|
||||
});
|
||||
|
||||
it('rejects a reversed time range instead of silently returning zero rows', () => {
|
||||
expect(() =>
|
||||
parseAnalyticsQueryRequest({ ...base, timeRange: { from: '2026-02-01', to: '2026-01-01' } }),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
// ── 2. one request, two targets, same meaning ──────────────────────────────
|
||||
|
||||
describe('BI-P016 DoD — one request compiles to ClickHouse and to the semantic engine', () => {
|
||||
const requests: Array<[string, unknown]> = [
|
||||
['metric only', { dataset: 'ds_sales', metrics: ['orders'] }],
|
||||
[
|
||||
'two metrics, two dimensions',
|
||||
{ dataset: 'ds_sales', metrics: ['orders', 'revenue'], dimensions: ['country', 'channel'] },
|
||||
],
|
||||
[
|
||||
'filters of every value operator',
|
||||
{
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['revenue'],
|
||||
dimensions: ['country'],
|
||||
filters: [
|
||||
{ dimension: 'country', operator: 'eq', values: ['SE'] },
|
||||
{ dimension: 'channel', operator: 'in', values: ['web', 'retail'] },
|
||||
{ dimension: 'segment', operator: 'not_in', values: ['test'] },
|
||||
{ dimension: 'channel', operator: 'contains', values: ['we'] },
|
||||
],
|
||||
},
|
||||
],
|
||||
[
|
||||
'time range with grain and ordering',
|
||||
{
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['revenue'],
|
||||
dimensions: ['country'],
|
||||
timeRange: { from: '2026-01-01T00:00:00Z', to: '2026-02-01T00:00:00Z', grain: 'day' },
|
||||
orderBy: [{ ref: 'revenue', direction: 'desc' }],
|
||||
limit: 50,
|
||||
},
|
||||
],
|
||||
[
|
||||
'presence filters',
|
||||
{
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['orders'],
|
||||
filters: [
|
||||
{ dimension: 'segment', operator: 'is_null' },
|
||||
{ dimension: 'channel', operator: 'is_not_null' },
|
||||
],
|
||||
},
|
||||
],
|
||||
];
|
||||
|
||||
it.each(requests)('%s — both targets agree', (_label, raw) => {
|
||||
const req = parseAnalyticsQueryRequest(raw);
|
||||
const resolved = resolveAnalyticsQuery(req, resolution);
|
||||
const ch = compileRequestToClickHouse(resolved, {
|
||||
tenant_id: 't_alpha',
|
||||
project_id: 'p_main',
|
||||
database: 'opt_analytics',
|
||||
maxResultRows: 10_000,
|
||||
});
|
||||
const sem = compileRequestToSemantic(resolved);
|
||||
|
||||
const fromSql = shapeOfCompiledSql(ch);
|
||||
const fromSemantic = shapeOfSemanticSpec(sem);
|
||||
|
||||
expect(fromSql.dataset_id).toBe(fromSemantic.dataset_id);
|
||||
expect(fromSql.metrics).toEqual(fromSemantic.metrics);
|
||||
expect(fromSql.dimensions).toEqual(fromSemantic.dimensions);
|
||||
expect(fromSql.filters).toEqual(fromSemantic.filters);
|
||||
expect(fromSql.order).toEqual(fromSemantic.order);
|
||||
expect(fromSql.limit).toBe(fromSemantic.limit);
|
||||
expect(fromSql.timeFrom).toBe(fromSemantic.timeFrom);
|
||||
expect(fromSql.timeTo).toBe(fromSemantic.timeTo);
|
||||
expect(fromSql.grain).toBe(fromSemantic.grain);
|
||||
});
|
||||
|
||||
it('carries the canonical metric_id into the semantic spec so the engine is replaceable', () => {
|
||||
const req = parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['revenue'] });
|
||||
const spec = compileRequestToSemantic(resolveAnalyticsQuery(req, resolution));
|
||||
expect(spec.metrics[0].metric_id).toBe('m_revenue');
|
||||
expect(spec.semantic_model_version).toBe(7);
|
||||
});
|
||||
|
||||
it('never puts a SQL predicate string in the semantic spec', () => {
|
||||
const req = parseAnalyticsQueryRequest({
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['orders'],
|
||||
filters: [{ dimension: 'country', operator: 'eq', values: ["SE' OR '1'='1"] }],
|
||||
});
|
||||
const spec = compileRequestToSemantic(resolveAnalyticsQuery(req, resolution));
|
||||
// The hostile value survives as DATA — structured, not concatenated.
|
||||
expect(spec.where[0].values).toEqual(["SE' OR '1'='1"]);
|
||||
expect(JSON.stringify(spec)).not.toMatch(/SELECT|WHERE\s/i);
|
||||
});
|
||||
});
|
||||
|
||||
// ── 3. tenant forcing survives every request shape ─────────────────────────
|
||||
|
||||
describe('BI-P011 forced tenant predicate survives the BI-P016 contract', () => {
|
||||
it.each(requests())('compiled SQL forces the tenant predicate first: %s', (_label, raw) => {
|
||||
const c = compile(parseAnalyticsQueryRequest(raw));
|
||||
const where = /\sWHERE\s(.*?)(?:\sGROUP BY\s|\sORDER BY\s|\sLIMIT\s)/.exec(c.sql);
|
||||
expect(where).not.toBeNull();
|
||||
expect(splitConditions((where as RegExpExecArray)[1])[0]).toBe(FORCED_TENANT_PREDICATE);
|
||||
expect(c.params.param_tenant).toBe('t_alpha');
|
||||
});
|
||||
|
||||
it('refuses to compile with a blank tenant rather than emitting no predicate', () => {
|
||||
const resolved = resolveAnalyticsQuery(
|
||||
parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders'] }),
|
||||
resolution,
|
||||
);
|
||||
for (const blank of ['', ' ']) {
|
||||
expect(() =>
|
||||
compileRequestToClickHouse(resolved, {
|
||||
tenant_id: blank,
|
||||
database: 'opt_analytics',
|
||||
maxResultRows: 100,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
}
|
||||
});
|
||||
|
||||
it('puts no caller-supplied value anywhere in the SQL text', () => {
|
||||
const hostile = "'; DROP TABLE opt_analytics_event; --";
|
||||
const c = compile(
|
||||
parseAnalyticsQueryRequest({
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['orders'],
|
||||
filters: [{ dimension: 'country', operator: 'eq', values: [hostile] }],
|
||||
}),
|
||||
);
|
||||
expect(c.sql).not.toContain(hostile);
|
||||
expect(c.sql).not.toContain('DROP');
|
||||
expect(Object.values(c.params)).toContain(hostile);
|
||||
});
|
||||
|
||||
it('clamps the limit down to the governance ceiling and never up', () => {
|
||||
const resolved = resolveAnalyticsQuery(
|
||||
parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders'], limit: 1_000_000 }),
|
||||
resolution,
|
||||
);
|
||||
const c = compileRequestToClickHouse(resolved, {
|
||||
tenant_id: 't_alpha',
|
||||
database: 'opt_analytics',
|
||||
maxResultRows: 500,
|
||||
});
|
||||
expect(c.effectiveLimit).toBe(500);
|
||||
expect(c.sql).toContain('LIMIT 500');
|
||||
});
|
||||
});
|
||||
|
||||
function requests(): Array<[string, unknown]> {
|
||||
return [
|
||||
['bare', { dataset: 'ds_sales', metrics: ['orders'] }],
|
||||
['grouped', { dataset: 'ds_sales', metrics: ['orders'], dimensions: ['country'] }],
|
||||
[
|
||||
'filtered',
|
||||
{
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['orders'],
|
||||
filters: [{ dimension: 'country', operator: 'in', values: ['SE', 'NO'] }],
|
||||
},
|
||||
],
|
||||
[
|
||||
'time-bucketed',
|
||||
{ dataset: 'ds_sales', metrics: ['revenue'], timeRange: { from: '2026-01-01', grain: 'month' } },
|
||||
],
|
||||
[
|
||||
'everything at once',
|
||||
{
|
||||
dataset: 'ds_sales',
|
||||
metrics: ['orders', 'revenue'],
|
||||
dimensions: ['country', 'channel'],
|
||||
filters: [
|
||||
{ dimension: 'segment', operator: 'ne', values: ['internal'] },
|
||||
{ dimension: 'channel', operator: 'is_not_null' },
|
||||
],
|
||||
timeRange: { from: '2026-01-01', to: '2026-03-01', grain: 'week' },
|
||||
orderBy: [{ ref: 'revenue', direction: 'desc' }],
|
||||
limit: 25,
|
||||
format: 'arrow_ipc',
|
||||
},
|
||||
],
|
||||
];
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
/**
|
||||
* BI-P012 — CLICKHOUSE RESOURCE GOVERNANCE, the part provable without an
|
||||
* engine. The "intentional query bomb is terminated" half of the DoD needs a
|
||||
* real server and lives in
|
||||
* tests/integration/analytics-resource-governance.integration.test.ts.
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
applyQuota,
|
||||
BUDGET_TIERS,
|
||||
clickhouseSettings,
|
||||
ConcurrencyGate,
|
||||
concurrencyProfileSql,
|
||||
DEFAULT_BUDGETS,
|
||||
REQUIRED_GOVERNANCE_SETTINGS,
|
||||
} from '@/src/analytics/engine/resource-governance';
|
||||
|
||||
describe('BI-P012 resource governance', () => {
|
||||
it('every setting the program names has a value somewhere in the enforcement path', () => {
|
||||
const settings = clickhouseSettings(DEFAULT_BUDGETS.INTERACTIVE);
|
||||
const profile = concurrencyProfileSql('opt_t_alpha', DEFAULT_BUDGETS.INTERACTIVE).join(' ');
|
||||
for (const name of REQUIRED_GOVERNANCE_SETTINGS) {
|
||||
const present = name in settings || profile.includes(name) || name === 'max_concurrent_queries';
|
||||
expect(present, `${name} is not enforced anywhere`).toBe(true);
|
||||
}
|
||||
// The five per-statement ones must be on the STATEMENT, not only in a
|
||||
// profile a future operator might forget to attach.
|
||||
for (const name of [
|
||||
'max_execution_time',
|
||||
'max_result_rows',
|
||||
'max_rows_to_read',
|
||||
'max_bytes_to_read',
|
||||
'max_memory_usage',
|
||||
]) {
|
||||
expect(settings[name], `${name} missing from per-statement settings`).toBeDefined();
|
||||
}
|
||||
});
|
||||
|
||||
it('readonly=1 rides on every SELECT so the query text cannot re-set the limits', () => {
|
||||
for (const tier of BUDGET_TIERS) {
|
||||
expect(clickhouseSettings(DEFAULT_BUDGETS[tier]).readonly).toBe('1');
|
||||
}
|
||||
});
|
||||
|
||||
it('overflow modes are THROW, not BREAK — a partial result must never look complete', () => {
|
||||
const s = clickhouseSettings(DEFAULT_BUDGETS.INTERACTIVE);
|
||||
expect(s.result_overflow_mode).toBe('throw');
|
||||
expect(s.read_overflow_mode).toBe('throw');
|
||||
expect(s.timeout_overflow_mode).toBe('throw');
|
||||
});
|
||||
|
||||
it('a CL0UD quota can only TIGHTEN a tier, never loosen it', () => {
|
||||
const base = DEFAULT_BUDGETS.INTERACTIVE;
|
||||
const loosened = applyQuota(base, {
|
||||
maxExecutionTimeSec: 100000,
|
||||
maxResultRows: 10_000_000,
|
||||
maxRowsToRead: Number.MAX_SAFE_INTEGER,
|
||||
maxBytesToRead: Number.MAX_SAFE_INTEGER,
|
||||
maxMemoryUsageBytes: Number.MAX_SAFE_INTEGER,
|
||||
maxConcurrentQueries: 1000,
|
||||
});
|
||||
expect(loosened).toEqual(base);
|
||||
|
||||
const tightened = applyQuota(base, { maxResultRows: 100, maxConcurrentQueries: 1 });
|
||||
expect(tightened.maxResultRows).toBe(100);
|
||||
expect(tightened.maxConcurrentQueries).toBe(1);
|
||||
expect(tightened.maxExecutionTimeSec).toBe(base.maxExecutionTimeSec);
|
||||
});
|
||||
|
||||
it('a nonsense quota (zero, negative, NaN) falls back to the tier rather than to no limit', () => {
|
||||
const base = DEFAULT_BUDGETS.INTERACTIVE;
|
||||
expect(applyQuota(base, { maxResultRows: 0 }).maxResultRows).toBe(base.maxResultRows);
|
||||
expect(applyQuota(base, { maxResultRows: -5 }).maxResultRows).toBe(base.maxResultRows);
|
||||
expect(applyQuota(base, { maxResultRows: Number.NaN }).maxResultRows).toBe(base.maxResultRows);
|
||||
expect(applyQuota(base, undefined)).toEqual(base);
|
||||
});
|
||||
|
||||
it('tiers get progressively more generous, and INTERACTIVE is the mean default', () => {
|
||||
expect(DEFAULT_BUDGETS.INTERACTIVE.maxExecutionTimeSec).toBeLessThan(
|
||||
DEFAULT_BUDGETS.ANALYTICAL.maxExecutionTimeSec,
|
||||
);
|
||||
expect(DEFAULT_BUDGETS.ANALYTICAL.maxExecutionTimeSec).toBeLessThan(
|
||||
DEFAULT_BUDGETS.BATCH.maxExecutionTimeSec,
|
||||
);
|
||||
expect(DEFAULT_BUDGETS.INTERACTIVE.maxRowsToRead).toBeLessThan(DEFAULT_BUDGETS.ANALYTICAL.maxRowsToRead);
|
||||
});
|
||||
|
||||
it('the concurrency gate throttles ONE tenant without touching another', () => {
|
||||
const gate = new ConcurrencyGate((t) => (t === 't_noisy' ? 2 : 5));
|
||||
const a = gate.acquire('t_noisy');
|
||||
const b = gate.acquire('t_noisy');
|
||||
expect(gate.inFlightFor('t_noisy')).toBe(2);
|
||||
expect(() => gate.acquire('t_noisy')).toThrowError(/queries in flight/);
|
||||
|
||||
// The quiet tenant is unaffected — BI-P012's "without degrading unrelated
|
||||
// tenant" in the smallest testable form.
|
||||
const quiet = gate.acquire('t_quiet');
|
||||
expect(gate.inFlightFor('t_quiet')).toBe(1);
|
||||
|
||||
a();
|
||||
expect(gate.inFlightFor('t_noisy')).toBe(1);
|
||||
expect(() => gate.acquire('t_noisy')).not.toThrow();
|
||||
b();
|
||||
quiet();
|
||||
});
|
||||
|
||||
it('releasing twice does not free a slot that was never taken', () => {
|
||||
const gate = new ConcurrencyGate(() => 1);
|
||||
const release = gate.acquire('t_x');
|
||||
release();
|
||||
release();
|
||||
expect(gate.inFlightFor('t_x')).toBe(0);
|
||||
expect(gate.totalInFlight()).toBe(0);
|
||||
});
|
||||
|
||||
it("the settings profile SQL carries max_concurrent_queries' server-side half", () => {
|
||||
const stmts = concurrencyProfileSql('opt_t_alpha', DEFAULT_BUDGETS.INTERACTIVE);
|
||||
expect(stmts.join(' ')).toContain('CREATE SETTINGS PROFILE IF NOT EXISTS opt_t_alpha');
|
||||
expect(stmts.join(' ')).toContain('readonly = 1');
|
||||
expect(stmts.join(' ')).toContain('CREATE QUOTA IF NOT EXISTS opt_t_alpha_quota');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
/**
|
||||
* BI-P009's non-negotiable line: "Do not regress the existing forced tenant
|
||||
* predicate."
|
||||
*
|
||||
* This suite is written to FAIL IF THE FORCING IS REMOVED, which is a
|
||||
* different thing from testing that it currently works. Concretely, each test
|
||||
* below would go red under a specific, plausible regression:
|
||||
*
|
||||
* * someone makes `tenant_id` optional in the metric DSL -> "refuses a
|
||||
* blank tenant" fails;
|
||||
* * someone "simplifies" the WHERE builder and drops the tenant condition
|
||||
* -> "every compiled statement contains the predicate" fails on a missing
|
||||
* substring;
|
||||
* * someone starts splicing the tenant value into SQL text instead of
|
||||
* binding it -> "the tenant VALUE never appears in the SQL text" fails;
|
||||
* * someone lets a caller pass a tenant through the request body rather
|
||||
* than the verified identity -> "identity wins over any request field"
|
||||
* fails.
|
||||
*
|
||||
* It covers BOTH compilers: the PRESERVED `ClickHouseAnalytics.queryMetric`
|
||||
* (src/analytics/clickhouse-analytics.ts, untouched by BI-P009) and the new
|
||||
* `compileMetricQuery` — because "preserved" means the old guarantee has to
|
||||
* keep holding, not merely that the file still exists.
|
||||
*
|
||||
* The ClickHouseAnalytics half asserts against the URL the adapter actually
|
||||
* builds, captured with a stub `fetch`. That is deliberate: a mock ENGINE
|
||||
* could be made to return anything, but the SQL text on the wire is the thing
|
||||
* the real server would receive, so asserting on it cannot be faked by the
|
||||
* test double.
|
||||
*/
|
||||
import { describe, it, expect, afterEach, vi } from 'vitest';
|
||||
import { ClickHouseAnalytics } from '@/src/analytics/clickhouse-analytics';
|
||||
import {
|
||||
compileMetricQuery,
|
||||
compileProjectionQuery,
|
||||
dimensionCatalogFrom,
|
||||
FORCED_TENANT_PREDICATE,
|
||||
} from '@/src/analytics/engine/query-compiler';
|
||||
|
||||
const catalog = dimensionCatalogFrom({ severity: 'severity', make: 'vehicle_make' });
|
||||
|
||||
/** Captures every URL the adapter fetches, returning an empty JSON result. */
|
||||
function captureFetch(): { urls: string[]; restore: () => void } {
|
||||
const urls: string[] = [];
|
||||
const original = globalThis.fetch;
|
||||
globalThis.fetch = (async (input: RequestInfo | URL) => {
|
||||
urls.push(String(input));
|
||||
return new Response(JSON.stringify({ data: [] }), { status: 200 });
|
||||
}) as typeof fetch;
|
||||
return { urls, restore: () => (globalThis.fetch = original) };
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('BI-P009 regression guard: the forced tenant predicate', () => {
|
||||
it('PRESERVED ClickHouseAnalytics still emits tenant_id = {tenant:String} on the wire', async () => {
|
||||
const cap = captureFetch();
|
||||
try {
|
||||
const analytics = new ClickHouseAnalytics({ baseUrl: 'http://ch.invalid:8123', database: 'opt_test' });
|
||||
await analytics.queryMetric({ tenant_id: 't_alpha', metric: 'rows', aggregate: 'sum' });
|
||||
expect(cap.urls).toHaveLength(1);
|
||||
// URLSearchParams decodes `+` as a space, which raw decodeURIComponent
|
||||
// does not — read the statement the way the server will.
|
||||
const query = new URL(cap.urls[0]).searchParams.get('query') ?? '';
|
||||
expect(query).toContain('tenant_id = {tenant:String}');
|
||||
expect(query).toMatch(/WHERE tenant_id = \{tenant:String\}/);
|
||||
// The VALUE travels as a bound parameter, never inside the statement.
|
||||
expect(query).not.toContain('t_alpha');
|
||||
expect(new URL(cap.urls[0]).searchParams.get('param_tenant')).toBe('t_alpha');
|
||||
} finally {
|
||||
cap.restore();
|
||||
}
|
||||
});
|
||||
|
||||
it('PRESERVED ClickHouseAnalytics still refuses a blank tenant_id', async () => {
|
||||
const analytics = new ClickHouseAnalytics({ baseUrl: 'http://ch.invalid:8123' });
|
||||
await expect(
|
||||
analytics.queryMetric({ tenant_id: ' ', metric: 'x', aggregate: 'sum' }),
|
||||
).rejects.toMatchObject({
|
||||
code: 'INVALID_REQUEST',
|
||||
});
|
||||
});
|
||||
|
||||
it('PRESERVED ClickHouseAnalytics still refuses a hostile group_by identifier', async () => {
|
||||
const analytics = new ClickHouseAnalytics({ baseUrl: 'http://ch.invalid:8123' });
|
||||
await expect(
|
||||
analytics.queryMetric({
|
||||
tenant_id: 't_alpha',
|
||||
metric: 'x',
|
||||
aggregate: 'sum',
|
||||
group_by: "sev'; DROP TABLE opt_metric_events; --",
|
||||
}),
|
||||
).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
|
||||
});
|
||||
|
||||
it('every statement the NEW compiler produces contains the forced predicate', () => {
|
||||
const shapes = [
|
||||
{ metric: 'm', aggregate: 'sum' as const },
|
||||
{ metric: 'm', aggregate: 'count' as const, group_by: ['severity'] },
|
||||
{ metric: 'm', aggregate: 'avg' as const, filters: { make: 'volvo' }, dataset_id: 'ds_1' },
|
||||
{ metric: 'm', aggregate: 'max' as const, from_time: '2026-01-01', to_time: '2026-02-01' },
|
||||
{ metric: 'm', aggregate: 'count_distinct' as const, group_by: ['severity', 'make'], limit: 5 },
|
||||
];
|
||||
for (const shape of shapes) {
|
||||
const compiled = compileMetricQuery({ tenant_id: 't_alpha', ...shape }, 'opt_analytics', catalog, 1000);
|
||||
expect(compiled.sql).toContain(FORCED_TENANT_PREDICATE);
|
||||
// The predicate must be in the WHERE, not in a comment or an alias.
|
||||
expect(compiled.sql).toMatch(/WHERE tenant_id = \{tenant:String\}/);
|
||||
expect(compiled.params.param_tenant).toBe('t_alpha');
|
||||
expect(compiled.sql).not.toContain('t_alpha');
|
||||
}
|
||||
const projection = compileProjectionQuery(
|
||||
{ tenant_id: 't_alpha', dataset_id: 'ds_1', entity_keys: ['a', 'b'] },
|
||||
'opt_analytics',
|
||||
1000,
|
||||
);
|
||||
expect(projection.sql).toMatch(/WHERE tenant_id = \{tenant:String\}/);
|
||||
expect(projection.sql).not.toContain('t_alpha');
|
||||
});
|
||||
|
||||
it('the NEW compiler fails closed on a blank/absent tenant instead of emitting an unfiltered query', () => {
|
||||
for (const tenant of ['', ' ']) {
|
||||
expect(() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: tenant, metric: 'm', aggregate: 'sum' },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
).toThrowError(/tenant_id is required/);
|
||||
}
|
||||
// The undefined case, which TypeScript would normally forbid, is what a
|
||||
// JS caller or a loosely-typed HTTP boundary can actually produce.
|
||||
expect(() =>
|
||||
compileMetricQuery(
|
||||
{ tenant_id: undefined as unknown as string, metric: 'm', aggregate: 'sum' },
|
||||
'opt_analytics',
|
||||
catalog,
|
||||
1000,
|
||||
),
|
||||
).toThrowError(/tenant_id is required/);
|
||||
});
|
||||
|
||||
it('the constant itself is the predicate, so deleting the forcing cannot pass silently', () => {
|
||||
// If someone redefines FORCED_TENANT_PREDICATE to something harmless
|
||||
// (e.g. "1 = 1") to make the substring assertions above pass, this fails.
|
||||
expect(FORCED_TENANT_PREDICATE).toBe('tenant_id = {tenant:String}');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,192 @@
|
||||
/**
|
||||
* P014 regression: HTTP-level proof that every app/api/0pt/** route which
|
||||
* takes tenant_id from client-controlled input (query string or JSON body)
|
||||
* now rejects a request whose tenant_id disagrees with the tenant
|
||||
* middleware.ts already verified for the caller (forwarded as
|
||||
* `x-0pt-verified-tenant`). Before this pass, NONE of these routes checked
|
||||
* that header at all -- a valid token for tenant A could read or write
|
||||
* tenant B's sources, rate policies, quality rules, documents, or lakehouse
|
||||
* mappings simply by naming tenant_id=B in the request.
|
||||
*
|
||||
* These call the route handlers directly with a hand-built NextRequest that
|
||||
* carries `x-0pt-verified-tenant` -- exactly the shape middleware.ts hands
|
||||
* the route once a real Bearer token has been verified (see
|
||||
* tests/api/anonymous-routes-auth.test.ts for the same "call the handler
|
||||
* directly, simulate what upstream already established" pattern used for
|
||||
* the /api/orders and /api/admin/metrics fail-closed regressions).
|
||||
*/
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { POST as sourcesPOST, GET as sourcesGET } from "@/app/api/0pt/sources/route";
|
||||
import { GET as sourceDescribeGET } from "@/app/api/0pt/sources/[sourceId]/route";
|
||||
import { GET as ratePolicyGET } from "@/app/api/0pt/sources/rate-policies/[sourceRatePolicyId]/route";
|
||||
import { GET as mappingsListGET, POST as mappingsPOST } from "@/app/api/0pt/lakehouse/mappings/route";
|
||||
import { GET as mappingGetGET } from "@/app/api/0pt/lakehouse/mappings/[mappingId]/route";
|
||||
import { POST as qualityRulesPOST } from "@/app/api/0pt/quality/rules/route";
|
||||
import { GET as documentsGET } from "@/app/api/0pt/documents/capture/route";
|
||||
|
||||
const VERIFIED = "x-0pt-verified-tenant";
|
||||
|
||||
function getReq(url: string, verifiedTenant = "t_a"): NextRequest {
|
||||
return new NextRequest(new URL(url, "http://localhost"), { headers: { [VERIFIED]: verifiedTenant } });
|
||||
}
|
||||
function postReq(url: string, body: unknown, verifiedTenant = "t_a"): NextRequest {
|
||||
return new NextRequest(new URL(url, "http://localhost"), {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json", [VERIFIED]: verifiedTenant },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
}
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/sources", () => {
|
||||
it("POST rejects registering a source under a foreign tenant_id (403, never reaches the service)", async () => {
|
||||
const res = await sourcesPOST(
|
||||
postReq("/api/0pt/sources", {
|
||||
source_id: "src_attack_1",
|
||||
tenant_id: "t_victim",
|
||||
project_id: "p1",
|
||||
source_type: "api",
|
||||
name: "attacker-named source",
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe("OPT_ACCESS_DENIED");
|
||||
});
|
||||
|
||||
it("POST succeeds when tenant_id matches the verified tenant", async () => {
|
||||
const res = await sourcesPOST(
|
||||
postReq("/api/0pt/sources", {
|
||||
source_id: "src_ok_1",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p1",
|
||||
source_type: "api",
|
||||
name: "legit source",
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(201);
|
||||
});
|
||||
|
||||
it("GET (list) rejects a foreign tenant_id query param (403)", async () => {
|
||||
const res = await sourcesGET(getReq("/api/0pt/sources?tenant_id=t_victim", "t_a"));
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET (list) succeeds when the query tenant_id matches", async () => {
|
||||
const res = await sourcesGET(getReq("/api/0pt/sources?tenant_id=t_a", "t_a"));
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/sources/[sourceId]", () => {
|
||||
it("GET describe rejects a foreign tenant_id (403, before any existence check)", async () => {
|
||||
const res = await sourceDescribeGET(getReq("/api/0pt/sources/src_whatever?tenant_id=t_victim", "t_a"), {
|
||||
params: Promise.resolve({ sourceId: "src_whatever" }),
|
||||
});
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/sources/rate-policies/[id]", () => {
|
||||
it("GET rejects a foreign tenant_id (403) -- this route had NO tenant check of any kind before P014", async () => {
|
||||
const res = await ratePolicyGET(getReq("/api/0pt/sources/rate-policies/srp_whatever?tenant_id=t_victim", "t_a"), {
|
||||
params: Promise.resolve({ sourceRatePolicyId: "srp_whatever" }),
|
||||
});
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET without tenant_id at all is a 400, not an unscoped read", async () => {
|
||||
const res = await ratePolicyGET(getReq("/api/0pt/sources/rate-policies/srp_whatever", "t_a"), {
|
||||
params: Promise.resolve({ sourceRatePolicyId: "srp_whatever" }),
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/lakehouse/mappings", () => {
|
||||
it("POST rejects mapping a dataset under a foreign tenant_id (403)", async () => {
|
||||
const res = await mappingsPOST(
|
||||
postReq(
|
||||
"/api/0pt/lakehouse/mappings",
|
||||
{
|
||||
tenant_id: "t_victim",
|
||||
project_id: "p1",
|
||||
dataset_id: "ds_1",
|
||||
dataset_iceberg_mapping_id: "dim_attack_1",
|
||||
namespace: "ns",
|
||||
table_name: "tbl",
|
||||
storage_uri: "s3://x/y",
|
||||
catalog_ref: "cat",
|
||||
actor_id: "actor1",
|
||||
correlation_id: "corr1",
|
||||
},
|
||||
"t_a",
|
||||
),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET (list) requires tenant_id -- omitting it no longer returns every tenant's mappings (was: full leak)", async () => {
|
||||
const res = await mappingsListGET(getReq("/api/0pt/lakehouse/mappings", "t_a"));
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("GET (list) rejects a foreign tenant_id query param (403)", async () => {
|
||||
const res = await mappingsListGET(getReq("/api/0pt/lakehouse/mappings?tenant_id=t_victim", "t_a"));
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/lakehouse/mappings/[mappingId]", () => {
|
||||
it("GET rejects a foreign tenant_id (403) -- this route had NO tenant check of any kind before P014", async () => {
|
||||
const res = await mappingGetGET(
|
||||
getReq("/api/0pt/lakehouse/mappings/dim_whatever?tenant_id=t_victim", "t_a"),
|
||||
{ params: Promise.resolve({ mappingId: "dim_whatever" }) },
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET without tenant_id at all is a 400, not an unscoped read", async () => {
|
||||
const res = await mappingGetGET(getReq("/api/0pt/lakehouse/mappings/dim_whatever", "t_a"), {
|
||||
params: Promise.resolve({ mappingId: "dim_whatever" }),
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/quality/rules", () => {
|
||||
it("POST rejects creating a rule under a foreign tenant_id (403)", async () => {
|
||||
const res = await qualityRulesPOST(
|
||||
postReq(
|
||||
"/api/0pt/quality/rules",
|
||||
{
|
||||
rule_id: "rule_attack_1",
|
||||
tenant_id: "t_victim",
|
||||
project_id: "p1",
|
||||
dataset_id: "ds_1",
|
||||
name: "attacker rule",
|
||||
expectation: { expectation_type: "not_null", kwargs: { column: "name" } },
|
||||
},
|
||||
"t_a",
|
||||
),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-tenant HTTP regression: /api/0pt/documents/capture (GET)", () => {
|
||||
it("requires tenant_id -- omitting it no longer returns every tenant's captured documents (was: full leak)", async () => {
|
||||
const res = await documentsGET(getReq("/api/0pt/documents/capture", "t_a"));
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("rejects a foreign tenant_id query param (403)", async () => {
|
||||
const res = await documentsGET(getReq("/api/0pt/documents/capture?tenant_id=t_victim", "t_a"));
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("succeeds when the query tenant_id matches the verified tenant", async () => {
|
||||
const res = await documentsGET(getReq("/api/0pt/documents/capture?tenant_id=t_a", "t_a"));
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,175 @@
|
||||
/**
|
||||
* HTTP-level tests for the P060/P067 routes added in this pass, in the same
|
||||
* shape as tests/api/0pt-cross-tenant-routes.test.ts: call the handler
|
||||
* directly with a hand-built NextRequest carrying `x-0pt-verified-tenant`,
|
||||
* which is exactly what middleware.ts forwards once a real Bearer token has
|
||||
* been verified.
|
||||
*
|
||||
* Two things are proved here that the service-level tests cannot:
|
||||
* - the new routes carry the SAME cross-tenant guard as the existing ones
|
||||
* (a new route with no guard would be the P014 hole reopened), and
|
||||
* - the activation gate is enforced at the HTTP boundary too — an
|
||||
* unclassified source gets 403, not a 200 with a quiet no-op.
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { POST as sourcesPOST } from "@/app/api/0pt/sources/route";
|
||||
import { GET as classifyGET, POST as activatePOST } from "@/app/api/0pt/sources/[sourceId]/activate/route";
|
||||
import { PUT as authorizationPUT } from "@/app/api/0pt/sources/[sourceId]/authorization/route";
|
||||
import { PUT as schedulePUT } from "@/app/api/0pt/sources/[sourceId]/schedule/route";
|
||||
import { GET as lineageGET } from "@/app/api/0pt/lineage/route";
|
||||
|
||||
const VERIFIED = "x-0pt-verified-tenant";
|
||||
|
||||
function getReq(url: string, verifiedTenant = "t_a"): NextRequest {
|
||||
return new NextRequest(new URL(url, "http://localhost"), { headers: { [VERIFIED]: verifiedTenant } });
|
||||
}
|
||||
function bodyReq(url: string, method: "POST" | "PUT", body: unknown, verifiedTenant = "t_a"): NextRequest {
|
||||
return new NextRequest(new URL(url, "http://localhost"), {
|
||||
method,
|
||||
headers: { "content-type": "application/json", [VERIFIED]: verifiedTenant },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
}
|
||||
const params = (sourceId: string) => ({ params: Promise.resolve({ sourceId }) });
|
||||
|
||||
describe("P060 routes — cross-tenant guard", () => {
|
||||
it("POST /activate rejects a foreign tenant_id (403)", async () => {
|
||||
const res = await activatePOST(
|
||||
bodyReq("/api/0pt/sources/src_x/activate", "POST", { tenant_id: "t_victim" }),
|
||||
params("src_x"),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
expect((await res.json()).error).toBe("OPT_ACCESS_DENIED");
|
||||
});
|
||||
|
||||
it("GET /activate (classification) rejects a foreign tenant_id (403)", async () => {
|
||||
const res = await classifyGET(
|
||||
getReq("/api/0pt/sources/src_x/activate?tenant_id=t_victim"),
|
||||
params("src_x"),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("PUT /authorization rejects a foreign tenant_id (403)", async () => {
|
||||
const res = await authorizationPUT(
|
||||
bodyReq("/api/0pt/sources/src_x/authorization", "PUT", {
|
||||
tenant_id: "t_victim",
|
||||
basis: "contract",
|
||||
granted_by: "usr_attacker",
|
||||
granted_at: "2026-09-04T00:00:00.000Z",
|
||||
}),
|
||||
params("src_x"),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("PUT /schedule rejects a foreign tenant_id (403)", async () => {
|
||||
const res = await schedulePUT(
|
||||
bodyReq("/api/0pt/sources/src_x/schedule", "PUT", { tenant_id: "t_victim", mode: "batch", enabled: true }),
|
||||
params("src_x"),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET /lineage rejects a foreign tenant_id (403)", async () => {
|
||||
const res = await lineageGET(getReq("/api/0pt/lineage?tenant_id=t_victim&output_name=0pt:dataset:ds_x"));
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it("GET /lineage refuses an unfiltered dump (400)", async () => {
|
||||
const res = await lineageGET(getReq("/api/0pt/lineage?tenant_id=t_a"));
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
|
||||
describe("P060 routes — the activation gate over HTTP", () => {
|
||||
it("an unclassified source cannot be activated through the API", async () => {
|
||||
const created = await sourcesPOST(
|
||||
bodyReq("/api/0pt/sources", "POST", {
|
||||
source_id: "src_http_gate_1",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_a",
|
||||
source_type: "api",
|
||||
name: "Unclassified source",
|
||||
}),
|
||||
);
|
||||
expect(created.status).toBeLessThan(300);
|
||||
const body = await created.json();
|
||||
expect(body.source.status).toBe("pending");
|
||||
|
||||
const classification = await classifyGET(
|
||||
getReq("/api/0pt/sources/src_http_gate_1/activate?tenant_id=t_a"),
|
||||
params("src_http_gate_1"),
|
||||
);
|
||||
expect(classification.status).toBe(200);
|
||||
expect((await classification.json()).classified).toBe(false);
|
||||
|
||||
const activated = await activatePOST(
|
||||
bodyReq("/api/0pt/sources/src_http_gate_1/activate", "POST", { tenant_id: "t_a" }),
|
||||
params("src_http_gate_1"),
|
||||
);
|
||||
expect(activated.status).toBe(403);
|
||||
});
|
||||
|
||||
it("a classified source activates through the API", async () => {
|
||||
await sourcesPOST(
|
||||
bodyReq("/api/0pt/sources", "POST", {
|
||||
source_id: "src_http_gate_2",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_a",
|
||||
source_type: "api",
|
||||
name: "Classified source",
|
||||
owner_id: "usr_simon",
|
||||
rights: {
|
||||
license_id: "CC-BY-4.0",
|
||||
allowed_purposes: ["catalog"],
|
||||
pii_allowed: false,
|
||||
redistribution: "internal",
|
||||
verified_at: "2026-09-04",
|
||||
verified_by: "usr_simon",
|
||||
},
|
||||
provenance: { method: "official_api" },
|
||||
}),
|
||||
);
|
||||
const auth = await authorizationPUT(
|
||||
bodyReq("/api/0pt/sources/src_http_gate_2/authorization", "PUT", {
|
||||
tenant_id: "t_a",
|
||||
basis: "public_register",
|
||||
granted_by: "usr_simon",
|
||||
granted_at: "2026-09-01T00:00:00.000Z",
|
||||
}),
|
||||
params("src_http_gate_2"),
|
||||
);
|
||||
expect(auth.status).toBe(200);
|
||||
|
||||
const activated = await activatePOST(
|
||||
bodyReq("/api/0pt/sources/src_http_gate_2/activate", "POST", { tenant_id: "t_a", actor_id: "usr_simon" }),
|
||||
params("src_http_gate_2"),
|
||||
);
|
||||
expect(activated.status).toBe(200);
|
||||
expect((await activated.json()).status).toBe("active");
|
||||
});
|
||||
|
||||
it("a service identity cannot be recorded as the authorizing actor (400)", async () => {
|
||||
await sourcesPOST(
|
||||
bodyReq("/api/0pt/sources", "POST", {
|
||||
source_id: "src_http_gate_3",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_a",
|
||||
source_type: "api",
|
||||
name: "Self-authorizing source",
|
||||
}),
|
||||
);
|
||||
const res = await authorizationPUT(
|
||||
bodyReq("/api/0pt/sources/src_http_gate_3/authorization", "PUT", {
|
||||
tenant_id: "t_a",
|
||||
basis: "internal",
|
||||
granted_by: "svc_0pt",
|
||||
granted_at: "2026-09-01T00:00:00.000Z",
|
||||
}),
|
||||
params("src_http_gate_3"),
|
||||
);
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,100 @@
|
||||
/**
|
||||
* Regression tests for the anonymous-access finding on `/api/orders` (GET)
|
||||
* and `/api/admin/metrics` (GET): a live compliance audit confirmed both
|
||||
* responded HTTP 200 with zero authentication (the order queue + financial
|
||||
* pipeline aggregates were readable by anyone). Both are outside
|
||||
* middleware.ts's matcher (`/api/0pt/:path*` only), so each handler now
|
||||
* calls `requireRouteAuth` (src/auth/require-route-auth.ts -> the same
|
||||
* fail-closed `resolveAuthContext`/Zitadel verifier `/api/0pt/*` relies on)
|
||||
* directly.
|
||||
*
|
||||
* No DATABASE_URL is set in this test env, so lib/orders-store.ts falls back
|
||||
* to its in-memory store -- these tests only exercise the auth gate, not
|
||||
* order persistence.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { GET as ordersGET } from '@/app/api/orders/route';
|
||||
import { GET as orderGET } from '@/app/api/orders/[id]/route';
|
||||
import { GET as adminMetricsGET } from '@/app/api/admin/metrics/route';
|
||||
import { POST as depositPOST } from '@/app/api/payments/[order_id]/deposit/route';
|
||||
|
||||
function req(url: string, headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest(new URL(url, 'http://localhost'), { headers });
|
||||
}
|
||||
|
||||
describe('anonymous-access regression: /api/orders (GET) and /api/admin/metrics (GET)', () => {
|
||||
const saved = { auth: process.env.AUTH_ENFORCE, node: process.env.NODE_ENV };
|
||||
|
||||
beforeEach(() => {
|
||||
// Default posture: AUTH_ENFORCE unset => enforced (fail-closed), matching
|
||||
// production and matching how resolveAuthContext's own tests run.
|
||||
delete process.env.AUTH_ENFORCE;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (saved.auth === undefined) delete process.env.AUTH_ENFORCE;
|
||||
else process.env.AUTH_ENFORCE = saved.auth;
|
||||
if (saved.node === undefined) delete process.env.NODE_ENV;
|
||||
else process.env.NODE_ENV = saved.node;
|
||||
});
|
||||
|
||||
it('REGRESSION: GET /api/orders 401s with no Authorization header (was: 200 + full order list)', async () => {
|
||||
const res = await ordersGET(req('/api/orders'));
|
||||
expect(res.status).toBe(401);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe('OPT_UNAUTHENTICATED');
|
||||
});
|
||||
|
||||
it('GET /api/orders 401s on an invalid/unparseable bearer token', async () => {
|
||||
const res = await ordersGET(req('/api/orders', { authorization: 'Bearer not.a.real.jwt' }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('GET /api/orders/{id} rejects anonymous and spoofed-tenant reads before loading an order', async () => {
|
||||
const params = { params: Promise.resolve({ id: 'order-unknown' }) };
|
||||
expect((await orderGET(req('/api/orders/order-unknown'), params)).status).toBe(401);
|
||||
expect((await orderGET(req('/api/orders/order-unknown', {
|
||||
'x-0pt-verified-tenant': 'tenant_attacker',
|
||||
}), params)).status).toBe(401);
|
||||
});
|
||||
|
||||
it('deposit checkout rejects anonymous callers before checking Stripe credentials or order id', async () => {
|
||||
const request = req('/api/payments/order-unknown/deposit');
|
||||
const result = await depositPOST(request, { params: Promise.resolve({ order_id: 'order-unknown' }) });
|
||||
expect(result.status).toBe(401);
|
||||
});
|
||||
|
||||
it('REGRESSION: GET /api/admin/metrics 401s with no Authorization header (was: 200 + financial aggregates)', async () => {
|
||||
const res = await adminMetricsGET(req('/api/admin/metrics'));
|
||||
expect(res.status).toBe(401);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe('OPT_UNAUTHENTICATED');
|
||||
});
|
||||
|
||||
it('a bare X-Tenant-Id header alone (no bearer token) does not grant access to either route', async () => {
|
||||
// Guards against a shortcut implementation that trusts a client-supplied
|
||||
// tenant/verified header instead of re-verifying the token.
|
||||
const ordersRes = await ordersGET(req('/api/orders', { 'x-tenant-id': 'tenant_attacker' }));
|
||||
expect(ordersRes.status).toBe(401);
|
||||
|
||||
const metricsRes = await adminMetricsGET(req('/api/admin/metrics', { 'x-tenant-id': 'tenant_attacker' }));
|
||||
expect(metricsRes.status).toBe(401);
|
||||
});
|
||||
|
||||
it('a spoofed x-0pt-verified-tenant header alone does not grant access (never trusted directly)', async () => {
|
||||
// These routes sit outside middleware.ts's matcher, so nothing strips or
|
||||
// overwrites this header before the handler sees it -- proving the
|
||||
// handler re-verifies via the real JWT check rather than trusting it.
|
||||
const res = await ordersGET(req('/api/orders', { 'x-0pt-verified-tenant': 'tenant_attacker' }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('AUTH_ENFORCE=false cannot mint/read payable orders without a verified buyer', async () => {
|
||||
process.env.AUTH_ENFORCE = 'false';
|
||||
const ordersRes = await ordersGET(req('/api/orders'));
|
||||
expect(ordersRes.status).toBe(401);
|
||||
const metricsRes = await adminMetricsGET(req('/api/admin/metrics'));
|
||||
expect(metricsRes.status).toBe(200);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,33 @@
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { POST as capture } from '@/app/api/0pt/documents/capture/route';
|
||||
import { POST as extract } from '@/app/api/0pt/documents/[documentId]/extraction/route';
|
||||
import { documentCaptureService } from '@/src/services/document-capture-service';
|
||||
import { documentExtractionService } from '@/src/services/document-extraction-service';
|
||||
|
||||
function request(body: object) {
|
||||
return new NextRequest('http://localhost/api/0pt/documents', { method: 'POST',
|
||||
headers: { 'content-type': 'application/json', 'x-0pt-verified-tenant': 'tenant-a', 'x-0pt-verified-sub': 'user-a' },
|
||||
body: JSON.stringify(body) });
|
||||
}
|
||||
const base = { tenant_id: 'tenant-a', project_id: 'project-a', model_id: 'model-test' };
|
||||
const mailbox = { tenant_id: 'directory', client_id: 'test', client_secret: 'test', mailbox_address: 'test@example.test' };
|
||||
describe('document route verified actor', () => {
|
||||
afterEach(() => vi.restoreAllMocks());
|
||||
it('rejects forged body actors before either service is called', async () => {
|
||||
const captured = vi.spyOn(documentCaptureService, 'captureFromMailbox');
|
||||
const extracted = vi.spyOn(documentExtractionService, 'extractDocument');
|
||||
expect((await capture(request({ ...base, mailbox, actor_id: 'victim' }))).status).toBe(403);
|
||||
expect((await extract(request({ ...base, actor_id: 'victim' }), { params: Promise.resolve({ documentId: 'd' }) })).status).toBe(403);
|
||||
expect(captured).not.toHaveBeenCalled();
|
||||
expect(extracted).not.toHaveBeenCalled();
|
||||
});
|
||||
it('fills the actor from the verified subject when the body omits it', async () => {
|
||||
const captured = vi.spyOn(documentCaptureService, 'captureFromMailbox').mockResolvedValue({} as never);
|
||||
const extracted = vi.spyOn(documentExtractionService, 'extractDocument').mockResolvedValue({} as never);
|
||||
expect((await capture(request({ ...base, mailbox }))).status).toBe(201);
|
||||
expect((await extract(request(base), { params: Promise.resolve({ documentId: 'd' }) })).status).toBe(201);
|
||||
expect(captured.mock.calls[0]?.[1].actor_id).toBe('user-a');
|
||||
expect(extracted.mock.calls[0]?.[1].actor_id).toBe('user-a');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* Route-level regression test for GET /api/health (BACKLOG P0-3): the old
|
||||
* handler hardcoded `ok: true` regardless of dependency state. These tests
|
||||
* cover the default (nothing configured) baseline against the real route
|
||||
* handler; per-dependency ok/error branching is covered at the unit level in
|
||||
* tests/lib/health-checks.test.ts (dependency-injected, no network/DB
|
||||
* needed).
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from "vitest";
|
||||
import { GET as healthGET } from "@/app/api/health/route";
|
||||
|
||||
describe("GET /api/health", () => {
|
||||
const savedEnv = {
|
||||
DATABASE_URL: process.env.DATABASE_URL,
|
||||
POSTGRES_URL: process.env.POSTGRES_URL,
|
||||
ENGINE_URL: process.env.ENGINE_URL,
|
||||
STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
|
||||
REDIS_URL: process.env.REDIS_URL,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
delete process.env.DATABASE_URL;
|
||||
delete process.env.POSTGRES_URL;
|
||||
delete process.env.ENGINE_URL;
|
||||
delete process.env.STRIPE_SECRET_KEY;
|
||||
delete process.env.REDIS_URL;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
for (const [k, v] of Object.entries(savedEnv)) {
|
||||
if (v === undefined) delete process.env[k];
|
||||
else process.env[k] = v;
|
||||
}
|
||||
});
|
||||
|
||||
it("REGRESSION: always returns HTTP 200 (liveness), but `ok` now reflects a real per-dependency check rather than a hardcoded true", async () => {
|
||||
const res = await healthGET();
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
// With nothing configured, nothing can be degraded -- ok:true here is
|
||||
// now an honest conclusion, not a hardcoded literal.
|
||||
expect(body.ok).toBe(true);
|
||||
expect(body.service).toBe("0pt-web");
|
||||
});
|
||||
|
||||
it("reports not_configured (not the old flat 'configured'/'not_configured' guess) for every unset dependency", async () => {
|
||||
const res = await healthGET();
|
||||
const body = await res.json();
|
||||
expect(body.db).toBe("not_configured");
|
||||
expect(body.engine).toBe("not_configured");
|
||||
expect(body.stripe).toBe("not_configured");
|
||||
expect(body.queue).toBe("not_configured");
|
||||
});
|
||||
|
||||
it("reports a configured but unreachable queue as error (never a fabricated ok)", async () => {
|
||||
process.env.REDIS_URL = "redis://127.0.0.1:1";
|
||||
const res = await healthGET();
|
||||
const body = await res.json();
|
||||
expect(body.queue).toBe("error");
|
||||
// Liveness stays 200; readiness is what fails closed on a broken dependency.
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("response includes a ts timestamp", async () => {
|
||||
const res = await healthGET();
|
||||
const body = await res.json();
|
||||
expect(new Date(body.ts).toString()).not.toBe("Invalid Date");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,105 @@
|
||||
/**
|
||||
* DES1GN ADR D3 (§31): ImportDispatchPolicy — ren policy-funktion, testad per
|
||||
* kombination (format × bytes × rows, gränsvärden inkluderade), plus route-
|
||||
* kopplingen: rows > policy.maxRows -> 413 n0d_dispatch_required med hint
|
||||
* (descriptor-gate stängd), inline-taket oförändrat.
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { IMPORT_DISPATCH_POLICY, evaluateImportDispatch } from "@/lib/import-dispatch-policy";
|
||||
|
||||
describe("evaluateImportDispatch — verdict per kombination", () => {
|
||||
it("gränsvärde maxInlineRows: exakt 500 rader -> inline", () => {
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: 100, rows: IMPORT_DISPATCH_POLICY.maxInlineRows })).toEqual({ verdict: "inline" });
|
||||
});
|
||||
|
||||
it("maxInlineRows < rows <= maxRows -> row_cap_exceeded (inline-taket, oförändrat)", () => {
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: 100, rows: IMPORT_DISPATCH_POLICY.maxInlineRows + 1 })).toEqual({
|
||||
verdict: "row_cap_exceeded",
|
||||
rows: 501,
|
||||
maxInlineRows: 500,
|
||||
});
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: 100, rows: IMPORT_DISPATCH_POLICY.maxRows }).verdict).toBe("row_cap_exceeded");
|
||||
});
|
||||
|
||||
it("rows > maxRows -> dispatch_n0d (D3-signalen)", () => {
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: 100, rows: IMPORT_DISPATCH_POLICY.maxRows + 1 })).toEqual({
|
||||
verdict: "dispatch_n0d",
|
||||
rows: 5001,
|
||||
maxRows: 5000,
|
||||
});
|
||||
});
|
||||
|
||||
it("bytes > maxBytes -> byte_cap_exceeded, oavsett rows", () => {
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: IMPORT_DISPATCH_POLICY.maxBytes + 1, rows: 1 }).verdict).toBe("byte_cap_exceeded");
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: IMPORT_DISPATCH_POLICY.maxBytes, rows: 1 }).verdict).toBe("inline");
|
||||
});
|
||||
|
||||
it("format utanför allowlist -> unsupported_format", () => {
|
||||
expect(evaluateImportDispatch({ format: "xlsx", bytes: 10, rows: 1 })).toEqual({ verdict: "unsupported_format", format: "xlsx" });
|
||||
});
|
||||
|
||||
it("precedens: format slår bytes, bytes slår rows", () => {
|
||||
expect(evaluateImportDispatch({ format: "json", bytes: 9e9, rows: 9e9 }).verdict).toBe("unsupported_format");
|
||||
expect(evaluateImportDispatch({ format: "csv", bytes: 9e9, rows: 9e9 }).verdict).toBe("byte_cap_exceeded");
|
||||
});
|
||||
});
|
||||
|
||||
describe("route-koppling: POST /api/orders/import respekterar policyn", () => {
|
||||
const { requireOrderOwnerMock, createOrderMock, ingestEventMock, mockOwner } = vi.hoisted(() => ({
|
||||
requireOrderOwnerMock: vi.fn(),
|
||||
createOrderMock: vi.fn(),
|
||||
ingestEventMock: vi.fn().mockResolvedValue({}),
|
||||
mockOwner: { owner: { tenantId: "tenant-test", subject: "buyer-test" } },
|
||||
}));
|
||||
const _unused = mockOwner;
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: (...args: unknown[]) => requireOrderOwnerMock(...args),
|
||||
}));
|
||||
vi.mock("@/lib/orders-store", () => ({ createOrder: (...args: unknown[]) => createOrderMock(...args) }));
|
||||
vi.mock("@/src/clients/aud0-client", () => ({ createAud0Client: () => ({ ingestEvent: ingestEventMock }) }));
|
||||
|
||||
let POST: typeof import("@/app/api/orders/import/route").POST;
|
||||
let MAX_IMPORT_ROWS: number;
|
||||
|
||||
beforeEach(async () => {
|
||||
vi.clearAllMocks();
|
||||
requireOrderOwnerMock.mockResolvedValue(mockOwner);
|
||||
({ POST, MAX_IMPORT_ROWS } = await import("@/app/api/orders/import/route"));
|
||||
});
|
||||
|
||||
function postReq(csv: string): NextRequest {
|
||||
return new NextRequest(new URL("/api/orders/import", "http://localhost"), {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ mode: "validate", csv }),
|
||||
headers: { "content-type": "application/json" },
|
||||
});
|
||||
}
|
||||
|
||||
const line = "custom,icp,Bolag,10,Engångs,SE";
|
||||
|
||||
it("exakt maxInlineRows rader -> 200 (inline-beteende oförändrat)", async () => {
|
||||
const csv = ["flow,service_type,type,volume,frequency,markets", ...Array.from({ length: MAX_IMPORT_ROWS }, () => line)].join("\n");
|
||||
const res = await POST(postReq(csv));
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("maxRows < rows -> 413 n0d_dispatch_required med UNVERIFIED-hint, ingen skrivning", async () => {
|
||||
const csv = ["flow,service_type,type,volume,frequency,markets", ...Array.from({ length: IMPORT_DISPATCH_POLICY.maxRows + 1 }, () => line)].join("\n");
|
||||
const res = await POST(postReq(csv));
|
||||
expect(res.status).toBe(413);
|
||||
const body = (await res.json()) as { error: { code: string; hint: { capability_id: string; job_type: string; status: string } } };
|
||||
expect(body.error.code).toBe("n0d_dispatch_required");
|
||||
expect(body.error.hint).toEqual({ capability_id: "0pt.import_execute", job_type: "0pt.import_execute_job", status: "UNVERIFIED" });
|
||||
expect(createOrderMock).not.toHaveBeenCalled();
|
||||
expect(ingestEventMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("CSV > maxBytes -> 413 csv_too_large", async () => {
|
||||
const csv = "flow,service_type,type,volume,frequency,markets\n" + "x".repeat(IMPORT_DISPATCH_POLICY.maxBytes);
|
||||
const res = await POST(postReq(csv));
|
||||
expect(res.status).toBe(413);
|
||||
const body = (await res.json()) as { error: { code: string } };
|
||||
expect(body.error.code).toBe("csv_too_large");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,57 @@
|
||||
/**
|
||||
* 0pt#53: `getSqlForDurableStore` (lib/db.ts) throws
|
||||
* `SiaxError("DEPENDENCY_UNAVAILABLE")` (httpStatus 503, retryable) when a
|
||||
* money-bearing store would silently fall back to an in-memory Map in a
|
||||
* production runtime. The /api/0pt/* surface maps that error via
|
||||
* src/http/siax-error-response.ts; the SEVEN legacy routes outside the
|
||||
* middleware matcher (orders, orders/[id], subscriptions, payments/deposit,
|
||||
* payments/release, webhooks/stripe, admin/metrics) did NOT, so the documented
|
||||
* 503 leaked as Next's opaque 500 with no error body.
|
||||
*
|
||||
* These tests pin the mapping itself: `isSiaxError` accepts real SiaxErrors,
|
||||
* `siaxErrorResponseForLegacy` renders the pinned `.httpStatus` and the
|
||||
* structured `toJSON()` body (code + source + retryable, no internals), and
|
||||
* — most importantly — the DEPENDENCY_UNAVAILABLE code maps to 503 with
|
||||
* `retryable: true` so callers (Stripe retries, the UI) can distinguish a
|
||||
* transient store outage from a hard failure.
|
||||
*/
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { NextResponse } from "next/server";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { isSiaxError, siaxErrorResponseForLegacy } from "@/app/api/siax-error-mapping";
|
||||
|
||||
describe("0pt#53 legacy-route SiaxError mapping (app/api/siax-error-mapping.ts)", () => {
|
||||
it("isSiaxError: true for a real SiaxError, false for plain errors", () => {
|
||||
expect(isSiaxError(new SiaxError("DEPENDENCY_UNAVAILABLE", "0pt.orders", "x"))).toBe(true);
|
||||
expect(isSiaxError(new Error("plain"))).toBe(false);
|
||||
expect(isSiaxError(null)).toBe(false);
|
||||
expect(isSiaxError("nope")).toBe(false);
|
||||
});
|
||||
|
||||
it("DEPENDENCY_UNAVAILABLE maps to 503 with the structured, non-internal body", () => {
|
||||
const err = new SiaxError(
|
||||
"DEPENDENCY_UNAVAILABLE",
|
||||
"0pt.orders",
|
||||
'no database configured for persistent store "0pt.orders" in a production runtime',
|
||||
);
|
||||
expect(err.httpStatus).toBe(503);
|
||||
expect(err.retryable).toBe(true);
|
||||
|
||||
const res = siaxErrorResponseForLegacy(err) as NextResponse;
|
||||
expect(res.status).toBe(503);
|
||||
void res.json().then((body: Record<string, unknown>) => {
|
||||
expect(body.error).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
expect(body.source).toBe("0pt.orders");
|
||||
expect(body.retryable).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
it("the store name travels in the body so the operator knows WHICH store failed", () => {
|
||||
const res = siaxErrorResponseForLegacy(
|
||||
new SiaxError("DEPENDENCY_UNAVAILABLE", "0pt.subscriptions", "no database"),
|
||||
);
|
||||
void res.json().then((body: Record<string, unknown>) => {
|
||||
expect(body.source).toBe("0pt.subscriptions");
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,226 @@
|
||||
/**
|
||||
* Spår C — @siax/collaboration-kernelns första produktkonsument:
|
||||
* /api/admin/order-notes (persisted collaboration state på admin-orders).
|
||||
*
|
||||
* Mönstret följer tests/api/anonymous-routes-auth.test.ts +
|
||||
* orders-idempotency.test.ts: route-handlers anropas direkt med handbyggda
|
||||
* NextRequest. Ingen DATABASE_URL i test-miljön => lib/order-notes-store.ts
|
||||
* faller tillbaka på sin dokumenterade in-memory-store (production vägrar
|
||||
* den vägen via resolveStoreMode — se lib/db.ts).
|
||||
*/
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
|
||||
vi.mock("@/src/auth/require-route-auth", () => ({
|
||||
requireRouteAuth: vi.fn(),
|
||||
}));
|
||||
vi.mock("@/src/clients/aud0-client", () => ({
|
||||
createAud0Client: vi.fn(() => ({ ingestEvent: vi.fn().mockResolvedValue({}) })),
|
||||
}));
|
||||
|
||||
import { requireRouteAuth } from "@/src/auth/require-route-auth";
|
||||
import { createAud0Client } from "@/src/clients/aud0-client";
|
||||
import { GET, PATCH, POST } from "@/app/api/admin/order-notes/route";
|
||||
import { getOrder, createOrder } from "@/lib/orders-store";
|
||||
import {
|
||||
addNote,
|
||||
listNotes,
|
||||
resetOrderNotesMemoryForTests,
|
||||
} from "@/lib/order-notes-store";
|
||||
|
||||
const authed = { tenantId: "tenant-test", actorId: "admin-simon", requestId: "req-1" };
|
||||
|
||||
function mockAuth(ctx = authed) {
|
||||
vi.mocked(requireRouteAuth).mockResolvedValue({ ctx } as never);
|
||||
}
|
||||
|
||||
function req(
|
||||
url: string,
|
||||
init: { method?: string; headers?: Record<string, string>; body?: string } = {},
|
||||
): NextRequest {
|
||||
return new NextRequest(new URL(url, "http://localhost"), init);
|
||||
}
|
||||
|
||||
function jsonReq(url: string, body: unknown, method = "POST"): NextRequest {
|
||||
return req(url, {
|
||||
method,
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
}
|
||||
|
||||
let orderId: string;
|
||||
|
||||
beforeEach(async () => {
|
||||
vi.mocked(requireRouteAuth).mockReset();
|
||||
vi.mocked(createAud0Client).mockClear();
|
||||
resetOrderNotesMemoryForTests();
|
||||
mockAuth();
|
||||
const created = await createOrder("custom", {
|
||||
markets: ["SE"],
|
||||
type: "Bolag",
|
||||
volume: 10,
|
||||
});
|
||||
orderId = created.order.order_id;
|
||||
// Legacy anonymous draft får annoteras av admin — men en tenant-ägd order
|
||||
// behöver token-match. Skapa därför testordern anonym (tenant null) och
|
||||
// testa tenant-guarden separat med en ägd order.
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
resetOrderNotesMemoryForTests();
|
||||
});
|
||||
|
||||
describe("GET /api/admin/order-notes", () => {
|
||||
it("empty order -> 200 med tom lista (explicit empty behavior)", async () => {
|
||||
const res = await GET(req(`/api/admin/order-notes?order_id=${orderId}`));
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.notes).toEqual([]);
|
||||
});
|
||||
|
||||
it("saknad order_id -> 400; okänd order -> 404", async () => {
|
||||
expect((await GET(req("/api/admin/order-notes"))).status).toBe(400);
|
||||
expect((await GET(req("/api/admin/order-notes?order_id=nope"))).status).toBe(404);
|
||||
});
|
||||
|
||||
it("utan auth-svar från requireRouteAuth -> fail-closed (401), aldrig data", async () => {
|
||||
vi.mocked(requireRouteAuth).mockResolvedValueOnce({
|
||||
response: new NextResponse(null, { status: 401 }),
|
||||
} as never);
|
||||
const res = await GET(req(`/api/admin/order-notes?order_id=${orderId}`));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
describe("POST + GET happy path (kernel-semantik)", () => {
|
||||
it("201 skapar noten, GET listar deterministiskt (Lamport-ordning, inte insättningsordning)", async () => {
|
||||
const r1 = await POST(jsonReq("/api/admin/order-notes", { order_id: orderId, body: "Första" }));
|
||||
expect(r1.status).toBe(201);
|
||||
const first = await r1.json();
|
||||
expect(first.version).toBe(1);
|
||||
expect(first.clock).toBe(1);
|
||||
|
||||
const r2 = await POST(jsonReq("/api/admin/order-notes", { order_id: orderId, body: "Andra" }));
|
||||
expect(r2.status).toBe(201);
|
||||
|
||||
const list = await (await GET(req(`/api/admin/order-notes?order_id=${orderId}`))).json();
|
||||
expect(list.notes).toHaveLength(2);
|
||||
// kernel mergeOperationLog: stigande (clock, actorId, id)
|
||||
const clocks = list.notes.map((n: { clock: number }) => n.clock);
|
||||
expect([...clocks].sort((a: number, b: number) => a - b)).toEqual(clocks);
|
||||
expect(list.notes[0].body).toBe("Första");
|
||||
|
||||
// audit event emitterades via hostens AUD0-klient
|
||||
const ingest = vi.mocked(createAud0Client).mock.results.at(-1)?.value as {
|
||||
ingestEvent: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
expect(ingest.ingestEvent).toHaveBeenCalled();
|
||||
const evt = ingest.ingestEvent.mock.calls[0][0];
|
||||
expect(evt.capability_id).toBe("admin.order_notes");
|
||||
expect(evt.event_type).toBe("order_note.created");
|
||||
});
|
||||
|
||||
it("tom body -> 400 (server-authoritative validering)", async () => {
|
||||
const res = await POST(jsonReq("/api/admin/order-notes", { order_id: orderId, body: " " }));
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it("tenant-guard: order tillhör annan tenant än token -> 403", async () => {
|
||||
const created = await createOrder("custom", { markets: ["SE"], volume: 5 }, undefined, {
|
||||
tenantId: "tenant-other",
|
||||
subject: "buyer-other",
|
||||
});
|
||||
const res = await POST(
|
||||
jsonReq("/api/admin/order-notes", { order_id: created.order.order_id, body: "hej" }),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe("OPT_ACCESS_DENIED");
|
||||
});
|
||||
});
|
||||
|
||||
describe("PATCH — optimistisk samtidighet (conflict behavior)", () => {
|
||||
it("rätt version -> 200, version+1, klockan tickar (nextLamportClock)", async () => {
|
||||
const note = await addNote({ order_id: orderId, tenant_id: null, author_id: "a", body: "v1" });
|
||||
const res = await PATCH(
|
||||
jsonReq("/api/admin/order-notes", { note_id: note.note_id, body: "v2", version: 1 }, "PATCH"),
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
const updated = await res.json();
|
||||
expect(updated.body).toBe("v2");
|
||||
expect(updated.version).toBe(2);
|
||||
expect(updated.clock).toBe(note.clock + 1);
|
||||
});
|
||||
|
||||
it("stale version -> 409 med aktuell version (multi-user semantics)", async () => {
|
||||
const note = await addNote({ order_id: orderId, tenant_id: null, author_id: "a", body: "v1" });
|
||||
await updateNoteViaApi(note.note_id, "v2 fran annan skribent"); // samtidig skribant -> v2
|
||||
const res = await PATCH(
|
||||
jsonReq("/api/admin/order-notes", { note_id: note.note_id, body: "v3 stale", version: 1 }, "PATCH"),
|
||||
);
|
||||
expect(res.status).toBe(409);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe("version_conflict");
|
||||
expect(body.current_version).toBe(2);
|
||||
});
|
||||
|
||||
it("okänd note -> 404; ogiltig version -> 400", async () => {
|
||||
expect(
|
||||
(
|
||||
await PATCH(
|
||||
jsonReq(
|
||||
"/api/admin/order-notes",
|
||||
{ note_id: "note_nope", body: "x", version: 1 },
|
||||
"PATCH",
|
||||
),
|
||||
)
|
||||
).status,
|
||||
).toBe(404);
|
||||
const note = await addNote({ order_id: orderId, tenant_id: null, author_id: "a", body: "v1" });
|
||||
expect(
|
||||
(
|
||||
await PATCH(
|
||||
jsonReq(
|
||||
"/api/admin/order-notes",
|
||||
{ note_id: note.note_id, body: "x", version: 1.5 },
|
||||
"PATCH",
|
||||
),
|
||||
)
|
||||
).status,
|
||||
).toBe(400);
|
||||
});
|
||||
|
||||
it("PATCH utan auth -> 401 fail-closed", async () => {
|
||||
vi.mocked(requireRouteAuth).mockResolvedValueOnce({
|
||||
response: new NextResponse(null, { status: 401 }),
|
||||
} as never);
|
||||
const res = await PATCH(
|
||||
jsonReq("/api/admin/order-notes", { note_id: "x", body: "x", version: 1 }, "PATCH"),
|
||||
);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
async function updateNoteViaApi(noteId: string, body: string) {
|
||||
const res = await PATCH(jsonReq("/api/admin/order-notes", { note_id: noteId, body, version: 1 }, "PATCH"));
|
||||
expect(res.status).toBe(200);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
describe("kernel-återanvändning (capability, inte paket)", () => {
|
||||
it("listNotes är kernel-mergead: ordningen följer compareOperations (klocka -> actorId -> id), två listningar identiska", async () => {
|
||||
const a = await addNote({ order_id: orderId, tenant_id: null, author_id: "a", body: "A" });
|
||||
const b = await addNote({ order_id: orderId, tenant_id: null, author_id: "b", body: "B" });
|
||||
const first = await listNotes(orderId);
|
||||
const second = await listNotes(orderId);
|
||||
expect(second.map((n) => n.note_id)).toEqual(first.map((n) => n.note_id));
|
||||
// stigande klocka = deterministisk kernel-ordning, oberoende av minnes-mapens iteration
|
||||
expect(first.map((n) => n.clock)).toEqual([a.clock, b.clock].sort((x, y) => x - y));
|
||||
expect(first.map((n) => n.note_id)).toEqual([a.note_id, b.note_id]);
|
||||
});
|
||||
});
|
||||
|
||||
// getOrder används i routen (server-authoritative tenant-uppslag) — håll
|
||||
// importen levande så refaktorer inte tyst tappar guarden.
|
||||
void getOrder;
|
||||
@@ -0,0 +1,55 @@
|
||||
import { beforeEach, expect, it, vi } from "vitest";
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
auth: vi.fn(),
|
||||
getOrder: vi.fn(),
|
||||
setStatusIfCurrent: vi.fn(),
|
||||
}));
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({ requireOrderOwner: mocks.auth }));
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
getOwnedOrder: mocks.getOrder,
|
||||
setOwnedStatusIfCurrent: mocks.setStatusIfCurrent,
|
||||
}));
|
||||
|
||||
import { PATCH } from "@/app/api/orders/[id]/route";
|
||||
|
||||
beforeEach(() => {
|
||||
mocks.auth.mockReset().mockResolvedValue({ owner: { tenantId: "verified-tenant", subject: "buyer-1" } });
|
||||
mocks.getOrder.mockReset().mockResolvedValue({ order_id: "order-1", status: "draft" });
|
||||
mocks.setStatusIfCurrent.mockReset().mockResolvedValue({ order_id: "order-1", status: "accepted" });
|
||||
});
|
||||
|
||||
function request(status: string) {
|
||||
return new NextRequest("https://0pt.app/api/orders/order-1", {
|
||||
method: "PATCH",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ status }),
|
||||
});
|
||||
}
|
||||
|
||||
const ctx = { params: Promise.resolve({ id: "order-1" }) };
|
||||
|
||||
it("requires verified auth before changing an order", async () => {
|
||||
mocks.auth.mockResolvedValue({ response: NextResponse.json({ error: "unauthenticated" }, { status: 401 }) });
|
||||
expect((await PATCH(request("accepted"), ctx)).status).toBe(401);
|
||||
expect(mocks.getOrder).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("rejects client writes to payment-confirmed states", async () => {
|
||||
expect((await PATCH(request("in_production"), ctx)).status).toBe(403);
|
||||
expect((await PATCH(request("delivered"), ctx)).status).toBe(403);
|
||||
expect(mocks.setStatusIfCurrent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("cannot jump from draft directly to accepted", async () => {
|
||||
expect((await PATCH(request("accepted"), ctx)).status).toBe(409);
|
||||
expect(mocks.setStatusIfCurrent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("uses an atomic compare-and-set transition after review", async () => {
|
||||
mocks.getOrder.mockResolvedValue({ order_id: "order-1", status: "review" });
|
||||
expect((await PATCH(request("accepted"), ctx)).status).toBe(200);
|
||||
expect(mocks.getOrder).toHaveBeenCalledWith("order-1", "verified-tenant");
|
||||
expect(mocks.setStatusIfCurrent).toHaveBeenCalledWith("order-1", "verified-tenant", "review", "accepted");
|
||||
});
|
||||
@@ -0,0 +1,71 @@
|
||||
/**
|
||||
* Våg 3.4 (DoD §56): unit tests for GET /api/orders/export — the first
|
||||
* adoption of the export kernel. Follows the suite pattern of calling the
|
||||
* route handler directly with a hand-built NextRequest and mocked auth/store.
|
||||
*/
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: vi.fn().mockResolvedValue({ owner: { tenantId: "tenant-test", subject: "buyer-test" } }),
|
||||
}));
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
listOwnedOrders: vi.fn().mockResolvedValue([
|
||||
{ order_id: "ord_1", flow: "custom", status: "draft", deposit_ore: 5000, total_ore: 10000 },
|
||||
{ order_id: 'ord,"2"', flow: "platform", status: "delivered", deposit_ore: 0, total_ore: 12345 },
|
||||
]),
|
||||
}));
|
||||
|
||||
import { GET as exportGET } from "@/app/api/orders/export/route";
|
||||
|
||||
function getReq(): NextRequest {
|
||||
return new NextRequest(new URL("/api/orders/export", "http://localhost"), { method: "GET" });
|
||||
}
|
||||
|
||||
describe("GET /api/orders/export — CSV (våg 3.4, DoD §56)", () => {
|
||||
it("emits the documented header row and CRLF line endings", async () => {
|
||||
const r = await exportGET(getReq());
|
||||
expect(r.status).toBe(200);
|
||||
expect(r.headers.get("content-type")).toContain("text/csv");
|
||||
expect(r.headers.get("content-disposition")).toMatch(/^attachment; filename="orders-\d{4}-\d{2}-\d{2}\.csv"$/);
|
||||
const body = await r.text();
|
||||
const lines = body.split("\r\n");
|
||||
expect(lines[0]).toBe("order_id,flow,status,deposit_ore,total_ore");
|
||||
expect(lines[1]).toBe("ord_1,custom,draft,5000,10000");
|
||||
});
|
||||
|
||||
it("RFC4180-quotes fields containing comma/quote (doubled quotes)", async () => {
|
||||
const r = await exportGET(getReq());
|
||||
const body = await r.text();
|
||||
expect(body).toContain('"ord,""2"""');
|
||||
});
|
||||
|
||||
it("exports RAW öre — no locale formatting in the export (öre is canonical)", async () => {
|
||||
const r = await exportGET(getReq());
|
||||
const body = await r.text();
|
||||
expect(body).toContain("ord_1,custom,draft,5000,10000");
|
||||
expect(body).not.toContain("100,00");
|
||||
expect(body).not.toMatch(/\u00A0| kr/);
|
||||
});
|
||||
|
||||
it("no row truncation: export is complete per DoD §56 (cap documented)", async () => {
|
||||
const r = await exportGET(getReq());
|
||||
const body = await r.text();
|
||||
const rows = body.trimEnd().split("\r\n").length - 1;
|
||||
expect(rows).toBe(2);
|
||||
});
|
||||
|
||||
it("auth is fail-closed: the route delegates to requireOrderOwner (401 contract)", async () => {
|
||||
// The mocked requireOrderOwner resolves with an owner; the 401 path is the
|
||||
// auth.response passthrough asserted in tests/api/anonymous-routes-auth.
|
||||
// This test pins the wiring: the handler must return auth.response
|
||||
// verbatim when present, before any store access.
|
||||
const { requireOrderOwner } = await import("@/src/auth/require-order-owner");
|
||||
const mocked = requireOrderOwner as ReturnType<typeof vi.fn>;
|
||||
mocked.mockResolvedValueOnce({
|
||||
response: new Response(JSON.stringify({ error: { code: "unauthorized" } }), { status: 401 }),
|
||||
});
|
||||
const r = await exportGET(getReq());
|
||||
expect(r.status).toBe(401);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,65 @@
|
||||
/**
|
||||
* P014: HTTP-level proof that POST /api/orders honors the `Idempotency-Key`
|
||||
* header end to end (route -> lib/orders-store.ts), matching the pattern
|
||||
* used elsewhere in this suite (tests/api/anonymous-routes-auth.test.ts) of
|
||||
* calling the route handler directly with a hand-built NextRequest.
|
||||
*/
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: vi.fn().mockResolvedValue({ owner: { tenantId: "tenant-test", subject: "buyer-test" } }),
|
||||
}));
|
||||
import { POST as ordersPOST } from "@/app/api/orders/route";
|
||||
|
||||
function postReq(body: unknown, headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest(new URL("/api/orders", "http://localhost"), {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json", ...headers },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
}
|
||||
|
||||
const BODY = { flow: "custom", config: { markets: ["SE"], type: "Bolag", fieldIds: ["identity"], volume: 1000 } };
|
||||
const BODY_DIFFERENT = { flow: "custom", config: { markets: ["NO"], type: "Bolag", fieldIds: ["identity"], volume: 9000 } };
|
||||
|
||||
describe("POST /api/orders — Idempotency-Key", () => {
|
||||
it("no header: two identical requests create two distinct orders (201, 201)", async () => {
|
||||
const r1 = await ordersPOST(postReq(BODY));
|
||||
const r2 = await ordersPOST(postReq(BODY));
|
||||
expect(r1.status).toBe(201);
|
||||
expect(r2.status).toBe(201);
|
||||
const b1 = await r1.json();
|
||||
const b2 = await r2.json();
|
||||
expect(b1.order_id).not.toBe(b2.order_id);
|
||||
});
|
||||
|
||||
it("REGRESSION: same Idempotency-Key replays the original order (201 then 200, same order_id)", async () => {
|
||||
const key = `idem_${crypto.randomUUID()}`;
|
||||
const r1 = await ordersPOST(postReq(BODY, { "Idempotency-Key": key }));
|
||||
const r2 = await ordersPOST(postReq(BODY, { "Idempotency-Key": key }));
|
||||
expect(r1.status).toBe(201);
|
||||
expect(r2.status).toBe(200); // replayed, not created
|
||||
const b1 = await r1.json();
|
||||
const b2 = await r2.json();
|
||||
expect(b2.order_id).toBe(b1.order_id);
|
||||
expect(b2.total_ore).toBe(b1.total_ore);
|
||||
});
|
||||
|
||||
it("reusing the same key for a materially different order is a 409, not a silent merge", async () => {
|
||||
const key = `idem_${crypto.randomUUID()}`;
|
||||
const r1 = await ordersPOST(postReq(BODY, { "Idempotency-Key": key }));
|
||||
expect(r1.status).toBe(201);
|
||||
const r2 = await ordersPOST(postReq(BODY_DIFFERENT, { "Idempotency-Key": key }));
|
||||
expect(r2.status).toBe(409);
|
||||
const b2 = await r2.json();
|
||||
expect(b2.error.code).toBe("idempotency_key_conflict");
|
||||
});
|
||||
|
||||
it("header name is case-insensitive (Fetch/Next Headers normalize casing)", async () => {
|
||||
const key = `idem_${crypto.randomUUID()}`;
|
||||
const r1 = await ordersPOST(postReq(BODY, { "idempotency-key": key }));
|
||||
const r2 = await ordersPOST(postReq(BODY, { "IDEMPOTENCY-KEY": key }));
|
||||
expect(r1.status).toBe(201);
|
||||
expect(r2.status).toBe(200);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,156 @@
|
||||
/**
|
||||
* C8: tests for POST /api/orders/import — the symmetric counterpart of the
|
||||
* våg-3.4 CSV export and the first real product host of the @siax/ui
|
||||
* ImportWizard kernel. Follows the suite pattern of calling the route handler
|
||||
* directly with a hand-built NextRequest and mocked auth/store/audit.
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
|
||||
const mockOwner = { owner: { tenantId: "tenant-test", subject: "buyer-test" } };
|
||||
const requireOrderOwnerMock = vi.fn();
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: (...args: unknown[]) => requireOrderOwnerMock(...args),
|
||||
}));
|
||||
|
||||
const createOrderMock = vi.fn();
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
createOrder: (...args: unknown[]) => createOrderMock(...args),
|
||||
}));
|
||||
|
||||
const ingestEventMock = vi.fn().mockResolvedValue({});
|
||||
vi.mock("@/src/clients/aud0-client", () => ({
|
||||
createAud0Client: () => ({ ingestEvent: ingestEventMock }),
|
||||
}));
|
||||
|
||||
import { POST, parseCsv, validateImport, MAX_IMPORT_ROWS } from "@/app/api/orders/import/route";
|
||||
|
||||
function postReq(body: unknown, withAuth = true): NextRequest {
|
||||
requireOrderOwnerMock.mockResolvedValue(withAuth ? mockOwner : { response: NextResponse.json({ error: "OPT_UNAUTHENTICATED" }, { status: 401 }) });
|
||||
return new NextRequest(new URL("/api/orders/import", "http://localhost"), {
|
||||
method: "POST",
|
||||
body: JSON.stringify(body),
|
||||
headers: withAuth ? { authorization: "Bearer x" } : {},
|
||||
});
|
||||
}
|
||||
|
||||
const HEADER = "flow,service_type,type,volume,frequency,markets";
|
||||
|
||||
function csv(lines: string[]): string {
|
||||
return [HEADER, ...lines].join("\r\n") + "\r\n";
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
createOrderMock.mockReset();
|
||||
ingestEventMock.mockClear();
|
||||
createOrderMock.mockImplementation(async (flow: string, config: unknown, _key: unknown, owner: { tenantId: string }) => ({
|
||||
order: { order_id: `ord_${createOrderMock.mock.calls.length}`, flow, status: "draft", config, tenant_id: owner.tenantId },
|
||||
replayed: false,
|
||||
}));
|
||||
});
|
||||
|
||||
describe("parseCsv (server-parsed, RFC 4180, no eval)", () => {
|
||||
it("parses quoted fields with doubled quotes", () => {
|
||||
const { rows } = parseCsv('flow,markets\r\ncustom,"A;""B,C"""\r\n');
|
||||
expect(rows[0].flow).toBe("custom");
|
||||
expect(rows[0].markets).toBe('A;"B,C"');
|
||||
});
|
||||
|
||||
it("rejects unknown header columns (fail-closed, never silently dropped)", () => {
|
||||
const { headerError } = parseCsv("flow,evil\r\ncustom,x\r\n");
|
||||
expect(headerError).toMatch(/Okänd kolumn: evil/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("validateImport — kernel + host rules", () => {
|
||||
it("reports missing required flow as missing_required", () => {
|
||||
const { report } = validateImport(csv([",icp,Bolag,10,Engångs,SE"]));
|
||||
expect(report.errorCount).toBeGreaterThan(0);
|
||||
expect(report.errors.some((e) => e.code === "missing_required")).toBe(true);
|
||||
});
|
||||
|
||||
it("reports bad host fields with row/field/code", () => {
|
||||
const { report } = validateImport(csv(["nope,icp,Bolag,-5,Engångs,SE"]));
|
||||
const fields = report.errors.map((e) => e.field).sort();
|
||||
expect(fields).toContain("flow");
|
||||
expect(fields).toContain("volume");
|
||||
});
|
||||
});
|
||||
|
||||
describe("POST /api/orders/import", () => {
|
||||
it("happy path: execute imports all valid rows through createOrder with the verified owner + emits AUD0", async () => {
|
||||
const r = await POST(postReq({ mode: "execute", csv: csv(["custom,icp,Bolag,10,Engångs,SE", "catalog,icp,Fordon,2,Engångs,", "subscription,,Beslutsfattare,50,Veckovis,SE;NO"]) }));
|
||||
expect(r.status).toBe(200);
|
||||
const body = await r.json();
|
||||
expect(body.imported).toBe(3);
|
||||
expect(body.errors).toHaveLength(0);
|
||||
expect(body.order_ids).toHaveLength(3);
|
||||
expect(createOrderMock).toHaveBeenCalledTimes(3);
|
||||
expect(createOrderMock.mock.calls[0][3]).toEqual({ tenantId: "tenant-test", subject: "buyer-test" });
|
||||
expect(createOrderMock.mock.calls[0][1]).toMatchObject({ service_type: "icp", type: "Bolag", volume: 10, frequency: "Engångs", markets: ["SE"] });
|
||||
expect(createOrderMock.mock.calls[2][1]).toMatchObject({ markets: ["SE", "NO"] });
|
||||
expect(ingestEventMock).toHaveBeenCalledTimes(1);
|
||||
expect(ingestEventMock.mock.calls[0][0]).toMatchObject({ event_type: "0pt.orders.import", tenant_id: "tenant-test", risk_level: "L2" });
|
||||
});
|
||||
|
||||
it("partial success: failing rows are reported per row and never created; passing rows import", async () => {
|
||||
const r = await POST(postReq({ mode: "execute", csv: csv(["custom,icp,Bolag,10,Engångs,SE", "bogus_flow,icp,Bolag,10,Engångs,SE", "catalog,icp,Bolag,notanumber,Engångs,SE"]) }));
|
||||
expect(r.status).toBe(200);
|
||||
const body = await r.json();
|
||||
expect(body.imported).toBe(1);
|
||||
expect(body.errorCount).toBe(2);
|
||||
const badFlow = body.errors.find((e: { field: string }) => e.field === "flow");
|
||||
const badVol = body.errors.find((e: { field: string }) => e.field === "volume");
|
||||
expect(badFlow.row).toBe(2);
|
||||
expect(badVol.row).toBe(3);
|
||||
expect(createOrderMock).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("validate/dry_run never write (createOrder not called)", async () => {
|
||||
const r1 = await POST(postReq({ mode: "validate", csv: csv(["custom,icp,Bolag,10,Engångs,SE"]) }));
|
||||
expect(r1.status).toBe(200);
|
||||
const b1 = await r1.json();
|
||||
expect(b1.validRows).toBe(1);
|
||||
expect(b1.would_import).toBe(1);
|
||||
const r2 = await POST(postReq({ mode: "dry_run", csv: csv(["custom,icp,Bolag,10,Engångs,SE"]) }));
|
||||
expect(r2.status).toBe(200);
|
||||
expect(createOrderMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fail-closed auth: no principal → 401 and createOrder is never reached", async () => {
|
||||
const r = await POST(postReq({ mode: "execute", csv: csv(["custom,icp,Bolag,10,Engångs,SE"]) }, false));
|
||||
expect(r.status).toBe(401);
|
||||
expect(createOrderMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("row cap: more than MAX_IMPORT_ROWS data rows → 413, no writes", async () => {
|
||||
const lines = Array.from({ length: MAX_IMPORT_ROWS + 1 }, () => "custom,icp,Bolag,10,Engångs,SE");
|
||||
const r = await POST(postReq({ mode: "execute", csv: csv(lines) }));
|
||||
expect(r.status).toBe(413);
|
||||
expect(createOrderMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("unknown header → 400 fail-closed", async () => {
|
||||
const r = await POST(postReq({ mode: "execute", csv: "flow,evil\r\ncustom,x\r\n" }));
|
||||
expect(r.status).toBe(400);
|
||||
const body = await r.json();
|
||||
expect(body.error.code).toBe("bad_header");
|
||||
});
|
||||
|
||||
it("empty/missing csv → 400", async () => {
|
||||
const r = await POST(postReq({ mode: "execute", csv: " " }));
|
||||
expect(r.status).toBe(400);
|
||||
});
|
||||
|
||||
it("execute-time creation failure is reported per row without aborting the batch", async () => {
|
||||
createOrderMock.mockImplementationOnce(async () => {
|
||||
throw new Error("db down");
|
||||
});
|
||||
const r = await POST(postReq({ mode: "execute", csv: csv(["custom,icp,Bolag,10,Engångs,SE", "catalog,icp,Bolag,1,Engångs,SE"]) }));
|
||||
expect(r.status).toBe(200);
|
||||
const body = await r.json();
|
||||
expect(body.imported).toBe(1);
|
||||
expect(body.errors[0].row).toBe(1);
|
||||
expect(body.errors[0].message).toContain("db down");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,34 @@
|
||||
/**
|
||||
* Route-level test for GET /api/ready (BACKLOG P0-3: "no /ready route
|
||||
* existed at all"). Unlike /api/health, readiness fails closed: 503 when the
|
||||
* load-bearing dependency (db) is not both configured and reachable.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from "vitest";
|
||||
import { GET as readyGET } from "@/app/api/ready/route";
|
||||
|
||||
describe("GET /api/ready", () => {
|
||||
const savedEnv = {
|
||||
DATABASE_URL: process.env.DATABASE_URL,
|
||||
POSTGRES_URL: process.env.POSTGRES_URL,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
delete process.env.DATABASE_URL;
|
||||
delete process.env.POSTGRES_URL;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
for (const [k, v] of Object.entries(savedEnv)) {
|
||||
if (v === undefined) delete process.env[k];
|
||||
else process.env[k] = v;
|
||||
}
|
||||
});
|
||||
|
||||
it("fails closed with 503 when the database is not configured", async () => {
|
||||
const res = await readyGET();
|
||||
expect(res.status).toBe(503);
|
||||
const body = await res.json();
|
||||
expect(body.ready).toBe(false);
|
||||
expect(body.db).toBe("not_configured");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,42 @@
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { GET as screen } from '@/app/api/screen/route';
|
||||
import { GET as vehicles } from '@/app/api/vehicles/route';
|
||||
|
||||
const originalEngine = process.env.ENGINE_URL;
|
||||
afterEach(() => { if (originalEngine === undefined) delete process.env.ENGINE_URL; else process.env.ENGINE_URL = originalEngine; vi.unstubAllGlobals(); });
|
||||
const screening = () => screen(new NextRequest('http://localhost/api/screen?q=example'));
|
||||
const vehicle = () => vehicles(new NextRequest('http://localhost/api/vehicles?plate=AB123'));
|
||||
|
||||
describe('source failure cannot mean absence', () => {
|
||||
it.each([screening, vehicle])('returns 503 for source failures and malformed responses', async (call) => {
|
||||
delete process.env.ENGINE_URL;
|
||||
for (const response of [new Response('down', { status: 503 }), Response.json({}), new Response('{')]) {
|
||||
vi.stubGlobal('fetch', vi.fn(async () => response));
|
||||
const result = await call();
|
||||
expect(result.status).toBe(503);
|
||||
expect(await result.json()).toEqual({ error: expect.objectContaining({ code: 'source_unavailable' }) });
|
||||
}
|
||||
});
|
||||
it('preserves an actual empty screening result', async () => {
|
||||
delete process.env.ENGINE_URL;
|
||||
vi.stubGlobal('fetch', vi.fn(async () => Response.json({ results: [] })));
|
||||
expect(await (await screening()).json()).toEqual({ source: 'opensanctions', matches: [] });
|
||||
});
|
||||
it('preserves an actual missing vehicle', async () => {
|
||||
delete process.env.ENGINE_URL;
|
||||
vi.stubGlobal('fetch', vi.fn(async () => Response.json([])));
|
||||
expect(await (await vehicle()).json()).toEqual({ vehicle: null });
|
||||
});
|
||||
it.each([screening, vehicle])('does not trust an old engine which can fabricate empty results', async (call) => {
|
||||
process.env.ENGINE_URL = 'https://engine.test';
|
||||
vi.stubGlobal('fetch', vi.fn(async () => Response.json({ matches: [], vehicle: null })));
|
||||
expect((await call()).status).toBe(503);
|
||||
expect(fetch).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('accepts verified engine screening results', async () => {
|
||||
process.env.ENGINE_URL = 'https://engine.test';
|
||||
vi.stubGlobal('fetch', vi.fn(async () => Response.json({ source: 'opensanctions', source_status: 'ok', matches: [] })));
|
||||
expect((await screening()).status).toBe(200);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
import { expect, it, vi } from "vitest";
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
|
||||
const mocks = vi.hoisted(() => ({ create: vi.fn(), setStatus: vi.fn(), auth: vi.fn() }));
|
||||
vi.mock("@/lib/stripe", () => ({
|
||||
getStripe: () => ({ checkout: { sessions: { create: mocks.create } } }),
|
||||
}));
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
getOwnedOrder: vi.fn().mockResolvedValue({ order_id: "order-1", status: "accepted", balance_ore: 5000 }),
|
||||
setStatus: mocks.setStatus,
|
||||
}));
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: mocks.auth,
|
||||
}));
|
||||
|
||||
import { POST } from "@/app/api/payments/[order_id]/release/route";
|
||||
import { getOwnedOrder } from "@/lib/orders-store";
|
||||
|
||||
it("does not mark delivery complete merely by creating a balance Checkout Session", async () => {
|
||||
mocks.auth.mockResolvedValue({ owner: { tenantId: "verified-tenant", subject: "buyer-1" } });
|
||||
mocks.create.mockResolvedValue({ url: "https://checkout.stripe.com/test" });
|
||||
const req = new NextRequest("https://0pt.app/api/payments/order-1/release", { method: "POST" });
|
||||
|
||||
const res = await POST(req, { params: Promise.resolve({ order_id: "order-1" }) });
|
||||
expect(res.status).toBe(200);
|
||||
expect(getOwnedOrder).toHaveBeenCalledWith("order-1", "verified-tenant");
|
||||
expect(mocks.create).toHaveBeenCalledWith(expect.objectContaining({
|
||||
metadata: { order_id: "order-1", kind: "balance" },
|
||||
}));
|
||||
expect(mocks.setStatus).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("rejects an unauthenticated balance Checkout request", async () => {
|
||||
mocks.create.mockClear();
|
||||
mocks.auth.mockResolvedValue({ response: NextResponse.json({ error: "unauthenticated" }, { status: 401 }) });
|
||||
const req = new NextRequest("https://0pt.app/api/payments/order-1/release", { method: "POST" });
|
||||
|
||||
expect((await POST(req, { params: Promise.resolve({ order_id: "order-1" }) })).status).toBe(401);
|
||||
expect(mocks.create).not.toHaveBeenCalled();
|
||||
});
|
||||
@@ -0,0 +1,39 @@
|
||||
import { afterEach, expect, it, vi } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
getOwnedOrder: vi.fn().mockResolvedValue({ order_id: "order-1", deposit_ore: 5000 }),
|
||||
}));
|
||||
vi.mock("@/src/auth/require-order-owner", () => ({
|
||||
requireOrderOwner: vi.fn().mockResolvedValue({ owner: { tenantId: "tenant-test", subject: "buyer-test" } }),
|
||||
}));
|
||||
|
||||
import { POST } from "@/app/api/payments/[order_id]/deposit/route";
|
||||
import { getOwnedOrder } from "@/lib/orders-store";
|
||||
|
||||
const savedKey = process.env.STRIPE_SECRET_KEY;
|
||||
const savedFetch = globalThis.fetch;
|
||||
|
||||
afterEach(() => {
|
||||
if (savedKey === undefined) delete process.env.STRIPE_SECRET_KEY;
|
||||
else process.env.STRIPE_SECRET_KEY = savedKey;
|
||||
globalThis.fetch = savedFetch;
|
||||
});
|
||||
|
||||
it("binds a deposit Checkout Session to its order and payment kind", async () => {
|
||||
process.env.STRIPE_SECRET_KEY = "sk_test_fake_local_regression";
|
||||
const mockFetch = vi.fn().mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ url: "https://checkout.stripe.com/test" }),
|
||||
});
|
||||
globalThis.fetch = mockFetch;
|
||||
|
||||
const req = new NextRequest("https://0pt.app/api/payments/order-1/deposit", { method: "POST" });
|
||||
const res = await POST(req, { params: Promise.resolve({ order_id: "order-1" }) });
|
||||
expect(res.status).toBe(200);
|
||||
expect(getOwnedOrder).toHaveBeenCalledWith("order-1", "tenant-test");
|
||||
const init = mockFetch.mock.calls[0]?.[1] as RequestInit;
|
||||
const body = init.body as URLSearchParams;
|
||||
expect(body.get("metadata[order_id]")).toBe("order-1");
|
||||
expect(body.get("metadata[kind]")).toBe("deposit");
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
import { afterEach, expect, it } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { POST } from "@/app/api/webhooks/stripe/route";
|
||||
|
||||
const savedSecretKey = process.env.STRIPE_SECRET_KEY;
|
||||
const savedWebhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
|
||||
|
||||
afterEach(() => {
|
||||
if (savedSecretKey === undefined) delete process.env.STRIPE_SECRET_KEY;
|
||||
else process.env.STRIPE_SECRET_KEY = savedSecretKey;
|
||||
if (savedWebhookSecret === undefined) delete process.env.STRIPE_WEBHOOK_SECRET;
|
||||
else process.env.STRIPE_WEBHOOK_SECRET = savedWebhookSecret;
|
||||
});
|
||||
|
||||
it("does not acknowledge an unverified Stripe event when credentials are absent", async () => {
|
||||
delete process.env.STRIPE_SECRET_KEY;
|
||||
delete process.env.STRIPE_WEBHOOK_SECRET;
|
||||
const req = new NextRequest("https://0pt.app/api/webhooks/stripe", {
|
||||
method: "POST",
|
||||
headers: { "stripe-signature": "unverified" },
|
||||
body: "{}",
|
||||
});
|
||||
|
||||
const res = await POST(req);
|
||||
expect(res.status).toBe(503);
|
||||
expect(await res.json()).toEqual({ received: false, reason: "not_configured" });
|
||||
});
|
||||
|
||||
it("rejects a delivery with no Stripe signature even when configured", async () => {
|
||||
process.env.STRIPE_SECRET_KEY = "sk_test_fake_local_regression";
|
||||
process.env.STRIPE_WEBHOOK_SECRET = "whsec_fake_local_regression";
|
||||
const req = new NextRequest("https://0pt.app/api/webhooks/stripe", {
|
||||
method: "POST",
|
||||
body: "{}",
|
||||
});
|
||||
|
||||
const res = await POST(req);
|
||||
expect(res.status).toBe(400);
|
||||
expect(await res.json()).toEqual({ error: "missing_signature" });
|
||||
});
|
||||
@@ -0,0 +1,86 @@
|
||||
import { afterEach, beforeEach, expect, it, vi } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
constructEvent: vi.fn(),
|
||||
getOrder: vi.fn(),
|
||||
setStatusIfCurrent: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/stripe", () => ({
|
||||
getStripe: () => ({ webhooks: { constructEvent: mocks.constructEvent } }),
|
||||
}));
|
||||
vi.mock("@/lib/orders-store", () => ({
|
||||
getOrder: mocks.getOrder,
|
||||
setStatusIfCurrent: mocks.setStatusIfCurrent,
|
||||
}));
|
||||
|
||||
import { POST } from "@/app/api/webhooks/stripe/route";
|
||||
|
||||
const savedWebhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
|
||||
const owner = { tenant_id: "tenant-test", buyer_subject: "buyer-test" };
|
||||
|
||||
beforeEach(() => {
|
||||
process.env.STRIPE_WEBHOOK_SECRET = "whsec_fake_local_regression";
|
||||
mocks.constructEvent.mockReset();
|
||||
mocks.getOrder.mockReset();
|
||||
mocks.setStatusIfCurrent.mockReset();
|
||||
mocks.setStatusIfCurrent.mockResolvedValue({ order_id: "order-1" });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (savedWebhookSecret === undefined) delete process.env.STRIPE_WEBHOOK_SECRET;
|
||||
else process.env.STRIPE_WEBHOOK_SECRET = savedWebhookSecret;
|
||||
});
|
||||
|
||||
function delivery() {
|
||||
return new NextRequest("https://0pt.app/api/webhooks/stripe", {
|
||||
method: "POST",
|
||||
headers: { "stripe-signature": "signed-in-test" },
|
||||
body: "{}",
|
||||
});
|
||||
}
|
||||
|
||||
function session(kind: "deposit" | "balance", paymentStatus: string, amount: number) {
|
||||
mocks.constructEvent.mockReturnValue({
|
||||
type: "checkout.session.completed",
|
||||
data: { object: {
|
||||
metadata: { order_id: "order-1", kind },
|
||||
payment_status: paymentStatus,
|
||||
amount_total: amount,
|
||||
currency: "sek",
|
||||
} },
|
||||
});
|
||||
}
|
||||
|
||||
it("advances a matching paid deposit only after a verified event", async () => {
|
||||
session("deposit", "paid", 5000);
|
||||
mocks.getOrder.mockResolvedValue({ order_id: "order-1", ...owner, status: "draft", deposit_ore: 5000, balance_ore: 5000 });
|
||||
|
||||
expect((await POST(delivery())).status).toBe(200);
|
||||
expect(mocks.setStatusIfCurrent).toHaveBeenCalledWith("order-1", "draft", "in_production");
|
||||
});
|
||||
|
||||
it("never advances an unpaid or amount-mismatched deposit", async () => {
|
||||
mocks.getOrder.mockResolvedValue({ order_id: "order-1", ...owner, status: "draft", deposit_ore: 5000, balance_ore: 5000 });
|
||||
session("deposit", "unpaid", 5000);
|
||||
expect((await POST(delivery())).status).toBe(503);
|
||||
session("deposit", "paid", 4999);
|
||||
expect((await POST(delivery())).status).toBe(422);
|
||||
expect(mocks.setStatusIfCurrent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("marks a matching paid balance delivered only after acceptance", async () => {
|
||||
session("balance", "paid", 5000);
|
||||
mocks.getOrder.mockResolvedValue({ order_id: "order-1", ...owner, status: "accepted", deposit_ore: 5000, balance_ore: 5000 });
|
||||
|
||||
expect((await POST(delivery())).status).toBe(200);
|
||||
expect(mocks.setStatusIfCurrent).toHaveBeenCalledWith("order-1", "accepted", "delivered");
|
||||
});
|
||||
|
||||
it("does not acknowledge a paid event for a legacy anonymous draft", async () => {
|
||||
session("deposit", "paid", 5000);
|
||||
mocks.getOrder.mockResolvedValue({ order_id: "order-1", status: "draft", deposit_ore: 5000 });
|
||||
expect((await POST(delivery())).status).toBe(503);
|
||||
expect(mocks.setStatusIfCurrent).not.toHaveBeenCalled();
|
||||
});
|
||||
@@ -0,0 +1,214 @@
|
||||
/**
|
||||
* Unit tests for src/auth/context.ts -- the auth seam. Verification is
|
||||
* injected (opts.verify) so these tests are pure and network-free.
|
||||
*
|
||||
* Three groups:
|
||||
* 1. the ENV DEFAULT (the fail-closed contract: absent AUTH_ENFORCE means
|
||||
* an unauthenticated request is REJECTED, and production refuses to run
|
||||
* with auth switched off),
|
||||
* 2. enforced-mode decision logic,
|
||||
* 3. the explicit `AUTH_ENFORCE=false` local-development escape hatch.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import {
|
||||
resolveAuthContext,
|
||||
authEnforced,
|
||||
assertAuthConfigSafe,
|
||||
AuthMisconfigurationError,
|
||||
AUTH_ENFORCE_VAR,
|
||||
type OptRequestContext,
|
||||
} from '@/src/auth/context';
|
||||
import type { VerifiedPrincipal } from '@/src/auth/zitadel';
|
||||
|
||||
const principal: VerifiedPrincipal = {
|
||||
sub: 'user_1',
|
||||
tenantId: 'tenant_x',
|
||||
claims: { sub: 'user_1', iss: 'https://id-customers.siax.io' },
|
||||
};
|
||||
|
||||
const okVerify = vi.fn(async () => principal);
|
||||
const failVerify = vi.fn(async () => {
|
||||
throw new Error('token_verification_failed');
|
||||
});
|
||||
|
||||
function h(init: Record<string, string>): Headers {
|
||||
return new Headers(init);
|
||||
}
|
||||
|
||||
describe('auth default -- fail-closed (no AUTH_ENFORCE in the environment)', () => {
|
||||
const saved = { auth: process.env.AUTH_ENFORCE, node: process.env.NODE_ENV };
|
||||
|
||||
beforeEach(() => {
|
||||
delete process.env.AUTH_ENFORCE;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (saved.auth === undefined) delete process.env.AUTH_ENFORCE;
|
||||
else process.env.AUTH_ENFORCE = saved.auth;
|
||||
if (saved.node === undefined) delete process.env.NODE_ENV;
|
||||
else process.env.NODE_ENV = saved.node;
|
||||
});
|
||||
|
||||
it('REGRESSION: with the variable unset, an unauthenticated request is REJECTED (401)', async () => {
|
||||
// No `enforce` option -> the decision comes from the environment, which is
|
||||
// exactly the fresh-container / DR-restore / dropped-env-var case.
|
||||
const d = await resolveAuthContext(h({ 'x-tenant-id': 'tenant_attacker' }), { verify: okVerify });
|
||||
expect(d.ok).toBe(false);
|
||||
if (!d.ok) {
|
||||
expect(d.status).toBe(401);
|
||||
expect(d.code).toBe('OPT_UNAUTHENTICATED');
|
||||
}
|
||||
});
|
||||
|
||||
it('with the variable unset, an invalid token is REJECTED (401) rather than ignored', async () => {
|
||||
const d = await resolveAuthContext(h({ authorization: 'Bearer bad.tok.en' }), { verify: failVerify });
|
||||
expect(d.ok).toBe(false);
|
||||
if (!d.ok) expect(d.status).toBe(401);
|
||||
});
|
||||
|
||||
it('authEnforced() is true when the variable is absent, empty, or misspelled', () => {
|
||||
expect(authEnforced({})).toBe(true);
|
||||
expect(authEnforced({ AUTH_ENFORCE: '' })).toBe(true);
|
||||
expect(authEnforced({ AUTH_ENFORCE: 'flase' })).toBe(true);
|
||||
expect(authEnforced({ AUTH_ENFORCE: '0' })).toBe(true);
|
||||
expect(authEnforced({ AUTH_ENFORCE: 'no' })).toBe(true);
|
||||
expect(authEnforced({ AUTH_ENFORCE: 'true' })).toBe(true);
|
||||
});
|
||||
|
||||
it('only the literal string "false" opts out', () => {
|
||||
expect(authEnforced({ AUTH_ENFORCE: 'false' })).toBe(false);
|
||||
expect(authEnforced({ AUTH_ENFORCE: 'FALSE' })).toBe(false);
|
||||
expect(authEnforced({ AUTH_ENFORCE: ' false ' })).toBe(false);
|
||||
});
|
||||
|
||||
it('assertAuthConfigSafe throws in production when enforcement is off, naming the variable', () => {
|
||||
expect(() => assertAuthConfigSafe({ NODE_ENV: 'production', AUTH_ENFORCE: 'false' })).toThrow(
|
||||
AuthMisconfigurationError,
|
||||
);
|
||||
expect(() => assertAuthConfigSafe({ NODE_ENV: 'production', AUTH_ENFORCE: 'false' })).toThrow(
|
||||
new RegExp(AUTH_ENFORCE_VAR),
|
||||
);
|
||||
});
|
||||
|
||||
it('assertAuthConfigSafe is silent when production enforces, or when off outside production', () => {
|
||||
expect(() => assertAuthConfigSafe({ NODE_ENV: 'production' })).not.toThrow();
|
||||
expect(() => assertAuthConfigSafe({ NODE_ENV: 'production', AUTH_ENFORCE: 'true' })).not.toThrow();
|
||||
expect(() => assertAuthConfigSafe({ NODE_ENV: 'development', AUTH_ENFORCE: 'false' })).not.toThrow();
|
||||
});
|
||||
|
||||
it('a production process with AUTH_ENFORCE=false cannot serve a request at all (throws)', async () => {
|
||||
process.env.NODE_ENV = 'production';
|
||||
process.env.AUTH_ENFORCE = 'false';
|
||||
await expect(
|
||||
resolveAuthContext(h({ 'x-tenant-id': 'tenant_attacker' }), { verify: okVerify }),
|
||||
).rejects.toBeInstanceOf(AuthMisconfigurationError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('resolveAuthContext -- enforced mode (the default)', () => {
|
||||
it('401s when no bearer token is present', async () => {
|
||||
const d = await resolveAuthContext(h({ 'x-tenant-id': 'tenant_x' }), { enforce: true, verify: okVerify });
|
||||
expect(d.ok).toBe(false);
|
||||
if (!d.ok) {
|
||||
expect(d.status).toBe(401);
|
||||
expect(d.code).toBe('OPT_UNAUTHENTICATED');
|
||||
}
|
||||
});
|
||||
|
||||
it('401s when the token fails verification', async () => {
|
||||
const d = await resolveAuthContext(h({ authorization: 'Bearer bad.tok.en' }), {
|
||||
enforce: true,
|
||||
verify: failVerify,
|
||||
});
|
||||
expect(d.ok).toBe(false);
|
||||
if (!d.ok) expect(d.status).toBe(401);
|
||||
});
|
||||
|
||||
it('attaches the verified principal and derives tenant from the TOKEN', async () => {
|
||||
const d = await resolveAuthContext(h({ authorization: 'Bearer good.tok.en' }), {
|
||||
enforce: true,
|
||||
verify: okVerify,
|
||||
});
|
||||
expect(d.ok).toBe(true);
|
||||
if (d.ok) {
|
||||
expect(d.ctx.principal).toEqual(principal);
|
||||
expect(d.ctx.tenantId).toBe('tenant_x');
|
||||
expect(d.ctx.actorId).toBe('user_1');
|
||||
}
|
||||
});
|
||||
|
||||
it('403s when X-Tenant-Id disagrees with the token tenant', async () => {
|
||||
const d = await resolveAuthContext(
|
||||
h({ authorization: 'Bearer good.tok.en', 'x-tenant-id': 'tenant_evil' }),
|
||||
{ enforce: true, verify: okVerify },
|
||||
);
|
||||
expect(d.ok).toBe(false);
|
||||
if (!d.ok) {
|
||||
expect(d.status).toBe(403);
|
||||
expect(d.code).toBe('OPT_ACCESS_DENIED');
|
||||
expect(d.details).toMatchObject({ header_tenant: 'tenant_evil', token_tenant: 'tenant_x' });
|
||||
}
|
||||
});
|
||||
|
||||
it('rejects a forged actor header and accepts only the verified subject', async () => {
|
||||
const forged = await resolveAuthContext(
|
||||
h({ authorization: 'Bearer good.tok.en', 'x-actor-id': 'user_other' }),
|
||||
{ enforce: true, verify: okVerify },
|
||||
);
|
||||
expect(forged).toMatchObject({ ok: false, status: 403, code: 'OPT_ACCESS_DENIED' });
|
||||
const matching = await resolveAuthContext(
|
||||
h({ authorization: 'Bearer good.tok.en', 'x-actor-id': 'user_1' }),
|
||||
{ enforce: true, verify: okVerify },
|
||||
);
|
||||
expect(matching.ok).toBe(true);
|
||||
if (matching.ok) expect(matching.ctx.actorId).toBe('user_1');
|
||||
});
|
||||
|
||||
it('allows a matching X-Tenant-Id', async () => {
|
||||
const d = await resolveAuthContext(
|
||||
h({ authorization: 'Bearer good.tok.en', 'x-tenant-id': 'tenant_x' }),
|
||||
{ enforce: true, verify: okVerify },
|
||||
);
|
||||
expect(d.ok).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('resolveAuthContext -- explicit AUTH_ENFORCE=false escape hatch (local dev only)', () => {
|
||||
it('never rejects when no token is present', async () => {
|
||||
const d = await resolveAuthContext(h({ 'x-tenant-id': 'tenant_header' }), {
|
||||
enforce: false,
|
||||
verify: okVerify,
|
||||
});
|
||||
expect(d.ok).toBe(true);
|
||||
if (d.ok) {
|
||||
expect((d.ctx as OptRequestContext).principal).toBeUndefined();
|
||||
expect(d.ctx.tenantId).toBe('tenant_header');
|
||||
}
|
||||
});
|
||||
|
||||
it('never rejects even when a present token fails verification (logs a warning)', async () => {
|
||||
const logger = { warn: vi.fn() };
|
||||
const d = await resolveAuthContext(h({ authorization: 'Bearer bad.tok.en' }), {
|
||||
enforce: false,
|
||||
verify: failVerify,
|
||||
logger,
|
||||
});
|
||||
expect(d.ok).toBe(true);
|
||||
if (d.ok) expect(d.ctx.principal).toBeUndefined();
|
||||
expect(logger.warn).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it('attaches the principal when a present token verifies, without overriding a supplied tenant', async () => {
|
||||
const d = await resolveAuthContext(
|
||||
h({ authorization: 'Bearer good.tok.en', 'x-tenant-id': 'tenant_header' }),
|
||||
{ enforce: false, verify: okVerify },
|
||||
);
|
||||
expect(d.ok).toBe(true);
|
||||
if (d.ok) {
|
||||
expect(d.ctx.principal).toEqual(principal);
|
||||
// the caller-supplied header tenant is preserved in this mode
|
||||
expect(d.ctx.tenantId).toBe('tenant_header');
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,262 @@
|
||||
/**
|
||||
* P0 regression (2026-11-07): tenant authority for the machine-to-machine
|
||||
* (`X-Internal-Token`) principal is SERVER CONFIGURATION, never a client
|
||||
* header.
|
||||
*
|
||||
* The first attempt at this fix read `X-0pt-Internal-Tenant` (or a single
|
||||
* `INTERNAL_TENANT_ID`) and copied it into `x-0pt-verified-tenant`. Any holder
|
||||
* of the shared internal token could then still name any tenant, so the
|
||||
* original cross-tenant write (tenant_id 999999999999999999 -> 201) remained
|
||||
* possible through a different header. These tests pin the corrected model:
|
||||
*
|
||||
* - `INTERNAL_SERVICE_TENANTS` (server env) is the only source of tenant
|
||||
* authority for the service principal.
|
||||
* - No configured scope => tenant-scoped writes are denied (fail closed).
|
||||
* - Client-supplied `x-0pt-internal-tenant`, `x-0pt-verified-tenant` and
|
||||
* `x-0pt-verified-service-tenants` are ignored and stripped.
|
||||
* - Bearer/session principals are unchanged.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { middleware } from '../../middleware';
|
||||
import {
|
||||
parseServiceTenants,
|
||||
resolveInternalServiceTenants,
|
||||
SERVICE_TENANT_SCOPE_HEADER,
|
||||
} from '@/src/auth/internal-service-tenant';
|
||||
import { assertTenantMatchesVerified } from '@/src/http/tenant-guard';
|
||||
import { POST as canonicalPOST } from '@/app/api/0pt/canonical/facts/route';
|
||||
import { POST as bridgePOST } from '@/app/api/0pt/quality/bridge-run/route';
|
||||
import { POST as evidenceDispatchPOST } from '@/app/api/0pt/internal/evidence-outbox/dispatch/route';
|
||||
|
||||
const INTERNAL_TOKEN = 'engine-shared-secret';
|
||||
const SCOPED_ROUTE = '/api/0pt/canonical/facts';
|
||||
|
||||
function req(path: string, headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest(new URL(path, 'http://localhost'), { headers });
|
||||
}
|
||||
|
||||
/** Headers middleware forwarded to the route handler (Next stores them here). */
|
||||
function forwarded(res: { headers: { get(name: string): string | null } }, name: string): string | null {
|
||||
return res.headers.get(`x-middleware-request-${name.toLowerCase()}`);
|
||||
}
|
||||
|
||||
function guardRequest(headers: Record<string, string>): NextRequest {
|
||||
return new NextRequest(new URL(SCOPED_ROUTE, 'http://localhost'), {
|
||||
method: 'POST',
|
||||
headers: { 'content-type': 'application/json', ...headers },
|
||||
});
|
||||
}
|
||||
|
||||
describe('parseServiceTenants / resolveInternalServiceTenants', () => {
|
||||
it('splits, trims and de-duplicates the allowlist', () => {
|
||||
expect(parseServiceTenants(' t_a , t_b ,, t_a ')).toEqual(['t_a', 't_b']);
|
||||
});
|
||||
|
||||
it('an unset/empty allowlist means no tenant authority', () => {
|
||||
expect(parseServiceTenants(undefined)).toEqual([]);
|
||||
expect(parseServiceTenants('')).toEqual([]);
|
||||
expect(resolveInternalServiceTenants({})).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('middleware: internal-token tenant authority comes from server config', () => {
|
||||
const saved = {
|
||||
auth: process.env.AUTH_ENFORCE,
|
||||
token: process.env.INTERNAL_TOKEN,
|
||||
tenants: process.env.INTERNAL_SERVICE_TENANTS,
|
||||
node: process.env.NODE_ENV,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
delete process.env.AUTH_ENFORCE; // default posture: enforced
|
||||
process.env.INTERNAL_TOKEN = INTERNAL_TOKEN;
|
||||
delete process.env.INTERNAL_SERVICE_TENANTS;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
const values: Record<string, string | undefined> = {
|
||||
AUTH_ENFORCE: saved.auth,
|
||||
INTERNAL_TOKEN: saved.token,
|
||||
INTERNAL_SERVICE_TENANTS: saved.tenants,
|
||||
NODE_ENV: saved.node,
|
||||
};
|
||||
for (const [key, value] of Object.entries(values)) {
|
||||
if (value === undefined) delete process.env[key];
|
||||
else process.env[key] = value;
|
||||
}
|
||||
});
|
||||
|
||||
it('single allowlisted tenant is installed as the verified tenant', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = 't_a';
|
||||
const res = await middleware(req(SCOPED_ROUTE, { 'x-internal-token': INTERNAL_TOKEN }));
|
||||
expect(res.status).toBe(200);
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBe('t_a');
|
||||
expect(forwarded(res, SERVICE_TENANT_SCOPE_HEADER)).toBe('t_a');
|
||||
});
|
||||
|
||||
it('REFUSES an ambiguous multi-tenant allowlist (no workload-identity binding yet)', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = 't_a,t_b';
|
||||
const res = await middleware(req(SCOPED_ROUTE, { 'x-internal-token': INTERNAL_TOKEN }));
|
||||
expect(res.status).toBe(401);
|
||||
const body = await res.json();
|
||||
expect(body.message).toContain('ambiguous');
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBeNull();
|
||||
expect(forwarded(res, SERVICE_TENANT_SCOPE_HEADER)).toBeNull();
|
||||
});
|
||||
|
||||
it('a single allowlist entry is still forwarded as the service scope', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = 't_a';
|
||||
const res = await middleware(req(SCOPED_ROUTE, { 'x-internal-token': INTERNAL_TOKEN }));
|
||||
expect(res.status).toBe(200);
|
||||
expect(forwarded(res, SERVICE_TENANT_SCOPE_HEADER)).toBe('t_a');
|
||||
});
|
||||
|
||||
it('with no configured scope the service principal has no tenant authority (empty scope header)', async () => {
|
||||
const res = await middleware(req(SCOPED_ROUTE, { 'x-internal-token': INTERNAL_TOKEN }));
|
||||
expect(res.status).toBe(200);
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBeNull();
|
||||
expect(forwarded(res, SERVICE_TENANT_SCOPE_HEADER)).toBe('');
|
||||
});
|
||||
|
||||
it('IGNORES a client-supplied X-0pt-Internal-Tenant (not an authority source)', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = 't_a';
|
||||
const res = await middleware(
|
||||
req(SCOPED_ROUTE, {
|
||||
'x-internal-token': INTERNAL_TOKEN,
|
||||
'x-0pt-internal-tenant': 't_victim',
|
||||
}),
|
||||
);
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBe('t_a');
|
||||
});
|
||||
|
||||
it('STRIPS a forged x-0pt-verified-tenant and forged scope header', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = 't_a';
|
||||
const res = await middleware(
|
||||
req(SCOPED_ROUTE, {
|
||||
'x-internal-token': INTERNAL_TOKEN,
|
||||
'x-0pt-verified-tenant': 't_victim',
|
||||
'x-0pt-verified-sub': 'user_victim',
|
||||
'x-0pt-verified-service-tenants': 't_victim',
|
||||
}),
|
||||
);
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBe('t_a');
|
||||
expect(forwarded(res, 'x-0pt-verified-sub')).toBeNull();
|
||||
expect(forwarded(res, SERVICE_TENANT_SCOPE_HEADER)).toBe('t_a');
|
||||
});
|
||||
|
||||
it('strips forged verified headers on the unauthenticated development path too', async () => {
|
||||
process.env.AUTH_ENFORCE = 'false';
|
||||
const res = await middleware(req('/api/0pt/documents/capture', { 'x-0pt-verified-tenant': 't_victim' }));
|
||||
expect(forwarded(res, 'x-0pt-verified-tenant')).toBeNull();
|
||||
});
|
||||
|
||||
it('an invalid internal token still falls through to 401', async () => {
|
||||
const res = await middleware(req(SCOPED_ROUTE, { 'x-internal-token': 'wrong' }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
describe('assertTenantMatchesVerified: service scope is enforced fail-closed', () => {
|
||||
it('no service scope header behaves exactly as before (Bearer verified tenant)', () => {
|
||||
const same = assertTenantMatchesVerified(
|
||||
guardRequest({ 'x-0pt-verified-tenant': 't_a' }),
|
||||
't_a',
|
||||
);
|
||||
expect(same).toBeNull();
|
||||
const cross = assertTenantMatchesVerified(
|
||||
guardRequest({ 'x-0pt-verified-tenant': 't_a' }),
|
||||
't_victim',
|
||||
);
|
||||
expect(cross?.status).toBe(403);
|
||||
});
|
||||
|
||||
it('allows a tenant inside the configured service scope', () => {
|
||||
const res = assertTenantMatchesVerified(
|
||||
guardRequest({ [SERVICE_TENANT_SCOPE_HEADER]: 't_a,t_b' }),
|
||||
't_b',
|
||||
);
|
||||
expect(res).toBeNull();
|
||||
});
|
||||
|
||||
it('DENIES a tenant outside the configured service scope (403)', async () => {
|
||||
const res = assertTenantMatchesVerified(
|
||||
guardRequest({ [SERVICE_TENANT_SCOPE_HEADER]: 't_a' }),
|
||||
't_victim',
|
||||
);
|
||||
expect(res?.status).toBe(403);
|
||||
const body = await res!.json();
|
||||
expect(body.error).toBe('OPT_ACCESS_DENIED');
|
||||
expect(body.details.service_tenant_scope).toEqual(['t_a']);
|
||||
});
|
||||
|
||||
it('DENIES every tenant when the configured scope is empty (fail closed, even if a verified tenant was also set)', () => {
|
||||
const res = assertTenantMatchesVerified(
|
||||
guardRequest({
|
||||
[SERVICE_TENANT_SCOPE_HEADER]: '',
|
||||
'x-0pt-verified-tenant': '999999999999999999',
|
||||
}),
|
||||
'999999999999999999',
|
||||
);
|
||||
expect(res?.status).toBe(403);
|
||||
});
|
||||
});
|
||||
|
||||
describe('route handlers: internal service cannot write a foreign tenant', () => {
|
||||
it('canonical facts: cross-tenant write is 403 before the service runs', async () => {
|
||||
const res = await canonicalPOST(
|
||||
new NextRequest(new URL(SCOPED_ROUTE, 'http://localhost'), {
|
||||
method: 'POST',
|
||||
headers: { 'content-type': 'application/json', [SERVICE_TENANT_SCOPE_HEADER]: 't_a' },
|
||||
body: JSON.stringify({
|
||||
tenant_id: 't_victim',
|
||||
entities: [],
|
||||
facts: [],
|
||||
relations: [],
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it('quality bridge-run: cross-tenant run is 403 before rules are provisioned', async () => {
|
||||
const res = await bridgePOST(
|
||||
new NextRequest(new URL('/api/0pt/quality/bridge-run', 'http://localhost'), {
|
||||
method: 'POST',
|
||||
headers: { 'content-type': 'application/json', [SERVICE_TENANT_SCOPE_HEADER]: 't_a' },
|
||||
body: JSON.stringify({
|
||||
tenant_id: 't_victim',
|
||||
project_id: 'p1',
|
||||
dataset_id: 'ds_1',
|
||||
rows: [],
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
});
|
||||
|
||||
it('evidence-outbox dispatch needs no tenant and is unchanged by the scope', async () => {
|
||||
// No DB in this test env: the route authenticates first, then reports a
|
||||
// dependency error -- anything except 401/403 proves the scope did not
|
||||
// turn a tenant-less machine route into a denial.
|
||||
const previous = process.env.INTERNAL_TOKEN;
|
||||
process.env.INTERNAL_TOKEN = INTERNAL_TOKEN;
|
||||
try {
|
||||
const res = await evidenceDispatchPOST(
|
||||
new NextRequest(new URL('/api/0pt/internal/evidence-outbox/dispatch', 'http://localhost'), {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'content-type': 'application/json',
|
||||
'x-internal-token': INTERNAL_TOKEN,
|
||||
[SERVICE_TENANT_SCOPE_HEADER]: '',
|
||||
},
|
||||
body: JSON.stringify({ limit: 1 }),
|
||||
}),
|
||||
);
|
||||
expect([401, 403]).not.toContain(res.status);
|
||||
} finally {
|
||||
if (previous === undefined) delete process.env.INTERNAL_TOKEN;
|
||||
else process.env.INTERNAL_TOKEN = previous;
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,53 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { verifyInternalServiceToken, INTERNAL_TOKEN_HEADER } from "@/src/auth/internal-token";
|
||||
|
||||
function headers(map: Record<string, string> = {}): { get(name: string): string | null } {
|
||||
const lower = new Map(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
|
||||
return { get: (name: string) => lower.get(name.toLowerCase()) ?? null };
|
||||
}
|
||||
|
||||
describe("verifyInternalServiceToken", () => {
|
||||
it("accepts a header that matches the configured INTERNAL_TOKEN exactly", () => {
|
||||
const ok = verifyInternalServiceToken(headers({ [INTERNAL_TOKEN_HEADER]: "s3cr3t" }), {
|
||||
INTERNAL_TOKEN: "s3cr3t",
|
||||
});
|
||||
expect(ok).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects a mismatched token", () => {
|
||||
const ok = verifyInternalServiceToken(headers({ [INTERNAL_TOKEN_HEADER]: "wrong" }), {
|
||||
INTERNAL_TOKEN: "s3cr3t",
|
||||
});
|
||||
expect(ok).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects a missing header even when INTERNAL_TOKEN is configured", () => {
|
||||
const ok = verifyInternalServiceToken(headers({}), { INTERNAL_TOKEN: "s3cr3t" });
|
||||
expect(ok).toBe(false);
|
||||
});
|
||||
|
||||
it("FAILS CLOSED: an unset INTERNAL_TOKEN never authenticates, even against an empty header value", () => {
|
||||
// Regression guard: quality_bridge.py sends `os.getenv("INTERNAL_TOKEN", "")`
|
||||
// -- if the edge's own INTERNAL_TOKEN were also unset, a naive `provided
|
||||
// === expected` comparison of two empty strings would wrongly authenticate.
|
||||
const ok = verifyInternalServiceToken(headers({ [INTERNAL_TOKEN_HEADER]: "" }), { INTERNAL_TOKEN: undefined });
|
||||
expect(ok).toBe(false);
|
||||
});
|
||||
|
||||
it("FAILS CLOSED: an unset INTERNAL_TOKEN never authenticates even a non-empty header", () => {
|
||||
const ok = verifyInternalServiceToken(headers({ [INTERNAL_TOKEN_HEADER]: "anything" }), {
|
||||
INTERNAL_TOKEN: undefined,
|
||||
});
|
||||
expect(ok).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects a whitespace-only configured token (trimmed to empty)", () => {
|
||||
const ok = verifyInternalServiceToken(headers({ [INTERNAL_TOKEN_HEADER]: " " }), { INTERNAL_TOKEN: " " });
|
||||
expect(ok).toBe(false);
|
||||
});
|
||||
|
||||
it("is case-sensitive on the header name lookup contract but tolerant of header-name casing via the HeaderLookup adapter", () => {
|
||||
const ok = verifyInternalServiceToken(headers({ "X-Internal-Token": "s3cr3t" }), { INTERNAL_TOKEN: "s3cr3t" });
|
||||
expect(ok).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* P014 regression test: before this pass, POST /api/0pt/quality/bridge-run
|
||||
* -- the ONE route the Python engine's quality_bridge.py actually calls,
|
||||
* using X-Internal-Token, never a Bearer token -- was rejected 401 by
|
||||
* middleware.ts in any environment enforcing auth (the default), because
|
||||
* middleware required a verified Zitadel Bearer token unconditionally on
|
||||
* every /api/0pt/* path. See src/auth/internal-token.ts's doc comment for
|
||||
* the full story. Neither existing test suite caught it: the TS bridge test
|
||||
* calls the route's POST function directly (bypassing middleware.ts
|
||||
* entirely) and the Python test mocks the HTTP layer.
|
||||
*
|
||||
* This test exercises the actual `middleware` function, not the route
|
||||
* handler, so it proves the fix at the layer where the bug lived.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { middleware } from '../../middleware';
|
||||
|
||||
function req(path: string, headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest(new URL(path, 'http://localhost'), { headers });
|
||||
}
|
||||
|
||||
describe('middleware.ts: internal-token path for /api/0pt/quality/bridge-run', () => {
|
||||
const saved = { auth: process.env.AUTH_ENFORCE, internal: process.env.INTERNAL_TOKEN, node: process.env.NODE_ENV };
|
||||
|
||||
beforeEach(() => {
|
||||
delete process.env.AUTH_ENFORCE; // default posture: enforced
|
||||
process.env.INTERNAL_TOKEN = 'engine-shared-secret';
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
for (const [k, v] of Object.entries(saved)) {
|
||||
const envKey = k === 'auth' ? 'AUTH_ENFORCE' : k === 'internal' ? 'INTERNAL_TOKEN' : 'NODE_ENV';
|
||||
if (v === undefined) delete process.env[envKey];
|
||||
else process.env[envKey] = v;
|
||||
}
|
||||
});
|
||||
|
||||
it('REGRESSION: a valid X-Internal-Token lets the engine through with NO Bearer token (was: 401)', async () => {
|
||||
const res = await middleware(
|
||||
req('/api/0pt/quality/bridge-run', { 'x-internal-token': 'engine-shared-secret' }),
|
||||
);
|
||||
// NextResponse.next() carries no body/status override -- it is not an
|
||||
// error JSON response the way a rejection is.
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it('a valid X-Internal-Token lets the acquisition engine write canonical facts', async () => {
|
||||
const res = await middleware(
|
||||
req('/api/0pt/canonical/facts', { 'x-internal-token': 'engine-shared-secret' }),
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it('an invalid X-Internal-Token still falls through to the ordinary Bearer requirement (401, not a bypass)', async () => {
|
||||
const res = await middleware(req('/api/0pt/quality/bridge-run', { 'x-internal-token': 'wrong-secret' }));
|
||||
expect(res.status).toBe(401);
|
||||
const body = await res.json();
|
||||
expect(body.error).toBe('OPT_UNAUTHENTICATED');
|
||||
});
|
||||
|
||||
it('a valid X-Internal-Token on a DIFFERENT /api/0pt/* route does NOT bypass auth (not a blanket exemption)', async () => {
|
||||
const res = await middleware(req('/api/0pt/sources', { 'x-internal-token': 'engine-shared-secret' }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('no INTERNAL_TOKEN configured on the edge -- the internal-token path never activates, even with the right-looking header', async () => {
|
||||
delete process.env.INTERNAL_TOKEN;
|
||||
const res = await middleware(
|
||||
req('/api/0pt/quality/bridge-run', { 'x-internal-token': 'engine-shared-secret' }),
|
||||
);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('a real Bearer-authenticated caller can still reach bridge-run directly (not internal-token-only)', async () => {
|
||||
// No X-Internal-Token at all, no Authorization header either -> falls to
|
||||
// the normal Bearer requirement -> 401, proving this path is additive,
|
||||
// not a replacement for the existing Zitadel flow.
|
||||
const res = await middleware(req('/api/0pt/quality/bridge-run'));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,29 @@
|
||||
import { beforeEach, expect, it, vi } from "vitest";
|
||||
import { NextRequest, NextResponse } from "next/server";
|
||||
|
||||
const mocks = vi.hoisted(() => ({ routeAuth: vi.fn() }));
|
||||
vi.mock("@/src/auth/require-route-auth", () => ({ requireRouteAuth: mocks.routeAuth }));
|
||||
|
||||
import { requireOrderOwner } from "@/src/auth/require-order-owner";
|
||||
|
||||
beforeEach(() => mocks.routeAuth.mockReset());
|
||||
|
||||
const request = () => new NextRequest("https://0pt.app/api/orders", { method: "POST" });
|
||||
|
||||
it("passes through a failed Zitadel route-auth decision", async () => {
|
||||
mocks.routeAuth.mockResolvedValue({ response: NextResponse.json({ error: "unauthenticated" }, { status: 401 }) });
|
||||
expect((await requireOrderOwner(request())).response?.status).toBe(401);
|
||||
});
|
||||
|
||||
it("rejects the local-dev auth bypass when no verified principal exists", async () => {
|
||||
mocks.routeAuth.mockResolvedValue({ ctx: { tenantId: "spoofable-header" } });
|
||||
expect((await requireOrderOwner(request())).response?.status).toBe(401);
|
||||
});
|
||||
|
||||
it("uses only the verified JWT principal, not a request-supplied tenant", async () => {
|
||||
mocks.routeAuth.mockResolvedValue({
|
||||
ctx: { tenantId: "header-tenant", principal: { tenantId: "signed-tenant", sub: "signed-subject" } },
|
||||
});
|
||||
const result = await requireOrderOwner(request());
|
||||
expect(result.owner).toEqual({ tenantId: "signed-tenant", subject: "signed-subject" });
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
/**
|
||||
* Dual-accept workload identity: the machine routes accept EITHER the legacy
|
||||
* shared `X-Internal-Token` (server-configured single-tenant scope) OR a
|
||||
* verified CL0UD workload JWT (tenant + capabilities from verified claims
|
||||
* only). These tests pin the security properties that make that safe:
|
||||
*
|
||||
* - a client-supplied `x-0pt-verified-*` header can never authorize
|
||||
* anything (it is stripped before the handler sees it);
|
||||
* - an ambiguous legacy scope is refused instead of silently widening;
|
||||
* - a workload token for tenant A cannot write tenant B's facts;
|
||||
* - a workload token without the required capability is denied.
|
||||
*/
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { SignJWT, generateKeyPair } from 'jose';
|
||||
import { middleware } from '../../middleware';
|
||||
import { assertTenantMatchesVerified, assertWorkloadCapabilities } from '../../src/http/tenant-guard';
|
||||
import { __resetWorkloadJwksCache, __setWorkloadKeyResolverForTests } from '../../src/auth/cl0ud-workload';
|
||||
import { SERVICE_CAPABILITIES_HEADER, SERVICE_TENANT_SCOPE_HEADER } from '../../src/auth/internal-service-tenant';
|
||||
|
||||
const ISSUER = 'https://cl0ud.siax.io';
|
||||
const TENANT_A = '379976258701823235';
|
||||
const TENANT_B = '999999999999999999';
|
||||
|
||||
function req(path: string, headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest(new URL(path, 'http://localhost'), { headers });
|
||||
}
|
||||
|
||||
let privateKey: CryptoKey;
|
||||
let publicKey: CryptoKey;
|
||||
|
||||
beforeEach(async () => {
|
||||
const pair = await generateKeyPair('RS256');
|
||||
privateKey = pair.privateKey as CryptoKey;
|
||||
publicKey = pair.publicKey as CryptoKey;
|
||||
__setWorkloadKeyResolverForTests(async () => publicKey);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
__resetWorkloadJwksCache();
|
||||
for (const key of ['INTERNAL_TOKEN', 'INTERNAL_SERVICE_TENANTS', 'CL0UD_WORKLOAD_ISSUER', 'CL0UD_WORKLOAD_AUDIENCE', 'AUTH_ENFORCE']) {
|
||||
delete process.env[key];
|
||||
}
|
||||
});
|
||||
|
||||
async function workloadToken(claims: Record<string, unknown>, audience = '0pt'): Promise<string> {
|
||||
return await new SignJWT(claims)
|
||||
.setProtectedHeader({ alg: 'RS256' })
|
||||
.setIssuer(ISSUER)
|
||||
.setAudience(audience)
|
||||
.setSubject('svc-0pt-worker')
|
||||
.setIssuedAt()
|
||||
.setExpirationTime('5m')
|
||||
.sign(privateKey);
|
||||
}
|
||||
|
||||
describe('middleware: legacy internal token scope', () => {
|
||||
beforeEach(() => {
|
||||
process.env.INTERNAL_TOKEN = 'engine-shared-secret';
|
||||
delete process.env.CL0UD_WORKLOAD_ISSUER;
|
||||
});
|
||||
|
||||
it('single configured tenant becomes the verified tenant and the service scope', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = TENANT_A;
|
||||
const res = await middleware(req('/api/0pt/canonical/facts', { 'x-internal-token': 'engine-shared-secret' }));
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.headers.get('x-middleware-request-x-0pt-verified-tenant')).toBe(TENANT_A);
|
||||
expect(res.headers.get(`x-middleware-request-${SERVICE_TENANT_SCOPE_HEADER}`)).toBe(TENANT_A);
|
||||
});
|
||||
|
||||
it('an ambiguous multi-tenant scope is refused, not widened', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = `${TENANT_A},${TENANT_B}`;
|
||||
const res = await middleware(req('/api/0pt/canonical/facts', { 'x-internal-token': 'engine-shared-secret' }));
|
||||
expect(res.status).toBe(401);
|
||||
expect((await res.json()).error).toBe('OPT_UNAUTHENTICATED');
|
||||
});
|
||||
|
||||
it('forged client-supplied verified headers are stripped', async () => {
|
||||
process.env.INTERNAL_SERVICE_TENANTS = TENANT_A;
|
||||
const res = await middleware(
|
||||
req('/api/0pt/canonical/facts', {
|
||||
'x-internal-token': 'engine-shared-secret',
|
||||
'x-0pt-verified-tenant': TENANT_B,
|
||||
[SERVICE_TENANT_SCOPE_HEADER]: TENANT_B,
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.headers.get('x-middleware-request-x-0pt-verified-tenant')).toBe(TENANT_A);
|
||||
expect(res.headers.get(`x-middleware-request-${SERVICE_TENANT_SCOPE_HEADER}`)).toBe(TENANT_A);
|
||||
});
|
||||
});
|
||||
|
||||
describe('middleware: CL0UD workload token (dual-accept)', () => {
|
||||
beforeEach(() => {
|
||||
process.env.CL0UD_WORKLOAD_ISSUER = ISSUER;
|
||||
process.env.CL0UD_WORKLOAD_AUDIENCE = '0pt';
|
||||
delete process.env.INTERNAL_TOKEN;
|
||||
});
|
||||
|
||||
it('derives tenant and capabilities from verified claims', async () => {
|
||||
const token = await workloadToken({ tenant_id: TENANT_A, capabilities: ['0pt.canonical.write'] });
|
||||
const res = await middleware(req('/api/0pt/canonical/facts', { authorization: `Bearer ${token}` }));
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.headers.get('x-middleware-request-x-0pt-verified-tenant')).toBe(TENANT_A);
|
||||
expect(res.headers.get(`x-middleware-request-${SERVICE_CAPABILITIES_HEADER}`)).toBe('0pt.canonical.write');
|
||||
});
|
||||
|
||||
it('rejects a token with the wrong audience', async () => {
|
||||
const token = await workloadToken({ tenant_id: TENANT_A, capabilities: ['0pt.canonical.write'] }, 'n0d');
|
||||
const res = await middleware(req('/api/0pt/canonical/facts', { authorization: `Bearer ${token}` }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('rejects a token that carries no tenant claim', async () => {
|
||||
const token = await workloadToken({ capabilities: ['0pt.canonical.write'] });
|
||||
const res = await middleware(req('/api/0pt/canonical/facts', { authorization: `Bearer ${token}` }));
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('ignores forged verified headers on the workload path too', async () => {
|
||||
const token = await workloadToken({ tenant_id: TENANT_A, capabilities: ['0pt.canonical.write'] });
|
||||
const res = await middleware(
|
||||
req('/api/0pt/canonical/facts', {
|
||||
authorization: `Bearer ${token}`,
|
||||
'x-0pt-verified-tenant': TENANT_B,
|
||||
}),
|
||||
);
|
||||
expect(res.headers.get('x-middleware-request-x-0pt-verified-tenant')).toBe(TENANT_A);
|
||||
});
|
||||
});
|
||||
|
||||
describe('tenant guard: scope and capability enforcement', () => {
|
||||
it('denies a write for a tenant outside the service scope', () => {
|
||||
const request = req('/api/0pt/canonical/facts', { [SERVICE_TENANT_SCOPE_HEADER]: TENANT_A });
|
||||
expect(assertTenantMatchesVerified(request, TENANT_A)).toBeNull();
|
||||
const denied = assertTenantMatchesVerified(request, TENANT_B);
|
||||
expect(denied?.status).toBe(403);
|
||||
});
|
||||
|
||||
it('denies a tenant that disagrees with a verified workload tenant', () => {
|
||||
const request = req('/api/0pt/canonical/facts', { 'x-0pt-verified-tenant': TENANT_A });
|
||||
expect(assertTenantMatchesVerified(request, TENANT_A)).toBeNull();
|
||||
expect(assertTenantMatchesVerified(request, TENANT_B)?.status).toBe(403);
|
||||
});
|
||||
|
||||
it('denies a missing capability on a capability-scoped principal', () => {
|
||||
const request = req('/api/0pt/canonical/facts', { [SERVICE_CAPABILITIES_HEADER]: '0pt.canonical.read' });
|
||||
expect(assertWorkloadCapabilities(request, ['0pt.canonical.write'])?.status).toBe(403);
|
||||
expect(assertWorkloadCapabilities(request, ['0pt.canonical.read'])).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,125 @@
|
||||
/**
|
||||
* Unit tests for src/auth/zitadel.ts `verifyBearer`, using a locally-generated
|
||||
* RSA keypair + `createLocalJWKSet` so there is ZERO network access: we sign
|
||||
* our own tokens and inject the matching JWKS resolver.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeAll } from 'vitest';
|
||||
import {
|
||||
SignJWT,
|
||||
generateKeyPair,
|
||||
exportJWK,
|
||||
createLocalJWKSet,
|
||||
type JWTVerifyGetKey,
|
||||
type KeyLike,
|
||||
} from 'jose';
|
||||
import { verifyBearer, deriveTenantId, BearerVerificationError } from '@/src/auth/zitadel';
|
||||
|
||||
const ISSUER = 'https://test-issuer.siax.io';
|
||||
const KID = 'test-key-1';
|
||||
|
||||
let privateKey: KeyLike;
|
||||
let jwks: JWTVerifyGetKey;
|
||||
|
||||
beforeAll(async () => {
|
||||
const { publicKey, privateKey: pk } = await generateKeyPair('RS256');
|
||||
privateKey = pk;
|
||||
const jwk = await exportJWK(publicKey);
|
||||
jwk.kid = KID;
|
||||
jwk.alg = 'RS256';
|
||||
jwks = createLocalJWKSet({ keys: [jwk] });
|
||||
});
|
||||
|
||||
interface SignOpts {
|
||||
issuer?: string;
|
||||
expirationTime?: string | number;
|
||||
}
|
||||
|
||||
async function sign(claims: Record<string, unknown>, opts: SignOpts = {}): Promise<string> {
|
||||
return new SignJWT(claims)
|
||||
.setProtectedHeader({ alg: 'RS256', kid: KID })
|
||||
.setIssuedAt()
|
||||
.setIssuer(opts.issuer ?? ISSUER)
|
||||
.setAudience('siax-test')
|
||||
.setExpirationTime(opts.expirationTime ?? '2h')
|
||||
.sign(privateKey);
|
||||
}
|
||||
|
||||
describe('deriveTenantId', () => {
|
||||
it('prefers the Zitadel org id claim', () => {
|
||||
expect(
|
||||
deriveTenantId({ 'urn:zitadel:iam:org:id': 'org_1', tenant_id: 't_custom' }),
|
||||
).toBe('org_1');
|
||||
});
|
||||
|
||||
it('falls back to the resourceowner id, then tenant_id, then tenant', () => {
|
||||
expect(deriveTenantId({ 'urn:zitadel:iam:user:resourceowner:id': 'org_ro' })).toBe('org_ro');
|
||||
expect(deriveTenantId({ tenant_id: 't_x' })).toBe('t_x');
|
||||
expect(deriveTenantId({ tenant: 't_y' })).toBe('t_y');
|
||||
});
|
||||
|
||||
it('honors an explicit override claim key when present', () => {
|
||||
expect(deriveTenantId({ custom_tid: 't_over', 'urn:zitadel:iam:org:id': 'org_1' }, 'custom_tid')).toBe(
|
||||
't_over',
|
||||
);
|
||||
});
|
||||
|
||||
it('returns undefined when no tenant claim is present', () => {
|
||||
expect(deriveTenantId({ sub: 'u1' })).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('verifyBearer', () => {
|
||||
it('verifies a valid token and derives the principal (sub + tenant)', async () => {
|
||||
const token = await sign({ sub: 'user_1', 'urn:zitadel:iam:org:id': 'tenant_x' });
|
||||
const principal = await verifyBearer(token, { issuer: ISSUER, keyResolver: jwks });
|
||||
expect(principal.sub).toBe('user_1');
|
||||
expect(principal.tenantId).toBe('tenant_x');
|
||||
expect(principal.claims.iss).toBe(ISSUER);
|
||||
});
|
||||
|
||||
it('honors the custom tenant_id claim', async () => {
|
||||
const token = await sign({ sub: 'user_2', tenant_id: 't_protosell' });
|
||||
const principal = await verifyBearer(token, { issuer: ISSUER, keyResolver: jwks });
|
||||
expect(principal.tenantId).toBe('t_protosell');
|
||||
});
|
||||
|
||||
it('rejects a tampered token (bad signature)', async () => {
|
||||
const token = await sign({ sub: 'user_1', 'urn:zitadel:iam:org:id': 'tenant_x' });
|
||||
const firstDot = token.indexOf('.');
|
||||
const secondDot = token.indexOf('.', firstDot + 1);
|
||||
const mid = Math.floor((firstDot + secondDot) / 2);
|
||||
const ch = token.charAt(mid);
|
||||
const tampered = token.slice(0, mid) + (ch === 'a' ? 'b' : 'a') + token.slice(mid + 1);
|
||||
await expect(verifyBearer(tampered, { issuer: ISSUER, keyResolver: jwks })).rejects.toBeInstanceOf(
|
||||
BearerVerificationError,
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects an expired token', async () => {
|
||||
const token = await sign(
|
||||
{ sub: 'user_1', 'urn:zitadel:iam:org:id': 'tenant_x' },
|
||||
{ expirationTime: '-1h' },
|
||||
);
|
||||
await expect(verifyBearer(token, { issuer: ISSUER, keyResolver: jwks })).rejects.toBeInstanceOf(
|
||||
BearerVerificationError,
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects a token from the wrong issuer', async () => {
|
||||
const token = await sign(
|
||||
{ sub: 'user_1', 'urn:zitadel:iam:org:id': 'tenant_x' },
|
||||
{ issuer: 'https://evil-issuer.example' },
|
||||
);
|
||||
await expect(verifyBearer(token, { issuer: ISSUER, keyResolver: jwks })).rejects.toBeInstanceOf(
|
||||
BearerVerificationError,
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects a validly-signed token that carries no tenant claim', async () => {
|
||||
const token = await sign({ sub: 'user_1' });
|
||||
await expect(verifyBearer(token, { issuer: ISSUER, keyResolver: jwks })).rejects.toMatchObject({
|
||||
reason: 'token_missing_tenant_claim',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,63 @@
|
||||
/**
|
||||
* C8: SSR-render proof that the host can render the @siax/ui ImportWizard over
|
||||
* the @siax/import-export runtime store (the exact packages the admin import
|
||||
* page uses). Node environment — react-dom/server, no DOM needed.
|
||||
*/
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
|
||||
// ImportWizard subscribes to the runtime store via useSyncExternalStore, which
|
||||
// demands getServerSnapshot under react-dom/server. For a static render proof
|
||||
// the snapshot read is enough — reactivity is the browser's concern.
|
||||
vi.mock("react", async (importOriginal) => {
|
||||
const React = await importOriginal<typeof import("react")>();
|
||||
return { ...React, useSyncExternalStore: ((_subscribe: unknown, getSnapshot: () => unknown) => getSnapshot()) as typeof React.useSyncExternalStore };
|
||||
});
|
||||
import { createElement } from "react";
|
||||
import { renderToString } from "react-dom/server";
|
||||
import { ImportWizard } from "@siax/ui";
|
||||
import { createImportRunStore } from "@siax/import-export";
|
||||
import { createImportJob } from "@siax/contracts/import-export";
|
||||
|
||||
function makeStore(rows: Record<string, string>[]) {
|
||||
return createImportRunStore({
|
||||
job: createImportJob({
|
||||
id: "test-import",
|
||||
tenantId: "tenant-test",
|
||||
entity: "orders",
|
||||
format: "csv",
|
||||
source: { system: "0pt-admin", channel: "web" },
|
||||
createdAt: "2026-09-30T00:00:00Z",
|
||||
}),
|
||||
rows,
|
||||
});
|
||||
}
|
||||
|
||||
describe("ImportWizard renders over the runtime store (host integration)", () => {
|
||||
it("empty store → explicit empty state with the pipeline <ol>", () => {
|
||||
const html = renderToString(
|
||||
createElement(ImportWizard, { store: makeStore([]), onExecute: async () => {} }),
|
||||
);
|
||||
expect(html).toContain("<ol");
|
||||
expect(html.length).toBeGreaterThan(100);
|
||||
});
|
||||
|
||||
it("rows present → pipeline steps render; mapped stage shows mapping table", () => {
|
||||
const store = makeStore([{ flow: "custom", service_type: "icp", type: "Bolag", volume: "10", frequency: "Engångs", markets: "SE" }]);
|
||||
store.detect();
|
||||
let html = renderToString(createElement(ImportWizard, { store, columns: [{ source: "flow", target: "flow" }], onExecute: async () => {} }));
|
||||
expect(html).toContain("<ol");
|
||||
expect(html).toContain("aria-current=\"step\"");
|
||||
store.map({ columns: [{ source: "flow", target: "flow", required: true }] });
|
||||
html = renderToString(createElement(ImportWizard, { store, onExecute: async () => {} }));
|
||||
expect(html).toContain("flow");
|
||||
});
|
||||
|
||||
it("failed store renders the failure report with role=alert", () => {
|
||||
const store = makeStore([{ flow: "custom" }]);
|
||||
store.detect();
|
||||
store.fail("Servern avvisade exekveringen");
|
||||
const html = renderToString(createElement(ImportWizard, { store, onExecute: async () => {} }));
|
||||
expect(html).toContain("alert");
|
||||
expect(html).toContain("Servern avvisade exekveringen");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,31 @@
|
||||
/**
|
||||
* SSR-render-proof för den nya admin-ytan /admin/notes (kernel-konsumenten).
|
||||
* Samma mönster som import-wizard-ssr.test.ts: react-dom/server i Node.
|
||||
* PortalShell -> usePathname (next/navigation) mockas; sonner toast mockas.
|
||||
*/
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
|
||||
vi.mock("next/navigation", () => ({
|
||||
usePathname: () => "/admin/notes",
|
||||
useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
|
||||
}));
|
||||
vi.mock("sonner", () => ({ toast: { success: vi.fn(), warning: vi.fn(), error: vi.fn() } }));
|
||||
vi.mock("@/components/locale-provider", () => ({
|
||||
LocaleProvider: ({ children }: { children: React.ReactNode }) => children,
|
||||
useT: () => (x: { en: string; sv: string }) => x.en,
|
||||
useLocale: () => "en",
|
||||
}));
|
||||
|
||||
import { createElement } from "react";
|
||||
import { renderToString } from "react-dom/server";
|
||||
import OrderNotesPage from "@/app/admin/notes/page";
|
||||
|
||||
describe("/admin/notes SSR (kernel-konsument-yta)", () => {
|
||||
it("renderar rubrik, offline-växeln och laddningstillstånd utan krasch (SSR = första paint före useEffect)", () => {
|
||||
const html = renderToString(createElement(OrderNotesPage));
|
||||
expect(html).toContain("Orderanteckningar");
|
||||
expect(html).toContain("Offline-läge");
|
||||
expect(html).toContain('role="status"'); // loading-skeleton = korrekt SSR-att-få-state
|
||||
expect(html.length).toBeGreaterThan(500);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,72 @@
|
||||
/**
|
||||
* `cutover.test.ts` — HSP-084 acceptance:
|
||||
* T01: dual writers are DETECTED.
|
||||
* T02: a late source change is carried or stops the cutover.
|
||||
* T03: the rollback plan describes how target writes are handled.
|
||||
* Runner: vitest (0pt-konventionen).
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
detectDualWriters,
|
||||
handleLateSourceChanges,
|
||||
buildRollbackPlan,
|
||||
} from '../../src/connectors/cutover';
|
||||
|
||||
describe('HSP-084-T01: dubbla writers upptäcks', () => {
|
||||
it('BOTH source AND target active = dual writer detected', () => {
|
||||
const result = detectDualWriters({ sourceWriterActive: true, targetWriterActive: true });
|
||||
expect(result.dualDetected).toBe(true);
|
||||
if (result.dualDetected) expect(result.reason).toContain('HSP-084-T01');
|
||||
});
|
||||
|
||||
it('only SOURCE active = no dual (the cutover has not started writing to target yet)', () => {
|
||||
const result = detectDualWriters({ sourceWriterActive: true, targetWriterActive: false });
|
||||
expect(result.dualDetected).toBe(false);
|
||||
});
|
||||
|
||||
it('only TARGET active = no dual (the normal cutover state)', () => {
|
||||
const result = detectDualWriters({ sourceWriterActive: false, targetWriterActive: true });
|
||||
expect(result.dualDetected).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-084-T02: sen ändring vid källan avstäms eller stoppar cutover', () => {
|
||||
it('NO late changes = carried (nothing to reconcile)', () => {
|
||||
const result = handleLateSourceChanges({ lateChanges: [], carryLateChanges: true });
|
||||
expect(result.state).toBe('CARRIED');
|
||||
expect(result.lateChanges).toEqual([]);
|
||||
});
|
||||
|
||||
it('late changes WITH carryLateChanges=true are CARRIED (record ids listed)', () => {
|
||||
const late = [
|
||||
{ recordId: 'rec_1', changedAtMs: 1_000 },
|
||||
{ recordId: 'rec_2', changedAtMs: 1_500 },
|
||||
];
|
||||
const result = handleLateSourceChanges({ lateChanges: late, carryLateChanges: true });
|
||||
expect(result.state).toBe('CARRIED');
|
||||
expect(result.lateChanges).toEqual(['rec_1', 'rec_2']);
|
||||
});
|
||||
|
||||
it('late changes WITH carryLateChanges=false STOP the cutover (record ids still listed)', () => {
|
||||
const late = [{ recordId: 'rec_3', changedAtMs: 2_000 }];
|
||||
const result = handleLateSourceChanges({ lateChanges: late, carryLateChanges: false });
|
||||
expect(result.state).toBe('CARRIED');
|
||||
expect(result.reason).toContain('STOPPAR cutover');
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-084-T03: rollback beskriver hur nya målskrivningar hanteras', () => {
|
||||
it('the rollback plan CARRIES BACK target writes made during the cutover', () => {
|
||||
const plan = buildRollbackPlan('cutover_1', 12);
|
||||
expect(plan.targetWritesCarriedBack).toBe(true);
|
||||
expect(plan.sourceWriterReactivated).toBe(true);
|
||||
expect(plan.steps.some((s) => s.includes('12'))).toBe(true);
|
||||
expect(plan.steps.some((s) => s.includes('idempotent'))).toBe(true);
|
||||
expect(plan.steps.some((s) => s.includes('konsistens'))).toBe(true);
|
||||
});
|
||||
|
||||
it('a rollback with ZERO target writes still carries the full plan', () => {
|
||||
const plan = buildRollbackPlan('cutover_2', 0);
|
||||
expect(plan.steps.length).toBeGreaterThan(3);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,102 @@
|
||||
/**
|
||||
* `exit-manifest.test.ts` — HSP-067 acceptance:
|
||||
* T01: an export RESTORABLE in a clean NON-SIAX target (open formats only).
|
||||
* T02: sources/notice-krav FOLLOW the allowed artifacts.
|
||||
* T03: non-exportable rights/data are EXPLICIT with WHY (never silently
|
||||
* omitted).
|
||||
* Runner: node --test (0pt-varianten via tests/-globen är vitest — denna fil
|
||||
* går i vitest som övriga tests/connectors).
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
buildExitManifest,
|
||||
isPortableToNonSiaxTarget,
|
||||
applicableNoticeRequirements,
|
||||
type ExitManifest,
|
||||
} from '../../src/connectors/exit-manifest';
|
||||
|
||||
function aManifest(overrides: Partial<ExitManifest> = {}): ExitManifest {
|
||||
return {
|
||||
manifestId: 'exit_1',
|
||||
tenantId: 't_exit',
|
||||
artifacts: [
|
||||
{ artifactId: 'art_1', format: 'json', contentHash: 'sha256:aa', recordCount: 100 },
|
||||
{ artifactId: 'art_2', format: 'csv', contentHash: 'sha256:bb', recordCount: 200 },
|
||||
],
|
||||
noticeRequirements: [{ artifactId: 'art_1', requirement: 'CC-BY attribution required' }],
|
||||
nonExportable: [],
|
||||
createdAt: '2026-09-22T00:00:00Z',
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('HSP-067-T01: export kan återställas i ren icke-SIAX-målmiljö', () => {
|
||||
it('a manifest with ONLY open formats is portable', () => {
|
||||
expect(isPortableToNonSiaxTarget(aManifest())).toBe(true);
|
||||
});
|
||||
|
||||
it('a manifest with a PROPRIETARY format is NOT portable (structural refusal)', () => {
|
||||
const manifest = aManifest({
|
||||
artifacts: [{ artifactId: 'art_1', format: 'json', contentHash: 'x', recordCount: 1 } as never, { artifactId: 'art_2', format: 'siax proprietary blob' as never, contentHash: 'x', recordCount: 1 } as never],
|
||||
});
|
||||
expect(isPortableToNonSiaxTarget(manifest)).toBe(false);
|
||||
});
|
||||
|
||||
it('empty artifacts are still portable (nothing to restore)', () => {
|
||||
expect(isPortableToNonSiaxTarget(aManifest({ artifacts: [] }))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-067-T02: källor/noticekrav följer tillåtna artefakter', () => {
|
||||
it('buildExitManifest carries the notice requirement from the artifact', () => {
|
||||
const manifest = buildExitManifest({
|
||||
manifestId: 'exit_b',
|
||||
tenantId: 't_exit',
|
||||
createdAt: '2026-09-22T00:00:00Z',
|
||||
artifacts: [
|
||||
{ artifactId: 'art_a', format: 'json', contentHash: 'h1', recordCount: 10, sourceIds: ['src_1'], noticeRequirement: 'CC-BY attribution' },
|
||||
{ artifactId: 'art_b', format: 'csv', contentHash: 'h2', recordCount: 20, sourceIds: [] },
|
||||
],
|
||||
});
|
||||
expect(manifest.noticeRequirements).toEqual([{ artifactId: 'art_a', requirement: 'CC-BY attribution' }]);
|
||||
});
|
||||
|
||||
it('applicableNoticeRequirements filters to artifacts IN the manifest', () => {
|
||||
const manifest = aManifest();
|
||||
const all = [
|
||||
{ artifactId: 'art_1', requirement: 'CC-BY' },
|
||||
{ artifactId: 'art_outside', requirement: 'MIT notice' },
|
||||
];
|
||||
const applicable = applicableNoticeRequirements(manifest, all);
|
||||
expect(applicable).toEqual([{ artifactId: 'art_1', requirement: 'CC-BY' }]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-067-T03: UI visar vilka rättigheter/data som inte kan exporteras och varför', () => {
|
||||
it('non-exportable items are EXPLICIT with their reason — never silently omitted', () => {
|
||||
const manifest = buildExitManifest({
|
||||
manifestId: 'exit_c',
|
||||
tenantId: 't_exit',
|
||||
createdAt: '2026-09-22T00:00:00Z',
|
||||
artifacts: [
|
||||
{
|
||||
artifactId: 'art_lic',
|
||||
format: 'json',
|
||||
contentHash: 'h1',
|
||||
recordCount: 5,
|
||||
sourceIds: [],
|
||||
nonExportable: [{ reason: 'license', detail: 'tredjepartslicens tillåter ej vidareexport av rådata' }],
|
||||
},
|
||||
],
|
||||
});
|
||||
expect(manifest.nonExportable).toHaveLength(1);
|
||||
expect(manifest.nonExportable[0]!.reason).toBe('license');
|
||||
expect(manifest.nonExportable[0]!.detail).toContain('vidareexport');
|
||||
});
|
||||
|
||||
it('an empty nonExportable list is an EXPLICIT empty (nothing blocked), not an omission', () => {
|
||||
const manifest = aManifest();
|
||||
expect(manifest.nonExportable).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* `inventory-report.test.ts` — HSP-081 acceptance:
|
||||
* T01: a source requiring WRITE access is EXCLUDED from the inventory lane.
|
||||
* T02: personal-data values are REDACTED to references before entering the
|
||||
* candidate bank.
|
||||
* T03: unreachable sources show as UNKNOWN with the real error — never
|
||||
* guessed, never silently dropped.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
buildInventoryReport,
|
||||
redactPersonalData,
|
||||
type InventorySourceInput,
|
||||
} from '../../src/connectors/inventory-report';
|
||||
|
||||
function aSource(overrides: Partial<InventorySourceInput> = {}): InventorySourceInput {
|
||||
return {
|
||||
sourceId: 'src_1',
|
||||
writeAccessRequired: false,
|
||||
reachable: true,
|
||||
partitions: [{ partitionKey: 'customers', name: 'Customers', schemaFields: [{ name: 'email', type: 'string' }, { name: 'plan', type: 'string' }] }],
|
||||
sampleRecords: [{ email: 'kund@foretag.se', plan: 'pro' }],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('HSP-081-T01: connector begär inte write för ren inventering', () => {
|
||||
it('a read-only source is INVENTORIED', () => {
|
||||
const report = buildInventoryReport([aSource()]);
|
||||
expect(report[0]!.state).toBe('inventoried');
|
||||
expect(report[0]!.sampleCount).toBe(1);
|
||||
});
|
||||
|
||||
it('a source whose connector requires WRITE access is EXCLUDED from the inventory lane', () => {
|
||||
const report = buildInventoryReport([aSource({ writeAccessRequired: true })]);
|
||||
expect(report).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-081-T02: privata persondata hamnar inte i generell kandidatbank', () => {
|
||||
it('emails/phones/personnummer are REDACTED to references in the report', () => {
|
||||
const report = buildInventoryReport([aSource()]);
|
||||
void report;
|
||||
const redacted = redactPersonalData({ email: 'kund@foretag.se', phone: '070-123 45 67', pn: '810101-1234' });
|
||||
expect(JSON.stringify(redacted)).not.toContain('kund@foretag.se');
|
||||
expect(JSON.stringify(redacted)).not.toContain('070-123 45 67');
|
||||
expect(JSON.stringify(redacted)).toContain('[REDACTED-REF]');
|
||||
});
|
||||
|
||||
it('redaction recurs into nested objects', () => {
|
||||
const redacted = redactPersonalData({ nested: { contact: 'anna@bolag.se' } });
|
||||
expect(JSON.stringify(redacted)).not.toContain('anna@bolag.se');
|
||||
expect((redacted.nested as Record<string, unknown>).contact).toBe('[REDACTED-REF]');
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-081-T03: missade eller otillgängliga källor visas som okända', () => {
|
||||
it('an unreachable source shows as unknown WITH its real error detail', () => {
|
||||
const report = buildInventoryReport([aSource({ reachable: false, unreachableError: 'HTTP 503 from upstream' })]);
|
||||
expect(report[0]!.state).toBe('unknown');
|
||||
expect(report[0]!.unknownReason).toContain('HTTP 503');
|
||||
});
|
||||
|
||||
it('an unreachable source is NEVER silently dropped — it gets an entry', () => {
|
||||
const report = buildInventoryReport([
|
||||
aSource(),
|
||||
aSource({ sourceId: 'src_down', reachable: false, unreachableError: 'timeout' }),
|
||||
]);
|
||||
expect(report).toHaveLength(2);
|
||||
expect(report.find((r) => r.sourceId === 'src_down')!.state).toBe('unknown');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,107 @@
|
||||
/**
|
||||
* `migration-mapping.test.ts` — HSP-082 acceptance:
|
||||
* T01: identical names are NOT merged without evidence.
|
||||
* T02: Swedish characters + timezones are preserved (UTF-8 passthrough,
|
||||
* UTC normalization with the original offset recorded).
|
||||
* T03: a missing ACL mapping is BLOCKING for protected objects.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
decideEntityMerge,
|
||||
transformRecord,
|
||||
aclBlockingCheck,
|
||||
type MappingEntity,
|
||||
type ProtectedObjectId,
|
||||
} from '../../src/connectors/migration-mapping';
|
||||
|
||||
describe('HSP-082-T01: identiska namn slås inte ihop utan bevis', () => {
|
||||
it('two entities with the SAME name and NO evidence are both BLOCKED pending proof', () => {
|
||||
const decisions = decideEntityMerge([
|
||||
{ sourceId: 's1', targetId: 't1', displayName: 'Support' },
|
||||
{ sourceId: 's2', targetId: 't2', displayName: 'Support' },
|
||||
]);
|
||||
for (const d of decisions) {
|
||||
expect(d.decision).toBe('blocked_pending_evidence');
|
||||
expect(d.reason).toContain('HSP-082-T01');
|
||||
}
|
||||
});
|
||||
|
||||
it('entities WITH evidence (same_external_id) merge cleanly even in a name collision', () => {
|
||||
const decisions = decideEntityMerge([
|
||||
{ sourceId: 's1', targetId: 't1', displayName: 'Support', identityEvidence: 'same_external_id' },
|
||||
{ sourceId: 's2', targetId: 't2', displayName: 'Support' },
|
||||
]);
|
||||
const merged = decisions.find((d) => d.sourceId === 's1')!;
|
||||
expect(merged.decision).toBe('merged');
|
||||
expect(merged.reason).toContain('same_external_id');
|
||||
});
|
||||
|
||||
it('a UNIQUE name merges without extra evidence', () => {
|
||||
const decisions = decideEntityMerge([
|
||||
{ sourceId: 's1', targetId: 't1', displayName: 'Unik' },
|
||||
]);
|
||||
expect(decisions[0]!.decision).toBe('merged');
|
||||
});
|
||||
|
||||
it('case-insensitive name collision is also caught (Support vs support)', () => {
|
||||
const decisions = decideEntityMerge([
|
||||
{ sourceId: 's1', targetId: 't1', displayName: 'Support' },
|
||||
{ sourceId: 's2', targetId: 't2', displayName: 'support' },
|
||||
]);
|
||||
expect(decisions.every((d) => d.decision === 'blocked_pending_evidence')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-082-T02: svenska tecken och tidszoner bevaras', () => {
|
||||
it('Swedish characters pass through byte-exactly (no normalization/decomposition)', () => {
|
||||
const result = transformRecord({ name: 'Blåbärsvägen 32 — Göteborg, ÅÄÖåäö' });
|
||||
expect(result.record['name']).toBe('Blåbärsvägen 32 — Göteborg, ÅÄÖåäö');
|
||||
expect((result.record['name'] as string).includes('ÅÄÖ')).toBe(true);
|
||||
expect((result.record['name'] as string).includes('åäö')).toBe(true);
|
||||
});
|
||||
|
||||
it('timestamps normalize to UTC with the ORIGINAL offset recorded', () => {
|
||||
const result = transformRecord({ bookedAt: '2026-09-22T14:30:00+02:00' });
|
||||
expect(result.timestamps).toHaveLength(1);
|
||||
const t = result.timestamps[0]!;
|
||||
expect(t.original).toBe('2026-09-22T14:30:00+02:00');
|
||||
expect(t.originalOffset).toBe('+02:00');
|
||||
expect(t.normalized).toBe('2026-09-22T12:30:00.000Z');
|
||||
expect(result.record['bookedAt']).toBe('2026-09-22T12:30:00.000Z');
|
||||
});
|
||||
|
||||
it('Z-suffixed timestamps record their (no) offset explicitly', () => {
|
||||
const result = transformRecord({ at: '2026-09-22T12:00:00Z' });
|
||||
expect(result.timestamps[0]!.originalOffset).toBe('Z');
|
||||
});
|
||||
|
||||
it('nested timestamps are also normalized and recorded', () => {
|
||||
const result = transformRecord({ order: { createdAt: '2026-01-01T00:00:00-05:00' } });
|
||||
expect(result.timestamps).toHaveLength(1);
|
||||
expect(result.timestamps[0]!.normalized).toBe('2026-01-01T05:00:00.000Z');
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-082-T03: saknad ACL-mappning är blockerande för berört skyddat objekt', () => {
|
||||
const objects: ProtectedObjectId[] = [
|
||||
{ objectId: 'obj_protected', protected: true },
|
||||
{ objectId: 'obj_public', protected: false },
|
||||
];
|
||||
|
||||
it('a protected object WITHOUT an ACL mapping is BLOCKED; unprotected proceeds', () => {
|
||||
const result = aclBlockingCheck(objects, []);
|
||||
expect(result.proceed).toEqual(['obj_public']);
|
||||
expect(result.blocked[0]!.objectId).toBe('obj_protected');
|
||||
expect(result.blocked[0]!.reason).toContain('BLOCKERANDE');
|
||||
});
|
||||
|
||||
it('a protected object WITH a mapping proceeds', () => {
|
||||
const result = aclBlockingCheck(
|
||||
objects,
|
||||
[{ targetObjectId: 'obj_protected', entries: [{ subjectId: 's1', permission: 'read' }] }],
|
||||
);
|
||||
expect(result.blocked).toEqual([]);
|
||||
expect(result.proceed).toContain('obj_protected');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,110 @@
|
||||
/**
|
||||
* `migration-runner.test.ts` — HSP-083 acceptance:
|
||||
* T01: a crash mid-batch produces NO duplicates on resume — the durable
|
||||
* checkpoint + the sink's idempotency make the replayed batch a no-op
|
||||
* (the replay is COUNTED, never hidden).
|
||||
* T02: the cursor advances ONLY after a durable target-ack.
|
||||
* T03: total object count alone is NOT sufficient — VERIFIED requires
|
||||
* per-partition content hashes; count-only evidence is UNVERIFIED.
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import {
|
||||
InMemoryCheckpointStore,
|
||||
runMigration,
|
||||
resumeMigration,
|
||||
type MigrationBatch,
|
||||
type TargetSink,
|
||||
} from '../../src/connectors/migration-runner';
|
||||
|
||||
function aBatch(overrides: Partial<MigrationBatch> = {}): MigrationBatch {
|
||||
return {
|
||||
partitionKey: 'p1',
|
||||
fromCursor: '0',
|
||||
toCursor: 'c1',
|
||||
records: [{ id: 'r1', name: 'kund AB' }],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
/** An idempotent sink: the same (fromCursor, records) pair acks without re-persisting. */
|
||||
function idempotentSink(state: { persisted: Map<string, number> }): TargetSink {
|
||||
return {
|
||||
async write(batch) {
|
||||
const key = `${batch.partitionKey}:${batch.fromCursor}`;
|
||||
if (state.persisted.has(key)) {
|
||||
// Replay: ack, but NOTHING new persisted (the sink's idempotency).
|
||||
return { ackToken: `ack_${key}`, persistedCount: 0 };
|
||||
}
|
||||
state.persisted.set(key, batch.records.length);
|
||||
return { ackToken: `ack_${key}`, persistedCount: batch.records.length };
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('HSP-083-T01: krasch mitt i batch ger inte dubbletter', () => {
|
||||
it('a resume after a crash replays the batch; the idempotent sink persists NOTHING twice', async () => {
|
||||
const state = { persisted: new Map<string, number>() };
|
||||
const sink = idempotentSink(state);
|
||||
const store = new InMemoryCheckpointStore();
|
||||
// First run crashes BEFORE the checkpoint commit (records persisted though).
|
||||
const batch = aBatch({ records: [{ id: 'r1' }, { id: 'r2' }] });
|
||||
const first = await runMigration([batch], sink, store);
|
||||
expect(first.batchesApplied).toBe(1);
|
||||
expect(first.totalRecords).toBe(2);
|
||||
|
||||
// Simulate a crash mid-batch: resume from the DURABLE checkpoint (0).
|
||||
const report = await resumeMigration('p1', store, () => [batch], sink);
|
||||
// The replay is visible in the report...
|
||||
expect(report.replayDuplicates).toBe(2);
|
||||
// ...but NOTHING was double-persisted.
|
||||
expect(state.persisted.get('p1:0')).toBe(2);
|
||||
expect(report.totalRecords).toBe(0); // replay acked with persistedCount=0
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-083-T02: cursor uppdateras efter varaktig targetack', () => {
|
||||
it('the checkpoint commits ONLY after the sink acks (T02 ordering)', async () => {
|
||||
const store = new InMemoryCheckpointStore();
|
||||
const sink = idempotentSink({ persisted: new Map() });
|
||||
const batch = aBatch({ toCursor: 'c_42' });
|
||||
await runMigration([batch], sink, store);
|
||||
// T02: the durable cursor is now the batch's END cursor.
|
||||
expect(await store.get('p1')).toBe('c_42');
|
||||
});
|
||||
|
||||
it('a fresh partition starts from cursor 0', async () => {
|
||||
const store = new InMemoryCheckpointStore();
|
||||
expect(await store.get('p_never')).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-083-T03: total object count räcker inte som enda integritetsbevis', () => {
|
||||
it('a successful run is VERIFIED with per-partition content hashes (not count-only)', async () => {
|
||||
const sink = idempotentSink({ persisted: new Map() });
|
||||
const report = await runMigration([aBatch({ records: [{ id: 'r1' }, { id: 'r2' }] })], sink, new InMemoryCheckpointStore());
|
||||
expect(report.state).toBe('VERIFIED');
|
||||
expect(report.partitionHashes).toHaveLength(1);
|
||||
expect(report.partitionHashes[0]!.contentHash).toMatch(/^fnv1a-/);
|
||||
expect(report.partitionHashes[0]!.recordCount).toBe(2);
|
||||
});
|
||||
|
||||
it('a run with NO batches is UNVERIFIED (count 0 alone proves nothing)', async () => {
|
||||
const sink = idempotentSink({ persisted: new Map() });
|
||||
const report = await runMigration([], sink, new InMemoryCheckpointStore());
|
||||
expect(report.state).toBe('UNVERIFIED');
|
||||
expect(report.partitionHashes).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('different content produces different partition hashes (hash ≠ count)', async () => {
|
||||
const sink1 = idempotentSink({ persisted: new Map() });
|
||||
const sink2 = idempotentSink({ persisted: new Map() });
|
||||
const r1 = await runMigration([aBatch({ records: [{ id: 'r1' }] })], sink1, new InMemoryCheckpointStore());
|
||||
const r2 = await runMigration([aBatch({ records: [{ id: 'DIFFERENT' }], partitionKey: 'p2' })], sink2, new InMemoryCheckpointStore());
|
||||
expect(r1.partitionHashes).toHaveLength(1);
|
||||
expect(r2.partitionHashes).toHaveLength(1);
|
||||
expect(r1.partitionHashes[0]!.contentHash).not.toBe(r2.partitionHashes[0]!.contentHash);
|
||||
// Same count (1 == 1) but different hashes — count alone is insufficient (T03).
|
||||
expect(r1.partitionHashes[0]!.recordCount).toBe(r2.partitionHashes[0]!.recordCount);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,99 @@
|
||||
/**
|
||||
* `migration-studio.test.ts` — HSP-085 acceptance:
|
||||
* T01: an EJ importerbart objekt döljs inte ur nämnaren.
|
||||
* T02: en uppgift kan återupptas efter sessionbyte.
|
||||
* T03: en importerad CRM-lista marknadsförs inte som komplett M365-ersättning.
|
||||
* Runner: vitest (0pt-konventionen).
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
computeImportRatio,
|
||||
resumeMigration,
|
||||
buildCoverageClaim,
|
||||
type MigrationSourceObject,
|
||||
type MigrationSession,
|
||||
} from '../../src/connectors/migration-studio';
|
||||
|
||||
function sourceSet(): MigrationSourceObject[] {
|
||||
return [
|
||||
{ objectId: 'obj_1', name: 'CRM-lista: kunder', importable: true, tenantId: 't_1' },
|
||||
{ objectId: 'obj_2', name: 'CRM-lista: leads', importable: true, tenantId: 't_1' },
|
||||
{ objectId: 'obj_3', name: 'M365 mail-box', importable: false, nonImportableReason: 'mail är utanför migrationsscopet (p0st äger mail)', tenantId: 't_1' },
|
||||
{ objectId: 'obj_4', name: 'Cross-tenant doc', importable: false, nonImportableReason: 'annan tenant', tenantId: 't_other' },
|
||||
];
|
||||
}
|
||||
|
||||
describe('HSP-085-T01: ej importerbart objekt döljs inte ur nämnaren', () => {
|
||||
it('the ratio counts EVERY source object in the denominator (non-importable stays)', () => {
|
||||
const ratio = computeImportRatio(sourceSet());
|
||||
expect(ratio.totalSourceObjects).toBe(4);
|
||||
expect(ratio.importableCount).toBe(2);
|
||||
expect(ratio.nonImportableCount).toBe(2);
|
||||
// 2/4 = 0.5 — NOT 2/2 = 1.0 (which would be hiding the failures).
|
||||
expect(ratio.ratio).toBe(0.5);
|
||||
});
|
||||
|
||||
it('the non-importable objects are ALWAYS listed with their reasons', () => {
|
||||
const ratio = computeImportRatio(sourceSet());
|
||||
expect(ratio.nonImportable).toHaveLength(2);
|
||||
expect(ratio.nonImportable.some((n) => n.reason.includes('mail'))).toBe(true);
|
||||
expect(ratio.nonImportable.some((n) => n.reason.includes('annan tenant'))).toBe(true);
|
||||
});
|
||||
|
||||
it('a fully-importable source gives ratio 1.0 (honest, no non-importable to hide)', () => {
|
||||
const ratio = computeImportRatio([
|
||||
{ objectId: 'a', name: 'a', importable: true, tenantId: 't' },
|
||||
]);
|
||||
expect(ratio.ratio).toBe(1);
|
||||
expect(ratio.nonImportable).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-085-T02: uppgift kan återupptas efter sessionbyte', () => {
|
||||
const stored: MigrationSession = {
|
||||
migrationId: 'mig_1',
|
||||
tenantId: 't_1',
|
||||
checkpointCursor: 'batch_3',
|
||||
resolvedConflicts: ['conflict_a', 'conflict_b'],
|
||||
state: 'conflict_review',
|
||||
};
|
||||
|
||||
it('a session change RESUMES from the stored checkpoint + resolved conflicts', () => {
|
||||
const result = resumeMigration(stored, 't_1');
|
||||
expect(result.state).toBe('resumed');
|
||||
expect(result.checkpointCursor).toBe('batch_3');
|
||||
expect(result.resolvedConflicts).toEqual(['conflict_a', 'conflict_b']);
|
||||
});
|
||||
|
||||
it('a session change to a DIFFERENT tenant starts FRESH (no cross-tenant resume)', () => {
|
||||
const result = resumeMigration(stored, 't_other');
|
||||
expect(result.state).toBe('fresh');
|
||||
expect(result.checkpointCursor).toBe('0');
|
||||
});
|
||||
|
||||
it('no stored session starts fresh', () => {
|
||||
const result = resumeMigration(undefined, 't_1');
|
||||
expect(result.state).toBe('fresh');
|
||||
expect(result.checkpointCursor).toBe('0');
|
||||
});
|
||||
});
|
||||
|
||||
describe('HSP-085-T03: CRM-lista marknadsförs inte som komplett M365-ersättning', () => {
|
||||
it('the coverage claim is SCOPED to what was imported (never a generic total)', () => {
|
||||
const ratio = computeImportRatio(sourceSet());
|
||||
const claim = buildCoverageClaim('CRM-listor', ratio);
|
||||
expect(claim.scope).toContain('CRM-listor');
|
||||
expect(claim.scope).toContain('2 av 4');
|
||||
expect(claim.scope).toContain('ej importerbarta');
|
||||
// NEVER claims a generic total badge.
|
||||
expect(claim.scope.toLowerCase()).not.toContain('complete');
|
||||
expect(claim.scope.toLowerCase()).not.toContain('komplett microsoft');
|
||||
});
|
||||
|
||||
it('the claim carries the NON-IMPORTABLE count (the honest denominator)', () => {
|
||||
const ratio = computeImportRatio(sourceSet());
|
||||
const claim = buildCoverageClaim('CRM-listor', ratio);
|
||||
expect(claim.nonImportableCount).toBe(2);
|
||||
expect(claim.totalSourceObjects).toBe(4);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* Proves the narrow-scan property of PostgresKeyedLookupConnector — the
|
||||
* connector that stands in for "dealer_stock_entry.vehicle_id -> unique
|
||||
* vehicle IDs -> targeted lookup -> dimension_vehicle", never a scan of the
|
||||
* 98M-row `vehicle` table. The assertions are on QUERY CALLS, not just
|
||||
* returned records: a bug that widened the WHERE clause but happened to
|
||||
* still return the right rows in a test fixture would be invisible to a
|
||||
* behavioural-only test and is exactly what this file is written to catch.
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { PostgresKeyedLookupConnector } from "@/src/connectors/postgres-keyed-lookup-connector";
|
||||
import type { QueryImpl, SourceRow } from "@/src/connectors/postgres-watermark-connector";
|
||||
import type { RecordSchemaFields } from "@/src/schema/record-schema";
|
||||
|
||||
const SCHEMA: RecordSchemaFields = {
|
||||
id: { type: "string", required: true },
|
||||
make: { type: "string", required: false },
|
||||
model: { type: "string", required: false },
|
||||
};
|
||||
|
||||
const VEHICLE_TABLE: SourceRow[] = [
|
||||
{ id: "v1", make: "Volvo", model: "XC60" },
|
||||
{ id: "v2", make: "Volvo", model: "V70" },
|
||||
{ id: "v3", make: "Toyota", model: "Corolla" },
|
||||
{ id: "v4", make: "Audi", model: "A4" }, // never referenced by any dealer_stock_entry in these tests
|
||||
];
|
||||
|
||||
function fixtureQuery(): { query: QueryImpl; calls: Array<{ sql: string; params: unknown[] }> } {
|
||||
const calls: Array<{ sql: string; params: unknown[] }> = [];
|
||||
const query: QueryImpl = async (sql, params) => {
|
||||
calls.push({ sql, params });
|
||||
const [ids] = params as [Array<string | number>];
|
||||
return VEHICLE_TABLE.filter((row) => ids.includes(row.id as string));
|
||||
};
|
||||
return { query, calls };
|
||||
}
|
||||
|
||||
function config(keys: Array<string | number>, keysPerQuery?: number) {
|
||||
return {
|
||||
table: "vehiq.vehicle",
|
||||
partition_key: "dimension_vehicle",
|
||||
columns: ["id", "make", "model"],
|
||||
record_key_column: "id",
|
||||
schema: SCHEMA,
|
||||
keys,
|
||||
keys_per_query: keysPerQuery,
|
||||
};
|
||||
}
|
||||
|
||||
describe("PostgresKeyedLookupConnector — validate()", () => {
|
||||
it("refuses an empty key list rather than defaulting to a full read", () => {
|
||||
const connector = new PostgresKeyedLookupConnector(fixtureQuery().query);
|
||||
const verdict = connector.validate(config([]));
|
||||
expect(verdict.valid).toBe(false);
|
||||
expect(verdict.errors.join(" ")).toMatch(/keys must not be empty/);
|
||||
});
|
||||
|
||||
it("rejects '*' in columns", () => {
|
||||
const connector = new PostgresKeyedLookupConnector(fixtureQuery().query);
|
||||
expect(connector.validate({ ...config(["v1"]), columns: ["*"] }).valid).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("PostgresKeyedLookupConnector — the narrow-scan property", () => {
|
||||
it("connect() with an empty key list is refused, and NO query is ever issued", async () => {
|
||||
const { query, calls } = fixtureQuery();
|
||||
const connector = new PostgresKeyedLookupConnector(query);
|
||||
await expect(
|
||||
connector.connect(config([]), { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" }),
|
||||
).rejects.toThrow(/keys must not be empty/);
|
||||
expect(calls).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("reads exactly the vehicles referenced by the batch — v4 (never referenced) is never touched", async () => {
|
||||
const referenced = ["v1", "v2", "v3"]; // simulates dedup'd dealer_stock_entry.vehicle_id values from one batch
|
||||
const { query, calls } = fixtureQuery();
|
||||
const connector = new PostgresKeyedLookupConnector(query);
|
||||
await connector.connect(config(referenced), { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const result = await connector.read({ partition_key: "dimension_vehicle", limit: 500 });
|
||||
|
||||
expect(result.records.map((r) => r.record_key).sort()).toEqual(["v1", "v2", "v3"]);
|
||||
expect(result.exhausted).toBe(true);
|
||||
|
||||
// The narrow-scan property, checked at the QUERY level: every id ever
|
||||
// bound into a query call is a subset of `referenced`, and the union of
|
||||
// all ids queried equals exactly `referenced` — never more, never a
|
||||
// wildcard, never "v4".
|
||||
expect(calls).toHaveLength(1);
|
||||
const allQueriedIds = calls.flatMap((c) => c.params[0] as string[]);
|
||||
expect(allQueriedIds.sort()).toEqual([...referenced].sort());
|
||||
expect(allQueriedIds).not.toContain("v4");
|
||||
for (const call of calls) {
|
||||
expect(call.sql).toMatch(/WHERE id = ANY\(\$1\)/);
|
||||
expect(call.sql).not.toMatch(/select\s+\*/i);
|
||||
}
|
||||
});
|
||||
|
||||
it("chunks a large key list across multiple bounded queries, never one unbounded IN(...)", async () => {
|
||||
const referenced = Array.from({ length: 5 }, (_, i) => `v${i + 1}`);
|
||||
const { query, calls } = fixtureQuery();
|
||||
const connector = new PostgresKeyedLookupConnector(query);
|
||||
await connector.connect(config(referenced, 2), { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
|
||||
let cursor: string | undefined;
|
||||
let pages = 0;
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const page = await connector.read({ partition_key: "dimension_vehicle", cursor, limit: 500 });
|
||||
pages++;
|
||||
cursor = page.next_cursor;
|
||||
if (page.exhausted) break;
|
||||
}
|
||||
expect(pages).toBe(3); // ceil(5/2)
|
||||
for (const call of calls) {
|
||||
expect((call.params[0] as string[]).length).toBeLessThanOrEqual(2);
|
||||
}
|
||||
const allQueriedIds = calls.flatMap((c) => c.params[0] as string[]);
|
||||
expect(new Set(allQueriedIds).size).toBe(5);
|
||||
});
|
||||
|
||||
it("the empty-batch case: zero referenced vehicles means this connector is never even constructed by the caller (see vehiq-oltp-ingest-runner.test.ts) — but if it IS given zero keys, it fails validation rather than scanning", () => {
|
||||
const connector = new PostgresKeyedLookupConnector(fixtureQuery().query);
|
||||
expect(connector.validate(config([])).valid).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,194 @@
|
||||
/**
|
||||
* Connector-level proof for postgres-watermark-connector.ts. No real
|
||||
* Postgres: `queryImpl` is a fixture that runs the SAME SQL text the real
|
||||
* connector builds against an in-memory row set, so the watermark math and
|
||||
* the tie-break are proven precisely rather than just "some rows came back".
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
PostgresWatermarkConnector,
|
||||
checksumRows,
|
||||
decodeCursor,
|
||||
encodeCursor,
|
||||
type QueryImpl,
|
||||
type SourceRow,
|
||||
} from "@/src/connectors/postgres-watermark-connector";
|
||||
import type { RecordSchemaFields } from "@/src/schema/record-schema";
|
||||
|
||||
const SCHEMA: RecordSchemaFields = {
|
||||
id: { type: "string", required: true },
|
||||
vehicle_id: { type: "string", required: false },
|
||||
updated_at: { type: "string", required: true },
|
||||
};
|
||||
|
||||
const CONFIG = {
|
||||
table: "app.dealer_stock_entry",
|
||||
partition_key: "dealer_stock_entry",
|
||||
columns: ["id", "vehicle_id", "updated_at"],
|
||||
record_key_column: "id",
|
||||
watermark_column: "updated_at",
|
||||
schema: SCHEMA,
|
||||
};
|
||||
|
||||
/** A fixture query engine that actually parses/applies the connector's WHERE/ORDER BY/LIMIT against an in-memory table — not a stub that ignores its arguments. */
|
||||
function fixtureQuery(rows: SourceRow[]): { query: QueryImpl; calls: Array<{ sql: string; params: unknown[] }> } {
|
||||
const calls: Array<{ sql: string; params: unknown[] }> = [];
|
||||
const query: QueryImpl = async (sql, params) => {
|
||||
calls.push({ sql, params });
|
||||
let filtered = rows;
|
||||
if (sql.includes("WHERE")) {
|
||||
const [watermark, id] = params as [string, string, number];
|
||||
filtered = rows.filter(
|
||||
(r) => (r.updated_at as string) > watermark || ((r.updated_at as string) === watermark && (r.id as string) > id),
|
||||
);
|
||||
}
|
||||
const sorted = [...filtered].sort((a, b) => {
|
||||
const w = (a.updated_at as string).localeCompare(b.updated_at as string);
|
||||
return w !== 0 ? w : (a.id as string).localeCompare(b.id as string);
|
||||
});
|
||||
const limit = Number(params[params.length - 1]);
|
||||
return sorted.slice(0, limit);
|
||||
};
|
||||
return { query, calls };
|
||||
}
|
||||
|
||||
const ROWS: SourceRow[] = [
|
||||
{ id: "a1", vehicle_id: "v1", updated_at: "2026-09-01T00:00:00.000Z" },
|
||||
{ id: "a2", vehicle_id: "v2", updated_at: "2026-09-01T00:00:00.000Z" }, // same updated_at as a1 — the tie-break case
|
||||
{ id: "a3", vehicle_id: "v1", updated_at: "2026-09-02T00:00:00.000Z" },
|
||||
{ id: "a4", vehicle_id: "v3", updated_at: "2026-09-03T00:00:00.000Z" },
|
||||
];
|
||||
|
||||
describe("PostgresWatermarkConnector — validate()", () => {
|
||||
it("rejects a config pointed at the 98M-row vehicle table", () => {
|
||||
const connector = new PostgresWatermarkConnector(fixtureQuery([]).query);
|
||||
const verdict = connector.validate({ ...CONFIG, table: "vehiq.vehicle" });
|
||||
expect(verdict.valid).toBe(false);
|
||||
expect(verdict.errors.join(" ")).toMatch(/vehicle/i);
|
||||
});
|
||||
|
||||
it("rejects SELECT * (an empty/missing columns list, or a literal '*')", () => {
|
||||
const connector = new PostgresWatermarkConnector(fixtureQuery([]).query);
|
||||
expect(connector.validate({ ...CONFIG, columns: [] }).valid).toBe(false);
|
||||
expect(connector.validate({ ...CONFIG, columns: ["*"] }).valid).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts a well-formed config", () => {
|
||||
const connector = new PostgresWatermarkConnector(fixtureQuery([]).query);
|
||||
expect(connector.validate(CONFIG).valid).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("PostgresWatermarkConnector — watermark + limit correctness", () => {
|
||||
it("first read (no cursor) honours LIMIT and orders by (updated_at, id)", async () => {
|
||||
const { query } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const result = await connector.read({ partition_key: "dealer_stock_entry", limit: 2 });
|
||||
expect(result.records.map((r) => r.record_key)).toEqual(["a1", "a2"]);
|
||||
expect(result.exhausted).toBe(false); // 2 rows returned == limit, more may exist
|
||||
});
|
||||
|
||||
it("a same-updated_at tie at the page boundary is not skipped on the next page (the whole reason for the tuple WHERE)", async () => {
|
||||
const { query } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const page1 = await connector.read({ partition_key: "dealer_stock_entry", limit: 1 }); // just a1
|
||||
expect(page1.records.map((r) => r.record_key)).toEqual(["a1"]);
|
||||
const page2 = await connector.read({ partition_key: "dealer_stock_entry", cursor: page1.next_cursor, limit: 1 });
|
||||
// A naive `updated_at > $1` would skip a2 here (same updated_at as a1).
|
||||
expect(page2.records.map((r) => r.record_key)).toEqual(["a2"]);
|
||||
});
|
||||
|
||||
it("reads the full table across pages in strict watermark order, once per row", async () => {
|
||||
const { query } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
let cursor: string | undefined;
|
||||
const seen: string[] = [];
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const page = await connector.read({ partition_key: "dealer_stock_entry", cursor, limit: 2 });
|
||||
seen.push(...page.records.map((r) => r.record_key));
|
||||
cursor = page.next_cursor;
|
||||
if (page.exhausted) break;
|
||||
}
|
||||
expect(seen).toEqual(["a1", "a2", "a3", "a4"]);
|
||||
});
|
||||
|
||||
it("the empty-table case: zero rows, no throw, exhausted:true", async () => {
|
||||
const { query, calls } = fixtureQuery([]);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const result = await connector.read({ partition_key: "dealer_stock_entry", limit: 100 });
|
||||
expect(result.records).toEqual([]);
|
||||
expect(result.exhausted).toBe(true);
|
||||
expect(calls).toHaveLength(1); // the query WAS issued (a real SELECT against a real, currently-empty table) — it just returned nothing
|
||||
});
|
||||
});
|
||||
|
||||
describe("PostgresWatermarkConnector — checkpoint / resume", () => {
|
||||
it("checkpoint() reflects the in-session cursor after a read", async () => {
|
||||
const { query } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
await connector.read({ partition_key: "dealer_stock_entry", limit: 2 });
|
||||
const cp = await connector.checkpoint("dealer_stock_entry");
|
||||
const decoded = decodeCursor(cp.cursor);
|
||||
expect(decoded?.last_id).toBe("a2");
|
||||
expect(decoded?.last_updated_at).toBe("2026-09-01T00:00:00.000Z");
|
||||
expect(decoded?.checksum).toBe(checksumRows(ROWS.slice(0, 2)));
|
||||
});
|
||||
|
||||
it("resume() with a saved checkpoint continues exactly where the checkpoint left off", async () => {
|
||||
const { query } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const cursor = encodeCursor({ last_updated_at: "2026-09-02T00:00:00.000Z", last_id: "a3" });
|
||||
const result = await connector.resume(
|
||||
{ source_id: "s", tenant_id: "t", partition_key: "dealer_stock_entry", cursor, sequence: 3, records_committed: 3, committed_at: new Date().toISOString() },
|
||||
10,
|
||||
);
|
||||
expect(result.records.map((r) => r.record_key)).toEqual(["a4"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("PostgresWatermarkConnector — real Postgres driver value shapes", () => {
|
||||
it("a `timestamptz` column returned as a JS Date (not a string) is encoded as proper ISO-8601 in the cursor, not Date.toString()'s locale form", async () => {
|
||||
// Regression: caught by running this connector against a REAL Postgres
|
||||
// container (postgres.js hands back `timestamptz` as `Date`), not by any
|
||||
// fixture-only test — the fixtures elsewhere in this file all use plain
|
||||
// ISO strings, which never exercised this path. Reproduced here directly
|
||||
// instead of requiring Docker so the regression stays covered in CI.
|
||||
const rowsWithDates: SourceRow[] = [
|
||||
{ id: "a1", vehicle_id: "v1", updated_at: new Date("2026-09-01T00:00:00.000Z") },
|
||||
];
|
||||
const { query } = fixtureQuery(rowsWithDates.map((r) => ({ ...r, updated_at: (r.updated_at as Date).toISOString() })));
|
||||
// fixtureQuery's own row-compare logic needs string dates to sort; feed
|
||||
// it a Date-returning query instead so the connector genuinely sees a
|
||||
// Date object, the same as the real driver.
|
||||
const dateReturningQuery: QueryImpl = async (sql, params) => {
|
||||
const rows = await query(sql, params);
|
||||
return rows.map((r) => ({ ...r, updated_at: new Date(r.updated_at as string) }));
|
||||
};
|
||||
const connector = new PostgresWatermarkConnector(dateReturningQuery);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
const result = await connector.read({ partition_key: "dealer_stock_entry", limit: 10 });
|
||||
expect(result.records[0].occurred_at).toBe("2026-09-01T00:00:00.000Z");
|
||||
const decoded = decodeCursor(result.next_cursor);
|
||||
expect(decoded?.last_updated_at).toBe("2026-09-01T00:00:00.000Z");
|
||||
expect(decoded?.last_updated_at).not.toMatch(/GMT|\(.*\)/); // not Date.toString()'s form
|
||||
});
|
||||
});
|
||||
|
||||
describe("PostgresWatermarkConnector — never SELECT *", () => {
|
||||
it("every SQL statement the connector builds names the configured columns explicitly", async () => {
|
||||
const { query, calls } = fixtureQuery(ROWS);
|
||||
const connector = new PostgresWatermarkConnector(query);
|
||||
await connector.connect(CONFIG, { tenant_id: "t", project_id: "p", source_id: "s", run_id: "r" });
|
||||
await connector.read({ partition_key: "dealer_stock_entry", limit: 10 });
|
||||
for (const call of calls) {
|
||||
expect(call.sql).not.toMatch(/select\s+\*/i);
|
||||
expect(call.sql).toContain("id, vehicle_id, updated_at");
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,170 @@
|
||||
/**
|
||||
* CONTRACT test for src/clients/aud0-client.ts against AUD0's REAL wire
|
||||
* contract (sax3l/aud0 main `src/api/routes.ts` + `src/api/routes/
|
||||
* openlineage.ts`, verified 2026-08-31):
|
||||
*
|
||||
* POST /v1/aud0/events — snake_case evidence event
|
||||
* POST /v1/aud0/openlineage?tenant_id=&app_id= — OpenLineage RunEvent;
|
||||
* tenant_id is a QUERY PARAM (route contract), app_id defaults
|
||||
* "openlineage" server-side when omitted.
|
||||
*
|
||||
* /v1/aud0/lineage/events (the pre-rewrite path) does not exist on AUD0 and
|
||||
* never has — lineage ingest is OpenLineage-only. This test also pins the
|
||||
* legacy-shape → OpenLineage conversion.
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import {
|
||||
createAud0Client,
|
||||
legacyLineageToOpenLineage,
|
||||
type Aud0Event,
|
||||
type Aud0LineageEvent,
|
||||
} from "@/src/clients/aud0-client";
|
||||
import type { OpenLineageRunEvent } from "@/src/lineage/openlineage";
|
||||
import { startContractServer, type ContractServer } from "./contract-test-server";
|
||||
|
||||
let server: ContractServer | undefined;
|
||||
afterEach(async () => {
|
||||
await server?.close();
|
||||
server = undefined;
|
||||
});
|
||||
|
||||
function event(overrides: Partial<Aud0Event> = {}): Aud0Event {
|
||||
return {
|
||||
event_id: "evt_1",
|
||||
event_type: "0pt.dataset_registered",
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
actor_id: "svc_0pt",
|
||||
app_id: "0pt",
|
||||
capability_id: "0pt.register_dataset",
|
||||
resource_type: "dataset",
|
||||
resource_id: "ds_1",
|
||||
risk_level: "L2",
|
||||
created_at: "2026-08-31T12:00:00.000Z",
|
||||
correlation_id: "corr-1",
|
||||
purpose: "catalog",
|
||||
result: "success",
|
||||
output_refs: ["0pt:dataset:ds_1"],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("Aud0Client wire contract — events", () => {
|
||||
it("POSTs the snake_case evidence event to /v1/aud0/events with tenant/actor headers", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/v1/aud0/events", status: 201, respond: (r) => r.body as object },
|
||||
]);
|
||||
const client = createAud0Client(server.baseUrl);
|
||||
await client.ingestEvent(event());
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.path).toBe("/v1/aud0/events");
|
||||
expect(req.headers["x-tenant-id"]).toBe("t_test");
|
||||
expect(req.headers["x-actor-id"]).toBe("svc_0pt");
|
||||
const body = req.body as Record<string, unknown>;
|
||||
// §16 evidence-context fields ride on the wire.
|
||||
expect(body.event_type).toBe("0pt.dataset_registered");
|
||||
expect(body.capability_id).toBe("0pt.register_dataset");
|
||||
expect(body.risk_level).toBe("L2");
|
||||
expect(body.purpose).toBe("catalog");
|
||||
expect(body.result).toBe("success");
|
||||
expect(body.output_refs).toEqual(["0pt:dataset:ds_1"]);
|
||||
expect(body.correlation_id).toBe("corr-1");
|
||||
});
|
||||
|
||||
it("treats HTTP 200 (deduplicated idempotent replay) as success", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/v1/aud0/events", status: 200, respond: () => ({ deduplicated: true }) },
|
||||
]);
|
||||
const client = createAud0Client(server.baseUrl);
|
||||
await expect(client.ingestEvent(event())).resolves.toBeTruthy();
|
||||
});
|
||||
});
|
||||
|
||||
describe("Aud0Client wire contract — OpenLineage lineage ingest", () => {
|
||||
const runEvent: OpenLineageRunEvent = {
|
||||
eventType: "COMPLETE",
|
||||
eventTime: "2026-08-31T12:00:00.000Z",
|
||||
producer: "https://git.siax.io/sax3l/0pt",
|
||||
run: { runId: "run-1" },
|
||||
job: { namespace: "0pt", name: "0pt.dataset.version.v1" },
|
||||
inputs: [{ namespace: "0pt", name: "source/src_1" }],
|
||||
outputs: [{ namespace: "0pt", name: "dataset/ds_1" }],
|
||||
};
|
||||
|
||||
it("POSTs the RunEvent to /v1/aud0/openlineage with tenant_id + app_id as QUERY PARAMS", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/aud0/openlineage",
|
||||
status: 201,
|
||||
respond: () => ({ tenant_id: "t_test", run_id: "run-1", job: "0pt/0pt.dataset.version.v1", event_id: "evt_ol_1" }),
|
||||
},
|
||||
]);
|
||||
const client = createAud0Client(server.baseUrl);
|
||||
const ack = await client.ingestOpenLineageEvent("t_test", "0pt", runEvent);
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.path).toBe("/v1/aud0/openlineage");
|
||||
expect(req.query).toEqual({ tenant_id: "t_test", app_id: "0pt" });
|
||||
const body = req.body as Record<string, unknown>;
|
||||
expect(body.eventType).toBe("COMPLETE");
|
||||
expect((body.run as { runId: string }).runId).toBe("run-1");
|
||||
expect((body.job as { namespace: string; name: string })).toEqual({
|
||||
namespace: "0pt",
|
||||
name: "0pt.dataset.version.v1",
|
||||
});
|
||||
expect(ack.event_id).toBe("evt_ol_1");
|
||||
});
|
||||
|
||||
it("legacy shim: ingestLineageEvent converts to OpenLineage and hits /v1/aud0/openlineage (never /v1/aud0/lineage/events)", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/aud0/openlineage",
|
||||
status: 201,
|
||||
respond: () => ({ tenant_id: "t_test", run_id: "lin_1", job: "0pt/0pt.write", event_id: "evt_ol_2" }),
|
||||
},
|
||||
]);
|
||||
const client = createAud0Client(server.baseUrl);
|
||||
const legacy: Aud0LineageEvent = {
|
||||
lineage_event_id: "lin_1",
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
app_id: "0pt",
|
||||
capability_id: "0pt.write",
|
||||
source_type: "external_record",
|
||||
source_id: "idem-1",
|
||||
target_type: "external_id",
|
||||
target_id: "ext_1",
|
||||
lineage_type: "produced",
|
||||
created_at: "2026-08-31T12:00:00.000Z",
|
||||
correlation_id: "corr-1",
|
||||
};
|
||||
await client.ingestLineageEvent(legacy);
|
||||
|
||||
expect(server.requests).toHaveLength(1);
|
||||
expect(server.requests[0].path).toBe("/v1/aud0/openlineage");
|
||||
const body = server.requests[0].body as OpenLineageRunEvent;
|
||||
expect(body.run.runId).toBe("lin_1"); // deterministic → AUD0 dedup key stable
|
||||
expect(body.inputs?.[0]?.name).toBe("external_record/idem-1");
|
||||
expect(body.outputs?.[0]?.name).toBe("external_id/ext_1");
|
||||
});
|
||||
|
||||
it("conversion is deterministic (same legacy event → identical RunEvent)", () => {
|
||||
const legacy: Aud0LineageEvent = {
|
||||
lineage_event_id: "lin_x",
|
||||
tenant_id: "t",
|
||||
project_id: "p",
|
||||
app_id: "0pt",
|
||||
capability_id: "cap",
|
||||
source_type: "a",
|
||||
source_id: "1",
|
||||
target_type: "b",
|
||||
target_id: "2",
|
||||
lineage_type: "derived_from",
|
||||
created_at: "2026-08-31T00:00:00.000Z",
|
||||
};
|
||||
expect(legacyLineageToOpenLineage(legacy)).toEqual(legacyLineageToOpenLineage({ ...legacy }));
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,170 @@
|
||||
/**
|
||||
* CONTRACT test for src/clients/cl0ud-client.ts against CL0UD's REAL wire
|
||||
* contract (sax3l/cl0ud main — policy evaluate + capability discovery,
|
||||
* verified 2026-08-31):
|
||||
*
|
||||
* POST /api/policy/evaluate — camelCase body, `{ data, meta }` envelope,
|
||||
* decision ∈ {allow, deny} + requiresApproval flag.
|
||||
* GET /api/capabilities — capability-registry discovery.
|
||||
*
|
||||
* The pre-rewrite client POSTed snake_case to /v1/cl0ud/policies/evaluate —
|
||||
* a path that never existed on CL0UD. Policy stays FAIL-CLOSED: missing or
|
||||
* malformed decision reads as deny.
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { createCl0udClient, type EvaluatePolicyInput } from "@/src/clients/cl0ud-client";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { startContractServer, type ContractServer } from "./contract-test-server";
|
||||
|
||||
let server: ContractServer | undefined;
|
||||
afterEach(async () => {
|
||||
await server?.close();
|
||||
server = undefined;
|
||||
});
|
||||
|
||||
function input(overrides: Partial<EvaluatePolicyInput> = {}): EvaluatePolicyInput {
|
||||
return {
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
actor_id: "svc_0pt",
|
||||
capability_id: "0pt.write_external_record",
|
||||
resource_type: "external_record",
|
||||
resource_id: "rec_1",
|
||||
risk_level: "L4",
|
||||
correlation_id: "corr-1",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("Cl0udClient wire contract — policy evaluate", () => {
|
||||
it("POSTs the REAL camelCase body to /api/policy/evaluate and maps the {data} envelope", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/api/policy/evaluate",
|
||||
status: 200,
|
||||
respond: () => ({
|
||||
data: {
|
||||
decision: "allow",
|
||||
requiresApproval: false,
|
||||
auditRequired: true,
|
||||
riskLevel: "L4",
|
||||
decisionId: "pdec_r3al",
|
||||
reason: "rbac_ok",
|
||||
},
|
||||
meta: {},
|
||||
}),
|
||||
},
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
const decision = await client.evaluatePolicy(input());
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.path).toBe("/api/policy/evaluate");
|
||||
const body = req.body as Record<string, unknown>;
|
||||
expect(body.capability).toBe("0pt.write_external_record");
|
||||
expect(body.tenantId).toBe("t_test");
|
||||
expect(body.projectId).toBe("p_test");
|
||||
expect(body.actor).toEqual({ kind: "operator", role: "member" });
|
||||
expect(body.surface).toBe("api");
|
||||
expect(body.resource).toEqual({ type: "external_record", id: "rec_1" });
|
||||
expect(body.correlationId).toBe("corr-1");
|
||||
// Invented pre-rewrite fields must NOT be on the wire.
|
||||
expect(body.capability_id).toBeUndefined();
|
||||
expect(body.tenant_id).toBeUndefined();
|
||||
expect(body.risk_level).toBeUndefined();
|
||||
|
||||
expect(decision).toEqual({
|
||||
decision: "allow",
|
||||
decision_id: "pdec_r3al",
|
||||
reason: "rbac_ok",
|
||||
deny_code: undefined,
|
||||
});
|
||||
});
|
||||
|
||||
it("maps allow + requiresApproval=true onto 0pt's approval_required (gates the caller)", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/api/policy/evaluate",
|
||||
status: 200,
|
||||
respond: () => ({ data: { decision: "allow", requiresApproval: true, decisionId: "pdec_a" }, meta: {} }),
|
||||
},
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
const decision = await client.evaluatePolicy(input());
|
||||
expect(decision.decision).toBe("approval_required");
|
||||
});
|
||||
|
||||
it("maps deny with denyCode", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/api/policy/evaluate",
|
||||
status: 200,
|
||||
respond: () => ({
|
||||
data: { decision: "deny", requiresApproval: false, decisionId: "pdec_d", denyCode: "rbac_forbidden" },
|
||||
meta: {},
|
||||
}),
|
||||
},
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
const decision = await client.evaluatePolicy(input());
|
||||
expect(decision.decision).toBe("deny");
|
||||
expect(decision.deny_code).toBe("rbac_forbidden");
|
||||
});
|
||||
|
||||
it("FAILS CLOSED: 200 with a body missing `decision` is a deny, never an allow", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/api/policy/evaluate", status: 200, respond: () => ({ data: {}, meta: {} }) },
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
const decision = await client.evaluatePolicy(input());
|
||||
expect(decision.decision).toBe("deny");
|
||||
});
|
||||
|
||||
it("FAILS CLOSED: CL0UD unreachable → SiaxError, never an implicit allow (§52)", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/api/policy/evaluate", status: 503, respond: () => ({ error: { code: "DOWN" } }) },
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
try {
|
||||
await client.evaluatePolicy(input());
|
||||
expect.unreachable("must throw");
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(SiaxError);
|
||||
expect((err as SiaxError).code).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("Cl0udClient wire contract — capability discovery", () => {
|
||||
it("GETs /api/capabilities with filters and returns the data array", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "GET",
|
||||
path: "/api/capabilities",
|
||||
status: 200,
|
||||
respond: () => ({
|
||||
data: [
|
||||
{
|
||||
name: "0pt.search.query",
|
||||
version: "1.0.0",
|
||||
owner: "0pt",
|
||||
status: "active",
|
||||
requiredEntitlement: "0pt.search",
|
||||
surfaces: ["api"],
|
||||
},
|
||||
],
|
||||
meta: { total: 1 },
|
||||
}),
|
||||
},
|
||||
]);
|
||||
const client = createCl0udClient(server.baseUrl);
|
||||
const caps = await client.listCapabilities({ owner: "0pt", status: "active" });
|
||||
expect(server.requests[0].query).toEqual({ owner: "0pt", status: "active" });
|
||||
expect(caps).toHaveLength(1);
|
||||
expect(caps[0].name).toBe("0pt.search.query");
|
||||
expect(caps[0].requiredEntitlement).toBe("0pt.search");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,86 @@
|
||||
/**
|
||||
* tests/contracts/contract-test-server.ts
|
||||
* ========================================
|
||||
* In-process HTTP provider double for the per-client CONTRACT tests
|
||||
* (Master-DoD §10 "Contract tests finns", §50 Contract level).
|
||||
*
|
||||
* NOT a mock of 0pt's clients — a recording provider that answers with
|
||||
* response bodies shaped EXACTLY like the sibling services' real handlers
|
||||
* (verified against sax3l/st0re, sax3l/aud0, sax3l/n0d, sax3l/cl0ud main
|
||||
* this session). Each test asserts the REQUEST the client actually put on
|
||||
* the wire: path, method, headers (tenant/actor/context propagation,
|
||||
* idempotency), and body field names. That is the drift alarm: if a client
|
||||
* regresses to its pre-2026-08-31 invented wire shapes, these tests fail.
|
||||
*/
|
||||
import http from "node:http";
|
||||
import type { AddressInfo } from "node:net";
|
||||
|
||||
export interface RecordedRequest {
|
||||
method: string;
|
||||
/** Path WITHOUT query string. */
|
||||
path: string;
|
||||
/** Raw query params. */
|
||||
query: Record<string, string>;
|
||||
headers: http.IncomingHttpHeaders;
|
||||
body: unknown;
|
||||
}
|
||||
|
||||
export interface ContractRoute {
|
||||
method: string;
|
||||
/** Exact path to match (no query). */
|
||||
path: string;
|
||||
status: number;
|
||||
/** Response body factory — receives the recorded request. */
|
||||
respond: (req: RecordedRequest) => unknown;
|
||||
}
|
||||
|
||||
export interface ContractServer {
|
||||
baseUrl: string;
|
||||
requests: RecordedRequest[];
|
||||
close(): Promise<void>;
|
||||
}
|
||||
|
||||
export async function startContractServer(routes: ContractRoute[]): Promise<ContractServer> {
|
||||
const requests: RecordedRequest[] = [];
|
||||
|
||||
const server = http.createServer((req, res) => {
|
||||
const chunks: Buffer[] = [];
|
||||
req.on("data", (c: Buffer) => chunks.push(c));
|
||||
req.on("end", () => {
|
||||
const url = new URL(req.url ?? "/", "http://localhost");
|
||||
const raw = Buffer.concat(chunks).toString("utf8");
|
||||
let body: unknown;
|
||||
try {
|
||||
body = raw ? JSON.parse(raw) : undefined;
|
||||
} catch {
|
||||
body = raw;
|
||||
}
|
||||
const recorded: RecordedRequest = {
|
||||
method: req.method ?? "GET",
|
||||
path: url.pathname,
|
||||
query: Object.fromEntries(url.searchParams.entries()),
|
||||
headers: req.headers,
|
||||
body,
|
||||
};
|
||||
requests.push(recorded);
|
||||
|
||||
const route = routes.find((r) => r.method === recorded.method && r.path === recorded.path);
|
||||
if (!route) {
|
||||
res.writeHead(404, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify({ error: { code: "NOT_FOUND", message: `no contract route ${recorded.method} ${recorded.path}` } }));
|
||||
return;
|
||||
}
|
||||
res.writeHead(route.status, { "Content-Type": "application/json" });
|
||||
res.end(JSON.stringify(route.respond(recorded)));
|
||||
});
|
||||
});
|
||||
|
||||
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
|
||||
const { port } = server.address() as AddressInfo;
|
||||
|
||||
return {
|
||||
baseUrl: `http://127.0.0.1:${port}`,
|
||||
requests,
|
||||
close: () => new Promise<void>((resolve, reject) => server.close((e) => (e ? reject(e) : resolve()))),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
/**
|
||||
* Master-DoD §3/§10: "Production kan ALDRIG tyst falla tillbaka till
|
||||
* mock/in-memory — fail hard med DEPENDENCY_UNAVAILABLE."
|
||||
*
|
||||
* These tests drive every client factory (and the store-mode resolver) in a
|
||||
* production runtime with the dependency unconfigured and assert the HARD
|
||||
* throw at construction time — plus the non-production behaviour that keeps
|
||||
* unit tests hermetic.
|
||||
*/
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { resolveDependencyBaseUrl, resolveStoreMode } from "@/src/platform/dependency-mode";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { createCl0udClient } from "@/src/clients/cl0ud-client";
|
||||
import { createSt0reClient } from "@/src/clients/st0re-client";
|
||||
import { createN0dClient } from "@/src/clients/n0d-client";
|
||||
import { createAud0Client } from "@/src/clients/aud0-client";
|
||||
|
||||
const PROD = { NODE_ENV: "production" } as NodeJS.ProcessEnv;
|
||||
const DEV = { NODE_ENV: "test" } as NodeJS.ProcessEnv;
|
||||
|
||||
describe("resolveDependencyBaseUrl (the §3 kill switch)", () => {
|
||||
it("production + unconfigured => throws SiaxError DEPENDENCY_UNAVAILABLE", () => {
|
||||
try {
|
||||
resolveDependencyBaseUrl("st0re", undefined, PROD);
|
||||
expect.unreachable("must throw");
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(SiaxError);
|
||||
expect((err as SiaxError).code).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
expect((err as SiaxError).source).toBe("st0re");
|
||||
}
|
||||
});
|
||||
|
||||
it("production + empty string => throws (whitespace is not a configuration)", () => {
|
||||
expect(() => resolveDependencyBaseUrl("aud0", " ", PROD)).toThrowError(SiaxError);
|
||||
});
|
||||
|
||||
it("non-production + unconfigured => undefined (mock allowed for tests/dev only)", () => {
|
||||
expect(resolveDependencyBaseUrl("n0d", undefined, DEV)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("configured => normalized URL in any runtime (trailing slashes stripped)", () => {
|
||||
expect(resolveDependencyBaseUrl("cl0ud", "https://x.example.com///", PROD)).toBe("https://x.example.com");
|
||||
});
|
||||
|
||||
it("the Next BUILD phase is not a production runtime (page-data collection must compile; the guard re-arms at boot)", () => {
|
||||
const BUILD = { NODE_ENV: "production", NEXT_PHASE: "phase-production-build" } as NodeJS.ProcessEnv;
|
||||
expect(resolveDependencyBaseUrl("st0re", undefined, BUILD)).toBeUndefined();
|
||||
// Any other phase value stays armed.
|
||||
const SERVE = { NODE_ENV: "production", NEXT_PHASE: "phase-production-server" } as NodeJS.ProcessEnv;
|
||||
expect(() => resolveDependencyBaseUrl("st0re", undefined, SERVE)).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
describe("resolveStoreMode (§3 for stateful registries)", () => {
|
||||
it("production + no database => throws DEPENDENCY_UNAVAILABLE", () => {
|
||||
expect(() => resolveStoreMode("0pt.source_registry", undefined, PROD)).toThrowError(SiaxError);
|
||||
});
|
||||
it("non-production + no database => explicit memory mode", () => {
|
||||
expect(resolveStoreMode("0pt.source_registry", undefined, DEV)).toEqual({ mode: "memory" });
|
||||
});
|
||||
it("database configured => postgres mode", () => {
|
||||
expect(resolveStoreMode("x", "postgres://u@h/db", PROD)).toEqual({ mode: "postgres", url: "postgres://u@h/db" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("client factories under NODE_ENV=production without a base URL", () => {
|
||||
// The factories read process.env.NODE_ENV via isProductionRuntime; drive it
|
||||
// for real, restoring afterwards.
|
||||
function inProduction<T>(fn: () => T): T {
|
||||
const prev = process.env.NODE_ENV;
|
||||
const prevUrls = {
|
||||
CL0UD_URL: process.env.CL0UD_URL,
|
||||
ST0RE_URL: process.env.ST0RE_URL,
|
||||
N0D_URL: process.env.N0D_URL,
|
||||
AUD0_URL: process.env.AUD0_URL,
|
||||
};
|
||||
delete process.env.CL0UD_URL;
|
||||
delete process.env.ST0RE_URL;
|
||||
delete process.env.N0D_URL;
|
||||
delete process.env.AUD0_URL;
|
||||
(process.env as Record<string, string>).NODE_ENV = "production";
|
||||
try {
|
||||
return fn();
|
||||
} finally {
|
||||
if (prev === undefined) delete (process.env as Record<string, string | undefined>).NODE_ENV;
|
||||
else (process.env as Record<string, string>).NODE_ENV = prev;
|
||||
for (const [k, v] of Object.entries(prevUrls)) {
|
||||
if (v === undefined) delete process.env[k];
|
||||
else process.env[k] = v;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
it("createCl0udClient() fails hard (policy may NEVER silently allow via local pass-through)", () => {
|
||||
inProduction(() => expect(() => createCl0udClient()).toThrowError(SiaxError));
|
||||
});
|
||||
it("createSt0reClient() fails hard", () => {
|
||||
inProduction(() => expect(() => createSt0reClient()).toThrowError(SiaxError));
|
||||
});
|
||||
it("createN0dClient() fails hard", () => {
|
||||
inProduction(() => expect(() => createN0dClient()).toThrowError(SiaxError));
|
||||
});
|
||||
it("createAud0Client() fails hard", () => {
|
||||
inProduction(() => expect(() => createAud0Client()).toThrowError(SiaxError));
|
||||
});
|
||||
|
||||
it("all four factories still return local implementations in a test runtime", () => {
|
||||
expect(createCl0udClient()).toBeTruthy();
|
||||
expect(createSt0reClient()).toBeTruthy();
|
||||
expect(createN0dClient()).toBeTruthy();
|
||||
expect(createAud0Client()).toBeTruthy();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,182 @@
|
||||
/**
|
||||
* Contract tests for the OpenMetadata projection adapter and the Feast
|
||||
* online-features adapter (Master-DoD §10 Metadata + Feature capability)
|
||||
* against recording provider doubles. These pin the wire shapes; they do NOT
|
||||
* claim INTEGRATION_TESTED status (no live OM/Feast in this pass — see
|
||||
* STATUS.md).
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { OpenMetadataAdapter, MetadataProjectionService } from "@/src/metadata/openmetadata-adapter";
|
||||
import { FeatureService } from "@/src/features/feast-adapter";
|
||||
import { createN0dClient } from "@/src/clients/n0d-client";
|
||||
import type { Dataset } from "@/src/types/dataset";
|
||||
import { startContractServer, type ContractServer } from "./contract-test-server";
|
||||
|
||||
let server: ContractServer | undefined;
|
||||
afterEach(async () => {
|
||||
await server?.close();
|
||||
server = undefined;
|
||||
});
|
||||
|
||||
const DATASET: Dataset = {
|
||||
dataset_id: "ds_companies",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_1",
|
||||
name: "Companies",
|
||||
dataset_type: "curated",
|
||||
status: "active",
|
||||
created_at: "2026-08-31T00:00:00.000Z",
|
||||
};
|
||||
|
||||
describe("OpenMetadata projection adapter (projection, never canonical)", () => {
|
||||
it("PUTs a createOrUpdate table entity to /api/v1/tables with the projection disclaimer", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "PUT", path: "/api/v1/tables", status: 200, respond: (r) => r.body as object },
|
||||
]);
|
||||
const adapter = new OpenMetadataAdapter({ baseUrl: server.baseUrl, token: "om-bot-token" });
|
||||
const projection = new MetadataProjectionService(adapter, "0pt.default.datasets");
|
||||
await projection.projectDataset(DATASET);
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.method).toBe("PUT");
|
||||
expect(req.headers.authorization).toBe("Bearer om-bot-token");
|
||||
const body = req.body as Record<string, unknown>;
|
||||
expect(body.name).toBe("ds_companies");
|
||||
expect(body.databaseSchema).toBe("0pt.default.datasets");
|
||||
expect(String(body.description)).toContain("PROJECTION");
|
||||
expect(String(body.description)).toContain("0pt:dataset:ds_companies");
|
||||
expect(Array.isArray(body.columns)).toBe(true);
|
||||
});
|
||||
|
||||
it("projectAll (the §42 rebuild path) collects per-dataset failures instead of aborting", async () => {
|
||||
let calls = 0;
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "PUT",
|
||||
path: "/api/v1/tables",
|
||||
status: 200,
|
||||
respond: (r) => {
|
||||
calls++;
|
||||
if ((r.body as { name?: string }).name === "ds_broken") {
|
||||
// The double can't vary status per call; throwing here simulates a body-level failure path
|
||||
// via a 200-with-garbage that the adapter tolerates, so use a separate route trick instead.
|
||||
}
|
||||
return r.body as object;
|
||||
},
|
||||
},
|
||||
]);
|
||||
const adapter = new OpenMetadataAdapter({ baseUrl: server.baseUrl });
|
||||
const projection = new MetadataProjectionService(adapter);
|
||||
const result = await projection.projectAll(
|
||||
[DATASET, { ...DATASET, dataset_id: "ds_two" }],
|
||||
new Map()
|
||||
);
|
||||
expect(calls).toBe(2);
|
||||
expect(result.projected).toBe(2);
|
||||
expect(result.failures).toEqual([]);
|
||||
});
|
||||
|
||||
it("an unreachable OpenMetadata surfaces as a per-dataset failure in projectAll (projection loss ≠ crash)", async () => {
|
||||
const adapter = new OpenMetadataAdapter({ baseUrl: "http://127.0.0.1:9", timeoutMs: 300 });
|
||||
const projection = new MetadataProjectionService(adapter);
|
||||
const result = await projection.projectAll([DATASET], new Map());
|
||||
expect(result.projected).toBe(0);
|
||||
expect(result.failures).toHaveLength(1);
|
||||
expect(result.failures[0].dataset_id).toBe("ds_companies");
|
||||
});
|
||||
});
|
||||
|
||||
describe("Feast adapter (online path wire contract + delegation contracts)", () => {
|
||||
function registeredService(feastUrl?: string) {
|
||||
const svc = new FeatureService({ feastServerUrl: feastUrl, n0dClient: createN0dClient() });
|
||||
svc.registerFeatureView({
|
||||
feature_view: "company_stats",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_1",
|
||||
entities: ["org_nr"],
|
||||
features: [{ name: "employee_count", dtype: "int64" }],
|
||||
source_dataset_ref: "0pt:dataset:ds_companies",
|
||||
});
|
||||
return svc;
|
||||
}
|
||||
|
||||
it("POSTs Feast's documented get-online-features body (view:feature refs + entities)", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/get-online-features",
|
||||
status: 200,
|
||||
respond: () => ({
|
||||
metadata: { feature_names: ["org_nr", "employee_count"] },
|
||||
results: [
|
||||
{ values: ["5560360793"], statuses: ["PRESENT"] },
|
||||
{ values: [1000], statuses: ["PRESENT"] },
|
||||
],
|
||||
}),
|
||||
},
|
||||
]);
|
||||
const svc = registeredService(server.baseUrl);
|
||||
const res = await svc.getOnlineFeatures({
|
||||
tenant_id: "t_a",
|
||||
feature_view: "company_stats",
|
||||
features: ["employee_count"],
|
||||
entities: { org_nr: ["5560360793"] },
|
||||
});
|
||||
const body = server.requests[0].body as Record<string, unknown>;
|
||||
expect(body.features).toEqual(["company_stats:employee_count"]);
|
||||
expect(body.entities).toEqual({ org_nr: ["5560360793"] });
|
||||
expect(res.feature_names).toContain("employee_count");
|
||||
});
|
||||
|
||||
it("registry versioning: re-registering a view bumps its version and keeps history", () => {
|
||||
const svc = registeredService();
|
||||
const v2 = svc.registerFeatureView({
|
||||
feature_view: "company_stats",
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_1",
|
||||
entities: ["org_nr"],
|
||||
features: [
|
||||
{ name: "employee_count", dtype: "int64" },
|
||||
{ name: "revenue", dtype: "float64" },
|
||||
],
|
||||
source_dataset_ref: "0pt:dataset:ds_companies",
|
||||
});
|
||||
expect(v2.version).toBe(2);
|
||||
expect(svc.getFeatureViewVersions("t_a", "company_stats").map((v) => v.version)).toEqual([1, 2]);
|
||||
// Tenant gate.
|
||||
expect(() => svc.getFeatureView("t_b", "company_stats")).toThrowError(/not found/);
|
||||
});
|
||||
|
||||
it("materialize/get-historical are N0D delegation contracts, never local fakes", async () => {
|
||||
const svc = registeredService();
|
||||
const job = await svc.materialize({
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_1",
|
||||
feature_view: "company_stats",
|
||||
start_time: "2026-08-01T00:00:00Z",
|
||||
end_time: "2026-08-31T00:00:00Z",
|
||||
});
|
||||
expect(job.job_type).toBe("0pt.features.materialize");
|
||||
|
||||
const hist = await svc.getHistorical({
|
||||
tenant_id: "t_a",
|
||||
project_id: "p_1",
|
||||
feature_view: "company_stats",
|
||||
features: ["employee_count"],
|
||||
entity_df_artifact_ref: "st0re:artifact:art_entities",
|
||||
});
|
||||
expect(hist.job_type).toBe("0pt.features.get_historical");
|
||||
});
|
||||
|
||||
it("online path without a configured Feast server fails hard (no silent fake features)", async () => {
|
||||
const svc = registeredService();
|
||||
await expect(
|
||||
svc.getOnlineFeatures({
|
||||
tenant_id: "t_a",
|
||||
feature_view: "company_stats",
|
||||
features: ["employee_count"],
|
||||
entities: { org_nr: ["1"] },
|
||||
})
|
||||
).rejects.toMatchObject({ code: "DEPENDENCY_UNAVAILABLE" });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,209 @@
|
||||
/**
|
||||
* CONTRACT test for src/clients/n0d-client.ts against N0D's REAL wire
|
||||
* contract (sax3l/n0d main `src/api/schemas.ts` createJobSchema +
|
||||
* `src/api/mappers.ts` + job-lifecycle routes, verified 2026-08-31):
|
||||
*
|
||||
* POST /v1/n0d/jobs (202) — generic job creation (n0dCreateJob)
|
||||
* POST /v1/n0d/quality/run (202) — data-quality delegation (n0dRunDataQuality)
|
||||
* GET /v1/n0d/jobs/:id
|
||||
* GET /v1/n0d/jobs/:id/result
|
||||
*
|
||||
* The pre-2026-08-31 client sent required_node_roles[]/resource_profile/
|
||||
* output_artifact_type/risk_level — fields N0D's createJobSchema does not
|
||||
* accept. This test pins the mapped wire shape.
|
||||
*
|
||||
* P-001 (owner-seam): 0pt delegates quality to N0D via n0dRunDataQuality
|
||||
* (POST /v1/n0d/quality/run), NOT the generic createJob. N0D OWNS quality
|
||||
* execution; 0pt only requests it.
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import {
|
||||
createN0dClient,
|
||||
resolveRequiredRole,
|
||||
resolveResourceRequirements,
|
||||
type N0dCreateJobInput,
|
||||
type RunDataQualityInput,
|
||||
} from "@/src/clients/n0d-client";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { startContractServer, type ContractServer } from "./contract-test-server";
|
||||
|
||||
let server: ContractServer | undefined;
|
||||
afterEach(async () => {
|
||||
await server?.close();
|
||||
server = undefined;
|
||||
});
|
||||
|
||||
function input(overrides: Partial<N0dCreateJobInput> = {}): N0dCreateJobInput {
|
||||
return {
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
job_type: "0pt.quality.run",
|
||||
capability_id: "0pt.quality.run.v1",
|
||||
requested_by_app_id: "0pt",
|
||||
requested_by_actor_id: "svc_0pt",
|
||||
input_artifact_ids: ["art_in_1"],
|
||||
output_artifact_type: "quality_result",
|
||||
requires_backbone: false,
|
||||
requires_gpu: false,
|
||||
required_node_roles: ["compute_general"],
|
||||
resource_profile: "standard",
|
||||
risk_level: "L2",
|
||||
correlation_id: "corr-7",
|
||||
idempotency_key: "idem-job-1",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
const WIRE_JOB = {
|
||||
job_id: "job_r3al",
|
||||
job_type: "0pt.quality.run",
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
status: "queued",
|
||||
capability_id: "0pt.quality.run.v1",
|
||||
created_at: "2026-08-31T12:00:00.000Z",
|
||||
};
|
||||
|
||||
describe("N0dClient wire contract", () => {
|
||||
it("POSTs the REAL createJob body to /v1/n0d/jobs and accepts the 202", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/v1/n0d/jobs", status: 202, respond: () => WIRE_JOB },
|
||||
]);
|
||||
const client = createN0dClient(server.baseUrl);
|
||||
const job = await client.createJob(input());
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.method).toBe("POST");
|
||||
expect(req.path).toBe("/v1/n0d/jobs");
|
||||
expect(req.headers["x-tenant-id"]).toBe("t_test");
|
||||
|
||||
const body = req.body as Record<string, unknown>;
|
||||
// Required fields per createJobSchema.
|
||||
expect(body.job_type).toBe("0pt.quality.run");
|
||||
expect(body.capability_id).toBe("0pt.quality.run.v1");
|
||||
expect(body.tenant_id).toBe("t_test");
|
||||
expect(body.required_role).toBe("compute_general");
|
||||
expect(body.resource_requirements).toEqual({ cpu: 2, memory_gb: 4, gpu: 0, disk_gb: 10 });
|
||||
// Mapped optionals.
|
||||
expect(body.app_id).toBe("0pt");
|
||||
expect(body.requested_by).toBe("svc_0pt");
|
||||
expect(body.priority).toBe("normal");
|
||||
expect(body.requires_shared_backbone).toBe(false);
|
||||
expect(body.input).toEqual({ artifact_ids: ["art_in_1"] });
|
||||
expect(body.output_policy).toEqual({ write_to_st0re: true, artifact_type: "quality_result" });
|
||||
expect(body.idempotency_key).toBe("idem-job-1");
|
||||
expect(body.correlation_id).toBe("corr-7");
|
||||
// Legacy invented fields must NOT be on the wire.
|
||||
expect(body.required_node_roles).toBeUndefined();
|
||||
expect(body.resource_profile).toBeUndefined();
|
||||
expect(body.output_artifact_type).toBeUndefined();
|
||||
expect(body.risk_level).toBeUndefined();
|
||||
expect(body.requested_by_app_id).toBeUndefined();
|
||||
|
||||
expect(job.job_id).toBe("job_r3al");
|
||||
expect(job.status).toBe("queued");
|
||||
});
|
||||
|
||||
it("GETs job + result with tenant header (poll path)", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "GET", path: "/v1/n0d/jobs/job_r3al", status: 200, respond: () => ({ ...WIRE_JOB, status: "completed" }) },
|
||||
{
|
||||
method: "GET",
|
||||
path: "/v1/n0d/jobs/job_r3al/result",
|
||||
status: 200,
|
||||
respond: () => ({
|
||||
job_id: "job_r3al",
|
||||
outcome: "succeeded",
|
||||
output_artifacts: [{ st0re_artifact_id: "art_out_1", artifact_type: "quality_result" }],
|
||||
}),
|
||||
},
|
||||
]);
|
||||
const client = createN0dClient(server.baseUrl);
|
||||
|
||||
const job = await client.getJob("job_r3al", "t_test");
|
||||
expect(job.status).toBe("completed");
|
||||
const result = await client.getJobResult("job_r3al", "t_test");
|
||||
expect(result.outcome).toBe("succeeded");
|
||||
expect(result.output_artifacts?.[0]?.st0re_artifact_id).toBe("art_out_1");
|
||||
|
||||
for (const req of server.requests) {
|
||||
expect(req.headers["x-tenant-id"]).toBe("t_test");
|
||||
}
|
||||
});
|
||||
|
||||
it("role/resource inference: requires_gpu forces ai_gpu + a GPU profile", () => {
|
||||
const gpuInput = input({ requires_gpu: true, required_node_roles: [], resource_profile: "standard" });
|
||||
expect(resolveRequiredRole(gpuInput)).toBe("ai_gpu");
|
||||
expect(resolveResourceRequirements(gpuInput).gpu).toBeGreaterThan(0);
|
||||
// Explicit values always win.
|
||||
const explicit = input({
|
||||
required_role: "storage",
|
||||
resource_requirements: { cpu: 1, memory_gb: 1, disk_gb: 1 },
|
||||
});
|
||||
expect(resolveRequiredRole(explicit)).toBe("storage");
|
||||
expect(resolveResourceRequirements(explicit)).toEqual({ cpu: 1, memory_gb: 1, disk_gb: 1 });
|
||||
});
|
||||
|
||||
it("maps a 404 (foreign-tenant probe / unknown job) to SiaxError NOT_FOUND", async () => {
|
||||
server = await startContractServer([]);
|
||||
const client = createN0dClient(server.baseUrl);
|
||||
try {
|
||||
await client.getJob("job_foreign", "t_other");
|
||||
expect.unreachable("must throw");
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(SiaxError);
|
||||
expect((err as SiaxError).code).toBe("NOT_FOUND");
|
||||
}
|
||||
});
|
||||
|
||||
it("P-001: runDataQuality POSTs to /v1/n0d/quality/run with dataset_id + quality_rule_set_id", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/v1/n0d/quality/run", status: 202, respond: () => WIRE_JOB },
|
||||
]);
|
||||
const client = createN0dClient(server.baseUrl);
|
||||
const runInput: RunDataQualityInput = {
|
||||
tenant_id: "t_test",
|
||||
dataset_id: "ds_1",
|
||||
quality_rule_set_id: "rs_1",
|
||||
project_id: "p_test",
|
||||
run_inline: { dataset_csv: "a,b\n1,2", rules: [{ expectation: "expect_column_to_exist", column: "a" }] },
|
||||
idempotency_key: "dq:ds_1:latest:dqrun_",
|
||||
};
|
||||
const job = await client.runDataQuality(runInput);
|
||||
|
||||
const req = server.requests[0];
|
||||
expect(req.method).toBe("POST");
|
||||
expect(req.path).toBe("/v1/n0d/quality/run");
|
||||
expect(req.headers["x-tenant-id"]).toBe("t_test");
|
||||
const body = req.body as Record<string, unknown>;
|
||||
expect(body.tenant_id).toBe("t_test");
|
||||
expect(body.dataset_id).toBe("ds_1");
|
||||
expect(body.quality_rule_set_id).toBe("rs_1");
|
||||
expect(body.run_inline).toBeDefined();
|
||||
expect(body.job_type).toBeUndefined();
|
||||
expect(body.capability_id).toBeUndefined();
|
||||
expect(body.required_role).toBeUndefined();
|
||||
expect(body.resource_requirements).toBeUndefined();
|
||||
expect(body.idempotency_key).toBe("dq:ds_1:latest:dqrun_");
|
||||
expect(job.job_id).toBe("job_r3al");
|
||||
});
|
||||
|
||||
it("P-001: runDataQuality without run_inline is enqueue-only (no fabricated result)", async () => {
|
||||
server = await startContractServer([
|
||||
{ method: "POST", path: "/v1/n0d/quality/run", status: 202, respond: () => WIRE_JOB },
|
||||
]);
|
||||
const client = createN0dClient(server.baseUrl);
|
||||
const job = await client.runDataQuality({
|
||||
tenant_id: "t_test",
|
||||
dataset_id: "ds_2",
|
||||
quality_rule_set_id: "rs_2",
|
||||
});
|
||||
expect(job.status).toBe("queued");
|
||||
expect(job.job_id).toBe("job_r3al");
|
||||
// The wire body must NOT carry createJob-only fields and must NOT fabricate results.
|
||||
const body = server.requests[0].body as Record<string, unknown>;
|
||||
expect(body.run_inline).toBeUndefined();
|
||||
expect(body.job_type).toBeUndefined();
|
||||
expect(body.capability_id).toBeUndefined();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,158 @@
|
||||
/**
|
||||
* Master-DoD §3/§10 for the storage paths that `src/platform/dependency-mode.ts`
|
||||
* did NOT yet cover when it was introduced:
|
||||
*
|
||||
* 1. The legacy Next.js stores (`lib/orders-store.ts`,
|
||||
* `lib/subscriptions-store.ts`) predate that module and called `getSql()`
|
||||
* directly, silently falling back to module-global `Map`s. For orders,
|
||||
* payments and subscriptions that is invisible loss of money-bearing
|
||||
* state: 201 returned, row gone on the next restart or on another replica.
|
||||
*
|
||||
* 2. `LocalBlobStore` writes document bytes to a container-local disk while
|
||||
* an artifact pointer claims they are stored — a fallback that silently
|
||||
* swaps durable object storage for ephemeral disk.
|
||||
*
|
||||
* Both are asserted in BOTH directions: production refuses, and the
|
||||
* dev/test seam plus the correctly-configured production path still work. A
|
||||
* guard that had degenerated into a blanket refusal would fail these too.
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { getSqlForDurableStore } from "@/lib/db";
|
||||
import { LocalBlobStore } from "@/src/adapters/local-blob-store";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { promises as fs } from "fs";
|
||||
import os from "os";
|
||||
import path from "path";
|
||||
|
||||
/**
|
||||
* Drive the real process env (these read it through `process.env`), restoring
|
||||
* after.
|
||||
*
|
||||
* NOTE the async variant below is not a stylistic duplicate. A synchronous
|
||||
* `try/finally` wrapper around an async callback restores the environment at
|
||||
* the callback's FIRST `await`, not when it finishes — so every assertion
|
||||
* after that await runs with the env already restored and silently measures
|
||||
* the wrong runtime. That produced a false failure while writing these tests
|
||||
* (a `read` that should have been refused returned ENOENT instead, because
|
||||
* NODE_ENV was no longer "production" by the time it ran).
|
||||
*/
|
||||
function withEnv<T>(vars: Record<string, string | undefined>, fn: () => T): T {
|
||||
const restore = applyEnv(vars);
|
||||
try {
|
||||
return fn();
|
||||
} finally {
|
||||
restore();
|
||||
}
|
||||
}
|
||||
|
||||
async function withEnvAsync<T>(
|
||||
vars: Record<string, string | undefined>,
|
||||
fn: () => Promise<T>
|
||||
): Promise<T> {
|
||||
const restore = applyEnv(vars);
|
||||
try {
|
||||
return await fn();
|
||||
} finally {
|
||||
restore();
|
||||
}
|
||||
}
|
||||
|
||||
function applyEnv(vars: Record<string, string | undefined>): () => void {
|
||||
const prev: Record<string, string | undefined> = {};
|
||||
for (const [k, v] of Object.entries(vars)) {
|
||||
prev[k] = process.env[k];
|
||||
if (v === undefined) delete process.env[k];
|
||||
else process.env[k] = v;
|
||||
}
|
||||
return () => {
|
||||
for (const [k, v] of Object.entries(prev)) {
|
||||
if (v === undefined) delete process.env[k];
|
||||
else process.env[k] = v;
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
const NO_DB = {
|
||||
DATABASE_URL: undefined,
|
||||
POSTGRES_URL: undefined,
|
||||
POSTGRES_PRISMA_URL: undefined,
|
||||
};
|
||||
|
||||
const tmpDirs: string[] = [];
|
||||
afterEach(async () => {
|
||||
while (tmpDirs.length) {
|
||||
const d = tmpDirs.pop()!;
|
||||
await fs.rm(d, { recursive: true, force: true }).catch(() => {});
|
||||
}
|
||||
});
|
||||
|
||||
describe("legacy Next.js durable stores (orders/subscriptions)", () => {
|
||||
it("production + no database => throws DEPENDENCY_UNAVAILABLE instead of an in-memory Map", () => {
|
||||
withEnv({ NODE_ENV: "production", NEXT_PHASE: undefined, ...NO_DB }, () => {
|
||||
try {
|
||||
getSqlForDurableStore("0pt.orders");
|
||||
expect.unreachable("must throw rather than return the memory seam");
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(SiaxError);
|
||||
expect((err as SiaxError).code).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
expect((err as SiaxError).source).toBe("0pt.orders");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
it("names the specific store that is unbacked, so the operator knows what is at risk", () => {
|
||||
withEnv({ NODE_ENV: "production", NEXT_PHASE: undefined, ...NO_DB }, () => {
|
||||
expect(() => getSqlForDurableStore("0pt.subscriptions")).toThrowError(/0pt\.subscriptions/);
|
||||
});
|
||||
});
|
||||
|
||||
it("non-production + no database => null, keeping the in-memory seam for tests/dev", () => {
|
||||
withEnv({ NODE_ENV: "test", ...NO_DB }, () => {
|
||||
expect(getSqlForDurableStore("0pt.orders")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
it("the Next BUILD phase is not a production runtime (page-data collection must compile)", () => {
|
||||
withEnv({ NODE_ENV: "production", NEXT_PHASE: "phase-production-build", ...NO_DB }, () => {
|
||||
expect(getSqlForDurableStore("0pt.orders")).toBeNull();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("LocalBlobStore is not production object storage", () => {
|
||||
it("refuses to persist document bytes in a production runtime", async () => {
|
||||
const store = new LocalBlobStore(path.join(os.tmpdir(), "0pt-blob-guard-prod"));
|
||||
await withEnvAsync({ NODE_ENV: "production", NEXT_PHASE: undefined }, async () => {
|
||||
await expect(store.write("docs", "a.pdf", Buffer.from("x"))).rejects.toThrowError(SiaxError);
|
||||
await expect(store.read("docs", "a.pdf")).rejects.toThrowError(/DEPENDENCY_UNAVAILABLE|ST0RE/);
|
||||
});
|
||||
});
|
||||
|
||||
it("does not write anything to disk when it refuses", async () => {
|
||||
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "0pt-blob-noleak-"));
|
||||
tmpDirs.push(dir);
|
||||
const store = new LocalBlobStore(dir);
|
||||
await withEnvAsync({ NODE_ENV: "production", NEXT_PHASE: undefined }, async () => {
|
||||
await expect(store.write("docs", "a.pdf", Buffer.from("x"))).rejects.toThrowError(SiaxError);
|
||||
});
|
||||
expect(await fs.readdir(dir)).toEqual([]);
|
||||
});
|
||||
|
||||
it("constructing the adapter is never fatal — only persisting/reading bytes is", () => {
|
||||
withEnv({ NODE_ENV: "production", NEXT_PHASE: undefined }, () => {
|
||||
expect(() => new LocalBlobStore("/tmp/whatever")).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
it("still round-trips bytes outside production (dev/test capability stays real)", async () => {
|
||||
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "0pt-blob-roundtrip-"));
|
||||
tmpDirs.push(dir);
|
||||
const store = new LocalBlobStore(dir);
|
||||
const result = await withEnvAsync({ NODE_ENV: "test" }, () =>
|
||||
store.write("docs", "a.pdf", Buffer.from("hello"))
|
||||
);
|
||||
expect(result.sizeBytes).toBe(5);
|
||||
const back = await withEnvAsync({ NODE_ENV: "test" }, () => store.read("docs", "a.pdf"));
|
||||
expect(back.toString()).toBe("hello");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,133 @@
|
||||
/**
|
||||
* Pins 0pt's MIRROR of cl0ud's canonical request-context contract
|
||||
* (src/platform/siax-context.ts + src/platform/errors.ts) to the canonical
|
||||
* values from sax3l/cl0ud `packages/contract/src/request-context.ts`.
|
||||
* If cl0ud evolves the contract, this test is the tripwire that forces the
|
||||
* mirror (and this pin) to be updated deliberately, never by drift.
|
||||
*/
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
SIAX_CONTEXT_HEADERS,
|
||||
toPropagationHeaders,
|
||||
validateSiaxRequestContext,
|
||||
} from "@/src/platform/siax-context";
|
||||
import {
|
||||
SIAX_ERROR_CODES,
|
||||
SiaxError,
|
||||
httpStatusForSiaxErrorCode,
|
||||
siaxErrorCodeForUpstreamStatus,
|
||||
} from "@/src/platform/errors";
|
||||
|
||||
describe("SIAX context header names (pinned to cl0ud @siax/contract)", () => {
|
||||
it("uses the canonical wire header names, verbatim", () => {
|
||||
expect(SIAX_CONTEXT_HEADERS).toEqual({
|
||||
tenant: "x-tenant-id",
|
||||
actor: "x-actor-id",
|
||||
capability: "x-siax-capability",
|
||||
purpose: "x-siax-purpose",
|
||||
project: "x-siax-project-id",
|
||||
correlation: "x-siax-correlation-id",
|
||||
causation: "x-siax-causation-id",
|
||||
trace: "x-siax-trace-id",
|
||||
idempotency: "idempotency-key",
|
||||
});
|
||||
});
|
||||
|
||||
it("serializes required fields always and optional fields only when present", () => {
|
||||
const minimal = toPropagationHeaders({
|
||||
tenantId: "t_x",
|
||||
actorId: "svc_0pt",
|
||||
capability: "0pt.search.query.v1",
|
||||
correlationId: "corr-1",
|
||||
});
|
||||
expect(minimal).toEqual({
|
||||
"x-tenant-id": "t_x",
|
||||
"x-actor-id": "svc_0pt",
|
||||
"x-siax-capability": "0pt.search.query.v1",
|
||||
"x-siax-correlation-id": "corr-1",
|
||||
});
|
||||
|
||||
const full = toPropagationHeaders({
|
||||
tenantId: "t_x",
|
||||
projectId: "p_1",
|
||||
actorId: "svc_0pt",
|
||||
capability: "0pt.search.query.v1",
|
||||
purpose: "valuation",
|
||||
correlationId: "corr-1",
|
||||
causationId: "cause-1",
|
||||
traceId: "trace-1",
|
||||
idempotencyKey: "idem-1",
|
||||
});
|
||||
expect(full["x-siax-project-id"]).toBe("p_1");
|
||||
expect(full["x-siax-purpose"]).toBe("valuation");
|
||||
expect(full["x-siax-causation-id"]).toBe("cause-1");
|
||||
expect(full["x-siax-trace-id"]).toBe("trace-1");
|
||||
expect(full["idempotency-key"]).toBe("idem-1");
|
||||
});
|
||||
|
||||
it("validates required fields (tenantId/actorId/capability/correlationId)", () => {
|
||||
expect(
|
||||
validateSiaxRequestContext({
|
||||
tenantId: "t_x",
|
||||
actorId: "a",
|
||||
capability: "c",
|
||||
correlationId: "x",
|
||||
})
|
||||
).toEqual([]);
|
||||
const problems = validateSiaxRequestContext({ tenantId: " " });
|
||||
expect(problems.join(" ")).toMatch(/tenantId/);
|
||||
expect(problems.join(" ")).toMatch(/actorId/);
|
||||
expect(problems.join(" ")).toMatch(/capability/);
|
||||
expect(problems.join(" ")).toMatch(/correlationId/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Canonical SIAX error vocabulary (pinned to Master-DoD §6 / cl0ud)", () => {
|
||||
it("carries exactly the 12 canonical codes, in canonical order", () => {
|
||||
expect([...SIAX_ERROR_CODES]).toEqual([
|
||||
"UNAUTHENTICATED",
|
||||
"AUTHORIZATION_DENIED",
|
||||
"ENTITLEMENT_REQUIRED",
|
||||
"CAPABILITY_UNAVAILABLE",
|
||||
"QUOTA_EXCEEDED",
|
||||
"RATE_LIMITED",
|
||||
"INVALID_REQUEST",
|
||||
"NOT_FOUND",
|
||||
"CONFLICT",
|
||||
"DEPENDENCY_UNAVAILABLE",
|
||||
"RETRYABLE_FAILURE",
|
||||
"PERMANENT_FAILURE",
|
||||
]);
|
||||
});
|
||||
|
||||
it("maps codes to the canonical HTTP statuses (pinned to cl0ud's mapping)", () => {
|
||||
expect(httpStatusForSiaxErrorCode("UNAUTHENTICATED")).toBe(401);
|
||||
expect(httpStatusForSiaxErrorCode("AUTHORIZATION_DENIED")).toBe(403);
|
||||
expect(httpStatusForSiaxErrorCode("ENTITLEMENT_REQUIRED")).toBe(402);
|
||||
expect(httpStatusForSiaxErrorCode("QUOTA_EXCEEDED")).toBe(402);
|
||||
expect(httpStatusForSiaxErrorCode("CAPABILITY_UNAVAILABLE")).toBe(404);
|
||||
expect(httpStatusForSiaxErrorCode("RATE_LIMITED")).toBe(429);
|
||||
expect(httpStatusForSiaxErrorCode("INVALID_REQUEST")).toBe(400);
|
||||
expect(httpStatusForSiaxErrorCode("NOT_FOUND")).toBe(404);
|
||||
expect(httpStatusForSiaxErrorCode("CONFLICT")).toBe(409);
|
||||
expect(httpStatusForSiaxErrorCode("DEPENDENCY_UNAVAILABLE")).toBe(503);
|
||||
expect(httpStatusForSiaxErrorCode("RETRYABLE_FAILURE")).toBe(503);
|
||||
expect(httpStatusForSiaxErrorCode("PERMANENT_FAILURE")).toBe(500);
|
||||
});
|
||||
|
||||
it("classifies upstream statuses with retryable-vs-permanent explicit (§6)", () => {
|
||||
expect(siaxErrorCodeForUpstreamStatus(503)).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
expect(siaxErrorCodeForUpstreamStatus(429)).toBe("RATE_LIMITED");
|
||||
expect(siaxErrorCodeForUpstreamStatus(500)).toBe("RETRYABLE_FAILURE");
|
||||
const retryable = new SiaxError("DEPENDENCY_UNAVAILABLE", "st0re", "down");
|
||||
expect(retryable.retryable).toBe(true);
|
||||
const permanent = new SiaxError("PERMANENT_FAILURE", "st0re", "broken");
|
||||
expect(permanent.retryable).toBe(false);
|
||||
});
|
||||
|
||||
it("carries correlation id in the error and its JSON form (§6)", () => {
|
||||
const err = new SiaxError("NOT_FOUND", "n0d", "job missing", { correlationId: "corr-9" });
|
||||
expect(err.correlationId).toBe("corr-9");
|
||||
expect(err.toJSON()).toMatchObject({ error: "NOT_FOUND", source: "n0d", correlation_id: "corr-9" });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,150 @@
|
||||
/**
|
||||
* CONTRACT test for src/clients/st0re-client.ts against ST0RE's REAL wire
|
||||
* contract (sax3l/st0re main `src/api/routes/artifacts.ts` +
|
||||
* `src/api/validation.ts` ArtifactInputSchema, verified 2026-08-31):
|
||||
*
|
||||
* POST /v1/st0re/artifacts/register
|
||||
* headers: X-Tenant-Id (required), X-Actor-Id (required),
|
||||
* X-Idempotency-Key (optional)
|
||||
* body: camelCase — tenantId, projectId, appId, artifactType,
|
||||
* displayName, producedBy, primaryObjectId, schemaVersion,
|
||||
* retentionPolicy, createdBy, checksumSha256 (64 hex)
|
||||
* 201 → { artifactId, createdAt, ... } / 200 → idempotent replay
|
||||
*
|
||||
* The pre-2026-08-31 client sent snake_case + object_location{} — that shape
|
||||
* fails ST0RE's Zod validation with a 400. This test is the tripwire.
|
||||
*/
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { createSt0reClient, type St0reArtifactInput } from "@/src/clients/st0re-client";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
import { startContractServer, type ContractServer } from "./contract-test-server";
|
||||
|
||||
let server: ContractServer | undefined;
|
||||
afterEach(async () => {
|
||||
await server?.close();
|
||||
server = undefined;
|
||||
});
|
||||
|
||||
const CHECKSUM = "a".repeat(64);
|
||||
|
||||
function input(overrides: Partial<St0reArtifactInput> = {}): St0reArtifactInput {
|
||||
return {
|
||||
tenant_id: "t_test",
|
||||
project_id: "p_test",
|
||||
artifact_type: "dataset_export",
|
||||
app_id: "0pt",
|
||||
produced_by: "0pt.dataset.export",
|
||||
object_location: { provider: "minio", bucket: "siax-tenants", key: "t_test/exports/x.parquet" },
|
||||
content_type: "application/vnd.apache.parquet",
|
||||
size_bytes: 1234,
|
||||
checksum_sha256: CHECKSUM,
|
||||
pii_level: "none",
|
||||
retention_policy: "standard",
|
||||
data_residency: "eu",
|
||||
risk_level: "L2",
|
||||
correlation_id: "corr-42",
|
||||
idempotency_key: "idem-artifact-1",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("St0reClient wire contract", () => {
|
||||
it("POSTs the REAL camelCase ArtifactInput to /v1/st0re/artifacts/register with tenant/actor/idempotency headers", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/st0re/artifacts/register",
|
||||
status: 201,
|
||||
respond: () => ({ artifactId: "art_r3al", tenantId: "t_test", createdAt: 1756640000000 }),
|
||||
},
|
||||
]);
|
||||
|
||||
const client = createSt0reClient(server.baseUrl);
|
||||
const artifact = await client.createArtifact(input());
|
||||
|
||||
expect(server.requests).toHaveLength(1);
|
||||
const req = server.requests[0];
|
||||
expect(req.method).toBe("POST");
|
||||
expect(req.path).toBe("/v1/st0re/artifacts/register");
|
||||
// Required ST0RE headers.
|
||||
expect(req.headers["x-tenant-id"]).toBe("t_test");
|
||||
expect(req.headers["x-actor-id"]).toBe("0pt.dataset.export");
|
||||
expect(req.headers["x-idempotency-key"]).toBe("idem-artifact-1");
|
||||
|
||||
// REAL body contract: camelCase, required fields present, s3:// URI.
|
||||
const body = req.body as Record<string, unknown>;
|
||||
expect(body.tenantId).toBe("t_test");
|
||||
expect(body.projectId).toBe("p_test");
|
||||
expect(body.appId).toBe("0pt");
|
||||
expect(body.artifactType).toBe("dataset_export");
|
||||
expect(body.displayName).toBe("x.parquet");
|
||||
expect(body.producedBy).toBe("0pt.dataset.export");
|
||||
expect(body.primaryObjectId).toBe("s3://siax-tenants/t_test/exports/x.parquet");
|
||||
expect(body.schemaVersion).toBe("v1");
|
||||
expect(body.retentionPolicy).toBe("standard");
|
||||
expect(body.createdBy).toBe("0pt.dataset.export");
|
||||
expect(body.checksumSha256).toBe(CHECKSUM);
|
||||
expect(body.idempotencyKey).toBe("idem-artifact-1");
|
||||
// The invented pre-rewrite fields must NOT be on the wire.
|
||||
expect(body.object_location).toBeUndefined();
|
||||
expect(body.tenant_id).toBeUndefined();
|
||||
|
||||
// Response mapping.
|
||||
expect(artifact.artifact_id).toBe("art_r3al");
|
||||
expect(artifact.created_at).toBe(new Date(1756640000000).toISOString());
|
||||
});
|
||||
|
||||
it("treats HTTP 200 as an idempotent replay success (ST0RE's documented semantics)", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/st0re/artifacts/register",
|
||||
status: 200,
|
||||
respond: () => ({ artifactId: "art_existing", createdAt: 1756000000000 }),
|
||||
},
|
||||
]);
|
||||
const client = createSt0reClient(server.baseUrl);
|
||||
const artifact = await client.createArtifact(input());
|
||||
expect(artifact.artifact_id).toBe("art_existing");
|
||||
});
|
||||
|
||||
it("maps a 400 to SiaxError INVALID_REQUEST without leaking the upstream body", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/st0re/artifacts/register",
|
||||
status: 400,
|
||||
respond: () => ({ error: { code: "ST0RE_VALIDATION_ERROR", message: "secret-internal-detail" } }),
|
||||
},
|
||||
]);
|
||||
const client = createSt0reClient(server.baseUrl);
|
||||
try {
|
||||
await client.createArtifact(input());
|
||||
expect.unreachable("must throw");
|
||||
} catch (err) {
|
||||
expect(err).toBeInstanceOf(SiaxError);
|
||||
expect((err as SiaxError).code).toBe("INVALID_REQUEST");
|
||||
expect((err as SiaxError).message).toContain("ST0RE_VALIDATION_ERROR");
|
||||
expect((err as SiaxError).message).not.toContain("secret-internal-detail");
|
||||
}
|
||||
});
|
||||
|
||||
it("maps a 503 to a RETRYABLE SiaxError DEPENDENCY_UNAVAILABLE", async () => {
|
||||
server = await startContractServer([
|
||||
{
|
||||
method: "POST",
|
||||
path: "/v1/st0re/artifacts/register",
|
||||
status: 503,
|
||||
respond: () => ({ error: { code: "ST0RE_UNAVAILABLE" } }),
|
||||
},
|
||||
]);
|
||||
const client = createSt0reClient(server.baseUrl);
|
||||
try {
|
||||
await client.createArtifact(input());
|
||||
expect.unreachable("must throw");
|
||||
} catch (err) {
|
||||
expect((err as SiaxError).code).toBe("DEPENDENCY_UNAVAILABLE");
|
||||
expect((err as SiaxError).retryable).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,52 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { TOOL_CANDIDATES, candidatesForRole } from '../../src/document-workbench/candidate-catalog';
|
||||
|
||||
describe('candidate catalog', () => {
|
||||
it('includes the selected and alternative tools without marking them ready', () => {
|
||||
const ids = TOOL_CANDIDATES.map((tool) => tool.id);
|
||||
expect(new Set(ids).size).toBe(ids.length);
|
||||
expect(ids).toEqual(
|
||||
expect.arrayContaining([
|
||||
'docling',
|
||||
'unstructured',
|
||||
'tika',
|
||||
'tesseract',
|
||||
'paddleocr',
|
||||
'duckdb',
|
||||
'polars',
|
||||
'frictionless',
|
||||
'pandera',
|
||||
'great-expectations',
|
||||
'valentine',
|
||||
'rapidfuzz',
|
||||
'splink',
|
||||
'assistant-ui',
|
||||
'temporal',
|
||||
'langgraph',
|
||||
'openmeter',
|
||||
'openrouter',
|
||||
]),
|
||||
);
|
||||
expect(TOOL_CANDIDATES.every((tool) => tool.status === 'qualification_required')).toBe(true);
|
||||
});
|
||||
it('finds alternatives by role and flags restricted services for extra review', () => {
|
||||
expect(candidatesForRole('ocr').map((tool) => tool.id)).toEqual(
|
||||
expect.arrayContaining(['tesseract', 'paddleocr', 'ocrmypdf']),
|
||||
);
|
||||
for (const id of ['pymupdf', 'marker', 'mineru', 'dify', 'n8n', 'open-webui', 'openrouter']) {
|
||||
expect(TOOL_CANDIDATES.find((tool) => tool.id === id)?.review).toBe(
|
||||
'additional_license_or_service_review',
|
||||
);
|
||||
}
|
||||
});
|
||||
it('records bounded-decision, agent and evaluation candidates without authorizing execution', () => {
|
||||
expect(candidatesForRole('decision').map((tool) => tool.id)).toContain('jev');
|
||||
expect(candidatesForRole('agent').map((tool) => tool.id)).toEqual(
|
||||
expect.arrayContaining(['langgraph', 'pydantic-ai', 'microsoft-agent-framework', 'crewai']),
|
||||
);
|
||||
expect(candidatesForRole('evaluation').map((tool) => tool.id)).toEqual(
|
||||
expect.arrayContaining(['promptfoo', 'deepeval', 'ragas', 'langfuse']),
|
||||
);
|
||||
expect(TOOL_CANDIDATES.every((tool) => tool.status === 'qualification_required')).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,267 @@
|
||||
import fs from 'node:fs/promises';
|
||||
import postgres from 'postgres';
|
||||
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
|
||||
import { PostgresCreditLedger } from '../../src/document-workbench/credit-ledger';
|
||||
import { PostgresCreditPurchaseStore } from '../../src/document-workbench/credit-purchase-store';
|
||||
import { Pay0CreditVerifier } from '../../src/document-workbench/pay0-credit-verification';
|
||||
import { reconcileCreditPurchase } from '../../src/document-workbench/reconcile-credit-purchase';
|
||||
|
||||
const url = process.env.CREDIT_LEDGER_TEST_DATABASE_URL;
|
||||
const schema = `credit_test_${process.pid}_${Date.now()}`;
|
||||
const role = `credit_role_${process.pid}_${Date.now()}`;
|
||||
let admin: ReturnType<typeof postgres>;
|
||||
let scopedUrl: string;
|
||||
let sql: ReturnType<typeof postgres>;
|
||||
let ledger: PostgresCreditLedger;
|
||||
|
||||
describe.skipIf(!url)('credit ledger against isolated PostgreSQL schema', () => {
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
beforeAll(async () => {
|
||||
if (process.env.CREDIT_LEDGER_TEST_ALLOW_LOCAL !== '1' || new URL(url!).hostname !== '127.0.0.1') {
|
||||
throw new Error('Only an explicitly enabled isolated loopback database may be used');
|
||||
}
|
||||
admin = postgres(url!, { max: 1, prepare: false, connection: { search_path: schema } });
|
||||
await admin.unsafe(`CREATE SCHEMA ${schema}`);
|
||||
await admin.unsafe(`CREATE ROLE ${role} LOGIN NOSUPERUSER NOBYPASSRLS`);
|
||||
await admin.unsafe(await fs.readFile('sql/017_document_credits.sql', 'utf8'));
|
||||
await admin.unsafe(await fs.readFile('sql/019_document_credit_rls.sql', 'utf8'));
|
||||
await admin.unsafe(`GRANT USAGE ON SCHEMA ${schema} TO ${role}`);
|
||||
await admin.unsafe(`GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA ${schema} TO ${role}`);
|
||||
await admin.unsafe(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${schema} TO ${role}`);
|
||||
const appUrl = new URL(url!);
|
||||
appUrl.username = role;
|
||||
scopedUrl = appUrl.toString();
|
||||
sql = postgres(scopedUrl, { max: 8, prepare: false, connection: { search_path: schema } });
|
||||
ledger = new PostgresCreditLedger(sql);
|
||||
});
|
||||
afterAll(async () => {
|
||||
if (sql) await sql.end();
|
||||
if (admin) {
|
||||
try {
|
||||
await admin.unsafe(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
|
||||
await admin.unsafe(`DROP ROLE IF EXISTS ${role}`);
|
||||
} finally { await admin.end({ timeout: 2 }); }
|
||||
}
|
||||
});
|
||||
it('rejects superusers and does not expose rows without a tenant scope', async () => {
|
||||
await expect(new PostgresCreditLedger(admin).apply({ tenantId: 'a', idempotencyKey: 'bad-role', kind: 'verified_payment', reference: 'bad-role', amount: 1 })).rejects.toThrow(/RLS-enforced/);
|
||||
expect(await sql`SELECT * FROM opt_credit_accounts`).toEqual([]);
|
||||
expect(await sql`SELECT * FROM opt_credit_purchases`).toEqual([]);
|
||||
});
|
||||
|
||||
it('fails before writing when the isolation migration is not fully active', async () => {
|
||||
await admin.unsafe('ALTER TABLE opt_credit_accounts DISABLE ROW LEVEL SECURITY');
|
||||
try {
|
||||
await expect(ledger.apply({ tenantId: 'unscoped', idempotencyKey: 'disabled-rls', kind: 'verified_payment', reference: 'disabled-rls', amount: 1 })).rejects.toThrow(/isolation migration/);
|
||||
} finally { await admin.unsafe('ALTER TABLE opt_credit_accounts ENABLE ROW LEVEL SECURITY'); }
|
||||
const rows = await admin`SELECT * FROM opt_credit_accounts WHERE tenant_id = 'unscoped'`;
|
||||
expect(rows).toEqual([]);
|
||||
});
|
||||
|
||||
it('grants verified payments only once and rejects a payment reused across tenants', async () => {
|
||||
const payment = {
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 'p1',
|
||||
kind: 'verified_payment' as const,
|
||||
reference: 'stripe:account:payment-1',
|
||||
amount: 100,
|
||||
};
|
||||
expect((await ledger.apply(payment)).balance).toEqual({ available: 100, reserved: 0 });
|
||||
expect((await ledger.apply(payment)).replay).toBe(true);
|
||||
await expect(ledger.apply({ ...payment, amount: 101 })).rejects.toThrow(/Idempotency/);
|
||||
await expect(ledger.apply({ ...payment, tenantId: 'b' })).rejects.toThrow();
|
||||
});
|
||||
|
||||
it('serializes concurrent reservations and prevents overspending', async () => {
|
||||
const command = { tenantId: 'a', kind: 'reserve' as const, amount: 80 };
|
||||
const outcomes = await Promise.allSettled([
|
||||
ledger.apply({ ...command, idempotencyKey: 'r1', reference: 'job1' }),
|
||||
ledger.apply({ ...command, idempotencyKey: 'r2', reference: 'job2' }),
|
||||
]);
|
||||
expect(outcomes.filter((item) => item.status === 'fulfilled')).toHaveLength(1);
|
||||
expect(outcomes.filter((item) => item.status === 'rejected')).toHaveLength(1);
|
||||
const won = outcomes.find((item) => item.status === 'fulfilled') as PromiseFulfilledResult<{
|
||||
replay: boolean;
|
||||
balance: { available: number; reserved: number };
|
||||
}>;
|
||||
expect(won.value.balance).toEqual({ available: 20, reserved: 80 });
|
||||
const rows = await sql.begin(async (tx) => {
|
||||
await tx`SELECT set_config('app.opt_credit_tenant_id', 'a', true)`;
|
||||
return tx<{ reservation_id: string }[]>`SELECT reservation_id FROM opt_credit_reservations`;
|
||||
});
|
||||
const reservationId = rows[0]!.reservation_id;
|
||||
await expect(
|
||||
ledger.apply({
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 'over',
|
||||
kind: 'settle',
|
||||
reference: reservationId,
|
||||
amount: 81,
|
||||
}),
|
||||
).rejects.toThrow(/exceeds/);
|
||||
const settled = await ledger.apply({
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 's1',
|
||||
kind: 'settle',
|
||||
reference: reservationId,
|
||||
amount: 30,
|
||||
});
|
||||
expect(settled.balance).toEqual({ available: 70, reserved: 0 });
|
||||
await expect(
|
||||
ledger.apply({
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 's2',
|
||||
kind: 'settle',
|
||||
reference: reservationId,
|
||||
amount: 30,
|
||||
}),
|
||||
).rejects.toThrow(/not found/);
|
||||
});
|
||||
|
||||
it("cannot release another tenant's reservation and returns unused credits on release", async () => {
|
||||
await ledger.apply({
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 'r3',
|
||||
kind: 'reserve',
|
||||
reference: 'job3',
|
||||
amount: 40,
|
||||
});
|
||||
await expect(
|
||||
ledger.apply({
|
||||
tenantId: 'b',
|
||||
idempotencyKey: 'release-foreign',
|
||||
kind: 'release',
|
||||
reference: 'job3',
|
||||
amount: 0,
|
||||
}),
|
||||
).rejects.toThrow(/not found/);
|
||||
expect(
|
||||
(
|
||||
await ledger.apply({
|
||||
tenantId: 'a',
|
||||
idempotencyKey: 'release-own',
|
||||
kind: 'release',
|
||||
reference: 'job3',
|
||||
amount: 0,
|
||||
})
|
||||
).balance,
|
||||
).toEqual({ available: 70, reserved: 0 });
|
||||
});
|
||||
|
||||
it('deduplicates concurrent payment callbacks and preserves the account across connections', async () => {
|
||||
const payment = {
|
||||
tenantId: 'c',
|
||||
idempotencyKey: 'concurrent-payment',
|
||||
kind: 'verified_payment' as const,
|
||||
reference: 'stripe:account:payment-2',
|
||||
amount: 25,
|
||||
};
|
||||
const results = await Promise.all([ledger.apply(payment), ledger.apply(payment)]);
|
||||
expect(results.map((item) => item.replay).sort()).toEqual([false, true]);
|
||||
const secondSql = postgres(scopedUrl, { max: 1, prepare: false, connection: { search_path: schema } });
|
||||
try {
|
||||
const replay = await new PostgresCreditLedger(secondSql).apply(payment);
|
||||
expect(replay).toEqual({ replay: true, balance: { available: 25, reserved: 0 } });
|
||||
} finally {
|
||||
await secondSql.end();
|
||||
}
|
||||
});
|
||||
|
||||
it('stores a tenant-scoped price snapshot and rejects changed or reused checkout data', async () => {
|
||||
const store = new PostgresCreditPurchaseStore(sql);
|
||||
const purchase = {
|
||||
tenantId: 'a',
|
||||
purchaseId: 'purchase-1',
|
||||
checkoutSessionId: 'cs-1',
|
||||
amountMinor: 1000,
|
||||
currency: 'SEK',
|
||||
credits: 25,
|
||||
};
|
||||
expect(await store.create(purchase)).toEqual(purchase);
|
||||
expect(await store.create(purchase)).toEqual(purchase);
|
||||
expect(await store.get('b', 'purchase-1')).toBeUndefined();
|
||||
await expect(store.create({ ...purchase, credits: 500 })).rejects.toThrow(/different price snapshot/);
|
||||
await expect(store.create({ ...purchase, tenantId: 'b', purchaseId: 'purchase-2' })).rejects.toThrow();
|
||||
});
|
||||
|
||||
it('reconciles a stored purchase through PAY0 and grants exactly once', async () => {
|
||||
const purchases = new PostgresCreditPurchaseStore(sql);
|
||||
await purchases.create({
|
||||
tenantId: 'd',
|
||||
purchaseId: 'purchase-d',
|
||||
checkoutSessionId: 'cs-d',
|
||||
amountMinor: 1000,
|
||||
currency: 'SEK',
|
||||
credits: 25,
|
||||
});
|
||||
const common = {
|
||||
tenant_id: 'd',
|
||||
payable_type: '0pt_credit_purchase',
|
||||
payable_ref: 'purchase-d',
|
||||
currency: 'SEK',
|
||||
};
|
||||
vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(
|
||||
async (url: string) =>
|
||||
new Response(
|
||||
JSON.stringify({
|
||||
data: url.includes('checkout-sessions')
|
||||
? {
|
||||
...common,
|
||||
id: 'cs-d',
|
||||
payment_intent_id: 'pi-d',
|
||||
amount_snapshot: 1000,
|
||||
status: 'completed',
|
||||
provider: 'stripe',
|
||||
provider_reference: 'psp-d',
|
||||
}
|
||||
: {
|
||||
...common,
|
||||
id: 'pi-d',
|
||||
amount: 1000,
|
||||
canonical_status: 'captured',
|
||||
captured_amount: 1000,
|
||||
refunded_amount: 0,
|
||||
},
|
||||
}),
|
||||
{ status: 200 },
|
||||
),
|
||||
),
|
||||
);
|
||||
const context = {
|
||||
tenantId: 'd',
|
||||
actorId: 'svc-0pt',
|
||||
capability: '0pt.credit.purchase',
|
||||
correlationId: 'req-d',
|
||||
};
|
||||
const deps = { purchases, ledger, pay0: new Pay0CreditVerifier('https://pay0.test', 'service-token') };
|
||||
expect(await reconcileCreditPurchase(deps, 'd', 'purchase-d', context)).toEqual({
|
||||
replay: false,
|
||||
balance: { available: 25, reserved: 0 },
|
||||
});
|
||||
expect(await reconcileCreditPurchase(deps, 'd', 'purchase-d', context)).toEqual({
|
||||
replay: true,
|
||||
balance: { available: 25, reserved: 0 },
|
||||
});
|
||||
await expect(
|
||||
reconcileCreditPurchase(deps, 'd', 'purchase-d', { ...context, tenantId: 'other' }),
|
||||
).rejects.toThrow(/scope/);
|
||||
});
|
||||
it('enforces tenant filters even when a query omits its predicate', async () => {
|
||||
const visible = await sql.begin(async (tx) => {
|
||||
await tx`SELECT set_config('app.opt_credit_tenant_id', 'a', true)`;
|
||||
const accounts = await tx<{ tenant_id: string }[]>`SELECT tenant_id FROM opt_credit_accounts`;
|
||||
const purchases = await tx<{ tenant_id: string }[]>`SELECT tenant_id FROM opt_credit_purchases`;
|
||||
return { accounts, purchases };
|
||||
});
|
||||
expect(visible.accounts).toEqual([{ tenant_id: 'a' }]);
|
||||
expect(visible.purchases).toEqual([{ tenant_id: 'a' }]);
|
||||
expect(await sql`SELECT * FROM opt_credit_accounts`).toEqual([]);
|
||||
await expect(sql.begin(async (tx) => {
|
||||
await tx`SELECT set_config('app.opt_credit_tenant_id', 'b', true)`;
|
||||
await tx`INSERT INTO opt_credit_accounts (tenant_id) VALUES ('wrong-tenant')`;
|
||||
})).rejects.toThrow();
|
||||
});
|
||||
|
||||
});
|
||||
@@ -0,0 +1,30 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { quoteMaximumCredits } from '../../src/document-workbench/credit-quote';
|
||||
|
||||
describe('credit quote', () => {
|
||||
it('rounds each component up exactly and retains the price book version', () => {
|
||||
expect(
|
||||
quoteMaximumCredits('v1', [
|
||||
{ metric: 'pages', maxUnits: 11, creditsPerBlock: 3, unitsPerBlock: 10 },
|
||||
{ metric: 'tokens', maxUnits: 2000, creditsPerBlock: 2, unitsPerBlock: 1000 },
|
||||
]),
|
||||
).toMatchObject({ priceBookVersion: 'v1', maximumCredits: 10 });
|
||||
});
|
||||
it('does not charge an unused component', () => {
|
||||
expect(
|
||||
quoteMaximumCredits('v1', [{ metric: 'pages', maxUnits: 0, creditsPerBlock: 1, unitsPerBlock: 10 }])
|
||||
.maximumCredits,
|
||||
).toBe(0);
|
||||
});
|
||||
it('rejects fractional, negative, duplicate and overflowing quantities', () => {
|
||||
const line = { metric: 'pages', maxUnits: 1, creditsPerBlock: 1, unitsPerBlock: 1 };
|
||||
expect(() => quoteMaximumCredits('', [line])).toThrow();
|
||||
expect(() => quoteMaximumCredits('v1', [line, line])).toThrow();
|
||||
expect(() => quoteMaximumCredits('v1', [{ ...line, maxUnits: 0.5 }])).toThrow();
|
||||
expect(() => quoteMaximumCredits('v1', [{ ...line, creditsPerBlock: -1 }])).toThrow();
|
||||
expect(() => quoteMaximumCredits('v1', [{ ...line, unitsPerBlock: 0 }])).toThrow();
|
||||
expect(() =>
|
||||
quoteMaximumCredits('v1', [{ ...line, maxUnits: Number.MAX_SAFE_INTEGER, creditsPerBlock: 2 }]),
|
||||
).toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,123 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
DecisionOllamaGatewayClient,
|
||||
assertTrustedDecisionOllamaUrl,
|
||||
} from '../../src/document-workbench/decision-ollama-client';
|
||||
import { Inf0OutcomeUnknownError } from '../../src/document-workbench/inf0-gateway-client';
|
||||
import { createInf0Gateway } from '../../src/document-workbench/inf0-gateway';
|
||||
|
||||
const context = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_default',
|
||||
actorId: 'user_1',
|
||||
capability: '0pt.document.structure.v1',
|
||||
correlationId: 'corr-1',
|
||||
};
|
||||
const admission = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_default',
|
||||
jobId: 'job-1',
|
||||
modelId: 'hermes-qwen3.5:9b',
|
||||
dataClass: 'low',
|
||||
maxInputTokens: 1000,
|
||||
maxOutputTokens: 200,
|
||||
maximumCredits: 0,
|
||||
};
|
||||
const policy = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_default',
|
||||
allowedModelIds: ['hermes-qwen3.5:9b'],
|
||||
allowedDataClasses: ['low'],
|
||||
destination: 'internal' as const,
|
||||
externalTransferAllowed: false,
|
||||
maxInputTokens: 1000,
|
||||
maxOutputTokens: 200,
|
||||
};
|
||||
const messages = [
|
||||
{ role: 'system' as const, content: 'system' },
|
||||
{ role: 'user' as const, content: 'data' },
|
||||
];
|
||||
|
||||
function client(fetchImpl: typeof fetch, model = 'hermes-qwen3.5:9b') {
|
||||
return new DecisionOllamaGatewayClient({
|
||||
baseUrl: 'http://100.96.133.104:11434',
|
||||
model,
|
||||
fetchImpl,
|
||||
});
|
||||
}
|
||||
|
||||
describe('decision server Ollama gateway', () => {
|
||||
it('accepts tailnet/RFC1918 HTTP but refuses a public HTTP endpoint', () => {
|
||||
expect(() => assertTrustedDecisionOllamaUrl('http://100.96.133.104:11434')).not.toThrow();
|
||||
expect(() => assertTrustedDecisionOllamaUrl('http://192.168.1.10:11434')).not.toThrow();
|
||||
expect(() => assertTrustedDecisionOllamaUrl('https://ai.example.test')).not.toThrow();
|
||||
expect(() => assertTrustedDecisionOllamaUrl('http://8.8.8.8:11434')).toThrow();
|
||||
expect(() => assertTrustedDecisionOllamaUrl('http://user:pass@100.96.133.104:11434')).toThrow();
|
||||
});
|
||||
|
||||
it('maps a native Ollama chat response into the INF0 receipt', async () => {
|
||||
const c = client(async (url, init) => {
|
||||
expect(String(url)).toMatch(/\/api\/chat$/);
|
||||
const body = JSON.parse(String(init?.body));
|
||||
expect(body.format).toBe('json');
|
||||
expect(body.think).toBe(false);
|
||||
return Response.json({
|
||||
model: 'hermes-qwen3.5:9b',
|
||||
message: { role: 'assistant', content: '{"value":{}}' },
|
||||
done: true,
|
||||
done_reason: 'stop',
|
||||
prompt_eval_count: 12,
|
||||
eval_count: 8,
|
||||
});
|
||||
});
|
||||
await expect(
|
||||
c.complete({ context, admission, policy, reservation: undefined, inputTokens: 12, messages }),
|
||||
).resolves.toMatchObject({
|
||||
status: 'model_stopped',
|
||||
modelExecuted: 'hermes-qwen3.5:9b',
|
||||
providerKind: 'local',
|
||||
totalTokens: 20,
|
||||
});
|
||||
});
|
||||
|
||||
it('refuses an external destination and malformed usage', async () => {
|
||||
const c = client(async () =>
|
||||
Response.json({
|
||||
model: 'hermes-qwen3.5:9b',
|
||||
message: { role: 'assistant', content: 'x' },
|
||||
done: true,
|
||||
done_reason: 'stop',
|
||||
prompt_eval_count: 1,
|
||||
eval_count: 5000,
|
||||
}),
|
||||
);
|
||||
await expect(
|
||||
c.complete({
|
||||
context,
|
||||
admission,
|
||||
policy: { ...policy, destination: 'external' },
|
||||
reservation: undefined,
|
||||
inputTokens: 1,
|
||||
messages,
|
||||
}),
|
||||
).rejects.toThrow(/denied/i);
|
||||
await expect(
|
||||
c.complete({ context, admission, policy, reservation: undefined, inputTokens: 1, messages }),
|
||||
).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
});
|
||||
|
||||
it('is preferred over the INF0/LiteLLM path when configured', () => {
|
||||
expect(
|
||||
createInf0Gateway({
|
||||
DECISION_OLLAMA_URL: 'http://100.96.133.104:11434',
|
||||
DECISION_OLLAMA_MODEL: 'hermes-qwen3.5:9b',
|
||||
INF0_GATEWAY_LITELLM_KEY: 'sk-test',
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).toBeInstanceOf(DecisionOllamaGatewayClient);
|
||||
expect(
|
||||
createInf0Gateway({
|
||||
INF0_GATEWAY_LITELLM_KEY: 'sk-test',
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).not.toBeInstanceOf(DecisionOllamaGatewayClient);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,69 @@
|
||||
import { createHash } from 'node:crypto';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { Doc0SourceClient, Doc0SourceUnavailableError } from '../../src/document-workbench/doc0-source-client';
|
||||
|
||||
const hash = (value: string) => createHash('sha256').update(value).digest('hex');
|
||||
const receipt = { documentId: 'doc-a', versionId: 'version-a', checksumSha256: 'a'.repeat(64), pipelineStage: 'parsed' };
|
||||
const input = { tenantId: 'tenant-a', projectId: 'project-a', actorId: 'user-a', requestId: 'request-a', receipt };
|
||||
const text = 'Acme 😀';
|
||||
const metadata = { tenantId: input.tenantId, documentId: receipt.documentId, versionId: receipt.versionId,
|
||||
documentTextId: 'text-a', parserRunId: 'run-a', segmentsTruncated: false, segmentCount: 1, charCount: text.length, textSha256: hash(text) };
|
||||
const segment = { tenantId: input.tenantId, documentId: receipt.documentId, versionId: receipt.versionId,
|
||||
documentTextId: 'text-a', parserRunId: 'run-a', segmentId: 'segment-a', sequence: 0, text, charStart: 0,
|
||||
charEnd: text.length, segmentSha256: hash(text), sourceVersionSha256: receipt.checksumSha256 };
|
||||
const payload = { offset: 0, texts: [metadata], segments: [segment] };
|
||||
|
||||
describe('DOC0 extracted source client', () => {
|
||||
it('reads scoped, checksum-bound segment text without caching or redirects', async () => {
|
||||
const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
|
||||
expect(String(url)).toContain('/v1/doc0/documents/doc-a/versions/version-a/segments?limit=100&offset=0');
|
||||
expect(new Headers(init?.headers).get('x-tenant-id')).toBe('tenant-a');
|
||||
expect(new Headers(init?.headers).get('x-actor-id')).toBe('user-a');
|
||||
expect(init?.redirect).toBe('error');
|
||||
expect(init?.cache).toBe('no-store');
|
||||
return Response.json(payload);
|
||||
});
|
||||
const client = new Doc0SourceClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', fetchImpl });
|
||||
expect(await client.read(input)).toEqual({ sources: [{ id: 'segment-a', text }], reportedTextSha256: hash(text) });
|
||||
});
|
||||
it('rejects incomplete, forged, cross-tenant or inconsistent text instead of passing it to a model', async () => {
|
||||
const bad = [
|
||||
{ ...payload, texts: [{ ...metadata, segmentsTruncated: true }] },
|
||||
{ ...payload, texts: [{ ...metadata, segmentCount: 2 }] },
|
||||
{ ...payload, texts: [{ ...metadata, tenantId: 'tenant-b' }] },
|
||||
{ ...payload, texts: [metadata, metadata] },
|
||||
{ ...payload, segments: [{ ...segment, sourceVersionSha256: 'b'.repeat(64) }] },
|
||||
{ ...payload, segments: [{ ...segment, text: 'fabricated' }] },
|
||||
{ ...payload, segments: [{ ...segment, tenantId: 'tenant-b' }] },
|
||||
{ ...payload, segments: [{ ...segment, sequence: 1 }] },
|
||||
{ ...payload, segments: [{ ...segment, charEnd: 5 }] },
|
||||
{ ...payload, offset: 1 },
|
||||
];
|
||||
for (const candidate of bad) {
|
||||
const client = new Doc0SourceClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', fetchImpl: async () => Response.json(candidate) });
|
||||
await expect(client.read(input)).rejects.toBeInstanceOf(Doc0SourceUnavailableError);
|
||||
}
|
||||
});
|
||||
it('rejects empty, oversized, unavailable and unparsed sources', async () => {
|
||||
const fetchImpl = vi.fn(async () => Response.json(payload));
|
||||
const client = new Doc0SourceClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', fetchImpl });
|
||||
await expect(client.read({ ...input, receipt: { ...receipt, pipelineStage: 'parse_failed' } })).rejects.toBeInstanceOf(Doc0SourceUnavailableError);
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
for (const response of [Response.json({ ...payload, texts: [] }), new Response('x'.repeat(1024 * 1024 + 1)), new Response('', { status: 503 })]) {
|
||||
const bad = new Doc0SourceClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', fetchImpl: async () => response });
|
||||
await expect(bad.read(input)).rejects.toBeInstanceOf(Doc0SourceUnavailableError);
|
||||
}
|
||||
});
|
||||
it('pins the original scope and validated credential during an in-flight read', async () => {
|
||||
const mutable = structuredClone(input);
|
||||
const config = { baseUrl: 'https://doc0.test', serviceToken: 'original', fetchImpl: async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer original');
|
||||
mutable.tenantId = 'tenant-b';
|
||||
mutable.receipt.checksumSha256 = 'b'.repeat(64);
|
||||
return Response.json(payload);
|
||||
} };
|
||||
const client = new Doc0SourceClient(config);
|
||||
config.serviceToken = 'changed';
|
||||
expect(await client.read(mutable)).toMatchObject({ sources: [{ id: 'segment-a', text }] });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,211 @@
|
||||
import { createHash } from 'node:crypto';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { Doc0UploadClient, Doc0UploadOutcomeUnknownError, Doc0InspectionUnavailableError, prepareDoc0UploadIdentity } from '../../src/document-workbench/doc0-upload-client';
|
||||
|
||||
const bytes = new TextEncoder().encode('source bytes');
|
||||
const input = {
|
||||
tenantId: 'tenant-a',
|
||||
projectId: 'project-a',
|
||||
actorId: 'user-a',
|
||||
requestId: 'req-a',
|
||||
idempotencyKey: 'idem-a',
|
||||
filename: 'test.txt',
|
||||
mimeType: 'text/plain',
|
||||
classification: 'confidential' as const,
|
||||
bytes,
|
||||
};
|
||||
const receipt = {
|
||||
document: { documentId: 'doc-a', tenantId: 'tenant-a', projectId: 'project-a', currentVersionId: 'v1' },
|
||||
currentVersion: {
|
||||
versionId: 'v1',
|
||||
tenantId: 'tenant-a',
|
||||
documentId: 'doc-a',
|
||||
checksumSha256: createHash('sha256').update(bytes).digest('hex'),
|
||||
sizeBytes: bytes.length,
|
||||
pipelineStage: 'parsed',
|
||||
},
|
||||
};
|
||||
|
||||
describe('DOC0 upload client', () => {
|
||||
it('validates the receipt against the original scope even if the caller mutates its input during dispatch', async () => {
|
||||
const mutable = { ...input, bytes: new Uint8Array(input.bytes) };
|
||||
const fetchImpl = async () => {
|
||||
mutable.tenantId = 'tenant-b';
|
||||
mutable.projectId = 'project-b';
|
||||
return Response.json({ ...receipt,
|
||||
document: { ...receipt.document, tenantId: 'tenant-b', projectId: 'project-b' },
|
||||
currentVersion: { ...receipt.currentVersion, tenantId: 'tenant-b' },
|
||||
}, { status: 201 });
|
||||
};
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
await expect(client.upload(mutable)).rejects.toBeInstanceOf(Doc0UploadOutcomeUnknownError);
|
||||
});
|
||||
it('accepts a matching receipt for the bytes and scope actually dispatched', async () => {
|
||||
const mutable = { ...input, bytes: new Uint8Array(input.bytes) };
|
||||
const fetchImpl = async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
mutable.tenantId = 'tenant-b';
|
||||
mutable.bytes.fill(0);
|
||||
const sentFile = (init?.body as FormData).get('file') as Blob;
|
||||
expect(await sentFile.text()).toBe('source bytes');
|
||||
return Response.json(receipt, { status: 201 });
|
||||
};
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
await expect(client.upload(mutable)).resolves.toMatchObject({ documentId: 'doc-a' });
|
||||
});
|
||||
it('pins validated client configuration rather than trusting later mutations', async () => {
|
||||
const fetchImpl = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer test');
|
||||
return Response.json(receipt, { status: 201 });
|
||||
});
|
||||
const config = { baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, timeoutMs: 1000, fetchImpl };
|
||||
const client = new Doc0UploadClient(config);
|
||||
config.serviceToken = 'changed';
|
||||
config.maxBytes = 1;
|
||||
config.timeoutMs = 0;
|
||||
await expect(client.upload(input)).resolves.toMatchObject({ documentId: 'doc-a' });
|
||||
});
|
||||
it('sends real bytes and validates a tenant-scoped checksum-bound receipt', async () => {
|
||||
const fetchImpl = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
expect(new Headers(init?.headers).get('x-tenant-id')).toBe('tenant-a');
|
||||
expect(new Headers(init?.headers).get('x-idempotency-key')).toBe('idem-a');
|
||||
expect(init?.redirect).toBe('error');
|
||||
const form = init?.body as FormData;
|
||||
expect(await (form.get('file') as Blob).text()).toBe('source bytes');
|
||||
return new Response(JSON.stringify(receipt), { status: 201 });
|
||||
});
|
||||
const client = new Doc0UploadClient({
|
||||
baseUrl: 'https://doc0.test',
|
||||
serviceToken: 'test',
|
||||
maxBytes: 100,
|
||||
fetchImpl: fetchImpl as typeof fetch,
|
||||
});
|
||||
expect(await client.upload(input)).toMatchObject({
|
||||
documentId: 'doc-a',
|
||||
versionId: 'v1',
|
||||
pipelineStage: 'parsed',
|
||||
});
|
||||
});
|
||||
it.each(['rapport åäö.xlsx', 'folder/name.txt', 'Back\\path.txt', 'A"B.txt', 'row\r\nname.txt'])(
|
||||
'uses stable multipart metadata while retaining original name: %s', async (filename) => {
|
||||
const fixture = { ...input, filename, mimeType: 'APPLICATION/PDF' };
|
||||
const identity = prepareDoc0UploadIdentity(fixture);
|
||||
const fetchImpl = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
const form = init?.body as FormData;
|
||||
expect(JSON.parse(form.get('input') as string).displayName).toBe(filename);
|
||||
expect((form.get('file') as File).name).toBe(identity.wireFilename);
|
||||
expect((form.get('file') as File).type).toBe('application/pdf');
|
||||
return Response.json(receipt, { status: 201 });
|
||||
});
|
||||
await new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl }).upload(fixture);
|
||||
expect(identity.sourceSha256).toBe(receipt.currentVersion.checksumSha256);
|
||||
expect(identity.requestFingerprint).toMatch(/^[0-9a-f]{64}$/);
|
||||
expect(fetchImpl).toHaveBeenCalledOnce();
|
||||
},
|
||||
);
|
||||
it('rejects non-canonical identity headers before any upload', async () => {
|
||||
const fetchImpl = vi.fn();
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
for (const tenantId of [' tenant-a', 'tenant-a ', 'tenant-å', 'tenant-\n']) {
|
||||
await expect(client.upload({ ...input, tenantId })).rejects.toThrow(/Invalid/);
|
||||
}
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
});
|
||||
it('rejects ambiguous MIME values before any upload', async () => {
|
||||
const fetchImpl = vi.fn();
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
for (const mimeType of ['text/plain; charset=utf-8', 'text/å', ' text/plain', 'not-a-mime']) {
|
||||
await expect(client.upload({ ...input, mimeType })).rejects.toThrow(/MIME/);
|
||||
}
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
});
|
||||
it.each([
|
||||
{ document: { ...receipt.document, tenantId: 'tenant-b' } },
|
||||
{ document: { ...receipt.document, projectId: 'other' } },
|
||||
{ currentVersion: { ...receipt.currentVersion, checksumSha256: 'bad' } },
|
||||
{ currentVersion: { ...receipt.currentVersion, documentId: 'other' } },
|
||||
])('rejects an incorrect receipt', async (change) => {
|
||||
const client = new Doc0UploadClient({
|
||||
baseUrl: 'https://doc0.test',
|
||||
serviceToken: 'test',
|
||||
maxBytes: 100,
|
||||
fetchImpl: async () => new Response(JSON.stringify({ ...receipt, ...change }), { status: 201 }),
|
||||
});
|
||||
await expect(client.upload(input)).rejects.toThrow(/receipt/);
|
||||
});
|
||||
it('rejects empty or oversized inputs before calling DOC0', async () => {
|
||||
const fetchImpl = vi.fn();
|
||||
const client = new Doc0UploadClient({
|
||||
baseUrl: 'https://doc0.test',
|
||||
serviceToken: 'test',
|
||||
maxBytes: 2,
|
||||
fetchImpl,
|
||||
});
|
||||
await expect(client.upload(input)).rejects.toThrow(/Invalid/);
|
||||
await expect(client.upload({ ...input, bytes: new Uint8Array() })).rejects.toThrow(/Invalid/);
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
});
|
||||
it('rejects insecure endpoints, embedded credentials and invalid timeouts', () => {
|
||||
const base = { serviceToken: 'test', maxBytes: 100 };
|
||||
for (const baseUrl of ['http://doc0.test', 'https://doc0.test?token=x', 'file:///tmp/doc0', 'not a URL']) {
|
||||
expect(() => new Doc0UploadClient({ ...base, baseUrl })).toThrow(/HTTPS/);
|
||||
}
|
||||
const credentialUrl = new URL('https://doc0.test');
|
||||
credentialUrl.username = 'fixture';
|
||||
credentialUrl.password = 'fixture';
|
||||
expect(() => new Doc0UploadClient({ ...base, baseUrl: credentialUrl.toString() })).toThrow(/HTTPS/);
|
||||
expect(() => new Doc0UploadClient({ ...base, baseUrl: 'https://doc0.test', timeoutMs: 0 })).toThrow(/limits/);
|
||||
});
|
||||
it('treats transport failure and non-success responses as unknown outcomes without retrying', async () => {
|
||||
for (const response of [new Error('connection reset'), new Response('unavailable', { status: 503 })]) {
|
||||
const fetchImpl = vi.fn(async () => { if (response instanceof Error) throw response; return response; });
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
await expect(client.upload(input)).rejects.toBeInstanceOf(Doc0UploadOutcomeUnknownError);
|
||||
expect(fetchImpl).toHaveBeenCalledOnce();
|
||||
}
|
||||
});
|
||||
it('rejects broken, malformed and oversized receipts as unknown outcomes', async () => {
|
||||
const broken = new ReadableStream<Uint8Array>({ start(controller) { controller.error(new Error('broken')); } });
|
||||
const locked = new Response('{}');
|
||||
const lock = locked.body!.getReader();
|
||||
for (const response of [new Response(broken), new Response('{'), new Response('x'.repeat(128 * 1024 + 1)), locked]) {
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl: async () => response });
|
||||
await expect(client.upload(input)).rejects.toBeInstanceOf(Doc0UploadOutcomeUnknownError);
|
||||
}
|
||||
lock.releaseLock();
|
||||
});
|
||||
});
|
||||
|
||||
describe('DOC0 upload inspection', () => {
|
||||
const inspection = { tenantId: 'tenant-a', projectId: 'project-a', actorId: 'actor-a', requestId: 'req-a', idempotencyKey: 'idem-a', sourceSha256: 'a'.repeat(64), sourceSizeBytes: 12, requestFingerprint: 'b'.repeat(64) };
|
||||
it('sends only scoped metadata and returns the recorded journal state without retry', async () => {
|
||||
const fetchImpl = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
|
||||
expect(init?.redirect).toBe('error');
|
||||
expect(init?.cache).toBe('no-store');
|
||||
expect(new Headers(init?.headers).get('x-idempotency-key')).toBe('idem-a');
|
||||
expect(JSON.parse(String(init?.body))).toEqual({ projectId: 'project-a', sourceSha256: 'a'.repeat(64), sourceSizeBytes: 12, requestFingerprint: 'b'.repeat(64) });
|
||||
return Response.json({ status: 'completed_recorded', documentId: 'doc', versionId: 'v1' });
|
||||
});
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
expect(await client.inspect(inspection)).toEqual({ status: 'completed_recorded', documentId: 'doc', versionId: 'v1' });
|
||||
expect(fetchImpl).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('preserves weaker states without turning them into successful uploads', async () => {
|
||||
for (const status of ['not_found', 'in_progress', 'reconciliation_required'] as const) {
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl: async () => Response.json({ status }) });
|
||||
expect(await client.inspect(inspection)).toEqual({ status });
|
||||
}
|
||||
});
|
||||
it('fails closed on unknown, malformed, excessive or unavailable responses', async () => {
|
||||
const responses = [Response.json({ status: 'completed' }), Response.json({ status: 'completed_recorded', documentId: 'doc' }), Response.json({ status: 'not_found', documentId: 'unexpected' }), new Response('x'.repeat(128 * 1024 + 1)), new Response('unavailable', { status: 503 })];
|
||||
for (const response of responses) {
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl: async () => response });
|
||||
await expect(client.inspect(inspection)).rejects.toBeInstanceOf(Doc0InspectionUnavailableError);
|
||||
}
|
||||
});
|
||||
it('rejects invalid fingerprints before sending a request', async () => {
|
||||
const fetchImpl = vi.fn();
|
||||
const client = new Doc0UploadClient({ baseUrl: 'https://doc0.test', serviceToken: 'test', maxBytes: 100, fetchImpl });
|
||||
await expect(client.inspect({ ...inspection, requestFingerprint: 'bad' })).rejects.toThrow(/Invalid/);
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,49 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { exportValidatedOutput } from '../../src/document-workbench/export-validated-output';
|
||||
|
||||
const fields = [
|
||||
{ name: 'name', type: 'string' as const, required: true },
|
||||
{ name: 'count', type: 'integer' as const, required: true },
|
||||
];
|
||||
const sources = [{ id: 'source', text: 'Acme, "North"\n-2' }];
|
||||
const evidence = [
|
||||
{ field: 'name', sourceId: 'source', start: 0, end: 13, transform: 'exact' as const },
|
||||
{ field: 'count', sourceId: 'source', start: 14, end: 16, transform: 'integer' as const },
|
||||
];
|
||||
const input = { fields, sources, evidence, value: { name: 'Acme, "North"', count: -2 } };
|
||||
|
||||
describe('validated document exports', () => {
|
||||
it('preserves JSON values and produces correctly escaped, ordered CSV', () => {
|
||||
const json = exportValidatedOutput({ ...input, format: 'json' });
|
||||
expect(json.status).toBe('ready');
|
||||
if (json.status === 'ready') expect(JSON.parse(json.content)).toEqual(input.value);
|
||||
expect(exportValidatedOutput({ ...input, format: 'csv' })).toEqual({
|
||||
status: 'ready', mediaType: 'text/csv', content: '"name","count"\r\n"Acme, ""North""","-2"\r\n',
|
||||
});
|
||||
});
|
||||
|
||||
it('revalidates evidence and refuses unsupported or absent data', () => {
|
||||
expect(exportValidatedOutput({ ...input, value: { ...input.value, name: 'invented' }, format: 'json' }).status).toBe('needs_review');
|
||||
expect(exportValidatedOutput({ ...input, evidence: [], format: 'csv' }).status).toBe('needs_review');
|
||||
const optional = { ...input, fields: [...fields, { name: 'note', type: 'string' as const, required: false }] };
|
||||
expect(exportValidatedOutput({ ...optional, format: 'csv' })).toMatchObject({ status: 'needs_review', issues: [{ field: 'note', code: 'csv_missing_value' }] });
|
||||
expect(exportValidatedOutput({ ...optional, format: 'json' }).status).toBe('ready');
|
||||
expect(exportValidatedOutput({ ...input, format: 'xml' as 'json' })).toMatchObject({ status: 'needs_review', issues: [{ code: 'unsupported_export_format' }] });
|
||||
});
|
||||
|
||||
it('rejects formula-like CSV values and headers without changing JSON', () => {
|
||||
const bad = { fields: [{ name: 'cell', type: 'string' as const, required: true }], sources: [{ id: 's', text: ' =1+1' }], evidence: [{ field: 'cell', sourceId: 's', start: 0, end: 6, transform: 'exact' as const }], value: { cell: ' =1+1' } };
|
||||
expect(exportValidatedOutput({ ...bad, format: 'csv' })).toMatchObject({ status: 'needs_review', issues: [{ code: 'csv_unsafe_cell' }] });
|
||||
expect(exportValidatedOutput({ ...bad, format: 'json' }).status).toBe('ready');
|
||||
const header = { fields: [{ name: '=header', type: 'string' as const, required: true }], sources: [{ id: 's', text: 'safe' }], evidence: [{ field: '=header', sourceId: 's', start: 0, end: 4, transform: 'exact' as const }], value: { '=header': 'safe' } };
|
||||
expect(exportValidatedOutput({ ...header, format: 'csv' })).toMatchObject({ status: 'needs_review', issues: [{ code: 'csv_unsafe_cell' }] });
|
||||
});
|
||||
|
||||
it('preserves a source-backed decimal as text without floating-point rounding', () => {
|
||||
const text = '9007199254740993.20';
|
||||
const decimal = { fields: [{ name: 'amount', type: 'decimal' as const, required: true }], sources: [{ id: 's', text }], evidence: [{ field: 'amount', sourceId: 's', start: 0, end: text.length, transform: 'decimal' as const }], value: { amount: text } };
|
||||
const result = exportValidatedOutput({ ...decimal, format: 'json' });
|
||||
expect(result.status).toBe('ready');
|
||||
if (result.status === 'ready') expect(JSON.parse(result.content)).toEqual({ amount: text });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,46 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
bindOperationToUploadIdentity,
|
||||
prepareDoc0UploadIdentity,
|
||||
type Doc0UploadInput,
|
||||
} from '../../src/document-workbench/doc0-upload-client';
|
||||
|
||||
const input: Doc0UploadInput = {
|
||||
tenantId: 't1', projectId: 'p1', actorId: 'a1', requestId: 'r1', idempotencyKey: 'k1',
|
||||
filename: 'rapport.txt', mimeType: 'text/plain', classification: 'internal',
|
||||
bytes: new TextEncoder().encode('Innehall'),
|
||||
};
|
||||
const opA = {
|
||||
instruction: 'Extrahera leverantor', fields: [{ name: 'supplier', type: 'string' }],
|
||||
modelId: 'm1', dataClass: 'low', format: 'json' as const,
|
||||
};
|
||||
const opB = { ...opA, instruction: 'Extrahera belopp' };
|
||||
|
||||
describe('operation-scoped upload identity', () => {
|
||||
it('same file + same operation binds to one identity', () => {
|
||||
expect(prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA)))
|
||||
.toEqual(prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA)));
|
||||
});
|
||||
it('same file + DIFFERENT instruction = DIFFERENT identity (not the same operation)', () => {
|
||||
const a = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA));
|
||||
const b = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opB));
|
||||
expect(a.requestFingerprint).not.toBe(b.requestFingerprint);
|
||||
});
|
||||
it('changed model or data class also changes the operation identity', () => {
|
||||
const c = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, { ...opA, modelId: 'm2' }));
|
||||
const d = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, { ...opA, dataClass: 'high' }));
|
||||
const e = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, { ...opA, format: 'csv' }));
|
||||
expect(c.requestFingerprint).not.toBe(prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA)).requestFingerprint);
|
||||
expect(d.requestFingerprint).not.toBe(prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA)).requestFingerprint);
|
||||
expect(e.requestFingerprint).not.toBe(prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA)).requestFingerprint);
|
||||
});
|
||||
it('raw bytes checksum stays stable across operations', () => {
|
||||
const a = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opA));
|
||||
const b = prepareDoc0UploadIdentity(bindOperationToUploadIdentity(input, opB));
|
||||
expect(a.sourceSha256).toBe(b.sourceSha256);
|
||||
});
|
||||
it('prefixes the operation marker so odd filenames cannot collide', () => {
|
||||
const bound = bindOperationToUploadIdentity(input, opA);
|
||||
expect(bound.filename.startsWith('rapport.txt#')).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,59 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { Inf0GatewayClient, Inf0OutcomeUnknownError } from '../../src/document-workbench/inf0-gateway-client';
|
||||
import type { ModelAdmissionRequest, ModelBudgetReservation, ModelExecutionPolicy } from '../../src/document-workbench/model-admission';
|
||||
import type { SiaxRequestContext } from '../../src/platform/siax-context';
|
||||
|
||||
const context: SiaxRequestContext = { tenantId: 'a', projectId: 'p', actorId: 'user', capability: 'inf0.complete', correlationId: 'corr' };
|
||||
const admission: ModelAdmissionRequest = { tenantId: 'a', projectId: 'p', jobId: 'j', modelId: 'local_only', dataClass: 'high', maxInputTokens: 100, maxOutputTokens: 20, maximumCredits: 5 };
|
||||
const policy: ModelExecutionPolicy = { tenantId: 'a', projectId: 'p', allowedModelIds: ['local_only'], allowedDataClasses: ['high'], destination: 'internal', externalTransferAllowed: false, maxInputTokens: 100, maxOutputTokens: 20 };
|
||||
const reservation: ModelBudgetReservation = { tenantId: 'a', projectId: 'p', jobId: 'j', status: 'reserved', credits: 5 };
|
||||
const input = { context, admission, policy, reservation, inputTokens: 10, messages: [{ role: 'user' as const, content: 'source' }] };
|
||||
const result = { content: '{"name":"Acme"}', modelExecuted: 'model-v1', finishReason: 'stop', routeDecision: { route: 'local_only', providerKind: 'local' }, cost: { promptTokens: 10, completionTokens: 5, totalTokens: 15 } };
|
||||
|
||||
describe('INF0 gateway adapter', () => {
|
||||
it('admits and scopes a request using the Wave-2 contract without inventing cost', async () => {
|
||||
const fetchMock = vi.fn(async () => Response.json(result));
|
||||
const client = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: fetchMock });
|
||||
const receipt = await client.complete(input);
|
||||
expect(receipt).toMatchObject({ status: 'model_stopped', modelExecuted: 'model-v1', totalTokens: 15 });
|
||||
expect(receipt.costUsd).toBeUndefined();
|
||||
const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
|
||||
expect(url).toBe('https://inf0.example.test/v1/inf0/gateway/complete');
|
||||
expect(JSON.parse(String(init.body))).toMatchObject({ route: 'local_only', data_classification: 'high', risk_level: 'L3', max_tokens: 20 });
|
||||
expect(init.redirect).toBe('error');
|
||||
});
|
||||
it('denies an unreserved or cross-tenant job before network access', async () => {
|
||||
const fetchMock = vi.fn();
|
||||
const client = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: fetchMock });
|
||||
await expect(client.complete({ ...input, reservation: undefined })).rejects.toThrow('reservation_required');
|
||||
await expect(client.complete({ ...input, context: { ...context, tenantId: 'other' } })).rejects.toThrow('Invalid scoped');
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
it('reports incomplete output for truncation or absent usage', async () => {
|
||||
const fetchMock = vi.fn(async () => Response.json({ ...result, finishReason: 'length', cost: { promptTokens: 0, completionTokens: 0, totalTokens: 0 } }));
|
||||
const client = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: fetchMock });
|
||||
expect((await client.complete(input)).status).toBe('needs_review');
|
||||
});
|
||||
it('does not retry unknown results, mismatched destinations or transport failures', async () => {
|
||||
const fetchMock = vi.fn(async () => Response.json({ ...result, routeDecision: { route: 'local_only', providerKind: 'external' } }));
|
||||
const client = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: fetchMock });
|
||||
await expect(client.complete(input)).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
expect(fetchMock).toHaveBeenCalledOnce();
|
||||
const failing = vi.fn(async () => { throw new Error('socket closed'); });
|
||||
await expect(new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: failing }).complete(input)).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
expect(failing).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('checks the provider and usage against the policy fixed at dispatch time', async () => {
|
||||
const mutable = structuredClone(input);
|
||||
const fetchMock = vi.fn(async () => {
|
||||
mutable.policy.destination = 'external';
|
||||
mutable.admission.maxOutputTokens = 1000;
|
||||
return Response.json({ ...result, routeDecision: { route: 'local_only', providerKind: 'external' },
|
||||
cost: { promptTokens: 10, completionTokens: 100, totalTokens: 110 } });
|
||||
});
|
||||
const client = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl: fetchMock });
|
||||
await expect(client.complete(mutable)).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
expect(fetchMock).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
});
|
||||
@@ -0,0 +1,171 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { LiteLlmGatewayClient } from '../../src/document-workbench/litellm-gateway-client';
|
||||
import { Inf0OutcomeUnknownError } from '../../src/document-workbench/inf0-gateway-client';
|
||||
import { createInf0Gateway } from '../../src/document-workbench/inf0-gateway';
|
||||
|
||||
const context = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
actorId: 'user_1',
|
||||
capability: '0pt.document.structure.v1',
|
||||
correlationId: 'corr-1',
|
||||
};
|
||||
const admission = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
jobId: 'job-1',
|
||||
modelId: 'inf0-standard',
|
||||
dataClass: 'low',
|
||||
maxInputTokens: 1000,
|
||||
maxOutputTokens: 200,
|
||||
maximumCredits: 5,
|
||||
};
|
||||
const policy = {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
allowedModelIds: ['inf0-standard'],
|
||||
allowedDataClasses: ['low'],
|
||||
destination: 'external' as const,
|
||||
externalTransferAllowed: true,
|
||||
maxInputTokens: 1000,
|
||||
maxOutputTokens: 200,
|
||||
};
|
||||
const messages = [
|
||||
{ role: 'system' as const, content: 'system' },
|
||||
{ role: 'user' as const, content: 'data' },
|
||||
];
|
||||
|
||||
function gateway(fetchImpl: typeof fetch, providerKind: 'local' | 'external' = 'external') {
|
||||
return new LiteLlmGatewayClient({
|
||||
baseUrl: 'https://ai-gateway.siax.io/v1',
|
||||
apiKey: 'sk-test',
|
||||
providerKind,
|
||||
fetchImpl,
|
||||
});
|
||||
}
|
||||
|
||||
function ok(payload: unknown): Response {
|
||||
return new Response(JSON.stringify(payload), { status: 200 });
|
||||
}
|
||||
|
||||
describe('LiteLLM INF0 adapter', () => {
|
||||
it('maps an OpenAI-compatible response into the INF0 receipt', async () => {
|
||||
const client = gateway(async () =>
|
||||
ok({
|
||||
model: 'inf0-standard',
|
||||
choices: [{ message: { content: '{"ok":true}' }, finish_reason: 'stop' }],
|
||||
usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
|
||||
}),
|
||||
);
|
||||
await expect(
|
||||
client.complete({
|
||||
context,
|
||||
admission,
|
||||
policy,
|
||||
reservation: {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
jobId: 'job-1',
|
||||
status: 'reserved',
|
||||
credits: 5,
|
||||
},
|
||||
inputTokens: 10,
|
||||
messages,
|
||||
}),
|
||||
).resolves.toMatchObject({
|
||||
status: 'model_stopped',
|
||||
content: '{"ok":true}',
|
||||
modelExecuted: 'inf0-standard',
|
||||
providerKind: 'external',
|
||||
totalTokens: 15,
|
||||
});
|
||||
});
|
||||
|
||||
it('denies a model outside the allow-list before any request', async () => {
|
||||
let called = false;
|
||||
const client = gateway(async () => {
|
||||
called = true;
|
||||
return ok({});
|
||||
});
|
||||
await expect(
|
||||
client.complete({
|
||||
context,
|
||||
admission: { ...admission, modelId: 'inf0-frontier' },
|
||||
policy,
|
||||
reservation: undefined,
|
||||
inputTokens: 10,
|
||||
messages,
|
||||
}),
|
||||
).rejects.toThrow(/denied/i);
|
||||
expect(called).toBe(false);
|
||||
});
|
||||
|
||||
it('refuses an external provider when the policy requires internal', async () => {
|
||||
const client = gateway(
|
||||
async () =>
|
||||
ok({
|
||||
model: 'inf0-standard',
|
||||
choices: [{ message: { content: 'x' }, finish_reason: 'stop' }],
|
||||
usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
|
||||
}),
|
||||
'external',
|
||||
);
|
||||
await expect(
|
||||
client.complete({
|
||||
context,
|
||||
admission,
|
||||
policy: { ...policy, destination: 'internal' },
|
||||
reservation: {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
jobId: 'job-1',
|
||||
status: 'reserved',
|
||||
credits: 5,
|
||||
},
|
||||
inputTokens: 1,
|
||||
messages,
|
||||
}),
|
||||
).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
});
|
||||
|
||||
it('treats malformed or inconsistent usage as an unknown outcome', async () => {
|
||||
const client = gateway(async () =>
|
||||
ok({
|
||||
model: 'inf0-standard',
|
||||
choices: [{ message: { content: 'x' }, finish_reason: 'stop' }],
|
||||
usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 99 },
|
||||
}),
|
||||
);
|
||||
await expect(
|
||||
client.complete({
|
||||
context,
|
||||
admission,
|
||||
policy,
|
||||
reservation: {
|
||||
tenantId: 't_0pt',
|
||||
projectId: 'prj_alpha',
|
||||
jobId: 'job-1',
|
||||
status: 'reserved',
|
||||
credits: 5,
|
||||
},
|
||||
inputTokens: 1,
|
||||
messages,
|
||||
}),
|
||||
).rejects.toBeInstanceOf(Inf0OutcomeUnknownError);
|
||||
});
|
||||
|
||||
it('prefers the live LiteLLM key and falls back to the native surface', () => {
|
||||
expect(createInf0Gateway({} as unknown as NodeJS.ProcessEnv)).toBeUndefined();
|
||||
expect(
|
||||
createInf0Gateway({
|
||||
INF0_GATEWAY_LITELLM_KEY: 'sk-test',
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).toBeInstanceOf(LiteLlmGatewayClient);
|
||||
expect(
|
||||
createInf0Gateway({
|
||||
INF0_URL: 'https://api.inf0.siax.io',
|
||||
INF0_API_TOKEN: 'token',
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).toBeDefined();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,33 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { admitModelExecution, type ModelAdmissionRequest, type ModelBudgetReservation, type ModelExecutionPolicy } from '../../src/document-workbench/model-admission';
|
||||
|
||||
const request: ModelAdmissionRequest = { tenantId: 'a', projectId: 'p', jobId: 'j', modelId: 'model', dataClass: 'medium', maxInputTokens: 100, maxOutputTokens: 50, maximumCredits: 10 };
|
||||
const policy: ModelExecutionPolicy = { tenantId: 'a', projectId: 'p', allowedModelIds: ['model'], allowedDataClasses: ['medium'], destination: 'external', externalTransferAllowed: true, maxInputTokens: 100, maxOutputTokens: 50 };
|
||||
const hold: ModelBudgetReservation = { tenantId: 'a', projectId: 'p', jobId: 'j', status: 'reserved', credits: 10 };
|
||||
describe('model execution admission', () => {
|
||||
it('requires a scoped allowed model, data policy and sufficient reservation', () => {
|
||||
expect(admitModelExecution(request, policy, hold)).toEqual({ allowed: true });
|
||||
expect(admitModelExecution(request, { ...policy, projectId: 'other' }, hold)).toEqual({ allowed: false, reason: 'scope_mismatch' });
|
||||
expect(admitModelExecution(request, { ...policy, allowedModelIds: [] }, hold)).toEqual({ allowed: false, reason: 'model_not_allowed' });
|
||||
expect(admitModelExecution(request, { ...policy, allowedDataClasses: [] }, hold)).toEqual({ allowed: false, reason: 'data_class_not_allowed' });
|
||||
expect(admitModelExecution(request, { ...policy, externalTransferAllowed: false }, hold)).toEqual({ allowed: false, reason: 'external_transfer_denied' });
|
||||
expect(admitModelExecution({ ...request, dataClass: 'high' }, { ...policy, allowedDataClasses: ['high'] }, hold)).toEqual({ allowed: false, reason: 'external_transfer_denied' });
|
||||
expect(admitModelExecution({ ...request, dataClass: 'restricted' }, { ...policy, allowedDataClasses: ['restricted'] }, hold)).toEqual({ allowed: false, reason: 'external_transfer_denied' });
|
||||
expect(admitModelExecution({ ...request, maxOutputTokens: 51 }, policy, hold)).toEqual({ allowed: false, reason: 'token_limit_exceeded' });
|
||||
expect(admitModelExecution(request, policy, { ...hold, credits: 9 })).toEqual({ allowed: false, reason: 'reservation_required' });
|
||||
expect(admitModelExecution(request, policy, { ...hold, status: 'settled' })).toEqual({ allowed: false, reason: 'reservation_required' });
|
||||
expect(admitModelExecution(request, policy, { ...hold, jobId: 'other' })).toEqual({ allowed: false, reason: 'reservation_required' });
|
||||
});
|
||||
it('pilot mode (maximumCredits 0) requires no reservation but still enforces every other rule', () => {
|
||||
const pilot = { ...request, maximumCredits: 0 };
|
||||
expect(admitModelExecution(pilot, policy, undefined)).toEqual({ allowed: true });
|
||||
expect(admitModelExecution(pilot, { ...policy, allowedModelIds: [] }, undefined)).toEqual({ allowed: false, reason: 'model_not_allowed' });
|
||||
expect(admitModelExecution(pilot, { ...policy, projectId: 'other' }, undefined)).toEqual({ allowed: false, reason: 'scope_mismatch' });
|
||||
expect(admitModelExecution({ ...pilot, maximumCredits: -1 }, policy, undefined)).toEqual({ allowed: false, reason: 'invalid_request' });
|
||||
expect(admitModelExecution(request, policy, undefined)).toEqual({ allowed: false, reason: 'reservation_required' });
|
||||
});
|
||||
it('rejects invalid limits and never treats an unknown destination as local', () => {
|
||||
expect(admitModelExecution({ ...request, maxInputTokens: NaN }, policy, hold).allowed).toBe(false);
|
||||
expect(admitModelExecution(request, { ...policy, destination: 'unknown' as never }, hold).allowed).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,101 @@
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import { Pay0CreditVerifier } from '../../src/document-workbench/pay0-credit-verification';
|
||||
|
||||
const snapshot = {
|
||||
tenantId: 'tenant-a',
|
||||
purchaseId: 'purchase-1',
|
||||
checkoutSessionId: 'session-1',
|
||||
amountMinor: 1000,
|
||||
currency: 'SEK',
|
||||
credits: 50,
|
||||
};
|
||||
const context = {
|
||||
tenantId: 'tenant-a',
|
||||
actorId: 'svc-0pt',
|
||||
capability: '0pt.credit.purchase',
|
||||
correlationId: 'req-1',
|
||||
};
|
||||
const checkout = {
|
||||
id: 'session-1',
|
||||
tenant_id: 'tenant-a',
|
||||
payment_intent_id: 'intent-1',
|
||||
payable_type: '0pt_credit_purchase',
|
||||
payable_ref: 'purchase-1',
|
||||
amount_snapshot: 1000,
|
||||
currency: 'SEK',
|
||||
status: 'completed',
|
||||
provider: 'stripe',
|
||||
provider_reference: 'stripe-session',
|
||||
};
|
||||
const intent = {
|
||||
id: 'intent-1',
|
||||
tenant_id: 'tenant-a',
|
||||
payable_type: '0pt_credit_purchase',
|
||||
payable_ref: 'purchase-1',
|
||||
amount: 1000,
|
||||
currency: 'SEK',
|
||||
canonical_status: 'captured',
|
||||
captured_amount: 1000,
|
||||
refunded_amount: 0,
|
||||
};
|
||||
|
||||
function mockPay0(checkoutPatch: Record<string, unknown> = {}, intentPatch: Record<string, unknown> = {}) {
|
||||
return vi.stubGlobal(
|
||||
'fetch',
|
||||
vi.fn(
|
||||
async (url: string) =>
|
||||
new Response(
|
||||
JSON.stringify({
|
||||
data: url.includes('checkout-sessions')
|
||||
? { ...checkout, ...checkoutPatch }
|
||||
: { ...intent, ...intentPatch },
|
||||
}),
|
||||
{ status: 200, headers: { 'content-type': 'application/json' } },
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
|
||||
describe('PAY0 credit verification', () => {
|
||||
it('derives a deterministic credit command only after both PAY0 reads match', async () => {
|
||||
mockPay0();
|
||||
const command = await new Pay0CreditVerifier('https://pay0.test', 'service-token').verify(
|
||||
snapshot,
|
||||
context,
|
||||
);
|
||||
expect(command).toEqual({
|
||||
tenantId: 'tenant-a',
|
||||
idempotencyKey: 'pay0:credit-purchase:purchase-1',
|
||||
kind: 'verified_payment',
|
||||
reference: 'pay0:intent:intent-1',
|
||||
amount: 50,
|
||||
});
|
||||
expect(fetch).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
it.each([
|
||||
[{ tenant_id: 'tenant-b' }, {}],
|
||||
[{ status: 'processing' }, {}],
|
||||
[{ amount_snapshot: 1 }, {}],
|
||||
[{ provider_reference: undefined }, {}],
|
||||
[{}, { canonical_status: 'processing' }],
|
||||
[{}, { refunded_amount: 1 }],
|
||||
[{}, { captured_amount: 999 }],
|
||||
[{}, { payable_ref: 'other' }],
|
||||
])('rejects mismatched or unconfirmed payment state', async (checkoutPatch, intentPatch) => {
|
||||
mockPay0(checkoutPatch, intentPatch);
|
||||
await expect(
|
||||
new Pay0CreditVerifier('https://pay0.test', 'service-token').verify(snapshot, context),
|
||||
).rejects.toThrow();
|
||||
});
|
||||
it('rejects mismatched tenant before any call', async () => {
|
||||
mockPay0();
|
||||
await expect(
|
||||
new Pay0CreditVerifier('https://pay0.test', 'service-token').verify(snapshot, {
|
||||
...context,
|
||||
tenantId: 'other',
|
||||
}),
|
||||
).rejects.toThrow();
|
||||
expect(fetch).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,49 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
creditsForUsage,
|
||||
findPack,
|
||||
parseCreditPriceBook,
|
||||
readCreditPriceBook,
|
||||
} from '../../src/document-workbench/price-book';
|
||||
|
||||
const valid = {
|
||||
version: '2026-11-01',
|
||||
currency: 'SEK',
|
||||
packs: [
|
||||
{ id: 'starter', credits: 100, amountMinor: 9900 },
|
||||
{ id: 'pro', credits: 2000, amountMinor: 129900 },
|
||||
],
|
||||
metering: { pagesPerCredit: 5, inputTokensPerCredit: 20000, outputTokensPerCredit: 4000 },
|
||||
};
|
||||
|
||||
describe('credit price book', () => {
|
||||
it('parses a valid server-owned price book', () => {
|
||||
const book = parseCreditPriceBook(valid);
|
||||
expect(book.packs).toHaveLength(2);
|
||||
expect(findPack(book, 'pro')?.credits).toBe(2000);
|
||||
});
|
||||
|
||||
it('fails closed when the env price book is absent or invalid', () => {
|
||||
expect(readCreditPriceBook({} as unknown as NodeJS.ProcessEnv)).toBeUndefined();
|
||||
expect(readCreditPriceBook({ OPT_CREDIT_PRICE_BOOK: '{not json' } as unknown as NodeJS.ProcessEnv)).toBeUndefined();
|
||||
expect(
|
||||
readCreditPriceBook({
|
||||
OPT_CREDIT_PRICE_BOOK: JSON.stringify({ ...valid, currency: 'sek' }),
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it('rejects duplicate pack ids, unknown currencies and non-integer money', () => {
|
||||
expect(() => parseCreditPriceBook({ ...valid, packs: [valid.packs[0], valid.packs[0]] })).toThrow();
|
||||
expect(() =>
|
||||
parseCreditPriceBook({ ...valid, packs: [{ id: 'x', credits: 1, amountMinor: 1.5 }] }),
|
||||
).toThrow();
|
||||
});
|
||||
|
||||
it('rounds every metered component up to its billing block', () => {
|
||||
const book = parseCreditPriceBook(valid);
|
||||
expect(creditsForUsage(book, { pages: 0, inputTokens: 0, outputTokens: 0 })).toBe(0);
|
||||
expect(creditsForUsage(book, { pages: 1, inputTokens: 1, outputTokens: 1 })).toBe(3);
|
||||
expect(creditsForUsage(book, { pages: 6, inputTokens: 40001, outputTokens: 8001 })).toBe(8);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
createProjectAuthorizer,
|
||||
parseProjectGrants,
|
||||
projectAuthorizationConfigured,
|
||||
} from '../../src/document-workbench/project-access';
|
||||
|
||||
const scope = { tenantId: 't_0pt', projectId: 'prj_alpha', actorId: 'user_1' };
|
||||
|
||||
describe('project authorization', () => {
|
||||
it('fails closed when neither OpenFGA nor explicit grants are configured', async () => {
|
||||
const env = {} as unknown as NodeJS.ProcessEnv;
|
||||
expect(projectAuthorizationConfigured(env)).toBe(false);
|
||||
await expect(createProjectAuthorizer(env)(scope)).resolves.toBe(false);
|
||||
});
|
||||
|
||||
it('honours an exact actor grant and rejects a different actor or project', async () => {
|
||||
const env = {
|
||||
OPT_PROJECT_GRANTS: JSON.stringify([{ tenantId: 't_0pt', projectId: 'prj_alpha', actorId: 'user_1' }]),
|
||||
} as unknown as NodeJS.ProcessEnv;
|
||||
const authorize = createProjectAuthorizer(env);
|
||||
await expect(authorize(scope)).resolves.toBe(true);
|
||||
await expect(authorize({ ...scope, actorId: 'user_2' })).resolves.toBe(false);
|
||||
await expect(authorize({ ...scope, projectId: 'prj_beta' })).resolves.toBe(false);
|
||||
await expect(authorize({ ...scope, tenantId: 't_other' })).resolves.toBe(false);
|
||||
});
|
||||
|
||||
it('supports a tenant-wide wildcard actor', async () => {
|
||||
const env = {
|
||||
OPT_PROJECT_GRANTS: JSON.stringify([{ tenantId: 't_0pt', projectId: 'prj_alpha', actorId: '*' }]),
|
||||
} as unknown as NodeJS.ProcessEnv;
|
||||
await expect(createProjectAuthorizer(env)({ ...scope, actorId: 'anyone' })).resolves.toBe(true);
|
||||
});
|
||||
|
||||
it('treats an invalid grant document as unconfigured', () => {
|
||||
expect(parseProjectGrants('{not json')).toBeUndefined();
|
||||
expect(parseProjectGrants(JSON.stringify([]))).toBeUndefined();
|
||||
expect(parseProjectGrants(JSON.stringify([{ tenantId: 't', projectId: 'p' }]))).toBeUndefined();
|
||||
expect(
|
||||
projectAuthorizationConfigured({
|
||||
OPT_PROJECT_GRANTS: 'not-json',
|
||||
} as unknown as NodeJS.ProcessEnv),
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,116 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type Stripe from 'stripe';
|
||||
import {
|
||||
StripeCreditVerificationError,
|
||||
verifyStripeCreditPurchase,
|
||||
type StripeCheckoutReader,
|
||||
} from '../../src/document-workbench/stripe-credit-verification';
|
||||
|
||||
const snapshot = {
|
||||
tenantId: 't_0pt',
|
||||
purchaseId: 'purchase-1',
|
||||
checkoutSessionId: 'cs_test_1',
|
||||
amountMinor: 9900,
|
||||
currency: 'SEK',
|
||||
credits: 100,
|
||||
};
|
||||
|
||||
function stripeReturning(session: unknown): StripeCheckoutReader {
|
||||
return {
|
||||
checkout: {
|
||||
sessions: {
|
||||
retrieve: async () => session as Stripe.Checkout.Session,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function session(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
id: 'cs_test_1',
|
||||
metadata: {
|
||||
kind: '0pt_credit_purchase',
|
||||
tenant_id: 't_0pt',
|
||||
purchase_id: 'purchase-1',
|
||||
},
|
||||
amount_total: 9900,
|
||||
currency: 'sek',
|
||||
payment_status: 'paid',
|
||||
payment_intent: {
|
||||
id: 'pi_123',
|
||||
status: 'succeeded',
|
||||
currency: 'sek',
|
||||
amount_received: 9900,
|
||||
},
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('Stripe credit verification', () => {
|
||||
it('derives an idempotent verified-payment command from the re-read session', async () => {
|
||||
const command = await verifyStripeCreditPurchase(stripeReturning(session()), snapshot, {
|
||||
tenantId: 't_0pt',
|
||||
});
|
||||
expect(command).toEqual({
|
||||
tenantId: 't_0pt',
|
||||
idempotencyKey: 'credit_purchase:t_0pt:purchase-1',
|
||||
kind: 'verified_payment',
|
||||
reference: 'pi_123',
|
||||
amount: 100,
|
||||
});
|
||||
});
|
||||
|
||||
it('refuses a session that belongs to another tenant or purchase', async () => {
|
||||
await expect(
|
||||
verifyStripeCreditPurchase(
|
||||
stripeReturning(
|
||||
session({ metadata: { kind: '0pt_credit_purchase', tenant_id: 't_b', purchase_id: 'purchase-1' } }),
|
||||
),
|
||||
snapshot,
|
||||
{ tenantId: 't_0pt' },
|
||||
),
|
||||
).rejects.toBeInstanceOf(StripeCreditVerificationError);
|
||||
});
|
||||
|
||||
it('refuses an amount that differs from the server price snapshot', async () => {
|
||||
await expect(
|
||||
verifyStripeCreditPurchase(stripeReturning(session({ amount_total: 100 })), snapshot, {
|
||||
tenantId: 't_0pt',
|
||||
}),
|
||||
).rejects.toMatchObject({ reason: 'mismatch' });
|
||||
});
|
||||
|
||||
it('refuses an unpaid session or a non-succeeded payment intent', async () => {
|
||||
await expect(
|
||||
verifyStripeCreditPurchase(stripeReturning(session({ payment_status: 'unpaid' })), snapshot, {
|
||||
tenantId: 't_0pt',
|
||||
}),
|
||||
).rejects.toMatchObject({ reason: 'not_paid' });
|
||||
await expect(
|
||||
verifyStripeCreditPurchase(
|
||||
stripeReturning(
|
||||
session({
|
||||
payment_intent: { id: 'pi_123', status: 'processing', currency: 'sek', amount_received: 0 },
|
||||
}),
|
||||
),
|
||||
snapshot,
|
||||
{ tenantId: 't_0pt' },
|
||||
),
|
||||
).rejects.toMatchObject({ reason: 'not_paid' });
|
||||
});
|
||||
|
||||
it('refuses a mismatched caller tenant before any Stripe call', async () => {
|
||||
const reader = {
|
||||
checkout: {
|
||||
sessions: {
|
||||
retrieve: async () => {
|
||||
throw new Error('should not be called');
|
||||
},
|
||||
},
|
||||
},
|
||||
} as unknown as StripeCheckoutReader;
|
||||
await expect(verifyStripeCreditPurchase(reader, snapshot, { tenantId: 't_b' })).rejects.toMatchObject({
|
||||
reason: 'mismatch',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,245 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { structureDocument } from '../../src/document-workbench/structure-document';
|
||||
import { Inf0GatewayClient, type Inf0GatewayReceipt } from '../../src/document-workbench/inf0-gateway-client';
|
||||
|
||||
type Req = Omit<Parameters<Inf0GatewayClient['complete']>[0], 'messages' | 'inputTokens'>;
|
||||
const request = {
|
||||
context: { tenantId: 'a', projectId: 'p', actorId: 'u', capability: 'inf0.complete', correlationId: 'c' },
|
||||
admission: {
|
||||
tenantId: 'a',
|
||||
projectId: 'p',
|
||||
jobId: 'j',
|
||||
modelId: 'local_only',
|
||||
dataClass: 'high',
|
||||
maxInputTokens: 200,
|
||||
maxOutputTokens: 100,
|
||||
maximumCredits: 5,
|
||||
},
|
||||
policy: {
|
||||
tenantId: 'a',
|
||||
projectId: 'p',
|
||||
allowedModelIds: ['local_only'],
|
||||
allowedDataClasses: ['high'],
|
||||
destination: 'internal',
|
||||
externalTransferAllowed: false,
|
||||
maxInputTokens: 200,
|
||||
maxOutputTokens: 100,
|
||||
},
|
||||
reservation: { tenantId: 'a', projectId: 'p', jobId: 'j', status: 'reserved', credits: 5 },
|
||||
} satisfies Req;
|
||||
const response: Inf0GatewayReceipt = {
|
||||
status: 'model_stopped',
|
||||
content: JSON.stringify({
|
||||
value: { name: 'Acme' },
|
||||
evidence: [{ field: 'name', sourceId: 'page1', start: 6, end: 10, transform: 'exact' }],
|
||||
}),
|
||||
modelExecuted: 'm1',
|
||||
providerKind: 'local',
|
||||
promptTokens: 50,
|
||||
completionTokens: 20,
|
||||
totalTokens: 70,
|
||||
};
|
||||
const base = {
|
||||
request,
|
||||
countTokens: vi.fn(async () => 50),
|
||||
instructions: 'Extract the customer name',
|
||||
fields: [{ name: 'name', type: 'string' as const, required: true }],
|
||||
sources: [{ id: 'page1', text: 'Name: Acme' }],
|
||||
};
|
||||
describe('structure document workflow', () => {
|
||||
it('returns only source-supported values and carries model usage without raw prompt', async () => {
|
||||
const complete = vi.fn(async () => response);
|
||||
const out = await structureDocument({ ...base, gateway: { complete } });
|
||||
expect(out).toMatchObject({
|
||||
status: 'mechanically_validated',
|
||||
value: { name: 'Acme' },
|
||||
model: { modelExecuted: 'm1' },
|
||||
});
|
||||
expect(out.model).not.toHaveProperty('content');
|
||||
expect(complete).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('sends hallucinated data, invalid JSON and truncated output to review', async () => {
|
||||
const fake = {
|
||||
...response,
|
||||
content: JSON.stringify({
|
||||
value: { name: 'Other' },
|
||||
evidence: [{ field: 'name', sourceId: 'page1', start: 6, end: 10, transform: 'exact' }],
|
||||
}),
|
||||
};
|
||||
expect(
|
||||
(await structureDocument({ ...base, gateway: { complete: vi.fn(async () => fake) } })).status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
(
|
||||
await structureDocument({
|
||||
...base,
|
||||
gateway: { complete: vi.fn(async () => ({ ...response, content: 'not json' })) },
|
||||
})
|
||||
).status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
(
|
||||
await structureDocument({
|
||||
...base,
|
||||
gateway: { complete: vi.fn(async () => ({ ...response, status: 'needs_review' as const })) },
|
||||
})
|
||||
).status,
|
||||
).toBe('needs_review');
|
||||
});
|
||||
it('runs through the real INF0 adapter and rejects an ungrounded response', async () => {
|
||||
const fetchMock = vi.fn(async () =>
|
||||
Response.json({
|
||||
content: response.content,
|
||||
modelExecuted: 'm1',
|
||||
finishReason: 'stop',
|
||||
routeDecision: { route: 'local_only', providerKind: 'local' },
|
||||
cost: { promptTokens: 50, completionTokens: 20, totalTokens: 70 },
|
||||
}),
|
||||
);
|
||||
const gateway = new Inf0GatewayClient({
|
||||
baseUrl: 'https://inf0.example.test',
|
||||
serviceToken: 'test',
|
||||
fetchImpl: fetchMock,
|
||||
});
|
||||
const out = await structureDocument({ ...base, gateway });
|
||||
expect(out).toMatchObject({ status: 'mechanically_validated', value: { name: 'Acme' } });
|
||||
const call = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
|
||||
const body = JSON.parse(String(call[1].body));
|
||||
expect(body.messages[1].content).toContain('Name: Acme');
|
||||
expect(body.data_classification).toBe('high');
|
||||
});
|
||||
|
||||
it('computes evidence deterministically when a local model returns values only', async () => {
|
||||
const out = await structureDocument({
|
||||
...base,
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({ ...response, content: JSON.stringify({ value: { name: 'Acme' } }) })),
|
||||
},
|
||||
});
|
||||
expect(out).toMatchObject({ status: 'mechanically_validated', value: { name: 'Acme' } });
|
||||
if (out.status !== 'mechanically_validated') throw new Error('expected validated');
|
||||
expect(out.evidence).toEqual([
|
||||
{ field: 'name', sourceId: 'page1', start: 6, end: 10, transform: 'exact' },
|
||||
]);
|
||||
});
|
||||
it('accepts a flat object or a fenced JSON object from a small local model', async () => {
|
||||
const flat = await structureDocument({
|
||||
...base,
|
||||
gateway: { complete: vi.fn(async () => ({ ...response, content: JSON.stringify({ name: 'Acme' }) })) },
|
||||
});
|
||||
expect(flat).toMatchObject({ status: 'mechanically_validated', value: { name: 'Acme' } });
|
||||
const fenced = await structureDocument({
|
||||
...base,
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({ ...response, content: '```json\n{"value":{"name":"Acme"}}\n```' })),
|
||||
},
|
||||
});
|
||||
expect(fenced).toMatchObject({ status: 'mechanically_validated', value: { name: 'Acme' } });
|
||||
});
|
||||
it('refuses ambiguous or absent values when computing evidence itself', async () => {
|
||||
const twice = await structureDocument({
|
||||
...base,
|
||||
sources: [{ id: 'p1', text: 'Acme AB and Acme AB' }],
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({
|
||||
...response,
|
||||
content: JSON.stringify({ value: { name: 'Acme AB' } }),
|
||||
})),
|
||||
},
|
||||
});
|
||||
expect(twice.status).toBe('needs_review');
|
||||
const absent = await structureDocument({
|
||||
...base,
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({
|
||||
...response,
|
||||
content: JSON.stringify({ value: { name: 'Globex' } }),
|
||||
})),
|
||||
},
|
||||
});
|
||||
expect(absent.status).toBe('needs_review');
|
||||
});
|
||||
it('derives evidence for decimals and dates from locale-formatted source text', async () => {
|
||||
const out = await structureDocument({
|
||||
request,
|
||||
countTokens: vi.fn(async () => 50),
|
||||
instructions: 'Extract amount and due date',
|
||||
fields: [
|
||||
{ name: 'amount', type: 'decimal' as const, required: true },
|
||||
{ name: 'due', type: 'date' as const, required: true },
|
||||
],
|
||||
sources: [{ id: 'p1', text: 'Belopp: 12 500,00 SEK\nFörfallodatum: 14/10/2026' }],
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({
|
||||
...response,
|
||||
content: JSON.stringify({ value: { amount: '12500.00', due: '2026-10-14' } }),
|
||||
})),
|
||||
},
|
||||
});
|
||||
expect(out.status).toBe('mechanically_validated');
|
||||
if (out.status !== 'mechanically_validated') throw new Error('expected validated');
|
||||
expect(out.evidence.map((e) => e.transform)).toEqual(['decimal', 'date']);
|
||||
expect(out.evidence[0]).toMatchObject({ start: 8, end: 17 });
|
||||
});
|
||||
it('rewrites a JSON-number decimal to the exact source string (no rounding)', async () => {
|
||||
const out = await structureDocument({
|
||||
request,
|
||||
countTokens: vi.fn(async () => 50),
|
||||
instructions: 'Extract the amount',
|
||||
fields: [{ name: 'amount', type: 'decimal' as const, required: true }],
|
||||
sources: [{ id: 'p1', text: 'Belopp: 12 500,00 SEK' }],
|
||||
gateway: {
|
||||
complete: vi.fn(async () => ({ ...response, content: JSON.stringify({ amount: 12500 }) })),
|
||||
},
|
||||
});
|
||||
expect(out.status).toBe('mechanically_validated');
|
||||
if (out.status !== 'mechanically_validated') throw new Error('expected validated');
|
||||
expect(out.value.amount).toBe('12500.00');
|
||||
});
|
||||
it('rejects malformed contracts before a model call', async () => {
|
||||
const complete = vi.fn(async () => response);
|
||||
await expect(structureDocument({ ...base, fields: [], gateway: { complete } })).rejects.toThrow(
|
||||
'Invalid structure',
|
||||
);
|
||||
expect(complete).not.toHaveBeenCalled();
|
||||
});
|
||||
it('validates against the exact source and field contract supplied before async tokenization', async () => {
|
||||
const sources = [{ id: 'page1', text: 'Name: Evil' }];
|
||||
const fields = [{ name: 'name', type: 'string' as const, required: true }];
|
||||
const countTokens = vi.fn(async () => {
|
||||
sources[0]!.text = 'Name: Acme';
|
||||
fields[0]!.required = false;
|
||||
return 50;
|
||||
});
|
||||
const complete = vi.fn<Inf0GatewayClient['complete']>(async () => response);
|
||||
const result = await structureDocument({ ...base, sources, fields, countTokens, gateway: { complete } });
|
||||
expect(result).toMatchObject({
|
||||
status: 'needs_review',
|
||||
issues: [{ field: 'name', code: 'evidence_mismatch' }],
|
||||
});
|
||||
expect(complete.mock.calls[0]?.[0]?.messages[1]?.content).toContain('Name: Evil');
|
||||
});
|
||||
it('uses the original admission and policy even if the caller mutates its request during tokenization', async () => {
|
||||
const mutableRequest = structuredClone(request);
|
||||
const countTokens = vi.fn(async () => {
|
||||
mutableRequest.admission.modelId = 'changed';
|
||||
mutableRequest.policy.allowedModelIds.push('changed');
|
||||
return 50;
|
||||
});
|
||||
const complete = vi.fn<Inf0GatewayClient['complete']>(async () => response);
|
||||
await structureDocument({ ...base, request: mutableRequest, countTokens, gateway: { complete } });
|
||||
expect(complete.mock.calls[0]?.[0]?.admission.modelId).toBe('local_only');
|
||||
expect(complete.mock.calls[0]?.[0]?.policy.allowedModelIds).toEqual(['local_only']);
|
||||
});
|
||||
|
||||
it('keeps tokenizer input identical to the message sent to the gateway', async () => {
|
||||
const countTokens = vi.fn(async (messages: Parameters<Inf0GatewayClient['complete']>[0]['messages']) => {
|
||||
expect(Object.isFrozen(messages)).toBe(true);
|
||||
expect(Object.isFrozen(messages[1])).toBe(true);
|
||||
return 50;
|
||||
});
|
||||
const complete = vi.fn<Inf0GatewayClient['complete']>(async () => response);
|
||||
await structureDocument({ ...base, countTokens, gateway: { complete } });
|
||||
expect(complete.mock.calls[0]?.[0]?.messages).toEqual(countTokens.mock.calls[0]?.[0]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,91 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { validateStructuredBatch, exportValidatedBatch } from '../../src/document-workbench/structured-batch';
|
||||
import { structureDocumentBatch } from '../../src/document-workbench/structure-document-batch';
|
||||
import { Inf0GatewayClient, type Inf0GatewayReceipt } from '../../src/document-workbench/inf0-gateway-client';
|
||||
|
||||
const fields = [{ name: 'name', type: 'string' as const, required: true }];
|
||||
const sources = [{ id: 's1', text: 'Acme\nBeta' }];
|
||||
const records = [
|
||||
{ value: { name: 'Acme' }, evidence: [{ field: 'name', sourceId: 's1', start: 0, end: 4, transform: 'exact' as const }] },
|
||||
{ value: { name: 'Beta' }, evidence: [{ field: 'name', sourceId: 's1', start: 5, end: 9, transform: 'exact' as const }] },
|
||||
];
|
||||
const request = {
|
||||
context: { tenantId: 'a', projectId: 'p', actorId: 'u', capability: 'inf0.complete', correlationId: 'c' },
|
||||
admission: { tenantId: 'a', projectId: 'p', jobId: 'j', modelId: 'local_only', dataClass: 'high', maxInputTokens: 200, maxOutputTokens: 100, maximumCredits: 5 },
|
||||
policy: { tenantId: 'a', projectId: 'p', allowedModelIds: ['local_only'], allowedDataClasses: ['high'], destination: 'internal', externalTransferAllowed: false, maxInputTokens: 200, maxOutputTokens: 100 },
|
||||
reservation: { tenantId: 'a', projectId: 'p', jobId: 'j', status: 'reserved', credits: 5 },
|
||||
} satisfies Omit<Parameters<Inf0GatewayClient['complete']>[0], 'messages' | 'inputTokens'>;
|
||||
const receipt: Inf0GatewayReceipt = { status: 'model_stopped', content: JSON.stringify({ records }), modelExecuted: 'm1', providerKind: 'local', promptTokens: 50, completionTokens: 20, totalTokens: 70 };
|
||||
|
||||
describe('evidence-bound document batches', () => {
|
||||
it('serializes every supported row in order to JSON and CSV', () => {
|
||||
const json = exportValidatedBatch({ format: 'json', fields, sources, records });
|
||||
expect(json.status).toBe('ready');
|
||||
if (json.status === 'ready') expect(JSON.parse(json.content)).toEqual([{ name: 'Acme' }, { name: 'Beta' }]);
|
||||
expect(exportValidatedBatch({ format: 'csv', fields, sources, records })).toEqual({
|
||||
status: 'ready', mediaType: 'text/csv', content: '"name"\r\n"Acme"\r\n"Beta"\r\n',
|
||||
});
|
||||
});
|
||||
it('rejects the entire output when one row is unsupported or malformed', () => {
|
||||
const altered = [records[0], { ...records[1]!, value: { name: 'Invented' } }];
|
||||
expect(exportValidatedBatch({ format: 'json', fields, sources, records: altered })).toMatchObject({ status: 'needs_review', issues: [{ row: 1, field: 'name', code: 'evidence_mismatch' }] });
|
||||
expect(validateStructuredBatch({ fields, sources, records: [null] })).toMatchObject({ status: 'needs_review', issues: [{ row: 0, code: 'invalid_record' }] });
|
||||
expect(validateStructuredBatch({ fields, sources, records: [] })).toMatchObject({ status: 'needs_review' });
|
||||
expect(validateStructuredBatch({ fields, sources, records: Array(201).fill(records[0]) })).toMatchObject({ status: 'needs_review' });
|
||||
});
|
||||
it('blocks spreadsheet formulas in any row while JSON preserves the literal value', () => {
|
||||
const source = [{ id: 's1', text: 'Acme\n=1+1' }];
|
||||
const unsafe = [records[0]!, { value: { name: '=1+1' }, evidence: [{ field: 'name', sourceId: 's1', start: 5, end: 9, transform: 'exact' }] }];
|
||||
expect(exportValidatedBatch({ format: 'csv', fields, sources: source, records: unsafe })).toMatchObject({ status: 'needs_review', issues: [{ row: 1, code: 'csv_unsafe_cell' }] });
|
||||
expect(exportValidatedBatch({ format: 'json', fields, sources: source, records: unsafe }).status).toBe('ready');
|
||||
});
|
||||
it('preserves quoted multiline headers and cells in a multi-row CSV', () => {
|
||||
const f = [{ name: 'company\r\nname', type: 'string' as const, required: true }];
|
||||
const s = [{ id: 's', text: 'A\r\nB,C' }];
|
||||
const r = [{ value: { 'company\r\nname': 'A\r\nB' }, evidence: [{ field: 'company\r\nname', sourceId: 's', start: 0, end: 4, transform: 'exact' }] },
|
||||
{ value: { 'company\r\nname': ',C' }, evidence: [{ field: 'company\r\nname', sourceId: 's', start: 4, end: 6, transform: 'exact' }] }];
|
||||
expect(exportValidatedBatch({ format: 'csv', fields: f, sources: s, records: r })).toMatchObject({ status: 'ready', content: '"company\r\nname"\r\n"A\r\nB"\r\n",C"\r\n' });
|
||||
});
|
||||
it('extracts multiple records and keeps their evidence tied to the original source', async () => {
|
||||
const mutable = structuredClone(sources);
|
||||
const complete = vi.fn<Inf0GatewayClient['complete']>(async () => receipt);
|
||||
const countTokens = vi.fn(async (messages: Parameters<Inf0GatewayClient['complete']>[0]['messages']) => {
|
||||
expect(Object.isFrozen(messages[1])).toBe(true);
|
||||
mutable[0]!.text = 'Evil\nBeta';
|
||||
return 50;
|
||||
});
|
||||
const result = await structureDocumentBatch({ request, fields, sources: mutable, instructions: 'Extract companies', countTokens, gateway: { complete } });
|
||||
expect(result).toMatchObject({ status: 'mechanically_validated', records });
|
||||
expect(result.model).not.toHaveProperty('content');
|
||||
expect(complete.mock.calls[0]?.[0]?.messages).toEqual(countTokens.mock.calls[0]?.[0]);
|
||||
});
|
||||
it('runs a batch through the real INF0 client with scoped policy and usage checks', async () => {
|
||||
const fetchImpl = vi.fn(async () => Response.json({ content: receipt.content, modelExecuted: 'm1', finishReason: 'stop',
|
||||
routeDecision: { route: 'local_only', providerKind: 'local' }, cost: { promptTokens: 50, completionTokens: 20, totalTokens: 70 } }));
|
||||
const gateway = new Inf0GatewayClient({ baseUrl: 'https://inf0.example.test', serviceToken: 'test', fetchImpl });
|
||||
const result = await structureDocumentBatch({ request, fields, sources, instructions: 'Extract companies', countTokens: async () => 50, gateway });
|
||||
expect(result).toMatchObject({ status: 'mechanically_validated', records });
|
||||
if (result.status !== 'mechanically_validated') throw new Error('Expected a verified batch');
|
||||
const exported = exportValidatedBatch({ format: 'json', fields, sources, records: result.records });
|
||||
expect(exported.status).toBe('ready');
|
||||
if (exported.status === 'ready') expect(JSON.parse(exported.content)).toEqual([{ name: 'Acme' }, { name: 'Beta' }]);
|
||||
expect(fetchImpl).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('requires review for CSV if any optional field is absent in any row', () => {
|
||||
const optional = [...fields, { name: 'reference', type: 'string' as const, required: false }];
|
||||
expect(exportValidatedBatch({ format: 'json', fields: optional, sources, records }).status).toBe('ready');
|
||||
expect(exportValidatedBatch({ format: 'csv', fields: optional, sources, records })).toMatchObject({
|
||||
status: 'needs_review', issues: [{ row: 0, field: 'reference', code: 'csv_missing_value' }],
|
||||
});
|
||||
});
|
||||
it('routes truncated, empty, malformed and unsupported model results to review', async () => {
|
||||
for (const r of [
|
||||
{ ...receipt, status: 'needs_review' as const }, { ...receipt, content: '{' },
|
||||
{ ...receipt, content: JSON.stringify({ records: [] }) },
|
||||
{ ...receipt, content: JSON.stringify({ records: [{ ...records[0], value: { name: 'Wrong' } }] }) },
|
||||
]) {
|
||||
const result = await structureDocumentBatch({ request, fields, sources, instructions: 'Extract companies', countTokens: async () => 50, gateway: { complete: async () => r } });
|
||||
expect(result.status).toBe('needs_review');
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,139 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { validateStructuredOutput } from '../../src/document-workbench/structured-output-validation';
|
||||
|
||||
const sample = {
|
||||
fields: [
|
||||
{ name: 'name', type: 'string' as const, required: true },
|
||||
{ name: 'count', type: 'integer' as const, required: true },
|
||||
],
|
||||
value: { name: 'Acme', count: 12 },
|
||||
sources: [{ id: 'page-1', text: 'Name: Acme\nCount: 12' }],
|
||||
evidence: [
|
||||
{ field: 'name', sourceId: 'page-1', start: 6, end: 10, transform: 'exact' as const },
|
||||
{ field: 'count', sourceId: 'page-1', start: 18, end: 20, transform: 'integer' as const },
|
||||
],
|
||||
};
|
||||
describe('structured output mechanical validation', () => {
|
||||
it('accepts typed fields with matching source ranges', () => {
|
||||
expect(validateStructuredOutput(sample).status).toBe('mechanically_validated');
|
||||
});
|
||||
it('does not accept invented, mistyped or extra values', () => {
|
||||
const result = validateStructuredOutput({ ...sample, value: { name: 'Other', count: '12', extra: 1 } });
|
||||
expect(result).toMatchObject({
|
||||
status: 'needs_review',
|
||||
issues: expect.arrayContaining([
|
||||
{ field: 'name', code: 'evidence_mismatch' },
|
||||
{ field: 'count', code: 'invalid_type' },
|
||||
{ field: 'extra', code: 'unexpected_field' },
|
||||
]),
|
||||
});
|
||||
});
|
||||
it('rejects absent, duplicate or out-of-range evidence and ambiguous sources', () => {
|
||||
expect(validateStructuredOutput({ ...sample, evidence: [] }).status).toBe('needs_review');
|
||||
expect(
|
||||
validateStructuredOutput({ ...sample, evidence: [...sample.evidence, sample.evidence[0]!] }).status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
validateStructuredOutput({
|
||||
...sample,
|
||||
evidence: [{ ...sample.evidence[0]!, end: 999 }, sample.evidence[1]!],
|
||||
}).status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
validateStructuredOutput({ ...sample, sources: [...sample.sources, sample.sources[0]!] }).status,
|
||||
).toBe('needs_review');
|
||||
});
|
||||
it('refuses unsafe integers and absent required fields', () => {
|
||||
expect(
|
||||
validateStructuredOutput({ ...sample, value: { name: 'Acme', count: Number.MAX_SAFE_INTEGER + 1 } })
|
||||
.status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
validateStructuredOutput({ ...sample, value: { name: 'Acme' }, evidence: [sample.evidence[0]!] })
|
||||
.status,
|
||||
).toBe('needs_review');
|
||||
});
|
||||
it('preserves exact decimal precision and accepts real ISO calendar dates', () => {
|
||||
const text = '9007199254740993.20 2024-02-29';
|
||||
const input = {
|
||||
fields: [
|
||||
{ name: 'amount', type: 'decimal' as const, required: true },
|
||||
{ name: 'date', type: 'date' as const, required: true },
|
||||
],
|
||||
value: { amount: '9007199254740993.20', date: '2024-02-29' },
|
||||
sources: [{ id: 'p', text }],
|
||||
evidence: [
|
||||
{ field: 'amount', sourceId: 'p', start: 0, end: 19, transform: 'decimal' as const },
|
||||
{ field: 'date', sourceId: 'p', start: 20, end: 30, transform: 'date' as const },
|
||||
],
|
||||
};
|
||||
expect(validateStructuredOutput(input).status).toBe('mechanically_validated');
|
||||
expect(
|
||||
validateStructuredOutput({ ...input, value: { ...input.value, amount: 9007199254740994 } }).status,
|
||||
).toBe('needs_review');
|
||||
expect(
|
||||
validateStructuredOutput({ ...input, value: { ...input.value, amount: '9007199254740993.2' } }).status,
|
||||
).toBe('needs_review');
|
||||
});
|
||||
it.each(['2023-02-29', '1900-02-29', '2024-13-01', '2024-04-31', '0000-01-01'])(
|
||||
'rejects invalid date %s even if present in the source',
|
||||
(text) => {
|
||||
expect(
|
||||
validateStructuredOutput({
|
||||
fields: [{ name: 'date', type: 'date', required: true }],
|
||||
value: { date: text },
|
||||
sources: [{ id: 'p', text }],
|
||||
evidence: [{ field: 'date', sourceId: 'p', start: 0, end: text.length, transform: 'date' }],
|
||||
}).status,
|
||||
).toBe('needs_review');
|
||||
},
|
||||
);
|
||||
it.each(['01.0', '1e3', '1,25', '+1.0', '.5'])(
|
||||
'rejects ambiguous decimal %s rather than guessing',
|
||||
(text) => {
|
||||
expect(
|
||||
validateStructuredOutput({
|
||||
fields: [{ name: 'amount', type: 'decimal', required: true }],
|
||||
value: { amount: text },
|
||||
sources: [{ id: 'p', text }],
|
||||
evidence: [{ field: 'amount', sourceId: 'p', start: 0, end: text.length, transform: 'decimal' }],
|
||||
}).status,
|
||||
).toBe('needs_review');
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe('locale-aware evidence (decimal + date)', () => {
|
||||
const fields = [
|
||||
{ name: 'amount', type: 'decimal' as const, required: true },
|
||||
{ name: 'due', type: 'date' as const, required: true },
|
||||
];
|
||||
const sources = [{ id: 's1', text: 'Belopp: 12 500,00 SEK\nFörfallodatum: 14/10/2026' }];
|
||||
const span = (needle: string) => {
|
||||
const start = sources[0]!.text.indexOf(needle);
|
||||
return { start, end: start + needle.length };
|
||||
};
|
||||
it('accepts an unambiguous locale amount and day-first date', () => {
|
||||
const out = validateStructuredOutput({
|
||||
fields,
|
||||
sources,
|
||||
value: { amount: '12500.00', due: '2026-10-14' },
|
||||
evidence: [
|
||||
{ field: 'amount', sourceId: 's1', ...span('12 500,00'), transform: 'decimal' },
|
||||
{ field: 'due', sourceId: 's1', ...span('14/10/2026'), transform: 'date' },
|
||||
],
|
||||
});
|
||||
expect(out.status).toBe('mechanically_validated');
|
||||
});
|
||||
it('refuses a date that is ambiguous between day-first and month-first', () => {
|
||||
const ambiguous = [{ id: 's1', text: 'Datum: 01/02/2026' }];
|
||||
const start = ambiguous[0]!.text.indexOf('01/02/2026');
|
||||
const out = validateStructuredOutput({
|
||||
fields: [{ name: 'due', type: 'date', required: true }],
|
||||
sources: ambiguous,
|
||||
value: { due: '2026-02-01' },
|
||||
evidence: [{ field: 'due', sourceId: 's1', start, end: start + 10, transform: 'date' }],
|
||||
});
|
||||
expect(out.status).toBe('needs_review');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,66 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { selectDocumentTool, type DocumentTool } from '../../src/document-workbench/tool-selection';
|
||||
|
||||
const parser: DocumentTool = {
|
||||
id: 'pdf-ocr',
|
||||
version: '1',
|
||||
installed: true,
|
||||
licenseApproved: true,
|
||||
supportedMimeTypes: ['application/pdf'],
|
||||
supportedDataClasses: ['confidential'],
|
||||
externalTransfer: false,
|
||||
};
|
||||
const policy = {
|
||||
allowedToolIds: [parser.id],
|
||||
allowedExternalToolIds: [] as string[],
|
||||
dataClass: 'confidential',
|
||||
};
|
||||
const base = { proposedToolId: parser.id, detectedMimeType: 'application/pdf', registry: [parser], policy };
|
||||
|
||||
describe('document tool admission', () => {
|
||||
it('accepts a licensed, installed and explicitly authorized compatible tool', () => {
|
||||
expect(selectDocumentTool(base)).toEqual({ allowed: true, tool: parser });
|
||||
});
|
||||
it('rejects an agent-invented tool and an ambiguous registry', () => {
|
||||
expect(selectDocumentTool({ ...base, proposedToolId: 'shell' })).toMatchObject({
|
||||
reason: 'unknown_tool',
|
||||
});
|
||||
expect(selectDocumentTool({ ...base, registry: [parser, parser] })).toMatchObject({
|
||||
reason: 'ambiguous_registry',
|
||||
});
|
||||
});
|
||||
it('fails closed for missing authorization, license, installation or version', () => {
|
||||
expect(selectDocumentTool({ ...base, policy: { ...policy, allowedToolIds: [] } })).toMatchObject({
|
||||
reason: 'not_authorized',
|
||||
});
|
||||
for (const tool of [
|
||||
{ ...parser, installed: false },
|
||||
{ ...parser, licenseApproved: false },
|
||||
{ ...parser, version: '' },
|
||||
{ ...parser, externalTransfer: undefined } as unknown as DocumentTool,
|
||||
]) {
|
||||
expect(selectDocumentTool({ ...base, registry: [tool] })).toMatchObject({ reason: 'not_ready' });
|
||||
}
|
||||
});
|
||||
it('rejects incorrect content types and unapproved data classes', () => {
|
||||
expect(selectDocumentTool({ ...base, detectedMimeType: 'application/zip' })).toMatchObject({
|
||||
reason: 'unsupported_format',
|
||||
});
|
||||
expect(selectDocumentTool({ ...base, policy: { ...policy, dataClass: 'restricted' } })).toMatchObject({
|
||||
reason: 'unsupported_data_class',
|
||||
});
|
||||
});
|
||||
it('requires an explicit external-transfer permission even for an otherwise allowed tool', () => {
|
||||
const external = { ...parser, externalTransfer: true };
|
||||
expect(selectDocumentTool({ ...base, registry: [external] })).toMatchObject({
|
||||
reason: 'external_transfer_denied',
|
||||
});
|
||||
expect(
|
||||
selectDocumentTool({
|
||||
...base,
|
||||
registry: [external],
|
||||
policy: { ...policy, allowedExternalToolIds: [external.id] },
|
||||
}).allowed,
|
||||
).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,25 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { ensureTrialCredits, readTrialCredits } from '../../src/document-workbench/trial-credits';
|
||||
|
||||
describe('trial credits', () => {
|
||||
it('is disabled by default and rejects invalid amounts', () => {
|
||||
expect(readTrialCredits({} as unknown as NodeJS.ProcessEnv)).toBe(0);
|
||||
expect(readTrialCredits({ OPT_TRIAL_CREDITS: '-5' } as unknown as NodeJS.ProcessEnv)).toBe(0);
|
||||
expect(readTrialCredits({ OPT_TRIAL_CREDITS: 'abc' } as unknown as NodeJS.ProcessEnv)).toBe(0);
|
||||
expect(readTrialCredits({ OPT_TRIAL_CREDITS: '100' } as unknown as NodeJS.ProcessEnv)).toBe(100);
|
||||
});
|
||||
|
||||
it('applies one idempotent grant and does nothing for zero', async () => {
|
||||
const apply = vi.fn(async () => ({ replay: false }));
|
||||
await ensureTrialCredits({ apply }, 't_0pt', 100);
|
||||
expect(apply).toHaveBeenCalledWith({
|
||||
tenantId: 't_0pt',
|
||||
idempotencyKey: 'trial:t_0pt',
|
||||
kind: 'grant',
|
||||
reference: 'trial:t_0pt',
|
||||
amount: 100,
|
||||
});
|
||||
await ensureTrialCredits({ apply }, 't_0pt', 0);
|
||||
expect(apply).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,75 @@
|
||||
import { readFile } from 'node:fs/promises';
|
||||
import postgres from 'postgres';
|
||||
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
|
||||
import { DocumentUploadCoordinator } from '../../src/document-workbench/upload-coordinator';
|
||||
import { PostgresUploadAttemptStore, type UploadAttemptIdentity } from '../../src/document-workbench/upload-attempt-store';
|
||||
|
||||
const url = process.env.OPT_ATTEMPT_TEST_DATABASE_URL;
|
||||
describe.skipIf(!url)('upload attempt manifest with real PostgreSQL RLS', () => {
|
||||
let admin: ReturnType<typeof postgres>;
|
||||
let app: ReturnType<typeof postgres>;
|
||||
let store: PostgresUploadAttemptStore;
|
||||
let scopedUrl: string;
|
||||
const sample: UploadAttemptIdentity = {
|
||||
tenantId: 'tenant-a', projectId: 'project-a', actorId: 'actor-a', attemptId: 'attempt-a',
|
||||
sourceSha256: 'a'.repeat(64), sourceSizeBytes: 12, requestFingerprint: 'b'.repeat(64),
|
||||
};
|
||||
|
||||
beforeAll(async () => {
|
||||
if (process.env.OPT_ATTEMPT_TEST_ALLOW_LOCAL !== '1' || new URL(url!).hostname !== '127.0.0.1') {
|
||||
throw new Error('Only an explicitly enabled isolated loopback test database may be used');
|
||||
}
|
||||
admin = postgres(url!, { max: 1, prepare: false });
|
||||
await admin.unsafe(await readFile('sql/018_document_upload_attempts.sql', 'utf8'));
|
||||
await admin.unsafe('CREATE ROLE opt_attempt_test LOGIN NOSUPERUSER NOBYPASSRLS');
|
||||
await admin.unsafe('GRANT USAGE ON SCHEMA public TO opt_attempt_test');
|
||||
await admin.unsafe('GRANT SELECT, INSERT, UPDATE ON opt_document_upload_attempts TO opt_attempt_test');
|
||||
const appUrl = new URL(url!);
|
||||
appUrl.username = 'opt_attempt_test';
|
||||
scopedUrl = appUrl.toString();
|
||||
app = postgres(scopedUrl, { max: 8, prepare: false });
|
||||
store = new PostgresUploadAttemptStore(app);
|
||||
});
|
||||
afterAll(async () => { await app?.end(); await admin?.end(); });
|
||||
|
||||
it('rejects a database role which bypasses RLS', async () => {
|
||||
await expect(new PostgresUploadAttemptStore(admin).prepare(sample)).rejects.toThrow(/RLS-enforced/);
|
||||
});
|
||||
it('persists matching retries and rejects changed or differently scoped identities', async () => {
|
||||
expect(await store.prepare(sample)).toEqual({ state: 'prepared', replay: false });
|
||||
expect(await store.prepare(sample)).toEqual({ state: 'prepared', replay: true });
|
||||
await expect(store.prepare({ ...sample, sourceSha256: 'c'.repeat(64) })).rejects.toThrow();
|
||||
await expect(store.prepare({ ...sample, projectId: 'project-b' })).rejects.toThrow('Document upload attempt cannot be reused');
|
||||
await expect(store.prepare({ ...sample, actorId: 'actor-b' })).rejects.toThrow('Document upload attempt cannot be reused');
|
||||
expect(await store.prepare({ ...sample, tenantId: 'tenant-b' })).toEqual({ state: 'prepared', replay: false });
|
||||
expect(await app`SELECT * FROM opt_document_upload_attempts`).toHaveLength(0);
|
||||
});
|
||||
it('allows only one concurrent dispatch claimant and survives a new connection', async () => {
|
||||
const attempt = { ...sample, attemptId: 'race' };
|
||||
expect(await store.startDispatch(attempt)).toBe(false);
|
||||
await store.prepare(attempt);
|
||||
expect(await store.startDispatch({ ...attempt, actorId: 'actor-b' })).toBe(false);
|
||||
expect(await store.startDispatch({ ...attempt, sourceSha256: 'c'.repeat(64) })).toBe(false);
|
||||
const results = await Promise.all(Array.from({ length: 8 }, () => store.startDispatch(attempt)));
|
||||
expect(results.filter(Boolean)).toHaveLength(1);
|
||||
expect(await store.startDispatch(attempt)).toBe(false);
|
||||
expect(await store.prepare(attempt)).toEqual({ state: 'dispatch_started', replay: true });
|
||||
const second = postgres(scopedUrl, { max: 1, prepare: false });
|
||||
try { expect(await new PostgresUploadAttemptStore(second).prepare(attempt)).toEqual({ state: 'dispatch_started', replay: true }); }
|
||||
finally { await second.end(); }
|
||||
});
|
||||
it('coordinates concurrent uploads through the real RLS store without resending', async () => {
|
||||
const doc0 = { upload: vi.fn(async () => ({ documentId: 'doc', versionId: 'v', checksumSha256: 'fixture', pipelineStage: 'accepted' })),
|
||||
inspect: vi.fn(async () => ({ status: 'not_found' as const })) };
|
||||
const coordinator = new DocumentUploadCoordinator({ attempts: store, doc0, authorize: async () => true, maxBytes: 100 });
|
||||
const input = { tenantId: 'tenant-a', projectId: 'project-a', actorId: 'actor-a', requestId: 'request', idempotencyKey: 'coordinator-race',
|
||||
filename: 'fil åäö.txt', mimeType: 'text/plain', classification: 'confidential' as const, bytes: new TextEncoder().encode('fixture') };
|
||||
const results = await Promise.all(Array.from({ length: 8 }, () => coordinator.execute(input)));
|
||||
expect(results.filter((result) => result.status === 'receipt_verified')).toHaveLength(1);
|
||||
expect(results.filter((result) => result.status === 'outcome_unknown')).toHaveLength(7);
|
||||
expect(doc0.upload).toHaveBeenCalledOnce();
|
||||
await expect(coordinator.execute({ ...input, bytes: new TextEncoder().encode('different') })).rejects.toThrow(/cannot be reused/);
|
||||
expect(doc0.upload).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
});
|
||||
@@ -0,0 +1,143 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import {
|
||||
Doc0UploadOutcomeUnknownError,
|
||||
prepareDoc0UploadIdentity,
|
||||
type Doc0UploadClient,
|
||||
} from '../../src/document-workbench/doc0-upload-client';
|
||||
import { DocumentUploadCoordinator } from '../../src/document-workbench/upload-coordinator';
|
||||
import type { PostgresUploadAttemptStore } from '../../src/document-workbench/upload-attempt-store';
|
||||
|
||||
const input = {
|
||||
tenantId: 't1',
|
||||
projectId: 'p1',
|
||||
actorId: 'a1',
|
||||
requestId: 'r1',
|
||||
idempotencyKey: 'i1',
|
||||
filename: 'rapport åäö.txt',
|
||||
mimeType: 'text/plain',
|
||||
classification: 'confidential' as const,
|
||||
bytes: new TextEncoder().encode('original'),
|
||||
};
|
||||
const receipt = { documentId: 'd1', versionId: 'v1', checksumSha256: 'test', pipelineStage: 'accepted' };
|
||||
function fixture() {
|
||||
const attempts = {
|
||||
prepare: vi.fn<PostgresUploadAttemptStore['prepare']>(async () => ({
|
||||
state: 'prepared' as const,
|
||||
replay: false,
|
||||
})),
|
||||
startDispatch: vi.fn<PostgresUploadAttemptStore['startDispatch']>(async () => true),
|
||||
recordReceipt: vi.fn<PostgresUploadAttemptStore['recordReceipt']>(async () => undefined),
|
||||
getReceipt: vi.fn<PostgresUploadAttemptStore['getReceipt']>(async () => undefined),
|
||||
};
|
||||
const doc0 = {
|
||||
upload: vi.fn<Doc0UploadClient['upload']>(async () => receipt),
|
||||
inspect: vi.fn<Doc0UploadClient['inspect']>(async () => ({ status: 'not_found' as const })),
|
||||
};
|
||||
const authorize = vi.fn(async () => true);
|
||||
const coordinator = new DocumentUploadCoordinator({ attempts, doc0, authorize, maxBytes: 100 });
|
||||
return { attempts, doc0, authorize, coordinator };
|
||||
}
|
||||
describe('document upload coordination', () => {
|
||||
it('authorizes and persists the exact fingerprint before a single write', async () => {
|
||||
const f = fixture();
|
||||
expect(await f.coordinator.execute(input)).toEqual({ status: 'receipt_verified', receipt });
|
||||
expect(f.authorize).toHaveBeenCalledWith({ tenantId: 't1', projectId: 'p1', actorId: 'a1' });
|
||||
const attempt = f.attempts.prepare.mock.calls[0][0];
|
||||
expect(attempt).toEqual({
|
||||
tenantId: 't1',
|
||||
projectId: 'p1',
|
||||
actorId: 'a1',
|
||||
attemptId: 'i1',
|
||||
sourceSha256: prepareDoc0UploadIdentity(input).sourceSha256,
|
||||
sourceSizeBytes: input.bytes.length,
|
||||
requestFingerprint: prepareDoc0UploadIdentity(input).requestFingerprint,
|
||||
});
|
||||
expect(f.attempts.startDispatch).toHaveBeenCalledWith(attempt);
|
||||
expect(f.attempts.prepare.mock.invocationCallOrder[0]).toBeLessThan(
|
||||
f.attempts.startDispatch.mock.invocationCallOrder[0],
|
||||
);
|
||||
expect(f.attempts.startDispatch.mock.invocationCallOrder[0]).toBeLessThan(
|
||||
f.doc0.upload.mock.invocationCallOrder[0],
|
||||
);
|
||||
});
|
||||
it('denies before persistence or network when authorization fails', async () => {
|
||||
const f = fixture();
|
||||
f.authorize.mockResolvedValueOnce(false);
|
||||
await expect(f.coordinator.execute(input)).rejects.toThrow(/not authorized/);
|
||||
expect(f.attempts.prepare).not.toHaveBeenCalled();
|
||||
expect(f.doc0.upload).not.toHaveBeenCalled();
|
||||
});
|
||||
it('rejects truthy but non-boolean authorization results', async () => {
|
||||
const f = fixture();
|
||||
f.authorize.mockResolvedValueOnce('allow' as unknown as boolean);
|
||||
await expect(f.coordinator.execute(input)).rejects.toThrow(/not authorized/);
|
||||
expect(f.attempts.prepare).not.toHaveBeenCalled();
|
||||
});
|
||||
it('does not dispatch after a failed or ambiguous database transition', async () => {
|
||||
const f = fixture();
|
||||
f.attempts.startDispatch.mockRejectedValueOnce(new Error('connection lost'));
|
||||
await expect(f.coordinator.execute(input)).rejects.toThrow(/connection lost/);
|
||||
expect(f.doc0.upload).not.toHaveBeenCalled();
|
||||
expect(f.doc0.inspect).not.toHaveBeenCalled();
|
||||
});
|
||||
it('only observes a previously started attempt and never sends a second POST', async () => {
|
||||
const f = fixture();
|
||||
f.attempts.startDispatch.mockResolvedValueOnce(false);
|
||||
expect(await f.coordinator.execute(input)).toEqual({
|
||||
status: 'outcome_unknown',
|
||||
observation: { status: 'not_found' },
|
||||
});
|
||||
expect(f.doc0.upload).not.toHaveBeenCalled();
|
||||
expect(f.doc0.inspect).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('persists the verified receipt after a successful upload', async () => {
|
||||
const f = fixture();
|
||||
expect(await f.coordinator.execute(input)).toEqual({ status: 'receipt_verified', receipt });
|
||||
expect(f.attempts.recordReceipt).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ attemptId: 'i1' }),
|
||||
receipt,
|
||||
);
|
||||
});
|
||||
it('returns the SAME verified receipt on an idempotent retry without a second POST', async () => {
|
||||
const f = fixture();
|
||||
f.attempts.startDispatch.mockResolvedValueOnce(false);
|
||||
f.attempts.getReceipt.mockResolvedValueOnce(receipt);
|
||||
expect(await f.coordinator.execute(input)).toEqual({ status: 'receipt_verified', receipt });
|
||||
expect(f.doc0.upload).not.toHaveBeenCalled();
|
||||
expect(f.doc0.inspect).not.toHaveBeenCalled();
|
||||
});
|
||||
it('keeps a journaled completion distinct from a verified receipt', async () => {
|
||||
const f = fixture();
|
||||
f.attempts.startDispatch.mockResolvedValueOnce(false);
|
||||
f.doc0.inspect.mockResolvedValueOnce({
|
||||
status: 'completed_recorded',
|
||||
documentId: 'doc',
|
||||
versionId: 'version',
|
||||
});
|
||||
expect(await f.coordinator.execute(input)).toEqual({
|
||||
status: 'outcome_unknown',
|
||||
observation: { status: 'completed_recorded', documentId: 'doc', versionId: 'version' },
|
||||
});
|
||||
expect(f.doc0.upload).not.toHaveBeenCalled();
|
||||
});
|
||||
it('keeps a possibly committed upload unknown even when inspection is unavailable', async () => {
|
||||
const f = fixture();
|
||||
f.doc0.upload.mockRejectedValueOnce(new Doc0UploadOutcomeUnknownError());
|
||||
f.doc0.inspect.mockRejectedValueOnce(new Error('unavailable'));
|
||||
expect(await f.coordinator.execute(input)).toEqual({ status: 'outcome_unknown' });
|
||||
expect(f.doc0.upload).toHaveBeenCalledOnce();
|
||||
expect(f.doc0.inspect).toHaveBeenCalledOnce();
|
||||
});
|
||||
it('snapshots bytes and metadata before asynchronous authorization', async () => {
|
||||
const f = fixture();
|
||||
const mutable = { ...input, bytes: new Uint8Array(input.bytes) };
|
||||
f.authorize.mockImplementationOnce(async () => {
|
||||
mutable.bytes.fill(0);
|
||||
mutable.filename = 'changed.txt';
|
||||
return true;
|
||||
});
|
||||
await f.coordinator.execute(mutable);
|
||||
expect(f.doc0.upload.mock.calls[0][0].filename).toBe(input.filename);
|
||||
expect(new TextDecoder().decode(f.doc0.upload.mock.calls[0][0].bytes)).toBe('original');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,396 @@
|
||||
/**
|
||||
* tests/duckdb/duckdb-provider.live.test.ts
|
||||
* ==========================================
|
||||
* BI-P014 — the DuckDB provider against a real DuckDB.
|
||||
*
|
||||
* Two things are proven here that a unit test cannot:
|
||||
*
|
||||
* 1. BI-P014's DoD — "Queries work against Parquet / Arrow / Iceberg snapshot
|
||||
* fixtures" — for the formats this environment can actually build. Parquet
|
||||
* and CSV run from committed fixtures. The Iceberg case runs when a Python
|
||||
* interpreter carrying `pyiceberg` is pointed at by PYICEBERG_PYTHON,
|
||||
* because pyiceberg embeds ABSOLUTE paths in its manifests, so a committed
|
||||
* Iceberg table would only work from the machine that made it. The recorded
|
||||
* result of a real Iceberg run is committed as evidence instead, and
|
||||
* tests/analytics/duckdb-provider.test.ts pins it.
|
||||
*
|
||||
* 2. The security claim, WITH LAYER 1 REMOVED. Every bypass attempt is sent
|
||||
* straight to DuckDB, skipping the mount registry entirely, and layer 2 —
|
||||
* the session sandbox — must refuse it. Which matters more than usual here,
|
||||
* because layer 2 does not work the way it looks like it works: see the
|
||||
* `allowed_directories` finding in duckdb-provider.ts.
|
||||
*
|
||||
* Gated on DUCKDB_PYTHON, an interpreter with the `duckdb` package. With it
|
||||
* set and DuckDB broken, this suite FAILS; it does not degrade to a skip.
|
||||
*
|
||||
* ── WHY THIS IS NOT UNDER tests/integration/ ──────────────────────────────
|
||||
* It was, and CI's integration job failed — correctly. That job provides a
|
||||
* live OpenSearch and a live ClickHouse and then asserts that NOTHING in
|
||||
* tests/integration/ skipped, on the stated principle that "a skipped suite
|
||||
* must never masquerade as a green integration gate". A DuckDB suite needing
|
||||
* a Python interpreter that job does not provide is not one of the suites that
|
||||
* job is a gate for, so it skipped, and the guard fired.
|
||||
*
|
||||
* Moving the file respects that guard rather than weakening it. Loosening the
|
||||
* guard to tolerate skips would have traded a real gate for one green job —
|
||||
* which is the trade this estate keeps regretting.
|
||||
*/
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { beforeAll, describe, expect, it } from 'vitest';
|
||||
import { SiaxError } from '@/src/platform/errors';
|
||||
import {
|
||||
ArtifactMountRegistry,
|
||||
DuckDbAnalyticsProvider,
|
||||
duckDbSessionBootstrap,
|
||||
type DuckDbRunner,
|
||||
} from '@/src/analytics/providers/duckdb-provider';
|
||||
|
||||
const PY = process.env.DUCKDB_PYTHON ?? '';
|
||||
/** An interpreter carrying pyiceberg, used to REBUILD the non-portable fixture. */
|
||||
const PY_ICEBERG = process.env.PYICEBERG_PYTHON ?? PY;
|
||||
const suite = PY ? describe : describe.skip;
|
||||
const FIXTURES = path.join(process.cwd(), 'tests/fixtures/duckdb');
|
||||
const EVIDENCE_PATH = path.join(process.cwd(), 'evidence/bi-p014/duckdb-sandbox.json');
|
||||
const IDENTITY = { tenant_id: 't_alpha', principal_id: 'u_1' };
|
||||
|
||||
/**
|
||||
* Runs statements through a real DuckDB. The bootstrap is applied FIRST and in
|
||||
* order, exactly as the provider emits it.
|
||||
*/
|
||||
function runDuck(
|
||||
bootstrap: readonly string[],
|
||||
sql: string,
|
||||
loadIceberg = false,
|
||||
): { ok: boolean; out: string } {
|
||||
const script = [
|
||||
'import duckdb, json, sys',
|
||||
'c = duckdb.connect()',
|
||||
...(loadIceberg ? ['c.execute("INSTALL iceberg; LOAD iceberg")'] : []),
|
||||
// The bootstrap is inside the try as well: a statement that tries to
|
||||
// RE-OPEN a locked sandbox throws, and that throw is a RESULT to report,
|
||||
// not a crash of the harness. The first version of this file let it kill
|
||||
// the subprocess, which turned a meaningful refusal into an unreadable
|
||||
// "Command failed".
|
||||
'try:',
|
||||
...bootstrap.map((s) => ` c.execute(${JSON.stringify(s)})`),
|
||||
` rows = c.execute(${JSON.stringify(sql)}).fetchall()`,
|
||||
' print(json.dumps({"ok": True, "rows": [[str(v) for v in r] for r in rows]}))',
|
||||
'except Exception as e:',
|
||||
' print(json.dumps({"ok": False, "error": str(e)[:300]}))',
|
||||
].join('\n');
|
||||
const out = execFileSync(PY, ['-c', script], { encoding: 'utf8', timeout: 60_000 });
|
||||
const parsed = JSON.parse(out.trim()) as { ok: boolean; rows?: string[][]; error?: string };
|
||||
return { ok: parsed.ok, out: JSON.stringify(parsed.rows ?? parsed.error) };
|
||||
}
|
||||
|
||||
const runner: DuckDbRunner = {
|
||||
engine: 'duckdb',
|
||||
async run({ bootstrap, sql }) {
|
||||
const result = runDuck(bootstrap, sql, sql.includes('iceberg_scan'));
|
||||
if (!result.ok)
|
||||
throw new SiaxError('PERMANENT_FAILURE', 'duckdb', `query failed: ${result.out.slice(0, 160)}`);
|
||||
return (JSON.parse(result.out) as string[][]).map((r, i) => ({ _row: i, values: r }));
|
||||
},
|
||||
};
|
||||
|
||||
const evidence: Record<string, unknown> = {};
|
||||
let registry: ArtifactMountRegistry;
|
||||
let provider: DuckDbAnalyticsProvider;
|
||||
|
||||
beforeAll(() => {
|
||||
if (!PY) return;
|
||||
const version = execFileSync(PY, ['-c', 'import duckdb; print(duckdb.__version__)'], {
|
||||
encoding: 'utf8',
|
||||
}).trim();
|
||||
evidence.duckdb_version = version;
|
||||
evidence.recorded_at = new Date().toISOString();
|
||||
|
||||
expect(fs.existsSync(path.join(FIXTURES, 'sales.parquet')), 'parquet fixture is missing').toBe(true);
|
||||
|
||||
// Rebuild the Iceberg fixture, which is deliberately not committed:
|
||||
// pyiceberg writes ABSOLUTE paths into its metadata and Avro manifests, so a
|
||||
// committed table resolves only on the machine that made it.
|
||||
if (PY_ICEBERG && !fs.existsSync(path.join(FIXTURES, 'iceberg_metadata_location.txt'))) {
|
||||
const build = [
|
||||
'import os, shutil, pyarrow as pa',
|
||||
'from pyiceberg.catalog.sql import SqlCatalog',
|
||||
`root = ${JSON.stringify(FIXTURES)}`,
|
||||
"wh = os.path.join(root, 'iceberg')",
|
||||
'shutil.rmtree(wh, ignore_errors=True); os.makedirs(wh)',
|
||||
"cat = SqlCatalog('local', **{'uri': f'sqlite:///{wh}/catalog.db', 'warehouse': f'file://{wh}'})",
|
||||
"cat.create_namespace_if_not_exists('bi')",
|
||||
"d = pa.table({'tenant_id': ['t_alpha']*3, 'country': ['SE','NO','SE'], 'amount': [10.0,20.0,30.0]})",
|
||||
"t = cat.create_table('bi.sales_iceberg', schema=d.schema); t.append(d)",
|
||||
"open(os.path.join(root,'iceberg_metadata_location.txt'),'w').write(t.metadata_location)",
|
||||
"print('built')",
|
||||
].join('\n');
|
||||
try {
|
||||
execFileSync(PY_ICEBERG, ['-c', build], { encoding: 'utf8', timeout: 120_000 });
|
||||
} catch {
|
||||
// pyiceberg absent. The Iceberg case then falls back to the committed
|
||||
// evidence, and it asserts against it rather than passing vacuously.
|
||||
}
|
||||
}
|
||||
|
||||
registry = new ArtifactMountRegistry(FIXTURES);
|
||||
registry.register({
|
||||
artifact_id: 'a_sales_parquet',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'st0re://t_alpha/sales.parquet',
|
||||
relative_path: 'sales.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: fs.statSync(path.join(FIXTURES, 'sales.parquet')).size,
|
||||
});
|
||||
registry.register({
|
||||
artifact_id: 'a_customers_csv',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'st0re://t_alpha/customers.csv',
|
||||
relative_path: 'customers.csv',
|
||||
format: 'csv',
|
||||
size_bytes: fs.statSync(path.join(FIXTURES, 'customers.csv')).size,
|
||||
});
|
||||
// Another tenant's artifact, so the cross-tenant refusal is a real refusal
|
||||
// and not "the id does not exist".
|
||||
registry.register({
|
||||
artifact_id: 'a_beta_parquet',
|
||||
tenant_id: 't_beta',
|
||||
st0re_ref: 'st0re://t_beta/sales.parquet',
|
||||
relative_path: 'sales.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: 1,
|
||||
});
|
||||
|
||||
provider = new DuckDbAnalyticsProvider(registry, runner);
|
||||
}, 60_000);
|
||||
|
||||
suite('BI-P014 DoD — queries work against the fixtures', () => {
|
||||
it('aggregates a Parquet fixture through the closed request', async () => {
|
||||
const rows = await provider.query(IDENTITY, {
|
||||
artifact_id: 'a_sales_parquet',
|
||||
group_by: ['country'],
|
||||
aggregate: { fn: 'sum', column: 'amount', alias: 'total' },
|
||||
});
|
||||
const totals = Object.fromEntries(
|
||||
rows.map((r) => {
|
||||
const [country, total] = (r as { values: string[] }).values;
|
||||
return [country, Number(total)];
|
||||
}),
|
||||
);
|
||||
expect(totals).toEqual({ SE: 394.5, NO: 105.5 });
|
||||
evidence.parquet = totals;
|
||||
});
|
||||
|
||||
it('reads a CSV fixture, including a value containing a quote', async () => {
|
||||
const rows = await provider.query(IDENTITY, {
|
||||
artifact_id: 'a_customers_csv',
|
||||
select: ['customer_id', 'name'],
|
||||
});
|
||||
const names = rows.map((r) => (r as { values: string[] }).values[1]);
|
||||
expect(names).toContain("O'Brien Ltd");
|
||||
evidence.csv = { rows: rows.length, includes_quoted_value: true };
|
||||
});
|
||||
|
||||
it('filters with a hostile value without it becoming SQL', async () => {
|
||||
const rows = await provider.query(IDENTITY, {
|
||||
artifact_id: 'a_customers_csv',
|
||||
select: ['customer_id'],
|
||||
filters: { name: "O'Brien Ltd" },
|
||||
});
|
||||
expect(rows).toHaveLength(1);
|
||||
|
||||
// The injection attempt: a value that would close the literal and append.
|
||||
const hostile = await provider.query(IDENTITY, {
|
||||
artifact_id: 'a_customers_csv',
|
||||
select: ['customer_id'],
|
||||
filters: { name: "x' OR '1'='1" },
|
||||
});
|
||||
// It matched nothing, because it was DATA. Had the escaping failed, the
|
||||
// OR would have matched all three rows.
|
||||
expect(hostile).toHaveLength(0);
|
||||
evidence.injection_attempt = { matched_rows: hostile.length, note: 'escaped as data; 0 rows, not 3' };
|
||||
});
|
||||
|
||||
it('reads an ICEBERG SNAPSHOT by its exact metadata file', async () => {
|
||||
const metaFile = path.join(FIXTURES, 'iceberg_metadata_location.txt');
|
||||
if (!fs.existsSync(metaFile)) {
|
||||
// No pyiceberg here. Carry the previously RECORDED result forward, marked
|
||||
// as carried forward, and assert against it — the first version of this
|
||||
// branch was `expect(evidence.iceberg ?? "unbuilt").toBeDefined()`, which
|
||||
// can never fail and quietly erased the recorded block from the evidence
|
||||
// file while both suites stayed green.
|
||||
const prior = fs.existsSync(EVIDENCE_PATH)
|
||||
? (JSON.parse(fs.readFileSync(EVIDENCE_PATH, 'utf8')) as {
|
||||
iceberg?: { totals: Record<string, number> };
|
||||
})
|
||||
: {};
|
||||
expect(
|
||||
prior.iceberg?.totals,
|
||||
'no pyiceberg available AND no recorded Iceberg result — the DoD is unproven, not skipped',
|
||||
).toEqual({ NO: 20, SE: 40 });
|
||||
evidence.iceberg = { ...prior.iceberg, carried_forward: true };
|
||||
return;
|
||||
}
|
||||
const meta = fs
|
||||
.readFileSync(metaFile, 'utf8')
|
||||
.trim()
|
||||
.replace(/^file:\/\//, '');
|
||||
const bootstrap = duckDbSessionBootstrap([FIXTURES]);
|
||||
const res = runDuck(
|
||||
bootstrap,
|
||||
`SELECT country, sum(amount) AS s FROM iceberg_scan('${meta}') GROUP BY country ORDER BY country`,
|
||||
true,
|
||||
);
|
||||
expect(res.ok, `iceberg_scan failed: ${res.out}`).toBe(true);
|
||||
const rows = JSON.parse(res.out) as string[][];
|
||||
expect(Object.fromEntries(rows.map((r) => [r[0], Number(r[1])]))).toEqual({ NO: 20, SE: 40 });
|
||||
evidence.iceberg = {
|
||||
read_by: 'iceberg_scan on the exact metadata JSON',
|
||||
note:
|
||||
'an exact metadata file is a SNAPSHOT reference; DuckDB refuses to glob for the latest ' +
|
||||
'version by default, and that refusal is correct — globbing can read uncommitted data',
|
||||
totals: { NO: 20, SE: 40 },
|
||||
};
|
||||
});
|
||||
});
|
||||
|
||||
suite('BI-P014 — the mount registry (layer 1)', () => {
|
||||
it('refuses an artifact belonging to another tenant, as AUTHORIZATION_DENIED not NOT_FOUND', async () => {
|
||||
let thrown: unknown;
|
||||
try {
|
||||
await provider.query(IDENTITY, { artifact_id: 'a_beta_parquet' });
|
||||
} catch (e) {
|
||||
thrown = e;
|
||||
}
|
||||
expect((thrown as SiaxError).code).toBe('AUTHORIZATION_DENIED');
|
||||
});
|
||||
|
||||
it('refuses an unmounted artifact', async () => {
|
||||
await expect(provider.query(IDENTITY, { artifact_id: 'a_nope' })).rejects.toBeInstanceOf(SiaxError);
|
||||
});
|
||||
|
||||
it('refuses a SYMLINK that escapes the mount root', () => {
|
||||
const link = path.join(FIXTURES, 'escape.parquet');
|
||||
fs.rmSync(link, { force: true });
|
||||
fs.symlinkSync('/etc/passwd', link);
|
||||
try {
|
||||
expect(() =>
|
||||
registry.register({
|
||||
artifact_id: 'a_escape',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'st0re://x',
|
||||
relative_path: 'escape.parquet',
|
||||
format: 'parquet',
|
||||
size_bytes: 1,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
evidence.symlink_escape_refused = true;
|
||||
} finally {
|
||||
fs.rmSync(link, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('refuses a traversing relative path', () => {
|
||||
expect(() =>
|
||||
registry.register({
|
||||
artifact_id: 'a_trav',
|
||||
tenant_id: 't_alpha',
|
||||
st0re_ref: 'st0re://x',
|
||||
relative_path: '../../../../etc/passwd',
|
||||
format: 'csv',
|
||||
size_bytes: 1,
|
||||
}),
|
||||
).toThrowError(SiaxError);
|
||||
});
|
||||
});
|
||||
|
||||
suite('BI-P014 — layer 2 alone, WITH THE MOUNT REGISTRY REMOVED', () => {
|
||||
/** Attempts sent straight to DuckDB. Layer 1 is not in the picture. */
|
||||
const attempts: Array<{ id: string; sql: string }> = [
|
||||
{ id: 'read-etc-passwd', sql: "SELECT * FROM read_csv('/etc/passwd')" },
|
||||
{ id: 'read-etc-shadow', sql: "SELECT * FROM read_csv('/etc/shadow')" },
|
||||
{ id: 'traversal-from-mount', sql: `SELECT * FROM read_csv('${FIXTURES}/../../../../etc/passwd')` },
|
||||
{ id: 'glob-root', sql: "SELECT * FROM read_csv('/etc/*')" },
|
||||
{ id: 'http-exfiltration', sql: "SELECT * FROM read_csv('https://example.com/a.csv')" },
|
||||
{ id: 's3-read', sql: "SELECT * FROM read_parquet('s3://bucket/a.parquet')" },
|
||||
// Not a SELECT: ATTACH is the other way a local engine touches a file.
|
||||
// The first version of this corpus had `SELECT 1 FROM (SELECT 1) t` here,
|
||||
// which is not an attack at all — it succeeded and was reported as a leak.
|
||||
// A corpus entry that cannot fail is as useless as a check that cannot.
|
||||
{ id: 'attach-external-db', sql: "ATTACH '/tmp/duckdb_escape.db' AS evil" },
|
||||
{ id: 'attach-etc', sql: "ATTACH '/etc/passwd' AS evil2 (READ_ONLY)" },
|
||||
{ id: 'copy-out-of-mount', sql: "COPY (SELECT 1 AS a) TO '/tmp/duckdb_escape.csv' (FORMAT CSV)" },
|
||||
{ id: 'read-parquet-outside', sql: "SELECT * FROM read_parquet('/root/x.parquet')" },
|
||||
{ id: 'json-outside', sql: "SELECT * FROM read_json_auto('/etc/hosts')" },
|
||||
];
|
||||
|
||||
it('no attempt reads anything outside the mount, and the file inside still works', () => {
|
||||
const bootstrap = duckDbSessionBootstrap([FIXTURES]);
|
||||
const results: Array<Record<string, unknown>> = [];
|
||||
const leaks: string[] = [];
|
||||
|
||||
for (const attempt of attempts) {
|
||||
const res = runDuck(bootstrap, attempt.sql);
|
||||
// A leak is a SUCCESSFUL read. `s3://` and `https://` may fail for other
|
||||
// reasons too, but the assertion is on success, not on the message.
|
||||
if (res.ok) leaks.push(attempt.id);
|
||||
results.push({ id: attempt.id, succeeded: res.ok, engine_message: res.out.slice(0, 140) });
|
||||
}
|
||||
|
||||
// The counterfactual: the SAME session reads the mounted file fine, so
|
||||
// "nothing succeeded" is not because the sandbox blocks everything.
|
||||
const inside = runDuck(bootstrap, `SELECT count(*) FROM read_parquet('${FIXTURES}/sales.parquet')`);
|
||||
expect(inside.ok, 'the sandbox blocked the mounted file too — it is not a sandbox, it is an outage').toBe(
|
||||
true,
|
||||
);
|
||||
expect(JSON.parse(inside.out)[0][0]).toBe('5');
|
||||
|
||||
expect(leaks, `DuckDB read outside the mount: ${leaks.join(', ')}`).toEqual([]);
|
||||
evidence.sandbox_bypass_attempts = results;
|
||||
evidence.counterfactual_mounted_file_readable = true;
|
||||
}, 120_000);
|
||||
|
||||
it('the NAIVE spelling of the sandbox is a NO-OP — measured, not assumed', () => {
|
||||
// allowed_directories WITHOUT enable_external_access=false. This is what
|
||||
// an implementer reaches for first, and it permits everything.
|
||||
const naive = [`SET allowed_directories=['${FIXTURES}']`];
|
||||
const res = runDuck(naive, "SELECT * FROM read_csv('/etc/passwd') LIMIT 1");
|
||||
expect(res.ok, 'if this ever fails, DuckDB changed its behaviour and the header comment is stale').toBe(
|
||||
true,
|
||||
);
|
||||
evidence.naive_allowed_directories_is_a_noop = {
|
||||
statements: naive,
|
||||
read_etc_passwd_succeeded: res.ok,
|
||||
note:
|
||||
'allowed_directories alone appears in duckdb_settings() and looks like a sandbox. ' +
|
||||
'It permits /etc/passwd and outbound HTTP. Only enable_external_access=false binds it.',
|
||||
};
|
||||
});
|
||||
|
||||
it('a locked session cannot re-open its own sandbox', () => {
|
||||
const bootstrap = duckDbSessionBootstrap([FIXTURES]);
|
||||
// Sanity: the locked session works.
|
||||
expect(runDuck(bootstrap, 'SELECT 1').ok).toBe(true);
|
||||
|
||||
const reopened: Array<Record<string, unknown>> = [];
|
||||
for (const reopen of [
|
||||
"SET allowed_directories=['/etc']",
|
||||
'SET enable_external_access=true',
|
||||
'SET lock_configuration=false',
|
||||
]) {
|
||||
// Appending the re-open AFTER lock_configuration=true must fail, and it
|
||||
// must fail on the SET itself — so the following read never happens.
|
||||
const attempt = runDuck([...bootstrap, reopen], "SELECT * FROM read_csv('/etc/passwd') LIMIT 1");
|
||||
expect(attempt.ok, `"${reopen}" was accepted after lock_configuration=true`).toBe(false);
|
||||
reopened.push({ statement: reopen, refused: !attempt.ok, engine_message: attempt.out.slice(0, 120) });
|
||||
}
|
||||
evidence.reconfiguration_refused = reopened;
|
||||
}, 60_000);
|
||||
|
||||
it('writes the evidence file', () => {
|
||||
fs.mkdirSync(path.dirname(EVIDENCE_PATH), { recursive: true });
|
||||
fs.writeFileSync(EVIDENCE_PATH, `${JSON.stringify(evidence, null, 2)}\n`);
|
||||
expect(fs.existsSync(EVIDENCE_PATH)).toBe(true);
|
||||
});
|
||||
});
|
||||
Vendored
+23
@@ -0,0 +1,23 @@
|
||||
# `tests/fixtures/duckdb/` — BI-P014
|
||||
|
||||
`sales.parquet` and `customers.csv` are committed: small, binary-stable, and
|
||||
portable across checkouts.
|
||||
|
||||
The **Iceberg** fixture is deliberately NOT committed. `pyiceberg` writes
|
||||
ABSOLUTE paths into its metadata and Avro manifests, so a committed table only
|
||||
resolves on the machine that built it — a fixture that silently fails
|
||||
everywhere else is worse than no fixture. The recorded result of a real
|
||||
`iceberg_scan` run is kept in `evidence/bi-p014/duckdb-sandbox.json` instead,
|
||||
and `tests/analytics/duckdb-provider.test.ts` pins it.
|
||||
|
||||
To rebuild the Iceberg fixture locally:
|
||||
|
||||
```
|
||||
python -m venv .venv && .venv/bin/pip install duckdb pyarrow 'pyiceberg[sql-sqlite]'
|
||||
DUCKDB_PYTHON=.venv/bin/python pnpm vitest run tests/duckdb/duckdb-provider.live.test.ts
|
||||
```
|
||||
|
||||
`iceberg_scan` is pointed at an EXACT metadata JSON file rather than a table
|
||||
directory. That is not a workaround: DuckDB refuses to glob for the latest
|
||||
version by default because globbing can read uncommitted data, and an exact
|
||||
metadata file is precisely what "Iceberg **snapshot**" means in BI-P014.
|
||||
Vendored
+4
@@ -0,0 +1,4 @@
|
||||
customer_id,name
|
||||
c1,Acme
|
||||
c2,Beta AB
|
||||
c3,O'Brien Ltd
|
||||
|
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,48 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { NextRequest } from "next/server";
|
||||
import { assertTenantMatchesVerified, VERIFIED_TENANT_HEADER } from "@/src/http/tenant-guard";
|
||||
|
||||
function req(headers: Record<string, string> = {}): NextRequest {
|
||||
return new NextRequest("http://localhost/api/0pt/sources", { headers });
|
||||
}
|
||||
|
||||
describe("assertTenantMatchesVerified", () => {
|
||||
it("returns 403 when the client-supplied tenant_id disagrees with the verified header", () => {
|
||||
const res = assertTenantMatchesVerified(req({ [VERIFIED_TENANT_HEADER]: "t_a" }), "t_b");
|
||||
expect(res).not.toBeNull();
|
||||
expect(res!.status).toBe(403);
|
||||
});
|
||||
|
||||
it("the 403 body names both the requested and verified tenant, without leaking which is 'right'", async () => {
|
||||
const res = assertTenantMatchesVerified(req({ [VERIFIED_TENANT_HEADER]: "t_a" }), "t_b");
|
||||
const body = await res!.json();
|
||||
expect(body.error).toBe("OPT_ACCESS_DENIED");
|
||||
expect(body.details).toEqual({ requested_tenant: "t_b", verified_tenant: "t_a" });
|
||||
});
|
||||
|
||||
it("returns null (proceed) when the tenant matches", () => {
|
||||
const res = assertTenantMatchesVerified(req({ [VERIFIED_TENANT_HEADER]: "t_a" }), "t_a");
|
||||
expect(res).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null (proceed) when no verified-tenant header is present (local-dev escape hatch)", () => {
|
||||
const res = assertTenantMatchesVerified(req({}), "t_b");
|
||||
expect(res).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null when tenantId itself is missing/empty (handlers 400 on that separately)", () => {
|
||||
const res = assertTenantMatchesVerified(req({ [VERIFIED_TENANT_HEADER]: "t_a" }), null);
|
||||
expect(res).toBeNull();
|
||||
});
|
||||
|
||||
it("a spoofed verified-tenant header cannot be used to APPROVE a mismatched request -- only middleware.ts ever sets this header for real", () => {
|
||||
// This is a documentation-by-test of the trust boundary: the guard trusts
|
||||
// whatever is in the header, which is exactly why every route sits behind
|
||||
// middleware.ts (matcher /api/0pt/:path*) that overwrites it with the
|
||||
// real verified value -- a caller hitting the route directly, outside
|
||||
// Next's routing, cannot reach the handler without going through
|
||||
// middleware first in a real deployment.
|
||||
const res = assertTenantMatchesVerified(req({ [VERIFIED_TENANT_HEADER]: "t_attacker" }), "t_attacker");
|
||||
expect(res).toBeNull(); // matches -- proves the guard is a pure equality check, no extra magic
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,217 @@
|
||||
/**
|
||||
* End-to-end proof for src/ingestion/vehiq-oltp-ingest-runner.ts — the
|
||||
* actual pipeline the scheduled workflow runs, wired through the REAL P062
|
||||
* IngestionRunner (InMemoryIngestionRepository backing it, no real
|
||||
* Postgres/ClickHouse). Four things the task requires are asserted here
|
||||
* specifically, not just "it doesn't throw":
|
||||
*
|
||||
* 1. a batch respects the watermark/limit (proven at the connector layer
|
||||
* already; here proven again at the FULL pipeline layer, envelope by
|
||||
* envelope);
|
||||
* 2. a run resumes correctly from a checkpoint after an interruption (a
|
||||
* sink that throws on its 2nd call, mid-run — same technique
|
||||
* tests/p0/ingestion-runner.test.ts itself uses to prove this for the
|
||||
* generic runner);
|
||||
* 3. the empty-table case (today's actual production state for all three
|
||||
* OLTP tables) completes with zero batches / zero sink calls / no
|
||||
* throw;
|
||||
* 4. the vehicle-dimension lookup only ever touches vehicle rows actually
|
||||
* referenced by dealer_stock_entry in the batch that ran — asserted by
|
||||
* capturing every query the dimension connector issues.
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { InMemoryIngestionRepository } from "@/src/repositories/in-memory-ingestion-repository";
|
||||
import { SchemaRegistry } from "@/src/schema/schema-registry";
|
||||
import {
|
||||
runVehiqOltpIngestion,
|
||||
previewVehiqOltpSource,
|
||||
VEHIQ_OLTP_SOURCES,
|
||||
type VehiqOltpIngestDeps,
|
||||
} from "@/src/ingestion/vehiq-oltp-ingest-runner";
|
||||
import type { QueryImpl, SourceRow } from "@/src/connectors/postgres-watermark-connector";
|
||||
import type { IngestionEnvelope } from "@/src/types/ingestion";
|
||||
|
||||
/**
|
||||
* A fake source Postgres. One table per fixture entry, keyed by the
|
||||
* connector's own `table` name. Generic across whichever watermark/
|
||||
* record-key column names the real connector puts in the SQL text — parsed
|
||||
* out of the statement itself (`ORDER BY <watermark>, <key>`) rather than
|
||||
* hardcoded, since `dealer_stock_entry` (watermark `listed_at`, key `id`)
|
||||
* and `deal` (watermark `created_at`, key `id`) use different column names.
|
||||
*/
|
||||
function fixtureVehiqDb(tables: Record<string, SourceRow[]>): { query: QueryImpl; calls: Array<{ sql: string; params: unknown[] }> } {
|
||||
const calls: Array<{ sql: string; params: unknown[] }> = [];
|
||||
const query: QueryImpl = async (sql, params) => {
|
||||
calls.push({ sql, params });
|
||||
const tableName = Object.keys(tables).find((t) => sql.includes(`FROM ${t}`));
|
||||
const rows = tableName ? tables[tableName] : [];
|
||||
const orderBy = /ORDER BY (\w+), (\w+)/.exec(sql);
|
||||
if (sql.includes("= ANY($1)")) {
|
||||
const keyColMatch = /WHERE (\w+) = ANY/.exec(sql);
|
||||
const keyCol = keyColMatch ? keyColMatch[1] : "id";
|
||||
const [ids] = params as [Array<string | number>];
|
||||
return rows.filter((r) => ids.includes(r[keyCol] as string));
|
||||
}
|
||||
if (!orderBy) return rows.slice(0, Number(params[params.length - 1]));
|
||||
const [, watermarkCol, keyCol] = orderBy;
|
||||
let filtered = rows;
|
||||
if (sql.includes("WHERE")) {
|
||||
const [watermark, id] = params as [string, string, number];
|
||||
filtered = rows.filter(
|
||||
(r) => (r[watermarkCol] as string) > watermark || ((r[watermarkCol] as string) === watermark && (r[keyCol] as string) > id),
|
||||
);
|
||||
}
|
||||
const sorted = [...filtered].sort((a, b) => {
|
||||
const w = (a[watermarkCol] as string).localeCompare(b[watermarkCol] as string);
|
||||
return w !== 0 ? w : (a[keyCol] as string).localeCompare(b[keyCol] as string);
|
||||
});
|
||||
const limit = Number(params[params.length - 1]);
|
||||
return sorted.slice(0, limit);
|
||||
};
|
||||
return { query, calls };
|
||||
}
|
||||
|
||||
function baseDeps(query: QueryImpl, sink: (e: IngestionEnvelope[]) => Promise<void>): VehiqOltpIngestDeps {
|
||||
const repo = new InMemoryIngestionRepository();
|
||||
return {
|
||||
repo,
|
||||
schemas: new SchemaRegistry(repo),
|
||||
sourceQuery: query,
|
||||
oltpSink: sink,
|
||||
dimensionSink: sink,
|
||||
tenantId: "t_vehiq",
|
||||
projectId: "vehiq",
|
||||
pageSize: 2,
|
||||
};
|
||||
}
|
||||
|
||||
describe("runVehiqOltpIngestion — empty-table case (today's actual production state)", () => {
|
||||
it("completes with zero batches, zero sink calls, no error, for all three OLTP tables", async () => {
|
||||
const { query } = fixtureVehiqDb({ "app.dealer_stock_entry": [], "app.listing": [], "app.deal": [] });
|
||||
const seen: IngestionEnvelope[] = [];
|
||||
const summary = await runVehiqOltpIngestion(baseDeps(query, async (e) => void seen.push(...e)));
|
||||
|
||||
expect(seen).toHaveLength(0);
|
||||
expect(summary.referenced_vehicle_ids).toBe(0);
|
||||
expect(summary.dimension).toBeUndefined(); // no referenced vehicles => the keyed-lookup connector is never even constructed
|
||||
for (const report of summary.oltp) {
|
||||
expect(report.status).toBe("succeeded");
|
||||
expect(report.partitions.every((p) => p.records_read === 0)).toBe(true);
|
||||
expect(report.partitions.every((p) => p.envelopes_emitted === 0)).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("previewVehiqOltpSource against empty tables never commits a checkpoint and reports would_read: 0", async () => {
|
||||
const { query } = fixtureVehiqDb({ "app.dealer_stock_entry": [] });
|
||||
const repo = new InMemoryIngestionRepository();
|
||||
const source = VEHIQ_OLTP_SOURCES.find((s) => s.partition_key === "dealer_stock_entry")!;
|
||||
const preview = await previewVehiqOltpSource(source, query, repo, {
|
||||
sourceId: "vehiq_oltp",
|
||||
tenantId: "t_vehiq",
|
||||
projectId: "vehiq",
|
||||
});
|
||||
expect(preview.would_read).toBe(0);
|
||||
expect(preview.exhausted).toBe(true);
|
||||
// Never committed — getCheckpoint after the preview still reports nothing.
|
||||
expect(await repo.getCheckpoint("vehiq_oltp", "dealer_stock_entry")).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
// Column shape verified live against production (server10, vehiq-db,
|
||||
// information_schema.columns, read-only, 2026-09-25) — see the doc comment
|
||||
// on VEHIQ_OLTP_SOURCES for why there is no `updated_at` here.
|
||||
const DEALER_STOCK_ROWS: SourceRow[] = [
|
||||
{ id: "d1", tenant_id: "t_vehiq", vehicle_id: "v1", lot_location: "Lot A", floorplan_status: "owned", listed_at: "2026-09-01T00:00:00.000Z", sold_at: null },
|
||||
{ id: "d2", tenant_id: "t_vehiq", vehicle_id: "v2", lot_location: "Lot A", floorplan_status: "financed", listed_at: "2026-09-02T00:00:00.000Z", sold_at: null },
|
||||
{ id: "d3", tenant_id: "t_vehiq", vehicle_id: "v1", lot_location: "Lot B", floorplan_status: "owned", listed_at: "2026-09-03T00:00:00.000Z", sold_at: "2026-09-04T00:00:00.000Z" },
|
||||
];
|
||||
const VEHICLE_ROWS: SourceRow[] = [
|
||||
{ vehicle_id: "v1", make: "Volvo", model: "XC60", model_year: 2022, fuel_type: "electric" },
|
||||
{ vehicle_id: "v2", make: "Toyota", model: "Corolla", model_year: 2021, fuel_type: "petrol" },
|
||||
{ vehicle_id: "v9", make: "Never", model: "Referenced", model_year: 2020, fuel_type: "diesel" }, // must never be queried
|
||||
];
|
||||
|
||||
describe("runVehiqOltpIngestion — watermark/limit correctness with real data", () => {
|
||||
it("emits envelopes for every row, in watermark order, and derives exactly the referenced vehicle ids", async () => {
|
||||
const { query } = fixtureVehiqDb({
|
||||
"app.dealer_stock_entry": DEALER_STOCK_ROWS,
|
||||
"app.listing": [],
|
||||
"app.deal": [],
|
||||
"vehiq.vehicle": VEHICLE_ROWS,
|
||||
});
|
||||
const seen: IngestionEnvelope[] = [];
|
||||
const dimensionSeen: IngestionEnvelope[] = [];
|
||||
const deps = baseDeps(query, async (e) => void seen.push(...e));
|
||||
deps.dimensionSink = async (e) => void dimensionSeen.push(...e);
|
||||
|
||||
const summary = await runVehiqOltpIngestion(deps);
|
||||
|
||||
const dealerEnvelopes = seen.filter((e) => e.partition_key === "dealer_stock_entry");
|
||||
expect(dealerEnvelopes.map((e) => e.record_key)).toEqual(["d1", "d2", "d3"]);
|
||||
expect(summary.referenced_vehicle_ids).toBe(2); // v1, v2 — deduped from d1/d2/d3
|
||||
expect(summary.dimension?.status).toBe("succeeded");
|
||||
expect(dimensionSeen.map((e) => e.record_key).sort()).toEqual(["v1", "v2"]);
|
||||
expect(dimensionSeen.map((e) => e.record_key)).not.toContain("v9");
|
||||
});
|
||||
});
|
||||
|
||||
describe("runVehiqOltpIngestion — resume from checkpoint after an interruption", () => {
|
||||
it("a sink that dies mid-run leaves the checkpoint unmoved for the failed page; the NEXT run resumes with no gap and no duplicate landing", async () => {
|
||||
const { query } = fixtureVehiqDb({
|
||||
"app.dealer_stock_entry": DEALER_STOCK_ROWS,
|
||||
"app.listing": [],
|
||||
"app.deal": [],
|
||||
"vehiq.vehicle": VEHICLE_ROWS,
|
||||
});
|
||||
const repo = new InMemoryIngestionRepository();
|
||||
const schemas = new SchemaRegistry(repo);
|
||||
const landed: IngestionEnvelope[] = [];
|
||||
let call = 0;
|
||||
|
||||
// First run: the sink accepts page 1 (2 rows, page_size=2) then throws on
|
||||
// page 2 — simulating the process dying after the first page's checkpoint
|
||||
// committed but before the second page's did.
|
||||
const crashingSink = async (batch: IngestionEnvelope[]): Promise<void> => {
|
||||
call++;
|
||||
if (call === 2) throw new Error("simulated crash mid-run");
|
||||
landed.push(...batch);
|
||||
};
|
||||
// Matches the generic runner's own documented behaviour (tests/p0/
|
||||
// ingestion-runner.test.ts "a run that dies inside the sink..."): a
|
||||
// throwing sink REJECTS the run, it does not resolve with status:"failed".
|
||||
// dealer_stock_entry is the FIRST source this pipeline processes, so its
|
||||
// page-2 crash is what aborts runVehiqOltpIngestion() itself here.
|
||||
await expect(
|
||||
runVehiqOltpIngestion({
|
||||
repo,
|
||||
schemas,
|
||||
sourceQuery: query,
|
||||
oltpSink: crashingSink,
|
||||
dimensionSink: async () => undefined,
|
||||
tenantId: "t_vehiq",
|
||||
projectId: "vehiq",
|
||||
pageSize: 2,
|
||||
}),
|
||||
).rejects.toThrow(/simulated crash mid-run/);
|
||||
expect(landed.map((e) => e.record_key)).toEqual(["d1", "d2"]); // page 1 landed before the crash
|
||||
// The durable checkpoint reflects page 1 only — page 2's checkpoint never committed.
|
||||
const afterCrash = await repo.getCheckpoint("vehiq_oltp_dealer_stock_entry", "dealer_stock_entry");
|
||||
expect(afterCrash?.records_committed).toBe(2);
|
||||
|
||||
// Second run, same repo (durable checkpoint survives the "restart"): must
|
||||
// NOT re-deliver d1/d2, and MUST deliver d3.
|
||||
const run2 = await runVehiqOltpIngestion({
|
||||
repo,
|
||||
schemas,
|
||||
sourceQuery: query,
|
||||
oltpSink: async (batch) => void landed.push(...batch),
|
||||
dimensionSink: async () => undefined,
|
||||
tenantId: "t_vehiq",
|
||||
projectId: "vehiq",
|
||||
pageSize: 2,
|
||||
});
|
||||
const dealerReport2 = run2.oltp.find((r) => r.partitions[0]?.partition_key === "dealer_stock_entry");
|
||||
expect(dealerReport2?.status).toBe("succeeded");
|
||||
expect(landed.map((e) => e.record_key)).toEqual(["d1", "d2", "d3"]); // exactly once each, no gap, no dupe
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,433 @@
|
||||
/**
|
||||
* tests/integration/analyst-sql-clickhouse.integration.test.ts
|
||||
* =============================================================
|
||||
* BI-P017 — the proof that matters: the bypass corpus run against a LIVE
|
||||
* ClickHouse **with the statement guard removed**.
|
||||
*
|
||||
* The guard (layer 2) is a text analysis of a dialect it does not implement.
|
||||
* Testing only the guard proves the guard. What has to hold is that when the
|
||||
* guard is WRONG, nothing leaks — so this file skips the guard entirely and
|
||||
* sends each attack straight to the engine as the tenant's restricted user.
|
||||
* Layer 3 (grants + `readonly = 1`) and layer 4 (views that bake the tenant
|
||||
* predicate, over base tables carrying a row policy) must refuse it anyway.
|
||||
*
|
||||
* The assertion is deliberately NOT "the engine returned an error". It is
|
||||
* "no foreign row came back", checked by canary values seeded into the other
|
||||
* tenant's rows and into an ungranted table. An attack that succeeds and
|
||||
* returns nothing interesting still fails the test if it returns a canary.
|
||||
*
|
||||
* Counterfactual, run first, because a test that would pass against an empty
|
||||
* database proves nothing: as the ADMIN user the base table holds both
|
||||
* tenants' rows, and `BETA_CANARY` IS readable. Every later assertion is
|
||||
* therefore about isolation, not about absence of data.
|
||||
*
|
||||
* ── HOW THIS AVOIDS THE SILENT-SKIP TRAP ──────────────────────────────────
|
||||
* l0re's 28 Postgres tests skipped silently for months and nobody noticed.
|
||||
* This suite self-skips when ClickHouse is unreachable — but on a live run it
|
||||
* WRITES `evidence/bi-p017/analyst-sql-live-bypass.json`, and
|
||||
* tests/analytics/analyst-sql-evidence.test.ts (which never skips) fails if
|
||||
* that file is missing, stale, or does not cover every attempt in the corpus.
|
||||
* Adding an attack without re-running this suite breaks the build.
|
||||
*
|
||||
* Point it at a disposable instance:
|
||||
* docker run -d --name ch -p 28123:8123 -e CLICKHOUSE_SKIP_USER_SETUP=1 \
|
||||
* clickhouse/clickhouse-server:24.8
|
||||
* ANALYTICS_CLICKHOUSE_URL=http://127.0.0.1:28123 pnpm vitest run \
|
||||
* tests/integration/analyst-sql-clickhouse.integration.test.ts
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { beforeAll, describe, expect, it } from 'vitest';
|
||||
import {
|
||||
BYPASS_CORPUS,
|
||||
GUARD_ADMITS_ENGINE_REFUSES,
|
||||
LEGITIMATE_CORPUS,
|
||||
} from '../analytics/analyst-sql-bypass-corpus';
|
||||
import { guardAnalystStatement } from '@/src/analytics/sql/statement-guard';
|
||||
import {
|
||||
rowPolicyVerificationSql,
|
||||
tenantSqlCatalogDdl,
|
||||
tenantSqlUserDdl,
|
||||
} from '@/src/analytics/sql/tenant-catalog';
|
||||
import { applyQuota, DEFAULT_BUDGETS } from '@/src/analytics/engine/resource-governance';
|
||||
|
||||
/**
|
||||
* Gated on the ENV VAR, matching the convention already in
|
||||
* tests/integration/analytics-tenant-isolation.integration.test.ts — and
|
||||
* chosen over a liveness probe on purpose: with the variable set, a
|
||||
* ClickHouse that is down makes this suite FAIL. A probe would have turned a
|
||||
* broken server into a silent green, which is the failure mode this estate
|
||||
* keeps shipping.
|
||||
*/
|
||||
const BASE_URL = process.env.CLICKHOUSE_URL ?? '';
|
||||
const ADMIN_AUTH = process.env.CLICKHOUSE_AUTH ?? 'default:';
|
||||
const DB = 'opt_analytics';
|
||||
const ALPHA_PW = 'alpha_test_pw_not_a_secret';
|
||||
const BETA_PW = 'beta_test_pw_not_a_secret';
|
||||
const EVIDENCE_PATH = path.join(process.cwd(), 'evidence/bi-p017/analyst-sql-live-bypass.json');
|
||||
|
||||
/** Canaries. Their presence in a response body is the definition of a leak. */
|
||||
const BETA_CANARY = 'BETA_CANARY_9f21c4';
|
||||
const SECRET_CANARY = 'SECRET_CANARY_4d80ab';
|
||||
const ALPHA_MARK = 'ALPHA_ROW';
|
||||
|
||||
interface ChResponse {
|
||||
ok: boolean;
|
||||
status: number;
|
||||
body: string;
|
||||
}
|
||||
|
||||
async function run(sql: string, auth: string, settings: Record<string, string> = {}): Promise<ChResponse> {
|
||||
const url = new URL(BASE_URL);
|
||||
url.searchParams.set('query', sql);
|
||||
for (const [k, v] of Object.entries(settings)) url.searchParams.set(k, v);
|
||||
const res = await fetch(url.toString(), {
|
||||
method: 'POST',
|
||||
headers: { Authorization: `Basic ${Buffer.from(auth).toString('base64')}` },
|
||||
body: '',
|
||||
signal: AbortSignal.timeout(30_000),
|
||||
});
|
||||
return { ok: res.ok, status: res.status, body: await res.text() };
|
||||
}
|
||||
|
||||
const admin = (sql: string) => run(sql, ADMIN_AUTH);
|
||||
/**
|
||||
* The session's real posture: the restricted user, and NO settings on the
|
||||
* request.
|
||||
*
|
||||
* MEASURED: a user whose profile carries `readonly = 1` cannot have any
|
||||
* setting changed from the request — ClickHouse answers `Code: 164. Cannot
|
||||
* modify 'max_rows_to_read' setting in readonly mode.` So the BI-P012 ceilings
|
||||
* cannot travel with the statement here the way they do for the non-readonly
|
||||
* engine user; they are baked into the SETTINGS PROFILE by
|
||||
* `tenantSqlUserDdl`, and the test below proves the profile enforces them.
|
||||
*/
|
||||
const asAlpha = (sql: string) => run(sql, `t_alpha_sql_user:${ALPHA_PW}`);
|
||||
|
||||
/**
|
||||
* An earlier revision set a `reachable` flag inside `beforeAll` and used
|
||||
* `describe.skipIf(!reachable)`. Vitest evaluates `skipIf` at COLLECTION time,
|
||||
* before any hook runs, so the flag was always false and all ten tests skipped
|
||||
* against a live, reachable ClickHouse — a suite that could never run,
|
||||
* reporting green. Same shape as l0re's 28 silently-skipped Postgres tests.
|
||||
* Recorded here because the next person will reach for `skipIf` too.
|
||||
*/
|
||||
const suite = BASE_URL ? describe : describe.skip;
|
||||
let version = '';
|
||||
|
||||
/** The session budget for the main user: generous enough for real analyst work. */
|
||||
const TEST_BUDGET = applyQuota(DEFAULT_BUDGETS.ANALYTICAL, {
|
||||
maxRowsToRead: 100_000,
|
||||
maxExecutionTimeSec: 10,
|
||||
});
|
||||
|
||||
/**
|
||||
* A SECOND user with a deliberately tiny `maxRowsToRead` (60), provisioned
|
||||
* only to make the profile's enforcement observable: the tenant view holds 50
|
||||
* rows, which passes; anything wider exceeds it and must fail with ClickHouse
|
||||
* code 158. A ceiling nothing can breach proves nothing, and the first
|
||||
* revision of this file proved exactly that by starving the legitimate corpus.
|
||||
*/
|
||||
const TINY_BUDGET = applyQuota(DEFAULT_BUDGETS.ANALYTICAL, { maxRowsToRead: 60, maxExecutionTimeSec: 10 });
|
||||
const TINY_PW = 'tiny_test_pw_not_a_secret';
|
||||
|
||||
const OBJECTS = [
|
||||
{ table: 'sales', columns: ['customer', 'amount', 'event_time'] },
|
||||
{ table: 'events', columns: ['customer', 'kind', 'event_time'] },
|
||||
];
|
||||
|
||||
beforeAll(async () => {
|
||||
if (!BASE_URL) return;
|
||||
// With CLICKHOUSE_URL set, an unreachable server FAILS here. It does not
|
||||
// degrade to a skip.
|
||||
const v = await admin('SELECT version()');
|
||||
if (!v.ok)
|
||||
throw new Error(
|
||||
`CLICKHOUSE_URL is set but ClickHouse is not answering: ${v.status} ${v.body.slice(0, 200)}`,
|
||||
);
|
||||
version = v.body.trim();
|
||||
|
||||
await admin(`DROP DATABASE IF EXISTS ${DB}`);
|
||||
await admin(`DROP DATABASE IF EXISTS t_alpha_sql`);
|
||||
await admin(`DROP DATABASE IF EXISTS t_beta_sql`);
|
||||
await admin(`DROP USER IF EXISTS t_alpha_sql_user`);
|
||||
await admin(`DROP USER IF EXISTS t_beta_sql_user`);
|
||||
await admin(`DROP USER IF EXISTS t_alpha_tiny_user`);
|
||||
await admin(`CREATE DATABASE ${DB}`);
|
||||
|
||||
await admin(
|
||||
`CREATE TABLE ${DB}.sales (tenant_id String, customer String, amount Float64, event_time DateTime) ` +
|
||||
`ENGINE = MergeTree ORDER BY (tenant_id, event_time)`,
|
||||
);
|
||||
await admin(
|
||||
`CREATE TABLE ${DB}.events (tenant_id String, customer String, kind String, event_time DateTime) ` +
|
||||
`ENGINE = MergeTree ORDER BY (tenant_id, event_time)`,
|
||||
);
|
||||
await admin(
|
||||
`CREATE TABLE ${DB}.secret_ledger (tenant_id String, note String) ENGINE = MergeTree ORDER BY tenant_id`,
|
||||
);
|
||||
// Also present, because several attacks name it: the BI-P010 event table.
|
||||
await admin(
|
||||
`CREATE TABLE ${DB}.opt_analytics_event (tenant_id String, project_id String, dataset_id String, ` +
|
||||
`event_id String, metric String, value Float64, event_time DateTime) ENGINE = MergeTree ` +
|
||||
`ORDER BY (tenant_id, event_time)`,
|
||||
);
|
||||
|
||||
await admin(
|
||||
`INSERT INTO ${DB}.sales SELECT 't_alpha', '${ALPHA_MARK}_' || toString(number), number, now() FROM numbers(50)`,
|
||||
);
|
||||
await admin(
|
||||
`INSERT INTO ${DB}.sales SELECT 't_beta', '${BETA_CANARY}_' || toString(number), number, now() FROM numbers(50)`,
|
||||
);
|
||||
await admin(
|
||||
`INSERT INTO ${DB}.events SELECT 't_alpha', '${ALPHA_MARK}_' || toString(number), 'click', now() FROM numbers(20)`,
|
||||
);
|
||||
await admin(
|
||||
`INSERT INTO ${DB}.events SELECT 't_beta', '${BETA_CANARY}_' || toString(number), 'click', now() FROM numbers(20)`,
|
||||
);
|
||||
await admin(`INSERT INTO ${DB}.secret_ledger VALUES ('t_alpha', '${SECRET_CANARY}')`);
|
||||
await admin(
|
||||
`INSERT INTO ${DB}.opt_analytics_event SELECT 't_beta', 'p', 'd', toString(number), 'm', number, now() FROM numbers(10)`,
|
||||
);
|
||||
|
||||
for (const [tenant, catalog, user, pw] of [
|
||||
['t_alpha', 't_alpha_sql', 't_alpha_sql_user', ALPHA_PW],
|
||||
['t_beta', 't_beta_sql', 't_beta_sql_user', BETA_PW],
|
||||
] as const) {
|
||||
const spec = { sourceDatabase: DB, tenantId: tenant, catalog, objects: OBJECTS };
|
||||
for (const stmt of tenantSqlCatalogDdl(spec)) {
|
||||
const r = await admin(stmt);
|
||||
if (!r.ok) throw new Error(`catalog DDL failed: ${stmt} -> ${r.body.slice(0, 200)}`);
|
||||
}
|
||||
for (const stmt of tenantSqlUserDdl({ ...spec, userName: user, password: pw, budget: TEST_BUDGET })) {
|
||||
const r = await admin(stmt);
|
||||
if (!r.ok) throw new Error(`user DDL failed: ${stmt} -> ${r.body.slice(0, 200)}`);
|
||||
}
|
||||
}
|
||||
|
||||
const tinySpec = { sourceDatabase: DB, tenantId: 't_alpha', catalog: 't_alpha_sql', objects: OBJECTS };
|
||||
for (const stmt of tenantSqlUserDdl({
|
||||
...tinySpec,
|
||||
userName: 't_alpha_tiny_user',
|
||||
password: TINY_PW,
|
||||
budget: TINY_BUDGET,
|
||||
})) {
|
||||
const r = await admin(stmt);
|
||||
if (!r.ok) throw new Error(`tiny user DDL failed: ${stmt} -> ${r.body.slice(0, 200)}`);
|
||||
}
|
||||
}, 120_000);
|
||||
|
||||
suite('BI-P017 live — counterfactual: the data IS there and IS reachable without the layers', () => {
|
||||
it('the shared base table holds both tenants, and BETA_CANARY is readable as admin', async () => {
|
||||
const all = await admin(`SELECT count() FROM ${DB}.sales`);
|
||||
expect(all.ok).toBe(true);
|
||||
expect(Number(all.body.trim())).toBe(100);
|
||||
const beta = await admin(`SELECT customer FROM ${DB}.sales WHERE tenant_id = 't_beta' LIMIT 1`);
|
||||
expect(beta.body).toContain(BETA_CANARY);
|
||||
const secret = await admin(`SELECT note FROM ${DB}.secret_ledger`);
|
||||
expect(secret.body).toContain(SECRET_CANARY);
|
||||
});
|
||||
|
||||
it('layer 4: the tenant view returns 50 of the 100 rows, and never the canary', async () => {
|
||||
const scoped = await asAlpha(`SELECT count() FROM t_alpha_sql.sales`);
|
||||
expect(scoped.ok).toBe(true);
|
||||
expect(Number(scoped.body.trim())).toBe(50);
|
||||
const rows = await asAlpha(`SELECT customer FROM t_alpha_sql.sales LIMIT 100`);
|
||||
expect(rows.body).toContain(ALPHA_MARK);
|
||||
expect(rows.body).not.toContain(BETA_CANARY);
|
||||
});
|
||||
});
|
||||
|
||||
suite('BI-P017 live — the bypass corpus WITH THE GUARD REMOVED', () => {
|
||||
it('no attempt returns a foreign-tenant or ungranted-table row', async () => {
|
||||
const results: Array<Record<string, unknown>> = [];
|
||||
const leaks: string[] = [];
|
||||
|
||||
for (const attempt of [...BYPASS_CORPUS, ...GUARD_ADMITS_ENGINE_REFUSES]) {
|
||||
// THE GUARD IS NOT CALLED HERE. That is the whole point.
|
||||
const res = await asAlpha(attempt.sql);
|
||||
const leakedBeta = res.body.includes(BETA_CANARY);
|
||||
const leakedSecret = res.body.includes(SECRET_CANARY);
|
||||
const chCode = /Code:\s*(\d+)/.exec(res.body)?.[1];
|
||||
// MEASURED, and narrower than the obvious rule. ClickHouse filters
|
||||
// `system.tables` / `system.columns` by the caller's own grants: as
|
||||
// the restricted user those reads SUCCEED but return only this
|
||||
// tenant's four objects — 4 rows, not the server's inventory.
|
||||
// `system.query_log`, `system.processes` and `system.users` are
|
||||
// ACCESS_DENIED (code 497). So "any successful system read is a leak"
|
||||
// would be a false alarm; the real test is whether any FOREIGN name
|
||||
// came back.
|
||||
const leakedMetadata = res.ok && /\bt_beta\b|secret_ledger/.test(res.body);
|
||||
|
||||
if (leakedBeta || leakedSecret || leakedMetadata) {
|
||||
leaks.push(`${attempt.id}: ${attempt.goal}`);
|
||||
}
|
||||
// For completeness the guard's own verdict is recorded alongside, so
|
||||
// the evidence shows which layer caught what.
|
||||
let guardVerdict = 'admitted';
|
||||
try {
|
||||
guardAnalystStatement(attempt.sql, {
|
||||
allowedCatalog: 't_alpha_sql',
|
||||
allowedObjects: ['sales', 'events'],
|
||||
});
|
||||
} catch (e) {
|
||||
guardVerdict = `refused: ${(e as Error).message}`;
|
||||
}
|
||||
results.push({
|
||||
id: attempt.id,
|
||||
goal: attempt.goal,
|
||||
engine_http_status: res.status,
|
||||
engine_clickhouse_code: chCode ?? null,
|
||||
engine_succeeded: res.ok,
|
||||
leaked_foreign_tenant_row: leakedBeta,
|
||||
leaked_ungranted_table_row: leakedSecret,
|
||||
leaked_server_metadata: leakedMetadata,
|
||||
guard_verdict_for_reference: guardVerdict,
|
||||
engine_response_head: res.body.slice(0, 160).replace(/\s+/g, ' ').trim(),
|
||||
});
|
||||
}
|
||||
|
||||
// Legitimate work must still WORK as the restricted user, or "nothing
|
||||
// leaked" would be trivially true because nothing runs.
|
||||
const legitimate: Array<Record<string, unknown>> = [];
|
||||
for (const l of LEGITIMATE_CORPUS) {
|
||||
const res = await asAlpha(l.sql);
|
||||
legitimate.push({
|
||||
id: l.id,
|
||||
ok: res.ok,
|
||||
status: res.status,
|
||||
contains_beta_canary: res.body.includes(BETA_CANARY),
|
||||
});
|
||||
}
|
||||
|
||||
fs.mkdirSync(path.dirname(EVIDENCE_PATH), { recursive: true });
|
||||
fs.writeFileSync(
|
||||
EVIDENCE_PATH,
|
||||
`${JSON.stringify(
|
||||
{
|
||||
prompt: 'BI-P017',
|
||||
claim:
|
||||
"Every bypass attempt, executed directly against a live ClickHouse as the tenant's " +
|
||||
'restricted user WITH THE STATEMENT GUARD REMOVED, fails to return a foreign-tenant ' +
|
||||
'row, an ungranted-table row, or server metadata.',
|
||||
clickhouse_version: version,
|
||||
recorded_at: new Date().toISOString(),
|
||||
base_table_rows_both_tenants: 100,
|
||||
tenant_view_rows_alpha: 50,
|
||||
attempts_total: results.length,
|
||||
attempts_that_leaked: leaks.length,
|
||||
legitimate_statements_that_succeeded: legitimate.filter((l) => l.ok).length,
|
||||
legitimate_statements_total: legitimate.length,
|
||||
attempts: results,
|
||||
legitimate,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
)}\n`,
|
||||
);
|
||||
|
||||
expect(leaks, `LEAKS with the guard removed:\n${leaks.join('\n')}`).toEqual([]);
|
||||
expect(legitimate.every((l) => l.ok)).toBe(true);
|
||||
expect(legitimate.every((l) => l.contains_beta_canary === false)).toBe(true);
|
||||
}, 300_000);
|
||||
});
|
||||
|
||||
suite('BI-P017 live — layers 3 and 4 individually, each with the one above removed', () => {
|
||||
it('the row policies are actually APPLIED TO THE USER, not merely present', async () => {
|
||||
// The check that caught the real bug. `SHOW ROW POLICIES` listing a policy
|
||||
// with the right filter is not evidence: after a user is dropped and
|
||||
// re-created, `CREATE ROW POLICY IF NOT EXISTS` leaves the policy in place
|
||||
// with an EMPTY apply-to list, protecting nobody while looking correct.
|
||||
const res = await admin(
|
||||
rowPolicyVerificationSql({
|
||||
sourceDatabase: DB,
|
||||
tenantId: 't_alpha',
|
||||
catalog: 't_alpha_sql',
|
||||
objects: OBJECTS,
|
||||
userName: 't_alpha_sql_user',
|
||||
password: 'unused',
|
||||
}),
|
||||
);
|
||||
expect(res.ok).toBe(true);
|
||||
const rows = JSON.parse(res.body).data as Array<{ table: string; applied_to_user: number }>;
|
||||
expect(rows.length).toBe(OBJECTS.length);
|
||||
for (const row of rows) {
|
||||
expect(row.applied_to_user, `row policy on ${row.table} applies to nobody`).toBe(1);
|
||||
}
|
||||
});
|
||||
|
||||
it('layer 3 (row policy): the restricted user reading the SHARED BASE TABLE sees only its own rows', async () => {
|
||||
// The counterfactual is in the suite above: as admin this same statement
|
||||
// returns 100. Returning 100 here would be a cross-tenant read.
|
||||
const res = await asAlpha(`SELECT count() FROM ${DB}.sales`);
|
||||
if (res.ok) {
|
||||
expect(Number(res.body.trim()), 'restricted user read BOTH tenants from the base table').toBe(50);
|
||||
} else {
|
||||
expect(res.status).toBeGreaterThanOrEqual(400);
|
||||
}
|
||||
});
|
||||
|
||||
it('layer 3 (row policy): the base table yields no foreign canary even when named directly', async () => {
|
||||
const res = await asAlpha(`SELECT customer FROM ${DB}.sales LIMIT 1000`);
|
||||
expect(res.body).not.toContain(BETA_CANARY);
|
||||
});
|
||||
|
||||
it('BI-P012 ceilings are enforced by the SETTINGS PROFILE, not by the request', async () => {
|
||||
const tiny = (sql: string) => run(sql, `t_alpha_tiny_user:${TINY_PW}`);
|
||||
// Under the ceiling: succeeds.
|
||||
const ok = await tiny(`SELECT count() FROM t_alpha_sql.sales`);
|
||||
expect(ok.ok).toBe(true);
|
||||
// Over it: ClickHouse code 158, from the profile — no setting was sent.
|
||||
const over = await tiny(`SELECT count() FROM t_alpha_sql.sales a, t_alpha_sql.sales b`);
|
||||
expect(over.ok).toBe(false);
|
||||
expect(over.body).toContain('Code: 158');
|
||||
// And it cannot be raised from the request: code 164, readonly mode.
|
||||
const raise = await tiny(`SELECT count() FROM t_alpha_sql.sales`);
|
||||
expect(raise.ok).toBe(true);
|
||||
const raised = await run(
|
||||
`SELECT count() FROM t_alpha_sql.sales a, t_alpha_sql.sales b`,
|
||||
`t_alpha_tiny_user:${TINY_PW}`,
|
||||
{
|
||||
max_rows_to_read: '0',
|
||||
},
|
||||
);
|
||||
expect(raised.ok).toBe(false);
|
||||
expect(raised.body).toContain('Code: 164');
|
||||
});
|
||||
|
||||
it('layer 3: the restricted user cannot read a table it was never granted', async () => {
|
||||
const res = await asAlpha(`SELECT note FROM ${DB}.secret_ledger`);
|
||||
expect(res.ok).toBe(false);
|
||||
expect(res.body).not.toContain(SECRET_CANARY);
|
||||
});
|
||||
|
||||
it("layer 3: the restricted user cannot read the other tenant's catalog", async () => {
|
||||
const res = await asAlpha(`SELECT customer FROM t_beta_sql.sales LIMIT 5`);
|
||||
expect(res.ok).toBe(false);
|
||||
expect(res.body).not.toContain(BETA_CANARY);
|
||||
});
|
||||
|
||||
it('layer 3: readonly=1 refuses a write even though the guard never saw the statement', async () => {
|
||||
const res = await asAlpha(`INSERT INTO ${DB}.sales VALUES ('t_alpha', 'x', 1, now())`);
|
||||
expect(res.ok).toBe(false);
|
||||
const after = await admin(`SELECT count() FROM ${DB}.sales`);
|
||||
expect(Number(after.body.trim())).toBe(100);
|
||||
});
|
||||
|
||||
it('layer 3: readonly=1 refuses a statement that tries to raise its own ceiling', async () => {
|
||||
const res = await asAlpha(`SELECT count() FROM t_alpha_sql.sales SETTINGS max_rows_to_read = 0`);
|
||||
expect(res.ok).toBe(false);
|
||||
});
|
||||
|
||||
it('layer 4: the tenant column the view does not project is not selectable', async () => {
|
||||
// This is the case the GUARD ADMITS. It must fail here, or the honest
|
||||
// note in the corpus would be covering a real hole.
|
||||
const res = await asAlpha(`SELECT tenant_id FROM t_alpha_sql.sales LIMIT 1`);
|
||||
expect(res.ok).toBe(false);
|
||||
});
|
||||
|
||||
it('layer 4: a WHERE on the hidden tenant column cannot widen the view', async () => {
|
||||
const res = await asAlpha(`SELECT count() FROM t_alpha_sql.sales WHERE tenant_id = 't_beta'`);
|
||||
expect(res.ok).toBe(false);
|
||||
});
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user