jwtwallet-jose

JWTWallet Protocol extension for jose.

Installation

npm install jwtwallet-jose jose

Usage

import * as jose from 'jose';
import { createJwtWallet } from 'jwtwallet-jose';

const JWKS = createJwtWallet('https://abc123.jwtwallet.com');

const { payload } = await jose.jwtVerify(token, JWKS, {
  issuer: 'https://abc123.jwtwallet.com',
  audience: 'my-app'
});

API

createJwtWallet(issuer, options?)

Creates a JWTWallet-aware remote JWKS verifier. Drop-in compatible with jose.jwtVerify().

Parameters:

• issuer - The issuer URL (e.g., 'https://abc123.jwtwallet.com')
• options - Configuration options (see below)

Options:

interface JWTWalletOptions {
  timeoutDuration?: number;    // HTTP timeout in ms (default: 5000)
  cooldownDuration?: number;   // Min time between fetches in ms (default: 30000)
  cacheMaxAge?: number;        // Max cache age in ms (default: 600000)
  headers?: Record<string, string>;  // Custom HTTP headers
  [customFetch]?: FetchImplementation;  // Custom fetch function
  [jwksCache]?: JWKSCacheInput;  // External cache for serverless
}

Returns:

A key set function with additional properties:

• .coolingDown - Whether the cooldown period is active
• .fresh - Whether the cache is still fresh
• .reloading - Whether a fetch is in progress
• .reload() - Manually trigger a refresh
• .jwks() - Get the cached JWKS

What it does

1. Fetches JWKS from {issuer}/.well-known/jwks.json
2. If jwtwallet extension present:
   • Verifies URL account ID matches embedded public key hash
   • Verifies JWKS signature (keys + accountPublicKey + issuer)
   • Checks key revocation list on each verification
3. Returns key set compatible with jose.jwtVerify()

Custom Fetch

import { createJwtWallet, customFetch } from 'jwtwallet-jose';

const JWKS = createJwtWallet('https://abc123.jwtwallet.com', {
  [customFetch]: (url, options) => {
    // Custom fetch logic (proxy, retry, logging, etc.)
    return fetch(url, options);
  }
});

Serverless Cache

import { createJwtWallet, jwksCache } from 'jwtwallet-jose';

// Load from KV store
const cache = await kv.get('jwks-cache') || {};

const JWKS = createJwtWallet('https://abc123.jwtwallet.com', {
  [jwksCache]: cache
});

await jose.jwtVerify(token, JWKS);

// Save updated cache
if (cache.uat) {
  await kv.set('jwks-cache', cache);
}

Errors

• JWTWalletTrustError - JWKS trust verification failed (signature or account ID mismatch)
• JWTWalletRevokedError - Key has been revoked

Protocol

See JWTWallet Protocol Specification.

License

MIT