first commit

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

@@ -0,0 +1,65 @@
+# entropy
+
+## Purpose
+
+Detects high-entropy strings that are likely secret tokens, API keys, or
+passwords using Shannon entropy analysis. This heuristic catches secrets that
+have no fixed prefix and would be missed by pattern-based detectors.
+While less precise than dedicated pattern detectors, it provides a useful
+catch-all for novel or unrecognized credential formats.
+
+## Features
+
+- Scans for base64/hex-alphabet runs of at least 20 characters.
+- Computes Shannon entropy (bits per character) for each candidate.
+- Returns only candidates with entropy ≥ 4.5 bits per character, a threshold
+  calibrated to separate random tokens from natural-language substrings.
+- Returns a deliberately conservative confidence of `0.6` to reflect the
+  heuristic nature of the detection.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/entropy';
+
+// A random-looking base64 string
+const matches = detect('secret=aB3dEfGhIjKlMnOpQrStUvWxYz012345678901');
+// matches[0].type === 'high-entropy', confidence 0.6
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/entropy';
+
+// Short or low-entropy strings are not flagged
+const noMatch = detect('hello world this is plain text');
+console.log(noMatch.length); // 0
+
+// High-entropy token is flagged
+const match = detect('TOKEN=xK8mP2nQ9rS5tV7wY1aB4cD6eF0gH3iJ');
+console.log(match[0].confidence); // 0.6
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for high-entropy strings.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan |
+
+Returns an array of `SecurityCodeMatch` with `type: 'high-entropy'` and
+`confidence: 0.6`. Returns an empty array when no high-entropy candidates
+are found.
+
+## Implementation Notes
+
+Shannon entropy `H = -∑ p(x) log₂ p(x)` over a string's character frequency
+distribution. Natural English text scores around 3.5–4.0 bits per character;
+random tokens typically exceed 4.5. The threshold was chosen empirically to
+minimise false positives on common identifiers and UUIDs while still catching
+hex-encoded secrets and base64 tokens. The minimum length of 20 characters
+filters out short words that happen to have high entropy due to their brevity.