@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/storage/windows-process-incarnation.js

@@ -0,0 +1,206 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import path from "node:path";
+
+export const WINDOWS_PROCESS_INCARNATION_SCHEMA_VERSION = 1;
+export const WINDOWS_PROCESS_INCARNATION_KIND = "windows-process-start-time-ticks-v1";
+export const WINDOWS_PROCESS_INCARNATION_DEFAULTS = Object.freeze({
+  timeoutMs: 5_000,
+  maxOutputBytes: 16 * 1024,
+});
+
+const MAX_TIMEOUT_MS = WINDOWS_PROCESS_INCARNATION_DEFAULTS.timeoutMs;
+const MAX_OUTPUT_BYTES = WINDOWS_PROCESS_INCARNATION_DEFAULTS.maxOutputBytes;
+const MAX_PROCESS_ID = 2_147_483_647;
+const MAX_DATETIME_TICKS = 3_155_378_975_999_999_999n;
+const PROCESS_STATUSES = new Set(["ALIVE", "EXITED", "NOT_FOUND"]);
+
+function boundedPositiveInteger(value, fallback, maximum) {
+  return Number.isInteger(value) && value > 0 ? Math.min(value, maximum) : fallback;
+}
+
+function assertProcessId(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1 || pid > MAX_PROCESS_ID) {
+    throw new TypeError("Windows process identity requires a positive 32-bit process ID");
+  }
+}
+
+/**
+ * Resolve only the conventional absolute system PowerShell path. This is a
+ * path constraint, not a signer or host attestation; unsupported/untrusted
+ * host configuration must remain unavailable to the caller.
+ */
+export function resolveWindowsPowerShellPath({ platform = process.platform, systemRoot = process.env.SystemRoot } = {}) {
+  if (platform !== "win32" || typeof systemRoot !== "string" || systemRoot.length === 0 || systemRoot.includes("\0")) return null;
+  // A SystemRoot value must name a fully qualified local drive path. Windows
+  // also treats `\\Windows` as absolute, but that form is current-drive
+  // relative and must not select an arbitrary host path. Device prefixes,
+  // UNC paths, and drive-relative values are rejected by this check.
+  if (!/^[A-Za-z]:[\\/]/u.test(systemRoot)) return null;
+  if (/(^|[\\/])\.\.([\\/]|$)/u.test(systemRoot)) return null;
+  const normalizedRoot = path.win32.normalize(systemRoot);
+  if (!/^[A-Za-z]:\\/u.test(normalizedRoot) || !path.win32.isAbsolute(normalizedRoot) || normalizedRoot.startsWith("\\\\")) return null;
+  return path.win32.join(normalizedRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+
+/**
+ * The script has one authority-bearing operation: StartTime, read while the
+ * Process object retains its kernel handle. Names and command lines are never
+ * queried. The PID is validated before it is embedded as a numeric literal.
+ */
+export function buildWindowsProcessIncarnationScript(pid) {
+  assertProcessId(pid);
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    "$WarningPreference = 'Stop'",
+    "$InformationPreference = 'SilentlyContinue'",
+    "$ProgressPreference = 'SilentlyContinue'",
+    "$VerbosePreference = 'SilentlyContinue'",
+    "$DebugPreference = 'SilentlyContinue'",
+    `$targetPid = ${pid}`,
+    "$result = $null",
+    "try {",
+    "  $candidate = $null",
+    "  try { $candidate = [System.Diagnostics.Process]::GetProcessById($targetPid) } catch {",
+    "    $lookupException = $_.Exception",
+    "    while ($lookupException -is [System.Management.Automation.MethodInvocationException] -and $null -ne $lookupException.InnerException) { $lookupException = $lookupException.InnerException }",
+    "    if ($lookupException -is [System.ArgumentException]) { $result = [ordered]@{ schemaVersion = 1; pid = $targetPid; status = 'NOT_FOUND' } } else { $result = [ordered]@{ schemaVersion = 1; pid = $targetPid; status = 'UNAVAILABLE' } }",
+    "  }",
+    "  if ($null -ne $candidate) {",
+    "    try {",
+    "      $retainedHandle = $candidate.Handle",
+    "      if ($retainedHandle -eq [IntPtr]::Zero) { throw [System.InvalidOperationException]::new('Process handle unavailable') }",
+    "      $startTimeTicks = $candidate.StartTime.ToUniversalTime().Ticks.ToString('D', [Globalization.CultureInfo]::InvariantCulture)",
+    "      $hasExited = $candidate.HasExited",
+    "      $status = 'ALIVE'",
+    "      if ($hasExited) { $status = 'EXITED' }",
+    "      $result = [ordered]@{ schemaVersion = 1; pid = $targetPid; status = $status; hasExited = $hasExited; startTimeTicks = $startTimeTicks }",
+    "    } catch {",
+    "      $result = [ordered]@{ schemaVersion = 1; pid = $targetPid; status = 'UNAVAILABLE' }",
+    "    } finally {",
+    "      $candidate.Dispose()",
+    "    }",
+    "  }",
+    "} catch { $result = [ordered]@{ schemaVersion = 1; pid = $targetPid; status = 'UNAVAILABLE' } }",
+    "[Console]::Out.Write(($result | ConvertTo-Json -Compress -Depth 2))",
+  ].join("\n");
+}
+
+function encodeWindowsProcessIncarnationScript(pid) {
+  return Buffer.from(buildWindowsProcessIncarnationScript(pid), "utf16le").toString("base64");
+}
+
+function windowsProcessIncarnationArgs(pid) {
+  return [
+    "-NoLogo",
+    "-NoProfile",
+    "-NonInteractive",
+    "-EncodedCommand",
+    encodeWindowsProcessIncarnationScript(pid),
+  ];
+}
+
+function exactKeys(value, keys) {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function validTicks(value) {
+  if (typeof value !== "string" || !/^[1-9]\d{0,18}$/u.test(value)) return false;
+  try { return BigInt(value) <= MAX_DATETIME_TICKS; } catch { return false; }
+}
+
+/** Validate the persisted owner token without accepting observation-only fields. */
+export function isWindowsProcessIncarnationToken(value, { pid = value?.pid } = {}) {
+  try { assertProcessId(pid); } catch { return false; }
+  return !!value
+    && exactKeys(value, ["kind", "pid", "schemaVersion", "startTimeTicks"])
+    && value.kind === WINDOWS_PROCESS_INCARNATION_KIND
+    && value.schemaVersion === WINDOWS_PROCESS_INCARNATION_SCHEMA_VERSION
+    && value.pid === pid
+    && validTicks(value.startTimeTicks);
+}
+
+/** Parse only the small, authority-bearing JSON envelope emitted by the fixed script. */
+export function parseWindowsProcessIncarnationOutput(stdout, { pid, maxOutputBytes = MAX_OUTPUT_BYTES } = {}) {
+  try { assertProcessId(pid); } catch { return null; }
+  const outputLimit = boundedPositiveInteger(maxOutputBytes, MAX_OUTPUT_BYTES, MAX_OUTPUT_BYTES);
+  if (typeof stdout !== "string" || Buffer.byteLength(stdout, "utf8") > outputLimit) return null;
+  const text = stdout.trim();
+  if (text.length === 0) return null;
+  let value;
+  try { value = JSON.parse(text); } catch { return null; }
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || value.schemaVersion !== WINDOWS_PROCESS_INCARNATION_SCHEMA_VERSION
+    || value.pid !== pid || typeof value.status !== "string" || !PROCESS_STATUSES.has(value.status)) return null;
+  if (value.status === "NOT_FOUND") {
+    return exactKeys(value, ["pid", "schemaVersion", "status"]) ? Object.freeze({
+      schemaVersion: value.schemaVersion,
+      pid: value.pid,
+      status: value.status,
+    }) : null;
+  }
+  if (!exactKeys(value, ["hasExited", "pid", "schemaVersion", "startTimeTicks", "status"])
+    || typeof value.hasExited !== "boolean"
+    || value.hasExited !== (value.status === "EXITED")
+    || !validTicks(value.startTimeTicks)) return null;
+  return Object.freeze({
+    schemaVersion: value.schemaVersion,
+    pid: value.pid,
+    status: value.status,
+    hasExited: value.hasExited,
+    startTimeTicks: value.startTimeTicks,
+  });
+}
+
+function invokeExecFile(execFileImpl, file, args, options, timeoutMs) {
+  return new Promise((resolve) => {
+    let child;
+    let timedOut = false;
+    const finish = (result) => {
+      clearTimeout(timer);
+      resolve(timedOut
+        ? { error: Object.assign(new Error("Windows process identity query timed out"), { code: "ETIMEDOUT" }), stdout: "", stderr: "" }
+        : result);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child?.kill?.(); } catch { /* process may already be gone */ }
+      // The child_process implementation invokes the callback after the
+      // killed child closes. Do not resolve before that close is observed.
+    }, timeoutMs);
+    try {
+      child = execFileImpl(file, args, options, (error, stdout, stderr) => finish({ error, stdout: stdout ?? "", stderr: stderr ?? "" }));
+    } catch (error) {
+      finish({ error, stdout: "", stderr: "" });
+    }
+  });
+}
+
+/**
+ * Return a kernel-backed Windows process observation, or null when the host
+ * cannot provide one. This helper is intentionally not wired into admission;
+ * callers must keep legacy schema-v1 ESRCH handling separate.
+ */
+export async function readWindowsProcessIncarnation(pid, {
+  platform = process.platform,
+  systemRoot = process.env.SystemRoot,
+  execFileImpl = nodeExecFile,
+  timeoutMs = WINDOWS_PROCESS_INCARNATION_DEFAULTS.timeoutMs,
+  maxOutputBytes = WINDOWS_PROCESS_INCARNATION_DEFAULTS.maxOutputBytes,
+} = {}) {
+  try { assertProcessId(pid); } catch { return null; }
+  const executable = resolveWindowsPowerShellPath({ platform, systemRoot });
+  if (!executable) return null;
+  const boundedTimeoutMs = boundedPositiveInteger(timeoutMs, WINDOWS_PROCESS_INCARNATION_DEFAULTS.timeoutMs, MAX_TIMEOUT_MS);
+  const boundedOutputBytes = boundedPositiveInteger(maxOutputBytes, WINDOWS_PROCESS_INCARNATION_DEFAULTS.maxOutputBytes, MAX_OUTPUT_BYTES);
+  const result = await invokeExecFile(execFileImpl, executable, windowsProcessIncarnationArgs(pid), {
+    shell: false,
+    windowsHide: true,
+    timeout: boundedTimeoutMs,
+    maxBuffer: boundedOutputBytes,
+    encoding: "utf8",
+  }, boundedTimeoutMs);
+  if (result.error || typeof result.stderr !== "string" || result.stderr.length !== 0) return null;
+  return parseWindowsProcessIncarnationOutput(result.stdout, { pid, maxOutputBytes: boundedOutputBytes });
+}

package/.forgeloop/forgeloop.gitignore

@@ -1,4 +0,0 @@
-# Local resumable task state is untrusted, target-specific data.
-work-state.json
-executions/
-repository-index/

package/LICENSE-DOCS.md

@@ -1,13 +0,0 @@
-# Documentation license
-
-Original documentation in this repository is offered under the Creative
-Commons Attribution 4.0 International license (CC BY 4.0):
-
-<https://creativecommons.org/licenses/by/4.0/>
-
-That license permits sharing, adaptation, and commercial use when appropriate
-credit, a link to the license, and an indication of changes are provided.
-
-This notice applies only to documentation for which the repository owner has
-the necessary rights. Adapted or externally sourced material remains subject
-to the terms and attribution recorded in `THIRD_PARTY_NOTICES.md`.

package/src/core/transaction-maintenance.js

@@ -1,70 +0,0 @@
-import { lstat, readdir, readFile, rm } from "node:fs/promises";
-import path from "node:path";
-import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
-import { withTaskLock } from "./task-lock.js";
-
-const ROOT = ".forgeloop/.txn";
-const TERMINAL = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
-const DAY_MS = 86_400_000;
-
-async function payloadBytes(directory) {
-  let bytes = 0;
-  for (const entry of await readdir(directory, { withFileTypes: true })) {
-    const child = path.join(directory, entry.name);
-    const metadata = await lstat(child);
-    if (metadata.isSymbolicLink()) throw new Error("Transaction payload contains a symlink");
-    if (metadata.isDirectory()) bytes += await payloadBytes(child);
-    else if (metadata.isFile()) bytes += metadata.size;
-    else throw new Error("Transaction payload contains a special file");
-  }
-  return bytes;
-}
-
-/** Compact terminal payloads only; preserve manifests and all event ledgers. */
-export async function compactTransactions({ target, retainDays = 7, apply = false, now = Date.now() } = {}) {
-  if (!Number.isFinite(retainDays) || retainDays < 1) throw new Error("retainDays must be at least one day");
-  await assertSafePath(target, ROOT);
-  const root = ensureWithin(target, ROOT);
-  const report = { apply, scanned: 0, eligible: 0, bytes: 0, compacted: 0, skipped: [] };
-  if (!await fileExists(root)) return report;
-  for (const entry of await readdir(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    report.scanned += 1;
-    const relative = `${ROOT}/${entry.name}`;
-    const manifestPath = `${relative}/manifest.json`;
-    try {
-      await assertSafePath(target, manifestPath);
-      const original = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
-      const lockTaskId = original.lockTaskId ?? original.taskId;
-      if (typeof lockTaskId !== "string" || !lockTaskId) throw new Error("Missing lock identity");
-      await withTaskLock(target, lockTaskId, "compact-transactions", async () => {
-        const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
-        if ((manifest.lockTaskId ?? manifest.taskId) !== lockTaskId || manifest.transactionId !== entry.name) throw new Error("Changed transaction identity");
-        const timestamp = Date.parse(manifest.committedAt ?? manifest.recoveredAt ?? manifest.failedAt ?? manifest.startedAt);
-        if (!TERMINAL.has(manifest.status) || !Number.isFinite(timestamp) || now - timestamp < retainDays * DAY_MS) return;
-        const payloads = [];
-        let bytes = 0;
-        for (const name of ["stage", "backup"]) {
-          const payload = `${relative}/${name}`;
-          await assertSafePath(target, payload);
-          const fullPath = ensureWithin(target, payload);
-          if (await fileExists(fullPath)) {
-            bytes += await payloadBytes(fullPath);
-            payloads.push(fullPath);
-          }
-        }
-        if (!payloads.length) return;
-        report.eligible += 1;
-        report.bytes += bytes;
-        if (!apply) return;
-        for (const payload of payloads) await rm(payload, { recursive: true, force: true, maxRetries: 3 });
-        manifest.compactedAt = new Date(now).toISOString();
-        await writeFileAtomic(ensureWithin(target, manifestPath), `${JSON.stringify(manifest, null, 2)}\n`);
-        report.compacted += 1;
-      });
-    } catch (error) {
-      report.skipped.push({ transactionId: entry.name, reason: error.message });
-    }
-  }
-  return report;
-}