65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# jwt
|
|
|
|
## Purpose
|
|
|
|
Detects JSON Web Tokens (JWTs) embedded in arbitrary strings. JWTs are
|
|
bearer tokens with a well-defined three-part base64url structure
|
|
(`header.payload.signature`). Leaking JWTs in logs, error messages, or
|
|
configuration files grants an attacker the same privileges as the original
|
|
holder until the token expires.
|
|
|
|
## Features
|
|
|
|
- Regex matches the canonical `eyJ...` header prefix followed by two more
|
|
base64url segments separated by dots.
|
|
- Secondary validation: decodes and JSON-parses the header segment to
|
|
confirm the match is a real JWT (not a coincidental dot-separated string).
|
|
- Uses `atob` for base64url decoding — available in all modern runtimes
|
|
including Node.js ≥16 and all browsers.
|
|
- Returns confidence `0.9` — the structural validation makes false positives
|
|
unlikely, while `1.0` is reserved for signatures that are cryptographically
|
|
verified.
|
|
|
|
## Usage: Basic Example
|
|
|
|
```ts
|
|
import { detect } from '@suaveplan/security-codes/patterns/jwt';
|
|
|
|
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
|
|
const matches = detect(`Authorization: Bearer ${token}`);
|
|
// matches[0].type === 'jwt'
|
|
```
|
|
|
|
## Usage: Advanced Example
|
|
|
|
```ts
|
|
import { detect } from '@suaveplan/security-codes/patterns/jwt';
|
|
|
|
// Multiple tokens in a single string
|
|
const text = 'token1=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4In0.abc token2=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ4In0.def';
|
|
const matches = detect(text);
|
|
console.log(matches.length); // 2
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### `detect(input: string): SecurityCodeMatch[]`
|
|
|
|
Scans `input` for JWTs.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `input` | `string` | The string to scan |
|
|
|
|
Returns an array of `SecurityCodeMatch` with `type: 'jwt'` and
|
|
`confidence: 0.9`. Returns an empty array when no valid JWTs are found.
|
|
Matches that pass the regex but fail the header JSON-parse are silently
|
|
dropped.
|
|
|
|
## Implementation Notes
|
|
|
|
The regex anchors on `\b` to avoid matching base64 blobs embedded inside
|
|
longer tokens. The header validation uses `atob` rather than a Node-only
|
|
`Buffer` to keep the module runtime-agnostic. The signature segment is not
|
|
cryptographically verified — that is outside the scope of detection.
|