engine.js

/*
 * airlock detection engine: the browser twin of the Python CLI's detectors.py.
 *
 * Kept deliberately in lock-step with that file: same patterns, same
 * validators (Luhn, Shannon entropy), same "specificity over recall" stance so
 * ordinary text never trips it. UMD wrapper so it loads both as a content
 * script (attaches to globalThis.Airlock) and under Node for the parity tests.
 */
(function (root) {
  "use strict";

  // ---- validators ------------------------------------------------------- //
  function shannonEntropy(s) {
    if (!s) return 0;
    const freq = Object.create(null);
    for (const ch of s) freq[ch] = (freq[ch] || 0) + 1;
    const n = s.length;
    let e = 0;
    for (const k in freq) {
      const p = freq[k] / n;
      e -= p * Math.log2(p);
    }
    return e;
  }

  function luhnOk(candidate) {
    const digits = [];
    for (const c of candidate) if (c >= "0" && c <= "9") digits.push(+c);
    if (digits.length < 13 || digits.length > 19) return false;
    let sum = 0;
    const parity = digits.length % 2;
    for (let i = 0; i < digits.length; i++) {
      let d = digits[i];
      if (i % 2 === parity) {
        d *= 2;
        if (d > 9) d -= 9;
      }
      sum += d;
    }
    return sum % 10 === 0;
  }

  function highEntropy(threshold, minLen) {
    return (value) => value.length >= minLen && shannonEntropy(value) >= threshold;
  }

  // ---- detector registry ------------------------------------------------ //
  // Every regex carries the `d` flag so match.indices gives per-group spans,
  // and `g` so matchAll works. `group` picks which capture holds the secret.
  const D = (kind, category, label, severity, pattern, opts = {}) => ({
    kind, category, label, severity, pattern,
    group: opts.group || 0,
    validate: opts.validate || null,
    default: opts.default !== false,
  });

  const DETECTORS = [
    // private keys
    D("private_key", "secret", "PRIVATE_KEY", "high",
      /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/gd),

    // cloud / provider tokens
    D("aws_access_key", "secret", "AWS_ACCESS_KEY", "high",
      /\b(?:AKIA|ASIA|AGPA|AIDA|AROA)[0-9A-Z]{16}\b/gd),
    D("gcp_api_key", "secret", "GCP_API_KEY", "high",
      /\bAIza[0-9A-Za-z\-_]{35}\b/gd),
    D("github_pat", "secret", "GITHUB_TOKEN", "high",
      /\bgh[posru]_[A-Za-z0-9]{36}\b/gd),
    D("github_fine_pat", "secret", "GITHUB_TOKEN", "high",
      /\bgithub_pat_[0-9a-zA-Z_]{82}\b/gd),
    D("anthropic_key", "secret", "ANTHROPIC_KEY", "high",
      /\bsk-ant-[A-Za-z0-9\-_]{20,}\b/gd),
    D("openai_key", "secret", "OPENAI_KEY", "high",
      /\bsk-(?:proj-)?[A-Za-z0-9]{20,}\b/gd),
    D("stripe_key", "secret", "STRIPE_KEY", "high",
      /\b[rsp]k_(?:live|test)_[0-9a-zA-Z]{16,}\b/gd),
    D("slack_token", "secret", "SLACK_TOKEN", "high",
      /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/gd),
    D("slack_webhook", "secret", "SLACK_WEBHOOK", "high",
      /https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/_+-]{40,}/gd),
    D("google_oauth", "secret", "GOOGLE_OAUTH_ID", "medium",
      /\b[0-9]+-[0-9a-z]{32}\.apps\.googleusercontent\.com\b/gd),
    D("sendgrid_key", "secret", "SENDGRID_KEY", "high",
      /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/gd),
    D("twilio_key", "secret", "TWILIO_KEY", "high",
      /\bSK[0-9a-fA-F]{32}\b/gd),
    D("npm_token", "secret", "NPM_TOKEN", "high",
      /\bnpm_[A-Za-z0-9]{36}\b/gd),
    D("jwt", "secret", "JWT", "medium",
      /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gd),

    // generic assigned secret, entropy-gated (kills password="changeme")
    D("generic_secret", "secret", "SECRET", "medium",
      /(?:api[_-]?key|secret|token|passwd|password|auth|access[_-]?key|client[_-]?secret|private[_-]?key|bearer)\s*[:=]\s*['"]?([A-Za-z0-9+/=_\-.]{16,})['"]?/gdi,
      { group: 1, validate: highEntropy(3.2, 16) }),

    // credentials embedded in URLs (proto://user:pass@host)
    D("connection_string", "secret", "CONNECTION_STRING", "high",
      /\b[a-z][a-z0-9+.\-]*:\/\/[^\s:@/]+:[^\s:@/]+@[^\s/]+/gd),

    // PII, low false-positive, on by default
    D("email", "pii", "EMAIL", "low",
      /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/gd),
    D("credit_card", "pii", "CREDIT_CARD", "high",
      /\b(?:\d[ -]?){13,19}\b/gd, { validate: luhnOk }),

    // PII, noisy: off unless includeAll
    D("us_ssn", "pii", "SSN", "medium",
      /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/gd, { default: false }),
    D("phone", "pii", "PHONE", "low",
      /\b(?:\+?\d{1,3}[ .-]?)?\(?\d{3}\)?[ .-]?\d{3}[ .-]?\d{4}\b/gd, { default: false }),
    D("ipv4", "pii", "IP_ADDRESS", "low",
      /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/gd, { default: false }),
  ];

  const RANK = { high: 3, medium: 2, low: 1 };

  // ---- scan ------------------------------------------------------------- //
  function scan(text, opts = {}) {
    const includeAll = !!opts.includeAll;
    const active = includeAll ? DETECTORS : DETECTORS.filter((d) => d.default);
    const raw = [];
    for (const det of active) {
      for (const m of text.matchAll(det.pattern)) {
        const value = m[det.group];
        if (!value) continue;
        const span = m.indices && m.indices[det.group];
        if (!span) continue;
        if (det.validate && !det.validate(value)) continue;
        raw.push({
          kind: det.kind, category: det.category, label: det.label,
          severity: det.severity, start: span[0], end: span[1], value,
        });
      }
    }
    // Overlap resolution: strongest (then longest, then earliest) wins its span.
    raw.sort((a, b) =>
      RANK[b.severity] - RANK[a.severity] ||
      (b.end - b.start) - (a.end - a.start) ||
      a.start - b.start);
    const chosen = [];
    for (const f of raw) {
      if (chosen.some((c) => f.start < c.end && c.start < f.end)) continue;
      chosen.push(f);
    }
    chosen.sort((a, b) => a.start - b.start);
    return chosen;
  }

  // ---- redact ----------------------------------------------------------- //
  function redact(text, findings) {
    if (!findings.length) return text;
    const counts = Object.create(null);
    for (const f of findings) counts[f.label] = (counts[f.label] || 0) + 1;
    const seen = Object.create(null);
    const sorted = [...findings].sort((a, b) => a.start - b.start);
    let out = "";
    let cursor = 0;
    for (const f of sorted) {
      out += text.slice(cursor, f.start);
      if (counts[f.label] > 1) {
        seen[f.label] = (seen[f.label] || 0) + 1;
        out += `[${f.label}_${seen[f.label]}]`;
      } else {
        out += `[${f.label}]`;
      }
      cursor = f.end;
    }
    out += text.slice(cursor);
    return out;
  }

  const api = { scan, redact, luhnOk, shannonEntropy, DETECTORS };
  root.Airlock = api;
  if (typeof module !== "undefined" && module.exports) module.exports = api;
})(typeof globalThis !== "undefined" ? globalThis : this);