@pikku/kysely 0.13.24 → 0.13.27

package/src/classification-crypto.test.ts

@@ -1,143 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { deriveKEK, generateKEKSalt } from '@pikku/core/crypto-utils'
-import {
-  ClassificationCrypto,
-  DEFAULT_KEY_ID,
-  isColumnEnvelope,
-  parseColumnEnvelope,
-  type KEKResolver,
-} from './classification-crypto.js'
-
-const passphrase = 'a-passphrase-long-enough-to-be-real-key-material'
-
-/**
- * A resolver that derives a KEK per keyId and remembers it.
- *
- * Caching is the part under test as much as the derivation: `resolveKEK` is
- * called per operation, and a resolver that re-derived every time would pay
- * key stretching on every row.
- */
-const testResolver = (): KEKResolver => {
-  const keks = new Map<string, Promise<CryptoKey>>()
-  return async (keyId) => {
-    let kek = keks.get(keyId)
-    if (!kek) {
-      kek = deriveKEK(passphrase, generateKEKSalt())
-      keks.set(keyId, kek)
-    }
-    return { kek: await kek, keyVersion: 1 }
-  }
-}
-
-const staticCrypto = async () =>
-  new ClassificationCrypto({ resolveKEK: testResolver() })
-
-describe('column envelope', () => {
-  test('round-trips a value through the default key', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn(DEFAULT_KEY_ID, 'hunter2')
-    assert.equal(await crypto.decryptColumn(envelope), 'hunter2')
-  })
-
-  test('the stored envelope names the key that protects it', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn('credentials', 'shh')
-    const parsed = parseColumnEnvelope(envelope)
-    assert.equal(parsed?.keyId, 'credentials')
-    assert.equal(parsed?.keyVersion, 1)
-  })
-
-  test('a value is not stored in the clear', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn(DEFAULT_KEY_ID, 'hunter2')
-    assert.ok(!envelope.includes('hunter2'))
-  })
-
-  test('every value gets its own DEK', async () => {
-    const crypto = await staticCrypto()
-    const a = parseColumnEnvelope(
-      await crypto.encryptColumn(DEFAULT_KEY_ID, 'same')
-    )
-    const b = parseColumnEnvelope(
-      await crypto.encryptColumn(DEFAULT_KEY_ID, 'same')
-    )
-    assert.notEqual(a?.wrappedDek, b?.wrappedDek)
-    assert.notEqual(a?.ciphertext, b?.ciphertext)
-  })
-
-  test('round-trips non-string values', async () => {
-    const crypto = await staticCrypto()
-    const value = { card: '4242', meta: [1, 2, 3] }
-    const envelope = await crypto.encryptColumn(DEFAULT_KEY_ID, value)
-    assert.deepEqual(await crypto.decryptColumn(envelope), value)
-  })
-
-  test('plaintext is not mistaken for an envelope', () => {
-    assert.equal(isColumnEnvelope('hunter2'), false)
-    assert.equal(isColumnEnvelope(''), false)
-    assert.equal(parseColumnEnvelope('hunter2'), null)
-  })
-
-  test('a keyId containing the separator survives the round trip', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn('tenant.42', 'x')
-    assert.equal(parseColumnEnvelope(envelope)?.keyId, 'tenant.42')
-    assert.equal(await crypto.decryptColumn(envelope), 'x')
-  })
-})
-
-describe('KEK scoping', () => {
-  test('different keyIds derive different KEKs from one passphrase', async () => {
-    const resolve = testResolver()
-    const a = await resolve(DEFAULT_KEY_ID)
-    const b = await resolve('credentials')
-    assert.notEqual(a.kek, b.kek)
-  })
-
-  test('a value written under one keyId does not open under another', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn('credentials', 'shh')
-    const forged = envelope.replace(
-      /^(pikku1\.)[^.]+/,
-      `$1${Buffer.from('notes').toString('base64url')}`
-    )
-    await assert.rejects(() => crypto.decryptColumn(forged))
-  })
-
-  test('the same keyId resolves to the same KEK, so derivation is paid once', async () => {
-    const resolve = testResolver()
-    assert.equal(
-      (await resolve(DEFAULT_KEY_ID)).kek,
-      (await resolve(DEFAULT_KEY_ID)).kek
-    )
-  })
-
-  test('rewrapping moves a value to a new key without touching the ciphertext', async () => {
-    const crypto = await staticCrypto()
-    const envelope = await crypto.encryptColumn(DEFAULT_KEY_ID, 'portable')
-    const before = parseColumnEnvelope(envelope)
-
-    const rewrapped = await crypto.rewrapColumn(envelope, 'credentials')
-    const after = parseColumnEnvelope(rewrapped)
-
-    assert.equal(after?.keyId, 'credentials')
-    assert.equal(
-      after?.ciphertext,
-      before?.ciphertext,
-      'rewrap must re-wrap the DEK, not re-encrypt the value'
-    )
-    assert.notEqual(after?.wrappedDek, before?.wrappedDek)
-    assert.equal(await crypto.decryptColumn(rewrapped), 'portable')
-  })
-
-  test('a resolver may hand back a KEK it derived any way it likes', async () => {
-    const kek = await deriveKEK(passphrase, generateKEKSalt())
-    const crypto = new ClassificationCrypto({
-      resolveKEK: async () => ({ kek, keyVersion: 7 }),
-    })
-    const envelope = await crypto.encryptColumn('anything', 'v')
-    assert.equal(parseColumnEnvelope(envelope)?.keyVersion, 7)
-    assert.equal(await crypto.decryptColumn(envelope), 'v')
-  })
-})

package/src/classification-crypto.ts

@@ -1,163 +0,0 @@
-import {
-  envelopeDecrypt,
-  envelopeEncrypt,
-  envelopeRewrap,
-} from '@pikku/core/crypto-utils'
-import { DEFAULT_KEY_ID } from '@pikku/core/classification'
-import type { WrappedValue } from '@pikku/core/classification'
-
-/**
- * The key a column is protected by when its classification names none. A
- * deployment that never scopes its keys stores this id in every row and still
- * gets the scoping seam for free.
- *
- * Re-exported from core rather than declared again: the same constant decides
- * which record `initialize` mints and which one a stored envelope names, and
- * two copies of it would only ever be found to disagree by a row that could
- * not be opened.
- */
-export { DEFAULT_KEY_ID }
-
-const ENVELOPE_PREFIX = 'pikku1'
-
-/** The parts of a stored envelope, as they came off the column. */
-export interface ColumnEnvelope {
-  keyId: string
-  keyVersion: number
-  wrappedDek: string
-  ciphertext: string
-}
-
-/**
- * A KEK for one `keyId`, plus the version it was derived at.
- *
- * The version is the resolver's to report rather than the caller's to ask for:
- * on a write it stamps the row, and on a read the row already carries the
- * version the value was written under.
- */
-export interface ResolvedKEK {
-  kek: CryptoKey
-  keyVersion: number
-}
-
-/**
- * Maps a `keyId` — and, when reading, the version the row was written under —
- * to the KEK that opens it.
- *
- * This is the seam the whole design turns on. An unlock gate, a per-tenant
- * lookup or a KMS call all replace this one function without reshaping anything
- * that calls it.
- */
-export type KEKResolver = (
-  keyId: string,
-  keyVersion?: number
-) => Promise<ResolvedKEK>
-
-const encodePart = (value: string): string =>
-  Buffer.from(value, 'utf8').toString('base64url')
-
-const decodePart = (value: string): string =>
-  Buffer.from(value, 'base64url').toString('utf8')
-
-const serializeEnvelope = (envelope: ColumnEnvelope): WrappedValue =>
-  [
-    ENVELOPE_PREFIX,
-    encodePart(envelope.keyId),
-    String(envelope.keyVersion),
-    envelope.wrappedDek,
-    envelope.ciphertext,
-  ].join('.') as WrappedValue
-
-/**
- * Read a stored envelope, or null when the value is not one.
- *
- * Every part is base64url except the version, so `.` cannot occur inside a part
- * and a fixed split is unambiguous — a `keyId` may contain dots.
- */
-export const parseColumnEnvelope = (value: unknown): ColumnEnvelope | null => {
-  if (typeof value !== 'string') return null
-  const parts = value.split('.')
-  if (parts.length !== 5 || parts[0] !== ENVELOPE_PREFIX) return null
-
-  const [, encodedKeyId, rawVersion, wrappedDek, ciphertext] = parts
-  const keyVersion = Number(rawVersion)
-  if (!Number.isInteger(keyVersion) || !wrappedDek || !ciphertext) return null
-
-  try {
-    return {
-      keyId: decodePart(encodedKeyId!),
-      keyVersion,
-      wrappedDek,
-      ciphertext,
-    }
-  } catch {
-    return null
-  }
-}
-
-export const isColumnEnvelope = (value: unknown): boolean =>
-  parseColumnEnvelope(value) !== null
-
-export interface ClassificationCryptoOptions {
-  resolveKEK: KEKResolver
-}
-
-/**
- * Envelope encryption for a single classified column.
- *
- * Unlike `KyselySecretService`, which owns its table and can afford a column
- * per envelope part, a classified column is one column in someone else's table.
- * So the envelope is self-describing: the `keyId` and `keyVersion` travel in
- * the value, which is what lets a row record the key that protects it without
- * a schema change to every table that has a secret in it.
- */
-export class ClassificationCrypto {
-  private readonly resolveKEK: KEKResolver
-
-  constructor(options: ClassificationCryptoOptions) {
-    this.resolveKEK = options.resolveKEK
-  }
-
-  async encryptColumn(keyId: string, value: unknown): Promise<WrappedValue> {
-    const { kek, keyVersion } = await this.resolveKEK(keyId)
-    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, value)
-    return serializeEnvelope({
-      keyId,
-      keyVersion,
-      wrappedDek: wrappedDEK,
-      ciphertext,
-    })
-  }
-
-  async decryptColumn<T = unknown>(value: unknown): Promise<T> {
-    const envelope = parseColumnEnvelope(value)
-    if (!envelope) {
-      throw new Error('Value is not a pikku column envelope')
-    }
-    const { kek } = await this.resolveKEK(envelope.keyId, envelope.keyVersion)
-    return envelopeDecrypt<T>(kek, envelope.ciphertext, envelope.wrappedDek)
-  }
-
-  /**
-   * Move a value to another key by re-wrapping its DEK. The ciphertext is
-   * untouched, so the cost is a constant per row rather than proportional to
-   * the value — the property that makes rescoping and rotation affordable.
-   */
-  async rewrapColumn(value: unknown, newKeyId: string): Promise<WrappedValue> {
-    const envelope = parseColumnEnvelope(value)
-    if (!envelope) {
-      throw new Error('Value is not a pikku column envelope')
-    }
-    const { kek: oldKEK } = await this.resolveKEK(
-      envelope.keyId,
-      envelope.keyVersion
-    )
-    const { kek: newKEK, keyVersion } = await this.resolveKEK(newKeyId)
-    return serializeEnvelope({
-      keyId: newKeyId,
-      keyVersion,
-      wrappedDek: await envelopeRewrap(oldKEK, newKEK, envelope.wrappedDek),
-      ciphertext: envelope.ciphertext,
-    })
-  }
-}

package/src/classification-plugin.pglite.test.ts

@@ -1,226 +0,0 @@
-import { describe, test, before, after } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  CamelCasePlugin,
-  Kysely,
-  PostgresAdapter,
-  PostgresIntrospector,
-  PostgresQueryCompiler,
-  sql,
-  type CompiledQuery,
-  type DatabaseConnection,
-  type Driver,
-  type QueryResult,
-} from 'kysely'
-import { PGlite } from '@electric-sql/pglite'
-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 AccountsDB {
-  accounts: {
-    id: string
-    email: string
-    ssn: string
-    recovery: string
-  }
-}
-
-const manifest: ClassificationManifest = {
-  version: 1,
-  tables: {
-    accounts: {
-      id: { classification: 'public', anonymize_strategy: null },
-      email: { classification: 'pii', anonymize_strategy: 'fake:email' },
-      ssn: {
-        classification: 'secret',
-        anonymize_strategy: null,
-        form: 'wrapped',
-      },
-      recovery: {
-        classification: 'secret',
-        anonymize_strategy: null,
-        form: 'wrapped',
-        keyId: 'recovery-codes',
-      },
-    },
-  },
-}
-
-class PGliteConnection implements DatabaseConnection {
-  constructor(private readonly db: PGlite) {}
-
-  async executeQuery<R>(query: CompiledQuery): Promise<QueryResult<R>> {
-    const result = await this.db.query<R>(query.sql, [...query.parameters])
-    return {
-      rows: result.rows,
-      numAffectedRows:
-        result.affectedRows !== undefined
-          ? BigInt(result.affectedRows)
-          : undefined,
-    }
-  }
-
-  async *streamQuery<R>(
-    query: CompiledQuery
-  ): AsyncIterableIterator<QueryResult<R>> {
-    yield await this.executeQuery<R>(query)
-  }
-}
-
-class PGliteDriver implements Driver {
-  private readonly connection: PGliteConnection
-  constructor(private readonly db: PGlite) {
-    this.connection = new PGliteConnection(db)
-  }
-  async init(): Promise<void> {}
-  async acquireConnection(): Promise<DatabaseConnection> {
-    return this.connection
-  }
-  async beginTransaction(): Promise<void> {
-    await this.db.exec('BEGIN')
-  }
-  async commitTransaction(): Promise<void> {
-    await this.db.exec('COMMIT')
-  }
-  async rollbackTransaction(): Promise<void> {
-    await this.db.exec('ROLLBACK')
-  }
-  async releaseConnection(): Promise<void> {}
-  async destroy(): Promise<void> {}
-}
-
-const PASSPHRASE = 'a-passphrase-long-enough-to-be-real-key-material'
-
-let pglite: PGlite
-let db: Kysely<AccountsDB>
-let crypto: ClassificationCrypto
-
-before(async () => {
-  const keks = new Map<string, Promise<CryptoKey>>()
-  const resolveKEK: KEKResolver = async (keyId) => {
-    let kek = keks.get(keyId)
-    if (!kek) {
-      kek = deriveKEK(PASSPHRASE, generateKEKSalt())
-      keks.set(keyId, kek)
-    }
-    return { kek: await kek, keyVersion: 1 }
-  }
-  crypto = new ClassificationCrypto({ resolveKEK })
-
-  pglite = new PGlite()
-  db = new Kysely<AccountsDB>({
-    dialect: {
-      createAdapter: () => new PostgresAdapter(),
-      createDriver: () => new PGliteDriver(pglite),
-      createIntrospector: (i) => new PostgresIntrospector(i),
-      createQueryCompiler: () => new PostgresQueryCompiler(),
-    },
-    plugins: [
-      new CamelCasePlugin(),
-      createClassificationPlugin({
-        manifest,
-        crypto,
-      }),
-    ],
-  })
-
-  await pglite.exec(`
-    CREATE TABLE accounts (
-      id TEXT PRIMARY KEY,
-      email TEXT NOT NULL,
-      ssn TEXT,
-      recovery TEXT
-    )
-  `)
-})
-
-after(async () => {
-  await pglite.close()
-})
-
-describe('against a real postgres', () => {
-  test('a wrapped column round-trips through the database', async () => {
-    await db
-      .insertInto('accounts')
-      .values({
-        id: 'a1',
-        email: 'a@b.c',
-        ssn: (await crypto.encryptColumn('default', '123-45-6789')) as never,
-        recovery: (await crypto.encryptColumn(
-          'recovery-codes',
-          'zzz-999'
-        )) as never,
-      })
-      .execute()
-
-    const row = await db
-      .selectFrom('accounts')
-      .selectAll()
-      .where('id', '=', 'a1')
-      .executeTakeFirstOrThrow()
-
-    assert.equal(row.ssn, '123-45-6789')
-    assert.equal(row.recovery, 'zzz-999')
-    assert.equal(row.email, 'a@b.c')
-  })
-
-  test('what is actually on disk is ciphertext', async () => {
-    const raw = await pglite.query<{ ssn: string }>(
-      `SELECT ssn FROM accounts WHERE id = 'a1'`
-    )
-    const stored = raw.rows[0]!.ssn
-    assert.ok(stored.startsWith('pikku1.'))
-    assert.ok(!stored.includes('123-45-6789'))
-  })
-
-  test('a pii column is still queryable, which is the point', async () => {
-    const row = await db
-      .selectFrom('accounts')
-      .select('id')
-      .where('email', '=', 'a@b.c')
-      .executeTakeFirst()
-    assert.equal(row?.id, 'a1')
-  })
-
-  test('a forgotten encryption never reaches the database', async () => {
-    await assert.rejects(
-      () =>
-        db
-          .insertInto('accounts')
-          .values({ id: 'a2', email: 'x@y.z', ssn: 'raw-ssn' as never })
-          .execute(),
-      /ssn/
-    )
-    const found = await db
-      .selectFrom('accounts')
-      .select('id')
-      .where('id', '=', 'a2')
-      .executeTakeFirst()
-    assert.equal(found, undefined)
-  })
-
-  test('a rewrapped value still reads back through the plugin', async () => {
-    const raw = await pglite.query<{ ssn: string }>(
-      `SELECT ssn FROM accounts WHERE id = 'a1'`
-    )
-    const rewrapped = await crypto.rewrapColumn(
-      raw.rows[0]!.ssn,
-      'recovery-codes'
-    )
-    await sql`UPDATE accounts SET ssn = ${rewrapped} WHERE id = 'a1'`.execute(
-      db
-    )
-
-    const row = await db
-      .selectFrom('accounts')
-      .select('ssn')
-      .where('id', '=', 'a1')
-      .executeTakeFirstOrThrow()
-    assert.equal(row.ssn, '123-45-6789')
-  })
-})