WebAuthnClient

WebAuthnClient is the abstraction layer between mera’s passkey functions and a platform’s WebAuthn API. For each call, mera builds a request that the client converts to the platform’s format and sends to the API.

The built-in browser client calls navigator.credentials. Apps on other platforms can provide a client that implements createCredential and getCredential.

Members

type 
type WebAuthnClient = {
    readonly createCredential: (request: MeraWebAuthnClient.CreateCredentialRequest) => Promise<MeraWebAuthnClient.CreateCredentialResult>;
    readonly getCredential: (request: MeraWebAuthnClient.GetCredentialRequest) => Promise<MeraWebAuthnClient.GetCredentialResult>;
}
WebAuthnClient = {
  readonly 
createCredential: (request: MeraWebAuthnClient.CreateCredentialRequest) => Promise<MeraWebAuthnClient.CreateCredentialResult>
createCredential: (
    
request: MeraWebAuthnClient.CreateCredentialRequest
request: 
(alias) namespace MeraWebAuthnClient
import MeraWebAuthnClient
MeraWebAuthnClient.
type WebAuthnClient.CreateCredentialRequest = {
    rp: PasskeyRelyingParty;
    user: {
        id: Uint8Array<ArrayBuffer>;
        name: string;
        displayName: string;
    };
    challenge: Uint8Array<ArrayBuffer>;
    algorithms: readonly number[];
    prfSalt: Uint8Array<ArrayBuffer>;
    residentKey: "required";
    userVerification: "required";
    attestation: "none";
    timeout?: number;
}
Ceremony parameters for creating one passkey and evaluating its PRF.
CreateCredentialRequest,
  ) => 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
(alias) namespace MeraWebAuthnClient
import MeraWebAuthnClient
MeraWebAuthnClient.
type WebAuthnClient.CreateCredentialResult = {
    credentialId: Uint8Array;
    transports?: readonly PasskeyCredentialTransport[];
    prfEnabled: boolean;
    prfOutput?: Uint8Array;
}
Outcome of one credential-creation ceremony.
CreateCredentialResult>;
  readonly 
getCredential: (request: MeraWebAuthnClient.GetCredentialRequest) => Promise<MeraWebAuthnClient.GetCredentialResult>
getCredential: (
    
request: MeraWebAuthnClient.GetCredentialRequest
request: 
(alias) namespace MeraWebAuthnClient
import MeraWebAuthnClient
MeraWebAuthnClient.
type WebAuthnClient.GetCredentialRequest = {
    rpId: string;
    challenge: Uint8Array<ArrayBuffer>;
    allowCredential?: MeraWebAuthnClient.AllowCredential;
    prfSalt: Uint8Array<ArrayBuffer>;
    userVerification: "required";
    timeout?: number;
}
Ceremony parameters for asserting a passkey and evaluating its PRF.
GetCredentialRequest,
  ) => 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
(alias) namespace MeraWebAuthnClient
import MeraWebAuthnClient
MeraWebAuthnClient.
type WebAuthnClient.GetCredentialResult = {
    credentialId: Uint8Array;
    prfOutput?: Uint8Array;
}
Outcome of one assertion ceremony.
GetCredentialResult>;
};

WebAuthnClient.CreateCredentialRequest

The relying party, user, challenge, credential policy, and PRF salt for a creation ceremony.

WebAuthnClient.CreateCredentialResult

The new credential ID, reported transports, PRF support flag, and optional PRF output.

WebAuthnClient.GetCredentialRequest

The relying party ID, challenge, optional allowed credential, and PRF salt for an assertion ceremony.

WebAuthnClient.GetCredentialResult

The credential ID that answered and its optional PRF output.

Requests and results use Uint8Array for binary values. When creation enables PRF but returns no output, mera calls getCredential with the same client and salt.

A PRF output that is not 32 bytes fails with PRF_UNAVAILABLE. Anything a client throws surfaces as PASSKEY_OPERATION_FAILED with the original error as its cause.

Usage

import { 
function getPasskeyPrfOutput({ rpId, credential: allowCredential, prfSalt, timeout, webAuthnClient, }: getPasskeyPrfOutput.Options): Promise<getPasskeyPrfOutput.Result>
Requests a passkey PRF evaluation and returns the first output.
@param ― options - Passkey PRF request inputs.
@returns ― The selected credential ID and first WebAuthn PRF output.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.
The WebAuthn challenge is generated internally.
The default salt is sha256("mera.prf.salt.v1") and will not change across
library versions. The PRF output is a deterministic function of the
credential, rpId, and salt; a different salt yields an unrelated output.
The assertion requires user verification, and the requirement is not
configurable. User verification is the authenticator's local check; the
gesture depends on the platform (a biometric, a device PIN, or a password).
Authenticators built on CTAP's hmac-secret keep two PRFs per credential,
one for user-verified requests and one for the rest; WebAuthn exposes only
the user-verified PRF and overrides a weaker userVerification setting
when evaluating it, so a configurable setting could neither change the PRF
output nor skip the check.
@see ― https://www.w3.org/TR/webauthn-3/#prf-extension WebAuthn: the PRF extension
@see ― https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement WebAuthn: UserVerificationRequirement
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when an explicit prfSalt is not 32 bytes, or credential.credentialId is empty or not canonical base64url.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues is unavailable.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, cancelled, or returns an unexpected credential.
getPasskeyPrfOutput } from "@category-labs/mera";
import { 
const reactNativeWebAuthnClient: WebAuthnClient
reactNativeWebAuthnClient } from "@category-labs/mera/react-native-webauthn-client";

const { 
const prfOutput: Uint8Array<ArrayBuffer>
First PRF output from WebAuthn. Always 32 bytes.
prfOutput } = await 
function getPasskeyPrfOutput({ rpId, credential: allowCredential, prfSalt, timeout, webAuthnClient, }: getPasskeyPrfOutput.Options): Promise<getPasskeyPrfOutput.Result>
Requests a passkey PRF evaluation and returns the first output.
@param ― options - Passkey PRF request inputs.
@returns ― The selected credential ID and first WebAuthn PRF output.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.
The WebAuthn challenge is generated internally.
The default salt is sha256("mera.prf.salt.v1") and will not change across
library versions. The PRF output is a deterministic function of the
credential, rpId, and salt; a different salt yields an unrelated output.
The assertion requires user verification, and the requirement is not
configurable. User verification is the authenticator's local check; the
gesture depends on the platform (a biometric, a device PIN, or a password).
Authenticators built on CTAP's hmac-secret keep two PRFs per credential,
one for user-verified requests and one for the rest; WebAuthn exposes only
the user-verified PRF and overrides a weaker userVerification setting
when evaluating it, so a configurable setting could neither change the PRF
output nor skip the check.
@see ― https://www.w3.org/TR/webauthn-3/#prf-extension WebAuthn: the PRF extension
@see ― https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement WebAuthn: UserVerificationRequirement
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when an explicit prfSalt is not 32 bytes, or credential.credentialId is empty or not canonical base64url.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues is unavailable.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, cancelled, or returns an unexpected credential.
getPasskeyPrfOutput({
  
rpId: string
Relying party ID for the WebAuthn assertion.
rpId: "account.example.com",
  
webAuthnClient?: WebAuthnClient | undefined
Client that runs the WebAuthn ceremony. Defaults to the built-in browser
client, which calls navigator.credentials.
webAuthnClient: 
const reactNativeWebAuthnClient: WebAuthnClient
reactNativeWebAuthnClient,
});

reactNativeWebAuthnClient

The React Native client requires react-native-passkey. It lives in a separate entry point, so the root package loads no React Native code.

The cause inside PASSKEY_OPERATION_FAILED is react-native-passkey’s PasskeyError.