agent-nuvira 3.3.12 → 3.3.13

package/dist/security/secret-scan.d.ts

@@ -0,0 +1,156 @@
+/**
+ * secret-scan — find secret-shaped strings in a working tree, ON DEMAND.
+ *
+ * WHY THIS EXISTS. Nuvira writes code and commits it. "Did I just stage a key?"
+ * is a real, recurring failure mode in that loop, and it is the one the toolchain
+ * cannot answer today: `redact()` (enterprise/secrets.ts) keeps secrets out of
+ * logs and history, but nothing ever LOOKS for them in the user's files.
+ *
+ * RELATIONSHIP TO `redact()`: deliberately complementary, not a second opinion.
+ * `redact()` is a SCRUBBER — it masks and never reports. This module is a
+ * DETECTOR — it reports what and where, and masks the value in its own output
+ * (reusing the SAME `maskSecret`/`redact` primitives and the SAME
+ * `KNOWN_KEY_PREFIXES` table), so what we detect can never drift from what we
+ * redact. One pattern source of truth, two readers.
+ *
+ * DESIGN CONSTRAINTS
+ * - Dependency-free and LOCAL. No `gitleaks`/`ggshield` binary, no network, no
+ *   vendor. That is the whole point of the local-first path: a scanner that
+ *   reads every file is a privacy decision, so the default must keep the data
+ *   on the machine.
+ * - PURE + DETERMINISTIC at the text level (`scanText`), so it is unit-testable
+ *   without a filesystem; `scanDirectory` is the thin I/O wrapper.
+ * - NEVER a security guarantee. It is a lint: it catches KNOWN shapes and common
+ *   assignments, and a clean result means "nothing matched", not "no secrets".
+ *   The summary says so, because a scanner that overclaims is worse than none.
+ */
+export type SecretSeverity = 'critical' | 'high' | 'medium';
+export interface SecretPattern {
+    /** Stable id used in the report. */
+    id: string;
+    /** Human label, e.g. 'AWS access key id'. */
+    label: string;
+    severity: SecretSeverity;
+    /** Global regex; `lastIndex` is reset before every use. */
+    re: RegExp;
+}
+export interface SecretFinding {
+    /** Workspace-relative path (never an absolute path — see scanDirectory). */
+    path: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column of the match start. */
+    column: number;
+    id: string;
+    label: string;
+    severity: SecretSeverity;
+    /** Masked form of the matched value (`gsk_…S9ak`). NEVER the real value. */
+    masked: string;
+    /** The containing line with every secret-shaped substring already redacted. */
+    preview: string;
+}
+export interface SecretScanResult {
+    root: string;
+    filesScanned: number;
+    filesSkipped: number;
+    /** True when the file cap or size cap stopped the walk early. */
+    truncated: boolean;
+    findings: SecretFinding[];
+    bySeverity: Record<SecretSeverity, number>;
+    /** One truthful line for a human/model — never overclaims a clean scan. */
+    summary: string;
+}
+/**
+ * High-confidence, low-false-positive shapes. Ordered most-specific first so a
+ * value is attributed to the narrowest pattern that matches it.
+ *
+ * Deliberately NOT included: a bare high-entropy heuristic. It is the classic
+ * source of "your scan found 4000 secrets" noise (git SHAs, hashes, minified
+ * bundles), and a lint nobody trusts gets switched off — which is worse than a
+ * narrower one people keep on.
+ */
+export declare const SECRET_PATTERNS: SecretPattern[];
+/** Is this matched VALUE obviously a placeholder rather than a real secret? */
+export declare function looksLikePlaceholder(value: string): boolean;
+/**
+ * Find secret-shaped substrings in `text`. Pure and synchronous — the whole
+ * detector lives here, so it can be tested without touching a filesystem.
+ *
+ * @param text   Content to scan (a file body, a diff, a log line).
+ * @param path   Label attached to each finding (workspace-relative).
+ */
+export declare function scanText(text: string, path?: string): Omit<SecretFinding, 'preview'>[];
+/** Per-file read cap. A secret never hides beyond this; a minified bundle does. */
+export declare const MAX_FILE_BYTES = 1000000;
+/** Default cap on files visited per scan, so a huge monorepo cannot hang a turn. */
+export declare const DEFAULT_MAX_FILES = 5000;
+/** Should this workspace-relative path be skipped? (exported for tests) */
+export declare function shouldSkipPath(relPath: string): boolean;
+export interface ScanDirectoryOptions {
+    /** Max files to read (default DEFAULT_MAX_FILES). */
+    maxFiles?: number;
+    /** Per-file byte cap (default MAX_FILE_BYTES). */
+    maxFileBytes?: number;
+    /** Restrict the walk to one workspace-relative subtree. */
+    subdir?: string;
+}
+/**
+ * Scan a directory tree for secret-shaped content.
+ *
+ * The walk is bounded twice (file count + per-file size) and skips binary dirs
+ * and generated artifacts. Findings carry a WORKSPACE-RELATIVE path so a report
+ * can be pasted into a ticket without leaking the operator's home directory.
+ * Read failures are counted as skipped, never thrown — a scan must not die on
+ * one unreadable file.
+ */
+export declare function scanDirectory(root: string, options?: ScanDirectoryOptions): SecretScanResult;
+/** Default cap on commits walked. */
+export declare const DEFAULT_MAX_HISTORY_COMMITS = 500;
+/** Default cap on distinct blobs read, so a huge history cannot hang a turn. */
+export declare const DEFAULT_MAX_HISTORY_BLOBS = 2000;
+/** Per-blob read cap (mirrors MAX_FILE_BYTES). */
+export declare const MAX_HISTORY_BLOB_BYTES = 1000000;
+/** A finding plus the commit it was found in (best-effort, may be undefined). */
+export interface HistoryFinding extends SecretFinding {
+    /** Abbreviated commit that last introduced this blob version, when known. */
+    commit?: string;
+}
+export interface SecretHistoryScanResult {
+    root: string;
+    /** False when the path is not a git work tree, or `git` is unavailable. */
+    isGitRepo: boolean;
+    commitsScanned: number;
+    blobsScanned: number;
+    blobsSkipped: number;
+    /** True when a cap stopped the walk early — coverage is partial. */
+    truncated: boolean;
+    findings: HistoryFinding[];
+    bySeverity: Record<SecretSeverity, number>;
+    summary: string;
+}
+export interface ScanHistoryOptions {
+    /** Max commits to walk (default DEFAULT_MAX_HISTORY_COMMITS). */
+    maxCommits?: number;
+    /** Max distinct blobs to read (default DEFAULT_MAX_HISTORY_BLOBS). */
+    maxBlobs?: number;
+    /** Per-blob byte cap (default MAX_HISTORY_BLOB_BYTES). */
+    maxBlobBytes?: number;
+    /** Restrict to one workspace-relative subtree. */
+    subdir?: string;
+}
+/**
+ * Scan reachable git history for secret-shaped content.
+ *
+ * Walks `git rev-list --objects --all` to enumerate every blob version, keeps
+ * only blobs whose path survives {@link shouldSkipPath}, reads the small ones
+ * through a single batched `git cat-file`, and runs the SAME {@link scanText}
+ * detector as the tree scan — one pattern source of truth across both surfaces.
+ * A finding's path is labelled `<path>@<commit>` when the introducing commit can
+ * be resolved (best-effort; the blob sha stand-in is used otherwise).
+ */
+export declare function scanGitHistory(root: string, options?: ScanHistoryOptions): SecretHistoryScanResult;
+/** Render a git-history result as a compact report a model or human can act on. */
+export declare function formatSecretHistoryScan(result: SecretHistoryScanResult): string;
+/** Render a result as a compact report a model or a human can act on. */
+export declare function formatSecretScan(result: SecretScanResult): string;
+//# sourceMappingURL=secret-scan.d.ts.map

package/dist/security/secret-scan.d.ts.map

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