@pikku/kysely 0.13.23 → 0.13.27

package/src/classification-plugin.test.ts

@@ -1,265 +0,0 @@
-import { describe, test, before } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  CamelCasePlugin,
-  DummyDriver,
-  Kysely,
-  PostgresAdapter,
-  PostgresIntrospector,
-  PostgresQueryCompiler,
-  type QueryResult,
-  type UnknownRow,
-} from 'kysely'
-import type { ClassificationManifest } from '@pikku/core/classification'
-import { deriveKEK, generateKEKSalt } from '@pikku/core/crypto-utils'
-import {
-  ClassificationCrypto,
-  type KEKResolver,
-} from './classification-crypto.js'
-import { createClassificationPlugin } from './classification-plugin.js'
-
-interface TestDB {
-  users: {
-    id: string
-    email: string
-    ssn: string
-    tokenHash: string
-    recovery: string
-  }
-}
-
-const manifest: ClassificationManifest = {
-  version: 1,
-  tables: {
-    users: {
-      id: { classification: 'public', anonymize_strategy: null },
-      email: { classification: 'pii', anonymize_strategy: 'fake:email' },
-      ssn: {
-        classification: 'secret',
-        anonymize_strategy: null,
-        form: 'wrapped',
-      },
-      token_hash: {
-        classification: 'secret',
-        anonymize_strategy: null,
-        form: 'hashed',
-      },
-      recovery: {
-        classification: 'secret',
-        anonymize_strategy: null,
-        form: 'wrapped',
-        keyId: 'recovery-codes',
-      },
-    },
-  },
-}
-
-let crypto: ClassificationCrypto
-
-/** A key source with nothing to give, the way an unconfigured one behaves. */
-class NoKeyError extends Error {}
-const noKey: KEKResolver = async () => {
-  throw new NoKeyError('no key for this column')
-}
-
-before(async () => {
-  const keks = new Map<string, Promise<CryptoKey>>()
-  const resolveKEK: KEKResolver = async (keyId) => {
-    let kek = keks.get(keyId)
-    if (!kek) {
-      kek = deriveKEK(
-        'a-passphrase-long-enough-to-be-real-key-material',
-        generateKEKSalt()
-      )
-      keks.set(keyId, kek)
-    }
-    return { kek: await kek, keyVersion: 1 }
-  }
-  crypto = new ClassificationCrypto({ resolveKEK })
-})
-
-const plugin = () => createClassificationPlugin({ manifest, crypto })
-
-const selectFrom = (tables: string[]) => ({
-  kind: 'SelectQueryNode',
-  from: {
-    kind: 'FromNode',
-    froms: tables.map((table) => ({
-      kind: 'TableNode',
-      table: {
-        kind: 'SchemableIdentifierNode',
-        identifier: { kind: 'IdentifierNode', name: table },
-      },
-    })),
-  },
-})
-
-const readRows = async (
-  rows: UnknownRow[],
-  tables: string[] = ['users']
-): Promise<UnknownRow[]> => {
-  const p = plugin()
-  const queryId = {} as { queryId: string }
-  p.transformQuery({ queryId, node: selectFrom(tables) } as any)
-  const out = await p.transformResult({
-    queryId,
-    result: { rows } as QueryResult<UnknownRow>,
-  } as any)
-  return out.rows as UnknownRow[]
-}
-
-const writeDb = () =>
-  new Kysely<TestDB>({
-    dialect: {
-      createAdapter: () => new PostgresAdapter(),
-      createDriver: () => new DummyDriver(),
-      createIntrospector: (db) => new PostgresIntrospector(db),
-      createQueryCompiler: () => new PostgresQueryCompiler(),
-    },
-    plugins: [new CamelCasePlugin(), plugin()],
-  })
-
-describe('reading classified columns', () => {
-  test('a wrapped column decrypts transparently', async () => {
-    const ssn = await crypto.encryptColumn('default', '123-45-6789')
-    const [row] = await readRows([{ id: 'u1', ssn }])
-    assert.equal(row!.ssn, '123-45-6789')
-  })
-
-  test('a column with its own keyId decrypts under that key', async () => {
-    const recovery = await crypto.encryptColumn('recovery-codes', 'abc-def')
-    const [row] = await readRows([{ id: 'u1', recovery }])
-    assert.equal(row!.recovery, 'abc-def')
-  })
-
-  test('plain and pii columns are left alone', async () => {
-    const [row] = await readRows([{ id: 'u1', email: 'a@b.c' }])
-    assert.equal(row!.email, 'a@b.c')
-    assert.equal(row!.id, 'u1')
-  })
-
-  test('a hashed column is never decrypted — the hash is the lookup key', async () => {
-    const tokenHash = 'sha256:deadbeef'
-    const [row] = await readRows([{ id: 'u1', tokenHash }])
-    assert.equal(row!.tokenHash, tokenHash)
-  })
-
-  test('a null wrapped column stays null', async () => {
-    const [row] = await readRows([{ id: 'u1', ssn: null }])
-    assert.equal(row!.ssn, null)
-  })
-
-  test('columns of a table the query never touched are left alone', async () => {
-    const [row] = await readRows([{ ssn: 'not-an-envelope' }], ['audit'])
-    assert.equal(row!.ssn, 'not-an-envelope')
-  })
-
-  test('plain and hashed columns still read without any key at all', async () => {
-    const p = createClassificationPlugin({
-      manifest,
-      crypto: new ClassificationCrypto({ resolveKEK: noKey }),
-    })
-    const queryId = {} as { queryId: string }
-    p.transformQuery({ queryId, node: selectFrom(['users']) } as any)
-
-    // A sign-in that checks a token hash has to work on a deployment whose key
-    // source is unavailable, so a query touching no wrapped column must never
-    // reach the resolver at all.
-    const out = await p.transformResult({
-      queryId,
-      result: {
-        rows: [{ id: 'u1', email: 'a@b.c', tokenHash: 'sha256:deadbeef' }],
-      } as QueryResult<UnknownRow>,
-    } as any)
-
-    assert.deepEqual(out.rows[0], {
-      id: 'u1',
-      email: 'a@b.c',
-      tokenHash: 'sha256:deadbeef',
-    })
-  })
-
-  test('a wrapped column read without its key fails loudly', async () => {
-    const stored = await crypto.encryptColumn('default', 'ssn')
-
-    const p = createClassificationPlugin({
-      manifest,
-      crypto: new ClassificationCrypto({ resolveKEK: noKey }),
-    })
-    const queryId = {} as { queryId: string }
-    p.transformQuery({ queryId, node: selectFrom(['users']) } as any)
-
-    await assert.rejects(
-      () =>
-        p.transformResult({
-          queryId,
-          result: {
-            rows: [{ id: 'u1', ssn: stored }],
-          } as QueryResult<UnknownRow>,
-        } as any),
-      (error: unknown) => error instanceof NoKeyError,
-      'handing back an unopened envelope as if it were the value would be worse'
-    )
-  })
-
-  test('decrypts under CamelCasePlugin, which renames the column first', async () => {
-    const value = await crypto.encryptColumn('default', 'x')
-    const [snake] = await readRows([{ token_hash: 'h', ssn: value }])
-    assert.equal(snake!.ssn, 'x')
-  })
-})
-
-describe('writing classified columns', () => {
-  test('plaintext into a wrapped column is refused', async () => {
-    await assert.rejects(
-      () =>
-        writeDb()
-          .insertInto('users')
-          .values({ id: 'u1', ssn: '123-45-6789' as never })
-          .execute(),
-      /ssn/,
-      'a forgotten encryption must not reach the database'
-    )
-  })
-
-  test('a real envelope is accepted', async () => {
-    const ssn = await crypto.encryptColumn('default', '123-45-6789')
-    await writeDb()
-      .insertInto('users')
-      .values({ id: 'u1', ssn: ssn as never })
-      .execute()
-  })
-
-  test('an update with plaintext is refused too', async () => {
-    await assert.rejects(
-      () =>
-        writeDb()
-          .updateTable('users')
-          .set({ ssn: 'oops' as never })
-          .where('id', '=', 'u1')
-          .execute(),
-      /ssn/
-    )
-  })
-
-  test('unclassified columns are written without complaint', async () => {
-    await writeDb()
-      .insertInto('users')
-      .values({ id: 'u1', email: 'a@b.c' })
-      .execute()
-  })
-
-  test('a hashed column takes its hash as-is', async () => {
-    await writeDb()
-      .insertInto('users')
-      .values({ id: 'u1', tokenHash: 'sha256:deadbeef' as never })
-      .execute()
-  })
-
-  test('a null wrapped column is allowed', async () => {
-    await writeDb()
-      .insertInto('users')
-      .values({ id: 'u1', ssn: null as never })
-      .execute()
-  })
-})

package/src/classification-plugin.ts

@@ -1,249 +0,0 @@
-import type { KyselyPlugin, RootOperationNode, UnknownRow } from 'kysely'
-import type {
-  ClassificationManifest,
-  ColumnForm,
-} from '@pikku/core/classification'
-import {
-  DEFAULT_KEY_ID,
-  isColumnEnvelope,
-  type ClassificationCrypto,
-} from './classification-crypto.js'
-
-/** What the manifest says about one column, reduced to what the query path needs. */
-interface EncryptedColumn {
-  form: Extract<ColumnForm, 'wrapped' | 'sealed'>
-  keyId: string
-}
-
-interface ResolvedManifest {
-  /** `table.column` → column, for the exact per-query resolution. */
-  qualified: Map<string, EncryptedColumn>
-  /** `column` → column, the fallback for when the query's tables say nothing. */
-  flat: Map<string, EncryptedColumn>
-}
-
-function snakeToCamel(name: string): string {
-  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
-}
-
-/**
- * Flatten the manifest into a table-qualified lookup plus a bare column-name
- * fallback, both indexed under snake_case and camelCase so the plugin works on
- * either side of `CamelCasePlugin` in the array.
- *
- * A bare name two tables disagree about is dropped rather than letting the last
- * one win: on a joined query it could carry either, and guessing wrong means
- * either handing back ciphertext or refusing a legitimate write. The qualified
- * map still resolves it whenever the query names its tables.
- */
-function buildManifest(manifest: ClassificationManifest): ResolvedManifest {
-  const qualified = new Map<string, EncryptedColumn>()
-  const flat = new Map<string, EncryptedColumn>()
-  const ambiguous = new Set<string>()
-
-  const assignFlat = (key: string, column: EncryptedColumn) => {
-    const existing = flat.get(key)
-    if (existing && existing.keyId !== column.keyId) {
-      ambiguous.add(key)
-      return
-    }
-    flat.set(key, column)
-  }
-
-  for (const [table, columns] of Object.entries(manifest.tables)) {
-    for (const [name, classification] of Object.entries(columns)) {
-      const form = classification.form
-      if (form !== 'wrapped' && form !== 'sealed') continue
-
-      const column: EncryptedColumn = {
-        form,
-        keyId: classification.keyId ?? DEFAULT_KEY_ID,
-      }
-      const camel = snakeToCamel(name)
-      qualified.set(`${table}.${name}`, column)
-      qualified.set(`${table}.${camel}`, column)
-      assignFlat(name, column)
-      assignFlat(camel, column)
-    }
-  }
-
-  for (const key of ambiguous) flat.delete(key)
-  return { qualified, flat }
-}
-
-function collectQueryTables(node: unknown, out: Set<string>): void {
-  if (!node || typeof node !== 'object') return
-
-  const op = node as {
-    kind?: string
-    table?: { identifier?: { name?: string } }
-  }
-  if (op.kind === 'TableNode') {
-    const name = op.table?.identifier?.name
-    if (typeof name === 'string' && name.length > 0) out.add(name)
-  }
-
-  for (const value of Object.values(node)) {
-    if (Array.isArray(value)) {
-      for (const item of value) collectQueryTables(item, out)
-    } else {
-      collectQueryTables(value, out)
-    }
-  }
-}
-
-function lookupColumn(
-  manifest: ResolvedManifest,
-  tables: readonly string[],
-  column: string
-): EncryptedColumn | undefined {
-  let matched: EncryptedColumn | undefined
-  for (const table of tables) {
-    const found = manifest.qualified.get(`${table}.${column}`)
-    if (!found) continue
-    if (matched && matched.keyId !== found.keyId) {
-      return manifest.flat.get(column)
-    }
-    matched = found
-  }
-  return matched ?? manifest.flat.get(column)
-}
-
-/**
- * The column names an insert or update writes, paired with the values going
- * into them.
- *
- * Only literal values are collected. A raw expression or a sub-select is
- * something this plugin cannot read and must not guess at, so it is skipped —
- * the guard's job is to catch a plaintext string a call site forgot to encrypt,
- * not to prove every write correct.
- */
-function collectWrittenValues(node: unknown): Array<[string, unknown]> {
-  const written: Array<[string, unknown]> = []
-
-  const visit = (current: unknown): void => {
-    if (!current || typeof current !== 'object') return
-    const op = current as {
-      kind?: string
-      column?: { column?: { name?: string } }
-      value?: { kind?: string; value?: unknown }
-      columns?: Array<{ column?: { name?: string } }>
-      values?: unknown
-    }
-
-    if (op.kind === 'ColumnUpdateNode') {
-      const name = op.column?.column?.name
-      if (typeof name === 'string' && op.value?.kind === 'ValueNode') {
-        written.push([name, op.value.value])
-      }
-    }
-
-    if (op.kind === 'InsertQueryNode' && Array.isArray(op.columns)) {
-      const names = op.columns.map((c) => c.column?.name)
-      const rows = (op.values as { kind?: string; values?: unknown[] })?.values
-      if (Array.isArray(rows)) {
-        for (const row of rows) {
-          const list = (row as { kind?: string; values?: unknown[] })?.values
-          if (!Array.isArray(list)) continue
-          list.forEach((value, index) => {
-            const name = names[index]
-            if (typeof name !== 'string') return
-            const unwrapped =
-              value && typeof value === 'object' && 'kind' in value
-                ? (value as { kind?: string; value?: unknown }).kind ===
-                  'ValueNode'
-                  ? (value as { value?: unknown }).value
-                  : undefined
-                : value
-            if (unwrapped !== undefined) written.push([name, unwrapped])
-          })
-        }
-      }
-    }
-
-    for (const value of Object.values(current)) {
-      if (Array.isArray(value)) {
-        for (const item of value) visit(item)
-      } else {
-        visit(value)
-      }
-    }
-  }
-
-  visit(node)
-  return written
-}
-
-export interface CreateClassificationPluginOptions {
-  manifest: ClassificationManifest
-  crypto: ClassificationCrypto
-}
-
-/**
- * Make a column's at-rest form a property of the column rather than of the
- * developer's memory.
- *
- * Reads are transparent: a `wrapped` column comes back decrypted, so
- * application code never sees an envelope. `hashed` and `plain` columns are
- * untouched, which is what keeps the rest of the schema queryable.
- *
- * Writes are *guarded* rather than transformed, and the reason is Kysely's
- * shape, not a preference: `transformQuery` is synchronous and WebCrypto is
- * not, so a plugin cannot encrypt on the way in. Encrypting at the call site
- * and letting a forgotten call slip through silently is the failure this
- * design exists to prevent, so the guard refuses any plaintext heading for a
- * `wrapped` or `sealed` column. Values are produced with
- * `ClassificationCrypto.encryptColumn`.
- *
- * A `sealed` column is never decrypted on the way out — the application holds
- * only the public half by definition, so returning it as stored is correct
- * rather than a gap.
- */
-export function createClassificationPlugin(
-  options: CreateClassificationPluginOptions
-): KyselyPlugin {
-  const manifest = buildManifest(options.manifest)
-  const queryTables = new WeakMap<object, readonly string[]>()
-
-  return {
-    transformQuery(args) {
-      const tables = new Set<string>()
-      collectQueryTables(args.node as RootOperationNode, tables)
-      queryTables.set(args.queryId, [...tables])
-
-      for (const [name, value] of collectWrittenValues(args.node)) {
-        if (value === null || value === undefined) continue
-        const column = lookupColumn(manifest, [...tables], name)
-        if (!column) continue
-        if (!isColumnEnvelope(value)) {
-          throw new Error(
-            `Refusing to write plaintext into "${name}", which is classified ${column.form}. ` +
-              `Produce the value with ClassificationCrypto.encryptColumn() before writing it.`
-          )
-        }
-      }
-
-      return args.node
-    },
-
-    async transformResult(args) {
-      const tables = queryTables.get(args.queryId) ?? []
-      const rows: UnknownRow[] = []
-
-      for (const row of args.result.rows as UnknownRow[]) {
-        let next: UnknownRow | undefined
-        for (const [name, value] of Object.entries(row)) {
-          if (value === null || value === undefined) continue
-          const column = lookupColumn(manifest, tables, name)
-          if (!column || column.form !== 'wrapped') continue
-          if (!isColumnEnvelope(value)) continue
-          next ??= { ...row }
-          next[name] = await options.crypto.decryptColumn(value)
-        }
-        rows.push(next ?? row)
-      }
-
-      return { ...args.result, rows }
-    },
-  }
-}

package/src/coercion-plugin.test.ts

@@ -1,160 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import type { QueryResult, UnknownRow } from 'kysely'
-import { createCoercionPlugin, type CoercionMap } from './coercion-plugin.js'
-
-function selectFrom(...tables: string[]) {
-  return {
-    kind: 'SelectQueryNode',
-    from: {
-      kind: 'FromNode',
-      froms: tables.map((table) => ({
-        kind: 'TableNode',
-        table: {
-          kind: 'SchemableIdentifierNode',
-          identifier: { kind: 'IdentifierNode', name: table },
-        },
-      })),
-    },
-  }
-}
-
-const runTransform = async (
-  map: CoercionMap,
-  rows: UnknownRow[],
-  node?: unknown
-): Promise<UnknownRow[]> => {
-  const plugin = createCoercionPlugin({ map })
-  const queryId = {} as { queryId: string }
-  if (node !== undefined) {
-    plugin.transformQuery({ node, queryId } as any)
-  }
-  const result = { rows } as QueryResult<UnknownRow>
-  const out = await plugin.transformResult({ result, queryId } as any)
-  return out.rows as UnknownRow[]
-}
-
-describe('createCoercionPlugin', () => {
-  test('transformQuery passes the node through untouched', () => {
-    const plugin = createCoercionPlugin({ map: {} })
-    const node = selectFrom('users') as any
-    assert.equal(
-      plugin.transformQuery({ node, queryId: { queryId: 'x' } } as any),
-      node
-    )
-  })
-
-  test('coerces date columns from ISO strings to Date', async () => {
-    const [row] = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: '2026-06-26T00:00:00.000Z' },
-    ])
-    assert.ok(row!.created_at instanceof Date)
-    assert.equal(
-      (row!.created_at as Date).toISOString(),
-      '2026-06-26T00:00:00.000Z'
-    )
-  })
-
-  test('leaves unparseable date strings untouched', async () => {
-    const [row] = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: 'not-a-date' },
-    ])
-    assert.equal(row!.created_at, 'not-a-date')
-  })
-
-  test('coerces bool columns from 0/1 numbers and bigints', async () => {
-    const rows = await runTransform(
-      { users: { is_active: 'bool', has_pets: 'bool' } },
-      [{ is_active: 1, has_pets: 0n }]
-    )
-    assert.equal(rows[0]!.is_active, true)
-    assert.equal(rows[0]!.has_pets, false)
-  })
-
-  test('parses json columns and tolerates invalid json', async () => {
-    const rows = await runTransform(
-      { users: { meta: 'json', broken: 'json' } },
-      [{ meta: '{"a":1}', broken: '{bad' }]
-    )
-    assert.deepEqual(rows[0]!.meta, { a: 1 })
-    assert.equal(rows[0]!.broken, '{bad')
-  })
-
-  test('passes through null values and unmapped columns', async () => {
-    const rows = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: null, name: 'leave me' },
-    ])
-    assert.equal(rows[0]!.created_at, null)
-    assert.equal(rows[0]!.name, 'leave me')
-  })
-
-  test('matches both snake_case and camelCase column names', async () => {
-    const rows = await runTransform({ users: { created_at: 'date' } }, [
-      { createdAt: '2026-06-26T00:00:00.000Z' },
-    ])
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-
-  test('leaves columns ambiguous across tables uncoerced', async () => {
-    const rows = await runTransform(
-      { users: { value: 'json' }, events: { value: 'bool' } },
-      [{ value: '{"a":1}' }]
-    )
-    assert.equal(rows[0]!.value, '{"a":1}')
-  })
-
-  test('still coerces columns that agree across tables', async () => {
-    const rows = await runTransform(
-      { users: { active: 'bool' }, events: { active: 'bool' } },
-      [{ active: 1 }]
-    )
-    assert.equal(rows[0]!.active, true)
-  })
-
-  test('uses table-qualified coercions when names collide', async () => {
-    const map: CoercionMap = {
-      users: { settings: 'json' },
-      posts: { settings: 'bool' },
-    }
-    const fromUsers = await runTransform(
-      map,
-      [{ settings: '{"theme":"dark"}' }],
-      selectFrom('users')
-    )
-    assert.deepEqual(fromUsers[0]!.settings, { theme: 'dark' })
-
-    const fromPosts = await runTransform(
-      map,
-      [{ settings: 1 }],
-      selectFrom('posts')
-    )
-    assert.equal(fromPosts[0]!.settings, true)
-  })
-
-  test('table-qualified lookup matches camelCase result columns too', async () => {
-    const rows = await runTransform(
-      { users: { created_at: 'date' }, jobs: { created_at: 'json' } },
-      [{ createdAt: '2026-06-26T00:00:00.000Z' }],
-      selectFrom('users')
-    )
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-
-  test('a join whose tables disagree leaves the column uncoerced', async () => {
-    const rows = await runTransform(
-      { users: { value: 'json' }, events: { value: 'bool' } },
-      [{ value: '{"a":1}' }],
-      selectFrom('users', 'events')
-    )
-    assert.equal(rows[0]!.value, '{"a":1}')
-  })
-
-  test('falls back to flat keys when the query names no known table', async () => {
-    const rows = await runTransform(
-      { users: { created_at: 'date' } },
-      [{ createdAt: '2026-01-02T03:04:05.000Z' }],
-      selectFrom('unrelated')
-    )
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-})