SimpleWebAuthn

https://simplewebauthn.dev/docs
Admin
SimpleWebAuthn is a pair of complementary libraries that simplify WebAuthn implementation by...
Tokens:40,183
Snippets:294
Trust Score:7.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start the example server with npm start

Source: https://simplewebauthn.dev/docs/advanced/example-project

Starts the example server. After running, the server is available at http://localhost:8000.

```bash
./example/ $> npm start  
```

--------------------------------

### Install dependencies with npm

Source: https://simplewebauthn.dev/docs/advanced/example-project

Installs the required npm packages for the example project.

```bash
./example/ $> npm install  
```

--------------------------------

### Start the server

Source: https://simplewebauthn.dev/docs/advanced/example-project

Run npm start from the example directory to launch the server with HTTPS enabled.

```bash
./example $> npm start  

```

--------------------------------

### Navigate to the example project directory

Source: https://simplewebauthn.dev/docs/advanced/example-project

Changes into the example subdirectory within the SimpleWebAuthn repository.

```bash
./SimpleWebAuthn/ $> cd example  

./example/ $>  
```

--------------------------------

### Install @simplewebauthn/server with Deno

Source: https://simplewebauthn.dev/docs/packages/server

Install the package for Deno v2.4.x and higher using the JSR registry.

```bash
deno add jsr:@simplewebauthn/server
```

--------------------------------

### Install @simplewebauthn/server with npm

Source: https://simplewebauthn.dev/docs/packages/server

Install the package for Node.js LTS 22.x and higher using npm.

```bash
npm install @simplewebauthn/server
```

--------------------------------

### Install with Deno

Source: https://simplewebauthn.dev/docs/packages/browser

Add the package via Deno for Deno v2.4.x and higher.

```bash
deno add jsr:@simplewebauthn/browser
```

--------------------------------

### Install with npm

Source: https://simplewebauthn.dev/docs/packages/browser

Install the package using npm for Node LTS 22.x and higher.

```bash
npm install @simplewebauthn/browser
```

--------------------------------

### Enable FIDO conformance routes in example/.env

Source: https://simplewebauthn.dev/docs/advanced/fido-conformance

Add this environment variable to the example project's .env file to activate additional routes on the /fido route.

```plaintext
ENABLE_CONFORMANCE=true  
```

--------------------------------

### startRegistration()

Source: https://simplewebauthn.dev/docs/packages/browser

Starts the WebAuthn registration process by submitting registration options to the authenticator and returning the authenticator's response. This method is used for new account creation.

```APIDOC
## startRegistration()

### Description
Starts the WebAuthn registration process. It takes registration options (typically generated by the server) and returns the authenticator's response, which should be sent to the server for verification.

### Method
Function call (JavaScript)

### Usage
#### Node/Deno
```javascript
import { startRegistration } from '@simplewebauthn/browser';
```

#### UMD
```javascript
const { startRegistration } = SimpleWebAuthnBrowser;
```

### Parameters
- **optionsJSON** (object) - Required - The registration options object, typically obtained from the server's `generateRegistrationOptions()` endpoint.

### Returns
- **attResp** (object) - The authenticator's response, which should be sent to the server for verification.

### Example
```javascript
const attResp = await startRegistration({ optionsJSON });
```

### Error Handling
- If the authenticator is already registered, an `InvalidStateError` may be thrown.

### Full Example (Plain HTML with UMD)
```html
<script>
  const { startRegistration } = SimpleWebAuthnBrowser;

  const elemBegin = document.getElementById('btnBegin');
  const elemSuccess = document.getElementById('success');
  const elemError = document.getElementById('error');

  elemBegin.addEventListener('click', async () => {
    elemSuccess.innerHTML = '';
    elemError.innerHTML = '';

    const resp = await fetch('/generate-registration-options');
    const optionsJSON = await resp.json();

    let attResp;
    try {
      attResp = await startRegistration({ optionsJSON });
    } catch (error) {
      if (error.name === 'InvalidStateError') {
        elemError.innerText = 'Error: Authenticator was probably already registered by user';
      } else {
        elemError.innerText = error;
      }
      throw error;
    }

    const verificationResp = await fetch('/verify-registration', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(attResp),
    });

    const verificationJSON = await verificationResp.json();

    if (verificationJSON && verificationJSON.verified) {
      elemSuccess.innerHTML = 'Success!';
    } else {
      elemError.innerHTML = `Oh no, something went wrong! Response: <pre>${JSON.stringify(verificationJSON)}</pre>`;
    }
  });
</script>
```
```

--------------------------------

### Expected server console output

Source: https://simplewebauthn.dev/docs/advanced/fido-conformance

When the example server is ready for testing, you should see this console output, indicating the metadata service initialized with 20 local statements and the FIDO conformance routes are ready.

```plaintext
🚀 Server ready at http://0.0.0.0:8000  

ℹ️ Initializing metadata service with 20 local statements  

🔐 FIDO Conformance routes ready  
```

--------------------------------

### Clone the SimpleWebAuthn repository with git

Source: https://simplewebauthn.dev/docs/advanced/example-project

Clones the SimpleWebAuthn codebase from GitHub. Use this to download the example project.

```bash
$> git clone https://github.com/MasterKale/SimpleWebAuthn.git  
```

--------------------------------

### Enable HTTPS via .env

Source: https://simplewebauthn.dev/docs/advanced/example-project

Add this environment variable to the .env file to enable HTTPS for the example project.

```env
ENABLE_HTTPS=true  

```

--------------------------------

### Fix startRegistration() optionsJSON TypeError

Source: https://simplewebauthn.dev/docs/packages/browser

Shows the correct way to call startRegistration() in SimpleWebAuthn v11.0.0 and later. Options must be wrapped in an object with the optionsJSON property, not passed directly. The before and after examples are shown together.

```javascript
// Before  

const response = await startRegistration(options, ...);  

  

// After  

const response = await startRegistration({ optionsJSON: options, ... });  


```

```javascript
// Before  

const response = await startAuthentication(options, ...);  

  

// After  

const response = await startAuthentication({ optionsJSON: options, ... });  


```

--------------------------------

### Use platformAuthenticatorIsAvailable to conditionally prompt for platform authenticators

Source: https://simplewebauthn.dev/docs/packages/browser

Example script that checks if a platform authenticator is available and then prompts the user accordingly. The script uses the UMD global and an async IIFE.

```html
<script>  
  const { platformAuthenticatorIsAvailable } = SimpleWebAuthnBrowser;  

  (async () => {  
    if (await platformAuthenticatorIsAvailable()) {  
      /**  
       * Prompt the user to use Touch ID/Windows Hello/etc... or security keys to register or  
       * authenticate  
       *  
       * How to decide which name to show for the device's platform authenticator is an exercise  
       * left up to the developer (your best bet is User Agent analysis)  
       */  
    } else {  
      /**  
       * Only prompt the user to use security keys to register or authenticate  
       */  
    }  
  })();  
</script>
```

--------------------------------

### Initialize MetadataService with custom MDS servers and local statements

Source: https://simplewebauthn.dev/docs/advanced/server/metadata-service

Initializes MetadataService with optional URLs to other MDS-compatible servers and local metadata statements. The example loads JSON files from a directory and passes them as statements. After initialization, verifyRegistrationResponse() will reference MDS metadata and error on unexpected authenticator responses.

```typescript
import { MetadataService, MetadataStatement } from '@simplewebauthn/server';  

  

const statements: MetadataStatement[] = [];  

  

// Load in statements from JSON files  

try {  

  const mdsMetadataPath = './metadata-statements';  

  const mdsMetadataFilenames = fs.readdirSync(mdsMetadataPath);  

  for (const statementPath of mdsMetadataFilenames) {  

    if (statementPath.endsWith('.json')) {  

      const contents = fs.readFileSync(`${mdsMetadataPath}/${statementPath}`, 'utf-8');  

      statements.push(JSON.parse(contents));  

    }  

  }  

} catch (err) {  

  // pass  

}  

  

MetadataService.initialize({  

  mdsServers: ['https://mds-compatible-server.example.com'],  

  statements: statements,  

}).then(() => {  

  console.log('🔐 MetadataService initialized');  

});  
```

--------------------------------

### Use getBrowserCapabilities to check WebAuthn capabilities

Source: https://simplewebauthn.dev/docs/packages/browser

Example of calling getBrowserCapabilities() and logging the returned capability values. The method returns an object with keys like conditionalGet, hybridTransport, and passkeyPlatformAuthenticator, each mapped to 'supported', 'unsupported', or 'unknown'.

```javascript
const {  
  conditionalGet,  
  hybridTransport,  
  passkeyPlatformAuthenticator,  
} = await getBrowserCapabilities();  

console.log(hybridTransport); // 'supported'  
console.log(conditionalGet); // 'unsupported'  
console.log(passkeyPlatformAuthenticator); // 'unknown'
```

--------------------------------

### Generate registration options with generateRegistrationOptions()

Source: https://simplewebauthn.dev/docs/packages/server

Example endpoint code that returns the result of generateRegistrationOptions(). It retrieves the user and their existing passkeys, then generates options with attestationType 'none', excludeCredentials to prevent re-registration, and authenticatorSelection defaults. The options are passed directly to @simplewebauthn/browser's startRegistration().

```typescript
// (Pseudocode) Retrieve the user from the database  

// after they've logged in  

const user: UserModel = getUserFromDB(loggedInUserId);  

// (Pseudocode) Retrieve any of the user's previously-  

// registered authenticators  

const userPasskeys: Passkey[] = getUserPasskeys(user);  

  

const options: PublicKeyCredentialCreationOptionsJSON = await generateRegistrationOptions({  
  rpName,  
  rpID,  
  userName: user.username,  
  // Don't prompt users for additional information about the authenticator  
  // (Recommended for smoother UX)  
  attestationType: 'none',  
  // Prevent users from re-registering existing authenticators  
  excludeCredentials: userPasskeys.map(passkey => ({  
    id: passkey.id,  
    // Optional  
    transports: passkey.transports,  
  })),  
  // See "Guiding use of authenticators via authenticatorSelection" below  
  authenticatorSelection: {  
    // Defaults  
    residentKey: 'preferred',  
    userVerification: 'preferred',  
    // Optional  
    authenticatorAttachment: 'platform',  
  },  
});  

  

// (Pseudocode) Remember these options for the user  

setCurrentRegistrationOptions(user, options);  

  

return options;  
```

--------------------------------

### Firefox verifyRegistrationResponse returns false for Ed25519

Source: https://simplewebauthn.dev/docs/advanced/browser-quirks

Example showing that verifyRegistrationResponse() returns false for Ed25519 responses in Firefox, even when the same setup works in other browsers. This is due to a bug resolved in Firefox 119.

```javascript
const verifiedFirefox = await verifyRegistrationResponse({ ... });  

console.log(verifiedFirefox.verified); // false  
```

--------------------------------

### Import startRegistration for Node/Deno

Source: https://simplewebauthn.dev/docs/packages/browser

Shows the standard import for the startRegistration method in Node.js or Deno environments. Use this to begin the registration flow.

```javascript
import { startRegistration } from '@simplewebauthn/browser';
```

--------------------------------

### Cancel a pending WebAuthn ceremony with WebAuthnAbortService

Source: https://simplewebauthn.dev/docs/packages/browser

Use WebAuthnAbortService.cancelCeremony() to manually cancel a pending WebAuthn request, for example when leaving a login page in a SPA. The example shows startAuthentication() with useBrowserAutofill and handling the 'ERROR_CEREMONY_ABORTED' error code.

```javascript
import {  

  startAuthentication,  

  WebAuthnAbortService,  

  WebAuthnError,  

} from '@simplewebauthn/browser';  

  

// On mount, the component triggers conditional UI  

useEffect(() => {  

  try {  

    const response = await startAuthentication({ ..., useBrowserAutofill: true });  

  } catch (err) {  

    if (err instanceof WebAuthnError && err.code === 'ERROR_CEREMONY_ABORTED') {  

      // Error can safely be ignored  

    } else {  

      // Something else went wrong  

    }  

  }  

}, []);  

  

function handleLeavePage() {  

  // Cancel the pending WebAuthn request before leaving the login page  

  WebAuthnAbortService.cancelCeremony();  

}  
```

--------------------------------

### Update rpID in index.ts

Source: https://simplewebauthn.dev/docs/advanced/example-project

Set the rpID to your custom domain in the example/index.ts file to match the HTTPS setup.

```typescript
const rpID = 'dev.example.com';  

```

--------------------------------

### Access startRegistration via UMD global

Source: https://simplewebauthn.dev/docs/packages/browser

Shows how to access startRegistration when using the UMD build, where the library is available as the global SimpleWebAuthnBrowser.

```javascript
const { startRegistration } = SimpleWebAuthnBrowser;
```

--------------------------------

### Auto Register with startRegistration and useAutoRegister: true

Source: https://simplewebauthn.dev/docs/packages/browser

HTML page with JavaScript that fetches registration options and calls startRegistration with useAutoRegister: true after a successful login. Errors should be ignored as auto upgrade is opportunistic. If successful, the response may have the User Presence bit false, so specify requireUserPresence: false when verifying with @simplewebauthn/server's verifyRegistrationResponse().

```html
<!-- completedPasswordLogin.html -->  

<body>  

  <!-- Typical landing page the user ends up on after login goes here -->  

  <script>  
    const { startRegistration } = SimpleWebAuthnBrowser;  

    /**  
     * Get options then call `startRegistration()`. Errors should be ignored  
     * as auto upgrade is considered "opportunistic" and can fail more easily  
     * than other such WebAuthn calls if the browser is not satisfied that all  
     * requirements have been met.  
     */  
    fetch('/generate-registration-options')  
      .then(resp => resp.json())  
      .then((optionsJSON) => {  
        // Note the `useAutoRegister: true` argument here  
        startRegistration({ optionsJSON, useAutoRegister: true })  
          .then(regResp => sendToServerForVerification)  
          .catch(err => handleError);  
      });  
  </script>  
</body>  
```

--------------------------------

### Import startAuthentication in Node/Deno

Source: https://simplewebauthn.dev/docs/packages/browser

Import the startAuthentication function from @simplewebauthn/browser in a Node.js or Deno environment.

```javascript
import { startAuthentication } from '@simplewebauthn/browser';
```

--------------------------------

### Import browserSupportsPasskeys (Node/Deno)

Source: https://simplewebauthn.dev/docs/packages/browser

Import the browserSupportsPasskeys function from @simplewebauthn/browser in a Node/Deno environment.

```javascript
import { browserSupportsPasskeys } from '@simplewebauthn/browser';
```

--------------------------------

### sendSignal() - allAcceptedCredentials

Source: https://simplewebauthn.dev/docs/packages/browser

Sends a signal with the current list of passkeys the Relying Party will recognize for the authenticated user on the next login. Should be sent periodically, for example after every successful authentication.

```APIDOC
## sendSignal() - allAcceptedCredentials

### Description
Sends a signal to the credential manager with the current list of passkeys the Relying Party will recognize for the authenticated user on the next login. This should be sent periodically, for example after every successful authentication.

### Method
sendSignal()

### Parameters
#### Options (SendSignalAllAcceptedCredentialsOpts)
- **signalName** (string) - Required - Must be set to 'allAcceptedCredentials'.
- **rpID** (string) - Required - The Relying Party ID (e.g., 'example.com').
- **userID** (string) - Required - The user ID. Must match the `options.user.id` used in `generateRegistrationOptions()` from @simplewebauthn/server.
- **allAcceptedCredentialIDs** (string[]) - Required - Array of credential IDs that the Relying Party accepts.

### Request Example
```typescript
import { sendSignal, type SendSignalAllAcceptedCredentialsOpts } from '@simplewebauthn/browser';

const opts: SendSignalAllAcceptedCredentialsOpts = {
  signalName: 'allAcceptedCredentials',
  rpID: 'example.com',
  userID: 'Lrk2ki-arSSFcm6PPlMKEQ',
  allAcceptedCredentialIDs: ['d77Hxqvltn66l7hegq_E3Q', 'nz_ajzNrMq3KfPrkOt3lHQ'],
};

await sendSignal(opts);
```

### Response
No response details are provided in the source.
```

--------------------------------

### Fix for 'Error: No data' by converting Binary public key to Uint8Array

Source: https://simplewebauthn.dev/docs/packages/server

Example of converting a MongoDB Binary public key to a Uint8Array using new Uint8Array(credentialPublicKey.buffer) before passing it to verifyAuthenticationResponse().

```javascript
const verification = await verifyAuthenticationResponse({  

  // ...  

  credential: {  

    // ...  

    publicKey: new Uint8Array(credentialPublicKey.buffer),  

  },  

});  


```

--------------------------------

### Change directory to SimpleWebAuthn

Source: https://simplewebauthn.dev/docs/advanced/example-project

Navigates into the cloned repository directory.

```bash
$> cd SimpleWebAuthn  

./SimpleWebAuthn/ $>  
```

--------------------------------

### Enable browser autofill with startAuthentication()

Source: https://simplewebauthn.dev/docs/packages/browser

Sets up conditional UI by calling startAuthentication() with useBrowserAutofill: true. Requires an <input> element with autocomplete="webauthn" on the page; otherwise startAuthentication() errors. Place this logic in <head> to give browsers time to query authenticators.

```html
<head>  

  <!-- ... -->  

  <script>  

    const { startAuthentication } = SimpleWebAuthnBrowser;  

  

    fetch('/generate-authentication-options')  

      .then(resp => resp.json())  

      .then((optionsJSON) => {  

        // Note the `useBrowserAutofill: true` argument here  

        startAuthentication({ optionsJSON, useBrowserAutofill: true })  

          .then(authResp => sendToServerForVerificationAndLogin)  

          .catch(err => handleError);  

      });  

  </script>  

</head>  

<body>  

  <!-- ... -->  

  <label for="username">Username</label>  

  <input type="text" name="username" autocomplete="webauthn">  


```

--------------------------------

### sendSignal() - currentUserDetails

Source: https://simplewebauthn.dev/docs/packages/browser

Sends a signal with the authenticated user's current name and display name. Should be sent periodically, for example after every successful authentication and immediately after user details change.

```APIDOC
## sendSignal() - currentUserDetails

### Description
Sends a signal to the credential manager with the authenticated user's current name and display name. This should be sent periodically, for example after every successful authentication and immediately after the user's name or display name changes.

### Method
sendSignal()

### Parameters
#### Options (SendSignalCurrentUserDetailsOpts)
- **signalName** (string) - Required - Must be set to 'currentUserDetails'.
- **rpID** (string) - Required - The Relying Party ID (e.g., 'example.com').
- **userID** (string) - Required - The user ID. Must match the `options.user.id` used in `generateRegistrationOptions()` from @simplewebauthn/server.
- **userName** (string) - Required - The user's new username.
- **userDisplayName** (string) - Required - The user's new display name.

### Request Example
```typescript
import { sendSignal, type SendSignalCurrentUserDetailsOpts } from '@simplewebauthn/browser';

const opts: SendSignalCurrentUserDetailsOpts = {
  signalName: 'currentUserDetails',
  rpID: 'example.com',
  userID: 'Lrk2ki-arSSFcm6PPlMKEQ',
  userName: 'newUsername@example.com',
  userDisplayName: 'NewUsername (Prod)',
};

await sendSignal(opts);
```

### Response
No response details are provided in the source.
```

--------------------------------

### Fix for 'extractStrings is not a function' by injecting CBOR_NATIVE_ACCELERATION_DISABLED

Source: https://simplewebauthn.dev/docs/packages/server

JavaScript function to set process.env['CBOR_NATIVE_ACCELERATION_DISABLED'] = 'true' to disable require() in cbor-x, fixing the error when using @vercel/ncc. Call this at the start of the project before any imports.

```javascript
function nodeEnvInjection() {  

  /**  

   * `@vercel/ncc` does not support the use of `require()` so disable its  

   * use in the `@simplewebauthn/server` dependency called `cbor-x`.  

   *  

   * https://github.com/kriszyp/cbor-x/blob/master/node-index.js#L10  

   */  

  process.env['CBOR_NATIVE_ACCELERATION_DISABLED'] = 'true';  

}  

  

// Call this at the start of the project, before any imports  

nodeEnvInjection()  


```

--------------------------------

### Generate SSL certificates with certbot

Source: https://simplewebauthn.dev/docs/advanced/example-project

Run this certbot command to generate SSL certificates for dev.example.com using DNS challenges. The certificates are valid for 90 days; re-run the command to renew.

```bash
$> sudo certbot --manual -d dev.example.com --preferred-challenges dns certonly  

```

--------------------------------

### Complete registration flow in plain JavaScript

Source: https://simplewebauthn.dev/docs/packages/browser

A full front-end implementation for WebAuthn registration using the UMD build. It fetches registration options, calls startRegistration(), and posts the response for verification. Includes error handling for InvalidStateError and displays success or error messages.

```html
<script>  

  const { startRegistration } = SimpleWebAuthnBrowser;  

  

  // <button>  

  const elemBegin = document.getElementById('btnBegin');  

  // <span>/<p>/etc...  

  const elemSuccess = document.getElementById('success');  

  // <span>/<p>/etc...  

  const elemError = document.getElementById('error');  

  

  // Start registration when the user clicks a button  

  elemBegin.addEventListener('click', async () => {  

    // Reset success/error messages  

    elemSuccess.innerHTML = '';  

    elemError.innerHTML = '';  

  

    // GET registration options from the endpoint that calls  

    // @simplewebauthn/server -> generateRegistrationOptions()  

    const resp = await fetch('/generate-registration-options');  

    const optionsJSON = await resp.json();  

  

    let attResp;  

    try {  

      // Pass the options to the authenticator and wait for a response  

      attResp = await startRegistration({ optionsJSON });  

    } catch (error) {  

      // Some basic error handling  

      if (error.name === 'InvalidStateError') {  

        elemError.innerText = 'Error: Authenticator was probably already registered by user';  

      } else {  

        elemError.innerText = error;  

      }  

  

      throw error;  

    }  

  

    // POST the response to the endpoint that calls  

    // @simplewebauthn/server -> verifyRegistrationResponse()  

    const verificationResp = await fetch('/verify-registration', {  

      method: 'POST',  

      headers: {  

        'Content-Type': 'application/json',  

      },  

      body: JSON.stringify(attResp),  

    });  

  

    // Wait for the results of verification  

    const verificationJSON = await verificationResp.json();  

  

    // Show UI appropriate for the `verified` status  

    if (verificationJSON && verificationJSON.verified) {  

      elemSuccess.innerHTML = 'Success!';  

    } else {  

      elemError.innerHTML = `Oh no, something went wrong! Response: <pre>${JSON.stringify(  

        verificationJSON,  

      )}</pre>`;  

    }  

  });  

</script>
```

--------------------------------

### Generate authentication options with generateAuthenticationOptions()

Source: https://simplewebauthn.dev/docs/packages/server

Endpoint (GET) that generates authentication options for a user. It retrieves the user and their passkeys, then calls generateAuthenticationOptions() with rpID and allowCredentials. The challenge must be saved for later verification.

```typescript
// (Pseudocode) Retrieve the user record for the account identifier (email, username, etc...) that  

// the unauthenticated user entered  

const user: UserModel = getUserFromDBByUsername(submittedUsername);  

// (Pseudocode) Retrieve any of the user's previously-  

// registered authenticators  

const userPasskeys: Passkey[] = getUserPasskeys(user);  

  

const options: PublicKeyCredentialRequestOptionsJSON = await generateAuthenticationOptions({  

  rpID,  

  // Require users to use a previously-registered authenticator  

  allowCredentials: userPasskeys.map(passkey => ({  

    id: passkey.id,  

    transports: passkey.transports,  

  })),  

});  

  

// (Pseudocode) Remember this challenge for this user  

setCurrentAuthenticationOptions(user, options);  

  

return options;  


```

--------------------------------

### Import startAuthentication in UMD

Source: https://simplewebauthn.dev/docs/packages/browser

Access the startAuthentication function from the SimpleWebAuthnBrowser global when using the UMD build.

```javascript
const { startAuthentication } = SimpleWebAuthnBrowser;
```

--------------------------------

### Import browserSupportsWebAuthn (Node/Deno)

Source: https://simplewebauthn.dev/docs/packages/browser

Import the browserSupportsWebAuthn function from @simplewebauthn/browser in a Node/Deno environment.

```javascript
import { browserSupportsWebAuthn } from '@simplewebauthn/browser';
```

--------------------------------

### Catch WebAuthnError from startRegistration

Source: https://simplewebauthn.dev/docs/packages/browser

Use WebAuthnError with instanceof to distinguish SimpleWebAuthn library errors from other errors. The error has name, message, code, and cause properties; cause holds the original WebAuthn error from navigator.credentials.create() or get().

```javascript
import { startRegistration, WebAuthnError } from '@simplewebauthn/browser';  

  

try {  

  const response = await startRegistration({ ... });  

} catch (err) {  

  if (err instanceof WebAuthnError) {  

    // See `name`, `message`, `code`, and `cause` for more info  

  } else {  

    // Something else went wrong  

  }  

}  
```

--------------------------------

### Initialize MetadataService with custom logger

Source: https://simplewebauthn.dev/docs/advanced/server/metadata-service

Shows how to pass a custom logger to initialize() that matches the SimpleWebAuthnLogger interface. The logger captures status output from MetadataService. Each log level is of type (message: string, ...args: unknown[]) => void.

```typescript
import { MetadataService } from '@simplewebauthn/server';  

import { type SimpleWebAuthnLogger } from '@simplewebauthn/server/helpers';  

  

// A custom logger in its simplest form  

const logger: SimpleWebAuthnLogger = {  

  debug: console.log,  

  info: console.log,  

  warn: console.warn,  

  error: console.error,  

};  

  

MetadataService.initialize({ logger }).then(() => {  

  console.log('🔐 MetadataService initialized');  

});  
```

--------------------------------

### Send allAcceptedCredentials signal with sendSignal()

Source: https://simplewebauthn.dev/docs/packages/browser

Use this snippet to communicate the current list of passkeys the Relying Party will accept for the authenticated user. Send it periodically, for example after every successful authentication. The userID must match the options.user.id used during registration.

```typescript
import { sendSignal, type SendSignalAllAcceptedCredentialsOpts } from '@simplewebauthn/browser';  

const opts: SendSignalAllAcceptedCredentialsOpts = {  
  signalName: 'allAcceptedCredentials',  
  rpID: 'example.com',  
  userID: 'Lrk2ki-arSSFcm6PPlMKEQ',  
  allAcceptedCredentialIDs: ['d77Hxqvltn66l7hegq_E3Q', 'nz_ajzNrMq3KfPrkOt3lHQ'],  
};  

await sendSignal(opts);  
```

--------------------------------

### Convert userHandle bytes back to UTF-8 string for authentication

Source: https://simplewebauthn.dev/docs/advanced/server/custom-user-ids

Use isoBase64URL.toUTF8String() to convert the base64url-encoded userHandle from the WebAuthn response back into the original UTF-8 string. The example logs the converted value, which should match the custom user ID used during registration.

```javascript
import { isoBase64URL } from '@simplewebauthn/server/helpers';  

const credential = await receiveFromBrowser();  
console.log(  
  isoBase64URL.toUTF8String(credential.response.userhandle), // 'customUserIDHere'  
);  
```

--------------------------------

### Import getBrowserCapabilities

Source: https://simplewebauthn.dev/docs/packages/browser

Import the getBrowserCapabilities helper method from @simplewebauthn/browser.

```javascript
import { getBrowserCapabilities } from '@simplewebauthn/browser';
```

--------------------------------

### SettingsService.runtimeSupportsPQC()

Source: https://simplewebauthn.dev/docs/advanced/server/settings-service

Returns a boolean indicating if the runtime supports use of ML-DSA-44. This is a strong signal that the runtime generally supports ML-DSA-65 and ML-DSA-87 operations as well.

```APIDOC
## SettingsService.runtimeSupportsPQC()

### Description
Returns a boolean indicating if the runtime supports use of ML-DSA-44. This is a strong signal that the runtime generally supports ML-DSA-65 and ML-DSA-87 operations as well.

### Method
runtimeSupportsPQC

### Endpoint
SettingsService.runtimeSupportsPQC()

### Parameters
None.

### Request Example
```js
import { SettingsService } from '@simplewebauthn/server';

const canUsePQC: boolean = SettingsService.runtimeSupportsPQC();
```

### Response
#### Success Response
- **boolean** (boolean) - True if the runtime supports ML-DSA-44, false otherwise.

### Notes
- Runtime support is determined on startup, when SettingsService is automatically initialized.
```

--------------------------------

### Custom debug handler for SimpleWebAuthnLogger

Source: https://simplewebauthn.dev/docs/advanced/server/metadata-service

Example of a custom debug handler that sends log messages to a third-party SaaS API. The handler matches the required call signature (message: string, ...args: unknown[]) => void. SimpleWebAuthnLogger does not require every logging level to be defined.

```typescript
function handleLogDebug(message: string, ...args: unknown[]): void {  

  CustomLoggingSDK.log('DEBUG', message, ...args);  

}  

  

const logger: SimpleWebAuthnLogger = {  

  debug: handleLogDebug,  

}  
```

--------------------------------

### startAuthentication() with Browser Autofill

Source: https://simplewebauthn.dev/docs/packages/browser

Enables credential selection via the browser's native autofill popup by passing useBrowserAutofill: true. Requires an input element with autocomplete="webauthn".

```APIDOC
## startAuthentication() with Browser Autofill

### Description
Calling `startAuthentication({ ..., useBrowserAutofill: true })` sets up support for credential selection via the browser's native autofill popup. The `"webauthn"` value in the `autocomplete` attribute is required for autofill to work.

### Method
startAuthentication()

### Parameters
#### Options Object
- **optionsJSON** (object) - Required - The authentication options JSON from the server.
- **useBrowserAutofill** (boolean) - Required - Set to `true` to enable browser autofill (conditional UI).
- **verifyBrowserAutofillInput** (boolean) - Optional - Set to `false` to bypass the error when a suitable `<input>` element cannot be found.

### Request Example
```javascript
startAuthentication({
  optionsJSON,
  useBrowserAutofill: true,
  verifyBrowserAutofillInput: false,
})
  .then(...)
```

### Response
Returns a Promise that resolves with the authentication response, which can be submitted to the server for verification.

### Notes
- The `"webauthn"` value in the `autocomplete` attribute is required for autofill to work.
- `"webauthn"` can be combined with other autocomplete values, but must appear at the end.
- The pending WebAuthn request is automatically cancelled on a subsequent execution of `startAuthentication()`.
```

--------------------------------

### Import registration methods from @simplewebauthn/server

Source: https://simplewebauthn.dev/docs/packages/server

Imports the two methods needed for registration: generateRegistrationOptions and verifyRegistrationResponse. These are used in the two-step registration flow.

```javascript
import {  
  generateRegistrationOptions,  
  verifyRegistrationResponse,  
} from '@simplewebauthn/server';  

```

--------------------------------

### Send currentUserDetails signal with sendSignal()

Source: https://simplewebauthn.dev/docs/packages/browser

Use this snippet to communicate changes in the authenticated user's name or display name. Send it periodically, for example after every successful authentication and immediately after the user's name or display name changes. The userID must match the options.user.id used during registration.

```typescript
import { sendSignal, type SendSignalCurrentUserDetailsOpts } from '@simplewebauthn/browser';  

const opts: SendSignalCurrentUserDetailsOpts = {  
  signalName: 'currentUserDetails',  
  rpID: 'example.com',  
  userID: 'Lrk2ki-arSSFcm6PPlMKEQ',  
  userName: 'newUsername@example.com',  
  userDisplayName: 'NewUsername (Prod)',  
};  

await sendSignal(opts);  
```

--------------------------------

### runtimeSupportsPQC() - Check runtime support for ML-DSA-44

Source: https://simplewebauthn.dev/docs/advanced/server/settings-service

Returns a boolean indicating if the runtime supports use of ML-DSA-44. This is a strong signal that the runtime generally supports ML-DSA-65 and ML-DSA-87 operations as well. Runtime support is determined on startup, when SettingsService is automatically initialized.

```typescript
import { SettingsService } from '@simplewebauthn/server';  

const canUsePQC: boolean = SettingsService.runtimeSupportsPQC();  
```

--------------------------------

### Import browserSupportsWebAuthnAutofill (Node/Deno)

Source: https://simplewebauthn.dev/docs/packages/browser

Import the browserSupportsWebAuthnAutofill function from @simplewebauthn/browser in a Node/Deno environment.

```javascript
import { browserSupportsWebAuthnAutofill } from '@simplewebauthn/browser';
```
Tokens:
Raw