@pikku/core 0.12.4 → 0.12.6

package/src/crypto-utils.test.ts

@@ -0,0 +1,214 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  encryptJSON,
+  decryptJSON,
+  generateDEK,
+  wrapDEK,
+  unwrapDEK,
+  envelopeEncrypt,
+  envelopeDecrypt,
+  envelopeRewrap,
+} from './crypto-utils.js'
+
+describe('encryptJSON / decryptJSON', () => {
+  const secret = 'test-secret-key-for-encryption'
+
+  test('should round-trip a simple object', async () => {
+    const original = { hello: 'world', num: 42 }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should round-trip a string value', async () => {
+    const original = 'just a string'
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, original)
+  })
+
+  test('should round-trip a number', async () => {
+    const original = 12345
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, original)
+  })
+
+  test('should round-trip null', async () => {
+    const encrypted = await encryptJSON(secret, null)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, null)
+  })
+
+  test('should round-trip a boolean', async () => {
+    const encrypted = await encryptJSON(secret, true)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.strictEqual(decrypted, true)
+  })
+
+  test('should round-trip a nested object', async () => {
+    const original = { user: { id: 1, roles: ['admin', 'user'] }, active: true }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should round-trip an array', async () => {
+    const original = [1, 'two', { three: 3 }]
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should produce different ciphertexts for same input (random IV)', async () => {
+    const value = { same: 'data' }
+    const enc1 = await encryptJSON(secret, value)
+    const enc2 = await encryptJSON(secret, value)
+    assert.notStrictEqual(enc1, enc2)
+  })
+
+  test('should produce a base64url string (no +, /, or = characters)', async () => {
+    const encrypted = await encryptJSON(secret, { test: 'base64url' })
+    assert.ok(!/[+/=]/.test(encrypted), `Expected base64url, got: ${encrypted}`)
+  })
+
+  test('should fail to decrypt with wrong secret', async () => {
+    const encrypted = await encryptJSON(secret, { data: 'sensitive' })
+    await assert.rejects(
+      () => decryptJSON('wrong-secret', encrypted),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('should reject an invalid encrypted payload (too short)', async () => {
+    await assert.rejects(() => decryptJSON(secret, 'dG9vc2hvcnQ'), {
+      message: 'Invalid encrypted payload',
+    })
+  })
+
+  test('should reject empty string', async () => {
+    await assert.rejects(() => decryptJSON(secret, ''), {
+      message: 'Invalid encrypted payload',
+    })
+  })
+
+  test('should reject corrupted ciphertext', async () => {
+    const encrypted = await encryptJSON(secret, { data: 'test' })
+    const corrupted = encrypted.slice(0, -4) + 'XXXX'
+    await assert.rejects(
+      () => decryptJSON(secret, corrupted),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('should handle unicode content', async () => {
+    const original = { emoji: '🎉', japanese: 'こんにちは', arabic: 'مرحبا' }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should handle empty object', async () => {
+    const original = {}
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('should handle large payload', async () => {
+    const original = { data: 'x'.repeat(10000) }
+    const encrypted = await encryptJSON(secret, original)
+    const decrypted = await decryptJSON(secret, encrypted)
+    assert.deepStrictEqual(decrypted, original)
+  })
+})
+
+describe('envelope encryption', () => {
+  const kek = 'my-key-encryption-key'
+
+  test('generateDEK produces unique keys', async () => {
+    const dek1 = await generateDEK()
+    const dek2 = await generateDEK()
+    assert.notStrictEqual(dek1, dek2)
+    assert.ok(dek1.length > 0)
+  })
+
+  test('wrapDEK / unwrapDEK round-trip', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    const unwrapped = await unwrapDEK(kek, wrapped)
+    assert.strictEqual(unwrapped, dek)
+  })
+
+  test('unwrapDEK fails with wrong KEK', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    await assert.rejects(
+      () => unwrapDEK('wrong-kek', wrapped),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeEncrypt / envelopeDecrypt round-trip', async () => {
+    const original = {
+      apiKey: 'sk-secret-123',
+      endpoint: 'https://api.example.com',
+    }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const decrypted = await envelopeDecrypt(kek, ciphertext, wrappedDEK)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeEncrypt produces unique ciphertexts and DEKs per call', async () => {
+    const value = { same: 'data' }
+    const r1 = await envelopeEncrypt(kek, value)
+    const r2 = await envelopeEncrypt(kek, value)
+    assert.notStrictEqual(r1.ciphertext, r2.ciphertext)
+    assert.notStrictEqual(r1.wrappedDEK, r2.wrappedDEK)
+  })
+
+  test('envelopeDecrypt fails with wrong KEK', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'secret')
+    await assert.rejects(
+      () => envelopeDecrypt('wrong-kek', ciphertext, wrappedDEK),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeRewrap allows decryption with new KEK', async () => {
+    const newKEK = 'my-new-kek'
+    const original = { token: 'abc-123' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+
+    const rewrapped = await envelopeRewrap(kek, newKEK, wrappedDEK)
+
+    await assert.rejects(
+      () => envelopeDecrypt(kek, ciphertext, rewrapped),
+      (err: any) => err instanceof Error
+    )
+
+    const decrypted = await envelopeDecrypt(newKEK, ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeRewrap does not change the ciphertext', async () => {
+    const original = { data: 'important' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const rewrapped = await envelopeRewrap(kek, 'new-kek', wrappedDEK)
+
+    assert.notStrictEqual(rewrapped, wrappedDEK)
+
+    const decrypted = await envelopeDecrypt('new-kek', ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelope handles string secrets', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(
+      kek,
+      'plain-string-secret'
+    )
+    const decrypted = await envelopeDecrypt<string>(kek, ciphertext, wrappedDEK)
+    assert.strictEqual(decrypted, 'plain-string-secret')
+  })
+})

package/src/crypto-utils.ts

@@ -0,0 +1,213 @@
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+const getSubtle = () => {
+  const crypto = globalThis.crypto
+  if (!crypto?.subtle) {
+    throw new Error('WebCrypto not available')
+  }
+  return crypto.subtle
+}
+
+const base64Encode = (bytes: Uint8Array): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!)
+  }
+  return btoa(binary)
+}
+
+const base64Decode = (input: string): Uint8Array => {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(input, 'base64'))
+  }
+  const binary = atob(input)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}
+
+const toBase64Url = (bytes: Uint8Array): string => {
+  return base64Encode(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '')
+}
+
+const fromBase64Url = (input: string): Uint8Array => {
+  let base64 = input.replace(/-/g, '+').replace(/_/g, '/')
+  while (base64.length % 4 !== 0) base64 += '='
+  return base64Decode(base64)
+}
+
+const deriveKey = async (secret: string): 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',
+  ])
+}
+
+export const encryptJSON = async (
+  secret: string,
+  value: unknown
+): Promise<string> => {
+  const crypto = globalThis.crypto
+  if (!crypto?.getRandomValues) {
+    throw new Error('WebCrypto not available')
+  }
+  const subtle = getSubtle()
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const key = await deriveKey(secret)
+  const plaintext = encoder.encode(JSON.stringify(value))
+  const encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    plaintext
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(iv.length + cipherBytes.length)
+  out.set(iv, 0)
+  out.set(cipherBytes, iv.length)
+  return toBase64Url(out)
+}
+
+export const decryptJSON = async <T>(
+  secret: string,
+  token: string
+): Promise<T> => {
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length < 13) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const iv = data.slice(0, 12)
+  const ciphertext = data.slice(12)
+  const key = await deriveKey(secret)
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as 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.
+ */
+
+const importRawKey = async (rawBytes: Uint8Array): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  return subtle.importKey(
+    'raw',
+    rawBytes.buffer as ArrayBuffer,
+    { name: 'AES-GCM' },
+    true,
+    ['encrypt', 'decrypt']
+  )
+}
+
+export const generateDEK = async (): Promise<string> => {
+  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32))
+  return toBase64Url(raw)
+}
+
+export const wrapDEK = async (
+  kek: string,
+  plaintextDEK: string
+): Promise<string> => {
+  return encryptJSON(kek, plaintextDEK)
+}
+
+export const unwrapDEK = async (
+  kek: string,
+  wrappedDEK: string
+): Promise<string> => {
+  return decryptJSON<string>(kek, wrappedDEK)
+}
+
+const encryptWithDEK = async (
+  dekBase64: string,
+  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 encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    plaintext
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(iv.length + cipherBytes.length)
+  out.set(iv, 0)
+  out.set(cipherBytes, iv.length)
+  return toBase64Url(out)
+}
+
+const decryptWithDEK = async <T>(
+  dekBase64: string,
+  token: string
+): Promise<T> => {
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length < 13) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const iv = data.slice(0, 12)
+  const ciphertext = data.slice(12)
+  const key = await importRawKey(fromBase64Url(dekBase64))
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
+}
+
+export interface EnvelopeEncryptResult {
+  ciphertext: string
+  wrappedDEK: string
+}
+
+export const envelopeEncrypt = async (
+  kek: string,
+  value: unknown
+): Promise<EnvelopeEncryptResult> => {
+  const dek = await generateDEK()
+  const ciphertext = await encryptWithDEK(dek, value)
+  const wrappedDEK = await wrapDEK(kek, dek)
+  return { ciphertext, wrappedDEK }
+}
+
+export const envelopeDecrypt = async <T>(
+  kek: string,
+  ciphertext: string,
+  wrappedDEK: string
+): Promise<T> => {
+  const dek = await unwrapDEK(kek, wrappedDEK)
+  return decryptWithDEK<T>(dek, ciphertext)
+}
+
+export const envelopeRewrap = async (
+  oldKEK: string,
+  newKEK: string,
+  wrappedDEK: string
+): Promise<string> => {
+  const dek = await unwrapDEK(oldKEK, wrappedDEK)
+  return wrapDEK(newKEK, dek)
+}