@proteinjs/db-driver-spanner 1.23.5 → 1.24.0

package/test/EncryptionSortAndUnique.test.ts

@@ -0,0 +1,130 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  EncryptedColumns,
+  EncryptedColumnQueryError,
+  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 { EncSortedItem, EncSortedItemTable, EncUniqueTag, EncUniqueTagTable } 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-sort-owner-a';
+const OWNER_B = 'enc-sort-owner-b';
+
+const sortedTable = new EncSortedItemTable() as Table<EncSortedItem>;
+const uniqueTable = new EncUniqueTagTable() as Table<EncUniqueTag>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+
+/**
+ * The sortKey tier of the sorting story (a DECLARED bounded reveal → native ORDER BY at any
+ * scale), the loud live rejection without one, and value uniqueness through the equality
+ * fingerprint (per owner).
+ */
+describe('Encrypted sortKey ORDER BY + fingerprint uniqueness', () => {
+  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_A],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [sortedTable, uniqueTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [sortedTable, uniqueTable]);
+  }, 120000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(new EncryptedColumns().tokenTableFor(sortedTable)!);
+    await dropTable(sortedTable);
+    await dropTable(uniqueTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  test('sortKey: native ORDER BY + sorted pagination over encrypted values; only the declared prefix is revealed at rest', async () => {
+    const titles = ['banana bread', 'Apple pie', 'cherry tart', 'apricot jam', 'Blueberry scone'];
+    const ids: string[] = [];
+    for (const title of titles) {
+      ids.push((await db.insert(sortedTable, { scope: OWNER_A, title })).id);
+    }
+
+    // native DB-side ORDER BY on the encrypted column (revealPrefix=3 buckets), ascending
+    const sorted = await db.query(
+      sortedTable,
+      new QueryBuilder<EncSortedItem>(sortedTable.name)
+        .condition({ field: 'scope', operator: '=', value: OWNER_A })
+        .sort([{ field: 'title' }])
+    );
+    const sortedTitles = sorted.map((row) => row.title);
+    // prefix buckets (first 3 chars, normalized): app=Apple/apricot tie-break within bucket,
+    // then ban, blu, che — assert bucket ORDER, the declared guarantee
+    const buckets = sortedTitles.map((title) => (title ?? '').toLowerCase().slice(0, 3));
+    expect(buckets).toEqual([...buckets].sort());
+
+    // sorted PAGINATION: the first page of the prefix order
+    const firstPage = await db.query(
+      sortedTable,
+      new QueryBuilder<EncSortedItem>(sortedTable.name)
+        .condition({ field: 'scope', operator: '=', value: OWNER_A })
+        .sort([{ field: 'title' }])
+        .paginate({ start: 0, end: 2 })
+    );
+    expect(firstPage.length).toBe(2);
+    for (const row of firstPage) {
+      expect((row.title ?? '').toLowerCase().slice(0, 2)).toBe('ap');
+    }
+
+    // at rest: the sort companion holds EXACTLY the declared 3-character reveal
+    const raw = await spannerDriver.runQuery(() => ({
+      sql: `SELECT \`title\`, \`title_enc_srt\` FROM \`${sortedTable.name}\` WHERE \`id\` = '${ids[0]}'`,
+    }));
+    expect((raw[0] as any).title_enc_srt).toBe('ban');
+    expect((raw[0] as any).title).not.toContain('banana');
+
+    for (const id of ids) {
+      await db.delete(sortedTable, { id });
+    }
+  });
+
+  test('the live loud rejection: ORDER BY an encrypted column with no sortKey throws at query-build time', async () => {
+    const tagQb = new QueryBuilder<EncUniqueTag>(uniqueTable.name).sort([{ field: 'name' }]);
+    await expect(db.query(uniqueTable, tagQb)).rejects.toThrow(EncryptedColumnQueryError);
+
+    const tagQb2 = new QueryBuilder<EncUniqueTag>(uniqueTable.name).sort([{ field: 'name' }]);
+    await expect(db.query(uniqueTable, tagQb2)).rejects.toThrow(/no sortKey declared/);
+  });
+
+  test('uniqueness on the value rides the fingerprint: duplicate value for the same owner rejected; other owners unaffected', async () => {
+    const first = await db.insert(uniqueTable, { scope: OWNER_A, name: 'oncologist' });
+    await expect(db.insert(uniqueTable, { scope: OWNER_A, name: 'oncologist' })).rejects.toThrow();
+
+    // per-owner semantics: another owner may hold the same value (fingerprints are keyed per owner)
+    const otherOwner = await db.insert(uniqueTable, { scope: OWNER_B, name: 'oncologist' });
+
+    await db.delete(uniqueTable, { id: first.id });
+    await db.delete(uniqueTable, { id: otherOwner.id });
+  });
+});

package/test/index.ts

@@ -1,3 +1,4 @@
 export * from './util/getDropTestTable';
 export * from './util/SpannerEmulatorProvisioner';
 export * from './util/serviceUpdateVerbsTestTables';
+export * from './util/columnEncryptionTestTables';

package/test/util/columnEncryptionTestHarness.ts

@@ -0,0 +1,54 @@
+import { DataEncryptionKeyTable, EncryptedColumns, Table, TableManager } from '@proteinjs/db';
+import { cascadeDeleteTestTables } from '@proteinjs/db/test';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+
+/**
+ * Schema loading for the column-encryption suites. `Db.delete` consults the reverse-cascade
+ * edge index over the WHOLE static table registry, and dynamic-reference edges are
+ * target-agnostic — so a delete from ANY table queries every registered table holding a
+ * `reverseCascadeDelete` dynamic-reference column (the cascade-delete test tables). A
+ * single-file run must therefore create those alongside the suite's own tables, plus the
+ * framework's data-key table. Serial `loadTable` (never batch `loadTables`): the registry
+ * deliberately holds same-name table pairs for schema-change tests, which a batch create
+ * would collide on.
+ *
+ * @internal This module is intended to be used only in tests.
+ */
+export const loadColumnEncryptionTestSchema = async (
+  tableManager: TableManager,
+  suiteTables: Table<any>[]
+): Promise<void> => {
+  const tables: Table<any>[] = [
+    ...Object.values(cascadeDeleteTestTables),
+    new DataEncryptionKeyTable(),
+    ...suiteTables,
+  ];
+  for (const table of tables) {
+    await tableManager.loadTable(table);
+  }
+};
+
+/**
+ * Clean-slate purge of a suite's tables (rows + their derived token tables) in beforeAll:
+ * a prior run killed mid-flight (or a teardown starved out by shared-emulator contention)
+ * leaves seeded rows behind, and exact-match search assertions must never depend on a
+ * previous process having exited cleanly.
+ */
+export const purgeColumnEncryptionTestRows = async (
+  spannerDriver: SpannerDriver,
+  suiteTables: Table<any>[]
+): Promise<void> => {
+  const encryptedColumns = new EncryptedColumns();
+  const tables: Table<any>[] = [];
+  for (const table of suiteTables) {
+    tables.push(table);
+    const tokenTable = encryptedColumns.tokenTableFor(table);
+    if (tokenTable) {
+      tables.push(tokenTable);
+    }
+  }
+
+  for (const table of tables) {
+    await spannerDriver.runDml(() => ({ sql: `DELETE FROM \`${table.name}\` WHERE TRUE` }));
+  }
+};

package/test/util/columnEncryptionTestTables.ts

@@ -0,0 +1,115 @@
+import { Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+
+/**
+ * Tables for the column-encryption suites (`ColumnEncryption.test.ts`,
+ * `EncryptedSearch.test.ts`, `EncryptionSortAndUnique.test.ts`,
+ * `EncryptionLifecycleWalker.test.ts`, `EncryptionPerf.test.ts`).
+ *
+ * Defined here rather than in the test files so the reflection build registers them as
+ * `Table` loadables — the driver's statement generation and the framework's derived
+ * token-table subqueries resolve tables through `tableByName`.
+ */
+
+/** Core seam suite: contains + equality + opaque encrypted + plaintext metadata. */
+export interface EncNote extends Record {
+  scope: string;
+  title?: string | null; // encrypted + contains search
+  label?: string | null; // encrypted + equality lookup
+  body?: string | null; // encrypted, never queried by value
+  status?: string | null; // plaintext metadata
+}
+
+export class EncNoteTable extends Table<EncNote> {
+  name = 'db_test_enc_note';
+  columns: Table<EncNote>['columns'] = withRecordColumns<EncNote>({
+    scope: new StringColumn('scope', {}, 36),
+    title: new StringColumn('title', { encrypted: { searchable: 'contains' } }),
+    label: new StringColumn('label', { encrypted: { searchable: 'equality' } }),
+    body: new StringColumn('body', { encrypted: {} }, 'MAX'),
+    status: new StringColumn('status', { encrypted: false }),
+  });
+}
+
+/** Search-exactness suite: one contains column beside plaintext metadata. */
+export interface EncSearchDoc extends Record {
+  scope: string;
+  title?: string | null; // encrypted + contains
+  name?: string | null; // encrypted + equality
+  kind?: string | null; // plaintext metadata
+}
+
+export class EncSearchDocTable extends Table<EncSearchDoc> {
+  name = 'db_test_enc_search_doc';
+  columns: Table<EncSearchDoc>['columns'] = withRecordColumns<EncSearchDoc>({
+    scope: new StringColumn('scope', {}, 36),
+    title: new StringColumn('title', { encrypted: { searchable: 'contains' } }),
+    name: new StringColumn('name', { encrypted: { searchable: 'equality' } }),
+    kind: new StringColumn('kind', { encrypted: false }),
+  });
+}
+
+/** sortKey suite: the declared bounded-reveal native ORDER BY. */
+export interface EncSortedItem extends Record {
+  scope: string;
+  title?: string | null; // encrypted + sortKey(3)
+}
+
+export class EncSortedItemTable extends Table<EncSortedItem> {
+  name = 'db_test_enc_sorted_item';
+  columns: Table<EncSortedItem>['columns'] = withRecordColumns<EncSortedItem>({
+    scope: new StringColumn('scope', {}, 36),
+    title: new StringColumn('title', { encrypted: { searchable: 'contains', sortKey: { revealPrefix: 3 } } }),
+  });
+}
+
+/** Uniqueness suite: unique moves onto the equality fingerprint. */
+export interface EncUniqueTag extends Record {
+  scope: string;
+  name?: string | null; // encrypted + equality, unique
+}
+
+export class EncUniqueTagTable extends Table<EncUniqueTag> {
+  name = 'db_test_enc_unique_tag';
+  columns: Table<EncUniqueTag>['columns'] = withRecordColumns<EncUniqueTag>({
+    scope: new StringColumn('scope', {}, 36),
+    name: new StringColumn('name', { unique: { unique: true }, encrypted: { searchable: 'equality' } }),
+  });
+}
+
+/** Lifecycle-walker suite: encrypt / retokenize / decrypt / rotate transitions. */
+export interface EncWalkRow extends Record {
+  scope: string;
+  title?: string | null; // encrypted + contains
+  body?: string | null; // encrypted, no search
+}
+
+export class EncWalkRowTable 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: { searchable: 'contains' } }),
+    body: new StringColumn('body', { encrypted: {} }, 'MAX'),
+  });
+}
+
+/** Perf suite: encrypted-at-rest body vs a plaintext twin, 1k-row reads. */
+export interface EncPerfRow extends Record {
+  scope: string;
+  body?: string | null;
+}
+
+export class EncPerfRowTable extends Table<EncPerfRow> {
+  name = 'db_test_enc_perf_row';
+  columns: Table<EncPerfRow>['columns'] = withRecordColumns<EncPerfRow>({
+    scope: new StringColumn('scope', {}, 36),
+    body: new StringColumn('body', { encrypted: {} }, 'MAX'),
+  });
+}
+
+export class PlainPerfRowTable extends Table<EncPerfRow> {
+  name = 'db_test_plain_perf_row';
+  columns: Table<EncPerfRow>['columns'] = withRecordColumns<EncPerfRow>({
+    scope: new StringColumn('scope', {}, 36),
+    body: new StringColumn('body', { encrypted: false }, 'MAX'),
+  });
+}