@ovixa/auth-client 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-01-29
+
+### Added
+
+- **WebAuthn/Passkey authentication support** - Passwordless authentication using FIDO2
+  - `auth.webauthn.getRegistrationOptions(realmId)` - Get options to register a new passkey
+  - `auth.webauthn.verifyRegistration(realmId, registration)` - Complete passkey registration
+  - `auth.webauthn.getAuthenticationOptions(realmId, email?)` - Get options to authenticate with passkey
+  - `auth.webauthn.authenticate(realmId, authentication)` - Authenticate and receive tokens
+  - `auth.webauthn.getCredentials(realmId)` - List user's registered passkeys
+  - `auth.webauthn.deleteCredential(realmId, credentialId)` - Remove a passkey
+  - `auth.webauthn.updateCredentialName(realmId, credentialId, name)` - Rename a passkey
+
+## [0.1.3] - 2026-01-29
+
+### Added
+
+- `auth.exchangeOAuthCode(code)` - Exchange OAuth authorization code for tokens, completing the OAuth 2.0 Authorization Code flow
+
+### Fixed
+
+- OAuth flow now works correctly with the auth server's secure authorization code pattern
+
 ## [0.1.2] - 2026-01-28
 
 ### Added

package/README.md

@@ -5,6 +5,7 @@ Client SDK for the Ovixa Auth service. Provides authentication, token verificati
 ## Features
 
 - Email/password authentication (signup, login, password reset)
+- **Passkey (WebAuthn) authentication** - phishing-resistant passwordless sign-in
 - OAuth integration (Google, GitHub)
 - JWT verification with JWKS caching
 - Automatic token refresh
@@ -141,6 +142,15 @@ await auth.forgotPassword({
 });
 ```
 
+### Email Branding
+
+Verification and password reset emails automatically display your realm's `display_name` as the brand name. To customize the branding in emails:
+
+1. Set `display_name` when creating your realm
+2. Emails will show your brand (e.g., "Linkdrop") instead of "Ovixa"
+
+If no `display_name` is set, emails default to "Ovixa".
+
 #### `resetPassword(options)`
 
 Set a new password using a reset token.
@@ -234,6 +244,109 @@ try {
 }
 ```
 
+### Passkeys (WebAuthn)
+
+Passkeys provide phishing-resistant, passwordless authentication using FIDO2/WebAuthn.
+
+#### `webauthn.getRegistrationOptions(options)`
+
+Get options for registering a new passkey. **Requires authentication.**
+
+```typescript
+const options = await auth.webauthn.getRegistrationOptions({
+  accessToken: 'user-access-token',
+});
+// Returns PublicKeyCredentialCreationOptions for navigator.credentials.create()
+```
+
+#### `webauthn.verifyRegistration(options)`
+
+Verify and store a new passkey registration. **Requires authentication.**
+
+```typescript
+const result = await auth.webauthn.verifyRegistration({
+  accessToken: 'user-access-token',
+  registration: credentialResponse, // From navigator.credentials.create()
+  deviceName: 'My MacBook', // Optional friendly name
+});
+// Returns: { success: true, credential_id: string, device_name?: string }
+```
+
+#### `webauthn.getAuthenticationOptions(options)`
+
+Get options for signing in with a passkey. Does not require authentication.
+
+```typescript
+const options = await auth.webauthn.getAuthenticationOptions({
+  email: 'user@example.com', // Optional - provides allowCredentials hint
+});
+// Returns PublicKeyCredentialRequestOptions for navigator.credentials.get()
+```
+
+#### `webauthn.authenticate(options)`
+
+Verify passkey authentication and receive tokens.
+
+```typescript
+const tokens = await auth.webauthn.authenticate({
+  authentication: credentialResponse, // From navigator.credentials.get()
+});
+// Returns: { access_token, refresh_token, token_type, expires_in }
+```
+
+#### Complete Passkey Flow Example
+
+```typescript
+import { OvixaAuth } from '@ovixa/auth-client';
+
+const auth = new OvixaAuth({
+  authUrl: 'https://auth.ovixa.io',
+  realmId: 'your-realm-id',
+});
+
+// Register a passkey (user must be logged in)
+async function registerPasskey(accessToken: string) {
+  // 1. Get registration options from server
+  const options = await auth.webauthn.getRegistrationOptions({ accessToken });
+
+  // 2. Create credential using browser API
+  const credential = await navigator.credentials.create({
+    publicKey: options,
+  });
+
+  if (!credential) throw new Error('Registration cancelled');
+
+  // 3. Verify with server
+  const result = await auth.webauthn.verifyRegistration({
+    accessToken,
+    registration: credential as PublicKeyCredential,
+    deviceName: 'My Device',
+  });
+
+  return result;
+}
+
+// Sign in with passkey
+async function signInWithPasskey(email?: string) {
+  // 1. Get authentication options
+  const options = await auth.webauthn.getAuthenticationOptions({ email });
+
+  // 2. Get credential using browser API
+  const credential = await navigator.credentials.get({
+    publicKey: options,
+  });
+
+  if (!credential) throw new Error('Authentication cancelled');
+
+  // 3. Verify and get tokens
+  const tokens = await auth.webauthn.authenticate({
+    authentication: credential as PublicKeyCredential,
+  });
+
+  return tokens;
+}
+```
+
 ### OAuth
 
 #### `getOAuthUrl(options)`

package/dist/{chunk-IIOWUPWH.js → chunk-5ZWKDQQM.js}

@@ -415,7 +415,8 @@ var OvixaAuth = class {
    * Generate an OAuth authorization URL.
    *
    * Redirect the user to this URL to start the OAuth flow. After authentication,
-   * the user will be redirected back to your `redirectUri` with tokens.
+   * the user will be redirected back to your `redirectUri` with an authorization code.
+   * Use `exchangeOAuthCode()` to exchange the code for tokens.
    *
    * @param options - OAuth URL options
    * @returns The full OAuth authorization URL
@@ -429,6 +430,10 @@ var OvixaAuth = class {
    *
    * // Redirect user to start OAuth flow
    * window.location.href = googleAuthUrl;
+   *
+   * // In your callback handler:
+   * // const code = new URLSearchParams(window.location.search).get('code');
+   * // const tokens = await auth.exchangeOAuthCode(code);
    * ```
    */
   getOAuthUrl(options) {
@@ -437,6 +442,329 @@ var OvixaAuth = class {
     url.searchParams.set("redirect_uri", options.redirectUri);
     return url.toString();
   }
+  // ============================================================
+  // WebAuthn / Passkey Methods
+  // ============================================================
+  /**
+   * Get registration options for creating a new passkey.
+   *
+   * The user must be logged in to register a passkey. Use the returned options
+   * with navigator.credentials.create() to create the credential.
+   *
+   * @param options - Registration options with access token
+   * @returns Registration options to pass to navigator.credentials.create()
+   * @throws {OvixaAuthError} If request fails
+   *
+   * @example
+   * ```typescript
+   * // User must be logged in
+   * const options = await auth.getPasskeyRegistrationOptions({
+   *   accessToken: session.accessToken,
+   * });
+   *
+   * // Create the credential using the browser API
+   * const credential = await navigator.credentials.create({
+   *   publicKey: {
+   *     ...options,
+   *     challenge: base64UrlToArrayBuffer(options.challenge),
+   *     user: {
+   *       ...options.user,
+   *       id: new TextEncoder().encode(options.user.id),
+   *     },
+   *     excludeCredentials: options.excludeCredentials.map(c => ({
+   *       ...c,
+   *       id: base64UrlToArrayBuffer(c.id),
+   *     })),
+   *   },
+   * });
+   *
+   * // Verify the registration with the server
+   * await auth.verifyPasskeyRegistration({
+   *   accessToken: session.accessToken,
+   *   registration: formatRegistrationResponse(credential),
+   *   deviceName: 'My MacBook',
+   * });
+   * ```
+   */
+  async getPasskeyRegistrationOptions(options) {
+    const url = `${this.config.authUrl}/webauthn/register/options`;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${options.accessToken}`
+        },
+        body: JSON.stringify({
+          realm_id: this.config.realmId
+        })
+      });
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OvixaAuthError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new OvixaAuthError(`Network error: ${error.message}`, "NETWORK_ERROR");
+      }
+      throw new OvixaAuthError("Request failed", "REQUEST_FAILED");
+    }
+  }
+  /**
+   * Verify a passkey registration and store the credential.
+   *
+   * Call this after navigator.credentials.create() succeeds to complete the
+   * registration on the server.
+   *
+   * @param options - Verification options with registration response
+   * @returns Registration response with credential ID
+   * @throws {OvixaAuthError} If verification fails
+   *
+   * @example
+   * ```typescript
+   * const result = await auth.verifyPasskeyRegistration({
+   *   accessToken: session.accessToken,
+   *   registration: {
+   *     id: credential.id,
+   *     rawId: arrayBufferToBase64Url(credential.rawId),
+   *     type: 'public-key',
+   *     response: {
+   *       clientDataJSON: arrayBufferToBase64Url(credential.response.clientDataJSON),
+   *       attestationObject: arrayBufferToBase64Url(credential.response.attestationObject),
+   *       transports: credential.response.getTransports?.(),
+   *     },
+   *   },
+   *   deviceName: 'My MacBook',
+   * });
+   *
+   * console.log('Passkey registered:', result.credential_id);
+   * ```
+   */
+  async verifyPasskeyRegistration(options) {
+    const url = `${this.config.authUrl}/webauthn/register/verify`;
+    const body = {
+      realm_id: this.config.realmId,
+      registration: options.registration
+    };
+    if (options.deviceName) {
+      body.device_name = options.deviceName;
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${options.accessToken}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OvixaAuthError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new OvixaAuthError(`Network error: ${error.message}`, "NETWORK_ERROR");
+      }
+      throw new OvixaAuthError("Request failed", "REQUEST_FAILED");
+    }
+  }
+  /**
+   * Get authentication options for signing in with a passkey.
+   *
+   * Use the returned options with navigator.credentials.get() to authenticate.
+   *
+   * @param options - Optional email for allowCredentials hint
+   * @returns Authentication options to pass to navigator.credentials.get()
+   * @throws {OvixaAuthError} If request fails
+   *
+   * @example
+   * ```typescript
+   * // Option 1: Discoverable credentials (no email needed)
+   * const options = await auth.getPasskeyAuthenticationOptions();
+   *
+   * // Option 2: Provide email for allowCredentials hint
+   * const options = await auth.getPasskeyAuthenticationOptions({
+   *   email: 'user@example.com',
+   * });
+   *
+   * // Authenticate using the browser API
+   * const credential = await navigator.credentials.get({
+   *   publicKey: {
+   *     ...options,
+   *     challenge: base64UrlToArrayBuffer(options.challenge),
+   *     allowCredentials: options.allowCredentials.map(c => ({
+   *       ...c,
+   *       id: base64UrlToArrayBuffer(c.id),
+   *     })),
+   *   },
+   * });
+   *
+   * // Verify and get tokens
+   * const tokens = await auth.verifyPasskeyAuthentication({
+   *   authentication: formatAuthenticationResponse(credential),
+   * });
+   * ```
+   */
+  async getPasskeyAuthenticationOptions(options) {
+    const url = `${this.config.authUrl}/webauthn/authenticate/options`;
+    const body = {
+      realm_id: this.config.realmId
+    };
+    if (options?.email) {
+      body.email = options.email;
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OvixaAuthError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new OvixaAuthError(`Network error: ${error.message}`, "NETWORK_ERROR");
+      }
+      throw new OvixaAuthError("Request failed", "REQUEST_FAILED");
+    }
+  }
+  /**
+   * Verify a passkey authentication and get tokens.
+   *
+   * Call this after navigator.credentials.get() succeeds to complete the
+   * authentication and receive access/refresh tokens.
+   *
+   * @param options - Verification options with authentication response
+   * @returns Token response with access and refresh tokens
+   * @throws {OvixaAuthError} If verification fails
+   *
+   * @example
+   * ```typescript
+   * const tokens = await auth.verifyPasskeyAuthentication({
+   *   authentication: {
+   *     id: credential.id,
+   *     rawId: arrayBufferToBase64Url(credential.rawId),
+   *     type: 'public-key',
+   *     response: {
+   *       clientDataJSON: arrayBufferToBase64Url(credential.response.clientDataJSON),
+   *       authenticatorData: arrayBufferToBase64Url(credential.response.authenticatorData),
+   *       signature: arrayBufferToBase64Url(credential.response.signature),
+   *       userHandle: credential.response.userHandle
+   *         ? arrayBufferToBase64Url(credential.response.userHandle)
+   *         : null,
+   *     },
+   *   },
+   * });
+   *
+   * // Use the tokens
+   * console.log('Logged in!', tokens.access_token);
+   * ```
+   */
+  async verifyPasskeyAuthentication(options) {
+    const url = `${this.config.authUrl}/webauthn/authenticate/verify`;
+    const body = {
+      realm_id: this.config.realmId,
+      authentication: options.authentication
+    };
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof OvixaAuthError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new OvixaAuthError(`Network error: ${error.message}`, "NETWORK_ERROR");
+      }
+      throw new OvixaAuthError("Request failed", "REQUEST_FAILED");
+    }
+  }
+  /**
+   * Handle error response from the server.
+   * @throws {OvixaAuthError} Always throws with appropriate error details
+   */
+  async handleErrorResponse(response) {
+    const errorBody = await response.json().catch(() => ({}));
+    const errorData = errorBody;
+    let errorCode;
+    let errorMessage;
+    if (typeof errorData.error === "object" && errorData.error) {
+      errorCode = errorData.error.code || this.mapHttpStatusToErrorCode(response.status);
+      errorMessage = errorData.error.message || "Request failed";
+    } else {
+      errorCode = this.mapHttpStatusToErrorCode(response.status);
+      errorMessage = typeof errorData.error === "string" ? errorData.error : "Request failed";
+    }
+    throw new OvixaAuthError(errorMessage, errorCode, response.status);
+  }
+  /**
+   * Exchange an OAuth authorization code for tokens.
+   *
+   * After the OAuth flow completes, the user is redirected back to your app with
+   * an authorization code in the URL query params. Use this method to exchange
+   * that code for access and refresh tokens.
+   *
+   * Note: Authorization codes expire after 60 seconds.
+   *
+   * @param code - The authorization code from the OAuth callback URL
+   * @returns Token response with access and refresh tokens
+   * @throws {OvixaAuthError} If the exchange fails
+   *
+   * @example
+   * ```typescript
+   * // In your OAuth callback handler
+   * const code = new URLSearchParams(window.location.search).get('code');
+   *
+   * if (code) {
+   *   try {
+   *     const tokens = await auth.exchangeOAuthCode(code);
+   *     console.log('OAuth successful!', tokens.access_token);
+   *
+   *     // Check if this is a new user (first-time OAuth login)
+   *     if (tokens.is_new_user) {
+   *       // Show onboarding flow
+   *     }
+   *   } catch (error) {
+   *     if (error instanceof OvixaAuthError) {
+   *       if (error.code === 'INVALID_CODE') {
+   *         console.error('Invalid or expired authorization code');
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  async exchangeOAuthCode(code) {
+    const url = `${this.config.authUrl}/oauth/token`;
+    const body = {
+      code,
+      realm_id: this.config.realmId
+    };
+    return this.makeRequest(url, body);
+  }
   /**
    * Transform a token response into an AuthResult with user and session data.
    *
@@ -723,9 +1051,95 @@ var OvixaAuthAdmin = class {
     }
   }
 };
+function arrayBufferToBase64Url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToArrayBuffer(base64url) {
+  const base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+function prepareRegistrationOptions(options) {
+  return {
+    challenge: base64UrlToArrayBuffer(options.challenge),
+    rp: options.rp,
+    user: {
+      id: new TextEncoder().encode(options.user.id),
+      name: options.user.name,
+      displayName: options.user.displayName
+    },
+    pubKeyCredParams: options.pubKeyCredParams,
+    excludeCredentials: options.excludeCredentials.map((cred) => ({
+      id: base64UrlToArrayBuffer(cred.id),
+      type: cred.type,
+      transports: cred.transports
+    })),
+    authenticatorSelection: options.authenticatorSelection,
+    timeout: options.timeout,
+    attestation: options.attestation
+  };
+}
+function prepareAuthenticationOptions(options) {
+  return {
+    challenge: base64UrlToArrayBuffer(options.challenge),
+    rpId: options.rpId,
+    allowCredentials: options.allowCredentials.map((cred) => ({
+      id: base64UrlToArrayBuffer(cred.id),
+      type: cred.type,
+      transports: cred.transports
+    })),
+    userVerification: options.userVerification,
+    timeout: options.timeout
+  };
+}
+function formatRegistrationResponse(credential) {
+  const response = credential.response;
+  return {
+    id: credential.id,
+    rawId: arrayBufferToBase64Url(credential.rawId),
+    type: "public-key",
+    response: {
+      clientDataJSON: arrayBufferToBase64Url(response.clientDataJSON),
+      attestationObject: arrayBufferToBase64Url(response.attestationObject),
+      transports: response.getTransports?.()
+    },
+    authenticatorAttachment: credential.authenticatorAttachment
+  };
+}
+function formatAuthenticationResponse(credential) {
+  const response = credential.response;
+  return {
+    id: credential.id,
+    rawId: arrayBufferToBase64Url(credential.rawId),
+    type: "public-key",
+    response: {
+      clientDataJSON: arrayBufferToBase64Url(response.clientDataJSON),
+      authenticatorData: arrayBufferToBase64Url(response.authenticatorData),
+      signature: arrayBufferToBase64Url(response.signature),
+      userHandle: response.userHandle ? arrayBufferToBase64Url(response.userHandle) : null
+    },
+    authenticatorAttachment: credential.authenticatorAttachment
+  };
+}
 
 export {
   OvixaAuthError,
-  OvixaAuth
+  OvixaAuth,
+  arrayBufferToBase64Url,
+  base64UrlToArrayBuffer,
+  prepareRegistrationOptions,
+  prepareAuthenticationOptions,
+  formatRegistrationResponse,
+  formatAuthenticationResponse
 };
-//# sourceMappingURL=chunk-IIOWUPWH.js.map
+//# sourceMappingURL=chunk-5ZWKDQQM.js.map