@mstar-harness/engine 3.2.6 → 3.4.0

package/dist/audit.d.ts

@@ -8,6 +8,11 @@ export type AuditEffort = (typeof AUDIT_EFFORTS)[number];
 /** Risk values. */
 export declare const AUDIT_RISKS: readonly ["LOW", "MED", "HIGH"];
 export type AuditRisk = (typeof AUDIT_RISKS)[number];
+/** Confidence values (finding-format.md § Template — Confidence: HIGH
+ * (certain, read the code) / MED (strong signal, verify) / LOW (smell,
+ * investigate)). Enum SSOT for finding-doc lint + AuditFinding. */
+export declare const AUDIT_CONFIDENCES: readonly ["HIGH", "MED", "LOW"];
+export type AuditConfidence = (typeof AUDIT_CONFIDENCES)[number];
 /** Category codes (finding-format.md § Category codes + mstar-audit SKILL.md § Plan output (all variants) Status block). */
 export declare const AUDIT_CATEGORIES: readonly ["bug", "security", "perf", "tests", "tech-debt", "migration", "dx", "docs", "direction"];
 export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
@@ -42,6 +47,55 @@ export type RedactResult = {
     text: string;
     findings: SecretFinding[];
 };
+/**
+ * Whole-match credential patterns — the match is fully replaced. Patterns
+ * are deliberately conservative (prefixed signatures + minimum lengths) to
+ * avoid false positives (mstar-audit Hard Rule 4: reference file:line and
+ * credential type only, never the value). Exported as the D-2 SSOT: both
+ * `redactSecrets` and `scanSecrets` share this one table, so reviewers can
+ * reconcile against exactly what the engine scans. Extending it only ever
+ * ADDS detections for consumers of either reader — existing-pattern
+ * behavior of the dsh audit seam (`validateAuditDoc`) stays byte-identical.
+ */
+export declare const WHOLE_MATCH_PATTERNS: readonly {
+    type: string;
+    re: RegExp;
+}[];
+/**
+ * Key-value assignment patterns — for redaction the key name is preserved
+ * and only the value is replaced. Value minimum lengths (8 quoted / 16
+ * unquoted) keep the scan conservative (`token: x` and `password: 1234`
+ * are not flagged). Keys may carry optional quotes (JSON/YAML
+ * `"password": "..."`), which are preserved in the replacement: group 1 =
+ * optional open quote, group 3 = optional close quote, group 4 = separator,
+ * group 5 = value (dropped). Exported as part of the D-2 SSOT — shared by
+ * `redactSecrets` and `scanSecrets`.
+ */
+export declare const VALUE_PATTERNS: readonly {
+    typeOf: (key: string) => string;
+    re: RegExp;
+}[];
+/**
+ * Never-commit filename patterns (security-review.md §6): a file whose name
+ * matches should not be committed regardless of content — `.env*`, `*.pem`,
+ * `*.key`, `id_rsa`-family, plus named credential stores. All patterns are
+ * matched against the path BASENAME, never the full path.
+ */
+export declare const NEVER_COMMIT_FILENAMES: readonly {
+    type: string;
+    re: RegExp;
+}[];
+/**
+ * CI/IaC credential-leak shapes (security-review.md §6). Each entry is one
+ * deterministic line shape; match groups feed the finding message. All
+ * shapes are additive on top of the pattern tables above and never capture
+ * secret VALUES into findings (Hard Rule 4) — only file:line + type.
+ */
+export declare const CI_IAC_LEAK_SHAPES: readonly {
+    kind: string;
+    description: string;
+    re: RegExp;
+}[];
 /**
  * Scan text for credential patterns and replace every occurrence with a
  * `[REDACTED <type>@<line> in <file>]` marker (file omitted when `filePath`
@@ -50,6 +104,61 @@ export type RedactResult = {
  * line-sorted findings summary (`{ line, type }`).
  */
 export declare function redactSecrets(text: string, filePath?: string): RedactResult;
+/** One `scanSecrets` finding: file + 1-based line + credential type ONLY —
+ * never the secret value (mstar-audit Hard Rule 4). */
+export type ScannedSecret = {
+    file: string;
+    line: number;
+    type: string;
+};
+/**
+ * Read-only per-line secret scan over the given files. Report-only by
+ * design — it never redacts, never writes, and its findings carry
+ * `file:line` + credential type only (Hard Rule 4). Patterns come from the
+ * D-2 SSOT tables above (`WHOLE_MATCH_PATTERNS`, `VALUE_PATTERNS`) plus the
+ * never-commit filename list (`NEVER_COMMIT_FILENAMES`) and CI/IaC leak
+ * shapes (`CI_IAC_LEAK_SHAPES`). Safe-placeholder spans are masked before
+ * pattern evaluation (only the span — a key beside it still fires). Files
+ * that cannot be read are counted in `unreadableFiles` instead of being
+ * silently skipped: a security gate must never report clean over input it
+ * could not inspect (qc1 W-002).
+ */
+/** Result of {@link scanSecrets}: findings plus how many selected files
+ * could not be read (fail-closed signal for CLI gates). */
+export type ScanSecretsResult = {
+    findings: ScannedSecret[];
+    unreadableFiles: number;
+};
+export declare function scanSecrets(files: readonly string[]): ScanSecretsResult;
+/** Kinds of supply-chain findings (B-11): lockfile presence/duplication at
+ * install boundaries and GitHub Actions pin/exposure shapes. */
+export type SupplyChainFindingKind = "lockfile-missing" | "lockfile-duplicate" | "action-unpinned" | "pull_request_target-head";
+export type SupplyChainFinding = {
+    kind: SupplyChainFindingKind;
+    file: string;
+    line?: number;
+};
+/** Result of {@link supplyChainChecks}: gate verdict + machine findings. */
+export type SupplyChainResult = GateResult & {
+    findings: SupplyChainFinding[];
+};
+/**
+ * Deterministic supply-chain checks over `repoRoot` (read-only):
+ * - `lockfile-missing`: no recognized lockfile at the repo root
+ *   (package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock[b] /
+ *   Cargo.lock / poetry.lock / uv.lock / Gemfile.lock / composer.lock).
+ * - `lockfile-duplicate`: two or more distinct lockfiles at the root —
+ *   ambiguous install boundaries.
+ * - `action-unpinned`: `.github/workflows/*.yml` steps using mutable refs
+ *   (`@main`, `@master`, `@latest` or any non-SHA ref).
+ * - `pull_request_target-head`: a workflow triggers on `pull_request_target`
+ *   AND checks out the PR head — untrusted code with secrets access.
+ *
+ * Tri-age judgment (reachable / runtime-relevant) is deliberately left to
+ * the reviewer (C-class). Violation codes mirror finding kinds with the
+ * `audit.supply.` prefix; `ok` is false iff any finding exists.
+ */
+export declare function supplyChainChecks(repoRoot: string): SupplyChainResult;
 /** One audit finding, shaped after finding-format.md. */
 export type AuditFinding = {
     title: string;
@@ -57,7 +166,7 @@ export type AuditFinding = {
     impact: string;
     effort: AuditEffort;
     risk: AuditRisk;
-    confidence: "HIGH" | "MED" | "LOW";
+    confidence: AuditConfidence;
     evidence: readonly string[];
     priority: AuditPriority;
     fixSketch?: string;
@@ -78,6 +187,15 @@ export type ScaffoldAuditPlanOptions = {
         title: string;
         reason: string;
     }[];
+    needsVerification?: readonly {
+        lead: string;
+        how: string;
+        evidence?: string;
+    }[];
+    hardeningChecked?: readonly {
+        kind: "Hardening" | "Checked and clean";
+        text: string;
+    }[];
 };
 /** Result of `scaffoldAuditPlan`. `nextNumber` is the next free plan number
  * (monotonic continuation vs. any pre-existing `NNN-*.md` files). */
@@ -94,7 +212,12 @@ export type ScaffoldAuditPlanResult = {
  * directory already contains `NNN-*.md` files (same-date re-run), the new
  * batch continues after the highest existing number instead of restarting
  * at 001, and the rebuilt index includes the pre-existing plans. Rejected
- * findings render in the "considered and rejected" section.
+ * findings render in the "considered and rejected" section. Security
+ * dispositions (`needsVerification` / `hardeningChecked`) render in their
+ * documented index sections. Policy: a SUPPLIED option is the authoritative
+ * current set and replaces the section (resolved leads can be removed,
+ * revised entries updated); an OMITTED option carries the previous section
+ * over from the existing README so hand-added entries survive the rebuild.
  */
 export declare function scaffoldAuditPlan(outDir: string, findings: readonly AuditFinding[], options?: ScaffoldAuditPlanOptions): ScaffoldAuditPlanResult;
 /** Options for `promoteAuditPlans`. `harnessDir` is required — the snapshot