2.1 KiB
Capability Spec: security-codes
Package: @suaveplan/security-codes
Version: 0.0.0 (genesis)
Status: ADDED
ADDED Requirements
SC-01 — Detection contract
SecurityCodeDetector.detect(input, options?) MUST return SecurityCodeMatch[] where each match carries { type, value, start, end, confidence }. The detector MUST support registering custom patterns via addPattern(type, pattern) and disabling built-ins via options.disable: SecurityCodeType[].
SC-02 — Built-in pattern set
The package MUST ship detectors for: AWS access key ID + secret, JWT (validated via three-part Base64URL shape), credit card (Luhn-validated), GitHub classic PAT (ghp_…), GitHub fine-grained (github_pat_…), Stripe secret key (sk_live_/sk_test_), Stripe publishable key (pk_live_/pk_test_), Google API key (AIza…), OpenAI key (sk-…), PEM -----BEGIN …----- blocks, OpenSSH private key block, high-entropy generic string (Shannon entropy ≥ configurable threshold).
SC-03 — Sanitizer strategies
SecurityCodeSanitizer.sanitize(input, options?) MUST support strategies full-redact (replace with [REDACTED:<type>]), partial (show first/last N chars), hash (HMAC-SHA256 truncated to 12 hex chars with caller-supplied key), and tokenize (stable uuid-style token kept in a reversible map). The function MUST return { output, matches } where matches lists every redaction performed.
SC-04 — Idempotency
Applying sanitize to already-sanitised output MUST yield the same output (no double-redaction). Running detect on any strategy's output MUST find zero matches for the original patterns (except when the strategy intentionally preserves a signature, e.g. partial).
SC-05 — Observability
Every detect call MUST increment security_codes.detect.total with label type per match and record security_codes.detect.duration_ms histogram. No PII or raw secret values MUST appear in OTel attributes.
SC-06 — Option validation
DetectorOptions and SanitizerOptions MUST be validated via Zod schemas. Invalid options MUST throw SECURITY_CODES.INVALID_PATTERN.