Initial Commit

openspec/archive/2026-04-19-enterprise-security-codes/proposal.md

@@ -0,0 +1,36 @@
+# OpenSpec Change: enterprise-security-codes
+
+- **Change ID**: enterprise-security-codes
+- **Package**: `@suaveplan/security-codes`
+- **Category**: universal
+- **Target path**: `universal/auth/security-codes`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/security-codes.md`
+
+## Summary
+Greenfield rebuild of `@suaveplan/security-codes` — detects and sanitises sensitive security-code leakage in strings (API keys, JWTs, credit cards, GitHub tokens, Stripe keys, SSH keys, PEM blocks, AWS access keys, etc.) with a pluggable detector and a redactor producing structured, reversible or one-way masks.
+
+## Current-state audit (genesis)
+Package does not exist yet — fresh build.
+
+## Dependencies
+- Workspace: none (leaf)
+- External (via catalog): `zod` → `catalog:forms`; `tslib` → `catalog:build`; `@opentelemetry/api` → `catalog:observability`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` → `catalog:testing`
+
+## Preserved public surface
+- `SecurityCodeDetector` — `detect(input, options?): SecurityCodeMatch[]`
+- `SecurityCodeSanitizer` — `sanitize(input, options?): { output, matches }`
+- Type exports: `SecurityCodeMatch`, `SecurityCodeType`, `DetectorOptions`, `SanitizerOptions`, `MaskingStrategy`
+- Built-in detectors: AWS access key, JWT, credit card (Luhn-validated), GitHub classic/fine-grained PAT, Stripe secret/publishable, Google API key, OpenAI `sk-…`, PEM block, SSH key, generic high-entropy string heuristic
+
+## New genesis additions
+- Codes: `SECURITY_CODES.DETECTION_FAILED`, `SECURITY_CODES.INVALID_PATTERN`, `SECURITY_CODES.SANITIZATION_FAILED`.
+- Zod schemas for `DetectorOptions`, `SanitizerOptions`, `SecurityCodeMatch`.
+- OTel counter `security_codes.detect.total{type}`, histogram `security_codes.detect.duration_ms`.
+- Property tests: sanitise twice is idempotent; detect→sanitise→detect yields zero remaining matches for masked outputs.
+
+## Impact
+- Adds one new package: `universal/auth/security-codes`
+- Adds one new spec capability: `security-codes`

openspec/archive/2026-04-19-enterprise-security-codes/specs/security-codes/spec.md

@@ -0,0 +1,27 @@
+# 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`.

openspec/archive/2026-04-19-enterprise-security-codes/tasks.md

@@ -0,0 +1,31 @@
+# Tasks: enterprise-security-codes
+
+## 1. Scaffold
+- [x] 1.1 `universal/auth/security-codes/` skeleton with 100/100/100/100 coverage (istanbul).
+- [x] 1.2 Guard tests; CLAUDE.md/README/FOLDERS.yml updated.
+
+## 2. Errors + schemas
+- [x] 2.1 `src/errors/security-codes-error.ts` — codes `SECURITY_CODES.*`.
+- [x] 2.2 Zod schemas for `DetectorOptions`, `SanitizerOptions`, `SecurityCodeMatch`.
+
+## 3. Pattern library
+- [x] 3.1 `src/patterns/aws.ts`, `jwt.ts`, `stripe.ts`, `github.ts`, `google.ts`, `openai.ts`, `credit-card.ts` (+ Luhn), `pem.ts`, `ssh.ts`, `entropy.ts`.
+- [x] 3.2 Co-located `.md` per pattern.
+
+## 4. Detector
+- [x] 4.1 `src/core/code-detector/code-detector.ts` — `SecurityCodeDetector`; plugin registration; OTel counter + histogram.
+- [x] 4.2 Co-located `.md`; unit tests per pattern; fuzz tests via fast-check.
+
+## 5. Sanitizer
+- [x] 5.1 `src/core/code-sanitizer/code-sanitizer.ts` — `SecurityCodeSanitizer`; strategies: `full-redact`, `partial`, `hash`, `tokenize`.
+- [x] 5.2 Idempotency property test.
+
+## 6. Index / README
+- [x] 6.1 Barrel; subpath exports per pattern + core.
+- [x] 6.2 Root README.
+
+## 7. Benchmarks
+- [x] 7.1 Detect / sanitize on 10 KB / 1 MB text fixtures.
+
+## 8. Ship gate
+- [x] 8.1 Verification sequence green; fold spec + archive.