JWT Decoder & Toothpick
Relevant source files
The following files were used as context for generating this wiki page:
The JWT Decoder & Toothpick is a dual-module system within the DevUtils suite designed for inspecting, generating, and security-testing JSON Web Tokens (JWT). The system consists of the JWT Decoder (internally referred to as the "JWT Can Opener"), which handles standard decoding and generation, and the JWT Toothpick, an educational brute-force tool for probing weak HMAC secrets.
These tools are built using React and leverage the jose library for cryptographic operations, ensuring that all token processing occurs locally within the application to maintain security.
Sources: README.md:16, components/tools/jwt-decoder.tsx:1-20, messages/en.json:44-67
JWT Decoder (Can Opener)
The JWT Decoder module provides a user interface for both inspecting existing tokens and creating new ones. It supports real-time validation, expiry tracking, and signature inspection.
Architecture and Data Flow
The module is divided into two primary functional tabs: Decode Token and Generate Token. When a user inputs a token, the application performs a Base64URL decode on the three standard JWT segments (Header, Payload, and Signature).
The decoding logic utilizes a custom base64UrlDecode function to handle URL-safe characters and UTF-8 encoding.
Sources: components/tools/jwt-decoder.tsx:55-100, components/tools/jwt-decoder.tsx:210-250
Functional Components
| Feature | Description |
|---|---|
| Token Input | Textarea for pasting JWTs with support for clipboard synchronization. |
| Real-time Decoding | Automatically parses headers and payloads as the user types. |
| Expiry Countdown | Calculates the difference between the exp claim and current system time, updating every second. |
| Token Generation | Allows users to specify custom JSON headers/payloads and a secret key to sign new HS256 tokens. |
Sources: components/tools/jwt-decoder.tsx:110-145, messages/en.json:48-60
Token Generation Logic
Generation is handled by the jose library's SignJWT class. It supports standard claims including iat (Issued At), exp (Expiration), nbf (Not Before), sub (Subject), and others.
Sources: components/tools/jwt-decoder.tsx:156-189, package.json:54
JWT Toothpick (Brute-Force)
The JWT Toothpick is an educational utility designed to test the strength of HMAC secrets (HS256, HS384, HS512) used in JWT signatures. It allows developers to "stress-test" tokens against a wordlist of common weak passwords.
Logic and Execution Flow
The tool iterates through a provided wordlist (up to 2,000 secrets) and attempts to verify the token signature using each entry.
Security and Education
To remain within a validity window during testing, the tool intelligently selects a verification date:
- It uses the
iat(Issued At) claim if present. - If
iatis missing, it uses a date 1 day before theexp(Expiration) claim. - Otherwise, it defaults to the Unix Epoch (1970).
Sources: components/tools/jwt-toothpick.tsx:107-118
Performance Metrics
The system tracks and displays several real-time metrics during a brute-force run:
- Attempts Made: Total number of secrets tested.
- Speed: Guesses per second (GPS).
- Elapsed Time: Total time since the start of the attack.
- Recent Attempts: A log showing the last 6 secrets tried and their result (Hit/Miss).
Sources: components/tools/jwt-toothpick.tsx:165-185, components/tools/jwt-toothpick.tsx:325-360
Technical Specifications
Supported Algorithms
| Module | Supported HMAC Algorithms |
|---|---|
| Decoder | Any valid JWT (HS256 for generation) |
| Toothpick | HS256, HS384, HS512 |
Sources: components/tools/jwt-decoder.tsx:161, components/tools/jwt-toothpick.tsx:145-150
Key Data Structures
The Toothpick utilizes an Attempt interface to track the state of the brute-force process:
interface Attempt {
secret: string;
success: boolean;
elapsedMs: number;
id?: string;
}
Sources: components/tools/jwt-toothpick.tsx:27-32
Summary
The JWT tools in DevUtils provide a comprehensive environment for working with JSON Web Tokens. While the Decoder focuses on the utility of inspecting and generating compliant tokens, the Toothpick serves as a security awareness tool to demonstrate the vulnerability of short or common HMAC secrets. All operations are performed locally using the jose library, ensuring user tokens and secrets are never transmitted over the network.
Sources: README.md:16, components/tools/jwt-toothpick.tsx:215-225