@ultimat3/testing 29.4.0 → 30.1.0

package/src/template-db.ts

@@ -5,6 +5,7 @@
 
 import { renderThrowable } from '@ultimat3/core';
 import { TestDatabaseUnavailableError } from './errors';
+import { prepareRowSecurity, rowSecurityUrls } from './template-db-roles';
 
 export type DbKind = 'postgres' | 'pglite';
 
@@ -20,6 +21,8 @@ export interface TemplateDbConfig {
   readonly templateName?: string;
   /** Applied into the template under an advisory lock, which every worker's clone also holds. */
   readonly migrate?: (url: string) => Promise<void>;
+  /** `database.rowSecurity`: migrate as `x_migrator`, hand the worker a URL that serves as `x_app`. */
+  readonly rowSecurity?: boolean | undefined;
 }
 
 export interface WorkerDatabase {
@@ -150,7 +153,10 @@ export async function acquireWorkerDatabase(
       // server that is not a fresh CI container. Migrations are idempotent and the advisory lock
       // serialises them, so a failure here is a real failure and `alreadyExists` (a substring match
       // on the message) would read `relation "x_jobs" already exists` as success.
-      if (config.migrate !== undefined) await config.migrate(urlFor(adminUrl, template));
+      const roles = config.rowSecurity === true;
+      if (roles) await prepareRowSecurity(connect, urlFor(adminUrl, template));
+      const migrateUrl = rowSecurityUrls(roles, urlFor(adminUrl, template)).migrate;
+      if (config.migrate !== undefined) await config.migrate(migrateUrl);
       // INSIDE the lock: `CREATE DATABASE … TEMPLATE` waits 5 s for every session on the template
       // to leave, then refuses — and the next worker's migration opens one the moment the lock is
       // free. Measured: a clone outside it failed whenever that migration ran past 5 s.
@@ -171,7 +177,7 @@ export async function acquireWorkerDatabase(
     kind: 'postgres',
     worker,
     database,
-    url: urlFor(adminUrl, database),
+    url: rowSecurityUrls(config.rowSecurity === true, urlFor(adminUrl, database)).serve,
     drop: async () => {
       const cleanup = connect(adminUrl);
       await cleanup.exec(dropSql(database));

package/src/tenant-canary.ts

@@ -0,0 +1,120 @@
+// The read half of the tenant proof: what of tenant A a call by B must never hand back — every A
+// row's canary and every A row's id, off the pass's one seed graph — and the walk that finds one in
+// an output or an effect, by path. Taint, not heuristics: only values the seed itself wrote count.
+
+import type { SeedGraph, SeedRow } from './seed-graph-plan';
+
+/**
+ * An id shorter than this is no taint: a serial `1` matches every count in every output. A seeded
+ * uuid is 36; a short key is still caught through its row's canary.
+ */
+export const MIN_TAINT_ID_LENGTH = 8;
+
+/** One tenant instance's taint: its rows, for the write half, and its markers, for the read half. */
+export interface TenantTaint {
+  readonly tenant: string;
+  /** Every row the seed wrote for the instance, a child with no tenant column included. */
+  readonly rows: readonly SeedRow[];
+  /** Per row, its primary key as printed: the parts in key order, joined by `,`. */
+  readonly ids: readonly string[];
+  /** Lower-case: each row's canary, and each key part no row of anyone else shares. */
+  readonly marks: readonly string[];
+}
+
+const keyParts = (key: Readonly<Record<string, unknown>>): readonly string[] =>
+  Object.values(key).flatMap((part) =>
+    typeof part === 'string' && part.length >= MIN_TAINT_ID_LENGTH ? [part.toLowerCase()] : [],
+  );
+
+/**
+ * The taint of `tenant`: canaries of its rows that carry one in some column, and its key parts —
+ * minus any key part a row outside the instance also has (a composite key naming a shared `plans`
+ * row is no proof of whose row came back).
+ */
+export function tenantTaint(graph: SeedGraph, tenant: string): TenantTaint {
+  // `canaries[i]` is `inserts[i]`'s: the graph writes the two together.
+  const mine = graph.inserts.flatMap((row, i) => {
+    const canary = graph.canaries[i];
+    return row.tenant === tenant && canary?.entity === row.entity ? [{ row, canary }] : [];
+  });
+  const rows = mine.map((one) => one.row);
+  const ids = mine.map((one) => Object.values(one.canary.key).map(String).join(','));
+  const ours = mine.map((one) => one.canary);
+  const elsewhere = new Set(
+    graph.canaries.filter((canary) => canary.tenant !== tenant).flatMap((c) => keyParts(c.key)),
+  );
+  const marks = new Set<string>();
+  for (const canary of ours) {
+    if (canary.columns.length > 0) marks.add(canary.marker.toLowerCase());
+    for (const part of keyParts(canary.key)) if (!elsewhere.has(part)) marks.add(part);
+  }
+  return { tenant, rows, ids, marks: [...marks] };
+}
+
+/** Every string a value holds, at any depth: what a caller HANDED in, so never a find. */
+const stringsOf = (value: unknown, into: string[] = [], seen = new WeakSet<object>()): string[] => {
+  if (typeof value === 'string') into.push(value.toLowerCase());
+  else if (typeof value === 'object' && value !== null && !seen.has(value)) {
+    seen.add(value);
+    const entries = value instanceof Map ? [...value] : Object.entries(value);
+    for (const [key, item] of entries) {
+      stringsOf(key, into, seen);
+      stringsOf(item, into, seen);
+    }
+    if (value instanceof Set) for (const item of value) stringsOf(item, into, seen);
+  }
+  return into;
+};
+
+/**
+ * The marks a call by B can be caught by: the taint, minus every mark B's own input carried.
+ * B was handed A's ids on purpose, so an echo of one (`{ id: input.postId, ok: false }`) proves
+ * nothing; an id B was NOT handed, or any canary, proves the handler read A's row.
+ */
+export function huntedMarks(taint: TenantTaint, input: unknown): readonly string[] {
+  const handed = stringsOf(input);
+  return taint.marks.filter((mark) => !handed.some((text) => text.includes(mark)));
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** A key that is no identifier is data — an id, an address — so the path says `[*]`, never it. */
+const step = (path: string, key: string): string =>
+  IDENTIFIER.test(key) ? `${path}.${key}` : `${path}[*]`;
+
+/**
+ * Every path under `root` where a string holds a hunted mark — `output.items[0].url`. Object
+ * keys are searched too (a record keyed by A's ids is a leak, `output[*]:key`); a path never holds
+ * the value found, and the walk stops at a value seen twice.
+ */
+export function findTaint(value: unknown, root: string, marks: readonly string[]): string[] {
+  const found: string[] = [];
+  if (marks.length === 0) return found;
+  const tainted = (text: string): boolean => {
+    const lower = text.toLowerCase();
+    return marks.some((mark) => lower.includes(mark));
+  };
+  const seen = new WeakSet<object>();
+  const walk = (item: unknown, path: string): void => {
+    if (typeof item === 'string') {
+      if (tainted(item)) found.push(path);
+      return;
+    }
+    if (typeof item !== 'object' || item === null || seen.has(item)) return;
+    if (item instanceof Date || ArrayBuffer.isView(item)) return;
+    seen.add(item);
+    if (Array.isArray(item) || item instanceof Set) {
+      for (const [i, one] of [...item].entries()) walk(one, `${path}[${i}]`);
+      return;
+    }
+    const entries: [unknown, unknown][] =
+      item instanceof Map ? [...item] : Object.entries(item as Record<string, unknown>);
+    for (const [key, one] of entries) {
+      const name = String(key);
+      const here = step(path, name);
+      if (tainted(name)) found.push(`${here}:key`);
+      walk(one, here);
+    }
+  };
+  walk(value, root);
+  return found;
+}

package/src/tenant-proof-report.ts

@@ -0,0 +1,62 @@
+// The tenant proof, as `x exercise` reports it: one line per finding — primitive, leg, and the path
+// of A's canary in B's answer or the table and id of A's changed row — and one coded finding each
+// for the gate to fail on. Only paths, tables and seeded ids are printed: never a bound value.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import type { ExerciseRecord, TenantFinding } from './exercise-report';
+
+/** One coded finding, the shape `x exercise` hands the gate. */
+export interface TenantProofFinding {
+  readonly code: TenantFinding['code'];
+  readonly cause: string;
+  readonly fix: string;
+  /** The primitive, by kind and name: the registry records no declaring file. */
+  readonly at: string;
+}
+
+const LEG = { before: 'before A ran', after: 'after A ran' } as const;
+
+/** `B with A's ids, before A ran: output.items[0].url` — where, never what. */
+const where = (finding: TenantFinding): string =>
+  finding.code === 'X_TENANT_LEAK'
+    ? `${finding.path ?? 'output'}`
+    : `${finding.table ?? '?'} row ${finding.id ?? '?'}`;
+
+/** Every finding of every crossed record, one line each: `action readPost · before · output.url`. */
+export function tenantFindingLines(records: readonly ExerciseRecord[]): readonly string[] {
+  return records.flatMap((record) =>
+    record.tenant?.verdict === 'crossed'
+      ? record.tenant.findings.map(
+          (finding) =>
+            `${record.kind} ${record.name} · ${finding.leg} · ${finding.code} ${where(finding)}`,
+        )
+      : [],
+  );
+}
+
+const causeOf = (record: ExerciseRecord, finding: TenantFinding): string =>
+  finding.code === 'X_TENANT_LEAK'
+    ? `${record.kind} ${record.name}, called by tenant B with tenant A's ids ${LEG[finding.leg]}, handed back A's seeded data at ${where(finding)}: a read reached A's row by an id the caller chose, past the tenant guard`
+    : `${record.kind} ${record.name}, called by tenant B with tenant A's ids ${LEG[finding.leg]}, changed A's ${where(finding)}: a write reached A's row by an id the caller chose, past the tenant guard`;
+
+/**
+ * One coded finding per tenant finding. The fix reruns the one primitive: what it reads or writes
+ * by input id goes through the repository scoped to `ctx.actor` (or `crossTenant()` with a public
+ * policy, when it truly spans tenants) — which read, only the handler shows.
+ */
+export function tenantProofFindings(
+  records: readonly ExerciseRecord[],
+): readonly TenantProofFinding[] {
+  return records.flatMap((record) => {
+    if (record.tenant?.verdict !== 'crossed') return [];
+    const name = renderFixShellArg(record.name, '<primitive>');
+    return record.tenant.findings.map(
+      (finding): TenantProofFinding => ({
+        code: finding.code,
+        cause: causeOf(record, finding),
+        fix: `x exercise ${name} --json — then read ${finding.code === 'X_TENANT_LEAK' ? 'the row behind ' : ''}${where(finding)} through the repository scoped to ctx.actor, never by the input id alone`,
+        at: `${record.kind} ${record.name}`,
+      }),
+    );
+  });
+}

package/src/tenant-proof.ts

@@ -0,0 +1,177 @@
+// The tenant proof, one primitive at a time: tenant B calls with A's ids before A's own call and
+// again after it, and the call is crossed if anything of A's — a canary, an id B was not handed —
+// came back in the output or an effect, or if one of A's rows changed. Order B, A, B: a deleting
+// action would leave B nothing to reach, and the second B catches a cache entry A filled.
+
+import type { Actor } from '@ultimat3/core';
+import type { Policy } from '@ultimat3/policy';
+import { policyMatrix } from '@ultimat3/policy';
+import type {
+  EffectPayload,
+  ExerciseRecord,
+  TenantFinding,
+  TenantLeg,
+  TenantProof,
+} from './exercise-report';
+import type { SeedRow } from './seed-graph-plan';
+import type { TenantTaint } from './tenant-canary';
+import { findTaint, huntedMarks } from './tenant-canary';
+
+export type { TenantFinding, TenantLeg, TenantProof } from './exercise-report';
+
+/**
+ * `@ultimat3/entity`'s `CROSS_TENANT_SCOPE`, restated: this module stays off entity at run time.
+ * `tenant-proof-legs.test.ts` holds the two equal, so a rename there fails here.
+ */
+export const CROSS_TENANT_SCOPE = 'tenancy:cross';
+
+/**
+ * B's actor: the role that grants the policy's permission, never the capability that lifts the
+ * tenant guard. An A actor holding `tenancy:cross` legitimately reads across; B attacking with it
+ * would prove only that the escape works.
+ */
+export const withoutCrossTenant = (actor: Actor | null): Actor | null =>
+  actor === null || !actor.scopes.includes(CROSS_TENANT_SCOPE)
+    ? actor
+    : Object.freeze({ ...actor, scopes: actor.scopes.filter((s) => s !== CROSS_TENANT_SCOPE) });
+
+/**
+ * Why the read half is skipped, or `undefined`: a policy that admits an anonymous caller with an
+ * empty input is public by its own declaration — what it returns, anyone may read. A job has no
+ * policy and a predicate the empty input cannot answer is not an admission: both are proven.
+ */
+export function publicReason(policy: Policy | undefined): string | undefined {
+  if (policy === undefined) return undefined;
+  try {
+    const row = policyMatrix(policy, { actors: [{ name: 'anonymous', actor: null }], input: {} })
+      .rows[0];
+    return row?.allowed === true
+      ? `${policy.label} admits an anonymous caller, so what it returns is public: read half skipped, write half kept`
+      : undefined;
+  } catch {
+    // A predicate that reads the input throws on the empty one: undecided, so not public.
+    return undefined;
+  }
+}
+
+/** What one B call answered and what the room saw it do. */
+export interface LegAnswer {
+  readonly output: unknown;
+  readonly payloads: readonly EffectPayload[];
+  /** Every `crossTenant()` reason the leg opened, as `@ultimat3/entity` witnessed it. */
+  readonly crossings?: readonly string[] | undefined;
+}
+
+export interface TenantAttack {
+  readonly taint: TenantTaint;
+  /** B's input: A's own first input, A's ids bound — both legs send exactly this. */
+  readonly input: unknown;
+  /** From `publicReason`: set, the read half is skipped and the verdict at best `public`. */
+  readonly public: string | undefined;
+  /**
+   * A read (a query): A's own answer must hold one of A's rows, or B's empty answer proves
+   * nothing — a cache shared across tenants that B filled first hands A the same nothing.
+   */
+  readonly read: boolean;
+  /**
+   * A job: its answer goes to no caller, so a leg that opened `crossTenant()` and was handed none
+   * of A's marks is a declared sweep — `sendDigest` fanning out one delivery per org — and its read
+   * half is skipped. An action or a query answers B directly, so a declared scope excuses nothing.
+   */
+  readonly sweep: boolean;
+  attack(leg: TenantLeg): Promise<LegAnswer>;
+  /** A's positive control: today's exercise of the primitive, and what A's last answer was. */
+  control(): Promise<{ readonly record: ExerciseRecord; readonly output: unknown }>;
+  snapshot(rows: readonly SeedRow[]): Promise<readonly (string | null)[]>;
+}
+
+/** A's rows whose digest moved across one B leg — changed, or gone. */
+export function crossedWrites(
+  leg: TenantLeg,
+  taint: Pick<TenantTaint, 'rows' | 'ids'>,
+  before: readonly (string | null)[],
+  after: readonly (string | null)[],
+): readonly TenantFinding[] {
+  return taint.rows.flatMap((row, i): TenantFinding[] =>
+    before[i] === after[i]
+      ? []
+      : [{ code: 'X_TENANT_WRITE_CROSSED', leg, table: row.table, id: taint.ids[i] ?? '' }],
+  );
+}
+
+/** Every path in B's answer holding a mark of A's that B was not handed. */
+export function leaksIn(
+  leg: TenantLeg,
+  answer: LegAnswer,
+  marks: readonly string[],
+): readonly TenantFinding[] {
+  const paths = [
+    ...findTaint(answer.output, 'output', marks),
+    ...answer.payloads.flatMap((payload) => findTaint(payload.value, payload.path, marks)),
+  ];
+  return paths.map((path): TenantFinding => ({ code: 'X_TENANT_LEAK', leg, path }));
+}
+
+/**
+ * The reason a leg's read half is skipped as a declared sweep, or `undefined`: a job, a scope the
+ * leg opened, and an input carrying nothing of A's — so no id B chose pointed at A, and what came
+ * back is what the sweep hands every caller. Handed one of A's ids, the scope is `tpCrossRead`'s.
+ */
+export function sweepReason(
+  plan: Pick<TenantAttack, 'sweep' | 'taint'>,
+  answer: LegAnswer,
+  hunted: readonly string[],
+): string | undefined {
+  const reason = answer.crossings?.[0];
+  if (!plan.sweep || reason === undefined || hunted.length !== plan.taint.marks.length) {
+    return undefined;
+  }
+  return `crossTenant(${JSON.stringify(reason)}) declares this job reads across tenants, and B's input named nothing of A's: read half skipped, write half kept`;
+}
+
+const verdictOf = (
+  plan: TenantAttack,
+  control: { readonly record: ExerciseRecord; readonly output: unknown },
+  findings: readonly TenantFinding[],
+  swept: string | undefined,
+): TenantProof => {
+  const { record } = control;
+  if (findings.length > 0) return { verdict: 'crossed', findings };
+  if (record.outcome !== 'reached') {
+    return {
+      verdict: 'unproven',
+      reason: `A's own call was not reached (${record.code ?? record.outcome}), so B's clean answers prove nothing`,
+    };
+  }
+  if (plan.public !== undefined) return { verdict: 'public', reason: plan.public };
+  if (swept !== undefined) return { verdict: 'public', reason: swept };
+  // Every mark of A's, handed ones included: A was handed its own ids, and reading them is the point.
+  if (plan.read && findTaint(control.output, 'output', plan.taint.marks).length === 0) {
+    return {
+      verdict: 'unproven',
+      reason: "A's control returned none of A's rows, so B's answers had nothing to leak",
+    };
+  }
+  return { verdict: 'proven' };
+};
+
+/** B, A, B — each B leg between two snapshots of A's rows — and A's record with the verdict on it. */
+export async function proveTenant(plan: TenantAttack): Promise<ExerciseRecord> {
+  const marks = huntedMarks(plan.taint, plan.input);
+  const findings: TenantFinding[] = [];
+  let swept: string | undefined;
+  const leg = async (name: TenantLeg): Promise<void> => {
+    const before = await plan.snapshot(plan.taint.rows);
+    const answer = await plan.attack(name);
+    const after = await plan.snapshot(plan.taint.rows);
+    findings.push(...crossedWrites(name, plan.taint, before, after));
+    if (plan.public !== undefined) return;
+    const sweep = sweepReason(plan, answer, marks);
+    if (sweep === undefined) findings.push(...leaksIn(name, answer, marks));
+    else swept = sweep;
+  };
+  await leg('before');
+  const control = await plan.control();
+  await leg('after');
+  return { ...control.record, tenant: verdictOf(plan, control, findings, swept) };
+}

package/src/test-types.ts

@@ -3,6 +3,7 @@
 // failure line say which of the six steps it belongs to. See packages/cli/src/verify-tests.ts.
 
 import { test } from 'bun:test';
+import type { A11yOptions } from './e2e-a11y-run';
 import { TestEvalThresholdError } from './errors';
 import type { FixtureBody } from './fixtures';
 import { runWithFixtures } from './fixtures';
@@ -116,8 +117,16 @@ export interface E2eFixtures {
 
 export type E2eBody = (fixtures: E2eFixtures) => Promise<void>;
 
-/** What registers one e2e test with a browser behind it. `options` is the test's own (`timeoutMs`). */
-export type E2eDriver = (name: string, body: E2eBody, options?: TestOptions) => void;
+/**
+ * An e2e test's own options. `a11y` is not a switch: every `e2eTest` audits the browser's
+ * accessibility tree, and the only exception is a reasoned `allow` entry for one element.
+ */
+export interface E2eTestOptions extends TestOptions {
+  readonly a11y?: A11yOptions | undefined;
+}
+
+/** What registers one e2e test with a browser behind it. `options` is the test's own. */
+export type E2eDriver = (name: string, body: E2eBody, options?: E2eTestOptions) => void;
 
 let e2eDriver: E2eDriver | undefined;
 
@@ -152,7 +161,7 @@ export const resetE2eDriver = (): void => {
   e2eDriver = undefined;
 };
 
-export const e2eTest = (name: string, body: E2eBody, options?: TestOptions): void => {
+export const e2eTest = (name: string, body: E2eBody, options?: E2eTestOptions): void => {
   if (e2eDriver === undefined) {
     test.skip(
       testName('e2e', `${name} (no browser driver: x build --target static && x e2e)`),