deepdebug-local-agent 1.0.22 → 1.1.0

package/src/siblings/incident-forwarder.js

@@ -0,0 +1,320 @@
+/**
+ * Adapter consumer / incident forwarder (sibling module).
+ *
+ * The legacy log-source adapters (src/adapters/*) emit a frozen 6-key 'error'
+ * event { adapter, errorCode, file, message, source, timestamp } but nothing was
+ * listening, so ingested errors went nowhere. This module is the missing
+ * consumer: server.js attaches `adapter.on('error', e => incidentForwarder
+ * .handleAdapterEvent(e, name))` in the existing boot loop, and configures the
+ * forwarder (gateway url + credentials) from the app.listen callback.
+ *
+ * Robustness contract (never silently drop):
+ *   - malformed event        -> validated + rejected, counted (forward_failure
+ *                               reason=malformed) and logged; NOT forwarded.
+ *   - gateway unreachable     -> retried with backoff; on final failure counted
+ *                               (reason=gateway_unreachable) and logged at error
+ *                               with the event; NOT thrown (boot/runtime safe).
+ *   - backpressure            -> bounded in-memory queue with a concurrency cap.
+ *                               When full, the OLDEST event is evicted, counted
+ *                               (dropped) and logged with a warning. Events that
+ *                               arrive before the forwarder is configured are
+ *                               buffered, not lost.
+ *
+ * The class is exported for tests (fresh instances, injectable fetch/metrics);
+ * server.js uses the shared singleton `incidentForwarder`.
+ */
+import { logger as defaultLogger } from './logger.js';
+import { BurstSuppressor } from './burst-suppressor.js';
+
+const SIX_KEYS = ['adapter', 'errorCode', 'file', 'message', 'source', 'timestamp'];
+
+// Contract errors: the endpoint answered, but rejected us structurally. Retrying
+// cannot help (bad token, forbidden, wrong path) — it only burns budget and hides
+// a misconfiguration. Fail loudly instead. Everything else (network, timeout, 5xx)
+// is transport and stays on the retry/backoff path.
+const CONTRACT_STATUSES = new Set([401, 403, 404]);
+
+export class IncidentForwarder {
+    constructor(opts = {}) {
+        this.configured = false;
+        this.gatewayUrl = null;
+        this.apiKey = null;
+        this.tenantId = null;
+        this.incidentPath = opts.incidentPath
+            || process.env.DEEPDEBUG_ADAPTER_INCIDENT_PATH
+            || '/api/v1/internal/incident/create';
+        this.maxQueue = opts.maxQueue || 1000;
+        this.maxInflight = opts.maxInflight || 4;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.timeoutMs = opts.timeoutMs || 8000;
+        this.fetchImpl = opts.fetchImpl || globalThis.fetch;
+        this.logger = opts.logger || defaultLogger;
+        this.metrics = opts.metrics || null;
+
+        this.queue = [];
+        this.inflight = 0;
+        // Independent counters so tests/health can assert without the metrics module.
+        this.stats = { received: 0, forwarded: 0, failed: 0, dropped: 0, malformed: 0, contract: 0, suppressed: 0 };
+        // Queue-admission burst limiter (NOT dedup; see burst-suppressor.js).
+        this.suppressor = opts.suppressor || new BurstSuppressor({ ttlMs: opts.suppressTtlMs });
+        // Sticky contract-failure state, surfaced on /capabilities.
+        this.contractError = null;         // { status, body, at }
+        this.contractPreflightResult = null; // { ok, status, reason, at }
+    }
+
+    /**
+     * Enable forwarding. Buffered events (received before config) start draining.
+     */
+    configure({ gatewayUrl, apiKey, tenantId, metrics, incidentPath, fetchImpl } = {}) {
+        this.gatewayUrl = gatewayUrl || this.gatewayUrl;
+        this.apiKey = apiKey || this.apiKey;
+        this.tenantId = tenantId || this.tenantId;
+        if (metrics) this.metrics = metrics;
+        if (incidentPath) this.incidentPath = incidentPath;
+        if (fetchImpl) this.fetchImpl = fetchImpl;
+        this.configured = Boolean(this.gatewayUrl);
+        if (!this.configured) {
+            this.logger.warn('[incident-forwarder] no gateway url; events will buffer until configured');
+        } else {
+            this.logger.info({ url: this.gatewayUrl + this.incidentPath, queued: this.queue.length },
+                '[incident-forwarder] configured');
+        }
+        this._drain();
+        return this;
+    }
+
+    /**
+     * Adapter 'error' handler. Validates, enqueues, and kicks the drain loop.
+     * Returns the outcome string (useful for tests): received | malformed | dropped.
+     */
+    handleAdapterEvent(evt, adapterName) {
+        this.stats.received++;
+        this.metrics?.incReceived?.(adapterName || (evt && evt.adapter) || 'unknown');
+
+        const norm = this._validate(evt);
+        if (!norm) {
+            this.stats.malformed++;
+            this.stats.failed++;
+            this.metrics?.incFailure?.('malformed');
+            this.logger.warn({ adapter: adapterName, evt: this._safe(evt) },
+                '[incident-forwarder] malformed adapter event rejected (not forwarded)');
+            return 'malformed';
+        }
+
+        // Burst control at queue ADMISSION (before the bounded queue). Recurrence
+        // across the TTL window still passes — it is the signal the gateway needs.
+        if (this.suppressor && this.suppressor.shouldSuppress(norm)) {
+            this.stats.suppressed++;
+            this.metrics?.incSuppressed?.(adapterName || norm.adapter || 'unknown');
+            return 'suppressed';
+        }
+
+        let outcome = 'received';
+        if (this.queue.length >= this.maxQueue) {
+            // Backpressure: never silently drop — evict oldest, count, log.
+            const victim = this.queue.shift();
+            this.stats.dropped++;
+            this.metrics?.incDropped?.();
+            this.logger.warn(
+                { adapter: adapterName, queue: this.maxQueue, droppedFingerprint: victim && victim.fingerprint },
+                '[incident-forwarder] queue full, evicted oldest event');
+            outcome = 'dropped';
+        }
+        this.queue.push(norm);
+        this._drain();
+        return outcome;
+    }
+
+    /** Wait until the queue is empty and all in-flight sends have settled (tests). */
+    async flush() {
+        while (this.queue.length > 0 || this.inflight > 0) {
+            await new Promise((r) => setTimeout(r, 5));
+        }
+    }
+
+    _drain() {
+        if (!this.configured) return; // buffer until configured
+        while (this.inflight < this.maxInflight && this.queue.length > 0) {
+            const evt = this.queue.shift();
+            this.inflight++;
+            this._send(evt, 0).finally(() => {
+                this.inflight--;
+                this._drain();
+            });
+        }
+    }
+
+    _headers() {
+        return {
+            'Content-Type': 'application/json',
+            ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            ...(this.tenantId ? { 'X-Tenant-Id': this.tenantId } : {}),
+            'X-Internal-Request': 'true',
+        };
+    }
+
+    async _post(url, payload) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            return await this.fetchImpl(url, {
+                method: 'POST',
+                headers: this._headers(),
+                body: JSON.stringify(payload),
+                signal: ctrl.signal,
+            });
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    async _readBody(res) {
+        try {
+            const t = res && typeof res.text === 'function' ? await res.text() : '';
+            return (t || '').slice(0, 500);
+        } catch {
+            return '';
+        }
+    }
+
+    async _send(evt, attempt) {
+        const url = this.gatewayUrl.replace(/\/+$/, '') + this.incidentPath;
+        const body = this._toIncident(evt);
+        let res;
+        try {
+            res = await this._post(url, body);
+        } catch (err) {
+            // Transport (network / timeout / abort): retry.
+            return this._retryOrFail(evt, attempt, err.message, 'network');
+        }
+
+        if (res && res.ok) {
+            this.stats.forwarded++;
+            this.metrics?.incForwarded?.();
+            return true;
+        }
+
+        const status = res ? res.status : 0;
+        if (CONTRACT_STATUSES.has(status)) {
+            // CONTRACT error: do NOT retry. Fail loudly with the response body.
+            const respBody = await this._readBody(res);
+            this.stats.failed++;
+            this.stats.contract++;
+            this.contractError = { status, body: respBody, at: new Date().toISOString() };
+            this.metrics?.incFailure?.('contract', String(status));
+            this.logger.error(
+                { status, respBody, incident: body, url },
+                '[incident-forwarder] CONTRACT error from incident endpoint — not retrying (check AGENT_INTERNAL_TOKEN / path)');
+            return false;
+        }
+
+        // 5xx / 429 / other: transport-class, retry. (429 is rate limiting, not a
+        // contract error — it must keep backoff.)
+        return this._retryOrFail(evt, attempt, `gateway responded ${status}`, String(status));
+    }
+
+    async _retryOrFail(evt, attempt, reason, code) {
+        if (attempt < this.maxRetries) {
+            const backoff = Math.min(2000, 200 * 2 ** attempt);
+            await new Promise((r) => setTimeout(r, backoff));
+            return this._send(evt, attempt + 1);
+        }
+        this.stats.failed++;
+        this.metrics?.incFailure?.('transport', code || 'network');
+        this.logger.error({ reason, code, incident: this._toIncident(evt), attempts: attempt + 1 },
+            '[incident-forwarder] forward failed after retries (transport)');
+        return false;
+    }
+
+    /**
+     * One-shot boot probe of the incident endpoint. Sends a body WITHOUT tenantId
+     * so a correctly-authenticated call returns 400 ("tenantId required") and never
+     * creates an incident; 401/403 means the shared token is wrong, 404 the path.
+     * Records + logs the result. Never throws, never blocks startup.
+     */
+    async contractPreflight() {
+        if (!this.configured) {
+            this.contractPreflightResult = { ok: false, status: 0, reason: 'not_configured', at: new Date().toISOString() };
+            return this.contractPreflightResult;
+        }
+        const url = this.gatewayUrl.replace(/\/+$/, '') + this.incidentPath;
+        let result;
+        try {
+            const res = await this._post(url, { __preflight: true }); // no tenantId on purpose
+            const status = res ? res.status : 0;
+            if (status === 401 || status === 403) result = { ok: false, status, reason: 'auth_rejected' };
+            else if (status === 404) result = { ok: false, status, reason: 'path_not_found' };
+            else if (status === 400) result = { ok: true, status, reason: 'reachable_auth_ok' };
+            else if (status >= 200 && status < 300) result = { ok: true, status, reason: 'unexpected_2xx' };
+            else result = { ok: false, status, reason: 'transport_or_5xx' };
+        } catch (err) {
+            result = { ok: false, status: 0, reason: 'unreachable', error: err.message };
+        }
+        this.contractPreflightResult = { ...result, at: new Date().toISOString() };
+        const level = this.contractPreflightResult.ok ? 'info' : 'error';
+        this.logger[level]({ ...this.contractPreflightResult, url },
+            '[incident-forwarder] contract preflight');
+        return this.contractPreflightResult;
+    }
+
+    /** Live status for /capabilities surfacing. */
+    getStatus() {
+        return {
+            configured: this.configured,
+            stats: { ...this.stats },
+            queued: this.queue.length,
+            contract_error: this.contractError,
+            contract_preflight: this.contractPreflightResult,
+            contract_ok: !this.contractError
+                && (this.contractPreflightResult ? this.contractPreflightResult.ok : null),
+        };
+    }
+
+    /** Validate the frozen 6-key shape; return a normalized copy or null. */
+    _validate(evt) {
+        if (!evt || typeof evt !== 'object') return null;
+        for (const k of SIX_KEYS) {
+            if (!(k in evt)) return null;
+        }
+        if (typeof evt.message !== 'string' || evt.message.trim() === '') return null;
+        if (typeof evt.source !== 'string' || evt.source.trim() === '') return null;
+        return {
+            adapter: String(evt.adapter),
+            errorCode: evt.errorCode == null ? '' : String(evt.errorCode),
+            file: evt.file == null ? '' : String(evt.file),
+            message: String(evt.message),
+            source: String(evt.source),
+            timestamp: evt.timestamp,
+        };
+    }
+
+    /** Map the 6-key adapter event to the gateway incident-create payload. */
+    _toIncident(evt) {
+        return {
+            tenantId: this.tenantId || undefined,
+            service: evt.source,
+            message: evt.message,
+            severity: 'error',
+            environment: 'production',
+            detectedBy: 'local-agent-adapter',
+            logSource: 'legacy-adapter',
+            adapter: evt.adapter,
+            errorCode: evt.errorCode,
+            file: evt.file,
+            timestamp: evt.timestamp,
+        };
+    }
+
+    _safe(evt) {
+        try {
+            return JSON.parse(JSON.stringify(evt));
+        } catch {
+            return String(evt);
+        }
+    }
+}
+
+/** Shared singleton used by server.js wiring. */
+export const incidentForwarder = new IncidentForwarder();
+
+export default incidentForwarder;

package/src/siblings/logger.js

@@ -0,0 +1,15 @@
+/**
+ * Structured logger for the sibling modules (adapter consumer, capability
+ * preflight, metrics). server.js itself stays on console.* (frozen); the new
+ * sibling plane logs structured JSON via pino so operators get parseable output
+ * and honours the manifest-declared LOG_LEVEL (see docker-compose/helm), which
+ * the legacy console.* path never read.
+ */
+import pino from 'pino';
+
+export const logger = pino({
+    level: process.env.LOG_LEVEL || 'info',
+    base: { svc: 'local-agent' },
+});
+
+export default logger;

package/src/siblings/metrics.js

@@ -0,0 +1,94 @@
+/**
+ * Self-metrics (sibling module). Exposes GET /metrics on the MAIN app (port
+ * 5055) because Helm already scrapes 5055/metrics (helm/values.yaml). Uses a
+ * dedicated prom-client Registry so it never collides with anything else.
+ *
+ * Minimum series (per task):
+ *   agent_adapter_events_received_total{adapter}            counter
+ *   agent_adapter_events_forwarded_total                    counter
+ *   agent_adapter_events_forward_failures_total{reason,code} counter
+ *       reason is class-based: "contract" | "transport" | "malformed" so a
+ *       Prometheus rule can alert on each class differently; code carries the
+ *       HTTP status / "network" for detail.
+ *   agent_mode{mode}                                        gauge (1 = active)
+ * plus agent_adapter_events_dropped_total (backpressure), agent_adapter_events_
+ * suppressed_total{adapter} (burst suppression) and default runtime metrics.
+ */
+import client from 'prom-client';
+import { logger } from './logger.js';
+
+const MODES = ['FULL_LOCAL', 'SPLIT_PLANE', 'DETECT_ONLY'];
+
+export function startMetrics(app, { register } = {}) {
+    const registry = register || new client.Registry();
+    registry.setDefaultLabels({ service: 'local-agent' });
+    try {
+        client.collectDefaultMetrics({ register: registry });
+    } catch {
+        // default metrics already collected on this registry — ignore
+    }
+
+    const eventsReceived = new client.Counter({
+        name: 'agent_adapter_events_received_total',
+        help: 'Adapter error events received by the consumer',
+        labelNames: ['adapter'],
+        registers: [registry],
+    });
+    const eventsForwarded = new client.Counter({
+        name: 'agent_adapter_events_forwarded_total',
+        help: 'Adapter events successfully forwarded to the gateway',
+        registers: [registry],
+    });
+    const forwardFailures = new client.Counter({
+        name: 'agent_adapter_events_forward_failures_total',
+        help: 'Adapter events that failed to forward, by class (reason) + status (code)',
+        labelNames: ['reason', 'code'],
+        registers: [registry],
+    });
+    const eventsDropped = new client.Counter({
+        name: 'agent_adapter_events_dropped_total',
+        help: 'Adapter events evicted under backpressure',
+        registers: [registry],
+    });
+    const eventsSuppressed = new client.Counter({
+        name: 'agent_adapter_events_suppressed_total',
+        help: 'Adapter events suppressed by the local burst limiter (not forwarded)',
+        labelNames: ['adapter'],
+        registers: [registry],
+    });
+    const modeGauge = new client.Gauge({
+        name: 'agent_mode',
+        help: 'Derived operating mode (1 = active) — FULL_LOCAL|SPLIT_PLANE|DETECT_ONLY',
+        labelNames: ['mode'],
+        registers: [registry],
+    });
+    // Initialise every mode label to 0 so the series exist before the preflight runs.
+    for (const m of MODES) modeGauge.set({ mode: m }, 0);
+
+    if (app && typeof app.get === 'function') {
+        app.get('/metrics', async (_req, res) => {
+            try {
+                res.set('Content-Type', registry.contentType);
+                res.end(await registry.metrics());
+            } catch (err) {
+                res.status(500).end(`# metrics error: ${err.message}`);
+            }
+        });
+        logger.info('[metrics] serving GET /metrics on the main app (5055)');
+    }
+
+    return {
+        registry,
+        incReceived: (adapter) => eventsReceived.inc({ adapter: adapter || 'unknown' }),
+        incForwarded: () => eventsForwarded.inc(),
+        incFailure: (reason, code) => forwardFailures.inc({ reason: reason || 'unknown', code: code || 'none' }),
+        incDropped: () => eventsDropped.inc(),
+        incSuppressed: (adapter) => eventsSuppressed.inc({ adapter: adapter || 'unknown' }),
+        setMode: (mode) => {
+            for (const m of MODES) modeGauge.set({ mode: m }, m === mode ? 1 : 0);
+            if (!MODES.includes(mode)) modeGauge.set({ mode: mode || 'UNKNOWN' }, 1);
+        },
+    };
+}
+
+export default startMetrics;

package/src/utils/agent-auth.js

@@ -0,0 +1,184 @@
+/**
+ * agent-auth.js — authentication perimeter for the local agent's HTTP API.
+ *
+ * WHY. The agent exposes ~100 routes that read/write the workspace and run
+ * shell commands (/workspace/exec, /setup/run-command, /mcp/execute-command).
+ * It runs INSIDE customer environments, and before this module every one of
+ * those routes was unauthenticated on 0.0.0.0 — anyone on the customer LAN
+ * (or any web page, via the permissive CORS) had remote code execution.
+ *
+ * MODES (resolved once at boot from env):
+ *   token      LOCAL_AGENT_TOKEN is set: every non-public route needs
+ *              `X-Agent-Token: <secret>` (constant-time compare), from any
+ *              source. The Authorization header is NOT used, because on Cloud
+ *              Run it carries the Google ID token the gateway mints.
+ *   token      (also) AGENT_SHARED_SECRET is set and LOCAL_AGENT_TOKEN is not:
+ *              the gateway sets that secret on BYOC ACI agents and its
+ *              AgentSharedSecretFilter sends it as X-Agent-Token on every
+ *              call, so it is enforced (security review 2026-10-11: before,
+ *              it was only forwarded on in-process calls).
+ *   compat     Cloud Run only (K_SERVICE set) when no token is configured:
+ *              Cloud Run IAM (run.invoker) is the perimeter, the service must
+ *              NOT be allUsers-invokable. Also reachable by an explicit
+ *              LOCAL_AGENT_AUTH=compat anywhere (loud opt-out for callers that
+ *              still do not send X-Agent-Token). A foreign browser Origin is
+ *              refused in every mode but off.
+ *   loopback   Default outside Cloud Run when no token is configured
+ *              (docker-compose / installer publish 127.0.0.1 and the gateway
+ *              reaches the agent through the reverse WS tunnel, whose hop
+ *              calls are loopback): only loopback socket + loopback Host (DNS
+ *              rebinding) + no foreign Origin. Previously the default here was
+ *              compat, i.e. unauthenticated shell exec for anyone who could
+ *              reach the port (Helm ClusterIP, BYOC VMs). Also LOCAL_AGENT_AUTH=loopback.
+ *   off        LOCAL_AGENT_AUTH=off: explicit, loud opt-out.
+ *
+ * Public in every mode: GET /health and GET /metrics (probes / scrapes).
+ */
+import crypto from "node:crypto";
+
+export const AGENT_TOKEN_HEADER = "x-agent-token";
+
+const PUBLIC_PATHS = new Set(["/health", "/metrics"]);
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+/** Browser origins allowed to call the agent (dev tooling only). */
+export const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
+    "http://localhost:3010",
+    "http://localhost:3000",
+    "http://localhost:8085",
+    "http://127.0.0.1:3010",
+    "http://127.0.0.1:3000",
+    "http://127.0.0.1:8085",
+    "https://deepdebug.ai",
+    "https://app.deepdebug.ai",
+]);
+
+export function resolveAuthConfig(env = process.env) {
+    const requested = (env.LOCAL_AGENT_AUTH || "").toLowerCase();
+    if (requested === "off") return { mode: "off", token: null };
+    const enforced = (env.LOCAL_AGENT_TOKEN || "").trim();
+    if (enforced) return { mode: "token", token: enforced };
+    if (requested === "loopback") return { mode: "loopback", token: null };
+    const shared = (env.AGENT_SHARED_SECRET || "").trim();
+    const cloudRun = Boolean(env.K_SERVICE);
+    if (requested === "compat") return { mode: "compat", token: shared || null, cloudRun, explicit: true };
+    if (shared) return { mode: "token", token: shared, source: "AGENT_SHARED_SECRET" };
+    if (cloudRun) return { mode: "compat", token: null, cloudRun: true };
+    return { mode: "loopback", token: null, implicit: true };
+}
+
+export function allowedOrigins(env = process.env) {
+    const extra = (env.LOCAL_AGENT_CORS_ORIGINS || "")
+        .split(",").map(s => s.trim()).filter(Boolean);
+    return new Set([...DEFAULT_ALLOWED_ORIGINS, ...extra]);
+}
+
+export function isLoopbackAddress(addr) {
+    if (!addr || typeof addr !== "string") return false;
+    const a = addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+    return a === "::1" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(a);
+}
+
+export function isLoopbackHostHeader(host) {
+    if (!host || typeof host !== "string") return false;
+    let h = host.trim().toLowerCase();
+    if (h.startsWith("[")) {
+        const end = h.indexOf("]");
+        h = end > 0 ? h.slice(0, end + 1) : h;
+    } else {
+        h = h.split(":")[0];
+    }
+    return LOOPBACK_HOSTNAMES.has(h);
+}
+
+export function tokensEqual(a, b) {
+    if (typeof a !== "string" || typeof b !== "string") return false;
+    const ha = crypto.createHash("sha256").update(a).digest();
+    const hb = crypto.createHash("sha256").update(b).digest();
+    return crypto.timingSafeEqual(ha, hb) && a.length === b.length;
+}
+
+/**
+ * Pure decision function (unit-tested). Returns { ok, status?, reason? }.
+ * req-like: { method, path, headers, remoteAddress }
+ */
+export function authorize(reqLike, cfg, origins = allowedOrigins()) {
+    const method = (reqLike.method || "GET").toUpperCase();
+    const p = reqLike.path || "/";
+    if ((method === "GET" || method === "HEAD") && PUBLIC_PATHS.has(p)) return { ok: true };
+    if (method === "OPTIONS") return { ok: true }; // CORS preflight; CORS layer decides
+
+    const headers = reqLike.headers || {};
+    if (cfg.mode !== "off" && headers.origin && !origins.has(headers.origin)) {
+        // No browser page needs the agent directly; a foreign Origin is a
+        // cross-site request (CSRF / drive-by) — refuse before any side effect.
+        return { ok: false, status: 403, reason: "browser origin not allowed" };
+    }
+    switch (cfg.mode) {
+        case "off":
+        case "compat":
+            return { ok: true };
+        case "token": {
+            const presented = headers[AGENT_TOKEN_HEADER];
+            if (tokensEqual(typeof presented === "string" ? presented : "", cfg.token)) return { ok: true };
+            return { ok: false, status: 401, reason: "missing or invalid X-Agent-Token" };
+        }
+        case "loopback":
+        default: {
+            if (!isLoopbackAddress(reqLike.remoteAddress)) {
+                return { ok: false, status: 401, reason: "remote access requires AGENT_SHARED_SECRET/LOCAL_AGENT_TOKEN" };
+            }
+            if (!isLoopbackHostHeader(headers.host)) {
+                return { ok: false, status: 403, reason: "non-loopback Host header rejected" };
+            }
+            return { ok: true };
+        }
+    }
+}
+
+/** Express middleware. Mount BEFORE any route. */
+export function createAuthMiddleware(cfg = resolveAuthConfig(), origins = allowedOrigins()) {
+    return function agentAuth(req, res, next) {
+        const decision = authorize({
+            method: req.method,
+            path: req.path,
+            headers: req.headers,
+            remoteAddress: req.socket?.remoteAddress,
+        }, cfg, origins);
+        if (decision.ok) return next();
+        console.warn(`[agent-auth] ${decision.status} ${req.method} ${req.path} from ${req.socket?.remoteAddress}: ${decision.reason}`);
+        return res.status(decision.status).json({ ok: false, error: "unauthorized", reason: decision.reason });
+    };
+}
+
+/** Headers the agent's own in-process callers (WS tunnel) must send. */
+export function internalAuthHeaders(cfg = resolveAuthConfig()) {
+    return cfg.token ? { "X-Agent-Token": cfg.token } : {};
+}
+
+/** CORS origin callback: exact allowlist only, no wildcard hosting domains. */
+export function corsOriginCallback(origins = allowedOrigins()) {
+    return function (origin, callback) {
+        if (!origin) return callback(null, true); // server-to-server
+        if (origins.has(origin)) return callback(null, true);
+        console.warn(`CORS: blocked origin: ${origin}`);
+        return callback(null, false);
+    };
+}
+
+export function describeAuthMode(cfg) {
+    switch (cfg.mode) {
+        case "token": return cfg.source === "AGENT_SHARED_SECRET"
+            ? "token (X-Agent-Token required; enforcing AGENT_SHARED_SECRET)"
+            : "token (X-Agent-Token required)";
+        case "compat":
+            return "compat — token not enforced: remote callers are unauthenticated "
+                + (cfg.explicit ? "(LOCAL_AGENT_AUTH=compat opt-out; set LOCAL_AGENT_TOKEN instead)"
+                    : "(Cloud Run: relying on IAM — ensure the service is NOT allUsers-invokable)");
+        case "loopback": return cfg.implicit
+            ? "loopback-only (default: no LOCAL_AGENT_TOKEN/AGENT_SHARED_SECRET; remote callers refused)"
+            : "loopback-only (LOCAL_AGENT_AUTH=loopback)";
+        case "off": return "OFF — LOCAL_AGENT_AUTH=off, every route is unauthenticated";
+        default: return cfg.mode;
+    }
+}

package/src/utils/approval-token.js

@@ -0,0 +1,56 @@
+/**
+ * approval-token.js — PolicyGate human-approval tokens (REQUIRE_HUMAN flow).
+ *
+ * A command outside the allowlist runs only when a human approved THAT exact
+ * command in PolicyGate. The gateway mints (HumanApprovalTokens.java):
+ *
+ *   vhapr1.<keyId>.<base64url(payload JSON)>.<base64url(Ed25519 signature)>
+ *
+ * signed with the same platform key as request signatures, over
+ * "VH-HUMAN-APPROVAL-V1\n<keyId>\n<payload segment>". Payload:
+ *   { typ: "vh-human-approval", tid, wid, sha256, iat, exp, jti, by, decision }
+ * where sha256 = hex SHA-256 of the exact command string (or of JSON.stringify
+ * (argv) for /workspace/run). Lifetime is capped at 15 minutes and each jti is
+ * single-use (shared nonce cache).
+ */
+import crypto from "node:crypto";
+import { sha256Hex } from "./request-signing.js";
+
+export const APPROVAL_PREFIX = "vhapr1";
+export const APPROVAL_SIG_PREFIX = "VH-HUMAN-APPROVAL-V1";
+export const MAX_APPROVAL_LIFETIME_SECONDS = 15 * 60;
+
+const b64urlDecode = (s) => Buffer.from(String(s).replace(/-/g, "+").replace(/_/g, "/"), "base64");
+
+/**
+ * Returns { ok: true, approvedBy, decision } or { ok: false, reason }.
+ * opts: { subject, keys: Map, identity, requestTenantId, nonces, now }
+ */
+export function verifyApprovalToken(token, { subject, keys, identity = {}, requestTenantId, nonces, now = () => Date.now() } = {}) {
+    if (typeof token !== "string" || token.length > 4096) return { ok: false, reason: "malformed approval token" };
+    const parts = token.split(".");
+    if (parts.length !== 4 || parts[0] !== APPROVAL_PREFIX) return { ok: false, reason: "malformed approval token" };
+    const [, keyId, payloadSeg, sigSeg] = parts;
+    const key = keys && keys.get(keyId);
+    if (!key) return { ok: false, reason: `unknown approval key id '${keyId.slice(0, 64)}'` };
+    const data = Buffer.from(`${APPROVAL_SIG_PREFIX}\n${keyId}\n${payloadSeg}`, "utf-8");
+    let good = false;
+    try { good = crypto.verify(null, data, key, b64urlDecode(sigSeg)); } catch { good = false; }
+    if (!good) return { ok: false, reason: "bad approval signature" };
+    let p;
+    try { p = JSON.parse(b64urlDecode(payloadSeg).toString("utf-8")); } catch { return { ok: false, reason: "malformed approval payload" }; }
+    if (p.typ !== "vh-human-approval") return { ok: false, reason: "not a human-approval token" };
+    const t = Math.floor(now() / 1000);
+    if (!Number.isInteger(p.exp) || !Number.isInteger(p.iat)) return { ok: false, reason: "approval token without iat/exp" };
+    if (p.exp - p.iat > MAX_APPROVAL_LIFETIME_SECONDS) return { ok: false, reason: "approval token lifetime too long" };
+    if (t > p.exp) return { ok: false, reason: "approval token expired" };
+    if (p.iat > t + 60) return { ok: false, reason: "approval token issued in the future" };
+    if (typeof p.sha256 !== "string" || p.sha256 !== sha256Hex(Buffer.from(String(subject ?? ""), "utf-8")))
+        return { ok: false, reason: "approval token is for a different command" };
+    if (identity.tenantId && p.tid !== identity.tenantId) return { ok: false, reason: "approval token tenant mismatch" };
+    if (identity.workspaceId && p.wid && p.wid !== identity.workspaceId) return { ok: false, reason: "approval token workspace mismatch" };
+    if (requestTenantId && p.tid !== requestTenantId) return { ok: false, reason: "approval token tenant differs from the signed request" };
+    if (!p.jti || !/^[A-Za-z0-9_-]{8,128}$/.test(p.jti)) return { ok: false, reason: "approval token without jti" };
+    if (nonces && !nonces.checkAndRemember(`apr:${p.jti}`)) return { ok: false, reason: "approval token already used" };
+    return { ok: true, approvedBy: p.by || null, decision: p.decision || null };
+}