/** * 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) : ({} as Record); 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 }; 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([]); }); });