@stravica-ai/digital-operator-pa 0.1.29 → 0.1.30

package/dist/engineering-pa-library-cli/src/envelope.mjs

@@ -13,7 +13,7 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
-import { relative, isAbsolute } from 'node:path';
+import { isAbsolute, normalize, relative, sep } from 'node:path';
 
 import { EVENT_KINDS, canonicalJson } from '@stravica-ai/remote-library';
 
@@ -31,6 +31,47 @@ export function contentShaOf(payload) {
   return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
 }
 
+/**
+ * Refuse a source path that would encode as an escape from the repo root.
+ * Root-cause cure for the poison-event wedge Stream 5 re-verify Scope C
+ * surfaced (w-2026-08-24-dave-025, SA14). Called by buildEnvelope after
+ * relPath is computed. Semantics match the server's assertPathSafe
+ * (spec §4 apply gate): reject empty, absolute, NUL, drive-letter,
+ * root-backslash, `..`-segments, and any string that normalises to a
+ * path starting with `..`. The error names the input sourcePath and
+ * repoRoot so an operator can see immediately why the encoding refused.
+ *
+ * @param {string} relPath      candidate repo-relative path
+ * @param {string} sourcePath   original input (for the error message)
+ * @param {string} repoRoot     resolved repo root (for the error message)
+ * @throws {Error} with exitCode=1 if the path is unsafe
+ */
+export function assertRepoRelativeSafe(relPath, sourcePath, repoRoot) {
+  const fail = (reason) => {
+    const err = new Error(
+      `refusing to encode source path outside repo root (${reason}): ` +
+        `sourcePath=${JSON.stringify(sourcePath)}, repoRoot=${JSON.stringify(repoRoot)}, ` +
+        `resolvedRelative=${JSON.stringify(relPath)}. ` +
+        `Move the file into the repo or stage it under a repo-resident path before calling library put.`,
+    );
+    err.exitCode = 1;
+    throw err;
+  };
+  if (typeof relPath !== 'string') fail('path must be a string');
+  if (relPath.length === 0) fail('path resolves empty');
+  if (relPath.includes('\0')) fail('path contains NUL byte');
+  if (isAbsolute(relPath)) fail('resolved path is absolute');
+  if (/^[A-Za-z]:[\\/]/.test(relPath) || relPath.startsWith('\\')) {
+    fail('drive-letter or root-backslash path');
+  }
+  const parts = relPath.split(/[/\\]/);
+  if (parts.some((seg) => seg === '..')) fail("'..' segments not permitted");
+  const normalised = normalize(relPath);
+  if (normalised === '..' || normalised.startsWith('..' + sep) || normalised.startsWith('../')) {
+    fail('path normalises outside repo root');
+  }
+}
+
 /**
  * Guess the event kind from a staging file path when the operator did
  * not supply one via `--kind`. Falls back to
@@ -77,9 +118,22 @@ export function buildEnvelope({
   sourceKind = 'manual',
   clock = () => new Date(),
 }) {
+  // Repo-relative resolution + refusal for anything that would encode as
+  // a `..`-segment or otherwise escape the repo root. This is the root
+  // cause cure for the Stream 5 re-verify Scope C poison-event wedge
+  // (w-2026-08-24-dave-025). Before this cure `relative(repoRoot, abs)`
+  // silently produced `../../etc/...` for files sitting outside the
+  // repo and the envelope was posted with a payload path the worker's
+  // apply gate would later refuse — halting single-writer propagation
+  // for the whole estate. Refusing here (client-side, at encoding time)
+  // stops the poison at source; SA14's ingest-side check is the second
+  // line; the worker's apply gate remains the third.
   const relPath = sourcePath
     ? isAbsolute(sourcePath) ? relative(repoRoot, sourcePath) : sourcePath
     : undefined;
+  if (relPath !== undefined) {
+    assertRepoRelativeSafe(relPath, sourcePath, repoRoot);
+  }
 
   const resolvedKind = kind ?? guessKindFromPath(relPath ?? sourcePath ?? '') ?? null;
   if (!resolvedKind) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",