npm package: @kakilangit/jwt
Description: WebAssembly bindings for JWT Debugger tool
Latest version: 0.2.0

# @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

```bash
npm install @kakilangit/jwt
```

## Usage

```javascript
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