# 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`.