sinapse-ai 1.8.0 → 1.9.1

package/.sinapse-ai/git-hooks/lib/framework-guard.js

@@ -0,0 +1,258 @@
+/**
+ * Framework Guard — Pre-commit hook that blocks commits to L1/L2 protected paths.
+ *
+ * Reads ALL configuration from core-config.yaml (single source of truth):
+ *   - boundary.frameworkProtection: toggle (true/false)
+ *   - boundary.protected: L1/L2 blocked glob patterns
+ *   - boundary.exceptions: L3 allowed glob patterns
+ *
+ * When frameworkProtection is true (default), blocks staged changes to protected paths.
+ * When false, acts as a no-op (contributor mode).
+ *
+ * Story: BM-3 (Epic: Boundary Mapping & Framework-Project Separation)
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Hardcoded fallbacks — used ONLY if core-config.yaml is missing or malformed.
+// The canonical source is core-config.yaml boundary.protected/exceptions.
+const FALLBACK_PROTECTED = [
+  '.sinapse-ai/core/**',
+  '.sinapse-ai/development/tasks/**',
+  '.sinapse-ai/development/templates/**',
+  '.sinapse-ai/development/checklists/**',
+  '.sinapse-ai/development/workflows/**',
+  '.sinapse-ai/infrastructure/**',
+  '.sinapse-ai/constitution.md',
+  'bin/sinapse.js',
+  'bin/sinapse-init.js',
+];
+
+const FALLBACK_EXCEPTIONS = [
+  '.sinapse-ai/data/**',
+  '.sinapse-ai/development/agents/*/MEMORY.md',
+];
+
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports: ** (any depth), * (single segment), literal dots.
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegex(glob) {
+  // 1. Replace ** with placeholder before processing
+  let pattern = glob.replace(/\*\*/g, '\u0000');
+
+  // 2. Escape all regex-special chars (dots, plus, etc.) — but NOT * or placeholder
+  pattern = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+
+  // 3. Convert remaining single * to single-segment matcher
+  pattern = pattern.replace(/\*/g, '[^/]+');
+
+  // 4. Restore ** placeholder to any-depth matcher
+  pattern = pattern.replace(/\u0000/g, '.+');
+
+  // If pattern ends with .+ (was **), match prefix
+  if (glob.endsWith('**')) {
+    return new RegExp('^' + pattern);
+  }
+  // Exact file match
+  return new RegExp('^' + pattern + '$');
+}
+
+/**
+ * Read the raw content of core-config.yaml.
+ *
+ * Resolution order (so this works both as the in-repo hook AND when bundled
+ * into .sinapse-ai/git-hooks/lib/ by the installer, where __dirname no longer
+ * sits two levels under the project root):
+ *   1. `<cwd>/.sinapse-ai/core-config.yaml` — git runs hooks from the repo root,
+ *      so cwd is the project root in the pre-commit path.
+ *   2. `<__dirname>/../../.sinapse-ai/core-config.yaml` — the original in-repo
+ *      location (bin/utils -> repo root), kept for direct/test invocation.
+ * @returns {string|null}
+ */
+function readConfigContent() {
+  const candidates = [
+    path.resolve(process.cwd(), '.sinapse-ai/core-config.yaml'),
+    path.resolve(__dirname, '../../.sinapse-ai/core-config.yaml'),
+  ];
+  for (const configPath of candidates) {
+    if (fs.existsSync(configPath)) {
+      return fs.readFileSync(configPath, 'utf8');
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse a YAML list under a given key using simple line-based parsing.
+ * Avoids js-yaml dependency for speed.
+ * @param {string} content - YAML file content
+ * @param {string} parentKey - Parent key (e.g., 'boundary')
+ * @param {string} listKey - List key (e.g., 'protected')
+ * @returns {string[]}
+ */
+function parseYamlList(content, parentKey, listKey) {
+  const lines = content.split('\n');
+  const items = [];
+  let inParent = false;
+  let inList = false;
+  let parentIndent = -1;
+  let listIndent = -1;
+
+  for (const line of lines) {
+    const trimmed = line.trimStart();
+    const indent = line.length - trimmed.length;
+
+    // Find parent key (e.g., "boundary:")
+    if (trimmed === parentKey + ':' || trimmed.startsWith(parentKey + ':')) {
+      inParent = true;
+      parentIndent = indent;
+      continue;
+    }
+
+    // If we're past the parent section (back to same or lower indent)
+    if (inParent && indent <= parentIndent && trimmed.length > 0 && !trimmed.startsWith('#')) {
+      inParent = false;
+      inList = false;
+    }
+
+    if (!inParent) continue;
+
+    // Find list key within parent (e.g., "protected:")
+    if (trimmed === listKey + ':' || trimmed.startsWith(listKey + ':')) {
+      inList = true;
+      listIndent = indent;
+      continue;
+    }
+
+    // If we're past the list (back to same or lower indent within parent)
+    if (inList && indent <= listIndent && trimmed.length > 0 && !trimmed.startsWith('#') && !trimmed.startsWith('-')) {
+      inList = false;
+    }
+
+    // Collect list items
+    if (inList && trimmed.startsWith('- ')) {
+      items.push(trimmed.slice(2).trim());
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Read boundary config from core-config.yaml.
+ * @returns {{ enabled: boolean, protected: string[], exceptions: string[] }}
+ */
+function readBoundaryConfig() {
+  const content = readConfigContent();
+  if (!content) {
+    return { enabled: true, protected: FALLBACK_PROTECTED, exceptions: FALLBACK_EXCEPTIONS };
+  }
+
+  // Read toggle
+  const toggleMatch = content.match(/frameworkProtection:\s*(true|false)/);
+  const enabled = toggleMatch ? toggleMatch[1] === 'true' : true;
+
+  // Read lists
+  const protectedPaths = parseYamlList(content, 'boundary', 'protected');
+  const exceptionPaths = parseYamlList(content, 'boundary', 'exceptions');
+
+  return {
+    enabled,
+    protected: protectedPaths.length > 0 ? protectedPaths : FALLBACK_PROTECTED,
+    exceptions: exceptionPaths.length > 0 ? exceptionPaths : FALLBACK_EXCEPTIONS,
+  };
+}
+
+/**
+ * Check if a file path matches any pattern in the list.
+ * @param {string} filePath
+ * @param {RegExp[]} patterns
+ * @returns {boolean}
+ */
+function matchesAny(filePath, patterns) {
+  return patterns.some((pattern) => pattern.test(filePath));
+}
+
+/**
+ * Get list of staged files from git.
+ * @returns {string[]}
+ */
+function getStagedFiles() {
+  try {
+    const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+    return output
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  // Step 1: Read config (single source of truth)
+  const config = readBoundaryConfig();
+
+  if (!config.enabled) {
+    process.exit(0);
+  }
+
+  // Step 2: Compile glob patterns to regex
+  const blockedPatterns = config.protected.map(globToRegex);
+  const allowedPatterns = config.exceptions.map(globToRegex);
+
+  // Step 3: Get staged files
+  const stagedFiles = getStagedFiles();
+  if (stagedFiles.length === 0) {
+    process.exit(0);
+  }
+
+  // Step 4: Check each staged file
+  const blockedFiles = [];
+  for (const file of stagedFiles) {
+    // Normalize to forward slashes (Windows compat)
+    const normalized = file.replace(/\\/g, '/');
+    if (matchesAny(normalized, blockedPatterns) && !matchesAny(normalized, allowedPatterns)) {
+      blockedFiles.push(normalized);
+    }
+  }
+
+  // Step 5: Report
+  if (blockedFiles.length > 0) {
+    console.error('');
+    console.error('Framework Guard: Commit blocked!');
+    console.error('');
+    console.error('The following framework files are protected (L1/L2):');
+    for (const file of blockedFiles) {
+      console.error(`  - ${file}`);
+    }
+    console.error('');
+    console.error('These files are read-only in project mode (boundary.frameworkProtection: true).');
+    console.error('');
+    console.error('To bypass (framework contributors only):');
+    console.error('  git commit --no-verify');
+    console.error('');
+    console.error('To disable permanently (contributors):');
+    console.error('  Set boundary.frameworkProtection: false in core-config.yaml');
+    console.error('');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// Export for testing
+module.exports = { readBoundaryConfig, globToRegex, matchesAny, getStagedFiles, FALLBACK_PROTECTED, FALLBACK_EXCEPTIONS };
+
+// Run when executed directly
+if (require.main === module) {
+  main();
+}
+

package/.sinapse-ai/git-hooks/lib/secret-scanner-core.js

@@ -0,0 +1,355 @@
+'use strict';
+
+/**
+ * Secret Scanner Core — shared detection logic.
+ *
+ * Single source of truth for secret detection, imported by BOTH:
+ *   - .claude/hooks/secret-scanning.cjs  (Claude Code PreToolUse, Write/Edit content)
+ *   - bin/utils/staged-secret-scan.js    (git pre-commit, staged diff content)
+ *
+ * Hardening (Frente 4.2 — Stream A):
+ *   - All 20+ named patterns preserved (no regression).
+ *   - Shannon entropy: flags high-entropy tokens (>= 20 contiguous chars,
+ *     >= 4.5 bits/char) as suspected secrets, BEYOND the named patterns.
+ *     Lockfile-hash context + code-identifier band are allowlisted to avoid
+ *     false positives on integrity hashes and long camelCase symbols.
+ *   - Allowlist: placeholders (your-key-here, xxx, CHANGEME, REPLACE_ME, <...>,
+ *     example.com, etc.) and obvious fakes PASS.
+ *   - Redaction: matched secrets are never printed in full.
+ *   - Designed for fail-CLOSED callers (this module never silently allows).
+ *
+ * @module bin/utils/secret-scanner-core
+ */
+
+// Private-key PEM headers are built from fragments so this source file holds no
+// literal "BEGIN ... PRIVATE KEY" marker (avoids self-tripping secret scanners).
+const PK = 'PRIVATE KEY';
+const BEGIN = '-----BEGIN ';
+const END5 = '-----';
+
+const NAMED_PATTERNS = [
+  // API Keys & Tokens
+  { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/ },
+  { name: 'AWS Secret Key', pattern: /(?:aws_secret_access_key|secret_key)\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40}['"]?/i, lowConfidence: true },
+  { name: 'GitHub Token', pattern: /gh[ps]_[A-Za-z0-9_]{36,}/ },
+  { name: 'GitHub OAuth', pattern: /gho_[A-Za-z0-9_]{36,}/ },
+  { name: 'GitHub Fine-Grained Token', pattern: /github_pat_[A-Za-z0-9_]{22,}/ },
+  { name: 'Slack Token', pattern: /xox[bpors]-[0-9]{10,}-[A-Za-z0-9-]+/ },
+  { name: 'Stripe Key', pattern: /[sr]k_(live|test)_[A-Za-z0-9]{20,}/ },
+  // OpenAI project-scoped keys (`sk-proj-…`) contain hyphens/underscores, so the
+  // generic `sk-[A-Za-z0-9]{20,}` rule below stops at the first hyphen and never
+  // matches the body. This explicit rule is CONCLUSIVE on shape (the `sk-proj-`
+  // prefix is unambiguous) and is NOT entropy-gated, so a leaked project key is
+  // caught even when its tail happens to score low on Shannon entropy.
+  { name: 'OpenAI Project Key', pattern: /sk-proj-[A-Za-z0-9_-]{40,}/ },
+  // Other OpenAI key families that also carry separators (svcacct / admin).
+  { name: 'OpenAI Service/Admin Key', pattern: /sk-(?:svcacct|admin)-[A-Za-z0-9_-]{20,}/ },
+  // Legacy/classic OpenAI keys (`sk-` + contiguous alnum). Entropy-gated to avoid
+  // tripping on `sk-` prefixed identifiers; threshold lowered to 3.0 (see note).
+  { name: 'OpenAI Key', pattern: new RegExp('sk-[A-Za-z0-9]{20,}'), entropyGated: true },
+  { name: 'Anthropic Key', pattern: new RegExp('sk-ant-[A-Za-z0-9-]{20,}') },
+  { name: 'Supabase Key', pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]{50,}/ },
+  { name: 'Google API Key', pattern: /AIza[0-9A-Za-z_-]{35}/ },
+  { name: 'Vercel Token', pattern: /vercel_[A-Za-z0-9]{20,}/ },
+
+  // Private Keys (built dynamically; no literal header in source)
+  { name: 'RSA Private Key', pattern: new RegExp(BEGIN + 'RSA ' + PK + END5) },
+  { name: 'SSH Private Key', pattern: new RegExp(BEGIN + 'OPENSSH ' + PK + END5) },
+  { name: 'PGP Private Key', pattern: new RegExp(BEGIN + 'PGP ' + PK + ' BLOCK' + END5) },
+  { name: 'EC Private Key', pattern: new RegExp(BEGIN + 'EC ' + PK + END5) },
+  { name: 'DSA Private Key', pattern: new RegExp(BEGIN + 'DSA ' + PK + END5) },
+  { name: 'Generic Private Key', pattern: new RegExp(BEGIN + PK + END5) },
+
+  // Connection Strings
+  // user/password are restricted to non-whitespace so the negated classes can't
+  // span newlines and match a bogus region across a whole file (the host part of
+  // a URL followed by an unrelated colon and at-sign on later lines). Real
+  // credentials never contain whitespace, so true detection is unaffected.
+  { name: 'DB Connection String', pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:\s]+:[^@\s]+@[^/\s]+/i, credentialPlaceholderGated: true },
+  { name: 'Supabase DB URL', pattern: /postgresql:\/\/postgres\.[A-Za-z0-9]+:[^@\s]+@/i, credentialPlaceholderGated: true },
+
+  // Generic Patterns (broader, lower confidence — placeholder-allowlisted)
+  { name: 'Hardcoded Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*['"][^'"]{8,}['"]/i, lowConfidence: true },
+  { name: 'Bearer Token', pattern: /[Bb]earer\s+[A-Za-z0-9_\-.]{20,}/, entropyGated: true, lowConfidence: true },
+  { name: 'Basic Auth', pattern: /[Bb]asic\s+[A-Za-z0-9+/=]{20,}/, lowConfidence: true },
+
+  // Long pure-hex runs (32–64 chars). The 16-symbol hex alphabet caps Shannon
+  // entropy at ~4.0, BELOW ENTROPY_THRESHOLD (4.5), so the generic entropy
+  // backstop never sees them — Twilio auth tokens (32-hex), webhook signing
+  // secrets and SHA-style 64-hex digests slip through. This explicit rule closes
+  // that gap. It is `hashContextGated`: a hex run sitting in an integrity /
+  // checksum / lockfile / git-sha context (covered by HASH_CONTEXT_PATTERN) is a
+  // legitimate hash, NOT a secret, and is allowlisted. `lowConfidence` keeps it
+  // OUT of the release publish gate (entropy:false there would otherwise match
+  // every documented digest); the diff-scoped commit hook still enforces it.
+  { name: 'Long Hex Token', pattern: /\b[a-f0-9]{32,64}\b/i, hashContextGated: true, lowConfidence: true },
+];
+
+const PLACEHOLDER_TOKENS = [
+  'your-key', 'your_key', 'yourkey', 'your-secret', 'your_secret',
+  'your-token', 'your_token', 'your-api', 'your_api',
+  'xxx', 'changeme', 'change-me', 'change_me',
+  'replace_me', 'replace-me', 'replaceme', 'replace_with',
+  'placeholder', 'example', 'sample', 'dummy', 'fake',
+  'todo', 'tbd', 'redacted', 'insert', 'put-your', 'put_your',
+  'my-secret', 'mysecret', 'my-password', 'mypassword',
+  'supersecret', 'super-secret', 'secret123', 'password123',
+  'notarealkey', 'not-a-real', 'test-key', 'test_key', 'testkey',
+  'abcdef', '123456', '000000', 'aaaaaa',
+];
+
+const PLACEHOLDER_PATTERNS = [
+  /^<.*>$/,                 // <sua-chave>, <token>, <REPLACE>
+  /^\[.*\]$/,               // [CHANGE_ME], [your key]
+  /^\{\{?.*\}?\}$/,         // {token}, {{secret}}
+  /^\$\{.*\}$/,             // ${TOKEN}
+  // SCREAMING_SNAKE env-var name used as value. Requires an underscore so raw
+  // all-caps secrets (e.g. AWS access keys) are NOT allowlisted by this rule.
+  /^[A-Z][A-Z0-9]*_[A-Z0-9_]*$/,
+  /^(x+|y+|z+|n+|0+|a+|\.+|-+|_+|\*+)$/i, // xxxx, 0000, ----, ....
+];
+
+const EXAMPLE_HOST_PATTERN = /(?:example\.(?:com|org|net)|localhost|127\.0\.0\.1|host\b|your-host|placeholder)/i;
+
+// A keyword placeholder only allowlists when it DOMINATES the value: once every
+// placeholder occurrence is removed, the TOTAL alphanumeric length that remains
+// is too short to be a secret on its own (< ENTROPY_MIN_LEN). A bare
+// `lower.includes(token)` was a trivial bypass — ANY real secret that happened to
+// contain "abcdef" / "123456" / "example" anywhere in its body got silently
+// allowlisted (e.g. Xq9Zk2…abcdef…Fg5 passed). Measuring the *total* remainder
+// (not just the longest contiguous run) closes that hole even when the buried
+// placeholder splits the secret into two sub-threshold runs: the legitimate
+// cases (your-key-here, placeholder123456, test-key-example, CHANGEME) strip down
+// to nothing, while a 35-char random token minus a 6-char placeholder still has
+// ~29 alphanumeric chars left and is NOT allowlisted.
+function placeholderDominates(lower) {
+  let stripped = lower;
+  let matchedAny = false;
+  for (const token of PLACEHOLDER_TOKENS) {
+    if (stripped.includes(token)) {
+      matchedAny = true;
+      // Replace with a separator so adjacent runs aren't fused into a longer one.
+      stripped = stripped.split(token).join(' ');
+    }
+  }
+  if (!matchedAny) return false;
+  // Total alphanumeric chars left after removing every placeholder occurrence.
+  const remaining = (stripped.match(/[a-z0-9]/g) || []).length;
+  return remaining < ENTROPY_MIN_LEN;
+}
+
+function isAllowlistPlaceholder(value) {
+  if (value === null || value === undefined) return false;
+  const v = String(value).trim();
+  if (v.length === 0) return true;
+
+  // Structural placeholders are always safe: <...>, [...], {token}, ${VAR},
+  // SCREAMING_SNAKE env-var names, and repeated single-symbol fillers.
+  for (const re of PLACEHOLDER_PATTERNS) {
+    if (re.test(v)) return true;
+  }
+  if (/^(.)\1{5,}$/.test(v)) return true; // repeated single char
+
+  // Keyword placeholders: word-boundary anchored + dominance, NOT raw includes().
+  if (placeholderDominates(v.toLowerCase())) return true;
+
+  return false;
+}
+
+function shannonEntropy(str) {
+  if (!str || str.length === 0) return 0;
+  const freq = Object.create(null);
+  for (const ch of str) {
+    freq[ch] = (freq[ch] || 0) + 1;
+  }
+  const len = str.length;
+  let entropy = 0;
+  for (const ch in freq) {
+    const p = freq[ch] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// 4.5 bits/char: long camelCase/snake identifiers in source top out around
+// ~4.2 (dictionary words have repeated letters), while real random secrets —
+// base64 of random bytes (~5.5), mixed alphanumeric tokens (~5.0), even base64
+// of text (~4.5) — clear it. Set above the identifier band to kill false
+// positives on code symbols; named patterns still catch branded low-entropy keys.
+const ENTROPY_THRESHOLD = 4.5;
+const ENTROPY_MIN_LEN = 20;
+const TOKEN_SHAPE = /[A-Za-z0-9_\-/+=]{20,}/g;
+
+const LOCKFILE_PATH_PATTERN = /(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|composer\.lock|Cargo\.lock|poetry\.lock|Gemfile\.lock|bun\.lockb)$/i;
+const HASH_CONTEXT_PATTERN = /(?:sha512-|sha384-|sha256-|sha1-|integrity"?\s*[:=]|"resolved"|"checksum"|"hash"|[a-f0-9]{40}|[a-f0-9]{64})/i;
+
+function isLockfilePath(filePath) {
+  if (!filePath) return false;
+  return LOCKFILE_PATH_PATTERN.test(String(filePath).replace(/\\/g, '/'));
+}
+
+function redactMatch(value, keep = 4) {
+  const v = String(value == null ? '' : value);
+  if (v.length === 0) return '[REDACTED]';
+  if (v.length <= keep) return '[REDACTED]';
+  const prefix = v.slice(0, keep);
+  return prefix + '...[REDACTED ' + (v.length - keep) + ' chars]';
+}
+
+function scanContent(content, options = {}) {
+  const text = String(content == null ? '' : content);
+  const filePath = options.filePath || '';
+  const entropyEnabled = options.entropy !== false;
+  const findings = [];
+
+  if (text.length === 0) return findings;
+
+  // 1) Named patterns
+  //    Structural patterns (AWS access key, Stripe, Google, PEM headers,
+  //    connection strings, JWT) are CONCLUSIVE on shape — they are NOT
+  //    placeholder-allowlisted (a real AKIA… key that happens to contain
+  //    "123456" is still a leak). Only `lowConfidence` value-bearing patterns
+  //    (password/secret assignments, Bearer/Basic headers) get the placeholder
+  //    allowlist, applied to the captured *value* portion.
+  for (const descriptor of NAMED_PATTERNS) {
+    const m = text.match(descriptor.pattern);
+    if (!m) continue;
+    const matched = m[0];
+
+    if (descriptor.lowConfidence) {
+      // Isolate the value side of `key = "<value>"` / `Bearer <value>`.
+      const valuePart = (matched.match(/(?:[=:]\s*['"]?|\s+)([^'"]+)['"]?\s*$/) || [null, matched])[1] || matched;
+      if (isAllowlistPlaceholder(valuePart)) continue;
+    }
+
+    if (descriptor.credentialPlaceholderGated) {
+      // A connection string carries a structured user:password@host. When the
+      // password slot is a placeholder/interpolation (${VAR}, <pass>, a
+      // SCREAMING_SNAKE env-var name, your-password…) it is a template/example,
+      // NOT a leaked credential — and is the idiomatic, safe way to document
+      // one. A real leaked password (random/literal) is not allowlisted and is
+      // still flagged.
+      const cred = (matched.match(/:\/\/[^:/\s]+:([^@\s]+)@/) || [null, ''])[1];
+      if (cred && isAllowlistPlaceholder(cred)) continue;
+    }
+
+    if (descriptor.entropyGated) {
+      const tail = (matched.match(/[A-Za-z0-9_\-/+=]{16,}$/) || [matched])[0];
+      if (isAllowlistPlaceholder(tail)) continue;
+      // Threshold lowered 2.5 -> 2.0: a short real token (e.g. a 20-char legacy
+      // key with a narrow alphabet) can dip just under 2.5 and would have been a
+      // false-NEGATIVE (leaked secret allowed through). 2.0 still rejects obvious
+      // non-random fixtures (a single repeated char ~ 0.0, repeated words ~1.5)
+      // while no longer dropping legitimately-shaped keys.
+      if (shannonEntropy(tail) < 2.0) continue; // clearly non-random
+    }
+
+    if (descriptor.hashContextGated) {
+      // Long hex runs are flagged as suspected secrets (Twilio token, webhook
+      // signing secret, SHA-style digest) EXCEPT when they sit in an integrity /
+      // checksum / lockfile / git-sha context — those are legitimate hashes, not
+      // leaked credentials. Reuse HASH_CONTEXT_PATTERN over a window around the
+      // match so package-lock integrity:, "resolved" tarball #sha, "checksum",
+      // and 40/64-hex git shas are NOT false-positived. A fully repeated/obvious
+      // placeholder hex (deadbeef…, 000…) is also allowlisted.
+      if (isAllowlistPlaceholder(matched)) continue;
+      if (isLockfilePath(filePath)) continue;
+      // Canonical digest lengths — git SHA-1 (40) and SHA-256 (64) — are
+      // overwhelmingly legitimate hashes (commit refs, file checksums, content
+      // digests) and appear bare in changelogs/docs/lockfiles. Treating every
+      // isolated 40/64-hex run as a leak would false-positive on the entire git
+      // ecosystem, so these exact lengths are hash-shaped by default. The
+      // headline real-secret case (Twilio auth token = 32-hex) and other
+      // non-digest lengths (33–39, 41–63) are NOT standard digests and stay
+      // flagged. A leaked literal hash secret of EXACTLY 40/64 hex is the
+      // accepted blind spot of this length-based heuristic (documented tradeoff
+      // favouring zero false-positives on git/checksum hashes).
+      const hexLen = matched.length;
+      if (hexLen === 40 || hexLen === 64) continue;
+      // For non-canonical lengths, allowlist only when the SURROUNDING context
+      // carries a hash marker (integrity:, sha256-, "resolved", "checksum"). The
+      // window is widened on the left so a marker earlier on the line
+      // (e.g. `"resolved": "https://…/x.tgz#<hex>"`) is still seen.
+      const mIdx = text.indexOf(matched);
+      const before = text.slice(Math.max(0, mIdx - 64), mIdx);
+      const after = text.slice(mIdx + matched.length, mIdx + matched.length + 4);
+      if (HASH_CONTEXT_PATTERN.test(before + ' ' + after)) continue;
+    }
+
+    findings.push({ name: descriptor.name, redacted: redactMatch(matched), kind: 'pattern' });
+  }
+
+  // 2) Generic high-entropy detector (beyond named patterns)
+  if (entropyEnabled && !isLockfilePath(filePath)) {
+    const seen = new Set();
+    let match;
+    TOKEN_SHAPE.lastIndex = 0;
+    while ((match = TOKEN_SHAPE.exec(text)) !== null) {
+      const token = match[0];
+      if (token.length < ENTROPY_MIN_LEN) continue;
+      if (seen.has(token)) continue;
+      seen.add(token);
+      if (isAllowlistPlaceholder(token)) continue;
+
+      // Real high-entropy secrets are a long *contiguous* alphanumeric body.
+      // File paths (a/b/c), kebab/snake IDs (PROP-20260507-slug) and dotted
+      // slugs split into short segments at separators — they only look
+      // "high-entropy" as a whole. Require a contiguous run >= ENTROPY_MIN_LEN
+      // so example identifiers and paths in prose/docs stop tripping the net,
+      // while branded tokens (caught by NAMED_PATTERNS) and raw base64/hex
+      // bodies still qualify.
+      const longestRun = (token.match(/[A-Za-z0-9]+/g) || [])
+        .reduce((max, seg) => Math.max(max, seg.length), 0);
+      if (longestRun < ENTROPY_MIN_LEN) continue;
+
+      // For KEY=value tokens (e.g. DATABASE_URL=your-db-url) also check whether
+      // the value-side alone is a placeholder. The token shape regex includes '='
+      // so a whole assignment can be captured as one long token; if the value part
+      // looks like a placeholder the whole thing is safe.
+      const eqIdx = token.indexOf('=');
+      if (eqIdx > 0) {
+        const valueSide = token.slice(eqIdx + 1);
+        if (isAllowlistPlaceholder(valueSide)) continue;
+        // Generic "your-*" / "my-*" prefix heuristic covers cases not in the list.
+        const vsLower = valueSide.toLowerCase();
+        if (vsLower.startsWith('your-') || vsLower.startsWith('your_') ||
+            vsLower.startsWith('my-') || vsLower.startsWith('my_') ||
+            vsLower.startsWith('insert-') || vsLower.startsWith('put-')) continue;
+      }
+
+      const ent = shannonEntropy(token);
+      if (ent < ENTROPY_THRESHOLD) continue;
+
+      const ctxStart = Math.max(0, match.index - 24);
+      const context = text.slice(ctxStart, match.index + token.length + 4);
+      if (HASH_CONTEXT_PATTERN.test(context)) continue;
+
+      findings.push({
+        name: 'High-entropy string (suspected secret)',
+        redacted: redactMatch(token),
+        entropy: Number(ent.toFixed(2)),
+        kind: 'entropy',
+      });
+    }
+  }
+
+  return findings;
+}
+
+function hasSecret(content, options = {}) {
+  return scanContent(content, options).length > 0;
+}
+
+module.exports = {
+  NAMED_PATTERNS,
+  PLACEHOLDER_TOKENS,
+  EXAMPLE_HOST_PATTERN,
+  ENTROPY_THRESHOLD,
+  ENTROPY_MIN_LEN,
+  shannonEntropy,
+  isAllowlistPlaceholder,
+  isLockfilePath,
+  redactMatch,
+  scanContent,
+  hasSecret,
+};