jules-orchestrator-kit 0.9.4 → 0.21.0

package/src/state.mjs

@@ -1,15 +1,18 @@
 import {
   readFileSync,
-  appendFileSync,
   existsSync,
   mkdirSync,
+  rmdirSync,
   readdirSync,
   openSync,
   writeSync,
   closeSync,
+  fsyncSync,
   unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 import { resolveRoot } from "./config.mjs";
 
 export function ensureDir(dirPath) {
@@ -43,17 +46,111 @@ export function getDailyLedgerPath(rootOrOpts = resolveRoot()) {
 }
 
 /**
- * Appends a structured audit event to the daily session ledger.
+ * Executes a function inside a kernel-level VFS directory mutex for strict linearizability.
+ */
+export function withVfsMutex(mutexDir, fn, opts = {}) {
+  const maxRetries = opts.maxRetries || 50;
+  const retryDelayMs = opts.retryDelayMs || 10;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      mkdirSync(mutexDir);
+      try {
+        return fn();
+      } finally {
+        try {
+          rmdirSync(mutexDir);
+        } catch (_) {}
+      }
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        const deadline = Date.now() + retryDelayMs;
+        while (Date.now() < deadline) {}
+        continue;
+      }
+      throw err;
+    }
+  }
+  return fn();
+}
+
+/**
+ * Appends a structured audit event to the daily session ledger with SHA-256 hash-chain (VFS Mutex Linearized).
  */
 export function appendLedger(entry, rootOrOpts = resolveRoot()) {
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const filePath = getDailyLedgerPath(root);
-  const payload = {
-    timestamp: new Date().toISOString(),
-    ...entry,
-  };
-  appendFileSync(filePath, JSON.stringify(payload) + "\n", "utf-8");
-  return payload;
+  const mutexDir = join(getStateDir(root), ".ledger.mutex");
+
+  return withVfsMutex(mutexDir, () => {
+    let prevHash = "0".repeat(64);
+    if (existsSync(filePath)) {
+      try {
+        const raw = readFileSync(filePath, "utf-8");
+        const lines = raw.split("\n").filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+          try {
+            const lastObj = JSON.parse(lines[i]);
+            if (lastObj.hash) {
+              prevHash = lastObj.hash;
+              break;
+            }
+          } catch (_) {}
+        }
+      } catch (_) {}
+    }
+
+    const timestamp = new Date().toISOString();
+    const rawPayload = { timestamp, ...entry, prevHash };
+    const hash = createHash("sha256").update(JSON.stringify(rawPayload)).digest("hex");
+    const payload = { ...rawPayload, hash };
+
+    const fd = openSync(filePath, "a");
+    try {
+      writeSync(fd, JSON.stringify(payload) + "\n", "utf-8");
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+
+    return payload;
+  });
+}
+
+/**
+ * Verifies the SHA-256 cryptographic hash-chain integrity of a ledger file.
+ */
+export function verifyLedgerIntegrity(filePath) {
+  if (!filePath || !existsSync(filePath)) return { ok: false, count: 0, error: "FILE_NOT_FOUND" };
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n").filter(Boolean);
+    let expectedPrevHash = "0".repeat(64);
+
+    for (let i = 0; i < lines.length; i++) {
+      let obj;
+      try {
+        obj = JSON.parse(lines[i]);
+      } catch (err) {
+        return { ok: false, line: i + 1, error: "TORN_WRITE_CORRUPTION", detail: err.message };
+      }
+      if (!obj.hash || !obj.prevHash) {
+        return { ok: false, line: i + 1, error: "MISSING_HASH_FIELDS" };
+      }
+      if (obj.prevHash !== expectedPrevHash) {
+        return { ok: false, line: i + 1, error: "BROKEN_PREV_HASH", expected: expectedPrevHash, actual: obj.prevHash };
+      }
+      const { hash, ...rest } = obj;
+      const recomputed = createHash("sha256").update(JSON.stringify(rest)).digest("hex");
+      if (recomputed !== hash) {
+        return { ok: false, line: i + 1, error: "CORRUPTED_ENTRY_HASH", expected: recomputed, actual: hash };
+      }
+      expectedPrevHash = hash;
+    }
+    return { ok: true, count: lines.length, lastHash: expectedPrevHash };
+  } catch (err) {
+    return { ok: false, count: 0, error: err.message };
+  }
 }
 
 export function readLedger(filePath) {
@@ -72,9 +169,6 @@ export function readLedger(filePath) {
   }
 }
 
-/**
- * Enforces a daily token budget.
- */
 export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
   let root = typeof arg1 === "string" ? arg1 : resolveRoot();
   let limit = typeof arg1 === "number" ? arg1 : typeof arg2 === "number" ? arg2 : 300;
@@ -106,17 +200,35 @@ export class BudgetError extends Error {
   }
 }
 
-export async function withBudget(fn, root = resolveRoot(), limit = 300) {
+export function reserveBudget(rootOrOpts = resolveRoot(), limit = 300) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const budget = checkDailyBudget(root, limit);
   if (!budget.ok) {
     throw new BudgetError(`Daily budget exhausted (${budget.used}/${budget.budget} tasks executed)`);
   }
-  return fn();
+
+  const reservationId = `res-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+  appendLedger({ event: "budget_reserved", reservationId, budget: limit }, root);
+  return { ok: true, reservationId, remaining: Math.max(0, budget.remaining - 1) };
+}
+
+export function commitBudgetReservation(rootOrOpts = resolveRoot(), reservationId = "") {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  return appendLedger({ event: "budget_committed", reservationId }, root);
+}
+
+export async function withBudget(fn, root = resolveRoot(), limit = 300) {
+  const reservation = reserveBudget(root, limit);
+  try {
+    const result = await fn();
+    commitBudgetReservation(root, reservation.reservationId);
+    return result;
+  } catch (err) {
+    appendLedger({ event: "budget_reservation_failed", reservationId: reservation.reservationId, error: err.message }, root);
+    throw err;
+  }
 }
 
-/**
- * Atomic Advisory Lock File Manager with PID Vitality Check & Stale Lock Reaper (CWE-367 Fix).
- */
 export function getLockDir(rootOrOpts = resolveRoot()) {
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const dir = join(getStateDir(root), "locks");
@@ -124,14 +236,39 @@ export function getLockDir(rootOrOpts = resolveRoot()) {
   return dir;
 }
 
-export function isPidAlive(pid) {
+/**
+ * Checks if a PID is alive with optional PID-recycling start time validation on Linux.
+ */
+export function isPidAlive(pid, expectedStartTime = null) {
   if (!pid || typeof pid !== "number") return false;
   try {
     process.kill(pid, 0);
-    return true;
   } catch (_) {
     return false;
   }
+
+  if (expectedStartTime && process.platform === "linux") {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+      const parts = stat.split(" ");
+      const startTime = parts[21];
+      if (startTime && String(startTime) !== String(expectedStartTime)) {
+        return false;
+      }
+    } catch (_) {}
+  }
+
+  return true;
+}
+
+function getProcessStartTime(pid) {
+  if (process.platform === "linux") {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+      return stat.split(" ")[21] || null;
+    } catch (_) {}
+  }
+  return null;
 }
 
 export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot()) {
@@ -139,15 +276,13 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   const lockDir = getLockDir(root);
   const lockFile = join(lockDir, `${taskId}.json`);
 
-  // Stale Lock Reaper Check
   if (existsSync(lockFile)) {
     try {
       const existing = JSON.parse(readFileSync(lockFile, "utf-8"));
-      const isAlive = isPidAlive(existing.pid);
+      const isAlive = isPidAlive(existing.pid, existing.processStartTime);
       const isExpired = existing.acquiredAt && Date.now() - new Date(existing.acquiredAt).getTime() > 7200000;
 
       if (!isAlive || isExpired) {
-        // Dead or expired holder; safely reap lock
         try { unlinkSync(lockFile); } catch (_) {}
       } else {
         return { ok: false, holder: existing.agent, taskId, pid: existing.pid };
@@ -162,13 +297,15 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     taskId,
     files,
     pid: process.pid,
+    processStartTime: getProcessStartTime(process.pid),
+    hostname: hostname(),
     acquiredAt: new Date().toISOString(),
   };
 
-  // Atomic file creation via 'wx' flag (Fixes TOCTOU Race Condition)
   try {
     const fd = openSync(lockFile, "wx");
     writeSync(fd, JSON.stringify(payload, null, 2), "utf-8");
+    fsyncSync(fd);
     closeSync(fd);
     return { ok: true, lockFile };
   } catch (err) {
@@ -191,7 +328,7 @@ export function releaseLock(taskId, rootOrOpts = resolveRoot()) {
 
   if (existsSync(lockFile)) {
     try {
-      unlinkSync(lockFile); // CRITICAL FIX: Fixed ESM unlinkSync (removed legacy require("node:fs"))
+      unlinkSync(lockFile);
       return true;
     } catch (_) {}
   }

package/src/webhook.mjs

@@ -9,8 +9,13 @@ import { createServer } from "node:http";
  * @returns {boolean} True if signature matches
  */
 export function verifySignature(payload, signatureHeader, secret) {
-  if (!secret) return true; // If no secret is configured, skip verification (development mode)
-  if (!signatureHeader || !signatureHeader.startsWith("sha256=")) return false;
+  if (!secret) return false; // Fail closed if secret is not configured
+  if (typeof signatureHeader !== "string") return false;
+  if (!signatureHeader.startsWith("sha256=")) return false;
+
+  const hexSignature = signatureHeader.slice(7);
+  // Verify hexSignature consists strictly of 64 hex characters (0-9, a-f, A-F)
+  if (!/^[0-9a-fA-F]{64}$/.test(hexSignature)) return false;
 
   const hmac = createHmac("sha256", secret);
   const bodyBuf = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf-8");
@@ -30,13 +35,16 @@ export function verifySignature(payload, signatureHeader, secret) {
  * @returns {object} Parsed JSON payload
  */
 export function parseWebhookPayload(bodyBuf, contentType = "application/json") {
-  const str = bodyBuf.toString("utf-8");
+  if (!bodyBuf || bodyBuf.length === 0) return {};
+  const str = bodyBuf.toString("utf-8").trim();
+  if (!str) return {};
+
   if (contentType.includes("application/x-www-form-urlencoded")) {
     const params = new URLSearchParams(str);
     const payloadStr = params.get("payload");
     return payloadStr ? JSON.parse(payloadStr) : {};
   }
-  return str ? JSON.parse(str) : {};
+  return JSON.parse(str);
 }
 
 /**
@@ -47,37 +55,64 @@ export function parseWebhookPayload(bodyBuf, contentType = "application/json") {
  * @returns {object} Response summary { handled: boolean, action: string, details: object }
  */
 export function routeWebhookEvent(eventType, payload, handlers = {}) {
+  const safePayload = payload || {};
+
   if (eventType === "ping") {
-    return { handled: true, action: "ping", details: { zen: payload.zen, hookId: payload.hook_id } };
+    return { handled: true, action: "ping", details: { zen: safePayload.zen, hookId: safePayload.hook_id } };
   }
 
   if (eventType === "pull_request") {
-    const action = payload.action;
-    const prNumber = payload.number || payload.pull_request?.number;
-    const repo = payload.repository?.full_name;
-    const branch = payload.pull_request?.head?.ref;
-    const merged = payload.pull_request?.merged || false;
+    const action = safePayload.action;
+    const prNumber = safePayload.number || safePayload.pull_request?.number;
+    const repo = safePayload.repository?.full_name;
+    const branch = safePayload.pull_request?.head?.ref;
+    const merged = safePayload.pull_request?.merged || false;
 
     const details = { action, prNumber, repo, branch, merged };
     if (typeof handlers.onPullRequest === "function") {
-      handlers.onPullRequest(details, payload);
+      try {
+        handlers.onPullRequest(details, safePayload);
+      } catch (err) {
+        // Safely ignore errors from handlers
+      }
     }
     return { handled: true, action: `pull_request:${action}`, details };
   }
 
   if (eventType === "workflow_run") {
-    const action = payload.action;
-    const name = payload.workflow?.name || payload.workflow_run?.name;
-    const conclusion = payload.workflow_run?.conclusion;
-    const repo = payload.repository?.full_name;
+    const action = safePayload.action;
+    const name = safePayload.workflow?.name || safePayload.workflow_run?.name;
+    const conclusion = safePayload.workflow_run?.conclusion;
+    const repo = safePayload.repository?.full_name;
 
     const details = { action, name, conclusion, repo };
     if (typeof handlers.onWorkflowRun === "function") {
-      handlers.onWorkflowRun(details, payload);
+      try {
+        handlers.onWorkflowRun(details, safePayload);
+      } catch (err) {
+        // Safely ignore errors from handlers
+      }
     }
     return { handled: true, action: `workflow_run:${action}`, details };
   }
 
+  // Fallback status handler for unhandled GitHub event types
+  if (typeof handlers.onUnhandled === "function") {
+    try {
+      handlers.onUnhandled(eventType, safePayload);
+    } catch (err) {
+      // Safely ignore or log error from fallback handler to prevent crashing
+    }
+  }
+
+  if (typeof handlers.onFallback === "function") {
+    try {
+      handlers.onFallback(eventType, safePayload);
+    } catch (err) {
+      // Safely ignore or log error from fallback handler to prevent crashing
+    }
+  }
+
   return { handled: false, action: eventType, details: {} };
 }
 
@@ -104,15 +139,29 @@ export function createWebhookServer({ _port = 8787, secret = process.env.JULES_W
       return;
     }
 
+    const MAX_BODY = 2 * 1024 * 1024; // 2MB payload cap
     const chunks = [];
-    req.on("data", (chunk) => chunks.push(chunk));
+    let totalSize = 0;
+
+    req.on("data", (chunk) => {
+      totalSize += chunk.length;
+      if (totalSize > MAX_BODY) {
+        res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Payload Too Large" }));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+
     req.on("end", () => {
+      if (totalSize > MAX_BODY) return;
       const bodyBuf = Buffer.concat(chunks);
       const sigHeader = req.headers["x-hub-signature-256"];
       const eventType = req.headers["x-github-event"];
       const contentType = req.headers["content-type"] || "application/json";
 
-      if (secret && !verifySignature(bodyBuf, sigHeader, secret)) {
+      if (!verifySignature(bodyBuf, sigHeader, secret)) {
         log(`[Webhook] Invalid signature received from ${req.socket.remoteAddress}`);
         res.writeHead(401, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Invalid signature" }));