@proteinjs/db-driver-spanner 1.23.5 → 1.25.0

package/test/ColumnEncryption.test.ts

@@ -0,0 +1,252 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  DataKeyStore,
+  EncryptionEnvelope,
+  EncryptionKeyUnavailableError,
+  MasterKeyProvider,
+  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 { EncNote, EncNoteTable } 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',
+});
+
+/** Key IO (DataKeyStore) rides the process's default driver — the getDbAsSystem idiom the
+ *  migration ledger already uses. The driver test harness has no DefaultDbDriverFactory, so
+ *  seed the global the same way the factory would (test-harness convention: runtime access
+ *  to internals rather than widening the API). */
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER_A = 'enc-core-owner-a';
+const OWNER_B = 'enc-core-owner-b';
+
+/** Counts vault calls, so unwrap-once caching is asserted on OUTCOMES (vault traffic). */
+class CountingMasterKeyProvider implements MasterKeyProvider {
+  public wrapCalls = 0;
+  public unwrapCalls = 0;
+  private delegate = new InMemoryMasterKeyProvider('column-encryption-test');
+
+  async wrapDataKey(material: Buffer): Promise<string> {
+    this.wrapCalls++;
+    return await this.delegate.wrapDataKey(material);
+  }
+
+  async unwrapDataKey(wrapped: string): Promise<Buffer> {
+    this.unwrapCalls++;
+    return await this.delegate.unwrapDataKey(wrapped);
+  }
+
+  getMasterKeyId(): string {
+    return 'counting-in-memory';
+  }
+}
+
+const masterKeyProvider = new CountingMasterKeyProvider();
+let accessibleOwners: string[] = [OWNER_A];
+
+const noteTable = new EncNoteTable() as Table<EncNote>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+const envelope = new EncryptionEnvelope();
+
+const rawColumn = async (tableName: string, id: string, columnName: string): Promise<any> => {
+  const rows = await spannerDriver.runQuery(() => ({
+    sql: `SELECT \`${columnName}\` FROM \`${tableName}\` WHERE \`id\` = '${id}'`,
+  }));
+  return rows[0]?.[columnName];
+};
+
+describe('Column encryption: the transparent seam', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider,
+      getAccessibleKeyOwners: async () => accessibleOwners,
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [noteTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [noteTable]);
+  }, 120000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    const { EncryptedColumns } = await import('@proteinjs/db');
+    await dropTable(new EncryptedColumns().tokenTableFor(noteTable)!);
+    await dropTable(noteTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  beforeEach(() => {
+    accessibleOwners = [OWNER_A];
+  });
+
+  test('round trip is transparent: callers write and read plaintext; the database stores a ciphertext envelope', async () => {
+    const inserted = await db.insert(noteTable, {
+      scope: OWNER_A,
+      title: 'Therapy notes — divorce',
+      label: 'personal',
+      body: 'The most sensitive words in the account.',
+      status: 'active',
+    });
+
+    // Caller-visible: plaintext, unchanged API
+    const fetched = await db.get(noteTable, { id: inserted.id });
+    expect(fetched.title).toBe('Therapy notes — divorce');
+    expect(fetched.label).toBe('personal');
+    expect(fetched.body).toBe('The most sensitive words in the account.');
+    expect(fetched.status).toBe('active');
+
+    // At rest: self-describing envelopes, no plaintext, plaintext column untouched
+    for (const columnName of ['title', 'label', 'body']) {
+      const stored = await rawColumn(noteTable.name, inserted.id, columnName);
+      expect(envelope.isEnvelope(stored)).toBe(true);
+      expect(stored).not.toContain('divorce');
+      expect(stored).not.toContain('sensitive');
+      const parsed = envelope.parse(stored)!;
+      expect(parsed.owner).toBe(OWNER_A);
+    }
+    expect(await rawColumn(noteTable.name, inserted.id, 'status')).toBe('active');
+
+    // Deserialized records carry no framework companion columns
+    expect(Object.keys(fetched).some((key) => key.includes('__enc'))).toBe(false);
+
+    await db.delete(noteTable, { id: inserted.id });
+  });
+
+  test('update through the seam: new ciphertext at rest, plaintext to callers', async () => {
+    const inserted = await db.insert(noteTable, { scope: OWNER_A, title: 'Before', label: 'a', body: 'b' });
+    const updateCount = await db.update(noteTable, { id: inserted.id, title: 'After the update' });
+    expect(updateCount).toBe(1);
+
+    const fetched = await db.get(noteTable, { id: inserted.id });
+    expect(fetched.title).toBe('After the update');
+    expect(fetched.label).toBe('a'); // untouched columns survive
+
+    const stored = await rawColumn(noteTable.name, inserted.id, 'title');
+    expect(envelope.isEnvelope(stored)).toBe(true);
+    expect(stored).not.toContain('After');
+
+    await db.delete(noteTable, { id: inserted.id });
+  });
+
+  test('null stays null: IS NULL / IS NOT NULL queries keep working natively', async () => {
+    const withTitle = await db.insert(noteTable, { scope: OWNER_A, title: 'present', label: 'x', body: null });
+    const withoutTitle = await db.insert(noteTable, { scope: OWNER_A, title: null, label: 'y', body: 'here' });
+
+    expect(await rawColumn(noteTable.name, withoutTitle.id, 'title')).toBeNull();
+
+    const nullTitles = await db.query(
+      noteTable,
+      new QueryBuilder<EncNote>(noteTable.name).condition({ field: 'title', operator: 'IS NULL' })
+    );
+    expect(nullTitles.some((row) => row.id === withoutTitle.id)).toBe(true);
+    expect(nullTitles.some((row) => row.id === withTitle.id)).toBe(false);
+
+    await db.delete(noteTable, { id: withTitle.id });
+    await db.delete(noteTable, { id: withoutTitle.id });
+  });
+
+  test('adoption path: a pre-encryption plaintext row reads through the seam unchanged', async () => {
+    const id = 'enc-adoption-row-1';
+    await spannerDriver.runDml(() => ({
+      sql:
+        `INSERT INTO \`${noteTable.name}\` (\`id\`, \`created\`, \`updated\`, \`scope\`, \`title\`, \`status\`) ` +
+        `VALUES ('${id}', CURRENT_TIMESTAMP(), CURRENT_TIMESTAMP(), '${OWNER_A}', 'legacy plaintext title', 'active')`,
+    }));
+
+    const fetched = await db.get(noteTable, { id });
+    expect(fetched.title).toBe('legacy plaintext title');
+    await db.delete(noteTable, { id });
+  });
+
+  test('scope-owner keying: each row encrypts under its scope owner; the vault is called once per key (unwrap caching)', async () => {
+    const rowA = await db.insert(noteTable, { scope: OWNER_A, title: 'a note', label: 'la', body: 'ba' });
+    const rowB = await db.insert(noteTable, { scope: OWNER_B, title: 'b note', label: 'lb', body: 'bb' });
+
+    expect(envelope.parse(await rawColumn(noteTable.name, rowA.id, 'title'))!.owner).toBe(OWNER_A);
+    expect(envelope.parse(await rawColumn(noteTable.name, rowB.id, 'title'))!.owner).toBe(OWNER_B);
+
+    // Server-side sharing mechanics: decrypt resolves the key FROM the envelope, so one
+    // reader's reads return both owners' rows decrypted.
+    const bothRows = [await db.get(noteTable, { id: rowA.id }), await db.get(noteTable, { id: rowB.id })];
+    expect(bothRows.map((row) => row.title)).toEqual(['a note', 'b note']);
+
+    // Unwrap-once caching: repeat reads add ZERO vault calls
+    const unwrapCallsBefore = masterKeyProvider.unwrapCalls;
+    for (let i = 0; i < 5; i++) {
+      await db.get(noteTable, { id: rowA.id });
+      await db.get(noteTable, { id: rowB.id });
+    }
+    expect(masterKeyProvider.unwrapCalls).toBe(unwrapCallsBefore);
+
+    await db.delete(noteTable, { id: rowA.id });
+    await db.delete(noteTable, { id: rowB.id });
+  });
+
+  test('a shared-scope row keys by the scope owner, not the writer: config resolveKeyOwner decides', async () => {
+    setDbEncryptionConfig({
+      masterKeyProvider,
+      getAccessibleKeyOwners: async () => accessibleOwners,
+      // The consumer's scope→owner mapping (thought-common's permission-source resolver in
+      // the app): here, rows whose scope starts with 'shared:' belong to OWNER_B.
+      resolveKeyOwner: async ({ record }) =>
+        typeof record.scope === 'string' && record.scope.startsWith('shared:') ? OWNER_B : undefined,
+    });
+
+    const sharedRow = await db.insert(noteTable, { scope: 'shared:tree-root', title: 'contributed text', label: 'l' });
+    expect(envelope.parse(await rawColumn(noteTable.name, sharedRow.id, 'title'))!.owner).toBe(OWNER_B);
+
+    await db.delete(noteTable, { id: sharedRow.id });
+    setDbEncryptionConfig({ masterKeyProvider, getAccessibleKeyOwners: async () => accessibleOwners });
+  });
+
+  test('crypto-shred: deleting an owner key makes their rows permanently unreadable, loudly', async () => {
+    const shredOwner = 'enc-core-shred-owner';
+    const row = await db.insert(noteTable, { scope: shredOwner, title: 'to be shredded', label: 'x', body: 'y' });
+
+    const deleted = await new DataKeyStore().shredOwnerKeys(shredOwner);
+    expect(deleted).toBeGreaterThanOrEqual(1);
+
+    await expect(db.get(noteTable, { id: row.id })).rejects.toThrow(EncryptionKeyUnavailableError);
+
+    // other owners' rows are untouched (blast radius = one owner)
+    const survivor = await db.insert(noteTable, { scope: OWNER_A, title: 'still fine', label: 'ok' });
+    expect((await db.get(noteTable, { id: survivor.id })).title).toBe('still fine');
+
+    await spannerDriver.runDml(() => ({
+      sql: `DELETE FROM \`${noteTable.name}\` WHERE \`id\` = '${row.id}'`,
+    }));
+    await db.delete(noteTable, { id: survivor.id });
+  });
+
+  test('transactions: encrypted writes and reads ride runTransaction like any other write', async () => {
+    const result = await db.runTransaction(async () => {
+      const inserted = await db.insert(noteTable, { scope: OWNER_A, title: 'txn title', label: 'txn' });
+      await db.update(noteTable, { id: inserted.id, body: 'txn body' });
+      return await db.get(noteTable, { id: inserted.id });
+    });
+    expect(result.title).toBe('txn title');
+    expect(result.body).toBe('txn body');
+    await db.delete(noteTable, { id: result.id });
+  });
+});

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 });
+  });
+});