@pikku/core 0.12.3 → 0.12.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/crypto-utils.test.ts

@@ -1,214 +0,0 @@
-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

@@ -1,213 +0,0 @@
-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)
-}

package/src/errors/error-handler.ts

@@ -1,62 +0,0 @@
-import { pikkuState } from '../pikku-state.js'
-
-/**
- * Base class for custom errors.
- * @extends {Error}
- */
-export class PikkuError extends Error {
-  /**
-   * Creates an instance of PikkuError.
-   * @param message - The error message.
-   */
-  constructor(message: string = 'An error occurred') {
-    super(message)
-    Object.setPrototypeOf(this, new.target.prototype)
-  }
-}
-
-/**
- * Interface for error details.
- */
-export interface ErrorDetails {
-  status: number
-  message: string
-  mcpCode?: number
-}
-
-/**
- * Adds an error to the API errors map.
- * @param error - The error to add.
- * @param details - The details of the error.
- */
-export const addError = (error: any, { status, message }: ErrorDetails) => {
-  pikkuState(null, 'misc', 'errors').set(error, { status, message })
-}
-
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
-export const addErrors = (
-  errors: Array<[error: any, details: ErrorDetails]>
-) => {
-  errors.forEach((error) => {
-    addError(error[0], error[1])
-  })
-}
-
-/**
- * Retrieves the error response for a given error.
- * @param error - The error to get the response for.
- * @returns An object containing the status and message, or undefined if the error is not found.
- */
-export const getErrorResponse = (
-  error: Error
-): { status: number; message: string; mcpCode?: number } | undefined => {
-  const errors = Array.from(pikkuState(null, 'misc', 'errors').entries())
-  const foundError = errors.find(([e]) => e.name === error.constructor.name)
-  if (foundError) {
-    return foundError[1]
-  }
-  return pikkuState(null, 'misc', 'errors').get(error)
-}

package/src/errors/error.test.ts

@@ -1,195 +0,0 @@
-import { test, describe } from 'node:test'
-import assert from 'assert'
-import {
-  getErrorResponse,
-  addError,
-  addErrors,
-  PikkuError,
-} from './error-handler.js'
-import {
-  BadRequestError,
-  UnauthorizedError,
-  MissingSessionError,
-  InvalidSessionError,
-  PaymentRequiredError,
-  ForbiddenError,
-  InvalidOriginError,
-  NotFoundError,
-  MethodNotAllowedError,
-  NotAcceptableError,
-  ProxyAuthenticationRequiredError,
-  RequestTimeoutError,
-  ConflictError,
-  GoneError,
-  LengthRequiredError,
-  PreconditionFailedError,
-  PayloadTooLargeError,
-  URITooLongError,
-  UnsupportedMediaTypeError,
-  RangeNotSatisfiableError,
-  ExpectationFailedError,
-  UnprocessableContentError,
-  LockedError,
-  TooManyRequestsError,
-  InternalServerError,
-  NotImplementedError,
-  BadGatewayError,
-  ServiceUnavailableError,
-  GatewayTimeoutError,
-  HTTPVersionNotSupportedError,
-  MaxComputeTimeReachedError,
-  MissingSchemaError,
-  InvalidMiddlewareWireError,
-  PikkuMissingMetaError,
-} from './errors.js'
-
-describe('PikkuError', () => {
-  test('should create error with default message', () => {
-    const error = new PikkuError()
-    assert.strictEqual(error.message, 'An error occurred')
-  })
-
-  test('should create error with custom message', () => {
-    const error = new PikkuError('custom message')
-    assert.strictEqual(error.message, 'custom message')
-  })
-
-  test('should be instance of Error', () => {
-    const error = new PikkuError()
-    assert.ok(error instanceof Error)
-  })
-
-  test('should be instance of PikkuError', () => {
-    const error = new PikkuError()
-    assert.ok(error instanceof PikkuError)
-  })
-
-  test('subclasses should be instanceof PikkuError', () => {
-    assert.ok(new BadRequestError() instanceof PikkuError)
-    assert.ok(new NotFoundError() instanceof PikkuError)
-    assert.ok(new ForbiddenError() instanceof PikkuError)
-  })
-})
-
-describe('getErrorResponse', () => {
-  test('should return the correct error response for BadRequestError', () => {
-    const error = new BadRequestError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 400,
-      message:
-        'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
-    })
-  })
-
-  test('should return the correct error response for NotFoundError', () => {
-    const error = new NotFoundError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 404,
-      message: 'The server cannot find the requested resource.',
-    })
-  })
-
-  test('should return the correct error response for ForbiddenError', () => {
-    const error = new ForbiddenError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 403,
-      message:
-        'The client does not have permission to access the requested resource.',
-    })
-  })
-
-  test('should return undefined for an unknown error', () => {
-    class UnknownError extends Error {}
-    const error = new UnknownError()
-    const response = getErrorResponse(error)
-    assert.strictEqual(response, undefined)
-  })
-
-  test('should return the correct error response for a custom error added to apiErrors', () => {
-    class CustomError extends Error {}
-    const customError = new CustomError()
-    const customErrorDetails = { status: 400, message: 'Custom Error' }
-
-    // Add the custom error to the apiErrors map
-    addError(CustomError, customErrorDetails)
-
-    const response = getErrorResponse(customError)
-    assert.deepStrictEqual(response, customErrorDetails)
-  })
-})
-
-describe('addErrors', () => {
-  test('should register multiple errors at once', () => {
-    class ErrA extends Error {}
-    class ErrB extends Error {}
-    addErrors([
-      [ErrA, { status: 450, message: 'Error A' }],
-      [ErrB, { status: 451, message: 'Error B' }],
-    ])
-    assert.deepStrictEqual(getErrorResponse(new ErrA()), {
-      status: 450,
-      message: 'Error A',
-    })
-    assert.deepStrictEqual(getErrorResponse(new ErrB()), {
-      status: 451,
-      message: 'Error B',
-    })
-  })
-})
-
-describe('all built-in error classes', () => {
-  const errorCases: [string, any, number][] = [
-    ['InvalidMiddlewareWireError', InvalidMiddlewareWireError, 500],
-    ['PikkuMissingMetaError', PikkuMissingMetaError, 500],
-    ['BadRequestError', BadRequestError, 400],
-    ['UnauthorizedError', UnauthorizedError, 401],
-    ['MissingSessionError', MissingSessionError, 401],
-    ['InvalidSessionError', InvalidSessionError, 401],
-    ['PaymentRequiredError', PaymentRequiredError, 402],
-    ['ForbiddenError', ForbiddenError, 403],
-    ['InvalidOriginError', InvalidOriginError, 403],
-    ['NotFoundError', NotFoundError, 404],
-    ['MethodNotAllowedError', MethodNotAllowedError, 405],
-    ['NotAcceptableError', NotAcceptableError, 406],
-    ['ProxyAuthenticationRequiredError', ProxyAuthenticationRequiredError, 407],
-    ['RequestTimeoutError', RequestTimeoutError, 408],
-    ['ConflictError', ConflictError, 409],
-    ['GoneError', GoneError, 410],
-    ['LengthRequiredError', LengthRequiredError, 411],
-    ['PreconditionFailedError', PreconditionFailedError, 412],
-    ['PayloadTooLargeError', PayloadTooLargeError, 413],
-    ['URITooLongError', URITooLongError, 414],
-    ['UnsupportedMediaTypeError', UnsupportedMediaTypeError, 415],
-    ['RangeNotSatisfiableError', RangeNotSatisfiableError, 416],
-    ['ExpectationFailedError', ExpectationFailedError, 417],
-    ['UnprocessableContentError', UnprocessableContentError, 422],
-    ['LockedError', LockedError, 423],
-    ['TooManyRequestsError', TooManyRequestsError, 429],
-    ['InternalServerError', InternalServerError, 500],
-    ['NotImplementedError', NotImplementedError, 501],
-    ['BadGatewayError', BadGatewayError, 502],
-    ['ServiceUnavailableError', ServiceUnavailableError, 503],
-    ['GatewayTimeoutError', GatewayTimeoutError, 504],
-    ['HTTPVersionNotSupportedError', HTTPVersionNotSupportedError, 505],
-    ['MaxComputeTimeReachedError', MaxComputeTimeReachedError, 524],
-    ['MissingSchemaError', MissingSchemaError, 500],
-  ]
-
-  for (const [name, ErrorClass, expectedStatus] of errorCases) {
-    test(`${name} should map to status ${expectedStatus}`, () => {
-      const error = new ErrorClass()
-      const response = getErrorResponse(error)
-      assert.ok(response, `Expected error response for ${name}`)
-      assert.strictEqual(response!.status, expectedStatus)
-      assert.ok(response!.message.length > 0)
-    })
-
-    test(`${name} should be instance of PikkuError`, () => {
-      const error = new ErrorClass()
-      assert.ok(error instanceof PikkuError)
-    })
-  }
-})