@vaultcompass/vault-guard-core 1.4.4 → 1.4.6

package/README.md

@@ -68,6 +68,7 @@ Full rule reference: [docs/RULES.md](https://github.com/vaultcompasshq/vault-gua
 | `fingerprintForMatch` | Baseline fingerprinting (no raw secrets stored) |
 | `scanTextFileAsync` / `scanTextFileSync` | Stream-aware file scanning |
 | `getGitStagedFilePaths` | Staged-file enumeration for hooks |
+| `getGitWorkTreeRoot` | Repository root for a directory, the base every staged path resolves against |
 
 ## Prefer the CLI?
 

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export * from './scan-output';
 export * from './diagnostics';
 export { shannonEntropy, DEFAULT_ENTROPY_THRESHOLD } from './utils/entropy';
 export { isPlaceholderSecret, isNonSecretConnectionString, isSampleJwt, isRedactedTemplateValue, isEnvVarNameToken, isCodeIdentifierReference, isPasswordHash, isPemHeaderWithoutBody } from './utils/placeholder';
-export { getGitStagedFilePaths, readGitIndexFile, isInsideGitWorkTree } from './utils/git-utils';
+export { getGitStagedFilePaths, readGitIndexFile, isInsideGitWorkTree, getGitWorkTreeRoot, } from './utils/git-utils';
 export { validateRegexSafety, validateRegexLength, mapRegexSafetyReasonToDiagnosticCode, mapPatternRejectionReasonToDiagnosticCode, REGEX_REASON_TO_DIAGNOSTIC_CODE, REGEX_MAX_LENGTH, REGEX_MAX_QUANTIFIERS, } from './utils/regex-safety';
 export { scanTextFileAsync, scanTextFileSync } from './utils/scan-file';
 export { applyPathAwareSeverity, isTestFilePath, isLocalePath } from './utils/path-severity';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveFailOn = exports.countBlockingMatches = exports.meetsFailThreshold = exports.isFailOnThreshold = exports.FAIL_ON_VALUES = exports.DEFAULT_FAIL_ON = exports.isLocalePath = exports.isTestFilePath = exports.applyPathAwareSeverity = exports.scanTextFileSync = exports.scanTextFileAsync = exports.REGEX_MAX_QUANTIFIERS = exports.REGEX_MAX_LENGTH = exports.REGEX_REASON_TO_DIAGNOSTIC_CODE = exports.mapPatternRejectionReasonToDiagnosticCode = exports.mapRegexSafetyReasonToDiagnosticCode = exports.validateRegexLength = exports.validateRegexSafety = exports.isInsideGitWorkTree = exports.readGitIndexFile = exports.getGitStagedFilePaths = exports.isPemHeaderWithoutBody = exports.isPasswordHash = exports.isCodeIdentifierReference = exports.isEnvVarNameToken = exports.isRedactedTemplateValue = exports.isSampleJwt = exports.isNonSecretConnectionString = exports.isPlaceholderSecret = exports.DEFAULT_ENTROPY_THRESHOLD = exports.shannonEntropy = exports.fingerprintForMatch = void 0;
+exports.resolveFailOn = exports.countBlockingMatches = exports.meetsFailThreshold = exports.isFailOnThreshold = exports.FAIL_ON_VALUES = exports.DEFAULT_FAIL_ON = exports.isLocalePath = exports.isTestFilePath = exports.applyPathAwareSeverity = exports.scanTextFileSync = exports.scanTextFileAsync = exports.REGEX_MAX_QUANTIFIERS = exports.REGEX_MAX_LENGTH = exports.REGEX_REASON_TO_DIAGNOSTIC_CODE = exports.mapPatternRejectionReasonToDiagnosticCode = exports.mapRegexSafetyReasonToDiagnosticCode = exports.validateRegexLength = exports.validateRegexSafety = exports.getGitWorkTreeRoot = exports.isInsideGitWorkTree = exports.readGitIndexFile = exports.getGitStagedFilePaths = exports.isPemHeaderWithoutBody = exports.isPasswordHash = exports.isCodeIdentifierReference = exports.isEnvVarNameToken = exports.isRedactedTemplateValue = exports.isSampleJwt = exports.isNonSecretConnectionString = exports.isPlaceholderSecret = exports.DEFAULT_ENTROPY_THRESHOLD = exports.shannonEntropy = exports.fingerprintForMatch = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./scanners"), exports);
@@ -42,6 +42,7 @@ var git_utils_1 = require("./utils/git-utils");
 Object.defineProperty(exports, "getGitStagedFilePaths", { enumerable: true, get: function () { return git_utils_1.getGitStagedFilePaths; } });
 Object.defineProperty(exports, "readGitIndexFile", { enumerable: true, get: function () { return git_utils_1.readGitIndexFile; } });
 Object.defineProperty(exports, "isInsideGitWorkTree", { enumerable: true, get: function () { return git_utils_1.isInsideGitWorkTree; } });
+Object.defineProperty(exports, "getGitWorkTreeRoot", { enumerable: true, get: function () { return git_utils_1.getGitWorkTreeRoot; } });
 var regex_safety_1 = require("./utils/regex-safety");
 Object.defineProperty(exports, "validateRegexSafety", { enumerable: true, get: function () { return regex_safety_1.validateRegexSafety; } });
 Object.defineProperty(exports, "validateRegexLength", { enumerable: true, get: function () { return regex_safety_1.validateRegexLength; } });

package/dist/scan-output.d.ts

@@ -25,6 +25,20 @@ export interface JsonRunMetadata {
      * this field rather than `summary.secrets`.
      */
     blocking_matches?: number;
+    /**
+     * Files the scan opened but could not read, so their contents were never
+     * examined. Omitted when zero.
+     *
+     * A non-zero value means the run is INCOMPLETE: `blocking_matches` counts
+     * only what the scanner actually looked at, so a clean gate result sits on
+     * top of files nobody checked. On the `--staged` path this is fatal on its
+     * own (exit 2) because that file list is exactly what is about to be
+     * committed; on a directory scan it is reported and counted but does not
+     * fail the gate, since an unreadable file inside a walked tree is an
+     * ordinary occurrence. Unreadable DIRECTORIES are not counted here -- they
+     * surface as `fs.permission_denied` diagnostics instead.
+     */
+    unscannable_files?: number;
 }
 export interface JsonOutput {
     version: string;
@@ -62,9 +76,24 @@ export interface FormatOptions {
     /**
      * Base directory to render `file` paths relative to.
      * Defaults to `process.cwd()`. Files outside this root are kept absolute.
-     * Pass `null` to skip relativization entirely.
+     * Pass `null` to skip relativization for `formatJson`'s `file` paths and
+     * for SARIF when no {@link scanRoot} is given either. A `scanRoot` still
+     * relativizes SARIF `artifactLocation.uri` (and diagnostic ctx) against
+     * itself in that case, so `cwd: null` does not skip SARIF relativization
+     * on its own.
      */
     cwd?: string | null;
+    /**
+     * Directory actually being scanned (the scan target), when it differs from
+     * {@link cwd}. SARIF only: `artifactLocation.uri` is relativized against
+     * this instead of `cwd`, so a finding outside the process cwd but inside the
+     * scan target still gets a relative uri. Defaults to `cwd`.
+     *
+     * `formatJson` ignores this field. Its `file` paths stay cwd-relative,
+     * because they are what the terminal output and the baseline fingerprints
+     * are keyed on.
+     */
+    scanRoot?: string;
     /** Non-fatal diagnostics to include in structured output. */
     diagnostics?: Diagnostic[];
     /** Scan timing / coverage stats for JSON and SARIF `runs[].properties`. */

package/dist/scan-output.js

@@ -37,24 +37,103 @@ function isWindowsStylePath(p) {
  * SARIF spec requires this even when the scanner itself runs on Windows,
  * where `path.relative` returns backslash-separated paths).
  *
+ * The base is the scan root (the directory actually being scanned), not the
+ * process cwd. Scanning an out-of-tree target from somewhere else used to
+ * leave every uri absolute, which published the developer's home directory
+ * and OS username to whoever reads the Code Scanning upload.
+ *
+ * A file genuinely outside the scan root still stays absolute rather than
+ * becoming a `../..` traversal: SARIF relative references are resolved
+ * against `%SRCROOT%`, so a traversal out of it is not a legal uri, and there
+ * is no other root to express such a path against. In practice this only
+ * happens for a path a caller injected from outside the scan, since every
+ * file the scanner itself walks is under the target it was given -- and a
+ * non-absolute `file` is resolved against cwd below before that check runs,
+ * so a literal `..` traversal segment never reaches the returned uri either.
+ *
  * Picks `path.win32` when either side of the comparison looks like a
  * Windows-style path, so this is correct both when the process itself runs
  * on Windows (native `path` is already `path.win32`) and when a
  * Windows-style path is normalized on a POSIX host (tests, or a SARIF file
  * produced elsewhere and re-normalized).
  */
-function toSarifArtifactUri(file, cwd) {
-    if (cwd === null)
+function toSarifArtifactUri(file, cwd, scanRoot) {
+    if (cwd === null && scanRoot === undefined)
         return file.split('\\').join('/');
-    const base = cwd ?? process.cwd();
-    const impl = isWindowsStylePath(file) || isWindowsStylePath(base) ? path_1.default.win32 : path_1.default;
-    if (!impl.isAbsolute(file))
-        return file.split('\\').join('/');
-    const rel = impl.relative(base, file);
+    const anchor = cwd ?? process.cwd();
+    const impl = isWindowsStylePath(file) || isWindowsStylePath(anchor) ? path_1.default.win32 : path_1.default;
+    const abs = impl.isAbsolute(file) ? file : impl.resolve(anchor, file);
+    const base = resolveSarifBase(anchor, scanRoot, impl);
+    const rel = impl.relative(base, abs);
     if (rel.startsWith('..') || impl.isAbsolute(rel))
-        return file.split('\\').join('/');
+        return abs.split('\\').join('/');
     return (rel || '.').split('\\').join('/');
 }
+/**
+ * The effective SARIF `%SRCROOT%` base. `scanRoot` is honored only when it
+ * is genuinely outside `cwd`: a scan root nested inside cwd (or equal to
+ * it) must not narrow `%SRCROOT%` to a subdirectory, because GitHub Code
+ * Scanning (and any other SARIF consumer) resolves `%SRCROOT%` from its own
+ * knowledge of the checkout, not from this uri -- a uri relative to a
+ * subdirectory would then name a different file entirely. Mirrors
+ * `resolveScanRoot` in `packages/cli/src/utils/scan-utils.ts`, which applies
+ * the same rule when it derives `scanRoot` from the CLI's scan target in the
+ * first place.
+ */
+function resolveSarifBase(cwd, scanRoot, impl) {
+    if (scanRoot === undefined)
+        return cwd;
+    const rel = impl.relative(cwd, scanRoot);
+    if (rel === '' || (!rel.startsWith('..') && !impl.isAbsolute(rel)))
+        return cwd;
+    return scanRoot;
+}
+/**
+ * Diagnostic `ctx` reaches SARIF notifications as `JSON.stringify(d.ctx)`
+ * (see `formatSarif` above), and some diagnostic sources (`fs.permission_denied`,
+ * `file.read_error`) carry the scanned directory or file as an absolute path,
+ * plus a `detail` field that is `String(error)` -- Node's own fs error text
+ * often bakes that same absolute path in (e.g. "EACCES: permission denied,
+ * scandir '/abs/dir'"). Both leak exactly what `artifactLocation.uri`
+ * exists to avoid leaking, so ctx gets the same relativize-or-keep-absolute
+ * treatment before it is stringified into a notification: any absolute-path
+ * ctx value (`dir`, `path`, `file`, or any other field shaped that way) is
+ * run through {@link toSarifArtifactUri}, and any other string value has
+ * literal occurrences of the base directory stripped out.
+ */
+function sanitizeDiagnosticCtxForSarif(ctx, cwd, scanRoot) {
+    if (cwd === null && scanRoot === undefined)
+        return ctx;
+    const anchor = cwd ?? process.cwd();
+    const base = resolveSarifBase(anchor, scanRoot, path_1.default);
+    const out = {};
+    for (const [key, value] of Object.entries(ctx)) {
+        if (typeof value !== 'string') {
+            out[key] = value;
+        }
+        else if (path_1.default.isAbsolute(value)) {
+            out[key] = toSarifArtifactUri(value, cwd, scanRoot);
+        }
+        else {
+            out[key] = stripSarifBasePath(value, base);
+        }
+    }
+    return out;
+}
+/**
+ * Removes literal occurrences of the SARIF base directory from a free-form
+ * string (diagnostic `detail`, which is `String(error)` and can embed the
+ * scanned path inside Node's own message text). This is not a full
+ * relative-path rewrite of the string, just enough to keep the base
+ * directory out of the document, matching what `artifactLocation.uri` does
+ * for the path fields themselves.
+ */
+function stripSarifBasePath(text, base) {
+    if (!text.includes(base))
+        return text;
+    const withTrailingSep = base.endsWith(path_1.default.sep) ? base : base + path_1.default.sep;
+    return text.split(withTrailingSep).join('').split(base).join('.');
+}
 function formatJson(results, opts = {}) {
     const fpCwd = opts.cwd === undefined ? process.cwd() : opts.cwd;
     const output = {
@@ -112,7 +191,10 @@ function formatSarif(results, opts = {}) {
         locations: [
             {
                 physicalLocation: {
-                    artifactLocation: { uri: toSarifArtifactUri(file, opts.cwd), uriBaseId: '%SRCROOT%' },
+                    artifactLocation: {
+                        uri: toSarifArtifactUri(file, opts.cwd, opts.scanRoot),
+                        uriBaseId: '%SRCROOT%',
+                    },
                     region: {
                         startLine: m.line,
                         startColumn: m.column + 1,
@@ -133,7 +215,9 @@ function formatSarif(results, opts = {}) {
         ? opts.diagnostics.map(d => ({
             id: d.code,
             level: d.severity === 'error' ? 'error' : 'warning',
-            message: { text: `${d.code}: ${JSON.stringify(d.ctx)}` },
+            message: {
+                text: `${d.code}: ${JSON.stringify(sanitizeDiagnosticCtxForSarif(d.ctx, opts.cwd, opts.scanRoot))}`,
+            },
         }))
         : undefined;
     const runProps = opts.run !== undefined
@@ -149,6 +233,9 @@ function formatSarif(results, opts = {}) {
                 ...(opts.run.baseline_suppressed !== undefined
                     ? { baseline_suppressed: opts.run.baseline_suppressed }
                     : {}),
+                ...(opts.run.unscannable_files !== undefined
+                    ? { unscannable_files: opts.run.unscannable_files }
+                    : {}),
             },
         }
         : undefined;

package/dist/scanners/pre-commit-hook.js

@@ -44,12 +44,28 @@ if ! command -v vault-guard >/dev/null 2>&1; then
 fi
 
 echo "🔍 vault-guard: scanning staged files..."
-if vault-guard scan --staged; then
+# Capture the status rather than branching on \`if vault-guard ...\`: after a
+# bare \`if\` with no else branch, \`$?\` is the IF STATEMENT's status (0), not
+# the command's, so the exit code would be lost. \`|| status=$?\` also keeps
+# \`set -e\` from aborting here, because the failure is handled.
+status=0
+vault-guard scan --staged || status=$?
+
+if [ "$status" -eq 0 ]; then
   echo "✅ vault-guard: no secrets in staged files"
   exit 0
 fi
 
 echo ""
+if [ "$status" -eq 2 ]; then
+  # Exit 2 means vault-guard could not finish the scan, not that it found
+  # something. Claiming secrets were detected would be false, and offering
+  # --no-verify beside it would recommend skipping a check that never ran.
+  echo "❌ COMMIT BLOCKED: vault-guard could not complete the scan"
+  echo "   See the message above for what went unexamined. This commit has not been checked."
+  exit 1
+fi
+
 echo "❌ COMMIT BLOCKED: secrets detected in staged files"
 echo "💡 Fix or unstage, then retry. Emergency bypass (discouraged): git commit --no-verify"
 exit 1
@@ -68,6 +84,14 @@ if errorlevel 1 (
 
 echo 🔍 vault-guard: scanning staged files...
 call vault-guard scan --staged
+REM \`if errorlevel N\` is true for anything >= N, so 2 must be tested BEFORE
+REM 1 or an incomplete scan would fall into the secrets-detected branch.
+if errorlevel 2 (
+  echo.
+  echo ❌ COMMIT BLOCKED: vault-guard could not complete the scan
+  echo    See the message above for what went unexamined. This commit has not been checked.
+  exit /b 1
+)
 if errorlevel 1 (
   echo.
   echo ❌ COMMIT BLOCKED: secrets detected in staged files
@@ -91,12 +115,25 @@ if ! command -v vault-guard >/dev/null 2>&1; then
 fi
 
 echo "🔍 vault-guard: scanning staged files..."
-vault-guard scan --staged || {
+status=0
+vault-guard scan --staged || status=$?
+
+if [ "$status" -eq 2 ]; then
+  # Could not finish the scan, as opposed to finding something. No
+  # --no-verify hint here: the check never ran, so bypassing it is not the
+  # remedy. See the native template for the same reasoning.
+  echo ""
+  echo "❌ COMMIT BLOCKED: vault-guard could not complete the scan"
+  echo "   See the message above for what went unexamined. This commit has not been checked."
+  exit 1
+fi
+
+if [ "$status" -ne 0 ]; then
   echo ""
   echo "❌ COMMIT BLOCKED: secrets detected in staged files"
   echo "💡 git commit --no-verify to bypass (discouraged)"
   exit 1
-}
+fi
 echo "✅ vault-guard: no secrets in staged files"
 `;
 const LEFTHOOK_LOCAL = `# Merged by Lefthook with lefthook.yml — added by vault-guard install-hook

package/dist/utils/git-utils.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Absolute, symlink-resolved path of the worktree root containing `cwd`.
+ *
+ * Every path git reports for the index is relative to this directory, and
+ * `git show :<path>` resolves its argument against it too, so it is the only
+ * correct base for turning git's output into filesystem paths. Deriving it
+ * from `cwd` instead (what this module used to do) is right only when the
+ * caller happens to be standing at the root.
+ *
+ * Throws `GitError` rather than falling back to `cwd`: a wrong root silently
+ * mis-resolves every staged path, which is exactly the failure this function
+ * exists to prevent.
+ */
+export declare function getGitWorkTreeRoot(cwd?: string): string;
+/**
+ * Exact argv passed to git when listing staged files, exported so the
+ * safety-critical parts of it can be asserted directly.
+ *
+ * The `-c diff.relative=false` override is deliberately BELT AND BRACES with
+ * running the command at the worktree root (see getGitStagedFilePaths):
+ * either one alone makes git's output root-relative. That redundancy is
+ * wanted in a published security gate, but redundant code that no test can
+ * observe is code the next person deletes as dead weight -- so
+ * `git-utils.test.ts` pins this argv, and removing the flag fails a test
+ * even though behaviour would not change.
+ */
+export declare const STAGED_DIFF_ARGV: readonly string[];
 /**
  * Return absolute paths of files staged for commit (cached index vs HEAD).
  *
@@ -6,6 +33,14 @@
  * was later deleted from disk (`AD` in `git status`) still appears — that
  * blob will be committed and must be scanned.
  *
+ * Three independent things keep `diff.relative` from deciding what the gate
+ * sees: the config is forced off in the argv, the command runs AT the
+ * worktree root where the setting has nothing to make relative, and the
+ * output is resolved against that root rather than against `cwd`. Any one of
+ * the first two would do; both are here because this is a pre-commit gate on
+ * a published package, and the failure mode is silent under-reporting rather
+ * than an error anyone would notice.
+ *
  * Throws `GitError` on git failure rather than returning an empty list.
  * Returning `[]` silently on git failure would produce a false "✅ nothing
  * staged" result in pre-commit, letting secrets through undetected.
@@ -13,8 +48,19 @@
 export declare function getGitStagedFilePaths(cwd?: string): string[];
 /**
  * Read a staged blob from the index (`git show :path`), not the worktree.
- * `relativePath` may use OS separators; it is normalized to git's `/` form.
+ *
+ * `filePath` may be absolute or relative to `cwd`, and may use OS
+ * separators. It is re-expressed relative to the worktree root before it
+ * reaches git, because git's `:<path>` revision syntax is root-relative by
+ * definition. Handing it a path relative to a subdirectory is what produced
+ * "fatal: path 'pkg/deep/staged.ts' is in the index, but not 'staged.ts'"
+ * and, one silent downgrade later, a clean bill of health over a real
+ * staged credential.
+ *
+ * Unlike the staged listing, this command needs no worktree-root `cwd` of
+ * its own: `:<path>` is defined as root-relative, so once the path has been
+ * re-expressed the working directory git runs in cannot change the answer.
  */
-export declare function readGitIndexFile(cwd: string, relativePath: string): string;
+export declare function readGitIndexFile(cwd: string, filePath: string): string;
 /** True when `cwd` is inside a work tree with a `.git` directory or file. */
 export declare function isInsideGitWorkTree(cwd?: string): boolean;

package/dist/utils/git-utils.js

@@ -3,12 +3,131 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGED_DIFF_ARGV = void 0;
+exports.getGitWorkTreeRoot = getGitWorkTreeRoot;
 exports.getGitStagedFilePaths = getGitStagedFilePaths;
 exports.readGitIndexFile = readGitIndexFile;
 exports.isInsideGitWorkTree = isInsideGitWorkTree;
 const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const errors_1 = require("../errors");
+/**
+ * Repository config that must never be allowed to decide what vault-guard
+ * sees, prepended to every git command this module runs.
+ *
+ * `diff.relative=false` is the load-bearing one. `diff.relative` is an
+ * ordinary, user-settable repo config, and with it on git makes
+ * `git diff --cached --name-only` both print paths relative to the process
+ * cwd instead of the worktree root AND omit every staged path outside that
+ * cwd. A pre-commit gate whose file list can be emptied by a line in
+ * `.git/config` is not a gate, so the setting is overridden per invocation
+ * rather than trusted.
+ *
+ * `core.quotePath=false` is belt-and-braces: every command below already
+ * passes `-z` or reads a single blob, so git never applies path quoting as
+ * things stand. Forcing it here means a future edit that drops `-z` cannot
+ * silently reintroduce `"\303\251.env"`-style names that would then resolve
+ * to a file that does not exist and be skipped.
+ *
+ * These are `-c key=value` arguments in the argv array, not a `git config`
+ * write: nothing on the user's disk is modified.
+ */
+const FORCED_GIT_CONFIG = ['-c', 'diff.relative=false', '-c', 'core.quotePath=false'];
+/**
+ * Resolve symlinks in a directory path, falling back to the input when it
+ * cannot be resolved. Git reports the physical worktree root, so a caller
+ * that passes a symlinked path (`/var/folders/...` on macOS, where the real
+ * directory is `/private/var/folders/...`) would otherwise produce a bogus
+ * `path.relative` against it.
+ */
+function canonicalDir(dir) {
+    try {
+        return fs_1.default.realpathSync.native(dir);
+    }
+    catch {
+        return dir;
+    }
+}
+/**
+ * Successful worktree-root lookups, keyed by the `cwd` asked about.
+ *
+ * `readGitIndexFile` needs the root for every staged file it reads, and a
+ * pre-commit run can have hundreds; without this each one would spawn a
+ * second git process on the latency-sensitive path. Only successes are
+ * cached, so a failure is retried and still throws. A directory's worktree
+ * root does not change under a running scan, and the key set is bounded by
+ * the number of distinct directories a single process asks about (one, in
+ * every current caller).
+ */
+const worktreeRootCache = new Map();
+/**
+ * Absolute, symlink-resolved path of the worktree root containing `cwd`.
+ *
+ * Every path git reports for the index is relative to this directory, and
+ * `git show :<path>` resolves its argument against it too, so it is the only
+ * correct base for turning git's output into filesystem paths. Deriving it
+ * from `cwd` instead (what this module used to do) is right only when the
+ * caller happens to be standing at the root.
+ *
+ * Throws `GitError` rather than falling back to `cwd`: a wrong root silently
+ * mis-resolves every staged path, which is exactly the failure this function
+ * exists to prevent.
+ */
+function getGitWorkTreeRoot(cwd = process.cwd()) {
+    const cached = worktreeRootCache.get(cwd);
+    if (cached !== undefined)
+        return cached;
+    const args = [...FORCED_GIT_CONFIG, 'rev-parse', '--show-toplevel'];
+    let out;
+    try {
+        out = (0, child_process_1.execFileSync)('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        throw new errors_1.GitError(`Failed to locate the git worktree root. Is this a git repository? (cwd: ${cwd})\n` +
+            `Run 'git status' to verify.\nUnderlying error: ${String(err)}`, `git ${args.join(' ')}`, err);
+    }
+    const root = out.trim();
+    if (!root) {
+        throw new errors_1.GitError(`git reported no worktree root for ${cwd} (bare repository?).`, `git ${args.join(' ')}`, undefined);
+    }
+    const resolved = canonicalDir(root);
+    worktreeRootCache.set(cwd, resolved);
+    return resolved;
+}
+/**
+ * Exact argv passed to git when listing staged files, exported so the
+ * safety-critical parts of it can be asserted directly.
+ *
+ * The `-c diff.relative=false` override is deliberately BELT AND BRACES with
+ * running the command at the worktree root (see getGitStagedFilePaths):
+ * either one alone makes git's output root-relative. That redundancy is
+ * wanted in a published security gate, but redundant code that no test can
+ * observe is code the next person deletes as dead weight -- so
+ * `git-utils.test.ts` pins this argv, and removing the flag fails a test
+ * even though behaviour would not change.
+ */
+exports.STAGED_DIFF_ARGV = [
+    ...FORCED_GIT_CONFIG,
+    'diff',
+    '--cached',
+    '--name-only',
+    '--diff-filter=ACMRT',
+    // A staged submodule pointer bump is listed here as an ordinary path,
+    // but its index entry is a gitlink (mode 160000) rather than a blob, so
+    // `git show :<path>` answers "fatal: bad object". There is no content
+    // behind a gitlink for this scanner to read, and treating one as an
+    // unreadable file made every routine submodule bump block the commit
+    // with a message about detected secrets. Dropping the entry is correct,
+    // not a suppression: nothing about the pointer is scannable, and the
+    // submodule's own contents are that repository's own gate to run.
+    '--ignore-submodules=all',
+    '-z',
+];
 /**
  * Return absolute paths of files staged for commit (cached index vs HEAD).
  *
@@ -17,16 +136,25 @@ const errors_1 = require("../errors");
  * was later deleted from disk (`AD` in `git status`) still appears — that
  * blob will be committed and must be scanned.
  *
+ * Three independent things keep `diff.relative` from deciding what the gate
+ * sees: the config is forced off in the argv, the command runs AT the
+ * worktree root where the setting has nothing to make relative, and the
+ * output is resolved against that root rather than against `cwd`. Any one of
+ * the first two would do; both are here because this is a pre-commit gate on
+ * a published package, and the failure mode is silent under-reporting rather
+ * than an error anyone would notice.
+ *
  * Throws `GitError` on git failure rather than returning an empty list.
  * Returning `[]` silently on git failure would produce a false "✅ nothing
  * staged" result in pre-commit, letting secrets through undetected.
  */
 function getGitStagedFilePaths(cwd = process.cwd()) {
-    const args = ['diff', '--cached', '--name-only', '--diff-filter=ACMRT', '-z'];
+    const root = getGitWorkTreeRoot(cwd);
+    const args = [...exports.STAGED_DIFF_ARGV];
     let out;
     try {
         out = (0, child_process_1.execFileSync)('git', args, {
-            cwd,
+            cwd: root,
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -35,19 +163,35 @@ function getGitStagedFilePaths(cwd = process.cwd()) {
         throw new errors_1.GitError(`Failed to list staged files — is this a git repository? (cwd: ${cwd})\n` +
             `Run 'git status' to verify.\nUnderlying error: ${String(err)}`, `git ${args.join(' ')}`, err);
     }
+    // `-z` gives NUL-separated, unquoted, verbatim paths, so entries are used
+    // exactly as git produced them. Trimming here would corrupt the legal (if
+    // unusual) filename with leading or trailing whitespace into a path that
+    // does not exist.
     return out
         .split('\0')
-        .map((line) => line.trim())
         .filter(Boolean)
-        .map((rel) => path_1.default.resolve(cwd, rel));
+        .map((rel) => path_1.default.resolve(root, rel));
 }
 /**
  * Read a staged blob from the index (`git show :path`), not the worktree.
- * `relativePath` may use OS separators; it is normalized to git's `/` form.
+ *
+ * `filePath` may be absolute or relative to `cwd`, and may use OS
+ * separators. It is re-expressed relative to the worktree root before it
+ * reaches git, because git's `:<path>` revision syntax is root-relative by
+ * definition. Handing it a path relative to a subdirectory is what produced
+ * "fatal: path 'pkg/deep/staged.ts' is in the index, but not 'staged.ts'"
+ * and, one silent downgrade later, a clean bill of health over a real
+ * staged credential.
+ *
+ * Unlike the staged listing, this command needs no worktree-root `cwd` of
+ * its own: `:<path>` is defined as root-relative, so once the path has been
+ * re-expressed the working directory git runs in cannot change the answer.
  */
-function readGitIndexFile(cwd, relativePath) {
-    const normalized = relativePath.split(path_1.default.sep).join('/');
-    const args = ['show', `:${normalized}`];
+function readGitIndexFile(cwd, filePath) {
+    const root = getGitWorkTreeRoot(cwd);
+    const abs = path_1.default.resolve(canonicalDir(cwd), filePath);
+    const rootRelative = path_1.default.relative(root, abs).split(path_1.default.sep).join('/');
+    const args = [...FORCED_GIT_CONFIG, 'show', `:${rootRelative}`];
     try {
         return (0, child_process_1.execFileSync)('git', args, {
             cwd,
@@ -57,13 +201,13 @@ function readGitIndexFile(cwd, relativePath) {
         });
     }
     catch (err) {
-        throw new errors_1.GitError(`Failed to read staged blob for ${normalized}\nUnderlying error: ${String(err)}`, `git ${args.join(' ')}`, err);
+        throw new errors_1.GitError(`Failed to read staged blob for ${rootRelative}\nUnderlying error: ${String(err)}`, `git ${args.join(' ')}`, err);
     }
 }
 /** True when `cwd` is inside a work tree with a `.git` directory or file. */
 function isInsideGitWorkTree(cwd = process.cwd()) {
     try {
-        (0, child_process_1.execFileSync)('git', ['rev-parse', '--is-inside-work-tree'], {
+        (0, child_process_1.execFileSync)('git', [...FORCED_GIT_CONFIG, 'rev-parse', '--is-inside-work-tree'], {
             cwd,
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'pipe'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultcompass/vault-guard-core",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Secret-scanning engine: vendor-anchored patterns, entropy gating, baselines, SARIF/JSON, hook helpers.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",