@hawcx/oauth-client 0.2.0 → 5.1.0

package/README.md

@@ -1,310 +1,693 @@
-# Hawcx OAuth Client SDK (Node.js)
+# @hawcx/oauth-client
 
-A lightweight, production-ready Node.js/TypeScript library for exchanging OAuth authorization codes and verifying JWT claims. Built with security, reliability, and ease of use in mind.
+Simple, production-ready OAuth client SDK for Hawcx authentication.
 
 ## Features
 
-- 🔐 **Secure JWT Verification**: RS256/ES256/EdDSA signature verification with configurable validation
-- 🆕 **PKCE Support**: Native PKCE (RFC 7636) support for enhanced OAuth security
-- 🚀 **Simple API**: One function call to go from code to verified claims
-- 🎯 **High-Level Hawcx Client**: One-line MFA setup with automatic encryption/signing
-- 🛡️ **Comprehensive Error Handling**: Clear, actionable error messages for all failure scenarios
-- 📝 **TypeScript First**: Full type definitions for better IDE support and type checking
-- 🧪 **Production Ready**: Extensive error handling and security best practices
-- 🔧 **Express/Fastify Compatible**: Works with any Node.js framework
-- 🔍 **Detailed Logging**: Structured logging for debugging (no sensitive data logged)
+- **OIDC Discovery** - `HawcxOAuth.fromIssuer(...)` resolves endpoints from `/.well-known/openid-configuration` and enforces signature + `iss` + `aud` + `exp` + `nbf` on verify
+- **Simple JWT Verification** - Uses `jose` library for automatic JWKS caching and signature handling
+- **PKCE Support** - Native PKCE (RFC 7636) support for enhanced OAuth security
+- **Delegation API** - Server-to-server user management (MFA, devices)
+- **Step-Up Auth** - Step-up authentication flows for sensitive operations
+- **TypeScript First** - Full type definitions included
+- **Zero Config Crypto** - All cryptographic complexity hidden behind a single secret key
 
 ## Installation
 
 ```bash
 npm install @hawcx/oauth-client
+```
+
+## Quick Start (OIDC discovery, recommended)
+
+`HawcxOAuth.fromIssuer(...)` does the discovery fetch once at startup and
+gives you a client whose `exchangeCode` + `verifyToken` enforce all the
+standard OIDC claim checks. Construct once and reuse.
+
+```typescript
+import { HawcxOAuth } from '@hawcx/oauth-client';
+
+const oauth = await HawcxOAuth.fromIssuer({
+  issuer: 'https://api.hawcx.com',        // → discovery + expected `iss`
+  configId: process.env.HAWCX_CONFIG_ID!, // → X-Config-Id header
+  clientId: process.env.HAWCX_CLIENT_ID!, // → expected `aud` on id_tokens
+});
+
+const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+console.log(claims.sub);   // user ID
+console.log(claims.email); // user email
+```
+
+> **`configId` vs `clientId` — they are different values.**
+> Hawcx separates the tenant routing key from the audience claim:
+>
+> - **`configId`** — the per-tenant config identifier. Sent as the
+>   `X-Config-Id` header on the token-exchange POST so the OAuth server
+>   can look up the tenant.
+> - **`clientId`** — the value the tenant has configured (in the Hawcx
+>   admin console) as the `aud` claim on issued id_tokens. The verifier
+>   matches the token's `aud` against this exact string.
+>
+> Passing the same value for both fails verification with
+> `Unexpected JWT audience` unless your tenant happens to use identical
+> strings.
+
+## Quick Start (legacy)
+
+The legacy single-arg constructor still works for backward compatibility
+with 4.x callers. It verifies the JWT signature only — `iss` and `aud`
+are not checked. Prefer `fromIssuer` for new code.
+
+```typescript
+import { HawcxOAuth } from '@hawcx/oauth-client';
 
-# or with yarn
-yarn add @hawcx/oauth-client
+const oauth = new HawcxOAuth({ configId: 'your-config-id' });
 
-# or with pnpm
-pnpm add @hawcx/oauth-client
+const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
 ```
 
-## Quick Start
+---
+
+## Confidential clients (`private_key_jwt`)
+
+If your project is registered in the Hawcx admin console with **Client
+authentication = Signing key (`private_key_jwt`)**, attach an Ed25519 signer.
+The SDK then signs an RFC 7523 `client_assertion` on every token exchange
+(PKCE is still sent). Public clients omit this and keep using PKCE only.
+
+```typescript
+import { HawcxOAuth, ClientAssertionSigner } from '@hawcx/oauth-client';
+
+const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!); // OKP/Ed25519, with kid
+
+const oauth = (
+  await HawcxOAuth.fromIssuer({
+    issuer: 'https://dev-demo-api.hawcx.com',
+    configId: process.env.HAWCX_CONFIG_ID!,
+    clientId: process.env.HAWCX_CLIENT_ID!,
+  })
+).withClientAssertion(ClientAssertionSigner.ed25519FromJwk(privateJwk));
+
+const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+```
+
+The private key must be Ed25519 (`kty: 'OKP', crv: 'Ed25519'`, with a `kid`);
+its public JWK is what you register in the admin console. The assertion's `aud`
+is the discovered `token_endpoint`, and EdDSA is the only accepted algorithm.
+`clientId` must be the confidential client's id — it becomes the assertion
+`iss`/`sub` and the id_token `aud`.
+
+> If you bound a `nonce` at `/authorize`, pass it as the 4th argument to
+> `exchangeCode(code, verifier, redirectUri?, expectedNonce)` — verification
+> refuses a nonce-bearing token when none is supplied (OIDC Core §3.1.3.7).
+
+---
+
+## Modules
 
-### OAuth Code Exchange
+| Module | Purpose |
+|--------|---------|
+| **OAuth** | Token exchange and JWT verification |
+| **Delegation** | Server-to-server user management (MFA, devices) |
+| **Step-Up** | Step-up authentication flows |
+
+---
+
+## OAuth Module
+
+Core module for OAuth 2.1 + PKCE authentication.
+
+### Construction
+
+#### Discovery mode (recommended)
 
 ```typescript
-import { exchangeCodeForClaims } from '@hawcx/oauth-client';
+import { HawcxOAuth } from '@hawcx/oauth-client';
+
+const oauth = await HawcxOAuth.fromIssuer({
+  issuer: 'https://api.hawcx.com',     // Required: discovery + expected `iss`
+  configId: 'your-config-id',          // Required: X-Config-Id header
+  clientId: 'your-client-id',          // Required: expected `aud` on id_tokens
+  timeout: 10000,                       // Optional: per-request timeout in ms
+  discoveryTimeout: 5000,               // Optional: discovery fetch timeout in ms
+});
 
-// Exchange authorization code for verified claims
-const claims = await exchangeCodeForClaims({
-  code: req.body.code,
-  oauthTokenUrl: process.env.OAUTH_TOKEN_ENDPOINT!,
-  clientId: process.env.OAUTH_CLIENT_ID!,
-  apiKey: process.env.HAWCX_API_KEY!,
-  publicKey: process.env.OAUTH_PUBLIC_KEY!,
-  // Optional (recommended for production):
-  codeVerifier: session.pkceVerifier,  // PKCE support
-  audience: 'my-app',  // Validate 'aud' claim
-  issuer: 'https://oauth.example.com',  // Validate 'iss' claim
-  leeway: 10  // Clock skew tolerance
+oauth.discoveryMetadata; // resolved OIDC discovery doc, for diagnostics
+```
+
+Throws `DiscoveryError` if the discovery document is unreachable, returns
+non-2xx, isn't valid JSON, or is missing any of `token_endpoint`,
+`jwks_uri`, `id_token_signing_alg_values_supported`.
+
+#### Legacy mode
+
+```typescript
+const oauth = new HawcxOAuth({
+  configId: 'your-config-id',        // Required
+  baseUrl: 'https://api.hawcx.com',  // Optional: defaults to api.hawcx.com
+  timeout: 10000,                     // Optional
 });
+```
+
+Hits the fixed endpoints `<baseUrl>/oauth2/token` and `<baseUrl>/keys`
+directly. **Signature-only verification** — `iss` and `aud` are not
+checked. Kept for backward compatibility with 4.x callers.
+
+### Methods
+
+#### `exchangeCode(code, codeVerifier, redirectUri?): Promise<ExchangeResult>`
+
+Exchange an authorization code for tokens.
+
+```typescript
+const { idToken, claims } = await oauth.exchangeCode(
+  'authorization-code',
+  'pkce-code-verifier'
+);
+
+// With redirect_uri (RFC 6749 §4.1.3) when your auth request registered one:
+const { idToken, claims } = await oauth.exchangeCode(
+  'authorization-code',
+  'pkce-code-verifier',
+  'https://app.example.com/auth/callback'
+);
+```
+
+**Returns:**
+```typescript
+interface ExchangeResult {
+  idToken: string;    // Raw JWT token
+  claims: JwtClaims;  // Verified claims
+}
+```
+
+#### `verifyToken(token, options?): Promise<JwtClaims>`
 
-// Use the verified claims
-const userId = claims.sub;
-// Mint your own access token (SDK only verifies, doesn't mint)
+Verify an existing JWT token. In discovery mode, enforces signature + `iss` +
+`aud` + `exp` + `nbf`. In legacy mode, only the signature is checked.
+
+```typescript
+const claims = await oauth.verifyToken(idToken);
+
+// With expected nonce (useful for flows that bind a nonce to the auth request):
+const claims = await oauth.verifyToken(idToken, { nonce: 'expected-nonce' });
+```
+
+**Returns:**
+```typescript
+interface JwtClaims {
+  sub?: string;            // User ID
+  iss?: string;            // Issuer
+  aud?: string | string[]; // Audience
+  iat?: number;            // Issued at (unix timestamp)
+  exp?: number;            // Expiration (unix timestamp)
+  email?: string;          // User email
+  name?: string;           // User name
+  amr?: string[];          // Authentication methods
+  mfa_method?: string;     // MFA method used
+  nonce?: string;          // Nonce (if bound)
+}
+```
+
+#### `refreshJwks(): void`
+
+Reset the JWKS cache so the next verification refetches keys (useful for testing
+or key rotation).
+
+```typescript
+oauth.refreshJwks();
+```
+
+> **Deprecated:** `clearCache()` is a deprecated passthrough that calls
+> `refreshJwks()` (and emits a one-time `console.warn`). It still works but will be
+> removed in 6.0.0 — prefer `refreshJwks()`.
+
+### Errors
+
+```typescript
+import {
+  HawcxOAuthError,        // Base error class
+  DiscoveryError,         // OIDC discovery resolution failed (fromIssuer only)
+  TokenExchangeError,     // Code exchange failed
+  TokenVerificationError  // JWT verification failed
+} from '@hawcx/oauth-client';
+
+try {
+  const oauth = await HawcxOAuth.fromIssuer({ issuer, configId, clientId });
+  await oauth.exchangeCode(code, verifier);
+} catch (error) {
+  if (error instanceof DiscoveryError) {
+    console.log(error.cause); // original network / parse error
+  }
+  if (error instanceof TokenExchangeError) {
+    console.log(error.statusCode); // HTTP status code
+  }
+  if (error instanceof TokenVerificationError) {
+    // "Token expired", "Invalid signature", "Unexpected JWT audience: ...", etc.
+    console.log(error.message);
+  }
+}
 ```
 
-### Hawcx Delegation (MFA Setup)
+---
+
+## Delegation Module
 
-For Hawcx MFA setup and user management, use the delegation client:
+Server-to-server API for managing users, MFA, and devices. Requires a Hawcx secret key.
+
+### `DelegationClient`
 
 ```typescript
-import { HawcxDelegationClient, MfaMethod } from '@hawcx/oauth-client';
+import { DelegationClient, MfaMethod } from '@hawcx/oauth-client';
+
+const client = DelegationClient.fromSecretKey({
+  baseUrl: 'https://api.hawcx.com',
+  secretKey: process.env.HAWCX_SECRET_KEY!,
+  apiKey: 'optional-api-key',  // Optional
+  timeoutSeconds: 15,          // Optional (default: 15)
+  clockSkewSeconds: 300,       // Optional (default: 300)
+});
+```
 
-// 🎉 One-line initialization from explicit keys!
-const client = HawcxDelegationClient.fromKeys({
-  spSigningKey: process.env.SP_ED25519_PRIVATE_KEY_PEM!,
-  spEncryptionKey: process.env.SP_X25519_PRIVATE_KEY_PEM!,
-  idpVerifyKey: process.env.IDP_ED25519_PUBLIC_KEY_PEM!,
-  idpEncryptionKey: process.env.IDP_X25519_PUBLIC_KEY_PEM!,
-  baseUrl: 'https://example.hawcx.com',
-  spId: process.env.OAUTH_CLIENT_ID!
+### MFA Operations
+
+#### `client.mfa.initiate(options): Promise<object>`
+
+Initiate MFA setup or change for a user.
+
+```typescript
+// Email MFA
+const result = await client.mfa.initiate({
+  userId: 'user@example.com',
+  mfaMethod: MfaMethod.EMAIL,
 });
 
-// Initiate MFA setup (Email, SMS, or TOTP)
-const result = await client.initiateMfaChange({
-  userid: "user@example.com",
-  mfaMethod: MfaMethod.SMS, 
-  phoneNumber: "+15551234567"
+// SMS MFA (requires phone number)
+const result = await client.mfa.initiate({
+  userId: 'user@example.com',
+  mfaMethod: MfaMethod.SMS,
+  phoneNumber: '+1234567890',
 });
 
-// Verify OTP and complete MFA setup
-await client.verifyMfaChange({
-  userid: "user@example.com",
-  sessionId: result.session_id,
-  otp: "123456"
+// TOTP MFA
+const result = await client.mfa.initiate({
+  userId: 'user@example.com',
+  mfaMethod: MfaMethod.TOTP,
 });
 
-// Get user credentials
-const creds = await client.getUserCredentials("user@example.com");
-console.log(`MFA method: ${creds.mfa_method}`);
+// Change MFA method
+const result = await client.mfa.initiate({
+  userId: 'user@example.com',
+  mfaMethod: MfaMethod.EMAIL,   // Current method for verification
+  mfaChangeTo: MfaMethod.TOTP,  // New method to switch to
+});
 ```
 
-**What it does automatically**: ECIES encryption, Ed25519 signatures, request/response crypto, Hawcx payload formatting, type-safe `MfaMethod` enum
+**MFA Methods:**
+```typescript
+enum MfaMethod {
+  EMAIL = 'email',
+  SMS = 'sms',
+  TOTP = 'totp',
+}
+```
 
-## Demo App
+#### `client.mfa.verify(options): Promise<object>`
 
-A simple demo application is included to show the OAuth and delegation flows in action:
+Verify MFA setup with OTP.
 
-```bash
-cd demo
-cp env.template .env
-# Edit .env with your credentials
-npm install
-npm run dev
-# Visit http://localhost:3000
+```typescript
+const result = await client.mfa.verify({
+  userId: 'user@example.com',
+  sessionId: 'session-from-initiate',
+  otp: '123456',  // 6-digit code
+});
 ```
 
-See [demo/README.md](demo/README.md) for details.
+### User Operations
 
-## Configuration
+#### `client.users.getCredentials(userId): Promise<object>`
 
-### Environment Variables
+Get user credentials/metadata.
 
-**For OAuth Code Exchange:**
-```bash
-OAUTH_TOKEN_ENDPOINT="https://oauth.example.com/token"
-OAUTH_CLIENT_ID="your-client-id"
-OAUTH_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."
-OAUTH_ISSUER="https://oauth.example.com"  # Optional but recommended
-OAUTH_AUDIENCE="your-client-id"  # Optional but recommended
+```typescript
+const creds = await client.users.getCredentials('user@example.com');
+console.log(creds.mfa_method);
 ```
 
-**For Hawcx Delegation:**
-```bash
-SP_ED25519_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----..."
-SP_X25519_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----..."
-IDP_ED25519_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----..."
-IDP_X25519_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----..."
+### Device Operations
+
+#### `client.devices.list(userId): Promise<object>`
+
+List all devices for a user.
+
+```typescript
+const { devices } = await client.devices.list('user@example.com');
 ```
 
-### Public Key Formats
+#### `client.devices.revoke(options): Promise<object>`
 
-The SDK accepts public keys in multiple formats:
+Revoke a device (block it from authenticating).
 
-**From file:**
 ```typescript
-const claims = await exchangeCodeForClaims({
-  // ...
-  apiKey: process.env.HAWCX_API_KEY!,
-  publicKey: '/path/to/public.pem'  // Absolute path
+await client.devices.revoke({
+  userId: 'user@example.com',
+  deviceId: 'device-h2index',
 });
 ```
 
-**From environment variable:**
+#### `client.devices.unrevoke(options): Promise<object>`
+
+Unrevoke a previously revoked device.
+
+```typescript
+await client.devices.unrevoke({
+  userId: 'user@example.com',
+  deviceId: 'device-h2index',
+});
+```
+
+#### `client.devices.delete(options): Promise<object>`
+
+Permanently delete a device.
+
 ```typescript
-const claims = await exchangeCodeForClaims({
-  // ...
-  apiKey: process.env.HAWCX_API_KEY!,
-  publicKey: process.env.OAUTH_PUBLIC_KEY!  // PEM string
+await client.devices.delete({
+  userId: 'user@example.com',
+  deviceId: 'device-h2index',
 });
 ```
 
-**Expected PEM format:**
+### Generic Request
+
+#### `client.request<TReq, TRes>(options): Promise<TRes>`
+
+Send a custom encrypted request to any delegation endpoint.
+
+```typescript
+const result = await client.request({
+  endpoint: '/hc_auth/v5/custom/endpoint',
+  payload: { userid: 'user@example.com', custom_field: 'value' },
+  headers: { 'X-Custom-Header': 'value' },
+  includeBaseUrl: true,  // Optional (default: true)
+});
 ```
------BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
------END PUBLIC KEY-----
+
+### Credential Utilities
+
+#### `parseHawcxSecretKey(secretKey): ParsedCredentials`
+
+Parse a secret key into usable key material (advanced usage).
+
+```typescript
+import { parseHawcxSecretKey } from '@hawcx/oauth-client';
+
+const creds = parseHawcxSecretKey(process.env.HAWCX_SECRET_KEY!);
+// Returns: { kid, hkid, signingKeyPem, verifyKeyPem, encryptKeyPem, decryptKeyPem }
 ```
 
-## Error Handling
+#### `generateCredentialBlob(options): string`
+
+Generate a new credential blob (for admin tooling).
+
+```typescript
+import { generateCredentialBlob } from '@hawcx/oauth-client';
+
+const secretKey = generateCredentialBlob({
+  kid: 'customer-key-id',
+  hkid: 'hawcx-key-id',
+  edPrivate: Buffer.alloc(32),     // Ed25519 private key (32 bytes)
+  xPrivate: Buffer.alloc(32),      // X25519 private key (32 bytes)
+  hawcxEdPublic: Buffer.alloc(32), // Hawcx Ed25519 public key (32 bytes)
+  hawcxXPublic: Buffer.alloc(32),  // Hawcx X25519 public key (32 bytes)
+});
+// Returns: "hwx_sk_v1_<base64url>"
+```
 
-The SDK provides specific exceptions for different failure scenarios:
+### Delegation Errors
 
 ```typescript
 import {
-  exchangeCodeForClaims,
-  OAuthExchangeError,
-  JWTVerificationError,
-  InvalidPublicKeyError
+  DelegationError,         // Base delegation error
+  DelegationCryptoError,   // Encryption/signing failed
+  DelegationRequestError,  // Request to IDP failed
+  DelegationResponseError, // Invalid response from IDP
 } from '@hawcx/oauth-client';
 
 try {
-  const claims = await exchangeCodeForClaims({
-    code,
-    oauthTokenUrl,
-    clientId,
-    apiKey,
-    publicKey
-  });
+  await client.mfa.initiate({ userId: 'user@example.com', mfaMethod: MfaMethod.EMAIL });
 } catch (error) {
-  if (error instanceof OAuthExchangeError) {
-    // Code exchange failed (invalid code, network error, etc.)
-    console.error(`Exchange failed: ${error.message}`);
-    console.error(`HTTP Status: ${error.statusCode}`);
-    console.error(`Response: ${error.responseBody}`);
-  } else if (error instanceof JWTVerificationError) {
-    // JWT verification failed (invalid signature, expired, etc.)
-    console.error(`Verification failed: ${error.message}`);
-    console.error(`Original error: ${error.originalError}`);
-  } else if (error instanceof InvalidPublicKeyError) {
-    // Public key is invalid or unreadable
-    console.error(`Key error: ${error.message}`);
+  if (error instanceof DelegationRequestError) {
+    console.log(error.statusCode);   // HTTP status
+    console.log(error.responseBody); // Response body
   }
 }
 ```
 
-### Common Error Scenarios
-
-| Exception | Common Causes | Recommended Action |
-|-----------|--------------|-------------------|
-| `OAuthExchangeError` | Invalid/expired code, network issues | Ask user to re-authenticate |
-| `JWTVerificationError` | Token tampering, expired token | Log incident, ask user to re-authenticate |
-| `InvalidPublicKeyError` | Wrong key, file not found | Check configuration, verify key format |
+---
 
-## Security Best Practices
+## Step-Up Module
 
-### ✅ DO
+For step-up authentication flows (e.g., changing MFA method requires re-authentication).
 
-- **Always validate audience and issuer** in production environments
-- **Use HTTPS** for all OAuth endpoints
-- **Store keys securely** (environment variables, secrets manager)
-- **Set appropriate leeway** for clock skew (5-10 seconds typical)
-- **Log authentication failures** for security monitoring
-- **Rotate keys regularly** following your security policy
+### `StepUpClient`
 
-### ❌ DON'T
+```typescript
+import { StepUpClient } from '@hawcx/oauth-client';
+
+const stepUp = StepUpClient.fromSecretKey({
+  baseUrl: 'https://api.hawcx.com',
+  secretKey: process.env.HAWCX_SECRET_KEY!,
+  relyingParty: 'your-app.com',       // Required
+  apiKey: 'optional-api-key',          // Optional
+  apiPrefix: '/v1',                    // Optional (default: '/v1')
+  timeoutSeconds: 15,                  // Optional
+  clockSkewSeconds: 300,               // Optional
+});
+```
 
-- **Never log JWT tokens** or claims containing sensitive data
-- **Don't disable signature verification** in production
-- **Don't use the id_token as your application's access token** (mint your own)
-- **Don't commit keys** to version control
-- **Don't ignore verification errors** or catch them silently
+### Methods
 
-## API Reference
+#### `stepUp.startToken(options): Promise<StepUpStartTokenResponse>`
 
-### `exchangeCodeForClaims()`
+Start a step-up authentication flow.
 
 ```typescript
-async function exchangeCodeForClaims(
-  options: ExchangeCodeOptions
-): Promise<Record<string, any>>
+const { start_token, expires_in } = await stepUp.startToken({
+  userId: 'user@example.com',
+  purpose: 'change_mfa_method',
+  newMfaMethod: 'totp',  // 'email_otp' | 'sms_otp' | 'totp'
+});
+// Send start_token to client for step-up authentication
 ```
 
-**Parameters:**
-- `code` (string): Authorization code from OAuth flow
-- `oauthTokenUrl` (string): Token endpoint URL
-- `clientId` (string): OAuth client identifier
-- `apiKey` (string): API key for Hawcx OAuth
-- `publicKey` (string, optional): RS256 public key (PEM string or file path) - optional if jwksUrl provided
-- `jwksUrl` (string, optional): JWKS URL for dynamic key fetching (alternative to publicKey)
-- `codeVerifier` (string, optional): PKCE code verifier (RFC 7636)
-- `redirectUri` (string, optional): OAuth redirect URI
-- `timeout` (number, optional): Request timeout in seconds (default: 20)
-- `audience` (string, optional): Expected 'aud' claim (recommended)
-- `issuer` (string, optional): Expected 'iss' claim (recommended)
-- `verifyExp` (boolean, optional): Verify token expiration (default: true)
-- `leeway` (number, optional): Clock skew tolerance in seconds (default: 0)
-- `algorithms` (string[], optional): Allowed signing algorithms (default: RS256, ES256/384/512, EdDSA)
+#### `stepUp.consumeReceipt(options): Promise<StepUpConsumeResponse>`
 
-**Returns:** `Promise<Record<string, any>>` - Verified JWT claims
+Consume a step-up receipt after user completes authentication.
 
-**Throws:**
-- `OAuthExchangeError`: Code exchange failed
-- `JWTVerificationError`: JWT verification failed
-- `InvalidPublicKeyError`: Public key invalid
+```typescript
+const { ok } = await stepUp.consumeReceipt({
+  receipt: 'step-up-receipt-from-client',
+});
+
+if (ok) {
+  // Step-up verified, proceed with sensitive operation
+}
+```
 
-### `verifyJwt()`
+### Types
 
 ```typescript
-function verifyJwt(
-  options: VerifyJwtOptions
-): Record<string, any>
+type StepUpPurpose = 'change_mfa_method';
+
+type HxAuthMfaMethod = 'sms_otp' | 'email_otp' | 'totp';
+
+interface StepUpStartTokenResponse {
+  start_token: string;
+  expires_in: number;
+}
+
+interface StepUpConsumeResponse {
+  ok: boolean;
+}
 ```
 
-Verify a JWT and return its claims. See full documentation in [API.md](./API.md).
+---
+
+## Examples
+
+### Next.js Auth Callback
 
-### HawcxDelegationClient
+```typescript
+// app/api/auth/callback/route.ts
+import { HawcxOAuth, TokenExchangeError } from '@hawcx/oauth-client';
+import { cookies } from 'next/headers';
+
+const oauth = new HawcxOAuth({
+  configId: process.env.HAWCX_CONFIG_ID!,
+});
 
-See [DELEGATION.md](./DELEGATION.md) for full Hawcx delegation client documentation.
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const code = url.searchParams.get('code');
 
-## TypeScript Support
+  const cookieStore = cookies();
+  const codeVerifier = cookieStore.get('code_verifier')?.value;
 
-This package is written in TypeScript and includes full type definitions:
+  if (!code || !codeVerifier) {
+    return Response.redirect('/login?error=missing_params');
+  }
+
+  try {
+    const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
+    // Create session with claims.sub, claims.email, etc.
+    return Response.redirect('/dashboard');
+  } catch (error) {
+    if (error instanceof TokenExchangeError) {
+      console.error('Token exchange failed:', error.message);
+    }
+    return Response.redirect('/login?error=auth_failed');
+  }
+}
+```
+
+### Admin MFA Management
 
 ```typescript
-import type {
-  ExchangeCodeOptions,
-  VerifyJwtOptions
-} from '@hawcx/oauth-client';
+import { DelegationClient, MfaMethod } from '@hawcx/oauth-client';
+
+const admin = DelegationClient.fromSecretKey({
+  baseUrl: process.env.HAWCX_API_URL!,
+  secretKey: process.env.HAWCX_SECRET_KEY!,
+});
+
+// Reset user MFA to email
+async function resetUserMfa(userId: string, otp: string) {
+  const initResult = await admin.mfa.initiate({
+    userId,
+    mfaMethod: MfaMethod.EMAIL,
+  });
+
+  const verifyResult = await admin.mfa.verify({
+    userId,
+    sessionId: initResult.session_id,
+    otp,
+  });
+
+  return verifyResult;
+}
 
-// All options are fully typed
-const options: ExchangeCodeOptions = {
-  code: 'abc123',
-  oauthTokenUrl: 'https://oauth.example.com/token',
-  clientId: 'my-app',
-  publicKey: process.env.OAUTH_PUBLIC_KEY!,
-  audience: 'my-app',  // TypeScript will catch typos!
-};
+// Revoke all user devices
+async function revokeAllDevices(userId: string) {
+  const { devices } = await admin.devices.list(userId);
+
+  for (const device of devices) {
+    await admin.devices.revoke({
+      userId,
+      deviceId: device.h2index,
+    });
+  }
+}
 ```
 
-## Development
+### Step-Up for MFA Change
 
-### Building
+```typescript
+import { StepUpClient, DelegationClient, MfaMethod } from '@hawcx/oauth-client';
 
-```bash
-npm install
-npm run build
+const stepUp = StepUpClient.fromSecretKey({
+  baseUrl: process.env.HAWCX_API_URL!,
+  secretKey: process.env.HAWCX_SECRET_KEY!,
+  relyingParty: 'myapp.com',
+});
+
+const delegation = DelegationClient.fromSecretKey({
+  baseUrl: process.env.HAWCX_API_URL!,
+  secretKey: process.env.HAWCX_SECRET_KEY!,
+});
+
+async function changeMfaMethod(userId: string, newMethod: 'totp' | 'sms_otp' | 'email_otp') {
+  // 1. Start step-up flow
+  const { start_token } = await stepUp.startToken({
+    userId,
+    purpose: 'change_mfa_method',
+    newMfaMethod: newMethod,
+  });
+
+  // 2. Send start_token to client, user completes step-up auth
+  // 3. Client sends back receipt
+
+  // 4. Verify step-up receipt
+  const { ok } = await stepUp.consumeReceipt({ receipt: 'receipt-from-client' });
+
+  if (!ok) {
+    throw new Error('Step-up verification failed');
+  }
+
+  // 5. Now safe to change MFA
+  await delegation.mfa.initiate({
+    userId,
+    mfaMethod: MfaMethod.EMAIL,
+    mfaChangeTo: newMethod,
+  });
+}
 ```
 
-### Testing
+---
 
-```bash
-npm test
-npm run test:coverage
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HAWCX_CONFIG_ID` | Your Hawcx OAuth config ID (for token verification) |
+| `HAWCX_SECRET_KEY` | Your Hawcx secret key (for delegation/step-up APIs) |
+| `HAWCX_API_URL` | API base URL (default: `https://api.hawcx.com`) |
+
+### Secret Key Format
+
+The `HAWCX_SECRET_KEY` is a compact credential blob:
+
+```
+hwx_sk_v1_<base64url-encoded-json>
 ```
 
-### Linting
+It contains:
+- Your Ed25519 signing key (for request authentication)
+- Your X25519 decryption key (for response decryption)
+- Hawcx's Ed25519 public key (for response verification)
+- Hawcx's X25519 public key (for request encryption)
+- Key IDs for rotation tracking
 
-```bash
-npm run lint
-npm run format
+Generate via the Hawcx Dashboard or admin tools.
+
+---
+
+## JWKS Caching
+
+The SDK automatically caches JWKS (JSON Web Key Set) for JWT verification:
+
+- Keys are fetched lazily on first `verifyToken()` call
+- Cached in memory for the lifetime of the `HawcxOAuth` instance
+- Auto-refreshes if a key ID isn't found (handles key rotation)
+- Call `refreshJwks()` to force a refresh (`clearCache()` is a deprecated alias — see above)
+
+```typescript
+// Keys fetched once, cached thereafter
+const claims1 = await oauth.verifyToken(token1); // Fetches JWKS
+const claims2 = await oauth.verifyToken(token2); // Uses cache
+const claims3 = await oauth.verifyToken(token3); // Uses cache
+
+// Force refresh if needed
+oauth.refreshJwks();
+const claims4 = await oauth.verifyToken(token4); // Fetches JWKS again
 ```
+
+---
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## License
+
+MIT