postex-auth-sdk-stage 1.0.0 → 1.0.2

package/README.md

@@ -1,80 +1,650 @@
-# PostEx Auth SDK
+# PostEx Authentication SDK
 
-PostEx Auth SDK for authentication flows: OTP, magic links, passkeys (WebAuthn), and token management. Use it in any frontend project via NPM or CDN.
+## Developer Documentation
+
+---
+
+## Overview
+
+The PostEx Authentication SDK provides a comprehensive solution for implementing secure authentication in web applications. It supports multiple authentication methods including:
+
+- WebAuthn/Passkeys for passwordless authentication
+- One-Time Password (OTP) verification
+- Magic link authentication
+- DPoP (Demonstration of Proof-of-Possession) for enhanced security
+
+### Key Features
+
+- **Multi-factor authentication:** Support for passkeys, OTP, and magic links
+- **DPoP security:** RFC 9449 compliant token binding using ECDSA P-256
+- **Token management:** Automatic token storage, refresh, and cleanup
+- **Trusted device support:** Cookie-based device recognition
+- **Browser compatibility:** Built-in feature detection and fallbacks
+
+---
 
 ## Installation
 
-### NPM
+Install the SDK via npm:
 
 ```bash
-npm install postex-auth-sdk
+npm install postex-auth-sdk-stage
+```
+
+---
+
+## Quick Start
+
+### Initialize the SDK
+
+```javascript
+import { AuthSDK } from 'postex-auth-sdk-stage';
+
+const auth = new AuthSDK({ apiKey: 'your-api-key' });
+```
+
+### Basic Authentication Flow
+
+```javascript
+// 1. Check authentication status
+const status = await auth.getStatus('user@example.com');
+
+// 2. Initiate authentication
+const result = await auth.initiateAuth('user@example.com');
+
+// 3. Handle authentication based on status
+if (result.status === 'webauthn_challenge') {
+  // Use passkey authentication
+  const authResponse = await auth.authenticateWithPasskey({
+    challenge: result.challenge,
+    rp: result.rp,
+    credentialIds: result.credentialIds
+  });
+} else if (result.status === 'otp_sent') {
+  // Verify OTP code
+  const response = await auth.verifyOTP(otpCode);
+}
+```
+
+---
+
+## API Reference
+
+### AuthSDK Class
+
+The main class for interacting with the authentication service.
+
+#### Constructor
+
+```typescript
+new AuthSDK(config: AuthSDKConfig)
+```
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `config.apiKey` | (Optional) Your API key for authentication |
+
+---
+
+### Core Authentication Methods
+
+#### getStatus()
+
+Check if the client has a trusted device session and what authentication method is available.
+
+```typescript
+async getStatus(email: string): Promise<AuthStatusResponse>
 ```
 
-### CDN (jsDelivr)
+**Returns:**
+
+- `status`: `'no_session'` | `'session_found'` | `'webauthn_ready'`
+- `email`: User's email address
+- `webauthn`: Whether WebAuthn is available
+- `challenge`, `credentialIds`, `rp`: WebAuthn challenge data if available
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
+---
+
+#### initiateAuth()
+
+Start the authentication process. Returns either a WebAuthn challenge or confirms OTP was sent.
+
+```typescript
+async initiateAuth(email: string): Promise<InitiateAuthResponse>
 ```
 
-### CDN (unpkg)
+**Returns:**
+
+- `status`: `'webauthn_challenge'` | `'otp_sent'`
+- `challenge`, `credentialIds`, `rp`: WebAuthn data if status is `'webauthn_challenge'`
+
+---
+
+#### verifyOTP()
+
+Verify the OTP code entered by the user. Automatically stores tokens on success.
 
-```html
-<script src="https://unpkg.com/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
+```typescript
+async verifyOTP(otp: string): Promise<OTPVerifyResponse>
 ```
 
-Use a specific version for production (e.g. `@1.0.0` instead of `@1`).
+**Returns:**
+
+- `access_token`: Bearer token for API requests
+- `refresh_token`: Token for refreshing access
+- `id_token`: User identity token
+- `expires_in`: Token expiration time in seconds
+- `verified`, `email`: Verification status and user email
+
+---
+
+### WebAuthn/Passkey Methods
+
+#### registerPasskey()
+
+Register a new passkey for the user. This enables passwordless authentication.
+
+```typescript
+async registerPasskey(email: string): Promise<PasskeyRegisterResponse>
+```
+
+**Process:**
+
+- Initiates passkey registration challenge
+- Triggers browser's passkey creation flow
+- Automatically prevents duplicate registration
+- Returns registration confirmation
+
+---
+
+#### authenticateWithPasskey()
+
+Authenticate using a registered passkey. Automatically stores tokens on success.
+
+```typescript
+async authenticateWithPasskey({
+  challenge: string,
+  rp: { name: string; host: string },
+  credentialIds: string[]
+}): Promise<AuthResponse>
+```
 
-## Usage
+**Parameters:**
 
-### Via CDN (script tag)
+- `challenge`: WebAuthn challenge from `initiateAuth()`
+- `rp`: Relying party information
+- `credentialIds`: List of allowed credential IDs
 
-After loading the script, the SDK is available on the global `PostexAuthSDK` object:
+---
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
-<script>
-  const { AuthSDK, WebAuthn } = PostexAuthSDK;
-  const sdk = new AuthSDK({ apiKey: "your-api-key" });
+#### getPasskeyStatus()
 
-  // Check auth status
-  const status = await sdk.getStatus("user@example.com");
+Check if a user has registered passkeys.
 
-  // Initiate auth (OTP or WebAuthn)
-  const result = await sdk.initiateAuth("user@example.com");
-  if (result.status === "webauthn_challenge") {
-    const authResult = await sdk.authenticateWithPasskey({
-      challenge: result.challenge,
-      rp: result.rp,
-      credentialIds: result.credentialIds || [],
-    });
-  } else if (result.status === "otp_sent") {
-    const verified = await sdk.verifyOTP("123456");
+```typescript
+async getPasskeyStatus(username: string): Promise<PasskeyStatusResponse>
+```
+
+**Returns:**
+
+- `hasCredentials`: Boolean indicating if user has passkeys
+- `credentialId`: The credential ID if available
+
+---
+
+#### removePasskey()
+
+Remove a user's registered passkey.
+
+```typescript
+async removePasskey(username: string): Promise<void>
+```
+
+---
+
+### Magic Link Methods
+
+#### verifyMagicLink()
+
+Verify a magic link token. This sets the authentication session cookie.
+
+```typescript
+async verifyMagicLink(token: string, email: string): Promise<void>
+```
+
+---
+
+#### completeMagicLink()
+
+Complete magic link authentication. Must be called after `verifyMagicLink()`. Automatically stores tokens.
+
+```typescript
+async completeMagicLink(): Promise<OTPVerifyResponse>
+```
+
+---
+
+### Token Management Methods
+
+#### refreshToken()
+
+Refresh the access token using the server-stored refresh token. Requires a trusted device cookie. Rate limited to 10 requests per minute.
+
+```typescript
+async refreshToken(): Promise<RefreshTokenResponse>
+```
+
+**Returns:**
+
+- `access_token`: New access token
+- `id_token`: New ID token
+- `expires_in`: Token expiration time
+
+---
+
+#### getAccessToken()
+
+Retrieve the stored access token.
+
+```typescript
+async getAccessToken(): Promise<string | null>
+```
+
+---
+
+#### logout()
+
+Log out from the current device. Revokes the current token and trusted device, then clears local tokens and DPoP keys.
+
+```typescript
+async logout(): Promise<void>
+```
+
+---
+
+### DPoP (Proof-of-Possession) Methods
+
+DPoP provides enhanced security by binding tokens to cryptographic keys. The SDK implements RFC 9449 using ECDSA P-256.
+
+#### getRequestAuthHeaders()
+
+Get authentication headers (Authorization + DPoP) for a request. Use this to attach auth to your own HTTP client.
+
+```typescript
+async getRequestAuthHeaders(
+  method: string,
+  url: string
+): Promise<Record<string, string>>
+```
+
+**Example:**
+
+```javascript
+const headers = await auth.getRequestAuthHeaders('GET', '/api/user');
+// headers = { Authorization: 'Bearer ...', DPoP: '...' }
+```
+
+---
+
+#### authenticatedFetch()
+
+Drop-in replacement for `fetch()` that automatically includes DPoP authentication headers.
+
+```typescript
+async authenticatedFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): Promise<Response>
+```
+
+**Example:**
+
+```javascript
+const response = await auth.authenticatedFetch('/api/protected', {
+  method: 'POST',
+  body: JSON.stringify({ data: 'value' })
+});
+```
+
+---
+
+## WebAuthn Utility Functions
+
+The webauthn module provides utility functions for WebAuthn support detection, data encoding, and passkey email management.
+
+### Browser Support Detection
+
+#### isWebAuthnSupported()
+
+Check if the browser supports WebAuthn.
+
+```typescript
+function isWebAuthnSupported(): boolean
+```
+
+---
+
+#### isConditionalUISupported()
+
+Check if conditional UI (autofill passkeys) is supported.
+
+```typescript
+async function isConditionalUISupported(): Promise<boolean>
+```
+
+---
+
+### Encoding Functions
+
+Functions for converting between ArrayBuffer and base64 formats.
+
+```typescript
+// Convert ArrayBuffer to base64
+function arrayBufferToBase64(buffer: ArrayBuffer): string
+
+// Convert base64 to ArrayBuffer
+function base64ToArrayBuffer(base64: string): ArrayBuffer
+
+// Convert ArrayBuffer to base64url (URL-safe)
+function arrayBufferToBase64url(buffer: ArrayBuffer): string
+
+// Convert string to ArrayBuffer
+function stringToArrayBuffer(str: string): ArrayBuffer
+```
+
+---
+
+### Passkey Email Management
+
+Functions for storing and retrieving the passkey email in IndexedDB.
+
+```typescript
+// Store passkey email
+async function setPasskeyEmail(email: string): Promise<void>
+
+// Retrieve passkey email
+async function getPasskeyEmail(): Promise<string | null>
+
+// Clear stored passkey email
+async function clearPasskeyEmail(): Promise<void>
+```
+
+---
+
+### DPoP Utility Functions
+
+Low-level DPoP functions. Most developers won't need these as they're handled automatically by the SDK.
+
+```typescript
+// Generate DPoP key pair
+async function generateDPoPKeyPair(): Promise<{
+  publicKey: MinimalECPublicKeyJWK;
+  thumbprint: string;
+}>
+
+// Generate DPoP proof JWT
+async function generateDPoPProof(
+  httpMethod: string,
+  httpUri: string,
+  accessToken?: string
+): Promise<string | null>
+
+// Check if DPoP is enabled
+async function isDPoPEnabled(): Promise<boolean>
+
+// Clear DPoP keys
+async function clearDPoPKey(): Promise<void>
+```
+
+---
+
+## Complete Examples
+
+### Passkey Registration Flow
+
+```javascript
+import { AuthSDK, isWebAuthnSupported } from 'postex-auth-sdk-stage';
+
+async function registerUserPasskey(email: string) {
+  // Check browser support
+  if (!isWebAuthnSupported()) {
+    alert('Passkeys not supported in this browser');
+    return;
+  }
+
+  const auth = new AuthSDK({ apiKey: 'your-api-key' });
+
+  try {
+    // Register passkey
+    const result = await auth.registerPasskey(email);
+
+    if (result.registered) {
+      console.log('Passkey registered successfully');
+    }
+  } catch (error) {
+    console.error('Passkey registration failed:', error);
+  }
+}
+```
+
+---
+
+### OTP Authentication Flow
+
+```javascript
+import { AuthSDK } from 'postex-auth-sdk-stage';
+
+async function loginWithOTP(email: string, otpCode: string) {
+  const auth = new AuthSDK({ apiKey: 'your-api-key' });
+
+  try {
+    // Initiate authentication
+    const initResult = await auth.initiateAuth(email);
+
+    if (initResult.status !== 'otp_sent') {
+      throw new Error('Expected OTP to be sent');
+    }
+
+    // Verify OTP
+    const verifyResult = await auth.verifyOTP(otpCode);
+
+    if (verifyResult.verified) {
+      console.log('Authentication successful');
+      console.log('Access token:', verifyResult.access_token);
+    }
+  } catch (error) {
+    console.error('Authentication failed:', error);
   }
-</script>
+}
 ```
 
-### Via NPM (ESM)
+---
+
+### Magic Link Authentication Flow
 
 ```javascript
-import { AuthSDK, WebAuthn, AuthSDKFetchError } from "postex-auth-sdk";
+import { AuthSDK } from 'postex-auth-sdk-stage';
+
+async function handleMagicLink(token: string, email: string) {
+  const auth = new AuthSDK({ apiKey: 'your-api-key' });
 
-const sdk = new AuthSDK({ apiKey: "your-api-key" });
+  try {
+    // Step 1: Verify the magic link token
+    await auth.verifyMagicLink(token, email);
 
-// Use SDK methods
-const status = await sdk.getStatus("user@example.com");
+    // Step 2: Complete authentication
+    const result = await auth.completeMagicLink();
+
+    console.log('Magic link authentication successful');
+    console.log('Access token:', result.access_token);
+  } catch (error) {
+    console.error('Magic link authentication failed:', error);
+  }
+}
 ```
 
-### WebAuthn utilities
+---
+
+### Making Authenticated API Requests
 
 ```javascript
-import { WebAuthn } from "postex-auth-sdk";
+import { AuthSDK } from 'postex-auth-sdk-stage';
+
+const auth = new AuthSDK({ apiKey: 'your-api-key' });
+
+// Option 1: Use authenticatedFetch (recommended)
+const response1 = await auth.authenticatedFetch('/api/user/profile');
+const userData = await response1.json();
+
+// Option 2: Get headers for your own HTTP client
+const headers = await auth.getRequestAuthHeaders(
+  'POST',
+  'https://api.example.com/data'
+);
+
+const response2 = await fetch('https://api.example.com/data', {
+  method: 'POST',
+  headers: {
+    ...headers,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ key: 'value' })
+});
+```
+
+---
+
+## Error Handling
 
-if (WebAuthn.isWebAuthnSupported()) {
-  const conditionalUI = await WebAuthn.isConditionalUISupported();
-  // ...
+The SDK throws `AuthSDKFetchError` for HTTP errors. This error includes the status code and response data.
+
+```javascript
+import { AuthSDK, AuthSDKFetchError } from 'postex-auth-sdk-stage';
+
+try {
+  await auth.verifyOTP(otpCode);
+} catch (error) {
+  if (error instanceof AuthSDKFetchError) {
+    console.error('Status:', error.response.status);
+    console.error('Data:', error.response.data);
+
+    if (error.response.status === 401) {
+      // Token expired - attempt refresh
+      try {
+        await auth.refreshToken();
+      } catch (refreshError) {
+        // Refresh failed - redirect to login
+        window.location.href = '/login';
+      }
+    }
+  }
 }
 ```
 
+---
+
+## Security Considerations
+
+### DPoP Token Binding
+
+The SDK automatically implements DPoP (RFC 9449) to bind tokens to cryptographic keys. This prevents token theft and replay attacks. DPoP keys are:
+
+- Generated using ECDSA P-256 (ES256)
+- Stored securely in IndexedDB
+- Non-extractable (private key cannot be exported)
+- Automatically included in all authenticated requests
+
+---
+
+### Token Storage
+
+Tokens are stored in localStorage with the following keys:
+
+- `postex-auth-token`: Access token
+- `auth_sdk_refresh_token`: Refresh token
+- `auth_sdk_id_token`: ID token
+
+---
+
+### Trusted Device Cookies
+
+The backend sets a secure, HTTP-only cookie (`td`) to identify trusted devices. This enables:
+
+- Token refresh without re-authentication
+- Session persistence across page reloads
+- Device-specific security policies
+
+---
+
+### Best Practices
+
+- **Always use HTTPS:** The SDK requires secure contexts for WebAuthn and cryptographic operations
+- **Handle token expiration:** Implement automatic token refresh before expiration
+- **Clear tokens on logout:** Always call `auth.logout()` when users sign out
+- **Validate on backend:** Never trust client-side authentication alone
+- **Monitor 401 errors:** The SDK automatically clears tokens on 401 responses
+
+---
+
+## Browser Compatibility
+
+### WebAuthn Support
+
+WebAuthn/Passkeys are supported in:
+
+- Chrome/Edge 67+
+- Firefox 60+
+- Safari 13+
+- Opera 54+
+
+### Fallback Authentication
+
+For browsers without WebAuthn support, the SDK automatically falls back to OTP authentication. Always check browser support before attempting passkey operations:
+
+```javascript
+import { isWebAuthnSupported } from 'postex-auth-sdk-stage';
+
+if (isWebAuthnSupported()) {
+  // Offer passkey registration/authentication
+} else {
+  // Use OTP or magic link
+}
+```
+
+---
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions. All interfaces are exported for your convenience:
+
+```typescript
+import {
+  AuthSDK,
+  AuthSDKConfig,
+  AuthStatusResponse,
+  InitiateAuthResponse,
+  OTPVerifyResponse,
+  AuthResponse,
+  PasskeyRegisterResponse,
+  PasskeyStatusResponse,
+  RefreshTokenResponse,
+  AuthSDKFetchError
+} from 'postex-auth-sdk-stage';
+```
+
+---
+
+## Support and Resources
+
+- **API Documentation:** https://auth-stage.postexglobal.com/docs
+- **GitHub Repository:** (Add your repository link)
+- **Issue Tracker:** (Add your issue tracker link)
+- **Email Support:** (Add your support email)
+
+---
+
 ## API overview
 
 - **AuthSDK** – Main client: `getStatus`, `initiateAuth`, `verifyOTP`, `verifyMagicLink`, `completeMagicLink`, `authenticateWithPasskey`, `registerPasskey`, `getPasskeyStatus`, `removePasskey`, `getRequestAuthHeaders`, `authenticatedFetch`, `refreshToken`, `logout`, `getAccessToken`, `storeTokens`, `clearTokens`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postex-auth-sdk-stage",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "PostEx Auth SDK for authentication flows: OTP, magic links, passkeys, and token management",
   "main": "./dist/postex-auth-sdk-stage.umd.js",
   "module": "./dist/postex-auth-sdk-stage.es.js",