@longarc/mdash 3.1.2 → 3.1.3

package/dist/context/crypto/hash.js

@@ -0,0 +1,248 @@
+/**
+ * Caret — Cryptographic Hash Utilities
+ * @module @longarcstudios/caret/crypto/hash
+ *
+ * SHA-256 implementation using Web Crypto API (browser + Node compatible).
+ * All hashing is deterministic — same input always produces same output.
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/** SHA-256 produces 256 bits = 64 hex characters */
+const HASH_LENGTH = 64;
+/** Algorithm identifier for Web Crypto */
+const ALGORITHM = 'SHA-256';
+// ============================================================================
+// TEXT ENCODER
+// ============================================================================
+/**
+ * Get TextEncoder instance.
+ * Works in both browser and Node.js environments.
+ */
+const getEncoder = () => {
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder();
+    }
+    // Node.js fallback (though TextEncoder is available in Node 11+)
+    throw new Error('TextEncoder not available');
+};
+// ============================================================================
+// CRYPTO IMPLEMENTATION
+// ============================================================================
+/**
+ * Get the crypto implementation for the current environment.
+ * Supports browser (window.crypto) and Node.js (crypto.subtle).
+ */
+async function getCrypto() {
+    // Browser environment
+    if (typeof window !== 'undefined' && window.crypto?.subtle) {
+        return window.crypto.subtle;
+    }
+    // Node.js environment
+    if (typeof globalThis !== 'undefined' && globalThis.crypto?.subtle) {
+        return globalThis.crypto.subtle;
+    }
+    // Node.js < 19 fallback
+    try {
+        const crypto = await import('crypto');
+        if (crypto.webcrypto?.subtle) {
+            return crypto.webcrypto.subtle;
+        }
+    }
+    catch {
+        // Import failed
+    }
+    throw new Error('No crypto implementation available');
+}
+/**
+ * Convert ArrayBuffer to hexadecimal string.
+ */
+function bufferToHex(buffer) {
+    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;
+}
+/**
+ * Convert hexadecimal string to ArrayBuffer.
+ */
+export function hexToBuffer(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('Invalid hex string length');
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    }
+    return bytes.buffer;
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Compute SHA-256 hash of a string.
+ *
+ * @param input - The string to hash
+ * @returns Promise resolving to the hash as a branded Hash type
+ *
+ * @example
+ * ```ts
+ * const hash = await sha256('hello world');
+ * // => 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'
+ * ```
+ */
+export async function sha256(input) {
+    const crypto = await getCrypto();
+    const encoder = getEncoder();
+    const data = encoder.encode(input);
+    const hashBuffer = await crypto.digest(ALGORITHM, data);
+    return bufferToHex(hashBuffer);
+}
+/**
+ * Compute SHA-256 hash of binary data.
+ *
+ * @param data - The binary data to hash
+ * @returns Promise resolving to the hash
+ */
+export async function sha256Binary(data) {
+    const crypto = await getCrypto();
+    const buffer = data instanceof Uint8Array ? new Uint8Array(data).buffer : data;
+    const hashBuffer = await crypto.digest(ALGORITHM, buffer);
+    return bufferToHex(hashBuffer);
+}
+/**
+ * Compute SHA-256 hash of a JSON-serializable object.
+ * Uses deterministic JSON serialization (sorted keys).
+ *
+ * @param obj - The object to hash
+ * @returns Promise resolving to the hash
+ *
+ * @example
+ * ```ts
+ * const hash = await sha256Object({ b: 2, a: 1 });
+ * // Same as sha256Object({ a: 1, b: 2 }) — deterministic
+ * ```
+ */
+export async function sha256Object(obj) {
+    const json = deterministicStringify(obj);
+    return sha256(json);
+}
+/**
+ * Compute a rolling hash combining multiple hashes.
+ * Used for chain verification in provenance tracking.
+ *
+ * @param hashes - Array of hashes to combine
+ * @returns Promise resolving to the combined hash
+ */
+export async function rollingHash(hashes) {
+    if (hashes.length === 0) {
+        // Hash of empty string for empty input
+        return sha256('');
+    }
+    if (hashes.length === 1) {
+        const first = hashes[0];
+        if (!first)
+            return sha256('');
+        return first;
+    }
+    // Concatenate all hashes and hash the result
+    const combined = hashes.join('');
+    return sha256(combined);
+}
+/**
+ * Verify that a hash matches expected content.
+ *
+ * @param content - The content to verify
+ * @param expectedHash - The expected hash
+ * @returns Promise resolving to boolean
+ */
+export async function verifyHash(content, expectedHash) {
+    const actualHash = await sha256(content);
+    return constantTimeEqual(actualHash, expectedHash);
+}
+/**
+ * Verify that an object's hash matches expected.
+ *
+ * @param obj - The object to verify
+ * @param expectedHash - The expected hash
+ * @returns Promise resolving to boolean
+ */
+export async function verifyObjectHash(obj, expectedHash) {
+    const actualHash = await sha256Object(obj);
+    return constantTimeEqual(actualHash, expectedHash);
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * Deterministic JSON stringify with sorted keys.
+ * Ensures same object always produces same string.
+ */
+export function deterministicStringify(obj) {
+    return JSON.stringify(obj, (_, value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            // Sort object keys
+            const sorted = {};
+            const keys = Object.keys(value).sort();
+            for (const key of keys) {
+                sorted[key] = value[key];
+            }
+            return sorted;
+        }
+        return value;
+    });
+}
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns true if equal, false otherwise
+ */
+export function constantTimeEqual(a, b) {
+    // Use the longer length to prevent early exit timing leak
+    const len = Math.max(a.length, b.length);
+    // Track both the XOR result and length mismatch
+    let result = a.length ^ b.length; // Will be non-zero if lengths differ
+    for (let i = 0; i < len; i++) {
+        // Use 0 for out-of-bounds access (safe because result already tracks length diff)
+        const charA = i < a.length ? a.charCodeAt(i) : 0;
+        const charB = i < b.length ? b.charCodeAt(i) : 0;
+        result |= charA ^ charB;
+    }
+    return result === 0;
+}
+/**
+ * Validate that a string is a valid SHA-256 hash.
+ *
+ * @param value - The value to validate
+ * @returns true if valid hash format
+ */
+export function isValidHash(value) {
+    return typeof value === 'string' &&
+        value.length === HASH_LENGTH &&
+        /^[a-f0-9]+$/i.test(value);
+}
+/**
+ * Create a Hash type from a raw string (unsafe — no validation).
+ * Use only when you've already validated the input.
+ */
+export function unsafeHash(value) {
+    return value;
+}
+/**
+ * Parse a string as a Hash, throwing if invalid.
+ */
+export function parseHash(value) {
+    if (!isValidHash(value)) {
+        // SECURITY: Do not leak input value in error message
+        throw new Error('Invalid hash format');
+    }
+    return value;
+}
+//# sourceMappingURL=hash.js.map

package/dist/context/crypto/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/context/crypto/hash.ts"],"names":[],"mappings":"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"}

package/dist/context/crypto/hmac.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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';
+/**
+ * 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 declare function hmacSeal(content: unknown, key: string): Promise<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 declare function hmacVerify(content: unknown, seal: Seal, key: string): Promise<boolean>;
+/**
+ * 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 declare function hmacSealMultiple(values: Record<string, unknown>, key: string): Promise<Seal>;
+/**
+ * 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 declare function sealFragment(fragment: {
+    id: string;
+    hash: Hash;
+    content: unknown;
+    provenance: unknown;
+    sealed_at: string;
+    constraints: unknown;
+}, key: string): Promise<Seal>;
+/**
+ * Verify a fragment's seal.
+ *
+ * @param fragment - The fragment to verify
+ * @param key - The secret key
+ * @returns Promise resolving to boolean
+ */
+export declare function verifyFragmentSeal(fragment: {
+    id: string;
+    hash: Hash;
+    content: unknown;
+    provenance: unknown;
+    sealed_at: string;
+    constraints: unknown;
+    seal: Seal;
+}, key: string): Promise<boolean>;
+/**
+ * Validate seal format.
+ */
+export declare function isValidSeal(value: string): value is Seal;
+/**
+ * Parse a string as a Seal, throwing if invalid.
+ */
+export declare function parseSeal(value: string): Seal;
+//# sourceMappingURL=hmac.d.ts.map

package/dist/context/crypto/hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.d.ts","sourceRoot":"","sources":["../../../src/context/crypto/hmac.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAgG9C;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3E;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5F;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE;IACR,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,EACD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE;IACR,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;CACZ,EACD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,CAalB;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAIxD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM7C"}

package/dist/context/crypto/hmac.js

@@ -0,0 +1,192 @@
+/**
+ * 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 { deterministicStringify, constantTimeEqual } from './hash.js';
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const ALGORITHM = { name: 'HMAC', hash: 'SHA-256' };
+const KEY_USAGES = ['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) {
+    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() {
+    if (typeof window !== 'undefined' && window.crypto?.subtle) {
+        return window.crypto.subtle;
+    }
+    if (typeof globalThis !== 'undefined' && globalThis.crypto?.subtle) {
+        return globalThis.crypto.subtle;
+    }
+    try {
+        const crypto = await import('crypto');
+        if (crypto.webcrypto?.subtle) {
+            return crypto.webcrypto.subtle;
+        }
+    }
+    catch {
+        // Import failed
+    }
+    throw new Error('No crypto implementation available');
+}
+/**
+ * Convert ArrayBuffer to hex string.
+ */
+function bufferToHex(buffer) {
+    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, key) {
+    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);
+}
+/**
+ * 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, seal, key) {
+    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, key) {
+    // Sort keys and create deterministic representation
+    const sorted = {};
+    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, key) {
+    // 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, key) {
+    // 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) {
+    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) {
+    if (!isValidSeal(value)) {
+        // SECURITY: Do not leak input value in error message
+        throw new Error('Invalid seal format');
+    }
+    return value;
+}
+//# sourceMappingURL=hmac.js.map

package/dist/context/crypto/hmac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../../../src/context/crypto/hmac.ts"],"names":[],"mappings":"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"}

package/dist/context/crypto/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/crypto/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/crypto/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,SAAS,GACV,MAAM,WAAW,CAAC"}

package/dist/context/crypto/index.js

@@ -0,0 +1,7 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/context/crypto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/context/crypto/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,SAAS,GACV,MAAM,WAAW,CAAC"}