@asgardeo/browser 0.1.21 → 0.1.22

package/dist/utils/handleWebAuthnAuthentication.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Handles WebAuthn/Passkey authentication flow for browser environments.
+ *
+ * This function processes a WebAuthn challenge, performs the authentication ceremony,
+ * and returns the authentication response that can be sent to the server for verification.
+ *
+ * The function handles various aspects of WebAuthn authentication including:
+ * - Browser compatibility checks for WebAuthn support
+ * - HTTPS requirement validation (except for localhost development)
+ * - Relying Party ID validation and domain compatibility
+ * - Challenge data decoding and credential request options processing
+ * - User authentication ceremony via navigator.credentials.get()
+ * - Response formatting for server consumption
+ *
+ * @param challengeData - Base64-encoded challenge data containing WebAuthn request options.
+ *                       This data typically includes the challenge, RP ID, allowed credentials,
+ *                       user verification requirements, and other authentication parameters.
+ *
+ * @returns Promise that resolves to a JSON string containing the WebAuthn authentication response.
+ *          The response includes the credential ID, authenticator data, client data JSON,
+ *          signature, and optional user handle that can be verified by the server.
+ *
+ * @throws {AsgardeoRuntimeError} When WebAuthn is not supported in the current browser
+ * @throws {AsgardeoRuntimeError} When the page is not served over HTTPS (except localhost)
+ * @throws {AsgardeoRuntimeError} When the user cancels or times out the authentication
+ * @throws {AsgardeoRuntimeError} When there's a domain/RP ID mismatch
+ * @throws {AsgardeoRuntimeError} When no valid passkey is found for the account
+ * @throws {AsgardeoRuntimeError} When WebAuthn is not supported on the device/browser
+ * @throws {AsgardeoRuntimeError} When there's a network error during authentication
+ * @throws {AsgardeoRuntimeError} For any other authentication failures
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const challengeData = 'eyJwdWJsaWNLZXlDcmVkZW50aWFsUmVxdWVzdE9wdGlvbnMiOi4uLn0=';
+ *   const authResponse = await handleWebAuthnAuthentication(challengeData);
+ *
+ *   // Send the response to your server for verification
+ *   const result = await fetch('/api/verify-webauthn', {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: authResponse
+ *   });
+ * } catch (error) {
+ *   if (error instanceof AsgardeoRuntimeError) {
+ *     console.error('WebAuthn authentication failed:', error.message);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in an authentication flow
+ * const authenticateWithPasskey = async (challengeFromServer: string) => {
+ *   try {
+ *     const response = await handleWebAuthnAuthentication(challengeFromServer);
+ *     return JSON.parse(response);
+ *   } catch (error) {
+ *     // Handle specific error cases
+ *     if (error instanceof AsgardeoRuntimeError) {
+ *       switch (error.code) {
+ *         case 'browser-webauthn-not-supported':
+ *           showFallbackAuth();
+ *           break;
+ *         case 'browser-webauthn-user-cancelled':
+ *           showRetryOption();
+ *           break;
+ *         default:
+ *           showGenericError();
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link https://webauthn.guide/} - WebAuthn specification guide
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API} - MDN WebAuthn API documentation
+ */
+declare const handleWebAuthnAuthentication: (challengeData: string) => Promise<string>;
+export default handleWebAuthnAuthentication;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asgardeo/browser",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Browser-specific implementation of Asgardeo JavaScript SDK.",
   "keywords": [
     "asgardeo",
@@ -60,7 +60,7 @@
     "randombytes": "^2.1.0",
     "stream-browserify": "^3.0.0",
     "tslib": "^2.8.1",
-    "@asgardeo/javascript": "^0.1.20"
+    "@asgardeo/javascript": "^0.1.21"
   },
   "publishConfig": {
     "access": "public"