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