@tracehound/core 1.2.0

package/README.md

@@ -0,0 +1,125 @@
+# @tracehound/core
+
+Security buffer system for threat quarantine.
+Part of the Tracehound Cyberimmune System.
+
+## Status
+
+**Phase 1-4 Complete:** ✅
+
+- **Phase 1:** Foundation (Types, Utils)
+- **Phase 2:** Evidence, Quarantine, AuditChain
+- **Phase 3:** Agent, RateLimiter
+- **Phase 4:** HoundPool, Scheduler, Watcher, BinaryCodec
+
+## Installation
+
+```bash
+pnpm add @tracehound/core
+```
+
+## Core Components
+
+### 1. Agent (`IAgent`)
+
+The main entry point. Orchestrates the threat detection flow.
+
+- **Stateless:** Depends on injected services.
+- **Fail-safe:** Defaults to "clean" on error.
+
+```ts
+import {
+  createAgent,
+  createQuarantine,
+  createRateLimiter,
+  createEvidenceFactory,
+} from '@tracehound/core'
+
+const agent = createAgent({ maxPayloadSize: 1_000_000 })
+const result = agent.intercept(scent)
+```
+
+### 2. Hound Pool (`IHoundPool`)
+
+Process-separated child worker pool for evidence processing.
+
+- **Containment-Oriented:** Uses process separation and hardening flags; OS sandboxing depends on deployment policy.
+- **Fire-and-Forget:** Agent never awaits detection.
+- **Resilient:** Auto-replenish on crash/timeout.
+
+```ts
+// Activate analysis (returns immediately)
+houndPool.activate(evidence)
+```
+
+### 3. Watcher (`IWatcher`)
+
+Pull-based observability.
+
+- **Passive:** Does not emit events (no EventEmitter).
+- **Snapshot:** Provides immutable view of system state.
+
+```ts
+const snapshot = watcher.snapshot()
+console.log(`Threats: ${snapshot.threats.total}`)
+```
+
+### 4. Scheduler (`IScheduler`)
+
+Background task management.
+
+- **Jittered:** Prevents timing attacks.
+- **Load-Aware:** Skips ticks if system is busy (`skipIfBusy`).
+
+## Usage Example
+
+```ts
+import {
+  createAgent,
+  createQuarantine,
+  createRateLimiter,
+  createEvidenceFactory,
+  createHoundPool,
+  AuditChain,
+} from '@tracehound/core'
+
+// 1. Setup Dependencies
+const auditChain = new AuditChain()
+const quarantine = createQuarantine({ maxCount: 1000 }, auditChain)
+const rateLimiter = createRateLimiter({ windowMs: 60000, maxRequests: 100 })
+const factory = createEvidenceFactory()
+
+// 2. Create Agent
+const agent = createAgent({ maxPayloadSize: 1_000_000 }, quarantine, rateLimiter, factory)
+
+// 3. Intercept Traffic
+const result = agent.intercept({
+  id: 'req-1',
+  source: '192.168.1.1',
+  payload: { user: 'input' },
+  timestamp: Date.now(),
+})
+
+if (result.status === 'quarantined') {
+  console.log('Threat quarantined:', result.handle.signature)
+}
+```
+
+## Architecture
+
+```
+[Traffic] → (Agent) → [RateLimiter]
+               │
+               ▼
+[EvidenceFactory] → (Hash/Compress) → [Evidence]
+                                         │
+                                         ▼
+                                   [Quarantine]
+                                         │
+                                         ▼
+                                    (HoundPool) → [Analysis]
+```
+
+## License
+
+Open-Core — this package is the open-source substrate of the Tracehound ecosystem. See the root [PRICING.md](../../docs/PRICING.md) for details on the commercial satellite packages.

package/dist/core/agent.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent - core orchestrator for Tracehound intercept flow.
+ *
+ * SECURITY: Agent does NOT perform threat detection.
+ * Agent orchestrates: rate limiting → validation → factory → quarantine.
+ *
+ * RFC Contract:
+ * - If scent.threat present → quarantine
+ * - If scent.threat absent → clean
+ * - Tracehound DOES NOT make threat decisions
+ */
+import type { InterceptResult } from '../types/result.js';
+import type { Scent } from '../types/scent.js';
+import type { IEvidenceFactory } from './evidence-factory.js';
+import type { Quarantine } from './quarantine.js';
+import type { IRateLimiter } from './rate-limiter.js';
+/**
+ * Agent configuration (subset of TracehoundConfig).
+ */
+export interface AgentConfig {
+    /** Maximum payload size in bytes */
+    maxPayloadSize: number;
+}
+/**
+ * Agent interface.
+ */
+export interface IAgent {
+    /**
+     * Intercept a scent and process according to RFC.
+     *
+     * Flow:
+     * 1. Rate limit check → rate_limited
+     * 2. If no threat signal → clean
+     * 3. Validate & encode payload → payload_too_large | error
+     * 4. Generate signature via factory
+     * 5. Check duplicate → ignored
+     * 6. Create evidence & quarantine → quarantined
+     *
+     * @param scent - Input scent to process
+     * @returns Intercept result
+     */
+    intercept(scent: Scent): InterceptResult;
+}
+/**
+ * Agent statistics.
+ */
+export interface AgentStats {
+    /** Total intercepts processed */
+    totalIntercepts: number;
+    /** Clean (no threat signal) */
+    cleanCount: number;
+    /** Rate limited */
+    rateLimitedCount: number;
+    /** Payload validation failures */
+    validationFailures: number;
+    /** Duplicates ignored */
+    ignoredCount: number;
+    /** Successfully quarantined */
+    quarantinedCount: number;
+    /** Errors */
+    errorCount: number;
+}
+/**
+ * Agent implementation.
+ */
+export declare class Agent implements IAgent {
+    private readonly config;
+    private readonly quarantine;
+    private readonly rateLimiter;
+    private readonly evidenceFactory;
+    private readonly stats;
+    constructor(config: AgentConfig, quarantine: Quarantine, rateLimiter: IRateLimiter, evidenceFactory: IEvidenceFactory);
+    intercept(scent: Scent): InterceptResult;
+    /**
+     * Get current agent statistics.
+     */
+    getStats(): Readonly<AgentStats>;
+}
+/**
+ * Create an agent instance.
+ *
+ * @param config - Agent configuration
+ * @param quarantine - Quarantine instance
+ * @param rateLimiter - Rate limiter instance
+ * @param evidenceFactory - Evidence factory instance
+ * @returns Agent instance
+ */
+export declare function createAgent(config: AgentConfig, quarantine: Quarantine, rateLimiter: IRateLimiter, evidenceFactory: IEvidenceFactory): IAgent;
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,mBAAmB,CAAA;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAAA;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAA;IACvB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,mBAAmB;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,kCAAkC;IAClC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,qBAAa,KAAM,YAAW,MAAM;IAYhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAdlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAQrB;gBAGkB,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,YAAY,EACzB,eAAe,EAAE,gBAAgB;IAQpD,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe;IAmGxC;;OAEG;IACH,QAAQ,IAAI,QAAQ,CAAC,UAAU,CAAC;CAGjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,YAAY,EACzB,eAAe,EAAE,gBAAgB,GAChC,MAAM,CAER"}

package/dist/core/agent.js

@@ -0,0 +1,141 @@
+/**
+ * Agent - core orchestrator for Tracehound intercept flow.
+ *
+ * SECURITY: Agent does NOT perform threat detection.
+ * Agent orchestrates: rate limiting → validation → factory → quarantine.
+ *
+ * RFC Contract:
+ * - If scent.threat present → quarantine
+ * - If scent.threat absent → clean
+ * - Tracehound DOES NOT make threat decisions
+ */
+/**
+ * Agent implementation.
+ */
+export class Agent {
+    config;
+    quarantine;
+    rateLimiter;
+    evidenceFactory;
+    stats = {
+        totalIntercepts: 0,
+        cleanCount: 0,
+        rateLimitedCount: 0,
+        validationFailures: 0,
+        ignoredCount: 0,
+        quarantinedCount: 0,
+        errorCount: 0,
+    };
+    constructor(config, quarantine, rateLimiter, evidenceFactory) {
+        this.config = config;
+        this.quarantine = quarantine;
+        this.rateLimiter = rateLimiter;
+        this.evidenceFactory = evidenceFactory;
+        // Validate config
+        if (config.maxPayloadSize <= 0) {
+            throw new Error('maxPayloadSize must be positive');
+        }
+    }
+    intercept(scent) {
+        this.stats.totalIntercepts++;
+        try {
+            // Step 1: Rate limit check
+            const rateResult = this.rateLimiter.check(scent.source);
+            if (!rateResult.allowed) {
+                this.stats.rateLimitedCount++;
+                return {
+                    status: 'rate_limited',
+                    retryAfter: rateResult.retryAfter,
+                };
+            }
+            // Step 2: Check for threat signal
+            if (!scent.threat) {
+                // No threat signal = clean
+                // Tracehound does NOT make threat detection decisions
+                this.stats.cleanCount++;
+                return { status: 'clean' };
+            }
+            // Step 3: Create evidence via factory
+            // Factory handles: validation, encoding, hashing, signature generation
+            const creationResult = this.evidenceFactory.create(scent, scent.threat, this.config.maxPayloadSize);
+            if (!creationResult.ok) {
+                // Check if it's a payload size error
+                if (creationResult.error.code === 'AGENT_PAYLOAD_TOO_LARGE') {
+                    this.stats.validationFailures++;
+                    return {
+                        status: 'payload_too_large',
+                        limit: this.config.maxPayloadSize,
+                    };
+                }
+                // Other errors
+                this.stats.errorCount++;
+                return {
+                    status: 'error',
+                    error: creationResult.error,
+                };
+            }
+            const { evidence, signature } = creationResult;
+            // Step 4: Check for duplicate in quarantine
+            if (this.quarantine.has(signature)) {
+                // Duplicate - already have evidence for this signature
+                // Evidence was created but not needed, dispose it
+                evidence.neutralize('');
+                this.stats.ignoredCount++;
+                return {
+                    status: 'ignored',
+                    signature,
+                };
+            }
+            // Step 5: Insert into quarantine
+            const insertResult = this.quarantine.insert(evidence);
+            if (insertResult.status === 'duplicate') {
+                // Race condition: became duplicate between has() and insert()
+                // Evidence already disposed by duplicate detection
+                this.stats.ignoredCount++;
+                return {
+                    status: 'ignored',
+                    signature,
+                };
+            }
+            // Success
+            this.stats.quarantinedCount++;
+            return {
+                status: 'quarantined',
+                handle: evidence,
+            };
+        }
+        catch (error) {
+            this.stats.errorCount++;
+            const tracehoundError = {
+                state: 'agent',
+                code: 'INTERCEPT_FAILED',
+                message: error instanceof Error ? error.message : 'Unknown error during intercept',
+                context: { scentId: scent.id },
+                recoverable: false,
+            };
+            return {
+                status: 'error',
+                error: tracehoundError,
+            };
+        }
+    }
+    /**
+     * Get current agent statistics.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+}
+/**
+ * Create an agent instance.
+ *
+ * @param config - Agent configuration
+ * @param quarantine - Quarantine instance
+ * @param rateLimiter - Rate limiter instance
+ * @param evidenceFactory - Evidence factory instance
+ * @returns Agent instance
+ */
+export function createAgent(config, quarantine, rateLimiter, evidenceFactory) {
+    return new Agent(config, quarantine, rateLimiter, evidenceFactory);
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

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

package/dist/core/audit-chain.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AuditChain - cryptographic hash chain for evidence integrity.
+ */
+import type { AuditRecord, IAuditChain } from '../types/audit.js';
+import type { EvacuateRecord, NeutralizationRecord } from '../types/evidence.js';
+/** Genesis hash (anchor for chain) */
+export declare const GENESIS_HASH: string;
+/**
+ * Cryptographic hash chain for audit integrity.
+ * Each record contains hash of previous record.
+ * Tampering with any record breaks the chain.
+ */
+export declare class AuditChain implements IAuditChain {
+    private records;
+    private _lastHash;
+    get lastHash(): string;
+    get length(): number;
+    /**
+     * Append a record to the chain.
+     */
+    append(record: NeutralizationRecord | EvacuateRecord): void;
+    /**
+     * Verify chain integrity.
+     */
+    verify(): boolean;
+    /**
+     * Export all records (defensive copy).
+     */
+    export(): AuditRecord[];
+    /**
+     * Compute hash for a new record.
+     */
+    private computeHash;
+    /**
+     * Recompute hash for verification.
+     */
+    private recomputeHash;
+}
+//# sourceMappingURL=audit-chain.d.ts.map

package/dist/core/audit-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-chain.d.ts","sourceRoot":"","sources":["../../src/core/audit-chain.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhF,sCAAsC;AACtC,eAAO,MAAM,YAAY,QAAiB,CAAA;AAE1C;;;;GAIG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAuB;IAExC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,GAAG,IAAI;IAgB3D;;OAEG;IACH,MAAM,IAAI,OAAO;IAqBjB;;OAEG;IACH,MAAM,IAAI,WAAW,EAAE;IAIvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,aAAa;CAStB"}

package/dist/core/audit-chain.js

@@ -0,0 +1,87 @@
+/**
+ * AuditChain - cryptographic hash chain for evidence integrity.
+ */
+import { createHash } from 'node:crypto';
+/** Genesis hash (anchor for chain) */
+export const GENESIS_HASH = '0'.repeat(64);
+/**
+ * Cryptographic hash chain for audit integrity.
+ * Each record contains hash of previous record.
+ * Tampering with any record breaks the chain.
+ */
+export class AuditChain {
+    records = [];
+    _lastHash = GENESIS_HASH;
+    get lastHash() {
+        return this._lastHash;
+    }
+    get length() {
+        return this.records.length;
+    }
+    /**
+     * Append a record to the chain.
+     */
+    append(record) {
+        const hash = this.computeHash(record, this._lastHash);
+        const auditRecord = {
+            id: record.id,
+            type: 'status' in record ? 'neutralization' : 'evacuation',
+            signature: record.signature,
+            timestamp: record.timestamp,
+            previousHash: this._lastHash,
+            hash,
+        };
+        this.records.push(auditRecord);
+        this._lastHash = hash;
+    }
+    /**
+     * Verify chain integrity.
+     */
+    verify() {
+        let expectedPreviousHash = GENESIS_HASH;
+        for (const record of this.records) {
+            // Check chain continuity
+            if (record.previousHash !== expectedPreviousHash) {
+                return false;
+            }
+            // Check hash integrity
+            const computedHash = this.recomputeHash(record);
+            if (computedHash !== record.hash) {
+                return false;
+            }
+            expectedPreviousHash = record.hash;
+        }
+        return true;
+    }
+    /**
+     * Export all records (defensive copy).
+     */
+    export() {
+        return [...this.records];
+    }
+    /**
+     * Compute hash for a new record.
+     */
+    computeHash(record, previousHash) {
+        const data = JSON.stringify({
+            id: record.id,
+            signature: record.signature,
+            timestamp: record.timestamp,
+            previousHash,
+        });
+        return createHash('sha256').update(data).digest('hex');
+    }
+    /**
+     * Recompute hash for verification.
+     */
+    recomputeHash(record) {
+        const data = JSON.stringify({
+            id: record.id,
+            signature: record.signature,
+            timestamp: record.timestamp,
+            previousHash: record.previousHash,
+        });
+        return createHash('sha256').update(data).digest('hex');
+    }
+}
+//# sourceMappingURL=audit-chain.js.map

package/dist/core/audit-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-chain.js","sourceRoot":"","sources":["../../src/core/audit-chain.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAIxC,sCAAsC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAE1C;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACb,OAAO,GAAkB,EAAE,CAAA;IAC3B,SAAS,GAAW,YAAY,CAAA;IAExC,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;IAC5B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAA6C;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAErD,MAAM,WAAW,GAAgB;YAC/B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,YAAY;YAC1D,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY,EAAE,IAAI,CAAC,SAAS;YAC5B,IAAI;SACL,CAAA;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;IACvB,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,IAAI,oBAAoB,GAAG,YAAY,CAAA;QAEvC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,yBAAyB;YACzB,IAAI,MAAM,CAAC,YAAY,KAAK,oBAAoB,EAAE,CAAC;gBACjD,OAAO,KAAK,CAAA;YACd,CAAC;YAED,uBAAuB;YACvB,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAA;YAC/C,IAAI,YAAY,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;gBACjC,OAAO,KAAK,CAAA;YACd,CAAC;YAED,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAA;QACpC,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,MAA6C,EAAE,YAAoB;QACrF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY;SACb,CAAC,CAAA;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACxD,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,MAAmB;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAA;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACxD,CAAC;CACF"}

package/dist/core/cold-storage.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Cold Storage Adapter
+ *
+ * Fire-and-forget interface for archiving evidence to external storage.
+ * Used by Quarantine.evacuate() for long-term forensic storage.
+ *
+ * RFC-0000 INVARIANTS:
+ * - write() is fire-and-forget (no blocking hot-path)
+ * - Adapter errors are logged, not thrown
+ * - Payload must be encoded with encodeWithIntegrity() before write
+ */
+import type { EncodedPayload } from '../utils/binary-codec.js';
+/**
+ * Cold storage write result.
+ */
+export interface ColdStorageWriteResult {
+    /** Whether write succeeded */
+    success: boolean;
+    /** Storage-specific ID (e.g., S3 key, URL) */
+    id?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Cold storage read result.
+ */
+export interface ColdStorageReadResult {
+    /** Whether read succeeded */
+    success: boolean;
+    /** Encoded payload if found */
+    payload?: EncodedPayload;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Cold Storage Adapter interface.
+ *
+ * Implementations: MemoryColdStorage (testing), S3Adapter, R2Adapter, etc.
+ */
+export interface IColdStorageAdapter {
+    /**
+     * Write encoded evidence to cold storage.
+     * Fire-and-forget semantics - caller does not wait.
+     *
+     * @param id - Unique evidence ID (signature)
+     * @param payload - Encoded and hashed payload
+     */
+    write(id: string, payload: EncodedPayload): Promise<ColdStorageWriteResult>;
+    /**
+     * Read evidence from cold storage.
+     * Used for forensics/evacuation only.
+     *
+     * @param id - Evidence ID to retrieve
+     */
+    read(id: string): Promise<ColdStorageReadResult>;
+    /**
+     * Delete evidence from cold storage.
+     * Used for policy-based cleanup.
+     *
+     * @param id - Evidence ID to delete
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Check if storage is available.
+     */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * In-memory cold storage for testing.
+ * NOT for production use.
+ */
+export declare class MemoryColdStorage implements IColdStorageAdapter {
+    private readonly storage;
+    write(id: string, payload: EncodedPayload): Promise<ColdStorageWriteResult>;
+    read(id: string): Promise<ColdStorageReadResult>;
+    delete(id: string): Promise<boolean>;
+    isAvailable(): Promise<boolean>;
+    /** Get storage size (testing helper) */
+    get size(): number;
+    /** Clear all storage (testing helper) */
+    clear(): void;
+}
+/**
+ * Create an in-memory cold storage adapter for testing.
+ */
+export declare function createMemoryColdStorage(): IColdStorageAdapter;
+//# sourceMappingURL=cold-storage.d.ts.map

package/dist/core/cold-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cold-storage.d.ts","sourceRoot":"","sources":["../../src/core/cold-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,8CAA8C;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAE3E;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAEhD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEpC;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAChC;AAMD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,mBAAmB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAEtD,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAK3E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAQhD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,yCAAyC;IACzC,KAAK,IAAI,IAAI;CAGd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,mBAAmB,CAE7D"}

package/dist/core/cold-storage.js

@@ -0,0 +1,53 @@
+/**
+ * Cold Storage Adapter
+ *
+ * Fire-and-forget interface for archiving evidence to external storage.
+ * Used by Quarantine.evacuate() for long-term forensic storage.
+ *
+ * RFC-0000 INVARIANTS:
+ * - write() is fire-and-forget (no blocking hot-path)
+ * - Adapter errors are logged, not thrown
+ * - Payload must be encoded with encodeWithIntegrity() before write
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// In-Memory Implementation (Testing)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * In-memory cold storage for testing.
+ * NOT for production use.
+ */
+export class MemoryColdStorage {
+    storage = new Map();
+    async write(id, payload) {
+        this.storage.set(id, payload);
+        return { success: true, id };
+    }
+    async read(id) {
+        const payload = this.storage.get(id);
+        if (payload) {
+            return { success: true, payload };
+        }
+        return { success: false, error: 'Not found' };
+    }
+    async delete(id) {
+        return this.storage.delete(id);
+    }
+    async isAvailable() {
+        return true;
+    }
+    /** Get storage size (testing helper) */
+    get size() {
+        return this.storage.size;
+    }
+    /** Clear all storage (testing helper) */
+    clear() {
+        this.storage.clear();
+    }
+}
+/**
+ * Create an in-memory cold storage adapter for testing.
+ */
+export function createMemoryColdStorage() {
+    return new MemoryColdStorage();
+}
+//# sourceMappingURL=cold-storage.js.map

package/dist/core/cold-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cold-storage.js","sourceRoot":"","sources":["../../src/core/cold-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiEH,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IAE5D,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,OAAuB;QAC7C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;QAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACpC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;QACnC,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAA;IAC/C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAChC,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAA;IACb,CAAC;IAED,wCAAwC;IACxC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;IAED,yCAAyC;IACzC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,iBAAiB,EAAE,CAAA;AAChC,CAAC"}