@proteinjs/db-driver-spanner 1.23.5 → 1.24.0

package/test/EncryptedSearch.test.ts

@@ -0,0 +1,247 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  EncryptedColumns,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncSearchDoc, EncSearchDocTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER_A = 'enc-search-owner-a';
+const OWNER_B = 'enc-search-owner-b';
+
+let accessibleOwners: string[] = [OWNER_A];
+
+const docTable = new EncSearchDocTable() as Table<EncSearchDoc>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+
+const titleLike = (pattern: string) =>
+  new QueryBuilder<EncSearchDoc>(docTable.name).condition({ field: 'title', operator: 'LIKE', value: pattern });
+
+const titlesOf = (rows: EncSearchDoc[]) => rows.map((row) => row.title).sort();
+
+/**
+ * Search exactness over encrypted columns — the recheck contract: the token index answers a
+ * candidate set, each candidate is verified against the decrypted value, so NO false
+ * positive surfaces and NO true match is missed (query words >= 3 chars); 1-2 character
+ * query words behave as word-prefix search (the documented narrowing).
+ */
+describe('Encrypted search: exact contains/prefix, equality, shared-scope OR', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+  const seeded: string[] = [];
+
+  const seed = async (scope: string, title: string | null, name?: string | null, kind?: string) => {
+    const row = await db.insert(docTable, { scope, title, name: name ?? null, kind: kind ?? 'doc' });
+    seeded.push(row.id);
+    return row;
+  };
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => accessibleOwners,
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [docTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [docTable]);
+
+    // The corpus: owner A's documents...
+    await seed(OWNER_A, 'Groceries list');
+    await seed(OWNER_A, 'Grocery budget planning');
+    await seed(OWNER_A, 'Pancake factory notes');
+    await seed(OWNER_A, 'cake factory shift plan');
+    await seed(OWNER_A, 'Therapy notes — divorce');
+    await seed(OWNER_A, 'n3xa notes');
+    await seed(OWNER_A, null, 'tag-null-title');
+    await seed(OWNER_A, 'Once and future factories');
+    // holds every fragment of "cake factory" NON-contiguously — a token-cover candidate the
+    // verify step must reject
+    await seed(OWNER_A, 'factory made cake platter');
+    // ...and owner B's (a sharer), including an overlapping word
+    await seed(OWNER_B, 'Groceries for the trip');
+    await seed(OWNER_B, 'B-only cake recipe');
+  }, 120000);
+
+  afterAll(async () => {
+    for (const id of seeded) {
+      await db.delete(docTable, { id }).catch(() => undefined);
+    }
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(new EncryptedColumns().tokenTableFor(docTable)!);
+    await dropTable(docTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  beforeEach(() => {
+    accessibleOwners = [OWNER_A];
+  });
+
+  test('contains search is exact: every true match returned, nothing else (the home-search shape)', async () => {
+    const rows = await db.query(docTable, titleLike('%Groceries%'));
+    expect(titlesOf(rows)).toEqual(['Groceries list']);
+
+    // multi-word contains, matching across a word prefix ("cake factory" inside "Pancake
+    // factory") — and NOT matching 'factory made cake platter', whose token cover holds
+    // every fragment non-contiguously (the verify step rejects it)
+    const factoryRows = await db.query(docTable, titleLike('%cake factory%'));
+    expect(titlesOf(factoryRows)).toEqual(['Pancake factory notes', 'cake factory shift plan']);
+  });
+
+  test('no false positives: rows holding all fragments non-contiguously are rejected by the verify step', async () => {
+    // "Once and future factories" holds trigrams of 'fact'/'tor' etc. — but not the
+    // contiguous phrase "factory shift"
+    const rows = await db.query(docTable, titleLike('%factory shift%'));
+    expect(titlesOf(rows)).toEqual(['cake factory shift plan']);
+  });
+
+  test('case-insensitive LIKE (caseSensitive=false) matches across case', async () => {
+    const qb = new QueryBuilder<EncSearchDoc>(docTable.name);
+    qb.condition({ field: 'title', operator: 'LIKE', value: '%GROCERIES%' }, undefined, false);
+    const rows = await db.query(docTable, qb);
+    expect(titlesOf(rows)).toEqual(['Groceries list']);
+
+    // and the default case-sensitive LIKE stays exact about case
+    const strict = await db.query(docTable, titleLike('%GROCERIES%'));
+    expect(strict.length).toBe(0);
+  });
+
+  test('prefix search (q%) matches value starts only', async () => {
+    const rows = await db.query(docTable, titleLike('Groc%'));
+    expect(titlesOf(rows)).toEqual(['Groceries list', 'Grocery budget planning']);
+  });
+
+  test('1-2 character queries behave as word-prefix search (the documented narrowing)', async () => {
+    // 'n' finds "n3xa notes" (word start), and also "notes" words — anything with an n-starting word
+    const rows = await db.query(docTable, titleLike('%n%'));
+    for (const row of rows) {
+      expect(
+        (row.title ?? '')
+          .toLowerCase()
+          .split(/[^a-z0-9]+/)
+          .some((word) => word.startsWith('n'))
+      ).toBe(true);
+    }
+    expect(titlesOf(rows)).toContain('n3xa notes');
+
+    // a 1-2 char MID-WORD substring is documented unsupported: 'x' inside 'n3xa' does not match
+    const midWord = await db.query(docTable, titleLike('%x%'));
+    expect(titlesOf(midWord)).toEqual([]);
+  });
+
+  test('composition: encrypted search ANDs with metadata conditions natively', async () => {
+    const rows = await db.query(
+      docTable,
+      titleLike('%Groceries%').condition({ field: 'kind', operator: '=', value: 'doc' })
+    );
+    expect(titlesOf(rows)).toEqual(['Groceries list']);
+
+    const noRows = await db.query(
+      docTable,
+      titleLike('%Groceries%').condition({ field: 'kind', operator: '=', value: 'other' })
+    );
+    expect(noRows.length).toBe(0);
+  });
+
+  test('getRowCount over an encrypted search is exact', async () => {
+    expect(await db.getRowCount(docTable, titleLike('%cake factory%'))).toBe(2);
+  });
+
+  test('equality lookup rides the whole-value fingerprint: exact, case-exact (the tag get-or-create shape)', async () => {
+    await seed(OWNER_A, 'eq holder', 'Divorce');
+    await seed(OWNER_A, 'eq holder 2', 'divorce');
+
+    const exact = await db.get(docTable, { name: 'Divorce' });
+    expect(exact.title).toBe('eq holder');
+
+    const lower = await db.query(docTable, { name: 'divorce' } as any);
+    expect(lower.length).toBe(1);
+    expect(lower[0].title).toBe('eq holder 2');
+
+    const missing = await db.get(docTable, { name: 'no-such-tag' });
+    expect(missing).toBeFalsy();
+  });
+
+  test('shared-scope search: fingerprints once per accessible owner, ORs the matches', async () => {
+    // Only own scope accessible: A sees only A's groceries
+    const own = await db.query(docTable, titleLike('%Groceries%'));
+    expect(titlesOf(own)).toEqual(['Groceries list']);
+
+    // B shares with A: the same caller query now covers both owners' keys
+    accessibleOwners = [OWNER_A, OWNER_B];
+    const shared = await db.query(docTable, titleLike('%Groceries%'));
+    expect(titlesOf(shared)).toEqual(['Groceries for the trip', 'Groceries list']);
+  });
+
+  test('token rows follow the row lifecycle: update rewrites them, delete removes them', async () => {
+    const row = await db.insert(docTable, {
+      scope: OWNER_A,
+      title: 'ephemeral zebra thoughts',
+      name: null,
+      kind: 'doc',
+    });
+
+    expect(titlesOf(await db.query(docTable, titleLike('%zebra%')))).toEqual(['ephemeral zebra thoughts']);
+
+    await db.update(docTable, { id: row.id, title: 'renamed giraffe thoughts' });
+    expect((await db.query(docTable, titleLike('%zebra%'))).length).toBe(0);
+    expect(titlesOf(await db.query(docTable, titleLike('%giraffe%')))).toEqual(['renamed giraffe thoughts']);
+
+    await db.delete(docTable, { id: row.id });
+    expect((await db.query(docTable, titleLike('%giraffe%'))).length).toBe(0);
+
+    // and the token table holds no orphans for the deleted row
+    const tokenTable = new EncryptedColumns().tokenTableFor(docTable)!;
+    const orphans = await spannerDriver.runQuery(() => ({
+      sql: `SELECT COUNT(*) as tokenCount FROM \`${tokenTable.name}\` WHERE \`record_id\` = '${row.id}'`,
+    }));
+    expect(Number((orphans[0] as any).tokenCount)).toBe(0);
+  });
+
+  test('delete by encrypted search: WHERE title LIKE deletes exactly the true matches', async () => {
+    const kept = await db.insert(docTable, { scope: OWNER_A, title: 'wombat keep', name: null, kind: 'doc' });
+    const doomed = await db.insert(docTable, { scope: OWNER_A, title: 'wombat purge now', name: null, kind: 'doc' });
+
+    const deleteCount = await db.delete(docTable, titleLike('%purge now%'));
+    expect(deleteCount).toBe(1);
+    expect((await db.get(docTable, { id: kept.id })).title).toBe('wombat keep');
+    expect(await db.get(docTable, { id: doomed.id })).toBeFalsy();
+
+    await db.delete(docTable, { id: kept.id });
+  });
+
+  test('update by encrypted search: WHERE title LIKE updates exactly the true matches', async () => {
+    const target = await db.insert(docTable, { scope: OWNER_A, title: 'quokka target row', name: null, kind: 'doc' });
+    const bystander = await db.insert(docTable, { scope: OWNER_A, title: 'quokka bystander', name: null, kind: 'doc' });
+
+    const updateCount = await db.update(docTable, { kind: 'flagged' }, titleLike('%target row%'));
+    expect(updateCount).toBe(1);
+    expect((await db.get(docTable, { id: target.id })).kind).toBe('flagged');
+    expect((await db.get(docTable, { id: bystander.id })).kind).toBe('doc');
+
+    await db.delete(docTable, { id: target.id });
+    await db.delete(docTable, { id: bystander.id });
+  });
+});

package/test/EncryptionLifecycleWalker.test.ts

@@ -0,0 +1,223 @@
+import {
+  Db,
+  Record,
+  StringColumn,
+  Table,
+  withRecordColumns,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  DataKeyStore,
+  EncryptedColumns,
+  EncryptionEnvelope,
+  EncryptionLifecycleWalker,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncWalkRow, EncWalkRowTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER = 'enc-walk-owner-a';
+
+const walkTable = new EncWalkRowTable() as Table<EncWalkRow>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+const systemDb = new Db(spannerDriver, undefined, new TransactionContext(), true);
+const envelope = new EncryptionEnvelope();
+const walker = new EncryptionLifecycleWalker();
+
+/**
+ * The decrypt-out view of the walk table: the SAME physical table with the columns declared
+ * plaintext — how the schema looks after a deliberate reclassification flips the config.
+ * Deliberately NOT a registered loadable (the registry holds the encrypted declaration;
+ * name-based lookups only resolve column names/types, identical between the two).
+ */
+class EncWalkRowDecryptedView extends Table<EncWalkRow> {
+  name = 'db_test_enc_walk_row';
+  columns: Table<EncWalkRow>['columns'] = withRecordColumns<EncWalkRow>({
+    scope: new StringColumn('scope', {}, 36),
+    title: new StringColumn('title', { encrypted: false }, 'MAX'),
+    body: new StringColumn('body', { encrypted: false }, 'MAX'),
+  });
+}
+
+const rawRows = async (): Promise<any[]> =>
+  await spannerDriver.runQuery(() => ({
+    sql: `SELECT \`id\`, \`title\`, \`body\` FROM \`${walkTable.name}\` ORDER BY \`id\``,
+  }));
+
+const seedPlaintextRow = async (id: string, title: string, body: string) => {
+  await spannerDriver.runDml(() => ({
+    sql:
+      `INSERT INTO \`${walkTable.name}\` (\`id\`, \`created\`, \`updated\`, \`scope\`, \`title\`, \`body\`) ` +
+      `VALUES ('${id}', CURRENT_TIMESTAMP(), CURRENT_TIMESTAMP(), '${OWNER}', '${title}', '${body}')`,
+  }));
+};
+
+const titleLike = (pattern: string) =>
+  new QueryBuilder<EncWalkRow>(walkTable.name).condition({ field: 'title', operator: 'LIKE', value: pattern });
+
+/**
+ * The one reusable ONLINE backfill behind every config transition (encrypt-in-place
+ * adoption, add-searchable tokenization, decrypt-out, key rotation) — idempotent,
+ * resumable, migration-runner-shaped.
+ */
+describe('Encryption lifecycle walker', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => [OWNER],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [walkTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [walkTable]);
+  }, 120000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(new EncryptedColumns().tokenTableFor(walkTable)!);
+    await dropTable(walkTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  afterEach(async () => {
+    await spannerDriver.runDml(() => ({ sql: `DELETE FROM \`${walkTable.name}\` WHERE TRUE` }));
+    const tokenTable = new EncryptedColumns().tokenTableFor(walkTable)!;
+    await spannerDriver.runDml(() => ({ sql: `DELETE FROM \`${tokenTable.name}\` WHERE TRUE` }));
+  });
+
+  test('encrypt-in-place adoption: plaintext rows become envelopes, search works, live rows are skipped (idempotence)', async () => {
+    // the pre-encryption estate
+    await seedPlaintextRow('walk-adopt-1', 'meeting notes alpha', 'body one');
+    await seedPlaintextRow('walk-adopt-2', 'meeting notes beta', 'body two');
+    await seedPlaintextRow('walk-adopt-3', 'unrelated title', 'body three');
+    // a row already written through the live seam (already encrypted)
+    const liveRow = await db.insert(walkTable, { scope: OWNER, title: 'live row gamma', body: 'live body' });
+
+    const summary = await walker.walkTable(walkTable, 'encrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      windowSize: 2, // exercise multi-window cursor paging
+    });
+    expect(summary.scanned).toBe(4);
+    expect(summary.rewritten).toBe(3); // the three plaintext rows; the live row skipped
+
+    // all rows now ciphertext at rest
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(true);
+      expect(envelope.isEnvelope(raw.body)).toBe(true);
+    }
+
+    // the adopted rows are searchable (tokens were written by the rewrite)
+    const found = await db.query(walkTable, titleLike('%meeting notes%'));
+    expect(found.map((row) => row.title).sort()).toEqual(['meeting notes alpha', 'meeting notes beta']);
+
+    // and values still read back exactly
+    expect((await db.get(walkTable, { id: 'walk-adopt-1' })).body).toBe('body one');
+
+    // IDEMPOTENCE: a re-run rewrites nothing
+    const rerun = await walker.walkTable(walkTable, 'encrypt', { dbDriver: spannerDriver, db: systemDb });
+    expect(rerun.scanned).toBe(4);
+    expect(rerun.rewritten).toBe(0);
+
+    void liveRow;
+  });
+
+  test('resumability: a walk resumed from a cursor completes the remainder; done rows stay done', async () => {
+    await seedPlaintextRow('walk-resume-1', 'resume one', 'b');
+    await seedPlaintextRow('walk-resume-2', 'resume two', 'b');
+    await seedPlaintextRow('walk-resume-3', 'resume three', 'b');
+
+    // "crash" after the first row: simulate by walking only rows after a cursor — then
+    // verify a fresh full run converges the rest without redoing done work
+    const partial = await walker.walkTable(walkTable, 'encrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      startAfterId: 'walk-resume-1',
+    });
+    expect(partial.rewritten).toBe(2);
+
+    const finish = await walker.walkTable(walkTable, 'encrypt', { dbDriver: spannerDriver, db: systemDb });
+    expect(finish.rewritten).toBe(1); // only the row the partial walk never reached
+
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(true);
+    }
+  });
+
+  test('decrypt-out reclassification: envelopes become plaintext, token rows are swept', async () => {
+    await db.insert(walkTable, { scope: OWNER, title: 'soon public alpha', body: 'body a' });
+    await db.insert(walkTable, { scope: OWNER, title: 'soon public beta', body: 'body b' });
+
+    const decryptedView = new EncWalkRowDecryptedView() as Table<EncWalkRow>;
+    const summary = await walker.walkTable(decryptedView, 'decrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      columns: ['title', 'body'],
+    });
+    expect(summary.rewritten).toBe(2);
+
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(false);
+      expect(raw.title).toContain('soon public');
+    }
+
+    const tokenTable = new EncryptedColumns().tokenTableFor(walkTable)!;
+    const tokenCount = await spannerDriver.runQuery(() => ({
+      sql: `SELECT COUNT(*) as tokenCount FROM \`${tokenTable.name}\``,
+    }));
+    expect(Number((tokenCount[0] as any).tokenCount)).toBe(0);
+  });
+
+  test('key rotation: rotate mints a new version, the walk rewrites envelopes to it, search stays exact, old version retires', async () => {
+    const row1 = await db.insert(walkTable, { scope: OWNER, title: 'rotation subject one', body: 'rb1' });
+    const row2 = await db.insert(walkTable, { scope: OWNER, title: 'rotation subject two', body: 'rb2' });
+
+    const store = new DataKeyStore();
+    const versionBefore = envelope.parse((await rawRows())[0].title)!.version;
+    const newVersion = await store.rotateKey(OWNER);
+    expect(newVersion).toBe(versionBefore + 1);
+
+    // during the rotation window (before the walk), reads and search still work
+    expect((await db.get(walkTable, { id: row1.id })).title).toBe('rotation subject one');
+    expect((await db.query(walkTable, titleLike('%rotation subject%'))).length).toBe(2);
+
+    const summary = await walker.walkTable(walkTable, 'rotate-keys', { dbDriver: spannerDriver, db: systemDb });
+    expect(summary.rewritten).toBe(2);
+
+    for (const raw of await rawRows()) {
+      expect(envelope.parse(raw.title)!.version).toBe(newVersion);
+      expect(envelope.parse(raw.body)!.version).toBe(newVersion);
+    }
+
+    // idempotence: nothing left at the old version
+    const rerun = await walker.walkTable(walkTable, 'rotate-keys', { dbDriver: spannerDriver, db: systemDb });
+    expect(rerun.rewritten).toBe(0);
+
+    // retire the old version: reads and search remain exact on the new key
+    await store.retireKeyVersion(OWNER, versionBefore);
+    expect((await db.get(walkTable, { id: row2.id })).title).toBe('rotation subject two');
+    const found = await db.query(walkTable, titleLike('%rotation subject%'));
+    expect(found.length).toBe(2);
+  });
+});

package/test/EncryptionPerf.test.ts

@@ -0,0 +1,156 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  DataKeyStore,
+  EncryptionEnvelope,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncPerfRow, EncPerfRowTable, PlainPerfRowTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER = 'enc-perf-owner-a';
+const ROW_COUNT = 1000;
+
+const encTable = new EncPerfRowTable() as Table<EncPerfRow>;
+const plainTable = new PlainPerfRowTable() as Table<EncPerfRow>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+
+/**
+ * Performance sanity for the doc's claims (TRUST_AND_COMPLIANCE §1.5): per-value AES-256-GCM
+ * decrypt ~1-3µs in Node; a 1k-row read's decrypt overhead an order of magnitude below the
+ * database/network latency the read already pays. Numbers are printed for the report.
+ */
+describe('Column encryption performance sanity', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => [OWNER],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [encTable, plainTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [encTable, plainTable]);
+
+    // Seed 1k rows in each table with identical ~120-char bodies (batched inserts via txns
+    // to keep seeding fast on the emulator).
+    const body = (index: number) =>
+      `note body ${index} — a sentence of ordinary length, the kind a document row actually stores in practice.`;
+    for (let batch = 0; batch < ROW_COUNT / 100; batch++) {
+      await db.runTransaction(async () => {
+        for (let i = 0; i < 100; i++) {
+          const index = batch * 100 + i;
+          await db.insert(encTable, { scope: OWNER, body: body(index) });
+        }
+      });
+      await db.runTransaction(async () => {
+        for (let i = 0; i < 100; i++) {
+          const index = batch * 100 + i;
+          await db.insert(plainTable, { scope: OWNER, body: body(index) });
+        }
+      });
+    }
+  }, 600000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(encTable);
+    await dropTable(plainTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  const timeQuery = async (table: Table<EncPerfRow>): Promise<{ ms: number; rows: number }> => {
+    const start = process.hrtime.bigint();
+    const rows = await db.query(
+      table,
+      new QueryBuilder<EncPerfRow>(table.name).condition({ field: 'scope', operator: '=', value: OWNER })
+    );
+    const ms = Number(process.hrtime.bigint() - start) / 1e6;
+    return { ms, rows: rows.length };
+  };
+
+  test('1k-row read: decrypt overhead measured against the plaintext twin', async () => {
+    // warm the key cache + driver sessions
+    await timeQuery(encTable);
+    await timeQuery(plainTable);
+
+    const samples = 5;
+    let encTotal = 0;
+    let plainTotal = 0;
+    for (let i = 0; i < samples; i++) {
+      encTotal += (await timeQuery(encTable)).ms;
+      plainTotal += (await timeQuery(plainTable)).ms;
+    }
+    const encAvg = encTotal / samples;
+    const plainAvg = plainTotal / samples;
+    const overheadMs = encAvg - plainAvg;
+    const perValueUs = (overheadMs * 1000) / ROW_COUNT;
+
+    // eslint-disable-next-line no-console
+    console.info(
+      `[perf] 1k-row read: encrypted ${encAvg.toFixed(1)}ms vs plaintext ${plainAvg.toFixed(1)}ms — ` +
+        `decrypt overhead ${overheadMs.toFixed(1)}ms total, ~${perValueUs.toFixed(2)}µs/value (doc claim: ~1-3µs/value)`
+    );
+
+    const encRows = await db.query(
+      encTable,
+      new QueryBuilder<EncPerfRow>(encTable.name).condition({ field: 'scope', operator: '=', value: OWNER })
+    );
+    expect(encRows.length).toBe(ROW_COUNT);
+    // Sanity bound, generous (emulator variance): the whole-read overhead stays well under
+    // the read itself — decrypt must not dominate.
+    expect(overheadMs).toBeLessThan(Math.max(plainAvg, 250));
+  });
+
+  test('per-value decrypt microbenchmark: the in-process AES-256-GCM cost itself', async () => {
+    const key = await new DataKeyStore().getWriteKey(OWNER);
+    const envelope = new EncryptionEnvelope();
+    const value = 'note body — a sentence of ordinary length, the kind a document row actually stores in practice.';
+    const encrypted = envelope.encrypt(value, key);
+
+    const iterations = 10000;
+    // warm
+    for (let i = 0; i < 1000; i++) {
+      envelope.decrypt(encrypted, key);
+    }
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i++) {
+      envelope.decrypt(encrypted, key);
+    }
+    const totalUs = Number(process.hrtime.bigint() - start) / 1e3;
+    const perValueUs = totalUs / iterations;
+
+    // eslint-disable-next-line no-console
+    console.info(
+      `[perf] in-process decrypt: ${perValueUs.toFixed(2)}µs/value over ${iterations} iterations ` +
+        `(doc claim: ~1-3µs/value)`
+    );
+
+    expect(envelope.decrypt(encrypted, key)).toBe(value);
+    // The claim's order of magnitude, with generous headroom for slow machines
+    expect(perValueUs).toBeLessThan(30);
+  });
+});