TokenToolkit.js 🛠️

A lightweight, local-first JavaScript utility library designed for deep JWT parsing, metadata extraction, and static security inspection.

TokenToolkit is the core parsing engine powering the nKode JWT Inspector. It decodes tokens entirely in-memory, enriches claims with human-readable parameters, and aggregates potential structural issues without any external network dependency.

---

Features ✨

• 🔒 100% Local-First: Performs all Base64URL parsing and JSON structural analysis inside the client runtime. Zero server leaks.
• 🩺 Deep Section Analysis: Automatically splits and maps claims into structured standard and custom arrays.
• 🕒 Smart Time Formats: Automatically intercepts Unix timestamps (exp, iat, nbf) and exposes clean, human-readable ISO/UTC strings (formattedDate).
• ⚠️ Issue Aggregation: Integrates modular validators to catch configuration mistakes or malformed parts, organizing anomalies by component.

---

Architecture & Usage 🚀

The package relies on modern ES modules. Import TokenToolkit to target a token:

1. Decoding a JWT

import TokenToolkit from "./TokenToolkit.js";

const rawJwt = "xxxxx.yyyyy.zzzzz";
const result = TokenToolkit.decodeJWT(rawJwt);

if (!result.valid) {
    console.error("Malformed token format:", result.error);
} else {
    const jwtInstance = result.jwt; // Returns instantiated JWT object
    
    // Quick plain objects conversion
    console.log(jwtInstance.toJSON());
}

2. Inspecting Enriched Metadata & Diagnostics

const { jwt } = TokenToolkit.decodeJWT(rawJwt);

// Inspect evaluated payload claims and formatted timestamps
jwt.payload.display.standard.forEach(claim => {
    console.log(`Claim: ${claim.key} -> Value: ${claim.value}`);
    if (claim.formattedDate) {
        console.log(`🕒 Readable Date: ${claim.formattedDate}`); // "2026-05-15 11:08:00 UTC"
    }
});

// Intercept structural or security anomalies flagged by validators
if (jwt.header.issues.length > 0) {
    jwt.header.issues.forEach(issue => {
        console.warn(`[${issue.severity}] Header Anomaly: ${issue.text}`);
    });
}

---

API Reference 📖

TokenToolkit.decodeJWT(jwt)

Static entry point. Validates the raw string layout (part1.part2.part3). Returns: { valid: false, error: string } OR { valid: true, jwt: JWTInstance }.

jwtInstance.toJSON()

Extracts the immediate string values of the header, payload, and signature components.

jwtInstance.toJSONString(pretty = true)

Converts the internal component data into an optionally formatted JSON string.

---

Ecosystem Integration 🌐

This library provides the native engine driving:

🛠️ [nKode Online JWT Decoder & Inspector](https://nkode.gr/EN/tools/jwt-decoder)

📝 [Deep Dive Article: The Anatomy of JSON Web Tokens]([https://nkode.gr/EN/tools/jwt-decoder](https://nkode.gr/EN/articles/286/the-anatomy-of-json-web-tokens-jwt-what-they-are-and-how-they-work))

---

---

---

📄 License

TokenToolkit.js is free software licensed under the GNU GPL v3.0 or later.