@vaultcompass/vault-guard-core 1.0.0

package/dist/utils/scan-file.d.ts

@@ -0,0 +1,29 @@
+import type { DiagnosticBus } from '../diagnostics';
+import { SecretScanner } from '../scanners/secret-scanner';
+import type { SecretMatch } from '../types';
+export interface ScanTextFileOptions {
+    maxFileBytes: number;
+    /** Skip scanning lines longer than this (UTF-16 code units, same as `String#length`). */
+    maxLineUtf16Units?: number;
+    bus?: DiagnosticBus;
+}
+/**
+ * Read `filePath` as UTF-8 and run {@link SecretScanner.scanContent}.
+ *
+ * Files larger than `maxFileBytes` are scanned **line-by-line** so the
+ * process does not load the entire file into memory. Multi-line secrets
+ * (e.g. PEM blocks split across lines) may be missed in that mode — the
+ * trade-off is intentional for very large text files.
+ *
+ * Line breaks are normalised to a single trailing `\n` per line for the
+ * scanner (same as {@link readline}).
+ */
+export declare function scanTextFileAsync(scanner: SecretScanner, filePath: string, options: ScanTextFileOptions): Promise<SecretMatch[]>;
+/**
+ * Synchronous variant of {@link scanTextFileAsync}. For files larger than
+ * `maxFileBytes` this path **does not** stream (it would block on a full read
+ * or require a heavy incremental decoder); callers receive an empty match list
+ * and should prefer the async API for large files.
+ */
+export declare function scanTextFileSync(scanner: SecretScanner, filePath: string, options: ScanTextFileOptions): SecretMatch[];
+//# sourceMappingURL=scan-file.d.ts.map

package/dist/utils/scan-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-file.d.ts","sourceRoot":"","sources":["../../src/utils/scan-file.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAiDxB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,GAC3B,WAAW,EAAE,CAkBf"}

package/dist/utils/scan-file.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanTextFileAsync = scanTextFileAsync;
+exports.scanTextFileSync = scanTextFileSync;
+const fs_1 = __importDefault(require("fs"));
+const fs_2 = require("fs");
+const readline = __importStar(require("readline"));
+const path_severity_1 = require("./path-severity");
+const DEFAULT_MAX_LINE_UTF16 = 1024 * 1024;
+/**
+ * Read `filePath` as UTF-8 and run {@link SecretScanner.scanContent}.
+ *
+ * Files larger than `maxFileBytes` are scanned **line-by-line** so the
+ * process does not load the entire file into memory. Multi-line secrets
+ * (e.g. PEM blocks split across lines) may be missed in that mode — the
+ * trade-off is intentional for very large text files.
+ *
+ * Line breaks are normalised to a single trailing `\n` per line for the
+ * scanner (same as {@link readline}).
+ */
+async function scanTextFileAsync(scanner, filePath, options) {
+    const maxLine = options.maxLineUtf16Units ?? DEFAULT_MAX_LINE_UTF16;
+    const st = await fs_1.default.promises.stat(filePath);
+    if (st.size <= options.maxFileBytes) {
+        const content = await fs_1.default.promises.readFile(filePath, 'utf-8');
+        return (0, path_severity_1.applyPathAwareSeverity)(scanner.scanContent(content), filePath);
+    }
+    const raw = [];
+    let utf16Offset = 0;
+    let lineNo = 0;
+    const rl = readline.createInterface({
+        input: (0, fs_2.createReadStream)(filePath, { encoding: 'utf-8' }),
+        crlfDelay: Infinity,
+    });
+    try {
+        for await (const line of rl) {
+            lineNo++;
+            if (line.length > maxLine) {
+                options.bus?.add({
+                    code: 'file.line_too_long',
+                    severity: 'warning',
+                    ctx: {
+                        file: filePath,
+                        line: lineNo,
+                        units: line.length,
+                        max_units: maxLine,
+                    },
+                });
+                utf16Offset += line.length + 1;
+                continue;
+            }
+            const slice = `${line}\n`;
+            const found = scanner.scanContent(slice).map(m => ({
+                ...m,
+                line: lineNo,
+                column: utf16Offset + m.column,
+            }));
+            raw.push(...found);
+            utf16Offset += line.length + 1;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return (0, path_severity_1.applyPathAwareSeverity)(scanner.mergeChunkedMatches(raw), filePath);
+}
+/**
+ * Synchronous variant of {@link scanTextFileAsync}. For files larger than
+ * `maxFileBytes` this path **does not** stream (it would block on a full read
+ * or require a heavy incremental decoder); callers receive an empty match list
+ * and should prefer the async API for large files.
+ */
+function scanTextFileSync(scanner, filePath, options) {
+    const st = fs_1.default.statSync(filePath);
+    if (st.size <= options.maxFileBytes) {
+        return (0, path_severity_1.applyPathAwareSeverity)(scanner.scanContent(fs_1.default.readFileSync(filePath, 'utf-8')), filePath);
+    }
+    options.bus?.add({
+        code: 'file.too_large',
+        severity: 'warning',
+        ctx: {
+            file: filePath,
+            bytes: st.size,
+            note: 'sync_scan_requires_async_for_streaming',
+        },
+    });
+    return [];
+}
+//# sourceMappingURL=scan-file.js.map

package/dist/utils/scan-file.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@vaultcompass/vault-guard-core",
+  "version": "1.0.0",
+  "description": "Core engine for Vault Guard - security scanning",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vaultcompasshq/vault-guard.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/vaultcompasshq/vault-guard/issues"
+  },
+  "homepage": "https://github.com/vaultcompasshq/vault-guard#readme",
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=9.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "keywords": [
+    "security",
+    "secret-scanner",
+    "token-counter",
+    "guardrails"
+  ],
+  "author": "Vault & Compass LLC",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.1",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "ignore": "^5.3.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  }
+}