npm package: @ideascol/jwt-inspector
Description: A comprehensive library for verifying JWTs (JSON Web Tokens) ensuring compliance with OWASP security recommendations. This library validates the structure, signature, and claims of JWTs, checks for secure algorithms, enforces size constraints, and ensures
Author: Andres Fernandez
Latest version: 0.0.5

# JWT Inspector

![Version](https://img.shields.io/npm/v/@ideascol/jwt-inspector) ![License](https://img.shields.io/npm/l/@ideascol/jwt-inspector) ![Downloads](https://img.shields.io/npm/dt/@ideascol/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

```bash
# 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

```bash
# 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:

```typescript
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

```typescript
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](https://ideascol.com) - Protecting applications through advanced security tooling.