@longarc/mdash 3.1.1 → 3.1.3

package/src/context/crypto/hmac.ts

@@ -0,0 +1,253 @@
+/**
+ * Caret — HMAC Seal Utilities
+ * @module @longarcstudios/caret/crypto/hmac
+ * 
+ * HMAC-SHA256 implementation for tamper-evident sealing.
+ * Seals bind content to a secret key — any modification invalidates the seal.
+ */
+
+import type { Seal, Hash } from '../types.js';
+import { deterministicStringify, constantTimeEqual } from './hash.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const ALGORITHM = { name: 'HMAC', hash: 'SHA-256' };
+const KEY_USAGES: KeyUsage[] = ['sign', 'verify'];
+
+// SECURITY: HKDF_INFO must match core/crypto.ts to ensure cross-module
+// seal verification works. Unified in SA-2026-008 (Feb 13, 2026).
+// Prior value 'caret-seal-v1' caused silent verification failures.
+const HKDF_INFO = new TextEncoder().encode('mdash-seal-v3');
+const HKDF_SALT = new TextEncoder().encode('caret-context-primitive-engine');
+
+// ============================================================================
+// KEY MANAGEMENT
+// ============================================================================
+
+/**
+ * Derive an HMAC key from a master key using HKDF.
+ * SECURITY: Key is bound to 'mdash-seal-v3' context, unified with core/crypto.ts.
+ */
+async function deriveKey(masterKey: string): Promise<CryptoKey> {
+  const crypto = await getCrypto();
+  const encoder = new TextEncoder();
+  const keyMaterial = encoder.encode(masterKey);
+  
+  // Import as raw key material for HKDF
+  const baseKey = await crypto.importKey(
+    'raw',
+    keyMaterial,
+    'HKDF',
+    false,
+    ['deriveKey']
+  );
+  
+  // Derive HMAC key using HKDF
+  return crypto.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: HKDF_SALT,
+      info: HKDF_INFO,
+    },
+    baseKey,
+    ALGORITHM,
+    false, // not extractable
+    KEY_USAGES
+  );
+}
+
+/**
+ * Get crypto implementation (same as hash.ts).
+ */
+async function getCrypto(): Promise<SubtleCrypto> {
+  if (typeof window !== 'undefined' && window.crypto?.subtle) {
+    return window.crypto.subtle;
+  }
+  
+  if (typeof globalThis !== 'undefined' && (globalThis as any).crypto?.subtle) {
+    return (globalThis as any).crypto.subtle;
+  }
+  
+  try {
+    const crypto = await import('crypto');
+    if (crypto.webcrypto?.subtle) {
+      return crypto.webcrypto.subtle as SubtleCrypto;
+    }
+  } catch {
+    // Import failed
+  }
+  
+  throw new Error('No crypto implementation available');
+}
+
+/**
+ * Convert ArrayBuffer to hex string.
+ */
+function bufferToHex(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let hex = '';
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    if (byte !== undefined) {
+      hex += byte.toString(16).padStart(2, '0');
+    }
+  }
+  return hex;
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Generate an HMAC-SHA256 seal for content.
+ * 
+ * @param content - The content to seal (will be JSON-stringified)
+ * @param key - The secret key
+ * @returns Promise resolving to the seal
+ * 
+ * @example
+ * ```ts
+ * const seal = await hmacSeal({ data: 'sensitive' }, 'secret-key');
+ * ```
+ */
+export async function hmacSeal(content: unknown, key: string): Promise<Seal> {
+  const crypto = await getCrypto();
+  const cryptoKey = await deriveKey(key); // SECURITY: Use HKDF-derived key
+  const encoder = new TextEncoder();
+  
+  // Deterministic serialization
+  const data = encoder.encode(deterministicStringify(content));
+  
+  const signature = await crypto.sign(ALGORITHM, cryptoKey, data);
+  return bufferToHex(signature) as Seal;
+}
+
+/**
+ * Verify an HMAC seal against content.
+ * 
+ * @param content - The content to verify
+ * @param seal - The seal to check
+ * @param key - The secret key
+ * @returns Promise resolving to boolean
+ */
+export async function hmacVerify(content: unknown, seal: Seal, key: string): Promise<boolean> {
+  const expectedSeal = await hmacSeal(content, key);
+  return constantTimeEqual(seal, expectedSeal);
+}
+
+/**
+ * Create a seal binding multiple values together.
+ * Useful for sealing a fragment with all its metadata.
+ * 
+ * @param values - Object with named values to seal
+ * @param key - The secret key
+ * @returns Promise resolving to the seal
+ */
+export async function hmacSealMultiple(
+  values: Record<string, unknown>, 
+  key: string
+): Promise<Seal> {
+  // Sort keys and create deterministic representation
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(values).sort();
+  for (const k of keys) {
+    sorted[k] = values[k];
+  }
+  
+  return hmacSeal(sorted, key);
+}
+
+/**
+ * Generate a seal for a context fragment.
+ * Seals all critical fields to detect any tampering.
+ * 
+ * @param fragment - Fragment data to seal (without the seal field)
+ * @param key - The secret key
+ * @returns Promise resolving to the seal
+ */
+export async function sealFragment(
+  fragment: {
+    id: string;
+    hash: Hash;
+    content: unknown;
+    provenance: unknown;
+    sealed_at: string;
+    constraints: unknown;
+  },
+  key: string
+): Promise<Seal> {
+  // Create canonical representation for sealing
+  // SECURITY: _v binds seal to protocol version, preventing downgrade attacks
+  const canonical = {
+    _v: 1,
+    id: fragment.id,
+    hash: fragment.hash,
+    content: fragment.content,
+    provenance: fragment.provenance,
+    sealed_at: fragment.sealed_at,
+    constraints: fragment.constraints,
+  };
+  
+  return hmacSeal(canonical, key);
+}
+
+/**
+ * Verify a fragment's seal.
+ * 
+ * @param fragment - The fragment to verify
+ * @param key - The secret key
+ * @returns Promise resolving to boolean
+ */
+export async function verifyFragmentSeal(
+  fragment: {
+    id: string;
+    hash: Hash;
+    content: unknown;
+    provenance: unknown;
+    sealed_at: string;
+    constraints: unknown;
+    seal: Seal;
+  },
+  key: string
+): Promise<boolean> {
+  // SECURITY: Must match _v from sealFragment
+  const canonical = {
+    _v: 1,
+    id: fragment.id,
+    hash: fragment.hash,
+    content: fragment.content,
+    provenance: fragment.provenance,
+    sealed_at: fragment.sealed_at,
+    constraints: fragment.constraints,
+  };
+  
+  return hmacVerify(canonical, fragment.seal, key);
+}
+
+// ============================================================================
+// SEAL UTILITIES
+// ============================================================================
+
+/**
+ * Validate seal format.
+ */
+export function isValidSeal(value: string): value is Seal {
+  return typeof value === 'string' && 
+    value.length === 64 && 
+    /^[a-f0-9]+$/i.test(value);
+}
+
+/**
+ * Parse a string as a Seal, throwing if invalid.
+ */
+export function parseSeal(value: string): Seal {
+  if (!isValidSeal(value)) {
+    // SECURITY: Do not leak input value in error message
+    throw new Error('Invalid seal format');
+  }
+  return value;
+}

package/src/context/crypto/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Caret — Cryptographic Utilities
+ * @module @longarcstudios/caret/crypto
+ */
+
+export {
+  sha256,
+  sha256Object,
+  sha256Binary,
+  rollingHash,
+  verifyHash,
+  verifyObjectHash,
+  isValidHash,
+  parseHash,
+  unsafeHash,
+  hexToBuffer,
+  deterministicStringify,
+  constantTimeEqual,
+} from './hash.js';
+
+export {
+  hmacSeal,
+  hmacVerify,
+  hmacSealMultiple,
+  sealFragment,
+  verifyFragmentSeal,
+  isValidSeal,
+  parseSeal,
+} from './hmac.js';