# Decoder Ring

> A browser-based developer toolkit for decoding, encoding, inspecting, and formatting tokens, timestamps, and data — everything runs locally in the browser and nothing is ever sent to a server.

Decoder Ring is a single-page application aimed at developers who regularly work with authentication tokens, identity protocols, and structured data. Every tool operates entirely client-side: no data leaves the browser at any point.

The app is available at the root path `/`. Each tool is accessible via a predictable URL path (`/{tab}` or `/{tab}/{mode}`) and every view is deep-linkable and bookmarkable. Legacy `?decoder=X&mode=Y` query-string URLs redirect automatically to the equivalent path.


## JWT — JSON Web Tokens

**Paths:** `/jwt` (defaults to decode), `/jwt/decode`, `/jwt/encode`

### JWT Decoder (`/jwt/decode`)

**Input:** A JWT string in the standard three-segment dot-separated format (header.payload.signature). Supports any algorithm header value; parses structure regardless of algorithm.

**Output:**
- Header section: decoded JSON with syntax highlighting
- Payload section: decoded JSON with syntax highlighting; `exp`, `iat`, `nbf` fields are rendered as human-readable dates alongside their raw numeric values; an expiry badge ("Expired" / "Valid" / time remaining) is shown inline with the `exp` field
- Signature section: the raw base64url-encoded signature string; note that signature verification is not performed client-side

**Notable features:**
- One-click copy for any section
- Example token button for immediate exploration

### JWT Encoder (`/jwt/encode`)

**Input:** Algorithm selection, signing secret (HMAC), header claims (JSON), payload claims (JSON).

**Output:** A signed or unsigned JWT string, ready to copy.

**Supported algorithms:** HS256 (HMAC-SHA256), HS384 (HMAC-SHA384), HS512 (HMAC-SHA512), None (unsigned). All signed algorithms use a symmetric HMAC secret string; asymmetric key algorithms are not supported.

**Notable features:**
- JSON-aware code editors for Header Claims and Payload Claims fields: full syntax highlighting (cyan keys, green strings, amber numbers, violet booleans), live JSON parse-error underlines, bracket matching, auto-close brackets, smart indentation
- Payload templates for the None algorithm: choose an identification template (email address, org route) or a registration template (full name, preferred name) from a dropdown that appears when None is selected; switching to None auto-applies the identification template when the payload is blank
- All settings (algorithm, secret, header claims, payload claims, last encoded token, selected template) are automatically saved to `localStorage` and restored on reload
- "Clear saved settings" button resets to defaults and wipes localStorage
- Encoded JWT is shared with the OIDC Sandbox via localStorage so it can be dropped directly into the `login_hint` field


## SAML — Security Assertion Markup Language

**Paths:** `/saml` (defaults to decode), `/saml/decode`, `/saml/encode`

### SAML Decoder (`/saml/decode`)

**Input:** A base64-encoded SAML assertion or raw SAML XML.

**Output:**
- Formatted, indented XML with syntax highlighting
- Attributes table: every SAML attribute extracted into name / value rows
- Date fields (`NotBefore`, `NotOnOrAfter`, `IssueInstant`) are validated and labelled inline ("Not Valid Yet", "Expired", or the parsed date)

### SAML Encoder (`/saml/encode`)

**Input:** SAML XML to encode.

**Output:** A base64-encoded SAML string, ready to use in a POST binding or URL parameter.


## OIDC — OpenID Connect

**Paths:** `/oidc` (defaults to sandbox), `/oidc/sandbox`, `/oidc/pkce`

### OIDC Sandbox (`/oidc`, `/oidc/sandbox`)

A full Authorization Code + PKCE flow runner that operates entirely in the browser.

**Configuration inputs:**
- Authorization endpoint URL
- Token endpoint URL
- Client ID
- Scopes (space-separated; defaults include `openid profile email`)
- Redirect URI (defaults to the current page)
- Optional revocation endpoint URL
- Optional advanced parameters: `prompt`, `login_hint`, `max_age`, `acr_values`

All configuration is persisted to `localStorage` and restored on reload. OpenID Connect Discovery: paste an issuer URL to auto-populate all endpoint fields from the provider's `/.well-known/openid-configuration` document.

**Flow:**
1. "Start flow" generates a PKCE pair, stores the verifier in `sessionStorage`, and redirects the browser to the authorization endpoint with the code challenge
2. After the provider redirects back, the sandbox automatically detects the `code` parameter and exchanges it for tokens at the token endpoint
3. The token response is displayed in full (colorized JWT view for access and ID tokens, raw JSON for the full response)

**Token display:**
- Access token decoded as JWT when possible: header, payload with syntax-highlighted claim values, signature segment
- ID token decoded with full claim list
- Refresh token expiry shown when `refresh_token_expires_in` is present in the response

**Token revocation (RFC 7009):**
- "Revoke" button available on access tokens and refresh tokens
- Sends a POST to the revocation endpoint with the token and `token_type_hint`
- Full HTTP response shown (status code + body, pretty-printed if JSON)
- Clear error message distinguishes CORS-blocked requests from other failures
- Revoke button disabled and token marked "Revoked" after a successful call; state resets when starting a new flow

**"Use JWT" button:**
- Appears next to the `login_hint` field; one click drops the saved encoded JWT (from the JWT Encoder) directly into the field
- Disabled with a tooltip when no JWT has been saved yet

### PKCE Generator (`/oidc/pkce`)

**Input:** None. Values are generated automatically on page load.

**Output:**
- Code verifier: a cryptographically random base64url string (43-128 characters), generated using `crypto.getRandomValues`
- Code challenge: the SHA-256 hash of the verifier, base64url-encoded (the S256 method required by RFC 7636)

**Notable features:** A "Regenerate" button produces a fresh pair on demand. Both output fields are read-only; one-click copy for each value.


## Base Encoding

**Path:** `/base64` (defaults to decode), `/base64/encode`

**Supported formats:** Base64, Base64url, Base32 (RFC 4648), Base16 (hexadecimal), Base58 (Bitcoin alphabet), Base62 (alphanumeric 0-9A-Za-z)

**Modes:** Decode (default), Encode

**Input:** Any text string. For decode mode, a string in the selected encoding format.

**Output:** Decoded plain text, or the input string encoded in the selected format.

**Layout:** Two-column (input left, output right) on screens ≥1024 px.


## Web Tools

**Path:** `/web` (defaults to URL decode/encode)

### URL Encoder / Decoder (`/web`)

**Input:** A URL-encoded string or plain text.

**Output:** Decoded plain text, or URL-percent-encoded string.

**Layout:** Two-column on wide screens.

### HAR Parser (`/web/har`)

**Input:** An HTTP Archive (HAR) file — either uploaded via file picker or pasted as JSON text.

**Output:**
- List of all network requests with method, URL, status code, content type, and timing
- Expandable detail view per request: request headers, response headers, query parameters, cookies, request body, response body, timing waterfall

**Security — automatic redaction:**
Every displayed HAR is scrubbed before rendering. The following are replaced with `[REDACTED]`:
- `Cookie` / `Set-Cookie` headers
- `Authorization` headers
- Values of fields named `token`, `access_token`, `refresh_token`, `id_token`, `api_key`, `apikey`, `password`, `secret`, `session`, `jwt`

The original uploaded data is never transmitted anywhere. A "Download redacted HAR" button exports the scrubbed version as a `.har` file so network traces can be shared safely.

**Performance:** 500 ms debounce on paste input; first 50 entries rendered with a "Load More" button; file size warning for inputs >5 MB; spinner during parse and redaction.

**Layout:** Two-column on wide screens.

### String Escaper (`/web/escape`)

**Input:** A raw string to escape, or an escaped string (with or without outer JSON quotes) to unescape.

**Output:**
- Escape mode: applies `JSON.stringify` semantics — wraps in double quotes, escapes `\n`, `\t`, `\"`, `\\`, `\uXXXX` for non-ASCII characters
- Unescape mode: accepts a JSON string literal (with outer quotes) or a raw escaped string; resolves all standard escape sequences including `\n`, `\t`, `\r`, `\"`, `\\`, `\uXXXX`, `\xXX`


## Timestamps

**Path:** `/timestamp` (defaults to decode), `/timestamp/decode`, `/timestamp/timezone`

### Timestamp Decoder (`/timestamp/decode`)

**Decode input:** A Unix timestamp (seconds or milliseconds) or an ISO 8601 / Zulu datetime string pasted into a single text field.

**Decode output:** The input is auto-detected and all of the following are shown simultaneously:
- Human-readable local date and time
- ISO 8601 / Zulu string
- UTC string
- Relative time (e.g. "3 hours ago", "in 2 days")

**Encode input:** A date/time picker field.

**Encode output:** The corresponding Unix timestamp (seconds) and ISO 8601 string.

**Notable features:** Auto-detects whether the input is Unix seconds, Unix milliseconds, or ISO 8601 / Zulu. One-click copy for each output value.

### Timezone Converter (`/timestamp/timezone`)

**Input:** A date input, a time input, a source timezone, and a target timezone.

**Output:** The equivalent date and time in the target timezone, with the UTC offset displayed for both zones.

**Notable features:** Timezone dropdowns offer a curated selection of ~18 commonly-used zones across the US, Europe, Asia, and Pacific regions (UTC, ET, CT, MT, PT, AKT, HT, London, Paris, Berlin, Moscow, Dubai, India, China, Japan, Korea, Sydney, Auckland). A "Now" button fills in the current date and time.


## JSON / XML Beautifier

**Path:** `/beautify` (defaults to JSON), `/beautify/json`, `/beautify/xml`

**Layout:** Two-column (input left, output right) on wide screens.

### JSON Beautifier (`/beautify/json`)

**Input:** Any valid (or minified) JSON string.

**Output:**
- Beautify mode: pretty-printed JSON with 2-space indentation
- Minify mode: compact single-line JSON with all whitespace removed
- Format validation: displays a clear parse error when the input is not valid JSON

### XML Beautifier (`/beautify/xml`)

**Input:** Any valid XML string, including minified XML.

**Output:**
- Beautify mode: indented XML preserving all node types — elements, text nodes, comments (`<!-- -->`), CDATA sections (`<![CDATA[...]]>`), processing instructions (`<?...?>`), DOCTYPE declarations, and XML declarations (`<?xml version="1.0"?>`)
- Minify mode: uses `XMLSerializer` to produce compact XML with whitespace-only text nodes stripped
- Format validation: displays a parser error when the input is not well-formed XML


## Privacy and Architecture

**All processing is client-side.** Decoder Ring is a static single-page application served by a minimal Express server whose only job is to deliver the compiled assets. There are no API routes that receive user data, no analytics, no logging of inputs, and no third-party data processing.

- JWT parsing uses the `jwt-decode` library in the browser
- SAML and XML parsing use the browser's native `DOMParser`
- JSON parsing uses native `JSON.parse` / `JSON.stringify`
- Timestamp parsing uses native JavaScript `Date`
- OIDC token exchange calls are made directly from the browser to the identity provider — the app server is not in the request path
- HAR files are parsed, redacted, and displayed entirely in memory; the original bytes never leave the tab

`localStorage` is used only to persist user preferences (theme, last-used settings for the JWT Encoder and OIDC Sandbox). No authentication or user accounts exist.