@jwtwallet/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Emin Kartal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# jwtwallet
+
+Server-side JWKS generation and management for the [JWTWallet Protocol](https://github.com/jwtwallet/protocol).
+
+## Installation
+
+```bash
+npm install jwtwallet
+# or
+yarn add jwtwallet
+```
+
+## Usage
+
+### Create a Wallet
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+wallet.revokeKey('my-key-1');
+
+const jwks = await wallet.signAndExportJwtWalletJWKS();
+// jwks.jwtwallet.revoked = ['my-key-1']
+```
+
+### Backup & Restore
+
+```typescript
+// Export (includes account private key)
+const backup = await wallet.export();
+// Store backup securely!
+
+// Import
+const restored = await JWTWallet.import(backup);
+```
+
+### Validate JWKS
+
+```typescript
+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](https://github.com/jwtwallet/jwtwallet-jose) to verify the JWKS trust chain before using keys.
+
+## Related
+
+- [jwtwallet-jose](https://github.com/jwtwallet/jwtwallet-jose) - Client-side JWKS verification
+- [JWTWallet Protocol](https://github.com/jwtwallet/protocol) - Protocol specification
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { JWTWallet } from './wallet.js';
+export { validateJWKS } from './validate.js';
+export { computeAccountId, buildSignedPayload } from './utils.js';
+export type { JWTWalletConfig, JWTWalletJWKS, JWTWalletExtension, AddSigningKeyOptions, SigningKeyInfo, WalletExport, ValidationResult, } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { JWTWallet } from './wallet.js';
+export { validateJWKS } from './validate.js';
+export { computeAccountId, buildSignedPayload } from './utils.js';

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import * as jose from 'jose';
+export interface JWTWalletConfig {
+    /** Platform domain for issuer URL. Default: 'jwtwallet.com' */
+    platform?: string;
+    /** Default algorithm for account key. Default: 'ES256' */
+    algorithm?: 'ES256' | 'ES384' | 'ES512';
+}
+export interface AddSigningKeyOptions {
+    /** Key ID. Auto-generated if not provided */
+    kid?: string;
+    /** Algorithm. Default: 'ES256' */
+    alg?: string;
+    /** Public key in JWK format */
+    publicKey: jose.JWK;
+}
+export interface SigningKeyInfo {
+    kid: string;
+    alg: string;
+    publicKey: jose.JWK;
+}
+export interface JWTWalletExtension {
+    version: number;
+    accountPublicKey: jose.JWK;
+    signature: string;
+    revoked: string[];
+}
+export interface JWTWalletJWKS extends jose.JSONWebKeySet {
+    jwtwallet: JWTWalletExtension;
+}
+export interface WalletExport {
+    version: number;
+    accountId: string;
+    platform: string;
+    accountKeyPair: {
+        publicKey: jose.JWK;
+        privateKey: jose.JWK;
+    };
+    signingKeys: SigningKeyInfo[];
+    revoked: string[];
+}
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+import * as jose from 'jose';
+/**
+ * Compute account ID from public key
+ * accountId = base64url(sha256(canonical(accountPublicKey))).slice(0, 20).toLowerCase()
+ */
+export declare function computeAccountId(accountPublicKey: jose.JWK): Promise<string>;
+/**
+ * Build the payload that should be signed
+ * payload = canonical(keys) || canonical(accountPublicKey) || issuer
+ */
+export declare function buildSignedPayload(keys: jose.JWK[], accountPublicKey: jose.JWK, issuer: string): string;
+/**
+ * Generate a unique key ID
+ */
+export declare function generateKid(): string;

package/dist/utils.js

@@ -0,0 +1,27 @@
+import * as jose from 'jose';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const canonicalize = require('canonicalize');
+/**
+ * Compute account ID from public key
+ * accountId = base64url(sha256(canonical(accountPublicKey))).slice(0, 20).toLowerCase()
+ */
+export async function computeAccountId(accountPublicKey) {
+    const canonical = canonicalize(accountPublicKey);
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+    return jose.base64url.encode(new Uint8Array(hash)).slice(0, 20).toLowerCase();
+}
+/**
+ * Build the payload that should be signed
+ * payload = canonical(keys) || canonical(accountPublicKey) || issuer
+ */
+export function buildSignedPayload(keys, accountPublicKey, issuer) {
+    return canonicalize(keys) + canonicalize(accountPublicKey) + issuer;
+}
+/**
+ * Generate a unique key ID
+ */
+export function generateKid() {
+    const bytes = crypto.getRandomValues(new Uint8Array(12));
+    return 'k_' + jose.base64url.encode(bytes);
+}

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+import type { JWTWalletJWKS, ValidationResult } from './types.js';
+/**
+ * Validate a JWTWallet JWKS
+ *
+ * Checks:
+ * 1. Account ID matches hash of accountPublicKey
+ * 2. Signature is valid over (keys || accountPublicKey || issuer)
+ * 3. All keys have kid and alg
+ * 4. Revoked keys are not in the keys array (warning only)
+ */
+export declare function validateJWKS(jwks: JWTWalletJWKS, issuer: string): Promise<ValidationResult>;

package/dist/validate.js

@@ -0,0 +1,73 @@
+import * as jose from 'jose';
+import { computeAccountId, buildSignedPayload } from './utils.js';
+/**
+ * Extract account ID from issuer URL (subdomain)
+ */
+function extractAccountIdFromIssuer(issuer) {
+    const url = new URL(issuer);
+    return url.hostname.split('.')[0];
+}
+/**
+ * Validate a JWTWallet JWKS
+ *
+ * Checks:
+ * 1. Account ID matches hash of accountPublicKey
+ * 2. Signature is valid over (keys || accountPublicKey || issuer)
+ * 3. All keys have kid and alg
+ * 4. Revoked keys are not in the keys array (warning only)
+ */
+export async function validateJWKS(jwks, issuer) {
+    try {
+        const { jwtwallet } = jwks;
+        if (!jwtwallet) {
+            return { valid: false, error: 'Missing jwtwallet extension' };
+        }
+        if (jwtwallet.version !== 1) {
+            return { valid: false, error: `Unsupported version: ${jwtwallet.version}` };
+        }
+        const { accountPublicKey, signature, revoked } = jwtwallet;
+        // 1. Verify account ID matches public key hash
+        const expectedAccountId = await computeAccountId(accountPublicKey);
+        const urlAccountId = extractAccountIdFromIssuer(issuer);
+        if (expectedAccountId !== urlAccountId) {
+            return {
+                valid: false,
+                error: `Account ID mismatch: expected ${expectedAccountId}, got ${urlAccountId}`,
+            };
+        }
+        // 2. Verify signature
+        const payload = buildSignedPayload(jwks.keys, accountPublicKey, issuer);
+        const payloadBytes = new TextEncoder().encode(payload);
+        const signatureBytes = jose.base64url.decode(signature);
+        const publicKey = await jose.importJWK(accountPublicKey, accountPublicKey.alg || 'ES256');
+        const isValid = await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, publicKey, new Uint8Array(signatureBytes), new Uint8Array(payloadBytes));
+        if (!isValid) {
+            return { valid: false, error: 'Invalid signature' };
+        }
+        // 3. Check all keys have kid and alg
+        for (const key of jwks.keys) {
+            if (!key.kid) {
+                return { valid: false, error: 'Key missing kid' };
+            }
+            if (!key.alg) {
+                return { valid: false, error: `Key ${key.kid} missing alg` };
+            }
+        }
+        // 4. Check revoked keys are not in keys array (optional warning)
+        const keyKids = new Set(jwks.keys.map((k) => k.kid));
+        for (const revokedKid of revoked || []) {
+            if (keyKids.has(revokedKid)) {
+                // This is allowed but might indicate an issue
+                // Platform should handle this - revoked keys should still be verifiable
+                // for tokens issued before revocation
+            }
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}

package/dist/wallet.d.ts

@@ -0,0 +1,54 @@
+import * as jose from 'jose';
+import type { JWTWalletConfig, JWTWalletJWKS, AddSigningKeyOptions, SigningKeyInfo, WalletExport, ValidationResult } from './types.js';
+export declare class JWTWallet {
+    #private;
+    private constructor();
+    /**
+     * Create a new JWTWallet with a fresh account key pair
+     */
+    static create(config?: JWTWalletConfig): Promise<JWTWallet>;
+    /**
+     * Import a wallet from exported data
+     */
+    static import(data: WalletExport): Promise<JWTWallet>;
+    /** Account ID (subdomain) */
+    get accountId(): string;
+    /** Full issuer URL */
+    get issuer(): string;
+    /** Platform domain */
+    get platform(): string;
+    /** Account public key */
+    get accountPublicKey(): jose.JWK;
+    /** List of signing keys */
+    get signingKeys(): SigningKeyInfo[];
+    /** List of revoked key IDs */
+    get revokedKeys(): string[];
+    /**
+     * Add a signing key (public key only)
+     */
+    addSigningKey(options: AddSigningKeyOptions): SigningKeyInfo;
+    /**
+     * Remove a signing key
+     */
+    removeSigningKey(kid: string): boolean;
+    /**
+     * Revoke a signing key (adds to revoked list, does not remove from keys)
+     */
+    revokeKey(kid: string): void;
+    /**
+     * Unrevoke a signing key
+     */
+    unrevokeKey(kid: string): boolean;
+    /**
+     * Sign and export the JWKS with JWTWallet extension
+     */
+    signAndExportJwtWalletJWKS(): Promise<JWTWalletJWKS>;
+    /**
+     * Export wallet for backup (includes account private key)
+     */
+    export(): Promise<WalletExport>;
+    /**
+     * Validate the current wallet state
+     */
+    validate(): Promise<ValidationResult>;
+}

package/dist/wallet.js

@@ -0,0 +1,163 @@
+import * as jose from 'jose';
+import { computeAccountId, buildSignedPayload, generateKid } from './utils.js';
+import { validateJWKS } from './validate.js';
+const DEFAULT_PLATFORM = 'jwtwallet.com';
+const DEFAULT_ALGORITHM = 'ES256';
+const WALLET_VERSION = 1;
+export class JWTWallet {
+    #platform;
+    #algorithm;
+    #accountId;
+    #accountPublicKey;
+    #accountPrivateKey;
+    #signingKeys = new Map();
+    #revoked = new Set();
+    constructor(platform, algorithm, accountId, accountPublicKey, accountPrivateKey) {
+        this.#platform = platform;
+        this.#algorithm = algorithm;
+        this.#accountId = accountId;
+        this.#accountPublicKey = accountPublicKey;
+        this.#accountPrivateKey = accountPrivateKey;
+    }
+    /**
+     * Create a new JWTWallet with a fresh account key pair
+     */
+    static async create(config = {}) {
+        const platform = config.platform ?? DEFAULT_PLATFORM;
+        const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+        // Generate account key pair
+        const { publicKey, privateKey } = await jose.generateKeyPair(algorithm, {
+            extractable: true,
+        });
+        const accountPublicKey = await jose.exportJWK(publicKey);
+        // Add alg to public key for clarity
+        accountPublicKey.alg = algorithm;
+        const accountId = await computeAccountId(accountPublicKey);
+        return new JWTWallet(platform, algorithm, accountId, accountPublicKey, privateKey);
+    }
+    /**
+     * Import a wallet from exported data
+     */
+    static async import(data) {
+        const algorithm = data.accountKeyPair.publicKey.alg ?? DEFAULT_ALGORITHM;
+        // Import the private key
+        const privateKey = await jose.importJWK(data.accountKeyPair.privateKey, algorithm);
+        const wallet = new JWTWallet(data.platform, algorithm, data.accountId, data.accountKeyPair.publicKey, privateKey);
+        // Restore signing keys
+        for (const key of data.signingKeys) {
+            wallet.#signingKeys.set(key.kid, key);
+        }
+        // Restore revoked keys
+        for (const kid of data.revoked) {
+            wallet.#revoked.add(kid);
+        }
+        return wallet;
+    }
+    /** Account ID (subdomain) */
+    get accountId() {
+        return this.#accountId;
+    }
+    /** Full issuer URL */
+    get issuer() {
+        return `https://${this.#accountId}.${this.#platform}`;
+    }
+    /** Platform domain */
+    get platform() {
+        return this.#platform;
+    }
+    /** Account public key */
+    get accountPublicKey() {
+        return { ...this.#accountPublicKey };
+    }
+    /** List of signing keys */
+    get signingKeys() {
+        return Array.from(this.#signingKeys.values());
+    }
+    /** List of revoked key IDs */
+    get revokedKeys() {
+        return Array.from(this.#revoked);
+    }
+    /**
+     * Add a signing key (public key only)
+     */
+    addSigningKey(options) {
+        const kid = options.kid ?? generateKid();
+        const alg = options.alg ?? DEFAULT_ALGORITHM;
+        // Ensure the public key has kid and alg
+        const publicKey = {
+            ...options.publicKey,
+            kid,
+            alg,
+            use: 'sig',
+        };
+        const keyInfo = { kid, alg, publicKey };
+        this.#signingKeys.set(kid, keyInfo);
+        return keyInfo;
+    }
+    /**
+     * Remove a signing key
+     */
+    removeSigningKey(kid) {
+        return this.#signingKeys.delete(kid);
+    }
+    /**
+     * Revoke a signing key (adds to revoked list, does not remove from keys)
+     */
+    revokeKey(kid) {
+        this.#revoked.add(kid);
+    }
+    /**
+     * Unrevoke a signing key
+     */
+    unrevokeKey(kid) {
+        return this.#revoked.delete(kid);
+    }
+    /**
+     * Sign and export the JWKS with JWTWallet extension
+     */
+    async signAndExportJwtWalletJWKS() {
+        // Collect all public keys (excluding revoked from keys array is optional,
+        // but revoked list will be in the extension)
+        const keys = Array.from(this.#signingKeys.values()).map((k) => k.publicKey);
+        // Build the payload to sign
+        const payload = buildSignedPayload(keys, this.#accountPublicKey, this.issuer);
+        const payloadBytes = new TextEncoder().encode(payload);
+        // Sign with account private key
+        const signatureBytes = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, this.#accountPrivateKey, payloadBytes);
+        const signature = jose.base64url.encode(new Uint8Array(signatureBytes));
+        return {
+            keys,
+            jwtwallet: {
+                version: WALLET_VERSION,
+                accountPublicKey: this.#accountPublicKey,
+                signature,
+                revoked: Array.from(this.#revoked),
+            },
+        };
+    }
+    /**
+     * Export wallet for backup (includes account private key)
+     */
+    async export() {
+        // Export private key
+        const privateKeyJWK = await crypto.subtle.exportKey('jwk', this.#accountPrivateKey);
+        return {
+            version: WALLET_VERSION,
+            accountId: this.#accountId,
+            platform: this.#platform,
+            accountKeyPair: {
+                publicKey: this.#accountPublicKey,
+                privateKey: privateKeyJWK,
+            },
+            signingKeys: Array.from(this.#signingKeys.values()),
+            revoked: Array.from(this.#revoked),
+        };
+    }
+    /**
+     * Validate the current wallet state
+     */
+    async validate() {
+        const jwks = await this.signAndExportJwtWalletJWKS();
+        return validateJWKS(jwks, this.issuer);
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@jwtwallet/core",
+  "version": "0.1.0",
+  "description": "JWTWallet Protocol - Server-side JWKS generation and management",
+  "author": {
+    "name": "Mehmet Emin Kartal",
+    "email": "mehmet@appac.ltd"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "semantic-release"
+  },
+  "keywords": [
+    "jwt",
+    "jwks",
+    "jwtwallet",
+    "jose",
+    "authentication",
+    "trustless"
+  ],
+  "dependencies": {
+    "canonicalize": "^2.1.0",
+    "jose": "^6.1.0"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^22.0.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwtwallet/jwtwallet"
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { JWTWallet } from './wallet.js';
+export { validateJWKS } from './validate.js';
+export { computeAccountId, buildSignedPayload } from './utils.js';
+export type {
+  JWTWalletConfig,
+  JWTWalletJWKS,
+  JWTWalletExtension,
+  AddSigningKeyOptions,
+  SigningKeyInfo,
+  WalletExport,
+  ValidationResult,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,61 @@
+import * as jose from 'jose';
+
+// ============ Config ============
+
+export interface JWTWalletConfig {
+  /** Platform domain for issuer URL. Default: 'jwtwallet.com' */
+  platform?: string;
+  /** Default algorithm for account key. Default: 'ES256' */
+  algorithm?: 'ES256' | 'ES384' | 'ES512';
+}
+
+// ============ Signing Key ============
+
+export interface AddSigningKeyOptions {
+  /** Key ID. Auto-generated if not provided */
+  kid?: string;
+  /** Algorithm. Default: 'ES256' */
+  alg?: string;
+  /** Public key in JWK format */
+  publicKey: jose.JWK;
+}
+
+export interface SigningKeyInfo {
+  kid: string;
+  alg: string;
+  publicKey: jose.JWK;
+}
+
+// ============ JWKS Types ============
+
+export interface JWTWalletExtension {
+  version: number;
+  accountPublicKey: jose.JWK;
+  signature: string;
+  revoked: string[];
+}
+
+export interface JWTWalletJWKS extends jose.JSONWebKeySet {
+  jwtwallet: JWTWalletExtension;
+}
+
+// ============ Export/Import ============
+
+export interface WalletExport {
+  version: number;
+  accountId: string;
+  platform: string;
+  accountKeyPair: {
+    publicKey: jose.JWK;
+    privateKey: jose.JWK;
+  };
+  signingKeys: SigningKeyInfo[];
+  revoked: string[];
+}
+
+// ============ Validation ============
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}

package/src/utils.ts

@@ -0,0 +1,38 @@
+import * as jose from 'jose';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const canonicalize = require('canonicalize') as (input: unknown) => string | undefined;
+
+/**
+ * Compute account ID from public key
+ * accountId = base64url(sha256(canonical(accountPublicKey))).slice(0, 20).toLowerCase()
+ */
+export async function computeAccountId(accountPublicKey: jose.JWK): Promise<string> {
+  const canonical = canonicalize(accountPublicKey)!;
+  const hash = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(canonical)
+  );
+  return jose.base64url.encode(new Uint8Array(hash)).slice(0, 20).toLowerCase();
+}
+
+/**
+ * Build the payload that should be signed
+ * payload = canonical(keys) || canonical(accountPublicKey) || issuer
+ */
+export function buildSignedPayload(
+  keys: jose.JWK[],
+  accountPublicKey: jose.JWK,
+  issuer: string
+): string {
+  return canonicalize(keys)! + canonicalize(accountPublicKey)! + issuer;
+}
+
+/**
+ * Generate a unique key ID
+ */
+export function generateKid(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  return 'k_' + jose.base64url.encode(bytes);
+}

package/src/validate.ts

@@ -0,0 +1,98 @@
+import * as jose from 'jose';
+import type { JWTWalletJWKS, ValidationResult } from './types.js';
+import { computeAccountId, buildSignedPayload } from './utils.js';
+
+/**
+ * Extract account ID from issuer URL (subdomain)
+ */
+function extractAccountIdFromIssuer(issuer: string): string {
+  const url = new URL(issuer);
+  return url.hostname.split('.')[0];
+}
+
+/**
+ * Validate a JWTWallet JWKS
+ * 
+ * Checks:
+ * 1. Account ID matches hash of accountPublicKey
+ * 2. Signature is valid over (keys || accountPublicKey || issuer)
+ * 3. All keys have kid and alg
+ * 4. Revoked keys are not in the keys array (warning only)
+ */
+export async function validateJWKS(
+  jwks: JWTWalletJWKS,
+  issuer: string
+): Promise<ValidationResult> {
+  try {
+    const { jwtwallet } = jwks;
+
+    if (!jwtwallet) {
+      return { valid: false, error: 'Missing jwtwallet extension' };
+    }
+
+    if (jwtwallet.version !== 1) {
+      return { valid: false, error: `Unsupported version: ${jwtwallet.version}` };
+    }
+
+    const { accountPublicKey, signature, revoked } = jwtwallet;
+
+    // 1. Verify account ID matches public key hash
+    const expectedAccountId = await computeAccountId(accountPublicKey);
+    const urlAccountId = extractAccountIdFromIssuer(issuer);
+
+    if (expectedAccountId !== urlAccountId) {
+      return {
+        valid: false,
+        error: `Account ID mismatch: expected ${expectedAccountId}, got ${urlAccountId}`,
+      };
+    }
+
+    // 2. Verify signature
+    const payload = buildSignedPayload(jwks.keys, accountPublicKey, issuer);
+    const payloadBytes = new TextEncoder().encode(payload);
+    const signatureBytes = jose.base64url.decode(signature);
+
+    const publicKey = await jose.importJWK(
+      accountPublicKey,
+      (accountPublicKey.alg as string) || 'ES256'
+    );
+
+    const isValid = await crypto.subtle.verify(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      publicKey as CryptoKey,
+      new Uint8Array(signatureBytes),
+      new Uint8Array(payloadBytes)
+    );
+
+    if (!isValid) {
+      return { valid: false, error: 'Invalid signature' };
+    }
+
+    // 3. Check all keys have kid and alg
+    for (const key of jwks.keys) {
+      if (!key.kid) {
+        return { valid: false, error: 'Key missing kid' };
+      }
+      if (!key.alg) {
+        return { valid: false, error: `Key ${key.kid} missing alg` };
+      }
+    }
+
+    // 4. Check revoked keys are not in keys array (optional warning)
+    const keyKids = new Set(jwks.keys.map((k) => k.kid));
+    for (const revokedKid of revoked || []) {
+      if (keyKids.has(revokedKid)) {
+        // This is allowed but might indicate an issue
+        // Platform should handle this - revoked keys should still be verifiable
+        // for tokens issued before revocation
+      }
+    }
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}

package/src/wallet.ts

@@ -0,0 +1,227 @@
+import * as jose from 'jose';
+import type {
+  JWTWalletConfig,
+  JWTWalletJWKS,
+  AddSigningKeyOptions,
+  SigningKeyInfo,
+  WalletExport,
+  ValidationResult,
+} from './types.js';
+import { computeAccountId, buildSignedPayload, generateKid } from './utils.js';
+import { validateJWKS } from './validate.js';
+
+const DEFAULT_PLATFORM = 'jwtwallet.com';
+const DEFAULT_ALGORITHM = 'ES256';
+const WALLET_VERSION = 1;
+
+export class JWTWallet {
+  readonly #platform: string;
+  readonly #algorithm: 'ES256' | 'ES384' | 'ES512';
+  #accountId: string;
+  #accountPublicKey: jose.JWK;
+  #accountPrivateKey: CryptoKey;
+  #signingKeys: Map<string, SigningKeyInfo> = new Map();
+  #revoked: Set<string> = new Set();
+
+  private constructor(
+    platform: string,
+    algorithm: 'ES256' | 'ES384' | 'ES512',
+    accountId: string,
+    accountPublicKey: jose.JWK,
+    accountPrivateKey: CryptoKey
+  ) {
+    this.#platform = platform;
+    this.#algorithm = algorithm;
+    this.#accountId = accountId;
+    this.#accountPublicKey = accountPublicKey;
+    this.#accountPrivateKey = accountPrivateKey;
+  }
+
+  /**
+   * Create a new JWTWallet with a fresh account key pair
+   */
+  static async create(config: JWTWalletConfig = {}): Promise<JWTWallet> {
+    const platform = config.platform ?? DEFAULT_PLATFORM;
+    const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+
+    // Generate account key pair
+    const { publicKey, privateKey } = await jose.generateKeyPair(algorithm, {
+      extractable: true,
+    });
+
+    const accountPublicKey = await jose.exportJWK(publicKey);
+    // Add alg to public key for clarity
+    accountPublicKey.alg = algorithm;
+
+    const accountId = await computeAccountId(accountPublicKey);
+
+    return new JWTWallet(
+      platform,
+      algorithm,
+      accountId,
+      accountPublicKey,
+      privateKey as CryptoKey
+    );
+  }
+
+  /**
+   * Import a wallet from exported data
+   */
+  static async import(data: WalletExport): Promise<JWTWallet> {
+    const algorithm = (data.accountKeyPair.publicKey.alg as 'ES256' | 'ES384' | 'ES512') ?? DEFAULT_ALGORITHM;
+    
+    // Import the private key
+    const privateKey = await jose.importJWK(data.accountKeyPair.privateKey, algorithm);
+
+    const wallet = new JWTWallet(
+      data.platform,
+      algorithm,
+      data.accountId,
+      data.accountKeyPair.publicKey,
+      privateKey as CryptoKey
+    );
+
+    // Restore signing keys
+    for (const key of data.signingKeys) {
+      wallet.#signingKeys.set(key.kid, key);
+    }
+
+    // Restore revoked keys
+    for (const kid of data.revoked) {
+      wallet.#revoked.add(kid);
+    }
+
+    return wallet;
+  }
+
+  /** Account ID (subdomain) */
+  get accountId(): string {
+    return this.#accountId;
+  }
+
+  /** Full issuer URL */
+  get issuer(): string {
+    return `https://${this.#accountId}.${this.#platform}`;
+  }
+
+  /** Platform domain */
+  get platform(): string {
+    return this.#platform;
+  }
+
+  /** Account public key */
+  get accountPublicKey(): jose.JWK {
+    return { ...this.#accountPublicKey };
+  }
+
+  /** List of signing keys */
+  get signingKeys(): SigningKeyInfo[] {
+    return Array.from(this.#signingKeys.values());
+  }
+
+  /** List of revoked key IDs */
+  get revokedKeys(): string[] {
+    return Array.from(this.#revoked);
+  }
+
+  /**
+   * Add a signing key (public key only)
+   */
+  addSigningKey(options: AddSigningKeyOptions): SigningKeyInfo {
+    const kid = options.kid ?? generateKid();
+    const alg = options.alg ?? DEFAULT_ALGORITHM;
+
+    // Ensure the public key has kid and alg
+    const publicKey: jose.JWK = {
+      ...options.publicKey,
+      kid,
+      alg,
+      use: 'sig',
+    };
+
+    const keyInfo: SigningKeyInfo = { kid, alg, publicKey };
+    this.#signingKeys.set(kid, keyInfo);
+
+    return keyInfo;
+  }
+
+  /**
+   * Remove a signing key
+   */
+  removeSigningKey(kid: string): boolean {
+    return this.#signingKeys.delete(kid);
+  }
+
+  /**
+   * Revoke a signing key (adds to revoked list, does not remove from keys)
+   */
+  revokeKey(kid: string): void {
+    this.#revoked.add(kid);
+  }
+
+  /**
+   * Unrevoke a signing key
+   */
+  unrevokeKey(kid: string): boolean {
+    return this.#revoked.delete(kid);
+  }
+
+  /**
+   * Sign and export the JWKS with JWTWallet extension
+   */
+  async signAndExportJwtWalletJWKS(): Promise<JWTWalletJWKS> {
+    // Collect all public keys (excluding revoked from keys array is optional,
+    // but revoked list will be in the extension)
+    const keys = Array.from(this.#signingKeys.values()).map((k) => k.publicKey);
+
+    // Build the payload to sign
+    const payload = buildSignedPayload(keys, this.#accountPublicKey, this.issuer);
+    const payloadBytes = new TextEncoder().encode(payload);
+
+    // Sign with account private key
+    const signatureBytes = await crypto.subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      this.#accountPrivateKey,
+      payloadBytes
+    );
+    const signature = jose.base64url.encode(new Uint8Array(signatureBytes));
+
+    return {
+      keys,
+      jwtwallet: {
+        version: WALLET_VERSION,
+        accountPublicKey: this.#accountPublicKey,
+        signature,
+        revoked: Array.from(this.#revoked),
+      },
+    };
+  }
+
+  /**
+   * Export wallet for backup (includes account private key)
+   */
+  async export(): Promise<WalletExport> {
+    // Export private key
+    const privateKeyJWK = await crypto.subtle.exportKey('jwk', this.#accountPrivateKey);
+
+    return {
+      version: WALLET_VERSION,
+      accountId: this.#accountId,
+      platform: this.#platform,
+      accountKeyPair: {
+        publicKey: this.#accountPublicKey,
+        privateKey: privateKeyJWK as jose.JWK,
+      },
+      signingKeys: Array.from(this.#signingKeys.values()),
+      revoked: Array.from(this.#revoked),
+    };
+  }
+
+  /**
+   * Validate the current wallet state
+   */
+  async validate(): Promise<ValidationResult> {
+    const jwks = await this.signAndExportJwtWalletJWKS();
+    return validateJWKS(jwks, this.issuer);
+  }
+}