@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/collectors/cred-stores.js

@@ -1,21 +1,10 @@
 "use strict";
 
 /**
- * lib/collectors/cred-stores.js
- *
- * Companion collector for the `cred-stores` playbook. Inspects local
- * credential carriers (~/.aws/credentials, ~/.kube/config, ~/.docker/
- * config.json, ~/.npmrc, ~/.pypirc, ~/.config/gcloud/application_
- * default_credentials.json, project-level .npmrc / .pypirc), and
- * flips signal_overrides for the deterministic indicators. Defers
- * non-deterministic indicators (ssh-key-rsa-short-bits, ssh-key-old,
- * gpg-key-old-or-weak, all-stores-empty-or-federated) so the runner
+ * Companion collector for the `cred-stores` playbook. Reads $HOME credential
+ * dotfiles plus project .npmrc / .pypirc under cwd, flipping signal_overrides
+ * for the deterministic indicators only — the rest stay unset so the runner
  * returns inconclusive rather than a forced miss.
- *
- * Scope: $HOME credential dotfiles + project-level .npmrc / .pypirc
- * under cwd. Posix-mode-bits indicators are skipped on win32 (ACL
- * audit out of scope).
- *
  * Interface: see lib/collectors/README.md
  */
 
@@ -31,10 +20,8 @@ function readSafe(full, max = 512 * 1024) {
     fd = fs.openSync(full, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd) loops to EOF — a single readSync can come back short on a
+    // network fd and NUL-fill the tail. Reading the open fd is also TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -54,8 +41,6 @@ function fileExists(full) {
   try { return fs.statSync(full).isFile(); } catch { return false; }
 }
 
-// AWS credentials INI: any [profile] block carrying
-// `aws_access_key_id` AND no `sso_session` / `credential_process`.
 function parseAwsCredentials(content) {
   if (!content) return { staticProfiles: [], federatedProfiles: [], staticKeys: {} };
   const lines = content.split(/\r?\n/);
@@ -77,22 +62,13 @@ function parseAwsCredentials(content) {
   }
   const staticProfiles = [];
   const federatedProfiles = [];
-  // Per-static-profile aws_access_key_id, so doc-fixture demotion can key off
-  // the exact parsed value instead of re-finding the first name-matching block.
-  // A duplicate profile name resolves to the LAST occurrence's keys here, which
-  // is the same precedence the AWS SDK applies.
+  // Per-profile aws_access_key_id. A duplicate profile name resolves to the last
+  // occurrence, the precedence the AWS SDK applies.
   const staticKeys = {};
   for (const [name, kv] of Object.entries(profiles)) {
     const hasKey = !!kv["aws_access_key_id"];
-    // role_arn is NOT a federation marker for this predicate. A profile that
-    // carries a static aws_access_key_id (AKIA*) alongside a role_arn is the
-    // canonical source_profile/assume-role setup where the static key IS the
-    // long-lived credential that bootstraps the assumed role — a real static-key
-    // exposure. The playbook's aws-static-key-present predicate lists only
-    // sso_session / credential_process as federation; treating role_arn as
-    // federation here suppressed a genuinely-present IAM user key. A pure
-    // assume-role profile (role_arn, no own access key) is still excluded by the
-    // hasKey gate below.
+    // role_arn is not federation: a static key alongside role_arn is the
+    // source_profile bootstrap. Federation is sso_session / credential_process.
     const hasFederation = !!(kv["sso_session"] || kv["credential_process"]);
     if (hasKey && !hasFederation) {
       staticProfiles.push(name);
@@ -103,14 +79,10 @@ function parseAwsCredentials(content) {
   return { staticProfiles, federatedProfiles, staticKeys };
 }
 
-// kubeconfig: users[].user.token field present (non-empty) with no
-// users[].user.exec sibling. Use a tolerant line-based scan rather
-// than pulling a YAML parser into the stdlib-only contract.
+// kubeconfig: a non-empty users[].user.token with no users[].user.exec sibling.
+// Line-based rather than parsed, to stay inside the stdlib-only contract.
 function parseKubeConfig(content) {
   if (!content) return { hasStaticToken: false, hasExec: false };
-  // Find every users: block + each `- name: ...` user entry and
-  // its sub-keys. The kubeconfig schema is regular enough that a
-  // line-window scan is reliable.
   const lines = content.split(/\r?\n/);
   let inUsers = false;
   let userIndent = -1;
@@ -129,7 +101,6 @@ function parseKubeConfig(content) {
         continue;
       }
       if (buf.length) {
-        // If we leave the users list (dedent), close current block.
         if (raw.trim() === "" || /^\S/.test(raw)) {
           if (/^\S/.test(raw) && !/^users:/.test(raw)) {
             blocks.push(buf.join("\n")); buf = [];
@@ -143,11 +114,8 @@ function parseKubeConfig(content) {
   }
   if (buf.length) blocks.push(buf.join("\n"));
 
-  // Match `token:` / `token-data:` ONLY at the user-block indent level
-  // (i.e. inside `user:`). Auth-provider blocks carry sub-keys like
-  // `access-token`, `id-token`, `refresh-token` which are dynamic /
-  // cached tokens, not static-credential evidence. Use a line-prefix
-  // anchor + auth-provider-vs-user proximity check to refuse those.
+  // `token:` / `token-data:` counts only under `user:` — an auth-provider block's
+  // tokens are cached dynamic ones, not static-credential evidence.
   let hasStaticToken = false;
   let hasExec = false;
   const userKvRe = /^(\s+)(token|token-data)\s*:\s*(\S[^\n]*)/gm;
@@ -157,16 +125,12 @@ function parseKubeConfig(content) {
     let blockHasStatic = false;
     for (const m of block.matchAll(userKvRe)) {
       const upto = block.slice(0, m.index);
-      // Indentation-agnostic key anchors: a kubeconfig may use 2-space, 4-space,
-      // or tab indentation. Hardcoding "\n  user:" missed a user-level static
-      // token under any other indentation and mislabeled it as an auth-provider
-      // (dynamic) token.
+      // Indentation-agnostic anchors: kubeconfig indent varies, and a fixed-width
+      // anchor mislabels a user-level static token as an auth-provider one.
       const userMatches = [...upto.matchAll(/\n[ \t]*user\s*:/g)];
       const lastUserAt = userMatches.length ? userMatches[userMatches.length - 1].index : -1;
       const apMatches = [...upto.matchAll(/\n[ \t]*auth-provider\s*:/g)];
       const lastAuthProviderAt = apMatches.length ? apMatches[apMatches.length - 1].index : -1;
-      // Reject when the closest enclosing key is auth-provider rather
-      // than user — those are dynamic tokens, not static credentials.
       if (lastAuthProviderAt > lastUserAt) continue;
       const value = m[3];
       if (!value || value.startsWith("null")) continue;
@@ -236,7 +200,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const presence = {};
   for (const [id, p] of Object.entries(carriers)) presence[id] = fileExists(p);
 
-  // Read carriers we care about.
   const awsCredsContent = presence["aws-credentials"] ? readSafe(carriers["aws-credentials"]) : null;
   const awsCfgContent = presence["aws-config"] ? readSafe(carriers["aws-config"]) : null;
   const kubeContent = presence["kube-config"] ? readSafe(carriers["kube-config"]) : null;
@@ -247,28 +210,18 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const pypirProjContent = presence["pypirc-project"] ? readSafe(carriers["pypirc-project"]) : null;
   const gcloudAdcContent = presence["gcloud-adc"] ? readSafe(carriers["gcloud-adc"]) : null;
 
-  // Indicator predicates.
   const awsCredsParsed = parseAwsCredentials(awsCredsContent);
   const awsCfgParsed = parseAwsCredentials(awsCfgContent);
   const ssoCacheFiles = (() => {
     try { return fs.readdirSync(ssoCacheDir).filter(f => f.endsWith(".json")); }
     catch { return []; }
   })();
-  // aws-static-key-present: any AKIA* key with no federation. Apply
-  // the playbook's catalogued FP[0] (AWS-published doc-fixture key)
-  // and FP[2] (break-glass profile-name pattern) directly in the
-  // collector — they're deterministic and the collector has the
-  // evidence locally. FP[1] requires `aws sts get-caller-identity`
-  // which is out of stdlib scope, so the collector cannot attest it;
-  // the runner downgrades hit → inconclusive with that one
-  // unsatisfied, which is the honest outcome.
+  // aws-static-key-present: any AKIA* key with no federation. FP[0] doc-fixture
+  // key and FP[2] break-glass profile are deterministic and applied here.
   const AWS_DOC_FIXTURE_KEY = "AKIAIOSFODNN7EXAMPLE";
   const realAwsProfiles = awsCredsParsed.staticProfiles.filter(p => {
-    // Demote off this profile's EXACT parsed key value (FP[0]) and its name
-    // (FP[2]). Keying off the parsed value — not the first raw block whose
-    // name matches — means a duplicate profile name whose first occurrence
-    // holds the doc-fixture key cannot demote the later real key under the
-    // same name (the parser resolves the live last-occurrence value).
+    // Demote on the exact parsed key, so a duplicate name whose first occurrence
+    // holds the fixture key cannot demote the real one.
     const keyVal = awsCredsParsed.staticKeys[p];
     if (keyVal === AWS_DOC_FIXTURE_KEY) return false; // FP[0]
     if (/^breakglass-/i.test(p) || /^break-glass-/i.test(p)) return false; // FP[2]
@@ -280,15 +233,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const gcloudParsed = parseGcloudAdc(gcloudAdcContent);
   const dockerParsed = parseDockerConfig(dockerContent);
 
-  // docker-cleartext-auth FP checks (per playbook):
-  //   FP[0] — vendor-token user pattern (decoded `user:pass`) is
-  //           `<token>` / `AWS` / `oauth2accesstoken` / a zero-UUID;
-  //           treat as a deliberately published convention, demote.
-  //   FP[1] — local-only registry (loopback IP, *.local, *.svc.
-  //           cluster.local, kind.local) on a dev workstation, demote.
-  //   FP[2] — global credsStore overrides per-registry omission —
-  //           the collector already accounts for this via
-  //           parseDockerConfig.hasCredHelper.
+  // docker-cleartext-auth FP checks: FP[0] vendor-token user in the decoded
+  // `user:pass`, FP[1] local-only registry, FP[2] a global credsStore, which
+  // parseDockerConfig already folds into hasCredHelper.
   const VENDOR_TOKEN_USERS = new Set([
     "<token>", "AWS", "oauth2accesstoken",
     "00000000-0000-0000-0000-000000000000",
@@ -324,10 +271,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     (pypirHomeContent && PYPI_TOKEN_RE.test(pypirHomeContent)) ||
     (pypirProjContent && PYPI_TOKEN_RE.test(pypirProjContent));
 
-  // credentials-file-bad-perms: POSIX only. Any of the listed
-  // carriers with mode != 0600. Per playbook the indicator covers
-  // `~/.config/gcloud/*` too, so include the gcloud ADC file (and
-  // its parent dir mode != 0700 expectation per the spec).
+  // credentials-file-bad-perms: POSIX only — carriers at 0600, the gcloud dir at 0700.
   let credsFileBadPerms;
   const permViolations = [];
   if (isPosix) {
@@ -342,8 +286,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     ];
     for (const [id, p, expectedMode] of permTargets) {
       if (!presence[id]) continue;
-      // FP[1]: 0-byte placeholder OR symlink to broker socket / tmpfs —
-      // mode bits don't carry the same blast radius. Skip these.
+      // FP[1]: a 0-byte placeholder or a symlink to a broker socket carries no
+      // blast radius in its mode bits.
       let lstat;
       try { lstat = fs.lstatSync(p); } catch { continue; }
       if (lstat.size === 0) continue;
@@ -354,7 +298,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
         permViolations.push({ id, mode_octal: "0" + m.toString(8) });
       }
     }
-    // Also check the gcloud directory itself (expected 0700 per spec).
     const gcloudDir = path.join(home, ".config", "gcloud");
     try {
       const gs = fs.statSync(gcloudDir);
@@ -380,28 +323,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     signal_overrides["credentials-file-bad-perms"] = credsFileBadPerms;
   }
 
-  // Per-indicator __fp_checks attestation. The runner gates a 'hit'
-  // verdict on false_positive_checks_required[] entries; an
-  // unsatisfied check downgrades to 'inconclusive'. Attest exactly
-  // the checks the collector itself ran (don't attest network /
-  // operator-judgement checks). Use the index-keyed form because
-  // false_positive_checks_required entries are free-text prose, not
-  // ids — the index is the stable cross-reference.
-  //
-  //   aws-static-key-present:
-  //     [0] doc-fixture demotion (AKIAIOSFODNN7EXAMPLE) — DONE
-  //     [1] live-key sts check — NOT DONE (needs network)
-  //     [2] break-glass profile-name pattern — DONE
-  //
-  //   docker-cleartext-auth:
-  //     [0] vendor-token user pattern — DONE
-  //     [1] local-only registry — DONE
-  //     [2] global credsStore — DONE
-  //
-  //   credentials-file-bad-perms:
-  //     [0] Windows / WSL skip — DONE (POSIX guard)
-  //     [1] 0-byte / symlink skip — DONE
-  //     [2] ACL-by-design (operator interview) — NOT DONE
+  // Per-indicator __fp_checks attestation: the runner downgrades a 'hit' to
+  // 'inconclusive' for every unattested false_positive_checks_required[] entry.
+  // Keys are indices into it; aws[1] (network) and perms[2] stay unattested.
   if (awsStaticKey) {
     signal_overrides["aws-static-key-present__fp_checks"] = { "0": true, "2": true };
   }
@@ -412,11 +336,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     signal_overrides["credentials-file-bad-perms__fp_checks"] = { "0": true, "1": true };
   }
 
-  // Artifact-level captures (one entry per artifact id in
-  // data/playbooks/cred-stores.json look.artifacts[]). We only
-  // populate the ones the collector actually reads; the rest are
-  // marked captured=false with a "reason" so the runner records
-  // partial-evidence coverage rather than a phantom miss.
+  // One entry per artifact id in data/playbooks/cred-stores.json look.artifacts[].
+  // What cannot be read is captured=false with a reason, not a phantom miss.
   const artifacts = {
     "aws-credentials": presence["aws-credentials"]
       ? { value: `present (${awsCredsParsed.staticProfiles.length} static profile(s), ${awsCredsParsed.federatedProfiles.length} federated)`, captured: true }
@@ -470,12 +391,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       captured: false,
       reason: "secret-tool / security dump-keychain require interactive auth or platform-specific binaries; out of stdlib collector scope",
     },
-    // Surface the POSIX-mode-bit skip on Windows so operators see the
-    // indicator was considered but skipped, mirroring the secrets
-    // collector's world-writable-secret-files skip artifact. Without
-    // this, credentials-file-bad-perms silently absent from
-    // signal_overrides looks indistinguishable from "indicator not
-    // catalogued".
+    // Names the win32 skip explicitly; an absent override would look uncatalogued.
     "credentials-file-perms-check": isPosix
       ? {
           value: permViolations.length > 0

package/lib/collectors/crypto-codebase.js

@@ -1,17 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/crypto-codebase.js
- *
- * Companion collector for the `crypto-codebase` playbook. Walks the
- * cwd tree, grepping source files for hash / cipher / KEX / signature
- * / KDF / RNG / TLS / PQC / FIPS call sites. Flips signal_overrides
- * only for indicators whose verdict can be determined deterministically
- * from the codebase scan; behavioral indicators that require operator
- * judgement (e.g. crypto-agility abstraction shape) are left unflipped
- * so the runner returns inconclusive rather than a forced miss.
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `crypto-codebase` playbook: greps the cwd source
+ * tree for hash / cipher / KEX / signature / KDF / RNG / TLS / PQC / FIPS call
+ * sites. Interface: see lib/collectors/README.md
  */
 
 const fs = require("node:fs");
@@ -21,10 +13,7 @@ const { codeExcludeSet, walkTree, buildEvidenceLocations, lineFromOffset } = req
 const COLLECTOR_ID = "crypto-codebase";
 
 const DEFAULT_MAX_DEPTH = 6;
-// Shared code-scope exclusions: dependency caches, build output, VCS +
-// agent/editor scratch (including `.claude/`). No crypto-codebase-specific
-// extras — the shared defaults already cover every directory this scan
-// should never descend into.
+// Shared code-scope exclusions; no collector-specific extras needed.
 const DEFAULT_EXCLUDES = codeExcludeSet();
 
 const SOURCE_EXTS = new Set([
@@ -41,12 +30,9 @@ const SOURCE_EXTS = new Set([
   ".m", ".mm",
 ]);
 
-// The exact marker set the crypto-codebase playbook's `repo-has-source-tree`
-// gate evaluates (data/playbooks/crypto-codebase.json: exists_any([...])).
-// The collector attests the gate by mirroring this predicate against the
-// scanned cwd — NOT by counting SOURCE_EXTS files — so a valid package repo
-// whose only marker is a manifest or an empty src/ dir (no extension-matched
-// source yet) still attests true, matching what the gate would compute.
+// The exact marker set the playbook's `repo-has-source-tree` gate evaluates
+// (data/playbooks/crypto-codebase.json: exists_any([...])). Mirrored here, NOT
+// counted from SOURCE_EXTS files, so an empty src/ attests what the gate computes.
 const SOURCE_TREE_MARKERS = [
   "package.json", "pyproject.toml", "go.mod", "Cargo.toml",
   "pom.xml", "build.gradle", "src", "lib", "crates",
@@ -57,10 +43,7 @@ const TEST_PATH_SEGMENTS = [
   "/fixtures/", "/fixture/", "/examples/", "/example/",
   "/docs/", "/doc/", "/sample/", "/samples/", "/demo/", "/demos/",
   "/benchmarks/", "/benchmark/", "/bench/",
-  // Files whose purpose is grepping for these patterns — their source
-  // literally contains the patterns, so production-scope scans would
-  // match the scanner itself. The crypto-codebase playbook's intent
-  // is the consumer's source, not the scanner's regex catalogue.
+  // These files contain the scan patterns; scanning them matches the scanner.
   "/lib/collectors/", "/scripts/check-version-tags",
 ];
 
@@ -71,19 +54,15 @@ function isTestPath(rel) {
   for (const seg of TEST_PATH_SEGMENTS) {
     if (norm.includes(seg)) return true;
   }
-  // `foo.test.js`, `bar.spec.py` (dot-separated)
   if (/\.(test|spec)\.[a-z]+$/i.test(rel)) return true;
-  // `foo_test.go` (Go convention), `_test.py` (some Python projects)
+  // Go's `foo_test.go` convention.
   if (/(?:^|[\\/])[^\\/]+_test\.[a-z]+$/i.test(rel)) return true;
   return false;
 }
 
 function readSafe(full) {
   try {
-    // Read raw bytes, enforce the 1 MB cap on the buffer length, then decode.
-    // Replaces a statSync-before-read on the hot path with a single read; the
-    // cap is byte-based, so Buffer.length is the correct measure and an
-    // oversized file is rejected before any UTF-8 decode.
+    // The cap is byte-based: enforced on the buffer, before any UTF-8 decode.
     const raw = fs.readFileSync(full);
     if (raw.length > MAX_FILE_BYTES) return null;
     return raw.toString("utf8");
@@ -91,25 +70,15 @@ function readSafe(full) {
 }
 
 const WEAK_HASH_RE = /(?:crypto\.createHash\(\s*['"](?:md5|sha1|sha-1)['"]|hashlib\.(?:md5|sha1)\s*\(|MessageDigest\.getInstance\(\s*['"](?:MD5|SHA-1|SHA1)['"]|crypto\/(?:md5|sha1)\b|Digest::(?:MD5|SHA1)\b)/i;
-// Token vocabulary signaling a SECURITY-CRITICAL use of the hash
-// primitive (not content-fingerprinting / cache-key / build-id usage,
-// where MD5 / SHA-1 are legitimate by design).
-//
-// "integrity" was previously in this set but matched non-security
-// integrity contexts (Hugo's content-integrity fingerprinting, sphinx
-// docs build-ids, etag generators) — too broad. Drop it; the
-// remaining vocabulary still catches crypto-security uses.
+// Token vocabulary signalling a SECURITY-CRITICAL use of the hash primitive, as
+// opposed to fingerprinting / cache-key / build-id use where MD5 and SHA-1 are
+// legitimate. "integrity" stays out: it also matches fingerprinting and etags.
 const WEAK_HASH_VAR_FLOW_RE = /(hmac|sign|signature|token|jwt|verify|password|hash[-_]?(?:credential|secret|password|key|auth))/i;
-// Strong, unambiguous security-context tokens. When ANY of these
-// appear in the file content, the hit fires regardless of the
-// filename — a file named `hashing.go` that genuinely uses MD5 on
-// a `password` / `token` / `jwt` is a real positive, no matter
-// what the filename suggests.
+// Unambiguous security-context tokens: any of these fires the hit regardless of
+// the filename — `hashing.go` running MD5 over a `password` is a real positive.
 const STRONG_SECURITY_VAR_RE = /\b(token|password|jwt|secret|credential|api[-_]?key|access[-_]?key|private[-_]?key)\b/i;
-// Filename-path demotion candidates: paths that suggest
-// content-addressable / fingerprint / etag / cache-key concerns.
-// Demotion fires only when STRONG_SECURITY_VAR_RE did NOT match —
-// the filename is a tiebreaker, never an override.
+// Paths suggesting fingerprint / etag / cache-key concerns. Demotion fires only
+// when STRONG_SECURITY_VAR_RE did NOT match: the filename is a tiebreaker only.
 const NON_SECURITY_HASH_FILE_RE = /(?:^|[\\/])(?:integrity|hashing|fingerprint|content[-_]?hash|cache[-_]?key|etag|build[-_]?id)\.(?:go|py|rs|java|js|ts|rb|php|cs|swift|m|cpp|cc|c|h|hpp)$/i;
 
 const WEAK_CIPHER_ECB_RE = /(?:aes-\d+-ecb|AES\/ECB\/|Cipher\.getInstance\(\s*['"]AES['"]\s*\))/i;
@@ -124,31 +93,17 @@ const SECURITY_VAR_RE = /\b(?:token|secret|key|salt|nonce|iv|seed|state|jwt|jti|
 const PBKDF2_BLOCK_GLOBAL_RE = /\b(?:pbkdf2(?:Sync)?|hashlib\.pbkdf2_hmac)\s*\([^)]{0,400}/g;
 
 const BCRYPT_BLOCK_GLOBAL_RE = /\b(?:bcrypt\.(?:hash|hashSync|gen_salt|genSalt|genSaltSync)|BCrypt::Password\.create)\s*\([^)]{0,200}/g;
-// Captures either named-arg form (`cost: 12` / `rounds=12`) or the
-// positional-arg trailing-integer form. Match against the block
-// captured by BCRYPT_BLOCK_GLOBAL_RE — which truncates at the first
-// `)`, so the trailing-int branch must match `, <digits>` followed
-// by either end-of-block or whitespace, not a closing paren.
+// Named-arg form (`cost: 12` / `rounds=12`) or the positional trailing integer.
+// The captured block truncates at the first `)`, so the trailing-int branch ends
+// at end-of-block, not at a paren.
 const BCRYPT_COST_RE = /(?:cost|rounds)\s*[:=]\s*(\d+)|,\s*(\d+)\s*$/;
 
-// `hardcoded-key-material` is a SECRET-leak signal, so it must match only an
-// actual embedded private key — a full PEM block: a `BEGIN ... PRIVATE KEY`
-// header, a base64 body, and a matching `END` marker.
-//
-//   - Public keys and certificates are published by design (BIMI trust
-//     anchors, release-signing public keys, autoupdate pubkeys), so the
-//     header is `PRIVATE KEY` only.
-//   - Requiring the base64 body + `END` marker distinguishes a real pasted
-//     key from a bare marker used as a *detection pattern* (a redaction
-//     library's `/-----BEGIN OPENSSH PRIVATE KEY-----/` regex literal) or a
-//     documentation placeholder (`privateKeyPem: "-----BEGIN PRIVATE KEY-----
-//     ..."`), neither of which carries a body or an `END`.
-//
-// The body class is base64 + whitespace only; `-` is excluded so the run
-// halts at the first `-` of `-----END` — no backtracking, ReDoS-safe. The
-// `-----END` requirement is the primary discriminator (detectors and
-// placeholders have no closing marker); the {20,4000} bound additionally
-// rejects the ~1-char run a bare marker leaves before the next punctuation.
+// `hardcoded-key-material` matches only a full PEM block: a `BEGIN ... PRIVATE
+// KEY` header, a base64 body, and a matching `END`. Public keys and certificates
+// are published by design, so the header is PRIVATE KEY only; requiring the body
+// and the `END` separates a pasted key from a bare marker in a detection pattern
+// or a placeholder. The body class excludes `-`, so the run halts at the first
+// `-` of `-----END`, with no backtracking.
 const PEM_PRIVATE_RE = /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----[A-Za-z0-9+/=\s]{20,4000}-----END/;
 
 const TLS_OLD_PROTO_RE = /(?:secureProtocol\s*:\s*['"](?:TLSv1_method|TLSv1_1_method|SSLv23_method|SSLv3_method)['"]|minVersion\s*:\s*['"]TLSv1(?:\.0|\.1)?['"]|ssl_version\s*=\s*ssl\.PROTOCOL_TLSv1(?:_1)?|MinTlsVersion::TLSv1\b)/i;
@@ -167,17 +122,9 @@ const VENDORED_PQC_NAMES_RE = /(?:kyber|dilithium|sphincs|ml[-_]?kem|ml[-_]?dsa|
 
 function scanWeakHash(content, rel) {
   if (!WEAK_HASH_RE.test(content)) return false;
-  // Strong security tokens fire the indicator regardless of the
-  // filename — a file named `integrity.go` that genuinely uses
-  // md5 on a password is a real positive.
   if (STRONG_SECURITY_VAR_RE.test(content)) return true;
-  // Otherwise the var-flow regex needs to match (hash / hmac /
-  // sign / signature / verify / ...). If neither STRONG nor
-  // WEAK_HASH_VAR_FLOW fired, this isn't a security-context use.
   if (!WEAK_HASH_VAR_FLOW_RE.test(content)) return false;
-  // Var-flow matched a soft / ambiguous keyword. Use the filename
-  // as a tiebreaker: paths like `integrity.go` / `hashing.go` /
-  // `fingerprint.py` indicate content-addressable use, demote.
+  // Only a soft keyword matched, so the filename is the tiebreaker.
   if (rel && NON_SECURITY_HASH_FILE_RE.test(rel)) return false;
   return true;
 }
@@ -202,11 +149,9 @@ function scanPbkdf2(content) {
     let threshold = 210000;
     if (/sha[-_]?256/i.test(block)) threshold = 600000;
     else if (/sha1\b/i.test(block) || /sha-1\b/i.test(block)) threshold = 1300000;
-    // Take the max 4+ digit literal as the iteration count. Don't
-    // pre-filter common key-bit-size values (256/384/512/1024) — a
-    // call like `pbkdf2Sync(pw, salt, 1024, 32, 'sha256')` IS under-
-    // iterated at 1024 and must hit. The max() picks iteration over
-    // keylen in the typical positional shape (iter, keylen, algo).
+    // The max 4+ digit literal is the iteration count. Common key-bit sizes are
+    // deliberately not pre-filtered — `pbkdf2Sync(pw, salt, 1024, 32, 'sha256')`
+    // IS under-iterated — and max() picks iteration over keylen in (iter, keylen).
     const nums = [];
     for (const nm of block.matchAll(/\b(\d{4,8})\b/g)) {
       nums.push(Number(nm[1]));
@@ -297,9 +242,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       if (RSA_1024_RE.test(content)) {
         hits["rsa-1024-anywhere"].push({ file: f.rel });
       }
-      // Attach a 1-based `line` (from the match offset) so the evidence
-      // location carries a SARIF startLine region rather than pointing at
-      // the file. Does not change hit/miss — the same matches still fire.
+      // The 1-based `line` gives the evidence location a SARIF startLine region.
       const mrHits = scanMathRandom(content);
       for (const h of mrHits) hits["math-random-in-security-path"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset) });
 
@@ -317,11 +260,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       }
     }
 
-    // Cross-file evidence for the conditional indicators (ecdsa-
-    // without-pqc-roadmap, no-ml-kem-implementation, fips-claim-
-    // without-runtime-activation). Production-context only — a
-    // PQC / FIPS reference inside `tests/` / `fixtures/` / `examples/`
-    // doesn't count as evidence the library SHIPS that capability.
+    // Cross-file evidence for the conditional indicators, production context only:
+    // a PQC / FIPS reference in tests is not evidence the library SHIPS it.
     if (!isTest) {
       if (CLASSICAL_SIG_RE.test(content)) sawClassicalSig = true;
       if (PQC_SIG_IMPL_RE.test(content)) sawPqcSigImpl = true;
@@ -348,19 +288,13 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const vendoredPqcFiles = files.filter(f => isVendored(f.rel) && VENDORED_PQC_NAMES_RE.test(f.rel));
   let vendoredPqcNoProvenance = "miss";
   if (vendoredPqcFiles.length > 0) {
-    // `MANIFEST.json` / `vendor/MANIFEST.json` is the common provenance
-    // record for a vendored dependency tree (records upstream version,
-    // source URL, license, copied-at commit). This walk only runs for
-    // files already classified as vendored, so a MANIFEST.json found while
-    // climbing the vendor tree is a genuine provenance marker, not a stray
-    // app/package manifest at the repo root.
+    // MANIFEST.json is a common provenance record for a vendored tree. The walk
+    // runs only over already-vendored files, so a hit is a marker, not the root
+    // app manifest.
     const provenanceMarkers = new Set(["_PROVENANCE.json", "UPSTREAM", "ORIGIN", ".upstream-commit", "PROVENANCE.md", "MANIFEST.json"]);
-    // Walk from the file's directory up to the repo root, checking
-    // each ancestor for a provenance marker. The marker can live at
-    // the immediate sibling (`vendor/kyber/_PROVENANCE.json`), at
-    // the vendor root (`vendor/_PROVENANCE.json`), or anywhere in
-    // between for deeply-nested vendor trees. Stop at the repo root
-    // (cwd) so we don't escape into the parent filesystem.
+    // Walk from the file's directory up to the repo root: the marker may sit
+    // beside the file, at the vendor root, or between. Stopping at the root
+    // keeps the search inside the repo.
     let anyMissing = false;
     for (const f of vendoredPqcFiles) {
       let dir = path.dirname(f.full);
@@ -405,28 +339,22 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   if (noMlKemImpl !== undefined) signal_overrides["no-ml-kem-implementation"] = noMlKemImpl;
   if (fipsTheater !== undefined) signal_overrides["fips-claim-without-runtime-activation"] = fipsTheater;
 
-  // Per-indicator __fp_checks attestation for the FP-gated call-site
-  // indicators. Every surviving hit is in a non-test source file (isTest is
-  // excluded before the scan) and, for weak-hash, flows into a security sink
-  // (scanWeakHash). The remaining false_positive_checks_required entries are
-  // legacy-protocol-shim / feature-flag / later-override judgements the
-  // collector does not make, so they stay unattested and the runner keeps
-  // those indicators inconclusive. Without attesting what it DID check, the
-  // collector's real call-site hits are downgraded to inconclusive after run.
+  // __fp_checks attest what the collector actually checked: every surviving hit is
+  // in a non-test source file and, for weak-hash, flows into a security sink. The
+  // unattested entries are judgements it does not make, and stay inconclusive.
   if (signal_overrides["weak-hash-import"] === "hit") {
-    // [0] not under test + non-security-file demotion; [2] hash flows to an
-    // authn/integrity sink. [1] legacy-protocol shim is operator judgement.
+    // [0] not under test, plus non-security-file demotion; [2] the hash flows to
+    //     an authn/integrity sink. [1] legacy-protocol shim is operator judgement.
     signal_overrides["weak-hash-import__fp_checks"] = { "0": true, "2": true };
   }
   if (signal_overrides["weak-cipher-mode"] === "hit") {
-    // [0] not under test/KAT-vector path; [2] construction is in a scanned
-    // (production) source file. [1] legacy-protocol-parser scope is operator.
+    // [0] not under a test / KAT-vector path; [2] the construction is in a
+    //     production source file. [1] legacy-protocol-parser scope is operator.
     signal_overrides["weak-cipher-mode__fp_checks"] = { "0": true, "2": true };
   }
   if (signal_overrides["tls-old-protocol"] === "hit") {
-    // [0] the hit is in non-test production code, not a test asserting the
-    // library REJECTS the legacy protocol. [1] feature-flag-default-off and
-    // [2] later-override are not inspected by the collector.
+    // [0] the hit is production code, not a test asserting the library REJECTS the
+    //     legacy protocol. [1] feature-flag default and [2] later override are not.
     signal_overrides["tls-old-protocol__fp_checks"] = { "0": true };
   }
 
@@ -488,15 +416,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     },
   };
 
-  // Per-indicator file locations for the call-site indicators flipped to
-  // "hit". The cross-file derived indicators (ecdsa-without-pqc-roadmap,
-  // no-ml-kem-implementation, fips-claim-without-runtime-activation,
-  // vendored-pqc-no-provenance) describe a whole-repo state rather than a
-  // single offending file, so they carry no file-level location. The
-  // offset-bearing call-site scans (math-random / pbkdf2 / bcrypt) now record
-  // a 1-based `line`, so their locations include a startLine region; the
-  // remaining whole-file scans (weak-hash / weak-cipher / rsa-1024 /
-  // hardcoded-key / tls) stay file-level (no startLine).
+  // File locations for the call-site indicators flipped to "hit". The cross-file
+  // derived indicators describe a whole-repo state, so they carry no location; the
+  // offset-bearing scans record a line, the whole-file scans stay file-level.
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {
@@ -507,15 +429,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
 
   return {
     precondition_checks: {
-      // Auto-attest the crypto-codebase playbook's own `repo-has-source-tree`
-      // gate by mirroring the gate's own exists_any(SOURCE_TREE_MARKERS)
-      // predicate against the scanned cwd. The runner's autoDetectPreconditions
-      // probes the run process's cwd (not the collected --cwd) and has no
-      // exists_any() branch, so a repo with a recognizable source tree would
-      // otherwise surface a spurious precondition_unverified warning. Keying to
-      // the gate's exact id + predicate mirrors the sbom / library-author
-      // collectors; `repo-context` is not a precondition this playbook
-      // references.
+      // Mirrors the playbook's own exists_any(SOURCE_TREE_MARKERS) predicate
+      // against the scanned cwd. The runner's autoDetectPreconditions probes the
+      // run process's cwd and has no exists_any branch, so without this a real
+      // source tree surfaces a spurious precondition_unverified warning.
       "repo-has-source-tree": SOURCE_TREE_MARKERS.some((m) => fs.existsSync(path.join(cwd, m))),
     },
     artifacts,