@develler/remediation-agent 1.0.2

package/dist/index.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Develler — Node.js/Express Agent
+ *
+ * Public API. Import and call createRemediationMiddleware() in your Express app:
+ *
+ *   import { createRemediationMiddleware } from 'develler-remediation-agent';
+ *
+ *   const remediation = await createRemediationMiddleware();
+ *   app.use(remediation.handler());
+ *
+ *   // Optional: mount the webhook receiver so the SaaS can push instructions.
+ *   app.use(remediation.webhookRouter());
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AstExtractorService = exports.MaskingEngine = exports.ReplayError = exports.SignatureError = exports.InstructionCollection = exports.RuntimeInstruction = exports.MaskRule = void 0;
+exports.createRemediationMiddleware = createRemediationMiddleware;
+const ioredis_1 = __importDefault(require("ioredis"));
+const express_1 = require("express");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const CircuitBreakerService_js_1 = require("./services/CircuitBreakerService.js");
+const InstructionCacheService_js_1 = require("./services/InstructionCacheService.js");
+const MaskingEngine_js_1 = require("./services/MaskingEngine.js");
+const AgentConnectionService_js_1 = require("./services/AgentConnectionService.js");
+const remediationInterceptor_js_1 = require("./middleware/remediationInterceptor.js");
+const webhookController_js_1 = require("./controllers/webhookController.js");
+var instructions_js_1 = require("./types/instructions.js");
+Object.defineProperty(exports, "MaskRule", { enumerable: true, get: function () { return instructions_js_1.MaskRule; } });
+Object.defineProperty(exports, "RuntimeInstruction", { enumerable: true, get: function () { return instructions_js_1.RuntimeInstruction; } });
+Object.defineProperty(exports, "InstructionCollection", { enumerable: true, get: function () { return instructions_js_1.InstructionCollection; } });
+var SignatureError_js_1 = require("./exceptions/SignatureError.js");
+Object.defineProperty(exports, "SignatureError", { enumerable: true, get: function () { return SignatureError_js_1.SignatureError; } });
+var ReplayError_js_1 = require("./exceptions/ReplayError.js");
+Object.defineProperty(exports, "ReplayError", { enumerable: true, get: function () { return ReplayError_js_1.ReplayError; } });
+var MaskingEngine_js_2 = require("./services/MaskingEngine.js");
+Object.defineProperty(exports, "MaskingEngine", { enumerable: true, get: function () { return MaskingEngine_js_2.MaskingEngine; } });
+var AstExtractorService_js_1 = require("./services/AstExtractorService.js");
+Object.defineProperty(exports, "AstExtractorService", { enumerable: true, get: function () { return AstExtractorService_js_1.AstExtractorService; } });
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+async function createRemediationMiddleware(cfg = {}) {
+    const enabled = cfg.enabled ?? (process.env['REMEDIATION_INTERCEPTOR_ENABLED'] !== 'false');
+    const cbTtl = cfg.cbTtlSeconds ?? parseInt(process.env['REMEDIATION_CB_TTL'] ?? '60', 10);
+    const webhookPath = cfg.webhookPath ?? (process.env['REMEDIATION_WEBHOOK_PATH'] ?? '/api/remediation/v1/webhook');
+    const webhookOn = cfg.webhookEnabled ?? (process.env['REMEDIATION_WEBHOOK_ENABLED'] !== 'false');
+    const redisUrl = cfg.redisUrl ?? (process.env['REDIS_URL'] ?? process.env['REMEDIATION_REDIS_URL'] ?? 'redis://127.0.0.1:6379');
+    const connection = cfg.connection ?? loadConnectionConfig();
+    const redis = new ioredis_1.default(redisUrl, { lazyConnect: false, enableOfflineQueue: false });
+    const cache = new InstructionCacheService_js_1.InstructionCacheService(redis, connection.client_id);
+    const breaker = new CircuitBreakerService_js_1.CircuitBreakerService(redis, connection.client_id, cbTtl);
+    const masker = new MaskingEngine_js_1.MaskingEngine();
+    const agentConn = new AgentConnectionService_js_1.AgentConnectionService(redis, cache, connection);
+    const interceptor = new remediationInterceptor_js_1.RemediationInterceptor(agentConn, masker, breaker, enabled);
+    return {
+        handler() {
+            return interceptor.handler();
+        },
+        webhookRouter() {
+            const router = (0, express_1.Router)();
+            router.use(require('express').json());
+            (0, webhookController_js_1.registerWebhookRoute)(router, agentConn, connection, webhookPath, webhookOn);
+            return router;
+        },
+        async resetCircuitBreaker() {
+            await interceptor.resetCircuitBreaker();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+function loadConnectionConfig() {
+    const configPath = (0, path_1.join)(process.cwd(), '.remediation-connection.json');
+    if ((0, fs_1.existsSync)(configPath)) {
+        return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    }
+    // Fallback to env vars (set these in your CI/CD secrets instead of a file).
+    const clientId = process.env['REMEDIATION_CLIENT_ID'] ?? '';
+    const token = process.env['REMEDIATION_TOKEN'] ?? '';
+    const saasUrl = (process.env['REMEDIATION_SAAS_URL'] ?? '').replace(/\/+$/, '');
+    if (!clientId || !token || !saasUrl) {
+        throw new Error('Remediation Engine: no connection config found. ' +
+            'Run `npx remediation-connect` or set REMEDIATION_CLIENT_ID, REMEDIATION_TOKEN, REMEDIATION_SAAS_URL.');
+    }
+    return {
+        client_id: clientId,
+        token,
+        saas_url: saasUrl,
+        channel_type: 'polling',
+        poll_url: '/api/remediation/v1/instructions/pending',
+        poll_interval_seconds: 30,
+        connected_at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Dedicated logger for the Remediation Engine agent.
+ * Writes to a separate file so agent logs never mix into the host app's log stream.
+ * No PII-adjacent data is ever logged — only instruction IDs and error messages.
+ */
+export declare const logger: import("winston").Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,MAAM,0BAkBjB,CAAC"}

package/dist/logger.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const winston_1 = require("winston");
+const path_1 = require("path");
+/**
+ * Dedicated logger for the Remediation Engine agent.
+ * Writes to a separate file so agent logs never mix into the host app's log stream.
+ * No PII-adjacent data is ever logged — only instruction IDs and error messages.
+ */
+exports.logger = (0, winston_1.createLogger)({
+    level: process.env['REMEDIATION_LOG_LEVEL'] ?? 'error',
+    format: winston_1.format.combine(winston_1.format.timestamp(), winston_1.format.errors({ stack: true }), winston_1.format.json()),
+    defaultMeta: { service: 'remediation-agent' },
+    transports: [
+        new winston_1.transports.File({
+            filename: (0, path_1.join)(process.cwd(), 'logs', 'remediation.log'),
+            maxsize: 10 * 1024 * 1024, // 10 MB
+            maxFiles: 5,
+            tailable: true,
+        }),
+    ],
+    // Silent by default in test environments.
+    silent: process.env['NODE_ENV'] === 'test',
+});
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";;;AAAA,qCAA2D;AAC3D,+BAA4B;AAE5B;;;;GAIG;AACU,QAAA,MAAM,GAAG,IAAA,sBAAY,EAAC;IACjC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,OAAO;IACtD,MAAM,EAAE,gBAAM,CAAC,OAAO,CACpB,gBAAM,CAAC,SAAS,EAAE,EAClB,gBAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAC9B,gBAAM,CAAC,IAAI,EAAE,CACd;IACD,WAAW,EAAE,EAAE,OAAO,EAAE,mBAAmB,EAAE;IAC7C,UAAU,EAAE;QACV,IAAI,oBAAU,CAAC,IAAI,CAAC;YAClB,QAAQ,EAAE,IAAA,WAAI,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,iBAAiB,CAAC;YACxD,OAAO,EAAG,EAAE,GAAG,IAAI,GAAG,IAAI,EAAG,QAAQ;YACrC,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,IAAI;SACf,CAAC;KACH;IACD,0CAA0C;IAC1C,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,MAAM;CAC3C,CAAC,CAAC"}

package/dist/middleware/remediationInterceptor.d.ts

@@ -0,0 +1,42 @@
+import type { Request, RequestHandler, Response } from 'express';
+import type { AgentConnectionInterface } from '../contracts/agentConnection.js';
+import type { LifecycleInterceptorInterface } from '../contracts/lifecycleInterceptor.js';
+import type { MaskRule } from '../types/instructions.js';
+import { CircuitBreakerService } from '../services/CircuitBreakerService.js';
+import { MaskingEngine } from '../services/MaskingEngine.js';
+/**
+ * Production-grade in-memory interceptor for Express (Mode B).
+ *
+ * Handle flow (mirrors the PHP RemediationInterceptor exactly):
+ *  1. Circuit breaker open?  → call next() immediately, zero overhead.
+ *  2. Load active instructions from Redis.
+ *  3. Route-block match?  → respond with 503/custom, do not call next().
+ *  4. Override res.json() BEFORE calling next() so the route handler's
+ *     response is captured before it reaches the socket.
+ *  5. Inside the override: inject headers, deep-clone, mask PII, swap.
+ *  6. Call next().
+ *
+ * On ANY exception in steps 2–5: trip circuit breaker, log silently,
+ * call next() with the original res.json untouched. Never a partial mask.
+ *
+ * Node.js-specific challenge solved here:
+ *   Express does not buffer outbound response bodies. We intercept res.json()
+ *   and res.send() before next() is called, so that when the downstream
+ *   handler calls res.json(data), our closure runs first.
+ */
+export declare class RemediationInterceptor implements LifecycleInterceptorInterface {
+    private readonly connection;
+    private readonly masker;
+    private readonly breaker;
+    private readonly enabled;
+    constructor(connection: AgentConnectionInterface, masker: MaskingEngine, breaker: CircuitBreakerService, enabled: boolean);
+    /** Returns an Express RequestHandler — the function registered via app.use(). */
+    handler(): RequestHandler;
+    interceptRequest(req: Request, res: Response): Promise<boolean>;
+    interceptRequest(req: Request, res: Response, block: unknown): Promise<boolean>;
+    applyMaskingRules(data: unknown, maskRules: MaskRule[]): unknown;
+    isCircuitBreakerOpen(): Promise<boolean>;
+    tripCircuitBreaker(reason: Error): Promise<void>;
+    resetCircuitBreaker(): Promise<void>;
+}
+//# sourceMappingURL=remediationInterceptor.d.ts.map

package/dist/middleware/remediationInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediationInterceptor.d.ts","sourceRoot":"","sources":["../../src/middleware/remediationInterceptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,sBAAuB,YAAW,6BAA6B;IAExE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAHP,UAAU,EAAE,wBAAwB,EACpC,MAAM,EAAM,aAAa,EACzB,OAAO,EAAK,qBAAqB,EACjC,OAAO,EAAK,OAAO;IAGtC,iFAAiF;IACjF,OAAO,IAAI,cAAc;IAiFnB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAC/D,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BrF,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO;IAI1D,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC,kBAAkB,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;CAG3C"}

package/dist/middleware/remediationInterceptor.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemediationInterceptor = void 0;
+/**
+ * Production-grade in-memory interceptor for Express (Mode B).
+ *
+ * Handle flow (mirrors the PHP RemediationInterceptor exactly):
+ *  1. Circuit breaker open?  → call next() immediately, zero overhead.
+ *  2. Load active instructions from Redis.
+ *  3. Route-block match?  → respond with 503/custom, do not call next().
+ *  4. Override res.json() BEFORE calling next() so the route handler's
+ *     response is captured before it reaches the socket.
+ *  5. Inside the override: inject headers, deep-clone, mask PII, swap.
+ *  6. Call next().
+ *
+ * On ANY exception in steps 2–5: trip circuit breaker, log silently,
+ * call next() with the original res.json untouched. Never a partial mask.
+ *
+ * Node.js-specific challenge solved here:
+ *   Express does not buffer outbound response bodies. We intercept res.json()
+ *   and res.send() before next() is called, so that when the downstream
+ *   handler calls res.json(data), our closure runs first.
+ */
+class RemediationInterceptor {
+    connection;
+    masker;
+    breaker;
+    enabled;
+    constructor(connection, masker, breaker, enabled) {
+        this.connection = connection;
+        this.masker = masker;
+        this.breaker = breaker;
+        this.enabled = enabled;
+    }
+    /** Returns an Express RequestHandler — the function registered via app.use(). */
+    handler() {
+        return async (req, res, next) => {
+            if (!this.enabled) {
+                next();
+                return;
+            }
+            // Step 1 — circuit breaker gate.
+            if (await this.isCircuitBreakerOpen()) {
+                next();
+                return;
+            }
+            // Step 2 — load instructions from Redis.
+            let instructions;
+            try {
+                instructions = await this.connection.getActiveInstructions();
+            }
+            catch (err) {
+                await this.tripCircuitBreaker(err instanceof Error ? err : new Error(String(err)));
+                next();
+                return;
+            }
+            if (instructions.isEmpty()) {
+                next();
+                return;
+            }
+            // Step 3 — route-block check (before running the application handler).
+            let blocked = false;
+            try {
+                blocked = !(await this.interceptRequest(req, res, instructions.matchingRouteBlock(req) !== null
+                    ? instructions.matchingRouteBlock(req)
+                    : null));
+            }
+            catch (err) {
+                await this.tripCircuitBreaker(err instanceof Error ? err : new Error(String(err)));
+                next();
+                return;
+            }
+            if (blocked)
+                return; // Response already sent by interceptRequest.
+            // Step 4 — intercept res.json() before calling next().
+            // We override the method here so that when the downstream route handler
+            // calls res.json(body), our version executes instead.
+            const originalJson = res.json.bind(res);
+            const maskRules = instructions.maskRules();
+            const headers = instructions.injectHeaders();
+            const hasMasks = instructions.hasMaskRules();
+            res.json = (body) => {
+                try {
+                    // Step 5a — inject headers.
+                    for (const [name, value] of Object.entries(headers)) {
+                        res.setHeader(name, value);
+                    }
+                    // Step 5b — deep-clone, mask, swap.
+                    if (hasMasks && body !== undefined) {
+                        const masked = this.applyMaskingRules(body, maskRules);
+                        return originalJson(masked);
+                    }
+                }
+                catch (err) {
+                    // Trip breaker async; do not await here (we are inside a sync method).
+                    void this.tripCircuitBreaker(err instanceof Error ? err : new Error(String(err)));
+                    // Return original body — never a partial mask.
+                    return originalJson(body);
+                }
+                return originalJson(body);
+            };
+            // Step 6 — run the application handler.
+            next();
+        };
+    }
+    async interceptRequest(req, res, block) {
+        // When called from the handler with a pre-resolved block:
+        if (block !== undefined) {
+            const routeBlock = block;
+            if (routeBlock !== null) {
+                res.status(routeBlock.responseStatus).json(routeBlock.responseBody);
+                return false; // blocked
+            }
+            return true; // pass through
+        }
+        // When called directly (interface compliance):
+        try {
+            const instructions = await this.connection.getActiveInstructions();
+            const matched = instructions.matchingRouteBlock(req);
+            if (matched !== null) {
+                res.status(matched.responseStatus).json(matched.responseBody);
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return true; // fail-safe pass-through
+        }
+    }
+    applyMaskingRules(data, maskRules) {
+        return this.masker.apply(data, maskRules);
+    }
+    async isCircuitBreakerOpen() {
+        return this.breaker.isOpen();
+    }
+    async tripCircuitBreaker(reason) {
+        await this.breaker.trip(reason);
+    }
+    async resetCircuitBreaker() {
+        await this.breaker.reset();
+    }
+}
+exports.RemediationInterceptor = RemediationInterceptor;
+//# sourceMappingURL=remediationInterceptor.js.map

package/dist/middleware/remediationInterceptor.js.map

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

package/dist/services/AgentConnectionService.d.ts

@@ -0,0 +1,37 @@
+import type { Redis } from 'ioredis';
+import type { AgentConnectionInterface } from '../contracts/agentConnection.js';
+import type { ConnectionConfig, WireEnvelope } from '../types/wireProtocol.js';
+import { InstructionCollection, RuntimeInstruction } from '../types/instructions.js';
+import { InstructionCacheService } from './InstructionCacheService.js';
+/**
+ * Implements AgentConnectionInterface for Node.js.
+ * Exact behavioural equivalent of the PHP AgentConnectionService.
+ *
+ * Key differences vs PHP:
+ *  - All methods are async (ioredis returns Promises).
+ *  - HMAC: crypto.createHmac + crypto.timingSafeEqual (replaces hash_hmac + hash_equals).
+ *  - Nonce dedup: ioredis SET NX EX (same semantics as PHP Redis::set NX).
+ *  - base64url: Buffer.toString('base64url') — available in Node ≥ 16.
+ */
+export declare class AgentConnectionService implements AgentConnectionInterface {
+    private readonly redis;
+    private readonly cache;
+    private readonly config;
+    constructor(redis: Redis, cache: InstructionCacheService, config: ConnectionConfig);
+    verifyEnvelope(raw: unknown): Promise<WireEnvelope>;
+    cacheInstruction(instruction: RuntimeInstruction): Promise<void>;
+    getActiveInstructions(): Promise<InstructionCollection>;
+    acknowledgeInstruction(instructionId: string): Promise<void>;
+    pollPendingInstructions(): Promise<InstructionCollection>;
+    private assertProtocolVersion;
+    private assertIssuedAtWindow;
+    private assertClientId;
+    private assertNonceUnique;
+    /**
+     * Recompute HMAC-SHA256 over the canonical string and timing-safe compare.
+     * Equivalent to PHP hash_hmac('sha256', ...) + hash_equals().
+     */
+    private assertHmac;
+    private authHeaders;
+}
+//# sourceMappingURL=AgentConnectionService.d.ts.map

package/dist/services/AgentConnectionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentConnectionService.d.ts","sourceRoot":"","sources":["../../src/services/AgentConnectionService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAiC,MAAM,0BAA0B,CAAC;AAC9G,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AASvE;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,YAAW,wBAAwB;IAEnE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,uBAAuB,EAC9B,MAAM,EAAE,gBAAgB;IAOrC,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAgBnD,gBAAgB,CAAC,WAAW,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,qBAAqB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAIvD,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5D,uBAAuB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAsC/D,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,cAAc;YAMR,iBAAiB;IAoB/B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAiClB,OAAO,CAAC,WAAW;CAMpB"}

package/dist/services/AgentConnectionService.js

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentConnectionService = void 0;
+const crypto_1 = require("crypto");
+const axios_1 = __importDefault(require("axios"));
+const instructions_js_1 = require("../types/instructions.js");
+const SignatureError_js_1 = require("../exceptions/SignatureError.js");
+const ReplayError_js_1 = require("../exceptions/ReplayError.js");
+const logger_js_1 = require("../logger.js");
+const PROTOCOL_MAJOR = 1;
+const NONCE_TTL = 300;
+const ISSUED_AT_TOLERANCE = 300;
+/**
+ * Implements AgentConnectionInterface for Node.js.
+ * Exact behavioural equivalent of the PHP AgentConnectionService.
+ *
+ * Key differences vs PHP:
+ *  - All methods are async (ioredis returns Promises).
+ *  - HMAC: crypto.createHmac + crypto.timingSafeEqual (replaces hash_hmac + hash_equals).
+ *  - Nonce dedup: ioredis SET NX EX (same semantics as PHP Redis::set NX).
+ *  - base64url: Buffer.toString('base64url') — available in Node ≥ 16.
+ */
+class AgentConnectionService {
+    redis;
+    cache;
+    config;
+    constructor(redis, cache, config) {
+        this.redis = redis;
+        this.cache = cache;
+        this.config = config;
+    }
+    // ---------------------------------------------------------------------------
+    // AgentConnectionInterface
+    // ---------------------------------------------------------------------------
+    async verifyEnvelope(raw) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new SignatureError_js_1.SignatureError('Envelope must be a non-null object.');
+        }
+        const envelope = raw;
+        this.assertProtocolVersion(envelope);
+        this.assertIssuedAtWindow(envelope);
+        this.assertClientId(envelope);
+        await this.assertNonceUnique(envelope);
+        this.assertHmac(envelope);
+        return raw;
+    }
+    async cacheInstruction(instruction) {
+        await this.cache.store(instruction);
+    }
+    async getActiveInstructions() {
+        return this.cache.getActive();
+    }
+    async acknowledgeInstruction(instructionId) {
+        try {
+            await axios_1.default.post(`${this.config.saas_url}/api/remediation/v1/instructions/${instructionId}/acknowledge`, {}, { headers: this.authHeaders(), timeout: 5000 });
+        }
+        catch (err) {
+            logger_js_1.logger.warn('RemediationEngine: acknowledge failed.', {
+                instructionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    async pollPendingInstructions() {
+        try {
+            const response = await axios_1.default.get(`${this.config.saas_url}${this.config.poll_url}`, { headers: this.authHeaders(), timeout: 10000 });
+            const instructions = [];
+            for (const raw of response.data.instructions ?? []) {
+                try {
+                    const envelope = await this.verifyEnvelope(raw);
+                    const instruction = instructions_js_1.RuntimeInstruction.fromWirePayload(envelope.payload);
+                    await this.cacheInstruction(instruction);
+                    await this.acknowledgeInstruction(instruction.instructionId);
+                    instructions.push(instruction);
+                }
+                catch (err) {
+                    logger_js_1.logger.error('RemediationEngine: poll envelope verification failed.', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            return new instructions_js_1.InstructionCollection(instructions);
+        }
+        catch (err) {
+            logger_js_1.logger.error('RemediationEngine: poll request failed.', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return instructions_js_1.InstructionCollection.empty();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Verification helpers
+    // ---------------------------------------------------------------------------
+    assertProtocolVersion(envelope) {
+        const version = String(envelope['protocol_version'] ?? '');
+        const major = parseInt(version.split('.')[0] ?? '0', 10);
+        if (major !== PROTOCOL_MAJOR) {
+            throw new SignatureError_js_1.SignatureError(`Unsupported protocol major version: ${version}`);
+        }
+    }
+    assertIssuedAtWindow(envelope) {
+        const issuedAt = Number(envelope['issued_at'] ?? 0);
+        const delta = Math.abs(Math.floor(Date.now() / 1000) - issuedAt);
+        if (delta > ISSUED_AT_TOLERANCE) {
+            throw new SignatureError_js_1.SignatureError(`Envelope issued_at out of tolerance window (${delta}s).`);
+        }
+    }
+    assertClientId(envelope) {
+        if (envelope['client_id'] !== this.config.client_id) {
+            throw new SignatureError_js_1.SignatureError('client_id mismatch.');
+        }
+    }
+    async assertNonceUnique(envelope) {
+        const nonce = String(envelope['nonce'] ?? '');
+        const clientId = String(envelope['client_id'] ?? '');
+        const nonceKey = `remediation:nonce:${clientId}:${nonce}`;
+        try {
+            // SET NX EX — atomic, identical semantics to PHP Redis::set NX
+            const result = await this.redis.set(nonceKey, '1', 'EX', NONCE_TTL, 'NX');
+            if (result === null) {
+                throw new ReplayError_js_1.ReplayError(`Replayed nonce detected: ${nonce}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof ReplayError_js_1.ReplayError)
+                throw err;
+            // Redis unavailable — skip dedup (circuit breaker handles safety).
+            logger_js_1.logger.warn('RemediationEngine: nonce Redis unavailable, skipping dedup.', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Recompute HMAC-SHA256 over the canonical string and timing-safe compare.
+     * Equivalent to PHP hash_hmac('sha256', ...) + hash_equals().
+     */
+    assertHmac(envelope) {
+        const payload = (envelope['payload'] ?? {});
+        const canonical = [
+            String(envelope['protocol_version'] ?? ''),
+            String(envelope['message_id'] ?? ''),
+            String(envelope['message_type'] ?? ''),
+            String(envelope['client_id'] ?? ''),
+            String(envelope['issued_at'] ?? ''),
+            String(envelope['nonce'] ?? ''),
+            Buffer.from(JSON.stringify(sortKeysDeep(payload))).toString('base64url'),
+        ].join('.');
+        const expected = (0, crypto_1.createHmac)('sha256', this.config.token)
+            .update(canonical)
+            .digest('hex');
+        const received = String(envelope['hmac_sha256'] ?? '').toLowerCase();
+        if (expected.length !== received.length) {
+            throw new SignatureError_js_1.SignatureError('HMAC verification failed.');
+        }
+        // crypto.timingSafeEqual requires same-length Buffers.
+        const expectedBuf = Buffer.from(expected);
+        const receivedBuf = Buffer.from(received);
+        if (!(0, crypto_1.timingSafeEqual)(expectedBuf, receivedBuf)) {
+            throw new SignatureError_js_1.SignatureError('HMAC verification failed.');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    authHeaders() {
+        return {
+            'X-Remediation-Client-Id': this.config.client_id,
+            'X-Remediation-Token': this.config.token,
+        };
+    }
+}
+exports.AgentConnectionService = AgentConnectionService;
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function sortKeysDeep(obj) {
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj))
+        return obj;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = sortKeysDeep(obj[key]);
+    }
+    return sorted;
+}
+//# sourceMappingURL=AgentConnectionService.js.map

package/dist/services/AgentConnectionService.js.map

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

package/dist/services/AstExtractorService.d.ts

@@ -0,0 +1,18 @@
+import type { ExtractionResult, ExtractionTarget } from '../types/extraction.js';
+/**
+ * AST-based extractor for TypeScript/JavaScript source files.
+ *
+ * Uses the TypeScript compiler API (the same `typescript` package that's
+ * already present in any TS project) to locate and extract symbol source.
+ * Falls back to a regex-based line scanner when the TS compiler is not
+ * available (plain JS projects or environments without `typescript`).
+ */
+export declare class AstExtractorService {
+    extract(absoluteFilePath: string, target: ExtractionTarget): ExtractionResult | null;
+    private extractWithTs;
+    private findNode;
+    private nodePosition;
+    private extractDocBlock;
+    private extractWithLineScan;
+}
+//# sourceMappingURL=AstExtractorService.d.ts.map

package/dist/services/AstExtractorService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AstExtractorService.d.ts","sourceRoot":"","sources":["../../src/services/AstExtractorService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGjF;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,IAAI;IAoBpF,OAAO,CAAC,aAAa;IAkCrB,OAAO,CAAC,QAAQ;IAsChB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,mBAAmB;CAoC5B"}