28 lines
2.1 KiB
Markdown
28 lines
2.1 KiB
Markdown
# 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`.
|