@iflow-mcp/jkheadley-instar 0.26.2

package/dist/messaging/AgentTokenManager.js

@@ -0,0 +1,213 @@
+/**
+ * AgentTokenManager — per-agent authentication tokens for cross-agent messaging.
+ *
+ * Each agent on the machine gets a 256-bit random token stored at:
+ *   ~/.instar/agent-tokens/{agentName}.token
+ *
+ * Tokens are generated on first agent registration and persist across restarts.
+ * Used for:
+ *   - Bearer auth on relay-agent endpoint (proving sender identity)
+ *   - HMAC computation on message drops (tamper protection for offline delivery)
+ *
+ * Security properties:
+ *   - Tokens are file-permission protected (0600 — owner read/write only)
+ *   - Token directory is 0700
+ *   - Agent names are validated to prevent path traversal
+ *
+ * Derived from: docs/specs/INTER-AGENT-MESSAGING-SPEC.md v3.1 §Cross-Agent Resolution
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+const TOKEN_SIZE_BYTES = 32; // 256 bits
+const TOKEN_DIR_NAME = 'agent-tokens';
+/** Get the token directory path */
+function tokenDir() {
+    return path.join(os.homedir(), '.instar', TOKEN_DIR_NAME);
+}
+/** Get the token file path for a specific agent */
+function tokenPath(agentName) {
+    return path.join(tokenDir(), `${agentName}.token`);
+}
+/**
+ * Validate an agent name for safe use in file paths.
+ * Rejects names with path separators, null bytes, dots, or non-alphanumeric chars.
+ */
+function validateTokenAgentName(name) {
+    if (!name || name.length > 64)
+        return false;
+    if (name.includes('/') || name.includes('\\') || name.includes('\0') || name.includes('..'))
+        return false;
+    return /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name);
+}
+/**
+ * Ensure the token directory exists with proper permissions.
+ */
+export function ensureTokenDir() {
+    const dir = tokenDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    // Enforce permissions even if dir already existed
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        // @silent-fallback-ok — chmod may fail on some filesystems, token files themselves are still protected
+    }
+}
+/**
+ * Generate a new agent token and persist it to disk.
+ * If a token already exists for this agent, returns the existing token.
+ *
+ * @param agentName - The agent's canonical name (validated for path safety)
+ * @returns The hex-encoded token string
+ */
+export function generateAgentToken(agentName) {
+    if (!validateTokenAgentName(agentName)) {
+        throw new Error(`Invalid agent name for token generation: "${agentName}"`);
+    }
+    ensureTokenDir();
+    const filePath = tokenPath(agentName);
+    // If token already exists, return it
+    if (fs.existsSync(filePath)) {
+        return fs.readFileSync(filePath, 'utf-8').trim();
+    }
+    // Generate new 256-bit random token
+    const token = crypto.randomBytes(TOKEN_SIZE_BYTES).toString('hex');
+    // Write with restricted permissions
+    fs.writeFileSync(filePath, token, { mode: 0o600, encoding: 'utf-8' });
+    return token;
+}
+/**
+ * Read an agent's token from disk.
+ * Used by the sending agent to authenticate with the target agent's relay endpoint.
+ *
+ * @param agentName - The target agent's name
+ * @returns The hex-encoded token, or null if no token exists
+ */
+export function getAgentToken(agentName) {
+    if (!validateTokenAgentName(agentName))
+        return null;
+    const filePath = tokenPath(agentName);
+    try {
+        return fs.readFileSync(filePath, 'utf-8').trim();
+    }
+    catch {
+        // @silent-fallback-ok — token file doesn't exist or not readable
+        return null;
+    }
+}
+/**
+ * Verify a bearer token matches the expected agent token.
+ * Used by the relay-agent endpoint to authenticate incoming requests.
+ *
+ * @param agentName - The agent whose token to check against
+ * @param bearerToken - The token provided in the Authorization header
+ * @returns true if the token matches
+ */
+export function verifyAgentToken(agentName, bearerToken) {
+    const stored = getAgentToken(agentName);
+    if (!stored || !bearerToken)
+        return false;
+    // Constant-time comparison to prevent timing attacks
+    const storedBuf = Buffer.from(stored, 'utf-8');
+    const providedBuf = Buffer.from(bearerToken, 'utf-8');
+    if (storedBuf.length !== providedBuf.length)
+        return false;
+    return crypto.timingSafeEqual(storedBuf, providedBuf);
+}
+/**
+ * Compute HMAC-SHA256 for a message drop envelope.
+ * Used when writing to the drop directory for offline same-machine delivery.
+ *
+ * The HMAC covers the same core fields as the cross-machine SignedPayload
+ * (minus relayChain and signature which don't apply to same-machine drops).
+ *
+ * @param agentToken - The sending agent's token
+ * @param fields - The fields to sign: { message, originServer, nonce, timestamp }
+ */
+export function computeDropHmac(agentToken, fields) {
+    // Canonical JSON: recursively sorted keys at all nesting levels.
+    // NOTE: Cannot use JSON.stringify(fields, arrayReplacer) because array replacers
+    // filter properties at EVERY nesting level, stripping inner message properties.
+    const canonical = canonicalJSON(fields);
+    return crypto.createHmac('sha256', agentToken).update(canonical).digest('hex');
+}
+/**
+ * Serialize an object to canonical JSON (RFC 8785 / JCS).
+ * Recursively sorts keys at all nesting levels for deterministic output.
+ */
+function canonicalJSON(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return JSON.stringify(value);
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJSON).join(',')}]`;
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        const pairs = keys
+            .filter(key => value[key] !== undefined)
+            .map(key => `${JSON.stringify(key)}:${canonicalJSON(value[key])}`);
+        return `{${pairs.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Verify HMAC on a received drop envelope.
+ *
+ * @param senderAgent - Name of the agent that wrote the drop
+ * @param hmac - The HMAC value from the envelope
+ * @param fields - The fields that were signed
+ * @returns true if the HMAC is valid
+ */
+export function verifyDropHmac(senderAgent, hmac, fields) {
+    const senderToken = getAgentToken(senderAgent);
+    if (!senderToken || !hmac)
+        return false;
+    const expected = computeDropHmac(senderToken, fields);
+    // Constant-time comparison
+    const expectedBuf = Buffer.from(expected, 'utf-8');
+    const providedBuf = Buffer.from(hmac, 'utf-8');
+    if (expectedBuf.length !== providedBuf.length)
+        return false;
+    return crypto.timingSafeEqual(expectedBuf, providedBuf);
+}
+/**
+ * Delete an agent's token. Used during agent unregistration.
+ */
+export function deleteAgentToken(agentName) {
+    if (!validateTokenAgentName(agentName))
+        return false;
+    const filePath = tokenPath(agentName);
+    try {
+        fs.unlinkSync(filePath);
+        return true;
+    }
+    catch {
+        // @silent-fallback-ok — file may not exist
+        return false;
+    }
+}
+/**
+ * List all agents that have tokens.
+ */
+export function listAgentTokens() {
+    try {
+        const dir = tokenDir();
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter(f => f.endsWith('.token'))
+            .map(f => f.replace(/\.token$/, ''));
+    }
+    catch {
+        // @silent-fallback-ok — directory not readable
+        return [];
+    }
+}
+//# sourceMappingURL=AgentTokenManager.js.map

package/dist/messaging/AgentTokenManager.js.map

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

package/dist/messaging/DeliveryRetryManager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DeliveryRetryManager — handles retry, watchdog, and TTL expiry for message delivery.
+ *
+ * Three responsibilities:
+ * 1. Retry delivery for queued messages (Layer 2 retry with exponential backoff)
+ * 2. Post-injection watchdog: after tmux injection, verify session is still alive
+ * 3. TTL expiry: move expired messages to dead-letter, escalate critical/alert to Telegram
+ *
+ * Per spec Phase 3: Layer 1 retry (server unreachable) uses exponential backoff
+ * with max 4-hour retry window. Layer 2 retry (session unavailable) retries
+ * every 30s for up to 5 minutes. Layer 3 timeout varies by message type.
+ */
+import type { MessageEnvelope } from './types.js';
+import type { MessageStore } from './MessageStore.js';
+import type { MessageDelivery } from './MessageDelivery.js';
+export interface DeliveryRetryManagerConfig {
+    /** Agent name for filtering messages */
+    agentName: string;
+    /** Callback for escalation (e.g., send to Telegram) */
+    onEscalate?: (envelope: MessageEnvelope, reason: string) => void;
+}
+export declare class DeliveryRetryManager {
+    private readonly store;
+    private readonly delivery;
+    private readonly config;
+    private timer;
+    /** Track watchdog targets: messageId → injection timestamp */
+    private readonly watchdogTargets;
+    /** Track retry state: messageId → { attempts, firstAttemptAt } */
+    private readonly retryState;
+    constructor(store: MessageStore, delivery: MessageDelivery, config: DeliveryRetryManagerConfig);
+    /** Start the periodic tick */
+    start(): void;
+    /** Stop the periodic tick */
+    stop(): void;
+    /** Register a message for post-injection watchdog monitoring */
+    registerWatchdog(messageId: string): void;
+    /** Main tick — runs every 15 seconds */
+    tick(): Promise<{
+        retried: number;
+        expired: number;
+        escalated: number;
+    }>;
+    /** Check if a message's delivery TTL has expired */
+    private isExpired;
+}
+//# sourceMappingURL=DeliveryRetryManager.d.ts.map

package/dist/messaging/DeliveryRetryManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeliveryRetryManager.d.ts","sourceRoot":"","sources":["../../src/messaging/DeliveryRetryManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA2B5D,MAAM,WAAW,0BAA0B;IACzC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,KAAK,CAA+C;IAE5D,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAE7D,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0F;gBAEzG,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,0BAA0B;IAM9F,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAKb,6BAA6B;IAC7B,IAAI,IAAI,IAAI;IASZ,gEAAgE;IAChE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC,wCAAwC;IAClC,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAiJ9E,oDAAoD;IACpD,OAAO,CAAC,SAAS;CAKlB"}

package/dist/messaging/DeliveryRetryManager.js

@@ -0,0 +1,201 @@
+/**
+ * DeliveryRetryManager — handles retry, watchdog, and TTL expiry for message delivery.
+ *
+ * Three responsibilities:
+ * 1. Retry delivery for queued messages (Layer 2 retry with exponential backoff)
+ * 2. Post-injection watchdog: after tmux injection, verify session is still alive
+ * 3. TTL expiry: move expired messages to dead-letter, escalate critical/alert to Telegram
+ *
+ * Per spec Phase 3: Layer 1 retry (server unreachable) uses exponential backoff
+ * with max 4-hour retry window. Layer 2 retry (session unavailable) retries
+ * every 30s for up to 5 minutes. Layer 3 timeout varies by message type.
+ */
+/** Layer 3 ACK timeout by message type (in minutes). null = no timeout (fire-and-forget) */
+const ACK_TIMEOUT = {
+    info: null,
+    sync: null,
+    alert: null,
+    request: 10,
+    query: 5,
+    response: null,
+    handoff: null,
+    wellness: 2,
+    system: null,
+};
+/** Layer 1 retry backoff schedule (seconds). Doubles after each attempt. */
+const LAYER1_BACKOFF_BASE_MS = 5_000;
+const LAYER1_MAX_INTERVAL_MS = 30 * 60_000; // 30 minutes
+const LAYER1_MAX_WINDOW_MS = 4 * 60 * 60_000; // 4 hours
+/** Layer 2 retry interval */
+const LAYER2_RETRY_INTERVAL_MS = 30_000; // 30 seconds
+const LAYER2_MAX_RETRIES = 10; // 5 minutes total
+/** How often the manager runs its tick */
+const TICK_INTERVAL_MS = 15_000; // 15 seconds
+export class DeliveryRetryManager {
+    store;
+    delivery;
+    config;
+    timer = null;
+    /** Track watchdog targets: messageId → injection timestamp */
+    watchdogTargets = new Map();
+    /** Track retry state: messageId → { attempts, firstAttemptAt } */
+    retryState = new Map();
+    constructor(store, delivery, config) {
+        this.store = store;
+        this.delivery = delivery;
+        this.config = config;
+    }
+    /** Start the periodic tick */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.tick(), TICK_INTERVAL_MS);
+    }
+    /** Stop the periodic tick */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.watchdogTargets.clear();
+        this.retryState.clear();
+    }
+    /** Register a message for post-injection watchdog monitoring */
+    registerWatchdog(messageId) {
+        this.watchdogTargets.set(messageId, Date.now());
+    }
+    /** Main tick — runs every 15 seconds */
+    async tick() {
+        let retried = 0;
+        let expired = 0;
+        let escalated = 0;
+        const inbox = await this.store.queryInbox(this.config.agentName);
+        for (const envelope of inbox) {
+            const phase = envelope.delivery.phase;
+            const messageId = envelope.message.id;
+            // ── TTL Expiry Check ──────────────────────────────────
+            if (this.isExpired(envelope)) {
+                if (phase !== 'read' && phase !== 'dead-lettered' && phase !== 'failed' && phase !== 'expired') {
+                    await this.store.deadLetter(messageId, 'TTL expired');
+                    expired++;
+                    // Escalate critical/alert to callback
+                    const priority = envelope.message.priority;
+                    const type = envelope.message.type;
+                    if ((priority === 'critical' || type === 'alert') && this.config.onEscalate) {
+                        this.config.onEscalate(envelope, `Message expired without delivery (type=${type}, priority=${priority})`);
+                        escalated++;
+                    }
+                }
+                continue;
+            }
+            // ── Layer 2 Retry: queued messages ────────────────────
+            if (phase === 'queued') {
+                const state = this.retryState.get(messageId) ?? {
+                    attempts: 0,
+                    firstAttemptAt: Date.now(),
+                    lastAttemptAt: 0,
+                };
+                if (state.attempts >= LAYER2_MAX_RETRIES) {
+                    // Max retries exceeded — expire
+                    await this.store.deadLetter(messageId, `Layer 2 max retries exceeded (${LAYER2_MAX_RETRIES})`);
+                    expired++;
+                    this.retryState.delete(messageId);
+                    continue;
+                }
+                const timeSinceLastAttempt = Date.now() - state.lastAttemptAt;
+                if (timeSinceLastAttempt < LAYER2_RETRY_INTERVAL_MS) {
+                    continue; // Not yet time to retry
+                }
+                // Attempt redelivery
+                const targetSession = envelope.message.to.session;
+                const result = await this.delivery.deliverToSession(targetSession, envelope);
+                state.attempts++;
+                state.lastAttemptAt = Date.now();
+                this.retryState.set(messageId, state);
+                if (result.success) {
+                    // Advance to delivered
+                    envelope.delivery.phase = 'delivered';
+                    envelope.delivery.transitions.push({
+                        from: 'queued',
+                        to: 'delivered',
+                        at: new Date().toISOString(),
+                        reason: `Retry attempt ${state.attempts}`,
+                    });
+                    envelope.delivery.attempts = state.attempts;
+                    await this.store.updateEnvelope(envelope);
+                    // Keep retryState so interval is respected if watchdog regresses to queued
+                    this.registerWatchdog(messageId);
+                    retried++;
+                }
+            }
+            // ── Layer 3 Timeout: unacknowledged delivered messages ─
+            if (phase === 'delivered') {
+                const timeout = ACK_TIMEOUT[envelope.message.type];
+                if (timeout !== null) {
+                    const deliveredAt = envelope.delivery.transitions
+                        .filter(t => t.to === 'delivered')
+                        .pop()?.at;
+                    if (deliveredAt) {
+                        const elapsed = Date.now() - new Date(deliveredAt).getTime();
+                        if (elapsed > timeout * 60_000) {
+                            // ACK timeout — escalate
+                            if (this.config.onEscalate) {
+                                this.config.onEscalate(envelope, `Layer 3 ACK timeout: ${envelope.message.type} message not acknowledged after ${timeout} minutes`);
+                                escalated++;
+                            }
+                            // Mark as expired
+                            envelope.delivery.phase = 'expired';
+                            envelope.delivery.transitions.push({
+                                from: 'delivered',
+                                to: 'expired',
+                                at: new Date().toISOString(),
+                                reason: `ACK timeout (${timeout}min) for type=${envelope.message.type}`,
+                            });
+                            await this.store.updateEnvelope(envelope);
+                            expired++;
+                        }
+                    }
+                }
+            }
+        }
+        // ── Watchdog: check injected messages ──────────────────
+        for (const [messageId, injectedAt] of this.watchdogTargets) {
+            const elapsed = Date.now() - injectedAt;
+            if (elapsed < 10_000)
+                continue; // Wait 10 seconds
+            // Watchdog window has passed — check if session is still alive
+            const envelope = await this.store.get(messageId);
+            if (!envelope || envelope.delivery.phase !== 'delivered') {
+                this.watchdogTargets.delete(messageId);
+                continue;
+            }
+            const targetSession = envelope.message.to.session;
+            const safety = await this.delivery.checkInjectionSafety(targetSession);
+            // If session process changed to something unsafe (crash/restart),
+            // regress to queued for retry
+            if (!safety.isSafeProcess) {
+                envelope.delivery.phase = 'queued';
+                envelope.delivery.transitions.push({
+                    from: 'delivered',
+                    to: 'queued',
+                    at: new Date().toISOString(),
+                    reason: `Watchdog: session process changed to ${safety.foregroundProcess}`,
+                });
+                await this.store.updateEnvelope(envelope);
+            }
+            else {
+                // Session healthy — delivery confirmed, clean up retry state
+                this.retryState.delete(messageId);
+            }
+            this.watchdogTargets.delete(messageId);
+        }
+        return { retried, expired, escalated };
+    }
+    /** Check if a message's delivery TTL has expired */
+    isExpired(envelope) {
+        const createdAt = new Date(envelope.message.createdAt).getTime();
+        const ttlMs = envelope.message.ttlMinutes * 60_000;
+        return Date.now() > createdAt + ttlMs;
+    }
+}
+//# sourceMappingURL=DeliveryRetryManager.js.map

package/dist/messaging/DeliveryRetryManager.js.map

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

package/dist/messaging/DropPickup.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DropPickup — ingest messages from the drop directory on server startup.
+ *
+ * When an agent is offline, other agents on the same machine write messages
+ * to ~/.instar/messages/drop/{agentName}/. On startup, this module scans
+ * the drop directory, verifies each envelope's HMAC, ingests valid messages,
+ * and cleans up processed files.
+ *
+ * Security: Each dropped envelope carries an HMAC-SHA256 computed with the
+ * sending agent's token. This prevents local processes from forging messages
+ * or tampering with routing metadata via the drop directory.
+ *
+ * Derived from: docs/specs/INTER-AGENT-MESSAGING-SPEC.md v3.1 §Cross-Agent Resolution
+ */
+import type { MessageStore } from './MessageStore.js';
+export interface DropPickupResult {
+    /** Number of messages successfully ingested */
+    ingested: number;
+    /** Number of messages rejected (invalid HMAC, bad format, etc.) */
+    rejected: number;
+    /** Number of messages skipped (already in store — dedup) */
+    duplicates: number;
+    /** Details of rejected messages for logging */
+    rejections: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+/**
+ * Scan the drop directory for this agent and ingest valid messages.
+ *
+ * @param agentName - This agent's name (used to locate drop dir and verify auth)
+ * @param store - The message store to ingest into
+ * @returns Summary of what was processed
+ */
+export declare function pickupDroppedMessages(agentName: string, store: MessageStore): Promise<DropPickupResult>;
+//# sourceMappingURL=DropPickup.d.ts.map

package/dist/messaging/DropPickup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropPickup.d.ts","sourceRoot":"","sources":["../../src/messaging/DropPickup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAiG3B"}

package/dist/messaging/DropPickup.js

@@ -0,0 +1,120 @@
+/**
+ * DropPickup — ingest messages from the drop directory on server startup.
+ *
+ * When an agent is offline, other agents on the same machine write messages
+ * to ~/.instar/messages/drop/{agentName}/. On startup, this module scans
+ * the drop directory, verifies each envelope's HMAC, ingests valid messages,
+ * and cleans up processed files.
+ *
+ * Security: Each dropped envelope carries an HMAC-SHA256 computed with the
+ * sending agent's token. This prevents local processes from forging messages
+ * or tampering with routing metadata via the drop directory.
+ *
+ * Derived from: docs/specs/INTER-AGENT-MESSAGING-SPEC.md v3.1 §Cross-Agent Resolution
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { verifyDropHmac } from './AgentTokenManager.js';
+/**
+ * Scan the drop directory for this agent and ingest valid messages.
+ *
+ * @param agentName - This agent's name (used to locate drop dir and verify auth)
+ * @param store - The message store to ingest into
+ * @returns Summary of what was processed
+ */
+export async function pickupDroppedMessages(agentName, store) {
+    const dropDir = path.join(os.homedir(), '.instar', 'messages', 'drop', agentName);
+    const result = {
+        ingested: 0,
+        rejected: 0,
+        duplicates: 0,
+        rejections: [],
+    };
+    // No drop directory = nothing to pick up
+    if (!fs.existsSync(dropDir)) {
+        return result;
+    }
+    let files;
+    try {
+        files = fs.readdirSync(dropDir).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        // @silent-fallback-ok — directory not readable, nothing to process
+        return result;
+    }
+    for (const file of files) {
+        const filePath = path.join(dropDir, file);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const envelope = JSON.parse(raw);
+            // Validate envelope structure
+            if (!envelope?.message?.id || !envelope?.transport || !envelope?.delivery) {
+                result.rejected++;
+                result.rejections.push({ file, reason: 'invalid envelope structure' });
+                unlinkSafe(filePath);
+                continue;
+            }
+            // Deduplication: skip if already in store
+            if (await store.exists(envelope.message.id)) {
+                result.duplicates++;
+                unlinkSafe(filePath);
+                continue;
+            }
+            // Verify HMAC if present
+            if (envelope.transport.hmac && envelope.transport.hmacBy) {
+                const valid = verifyDropHmac(envelope.transport.hmacBy, envelope.transport.hmac, {
+                    message: envelope.message,
+                    originServer: envelope.transport.originServer,
+                    nonce: envelope.transport.nonce,
+                    timestamp: envelope.transport.timestamp,
+                });
+                if (!valid) {
+                    result.rejected++;
+                    result.rejections.push({ file, reason: `invalid HMAC from ${envelope.transport.hmacBy}` });
+                    unlinkSafe(filePath);
+                    continue;
+                }
+            }
+            else {
+                // No HMAC — reject (spec requires HMAC on all drops)
+                result.rejected++;
+                result.rejections.push({ file, reason: 'missing HMAC' });
+                unlinkSafe(filePath);
+                continue;
+            }
+            // Update delivery phase to 'received'
+            const now = new Date().toISOString();
+            envelope.delivery = {
+                ...envelope.delivery,
+                phase: 'received',
+                transitions: [
+                    ...envelope.delivery.transitions,
+                    { from: envelope.delivery.phase, to: 'received', at: now, reason: 'picked up from drop directory' },
+                ],
+            };
+            // Ingest into store
+            await store.save(envelope);
+            result.ingested++;
+            // Clean up processed file
+            unlinkSafe(filePath);
+        }
+        catch {
+            // @silent-fallback-ok — malformed file, skip it
+            result.rejected++;
+            result.rejections.push({ file, reason: 'parse error or I/O failure' });
+            unlinkSafe(filePath);
+        }
+    }
+    return result;
+}
+/** Safely delete a file, ignoring errors */
+function unlinkSafe(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // @silent-fallback-ok — file may already be deleted
+    }
+}
+//# sourceMappingURL=DropPickup.js.map

package/dist/messaging/DropPickup.js.map

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