@kakilangit/jwt

WebAssembly bindings for JWT (JSON Web Token) Debugger tool.

Overview

This package provides comprehensive JWT handling functionality compiled to WebAssembly from Rust. It supports:

• Decoding - Decode JWT tokens to inspect header and payload
• Encoding - Create unsigned JWT tokens from header and payload
• Signing - Sign JWT tokens with various algorithms
• Verification - Verify JWT signatures
• Key Generation - Generate key pairs for asymmetric algorithms

Supported Algorithms

Symmetric (HMAC)

• HS256 (HMAC-SHA256)
• HS384 (HMAC-SHA384)
• HS512 (HMAC-SHA512)
• BLAKE2B-256

Asymmetric (RSA)

• RS256, RS384, RS512 (PKCS#1 v1.5)
• PS256, PS384, PS512 (PSS padding)

Asymmetric (ECDSA)

• ES256 (P-256)
• ES384 (P-384)
• ES256K (secp256k1)

Asymmetric (EdDSA)

• EdDSA (Ed25519)

Installation

npm install @kakilangit/jwt

Usage

import init, { 
  decode_jwt, 
  encode_jwt, 
  sign_jwt, 
  verify_jwt, 
  generate_key_pair,
  JwtAlgorithm 
} from '@kakilangit/jwt';

// Initialize the WASM module
await init();

// Decode a JWT token
const decoded = decode_jwt("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");
console.log(decoded.header);    // '{"alg":"HS256","typ":"JWT"}'
console.log(decoded.payload);   // '{"sub":"1234567890","name":"John Doe"}'
console.log(decoded.algorithm); // "HS256"

// Create an unsigned JWT
const encoded = encode_jwt(
  '{"alg":"HS256","typ":"JWT"}',
  '{"sub":"1234567890","name":"John Doe"}'
);
console.log(encoded.token); // "eyJhbGc..."

// Sign a JWT with HMAC
const signed = sign_jwt(
  '{"sub":"1234567890","name":"John Doe"}',
  'your-256-bit-secret',
  JwtAlgorithm.HS256
);

// Verify a JWT
const verified = verify_jwt(signed.token, 'your-256-bit-secret');
console.log(verified.is_valid); // true

// Generate key pair for asymmetric algorithm
const keyPair = generate_key_pair(JwtAlgorithm.ES256);
console.log(keyPair.private_key); // PEM format
console.log(keyPair.public_key);  // PEM format

API

Functions

decode_jwt(token)

Decodes a JWT token into its components without verifying the signature.

• token (string): The JWT token to decode

Returns JwtDecodeResult:

• header: Decoded header as JSON string
• payload: Decoded payload as JSON string
• signature: Original signature (base64url encoded)
• algorithm: Algorithm from header (if present)
• token_type: Token type from header (if present)
• is_complete: Whether the token has all 3 parts

encode_jwt(header, payload)

Encodes a header and payload into a JWT token (without signature).

• header (string): JSON header object
• payload (string): JSON payload object

Returns JwtEncodeResult:

• token: Complete JWT token (header.payload.)
• success: Whether encoding was successful

sign_jwt(payload, key, algorithm)

Signs a JWT payload with the specified key and algorithm.

• payload (string): JSON payload object
• key (string): Secret key (symmetric) or private key PEM (asymmetric)
• algorithm (JwtAlgorithm): Algorithm to use

Note: If your payload includes iat, exp, or nbf timestamp claims, they will be preserved exactly as provided. Otherwise, a default 24-hour expiration is added automatically.

Returns JwtEncodeResult:

• token: Complete signed JWT token
• success: Whether signing was successful

verify_jwt(token, key)

Verifies a JWT token's signature.

• token (string): The JWT token to verify
• key (string): Secret key (symmetric) or public key PEM (asymmetric)

Returns JwtVerifyResult:

• is_valid: Whether the signature is valid
• error: Error message if verification failed

generate_key_pair(algorithm)

Generates a new key pair for asymmetric algorithms.

• algorithm (JwtAlgorithm): Asymmetric algorithm (RS*, PS*, ES*, EdDSA)

Returns JwtKeyPairResult:

• private_key: Private key in PEM format
• public_key: Public key in PEM format

algorithm_is_symmetric(algorithm)

Returns true if the algorithm uses symmetric keys (HMAC).

algorithm_is_asymmetric(algorithm)

Returns true if the algorithm uses asymmetric keys (RSA, ECDSA, EdDSA).

algorithm_as_str(algorithm)

Returns the algorithm name as used in JWT header (e.g., "HS256", "RS256").

Enums

JwtAlgorithm

• HS256, HS384, HS512 - HMAC-SHA algorithms
• Blake2b - BLAKE2B-256
• RS256, RS384, RS512 - RSA PKCS#1 v1.5
• PS256, PS384, PS512 - RSA-PSS
• ES256, ES384, ES256K - ECDSA
• EdDSA - Ed25519

Security Notes

• Always use HTTPS in production
• Store secret keys securely
• For asymmetric algorithms, never share private keys
• BLAKE2B is a non-standard JWT algorithm but provided for flexibility

License

MIT