first commit

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

@@ -0,0 +1,67 @@
+# pem
+
+## Purpose
+
+Detects PEM-encoded blocks in arbitrary strings. PEM (Privacy Enhanced Mail)
+is the standard encoding for TLS certificates, RSA/EC private keys, certificate
+signing requests, and public keys. Leaking private-key PEM blocks in logs or
+error messages compromises the entire cryptographic identity of the affected
+service.
+
+## Features
+
+- Regex uses a non-greedy `[\s\S]*?` between the `-----BEGIN … -----` and
+  `-----END … -----` markers to match the full block including newlines.
+- Matches any PEM type: `RSA PRIVATE KEY`, `EC PRIVATE KEY`,
+  `CERTIFICATE`, `CERTIFICATE REQUEST`, `PUBLIC KEY`, etc.
+- Returns confidence `0.97` — the fixed delimiter format makes false positives
+  extremely unlikely.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/pem';
+
+const pem = '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA0Z3V...\n-----END RSA PRIVATE KEY-----';
+const matches = detect(pem);
+// matches[0].type === 'pem-block'
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/pem';
+
+// Embedded in a config file
+const config = `tls_cert: |\n  -----BEGIN CERTIFICATE-----\n  MIIBxTCC...\n  -----END CERTIFICATE-----`;
+const matches = detect(config);
+console.log(matches[0].confidence); // 0.97
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for PEM blocks.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan (may contain newlines) |
+
+Returns an array of `SecurityCodeMatch` with `type: 'pem-block'` and
+`confidence: 0.97`. The `value` includes the full block including header,
+base64 content, and footer.
+
+## Implementation Notes
+
+The regex uses the `g` flag with `lastIndex` reset before each call. The
+`[\s\S]*?` pattern enables cross-line matching without the `s` (dotAll) flag,
+ensuring compatibility with environments where dotAll behaviour may differ.
+
+The non-greedy quantifier is critical here: a greedy `[\s\S]*` would consume
+everything between the first `-----BEGIN` and the last `-----END` in a
+multi-certificate chain, collapsing multiple blocks into a single oversized
+match. The non-greedy form correctly yields one match per PEM block. The
+confidence of `0.97` is among the highest in the package because the
+`-----BEGIN … -----` / `-----END … -----` framing is extremely unlikely to
+appear in non-PEM text, making false positives rare even in noisy inputs.