@chengyixu/jwt-decode-cli 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# jwt-decode-cli
+
+> Decode and inspect JWT tokens from the terminal. No external dependencies.
+
+[![npm version](https://img.shields.io/npm/v/jwt-decode-cli.svg)](https://www.npmjs.com/package/jwt-decode-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A fast, zero-dependency CLI tool to decode JSON Web Tokens (JWTs). Inspect headers, payloads, expiry status, and claim details — all from your terminal.
+
+---
+
+## Install
+
+```bash
+npm install -g jwt-decode-cli
+```
+
+Or run without installing:
+
+```bash
+npx jwt-decode-cli <token>
+```
+
+---
+
+## Usage
+
+```bash
+# Pass token directly
+jwt-decode eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# Pipe from stdin
+echo "eyJhbGci..." | jwt-decode
+cat token.txt | jwt-decode
+
+# Show help
+jwt-decode --help
+
+# Note signature verification requirement
+jwt-decode <token> --verify
+
+# Raw JSON output (no formatting)
+jwt-decode <token> --raw
+```
+
+---
+
+## Output
+
+```
+━━ Header ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{
+  "alg": "HS256",
+  "typ": "JWT"
+}
+
+━━ Payload ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{
+  "sub": "1234567890",
+  "name": "John Doe",
+  "iat": 1516239022
+}
+
+━━ Signature ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+
+━━ Time Analysis ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  iat (issued at):  2018-01-18 01:30:22 UTC  (7y 2m ago)
+  exp:              ⚠ No expiry set — token never expires
+
+━━ Claims Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  sub (subject):   1234567890
+  custom claims:   name
+```
+
+---
+
+## Features
+
+- **Zero dependencies** — uses only Node.js built-ins
+- **Colored output** — syntax-highlighted JSON, color-coded expiry status
+- **Expiry detection** — shows time until expiry or how long since expired
+- **Stdin support** — pipe tokens from other commands
+- **Claims summary** — highlights standard JWT claims (iss, sub, aud, jti, etc.)
+- **Raw JSON mode** — `--raw` for scripting/piping to `jq`
+- **Expired token warning** — bold red banner when token is expired
+- **`--verify` flag** — placeholder with guidance for signature verification
+
+---
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--verify` | Notes that verification requires a secret/public key, provides guidance |
+| `--raw` | Output raw JSON (no colors or formatting) |
+| `--no-color` | Disable colored output (or set `NO_COLOR` env var) |
+| `--help`, `-h` | Show help |
+
+---
+
+## Examples
+
+```bash
+# Decode a token from an environment variable
+jwt-decode $JWT_TOKEN
+
+# Check token expiry in a script
+jwt-decode $TOKEN --raw | jq '.payload.exp'
+
+# Decode token stored in a file
+cat ~/.config/token | jwt-decode
+
+# Use in CI/CD to inspect tokens
+echo $GITHUB_TOKEN | jwt-decode
+```
+
+---
+
+## Security Note
+
+This tool **decodes** JWTs but does **not verify** the signature. It is intended for development, debugging, and inspection purposes. Never trust a JWT's claims without verifying the signature using the appropriate secret or public key.
+
+For signature verification, use:
+- [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) npm package
+- [jwt.io](https://jwt.io) (web-based debugger)
+
+---
+
+## License
+
+MIT © chengyixu

package/index.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const args = process.argv.slice(2);
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+};
+
+function c(color, text) {
+  // Disable colors if not a TTY or NO_COLOR env set
+  if (!process.stdout.isTTY || process.env.NO_COLOR) return text;
+  return colors[color] + text + colors.reset;
+}
+
+function printHelp() {
+  console.log(`
+${c('bold', 'jwt-decode-cli')} — Decode and inspect JWT tokens from the terminal
+
+${c('cyan', 'USAGE:')}
+  jwt-decode <token>          Decode a JWT token
+  echo <token> | jwt-decode   Decode via stdin
+  jwt-decode --help           Show this help
+
+${c('cyan', 'FLAGS:')}
+  --verify        Placeholder: signature verification (requires secret/key)
+  --raw           Output raw JSON (no formatting)
+  --no-color      Disable colored output
+  --help, -h      Show help
+
+${c('cyan', 'EXAMPLES:')}
+  jwt-decode eyJhbGci...
+  cat token.txt | jwt-decode
+  jwt-decode eyJhbGci... --verify
+
+${c('cyan', 'OUTPUT:')}
+  - Header (algorithm, token type)
+  - Payload (claims, custom fields)
+  - Expiry status (valid, expired, or no expiry set)
+  - Time until expiration or time since expiry
+  - Issued-at and not-before times
+`);
+}
+
+function base64urlDecode(str) {
+  // Convert base64url to base64
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  // Pad to multiple of 4
+  while (base64.length % 4 !== 0) {
+    base64 += '=';
+  }
+  try {
+    return Buffer.from(base64, 'base64').toString('utf8');
+  } catch (e) {
+    throw new Error('Failed to base64url-decode segment: ' + e.message);
+  }
+}
+
+function formatDuration(seconds) {
+  const abs = Math.abs(seconds);
+  if (abs < 60) return `${Math.floor(abs)}s`;
+  if (abs < 3600) return `${Math.floor(abs / 60)}m ${Math.floor(abs % 60)}s`;
+  if (abs < 86400) return `${Math.floor(abs / 3600)}h ${Math.floor((abs % 3600) / 60)}m`;
+  const days = Math.floor(abs / 86400);
+  const hours = Math.floor((abs % 86400) / 3600);
+  return `${days}d ${hours}h`;
+}
+
+function formatTimestamp(ts) {
+  try {
+    return new Date(ts * 1000).toISOString().replace('T', ' ').replace('.000Z', ' UTC');
+  } catch (e) {
+    return String(ts);
+  }
+}
+
+function prettyPrintJSON(obj, indent = 2) {
+  if (!process.stdout.isTTY || process.env.NO_COLOR) {
+    return JSON.stringify(obj, null, indent);
+  }
+  // Colorize JSON output
+  return JSON.stringify(obj, null, indent)
+    .replace(/"([^"]+)":/g, c('cyan', '"$1"') + ':')
+    .replace(/: "([^"]*)"/g, ': ' + c('green', '"$1"'))
+    .replace(/: (\d+\.?\d*)/g, ': ' + c('yellow', '$1'))
+    .replace(/: (true|false)/g, ': ' + c('magenta', '$1'))
+    .replace(/: (null)/g, ': ' + c('dim', '$1'));
+}
+
+function decodeJWT(token, opts = {}) {
+  const parts = token.split('.');
+
+  if (parts.length !== 3) {
+    console.error(c('red', `Error: Invalid JWT format. Expected 3 parts (header.payload.signature), got ${parts.length}.`));
+    process.exit(1);
+  }
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // Decode header
+  let header;
+  try {
+    header = JSON.parse(base64urlDecode(headerB64));
+  } catch (e) {
+    console.error(c('red', 'Error: Could not decode JWT header: ' + e.message));
+    process.exit(1);
+  }
+
+  // Decode payload
+  let payload;
+  try {
+    payload = JSON.parse(base64urlDecode(payloadB64));
+  } catch (e) {
+    console.error(c('red', 'Error: Could not decode JWT payload: ' + e.message));
+    process.exit(1);
+  }
+
+  if (opts.raw) {
+    console.log(JSON.stringify({ header, payload, signature: signatureB64 }, null, 2));
+    return;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+
+  // ── HEADER ──────────────────────────────────────────────────────────────
+  console.log('\n' + c('bold', c('blue', '━━ Header ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+  console.log(prettyPrintJSON(header));
+
+  // ── PAYLOAD ─────────────────────────────────────────────────────────────
+  console.log('\n' + c('bold', c('blue', '━━ Payload ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+  console.log(prettyPrintJSON(payload));
+
+  // ── SIGNATURE ───────────────────────────────────────────────────────────
+  console.log('\n' + c('bold', c('blue', '━━ Signature ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+  console.log(c('dim', signatureB64));
+
+  // ── TIME ANALYSIS ────────────────────────────────────────────────────────
+  console.log('\n' + c('bold', c('blue', '━━ Time Analysis ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+
+  // Issued at (iat)
+  if (payload.iat !== undefined) {
+    const issuedAgo = now - payload.iat;
+    console.log(c('dim', '  iat (issued at):  ') + c('white', formatTimestamp(payload.iat)) +
+      c('dim', `  (${formatDuration(issuedAgo)} ago)`));
+  }
+
+  // Not before (nbf)
+  if (payload.nbf !== undefined) {
+    const nbfDiff = now - payload.nbf;
+    const nbfStatus = nbfDiff >= 0
+      ? c('green', '✓ active')
+      : c('yellow', `⚠ not yet valid (in ${formatDuration(-nbfDiff)})`);
+    console.log(c('dim', '  nbf (not before): ') + c('white', formatTimestamp(payload.nbf)) +
+      '  ' + nbfStatus);
+  }
+
+  // Expiry (exp)
+  if (payload.exp !== undefined) {
+    const diff = payload.exp - now;
+    const expLine = c('dim', '  exp (expires):   ') + c('white', formatTimestamp(payload.exp));
+
+    if (diff > 0) {
+      console.log(expLine + '  ' + c('green', `✓ valid (expires in ${formatDuration(diff)})`));
+    } else {
+      console.log(expLine + '  ' + c('red', `✗ EXPIRED ${formatDuration(diff)} ago`));
+    }
+  } else {
+    console.log(c('dim', '  exp:              ') + c('yellow', '⚠ No expiry set — token never expires'));
+  }
+
+  // ── CLAIMS SUMMARY ───────────────────────────────────────────────────────
+  const standardClaims = new Set(['iss', 'sub', 'aud', 'exp', 'nbf', 'iat', 'jti']);
+  const customClaims = Object.keys(payload).filter(k => !standardClaims.has(k));
+
+  console.log('\n' + c('bold', c('blue', '━━ Claims Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+
+  if (payload.iss) console.log(c('dim', '  iss (issuer):    ') + c('white', payload.iss));
+  if (payload.sub) console.log(c('dim', '  sub (subject):   ') + c('white', payload.sub));
+  if (payload.aud) {
+    const aud = Array.isArray(payload.aud) ? payload.aud.join(', ') : payload.aud;
+    console.log(c('dim', '  aud (audience):  ') + c('white', aud));
+  }
+  if (payload.jti) console.log(c('dim', '  jti (JWT ID):    ') + c('white', payload.jti));
+
+  if (customClaims.length > 0) {
+    console.log(c('dim', `  custom claims:   `) + c('cyan', customClaims.join(', ')));
+  }
+
+  // ── VERIFICATION NOTICE ──────────────────────────────────────────────────
+  if (opts.verify) {
+    console.log('\n' + c('bold', c('blue', '━━ Verification ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
+    console.log(c('yellow', '  ⚠ --verify flag noted.'));
+    console.log(c('dim', '  Signature verification requires the secret key or public key.'));
+    console.log(c('dim', '  This tool decodes the token without verifying the signature.'));
+    console.log(c('dim', '  For full verification, use: https://jwt.io or a library like jsonwebtoken.'));
+  }
+
+  // ── EXPIRY BANNER ────────────────────────────────────────────────────────
+  if (payload.exp !== undefined && payload.exp < now) {
+    console.log('\n' + c('bgRed', c('bold', '  !! TOKEN IS EXPIRED !!  ')));
+  }
+
+  console.log('');
+}
+
+// ── MAIN ──────────────────────────────────────────────────────────────────
+
+const opts = {
+  verify: args.includes('--verify'),
+  raw: args.includes('--raw'),
+};
+
+// Handle --help / -h
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+// Filter out flags to get positional token argument
+const positional = args.filter(a => !a.startsWith('--'));
+
+if (positional.length > 0) {
+  // Token from CLI argument
+  decodeJWT(positional[0].trim(), opts);
+} else if (!process.stdin.isTTY) {
+  // Token from stdin (pipe)
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { data += chunk; });
+  process.stdin.on('end', () => {
+    const token = data.trim();
+    if (!token) {
+      console.error(c('red', 'Error: No token provided via stdin.'));
+      printHelp();
+      process.exit(1);
+    }
+    decodeJWT(token, opts);
+  });
+} else {
+  // No input at all
+  console.error(c('red', 'Error: No JWT token provided.\n'));
+  printHelp();
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@chengyixu/jwt-decode-cli",
+  "version": "1.0.0",
+  "description": "Decode and inspect JWT tokens from the terminal. View header, payload, expiry, and more.",
+  "main": "index.js",
+  "bin": {
+    "jwt-decode": "index.js"
+  },
+  "scripts": {
+    "test": "node index.js eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+  },
+  "keywords": [
+    "jwt",
+    "token",
+    "decode",
+    "auth",
+    "cli",
+    "security",
+    "json-web-token",
+    "inspect",
+    "debug",
+    "authentication"
+  ],
+  "author": "chengyixu",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chengyixu/jwt-decode-cli.git"
+  },
+  "homepage": "https://github.com/chengyixu/jwt-decode-cli#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  }
+}