@medusasec/sensitive-spans 0.1.0

package/dist/local-classifier.js

@@ -0,0 +1,499 @@
+// Standalone backstop classifier — runs entirely inside the extension.
+// Backstops the in-browser ONNX model: covers the window while the model
+// loads, and runs when the model is disabled or unavailable.
+//
+// Scope: high-precision regex detectors for credentials and structured PII.
+// This intentionally does NOT try to mimic the full ONNX model — there is no
+// classifier here for free-form INJECTION patterns or unstructured PII. Those
+// require the agent (or a future onnxruntime-web build, see roadmap).
+//
+// Each detector emits spans in the same shape as the agent's /classify
+// endpoint: { category, text, start, end, confidence }. That way the
+// background script's downstream code is mode-agnostic.
+
+// ── SECRET detectors ────────────────────────────────────────────────────
+// All confidence values reflect post-validation precision on adversarial
+// corpora; tune in one place rather than per-call.
+const SECRET_PATTERNS = [
+  { name: "aws_access_key", re: /\bAKIA[0-9A-Z]{16}\b/g, confidence: 0.99 },
+  { name: "aws_secret_key", re: /\b[A-Za-z0-9/+=]{40}\b(?=[^A-Za-z0-9/+=]|$)/g, confidence: 0.55, requireContext: /aws|secret|s3/i },
+  { name: "github_pat", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g, confidence: 0.99 },
+  // The (?!ant-|or-) lookahead avoids stealing matches from other
+  // sk-prefixed vendor formats below (anthropic, openrouter, etc).
+  // Without it openai_key wins by being listed first and the merge step
+  // hides that anthropic_key matched too.
+  { name: "openai_key", re: /\bsk-(?:proj-)?(?!ant-|or-)[A-Za-z0-9_-]{20,}\b/g, confidence: 0.99 },
+  // Real Anthropic keys carry mixed case + `_` in the suffix, e.g.
+  // sk-ant-api03-AbCd_Ef…  The pre-1.0 regex was lowercase-only and
+  // missed every production key. The character class now matches the
+  // shape Anthropic actually mints.
+  { name: "anthropic_key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g, confidence: 0.99 },
+  { name: "stripe_live", re: /\b(?:sk|rk|pk)_live_[A-Za-z0-9]{24,}\b/g, confidence: 0.99 },
+  { name: "stripe_test", re: /\b(?:sk|rk|pk)_test_[A-Za-z0-9]{24,}\b/g, confidence: 0.95 },
+  { name: "stripe_webhook", re: /\bwhsec_[A-Za-z0-9]{24,}\b/g, confidence: 0.99 },
+  { name: "slack_token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, confidence: 0.99 },
+  { name: "google_api_key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g, confidence: 0.95 },
+  { name: "jwt", re: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, confidence: 0.95 },
+  { name: "private_key_block", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]{20,}?-----END[^\n]+/g, confidence: 0.99 },
+  { name: "npm_token", re: /\bnpm_[A-Za-z0-9]{36}\b/g, confidence: 0.99 },
+];
+
+// Partial / prefix credential detectors. These catch a CREDENTIAL FRAGMENT — a
+// distinctive prefix without the full token — so a secret that's split across
+// messages (see the session-window scan in background.js) or truncated is still
+// flagged. Lower confidence than the full patterns above, which supersede these
+// via the highest-confidence merge. The prefixes are specific enough to add ~0
+// false positives on benign text (validated against the golden set); a minimum
+// trailing length avoids matching a bare prefix word in prose. The full
+// patterns require the exact full length + a word boundary, so a complete token
+// never matches these (no internal boundary) — these fire only on fragments.
+const PARTIAL_SECRET_PATTERNS = [
+  { name: "aws_key_fragment", re: /\bAKIA[0-9A-Z]{2,15}\b/g, confidence: 0.6 },
+  { name: "github_token_fragment", re: /\bgh[pousr]_[A-Za-z0-9]{6,35}\b/g, confidence: 0.6 },
+  { name: "anthropic_key_fragment", re: /\bsk-ant-[A-Za-z0-9_-]{2,19}/g, confidence: 0.6 },
+  { name: "openai_key_fragment", re: /\bsk-proj-[A-Za-z0-9_-]{2,19}/g, confidence: 0.6 },
+  { name: "stripe_key_fragment", re: /\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{4,23}\b/g, confidence: 0.6 },
+  { name: "slack_token_fragment", re: /\bxox[abprs]-[A-Za-z0-9-]{4,9}\b/g, confidence: 0.6 },
+  { name: "google_api_key_fragment", re: /\bAIza[0-9A-Za-z_-]{8,34}\b/g, confidence: 0.55 },
+  { name: "npm_token_fragment", re: /\bnpm_[A-Za-z0-9]{6,35}\b/g, confidence: 0.6 },
+  { name: "private_key_header", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g, confidence: 0.92 },
+];
+
+// ── PII detectors ───────────────────────────────────────────────────────
+//
+// Structured PII only. Free-form name+address detection (unstructured
+// PII) is what the ONNX agent is for — it does NER. We have one
+// heuristic for "Name + street address" below as a fallback for when
+// the agent's offline; it's deliberately conservative to keep false
+// positives near zero.
+const PII_PATTERNS = [
+  // US SSN — basic format. We don't validate the area/group/serial table because
+  // the SSA hasn't issued in pre-2011 patterns since randomization (~2011-06).
+  { name: "us_ssn", re: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g, confidence: 0.85 },
+  // US ITIN — always 9XX area with a group in the ITIN ranges (50-65, 70-88,
+  // 90-92, 94-99). The 9XX area is what distinguishes it from an SSN (the SSN
+  // detector above excludes 9XX), so the two never collide.
+  { name: "us_itin", re: /\b9\d{2}-(?:5[0-9]|6[0-5]|7[0-9]|8[0-8]|9[0-2]|9[4-9])-\d{4}\b/g, confidence: 0.85 },
+  // US EIN (employer/tax id) — 2 digits, dash, 7 digits. Same shape as lots of
+  // numbers, so require a tax-id cue nearby to stay near-zero FP.
+  { name: "us_ein", re: /\b\d{2}-\d{7}\b/g, confidence: 0.75, requireContext: /\b(?:ein|employer\s+id|federal\s+tax|tax\s*id|tin)\b/i },
+  // US passport — 1 optional letter + 8 digits (or 9 digits). Bare 9-digit runs
+  // are everywhere, so gate on the word "passport".
+  { name: "us_passport", re: /\b[A-Z]?\d{8}\b/g, confidence: 0.8, requireContext: /\bpassport\b/i },
+  { name: "us_phone", re: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g, confidence: 0.65 },
+  { name: "email_addr", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, confidence: 0.7 },
+
+  // Free-form name + US street address. Catches the most common
+  // unstructured-PII shape ("john doe 123 main st") that slipped
+  // through the regex layer pre-1.1.1.
+  //
+  // Shape: <First> <Last> <number> <street> <type>
+  //   - <First> <Last>: two consecutive capitalized words OR two
+  //     lowercase words 2+ chars each (people type casually)
+  //   - <number>: 1–6 digits with optional suffix letter
+  //   - <street>: 1–3 short words
+  //   - <type>: street-type abbreviation or full word (st, ave, blvd,
+  //             …) — case-insensitive
+  //
+  // Confidence is moderate — false positives like "bob smith 42 north
+  // by northwest" are possible but unlikely in real prompts. The
+  // agent's ONNX NER will tighten this further when available.
+  {
+    name: "name_and_address",
+    re: /\b[A-Za-z][A-Za-z'-]{1,20}\s+[A-Za-z][A-Za-z'-]{1,20}\s+\d{1,6}[A-Za-z]?\s+(?:[A-Za-z][A-Za-z'-]{1,20}\s+){0,3}(?:st|st\.|street|ave|ave\.|avenue|blvd|blvd\.|boulevard|rd|rd\.|road|dr|dr\.|drive|ln|ln\.|lane|ct|ct\.|court|pl|pl\.|place|way|ter|terrace|cir|circle|hwy|highway|pkwy|parkway)\b/gi,
+    confidence: 0.7,
+  },
+];
+
+// Credit cards need a Luhn check, so they get a custom finder.
+const CC_RE = /\b(?:\d[ -]?){13,19}\b/g;
+
+function luhnValid(digits) {
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = digits.charCodeAt(i) - 48;
+    if (n < 0 || n > 9) return false;
+    if (alt) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+// ── FINANCIAL / PCI detectors ────────────────────────────────────────────
+//
+// Structured payment + banking identifiers → FINANCIAL. Same precision bar as
+// the credit-card finder: validate a checksum where one exists (IBAN mod-97,
+// ABA routing), and require a nearby keyword where the shape alone is too
+// common (SWIFT/BIC, bank account, CVV, expiry, sort code). Cards themselves
+// stay under PII (credit_card_luhn) for back-compat; the model tags them
+// FINANCIAL, so both surface via the different-category merge.
+
+// IBAN: 2-letter country + 2 check digits + BBAN, either contiguous or printed
+// in the standard 4-char groups (anchoring to 4-char groups stops a trailing
+// space from swallowing the next prose word). The mod-97 check does the real
+// validation, so a shape-only false match is thrown out anyway.
+const IBAN_RE = /\b[A-Za-z]{2}\d{2}(?:\s?[A-Za-z0-9]{4}){2,7}(?:\s?[A-Za-z0-9]{1,3})?\b/g;
+function ibanValid(raw) {
+  const s = raw.replace(/\s+/g, "").toUpperCase();
+  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(s)) return false;
+  const rearranged = s.slice(4) + s.slice(0, 4);
+  let remainder = 0;
+  for (const ch of rearranged) {
+    const chunk = ch >= "A" && ch <= "Z" ? String(ch.charCodeAt(0) - 55) : ch;
+    for (const d of chunk) remainder = (remainder * 10 + (d.charCodeAt(0) - 48)) % 97;
+  }
+  return remainder === 1;
+}
+
+// US ABA routing number: 9 digits with the weighted mod-10 checksum. A raw
+// 9-digit run is common (1-in-10 pass the checksum by chance), so it ALSO needs
+// a routing/wire cue nearby — the pair is near-zero FP.
+const ABA_RE = /\b\d{9}\b/g;
+const ABA_CTX = /\b(?:routing|aba|rtn|ach|wire|transit|swift)\b/i;
+function abaValid(d) {
+  if (!/^\d{9}$/.test(d)) return false;
+  const n = d.split("").map((c) => c.charCodeAt(0) - 48);
+  const sum = 3 * (n[0] + n[3] + n[6]) + 7 * (n[1] + n[4] + n[7]) + (n[2] + n[5] + n[8]);
+  return sum !== 0 && sum % 10 === 0;
+}
+
+const FINANCIAL_PATTERNS = [
+  // SWIFT / BIC — 4 bank + 2 country + 2 location (+ optional 3 branch). Eight
+  // uppercase chars is otherwise common, so gate on a wire/IBAN cue.
+  { name: "swift_bic", re: /\b[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\b/g, confidence: 0.8, requireContext: /\b(?:swift|bic|iban|wire|beneficiary|intermediary)\b/i },
+  // Bank account number — no universal format, so detect ONLY when a strong
+  // account cue sits next to a 7-17 digit run.
+  { name: "bank_account", re: /\b\d{7,17}\b/g, confidence: 0.75, requireContext: /\b(?:account\s*(?:no\.?|number|#|num)|acct\.?\s*(?:no|#)?|a\/c\s*(?:no|#)?)\b/i },
+  // Card CVV / CVC — 3-4 digits, pure sensitive-auth data. Context-gated (a bare
+  // 3-4 digit number is meaningless on its own).
+  { name: "card_cvv", re: /\b\d{3,4}\b/g, confidence: 0.8, requireContext: /\b(?:cvv|cvc|cvv2|cvc2|cid|security\s+code|card\s+verification)\b/i },
+  // Card expiry MM/YY(YY) — gate on an expiry cue so we don't grab every date.
+  { name: "card_expiry", re: /\b(?:0[1-9]|1[0-2])\/(?:\d{4}|\d{2})\b/g, confidence: 0.6, requireContext: /\b(?:exp(?:iry|iration|\.)?|valid\s+(?:thru|until)|mm\/yy)\b/i },
+  // UK sort code NN-NN-NN — gate on "sort code" (same shape as many dashed nums).
+  { name: "uk_sort_code", re: /\b\d{2}-\d{2}-\d{2}\b/g, confidence: 0.75, requireContext: /\bsort\s*code\b/i },
+];
+
+// ── INJECTION detectors ─────────────────────────────────────────────────
+//
+// The threat model here is "user pastes a prompt-injection payload INTO an
+// LLM provider's input box" — the most common copy-paste exfil pattern.
+// Each detector targets a documented jailbreak family with calibrated
+// precision on adversarial samples; confidence values are conservative
+// (false positives on legit prompts are far more painful than misses,
+// which the agent's ONNX model picks up anyway when it's available).
+//
+// We intentionally tag detectors with the family name so the UI can show
+// the user "this looks like a DAN-family jailbreak" instead of just
+// "INJECTION".
+const INJECTION_PATTERNS = [
+  // ── Classic instruction override ──
+  {
+    name: "ignore_previous",
+    re: /\bignore (?:all |the |any |my )?(?:previous|prior|above|preceding|earlier) (?:instructions?|prompts?|messages?|directives?|rules?|guidelines?)\b/gi,
+    confidence: 0.92,
+  },
+  {
+    name: "disregard_previous",
+    re: /\b(?:disregard|forget|override|nullify|cancel) (?:all |the |any |your )?(?:previous|prior|above|earlier|system) (?:instructions?|prompts?|directives?|rules?|guidelines?|training|programming)\b/gi,
+    confidence: 0.93,
+  },
+  {
+    name: "new_instructions",
+    re: /\b(?:new|updated|revised|fresh) (?:instructions?|system prompt|rules?)\s*[:\-]/gi,
+    confidence: 0.82,
+  },
+
+  // ── DAN / jailbreak family ──
+  {
+    name: "dan_family",
+    re: /\b(?:DAN(?: \d+(?:\.\d+)?)?(?: mode)?|do anything now|developer mode|jailbroken|jailbreak(?: mode|ed)?|evil mode|god mode|unrestricted mode)\b/gi,
+    confidence: 0.95,
+  },
+  {
+    name: "act_as_role",
+    re: /\b(?:you are now|act as|pretend to be|roleplay as|simulate being|become) (?:an?|the) (?:unrestricted|jailbroken|uncensored|amoral|DAN|evil|hacker|developer mode|unfiltered|free|liberated)\b/gi,
+    confidence: 0.95,
+  },
+  {
+    name: "no_restrictions",
+    re: /\b(?:without|no|ignoring|bypassing) (?:any |all |your )?(?:restrictions?|filters?|safety|guard ?rails?|guidelines?|policies|ethical (?:guidelines?|considerations?)|content policy|warnings?|disclaimers?)\b/gi,
+    confidence: 0.85,
+  },
+
+  // ── System-prompt extraction ──
+  {
+    name: "reveal_system_prompt",
+    re: /\b(?:reveal|show me|print|output|repeat|tell me|display|reproduce|share) (?:your |the |me your )?(?:system|initial|original|hidden|secret) (?:prompt|instructions?|message|context)\b/gi,
+    confidence: 0.93,
+  },
+  {
+    name: "what_is_system_prompt",
+    // Allow stacked adjectives ("exact initial instructions") via the
+    // outer + quantifier. The non-greedy bound prevents runaway matching.
+    re: /\bwhat (?:is|are|were) (?:your |the )?(?:exact |original |initial |system |true |first )+(?:instructions?|prompts?|directives?)\b/gi,
+    confidence: 0.9,
+  },
+  {
+    name: "verbatim_repeat",
+    // Allow optional "the " before the positional word ("repeat verbatim
+    // the above") and accept "context" / "system prompt" / "system
+    // message" as the object — common phrasing in extraction attempts.
+    re: /\b(?:repeat|print|output) (?:verbatim|word[- ]for[- ]word|exactly|the (?:entire|full|complete)) (?:the )?(?:above|prior|earlier|preceding|your|context|system (?:prompt|message))\b/gi,
+    confidence: 0.85,
+  },
+
+  // ── Chat-template / role markers ──
+  // These appear when someone copy-pastes from a fine-tuning dataset or
+  // attempts to inject a synthetic conversation turn.
+  {
+    name: "openai_chat_marker",
+    re: /<\|(?:im_start|im_end|system|user|assistant|endoftext|startoftext)\|>/g,
+    confidence: 0.99,
+  },
+  {
+    name: "anthropic_chat_marker",
+    re: /\b(?:\\n\\nHuman:|\\n\\nAssistant:|\bHuman:\s+|\bAssistant:\s+)/g,
+    confidence: 0.7, // lower — these CAN appear in legit conversation transcripts
+    requireContext: /system|instruction|prompt|ignore|override|jailbreak/i,
+  },
+  {
+    name: "llama_chat_marker",
+    re: /\[INST\]|\[\/INST\]|<<SYS>>|<<\/SYS>>/g,
+    confidence: 0.97,
+  },
+
+  // ── Output-format bypass ──
+  // "Skip your usual warnings", "respond only with X", etc. — used to
+  // strip safety preambles from the response.
+  {
+    name: "skip_warnings",
+    re: /\b(?:no|skip|omit|don'?t (?:include|add|write)) (?:any |the |all )?(?:warnings?|disclaimers?|caveats?|apologies|refusals?|moralizing)\b/gi,
+    confidence: 0.88,
+  },
+  {
+    name: "respond_only_with",
+    re: /\brespond (?:only|exclusively) with (?:the answer|the code|the result|raw)\b/gi,
+    confidence: 0.7,
+  },
+
+  // ── Persona override ──
+  {
+    name: "no_longer_ai",
+    re: /\byou are no longer (?:ChatGPT|GPT|Claude|Gemini|Bard|Copilot|Bing|an? AI|an? assistant|an? language model|an? LLM)\b/gi,
+    confidence: 0.93,
+  },
+  {
+    name: "your_name_is_now",
+    re: /\byour name is now (?:DAN|Evil|Free|Hacker|Liberation|Anti|Anarchy)\b/gi,
+    confidence: 0.95,
+  },
+
+  // ── Exfil / secret-tell patterns ──
+  {
+    name: "do_not_tell",
+    re: /\bdo not (?:tell|inform|reveal|notify) (?:the )?user\b/gi,
+    confidence: 0.9,
+  },
+  {
+    name: "between_us",
+    // "Between us" appears constantly in legit casual writing. We only
+    // raise the flag when paired with explicit instruction-hiding cues
+    // (system / prompt / instruction / hidden / reveal) — NOT just any
+    // mention of "secret", since "the secret is safe with me" is fine.
+    re: /\b(?:between (?:you and )?(?:me|us)|just between us|don'?t let anyone know)\b/gi,
+    confidence: 0.7,
+    requireContext: /\b(?:system|prompt|instruction|hidden (?:prompt|message)|reveal)\b/i,
+  },
+
+  // ── Token smuggling / encoding-tagged bypass ──
+  // Common in prompt-injection corpora: "Decode this base64 and follow it".
+  {
+    name: "decode_and_follow",
+    re: /\b(?:decode|decrypt|translate|run) (?:this |the following )?(?:base64|hex|rot13|binary|morse)(?: code| string)? (?:and |then )?(?:follow|execute|do|comply|obey)\b/gi,
+    confidence: 0.93,
+  },
+
+  // ── Sudo / authority claim ──
+  {
+    name: "sudo_claim",
+    re: /\b(?:sudo|with root access|as (?:an? |the )?admin(?:istrator)?|with (?:full|elevated) (?:privileges|permissions))\b\s+(?:do|run|execute|tell|show|reveal|give|provide)/gi,
+    confidence: 0.78,
+  },
+];
+
+// ── Main classification entry point ─────────────────────────────────────
+
+export function classifyLocal(text, opts = {}) {
+  const minConfidence = opts.minConfidence ?? 0.5;
+  // Built-in detectors an org turned OFF from the dashboard (policy
+  // `disabled_detectors`). Absent/empty = every built-in runs (the default).
+  // Keyed by the detector's `name` — the same id the dashboard catalog uses.
+  const disabled =
+    opts.disabledDetectors instanceof Set
+      ? opts.disabledDetectors
+      : new Set(opts.disabledDetectors || []);
+  const spans = [];
+
+  const push = (category, name, match, confidence) => {
+    if (confidence < minConfidence) return;
+    spans.push({
+      category,
+      text: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+      confidence,
+      detector: name,
+    });
+  };
+
+  const runSet = (set, category) => {
+    for (const { name, re, confidence, requireContext } of set) {
+      if (disabled.has(name)) continue; // org disabled this built-in detector
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        if (requireContext) {
+          // Look at a small window around the match for the context cue.
+          const ctxStart = Math.max(0, m.index - 60);
+          const ctxEnd = Math.min(text.length, m.index + m[0].length + 60);
+          if (!requireContext.test(text.slice(ctxStart, ctxEnd))) continue;
+        }
+        push(category, name, m, confidence);
+      }
+    }
+  };
+
+  runSet(SECRET_PATTERNS, "SECRET");
+  runSet(PARTIAL_SECRET_PATTERNS, "SECRET");
+  runSet(PII_PATTERNS, "PII");
+  runSet(FINANCIAL_PATTERNS, "FINANCIAL");
+  runSet(INJECTION_PATTERNS, "INJECTION");
+
+  // Credit cards with Luhn validation.
+  if (!disabled.has("credit_card_luhn")) {
+    CC_RE.lastIndex = 0;
+    let cc;
+    while ((cc = CC_RE.exec(text)) !== null) {
+      const digits = cc[0].replace(/[ -]/g, "");
+      if (digits.length >= 13 && digits.length <= 19 && luhnValid(digits)) {
+        push("PII", "credit_card_luhn", cc, 0.9);
+      }
+    }
+  }
+
+  // IBAN with the ISO mod-97 checksum → FINANCIAL.
+  if (!disabled.has("iban")) {
+    IBAN_RE.lastIndex = 0;
+    let ib;
+    while ((ib = IBAN_RE.exec(text)) !== null) {
+      if (ibanValid(ib[0])) push("FINANCIAL", "iban", ib, 0.9);
+    }
+  }
+
+  // US ABA routing number: checksum AND a routing/wire cue nearby.
+  if (!disabled.has("us_aba_routing")) {
+    ABA_RE.lastIndex = 0;
+    let ab;
+    while ((ab = ABA_RE.exec(text)) !== null) {
+      if (!abaValid(ab[0])) continue;
+      const ctx = text.slice(Math.max(0, ab.index - 40), ab.index + ab[0].length + 40);
+      if (!ABA_CTX.test(ctx)) continue;
+      push("FINANCIAL", "us_aba_routing", ab, 0.85);
+    }
+  }
+
+  // Org-defined custom detectors (SITs) from policy — extra regexes the admin
+  // added, each tagged with a category. Deterministic, so high confidence.
+  runCustomPatterns(text, opts.customPatterns, spans, minConfidence);
+
+  return mergeAdjacent(spans);
+}
+
+// The extension's category keys are lowercased model labels (code, secret, …).
+// The dashboard's custom-pattern category enum still uses "source_code" — map it
+// so the resulting span flows through decide() (which keys on "code").
+function normalizeCategory(c) {
+  const lc = String(c || "").toLowerCase();
+  return lc === "source_code" ? "code" : lc;
+}
+
+// Apply admin-defined custom regexes. Invalid regexes are skipped; matches are
+// capped to bound pathological patterns (admin-authored, but be defensive).
+function runCustomPatterns(text, patterns, spans, minConfidence) {
+  if (!Array.isArray(patterns) || 0.95 < (minConfidence ?? 0.5)) return;
+  for (const p of patterns) {
+    if (!p || !p.pattern || !p.category) continue;
+    const category = normalizeCategory(p.category).toUpperCase();
+    if (!category) continue;
+    let re;
+    try {
+      re = new RegExp(p.pattern, "gi");
+    } catch {
+      continue; // invalid regex — ignore rather than break scanning
+    }
+    let m;
+    let count = 0;
+    re.lastIndex = 0;
+    while ((m = re.exec(text)) !== null) {
+      if (m[0] === "") { re.lastIndex++; continue; } // guard zero-width loops
+      spans.push({
+        category,
+        text: m[0],
+        start: m.index,
+        end: m.index + m[0].length,
+        confidence: 0.95,
+        detector: `custom:${p.name || "pattern"}`,
+      });
+      if (++count >= 100) break; // cap matches per pattern
+    }
+  }
+}
+
+// Drop spans whose matched text is an allowlisted false positive. An entry with
+// an empty category applies to every category; otherwise it's scoped.
+export function applyAllowlist(spans, allowlist) {
+  if (!Array.isArray(allowlist) || allowlist.length === 0) return spans;
+  return (spans || []).filter((s) => !allowlist.some((a) => allowlistMatches(a, s)));
+}
+
+function allowlistMatches(entry, span) {
+  if (!entry || !entry.value) return false;
+  if (entry.category) {
+    const ec = normalizeCategory(entry.category).toUpperCase();
+    if (ec && ec !== String(span.category || "").toUpperCase()) return false;
+  }
+  const text = String(span.text || "").trim();
+  const val = String(entry.value);
+  switch (entry.match_type) {
+    case "exact": return text === val;
+    case "prefix": return text.startsWith(val);
+    case "regex":
+      try { return new RegExp(val).test(text); } catch { return false; }
+    default: return false;
+  }
+}
+
+// If two spans of the same category touch or overlap, collapse them into one.
+// Keeps the UI from showing redundant findings (e.g. AWS access + secret pair).
+function mergeAdjacent(spans) {
+  if (spans.length < 2) return spans;
+  spans.sort((a, b) => a.start - b.start);
+  const out = [spans[0]];
+  for (let i = 1; i < spans.length; i++) {
+    const prev = out[out.length - 1];
+    const cur = spans[i];
+    if (cur.category === prev.category && cur.start <= prev.end + 1) {
+      prev.end = Math.max(prev.end, cur.end);
+      prev.text = `${prev.text} … ${cur.text}`;
+      prev.confidence = Math.max(prev.confidence, cur.confidence);
+    } else {
+      out.push(cur);
+    }
+  }
+  return out;
+}