@patchstack/connect 0.3.30 → 0.3.31

package/AGENT-INSTALL.md

@@ -21,12 +21,15 @@ Every command at a glance — what it does, whether it reads your source, what i
 | `login` | Recover a lost credential for an existing site: print an owner-approval link and poll (10 min). Approving **rotates** the credential. Not usable in CI. | No | New credential into `.patchstackrc.local.json` on approval | Device-code request + approval poll |
 | `uninstall` | Signal Patchstack that the package is being removed: an unclaimed record is deleted, a claimed one is flagged. Does **not** touch local files. | No | Nothing local | Removal signal |
 
-Only `map` reads your source, and only `map --upload` sends anything derived from it. `scan` transmits nothing but package names + versions — never source code, env var values, file paths, or git history.
+Only `map` reads your source, and only `map --upload` sends anything derived from it. `scan` transmits nothing but package names + versions — never source code, env var values, file paths, or git history. `scan --install-paths` additionally sends where each package sits in the dependency tree; it is off unless you pass it.
 
 ## Package and command behavior
 
 - Package: [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), MIT-licensed, source at https://github.com/patchstack/connect. `npm view @patchstack/connect` shows the live registry metadata.
-- **What is sent to Patchstack is the dependency list only** — read from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — package names + versions, for vulnerability matching. No source code, no env var values, no file paths, no git history is ever transmitted. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
+- **What is sent to Patchstack is the dependency list only** — read from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — package names + versions, for vulnerability matching. No source code, no env var values, no file paths, no git history is ever transmitted.
+  - **`scan --install-paths` is the one exception, and it is opt-in.** It adds where each package sits in the dependency tree — repo-relative paths made of `node_modules` segments, plus a workspace directory name when a workspace pins its own copy. They are read from the lockfile's own keys or from the `node_modules` walk, **never from your source tree**: no path to a file you wrote is sent by either form of `scan`.
+  - Why it exists: the same package is routinely installed twice at different versions, and without the locations an advisory affecting only one of them cannot be matched to the copy your code actually loads. Node resolves an import by walking up from the importing file, so the location is what distinguishes "you are running the vulnerable copy" from "the vulnerable copy is installed but nothing reaches it". Absent them, every installed version has to be treated as if the app used it — warnings about code you never call, and protection rules pinned to routes that run the safe copy.
+  - Why it is off by default: it widens what leaves the machine, so it is your explicit choice and not a consequence of upgrading the package. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
 - **One command reads source files:** `map` (see below) parses your server source to report your app's attack surface. It runs only when you invoke it and prints to stdout. It transmits nothing unless you explicitly pass `--upload`, which sends that description of your app's structure to your own site's Patchstack endpoint — never source code, and never without that flag. No other command reads source (`protect` writes guard files but does not analyze your code).
 - **`scan` makes up to two source edits, both in the project's root shell:** the disclosure widget's `<script>` tag, and the production marker. Neither runs on `--dry-run`, both are idempotent, both leave a pre-existing manual install untouched, and `"widget": false` in `.patchstackrc.json` disables both.
   - The **widget tag** goes in the root HTML shell — the first of `index.html`, `public/index.html`, or `src/app.html` that exists — and only after a successful post, because it carries the site UUID.

package/README.md

@@ -216,6 +216,7 @@ Lower-level pieces are also exported: `scanLockfile`, `buildWirePayload`, `postM
 ```json
 {
   "ecosystem": "npm",
+  "installPathsComplete": false,
   "packages": [
     { "name": "axios",  "version": "1.6.0" },
     { "name": "lodash", "version": "4.17.15" },
@@ -224,7 +225,21 @@ Lower-level pieces are also exported: `scanLockfile`, `buildWirePayload`, `postM
 }
 ```
 
-That's the entire payload. No source code, no environment variable values, no file paths — just the package names and versions from your lockfile. (The `map` command reads source files locally to report your attack surface; it transmits nothing unless you pass `--upload`, which sends that structural description — route paths, parameter names, the dependency behind each sink, and file/line locations, never file contents — to your own site's endpoint so rules can be pinned to your real parameter names.) Duplicate names with different versions are preserved so transitive vulnerabilities aren't missed. (`mark-build` separately stamps built HTML with a stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL` — never their values.)
+That's the entire payload. No source code, no environment variable values, no file paths — just the package names and versions from your lockfile.
+
+### `scan --install-paths` (opt-in)
+
+Pass it and each entry also carries where that version is installed:
+
+```json
+{ "name": "lodash", "version": "4.17.15", "paths": ["apps/api/node_modules/lodash"] }
+```
+
+Why you might want it: the two `lodash` entries above are not a contrived example — the same package is routinely installed twice at different versions. An advisory affecting only `4.17.15` cannot otherwise be matched to the copy your code actually loads. Node resolves an import by walking up from the importing file, so the location is what separates "you are running the vulnerable copy" from "the vulnerable copy is installed but nothing reaches it". Without it every installed version has to be treated as if the app used it — warnings about code you never call, and protection rules pinned to routes that run the safe copy.
+
+These are repo-relative locations built from `node_modules` segments, plus a workspace directory name when a workspace pins its own copy. They come from the lockfile's own keys or from the `node_modules` walk — **never from your source tree**. No path to a file you wrote is sent by either form of `scan`.
+
+`installPathsComplete` says whether the set is total. It is `false` without the flag, and `false` with it whenever the source cannot supply locations — a `yarn.lock` is flat because hoisting is decided at install time, and a v1 `package-lock.json` records the dependency graph rather than the installed tree. Whenever it is `false`, a missing `paths` means **"not recorded"**, never "not installed there". (The `map` command reads source files locally to report your attack surface; it transmits nothing unless you pass `--upload`, which sends that structural description — route paths, parameter names, the dependency behind each sink, and file/line locations, never file contents — to your own site's endpoint so rules can be pinned to your real parameter names.) Duplicate names with different versions are preserved so transitive vulnerabilities aren't missed. (`mark-build` separately stamps built HTML with a stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL` — never their values.)
 
 ## Supported lockfiles
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "fs";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -330,7 +330,7 @@ async function walkNodeModules(cwd) {
     seen.set(await realpath(cwd), -1);
   } catch {
   }
-  return dedupeByShallowest(await walk(root, 0, seen));
+  return dedupeByShallowest(await walk(root, 0, seen, cwd));
 }
 function dedupeByShallowest(found) {
   const best = /* @__PURE__ */ new Map();
@@ -341,7 +341,7 @@ function dedupeByShallowest(found) {
   return [...best.values()].map(({ entry }) => entry);
 }
 var CONCURRENCY = 32;
-async function walk(dir, depth, seen) {
+async function walk(dir, depth, seen, root) {
   let names;
   try {
     names = await readdir(dir);
@@ -353,7 +353,7 @@ async function walk(dir, depth, seen) {
     const fullPath = path3.join(dir, name);
     const resolved = await claim(fullPath, seen, depth);
     if (resolved === null) return [];
-    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen);
+    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen, root);
     if (name.startsWith("@")) {
       let subNames;
       try {
@@ -366,16 +366,16 @@ async function walk(dir, depth, seen) {
         const scopedDir = path3.join(fullPath, sub);
         const scopedReal = await claim(scopedDir, seen, depth);
         if (scopedReal === null) return [];
-        return packageAndNested(scopedDir, scopedReal, depth, seen);
+        return packageAndNested(scopedDir, scopedReal, depth, seen, root);
       });
       return scoped.flat();
     }
-    return packageAndNested(fullPath, resolved, depth, seen);
+    return packageAndNested(fullPath, resolved, depth, seen, root);
   });
   return perEntry.flat();
 }
-async function packageAndNested(pkgDir, resolved, depth, seen) {
-  const [own, nested] = await Promise.all([readPackage(pkgDir, depth), walkNested(pkgDir, depth, seen)]);
+async function packageAndNested(pkgDir, resolved, depth, seen, root) {
+  const [own, nested] = await Promise.all([readPackage(pkgDir, depth, root), walkNested(pkgDir, depth, seen, root)]);
   return own === null ? nested : [{ entry: own, realpath: resolved, depth }, ...nested];
 }
 async function mapLimit(items, fn) {
@@ -390,7 +390,10 @@ async function mapLimit(items, fn) {
   await Promise.all(workers);
   return results;
 }
-async function readPackage(pkgDir, depth) {
+function installLocation(root, pkgDir, impl = path3) {
+  return impl.relative(root, pkgDir).split(impl.sep).join("/");
+}
+async function readPackage(pkgDir, depth, root) {
   let raw;
   try {
     raw = await readFile4(path3.join(pkgDir, "package.json"), "utf8");
@@ -409,14 +412,14 @@ async function readPackage(pkgDir, depth) {
   if (typeof parsed.version !== "string" || parsed.version.length === 0) {
     return null;
   }
-  return { name: parsed.name, version: parsed.version, direct: depth === 0 };
+  return { name: parsed.name, version: parsed.version, path: installLocation(root, pkgDir), direct: depth === 0 };
 }
-async function walkNested(pkgDir, depth, seen) {
+async function walkNested(pkgDir, depth, seen, root) {
   const nested = path3.join(pkgDir, "node_modules");
   if (await claim(nested, seen, depth + 1) === null) {
     return [];
   }
-  return walk(nested, depth + 1, seen);
+  return walk(nested, depth + 1, seen, root);
 }
 async function claim(dir, seen, depth) {
   let resolved;
@@ -1059,21 +1062,33 @@ async function exists(filePath) {
 }
 
 // src/normalize.ts
-function buildWirePayload(manifest) {
+function buildWirePayload(manifest, options = {}) {
+  const withPaths = options.installPaths === true;
   const seen = /* @__PURE__ */ new Map();
   const wirePackages = [];
+  const byIdentity = /* @__PURE__ */ new Map();
+  let entriesWithoutPath = 0;
   for (const entry of manifest.packages) {
+    const identity = `${entry.name}@${entry.version}`;
+    const location = withPaths && entry.path !== void 0 && entry.path !== "" ? entry.path : void 0;
+    if (location === void 0) entriesWithoutPath++;
+    const existing = byIdentity.get(identity);
+    if (existing) {
+      if (location !== void 0) addPath(existing, location);
+      continue;
+    }
     const versions = seen.get(entry.name);
     if (versions) {
-      if (versions.has(entry.version)) {
-        continue;
-      }
       versions.add(entry.version);
     } else {
       seen.set(entry.name, /* @__PURE__ */ new Set([entry.version]));
     }
-    wirePackages.push({ name: entry.name, version: entry.version });
+    const wire6 = { name: entry.name, version: entry.version };
+    if (location !== void 0) addPath(wire6, location);
+    byIdentity.set(identity, wire6);
+    wirePackages.push(wire6);
   }
+  for (const wire6 of wirePackages) wire6.paths?.sort();
   wirePackages.sort((a, b) => {
     if (a.name === b.name) {
       return compareVersions(a.version, b.version);
@@ -1087,7 +1102,18 @@ function buildWirePayload(manifest) {
     }
   }
   return {
-    payload: { ecosystem: manifest.ecosystem, packages: wirePackages },
+    payload: {
+      ecosystem: manifest.ecosystem,
+      packages: wirePackages,
+      // Every entry had a location, so a missing path anywhere means the package is not installed there.
+      // One entry without one forfeits that for the whole payload: a consumer reading a short `paths` has
+      // no way to tell which entry was the incomplete one.
+      //
+      // No separate check for "locations were not requested": with them off every entry counts as without
+      // one, so this is already false — which is the default, and the safe direction. An explicit
+      // `withPaths &&` here was a guard no test could distinguish from its absence.
+      installPathsComplete: entriesWithoutPath === 0 && manifest.packages.length > 0
+    },
     stats: {
       uniqueNames: seen.size,
       duplicateNames,
@@ -1095,6 +1121,10 @@ function buildWirePayload(manifest) {
     }
   };
 }
+function addPath(wire6, installPath) {
+  if (wire6.paths === void 0) wire6.paths = [installPath];
+  else if (!wire6.paths.includes(installPath)) wire6.paths.push(installPath);
+}
 function compareVersions(a, b) {
   if (a === b) {
     return 0;
@@ -4078,6 +4108,9 @@ async function login(config, onPrompt, deps = {}) {
   return waitForApproval(config, started.pending, deps);
 }
 
+// src/map-command.ts
+import { writeFileSync as writeFileSync8 } from "fs";
+
 // src/map/ts-loader.ts
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
@@ -4485,7 +4518,30 @@ var SKIP_DIRS2 = /* @__PURE__ */ new Set([
   "temp",
   "__pycache__"
 ]);
-function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ new Set(), stats = { discovered: 0, unwalked: 0 }) {
+var SKIP_IS_DEFINITIONAL = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+var PROBE_BUDGET = 4096;
+function probeForSource(dir, budget) {
+  let entries;
+  try {
+    entries = readdirSync5(dir, { withFileTypes: true });
+  } catch {
+    return "unknown";
+  }
+  const dirs = [];
+  for (const e of entries) {
+    if (budget.left-- <= 0) return "unknown";
+    if (e.isDirectory()) {
+      if (!SKIP_IS_DEFINITIONAL.has(e.name)) dirs.push(join13(dir, e.name));
+    } else if (isSourceFile(e.name)) return true;
+    else if (e.isSymbolicLink()) return "unknown";
+  }
+  for (const sub of dirs) {
+    const found = probeForSource(sub, budget);
+    if (found !== false) return found;
+  }
+  return false;
+}
+function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ new Set(), stats = { discovered: 0, unwalked: 0, skippedWithSource: [], skippedUnknown: 0 }, probeBudget = { left: PROBE_BUDGET }) {
   let key;
   try {
     key = realpathSync(dir);
@@ -4508,9 +4564,18 @@ function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ ne
   }
   entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
   for (const e of entries) {
-    if (SKIP_DIRS2.has(e.name) || e.name.startsWith(".") && e.name !== ".") continue;
+    if (SKIP_DIRS2.has(e.name) || e.name.startsWith(".") && e.name !== ".") {
+      const probeable = !SKIP_IS_DEFINITIONAL.has(e.name);
+      if (probeable && !e.isDirectory() && e.isSymbolicLink()) stats.skippedUnknown++;
+      else if (probeable && e.isDirectory()) {
+        const held = probeForSource(join13(dir, e.name), probeBudget);
+        if (held === true) stats.skippedWithSource.push(join13(dir, e.name));
+        else if (held === "unknown") stats.skippedUnknown++;
+      }
+      continue;
+    }
     const full = join13(dir, e.name);
-    if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats);
+    if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
     else if (e.isSymbolicLink()) {
       let st, real;
       try {
@@ -4524,7 +4589,7 @@ function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ ne
         if (st.isDirectory() || isSourceFile(e.name)) stats.unwalked++;
         continue;
       }
-      if (st.isDirectory()) collectSources(full, boundary, opts, out, seen, stats);
+      if (st.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
       else if (st.isFile() && isSourceFile(e.name)) {
         out.push(full);
         stats.discovered++;
@@ -5349,7 +5414,7 @@ function zodShape(node, ts) {
   }
   return shape;
 }
-var REQ_SOURCES = ["body", "query", "params"];
+var REQ_SOURCES = ["body", "query", "params", "headers", "cookies", "files"];
 function requestMemberAccesses(params, body, ts, opts = {}) {
   if (!body) return [];
   const out = /* @__PURE__ */ new Map();
@@ -5386,6 +5451,12 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
     if (ts.isPropertyAccessExpression(n) && isReqSourceExpr(n.expression)) {
       record(n.name.text, sourceOfExpr(n.expression));
     }
+    if (ts.isElementAccessExpression(n) && isReqSourceExpr(n.expression) && n.argumentExpression && ts.isStringLiteral(n.argumentExpression)) {
+      record(n.argumentExpression.text, sourceOfExpr(n.expression));
+    }
+    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "get" && isReqSourceExpr(n.expression.expression) && n.arguments.length === 1 && n.arguments[0] && ts.isStringLiteral(n.arguments[0])) {
+      record(n.arguments[0].text, sourceOfExpr(n.expression.expression));
+    }
     if (ts.isVariableDeclaration(n) && n.initializer) {
       const init = unwrap(n.initializer);
       if (ts.isIdentifier(n.name) && isBodyReadCall(n.initializer)) sourceNames.set(n.name.text, bodyReadSource(n.initializer));
@@ -5410,9 +5481,8 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
   function sourceOfExpr(e) {
     if (isPayloadExpr(e)) return "server-fn-data";
     if (ts.isPropertyAccessExpression(e)) {
-      if (e.name.text === "query") return "query";
-      if (e.name.text === "params") return "route-param";
-      if (e.name.text === "body") return "body";
+      const named = namespaceSource(e.name.text);
+      if (REQ_SOURCES.includes(e.name.text)) return named;
     }
     if (ts.isIdentifier(e)) {
       const recorded = sourceNames.get(e.text);
@@ -5423,6 +5493,9 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
   function namespaceSource(key) {
     if (key === "query") return "query";
     if (key === "params") return "route-param";
+    if (key === "headers") return "header";
+    if (key === "cookies") return "cookie";
+    if (key === "files") return "file";
     return "body";
   }
   function bodyReadSource(init) {
@@ -5437,6 +5510,9 @@ function spaceOfKey(key) {
   if (key === "params") return "route-param";
   if (key === "body") return "post";
   if (key === "data" || key === "input" || key === "payload") return "post";
+  if (key === "headers") return "server";
+  if (key === "cookies") return "cookie";
+  if (key === "files") return "files";
   return void 0;
 }
 function linkedFlows(body, params, inputs, sinks, ts) {
@@ -6216,7 +6292,7 @@ async function extractInputMap(cwd, ts, options = {}) {
   } catch {
   }
   const graph = createModuleGraph(ts, { cwd, boundary, followOutside: options.followSymlinks });
-  const stats = { discovered: 0, unwalked: 0 };
+  const stats = { discovered: 0, unwalked: 0, skippedWithSource: [], skippedUnknown: 0 };
   const files = collectSources(cwd, boundary, { followOutside: options.followSymlinks }, [], /* @__PURE__ */ new Set(), stats);
   const imports = createImportInventory(readPathAliases(cwd));
   const invocations = createInvocationInventory();
@@ -6321,19 +6397,31 @@ async function extractInputMap(cwd, ts, options = {}) {
   if (endpoints.length === 0) notes.push("No recognized server-side entry points found under the analyzed roots.");
   const importList = imports.list();
   const unmodelled = importList.filter((d) => d.recognizedSinkKinds.length === 0).length;
+  const skippedDirsWithSource = stats.skippedWithSource.map((d) => relative4(cwd, d));
   const importCoverageGaps = {
     unreadableFiles: failed.length,
     unscannableFiles: importScanFailures,
     unwalkedPaths: stats.unwalked,
-    unresolvableImports
+    unresolvableImports,
+    // A directory skipped by NAME that turned out to hold source. It moved no other counter, so before
+    // this an app whose server lived under `vendor/` was indistinguishable from one with no such
+    // directory — and the inventory still claimed to be complete.
+    skippedDirsWithSource,
+    skippedDirsUnsettled: stats.skippedUnknown
   };
-  const environmentalGaps = failed.length + importScanFailures + stats.unwalked;
+  const environmentalGaps = failed.length + importScanFailures + stats.unwalked + stats.skippedWithSource.length + stats.skippedUnknown;
   const importsComplete = environmentalGaps === 0 && unresolvableImports === 0;
   notes.push("`imports` lists every package the app imports, from ALL source files \u2014 not only files holding an entry point. Absence of a SINK for a package is never evidence; absence of the PACKAGE is evidence only when coverage.importsComplete is true.");
   notes.push(`${unmodelled} of ${importList.length} imported package(s) have no recognized sink family (recognizedSinkKinds: []). The extractor models a small set of API families, so for those packages it cannot tell whether input reaches them: a vulnerability in one must stay "needs review" and can never be closed as unreachable using this map.`);
   if (environmentalGaps > 0) {
     notes.push(`The import inventory is INCOMPLETE: ${failed.length} file(s) could not be read, ${importScanFailures} could not be scanned, and ${stats.unwalked} path(s) could not be walked at all (unreadable directory, broken link, or a symlink leaving the project). A package may therefore be imported without appearing in \`imports\`. Do not read a package's absence as "not imported" while coverage.importsComplete is false.`);
   }
+  if (stats.skippedWithSource.length > 0) {
+    notes.push(`${stats.skippedWithSource.length} director(ies) skipped by name hold source that was NOT analyzed: ${skippedDirsWithSource.slice(0, 10).join(", ")}${skippedDirsWithSource.length > 10 ? ", \u2026" : ""}. The walk excludes these names because they are usually generated or vendored, which is a guess about where app source lives \u2014 and here the guess was wrong. Code in them can import, and serve, anything. Point the scan at the directory, or move the app source out of it, before reading any package's absence as evidence.`);
+  }
+  if (stats.skippedUnknown > 0) {
+    notes.push(`${stats.skippedUnknown} skipped director(ies) could not be settled either way \u2014 the probe for source hit its budget or the directory could not be read. Counted against completeness deliberately: "we stopped looking" is not the same answer as "nothing there".`);
+  }
   if (unresolvableImports > 0) {
     notes.push(`The import inventory is INCOMPLETE for a reason no re-run can fix: ${unresolvableImports} import(s) do not name a resolvable module \u2014 either the specifier is computed at runtime (\`require(REGISTRY[kind])\`) or the loader itself was aliased (\`const r = require\`), so which package is loaded is not knowable from the source. Those imports appear NOWHERE in \`imports\` \u2014 not as an unresolved entry, simply absent \u2014 so a package's absence is not evidence of it being unused. This is a property of the application's code, not a scan failure. Reported conservatively: an aliased loader counts even if every call through it uses a literal.`);
   }
@@ -6416,8 +6504,88 @@ async function buildInputMap(cwd, options = {}) {
   return { map };
 }
 
+// src/flags.ts
+function getStringFlag(flags, name) {
+  const value = flags.get(name);
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/map-command.ts
+async function runMap(flags) {
+  const cwd = getStringFlag(flags, "dir") ?? process.cwd();
+  const { map, error } = await buildInputMap(cwd, {
+    followSymlinks: flags.get("follow-symlinks") === true
+  });
+  if (!map) {
+    console.error(`patchstack: ${error}`);
+    return 1;
+  }
+  const inputs = map.endpoints.reduce((n, e) => n + e.inputs.length, 0);
+  const sinks = map.endpoints.reduce((n, e) => n + e.sinks.length, 0);
+  const proven = map.endpoints.reduce((n, e) => n + e.flows.filter((f) => isProvenFlow(f.confidence)).length, 0);
+  const c = map.coverage;
+  console.error(
+    `patchstack: ${map.endpoints.length} entry point(s), ${inputs} input(s), ${sinks} sink(s), ${proven} proven input\u2192sink flow(s) [${map.framework}].`
+  );
+  console.error(
+    // All three buckets, explicitly: "6/66 parsed" reads as "91% unanalysed" when the other 60 files
+    // simply contain no server entry point (most of a project is client code). Only `skipped` is a
+    // failure to analyse.
+    `patchstack: ${c.filesDiscovered} file(s) found \u2014 ${c.filesParsed} analysed, ${c.filesPreFiltered} skipped (no server entry point)` + (c.filesSkipped ? `, ${c.filesSkipped} could not be analysed` : "") + `. DETECTED surface only \u2014 static analysis is best-effort; every flow carries the tier it was established at ("exact-local" and "transformed-local" are proven; "imported", "heuristic" and "unknown" are not).`
+  );
+  const invoked = map.apiInvocations ?? [];
+  if (invoked.length > 0) {
+    const c2 = map.coverage;
+    const dependency = c2.callsDependency ?? 0;
+    const ambiguous = c2.callsAmbiguous ?? 0;
+    const denominator = dependency + ambiguous;
+    const quality = denominator > 0 ? Math.round(100 * dependency / denominator) : 100;
+    console.error(
+      `patchstack: ${invoked.length} dependency API call(s) resolved across ${new Set(invoked.map((i) => i.package)).size} package(s) from ${c2.callsTotal ?? 0} call site(s) \u2014 ${quality}% of dependency-candidate receivers resolved (${c2.callsLocal ?? 0} local, ${ambiguous} ambiguous). Positive evidence only: absence here never means an API is not called.`
+    );
+  }
+  const imported = map.imports ?? [];
+  if (imported.length > 0) {
+    const unmodelled = imported.filter((d) => d.recognizedSinkKinds.length === 0).length;
+    console.error(
+      `patchstack: ${imported.length} package(s) imported \u2014 ${unmodelled} with no recognized sink family, so a vulnerability in those cannot be judged reachable or unreachable from this map.`
+    );
+  }
+  const json = JSON.stringify(map, null, 2);
+  const out = getStringFlag(flags, "out");
+  if (out) {
+    writeFileSync8(out, json);
+    console.error(`patchstack: wrote ${out}`);
+  } else if (flags.get("upload") !== true) {
+    console.log(json);
+  }
+  if (flags.get("upload") === true) {
+    if (map.endpoints.length === 0) {
+      console.error(
+        "patchstack: no server entry points were recognized \u2014 uploading the import inventory and coverage notes anyway, so a vulnerability can still be judged imported or not. Nothing here can decide whether a request reaches it."
+      );
+    }
+    const config = await resolveConfig({
+      cwd,
+      cliSiteUuid: getStringFlag(flags, "site-uuid"),
+      cliEndpoint: getStringFlag(flags, "endpoint")
+    });
+    const outcome = await postInputMap(config, map);
+    if (outcome.result === "stored") {
+      console.error(`patchstack: uploaded the attack surface (revision ${outcome.revision}).`);
+    } else if (outcome.result === "unchanged") {
+      console.error(`patchstack: attack surface unchanged since revision ${outcome.revision} \u2014 nothing to store.`);
+    } else if (outcome.result === "skipped") {
+      console.error(`patchstack: did not upload the attack surface \u2014 ${outcome.message}`);
+    } else {
+      console.error(`patchstack: could not upload the attack surface \u2014 ${outcome.message}`);
+    }
+  }
+  return 0;
+}
+
 // src/setup.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
 import path11 from "path";
 var SCAN_COMMAND = "patchstack-connect scan";
 var MARK_BUILD_COMMAND = "patchstack-connect mark-build";
@@ -6486,7 +6654,7 @@ function wireBuildScripts(cwd, packageManager) {
   const indentMatch = raw.match(/^[\t ]+(?=")/m)?.[0];
   const indent = indentMatch?.includes("	") ? "	" : indentMatch?.length ?? 2;
   const trailingNewline = raw.endsWith("\n") ? "\n" : "";
-  writeFileSync8(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
+  writeFileSync9(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
   if (build === void 0 || build.trim().length === 0) {
     return {
       changed: true,
@@ -6587,6 +6755,11 @@ Options (for scan, setup, status, and uninstall):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
   --dry-run               (scan only) Show the payload without posting
+  --install-paths         (scan only) Also send where each package is installed
+                          in the dependency tree (node_modules/lodash, and the
+                          same under a workspace that pins its own copy), so an
+                          advisory can be matched to the copy your code actually
+                          loads. Off by default; never source file paths
 
 Options (for mark-build):
   --dir <path>            Build output directory (default: auto-detect
@@ -6651,10 +6824,6 @@ function parseArgs(argv) {
     flags
   };
 }
-function getStringFlag(flags, name) {
-  const value = flags.get(name);
-  return typeof value === "string" ? value : void 0;
-}
 async function runInit(args) {
   const uuid = args.positional[0];
   if (!uuid) {
@@ -6752,77 +6921,6 @@ async function runLogin(args) {
 `);
   return 1;
 }
-async function runMap(args) {
-  const cwd = getStringFlag(args.flags, "dir") ?? process.cwd();
-  const { map, error } = await buildInputMap(cwd, {
-    followSymlinks: args.flags.get("follow-symlinks") === true
-  });
-  if (!map) {
-    console.error(`patchstack: ${error}`);
-    return 1;
-  }
-  const inputs = map.endpoints.reduce((n, e) => n + e.inputs.length, 0);
-  const sinks = map.endpoints.reduce((n, e) => n + e.sinks.length, 0);
-  const proven = map.endpoints.reduce((n, e) => n + e.flows.filter((f) => isProvenFlow(f.confidence)).length, 0);
-  const c = map.coverage;
-  console.error(
-    `patchstack: ${map.endpoints.length} entry point(s), ${inputs} input(s), ${sinks} sink(s), ${proven} proven input\u2192sink flow(s) [${map.framework}].`
-  );
-  console.error(
-    // All three buckets, explicitly: "6/66 parsed" reads as "91% unanalysed" when the other 60 files
-    // simply contain no server entry point (most of a project is client code). Only `skipped` is a
-    // failure to analyse.
-    `patchstack: ${c.filesDiscovered} file(s) found \u2014 ${c.filesParsed} analysed, ${c.filesPreFiltered} skipped (no server entry point)` + (c.filesSkipped ? `, ${c.filesSkipped} could not be analysed` : "") + `. DETECTED surface only \u2014 static analysis is best-effort; every flow carries the tier it was established at ("exact-local" and "transformed-local" are proven; "imported", "heuristic" and "unknown" are not).`
-  );
-  const invoked = map.apiInvocations ?? [];
-  if (invoked.length > 0) {
-    const c2 = map.coverage;
-    const dependency = c2.callsDependency ?? 0;
-    const ambiguous = c2.callsAmbiguous ?? 0;
-    const denominator = dependency + ambiguous;
-    const quality = denominator > 0 ? Math.round(100 * dependency / denominator) : 100;
-    console.error(
-      `patchstack: ${invoked.length} dependency API call(s) resolved across ${new Set(invoked.map((i) => i.package)).size} package(s) from ${c2.callsTotal ?? 0} call site(s) \u2014 ${quality}% of dependency-candidate receivers resolved (${c2.callsLocal ?? 0} local, ${ambiguous} ambiguous). Positive evidence only: absence here never means an API is not called.`
-    );
-  }
-  const imported = map.imports ?? [];
-  if (imported.length > 0) {
-    const unmodelled = imported.filter((d) => d.recognizedSinkKinds.length === 0).length;
-    console.error(
-      `patchstack: ${imported.length} package(s) imported \u2014 ${unmodelled} with no recognized sink family, so a vulnerability in those cannot be judged reachable or unreachable from this map.`
-    );
-  }
-  const json = JSON.stringify(map, null, 2);
-  const out = getStringFlag(args.flags, "out");
-  if (out) {
-    writeFileSync9(out, json);
-    console.error(`patchstack: wrote ${out}`);
-  } else if (args.flags.get("upload") !== true) {
-    console.log(json);
-  }
-  if (args.flags.get("upload") === true) {
-    if (map.endpoints.length === 0) {
-      console.error("patchstack: nothing to upload \u2014 no server entry points were detected.");
-      return 0;
-    }
-    const config = await resolveConfig({
-      cwd,
-      cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
-      cliEndpoint: getStringFlag(args.flags, "endpoint")
-    });
-    const outcome = await postInputMap(config, map);
-    if (outcome.result === "stored") {
-      console.error(`patchstack: uploaded the attack surface (revision ${outcome.revision}).`);
-    } else if (outcome.result === "unchanged") {
-      console.error(`patchstack: attack surface unchanged since revision ${outcome.revision} \u2014 nothing to store.`);
-    } else if (outcome.result === "skipped") {
-      console.error(`patchstack: did not upload the attack surface \u2014 ${outcome.message}`);
-    } else {
-      console.error(`patchstack: could not upload the attack surface \u2014 ${outcome.message}`);
-    }
-  }
-  return 0;
-}
 async function runScan(args, options = {}) {
   const dryRun = args.flags.get("dry-run") === true;
   const config = await resolveConfig({
@@ -6834,10 +6932,17 @@ async function runScan(args, options = {}) {
   for (const warning of manifest.warnings ?? []) {
     console.warn(`patchstack: ${warning}`);
   }
-  const { payload, stats } = buildWirePayload(manifest);
+  const installPaths = args.flags.get("install-paths") === true;
+  const { payload, stats } = buildWirePayload(manifest, { installPaths });
   console.log(
     `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names (${manifest.ecosystem} ecosystem).`
   );
+  if (installPaths) {
+    const located = payload.packages.filter((pkg) => pkg.paths !== void 0).length;
+    console.log(
+      payload.installPathsComplete ? `Including each package's install location in the dependency tree (--install-paths), for all ${located}.` : `Including install locations (--install-paths), for ${located} of ${payload.packages.length} \u2014 this lockfile format does not record them for the rest, which will be reported as "not recorded" rather than "not installed there".`
+    );
+  }
   console.log(
     `Reporting under the ${config.environment} environment (override with PATCHSTACK_ENVIRONMENT).`
   );
@@ -7330,7 +7435,7 @@ async function runMarkBuild(args) {
       after = ensured.html;
     }
     if (after !== before) {
-      writeFileSync9(file, after);
+      writeFileSync10(file, after);
       marked += 1;
     }
   }
@@ -7368,7 +7473,7 @@ async function main() {
     case "setup":
       return runSetup(args);
     case "map":
-      return runMap(args);
+      return runMap(args.flags);
     case "login":
       return runLogin(args);
     default: