jules-orchestrator-kit 0.9.4 → 0.20.0

package/src/rules_budget.mjs

@@ -1,9 +1,13 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 
 const DEFAULT_MAX_CHARS = 10000; // Safe threshold below Antigravity 12k & Claude 25k limits
 const DEFAULT_MAX_LINES = 250;
 
+export const SENTINEL_BEGIN = "JULES_RULES_SENTINEL BEGIN";
+export const SENTINEL_END = "JULES_RULES_SENTINEL END";
+
 /**
  * Audit character and line counts of compiled instruction files to prevent truncation.
  *
@@ -68,6 +72,103 @@ export function checkRulesBudget(root = process.cwd(), opts = {}) {
   };
 }
 
+/**
+ * Compiles markdown/rules files into a single unified context block wrapped
+ * in SHA-256 and byte-length anti-truncation sentinels.
+ */
+export function compileRules(root = process.cwd(), _opts = {}) {
+  const candidateFiles = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+    "JULES_RULES_TEMPLATE.md",
+  ];
+
+  const rulesDir = join(root, ".agent", "rules");
+  try {
+    const files = readdirSync(rulesDir);
+    for (const f of files) {
+      if (f.endsWith(".md")) {
+        candidateFiles.push(join(".agent", "rules", f));
+      }
+    }
+  } catch (_) {}
+
+  const sources = [];
+  const sections = [];
+
+  for (const relPath of candidateFiles) {
+    const fullPath = join(root, relPath);
+    if (!existsSync(fullPath)) continue;
+    try {
+      const raw = readFileSync(fullPath, "utf-8");
+      const body = raw.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+      if (!body) continue;
+      sections.push(`<!-- source: ${relPath} -->\n${body}`);
+      sources.push(relPath);
+    } catch (_) {}
+  }
+
+  const body = sections.join("\n\n---\n\n");
+  const bodyLen = Buffer.byteLength(body, "utf-8");
+  const sha256 = createHash("sha256").update(body).digest("hex");
+
+  const header = `<!-- ${SENTINEL_BEGIN} len=${bodyLen} sha256=${sha256} -->`;
+  const footer = `<!-- ${SENTINEL_END} len=${bodyLen} sha256=${sha256} -->`;
+  const compiled = `${header}\n${body}\n${footer}\n`;
+
+  return { compiled, body, bodyLen, sha256, sources };
+}
+
+/**
+ * Verifies that a compiled rule string has not been truncated or tampered with by downstream LLMs.
+ */
+export function verifyRulesSentinel(compiled) {
+  const errors = [];
+  if (typeof compiled !== "string" || compiled.length === 0) {
+    return { ok: false, errors: ["empty input"] };
+  }
+
+  const beginRe = new RegExp(`<!--\\s*${SENTINEL_BEGIN.replace(/ /g, "\\s+")}\\s+len=(\\d+)\\s+sha256=([0-9a-f]{64})\\s*-->`);
+  const endRe = new RegExp(`<!--\\s*${SENTINEL_END.replace(/ /g, "\\s+")}\\s+len=(\\d+)\\s+sha256=([0-9a-f]{64})\\s*-->`);
+
+  const beginMatch = beginRe.exec(compiled);
+  const endMatch = endRe.exec(compiled);
+
+  if (!beginMatch) { errors.push("missing or malformed BEGIN sentinel"); return { ok: false, errors }; }
+  if (!endMatch) { errors.push("missing or malformed END sentinel"); return { ok: false, errors }; }
+
+  const beginLen = Number(beginMatch[1]);
+  const beginSha = beginMatch[2];
+  const endLen = Number(endMatch[1]);
+  const endSha = endMatch[2];
+
+  if (beginLen !== endLen) errors.push(`length mismatch: BEGIN=${beginLen} END=${endLen}`);
+  if (beginSha !== endSha) errors.push("checksum mismatch between BEGIN and END sentinels");
+
+  const bodyStart = beginMatch.index + beginMatch[0].length;
+  const bodyEnd = endMatch.index;
+  const body = compiled.slice(bodyStart, bodyEnd).replace(/^\r?\n/, "").replace(/\r?\n$/, "");
+  const actualLen = Buffer.byteLength(body, "utf-8");
+
+  if (actualLen !== beginLen) {
+    errors.push(`body length ${actualLen} != declared ${beginLen} (possible truncation or injection)`);
+  }
+
+  const recomputed = createHash("sha256").update(body).digest("hex");
+  if (recomputed !== beginSha) {
+    errors.push(`body checksum ${recomputed} != declared ${beginSha} (content tampered or truncated)`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    bodyLen: actualLen,
+    sha256: recomputed,
+  };
+}
+
 function existsSync(p) {
   try {
     return statSync(p).isFile();
@@ -75,3 +176,4 @@ function existsSync(p) {
     return false;
   }
 }
+

package/src/security.mjs

@@ -1,3 +1,6 @@
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
 import { normalizePath } from "./config.mjs";
 
 export const HIGH_CONFIDENCE_PATTERNS = [
@@ -6,34 +9,70 @@ export const HIGH_CONFIDENCE_PATTERNS = [
   /\bghu_[A-Za-z0-9_]{36,255}\b/g,
   /\bghs_[A-Za-z0-9_]{36,255}\b/g,
   /\bghr_[A-Za-z0-9_]{36,255}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{22,255}\b/g,
 
   /\bAKIA[0-9A-Z]{16}\b/g,
   /\bASIA[0-9A-Z]{16}\b/g,
   /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/g,
 
-  /-----BEGIN\s+(?:RSA|DSA|EC|OPENSSH|PRIVATE)\s+KEY-----[\s\S]*?-----END\s+(?:RSA|DSA|EC|OPENSSH|PRIVATE)\s+KEY-----/g,
+  /-----BEGIN (?:RSA|DSA|EC|OPENSSH|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|DSA|EC|OPENSSH|PRIVATE) KEY-----/g,
   /PuTTY-User-Key-File-[0-9]:[^\n]+/g,
 
   /\bsk_live_[0-9a-zA-Z]{24,99}\b/g,
   /\brk_live_[0-9a-zA-Z]{24,99}\b/g,
   /\bnpm_[0-9a-zA-Z]{36}\b/g,
-  /\bglpat-[0-9a-zA-Z_-]{20,}\b/g,
-  /\bGOCSPX-[0-9a-zA-Z_-]{28}\b/g,
+  /\bglpat-[0-9a-zA-Z_-]{20,99}\b/g,
+  /\bGOCSPX-[0-9a-zA-Z_-]{28,99}\b/g,
 
   /\bAIzaSy[A-Za-z0-9_-]{33}\b/g,
+  /\bya29\.[A-Za-z0-9_-]{20,255}\b/g,
+  /\b(?:sk-ant-api03-|sk-proj-)[A-Za-z0-9_-]{32,255}\b/g,
 
-  /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]+\/B[A-Za-z0-9_]+\/[A-Za-z0-9_]+/g,
+  /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]{8,}\/B[A-Za-z0-9_]{8,}\/[A-Za-z0-9_]{24,}/g,
+  /\bxox[baprs]-[0-9a-zA-Z-]{10,48}\b/g,
 
   /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
 ];
 
 export const LOW_CONFIDENCE_PATTERNS = [
-  /Bearer\s+[A-Za-z0-9._~+/-]{10,}/gi,
-  /Authorization:\s*Bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+  /Bearer\s+[A-Za-z0-9._~+/-]{10,255}/gi,
+  /Authorization:\s*Bearer\s+[A-Za-z0-9._~+/-]{10,255}/gi,
   /\bsk_test_[0-9a-zA-Z]{24,99}\b/g,
   /(?:api[_-]?key|secret|password|passwd|token|auth[_-]?token)\s*[:=]\s*['"]([^'"]{8,128})['"]/gi,
 ];
 
+/**
+ * TOCTOU-safe atomic file write using O_CREAT|O_EXCL|O_WRONLY temp file in target dir.
+ */
+export function safeAtomicWrite(filePath, content, options = {}) {
+  const mode = options.mode || 0o644;
+  const encoding = options.encoding || "utf-8";
+
+  if (existsSync(filePath)) {
+    const stat = lstatSync(filePath);
+    if (stat.isSymbolicLink()) {
+      const realPath = realpathSync(filePath);
+      if (options.rejectSymlinks) {
+        throw new Error(`TOCTOU Guard: Refusing to write to symlink ${filePath} -> ${realPath}`);
+      }
+    }
+  }
+
+  const dir = dirname(filePath);
+  const tempFile = join(dir, `.tmp-${basename(filePath)}-${randomBytes(6).toString("hex")}`);
+
+  const fd = openSync(tempFile, "wx", mode);
+  try {
+    writeSync(fd, content, null, encoding);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+
+  renameSync(tempFile, filePath);
+  return true;
+}
+
 export function shannonEntropy(str) {
   if (!str || typeof str !== "string") return 0;
   const len = str.length;

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,7 +9,7 @@ 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 (!secret) return false; // Fail closed if secret is not configured
   if (!signatureHeader || !signatureHeader.startsWith("sha256=")) return false;
 
   const hmac = createHmac("sha256", secret);
@@ -104,15 +104,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" }));