@vaultcompass/vault-guard-core 1.0.0

package/dist/utils/path-severity.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestFilePath = isTestFilePath;
+exports.applyPathAwareSeverity = applyPathAwareSeverity;
+const path_1 = __importDefault(require("path"));
+/**
+ * Pattern IDs whose severity is downgraded to `low` in obvious test / fixture
+ * paths. Two groups:
+ *
+ *   - Low-precision generic patterns (`password-in-code`, …) — common in test
+ *     scaffolding and rarely real leaks there.
+ *   - Connection strings and key/token shapes (`postgresql-url`,
+ *     `ssh-private-key`, `jwt-token`, …) — test suites are full of throwaway
+ *     DSNs, fixture PEMs, and sample tokens. Downgrading (not suppressing)
+ *     keeps them visible at `low` without drowning real criticals.
+ *
+ * Hard vendor-anchored API-key patterns (anthropic, aws-access, stripe,
+ * github-token, …) are intentionally **absent**: a real provider key is a real
+ * key even in a test file, and those patterns have near-zero false positives.
+ */
+const TEST_PATH_DOWNGRADE_IDS = new Set([
+    // generic / assignment
+    'password-in-code',
+    'api-key-generic',
+    'secret-generic',
+    'bearer-token',
+    // connection strings
+    'postgresql-url',
+    'mysql-url',
+    'mongodb-url',
+    'redis-url',
+    // key / token shapes
+    'ssh-private-key',
+    'jwt-token',
+]);
+/**
+ * Segments that indicate a file lives in a test / fixture tree.
+ * Matched against every directory component in the file path.
+ */
+const TEST_DIR_SEGMENTS = new Set([
+    '__tests__',
+    '__mocks__',
+    'tests',
+    'test',
+    'fixtures',
+    'testdata',
+    'spec',
+    'e2e',
+]);
+/**
+ * File name suffixes / extensions that mark test or fixture files.
+ * Checked against `path.basename(filePath)`.
+ */
+const TEST_FILE_PATTERNS = [
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /\.test\.api\.[jt]sx?$/,
+    /\.fixture\.[jt]sx?$/,
+];
+/**
+ * Return `true` when `filePath` looks like a test or fixture file.
+ */
+function isTestFilePath(filePath) {
+    const parts = filePath.split(path_1.default.sep).flatMap(p => p.split('/'));
+    if (parts.some(seg => TEST_DIR_SEGMENTS.has(seg)))
+        return true;
+    const basename = path_1.default.basename(filePath);
+    return TEST_FILE_PATTERNS.some(re => re.test(basename));
+}
+/**
+ * Downgrade low-precision generic pattern findings to `'low'` severity when
+ * they appear inside a test / fixture file.
+ *
+ * Rationale: password assignments, bearer tokens, and generic api-key patterns
+ * are common in test scaffolding (`const password = 'Admin1234!'`) and are
+ * rarely real leaked credentials in that context. Vendor-anchored patterns
+ * (aws-access, anthropic, stripe, …) are unaffected — a real key in a test
+ * file is still worth a `critical` alert.
+ */
+function applyPathAwareSeverity(matches, filePath) {
+    if (matches.length === 0)
+        return matches;
+    if (!isTestFilePath(filePath))
+        return matches;
+    return matches.map(m => {
+        if (!TEST_PATH_DOWNGRADE_IDS.has(m.type))
+            return m;
+        if (m.severity === 'low')
+            return m;
+        return { ...m, severity: 'low' };
+    });
+}
+//# sourceMappingURL=path-severity.js.map

package/dist/utils/path-severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-severity.js","sourceRoot":"","sources":["../../src/utils/path-severity.ts"],"names":[],"mappings":";;;;;AA+DA,wCAKC;AAYD,wDAYC;AA5FD,gDAAwB;AAGxB;;;;;;;;;;;;;;GAcG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IACtC,uBAAuB;IACvB,kBAAkB;IAClB,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,qBAAqB;IACrB,gBAAgB;IAChB,WAAW;IACX,aAAa;IACb,WAAW;IACX,qBAAqB;IACrB,iBAAiB;IACjB,WAAW;CACZ,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,WAAW;IACX,WAAW;IACX,OAAO;IACP,MAAM;IACN,UAAU;IACV,UAAU;IACV,MAAM;IACN,KAAK;CACN,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,kBAAkB;IAClB,kBAAkB;IAClB,uBAAuB;IACvB,qBAAqB;CACtB,CAAC;AAEF;;GAEG;AACH,SAAgB,cAAc,CAAC,QAAgB;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,cAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,QAAQ,GAAG,cAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,OAAO,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,sBAAsB,CACpC,OAAsB,EACtB,QAAgB;IAEhB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IAE9C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QACrB,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK;YAAE,OAAO,CAAC,CAAC;QACnC,OAAO,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAc,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/placeholder.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Recognise obviously non-secret placeholder / example / test values so that
+ * broad patterns stop firing on documentation samples and unit-test fixtures —
+ * empirically the dominant real-world false-positive source (e.g. AWS's own
+ * documented `AKIAIOSFODNN7EXAMPLE` key, or `const password = 'testPass1234'`).
+ *
+ * Two tiers, by precision cost:
+ *
+ *   - `standard` (safe for every pattern, including vendor-anchored keys):
+ *     unambiguous markers that effectively never occur inside a real generated
+ *     credential — `EXAMPLE`, `changeme`, `your_token_here`, all-`x` padding, …
+ *
+ *   - `aggressive` (opt-in, used only by the low-precision generic / password
+ *     assignment patterns): additionally treats common test-fixture words
+ *     (`test`, `sample`, `password`, …) as placeholders. Scoped to those
+ *     patterns so vendor-anchored keys keep full recall.
+ *
+ * Matching is substring-based on the lower-cased value. Markers are chosen to
+ * be long/specific enough that a real high-entropy secret will not contain them
+ * by chance.
+ */
+/**
+ * Return `true` when a database/Redis connection string is **not** a real
+ * credential leak — i.e. it targets a local/dev/docker/example host, or uses
+ * obvious placeholder/default credentials.
+ *
+ * The exploitable secret in a DSN is the password against a *reachable* host.
+ * We suppress when either:
+ *   1. the host is local, a bare docker-compose service name, or a reserved
+ *      TLD (`localhost`, `mysql`, `db.local`, …) — not remotely reachable; or
+ *   2. the password is a placeholder/default (`pass`, `PASSWORD`, `root:root`,
+ *      `${DB_PASS}`, `<your-password>`, …).
+ *
+ * A real remote host with a real password (e.g.
+ * `postgres://app:8Fk2$mQ9z@db.prod.example-corp.com/main`) is **not**
+ * suppressed.
+ */
+/**
+ * Recognise the canonical jwt.io / RFC 7519 sample token that is pasted into
+ * countless READMEs, OpenAPI specs, and tutorials. Its decoded payload carries
+ * the well-known sample claims (`sub: "1234567890"`, `name: "John Doe"`,
+ * `iat: 1516239022`). These are never real credentials.
+ */
+export declare function isSampleJwt(token: string): boolean;
+export declare function isNonSecretConnectionString(url: string): boolean;
+/**
+ * @returns `true` when `value` looks like a placeholder / example / test
+ * credential and should be suppressed.
+ */
+export declare function isPlaceholderSecret(value: string, opts?: {
+    aggressive?: boolean;
+}): boolean;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/utils/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../../src/utils/placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0FH;;;;;;;;;;;;;;;GAeG;AACH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAclD;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAwBhE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAiBT"}

package/dist/utils/placeholder.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Recognise obviously non-secret placeholder / example / test values so that
+ * broad patterns stop firing on documentation samples and unit-test fixtures —
+ * empirically the dominant real-world false-positive source (e.g. AWS's own
+ * documented `AKIAIOSFODNN7EXAMPLE` key, or `const password = 'testPass1234'`).
+ *
+ * Two tiers, by precision cost:
+ *
+ *   - `standard` (safe for every pattern, including vendor-anchored keys):
+ *     unambiguous markers that effectively never occur inside a real generated
+ *     credential — `EXAMPLE`, `changeme`, `your_token_here`, all-`x` padding, …
+ *
+ *   - `aggressive` (opt-in, used only by the low-precision generic / password
+ *     assignment patterns): additionally treats common test-fixture words
+ *     (`test`, `sample`, `password`, …) as placeholders. Scoped to those
+ *     patterns so vendor-anchored keys keep full recall.
+ *
+ * Matching is substring-based on the lower-cased value. Markers are chosen to
+ * be long/specific enough that a real high-entropy secret will not contain them
+ * by chance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSampleJwt = isSampleJwt;
+exports.isNonSecretConnectionString = isNonSecretConnectionString;
+exports.isPlaceholderSecret = isPlaceholderSecret;
+/** Unambiguous placeholder markers — applied to all patterns. */
+const STANDARD_MARKERS = [
+    'example',
+    'changeme',
+    'change-me',
+    'change_me',
+    'placeholder',
+    'redacted',
+    'notreal',
+    'not-a-real',
+    'dummy',
+    'yourtoken',
+    'yourkey',
+    'yourapikey',
+    'your_token',
+    'your-token',
+    'your_key',
+    'your-key',
+    'your_api_key',
+    'your-api-key',
+    'insertyour',
+    'insert_your',
+    'replace_me',
+    'replaceme',
+    'loremipsum',
+    // Pure character repetition (e.g. `xxxxxxxx`, `00000000`) is handled by the
+    // low-variety check below rather than literal markers, so it does not clash
+    // with real keys that merely contain a short repeated run.
+];
+/** Common test / fixture markers — applied only to generic assignment patterns. */
+const AGGRESSIVE_MARKERS = [
+    'test',
+    'sample',
+    'demo',
+    'fake',
+    'mock',
+    'foobar',
+    'password',
+    'passw0rd',
+    'secret',
+    'hunter2',
+    'qwerty',
+    'letmein',
+];
+/**
+ * A value made of one or two distinct characters (e.g. `xxxxxxxx`, `00000000`)
+ * is padding, never a real secret.
+ */
+function isLowVariety(value) {
+    return value.length >= 8 && new Set(value).size <= 2;
+}
+/** Hosts that are never a remotely-exploitable credential leak. */
+const LOCAL_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0',
+    '::1',
+    '[::1]',
+    'host.docker.internal',
+]);
+/** Reserved / non-routable TLD suffixes (RFC 6761 + docker/dev conventions). */
+const LOCAL_TLD_SUFFIXES = [
+    '.local',
+    '.localhost',
+    '.test',
+    '.example',
+    '.invalid',
+];
+/**
+ * Password tokens that are obviously defaults / placeholders rather than a
+ * real secret. Matched case-insensitively against the password component of a
+ * connection string. Deliberately scoped to the *password* — usernames like
+ * `admin` / `root` / `postgres` are extremely common in genuine leaks, so we
+ * never suppress based on the username alone.
+ */
+const PLACEHOLDER_PASSWORDS = new Set([
+    'password', 'passwd', 'pass', 'pwd', 'secret',
+    'changeme', 'example', 'test', 'user', 'username',
+    'root', 'admin', 'postgres', 'mysql', 'mongo', 'mongodb', 'redis',
+    'db', 'database', 'prisma', 'identifier', 'key', 'token', 'name',
+    'randompassword', 'yourpassword', 'mypassword',
+]);
+/**
+ * Return `true` when a database/Redis connection string is **not** a real
+ * credential leak — i.e. it targets a local/dev/docker/example host, or uses
+ * obvious placeholder/default credentials.
+ *
+ * The exploitable secret in a DSN is the password against a *reachable* host.
+ * We suppress when either:
+ *   1. the host is local, a bare docker-compose service name, or a reserved
+ *      TLD (`localhost`, `mysql`, `db.local`, …) — not remotely reachable; or
+ *   2. the password is a placeholder/default (`pass`, `PASSWORD`, `root:root`,
+ *      `${DB_PASS}`, `<your-password>`, …).
+ *
+ * A real remote host with a real password (e.g.
+ * `postgres://app:8Fk2$mQ9z@db.prod.example-corp.com/main`) is **not**
+ * suppressed.
+ */
+/**
+ * Recognise the canonical jwt.io / RFC 7519 sample token that is pasted into
+ * countless READMEs, OpenAPI specs, and tutorials. Its decoded payload carries
+ * the well-known sample claims (`sub: "1234567890"`, `name: "John Doe"`,
+ * `iat: 1516239022`). These are never real credentials.
+ */
+function isSampleJwt(token) {
+    const parts = token.split('.');
+    if (parts.length < 2 || !parts[1])
+        return false;
+    let payload;
+    try {
+        payload = Buffer.from(parts[1], 'base64url').toString('utf-8');
+    }
+    catch {
+        return false;
+    }
+    return (/"sub"\s*:\s*"1234567890"/.test(payload) ||
+        /"name"\s*:\s*"John Doe"/.test(payload) ||
+        /\b1516239022\b/.test(payload));
+}
+function isNonSecretConnectionString(url) {
+    const m = /^[a-z][a-z0-9+.-]*:\/\/([^:@/\s]+):([^@/\s]+)@([^:/?\s]+)/i.exec(url);
+    if (!m)
+        return false;
+    const user = m[1];
+    const pass = m[2];
+    const host = m[3].toLowerCase();
+    // 1. Non-routable / local / docker-service / reserved-TLD host.
+    if (LOCAL_HOSTS.has(host))
+        return true;
+    if (LOCAL_TLD_SUFFIXES.some(suffix => host.endsWith(suffix)))
+        return true;
+    // Bare single-token host with no dot (and not a raw IPv4) is a docker-compose
+    // service name (`mysql`, `db`, `postgres`) — local to a compose network.
+    if (!host.includes('.') && !host.includes(':') && !/^\d+$/.test(host))
+        return true;
+    // 2. Placeholder / default password.
+    const p = pass.toLowerCase();
+    if (PLACEHOLDER_PASSWORDS.has(p))
+        return true;
+    if (user.toLowerCase() === p)
+        return true; // root:root, prisma:prisma
+    if (/^[A-Z][A-Z0-9_]*$/.test(pass))
+        return true; // USER:PASSWORD, DBPASS
+    if (pass.startsWith('$') || pass.startsWith('<') || pass.startsWith('{'))
+        return true; // ${DB_PASS}, <pw>
+    if (isPlaceholderSecret(pass, { aggressive: true }))
+        return true;
+    return false;
+}
+/**
+ * @returns `true` when `value` looks like a placeholder / example / test
+ * credential and should be suppressed.
+ */
+function isPlaceholderSecret(value, opts = {}) {
+    if (!value)
+        return false;
+    const v = value.toLowerCase();
+    for (const marker of STANDARD_MARKERS) {
+        if (v.includes(marker))
+            return true;
+    }
+    if (isLowVariety(value))
+        return true;
+    if (opts.aggressive) {
+        for (const marker of AGGRESSIVE_MARKERS) {
+            if (v.includes(marker))
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=placeholder.js.map

package/dist/utils/placeholder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.js","sourceRoot":"","sources":["../../src/utils/placeholder.ts"],"names":[],"mappings":"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"}

package/dist/utils/regex-safety.d.ts

@@ -0,0 +1,102 @@
+import type { DiagnosticCode } from '../diagnostics';
+/**
+ * Heuristic safety checks for user-supplied regex patterns.
+ *
+ * Why this exists
+ * ---------------
+ * `VaultGuardConfig.extra_patterns[].regex` is compiled with `new RegExp(src, 'g')`
+ * and run against every line of every scanned file. A malicious or careless
+ * `.vault-guard.json` (anywhere in the repo, after the `loadConfig` git-boundary
+ * fix) can therefore implant a catastrophic-backtracking regex that pins the
+ * scanner CPU on the first file with the right shape.
+ *
+ * What this does (and does not) catch
+ * -----------------------------------
+ * This is a **conservative, dependency-free** static check:
+ *
+ *   1. Hard length cap (256 chars): real-world secret patterns are <100 chars;
+ *      anything longer is suspicious and also bounds compile-time RAM use.
+ *   2. Quantifier-density cap (>25 of `* + ? {`): the academic ReDoS literature
+ *      shows pathological patterns concentrate quantifiers; this is the same
+ *      threshold `safe-regex` uses.
+ *   3. Nested-quantifier shape: `(…[*+]…)[*+]` — catches `(a+)+`, `(\d+)*`.
+ *   4. Alternation-quantifier shape: `(.|.)[*+]` — catches `(a|a)+`, `(\d|\d)*`.
+ *
+ * What this does NOT catch
+ * ------------------------
+ * - Cross-group backtracking like `(.*x)(y.*)` chains.
+ * - Pathological lookaheads.
+ * - Anything a determined attacker can hide behind character classes.
+ *
+ * Real defence in depth requires execution-time bounds (e.g. `re2`). That is
+ * tracked as a Phase 8 follow-up; this module is the pre-launch backstop.
+ *
+ * Users who need to bypass the heuristic for a known-safe pattern can set
+ * `extra_patterns_unsafe: true` in `.vault-guard.json`. The length cap still
+ * applies as a memory-use backstop even in unsafe mode.
+ */
+/**
+ * Maximum allowed source length for user-provided regex strings.
+ *
+ * @remarks
+ * This cap is both a safety and performance bound. Real-world secret patterns
+ * are usually well under 100 characters; 256 leaves margin for legitimate
+ * patterns while rejecting pathological or accidental megaregex input.
+ */
+export declare const REGEX_MAX_LENGTH = 256;
+/**
+ * Maximum number of quantifier tokens (`* + ? {`) allowed in a user pattern.
+ *
+ * @remarks
+ * High quantifier density correlates strongly with catastrophic backtracking.
+ * The threshold intentionally matches common static-check heuristics.
+ */
+export declare const REGEX_MAX_QUANTIFIERS = 25;
+export type RegexSafetyReason = 'too_long' | 'too_many_quantifiers' | 'nested_quantifier' | 'alternation_quantifier' | 'invalid_syntax';
+/**
+ * Canonical mapping from regex-safety rejections to diagnostics codes.
+ *
+ * Keep this mapping in one place so scan/reporting surfaces don't drift.
+ */
+export declare const REGEX_REASON_TO_DIAGNOSTIC_CODE: Record<RegexSafetyReason, DiagnosticCode>;
+export interface RegexSafetyResult {
+    ok: boolean;
+    reason?: RegexSafetyReason;
+    detail?: string;
+}
+/**
+ * Validate a user-supplied regex source string with heuristic ReDoS guards.
+ *
+ * @param source - Raw regex source from `.vault-guard.json` (without delimiters).
+ * @returns `ok: true` when accepted, otherwise `ok: false` with machine-readable
+ * `reason` and human-readable `detail` for diagnostics output.
+ */
+export declare function validateRegexSafety(source: string): RegexSafetyResult;
+/**
+ * Perform a length-only safety check.
+ *
+ * @param source - Raw regex source from `.vault-guard.json`.
+ * @returns `ok: false` with `reason: 'too_long'` when the source exceeds
+ * `REGEX_MAX_LENGTH`, otherwise `ok: true`.
+ *
+ * @remarks
+ * This is intentionally used even when `extra_patterns_unsafe: true` so there
+ * is always a hard memory backstop.
+ */
+export declare function validateRegexLength(source: string): RegexSafetyResult;
+/**
+ * Convert a regex safety rejection reason to the canonical diagnostic code.
+ *
+ * @param reason - Safety rejection identifier.
+ * @returns Stable diagnostics code for JSON/SARIF/text reporting.
+ */
+export declare function mapRegexSafetyReasonToDiagnosticCode(reason: RegexSafetyReason): DiagnosticCode;
+/**
+ * Safely map an untyped rejection reason string to a diagnostics code.
+ *
+ * @param reason - Rejection reason coming from runtime validation paths.
+ * @returns Canonical diagnostics code, defaulting to `pattern.redos_unsafe`
+ * when the reason is unknown.
+ */
+export declare function mapPatternRejectionReasonToDiagnosticCode(reason: string): DiagnosticCode;
+//# sourceMappingURL=regex-safety.d.ts.map

package/dist/utils/regex-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-safety.d.ts","sourceRoot":"","sources":["../../src/utils/regex-safety.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAKxC,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,sBAAsB,GACtB,mBAAmB,GACnB,wBAAwB,GACxB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,iBAAiB,EAAE,cAAc,CAMrF,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAmCrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CASrE;AAED;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,CAE9F;AAED;;;;;;GAMG;AACH,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAKxF"}

package/dist/utils/regex-safety.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGEX_REASON_TO_DIAGNOSTIC_CODE = exports.REGEX_MAX_QUANTIFIERS = exports.REGEX_MAX_LENGTH = void 0;
+exports.validateRegexSafety = validateRegexSafety;
+exports.validateRegexLength = validateRegexLength;
+exports.mapRegexSafetyReasonToDiagnosticCode = mapRegexSafetyReasonToDiagnosticCode;
+exports.mapPatternRejectionReasonToDiagnosticCode = mapPatternRejectionReasonToDiagnosticCode;
+/**
+ * Heuristic safety checks for user-supplied regex patterns.
+ *
+ * Why this exists
+ * ---------------
+ * `VaultGuardConfig.extra_patterns[].regex` is compiled with `new RegExp(src, 'g')`
+ * and run against every line of every scanned file. A malicious or careless
+ * `.vault-guard.json` (anywhere in the repo, after the `loadConfig` git-boundary
+ * fix) can therefore implant a catastrophic-backtracking regex that pins the
+ * scanner CPU on the first file with the right shape.
+ *
+ * What this does (and does not) catch
+ * -----------------------------------
+ * This is a **conservative, dependency-free** static check:
+ *
+ *   1. Hard length cap (256 chars): real-world secret patterns are <100 chars;
+ *      anything longer is suspicious and also bounds compile-time RAM use.
+ *   2. Quantifier-density cap (>25 of `* + ? {`): the academic ReDoS literature
+ *      shows pathological patterns concentrate quantifiers; this is the same
+ *      threshold `safe-regex` uses.
+ *   3. Nested-quantifier shape: `(…[*+]…)[*+]` — catches `(a+)+`, `(\d+)*`.
+ *   4. Alternation-quantifier shape: `(.|.)[*+]` — catches `(a|a)+`, `(\d|\d)*`.
+ *
+ * What this does NOT catch
+ * ------------------------
+ * - Cross-group backtracking like `(.*x)(y.*)` chains.
+ * - Pathological lookaheads.
+ * - Anything a determined attacker can hide behind character classes.
+ *
+ * Real defence in depth requires execution-time bounds (e.g. `re2`). That is
+ * tracked as a Phase 8 follow-up; this module is the pre-launch backstop.
+ *
+ * Users who need to bypass the heuristic for a known-safe pattern can set
+ * `extra_patterns_unsafe: true` in `.vault-guard.json`. The length cap still
+ * applies as a memory-use backstop even in unsafe mode.
+ */
+/**
+ * Maximum allowed source length for user-provided regex strings.
+ *
+ * @remarks
+ * This cap is both a safety and performance bound. Real-world secret patterns
+ * are usually well under 100 characters; 256 leaves margin for legitimate
+ * patterns while rejecting pathological or accidental megaregex input.
+ */
+exports.REGEX_MAX_LENGTH = 256;
+/**
+ * Maximum number of quantifier tokens (`* + ? {`) allowed in a user pattern.
+ *
+ * @remarks
+ * High quantifier density correlates strongly with catastrophic backtracking.
+ * The threshold intentionally matches common static-check heuristics.
+ */
+exports.REGEX_MAX_QUANTIFIERS = 25;
+const NESTED_QUANTIFIER = /\([^()]*[*+][^()]*\)[*+]/;
+const ALT_QUANTIFIER = /\([^()|]*\|[^()|]*\)[*+]/;
+/**
+ * Canonical mapping from regex-safety rejections to diagnostics codes.
+ *
+ * Keep this mapping in one place so scan/reporting surfaces don't drift.
+ */
+exports.REGEX_REASON_TO_DIAGNOSTIC_CODE = {
+    invalid_syntax: 'pattern.invalid',
+    too_long: 'pattern.too_long',
+    too_many_quantifiers: 'pattern.redos_unsafe',
+    nested_quantifier: 'pattern.redos_unsafe',
+    alternation_quantifier: 'pattern.redos_unsafe',
+};
+/**
+ * Validate a user-supplied regex source string with heuristic ReDoS guards.
+ *
+ * @param source - Raw regex source from `.vault-guard.json` (without delimiters).
+ * @returns `ok: true` when accepted, otherwise `ok: false` with machine-readable
+ * `reason` and human-readable `detail` for diagnostics output.
+ */
+function validateRegexSafety(source) {
+    if (source.length > exports.REGEX_MAX_LENGTH) {
+        return {
+            ok: false,
+            reason: 'too_long',
+            detail: `regex source is ${source.length} chars (max ${exports.REGEX_MAX_LENGTH})`,
+        };
+    }
+    const quantifierCount = countQuantifiers(source);
+    if (quantifierCount > exports.REGEX_MAX_QUANTIFIERS) {
+        return {
+            ok: false,
+            reason: 'too_many_quantifiers',
+            detail: `regex contains ${quantifierCount} quantifiers (max ${exports.REGEX_MAX_QUANTIFIERS})`,
+        };
+    }
+    if (NESTED_QUANTIFIER.test(source)) {
+        return {
+            ok: false,
+            reason: 'nested_quantifier',
+            detail: 'nested quantifier of the form `(…[*+]…)[*+]` detected (catastrophic backtracking)',
+        };
+    }
+    if (ALT_QUANTIFIER.test(source)) {
+        return {
+            ok: false,
+            reason: 'alternation_quantifier',
+            detail: 'alternation under quantifier `(a|b)[*+]` detected (potential exponential backtracking)',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Perform a length-only safety check.
+ *
+ * @param source - Raw regex source from `.vault-guard.json`.
+ * @returns `ok: false` with `reason: 'too_long'` when the source exceeds
+ * `REGEX_MAX_LENGTH`, otherwise `ok: true`.
+ *
+ * @remarks
+ * This is intentionally used even when `extra_patterns_unsafe: true` so there
+ * is always a hard memory backstop.
+ */
+function validateRegexLength(source) {
+    if (source.length > exports.REGEX_MAX_LENGTH) {
+        return {
+            ok: false,
+            reason: 'too_long',
+            detail: `regex source is ${source.length} chars (max ${exports.REGEX_MAX_LENGTH})`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Convert a regex safety rejection reason to the canonical diagnostic code.
+ *
+ * @param reason - Safety rejection identifier.
+ * @returns Stable diagnostics code for JSON/SARIF/text reporting.
+ */
+function mapRegexSafetyReasonToDiagnosticCode(reason) {
+    return exports.REGEX_REASON_TO_DIAGNOSTIC_CODE[reason];
+}
+/**
+ * Safely map an untyped rejection reason string to a diagnostics code.
+ *
+ * @param reason - Rejection reason coming from runtime validation paths.
+ * @returns Canonical diagnostics code, defaulting to `pattern.redos_unsafe`
+ * when the reason is unknown.
+ */
+function mapPatternRejectionReasonToDiagnosticCode(reason) {
+    if (reason in exports.REGEX_REASON_TO_DIAGNOSTIC_CODE) {
+        return exports.REGEX_REASON_TO_DIAGNOSTIC_CODE[reason];
+    }
+    return 'pattern.redos_unsafe';
+}
+/**
+ * Count `* + ? {` quantifier characters outside character classes.
+ *
+ * Approximation only — doesn't fully tokenise the regex, just skips `[…]`
+ * blocks where these characters are literal. Good enough to flag pathological
+ * patterns without false-positiving on `[a-z?]` or `\?`.
+ */
+function countQuantifiers(source) {
+    let count = 0;
+    let inClass = false;
+    let escape = false;
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (c === '\\') {
+            escape = true;
+            continue;
+        }
+        if (c === '[' && !inClass) {
+            inClass = true;
+            continue;
+        }
+        if (c === ']' && inClass) {
+            inClass = false;
+            continue;
+        }
+        if (inClass)
+            continue;
+        if (c === '*' || c === '+' || c === '?' || c === '{')
+            count++;
+    }
+    return count;
+}
+//# sourceMappingURL=regex-safety.js.map

package/dist/utils/regex-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-safety.js","sourceRoot":"","sources":["../../src/utils/regex-safety.ts"],"names":[],"mappings":"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"}