feat(stack): synthesize/merge v3 tables + guard unmodelled EQL domains

tobyhede · tobyhede · commit 1cbd957b9c8c · 2026-07-09T14:58:04.000+10:00
diff --git a/packages/stack/__tests__/supabase-schema-builder.test.ts b/packages/stack/__tests__/supabase-schema-builder.test.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest'
+import { encryptedTable, types } from '@/eql/v3'
+import type { IntrospectionResult } from '@/supabase/introspect'
+import {
+  assertModelledDomains,
+  mergeDeclaredTables,
+  synthesizeTables,
+} from '@/supabase/schema-builder'
+
+const introspection: IntrospectionResult = [
+  {
+    tableName: 'users',
+    columns: [
+      { columnName: 'id', domainName: null },
+      { columnName: 'email', domainName: 'text_search' },
+      { columnName: 'amount', domainName: 'integer_ord' },
+      { columnName: 'note', domainName: null },
+      { columnName: 'weird', domainName: 'not_a_domain' }, // unknown → plaintext
+    ],
+  },
+]
+
+describe('synthesizeTables', () => {
+  it('builds an EncryptedTable with only the recognised domain columns', () => {
+    const { tables } = synthesizeTables(introspection)
+    const users = tables.get('users')
+    expect(users).toBeDefined()
+    expect(Object.keys(users!.columnBuilders).sort()).toEqual([
+      'amount',
+      'email',
+    ])
+  })
+
+  it('records the FULL column list (encrypted + plaintext) for select(*)', () => {
+    const { allColumns } = synthesizeTables(introspection)
+    expect(allColumns.get('users')).toEqual([
+      'id',
+      'email',
+      'amount',
+      'note',
+      'weird',
+    ])
+  })
+
+  it('synthesizes a domain column byte-identically to a declared column', () => {
+    const { tables } = synthesizeTables(introspection)
+    const synthesized = tables.get('users')!.build()
+    const declared = encryptedTable('users', {
+      email: types.TextSearch('email'),
+      amount: types.IntegerOrd('amount'),
+    }).build()
+    expect(synthesized.columns.email).toEqual(declared.columns.email)
+    expect(synthesized.columns.amount).toEqual(declared.columns.amount)
+  })
+
+  it('treats an Object.prototype-named domain as plaintext, not a domain', () => {
+    // `DOMAIN_REGISTRY['constructor']` would be truthy on a plain object; the
+    // null prototype + Object.hasOwn guard keep this column plaintext.
+    const prototypeNamed: IntrospectionResult = [
+      {
+        tableName: 'weird',
+        columns: [
+          { columnName: 'a', domainName: 'constructor' },
+          { columnName: 'b', domainName: '__proto__' },
+          { columnName: 'c', domainName: 'toString' },
+        ],
+      },
+    ]
+    const { tables, allColumns } = synthesizeTables(prototypeNamed)
+    expect(Object.keys(tables.get('weird')!.columnBuilders)).toEqual([])
+    expect(allColumns.get('weird')).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('mergeDeclaredTables', () => {
+  it('lets a declared TextSearch column keep its tuned match options', () => {
+    const synth = synthesizeTables(introspection)
+    const declaredTable = encryptedTable('users', {
+      email: types
+        .TextSearch('email')
+        .freeTextSearch({ include_original: false }),
+    })
+    const merged = mergeDeclaredTables(synth, { users: declaredTable })
+    const built = merged.tables.get('users')!.build()
+    expect(built.columns.email.indexes.match?.include_original).toBe(false)
+    expect(built.columns.amount).toBeDefined()
+    expect(merged.allColumns.get('users')).toEqual(
+      synth.allColumns.get('users'),
+    )
+  })
+
+  it('preserves a declared property→DB-name rename', () => {
+    const renamed: IntrospectionResult = [
+      {
+        tableName: 'events',
+        columns: [
+          { columnName: 'id', domainName: null },
+          { columnName: 'created_on', domainName: 'timestamp_ord' },
+        ],
+      },
+    ]
+    const synth = synthesizeTables(renamed)
+    const declaredTable = encryptedTable('events', {
+      createdAt: types.TimestampOrd('created_on'),
+    })
+    const merged = mergeDeclaredTables(synth, { events: declaredTable })
+    const table = merged.tables.get('events')!
+    expect(table.buildColumnKeyMap()).toEqual({ createdAt: 'created_on' })
+    expect(Object.keys(table.columnBuilders)).toEqual(['createdAt'])
+  })
+})
+
+describe('assertModelledDomains', () => {
+  it('passes when every EQL domain in use is modelled', () => {
+    const eqlDomains = new Set(['text_search', 'integer_ord'])
+    expect(() => assertModelledDomains(introspection, eqlDomains)).not.toThrow()
+  })
+
+  it('throws naming the column + domain for a recognised-but-unmodelled domain', () => {
+    const withOpe: IntrospectionResult = [
+      {
+        tableName: 'metrics',
+        columns: [
+          { columnName: 'id', domainName: null },
+          { columnName: 'score', domainName: 'integer_ord_ope' },
+        ],
+      },
+    ]
+    // integer_ord_ope IS an EQL v3 domain, but has no types factory.
+    const eqlDomains = new Set(['integer_ord_ope'])
+    expect(() => assertModelledDomains(withOpe, eqlDomains)).toThrow(
+      /metrics\.score.*integer_ord_ope|integer_ord_ope.*metrics\.score/,
+    )
+  })
+
+  it('does NOT throw for a user jsonb domain that is not an EQL domain', () => {
+    const withUserDomain: IntrospectionResult = [
+      {
+        tableName: 'docs',
+        columns: [{ columnName: 'body', domainName: 'my_json' }],
+      },
+    ]
+    // my_json is NOT in eqlDomains → plaintext passthrough, no throw.
+    expect(() => assertModelledDomains(withUserDomain, new Set())).not.toThrow()
+  })
+})
diff --git a/packages/stack/src/supabase/schema-builder.ts b/packages/stack/src/supabase/schema-builder.ts
@@ -0,0 +1,115 @@
+import { type AnyV3Table, EncryptedTable } from '@/eql/v3'
+import type { AnyEncryptedV3Column } from '@/eql/v3/columns'
+import { factoryForDomain } from '@/eql/v3/domain-registry'
+import type { IntrospectionResult } from './introspect'
+
+/** A record of declared v3 tables, keyed by table name. */
+export type V3Schemas = Record<string, AnyV3Table>
+
+export interface SynthesizedSchema {
+  /** Every introspected table (even zero-encrypted ones), keyed by table name.
+   * Values hold ONLY the encrypted columns; plaintext columns live in
+   * `allColumns`. */
+  tables: Map<string, AnyV3Table>
+  /** Full column list per table (encrypted + plaintext), for select('*'). */
+  allColumns: Map<string, string[]>
+}
+
+/**
+ * Build one `EncryptedTable` per introspected table from its domain columns.
+ * A column whose `domainName` is NULL or absent from the registry is treated as
+ * plaintext — retained in `allColumns` but not added to the table. Synthesized
+ * columns are keyed by DB name (property == DB name).
+ *
+ * NOTE: this does NOT reject recognized-but-unmodelled EQL domains — call
+ * {@link assertModelledDomains} first; here such a column would silently become
+ * a plaintext passthrough.
+ */
+export function synthesizeTables(
+  introspection: IntrospectionResult,
+): SynthesizedSchema {
+  const tables = new Map<string, AnyV3Table>()
+  const allColumns = new Map<string, string[]>()
+
+  for (const table of introspection) {
+    const builders: Record<string, AnyEncryptedV3Column> = {}
+    for (const col of table.columns) {
+      if (col.domainName === null) continue
+      const factory = factoryForDomain(col.domainName)
+      if (!factory) continue // unknown / unmodelled → guarded elsewhere
+      builders[col.columnName] = factory(col.columnName)
+    }
+    // Raw constructor (not `encryptedTable`) — no accessor copy or reserved-key
+    // guard is needed, and it avoids throwing on an arbitrary DB column name
+    // that happens to collide with a reserved table member.
+    tables.set(table.tableName, new EncryptedTable(table.tableName, builders))
+    allColumns.set(
+      table.tableName,
+      table.columns.map((c) => c.columnName),
+    )
+  }
+
+  return { tables, allColumns }
+}
+
+/**
+ * Replace synthesized tables with a merge of declared-over-synthesized columns.
+ * For each declared column, drop the synthesized entry that resolves to the
+ * same DB name and add the declared builder under its JS property name (so a
+ * property→DB rename and any tuner options survive). Undeclared columns stay
+ * synthesized. `allColumns` is unchanged (DB-name based, from introspection).
+ */
+export function mergeDeclaredTables(
+  synth: SynthesizedSchema,
+  schemas: V3Schemas,
+): SynthesizedSchema {
+  const tables = new Map(synth.tables)
+
+  for (const declared of Object.values(schemas)) {
+    const tableName = declared.tableName
+    const synthesized = tables.get(tableName)
+
+    const merged: Record<string, AnyEncryptedV3Column> = {}
+    if (synthesized) {
+      for (const [prop, builder] of Object.entries(
+        synthesized.columnBuilders,
+      )) {
+        merged[prop] = builder as AnyEncryptedV3Column
+      }
+    }
+    for (const [prop, builder] of Object.entries(declared.columnBuilders)) {
+      const dbName = builder.getName()
+      if (dbName !== prop && Object.hasOwn(merged, dbName)) {
+        delete merged[dbName]
+      }
+      merged[prop] = builder as AnyEncryptedV3Column
+    }
+    tables.set(tableName, new EncryptedTable(tableName, merged))
+  }
+
+  return { tables, allColumns: synth.allColumns }
+}
+
+/**
+ * Throw if any introspected column uses an EQL v3 domain this SDK version does
+ * not model. Such a column would otherwise become a plaintext passthrough:
+ * inserts fail on the domain CHECK, but reads return raw ciphertext undecrypted
+ * (`decryptModel` skips columns absent from the config) — a silent data leak.
+ * A domain not in `eqlDomains` (a user's own jsonb domain) is fine — plaintext.
+ */
+export function assertModelledDomains(
+  introspection: IntrospectionResult,
+  eqlDomains: Set<string>,
+): void {
+  for (const table of introspection) {
+    for (const col of table.columns) {
+      const domain = col.domainName
+      if (domain === null) continue
+      if (!eqlDomains.has(domain)) continue // not an EQL domain → plaintext
+      if (factoryForDomain(domain)) continue // modelled → ok
+      throw new Error(
+        `[supabase v3]: column "${table.tableName}.${col.columnName}" uses EQL v3 domain "public.${domain}", which this @cipherstash/stack version does not model. Upgrade the package or drop the column — it cannot be used as a plaintext passthrough (reads would return ciphertext undecrypted).`,
+      )
+    }
+  }
+}
