@ovixa/auth-client 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.3.0] - 2026-01-30
+
+### Added
+
+- `auth.webauthn.listPasskeys({ accessToken })` - List all passkeys for the authenticated user
+- `auth.webauthn.deletePasskey({ accessToken, credentialId })` - Delete a specific passkey
+
+### Changed
+
+- **BREAKING**: Moved WebAuthn methods to `auth.webauthn` namespace
+  - `auth.getPasskeyRegistrationOptions()` → `auth.webauthn.getRegistrationOptions()`
+  - `auth.verifyPasskeyRegistration()` → `auth.webauthn.verifyRegistration()`
+  - `auth.getPasskeyAuthenticationOptions()` → `auth.webauthn.getAuthenticationOptions()`
+  - `auth.verifyPasskeyAuthentication()` → `auth.webauthn.authenticate()`
+
+## [0.2.0] - 2026-01-29
+
+### Added
+
+- **WebAuthn/Passkey authentication support** - Passwordless authentication using FIDO2
+  - `auth.getPasskeyRegistrationOptions({ accessToken })` - Get options to register a new passkey
+  - `auth.verifyPasskeyRegistration({ accessToken, registration, deviceName? })` - Complete passkey registration
+  - `auth.getPasskeyAuthenticationOptions({ email? })` - Get options to authenticate with passkey
+  - `auth.verifyPasskeyAuthentication({ authentication })` - Authenticate and receive tokens
+
 ## [0.1.3] - 2026-01-29
 
 ### 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
@@ -243,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-CUACHOKT.js → chunk-5QEKSWV4.js}

@@ -683,6 +683,37 @@ var OvixaAuth = class {
     }
     return new OvixaAuthAdmin(this.config);
   }
+  /**
+   * Get the WebAuthn API interface for passkey operations.
+   *
+   * The WebAuthn namespace provides methods for registering and authenticating
+   * with passkeys, as well as managing existing passkeys.
+   *
+   * @returns OvixaAuthWebAuthn interface for passkey operations
+   *
+   * @example
+   * ```typescript
+   * const auth = new OvixaAuth({
+   *   authUrl: 'https://auth.ovixa.io',
+   *   realmId: 'your-realm',
+   * });
+   *
+   * // Register a passkey
+   * const options = await auth.webauthn.getRegistrationOptions({ accessToken });
+   *
+   * // Authenticate with passkey
+   * const authOptions = await auth.webauthn.getAuthenticationOptions();
+   *
+   * // List passkeys
+   * const { passkeys } = await auth.webauthn.listPasskeys({ accessToken });
+   *
+   * // Delete a passkey
+   * await auth.webauthn.deletePasskey({ accessToken, credentialId });
+   * ```
+   */
+  get webauthn() {
+    return new OvixaAuthWebAuthn(this.config);
+  }
 };
 var OvixaAuthAdmin = class {
   config;
@@ -773,9 +804,382 @@ var OvixaAuthAdmin = class {
     }
   }
 };
+var OvixaAuthWebAuthn = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * 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
+   */
+  async getRegistrationOptions(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
+   */
+  async verifyRegistration(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
+   */
+  async getAuthenticationOptions(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
+   */
+  async authenticate(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");
+    }
+  }
+  /**
+   * List all passkeys for the authenticated user.
+   *
+   * @param options - Options with access token
+   * @returns List of passkeys
+   * @throws {OvixaAuthError} If request fails
+   *
+   * @example
+   * ```typescript
+   * const { passkeys } = await auth.webauthn.listPasskeys({ accessToken });
+   * for (const passkey of passkeys) {
+   *   console.log(passkey.device_name, passkey.created_at);
+   * }
+   * ```
+   */
+  async listPasskeys(options) {
+    const url = `${this.config.authUrl}/webauthn/passkeys`;
+    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");
+    }
+  }
+  /**
+   * Delete a passkey for the authenticated user.
+   *
+   * @param options - Options with access token and credential ID
+   * @returns Success response
+   * @throws {OvixaAuthError} If deletion fails
+   *
+   * @example
+   * ```typescript
+   * await auth.webauthn.deletePasskey({
+   *   accessToken,
+   *   credentialId: 'credential-id-to-delete',
+   * });
+   * ```
+   */
+  async deletePasskey(options) {
+    const url = `${this.config.authUrl}/webauthn/passkeys/${encodeURIComponent(options.credentialId)}`;
+    try {
+      const response = await fetch(url, {
+        method: "DELETE",
+        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");
+    }
+  }
+  /**
+   * 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);
+  }
+  /**
+   * Map HTTP status codes to error codes.
+   */
+  mapHttpStatusToErrorCode(status) {
+    switch (status) {
+      case 400:
+        return "BAD_REQUEST";
+      case 401:
+        return "UNAUTHORIZED";
+      case 403:
+        return "FORBIDDEN";
+      case 404:
+        return "NOT_FOUND";
+      case 429:
+        return "RATE_LIMITED";
+      case 500:
+      case 502:
+      case 503:
+        return "SERVER_ERROR";
+      default:
+        return "UNKNOWN_ERROR";
+    }
+  }
+};
+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-CUACHOKT.js.map
+//# sourceMappingURL=chunk-5QEKSWV4.js.map