first commit

docs/security-stack/security/security-codes/src/patterns/stripe.md

@@ -0,0 +1,68 @@
+# stripe
+
+## Purpose
+
+Detects Stripe API keys — both secret keys (`sk_live_` / `sk_test_`) and
+publishable keys (`pk_live_` / `pk_test_`) — embedded in arbitrary strings.
+While publishable keys are technically public, detecting them prevents
+environment confusion. Secret keys provide full API access and must never
+appear in logs or source code.
+
+## Features
+
+- Separate regexes for secret and publishable prefixes to distinguish types.
+- Live secret keys receive a higher confidence score (`0.99`) than test
+  variants (`0.9`) because live credentials are more sensitive.
+- Publishable keys score `0.9` regardless of environment.
+- Minimum 24-character suffix requirement filters out truncated or partial
+  matches.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/stripe';
+
+const matches = detect('STRIPE_SECRET=sk_live_ABCDEFGHIJKLMNOPQRSTUVWX');
+// matches[0].type === 'stripe-secret'
+// matches[0].confidence === 0.99
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/stripe';
+
+const env = 'sk_test_TESTKEY1234567890123456 pk_live_PUBKEY1234567890123456';
+const matches = detect(env);
+// matches[0].type === 'stripe-secret', confidence 0.9 (test key)
+// matches[1].type === 'stripe-publishable', confidence 0.9
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for Stripe secret and publishable keys.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan |
+
+Returns an array of `SecurityCodeMatch` objects. Live secret keys have
+`confidence: 0.99`, all other variants have `confidence: 0.9`.
+
+## Implementation Notes
+
+Stripe's key format is documented in their API reference. The `\b` word
+boundary on both ends prevents matching a key that is part of a longer
+alphanumeric string. Both regex objects have `lastIndex` reset before each
+scan to handle repeated calls safely.
+
+Distinguishing live from test keys matters because test keys can be committed
+to public repositories intentionally (for CI integration tests), while live
+keys must never appear outside of secrets management infrastructure. The
+confidence delta between `sk_live_` (`0.99`) and `sk_test_` (`0.9`) allows
+callers to apply a stricter response policy to live keys — for example,
+immediately revoking them via Stripe's API — while treating test-key
+detections as lower-priority warnings. Publishable keys are tracked at `0.9`
+to surface environment-confusion issues during code review.