first commit

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

@@ -0,0 +1,65 @@
+# openai
+
+## Purpose
+
+Detects OpenAI API keys in arbitrary strings. OpenAI API keys follow the
+format `sk-<48 chars>` for standard keys and `sk-proj-<48+ chars>` for
+project-scoped keys. Exposing these credentials allows unauthorized access
+to OpenAI's models, incurring cost and potential data leakage.
+
+## Features
+
+- Handles both standard (`sk-`) and project-scoped (`sk-proj-`) key formats.
+- Project keys are matched first; the shorter `sk-` pattern skips positions
+  already claimed by a project key to avoid double-reporting.
+- Project keys receive a slightly higher confidence (`0.95`) than standard
+  keys (`0.92`) due to the more distinctive prefix.
+- Word-boundary anchors on both ends.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/openai';
+
+const matches = detect('OPENAI_API_KEY=sk-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv');
+// matches[0].type === 'openai-key'
+// matches[0].confidence === 0.92
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/openai';
+
+const text = 'key=sk-proj-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const matches = detect(text);
+// matches[0].type === 'openai-key'
+// matches[0].confidence === 0.95
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for OpenAI API keys.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan |
+
+Returns an array of `SecurityCodeMatch` with `type: 'openai-key'`.
+Standard keys have `confidence: 0.92`; project keys have `confidence: 0.95`.
+
+## Implementation Notes
+
+The project-key regex (`sk-proj-`) is tested first and winning positions are
+recorded in a `Set` so the standard-key regex does not produce duplicate
+matches for the same token. Both regexes reset `lastIndex` before scanning.
+
+OpenAI introduced project-scoped keys to allow tighter permission boundaries
+per API project. Detecting them separately lets security tooling distinguish
+between a leaked organisation-wide key (higher blast radius) and a
+project-scoped key (limited blast radius). The 48-character suffix length for
+standard keys and the extended suffix for project keys match OpenAI's published
+key format; the exact length boundary is enforced via `{48,}` to tolerate any
+future increases without requiring a regex update.