@ctrl-spc/cs 0.7.3 → 0.7.4

package/dist/local-paths.js

@@ -0,0 +1,241 @@
+/**
+ * ═══ AN ABSOLUTE LOCAL PATH MUST NEVER LEAVE THIS MACHINE. ═══
+ *
+ * GENERATION-NEUTRAL, and that is why it lives here rather than in `mcp.ts`. The
+ * rule is the product's, not one generation's: the hosted-path-privacy contract
+ * forbids an absolute local path in hosted browser JS, so every writer of prose
+ * the web renders has to ask the same question of it. This file is the one
+ * answer; `mcp.ts` wraps it in `refuseAbsolutePaths` and `workflows.ts` sweeps a
+ * workflow with it before building one.
+ *
+ * Nothing here reads a file, a table or an environment. It is a scan over a
+ * string and the reasoning about what a path looks like, moved whole out of
+ * `mcp.ts` with that reasoning intact.
+ */
+/** Absolute in any form a repo path can arrive in: POSIX (`/etc`), UNC and
+ *  root-relative Windows (`\\server\share`, `\Users\Lane\repo`), Windows
+ *  drive-letter (`C:\repo`, `C:/repo`) and drive-RELATIVE (`C:AGENTS.md`, which
+ *  resolves against that drive's current directory and still discloses a local
+ *  layout). One leading separator of EITHER kind, or any drive letter, is
+ *  enough — a single leading backslash is a Windows absolute path just as `/`
+ *  is a POSIX one.
+ *
+ *  `cliv2_work_reservations_path_relative`
+ *  (20260722160000_cliv2_coordination.sql) is the same rule for the same
+ *  reason, and it has the narrower form with both of those holes. That is a
+ *  pre-existing bug on that table, not a licence to repeat it here. */
+export const ABSOLUTE_PATH_RE = /^(?:[\\/]|[A-Za-z]:)/;
+/** Decode the HTML entities a browser would decode, so the guard scans what
+ *  the USER will eventually read rather than what the agent happened to type.
+ *  Without this, `/Users/lane/x` sails past every scan and then
+ *  `interactiveArtifactHtml()` — which parses with DOMParser — paints the
+ *  real absolute path into hosted browser JS. The guard and the renderer must
+ *  agree about what a string SAYS; entities are exactly where they diverge.
+ *  Numeric (decimal and hex) plus the small set of named entities that can
+ *  spell a path separator or a drive colon. */
+const NAMED_ENTITIES = {
+    sol: '/',
+    bsol: '\\',
+    colon: ':',
+    period: '.',
+    lowbar: '_',
+    quot: '"',
+    apos: "'",
+    amp: '&',
+    lt: '<',
+    gt: '>',
+};
+/* The trailing `;` is OPTIONAL for numeric entities, because browsers accept
+   it that way: `&#47Users` renders as `/Users`. A guard that required the
+   semicolon allowed exactly that string through while the renderer painted a
+   real path — found by differentially testing this function against jsdom's
+   DOMParser, which is the same parser interactiveArtifactHtml() uses. Named
+   entities keep the required `;` (that is what browsers do outside a short
+   legacy list, and dropping it would eat `&sole` in ordinary prose). */
+function decodeEntities(text) {
+    return text.replace(/&(?:(#[Xx][0-9A-Fa-f]+|#\d+);?|([A-Za-z][A-Za-z0-9]*);)/g, (whole, numericBody, namedBody) => {
+        const body = numericBody ?? namedBody ?? '';
+        if (body.startsWith('#')) {
+            const code = body[1] === 'x' || body[1] === 'X'
+                ? Number.parseInt(body.slice(2), 16)
+                : Number.parseInt(body.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        }
+        // Named entities are case-SENSITIVE in HTML: `&Colon;` is U+2237 (∷), not
+        // a colon, so lower-casing here refused text the browser never renders as
+        // a path. Exact match only.
+        const named = NAMED_ENTITIES[body];
+        return named ?? whole;
+    });
+}
+/**
+ * The first absolute local path inside `text`, or null.
+ *
+ * THE DESIGN, and why it is not the previous one. This helper used to split
+ * the text into tokens on a separator list and test each token. Three review
+ * rounds each answered a leak by adding characters to that list (`(,=;`, then
+ * `<>"'`), and the third round proved the approach is wrong rather than
+ * incomplete: a quote *inside* a path (`/'Users/lane/x`, `/Users/lane/Lane's
+ * Docs/x`) SPLIT the path into fragments, none of which starts with a root
+ * marker — so widening the separator list to catch markup simultaneously
+ * opened a hole for paths containing that markup, and the refusal message for
+ * a legitimate apostrophe path named a truncated path that did not exist.
+ * Separators cannot both be inside and outside the thing being matched.
+ *
+ * So: do not tokenise. SCAN for the path shape itself, anchored at a root
+ * marker, and let the match end where a character that cannot appear in a
+ * path appears. A path is a match, not a token. The exclusions below are the
+ * genuine false positives, tested against the same corpus as before:
+ *
+ *   - a URL's authority (`https://host/path`) is not a local path — a match
+ *     immediately preceded by `//` of a non-`file:` scheme is skipped, while
+ *     `file:///Users/…` IS reported (its body is a real local path);
+ *   - a bare drive label `A:` with no path body is a list marker;
+ *   - a single-segment `/word` (`/dashboard`, `/api/`) is a URL path — local
+ *     paths in prose always carry a second separator.
+ *
+ * Entities are decoded first (see `decodeEntities`), because the renderer
+ * decodes them too.
+ */
+/* The scan finds the path SHAPE anywhere in the text and decides what it is
+   from WHAT MATCHED, not from what precedes it.
+ *
+ * A previous round anchored this with a lookbehind excluding "characters a
+ * path cannot follow". That was the separator-list mistake one layer down: the
+ * exclusion set is itself a character list, and every character in it became a
+ * hiding place. `~/Users/lane/x`, `x./Users/lane/x` and a path embedded in a
+ * URL all leaked, and `~/…` is an entirely ordinary thing for an agent to
+ * write. A rule that says "not after these characters" can always be defeated
+ * by writing one of them first.
+ *
+ * So there is no lookbehind. Instead the two genuine false positives are
+ * excluded by structure, below:
+ *   - a repo-relative path (`web/src/App.tsx`) never starts at a root marker,
+ *     so requiring the match to BEGIN with `/`, `\\` or `C:` already excludes
+ *     it — `/src/App.tsx` inside it is only reachable mid-token, which the
+ *     single-segment and second-separator rules then handle;
+ *   - a URL's authority is recognised by its own scheme, checked explicitly.
+ *
+ * `'` and `"` are NOT body terminators — a quote inside a path is exactly the
+ * case that made the separator-splitting design leak. */
+const ABSOLUTE_PATH_SCAN = /(?:[A-Za-z]:[\\/'"]|\\\\|\/)[^\s<>`(){}\[\],;|&*?\n\r\t]*/g;
+/* The POSIX roots that actually hold a user's files. A leading `/` alone does
+   NOT make a machine path — `/api/items`, `/img/logo.png` and `/dashboard` are
+   site paths, and an agent's panel is full of them (href, src, srcset, CSS
+   url()). Refusing those would make the house style unusable and agents would
+   route around the guard, which is worse than a narrower rule. These roots are
+   the ones whose contents are private to the machine. */
+const POSIX_MACHINE_ROOT = /^\/(?:Users|home|root|var|etc|opt|srv|private|tmp|mnt|media|Volumes|Applications|Library|System|usr\/local|dev)(?:\/|$)/i;
+/** A machine path buried inside a longer match — the segment of a remote URL
+ *  that spells one (`https://host/x/Users/lane/secret.txt`). The scan's body
+ *  is greedy, so such a path never gets a match of its own; it has to be dug
+ *  out of the match that swallowed it. Rendered in front of a viewer, it
+ *  discloses exactly what bare text would. */
+function buriedMachinePath(candidate) {
+    // A Windows path can be buried too — `https://host/xC:\Users\Lane\x` — and
+    // it does not begin at a `/`, so scanning only slash positions missed it.
+    // Shape, not just a colon-slash: a drive letter, a separator, then at least
+    // one real segment. `a:/b` in a URL query is not a Windows path; the `\` or
+    // a `Users`-style segment is what makes it one. Requiring a BACKSLASH
+    // separator keeps this narrow — a forward-slash drive path (`C:/x`) inside a
+    // URL is indistinguishable from an ordinary URL fragment, and the POSIX pass
+    // below already covers the roots that matter.
+    const drive = /[A-Za-z]:\\[^\s<>"'`]+/.exec(candidate);
+    if (drive)
+        return candidate.slice(drive.index);
+    for (let at = candidate.indexOf('/'); at !== -1; at = candidate.indexOf('/', at + 1)) {
+        const tail = candidate.slice(at);
+        if (POSIX_MACHINE_ROOT.test(tail))
+            return tail;
+    }
+    return null;
+}
+export function absolutePathToken(text) {
+    const decoded = decodeEntities(text);
+    // `file:///Users/lane/x` is a local path wearing a URL. Handle it up front
+    // and by NAME, rather than leaving the generic scan to reason about where a
+    // scheme ends — that reasoning is what produced two of this function's bugs.
+    const fileUrl = /\bfile:\/\/(\/\S*)/i.exec(decoded);
+    if (fileUrl && POSIX_MACHINE_ROOT.test(fileUrl[1]))
+        return fileUrl[1];
+    ABSOLUTE_PATH_SCAN.lastIndex = 0;
+    let match;
+    while ((match = ABSOLUTE_PATH_SCAN.exec(decoded)) !== null) {
+        // Trailing wrapping punctuation belongs to the prose, not the path:
+        // `("/Users/lane/x.md")` and `see /Users/lane/x.md.` both end early.
+        const candidate = match[0].replace(/["')\].,:;]+$/, '');
+        if (!candidate || !ABSOLUTE_PATH_RE.test(candidate))
+            continue;
+        const before = decoded.slice(0, match.index);
+        // A URL: skip its authority and its ordinary path — `https://host/a/b`
+        // matches at `//host/a/b` and again at `/b`, and neither is a local path.
+        // The scheme identifies it, so look for the scheme rather than testing the
+        // character immediately before. (`file:` never reaches here; it is handled
+        // by name above.)
+        //
+        // EXCEPT when the URL's path is itself rooted at a machine root. A remote
+        // URL spelling `…/x/Users/lane/private/secret.txt` puts that path in front
+        // of a viewer just as plainly as bare text does, and the contract is about
+        // the string reaching hosted browser JS, not about how it got there. A
+        // false alarm costs the agent one retry; a leak is permanent, so this errs
+        // toward refusing.
+        if (/([A-Za-z][A-Za-z0-9+.-]*):\/\/\S*$/.test(before) && !POSIX_MACHINE_ROOT.test(candidate)) {
+            const buried = buriedMachinePath(candidate);
+            if (buried)
+                return buried;
+            continue;
+        }
+        // `https://host/x` also matches AT the scheme's own `s://…`, which reads
+        // as a one-letter drive. A real drive letter is followed by a separator
+        // and then a path segment — never by `//`. Before discarding it, check
+        // whether a machine root is buried INSIDE: the scan's body is greedy, so
+        // `s://example.com/x/Users/lane/x` is one match and the `/Users/…` inside
+        // it never gets a match of its own. A remote URL spelling a machine path
+        // discloses it to a viewer just as plainly as bare text does.
+        if (/^[A-Za-z]:\/\//.test(candidate)) {
+            const buried = buriedMachinePath(candidate);
+            if (buried)
+                return buried;
+            continue;
+        }
+        // A CONTINUATION of a relative path: `web/src/App.tsx` matches at
+        // `/src/App.tsx`, which is not a local path — the token it belongs to
+        // began with a bare word. Walk back to the start of the whole token and
+        // ask what IT begins with. This is deliberately not "is the preceding
+        // character in a set": `~/Users/lane/x` and `x./Users/lane/x` both have a
+        // path-ish character before the slash, and both DO carry a real absolute
+        // path, so a character test leaks them. Reading the token's own first
+        // character answers correctly in every one of those cases.
+        // The token runs back to whitespace OR a markup boundary (`<>"'=`) — a
+        // quote or a tag bracket ends the token even though it is not whitespace,
+        // which is what lets `class="mono">/Users/…` be seen as a path rather than
+        // as the tail of the token `class`.
+        // Only a token that is itself a plausible RELATIVE PATH suppresses the
+        // match — `web/src` in `web/src/App.tsx`. A bare word (`x.`), a number
+        // (`1`), or anything not shaped like a path segment does not, because
+        // `x./Users/lane/x` and `1/Users/lane/x` still carry a real absolute path.
+        const tokenStart = /([^\s<>"'=]+)$/.exec(before)?.[1] ?? '';
+        if (/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9._-]+)*\/?$/.test(tokenStart)
+            && tokenStart.includes('/')
+            && !POSIX_MACHINE_ROOT.test(candidate))
+            continue;
+        if (/^[A-Za-z]:$/.test(candidate))
+            continue;
+        // A POSIX candidate is only a MACHINE path if it starts at a real root.
+        // `/img/x.png`, `/api/items`, `/dashboard` and `2026/07/31` are site paths
+        // and dates — they are not local paths, they are the ordinary content of
+        // an agent's panel (CSS urls, hrefs, srcset), and refusing them makes the
+        // house style unusable. The roots below are the ones that actually carry a
+        // user's files; a path under any of them is refused, everything else is
+        // left alone. Windows (`C:\…`) and UNC (`\\host\share`) are unambiguous by
+        // construction and are not filtered here.
+        // Strip a quote sitting immediately after the root before classifying:
+        // `/'Users/lane/x` is the separator-design leak, and the root test must
+        // see `/Users/…` to recognise it.
+        const rooted = candidate.replace(/^([\\/]+)["']/, '$1');
+        if (rooted.startsWith('/') && !POSIX_MACHINE_ROOT.test(rooted))
+            continue;
+        return candidate;
+    }
+    return null;
+}