fullstackgtm 0.47.0 → 0.49.0

package/src/secureFile.ts

@@ -0,0 +1,169 @@
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fsyncSync,
+  fchmodSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+  readFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, parse, resolve } from "node:path";
+
+export class UnsafeManagedPathError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsafeManagedPathError";
+  }
+}
+
+export function assertNoSymlinkComponents(path: string): void {
+  const absolute = isAbsolute(path) ? path : resolve(path);
+  const root = parse(absolute).root;
+  const relative = absolute.slice(root.length);
+  let current = root;
+
+  for (const component of relative.split(/[\\/]+/).filter(Boolean)) {
+    current = resolve(current, component);
+    let stat;
+    try {
+      stat = lstatSync(current);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new UnsafeManagedPathError(`Refusing to use unsafe path containing a symbolic link: ${current}`);
+    }
+  }
+}
+
+/** Read a managed file through a no-follow descriptor and require a regular file. */
+export function readSecureRegularFile(
+  path: string,
+  options: { tightenMode?: number; onModeTightened?: (previousMode: number) => void } = {},
+): string {
+  const absolute = resolve(path);
+  assertNoSymlinkComponents(dirname(absolute));
+  try {
+    if (lstatSync(absolute).isSymbolicLink()) {
+      throw new UnsafeManagedPathError(`Refusing to read symbolic link: ${absolute}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+  let fd: number | undefined;
+  try {
+    fd = openSync(absolute, constants.O_RDONLY | noFollow);
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) {
+      throw new UnsafeManagedPathError(`Refusing to read non-regular file: ${absolute}`);
+    }
+    if (options.tightenMode !== undefined) {
+      const previousMode = stat.mode & 0o777;
+      if ((previousMode & ~options.tightenMode) !== 0) {
+        try {
+          fchmodSync(fd, options.tightenMode);
+          options.onModeTightened?.(previousMode);
+        } catch {
+          // Windows and some non-POSIX filesystems do not implement chmod.
+        }
+      }
+    }
+    return readFileSync(fd, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+      throw new UnsafeManagedPathError(`Refusing to read symbolic link: ${absolute}`);
+    }
+    throw error;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * Atomically replace a private file without ever opening the destination.
+ * Existing destination and parent symlinks are rejected. The temporary file
+ * is created exclusively beside the destination so rename remains atomic.
+ */
+export function writeSecureFileAtomic(path: string, contents: string | Uint8Array): void {
+  const destination = resolve(path);
+  const parent = dirname(destination);
+  assertNoSymlinkComponents(parent);
+
+  try {
+    if (lstatSync(destination).isSymbolicLink()) {
+      throw new Error(`Refusing to replace symbolic link: ${destination}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  let temporary = "";
+  let fd: number | undefined;
+  try {
+    for (let attempt = 0; attempt < 10; attempt++) {
+      temporary = `${destination}.tmp-${process.pid}-${randomBytes(8).toString("hex")}`;
+      try {
+        const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+        fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600);
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+    }
+    if (fd === undefined) throw new Error(`Unable to create an exclusive temporary file for ${destination}`);
+
+    writeFileSync(fd, contents);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    try {
+      chmodSync(temporary, 0o600);
+    } catch {
+      // Windows and some non-POSIX filesystems do not implement chmod.
+    }
+
+    // Recheck immediately before replacement. rename replaces a symlink rather
+    // than following it, but rejecting one makes managed-path policy explicit.
+    try {
+      if (lstatSync(destination).isSymbolicLink()) {
+        throw new Error(`Refusing to replace symbolic link: ${destination}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    assertNoSymlinkComponents(parent);
+    renameSync(temporary, destination);
+    temporary = "";
+
+    // Persist the directory entry where supported. Opening/fsyncing a
+    // directory is not available on Windows, so this durability enhancement is
+    // deliberately best-effort there.
+    let directoryFd: number | undefined;
+    try {
+      directoryFd = openSync(parent, constants.O_RDONLY);
+      fsyncSync(directoryFd);
+    } catch {
+      // Unsupported by the platform/filesystem.
+    } finally {
+      if (directoryFd !== undefined) closeSync(directoryFd);
+    }
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (temporary) {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // Best-effort cleanup after a failed write.
+      }
+    }
+  }
+}

package/src/types.ts

@@ -20,6 +20,7 @@ export type ApprovalStatus =
   | "draft"
   | "needs_approval"
   | "approved"
+  | "applying"
   | "rejected"
   | "applied";
 
@@ -105,6 +106,15 @@ export type CreateRecordPayload = {
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 
+export type PatchPlanAssumptionConfidence = "derived" | "heuristic" | "guess";
+
+export type PatchPlanAssumption = {
+  id: string;
+  text: string;
+  source?: string;
+  confidence?: PatchPlanAssumptionConfidence;
+};
+
 /**
  * One claim that a canonical record exists in an external system. A record
  * merged from several providers carries one identity per provider.
@@ -397,6 +407,10 @@ export type PatchPlan = {
    *  Account/contact hygiene findings are NOT here; read `findings` for those. */
   pipelineFindings?: PipelineFinding[];
   evidence?: GtmEvidence[];
+  /** Assumptions used to turn audit observations into findings and operations. */
+  assumptions?: PatchPlanAssumption[];
+  /** Human decisions or unresolved questions that affect how the plan should be applied. */
+  openQuestions?: string[];
   operations: PatchOperation[];
   /**
    * The filter this plan's operations were selected by. Re-evaluated per
@@ -454,6 +468,8 @@ export type GtmRuleContext = {
 export type GtmRuleResult = {
   findings: AuditFinding[];
   operations: PatchOperation[];
+  /** Rule-level assumptions that explain the policy or heuristic behind returned findings. */
+  assumptions?: PatchPlanAssumption[];
 };
 
 /**
@@ -466,6 +482,8 @@ export type GtmAuditRule = {
   description: string;
   /** Grouping for docs and discovery, e.g. "hygiene", "forecast", "coverage". */
   category?: string;
+  /** False for findings-only rules whose evaluator intentionally emits no patch operations. */
+  emitsOperations?: boolean;
   evaluate: (context: GtmRuleContext) => GtmRuleResult;
 };