@vaultcompass/vault-guard-core 1.4.5 → 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;

package/dist/scan-output.js

@@ -233,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.5",
+  "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",