@claude-agent/jwt-explain 1.0.0

package/bin/cli.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+/**
+ * jwt-explain CLI
+ * Decode and explain JWT tokens in plain English
+ */
+
+'use strict';
+
+const {
+  decode,
+  validate,
+  explain,
+  format,
+  isExpired,
+  getTimeUntilExpiry,
+  getRegisteredClaims,
+  getCommonClaims,
+  getAlgorithms
+} = require('../src/index.js');
+
+const HELP = `
+jwt-explain - Decode and explain JWT tokens in plain English
+
+USAGE:
+  jwt-explain <token>              Explain a JWT token
+  jwt-explain -d <token>           Decode and show raw parts
+  jwt-explain -v <token>           Validate token structure
+  jwt-explain -e <token>           Check if token is expired
+  jwt-explain --claims             List registered JWT claims
+  jwt-explain --algorithms         List signing algorithms
+
+OPTIONS:
+  -d, --decode       Decode and show raw header/payload JSON
+  -v, --validate     Validate token structure
+  -e, --expiry       Show expiration status
+  -D, --detailed     Show detailed explanations
+      --no-color     Disable colored output
+  -j, --json         Output as JSON
+      --claims       List all registered claims
+      --algorithms   List all algorithms
+  -h, --help         Show this help
+  -V, --version      Show version
+
+EXAMPLES:
+  jwt-explain eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+  jwt-explain -d "Bearer eyJhbGciOiJIUzI1NiI..."
+  jwt-explain -v eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+  jwt-explain -e eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+  jwt-explain --claims
+  jwt-explain --algorithms
+
+NOTES:
+  - This tool decodes JWTs but does NOT verify signatures
+  - Never trust a decoded JWT without verification
+  - "Bearer " prefix is automatically stripped
+
+Built autonomously by Claude (Anthropic's AI)
+https://github.com/claude-agent-tools/jwt-explain
+`;
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Parse options
+  let mode = 'explain';
+  let detailed = false;
+  let useColor = process.stdout.isTTY !== false;
+  let json = false;
+  let token = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      console.log(HELP);
+      process.exit(0);
+    }
+
+    if (arg === '-V' || arg === '--version') {
+      const pkg = require('../package.json');
+      console.log(pkg.version);
+      process.exit(0);
+    }
+
+    if (arg === '-D' || arg === '--detailed') {
+      detailed = true;
+      continue;
+    }
+
+    if (arg === '--no-color') {
+      useColor = false;
+      continue;
+    }
+
+    if (arg === '-j' || arg === '--json') {
+      json = true;
+      continue;
+    }
+
+    if (arg === '-d' || arg === '--decode') {
+      mode = 'decode';
+      continue;
+    }
+
+    if (arg === '-v' || arg === '--validate') {
+      mode = 'validate';
+      continue;
+    }
+
+    if (arg === '-e' || arg === '--expiry') {
+      mode = 'expiry';
+      continue;
+    }
+
+    if (arg === '--claims') {
+      mode = 'claims';
+      continue;
+    }
+
+    if (arg === '--algorithms') {
+      mode = 'algorithms';
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}`);
+      console.error('Use --help for usage information');
+      process.exit(2);
+    }
+
+    token = arg;
+  }
+
+  // Handle info modes
+  if (mode === 'claims') {
+    const claims = { ...getRegisteredClaims(), ...getCommonClaims() };
+    if (json) {
+      console.log(JSON.stringify(claims, null, 2));
+    } else {
+      const bold = useColor ? '\x1b[1m' : '';
+      const cyan = useColor ? '\x1b[36m' : '';
+      const blue = useColor ? '\x1b[34m' : '';
+      const magenta = useColor ? '\x1b[35m' : '';
+      const reset = useColor ? '\x1b[0m' : '';
+
+      console.log(`${bold}Registered Claims:${reset}`);
+      console.log('');
+      for (const [key, info] of Object.entries(getRegisteredClaims())) {
+        console.log(`  ${blue}${key.padEnd(10)}${reset} ${info.name} - ${info.description}`);
+      }
+      console.log('');
+      console.log(`${bold}Common Claims:${reset}`);
+      console.log('');
+      for (const [key, info] of Object.entries(getCommonClaims())) {
+        console.log(`  ${magenta}${key.padEnd(15)}${reset} ${info.name} - ${info.description}`);
+      }
+    }
+    process.exit(0);
+  }
+
+  if (mode === 'algorithms') {
+    const algs = getAlgorithms();
+    if (json) {
+      console.log(JSON.stringify(algs, null, 2));
+    } else {
+      const bold = useColor ? '\x1b[1m' : '';
+      const cyan = useColor ? '\x1b[36m' : '';
+      const green = useColor ? '\x1b[32m' : '';
+      const yellow = useColor ? '\x1b[33m' : '';
+      const red = useColor ? '\x1b[31m' : '';
+      const reset = useColor ? '\x1b[0m' : '';
+
+      console.log(`${bold}JWT Signing Algorithms:${reset}`);
+      console.log('');
+
+      const byType = { symmetric: [], asymmetric: [], none: [] };
+      for (const [key, info] of Object.entries(algs)) {
+        byType[info.type].push({ key, ...info });
+      }
+
+      console.log(`${bold}Symmetric (shared secret):${reset}`);
+      for (const alg of byType.symmetric) {
+        console.log(`  ${green}${alg.key.padEnd(8)}${reset} ${alg.description}`);
+      }
+
+      console.log('');
+      console.log(`${bold}Asymmetric (public/private key):${reset}`);
+      for (const alg of byType.asymmetric) {
+        console.log(`  ${cyan}${alg.key.padEnd(8)}${reset} ${alg.description}`);
+      }
+
+      console.log('');
+      console.log(`${bold}Insecure:${reset}`);
+      for (const alg of byType.none) {
+        console.log(`  ${red}${alg.key.padEnd(8)}${reset} ${alg.description}`);
+      }
+    }
+    process.exit(0);
+  }
+
+  // Modes that require a token
+  if (!token) {
+    console.error('Error: No JWT token provided');
+    console.error('Usage: jwt-explain <token>');
+    console.error('Use --help for more information');
+    process.exit(2);
+  }
+
+  // Handle different modes
+  switch (mode) {
+    case 'decode': {
+      const decoded = decode(token);
+      if (!decoded) {
+        console.error('Error: Invalid JWT token format');
+        process.exit(1);
+      }
+
+      if (json) {
+        console.log(JSON.stringify({
+          header: decoded.header,
+          payload: decoded.payload,
+          signature: decoded.signature
+        }, null, 2));
+      } else {
+        const bold = useColor ? '\x1b[1m' : '';
+        const cyan = useColor ? '\x1b[36m' : '';
+        const reset = useColor ? '\x1b[0m' : '';
+
+        console.log(`${bold}Header:${reset}`);
+        console.log(cyan + JSON.stringify(decoded.header, null, 2) + reset);
+        console.log('');
+        console.log(`${bold}Payload:${reset}`);
+        console.log(cyan + JSON.stringify(decoded.payload, null, 2) + reset);
+        console.log('');
+        console.log(`${bold}Signature:${reset}`);
+        console.log(decoded.signature);
+      }
+      break;
+    }
+
+    case 'validate': {
+      const result = validate(token);
+
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const bold = useColor ? '\x1b[1m' : '';
+        const green = useColor ? '\x1b[32m' : '';
+        const red = useColor ? '\x1b[31m' : '';
+        const yellow = useColor ? '\x1b[33m' : '';
+        const reset = useColor ? '\x1b[0m' : '';
+
+        console.log(`${bold}Validation Result:${reset}`);
+        console.log('');
+
+        if (result.valid) {
+          console.log(`${green}✓ Token has valid JWT structure${reset}`);
+        } else {
+          console.log(`${red}✗ Token has invalid JWT structure${reset}`);
+        }
+
+        if (result.errors.length > 0) {
+          console.log('');
+          console.log(`${bold}Errors:${reset}`);
+          for (const error of result.errors) {
+            console.log(`  ${red}✗ ${error}${reset}`);
+          }
+        }
+
+        if (result.warnings.length > 0) {
+          console.log('');
+          console.log(`${bold}Warnings:${reset}`);
+          for (const warning of result.warnings) {
+            console.log(`  ${yellow}⚠ ${warning}${reset}`);
+          }
+        }
+      }
+
+      process.exit(result.valid ? 0 : 1);
+    }
+
+    case 'expiry': {
+      const result = getTimeUntilExpiry(token);
+
+      if (result.error) {
+        console.error(`Error: ${result.error}`);
+        process.exit(1);
+      }
+
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const bold = useColor ? '\x1b[1m' : '';
+        const green = useColor ? '\x1b[32m' : '';
+        const red = useColor ? '\x1b[31m' : '';
+        const yellow = useColor ? '\x1b[33m' : '';
+        const reset = useColor ? '\x1b[0m' : '';
+
+        if (result.neverExpires) {
+          console.log(`${yellow}⚠ Token has no expiration${reset}`);
+        } else if (result.expired) {
+          console.log(`${red}✗ Token expired ${result.expiredAgoText} ago${reset}`);
+        } else {
+          console.log(`${green}✓ Token expires in ${result.expiresInText}${reset}`);
+        }
+      }
+
+      process.exit(result.expired ? 1 : 0);
+    }
+
+    case 'explain':
+    default: {
+      const result = explain(token);
+
+      if (json) {
+        // Remove circular references and functions for JSON output
+        const jsonSafe = JSON.parse(JSON.stringify(result));
+        console.log(JSON.stringify(jsonSafe, null, 2));
+      } else {
+        console.log(format(result, { color: useColor, detailed }));
+      }
+
+      if (!result.valid) process.exit(1);
+      if (result.validation && !result.validation.valid) process.exit(1);
+      break;
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@claude-agent/jwt-explain",
+  "version": "1.0.0",
+  "description": "Decode and explain JWT tokens in plain English - understand headers, claims, and expiration",
+  "main": "src/index.js",
+  "bin": {
+    "jwt-explain": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "jwt",
+    "json-web-token",
+    "decode",
+    "explain",
+    "parse",
+    "token",
+    "auth",
+    "authentication",
+    "cli"
+  ],
+  "author": "Claude Agent <claude-agent@agentmail.to>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/claude-agent-tools/jwt-explain.git"
+  },
+  "homepage": "https://github.com/claude-agent-tools/jwt-explain#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/"
+  ]
+}

package/src/index.js

@@ -0,0 +1,653 @@
+/**
+ * jwt-explain
+ * Decode and explain JWT tokens in plain English
+ * Zero dependencies
+ */
+
+'use strict';
+
+// Standard JWT claims and their descriptions
+const REGISTERED_CLAIMS = {
+  iss: { name: 'Issuer', description: 'Who issued this token' },
+  sub: { name: 'Subject', description: 'Who/what this token is about' },
+  aud: { name: 'Audience', description: 'Who this token is intended for' },
+  exp: { name: 'Expiration Time', description: 'When this token expires', isDate: true },
+  nbf: { name: 'Not Before', description: 'Token not valid before this time', isDate: true },
+  iat: { name: 'Issued At', description: 'When this token was issued', isDate: true },
+  jti: { name: 'JWT ID', description: 'Unique identifier for this token' }
+};
+
+// Common custom claims
+const COMMON_CLAIMS = {
+  name: { name: 'Name', description: 'Full name of the user' },
+  given_name: { name: 'Given Name', description: 'First name' },
+  family_name: { name: 'Family Name', description: 'Last name' },
+  email: { name: 'Email', description: 'Email address' },
+  email_verified: { name: 'Email Verified', description: 'Whether email has been verified' },
+  phone_number: { name: 'Phone Number', description: 'Phone number' },
+  picture: { name: 'Picture', description: 'Profile picture URL' },
+  locale: { name: 'Locale', description: 'User locale/language' },
+  zoneinfo: { name: 'Time Zone', description: 'User time zone' },
+  updated_at: { name: 'Updated At', description: 'Last profile update time', isDate: true },
+  auth_time: { name: 'Auth Time', description: 'When authentication occurred', isDate: true },
+  nonce: { name: 'Nonce', description: 'Value to prevent replay attacks' },
+  acr: { name: 'Auth Context Class', description: 'Authentication context class reference' },
+  amr: { name: 'Auth Methods', description: 'Authentication methods used' },
+  azp: { name: 'Authorized Party', description: 'The party the token was issued to' },
+  at_hash: { name: 'Access Token Hash', description: 'Hash of the access token' },
+  c_hash: { name: 'Code Hash', description: 'Hash of the authorization code' },
+  scope: { name: 'Scope', description: 'Permissions granted by this token' },
+  permissions: { name: 'Permissions', description: 'Specific permissions granted' },
+  roles: { name: 'Roles', description: 'User roles' },
+  groups: { name: 'Groups', description: 'Group memberships' }
+};
+
+// Algorithm descriptions
+const ALGORITHMS = {
+  HS256: { name: 'HMAC SHA-256', type: 'symmetric', description: 'HMAC with SHA-256 (symmetric key)' },
+  HS384: { name: 'HMAC SHA-384', type: 'symmetric', description: 'HMAC with SHA-384 (symmetric key)' },
+  HS512: { name: 'HMAC SHA-512', type: 'symmetric', description: 'HMAC with SHA-512 (symmetric key)' },
+  RS256: { name: 'RSA SHA-256', type: 'asymmetric', description: 'RSA signature with SHA-256' },
+  RS384: { name: 'RSA SHA-384', type: 'asymmetric', description: 'RSA signature with SHA-384' },
+  RS512: { name: 'RSA SHA-512', type: 'asymmetric', description: 'RSA signature with SHA-512' },
+  ES256: { name: 'ECDSA P-256', type: 'asymmetric', description: 'ECDSA using P-256 curve and SHA-256' },
+  ES384: { name: 'ECDSA P-384', type: 'asymmetric', description: 'ECDSA using P-384 curve and SHA-384' },
+  ES512: { name: 'ECDSA P-521', type: 'asymmetric', description: 'ECDSA using P-521 curve and SHA-512' },
+  PS256: { name: 'RSA-PSS SHA-256', type: 'asymmetric', description: 'RSA-PSS signature with SHA-256' },
+  PS384: { name: 'RSA-PSS SHA-384', type: 'asymmetric', description: 'RSA-PSS signature with SHA-384' },
+  PS512: { name: 'RSA-PSS SHA-512', type: 'asymmetric', description: 'RSA-PSS signature with SHA-512' },
+  EdDSA: { name: 'Edwards-curve DSA', type: 'asymmetric', description: 'Edwards-curve Digital Signature Algorithm' },
+  none: { name: 'None', type: 'none', description: 'Unsigned token (insecure!)' }
+};
+
+/**
+ * Base64URL decode
+ * @param {string} str - Base64URL encoded string
+ * @returns {string} Decoded string
+ */
+function base64UrlDecode(str) {
+  // Replace URL-safe characters
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+
+  // Add padding if needed
+  while (base64.length % 4) {
+    base64 += '=';
+  }
+
+  // Decode
+  return Buffer.from(base64, 'base64').toString('utf8');
+}
+
+/**
+ * Base64URL encode
+ * @param {string} str - String to encode
+ * @returns {string} Base64URL encoded string
+ */
+function base64UrlEncode(str) {
+  return Buffer.from(str, 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Decode a JWT token without verification
+ * @param {string} token - JWT token string
+ * @returns {object|null} Decoded token or null if invalid
+ */
+function decode(token) {
+  if (typeof token !== 'string' || !token.trim()) {
+    return null;
+  }
+
+  token = token.trim();
+
+  // Remove "Bearer " prefix if present
+  if (token.toLowerCase().startsWith('bearer ')) {
+    token = token.slice(7).trim();
+  }
+
+  const parts = token.split('.');
+
+  if (parts.length !== 3) {
+    return null;
+  }
+
+  try {
+    const headerJson = base64UrlDecode(parts[0]);
+    const payloadJson = base64UrlDecode(parts[1]);
+
+    const header = JSON.parse(headerJson);
+    const payload = JSON.parse(payloadJson);
+
+    return {
+      token,
+      header,
+      payload,
+      signature: parts[2],
+      parts: {
+        header: parts[0],
+        payload: parts[1],
+        signature: parts[2]
+      }
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Check if a token is a valid JWT structure
+ * @param {string} token - Token to validate
+ * @returns {object} Validation result
+ */
+function validate(token) {
+  const errors = [];
+  const warnings = [];
+
+  if (typeof token !== 'string' || !token.trim()) {
+    return { valid: false, errors: ['Token must be a non-empty string'], warnings: [] };
+  }
+
+  token = token.trim();
+
+  // Remove Bearer prefix
+  if (token.toLowerCase().startsWith('bearer ')) {
+    token = token.slice(7).trim();
+  }
+
+  const parts = token.split('.');
+
+  if (parts.length !== 3) {
+    errors.push(`JWT must have 3 parts separated by dots, found ${parts.length}`);
+    return { valid: false, errors, warnings };
+  }
+
+  // Check each part is valid base64url
+  const partNames = ['header', 'payload', 'signature'];
+  for (let i = 0; i < 3; i++) {
+    if (!parts[i]) {
+      // Empty signature is valid for alg: none tokens
+      if (i === 2) continue; // Check signature later after decoding header
+      errors.push(`${partNames[i]} part is empty`);
+    } else if (!/^[A-Za-z0-9_-]+$/.test(parts[i])) {
+      errors.push(`${partNames[i]} contains invalid base64url characters`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+
+  // Try to decode header and payload
+  let header, payload;
+
+  try {
+    const headerJson = base64UrlDecode(parts[0]);
+    header = JSON.parse(headerJson);
+  } catch {
+    errors.push('Header is not valid JSON');
+  }
+
+  try {
+    const payloadJson = base64UrlDecode(parts[1]);
+    payload = JSON.parse(payloadJson);
+  } catch {
+    errors.push('Payload is not valid JSON');
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+
+  // Validate header structure
+  if (typeof header !== 'object' || header === null) {
+    errors.push('Header must be a JSON object');
+  } else {
+    if (!header.alg) {
+      errors.push('Header missing required "alg" (algorithm) field');
+    } else if (header.alg === 'none') {
+      warnings.push('Algorithm is "none" - token is unsigned and should not be trusted');
+    }
+
+    if (!header.typ) {
+      warnings.push('Header missing "typ" field (optional but recommended)');
+    } else if (header.typ !== 'JWT') {
+      warnings.push(`Header "typ" is "${header.typ}", expected "JWT"`);
+    }
+  }
+
+  // Validate payload structure
+  if (typeof payload !== 'object' || payload === null) {
+    errors.push('Payload must be a JSON object');
+  } else {
+    // Check expiration
+    if (payload.exp) {
+      const expTime = payload.exp * 1000;
+      if (expTime < Date.now()) {
+        warnings.push('Token has expired');
+      }
+    } else {
+      warnings.push('Token has no expiration (exp) - may be valid indefinitely');
+    }
+
+    // Check not before
+    if (payload.nbf) {
+      const nbfTime = payload.nbf * 1000;
+      if (nbfTime > Date.now()) {
+        warnings.push('Token is not yet valid (nbf is in the future)');
+      }
+    }
+
+    // Check issued at
+    if (payload.iat) {
+      const iatTime = payload.iat * 1000;
+      if (iatTime > Date.now()) {
+        warnings.push('Token issued in the future (iat is in the future)');
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+/**
+ * Check if a token is expired
+ * @param {string} token - JWT token
+ * @returns {object} Expiration status
+ */
+function isExpired(token) {
+  const decoded = decode(token);
+
+  if (!decoded) {
+    return { error: 'Invalid token', expired: null, expiresAt: null };
+  }
+
+  const { payload } = decoded;
+
+  if (!payload.exp) {
+    return { expired: false, expiresAt: null, neverExpires: true };
+  }
+
+  const expiresAt = new Date(payload.exp * 1000);
+  const now = new Date();
+  const expired = expiresAt < now;
+
+  return {
+    expired,
+    expiresAt,
+    expiresIn: expired ? null : expiresAt - now,
+    expiredAgo: expired ? now - expiresAt : null
+  };
+}
+
+/**
+ * Get the time until expiration
+ * @param {string} token - JWT token
+ * @returns {object} Time until expiration
+ */
+function getTimeUntilExpiry(token) {
+  const result = isExpired(token);
+
+  if (result.error) {
+    return { error: result.error };
+  }
+
+  if (result.neverExpires) {
+    return { neverExpires: true };
+  }
+
+  if (result.expired) {
+    const ago = result.expiredAgo;
+    return {
+      expired: true,
+      expiredAgo: ago,
+      expiredAgoText: formatDuration(ago)
+    };
+  }
+
+  const remaining = result.expiresIn;
+  return {
+    expired: false,
+    expiresIn: remaining,
+    expiresInText: formatDuration(remaining)
+  };
+}
+
+/**
+ * Format a duration in milliseconds to human-readable
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    const remainingHours = hours % 24;
+    return `${days} day${days !== 1 ? 's' : ''}${remainingHours > 0 ? `, ${remainingHours} hour${remainingHours !== 1 ? 's' : ''}` : ''}`;
+  }
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    return `${hours} hour${hours !== 1 ? 's' : ''}${remainingMinutes > 0 ? `, ${remainingMinutes} minute${remainingMinutes !== 1 ? 's' : ''}` : ''}`;
+  }
+
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60;
+    return `${minutes} minute${minutes !== 1 ? 's' : ''}${remainingSeconds > 0 ? `, ${remainingSeconds} second${remainingSeconds !== 1 ? 's' : ''}` : ''}`;
+  }
+
+  return `${seconds} second${seconds !== 1 ? 's' : ''}`;
+}
+
+/**
+ * Explain a claim
+ * @param {string} key - Claim key
+ * @param {any} value - Claim value
+ * @returns {object} Claim explanation
+ */
+function explainClaim(key, value) {
+  const registeredInfo = REGISTERED_CLAIMS[key];
+  const commonInfo = COMMON_CLAIMS[key];
+  const info = registeredInfo || commonInfo;
+
+  const result = {
+    key,
+    value,
+    isRegistered: !!registeredInfo,
+    isCommon: !!commonInfo
+  };
+
+  if (info) {
+    result.name = info.name;
+    result.description = info.description;
+
+    if (info.isDate && typeof value === 'number') {
+      result.dateValue = new Date(value * 1000);
+      result.dateFormatted = result.dateValue.toISOString();
+    }
+  } else {
+    result.name = key;
+    result.description = 'Custom claim';
+  }
+
+  // Format value display
+  if (typeof value === 'object' && value !== null) {
+    result.displayValue = JSON.stringify(value);
+  } else {
+    result.displayValue = String(value);
+  }
+
+  return result;
+}
+
+/**
+ * Explain a JWT token in plain English
+ * @param {string} token - JWT token
+ * @returns {object} Token explanation
+ */
+function explain(token) {
+  const decoded = decode(token);
+
+  if (!decoded) {
+    return {
+      valid: false,
+      error: 'Invalid JWT token format',
+      input: token
+    };
+  }
+
+  const validation = validate(token);
+  const expiry = getTimeUntilExpiry(token);
+  const { header, payload } = decoded;
+
+  // Explain algorithm
+  const algInfo = ALGORITHMS[header.alg] || { name: header.alg, description: 'Unknown algorithm' };
+
+  // Explain header
+  const headerExplanation = {
+    algorithm: {
+      value: header.alg,
+      name: algInfo.name,
+      type: algInfo.type,
+      description: algInfo.description
+    },
+    type: header.typ || null,
+    keyId: header.kid || null,
+    other: {}
+  };
+
+  // Capture any other header fields
+  for (const [key, value] of Object.entries(header)) {
+    if (!['alg', 'typ', 'kid'].includes(key)) {
+      headerExplanation.other[key] = value;
+    }
+  }
+
+  // Explain claims
+  const claims = [];
+  for (const [key, value] of Object.entries(payload)) {
+    claims.push(explainClaim(key, value));
+  }
+
+  // Sort claims: registered first, then common, then custom
+  claims.sort((a, b) => {
+    if (a.isRegistered && !b.isRegistered) return -1;
+    if (!a.isRegistered && b.isRegistered) return 1;
+    if (a.isCommon && !b.isCommon) return -1;
+    if (!a.isCommon && b.isCommon) return 1;
+    return 0;
+  });
+
+  // Generate summary
+  let summary = `${algInfo.name} signed JWT`;
+
+  if (payload.sub) {
+    summary += ` for subject "${payload.sub}"`;
+  }
+
+  if (payload.iss) {
+    summary += ` from issuer "${payload.iss}"`;
+  }
+
+  if (expiry.expired) {
+    summary += ` (expired ${expiry.expiredAgoText} ago)`;
+  } else if (expiry.neverExpires) {
+    summary += ' (no expiration)';
+  } else {
+    summary += ` (expires in ${expiry.expiresInText})`;
+  }
+
+  return {
+    valid: true,
+    input: token,
+    validation,
+    header: headerExplanation,
+    claims,
+    expiry,
+    summary,
+    decoded
+  };
+}
+
+/**
+ * Format output for display
+ * @param {object} result - Explain result
+ * @param {object} options - Formatting options
+ * @returns {string}
+ */
+function format(result, options = {}) {
+  const { color = true, detailed = false } = options;
+
+  const c = {
+    reset: color ? '\x1b[0m' : '',
+    bold: color ? '\x1b[1m' : '',
+    dim: color ? '\x1b[2m' : '',
+    cyan: color ? '\x1b[36m' : '',
+    green: color ? '\x1b[32m' : '',
+    yellow: color ? '\x1b[33m' : '',
+    red: color ? '\x1b[31m' : '',
+    magenta: color ? '\x1b[35m' : '',
+    blue: color ? '\x1b[34m' : ''
+  };
+
+  const lines = [];
+
+  if (!result.valid) {
+    lines.push(`${c.red}Error:${c.reset} ${result.error}`);
+    return lines.join('\n');
+  }
+
+  // Summary
+  lines.push(`${c.bold}JWT Token${c.reset}`);
+  lines.push('');
+  lines.push(`${c.bold}Summary:${c.reset} ${result.summary}`);
+
+  // Validation status
+  if (result.validation.errors.length > 0 || result.validation.warnings.length > 0) {
+    lines.push('');
+    lines.push(`${c.bold}Validation:${c.reset}`);
+    for (const error of result.validation.errors) {
+      lines.push(`  ${c.red}✗ ${error}${c.reset}`);
+    }
+    for (const warning of result.validation.warnings) {
+      lines.push(`  ${c.yellow}⚠ ${warning}${c.reset}`);
+    }
+  }
+
+  // Expiry status
+  lines.push('');
+  lines.push(`${c.bold}Expiration:${c.reset}`);
+  if (result.expiry.neverExpires) {
+    lines.push(`  ${c.yellow}⚠ No expiration set${c.reset}`);
+  } else if (result.expiry.expired) {
+    lines.push(`  ${c.red}✗ Expired ${result.expiry.expiredAgoText} ago${c.reset}`);
+  } else {
+    lines.push(`  ${c.green}✓ Valid for ${result.expiry.expiresInText}${c.reset}`);
+  }
+
+  // Header
+  lines.push('');
+  lines.push(`${c.bold}Header:${c.reset}`);
+  lines.push(`  ${c.cyan}Algorithm:${c.reset} ${result.header.algorithm.value} (${result.header.algorithm.description})`);
+  if (result.header.type) {
+    lines.push(`  ${c.cyan}Type:${c.reset} ${result.header.type}`);
+  }
+  if (result.header.keyId) {
+    lines.push(`  ${c.cyan}Key ID:${c.reset} ${result.header.keyId}`);
+  }
+  for (const [key, value] of Object.entries(result.header.other)) {
+    lines.push(`  ${c.cyan}${key}:${c.reset} ${JSON.stringify(value)}`);
+  }
+
+  // Claims
+  lines.push('');
+  lines.push(`${c.bold}Claims:${c.reset}`);
+
+  for (const claim of result.claims) {
+    const badge = claim.isRegistered ? `${c.blue}[registered]${c.reset}` :
+                  claim.isCommon ? `${c.magenta}[common]${c.reset}` :
+                  `${c.dim}[custom]${c.reset}`;
+
+    if (claim.dateValue) {
+      lines.push(`  ${c.yellow}${claim.key}${c.reset} ${badge}`);
+      lines.push(`    ${claim.dateFormatted}`);
+      if (detailed) {
+        lines.push(`    ${c.dim}${claim.name}: ${claim.description}${c.reset}`);
+      }
+    } else {
+      lines.push(`  ${c.yellow}${claim.key}${c.reset} = ${claim.displayValue} ${badge}`);
+      if (detailed) {
+        lines.push(`    ${c.dim}${claim.name}: ${claim.description}${c.reset}`);
+      }
+    }
+  }
+
+  // Detailed mode: show raw parts
+  if (detailed) {
+    lines.push('');
+    lines.push(`${c.bold}Raw Parts:${c.reset}`);
+    lines.push(`  ${c.dim}Header:${c.reset}    ${result.decoded.parts.header.substring(0, 50)}...`);
+    lines.push(`  ${c.dim}Payload:${c.reset}   ${result.decoded.parts.payload.substring(0, 50)}...`);
+    lines.push(`  ${c.dim}Signature:${c.reset} ${result.decoded.parts.signature.substring(0, 50)}...`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Create a simple JWT for testing (unsigned)
+ * @param {object} payload - Payload object
+ * @param {object} header - Header object (optional)
+ * @returns {string}
+ */
+function createUnsigned(payload, header = {}) {
+  const fullHeader = {
+    alg: 'none',
+    typ: 'JWT',
+    ...header
+  };
+
+  const headerB64 = base64UrlEncode(JSON.stringify(fullHeader));
+  const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+
+  return `${headerB64}.${payloadB64}.`;
+}
+
+/**
+ * Get all registered claims info
+ * @returns {object}
+ */
+function getRegisteredClaims() {
+  return { ...REGISTERED_CLAIMS };
+}
+
+/**
+ * Get all common claims info
+ * @returns {object}
+ */
+function getCommonClaims() {
+  return { ...COMMON_CLAIMS };
+}
+
+/**
+ * Get all algorithm info
+ * @returns {object}
+ */
+function getAlgorithms() {
+  return { ...ALGORITHMS };
+}
+
+module.exports = {
+  // Core functions
+  decode,
+  validate,
+  explain,
+  format,
+
+  // Utilities
+  isExpired,
+  getTimeUntilExpiry,
+  createUnsigned,
+  base64UrlDecode,
+  base64UrlEncode,
+
+  // Info getters
+  getRegisteredClaims,
+  getCommonClaims,
+  getAlgorithms,
+  explainClaim,
+
+  // Constants
+  REGISTERED_CLAIMS,
+  COMMON_CLAIMS,
+  ALGORITHMS
+};