Errors

The library uses MeraError for its documented failure modes. It carries a stable, machine-readable code alongside the usual message and optional cause. The codes are the contract; the message text is free to change between versions.

MeraError

declare class 
class MeraError
MeraError extends 
var Error: ErrorConstructor
Error {
  readonly 
MeraError.code: MeraErrorCode
code: 
type MeraErrorCode = "PASSKEY_OPERATION_FAILED" | "CRYPTO_UNAVAILABLE" | "PRF_UNAVAILABLE" | "SESSION_ENDED" | "DECRYPT_FAILED" | "INPUT_INVALID" | "VAULT_FORMAT_INVALID"
Stable error codes thrown by this package.

PASSKEY_OPERATION_FAILED: WebAuthn failed, was cancelled, returned an unexpected credential, or the credential API is unavailable.
CRYPTO_UNAVAILABLE: the runtime lacks a needed Web Crypto primitive. The passkey APIs need crypto.getRandomValues; the secret-vault APIs also need crypto.subtle.
PRF_UNAVAILABLE: the authenticator did not enable or return a usable 32-byte WebAuthn PRF output.
SESSION_ENDED: a signing call was made after end().
DECRYPT_FAILED: AES-GCM authentication failed (wrong key or tampered nonce/ciphertext).
INPUT_INVALID: a caller-supplied value at a public boundary did not satisfy a length, range, encoding, or curve (scalar or point) constraint.
VAULT_FORMAT_INVALID: untrusted vault data (JSON or object) was malformed, missing required fields, used a non-canonical encoding, or declared an unsupported version.
MeraErrorCode;
}

name is always "MeraError". When a lower-level failure triggered the error (a WebAuthn rejection, a Web Crypto failure), it is attached as cause.

isMeraError

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,
  
function isMeraError(error: unknown): error is MeraError
Returns true when error is a MeraError.
isMeraError,
} from "@category-labs/mera";

try {
  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",
  });
} catch (
var error: unknown
error) {
  if (
function isMeraError(error: unknown): error is MeraError
Returns true when error is a MeraError.
isMeraError(
var error: unknown
error) && 
var error: MeraError
error.
MeraError.code: MeraErrorCode
Stable machine-readable category for the failure.
code === "PRF_UNAVAILABLE") {
    // Point at a PRF-capable authenticator.
  }
  throw 
var error: unknown
error;
}

isMeraError is a type guard: it narrows a caught value so code can be branched on.

Codes

PASSKEY_OPERATION_FAILED

WebAuthn failed, was cancelled, returned an unexpected credential, or the credential API is unavailable. Cancellation is the everyday case: the person dismissed the prompt.

CRYPTO_UNAVAILABLE

A Web Crypto primitive is unavailable. The passkey APIs need crypto.getRandomValues; the secret-vault APIs also need crypto.subtle (requires HTTPS or localhost during development).

PRF_UNAVAILABLE

The authenticator did not enable PRF, or did not return a usable 32-byte PRF output. Authenticator support lists tested compatible stacks.

SESSION_ENDED

A signing call was made after the session’s end().

DECRYPT_FAILED

AES-GCM authentication failed while decrypting a vault: wrong key material or a tampered nonce/ciphertext pair.

INPUT_INVALID

A caller-supplied value at a public boundary did not satisfy a length, range, encoding, or curve constraint (a private key that is not a valid scalar, a public key that is not a valid point). Each function’s Errors section lists its specific conditions.

VAULT_FORMAT_INVALID

Untrusted vault data (JSON text or an object) was malformed, missing required fields, used a non-canonical encoding, or declared an unsupported version.