JWT Inspector

A comprehensive security tool for validating and auditing JSON Web Tokens (JWTs). This tool helps security professionals analyze JWT structure, signature, and claim validity to identify security issues and potential vulnerabilities.

Features

• Comprehensive JWT structure validation
• Thorough claims verification (iat, exp, nbf, aud, iss, etc.)
• Signature verification with secure key validation
• Secret key strength analysis
• Token duration security assessment
• Detailed audit reports with pass/fail/warning statuses
• Both CLI and programmatic usage

Installation

# Using npm
npm install -g @ideascol/jwt-inspector

# Using bun (recommended for better performance)
bun install -g @ideascol/jwt-inspector

Usage as CLI

Validate JWT Structure

# Full command with options
jwt-inspector validate-structure -token=[YOUR_JWT_TOKEN] -secret=[YOUR_SECRET_KEY]

# Interactive mode (will prompt for inputs)
jwt-inspector validate-structure

The CLI will output a detailed audit report including:

• Overall token validity status
• Token size and structure analysis
• Header validation results (algorithm, type)
• Claims presence and validity
• Expiration and temporal claim checks
• Key strength assessment (when secret is provided)
• Signature validation results (when secret is provided)

Security Recommendations

The tool provides actionable security recommendations for improving JWT security, such as:

• Secret key length and complexity requirements
• Token duration best practices
• Required claims for enhanced security

Usage as Library

You can integrate JWT Inspector directly into your security applications:

import { ValidateJwt, ValidateSecretKey } from '@ideascol/jwt-inspector';

// Validate a JWT token with signature verification
const results = ValidateJwt('your.jwt.token');
console.log(results);

// Validate only the secret key strength
const keyResults = ValidateSecretKey('your-secret-key');
console.log(keyResults);

API Reference

ValidateJwt(token: string, options?: ValidateOptions): JwtAuditResult

Validates a JWT token and returns a comprehensive audit result.

• token: The JWT token to validate
• options: (Optional)
  • key: Secret key for signature verification
  • output: Output format ('json' or 'text')
  • keyStrengthResults: Pre-computed key strength results

ValidateSecretKey(key: string): KeyStrengthResult[]

Validates the security strength of a secret key.

• key: The secret key to validate
• Returns: Array of validation results with security assessments

Result Structure

interface JwtAuditResult {
  auditTimestamp: string;     // ISO timestamp when the audit was performed
  isValid: boolean;           // Overall validity of the token
  results: ValidationResult[]; // Detailed validation results
  errors: string[];           // Critical errors found during validation
  warnings: string[];         // Security warnings and recommendations
}

Security Best Practices

When using JWTs in your applications, follow these security best practices:

1. Use strong secret keys (32+ characters with mixed case, numbers, and special characters)
2. Set reasonable expiration times (shorter is better)
3. Include all standard claims (iss, aud, sub, jti)
4. Always verify signatures in production environments
5. Use the 'nbf' (Not Before) claim to prevent token use before a specified time

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed by IdeasCol Digital Security Team - Protecting applications through advanced security tooling.