first commit

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

@@ -0,0 +1,65 @@
+# google
+
+## Purpose
+
+Detects Google API keys embedded in arbitrary strings. Google API keys begin
+with the well-known prefix `AIza` and are used to authenticate requests to
+Google Cloud APIs, Maps, Firebase, and other Google services. Leaking these
+keys in source code or logs can result in unexpected billing and unauthorized
+access to Google services.
+
+## Features
+
+- Regex anchored with `\b` on both ends to avoid matching substrings of
+  longer tokens.
+- Fixed 35-character suffix using URL-safe base64 characters (`[0-9A-Za-z-_]`).
+- Returns confidence `0.9` — the fixed prefix is distinctive but not as unique
+  as AWS or Stripe prefixes.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/google';
+
+const matches = detect('GOOGLE_API_KEY=AIzaSyDummyKey12345678901234567890123');
+// matches[0].type === 'google-api-key'
+// matches[0].confidence === 0.9
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/google';
+
+const config = JSON.stringify({ apiKey: 'AIzaSyDummyKey12345678901234567890123' });
+const matches = detect(config);
+console.log(matches[0].start, matches[0].end);
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for Google API keys.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan |
+
+Returns an array of `SecurityCodeMatch` with `type: 'google-api-key'` and
+`confidence: 0.9`.
+
+## Implementation Notes
+
+The `AIza` prefix is used by Google for API keys across many of their services.
+The trailing character set (`[0-9A-Za-z-_]`) is the URL-safe base64 alphabet,
+matching Google's actual key encoding. `lastIndex` is reset before each scan.
+
+The confidence value of `0.9` is intentionally conservative relative to
+Stripe or GitHub patterns, because the `AIza` prefix is shorter and the
+character set is broad enough that coincidental matches in large documents are
+plausible. Callers that process Google-specific configuration files may wish to
+raise `minConfidence` to `0.95` and accept the small risk of missing an
+obfuscated key, while callers performing broad log sweeps should leave it at
+the default to maximise recall. The 35-character suffix length matches the
+actual key length as observed in Google Cloud Console-issued credentials.