@tuturuuu/utils 0.0.3 → 0.6.1

package/src/encryption/encryption-service.ts

@@ -0,0 +1,343 @@
+/**
+ * Encryption service for transparent encryption at rest
+ *
+ * Uses AES-256-GCM for symmetric encryption of sensitive calendar event fields.
+ * Workspace keys are encrypted with a master key from environment variables.
+ *
+ * Security Model:
+ * - Master key: stored in ENCRYPTION_MASTER_KEY environment variable
+ * - Workspace keys: AES-256 keys, unique per workspace, encrypted with master key
+ * - Field encryption: AES-GCM with random IV per encryption
+ */
+
+import { gcm } from '@noble/ciphers/aes.js';
+import { scryptAsync } from '@noble/hashes/scrypt.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import type { EncryptedCalendarEventFields, EncryptedField } from './types';
+
+// Encryption constants
+const KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 12; // 96 bits for GCM
+const AUTH_TAG_LENGTH = 16; // 128 bits
+
+// Scrypt parameters (explicit for documentation and security auditing)
+//
+// SECURITY RATIONALE:
+// N=16384 (2^14), r=8, p=1 are used for key derivation from the master key.
+// OWASP recommends N>=2^17 for PASSWORD HASHING, but this is KEY DERIVATION:
+// - The master key is a high-entropy secret from environment variables
+// - Key derivation doesn't need the same protection against brute-force as password hashing
+// - Lower cost reduces latency for encryption/decryption operations
+// - The threat model assumes the master key is not guessed (it's a 256-bit secret)
+//
+// NOTE: Re-evaluate cost parameters periodically. Consider:
+// - Increasing N if server performance allows
+// - Using per-workspace salt instead of fixed salt for additional isolation
+//
+const SCRYPT_COST = 16384;
+const SCRYPT_BLOCK_SIZE = 8;
+const SCRYPT_PARALLELISM = 1;
+const SCRYPT_KEY_LENGTH = 32; // 256 bits
+const SCRYPT_SALT = 'workspace-key-salt'; // Fixed salt (per-workspace salt is a future enhancement)
+
+/**
+ * Maximum number of derived keys to cache.
+ * Prevents unbounded memory growth in long-running processes.
+ */
+const MAX_CACHE_SIZE = 100;
+
+// Cache for derived keys to avoid repeated scrypt calls
+// Key: masterKey, Value: derived key buffer
+const derivedKeyCache = new Map<string, Buffer>();
+
+/**
+ * Derive a key from master key using scrypt (async, non-blocking)
+ * Results are cached to avoid repeated derivation.
+ * Cache is bounded to MAX_CACHE_SIZE entries using FIFO eviction.
+ */
+async function getDerivedKey(masterKey: string): Promise<Buffer> {
+  const cached = derivedKeyCache.get(masterKey);
+  if (cached) {
+    return cached;
+  }
+
+  // Use @noble/hashes/scrypt instead of node:crypto for Vercel Edge compatibility
+  const derivedKeyArray = await scryptAsync(masterKey, SCRYPT_SALT, {
+    N: SCRYPT_COST,
+    r: SCRYPT_BLOCK_SIZE,
+    p: SCRYPT_PARALLELISM,
+    dkLen: SCRYPT_KEY_LENGTH,
+  });
+
+  const derivedKey = Buffer.from(derivedKeyArray);
+
+  // Evict oldest entry if cache is at capacity (FIFO eviction)
+  if (derivedKeyCache.size >= MAX_CACHE_SIZE) {
+    const oldestKey = derivedKeyCache.keys().next().value;
+    if (oldestKey !== undefined) {
+      derivedKeyCache.delete(oldestKey);
+    }
+  }
+  derivedKeyCache.set(masterKey, derivedKey);
+
+  return derivedKey;
+}
+
+/**
+ * Generate a new workspace encryption key (256-bit)
+ */
+export function generateWorkspaceKey(): Buffer {
+  return Buffer.from(randomBytes(KEY_LENGTH));
+}
+
+/**
+ * Encrypt a workspace key with the master key
+ * @param workspaceKey - The workspace key to encrypt
+ * @param masterKey - The master key (from environment variable)
+ * @returns Base64-encoded encrypted key
+ */
+export async function encryptWorkspaceKey(
+  workspaceKey: Buffer,
+  masterKey: string
+): Promise<string> {
+  // Derive a consistent key from the master key string (async, cached)
+  const derivedKey = await getDerivedKey(masterKey);
+  const iv = randomBytes(IV_LENGTH);
+
+  const cipher = gcm(new Uint8Array(derivedKey), new Uint8Array(iv));
+  const encryptedAndTag = cipher.encrypt(new Uint8Array(workspaceKey));
+
+  // Format: iv + encrypted + authTag
+  return Buffer.concat([
+    Buffer.from(iv),
+    Buffer.from(encryptedAndTag),
+  ]).toString('base64');
+}
+
+/**
+ * Decrypt a workspace key with the master key
+ * @param encryptedKey - Base64-encoded encrypted key
+ * @param masterKey - The master key (from environment variable)
+ * @returns The decrypted workspace key
+ */
+export async function decryptWorkspaceKey(
+  encryptedKey: string,
+  masterKey: string
+): Promise<Buffer> {
+  const derivedKey = await getDerivedKey(masterKey);
+  const data = Buffer.from(encryptedKey, 'base64');
+
+  const iv = data.subarray(0, IV_LENGTH);
+  const encryptedAndTag = data.subarray(IV_LENGTH);
+
+  const decipher = gcm(new Uint8Array(derivedKey), new Uint8Array(iv));
+  const decrypted = decipher.decrypt(new Uint8Array(encryptedAndTag));
+
+  return Buffer.from(decrypted);
+}
+
+/**
+ * Encrypt a single field value
+ * @param plaintext - The plaintext value to encrypt
+ * @param workspaceKey - The decrypted workspace key
+ * @returns Base64-encoded ciphertext (iv + encrypted + authTag)
+ */
+export function encryptField(
+  plaintext: string,
+  workspaceKey: Buffer
+): EncryptedField {
+  if (!plaintext) {
+    return ''; // Don't encrypt empty strings
+  }
+
+  // Validate workspace key before using it
+  if (!Buffer.isBuffer(workspaceKey)) {
+    throw new Error(
+      `Invalid workspaceKey: expected Buffer, got ${typeof workspaceKey}`
+    );
+  }
+  if (workspaceKey.length !== KEY_LENGTH) {
+    throw new Error(
+      `Invalid workspaceKey: expected ${KEY_LENGTH} bytes for AES-256, got ${workspaceKey.length} bytes`
+    );
+  }
+
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = gcm(new Uint8Array(workspaceKey), new Uint8Array(iv));
+
+  const textBytes = new TextEncoder().encode(plaintext);
+  const encryptedAndTag = cipher.encrypt(new Uint8Array(textBytes));
+
+  return Buffer.concat([
+    Buffer.from(iv),
+    Buffer.from(encryptedAndTag),
+  ]).toString('base64');
+}
+
+/**
+ * Decrypt a single field value
+ * @param ciphertext - Base64-encoded ciphertext
+ * @param workspaceKey - The decrypted workspace key
+ * @returns The decrypted plaintext
+ */
+export function decryptField(
+  ciphertext: EncryptedField,
+  workspaceKey: Buffer
+): string {
+  if (!ciphertext) {
+    return ''; // Handle empty strings
+  }
+
+  const data = Buffer.from(ciphertext, 'base64');
+
+  if (data.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+    // Data too short to be encrypted - may indicate corruption or truncation
+    // Log a warning with diagnostic info (scrubbed to avoid leaking sensitive data)
+    const expectedMinLength = IV_LENGTH + AUTH_TAG_LENGTH;
+    const scrubbedSample = `${ciphertext.slice(0, 8)}...`;
+    console.warn(
+      `[decryptField] Data too short to decrypt: got ${data.length} bytes, ` +
+        `expected at least ${expectedMinLength} bytes. ` +
+        `Ciphertext sample: "${scrubbedSample}" (length: ${ciphertext.length}). ` +
+        `Returning original value for backward compatibility.`
+    );
+    return ciphertext;
+  }
+
+  const iv = data.subarray(0, IV_LENGTH);
+  const encryptedAndTag = data.subarray(IV_LENGTH);
+
+  try {
+    const decipher = gcm(new Uint8Array(workspaceKey), new Uint8Array(iv));
+    const decryptedBytes = decipher.decrypt(new Uint8Array(encryptedAndTag));
+    return new TextDecoder().decode(decryptedBytes);
+  } catch (error) {
+    // Decryption failed - log scrubbed warning and return original for backward compatibility
+    const scrubbedSample = `${ciphertext.slice(0, 8)}...`;
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+    console.warn(
+      `[decryptField] Decryption failed: ${errorMessage}. ` +
+        `Ciphertext sample: "${scrubbedSample}" (length: ${ciphertext.length}). ` +
+        `Returning original value for backward compatibility.`
+    );
+    return ciphertext;
+  }
+}
+
+/**
+ * Encrypt sensitive fields of a calendar event
+ * @param event - The calendar event with plaintext fields
+ * @param workspaceKey - The decrypted workspace key
+ * @returns The event with encrypted title, description, location
+ */
+export function encryptCalendarEventFields(
+  event: EncryptedCalendarEventFields,
+  workspaceKey: Buffer
+): EncryptedCalendarEventFields {
+  return {
+    title: encryptField(event.title || '', workspaceKey),
+    description: encryptField(event.description || '', workspaceKey),
+    location: event.location
+      ? encryptField(event.location, workspaceKey)
+      : undefined,
+  };
+}
+
+/**
+ * Decrypt sensitive fields of a calendar event
+ * @param event - The calendar event with encrypted fields
+ * @param workspaceKey - The decrypted workspace key
+ * @returns The event with decrypted title, description, location
+ */
+export function decryptCalendarEventFields(
+  event: EncryptedCalendarEventFields,
+  workspaceKey: Buffer
+): EncryptedCalendarEventFields {
+  return {
+    title: decryptField(event.title || '', workspaceKey),
+    description: decryptField(event.description || '', workspaceKey),
+    location: event.location
+      ? decryptField(event.location, workspaceKey)
+      : undefined,
+  };
+}
+
+/**
+ * Check if encryption is enabled (master key is configured)
+ */
+export function isEncryptionEnabled(): boolean {
+  return !!process.env.ENCRYPTION_MASTER_KEY?.trim();
+}
+
+/**
+ * Get the master key from environment
+ * @throws Error if master key is not configured
+ */
+export function getMasterKey(): string {
+  const masterKey = process.env.ENCRYPTION_MASTER_KEY?.trim();
+  if (!masterKey) {
+    throw new Error(
+      'ENCRYPTION_MASTER_KEY environment variable is not configured'
+    );
+  }
+  return masterKey;
+}
+
+/**
+ * Batch decrypt multiple calendar events
+ * After successful decryption, is_encrypted is set to false to indicate
+ * the event data is now plaintext (in memory).
+ */
+export function decryptCalendarEvents<
+  T extends {
+    is_encrypted?: boolean;
+    title?: string | null;
+    description?: string | null;
+    location?: string | null;
+    [key: string]: any;
+  },
+>(events: T[], workspaceKey: Buffer): T[] {
+  return events.map((event) => {
+    if (!event.is_encrypted) {
+      return event; // Already plaintext
+    }
+    const decrypted = decryptCalendarEventFields(
+      {
+        title: event.title ?? '',
+        description: event.description ?? '',
+        location: event.location ?? undefined,
+      },
+      workspaceKey
+    );
+    return {
+      ...event,
+      ...decrypted,
+      is_encrypted: false, // Mark as decrypted (plaintext in memory)
+    };
+  });
+}
+
+/**
+ * Batch encrypt multiple calendar events
+ */
+export function encryptCalendarEvents<T extends EncryptedCalendarEventFields>(
+  events: T[],
+  workspaceKey: Buffer
+): (T & { is_encrypted: boolean })[] {
+  return events.map((event) => {
+    const encrypted = encryptCalendarEventFields(
+      {
+        title: event.title,
+        description: event.description,
+        location: event.location,
+      },
+      workspaceKey
+    );
+    return {
+      ...event,
+      ...encrypted,
+      is_encrypted: true,
+    };
+  });
+}

package/src/encryption/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Encryption utilities for transparent encryption at rest
+ */
+
+export {
+  decryptCalendarEventFields,
+  decryptCalendarEvents,
+  decryptField,
+  decryptWorkspaceKey,
+  encryptCalendarEventFields,
+  encryptCalendarEvents,
+  encryptField,
+  encryptWorkspaceKey,
+  generateWorkspaceKey,
+  getMasterKey,
+  isEncryptionEnabled,
+} from './encryption-service';
+
+export type {
+  CalendarEventWithEncryption,
+  EncryptedCalendarEventFields,
+  EncryptedField,
+  EncryptionConfig,
+  WorkspaceEncryptionKey,
+} from './types';

package/src/encryption/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for workspace encryption
+ */
+
+import type { Tables } from '@tuturuuu/types';
+
+/**
+ * Encrypted calendar event - fields that can be encrypted
+ */
+export interface EncryptedCalendarEventFields {
+  title: string;
+  description: string;
+  location?: string;
+}
+
+/**
+ * Base calendar event type from database schema
+ */
+type BaseCalendarEvent = Tables<'workspace_calendar_events'>;
+
+/**
+ * Calendar event with encryption metadata
+ * Derived from canonical DB types to stay in sync with schema changes
+ */
+export type CalendarEventWithEncryption = Pick<
+  BaseCalendarEvent,
+  | 'id'
+  | 'title'
+  | 'description'
+  | 'location'
+  | 'start_at'
+  | 'end_at'
+  | 'color'
+  | 'ws_id'
+  | 'is_encrypted'
+>;
+
+/**
+ * Workspace encryption key record from database
+ * Re-exported from auto-generated types to stay in sync with schema
+ */
+export type { WorkspaceEncryptionKey } from '@tuturuuu/types';
+
+/**
+ * Encryption configuration
+ */
+export interface EncryptionConfig {
+  algorithm: 'AES-GCM';
+  keyLength: 256;
+  ivLength: 12;
+  tagLength: 128;
+}
+
+/**
+ * Encrypted field format: base64(iv + ciphertext + authTag)
+ */
+export type EncryptedField = string;

package/src/exchange-rates.ts

@@ -0,0 +1,49 @@
+export interface ExchangeRate {
+  base_currency: string;
+  target_currency: string;
+  rate: number;
+  date: string;
+}
+
+/**
+ * Convert an amount from one currency to another using USD-based exchange rates.
+ *
+ * @param amount - The amount to convert
+ * @param fromCurrency - Source currency code (e.g., 'EUR')
+ * @param toCurrency - Target currency code (e.g., 'VND')
+ * @param rates - Array of USD-based exchange rates
+ * @returns The converted amount, or null if conversion is not possible
+ */
+export function convertCurrency(
+  amount: number,
+  fromCurrency: string,
+  toCurrency: string,
+  rates: ExchangeRate[]
+): number | null {
+  const from = fromCurrency.toUpperCase();
+  const to = toCurrency.toUpperCase();
+
+  if (from === to) return amount;
+
+  // Find USD -> from and USD -> to rates
+  const fromRate =
+    from === 'USD'
+      ? 1
+      : (rates.find(
+          (r) =>
+            r.base_currency === 'USD' &&
+            r.target_currency.toUpperCase() === from
+        )?.rate ?? null);
+
+  const toRate =
+    to === 'USD'
+      ? 1
+      : (rates.find(
+          (r) =>
+            r.base_currency === 'USD' && r.target_currency.toUpperCase() === to
+        )?.rate ?? null);
+
+  if (fromRate === null || toRate === null || fromRate === 0) return null;
+
+  return amount * (toRate / fromRate);
+}