threadforge 0.1.0 → 0.2.1

package/dist/core/SignatureCache.js

@@ -0,0 +1,172 @@
+/**
+ * SignatureCache - Rotating HMAC signature cache for internal RPC optimization
+ *
+ * P-PERF-29: Reduce per-request HMAC computation cost by caching signatures with
+ * periodic rotation. Maintains replay protection guarantees while reducing CPU overhead.
+ *
+ * Security Model:
+ * - Signatures rotate every 5 seconds (configurable)
+ * - Multiple signatures active during overlap window for clock drift tolerance
+ * - Replay protection window: 30 seconds (INTERNAL_SIG_MAX_AGE_MS)
+ * - Rotation interval (5s) << replay window (30s) = safe
+ *
+ * Performance:
+ * - Reduces HMAC computations by ~5s/rotation_interval ratio
+ * - At 1000 RPS: 5000 HMAC ops/rotation vs 1 per rotation = ~5000x reduction
+ * - Memory overhead: ~200 bytes per cached signature entry
+ */
+import { createHmac } from "node:crypto";
+const MIN_SECRET_LENGTH = 32;
+/**
+ * SignatureCache maintains a rotating set of precomputed HMAC signatures
+ * for internal RPC authentication. Reduces per-request CPU cost while
+ * preserving replay protection guarantees.
+ */
+export class SignatureCache {
+    secret;
+    rotationIntervalMs;
+    enabled;
+    // Current and previous signatures for overlap tolerance, keyed by method:path
+    currentSignatures = new Map();
+    previousSignatures = new Map();
+    // Current rotation timestamp (shared across all keys)
+    currentTimestamp = null;
+    previousTimestamp = null;
+    // Timer for automatic rotation
+    rotationTimer = null;
+    constructor(secret, config = {}) {
+        this.secret = secret;
+        this.rotationIntervalMs = config.rotationIntervalMs ?? 5000; // 5 seconds default
+        this.enabled = config.enabled ?? false; // Opt-in for safety
+        // SEC-L2: Warn on short FORGE_INTERNAL_SECRET
+        if (secret.length < MIN_SECRET_LENGTH) {
+            process.stderr.write(`${JSON.stringify({
+                timestamp: new Date().toISOString(),
+                level: "warn",
+                message: `FORGE_INTERNAL_SECRET is shorter than ${MIN_SECRET_LENGTH} characters — this is insecure. Use a longer secret in production.`,
+            })}\n`);
+        }
+        if (this.rotationIntervalMs < 1000) {
+            throw new Error("rotationIntervalMs must be at least 1000ms");
+        }
+        // Validate rotation interval doesn't exceed replay window
+        // INTERNAL_SIG_MAX_AGE_MS is 30000ms - rotation should be significantly smaller
+        const REPLAY_WINDOW_MS = 30000;
+        if (this.rotationIntervalMs >= REPLAY_WINDOW_MS / 2) {
+            throw new Error(`rotationIntervalMs (${this.rotationIntervalMs}ms) must be less than half the replay window (${REPLAY_WINDOW_MS}ms)`);
+        }
+        if (this.enabled) {
+            this._initializeCache();
+            this._startRotation();
+        }
+    }
+    /**
+     * Get a signature for the given method and path.
+     * If caching is disabled, computes a fresh signature each time.
+     * If caching is enabled, returns the current cached signature.
+     */
+    getSignature(method, path) {
+        if (!this.enabled) {
+            // Fallback to per-request computation (original behavior)
+            const ts = Date.now();
+            const sig = createHmac("sha256", this.secret).update(`${method}:${path}:${ts}`).digest("hex");
+            return { signature: sig, timestamp: String(ts) };
+        }
+        if (this.currentTimestamp === null) {
+            // Shouldn't happen if properly initialized, but handle gracefully
+            return this._computeFreshSignature(method, path);
+        }
+        const key = `${method}:${path}`;
+        let entry = this.currentSignatures.get(key);
+        if (!entry) {
+            // Lazily compute and cache for this method:path at the current rotation timestamp
+            const signature = createHmac("sha256", this.secret)
+                .update(`${method}:${path}:${this.currentTimestamp}`)
+                .digest("hex");
+            entry = { signature, timestamp: this.currentTimestamp };
+            this.currentSignatures.set(key, entry);
+        }
+        return {
+            signature: entry.signature,
+            timestamp: String(entry.timestamp),
+        };
+    }
+    /**
+     * Check if caching is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get cache statistics for monitoring
+     */
+    getStats() {
+        return {
+            enabled: this.enabled,
+            rotationIntervalMs: this.rotationIntervalMs,
+            currentTimestamp: this.currentTimestamp,
+            previousTimestamp: this.previousTimestamp,
+        };
+    }
+    /**
+     * Stop the rotation timer (for cleanup)
+     */
+    stop() {
+        if (this.rotationTimer) {
+            clearInterval(this.rotationTimer);
+            this.rotationTimer = null;
+        }
+    }
+    /**
+     * Force an immediate rotation (useful for testing)
+     */
+    rotate() {
+        this._rotateSignature();
+    }
+    // ─── Private Methods ────────────────────────────────────────
+    _initializeCache() {
+        // Generate initial signature
+        this._rotateSignature();
+    }
+    _startRotation() {
+        // Set up periodic rotation
+        this.rotationTimer = setInterval(() => {
+            this._rotateSignature();
+        }, this.rotationIntervalMs);
+        // Don't keep process alive for rotation timer
+        this.rotationTimer.unref?.();
+    }
+    _rotateSignature() {
+        // Move current to previous
+        this.previousSignatures = this.currentSignatures;
+        this.previousTimestamp = this.currentTimestamp;
+        // Start new rotation with fresh map and timestamp
+        // Signatures are lazily computed per method:path on first access
+        const now = Date.now();
+        this.currentTimestamp = now;
+        this.currentSignatures = new Map();
+    }
+    _computeFreshSignature(method, path) {
+        const ts = Date.now();
+        const sig = createHmac("sha256", this.secret).update(`${method}:${path}:${ts}`).digest("hex");
+        return { signature: sig, timestamp: String(ts) };
+    }
+}
+/**
+ * Create a signature cache instance from environment configuration
+ */
+export function createSignatureCacheFromEnv() {
+    const secret = process.env.FORGE_INTERNAL_SECRET;
+    if (!secret) {
+        return null;
+    }
+    const enableCache = process.env.FORGE_CACHE_SIGNATURES === "true";
+    const rotationMs = process.env.FORGE_SIGNATURE_ROTATION_MS
+        ? parseInt(process.env.FORGE_SIGNATURE_ROTATION_MS, 10)
+        : 5000;
+    return new SignatureCache(secret, {
+        enabled: enableCache,
+        rotationIntervalMs: rotationMs,
+    });
+}
+//# sourceMappingURL=SignatureCache.js.map

package/dist/core/SignatureCache.js.map

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

package/dist/core/StaticFileServer.d.ts

@@ -0,0 +1,34 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ResolvedStaticMount } from "../frontend/StaticMountRegistry.js";
+import type { StaticMountRegistry } from "../frontend/StaticMountRegistry.js";
+export interface StaticMount extends ResolvedStaticMount {
+    spaExclude?: string[];
+}
+interface LoggerLike {
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface MetricsLike {
+    httpRequestEnd: (durationSeconds: number, labels: Record<string, string | number>) => void;
+}
+interface StaticFileServerOptions {
+    staticRegistry: StaticMountRegistry;
+    logger: LoggerLike;
+    metrics: MetricsLike;
+}
+export declare class StaticFileServer {
+    private readonly _staticRegistry;
+    private readonly _logger;
+    private readonly _metrics;
+    constructor(options: StaticFileServerOptions);
+    resolveMountForRequest(req: IncomingMessage, pathname: string): ResolvedStaticMount | null;
+    tryServeStatic(req: IncomingMessage, res: ServerResponse, start: number): Promise<boolean>;
+    private _proxyStaticToDevServer;
+    private _resolveStaticFile;
+    private _resolveExistingStaticFile;
+    private _isWithinRoot;
+    private _parseRange;
+    private _staticCacheControl;
+}
+export {};
+//# sourceMappingURL=StaticFileServer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StaticFileServer.d.ts","sourceRoot":"","sources":["../../src/core/StaticFileServer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAIjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAiB9E,MAAM,WAAW,WAAY,SAAQ,mBAAmB;IACtD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAChE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAClE;AAED,UAAU,WAAW;IACnB,cAAc,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;CAC5F;AAED,UAAU,uBAAuB;IAC/B,cAAc,EAAE,mBAAmB,CAAC;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AA0ED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,OAAO,EAAE,uBAAuB;IAM5C,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAMpF,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAiPlF,uBAAuB;IAuFrC,OAAO,CAAC,kBAAkB;YAmBZ,0BAA0B;YAmB1B,aAAa;IAU3B,OAAO,CAAC,WAAW;IAyBnB,OAAO,CAAC,mBAAmB;CAoB5B"}