jwtwallet

Server-side JWKS generation and management for the JWTWallet Protocol.

Installation

npm install jwtwallet
# or
yarn add jwtwallet

Usage

Create a Wallet

import { JWTWallet } from 'jwtwallet';

// Create with default platform (jwtwallet.com)
const wallet = await JWTWallet.create();

// Or with custom platform
const wallet = await JWTWallet.create({
  platform: 'keys.mycompany.com',
});

console.log(wallet.accountId);  // "abc123..." → use as subdomain
console.log(wallet.issuer);     // "https://abc123.jwtwallet.com"

Add Signing Keys

import * as jose from 'jose';

// Generate key pair (you keep the private key!)
const { publicKey, privateKey } = await jose.generateKeyPair('ES256');
const publicJWK = await jose.exportJWK(publicKey);

// Add only the public key to wallet
wallet.addSigningKey({
  kid: 'my-key-1',
  alg: 'ES256',
  publicKey: publicJWK,
});

Export Signed JWKS

const jwks = await wallet.signAndExportJwtWalletJWKS();
// {
//   keys: [{ kty: 'EC', ... }],
//   jwtwallet: {
//     version: 1,
//     accountPublicKey: { ... },
//     signature: "...",
//     revoked: []
//   }
// }

// Host this at: https://{accountId}.{platform}/.well-known/jwks.json

Revoke Keys

wallet.revokeKey('my-key-1');

const jwks = await wallet.signAndExportJwtWalletJWKS();
// jwks.jwtwallet.revoked = ['my-key-1']

Backup & Restore

// Export (includes account private key)
const backup = await wallet.export();
// Store backup securely!

// Import
const restored = await JWTWallet.import(backup);

Validate JWKS

import { validateJWKS } from 'jwtwallet';

const result = await validateJWKS(jwks, 'https://abc123.jwtwallet.com');
if (!result.valid) {
  console.error(result.error);
}

// Or self-validate
const result = await wallet.validate();

How It Works

1. Account Key: Each wallet has an account key pair (ES256). The public key hash becomes your account ID (subdomain).

2. Signing Keys: You generate signing keys externally and register only the public keys with your wallet.

3. JWKS Signing: When you export, the wallet signs canonical(keys) || canonical(accountPublicKey) || issuer with the account private key.

4. Verification: Clients use jwtwallet-jose to verify the JWKS trust chain before using keys.

Related

• jwtwallet-jose - Client-side JWKS verification
• JWTWallet Protocol - Protocol specification

License

MIT