jwtpeek 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jwtpeek contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# jwtpeek
+
+**Decode and inspect a JWT in your terminal.** See the header, the payload, and
+a human-readable expiry verdict — without pasting your token into a website.
+**Zero dependencies, fully offline, nothing uploaded.**
+
+```bash
+npx jwtpeek eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+```
+Header
+  {
+    "alg": "HS256",
+    "typ": "JWT"
+  }
+
+Payload
+  {
+    "sub": "1234567890",
+    "name": "John Doe",
+    "iat": 1516239022
+  }
+
+Claims
+  issued   2018-01-18 01:30:22 UTC  8y 150d ago
+```
+
+## Why
+
+Debugging auth means constantly asking *"what's actually in this token, and has
+it expired?"* The usual answers are bad: paste it into **jwt.io** (your token —
+often a live credential — now lives in a browser tab and maybe a third party's
+logs), or hand-assemble a pipeline nobody remembers:
+
+```bash
+echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python -m json.tool   # and base64 -d vs -D differs across macOS/Linux…
+```
+
+`jwtpeek` is one command. It runs entirely on your machine, makes no network
+requests, and prints the time claims (`exp`, `iat`, `nbf`, …) as real dates plus
+"expires in 3h 21m" / "EXPIRED 2d ago".
+
+## Decode, not verify — read this
+
+> **jwtpeek never checks the signature.** It shows you what a token *says*, not
+> whether it's authentic. Anyone can forge a token that decodes cleanly. Never
+> trust decoded contents for an authorization decision — verify the signature
+> against the issuer's key first (that needs a secret/public key, which is out
+> of scope for a decoder).
+
+## Usage
+
+```bash
+jwtpeek <token>            # header, payload & expiry (human-readable)
+jwtpeek <token> --json     # {header, payload, signature, expired, notYetValid}
+jwtpeek <token> --header   # only the decoded header (JSON)
+jwtpeek <token> --payload  # only the decoded payload (JSON)
+
+pbpaste | jwtpeek          # read the token from stdin
+echo "$AUTH_HEADER" | jwtpeek   # a leading "Bearer "/"Authorization:" is stripped
+```
+
+Pipe-friendly: the decoded output goes to **stdout**, the "not verified" safety
+note goes to **stderr**, so `jwtpeek "$t" --json | jq .payload` stays clean.
+
+### Scripting with the exit code
+
+```
+0   decoded OK and not expired (or no exp claim)
+1   decoded OK but the token is expired
+2   not a valid JWT (decode error)
+```
+
+```bash
+jwtpeek "$TOKEN" >/dev/null 2>&1 && echo "still valid" || echo "expired or invalid"
+```
+
+## Install
+
+```bash
+npm install -g jwtpeek     # then: jwtpeek <token>
+# or just run it once:
+npx jwtpeek <token>
+```
+
+Requires Node ≥ 18. There is also a byte-for-byte Python port:
+`pip install jwtpeek` ([jwtpeek-py](https://github.com/jjdoor/jwtpeek-py)).
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const core = require('../src/core.js');
+const VERSION = require('../package.json').version;
+
+// ----- tiny color helpers (no dep) -----
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR && !process.argv.includes('--no-color');
+const col = (c, s) => (useColor ? `\x1b[${c}m${s}\x1b[0m` : s);
+const red = (s) => col('31', s), green = (s) => col('32', s), yellow = (s) => col('33', s),
+  dim = (s) => col('2', s), bold = (s) => col('1', s), cyan = (s) => col('36', s);
+
+const HELP = `${bold('jwtpeek')} — decode & inspect a JWT in your terminal. Decodes only, never verifies.
+
+${bold('Usage')}
+  jwtpeek <token>            Decode a token and show header, payload & expiry
+  jwtpeek <token> --json     Machine-readable {header, payload, signature, ...}
+  jwtpeek <token> --header   Print only the decoded header (JSON)
+  jwtpeek <token> --payload  Print only the decoded payload (JSON)
+  pbpaste | jwtpeek          Read the token from stdin (pipe)
+  echo "$AUTH" | jwtpeek     "Bearer "/"Authorization:" prefixes are stripped
+
+${bold('Options')}
+  --json        Full structure as JSON (stdout stays pure; notes go to stderr)
+  --header      Only the header object
+  --payload     Only the payload object
+  --no-color    Disable ANSI colors
+  -v, --version
+  -h, --help
+
+${bold('Exit')}  0 valid (or no exp) · 1 expired · 2 decode error
+`;
+
+function fail(msg) {
+  process.stderr.write(red(`jwtpeek: ${msg}\n`));
+  process.exit(2);
+}
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+// "2018-01-18T02:30:22.000Z" -> "2018-01-18 02:30:22 UTC"
+function isoUTC(ms) {
+  return new Date(ms).toISOString().replace('T', ' ').replace(/\.\d+Z$/, '') + ' UTC';
+}
+
+function indentJSON(obj) {
+  return JSON.stringify(obj, null, 2).split('\n').map((l) => '  ' + l).join('\n');
+}
+
+function claimVerdict(key, ms, exp, nowMs) {
+  if (key === 'exp') {
+    return exp.expired
+      ? red(`EXPIRED ${core.formatDuration(nowMs - ms)} ago`)
+      : green(`expires in ${core.formatDuration(ms - nowMs)}`);
+  }
+  if (key === 'nbf') {
+    return nowMs < ms
+      ? yellow(`not valid for ${core.formatDuration(ms - nowMs)}`)
+      : dim(`valid since ${core.formatDuration(nowMs - ms)} ago`);
+  }
+  return ms <= nowMs
+    ? dim(`${core.formatDuration(nowMs - ms)} ago`)
+    : dim(`in ${core.formatDuration(ms - nowMs)}`);
+}
+
+function printHuman(decoded, exp, nowMs) {
+  const out = [bold('Header'), indentJSON(decoded.header), '',
+    bold('Payload'), indentJSON(decoded.payload)];
+
+  const rows = [];
+  for (const [key, label] of core.TIME_CLAIMS) {
+    if (!(key in decoded.payload)) continue;
+    const ms = core.normalizeEpochMs(decoded.payload[key]);
+    if (ms == null) continue;
+    rows.push({ key, label, ms });
+  }
+  if (rows.length) {
+    out.push('', bold('Claims'));
+    const w = Math.max(...rows.map((r) => r.label.length));
+    for (const r of rows) {
+      out.push(`  ${cyan(r.label.padEnd(w))}  ${dim(isoUTC(r.ms))}  ${claimVerdict(r.key, r.ms, exp, nowMs)}`);
+    }
+  }
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('-h') || argv.includes('--help')) { process.stdout.write(HELP); process.exit(0); }
+  if (argv.includes('-v') || argv.includes('--version')) { process.stdout.write(VERSION + '\n'); process.exit(0); }
+  if (argv.length === 0 && process.stdin.isTTY) { process.stdout.write(HELP); process.exit(0); }
+
+  const flags = new Set(argv.filter((a) => a.startsWith('-')));
+  const positional = argv.filter((a) => !a.startsWith('-'));
+
+  let raw = positional[0];
+  if (!raw) {
+    if (process.stdin.isTTY) fail('no token given (pass it as an argument or pipe it in)');
+    raw = readStdin();
+  }
+  const token = core.stripToken(raw);
+  if (!token) fail('no token given (pass it as an argument or pipe it in)');
+
+  let decoded;
+  try { decoded = core.decodeJwt(token); }
+  catch (e) { fail(e.message); }
+
+  const nowMs = Date.now();
+  const exp = core.evaluateExpiry(decoded.payload, nowMs);
+
+  if (flags.has('--header')) {
+    process.stdout.write(JSON.stringify(decoded.header, null, 2) + '\n');
+  } else if (flags.has('--payload')) {
+    process.stdout.write(JSON.stringify(decoded.payload, null, 2) + '\n');
+  } else if (flags.has('--json')) {
+    process.stdout.write(JSON.stringify({
+      header: decoded.header,
+      payload: decoded.payload,
+      signature: decoded.signature,
+      expired: exp.expired,
+      notYetValid: exp.notYetValid,
+    }, null, 2) + '\n');
+  } else {
+    printHuman(decoded, exp, nowMs);
+  }
+
+  // Safety note always to stderr so it never pollutes stdout / pipes.
+  process.stderr.write(dim('note: signature NOT verified — jwtpeek decodes only\n'));
+  if (exp.notYetValid) process.stderr.write(yellow('warning: token is not valid yet (nbf is in the future)\n'));
+
+  process.exit(exp.expired ? 1 : 0);
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "jwtpeek",
+  "version": "0.1.0",
+  "description": "Decode & inspect JWT tokens in your terminal — header, payload, and human-readable expiry. Zero dependencies, fully offline, nothing uploaded.",
+  "bin": {
+    "jwtpeek": "bin/cli.js"
+  },
+  "main": "src/core.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "jwt",
+    "jwt-decode",
+    "json-web-token",
+    "jwt-cli",
+    "token",
+    "decode",
+    "auth",
+    "oauth",
+    "oidc",
+    "cli",
+    "devtools",
+    "debug"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jjdoor/jwtpeek.git"
+  },
+  "homepage": "https://github.com/jjdoor/jwtpeek#readme",
+  "bugs": {
+    "url": "https://github.com/jjdoor/jwtpeek/issues"
+  }
+}

package/src/core.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * jwtpeek core — pure JWT decoding + claim classification.
+ *
+ * No fs, no clock, no network: every function takes its inputs explicitly so
+ * this and the Python port behave identically and stay unit-testable.
+ *
+ * IMPORTANT: jwtpeek DECODES, it does not VERIFY. A JWT's signature is what
+ * proves the payload wasn't tampered with; we never check it. Treat decoded
+ * contents as untrusted unless you've verified the signature with the issuer's
+ * key.
+ */
+
+const UNITS = { y: 31536000000, d: 86400000, h: 3600000, m: 60000, s: 1000 };
+
+// Registered date claims (RFC 7519 + common OIDC) mapped to a display label.
+// This is also the print order; `exp` is last so the validity verdict lands
+// as the kicker.
+const TIME_CLAIMS = [
+  ['iat', 'issued'],
+  ['nbf', 'not before'],
+  ['auth_time', 'auth time'],
+  ['updated_at', 'updated'],
+  ['exp', 'expires'],
+];
+
+/**
+ * Strip the noise that creeps in when a token is copy-pasted: surrounding
+ * quotes, an "Authorization:"/"Bearer " prefix, and any wrapping whitespace
+ * (including the line breaks a wrapped terminal paste introduces).
+ *
+ * @param {*} input
+ * @returns {string}
+ */
+function stripToken(input) {
+  let s = String(input == null ? '' : input).trim();
+  s = s.replace(/^['"]+|['"]+$/g, '');
+  s = s.replace(/^Authorization:\s*/i, '');
+  s = s.replace(/^Bearer\s+/i, '');
+  s = s.replace(/\s+/g, '');
+  return s;
+}
+
+/**
+ * Decode one base64url segment to a UTF-8 string. Throws on non-base64url so
+ * callers can report a precise error instead of silently mangling bytes.
+ *
+ * @param {string} seg
+ * @returns {string}
+ */
+function b64urlToString(seg) {
+  if (!/^[A-Za-z0-9_-]+$/.test(seg)) throw new Error('not base64url');
+  let b64 = seg.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4) b64 += '=';
+  return Buffer.from(b64, 'base64').toString('utf8');
+}
+
+function parseSegment(seg, which) {
+  if (!seg) throw new Error(`${which} segment is empty`);
+  let json;
+  try { json = b64urlToString(seg); }
+  catch { throw new Error(`${which} is not valid base64url`); }
+  let obj;
+  try { obj = JSON.parse(json); }
+  catch { throw new Error(`${which} is not valid JSON`); }
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`${which} is not a JSON object`);
+  }
+  return obj;
+}
+
+/**
+ * Decode a JWT into { header, payload, signature }. Accepts a 2-part unsecured
+ * token (alg: none) as well as the usual 3-part form. Throws an Error with a
+ * human message on anything that isn't a structurally valid JWT.
+ *
+ * Does NOT verify the signature — see the module note.
+ *
+ * @param {string} token
+ * @returns {{ header: object, payload: object, signature: string }}
+ */
+function decodeJwt(token) {
+  const t = String(token == null ? '' : token).trim();
+  if (!t) throw new Error('empty token');
+  const parts = t.split('.');
+  if (parts.length < 2 || parts.length > 3) {
+    throw new Error(`not a JWT: expected 2 or 3 dot-separated parts, got ${parts.length}`);
+  }
+  return {
+    header: parseSegment(parts[0], 'header'),
+    payload: parseSegment(parts[1], 'payload'),
+    signature: parts.length === 3 ? parts[2] : '',
+  };
+}
+
+/**
+ * Normalize a JWT NumericDate to epoch milliseconds. Per RFC 7519 these are
+ * *seconds*, but some issuers wrongly emit milliseconds — detect that (a real
+ * seconds value won't reach 1e12 until the year 5138) and pass it through.
+ * Returns null for anything that isn't a finite number.
+ *
+ * @param {*} value
+ * @returns {number|null}
+ */
+function normalizeEpochMs(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return value >= 1e12 ? Math.round(value) : Math.round(value * 1000);
+}
+
+/**
+ * Evaluate validity windows against a supplied `nowMs` (no clock in here).
+ * `expired`/`notYetValid` are null when the corresponding claim is absent.
+ *
+ * @param {object} payload
+ * @param {number} nowMs
+ * @returns {{ expMs:number|null, nbfMs:number|null, expired:boolean|null, notYetValid:boolean|null }}
+ */
+function evaluateExpiry(payload, nowMs) {
+  const expMs = normalizeEpochMs(payload && payload.exp);
+  const nbfMs = normalizeEpochMs(payload && payload.nbf);
+  return {
+    expMs,
+    nbfMs,
+    expired: expMs == null ? null : nowMs >= expMs,
+    notYetValid: nbfMs == null ? null : nowMs < nbfMs,
+  };
+}
+
+/**
+ * Compact, two-unit-max human span, e.g. "1d 3h", "7y 2d", "45s". Sign is
+ * ignored (callers phrase "ago"/"in" themselves).
+ *
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  ms = Math.abs(Math.round(Number(ms) || 0));
+  if (ms < 1000) return '0s';
+  const order = [['y', UNITS.y], ['d', UNITS.d], ['h', UNITS.h], ['m', UNITS.m], ['s', UNITS.s]];
+  const parts = [];
+  let rem = ms;
+  for (const [label, size] of order) {
+    if (rem >= size) {
+      const n = Math.floor(rem / size);
+      rem -= n * size;
+      parts.push(`${n}${label}`);
+      if (parts.length === 2) break;
+    } else if (parts.length) {
+      break;
+    }
+  }
+  return parts.length ? parts.join(' ') : '0s';
+}
+
+module.exports = {
+  UNITS, TIME_CLAIMS, stripToken, b64urlToString, decodeJwt,
+  normalizeEpochMs, evaluateExpiry, formatDuration,
+};