@hawcx/oauth-client 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Hawcx
+
+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,304 @@
+# Hawcx OAuth Client SDK (Node.js)
+
+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.
+
+## 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)
+
+## Installation
+
+```bash
+npm install @hawcx/oauth-client
+
+# or with yarn
+yarn add @hawcx/oauth-client
+
+# or with pnpm
+pnpm add @hawcx/oauth-client
+```
+
+## Quick Start
+
+### OAuth Code Exchange
+
+```typescript
+import { exchangeCodeForClaims } from '@hawcx/oauth-client';
+
+// 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!,
+  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
+});
+
+// Use the verified claims
+const userId = claims.sub;
+// Mint your own access token (SDK only verifies, doesn't mint)
+```
+
+### Hawcx Delegation (MFA Setup)
+
+For Hawcx MFA setup and user management, use the delegation client:
+
+```typescript
+import { HawcxDelegationClient, MfaMethod } from '@hawcx/oauth-client';
+
+// 🎉 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://ceasar-api.hawcx.com',
+  spId: process.env.OAUTH_CLIENT_ID!
+});
+
+// Initiate MFA setup (Email, SMS, or TOTP)
+const result = await client.initiateMfaChange({
+  userid: "user@example.com",
+  mfaMethod: MfaMethod.SMS, 
+  phoneNumber: "+15551234567"
+});
+
+// Verify OTP and complete MFA setup
+await client.verifyMfaChange({
+  userid: "user@example.com",
+  sessionId: result.session_id,
+  otp: "123456"
+});
+
+// Get user credentials
+const creds = await client.getUserCredentials("user@example.com");
+console.log(`MFA method: ${creds.mfa_method}`);
+```
+
+**What it does automatically**: ECIES encryption, Ed25519 signatures, request/response crypto, Hawcx payload formatting, type-safe `MfaMethod` enum
+
+## Demo App
+
+A simple demo application is included to show the OAuth and delegation flows in action:
+
+```bash
+cd demo
+cp env.template .env
+# Edit .env with your credentials
+npm install
+npm run dev
+# Visit http://localhost:3000
+```
+
+See [demo/README.md](demo/README.md) for details.
+
+## Configuration
+
+### Environment Variables
+
+**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
+```
+
+**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-----..."
+```
+
+### Public Key Formats
+
+The SDK accepts public keys in multiple formats:
+
+**From file:**
+```typescript
+const claims = await exchangeCodeForClaims({
+  // ...
+  publicKey: '/path/to/public.pem'  // Absolute path
+});
+```
+
+**From environment variable:**
+```typescript
+const claims = await exchangeCodeForClaims({
+  // ...
+  publicKey: process.env.OAUTH_PUBLIC_KEY!  // PEM string
+});
+```
+
+**Expected PEM format:**
+```
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----
+```
+
+## Error Handling
+
+The SDK provides specific exceptions for different failure scenarios:
+
+```typescript
+import {
+  exchangeCodeForClaims,
+  OAuthExchangeError,
+  JWTVerificationError,
+  InvalidPublicKeyError
+} from '@hawcx/oauth-client';
+
+try {
+  const claims = await exchangeCodeForClaims({
+    code,
+    oauthTokenUrl,
+    clientId,
+    publicKey
+  });
+} 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}`);
+  }
+}
+```
+
+### 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
+
+### ✅ DO
+
+- **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
+
+### ❌ DON'T
+
+- **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
+
+## API Reference
+
+### `exchangeCodeForClaims()`
+
+```typescript
+async function exchangeCodeForClaims(
+  options: ExchangeCodeOptions
+): Promise<Record<string, any>>
+```
+
+**Parameters:**
+- `code` (string): Authorization code from OAuth flow
+- `oauthTokenUrl` (string): Token endpoint URL
+- `clientId` (string): OAuth client identifier
+- `publicKey` (string): RS256 public key (PEM string or file path)
+- `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)
+
+**Returns:** `Promise<Record<string, any>>` - Verified JWT claims
+
+**Throws:**
+- `OAuthExchangeError`: Code exchange failed
+- `JWTVerificationError`: JWT verification failed
+- `InvalidPublicKeyError`: Public key invalid
+
+### `verifyJwt()`
+
+```typescript
+function verifyJwt(
+  options: VerifyJwtOptions
+): Record<string, any>
+```
+
+Verify a JWT and return its claims. See full documentation in [API.md](./API.md).
+
+### HawcxDelegationClient
+
+See [DELEGATION.md](./DELEGATION.md) for full Hawcx delegation client documentation.
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions:
+
+```typescript
+import type {
+  ExchangeCodeOptions,
+  VerifyJwtOptions
+} from '@hawcx/oauth-client';
+
+// 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!
+};
+```
+
+## Development
+
+### Building
+
+```bash
+npm install
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:coverage
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run format
+```

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Core OAuth client implementation
+ */
+/**
+ * Options for exchanging authorization code for claims
+ */
+export interface ExchangeCodeOptions {
+    /** Authorization code from OAuth flow */
+    code: string;
+    /** Token endpoint URL */
+    oauthTokenUrl: string;
+    /** OAuth client identifier */
+    clientId: string;
+    /** Ed25519 public key (PEM string or file path) - optional if jwksUrl provided */
+    publicKey?: string;
+    /** JWKS URL for dynamic key fetching (alternative to publicKey) */
+    jwksUrl?: string;
+    /** API key for OAuth provider (required for Hawcx) */
+    apiKey?: string;
+    /** PKCE code verifier (optional, recommended for security) */
+    codeVerifier?: string;
+    /** OAuth redirect URI (optional, required by some providers) */
+    redirectUri?: string;
+    /** Request timeout in seconds (default: 20) */
+    timeout?: number;
+    /** Expected 'aud' claim (optional but recommended) */
+    audience?: string;
+    /** Expected 'iss' claim (optional but recommended) */
+    issuer?: string;
+    /** Verify token expiration (default: true) */
+    verifyExp?: boolean;
+    /** Clock skew tolerance in seconds (default: 0) */
+    leeway?: number;
+    /** List of allowed signing algorithms (default: RS256, ES256/384/512, EdDSA) */
+    algorithms?: string[];
+}
+/**
+ * Options for verifying JWT tokens
+ */
+export interface VerifyJwtOptions {
+    /** JWT token to verify */
+    token: string;
+    /** Public key for JWT verification (PEM string or file path) - optional if jwksUrl provided */
+    publicKey?: string;
+    /** JWKS URL for dynamic key fetching (alternative to publicKey) */
+    jwksUrl?: string;
+    /** Expected 'aud' claim (optional but recommended) */
+    audience?: string;
+    /** Expected 'iss' claim (optional but recommended) */
+    issuer?: string;
+    /** Verify token expiration (default: true) */
+    verifyExp?: boolean;
+    /** Clock skew tolerance in seconds (default: 0) */
+    leeway?: number;
+    /** List of allowed signing algorithms (default: RS256, ES256/384/512, EdDSA) */
+    algorithms?: string[];
+}
+/**
+ * Exchange OAuth authorization code for verified JWT claims.
+ *
+ * Supports PKCE (Proof Key for Code Exchange) per RFC 7636 for enhanced security.
+ *
+ * @param options - Configuration options for code exchange
+ * @returns Dictionary containing the verified JWT claims
+ * @throws OAuthExchangeError - Code exchange failed
+ * @throws JWTVerificationError - JWT verification failed
+ * @throws InvalidPublicKeyError - Public key invalid
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const claims = await exchangeCodeForClaims({
+ *   code: req.body.code,
+ *   oauthTokenUrl: 'https://oauth.example.com/token',
+ *   clientId: 'my-app',
+ *   publicKey: '/path/to/public.pem'
+ * });
+ *
+ * // With PKCE (recommended)
+ * const claims = await exchangeCodeForClaims({
+ *   code: req.body.code,
+ *   oauthTokenUrl: 'https://oauth.example.com/token',
+ *   clientId: 'my-app',
+ *   publicKey: process.env.OAUTH_PUBLIC_KEY!,
+ *   codeVerifier: session.pkceVerifier,
+ *   redirectUri: 'https://myapp.com/callback',
+ *   audience: 'my-app',
+ *   issuer: 'https://oauth.example.com'
+ * });
+ * ```
+ */
+export declare function exchangeCodeForClaims(options: ExchangeCodeOptions): Promise<Record<string, any>>;
+/**
+ * Exchange OAuth authorization code for verified JWT claims and the raw id_token.
+ *
+ * @param options - Configuration options for code exchange
+ * @returns Tuple containing [claims, idToken]
+ * @throws OAuthExchangeError - Code exchange failed
+ * @throws JWTVerificationError - JWT verification failed
+ * @throws InvalidPublicKeyError - Public key invalid
+ */
+export declare function exchangeCodeForTokenAndClaims(options: ExchangeCodeOptions): Promise<[Record<string, any>, string]>;
+/**
+ * Verify a JWT and return its claims.
+ *
+ * This function verifies the JWT signature using the provided public key
+ * and validates claims (audience, issuer, expiration).
+ *
+ * @param options - Configuration options for JWT verification
+ * @returns Dictionary containing the verified JWT claims
+ * @throws JWTVerificationError - JWT verification failed
+ * @throws InvalidPublicKeyError - Public key invalid
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const claims = verifyJwt({
+ *   token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...',
+ *   publicKey: 'keys/public.pem'
+ * });
+ * console.log(`User: ${claims.sub}`);
+ *
+ * // With validation
+ * const claims = verifyJwt({
+ *   token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...',
+ *   publicKey: process.env.OAUTH_PUBLIC_KEY!,
+ *   audience: 'my-app',
+ *   issuer: 'https://oauth.example.com',
+ *   leeway: 10  // Allow 10 seconds clock skew
+ * });
+ * ```
+ */
+export declare function verifyJwt(options: VerifyJwtOptions): Promise<Record<string, any>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAoED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAgE9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAiDxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAyHvF"}