@tracehound/core 1.2.0

package/dist/types/signature.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Signature generation and validation.
+ */
+import type { ThreatInput } from './threat.js';
+/**
+ * Options for signature generation.
+ */
+export interface GenerateSignatureOptions {
+    /** Maximum payload size in bytes. Default: 1MB */
+    maxPayloadSize?: number;
+}
+/**
+ * Generate a content-based, collision-resistant threat signature.
+ *
+ * Format: {category}:{sha256(payload)}
+ *
+ * Uses deterministic serialization to ensure identical payloads
+ * produce identical signatures regardless of key order.
+ *
+ * SECURITY INVARIANTS:
+ * - Validates payload structure (rejects undefined, NaN, Infinity, etc.)
+ * - Checks size before hashing (memory exhaustion prevention)
+ * - Hashes UTF-8 bytes directly (split-brain prevention)
+ *
+ * @param threat - Threat input (without signature)
+ * @param options - Optional configuration
+ * @returns Signature string
+ * @throws TracehoundError if payload validation fails
+ */
+export declare function generateSignature(threat: ThreatInput, options?: GenerateSignatureOptions): string;
+/**
+ * Compare two signatures in constant time.
+ * MUST be used for all signature comparisons to prevent timing attacks.
+ *
+ * @param a - First signature
+ * @param b - Second signature
+ * @returns True if signatures are equal
+ */
+export declare function compareSignatures(a: string, b: string): boolean;
+/**
+ * Validate a signature format.
+ *
+ * @param sig - Signature to validate
+ * @returns True if valid format
+ */
+export declare function validateSignature(sig: string): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/types/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/types/signature.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAK9C;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,wBAA6B,GACrC,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAetD"}

package/dist/types/signature.js

@@ -0,0 +1,68 @@
+/**
+ * Signature generation and validation.
+ */
+import { constantTimeEqual } from '../utils/compare.js';
+import { encodePayload } from '../utils/encode.js';
+import { hashBuffer } from '../utils/hash.js';
+/** Default max payload size for signature generation (1MB) */
+const DEFAULT_MAX_PAYLOAD_SIZE = 1_000_000;
+/**
+ * Generate a content-based, collision-resistant threat signature.
+ *
+ * Format: {category}:{sha256(payload)}
+ *
+ * Uses deterministic serialization to ensure identical payloads
+ * produce identical signatures regardless of key order.
+ *
+ * SECURITY INVARIANTS:
+ * - Validates payload structure (rejects undefined, NaN, Infinity, etc.)
+ * - Checks size before hashing (memory exhaustion prevention)
+ * - Hashes UTF-8 bytes directly (split-brain prevention)
+ *
+ * @param threat - Threat input (without signature)
+ * @param options - Optional configuration
+ * @returns Signature string
+ * @throws TracehoundError if payload validation fails
+ */
+export function generateSignature(threat, options = {}) {
+    const maxSize = options.maxPayloadSize ?? DEFAULT_MAX_PAYLOAD_SIZE;
+    // CRITICAL: Use encodePayload for full validation
+    // This enforces: structure validation, size check, canonical encoding
+    const { bytes } = encodePayload(threat.scent.payload, maxSize);
+    const contentHash = hashBuffer(bytes);
+    return `${threat.category}:${contentHash}`;
+}
+/**
+ * Compare two signatures in constant time.
+ * MUST be used for all signature comparisons to prevent timing attacks.
+ *
+ * @param a - First signature
+ * @param b - Second signature
+ * @returns True if signatures are equal
+ */
+export function compareSignatures(a, b) {
+    return constantTimeEqual(a, b);
+}
+/**
+ * Validate a signature format.
+ *
+ * @param sig - Signature to validate
+ * @returns True if valid format
+ */
+export function validateSignature(sig) {
+    const colonIndex = sig.indexOf(':');
+    if (colonIndex === -1)
+        return false;
+    const category = sig.slice(0, colonIndex);
+    const contentHash = sig.slice(colonIndex + 1);
+    // Category must not be empty
+    if (category.length === 0)
+        return false;
+    // Hash must be 64 hex characters (SHA-256)
+    if (contentHash.length !== 64)
+        return false;
+    if (!/^[a-f0-9]+$/.test(contentHash))
+        return false;
+    return true;
+}
+//# sourceMappingURL=signature.js.map

package/dist/types/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/types/signature.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8DAA8D;AAC9D,MAAM,wBAAwB,GAAG,SAAS,CAAA;AAU1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,UAAoC,EAAE;IAEtC,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAA;IAElE,kDAAkD;IAClD,sEAAsE;IACtE,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAE9D,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IACrC,OAAO,GAAG,MAAM,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAA;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,OAAO,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACnC,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAEnC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;IACzC,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IAE7C,6BAA6B;IAC7B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEvC,2CAA2C;IAC3C,IAAI,WAAW,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAA;IAElD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/types/threat.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Threat - a classified scent with signature.
+ */
+import type { Severity } from './common.js';
+import type { Scent, ThreatCategory } from './scent.js';
+export type { ThreatCategory, ThreatSignal } from './scent.js';
+/**
+ * A threat is a scent that has been classified as malicious
+ * and assigned a signature for deduplication.
+ */
+export interface Threat {
+    /** Content-based, collision-resistant signature */
+    readonly signature: string;
+    /** Classification category */
+    readonly category: ThreatCategory;
+    /** Severity level */
+    readonly severity: Severity;
+    /** Original scent */
+    readonly scent: Scent;
+}
+/**
+ * Input for threat classification (before signature generation).
+ * Used internally by EvidenceFactory.
+ */
+export interface ThreatInput {
+    /** Classification category */
+    readonly category: ThreatCategory;
+    /** Severity level */
+    readonly severity: Severity;
+    /** Original scent */
+    readonly scent: Scent;
+}
+/**
+ * Create ThreatInput from Scent with threat signal.
+ * Helper function for type conversion.
+ */
+export declare function createThreatInput(scent: Scent): ThreatInput | null;
+//# sourceMappingURL=threat.d.ts.map

package/dist/types/threat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threat.d.ts","sourceRoot":"","sources":["../../src/types/threat.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGvD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9D;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,GAAG,IAAI,CASlE"}

package/dist/types/threat.js

@@ -0,0 +1,18 @@
+/**
+ * Threat - a classified scent with signature.
+ */
+/**
+ * Create ThreatInput from Scent with threat signal.
+ * Helper function for type conversion.
+ */
+export function createThreatInput(scent) {
+    if (!scent.threat) {
+        return null;
+    }
+    return {
+        category: scent.threat.category,
+        severity: scent.threat.severity,
+        scent,
+    };
+}
+//# sourceMappingURL=threat.js.map

package/dist/types/threat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threat.js","sourceRoot":"","sources":["../../src/types/threat.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoCH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC5C,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ;QAC/B,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ;QAC/B,KAAK;KACN,CAAA;AACH,CAAC"}

package/dist/utils/binary-codec.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Binary Codec - gzip encoding for evidence storage.
+ *
+ * SECURITY INVARIANT:
+ * - `encode()` used in hot-path (Agent → EvidenceFactory)
+ * - `decode()` ONLY for cold storage / forensics
+ * - Agent / Hound Pool MUST NOT have access to decode
+ *
+ * INTEGRITY INVARIANT (Cold Storage):
+ * - Always call verify() BEFORE decode()
+ * - Decoding without verification is a DoS vector
+ * - Empty payloads are VALID (originalSize=0, compressedSize>0)
+ */
+/**
+ * Hot-path codec interface.
+ * Used by Agent, EvidenceFactory, Hound Pool.
+ * NO decode access - security by design.
+ */
+export interface HotPathCodec {
+    /**
+     * Encode bytes to compressed format.
+     * Used in hot-path for evidence creation.
+     */
+    encode(bytes: Uint8Array): Uint8Array;
+}
+/**
+ * Cold-path codec interface.
+ * Used ONLY for: evacuate, cold storage retrieval, forensics.
+ * Extends HotPathCodec with decode capability.
+ */
+export interface ColdPathCodec extends HotPathCodec {
+    /**
+     * Decode compressed bytes back to original.
+     * NOT used in Agent/Hound hot-path.
+     */
+    decode(bytes: Uint8Array): Uint8Array;
+}
+/**
+ * Codec statistics.
+ */
+export interface CodecStats {
+    /** Total encode operations */
+    encodeCount: number;
+    /** Total decode operations */
+    decodeCount: number;
+    /** Total bytes before encoding */
+    totalInputBytes: number;
+    /** Total bytes after encoding */
+    totalOutputBytes: number;
+    /** Average compression ratio */
+    compressionRatio: number;
+}
+/**
+ * Gzip codec implementation.
+ * Provides both hot-path and cold-path capabilities.
+ *
+ * USAGE:
+ * - Pass as HotPathCodec to Agent/EvidenceFactory
+ * - Pass as ColdPathCodec only to cold storage / forensics tools
+ */
+export declare class GzipCodec implements ColdPathCodec {
+    private _encodeCount;
+    private _decodeCount;
+    private _totalInputBytes;
+    private _totalOutputBytes;
+    /**
+     * Encode bytes using gzip compression.
+     * Sync operation for hot-path performance.
+     */
+    encode(bytes: Uint8Array): Uint8Array;
+    /**
+     * Decode gzip compressed bytes.
+     * ONLY for cold storage retrieval / forensics.
+     */
+    decode(bytes: Uint8Array): Uint8Array;
+    /**
+     * Get codec statistics (immutable snapshot).
+     */
+    get stats(): Readonly<CodecStats>;
+}
+/**
+ * Create a hot-path codec (encode only).
+ * Use this for Agent / EvidenceFactory.
+ *
+ * @returns HotPathCodec with no decode access
+ */
+export declare function createHotPathCodec(): HotPathCodec;
+/**
+ * Create a cold-path codec (encode + decode).
+ * Use ONLY for cold storage / forensics.
+ *
+ * @returns ColdPathCodec with full access
+ */
+export declare function createColdPathCodec(): ColdPathCodec;
+/**
+ * Async hot-path codec interface.
+ * Non-blocking encode for background operations.
+ */
+export interface AsyncHotPathCodec {
+    /** Async encode bytes to compressed format. */
+    encode(bytes: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Async cold-path codec interface.
+ * Non-blocking encode + decode for cold storage operations.
+ * Extends AsyncHotPathCodec with decode capability.
+ */
+export interface AsyncColdPathCodec extends AsyncHotPathCodec {
+    /** Async decode compressed bytes back to original. */
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Async gzip codec implementation.
+ * Uses Node.js non-blocking zlib for cold storage and background operations.
+ *
+ * USAGE:
+ * - Cold storage write/read (never blocks the event loop)
+ * - Batch evidence evacuation
+ * - Background forensic analysis
+ *
+ * NOT for hot-path — use GzipCodec (sync) for Agent/EvidenceFactory.
+ */
+export declare class AsyncGzipCodec implements AsyncColdPathCodec {
+    private _encodeCount;
+    private _decodeCount;
+    private _totalInputBytes;
+    private _totalOutputBytes;
+    /**
+     * Async encode bytes using gzip compression.
+     * Non-blocking — yields to event loop during compression.
+     */
+    encode(bytes: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Async decode gzip compressed bytes.
+     * Non-blocking — yields to event loop during decompression.
+     */
+    decode(bytes: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Get codec statistics (immutable snapshot).
+     */
+    get stats(): Readonly<CodecStats>;
+}
+/**
+ * Create an async cold-path codec (encode + decode).
+ * Use for cold storage operations where blocking is unacceptable.
+ *
+ * @returns AsyncColdPathCodec with non-blocking encode/decode
+ */
+export declare function createAsyncColdPathCodec(): AsyncColdPathCodec;
+/**
+ * Encoded payload with compression and integrity hash.
+ * Used for cold storage serialization.
+ */
+export interface EncodedPayload {
+    /** gzip compressed bytes */
+    readonly compressed: Uint8Array;
+    /** SHA-256 hash of compressed bytes (hex) */
+    readonly hash: string;
+    /** Original uncompressed size in bytes */
+    readonly originalSize: number;
+    /** Compressed size in bytes */
+    readonly compressedSize: number;
+}
+/**
+ * Codec error for integrity violations.
+ */
+export declare class CodecError extends Error {
+    readonly code: 'INTEGRITY_VIOLATION' | 'DECODE_FAILED' | 'ENCODE_FAILED';
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: 'INTEGRITY_VIOLATION' | 'DECODE_FAILED' | 'ENCODE_FAILED', cause?: unknown | undefined);
+}
+/**
+ * Encode payload for cold storage with integrity hash.
+ *
+ * - Compresses with gzip
+ * - Computes SHA-256 of compressed bytes
+ * - Empty payloads are VALID (originalSize=0, compressedSize>0)
+ *
+ * @param payload - Raw bytes to encode
+ * @returns Encoded payload with hash
+ */
+export declare function encodeWithIntegrity(payload: Uint8Array): EncodedPayload;
+/**
+ * Verify integrity of encoded payload.
+ *
+ * MUST be called BEFORE decodeWithIntegrity().
+ * This is a cheap operation (hash only, no decompression).
+ *
+ * @param encoded - Payload to verify
+ * @returns true if hash matches, false if tampered
+ */
+export declare function verify(encoded: EncodedPayload): boolean;
+/**
+ * Decode payload from cold storage.
+ *
+ * CRITICAL: Call verify() first. Decoding untrusted data wastes CPU.
+ *
+ * @param encoded - Verified encoded payload
+ * @returns Original uncompressed bytes
+ * @throws CodecError if decompression fails (storage corruption)
+ */
+export declare function decodeWithIntegrity(encoded: EncodedPayload): Uint8Array;
+/**
+ * Async encode payload for cold storage with integrity hash.
+ * Non-blocking version of encodeWithIntegrity().
+ *
+ * Use for cold storage write operations where event loop must not stall.
+ *
+ * @param payload - Raw bytes to encode
+ * @returns Encoded payload with hash
+ * @throws CodecError if compression fails
+ */
+export declare function encodeWithIntegrityAsync(payload: Uint8Array): Promise<EncodedPayload>;
+/**
+ * Async decode payload from cold storage.
+ * Non-blocking version of decodeWithIntegrity().
+ *
+ * CRITICAL: Call verify() first. Decoding untrusted data wastes CPU.
+ *
+ * @param encoded - Verified encoded payload
+ * @returns Original uncompressed bytes
+ * @throws CodecError if decompression fails (storage corruption)
+ */
+export declare function decodeWithIntegrityAsync(encoded: EncodedPayload): Promise<Uint8Array>;
+//# sourceMappingURL=binary-codec.d.ts.map

package/dist/utils/binary-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-codec.d.ts","sourceRoot":"","sources":["../../src/utils/binary-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAA;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAA;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAA;IACvB,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAA;IACxB,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,SAAU,YAAW,aAAa;IAC7C,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAE7B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAcrC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAOrC;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAUhC;CACF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAMjD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD;AAMD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IACvD,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAE7B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAWpD;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAOpD;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAUhC;CACF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAE7D;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;aAGjB,IAAI,EAAE,qBAAqB,GAAG,eAAe,GAAG,eAAe;aAC/D,KAAK,CAAC,EAAE,OAAO;gBAF/B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,qBAAqB,GAAG,eAAe,GAAG,eAAe,EAC/D,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAWvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAGvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CASvE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAe3F;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAO3F"}

package/dist/utils/binary-codec.js

@@ -0,0 +1,266 @@
+/**
+ * Binary Codec - gzip encoding for evidence storage.
+ *
+ * SECURITY INVARIANT:
+ * - `encode()` used in hot-path (Agent → EvidenceFactory)
+ * - `decode()` ONLY for cold storage / forensics
+ * - Agent / Hound Pool MUST NOT have access to decode
+ *
+ * INTEGRITY INVARIANT (Cold Storage):
+ * - Always call verify() BEFORE decode()
+ * - Decoding without verification is a DoS vector
+ * - Empty payloads are VALID (originalSize=0, compressedSize>0)
+ */
+import { promisify } from 'node:util';
+import { gunzip, gunzipSync, gzip, gzipSync } from 'node:zlib';
+import { hashBuffer } from './hash.js';
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+/**
+ * Gzip codec implementation.
+ * Provides both hot-path and cold-path capabilities.
+ *
+ * USAGE:
+ * - Pass as HotPathCodec to Agent/EvidenceFactory
+ * - Pass as ColdPathCodec only to cold storage / forensics tools
+ */
+export class GzipCodec {
+    _encodeCount = 0;
+    _decodeCount = 0;
+    _totalInputBytes = 0;
+    _totalOutputBytes = 0;
+    /**
+     * Encode bytes using gzip compression.
+     * Sync operation for hot-path performance.
+     */
+    encode(bytes) {
+        this._encodeCount++;
+        this._totalInputBytes += bytes.length;
+        const compressed = gzipSync(bytes, {
+            level: 6, // Balanced speed/compression
+        });
+        const result = new Uint8Array(compressed);
+        this._totalOutputBytes += result.length;
+        return result;
+    }
+    /**
+     * Decode gzip compressed bytes.
+     * ONLY for cold storage retrieval / forensics.
+     */
+    decode(bytes) {
+        this._decodeCount++;
+        const decompressed = gunzipSync(bytes);
+        return new Uint8Array(decompressed);
+    }
+    /**
+     * Get codec statistics (immutable snapshot).
+     */
+    get stats() {
+        const ratio = this._totalInputBytes > 0 ? this._totalOutputBytes / this._totalInputBytes : 0;
+        return Object.freeze({
+            encodeCount: this._encodeCount,
+            decodeCount: this._decodeCount,
+            totalInputBytes: this._totalInputBytes,
+            totalOutputBytes: this._totalOutputBytes,
+            compressionRatio: ratio,
+        });
+    }
+}
+/**
+ * Create a hot-path codec (encode only).
+ * Use this for Agent / EvidenceFactory.
+ *
+ * @returns HotPathCodec with no decode access
+ */
+export function createHotPathCodec() {
+    const codec = new GzipCodec();
+    // Return only HotPathCodec interface - no decode access
+    return {
+        encode: (bytes) => codec.encode(bytes),
+    };
+}
+/**
+ * Create a cold-path codec (encode + decode).
+ * Use ONLY for cold storage / forensics.
+ *
+ * @returns ColdPathCodec with full access
+ */
+export function createColdPathCodec() {
+    return new GzipCodec();
+}
+/**
+ * Async gzip codec implementation.
+ * Uses Node.js non-blocking zlib for cold storage and background operations.
+ *
+ * USAGE:
+ * - Cold storage write/read (never blocks the event loop)
+ * - Batch evidence evacuation
+ * - Background forensic analysis
+ *
+ * NOT for hot-path — use GzipCodec (sync) for Agent/EvidenceFactory.
+ */
+export class AsyncGzipCodec {
+    _encodeCount = 0;
+    _decodeCount = 0;
+    _totalInputBytes = 0;
+    _totalOutputBytes = 0;
+    /**
+     * Async encode bytes using gzip compression.
+     * Non-blocking — yields to event loop during compression.
+     */
+    async encode(bytes) {
+        this._encodeCount++;
+        this._totalInputBytes += bytes.length;
+        const compressed = await gzipAsync(bytes, { level: 6 });
+        const result = new Uint8Array(compressed);
+        this._totalOutputBytes += result.length;
+        return result;
+    }
+    /**
+     * Async decode gzip compressed bytes.
+     * Non-blocking — yields to event loop during decompression.
+     */
+    async decode(bytes) {
+        this._decodeCount++;
+        const decompressed = await gunzipAsync(bytes);
+        return new Uint8Array(decompressed);
+    }
+    /**
+     * Get codec statistics (immutable snapshot).
+     */
+    get stats() {
+        const ratio = this._totalInputBytes > 0 ? this._totalOutputBytes / this._totalInputBytes : 0;
+        return Object.freeze({
+            encodeCount: this._encodeCount,
+            decodeCount: this._decodeCount,
+            totalInputBytes: this._totalInputBytes,
+            totalOutputBytes: this._totalOutputBytes,
+            compressionRatio: ratio,
+        });
+    }
+}
+/**
+ * Create an async cold-path codec (encode + decode).
+ * Use for cold storage operations where blocking is unacceptable.
+ *
+ * @returns AsyncColdPathCodec with non-blocking encode/decode
+ */
+export function createAsyncColdPathCodec() {
+    return new AsyncGzipCodec();
+}
+/**
+ * Codec error for integrity violations.
+ */
+export class CodecError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'CodecError';
+    }
+}
+/**
+ * Encode payload for cold storage with integrity hash.
+ *
+ * - Compresses with gzip
+ * - Computes SHA-256 of compressed bytes
+ * - Empty payloads are VALID (originalSize=0, compressedSize>0)
+ *
+ * @param payload - Raw bytes to encode
+ * @returns Encoded payload with hash
+ */
+export function encodeWithIntegrity(payload) {
+    const compressed = gzipSync(payload, { level: 6 });
+    const compressedBytes = new Uint8Array(compressed);
+    const hash = hashBuffer(compressedBytes);
+    return {
+        compressed: compressedBytes,
+        hash,
+        originalSize: payload.length,
+        compressedSize: compressedBytes.length,
+    };
+}
+/**
+ * Verify integrity of encoded payload.
+ *
+ * MUST be called BEFORE decodeWithIntegrity().
+ * This is a cheap operation (hash only, no decompression).
+ *
+ * @param encoded - Payload to verify
+ * @returns true if hash matches, false if tampered
+ */
+export function verify(encoded) {
+    const computed = hashBuffer(encoded.compressed);
+    return computed === encoded.hash;
+}
+/**
+ * Decode payload from cold storage.
+ *
+ * CRITICAL: Call verify() first. Decoding untrusted data wastes CPU.
+ *
+ * @param encoded - Verified encoded payload
+ * @returns Original uncompressed bytes
+ * @throws CodecError if decompression fails (storage corruption)
+ */
+export function decodeWithIntegrity(encoded) {
+    try {
+        const decompressed = gunzipSync(encoded.compressed);
+        return new Uint8Array(decompressed);
+    }
+    catch (err) {
+        // Decompression failure = integrity violation or storage corruption
+        // NEVER swallow this error - propagate for Fail-Safe handling
+        throw new CodecError('Decompression failed - possible storage corruption', 'DECODE_FAILED', err);
+    }
+}
+// ============================================================================
+// ASYNC COLD STORAGE INTEGRITY (Non-blocking encode/decode for cold storage)
+// ============================================================================
+/**
+ * Async encode payload for cold storage with integrity hash.
+ * Non-blocking version of encodeWithIntegrity().
+ *
+ * Use for cold storage write operations where event loop must not stall.
+ *
+ * @param payload - Raw bytes to encode
+ * @returns Encoded payload with hash
+ * @throws CodecError if compression fails
+ */
+export async function encodeWithIntegrityAsync(payload) {
+    try {
+        const compressed = await gzipAsync(payload, { level: 6 });
+        const compressedBytes = new Uint8Array(compressed);
+        const hash = hashBuffer(compressedBytes);
+        return {
+            compressed: compressedBytes,
+            hash,
+            originalSize: payload.length,
+            compressedSize: compressedBytes.length,
+        };
+    }
+    catch (err) {
+        throw new CodecError('Async compression failed', 'ENCODE_FAILED', err);
+    }
+}
+/**
+ * Async decode payload from cold storage.
+ * Non-blocking version of decodeWithIntegrity().
+ *
+ * CRITICAL: Call verify() first. Decoding untrusted data wastes CPU.
+ *
+ * @param encoded - Verified encoded payload
+ * @returns Original uncompressed bytes
+ * @throws CodecError if decompression fails (storage corruption)
+ */
+export async function decodeWithIntegrityAsync(encoded) {
+    try {
+        const decompressed = await gunzipAsync(encoded.compressed);
+        return new Uint8Array(decompressed);
+    }
+    catch (err) {
+        throw new CodecError('Async decompression failed - possible storage corruption', 'DECODE_FAILED', err);
+    }
+}
+//# sourceMappingURL=binary-codec.js.map