fix(stack): select('*') must alias renamed v3 columns back to their property

`select('*')` expanded the introspected column list, which holds DB column
names. `addJsonbCastsV3` only emits the `prop:db_name::jsonb` PostgREST alias
when it sees a *property* name; a raw DB name took the unaliased
`dbNames.has(...)` branch. So on a declared table with a property→DB rename,
rows came back keyed `created_at` while the declared row type promises
`createdAt` — `row.createdAt` was silently `undefined` for a field TypeScript
guaranteed as a Date. Synthesized columns were unaffected (property == DB name),
which is why no existing test caught it: the select-star suite used only
matching names, and the rename suite used only explicit selects.

Adds an `expandAllColumns` hook on the base builder (identity for v2, which
never supplies a column list) that the v3 dialect overrides to map DB names
back through the inverse of `buildColumnKeyMap()`.

Also fixes a pre-existing prototype-inheritance hazard surfaced by the new
tests: `propToDb` was a plain object indexed by column names that originate in
the database, so a plaintext column named `constructor` resolved to
`Object.prototype.constructor` — truthy — and interpolated
`function Object() { [native code] }` into the emitted select string. It was
reachable from explicit selects too (`select('constructor')`), and equally from
`filterColumnName` and the mutation-payload transform. `buildColumnKeyMap()` now
returns a null-prototype map, and every read site is `Object.hasOwn`-guarded —
the same belt-and-braces the DOMAIN_REGISTRY already uses.

Regression tests assert the resulting ROW KEY, not just the select string: the
Supabase double now simulates PostgREST's alias projection, since the alias is
what performs the rename server-side. All five new assertions fail against the
prior implementation.

Author: tobyhede

.changeset/eql-v3-supabase-adapter.md

@@ -8,7 +8,8 @@ now a connect-time-async factory: `await encryptedSupabaseV3(url, key)` (or
 by their Postgres domain (`information_schema.columns.domain_name`), and derives
 each column's encryption config from its domain — callers no longer pass a
 schema to `from()`. `select('*')` is supported (expanded from the introspected
-column list). A column using an EQL v3 domain this SDK version does not model
+column list, and aliased back to each declared column's JS property name so a
+property→DB rename round-trips). A column using an EQL v3 domain this SDK version does not model
 (e.g. `public.json`, `*_ord_ope`) throws at construction rather than silently
 passing through. Supplying `schemas` remains optional and adds compile-time
 types plus startup verification of the declared tables against the database.

packages/stack/__tests__/supabase-v3-select-star.test.ts

@@ -3,9 +3,32 @@ import type { EncryptionClient } from '@/encryption'
 import { encryptedTable, types } from '@/eql/v3'
 import { EncryptedQueryBuilderV3Impl } from '@/supabase/query-builder-v3'
 
-/** Minimal Supabase double that records only the select string. */
-function mockSupabase() {
+/**
+ * Supabase double that records the select string AND simulates the part of
+ * PostgREST this adapter depends on: a `alias:column::jsonb` token returns the
+ * value under `alias`, a bare `column::jsonb` (or `column`) under `column`.
+ *
+ * Simulating the rename is the point. The alias is the ONLY thing that makes a
+ * renamed column come back under its JS property name, and it is produced
+ * server-side — a double that echoes rows verbatim would assert nothing about
+ * it. `dbRows` are keyed by DB column name, exactly as Postgres stores them.
+ */
+function mockSupabase(dbRows: Record<string, unknown>[] = []) {
   const selects: string[] = []
+
+  const project = (select: string) =>
+    dbRows.map((dbRow) => {
+      const row: Record<string, unknown> = {}
+      for (const token of select.split(',')) {
+        const bare = token.trim().replace(/::jsonb$/, '')
+        const [alias, column] = bare.includes(':')
+          ? bare.split(':')
+          : [bare, bare]
+        row[alias] = dbRow[column]
+      }
+      return row
+    })
+
   // biome-ignore lint/suspicious/noExplicitAny: test double
   const qb: any = {
     select: (s: string) => {
@@ -17,7 +40,7 @@ function mockSupabase() {
       onrejected?: ((r: unknown) => unknown) | null,
     ) =>
       Promise.resolve({
-        data: [],
+        data: project(selects[0] ?? ''),
         error: null,
         count: null,
         status: 200,
@@ -27,6 +50,20 @@ function mockSupabase() {
   return { client: { from: () => qb }, selects }
 }
 
+/** Identity decrypt — this suite is about column naming, not envelopes. */
+function mockEncryptionClient() {
+  const operation = <T>(data: T) => ({
+    withLockContext: () => operation(data),
+    audit: () => operation(data),
+    then: (f?: ((v: { data: T }) => unknown) | null) =>
+      Promise.resolve({ data }).then(f),
+  })
+  return {
+    decryptModel: (m: Record<string, unknown>) => operation(m),
+    bulkDecryptModels: (m: Record<string, unknown>[]) => operation(m),
+  } as unknown as EncryptionClient
+}
+
 const users = encryptedTable('users', {
   email: types.TextSearch('email'),
   amount: types.IntegerOrd('amount'),
@@ -36,53 +73,112 @@ const users = encryptedTable('users', {
 // DB column names as introspection would report them (plaintext id/note included).
 const ALL_COLUMNS = ['id', 'email', 'amount', 'created_at', 'note']
 
+function builderFor(
+  supabase: ReturnType<typeof mockSupabase>,
+  allColumns: string[] | null = ALL_COLUMNS,
+) {
+  return new EncryptedQueryBuilderV3Impl(
+    'users',
+    users,
+    mockEncryptionClient(),
+    supabase.client,
+    allColumns,
+  )
+}
+
 describe("v3 select('*') expansion", () => {
   it('expands * to the full column list and casts encrypted columns', async () => {
     const supabase = mockSupabase()
-    const builder = new EncryptedQueryBuilderV3Impl(
-      'users',
-      users,
-      {} as EncryptionClient,
-      supabase.client,
-      ALL_COLUMNS,
+    await builderFor(supabase).select('*')
+
+    // `created_at` is aliased back to its JS property name; `id`/`note` are
+    // plaintext passthrough and `email`/`amount` are named identically in both.
+    expect(supabase.selects[0]).toBe(
+      'id, email::jsonb, amount::jsonb, createdAt:created_at::jsonb, note',
     )
+  })
 
-    await builder.select('*')
+  it('no-arg select() behaves exactly like select("*")', async () => {
+    const supabase = mockSupabase()
+    await builderFor(supabase).select()
 
     expect(supabase.selects[0]).toBe(
-      'id, email::jsonb, amount::jsonb, created_at::jsonb, note',
+      'id, email::jsonb, amount::jsonb, createdAt:created_at::jsonb, note',
     )
   })
 
-  it('no-arg select() behaves exactly like select("*")', async () => {
+  it("still throws select('*') when no column list is available", async () => {
     const supabase = mockSupabase()
-    const builder = new EncryptedQueryBuilderV3Impl(
-      'users',
-      users,
-      {} as EncryptionClient,
-      supabase.client,
-      ALL_COLUMNS,
+    const builder = builderFor(supabase, null)
+
+    expect(() => builder.select('*')).toThrow(/select\('\*'\)/)
+    // v2 regression: a bare select() takes the same path and throws the same way.
+    expect(() => builder.select()).toThrow(/select\('\*'\)/)
+  })
+})
+
+describe("REGRESSION: select('*') keys rows by JS property, not DB column", () => {
+  // A declared column whose property name differs from its DB column is the
+  // only case that can drift: synthesized columns always have property == DB
+  // name. Before the `expandAllColumns` override, `select('*')` emitted the
+  // unaliased `created_at::jsonb`, so rows came back keyed `created_at` while
+  // the declared row type promises `createdAt` — `row.createdAt` was silently
+  // `undefined` for a field TypeScript guaranteed as a Date.
+  const dbRow = {
+    id: 1,
+    email: 'a@b.com',
+    amount: 30,
+    created_at: '2026-01-02T03:04:05.000Z',
+    note: 'hi',
+  }
+
+  it('returns the renamed column under its property name', async () => {
+    const supabase = mockSupabase([dbRow])
+    const { data } = await builderFor(supabase).select('*')
+
+    expect(data![0].createdAt).toBeInstanceOf(Date)
+    expect((data![0].createdAt as Date).toISOString()).toBe(
+      '2026-01-02T03:04:05.000Z',
     )
+    expect(data![0]).not.toHaveProperty('created_at')
+  })
 
-    await builder.select()
+  it("select('*') and an explicit property select agree on row shape", async () => {
+    const star = mockSupabase([dbRow])
+    const explicit = mockSupabase([dbRow])
 
-    expect(supabase.selects[0]).toBe(
-      'id, email::jsonb, amount::jsonb, created_at::jsonb, note',
+    const { data: starData } = await builderFor(star).select('*')
+    const { data: explicitData } = await builderFor(explicit).select(
+      'id, email, amount, createdAt, note',
     )
+
+    expect(Object.keys(starData![0]).sort()).toEqual(
+      Object.keys(explicitData![0]).sort(),
+    )
+    expect(starData![0]).toEqual(explicitData![0])
   })
 
-  it("still throws select('*') when no column list is available", async () => {
+  it('leaves plaintext passthrough columns under their DB name', async () => {
+    const supabase = mockSupabase([dbRow])
+    const { data } = await builderFor(supabase).select('*')
+
+    expect(data![0].id).toBe(1)
+    expect(data![0].note).toBe('hi')
+  })
+
+  it('does not treat a DB column named like an Object.prototype member as a property', async () => {
+    // `dbToProp['constructor']` would resolve to Object.prototype.constructor on
+    // a plain object, emitting a function where a column name belongs.
     const supabase = mockSupabase()
     const builder = new EncryptedQueryBuilderV3Impl(
-      'users',
-      users,
-      {} as EncryptionClient,
+      'weird',
+      encryptedTable('weird', { email: types.TextSearch('email') }),
+      mockEncryptionClient(),
       supabase.client,
-      null,
+      ['constructor', 'toString', 'email'],
     )
+    await builder.select('*')
 
-    expect(() => builder.select('*')).toThrow(/select\('\*'\)/)
-    // v2 regression: a bare select() takes the same path and throws the same way.
-    expect(() => builder.select()).toThrow(/select\('\*'\)/)
+    expect(supabase.selects[0]).toBe('constructor, toString, email::jsonb')
   })
 })

packages/stack/src/eql/v3/table.ts

@@ -56,9 +56,19 @@ export class EncryptedTable<T extends EncryptedV3TableColumn> {
    * encrypt config and FFI by DB name — `build()` keys columns by DB name, so
    * the two only agree when property == name. This recovers the mapping that
    * `build()` discards.
+   *
+   * NULL PROTOTYPE — load-bearing. Callers index this map by a column name that
+   * ultimately comes from the database (`addJsonbCastsV3`, `filterColumnName`,
+   * the mutation transform). On a plain object literal, a column named
+   * `constructor` / `toString` / `valueOf` / `__proto__` resolves to an
+   * inherited `Object.prototype` member, which is truthy — so a *plaintext*
+   * column with such a name would be mistaken for a mapped encrypted column and
+   * its `Object.prototype` value interpolated into the emitted select string.
+   * `encryptedTable()` rejects such names as JS *properties*, but nothing
+   * constrains the DB column names a table may contain.
    */
   buildColumnKeyMap(): Record<string, string> {
-    const map: Record<string, string> = {}
+    const map = Object.create(null) as Record<string, string>
     for (const [property, builder] of Object.entries(this.columnBuilders)) {
       map[property] = builder.getName()
     }

packages/stack/src/supabase/helpers.ts

@@ -68,6 +68,24 @@ export function addJsonbCasts(
     .join(',')
 }
 
+/**
+ * Resolve a select token to its DB column name, or `undefined`.
+ *
+ * `Object.hasOwn` is required, not decorative: the token comes from the caller's
+ * select string (or, for `select('*')`, from the database's own column list).
+ * `buildColumnKeyMap()` already returns a null-prototype map, but an inherited
+ * `Object.prototype` member is truthy, so a plain-object map would let a column
+ * named `constructor` interpolate `function Object() { … }` into the emitted
+ * select string. Both guards are kept — a future refactor that drops the null
+ * prototype must not silently reopen the hole.
+ */
+function lookupDbName(
+  propToDb: Record<string, string>,
+  token: string,
+): string | undefined {
+  return Object.hasOwn(propToDb, token) ? propToDb[token] : undefined
+}
+
 /**
  * Parse a Supabase select string and add `::jsonb` casts to encrypted EQL v3
  * columns, resolving JS property names to DB column names via PostgREST
@@ -106,14 +124,15 @@ export function addJsonbCastsV3(
       )
       if (aliasMatch) {
         const [, alias, name] = aliasMatch
-        const db = propToDb[name] ?? (dbNames.has(name) ? name : undefined)
+        const db =
+          lookupDbName(propToDb, name) ?? (dbNames.has(name) ? name : undefined)
         if (db !== undefined) {
           return `${leadingWhitespace}${alias}:${db}::jsonb`
         }
         return col
       }
 
-      const db = propToDb[trimmed]
+      const db = lookupDbName(propToDb, trimmed)
       if (db !== undefined) {
         return db === trimmed
           ? `${leadingWhitespace}${trimmed}::jsonb`

packages/stack/src/supabase/query-builder-v3.ts

@@ -79,6 +79,11 @@ export class EncryptedQueryBuilderV3Impl<
   private v3Table: AnyV3Table
   /** JS property name → DB column name, for every encrypted column. */
   private propToDb: Record<string, string>
+  /** DB column name → JS property name — the inverse of {@link propToDb}, used
+   * to expand `select('*')` back into property names. Null prototype: a DB
+   * column literally named `constructor` / `toString` would otherwise resolve
+   * to an inherited `Object.prototype` member and be emitted as a select token. */
+  private dbToProp: Record<string, string>
   /** Built column schemas keyed by DB column name (for `cast_as`). */
   private columnSchemas: Record<string, ColumnSchema>
   /** Column builders keyed by BOTH property name and DB name. */
@@ -106,6 +111,11 @@ export class EncryptedQueryBuilderV3Impl<
     this.propToDb = table.buildColumnKeyMap()
     this.columnSchemas = table.build().columns
 
+    this.dbToProp = Object.create(null) as Record<string, string>
+    for (const [property, dbName] of Object.entries(this.propToDb)) {
+      this.dbToProp[dbName] = property
+    }
+
     this.v3Columns = {}
     for (const [property, builder] of Object.entries(table.columnBuilders)) {
       if (builder instanceof EncryptedV3Column) {
@@ -129,22 +139,48 @@ export class EncryptedQueryBuilderV3Impl<
     return this.v3Columns as unknown as Record<string, BuildableQueryColumn>
   }
 
+  /** Resolve a JS property name to its DB column name. `Object.hasOwn` guards
+   * the inherited-member hazard described on {@link EncryptedTable.buildColumnKeyMap}. */
+  private dbNameFor(name: string): string {
+    return Object.hasOwn(this.propToDb, name) ? this.propToDb[name] : name
+  }
+
   protected override filterColumnName(column: string): string {
-    return this.propToDb[column] ?? column
+    return this.dbNameFor(column)
   }
 
   protected override buildSelectString(): string | null {
     if (this.selectColumns === null) return null
     return addJsonbCastsV3(this.selectColumns, this.propToDb)
   }
 
+  /**
+   * Expand the introspected column list (DB names) into JS property names.
+   *
+   * Load-bearing for `select('*')` on a DECLARED table that renames a column.
+   * `addJsonbCastsV3` only emits the `prop:db_name::jsonb` alias — the thing
+   * that makes PostgREST return the column under its property name — when the
+   * token it sees is a property name. Feeding it the raw DB name instead takes
+   * the unaliased `dbNames.has(...)` branch, so the row comes back keyed
+   * `created_at` while the declared row type promises `createdAt`, silently
+   * yielding `undefined` for a field TypeScript guarantees.
+   *
+   * A DB column with no encrypted builder (plaintext passthrough, and every
+   * synthesized column, where property == DB name) maps to itself.
+   */
+  protected override expandAllColumns(columns: string[]): string[] {
+    return columns.map((dbName) =>
+      Object.hasOwn(this.dbToProp, dbName) ? this.dbToProp[dbName] : dbName,
+    )
+  }
+
   /** v3 domains are plain jsonb — send the raw payload, keyed by DB name. */
   protected override transformEncryptedMutationModel(
     model: Record<string, unknown>,
   ): Record<string, unknown> {
     const out: Record<string, unknown> = {}
     for (const [key, value] of Object.entries(model)) {
-      out[this.propToDb[key] ?? key] = value
+      out[this.dbNameFor(key)] = value
     }
     return out
   }

packages/stack/src/supabase/query-builder.ts

@@ -104,14 +104,25 @@ export class EncryptedQueryBuilderImpl<
           "encryptedSupabase does not support select('*'). Please list columns explicitly so that encrypted columns can be cast with ::jsonb.",
         )
       }
-      this.selectColumns = this.allColumns.join(', ')
+      this.selectColumns = this.expandAllColumns(this.allColumns).join(', ')
     } else {
       this.selectColumns = columns
     }
     this.selectOptions = options
     return this
   }
 
+  /**
+   * Turn the introspected column list (DB names) into select tokens. The base
+   * returns them unchanged — v2 never supplies a column list, so this is dead
+   * for v2. The v3 dialect overrides it to emit JS property names, which is
+   * what makes `addJsonbCastsV3` alias a renamed column back to its property
+   * (`createdAt:created_at::jsonb`) rather than returning it under its DB name.
+   */
+  protected expandAllColumns(columns: string[]): string[] {
+    return columns
+  }
+
   insert(
     data: Partial<T> | Partial<T>[],
     options?: {