0
# SimpleWebAuthn Browser
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @simplewebauthn/browser
7
- **Package Type**: npm/JSR
8
- **Language**: TypeScript
9
- **Installation**: `npm install @simplewebauthn/browser` or `deno add jsr:@simplewebauthn/browser`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  startRegistration,
16
  startAuthentication,
17
  browserSupportsWebAuthn,
18
  platformAuthenticatorIsAvailable,
19
  browserSupportsWebAuthnAutofill,
20
  base64URLStringToBuffer,
21
  bufferToBase64URLString,
22
  WebAuthnAbortService,
23
  WebAuthnError,
24
  type WebAuthnErrorCode
25
} from '@simplewebauthn/browser';
26
```
27

28
For UMD (browser):
29
```html
30
<script src="https://unpkg.com/@simplewebauthn/browser/dist/bundle/index.umd.min.js"></script>
31
<!-- Available on global SimpleWebAuthnBrowser object -->
32
```
33

34
## Basic Usage
35

36
```typescript
37
import {
38
  startRegistration,
39
  startAuthentication,
40
  browserSupportsWebAuthn,
41
  type RegistrationResponseJSON,
42
  type AuthenticationResponseJSON
43
} from '@simplewebauthn/browser';
44

45
// Check WebAuthn support
46
if (!browserSupportsWebAuthn()) {
47
  throw new Error('WebAuthn not supported');
48
}
49

50
// Registration flow
51
const registrationResponse: RegistrationResponseJSON = await startRegistration({
52
  optionsJSON: registrationOptionsFromServer
53
});
54

55
// Send registrationResponse to server for verification
56

57
// Authentication flow  
58
const authResponse: AuthenticationResponseJSON = await startAuthentication({
59
  optionsJSON: authenticationOptionsFromServer
60
});
61

62
// Send authResponse to server for verification
63
```
64

65
## Architecture
66

67
SimpleWebAuthn Browser is built around several key components:
68

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

75
## Capabilities
76

77
### WebAuthn Authentication Operations
78

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

81
```typescript { .api }
82
function startRegistration(options: StartRegistrationOpts): Promise<RegistrationResponseJSON>;
83

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

86
interface StartRegistrationOpts {
87
  optionsJSON: PublicKeyCredentialCreationOptionsJSON;
88
  useAutoRegister?: boolean;
89
}
90

91
interface StartAuthenticationOpts {
92
  optionsJSON: PublicKeyCredentialRequestOptionsJSON;
93
  useBrowserAutofill?: boolean;
94
  verifyBrowserAutofillInput?: boolean;
95
}
96
```
97

98
[Authentication Operations](./authentication.md)
99

100
### Helper Functions and Utilities
101

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

104
```typescript { .api }
105
function browserSupportsWebAuthn(): boolean;
106
function platformAuthenticatorIsAvailable(): Promise<boolean>;
107
function browserSupportsWebAuthnAutofill(): Promise<boolean>;
108
function base64URLStringToBuffer(base64URLString: string): ArrayBuffer;
109
function bufferToBase64URLString(buffer: ArrayBuffer): string;
110
```
111

112
[Helper Functions](./helpers.md)
113

114
### Error Handling and Abort Control
115

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

118
```typescript { .api }
119
class WebAuthnError extends Error {
120
  code: WebAuthnErrorCode;
121
  constructor(options: {
122
    message: string;
123
    code: WebAuthnErrorCode;
124
    cause: Error;
125
    name?: string;
126
  });
127
}
128

129
type WebAuthnErrorCode =
130
  | 'ERROR_CEREMONY_ABORTED'
131
  | 'ERROR_INVALID_DOMAIN'
132
  | 'ERROR_INVALID_RP_ID'
133
  | 'ERROR_INVALID_USER_ID_LENGTH'
134
  | 'ERROR_MALFORMED_PUBKEYCREDPARAMS'
135
  | 'ERROR_AUTHENTICATOR_GENERAL_ERROR'
136
  | 'ERROR_AUTHENTICATOR_MISSING_DISCOVERABLE_CREDENTIAL_SUPPORT'
137
  | 'ERROR_AUTHENTICATOR_MISSING_USER_VERIFICATION_SUPPORT'
138
  | 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED'
139
  | 'ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG'
140
  | 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE'
141
  | 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY';
142

143
interface WebAuthnAbortService {
144
  createNewAbortSignal(): AbortSignal;
145
  cancelCeremony(): void;
146
}
147
```
148

149
[Error Handling](./error-handling.md)
150

151
## Core Types
152

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

155
```typescript { .api }
156
// Registration types
157
interface RegistrationResponseJSON {
158
  id: Base64URLString;
159
  rawId: Base64URLString;
160
  response: AuthenticatorAttestationResponseJSON;
161
  authenticatorAttachment?: AuthenticatorAttachment;
162
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
163
  type: PublicKeyCredentialType;
164
}
165

166
// Authentication types
167
interface AuthenticationResponseJSON {
168
  id: Base64URLString;
169
  rawId: Base64URLString;
170
  response: AuthenticatorAssertionResponseJSON;
171
  authenticatorAttachment?: AuthenticatorAttachment;
172
  clientExtensionResults: AuthenticationExtensionsClientOutputs;
173
  type: PublicKeyCredentialType;
174
}
175

176
// Server options (input to browser methods)
177
interface PublicKeyCredentialCreationOptionsJSON {
178
  rp: PublicKeyCredentialRpEntity;
179
  user: PublicKeyCredentialUserEntityJSON;
180
  challenge: Base64URLString;
181
  pubKeyCredParams: PublicKeyCredentialParameters[];
182
  timeout?: number;
183
  excludeCredentials?: PublicKeyCredentialDescriptorJSON[];
184
  authenticatorSelection?: AuthenticatorSelectionCriteria;
185
  attestation?: AttestationConveyancePreference;
186
  extensions?: AuthenticationExtensionsClientInputs;
187
}
188

189
interface PublicKeyCredentialRequestOptionsJSON {
190
  challenge: Base64URLString;
191
  timeout?: number;
192
  rpId?: string;
193
  allowCredentials?: PublicKeyCredentialDescriptorJSON[];
194
  userVerification?: UserVerificationRequirement;
195
  extensions?: AuthenticationExtensionsClientInputs;
196
}
197

198
// Supporting types for options and descriptors
199
interface PublicKeyCredentialUserEntityJSON {
200
  id: string;
201
  name: string;
202
  displayName: string;
203
}
204

205
interface PublicKeyCredentialDescriptorJSON {
206
  id: Base64URLString;
207
  type: PublicKeyCredentialType;
208
  transports?: AuthenticatorTransportFuture[];
209
}
210

211
interface AuthenticatorAttestationResponseJSON {
212
  clientDataJSON: Base64URLString;
213
  attestationObject: Base64URLString;
214
  authenticatorData?: Base64URLString;
215
  transports?: AuthenticatorTransportFuture[];
216
  publicKeyAlgorithm?: COSEAlgorithmIdentifier;
217
  publicKey?: Base64URLString;
218
}
219

220
interface AuthenticatorAssertionResponseJSON {
221
  clientDataJSON: Base64URLString;
222
  authenticatorData: Base64URLString;
223
  signature: Base64URLString;
224
  userHandle?: Base64URLString;
225
}
226

227
// Additional supporting types
228
type AuthenticatorTransportFuture = 
229
  | 'ble' 
230
  | 'cable' 
231
  | 'hybrid' 
232
  | 'internal' 
233
  | 'nfc' 
234
  | 'smart-card' 
235
  | 'usb';
236

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

239
type PublicKeyCredentialType = 'public-key';
240

241
type COSEAlgorithmIdentifier = number;
242

243
// DOM-imported types (from WebAuthn spec)
244
interface PublicKeyCredentialRpEntity {
245
  id?: string;
246
  name: string;
247
}
248

249
interface PublicKeyCredentialParameters {
250
  type: PublicKeyCredentialType;
251
  alg: COSEAlgorithmIdentifier;
252
}
253

254
interface AuthenticatorSelectionCriteria {
255
  authenticatorAttachment?: AuthenticatorAttachment;
256
  residentKey?: ResidentKeyRequirement;
257
  requireResidentKey?: boolean;
258
  userVerification?: UserVerificationRequirement;
259
}
260

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

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

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

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

270
type AuthenticationExtensionsClientOutputs = Record<string, any>;
271

272
// Base64URL string type
273
type Base64URLString = string;
274
```