or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

authentication.md error-handling.md helpers.md index.md

tile.json

tessl/deno-simplewebauthn--browser

Browser-side WebAuthn library that simplifies WebAuthn credential registration and authentication workflows

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@simplewebauthn/browser@12.0.x

To install, run

npx @tessl/cli install tessl/deno-simplewebauthn--browser@12.0.0

SimpleWebAuthn Browser

SimpleWebAuthn Browser is a TypeScript library that simplifies WebAuthn credential registration and authentication workflows for web applications. It provides high-level methods that handle the complex browser WebAuthn API interactions, credential parsing, and error handling, making it easy to implement passwordless authentication.

Package Information

Package Name: @simplewebauthn/browser
Package Type: npm/JSR
Language: TypeScript
Installation: npm install @simplewebauthn/browser or deno add jsr:@simplewebauthn/browser

Core Imports

import {
  startRegistration,
  startAuthentication,
  browserSupportsWebAuthn,
  platformAuthenticatorIsAvailable,
  browserSupportsWebAuthnAutofill,
  base64URLStringToBuffer,
  bufferToBase64URLString,
  WebAuthnAbortService,
  WebAuthnError,
  type WebAuthnErrorCode
} from '@simplewebauthn/browser';

For UMD (browser):

<script src="https://unpkg.com/@simplewebauthn/browser/dist/bundle/index.umd.min.js"></script>
<!-- Available on global SimpleWebAuthnBrowser object -->

Basic Usage

import {
  startRegistration,
  startAuthentication,
  browserSupportsWebAuthn,
  type RegistrationResponseJSON,
  type AuthenticationResponseJSON
} from '@simplewebauthn/browser';

// Check WebAuthn support
if (!browserSupportsWebAuthn()) {
  throw new Error('WebAuthn not supported');
}

// Registration flow
const registrationResponse: RegistrationResponseJSON = await startRegistration({
  optionsJSON: registrationOptionsFromServer
});

// Send registrationResponse to server for verification

// Authentication flow  
const authResponse: AuthenticationResponseJSON = await startAuthentication({
  optionsJSON: authenticationOptionsFromServer
});

// Send authResponse to server for verification

Architecture

SimpleWebAuthn Browser is built around several key components:

Core Methods: High-level startRegistration() and startAuthentication() functions that orchestrate the WebAuthn ceremonies
Feature Detection: Functions to detect WebAuthn support and capabilities across different browsers and environments
Data Conversion: Utilities for converting between ArrayBuffer and Base64URL string formats required by WebAuthn
Error Handling: Comprehensive error classification with specific error codes for different WebAuthn failure scenarios
Abort Management: Service to handle cancellation of WebAuthn operations, ensuring only one ceremony runs at a time

Capabilities

WebAuthn Authentication Operations

Core WebAuthn registration and authentication functionality. These methods handle the complete ceremony flow including credential creation, user verification, and response formatting.

function startRegistration(options: StartRegistrationOpts): Promise<RegistrationResponseJSON>;

function startAuthentication(options: StartAuthenticationOpts): Promise<AuthenticationResponseJSON>;

interface StartRegistrationOpts {
  optionsJSON: PublicKeyCredentialCreationOptionsJSON;
  useAutoRegister?: boolean;
}

interface StartAuthenticationOpts {
  optionsJSON: PublicKeyCredentialRequestOptionsJSON;
  useBrowserAutofill?: boolean;
  verifyBrowserAutofillInput?: boolean;
}

Authentication Operations

Helper Functions and Utilities

Feature detection functions and data conversion utilities that support WebAuthn operations. Includes browser capability checks and Base64URL encoding/decoding helpers.

function browserSupportsWebAuthn(): boolean;
function platformAuthenticatorIsAvailable(): Promise<boolean>;
function browserSupportsWebAuthnAutofill(): Promise<boolean>;
function base64URLStringToBuffer(base64URLString: string): ArrayBuffer;
function bufferToBase64URLString(buffer: ArrayBuffer): string;

Helper Functions

Error Handling and Abort Control

Comprehensive error handling with WebAuthn-specific error codes and abort service for managing ceremony lifecycles.

class WebAuthnError extends Error {
  code: WebAuthnErrorCode;
  constructor(options: {
    message: string;
    code: WebAuthnErrorCode;
    cause: Error;
    name?: string;
  });
}

type WebAuthnErrorCode =
  | 'ERROR_CEREMONY_ABORTED'
  | 'ERROR_INVALID_DOMAIN'
  | 'ERROR_INVALID_RP_ID'
  | 'ERROR_INVALID_USER_ID_LENGTH'
  | 'ERROR_MALFORMED_PUBKEYCREDPARAMS'
  | 'ERROR_AUTHENTICATOR_GENERAL_ERROR'
  | 'ERROR_AUTHENTICATOR_MISSING_DISCOVERABLE_CREDENTIAL_SUPPORT'
  | 'ERROR_AUTHENTICATOR_MISSING_USER_VERIFICATION_SUPPORT'
  | 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED'
  | 'ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG'
  | 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE'
  | 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY';

interface WebAuthnAbortService {
  createNewAbortSignal(): AbortSignal;
  cancelCeremony(): void;
}

Error Handling

Core Types

Key type definitions used throughout the API, imported from @simplewebauthn/types:

// Registration types
interface RegistrationResponseJSON {
  id: Base64URLString;
  rawId: Base64URLString;
  response: AuthenticatorAttestationResponseJSON;
  authenticatorAttachment?: AuthenticatorAttachment;
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
  type: PublicKeyCredentialType;
}

// Authentication types
interface AuthenticationResponseJSON {
  id: Base64URLString;
  rawId: Base64URLString;
  response: AuthenticatorAssertionResponseJSON;
  authenticatorAttachment?: AuthenticatorAttachment;
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
  type: PublicKeyCredentialType;
}

// Server options (input to browser methods)
interface PublicKeyCredentialCreationOptionsJSON {
  rp: PublicKeyCredentialRpEntity;
  user: PublicKeyCredentialUserEntityJSON;
  challenge: Base64URLString;
  pubKeyCredParams: PublicKeyCredentialParameters[];
  timeout?: number;
  excludeCredentials?: PublicKeyCredentialDescriptorJSON[];
  authenticatorSelection?: AuthenticatorSelectionCriteria;
  attestation?: AttestationConveyancePreference;
  extensions?: AuthenticationExtensionsClientInputs;
}

interface PublicKeyCredentialRequestOptionsJSON {
  challenge: Base64URLString;
  timeout?: number;
  rpId?: string;
  allowCredentials?: PublicKeyCredentialDescriptorJSON[];
  userVerification?: UserVerificationRequirement;
  extensions?: AuthenticationExtensionsClientInputs;
}

// Supporting types for options and descriptors
interface PublicKeyCredentialUserEntityJSON {
  id: string;
  name: string;
  displayName: string;
}

interface PublicKeyCredentialDescriptorJSON {
  id: Base64URLString;
  type: PublicKeyCredentialType;
  transports?: AuthenticatorTransportFuture[];
}

interface AuthenticatorAttestationResponseJSON {
  clientDataJSON: Base64URLString;
  attestationObject: Base64URLString;
  authenticatorData?: Base64URLString;
  transports?: AuthenticatorTransportFuture[];
  publicKeyAlgorithm?: COSEAlgorithmIdentifier;
  publicKey?: Base64URLString;
}

interface AuthenticatorAssertionResponseJSON {
  clientDataJSON: Base64URLString;
  authenticatorData: Base64URLString;
  signature: Base64URLString;
  userHandle?: Base64URLString;
}

// Additional supporting types
type AuthenticatorTransportFuture = 
  | 'ble' 
  | 'cable' 
  | 'hybrid' 
  | 'internal' 
  | 'nfc' 
  | 'smart-card' 
  | 'usb';

type AuthenticatorAttachment = 'platform' | 'cross-platform';

type PublicKeyCredentialType = 'public-key';

type COSEAlgorithmIdentifier = number;

// DOM-imported types (from WebAuthn spec)
interface PublicKeyCredentialRpEntity {
  id?: string;
  name: string;
}

interface PublicKeyCredentialParameters {
  type: PublicKeyCredentialType;
  alg: COSEAlgorithmIdentifier;
}

interface AuthenticatorSelectionCriteria {
  authenticatorAttachment?: AuthenticatorAttachment;
  residentKey?: ResidentKeyRequirement;
  requireResidentKey?: boolean;
  userVerification?: UserVerificationRequirement;
}

type AttestationConveyancePreference = 'none' | 'indirect' | 'direct' | 'enterprise';

type UserVerificationRequirement = 'required' | 'preferred' | 'discouraged';

type ResidentKeyRequirement = 'discouraged' | 'preferred' | 'required';

// Extension types (these can be any object in practice)
type AuthenticationExtensionsClientInputs = Record<string, any>;

type AuthenticationExtensionsClientOutputs = Record<string, any>;

// Base64URL string type
type Base64URLString = string;