@pikku/core 0.12.72 → 0.12.77

package/src/crypto-utils.ts

@@ -1,3 +1,6 @@
+import type { WrappedValue } from './data-classification.js'
+import { WeakKeyMaterialError } from './errors/errors.js'
+
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 
@@ -45,13 +48,35 @@ const fromBase64Url = (input: string): Uint8Array => {
   return base64Decode(base64)
 }
 
-const deriveKey = async (secret: string): Promise<CryptoKey> => {
+const SALT_BYTES = 16
+const IV_BYTES = 12
+const TAG_BYTES = 16
+const PBKDF2_ITERATIONS = 600_000
+
+const deriveKey = async (
+  secret: string,
+  salt: Uint8Array
+): Promise<CryptoKey> => {
   const subtle = getSubtle()
-  const hash = await subtle.digest('SHA-256', encoder.encode(secret))
-  return subtle.importKey('raw', hash, { name: 'AES-GCM' }, false, [
-    'encrypt',
-    'decrypt',
-  ])
+  const material = await subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'PBKDF2' },
+    false,
+    ['deriveKey']
+  )
+  return subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt: salt as BufferSource,
+      iterations: PBKDF2_ITERATIONS,
+      hash: 'SHA-256',
+    },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt']
+  )
 }
 
 export const encryptJSON = async (
@@ -63,8 +88,9 @@ export const encryptJSON = async (
     throw new Error('WebCrypto not available')
   }
   const subtle = getSubtle()
-  const iv = crypto.getRandomValues(new Uint8Array(12))
-  const key = await deriveKey(secret)
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES))
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES))
+  const key = await deriveKey(secret, salt)
   const plaintext = encoder.encode(JSON.stringify(value))
   const encrypted = await subtle.encrypt(
     { name: 'AES-GCM', iv },
@@ -72,9 +98,10 @@ export const encryptJSON = async (
     plaintext
   )
   const cipherBytes = new Uint8Array(encrypted)
-  const out = new Uint8Array(iv.length + cipherBytes.length)
-  out.set(iv, 0)
-  out.set(cipherBytes, iv.length)
+  const out = new Uint8Array(salt.length + iv.length + cipherBytes.length)
+  out.set(salt, 0)
+  out.set(iv, salt.length)
+  out.set(cipherBytes, salt.length + iv.length)
   return toBase64Url(out)
 }
 
@@ -84,12 +111,13 @@ export const decryptJSON = async <T>(
 ): Promise<T> => {
   const subtle = getSubtle()
   const data = fromBase64Url(token)
-  if (data.length < 13) {
+  if (data.length <= SALT_BYTES + IV_BYTES + TAG_BYTES) {
     throw new Error('Invalid encrypted payload')
   }
-  const iv = data.slice(0, 12)
-  const ciphertext = data.slice(12)
-  const key = await deriveKey(secret)
+  const salt = data.slice(0, SALT_BYTES)
+  const iv = data.slice(SALT_BYTES, SALT_BYTES + IV_BYTES)
+  const ciphertext = data.slice(SALT_BYTES + IV_BYTES)
+  const key = await deriveKey(secret, salt)
   const decrypted = await subtle.decrypt(
     { name: 'AES-GCM', iv },
     key,
@@ -99,58 +127,202 @@ export const decryptJSON = async <T>(
 }
 
 /**
- * Envelope encryption utilities.
- *
- * Each secret gets its own random DEK (data encryption key).
- * The DEK is wrapped (encrypted) by a KEK (key encryption key) — typically an env var.
- * The actual secret is encrypted with the DEK.
- *
- * KEK rotation only re-wraps the DEK, never touches the ciphertext.
+ * Namespaces the remote-RPC session key so the same deployment secret used for
+ * another purpose derives a different key. See knowledge/crypto.md.
  */
+export const REMOTE_SESSION_INFO = 'pikku:remote-session'
 
-const importRawKey = async (rawBytes: Uint8Array): Promise<CryptoKey> => {
+export const MIN_KEY_MATERIAL_LENGTH = 32
+
+export const assertStrongKeyMaterial = (
+  name: string,
+  keyMaterial: string
+): void => {
+  if (keyMaterial.length < MIN_KEY_MATERIAL_LENGTH) {
+    throw new WeakKeyMaterialError(
+      name,
+      MIN_KEY_MATERIAL_LENGTH,
+      keyMaterial.length
+    )
+  }
+}
+
+const expandKeyMaterial = async (
+  keyMaterial: string,
+  info: string,
+  salt: Uint8Array
+): Promise<CryptoKey> => {
   const subtle = getSubtle()
-  return subtle.importKey(
+  const material = await subtle.importKey(
     'raw',
-    rawBytes.buffer as ArrayBuffer,
-    { name: 'AES-GCM' },
-    true,
+    encoder.encode(keyMaterial),
+    'HKDF',
+    false,
+    ['deriveKey']
+  )
+  return subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: salt as BufferSource,
+      info: encoder.encode(info) as BufferSource,
+    },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false,
     ['encrypt', 'decrypt']
   )
 }
 
-export const generateDEK = async (): Promise<string> => {
-  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32))
-  return toBase64Url(raw)
+export const encryptWithKeyMaterial = async (
+  name: string,
+  keyMaterial: string,
+  info: string,
+  value: unknown
+): Promise<string> => {
+  assertStrongKeyMaterial(name, keyMaterial)
+  const crypto = globalThis.crypto
+  if (!crypto?.getRandomValues) {
+    throw new Error('WebCrypto not available')
+  }
+  const subtle = getSubtle()
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES))
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES))
+  const key = await expandKeyMaterial(keyMaterial, info, salt)
+  const encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    encoder.encode(JSON.stringify(value))
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(salt.length + iv.length + cipherBytes.length)
+  out.set(salt, 0)
+  out.set(iv, salt.length)
+  out.set(cipherBytes, salt.length + iv.length)
+  return toBase64Url(out)
 }
 
-export const wrapDEK = async (
-  kek: string,
-  plaintextDEK: string
-): Promise<string> => {
-  return encryptJSON(kek, plaintextDEK)
+export const decryptWithKeyMaterial = async <T>(
+  name: string,
+  keyMaterial: string,
+  info: string,
+  token: string
+): Promise<T> => {
+  assertStrongKeyMaterial(name, keyMaterial)
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length <= SALT_BYTES + IV_BYTES + TAG_BYTES) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const salt = data.slice(0, SALT_BYTES)
+  const iv = data.slice(SALT_BYTES, SALT_BYTES + IV_BYTES)
+  const ciphertext = data.slice(SALT_BYTES + IV_BYTES)
+  const key = await expandKeyMaterial(keyMaterial, info, salt)
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
 }
 
-export const unwrapDEK = async (
-  kek: string,
-  wrappedDEK: string
+export const encodeBase64UrlText = (value: string): string =>
+  toBase64Url(encoder.encode(value))
+
+export const decodeBase64UrlText = (value: string): string =>
+  decoder.decode(fromBase64Url(value))
+
+const expandSigningKeyMaterial = async (
+  keyMaterial: string,
+  info: string
+): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  const material = await subtle.importKey(
+    'raw',
+    encoder.encode(keyMaterial),
+    'HKDF',
+    false,
+    ['deriveKey']
+  )
+  return subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(0) as BufferSource,
+      info: encoder.encode(info) as BufferSource,
+    },
+    material,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify']
+  )
+}
+
+/**
+ * HMAC-SHA256 over `payload` under a key expanded from high-entropy key
+ * material, base64url-encoded. The salt is empty by design so the verifier can
+ * re-derive the key from `keyMaterial` and `info` alone.
+ */
+export const signWithKeyMaterial = async (
+  name: string,
+  keyMaterial: string,
+  info: string,
+  payload: string
 ): Promise<string> => {
-  return decryptJSON<string>(kek, wrappedDEK)
+  assertStrongKeyMaterial(name, keyMaterial)
+  const key = await expandSigningKeyMaterial(keyMaterial, info)
+  const signature = await getSubtle().sign(
+    'HMAC',
+    key,
+    encoder.encode(payload) as BufferSource
+  )
+  return toBase64Url(new Uint8Array(signature))
 }
 
-const encryptWithDEK = async (
-  dekBase64: string,
+/** False — never throws — for a malformed, truncated or mismatched signature. */
+export const verifyWithKeyMaterial = async (
+  name: string,
+  keyMaterial: string,
+  info: string,
+  payload: string,
+  signature: string
+): Promise<boolean> => {
+  assertStrongKeyMaterial(name, keyMaterial)
+  const key = await expandSigningKeyMaterial(keyMaterial, info)
+  try {
+    return await getSubtle().verify(
+      'HMAC',
+      key,
+      fromBase64Url(signature) as BufferSource,
+      encoder.encode(payload) as BufferSource
+    )
+  } catch {
+    return false
+  }
+}
+
+const importRawKey = async (rawBytes: Uint8Array): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  return subtle.importKey(
+    'raw',
+    rawBytes.buffer as ArrayBuffer,
+    { name: 'AES-GCM' },
+    true,
+    ['encrypt', 'decrypt']
+  )
+}
+
+const encryptWithCryptoKey = async (
+  key: CryptoKey,
   value: unknown
 ): Promise<string> => {
   const crypto = globalThis.crypto
   const subtle = getSubtle()
-  const iv = crypto.getRandomValues(new Uint8Array(12))
-  const key = await importRawKey(fromBase64Url(dekBase64))
-  const plaintext = encoder.encode(JSON.stringify(value))
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES))
   const encrypted = await subtle.encrypt(
     { name: 'AES-GCM', iv },
     key,
-    plaintext
+    encoder.encode(JSON.stringify(value))
   )
   const cipherBytes = new Uint8Array(encrypted)
   const out = new Uint8Array(iv.length + cipherBytes.length)
@@ -159,18 +331,17 @@ const encryptWithDEK = async (
   return toBase64Url(out)
 }
 
-const decryptWithDEK = async <T>(
-  dekBase64: string,
+const decryptWithCryptoKey = async <T>(
+  key: CryptoKey,
   token: string
 ): Promise<T> => {
   const subtle = getSubtle()
   const data = fromBase64Url(token)
-  if (data.length < 13) {
+  if (data.length < IV_BYTES + TAG_BYTES) {
     throw new Error('Invalid encrypted payload')
   }
-  const iv = data.slice(0, 12)
-  const ciphertext = data.slice(12)
-  const key = await importRawKey(fromBase64Url(dekBase64))
+  const iv = data.slice(0, IV_BYTES)
+  const ciphertext = data.slice(IV_BYTES)
   const decrypted = await subtle.decrypt(
     { name: 'AES-GCM', iv },
     key,
@@ -179,23 +350,99 @@ const decryptWithDEK = async <T>(
   return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
 }
 
-export interface EnvelopeEncryptResult {
-  ciphertext: string
+export const generateDEK = async (): Promise<string> => {
+  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32))
+  return toBase64Url(raw)
+}
+
+/**
+ * One salt per (deployment, key version), stored beside the wrapped DEKs.
+ * See knowledge/crypto.md.
+ */
+export const generateKEKSalt = (): string => {
+  const crypto = globalThis.crypto
+  if (!crypto?.getRandomValues) {
+    throw new Error('WebCrypto not available')
+  }
+  return toBase64Url(crypto.getRandomValues(new Uint8Array(SALT_BYTES)))
+}
+
+export const deriveKEK = async (
+  passphrase: string,
+  salt: string
+): Promise<CryptoKey> => {
+  return deriveKey(passphrase, fromBase64Url(salt))
+}
+
+/**
+ * The one place a `WrappedValue` is minted. Every branded return below routes
+ * through here, so the assertion "these bytes really are ciphertext" is made
+ * once and audited once instead of at each call site.
+ */
+const asWrapped = (ciphertext: string): WrappedValue =>
+  ciphertext as WrappedValue
+
+export const wrapDEK = async (
+  kek: CryptoKey,
+  plaintextDEK: string
+): Promise<WrappedValue> => {
+  return asWrapped(await encryptWithCryptoKey(kek, plaintextDEK))
+}
+
+export const unwrapDEK = async (
+  kek: CryptoKey,
   wrappedDEK: string
+): Promise<string> => {
+  return decryptWithCryptoKey<string>(kek, wrappedDEK)
+}
+
+const encryptWithDEK = async (
+  dekBase64: string,
+  value: unknown
+): Promise<string> => {
+  return encryptWithCryptoKey(
+    await importRawKey(fromBase64Url(dekBase64)),
+    value
+  )
+}
+
+const decryptWithDEK = async <T>(
+  dekBase64: string,
+  token: string
+): Promise<T> => {
+  return decryptWithCryptoKey<T>(
+    await importRawKey(fromBase64Url(dekBase64)),
+    token
+  )
+}
+
+export interface EnvelopeEncryptResult {
+  ciphertext: WrappedValue
+  wrappedDEK: WrappedValue
 }
 
 export const envelopeEncrypt = async (
-  kek: string,
+  kek: CryptoKey,
   value: unknown
 ): Promise<EnvelopeEncryptResult> => {
   const dek = await generateDEK()
-  const ciphertext = await encryptWithDEK(dek, value)
+  const ciphertext = asWrapped(await encryptWithDEK(dek, value))
   const wrappedDEK = await wrapDEK(kek, dek)
   return { ciphertext, wrappedDEK }
 }
 
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
 export const envelopeDecrypt = async <T>(
-  kek: string,
+  kek: CryptoKey,
   ciphertext: string,
   wrappedDEK: string
 ): Promise<T> => {
@@ -204,10 +451,10 @@ export const envelopeDecrypt = async <T>(
 }
 
 export const envelopeRewrap = async (
-  oldKEK: string,
-  newKEK: string,
+  oldKEK: CryptoKey,
+  newKEK: CryptoKey,
   wrappedDEK: string
-): Promise<string> => {
+): Promise<WrappedValue> => {
   const dek = await unwrapDEK(oldKEK, wrappedDEK)
   return wrapDEK(newKEK, dek)
 }

package/src/data-classification.ts

@@ -1,10 +1,4 @@
-// The `__classification__` marker is OPTIONAL on purpose. A required property
-// would make a plain value (e.g. `string`) unassignable to a branded column
-// (`Private<string>`), which breaks ordinary Kysely query operands —
-// `where('email', '=', someString)`, inserts, and `.set(...)`. Making it
-// optional keeps the brand structurally present (so the inspector's PKU910
-// output check still detects it) while allowing plain values to flow IN.
-// See `findPiiPaths` in @pikku/inspector, which reads the level union-aware.
+// knowledge: decisions/internals/core-data-classification-brand-is-an-optional-property.md
 export type Private<T> = T & { readonly __classification__?: 'private' }
 export type Pii<T> = T & { readonly __classification__?: 'pii' }
 export type Secret<T> = T & { readonly __classification__?: 'secret' }
@@ -17,9 +11,53 @@ export type AnonymizeStrategy =
   | 'keep'
   | null
 
+// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
+
+/**
+ * How a column's bytes are represented at rest, as distinct from how sensitive
+ * the value is (`Classification`). The two are independent: a token hash is
+ * `secret` + `hashed` and must never be encrypted, because the hash *is* the
+ * lookup key; a live bearer token is `secret` + `plain` today and should not be.
+ *
+ * `wrapped` and `sealed` are siblings rather than one being "encrypted": both
+ * are ciphertext, and what separates them is who can read it back. Wrapped is
+ * symmetric and the application holds the key. Sealed is asymmetric and the
+ * application holds only the public half, so it can write the value and never
+ * read it. Storing one where the other is expected is silent, permanent data
+ * loss, which is why they are not collapsed into a single `encrypted`.
+ */
+export type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed'
+
+declare const wrappedBrand: unique symbol
+declare const sealedBrand: unique symbol
+declare const hashedBrand: unique symbol
+
+/**
+ * Ciphertext under a symmetric key the application holds — the output of
+ * `envelopeEncrypt`, `wrapDEK` or `envelopeRewrap`.
+ *
+ * Unlike `Secret<T>` the brand is REQUIRED, so a plain `string` is not
+ * assignable and a column declared `form: 'wrapped'` cannot be written with
+ * anything but genuine ciphertext. It stays assignable *to* `string`, so it
+ * still works as a query operand and serializes normally — the constraint is on
+ * construction, not on use.
+ */
+export type WrappedValue = string & { readonly [wrappedBrand]: true }
+
+/** Ciphertext under a public key whose private half the application does not
+ *  hold. Deliberately not assignable to `WrappedValue`: writing one where the
+ *  other belongs produces a row nobody can ever open. */
+export type SealedValue = string & { readonly [sealedBrand]: true }
+
+/** A one-way digest of a secret input. The brand's job is narrow — stop a *raw*
+ *  credential being written into the column that should hold its hash. */
+export type HashedValue = string & { readonly [hashedBrand]: true }
+
 export interface ColumnClassification {
   classification: Classification
   anonymize_strategy: AnonymizeStrategy
+  /** At-rest representation. Absent means `plain`. */
+  form?: ColumnForm
   description?: string
 }
 

package/src/dev/hot-reload.test.ts

@@ -354,14 +354,12 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
       pikkuDir: tmpDir,
     })
 
-    // Write updated function via file system and let the watcher pick it up
     const jsV2 = `export const hotTask = { func: async () => { return { reloaded: true }; }, auth: false };\n`
     await writeFile(join(tmpDir, 'hotTask.js'), jsV2)
     await writeFile(join(tmpDir, 'hotTask.ts'), `// trigger ${Date.now()}`)
 
     await wait(300)
 
-    // Verify the function was reloaded via the watcher
     const reloadLog = mockLogger
       .getLogs()
       .find(
@@ -370,8 +368,6 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
       )
     assert.ok(reloadLog, 'Should log hot-reload for hotTask')
 
-    // runScheduledTask uses runPikkuFunc which reads from the functions Map,
-    // so it will pick up the hot-reloaded function (no longer sets taskResult.ref)
     await runScheduledTask({ name: 'hotTask' })
 
     // The reloaded function no longer sets taskResult.ref, so it should

package/src/dev/hot-reload.ts

@@ -52,12 +52,6 @@ const findCompiledFile = async (
   return null
 }
 
-// Changed user files are re-run through an evictable module runner keyed by a
-// stable path (createModuleRunner), NOT re-imported under a fresh URL. A
-// fresh-URL import (a `data:` URL on Node, a uniquely-named temp sibling on
-// Bun) permanently leaks a record in the native ESM loader map on every
-// reload, OOMing long editing sessions; the runner overwrites a single slot so
-// the previous module is collected. See ./module-runner.ts.
 const isWatchedTsFile = (filename: string): boolean => {
   return (
     filename.endsWith('.ts') &&
@@ -110,17 +104,12 @@ export async function pikkuDevReloader(
       return
     }
 
-    // Register every function-config export — replacing known functions AND
-    // adding new ones (a brand-new function becomes callable as soon as its
-    // meta lands via reloadGeneratedMeta after the next codegen pass).
-    // Write into the map captured at startup, NOT pikkuState's current one:
-    // a dev-server watcher may have temporarily swapped in a codegen-scoped
-    // map for the same file event (runAllWithCommandState), and a write to
-    // that map is silently discarded when it restores the original.
-    // Schemas are NOT touched here: `input`/`output` hold raw zod schemas,
-    // while the schema map carries codegen-generated JSON schemas — mixing the
-    // two crashed every reload. Fresh JSON schemas arrive via
-    // reloadGeneratedMeta once codegen has re-emitted them.
+    // Register every function-config export, replacing known functions and
+    // adding new ones. Write into the map captured at startup, NOT pikkuState's
+    // current one: a dev-server watcher may have temporarily swapped in a
+    // codegen-scoped map, whose writes are discarded when it restores.
+    // Schemas are NOT touched here: `input`/`output` hold raw zod schemas while
+    // the schema map carries codegen JSON schemas; mixing them crashed reloads.
     for (const [exportName, exportValue] of Object.entries(mod)) {
       if (!isFunctionConfig(exportValue)) continue
       const isNew = !functionsMap.has(exportName)
@@ -129,10 +118,9 @@ export async function pikkuDevReloader(
       else reloadedNames.push(exportName)
     }
 
-    // Re-importing the module re-ran its wire* side effects (wireHTTP et al
-    // are keyed map-sets, so re-registration replaces/adds) — reset the
-    // router and caches even when no function export changed, so a
-    // wiring-only file edit rebuilds the route matchers too.
+    // Re-importing re-ran the module’s wire* side effects, so reset the router
+    // and caches even when no function export changed — a wiring-only edit has
+    // to rebuild the route matchers too.
     clearMiddlewareCache()
     clearPermissionsCache()
     clearChannelMiddlewareCache()
@@ -149,9 +137,8 @@ export async function pikkuDevReloader(
 
   let debounceTimer: ReturnType<typeof setTimeout> | undefined
   const pendingChanges = new Set<string>()
-  // Files re-imported since the last reimportPending() drain. A dev-server
-  // watcher drains this after its codegen pass so wire* registrations that
-  // were skipped for missing meta (a NEW route) run again with fresh meta.
+  // Files re-imported since the last reimportPending() drain, re-run after the
+  // dev server's codegen pass so registrations skipped for missing meta retry.
   const postCodegenQueue = new Set<string>()
 
   const safeHandleFileChange = async (file: string) => {
@@ -206,12 +193,6 @@ export async function pikkuDevReloader(
       }
       moduleRunner.clear()
     },
-    // Drain the queue of recently re-imported files and import them again.
-    // A dev-server watcher calls this AFTER its codegen pass has refreshed
-    // the generated meta (reloadGeneratedMeta): wire* registrations skip
-    // routes whose meta doesn't exist yet, so a wiring file changed
-    // alongside a NEW function only registers its new route when
-    // re-imported after the fresh meta has landed.
     reimportPending: async () => {
       const files = [...postCodegenQueue]
       postCodegenQueue.clear()