🚀 jwt-timeline

✨ Why jwt-timeline?

Debugging JWTs from logs is painful.

jwt-timeline gives you:

• 📅 Issued time (iat)
• ⏳ Not-before time (nbf)
• 🕒 Expiration time (exp)
• 📊 Visual lifetime progress bar
• 🟢 Valid / 🟡 Expiring / 🔴 Expired status
• 🔐 Optional signature verification
• 🧪 Clock skew testing

All directly inside your terminal.

📦 Installation

🌍 Global Install

npm install -g jwt-timeline

⚡ Run Without Installing

npx jwt-timeline <jwt>

Requires Node.js 18+

🚀 Usage

🔹 Single Token

jwt-timeline <jwt>

🔹 Multiple Tokens

jwt-timeline <jwt1> <jwt2>

🔹 Read From File

jwt-timeline --file access.txt

Multiple files:

jwt-timeline --file access.txt --file refresh.txt

🔹 Read From STDIN

cat token.txt | jwt-timeline -

🔹 Override Current Time (Testing)

jwt-timeline <jwt> --now 2025-03-04T14:00:00

🔹 Adjust Clock Skew & Width

jwt-timeline <jwt> --skew 60 --width 80

🔐 Signature Verification

Supports shared-secret algorithms:

• HS256
• HS384
• HS512

jwt-timeline --file token.txt --secret mysecret

Example output:

Signature check : valid (HS256)

If invalid:

Signature check : invalid (signature verification failed)

Future support planned for RS/ES/JWKS.

📊 Example Output

┌─────────────────────────────┐
│     jwt timeline debug      │
│          v0.1 · IST HH      │
└─────────────────────────────┘

Issued (iat)    : 2026-03-04 10:00:00 IST
Not Before (nbf): not set
Expires (exp)   : 2026-03-04 12:00:00 IST
Current time    : 2026-03-04 11:30:00 IST

Timeline (50 chars = full token lifetime):
[█████████████████████████────────────]

^Issued          ^Now                  ^Expires
Valid • ~30 min remaining

🎨 Status Colors

| Color | Meaning | | --------- | ----------------------------- | | 🟢 Green | Token valid | | 🟡 Yellow | Expiring soon / Not yet valid | | 🔴 Red | Expired |

🧾 JSON Mode (For Automation / CI)

jwt-timeline --file token.txt --json

Example:

[
  {
    "source": "file:token.txt",
    "iat": 1740998400,
    "nbf": null,
    "exp": 1741005600,
    "valid": true,
    "expiringSoon": true,
    "signatureValid": true
  }
]

⚙️ CLI Options

| Option | Description | Default | | ------------------ | ----------------------- | ----------- | | --file <path...> | Read JWT from file(s) | — | | --json | Output structured JSON | false | | --now <time> | Override current time | system time | | --skew <seconds> | Clock skew tolerance | 30 | | --width <n> | Timeline width (10–200) | 50 | | --secret <key> | Verify signature (HS*) | — |

💡 Use Cases

• Debugging authentication issues
• Comparing access vs refresh tokens
• Diagnosing clock drift
• CI validation checks
• Security auditing
• Teaching JWT lifecycle visually

👤 Author

Hari Haran S Software Engineer | Backend & DevTools Builder GitHub: https://github.com/hariharan138

📝 License

MIT © 2026 Hari Haran