patchwork-os 0.2.0-beta.2 → 0.2.0-beta.4

package/dist/server.js

@@ -1,12 +1,15 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { WebSocket, WebSocketServer as WsServer } from "ws";
+import { getAnalyticsPrefsAll, getTelemetryPrefs, setTelemetryPrefs, } from "./analyticsPrefs.js";
 import { handleApprovalsStream, routeApprovalRequest } from "./approvalHttp.js";
 import { getApprovalQueue } from "./approvalQueue.js";
 import { saveBridgeConfigDriver } from "./config.js";
 import { tryHandleConnectorRoute, tryHandlePublicConnectorRoute, } from "./connectorRoutes.js";
 import { timingSafeStringEqual } from "./crypto.js";
 import { renderDashboardHtml } from "./dashboard.js";
+import { EnvLockedFlagError, getEnvLockedValue, isEnvLockedFor, isWriteKillSwitchActive, KILL_SWITCH_WRITES, setFlag, } from "./featureFlags.js";
 import { respond500 } from "./httpErrorResponse.js";
 import { tryHandleInboxRoute } from "./inboxRoutes.js";
 import { tryHandleMcpRoute } from "./mcpRoutes.js";
@@ -103,6 +106,10 @@ export class Server extends EventEmitter {
     runsFn = null;
     /** Patchwork: set by bridge to fetch a single run by seq for the detail page. */
     runDetailFn = null;
+    /** Patchwork (PR1c): aggregate halt-reason categories across recent runs. */
+    haltSummaryFn = null;
+    /** Patchwork (PR3b): aggregate judge-step verdicts across recent runs. */
+    judgeSummaryFn = null;
     /** Patchwork: set by bridge to generate a dry-run plan for a recipe by name. */
     runPlanFn = null;
     /** Patchwork (VD-4): mocked replay of an existing run. Returns the new
@@ -110,10 +117,25 @@ export class Server extends EventEmitter {
     runReplayFn = null;
     /** Patchwork: set by bridge to launch a named recipe via the orchestrator. */
     runRecipeFn = null;
+    /**
+     * Patchwork: set by bridge to re-prime the recipe scheduler when the
+     * on-disk recipe set changes (install / save / delete). Lets cron-
+     * triggered recipes start firing without a bridge restart. Optional —
+     * tests + headless tooling leave it null; the install handler treats
+     * the callback as best-effort fire-and-forget.
+     */
+    onRecipesChangedFn = null;
     /** Patchwork: admin-controlled managed settings path (highest rule precedence). */
     managedSettingsPath = undefined;
     /** Effective bridge config path to update when dashboard saves driver changes. */
     bridgeConfigPath = undefined;
+    /**
+     * Shared secret for HMAC-SHA256 verification of POST /hooks/* requests
+     * carrying `X-Hub-Signature-256`. When null (default), HMAC auth is
+     * disabled and /hooks/* requires the bridge bearer token like every
+     * other route. Set by Bridge constructor from `config.webhookSecret`.
+     */
+    webhookSecret = null;
     /** Patchwork: live approval gate level — mutated by POST /settings, read by bridge per-session setup. */
     approvalGate = "off";
     /** Patchwork: outbound webhook URL for approval notifications (from dashboard.webhookUrl in config). */
@@ -150,6 +172,33 @@ export class Server extends EventEmitter {
      * the user's preference.
      */
     enableTimeOfDayAnomaly = false;
+    /**
+     * Patchwork: set by bridge to record a kill-switch audit trace.
+     * `/kill-switch` POST emits one entry on every state transition (no-op
+     * toggles do not emit). When unset, the handler logs via this.logger
+     * instead — see step 5 of issue #422.
+     *
+     * Trace encoding (v2-I6 from #422): we encode kill-switch events via
+     * the existing `DecisionTrace` schema rather than extending its
+     * `traceType` union, to keep schema migration off the kill-switch
+     * critical path. Fields used:
+     *   ref       = "kill-switch.writes"
+     *   problem   = "<short reason>" or "engage" / "release" if no reason
+     *   solution  = "ENGAGED at <ts>" or "RELEASED at <ts>"
+     *   tags      = ["kill-switch", "engage" | "release", "actor:http"]
+     *
+     * `ctxQueryTraces({tag: "kill-switch"})` returns the full audit
+     * history; pair with `tag: "engage"` / `tag: "release"` to filter
+     * direction.
+     */
+    recordKillSwitchTraceFn = null;
+    /**
+     * Set by bridge to broadcast a `kind: "kill-switch"` SSE event from
+     * `/stream` when the kill-switch state changes (issue #422 v2, pitfall I8).
+     * Bridge wires this to `activityLog.broadcastKillSwitch()` or an equivalent
+     * that notifies all active SSE listeners so the dashboard updates in <1s.
+     */
+    broadcastKillSwitchEventFn = null;
     /** Patchwork: set by bridge to match + fire webhook-triggered recipes. */
     webhookFn = null;
     /**
@@ -215,6 +264,22 @@ export class Server extends EventEmitter {
     /** Set by bridge to handle POST /launch-quick-task — invokes launchQuickTask tool in-process. */
     launchQuickTaskFn = null;
     setRecipeEnabledFn = null;
+    /** Set by bridge to check if restart is safe (no in-flight tool calls). */
+    restartCheckFn = null;
+    /**
+     * Called when /restart decides it is safe to shut down. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Override in tests to a no-op so
+     * the Vitest runner process is not actually killed.
+     */
+    restartKillFn = () => process.kill(process.pid, "SIGTERM");
+    /**
+     * Called when /shutdown decides it is safe to exit. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Bridge overrides this to run its
+     * internal shutdown sequence directly — necessary on Windows where
+     * `process.kill(pid, 'SIGTERM')` is TerminateProcess and cleanup handlers
+     * never fire.
+     */
+    shutdownFn = () => process.kill(process.pid, "SIGTERM");
     /**
      * Attach an OAuth 2.0 Authorization Server.
      * When set, the bridge exposes:
@@ -418,6 +483,14 @@ export class Server extends EventEmitter {
             const isPhoneApprovalPath = req.method === "POST" &&
                 /^\/(approve|reject)\/[A-Za-z0-9-]+$/.test(parsedUrl.pathname) &&
                 !!req.headers["x-approval-token"];
+            // GitHub-style webhook bypass: when --webhook-secret is configured,
+            // POST /hooks/* requests carrying X-Hub-Signature-256 bypass the
+            // bearer-token gate. Signature itself is verified inside the
+            // /hooks/* handler after the body has been read.
+            const isHmacWebhookCandidate = req.method === "POST" &&
+                parsedUrl.pathname.startsWith("/hooks/") &&
+                !!req.headers["x-hub-signature-256"] &&
+                this.webhookSecret !== null;
             // Rate-limit the phone bypass surface. Only applies when this is
             // actually a phone-path request that's relying on the bypass — a
             // properly-authenticated bearer caller is unaffected. Counted +
@@ -464,7 +537,10 @@ export class Server extends EventEmitter {
                 }
             }
             // oauthResolved is the bridge token if the OAuth token is valid; null otherwise
-            if (!isStaticToken && !oauthResolved && !isPhoneApprovalPath) {
+            if (!isStaticToken &&
+                !oauthResolved &&
+                !isPhoneApprovalPath &&
+                !isHmacWebhookCandidate) {
                 // RFC 6750: only include error= when a token was actually presented but invalid
                 const tokenPresented = bearer.length > 0;
                 const wwwAuth = this.oauthServer && this.oauthIssuerUrl
@@ -776,6 +852,33 @@ export class Server extends EventEmitter {
                     respond413(res, HOOKS_BODY_CAP);
                     return;
                 }
+                // HMAC-SHA256 verification for GitHub-style webhooks. Signature is
+                // computed over the raw on-the-wire bytes (read.bytes), not the
+                // utf-8-decoded string — non-UTF-8 or denormalized payloads must
+                // round-trip identically to validate.
+                const sigHeader = req.headers["x-hub-signature-256"];
+                if (typeof sigHeader === "string" && sigHeader.length > 0) {
+                    if (!this.webhookSecret) {
+                        res.writeHead(401, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "webhook_secret_not_configured" }));
+                        return;
+                    }
+                    const expected = "sha256=" +
+                        createHmac("sha256", this.webhookSecret)
+                            .update(read.bytes)
+                            .digest("hex");
+                    const expectedBuf = Buffer.from(expected, "utf-8");
+                    const providedBuf = Buffer.from(sigHeader, "utf-8");
+                    // timingSafeEqual throws on length mismatch — length-check first
+                    // so the constant-time path is only taken on equal-length inputs.
+                    const sigOk = expectedBuf.length === providedBuf.length &&
+                        timingSafeEqual(expectedBuf, providedBuf);
+                    if (!sigOk) {
+                        res.writeHead(401, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_signature" }));
+                        return;
+                    }
+                }
                 let payload;
                 if (read.body.trim()) {
                     try {
@@ -789,7 +892,7 @@ export class Server extends EventEmitter {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Webhooks unavailable — start bridge with --claude-driver subprocess",
+                        error: "Webhooks unavailable — start bridge with --driver subprocess",
                     }));
                     return;
                 }
@@ -992,9 +1095,12 @@ export class Server extends EventEmitter {
                 setRecipeEnabledFn: this.setRecipeEnabledFn,
                 runsFn: this.runsFn,
                 runDetailFn: this.runDetailFn,
+                haltSummaryFn: this.haltSummaryFn,
+                judgeSummaryFn: this.judgeSummaryFn,
                 runPlanFn: this.runPlanFn,
                 runReplayFn: this.runReplayFn,
                 runRecipeFn: this.runRecipeFn,
+                onRecipesChangedFn: this.onRecipesChangedFn,
             })) {
                 return;
             }
@@ -1261,6 +1367,253 @@ export class Server extends EventEmitter {
                 }
                 return;
             }
+            // /kill-switch — dedicated endpoint for the global write-tier kill switch.
+            // See issue #422 v2: not folded into /settings because kill-switch has
+            // audit + idempotency + env-lock semantics nothing else on /settings has.
+            //
+            // POST {engage: boolean, reason?: string} → toggle; idempotent.
+            //   200 {engaged, changed, locked: false}     — accepted
+            //   200 {engaged, changed: false, locked: false} — no-op (already in that state)
+            //   409 {error: "env_locked", flag, frozenValue, lockedReason}
+            //                                               — env-locked, cannot toggle
+            //   400 {error: "invalid_request"}            — malformed body
+            //
+            // GET → status. 200 {engaged, locked, lockedReason?, lockedValue?}
+            //
+            // Audit emit: state transitions log to this.logger.info (always)
+            // AND record via this.recordKillSwitchTraceFn (when wired by the
+            // bridge — see src/bridge.ts where it threads decisionTraceLog
+            // through to ~/.patchwork/decision_traces.jsonl). Tests / headless
+            // contexts that don't wire the callback still get the log line.
+            if (parsedUrl.pathname === "/kill-switch") {
+                if (req.method === "GET") {
+                    const engaged = isWriteKillSwitchActive();
+                    const locked = isEnvLockedFor(KILL_SWITCH_WRITES);
+                    const body = { engaged, locked };
+                    if (locked) {
+                        const lockedValue = getEnvLockedValue(KILL_SWITCH_WRITES);
+                        body.lockedValue = lockedValue;
+                        body.lockedReason = `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${lockedValue ? "1" : "0"} at bridge startup`;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(body));
+                    return;
+                }
+                if (req.method === "POST") {
+                    // 1 KB — body is `{engage: bool, reason?: string}`; reason is a
+                    // short audit note, 1 KB is generous.
+                    const KS_BODY_CAP = 1 * 1024;
+                    const parsed = await readJsonBody(req, KS_BODY_CAP);
+                    if (!parsed.ok) {
+                        if (parsed.code === "too_large") {
+                            respond413(res, KS_BODY_CAP);
+                            return;
+                        }
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_request", reason: "bad_json" }));
+                        return;
+                    }
+                    const body = parsed.value ?? {};
+                    if (typeof body.engage !== "boolean") {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "invalid_request",
+                            reason: "engage must be boolean",
+                        }));
+                        return;
+                    }
+                    const reason = typeof body.reason === "string" && body.reason.trim().length > 0
+                        ? body.reason.trim().slice(0, 500)
+                        : undefined;
+                    // v2-B2 + I3: surface env-lock conflict as structured 409 so CLI
+                    // + dashboard can distinguish "you sent garbage" from
+                    // "policy-locked by sysadmin via PATCHWORK_FLAG_*".
+                    if (isEnvLockedFor(KILL_SWITCH_WRITES)) {
+                        const lockedValue = getEnvLockedValue(KILL_SWITCH_WRITES);
+                        res.writeHead(409, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "env_locked",
+                            flag: KILL_SWITCH_WRITES,
+                            frozenValue: lockedValue,
+                            lockedReason: `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${lockedValue ? "1" : "0"} at bridge startup`,
+                        }));
+                        return;
+                    }
+                    // v2-I12: idempotent. State transitions emit audit; no-ops don't.
+                    const prev = isWriteKillSwitchActive();
+                    const next = body.engage;
+                    const changed = prev !== next;
+                    if (changed) {
+                        try {
+                            setFlag(KILL_SWITCH_WRITES, next, true);
+                        }
+                        catch (err) {
+                            // Belt-and-suspenders: setFlag now throws EnvLockedFlagError if
+                            // the flag was env-locked (we already checked isEnvLockedFor above,
+                            // but a race with lockKillSwitchEnv() in tests warrants this).
+                            if (err instanceof EnvLockedFlagError) {
+                                res.writeHead(409, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({
+                                    error: "env_locked",
+                                    flag: KILL_SWITCH_WRITES,
+                                    frozenValue: err.frozenValue,
+                                    lockedReason: `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${err.frozenValue ? "1" : "0"} at bridge startup`,
+                                }));
+                                return;
+                            }
+                            throw err;
+                        }
+                        // v2-I6: audit emit on every state transition; no-ops skip.
+                        // The bridge wires recordKillSwitchTraceFn to write a
+                        // DecisionTrace entry to ~/.patchwork/decision_traces.jsonl
+                        // (see src/bridge.ts). The logger.info line stays as a
+                        // secondary signal in the bridge log and is the only output
+                        // when the trace fn is unset (tests, headless contexts).
+                        this.logger.info(`[kill-switch] ${next ? "ENGAGED" : "RELEASED"}${reason ? ` (reason: ${reason})` : ""} — actor=http`);
+                        this.recordKillSwitchTraceFn?.({
+                            engaged: next,
+                            reason,
+                            ts: Date.now(),
+                        });
+                        // v2-I8: broadcast SSE kind:"kill-switch" so dashboard updates
+                        // in <1s without changing the poll cadence.
+                        this.broadcastKillSwitchEventFn?.(next, reason);
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        engaged: next,
+                        changed,
+                        locked: false,
+                    }));
+                    return;
+                }
+            }
+            // /telemetry-prefs — read/write per-flag telemetry preferences.
+            // GET  → {crashReports, usageStats, localDiagnostics}
+            // POST {crashReports?, usageStats?, localDiagnostics?} → same shape (partial update)
+            if (parsedUrl.pathname === "/telemetry-prefs") {
+                if (req.method === "GET") {
+                    const prefs = getTelemetryPrefs();
+                    const all = getAnalyticsPrefsAll();
+                    const response = { ...prefs };
+                    if (all?.lastSentAt !== undefined) {
+                        response.lastSentAt = all.lastSentAt;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(response));
+                    return;
+                }
+                if (req.method === "POST") {
+                    const TP_BODY_CAP = 1 * 1024;
+                    const parsed = await readJsonBody(req, TP_BODY_CAP);
+                    if (!parsed.ok) {
+                        if (parsed.code === "too_large") {
+                            respond413(res, TP_BODY_CAP);
+                            return;
+                        }
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_request", reason: "bad_json" }));
+                        return;
+                    }
+                    const body = parsed.value ?? {};
+                    const update = {};
+                    if (typeof body.crashReports === "boolean") {
+                        update.crashReports = body.crashReports;
+                    }
+                    if (typeof body.usageStats === "boolean") {
+                        update.usageStats = body.usageStats;
+                    }
+                    if (typeof body.localDiagnostics === "boolean") {
+                        update.localDiagnostics = body.localDiagnostics;
+                    }
+                    setTelemetryPrefs(update);
+                    const prefs = getTelemetryPrefs();
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(prefs));
+                    return;
+                }
+            }
+            // /restart — graceful bridge restart endpoint.
+            // POST → triggers SIGTERM if no active work; returns 409 if busy.
+            // Safety checks: rejects restart if sessions have in-flight tool calls.
+            if (parsedUrl.pathname === "/restart" && req.method === "POST") {
+                if (!this.restartCheckFn) {
+                    res.writeHead(503, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: "restart_unavailable",
+                        reason: "Restart endpoint not configured",
+                    }));
+                    return;
+                }
+                const check = this.restartCheckFn();
+                // Reject restart if there's active work
+                if (check.inFlightCalls > 0) {
+                    this.logger.warn(`[/restart] Rejected — ${check.inFlightCalls} in-flight tool call${check.inFlightCalls === 1 ? "" : "s"} across ${check.busySessions.length} session${check.busySessions.length === 1 ? "" : "s"}`);
+                    res.writeHead(409, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: "restart_blocked",
+                        reason: `${check.inFlightCalls} tool call${check.inFlightCalls === 1 ? "" : "s"} in progress`,
+                        activeSessions: check.totalSessions,
+                        inFlightCalls: check.inFlightCalls,
+                        busySessions: check.busySessions,
+                    }));
+                    return;
+                }
+                // Safe to restart — log and trigger SIGTERM
+                this.logger.info(`[/restart] Initiating graceful restart — ${check.totalSessions} session${check.totalSessions === 1 ? "" : "s"}, 0 in-flight calls`);
+                res.writeHead(202, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: true,
+                    message: "Restart initiated. Bridge will shut down gracefully.",
+                    activeSessions: check.totalSessions,
+                }));
+                // Trigger shutdown after response is sent (100ms delay to ensure response delivery).
+                // Uses this.restartKillFn so tests can override without killing the runner.
+                const killFn = this.restartKillFn;
+                setTimeout(() => {
+                    this.logger.info("[/restart] Sending SIGTERM to self");
+                    killFn();
+                }, 100);
+                return;
+            }
+            // /shutdown — graceful exit endpoint. POST → triggers the bridge's
+            // internal shutdown sequence (lockfile unlink, HTTP close, telemetry
+            // flush). Same in-flight safety check as /restart; pass `?force=1` to
+            // skip it. Necessary on Windows where `process.kill(pid, 'SIGTERM')`
+            // is TerminateProcess and cleanup handlers never fire — the bridge
+            // wires `shutdownFn` to call the shutdown sequence directly.
+            if (parsedUrl.pathname === "/shutdown" && req.method === "POST") {
+                const force = parsedUrl.searchParams.get("force") === "1";
+                if (!force && this.restartCheckFn) {
+                    const check = this.restartCheckFn();
+                    if (check.inFlightCalls > 0) {
+                        this.logger.warn(`[/shutdown] Rejected — ${check.inFlightCalls} in-flight tool call${check.inFlightCalls === 1 ? "" : "s"}`);
+                        res.writeHead(409, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: "shutdown_blocked",
+                            reason: `${check.inFlightCalls} tool call${check.inFlightCalls === 1 ? "" : "s"} in progress`,
+                            inFlightCalls: check.inFlightCalls,
+                            busySessions: check.busySessions,
+                        }));
+                        return;
+                    }
+                }
+                this.logger.info("[/shutdown] Initiating graceful shutdown");
+                res.writeHead(202, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: true,
+                    message: "Shutdown initiated.",
+                }));
+                const shutdownFn = this.shutdownFn;
+                setTimeout(() => {
+                    this.logger.info("[/shutdown] Calling bridge shutdown sequence");
+                    shutdownFn();
+                }, 100);
+                return;
+            }
             // CC hook notify endpoint — lightweight alternative to full MCP session for hook wiring.
             if (parsedUrl.pathname === "/notify" && req.method === "POST") {
                 // 8 KB — notify payloads carry an event name + small arg map
@@ -1409,7 +1762,7 @@ export class Server extends EventEmitter {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Quick tasks unavailable — requires --claude-driver subprocess",
+                        error: "Quick tasks unavailable — requires --driver subprocess",
                     }));
                     return;
                 }