masterkale / simplewebauthn

WebAuthn, Simplified. A collection of TypeScript-first libraries for simpler WebAuthn integration. Supports modern browsers, Node, Deno, and more.

SimpleWebAuthn Project

• Overview
• Installation
• Example
• Contributions
• Development

Overview

This monorepo contains two complimentary libraries to help reduce the amount of work needed to incorporate WebAuthn into a website. The following packages are maintained here:

• @simplewebauthn/server
• @simplewebauthn/browser

An additional package is also included that contains shared TypeScript definitions:

• @simplewebauthn/types

See these packages' READMEs for more specific implementation information.

API Documentation

In-depth documentation for all of the packages in this project is available here: https://simplewebauthn.dev/docs/

Installation

These packages are all available on npm for use in Node LTS 20.x projects and supports both CommonJS and ECMAScript modules (ESM):

npm install @simplewebauthn/browser
npm install @simplewebauthn/server
npm install @simplewebauthn/types

The server and types packages are also available for import into Deno v1.33.x projects from deno.land/x:

import {...} from 'https://deno.land/x/simplewebauthn/deno/server.ts';
import type {...} from 'https://deno.land/x/simplewebauthn/deno/types.ts';

Example

For a practical guide to implementing these libraries, take a look at the example project. It includes a single-file Express server and a few HTML files that, combined with the packages in this repo, are close to all it takes to get up and running with WebAuthn.

Contributions

The SimpleWebAuthn project is not currently open to external contributions.

Please submit an Issue and fill out the provided template with as much information as possible if you have found a bug in need of fixing.

You can also submit an Issue to request new features, or to suggest changes to existing features.

Development

Install the following before proceeding:

• Node.js 18.x
• Deno 1.41.x
• pnpm 8.6.x

After pulling down the code, set up dependencies:

$> pnpm run bootstrap-monorepo

To run unit tests for all workspace packages, use the test series of scripts:

# Run All tests
$> pnpm run test
# Run an individual package's tests
$> pnpm run test:browser
$> pnpm run test:server

Tests can be run in watch mode with the dev series of scripts:

$> pnpm run dev:browser
$> pnpm run dev:server

simplewebauthn's Issues

Inconsistent serviceName

Hi, it is small but breaking change.

It is inconsistent to have serviceName property name. It should be rpName by similarity with rpID and user* properties. Also rpName is close to specification.

I think it is ok to have that change for 1.0.0 release 😉

Simplify example

It is possible to simplify example by removing SSL cert and key pair because browser treats requests to localhost at any port as secure connection in term of WebAuthn. https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API

Passwordless: Possibility to skip allowCredentials

In password less use case it's pretty hard to know in advance user ID. I remember that if we call navigator.credentials without allowCredentials, the browser can ask which Public Key the user wants to use (and display userName) if multiple public keys exists.

I saw that currently the lib require allowCredentials. Is there any security issue by allowing empty allowCredentials.

An alternative method could be to use localStorage to save the userId, but it need an additional front user selection system. I think it's also not safe since local storage can be cleared.

Interface for checking assertion flags

Hello! I hope all is well! I was wondering if you could answer this question for me, i couldnt see anything explicit in the documentation.

I have found that not all browsers fully respect requiring user verification, examples being most major browsers on androids. Does SimpleWebAuthn support explicit checks for either the UV or the UP flag?

Something along the lines of 'assertionResponse.isUserVerified' or 'isUserPresenceVerified', etc, etc. Just to allow some additional control on how a server can response to settings of UV = required, but UV not being true in the response.

Thank you!

NPM docs contain broken links

The following links to subfolders in the repo work on Github, but not on the packages' NPM listings:

https://www.npmjs.com/package/@simplewebauthn/browser

• "Check out the example's public/ folder for a practical implementation of this library."
• The Homepage link on the right sidebar

https://www.npmjs.com/package/@simplewebauthn/server

• "Check out the example's index.js for a practical implementation of this library."
• The Homepage link on the right sidebar

https://www.npmjs.com/package/@simplewebauthn/typescript-types

• "TypeScript typings for @simplewebauthn/server and @simplewebauthn/browser"
• The Homepage link on the right sidebar

The issue is that the various READMEs were originally authored expecting to only be viewed on Github. I need to figure out what my strategy is for including these kinds of relative links in READMEs so that they work on NPM too.

Maybe I just don't include relative links...?

Can't include browser package with webpack

My code:

const { SimpleWebAuthnBrowser } = require('@simplewebauthn/browser');

Error:

ERROR in ./node_modules/@simplewebauthn/browser/dist/simplewebauthn-browser.min.js
Module parse failed: Unexpected token (2:2177)
You may need an appropriate loader to handle this file type.
| // [@webauthentine/browser]  Version: 0.9.0 - Wednesday, September 9th, 2020, 11:12:48 PM  

Perhaps, webpack is old, but everything else works.

    "webpack-dev-server": "^2.8.1",

I think it's because of triple dots. Any ideas how to fix it?

Unexpected token 'export'

I just updated the '@simplewebauthn/browser' dependency in my NUXT project (from ^3.0.0 to ^3.1.0) and now the pages that require startAttestation from the @simplewebauthn/browser package no longer render.

I get the following error:
webpack:/external "@simplewebauthn/browser"
Missing stack framesJS
Object.@simplewebauthn/browser@1:

(https://prnt.sc/17aah2p)

I don't know how to further debug this error. Let me know if I can provide more information on this error.

Custom handler for expectedOrigin and expectedRPID

Hello,

As a followup of #90, when using a browser extension, having multiple origin/rpID possible was really cool but we got into facing another issue which is that some browsers like Firefox are using random IDs for their extensions that means it's impossible to maintain a hard-coded list of origins/rpID.

For instance here is the way to validate a FF origin:

    const originIsMozillaExtension = origin.match(
        /^moz-extension:\/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
    );

I know it's yet another addition but would you allow to have a custom function handler to validate origins and rpIDs?
Let me know if you have a better solution but I guess anyone using SWA with browser extension will face this issue.

Pass the conformance test tools

You guys should do this and become "compliant"! https://fidoalliance.org/certification/functional-certification/conformance/

verifyAssertionResponse on TPM returns wrong tag error

Registration process was set with requireResidentKey: true and userVerification: "preferred".
I registered successfully using my computer PIN code but on login, after entring my PIN code I've got the following error:
error:0D0680A8:asn1 encoding routines:asn1_check_tlen:wrong tag

Am I missing something in my assertion config, or even something is missing or wrong I'm carrying from registration?

Fix broken Netlify deploy

For some reason after migrating the example project to TypeScript in PR #71 Netlify started having issues with npm run docs:

7:46:23 AM: Now using node v12.19.1 (npm v6.14.8)
# ...snip...
7:46:43 AM: $ npm run docs
# ...snip...
7:47:24 AM: Loaded plugin /opt/build/repo/typedoc-plugin-external-module-name
7:47:24 AM: Using TypeScript 3.9.7 from /opt/build/repo/node_modules/typescript/lib
7:47:32 AM: Error: /opt/build/repo/example/fido-conformance.ts(12)
7:47:32 AM:  Cannot find module '@simplewebauthn/server/dist/metadata/metadataService' or its corresponding type declarations.
7:47:32 AM: Error: /opt/build/repo/example/index.ts(11)
7:47:32 AM:  Cannot find module 'dotenv' or its corresponding type declarations.
7:47:32 AM: npm ERR! code ELIFECYCLE
7:47:32 AM: npm ERR! errno 4
7:47:32 AM: npm ERR! simplewebauthn-monorepo@ docs: `npm run bootstrap && typedoc --tsconfig tsconfigdoc.json`
7:47:32 AM: npm ERR! Exit status 4
7:47:32 AM: npm ERR!
7:47:32 AM: npm ERR! Failed at the simplewebauthn-monorepo@ docs script.
7:47:32 AM: npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
7:47:32 AM: npm ERR! A complete log of this run can be found in:
7:47:32 AM: npm ERR!     /opt/buildhome/.npm/_logs/2020-11-17T15_47_32_501Z-debug.log

https://app.netlify.com/sites/simplewebauthn/deploys/5fb3f00102e84400084e2ef4 (I probably only have access to this right now)

I tried recreating this issue locally but docs generate just fine. I need to investigate this further to find out why it complains about the missing type declarations.

`allowCredentials` should be specified precisely

To specify allowCredentials, generateAssertionOptions() currently requires allowedCredentialIDs to be an array of base64 credential ids and transports is fixed to ['usb', 'ble', 'nfc', 'internal'], but it should be flexible for developers to specify specific transports.

https://github.com/MasterKale/SimpleWebAuthn/blob/master/packages/server/src/assertion/generateAssertionOptions.ts

I suggest adding an ability to pass CredentialDescriptors to allowedCredentialIDs (or should be renamed to allowCredentials for consistency with the spec) instead of just base64 credential ids.

TPM attestation verification is slow

Something within TPM verification specifically is taking a lot of time:

See the red time badges, there's nothing immediately obvious about why these are taking nearly a second per execution.

Error prone toUint8Array method

I've faced that toUint8Array method treats input as ASCII string:

SimpleWebAuthn/packages/browser/src/helpers/toUint8Array.ts

Line 6 in bc9ad0f

return Uint8Array.from(value, c => c.charCodeAt(0));

It is impossible to change transformation of challenge on the client.

1. Attestation

   SimpleWebAuthn/packages/browser/src/methods/startAttestation.ts

   Line 27 in bc9ad0f

   challenge: toUint8Array(creationOptionsJSON.challenge),

2. Assertion

   SimpleWebAuthn/packages/browser/src/methods/startAssertion.ts

   Line 27 in bc9ad0f

   challenge: toUint8Array(requestOptionsJSON.challenge),

Whats wrong?

First: Challenge verification will fail if challenge string contains non ASCII character. For example: abcж yep, ж occupy 2 bytes.

const value = 'abcж';

const array = Uint8Array.from(value, c => c.charCodeAt(0));
const string = String.fromCharCode.apply(null, array);

/// 'abcж' !== 'abc6'
value !== string

Second: user may want to transfer challenge from server in different format:

• ASCII string - current assumption
• HEX string - I prefer this format
• OCTET string
• base64 or base64url strings
• and so on

So it would be better to allow user configure challenge encoding or move conversion and appropriate helper(s) to userland instead hard coded into the lib.

requireResidentKey Android 7 bug

Hi,

I was trying to catch the bug for a week: Android 7.0 requires authenticatorSelection.requireResidentKey to be set to false to works without error:

An unknown error occurred while talking to credential manager

Yep, it is default value https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions/authenticatorSelection but attestation doesn't work without it.

I think the library may set authenticatorSelection.requireResidentKey to default value false.

Docs don't include info on MetadataService

For some reason TypeDoc isn't including the MetadataService singleton. I need to figure out how to get it to display while preserving the ability to organize documentation into library packages.

SafetyNet attestation verification is slow

Something within SafetyNet verification specifically is taking a lot of time:

See the red time badges, there's nothing immediately obvious about why these are taking nearly a second per execution.

default not exported

this is generated from my rollup...

'default' is not exported by apps/store/code/node_modules/@simplewebauthn/browser/dist/simplewebauthn-browser.min.js

thus import SimpleWebAuthnBrowser from '@simplewebauthn/browser' does not work

What to do about `supportsWebAuthn()`...

As highlighted in PR #112 and #113, @simplewebauthn/browser's supportsWebAuthn() method can't actually execute in browsers that don't support WebAuthn, like IE11 and Edge Legacy, because those browsers don't support ES2018 syntax. This negates the reason for its existence.

As I mentioned in PR #113, the path forward is ambiguous to me. It's likely not as simple as updating packages/browser/tsconfig.json to target ES5 instead of ES2018.

Possible options I proposed included:

• Maybe there's a way to build the code with Webpack that lets developers pick-and-choose which version of the library they want to use in their code.
• Maybe the solution is another library that's only the supportsWebAuthn() method built for ES5 environments.
• A third alternative is I just nuke supportsWebAuthn() and update the docs to say, "if you need to support IE11/Edge Legacy, here's a snippet of VanillaJS you can copy-paste into your code to tell if WebAuthn is available."

I'm open to suggestions on how we might solve the problem of building a library that simultaneously needs to sometimes support ES5 while often supporting ES2018.

devices not explained

the use of the devices parameter in the online docs at https://simplewebauthn.dev/docs/packages/server is not explained.

clientExtensionResults to be optional

Hello,

In the following types, it would be nice to have clientExtensionResults optional as it is not used in the verify attestation nor assertion:

export interface AttestationCredentialJSON extends Omit<AttestationCredential, 'response' | 'rawId' | 'getClientExtensionResults'> {
    rawId: Base64URLString;
    response: AuthenticatorAttestationResponseJSON;
    clientExtensionResults: AuthenticationExtensionsClientOutputs;
    transports?: AuthenticatorTransport[];
}

export interface AssertionCredentialJSON extends Omit<AssertionCredential, 'response' | 'rawId' | 'getClientExtensionResults'> {
    rawId: Base64URLString;
    response: AuthenticatorAssertionResponseJSON;
    clientExtensionResults: AuthenticationExtensionsClientOutputs;
}

Missing exported type `VerifiedAttestation`

The response of verifyAttestationResponse isn't exported in types package or server package.

TS is going inside @simplewebauthn/server/dist/attestation/verifyAttestationResponse to get it.

@simplewebauthn/browser v0.10.0 make Edge stuck on Windows 10

@simplewebauthn/browser v0.10.0 make Edge stuck on Windows 10.

const { startAttestation, startAssertion } = require('@simplewebauthn/browser');

// never reached 

Build env: commonjs + webpack

New release of specifications - Level 2

A new release of the specification has been deployed and we should check it to be sure all is still conform to it.

Tor & WebAuthn

I've just leave it here.

Multiple expected origins allows to use .onion domain in additional to standard one. But WebAuthn feature is disabled in most popular Tor browser:

• https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/40223
• https://gitlab.torproject.org/legacy/trac/-/issues/26614

I don't know how to move this feature forward, but it would be awesome to have SimpleWebAuthn working in tor.

Document FIDO Conformance Tools testing setup

I need to include a list of steps others can follow to set up the example server to test against the FIDO Conformance Tools Server Tests.

Ideally addressing this should also establish a new static site setup to enable easily adding more documentation later.

@webauthn/browser not working with SSR

@webauthn/browser needs access to window when loading the module.
This causes errors in SSR environments, because window is not defined there.
Would be great if loading the module would also work in SSR environment.

Improve findability

It should make it easier to find the library:

• Add NPM keywords https://docs.npmjs.com/files/package.json#keywords
• Add Github topics https://github.blog/2017-01-31-introducing-topics/

At least FIDO and WebAuthn may be added 😉

Error in verifyAttestationResponse when using apple format and FaceID/TouchID sometimes not showing up

There is an error thrown in verifyAssertionOptions when using apple FaceID to solve the attestation request.

Attestation options:

{
  challenge: 'VNT_3_E2tFGe4NUoLRdJhsztnVMbI_98Vr3GgMmRVlg',
  rp: { name: 'IPS Hosting', id: 'ips-hosting.eu.ngrok.io' },
  user: { id: '21', name: 'P4sca1', displayName: 'P4sca1' },
  pubKeyCredParams: [
    { alg: -7, type: 'public-key' },
    { alg: -8, type: 'public-key' },
    { alg: -36, type: 'public-key' },
    { alg: -37, type: 'public-key' },
    { alg: -38, type: 'public-key' },
    { alg: -39, type: 'public-key' },
    { alg: -257, type: 'public-key' },
    { alg: -258, type: 'public-key' },
    { alg: -259, type: 'public-key' }
  ],
  timeout: 60000,
  attestation: 'direct',
  excludeCredentials: [],
  authenticatorSelection: { userVerification: 'discouraged' },
  extensions: undefined
}

Attestation response (SimpleWebAuthn Debugger link)

{
  id: '24qeQ_g9SbjwmEdgagzhrzhN_DI',
  rawId: '24qeQ_g9SbjwmEdgagzhrzhN_DI',
  response: {
    attestationObject: 'o2NmbXRlYXBwbGVnYXR0U3RtdKJjYWxnJmN4NWOCWQJIMIICRDCCAcmgAwIBAgIGAXUUh_QAMAoGCCqGSM49BAMCMEgxHDAaBgNVBAMME0FwcGxlIFdlYkF1dGhuIENBIDExEzARBgNVBAoMCkFwcGxlIEluYy4xEzARBgNVBAgMCkNhbGlmb3JuaWEwHhcNMjAxMDA5MjIwMDU1WhcNMjAxMDEyMjIwMDU1WjCBkTFJMEcGA1UEAwxANjEyMTQyMmNmNWY1MWNhMWQ4NTIyZDEwZDlhYzY3OGYxZjNjNTRhYjBmZDk5M2ViZWI2NDI3NzY4NDY2NjNhNjEaMBgGA1UECwwRQUFBIENlcnRpZmljYXRpb24xEzARBgNVBAoMCkFwcGxlIEluYy4xEzARBgNVBAgMCkNhbGlmb3JuaWEwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ7qQ-_z-C1n5CYXuYzYNrWt9NCPpfO2i7Kisiu-5IHwyFFwOTpEmCIoNvlHZnBnKeLmTJ8zQh85cv0gI7iKNRWo1UwUzAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB_wQEAwIE8DAzBgkqhkiG92NkCAIEJjAkoSIEIO3z3p0sNCSsTheri1FqVoEfQ9uLJGXnsrfHile9fwgjMAoGCCqGSM49BAMCA2kAMGYCMQD6TBLDKVkZBicGfFjk44cq_ZbnaW9blEdt3w0Auk4RDDt4HCK70iQFg2_DbmSP3RECMQDJDtmxXuTM-RljP2H50AOAbLKbLvSQNMHLbEe9TqAQe1Yq-D0uqf_l5CuCE04pVJVZAjgwggI0MIIBuqADAgECAhBWJVOVx6f7QOviKNgmCFO2MAoGCCqGSM49BAMDMEsxHzAdBgNVBAMMFkFwcGxlIFdlYkF1dGhuIFJvb3QgQ0ExEzARBgNVBAoMCkFwcGxlIEluYy4xEzARBgNVBAgMCkNhbGlmb3JuaWEwHhcNMjAwMzE4MTgzODAxWhcNMzAwMzEzMDAwMDAwWjBIMRwwGgYDVQQDDBNBcHBsZSBXZWJBdXRobiBDQSAxMRMwEQYDVQQKDApBcHBsZSBJbmMuMRMwEQYDVQQIDApDYWxpZm9ybmlhMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEgy6HLyYUkYECJbn1_Na7Y3i19V8_ywRbxzWZNHX9VJBE35v-GSEXZcaaHdoFCzjUUINAGkNPsk0RLVbD4c-_y5iR_sBpYIG--Wy8d8iN3a9Gpa7h3VFbWvqrk76cCyaRo2YwZDASBgNVHRMBAf8ECDAGAQH_AgEAMB8GA1UdIwQYMBaAFCbXZNnFeMJaZ9Gn3msS0Btj8cbXMB0GA1UdDgQWBBTrroLE_6GsW1HUzyRhBQC-Y713iDAOBgNVHQ8BAf8EBAMCAQYwCgYIKoZIzj0EAwMDaAAwZQIxAN2LGjSBpfrZ27TnZXuEHhRMJ7dbh2pBhsKxR1dQM3In7-VURX72SJUMYy5cSD5wwQIwLIpgRNwgH8_lm8NNKTDBSHhR2WDtanXx60rKvjjNJbiX0MgFvvDH94sHpXHG6A4HaGF1dGhEYXRhWJgBpwTFUgYt_G45iIlHM9dA5ir7lBILi7_AbJl0nYyG-UUAAAAAAAAAAAAAAAAAAAAAAAAAAAAU24qeQ_g9SbjwmEdgagzhrzhN_DKlAQIDJiABIVggO6kPv8_gtZ-QmF7mM2Da1rfTQj6XztouyorIrvuSB8MiWCAhRcDk6RJgiKDb5R2ZwZyni5kyfM0IfOXL9ICO4ijUVg',
    clientDataJSON: 'eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiVk5UXzNfRTJ0RkdlNE5Vb0xSZEpoc3p0blZNYklfOThWcjNHZ01tUlZsZyIsIm9yaWdpbiI6Imh0dHBzOi8vaXBzLWhvc3RpbmcuZXUubmdyb2suaW8ifQ'
  },
  type: 'public-key'
}

Error:

Error: Cannot get schema for 'Certificate' target
    at AsnSchemaStorage.get (/Users/pascal/code/ips-hosting/node_modules/@simplewebauthn/server/node_modules/@peculiar/asn1-schema/build/cjs/schema.js:17:19)
    at Function.fromASN (/Users/pascal/code/ips-hosting/node_modules/@simplewebauthn/server/node_modules/@peculiar/asn1-schema/build/cjs/parser.js:38:52)
    at Function.parse (/Users/pascal/code/ips-hosting/node_modules/@simplewebauthn/server/node_modules/@peculiar/asn1-schema/build/cjs/parser.js:28:26)
    at Object.verifyApple [as default] (/Users/pascal/code/ips-hosting/node_modules/@simplewebauthn/server/src/attestation/verifications/verifyApple.ts:40:36)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
    at Object.verifyAttestationResponse (/Users/pascal/code/ips-hosting/node_modules/@simplewebauthn/server/src/attestation/verifyAttestationResponse.ts:198:16)
    at Function.verifyAttestationResponse (/Users/pascal/code/ips-hosting/apps/api/src/controllers/auth/two-step-verification/web-authn.ts:72:47)
    at /Users/pascal/code/ips-hosting/apps/api/src/router/auth/two-step-verifiation/web-authn.ts:85:24

Also I noticed that you need to start the attestation 2 times to be able to use FaceID. In the first attempt, Safari only asks for a security key. Only when you cancel and restart the attestation, you can select from security key and FaceID.
I don`t know whether this is an issue with the attestation options or with Safari.

Improve library API documentation

I'm not really happy with the TypeDoc-generated docs that are hosted at https://api-docs.simplewebauthn.dev/. It's primarily because of things like this:

What arguments are within Options? Who knows?!

This is partially my fault for rolling with an old version of TypeDoc that works with a plugin that supports a "library" mode. I chose this approach because early testing produced adequate documentation of the monorepo's multiple libraries, but it just hasn't scaled well as the libraries' have evolved.

Now that I have a proper website up with its own docs section, though, it's feasible for me to start maintaining manually-authored API docs and host them there to achieve the desired level of exposure of the various methods' arguments.

"list" argument must be an Array of Buffers

I was trying to use @simplewebauthn/server in cloudflare workers, but getting this error when verifying attestation

TypeError: "list" argument must be an Array of Buffers
    at Function.a.concat (index.js:376)
    at Object.convertCOSEtoPKCS [as default] (convertCOSEtoPKCS.js:19)
    at Object.verifyAttestationPacked [as default] (verifyPacked.js:50)
    at verifyAttestationResponse (verifyAttestationResponse.js:166)

Cloudflare workers provide access to most browser api's including cypto api. Is this possible to run this package in cloudflare workers with browserifying ?

Challenge not checked in verifyAttestation/AssertionResponse

Hey there!
I noticed that a challenge is passed to generateAttestation/AssertionOptions but when verifying the respone, the returned challenge is never verified.
See step 4: https://www.w3.org/TR/webauthn/#registering-a-new-credential
The verify functions would need another argument where the challenge needs to be passed again.

Certiticate parse error in verifyAttestationResponse

I am trying out the webauthn process using Chromes webauthn dev tools with protocol ctap2 and transport internal, and on the server side I am getting the following error

Error: hExtV parse error: 3003010100
    at X509.getExtBasicConstraints (.../node_modules/jsrsasign/lib/jsrsasign.js:249:3670)
    at Object.getCertificateInfo [as default] (.../node_modules/@simplewebauthn/server/dist/helpers/getCertificateInfo.js:41:53)
    at Object.verifyAttestationPacked [as default] (.../node_modules/@simplewebauthn/server/dist/attestation/verifications/verifyPacked.js:53:107)
    at verifyAttestationResponse (.../node_modules/@simplewebauthn/server/dist/attestation/verifyAttestationResponse.js:166:48)

Settle on a documentation setup

I'm planning on maintaining the example project as a practical, living reference point for how to work with these libraries. However, I'd still like to make available a lower-level reference doc for the various methods in both libraries.

To that end I need to settle on some kind of documentation generation setup. Ideally it'd be a low-effort thing that pulls all the info from the type annotations, with JSDocs as supplemental context. And it should output a tasteful collection of static HTML pages I could host on Github Pages/etc...

For now I'm going to take a look at TypeDoc and see if it'll work for this.

Support for Usernameless

Hello,
has anyone implemented userless webauthn authentication?

thanks for help
regards

Multiple expectedOrigin and expectedRPID

Hello,

Thanks for your great work.

I have a use case that seems not working with the current implementation of the lib.
When using SimpleWebAuthn on a browser extension I have different expectedOrigin and expectedRPID for Firefox / Chrome / ...
Maybe I'm wrong but the only way I see to have the lib working with this use case is to change both expectedOrigin and expectedRPID from string to tables so that I can check if the origin and rpId in the attestation/assertion are in the list.

Is my interpretation correct and is it worth to support this use case in the lib?

Feature proposal: Stateless Challenge via JWT

For a better DX and also reinforced security (JWT allow to easly implement challenge expiration) it could be interesting to implement the following pattern

Main concept:

• Return a JWT signed version of the challenge with some user and options at the same time.

Pro:

• Challenge not stored in DB
• Due to JWT expire behavior, challenge can expire
• On verify, call to DB can be avoided (since we can get userId from JWT)
• JWT secret can be rotated easly (through env vars, config, etc...)
• Better performance (reduce calls to DB)

Cons:

• if an attacker can found the JWT secret he can spoof challenges (but in this case the challenge spoof would be the least of the developer's worries. )
• Post other cons in comments

Lib could be used for this feature: https://www.npmjs.com/package/jsonwebtoken

How to use usernameless and passwordless at the same time

As described in the Yubico developer Guide we can use User Handle to allow usernameless and passwordless authentication.

How to do it with this library and initiate attestation and assertion phases without a username because all documentation describes an associated user passed in parameter.

Thanks for your help.

Add link to docs

At the moment there is no link to the documentation. I would add it as a website in the git description and also in the README.

Developer should be able to specify `pubKeyCredParams` to support.

Currently the library is passing all potential algorithms to pubKeyCredParams in the PublicKeyCredentialCreationOptions but it should be selectable by the RP because some authenticators reject when unsupported algorithm is passed.

Support returning extension outputs

While preparing #21, I discovered that browser wasn't actually returning extension results due to some weird issue with navigator.credentials.create()/get() returning a credential with non-enumerable properties, so the spread operator was ineffective.

Anyway after some more digging it turns out that TypeScript's AuthenticationExtensionsClientInputs and AuthenticationExtensionsClientOutputs definitions are wildly out of date, especially due to a recent WebAuthn spec change that removed a bunch of outdated extensions. Therefore I need to upgrade browser to support returning the results of getClientExtensionResults() to support the list of extension currently defined in the spec:

• appid
• appidExclude
• uvm
• credProps

Simplify @simplewebauthn/browser

Having been exposed to some other existing libraries, I've thought of ways to improve the browser package:

1. Return everything from navigator.credentials.create() and navigator.credentials.get()

Right now the library picks and chooses what to send back to the back end. This'll likely not scale if/when WebAuthn expands, especially as more and more extensions get added.

It also means server is tightly-coupled to browser (an intentional decision, admittedly) - having browser return the entire response from the navigator.credentials commands (and updating server to accept the full response) will offer a more decoupled pair of packages in case a better alternative to browser exists/comes along while server still remains a more superior implementation of the back end.

Exposing more info to the server package might also be needed for more spec-compliant attestation/assertion verification - right now verification seems pretty reliable, but it's not a to-the-letter implementation.

I feel this'll also make conformance testing easier as it'll mean less proxy code needs to be written for the various tests they run code through.

2. Try to remove the single project dependency

This'd basically involve cribbing some notes from Github's https://github.com/github/webauthn-json. It turns out that if we lean more on modern browsers' Uint8Array support and the global atob method, we can completely do away with third-party dependencies. I'd like to continue to make browser as lean as possible, and it looks like we can make it even slimmer than it already is.

Support user verification

The default value of user verification is "preferred". Chromium shows the following warning when using the default: https://chromium.googlesource.com/chromium/src/+/master/content/browser/webauth/uv_preferred.md
We should make it possible to pass a custom user verification flag to generateAssertionOptions and generateAtestationOptions. By default undefined should be used to let the browser decide on the default (which is preferred at the moment).

It would be great to add a description to the parameter stating that:

• UV should be set to discouraged when Webauthn is used as a multi factor.
• UV should be set to preferred or required when Webauthn is used as a stand alone passwordless (or even usernameless) flow.

Build error when I tried to import SimpleWebAuthn server

Hi,
I am trying to import SimpleWebAuthn to my typescript project. After import it with npm, I got error as on the attached image.

npm install @simplewebauthn/server
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules/fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

+ @simplewebauthn/[email protected]
added 32 packages from 28 contributors and audited 684 packages in 4.951s
found 179 vulnerabilities (123 low, 1 moderate, 54 high, 1 critical)
  run `npm audit fix` to fix them, or `npm audit` for details
phoebe@watsoncao-X570-UD:~/cybersec/clean-starter/app$ npm run build

> [email protected] build /home/phoebe/cybersec/clean-starter/app
> tsc

node_modules/@types/pvutils/index.d.ts:115:42 - error TS2304: Cannot find name 'BufferSource'.

115     function arrayBufferToString(buffer: BufferSource): string;
                                             ~~~~~~~~~~~~


Found 1 error.

npm ERR! code ELIFECYCLE
npm ERR! errno 2
npm ERR! [email protected] build: `tsc`
npm ERR! Exit status 2
npm ERR! 
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/phoebe/.npm/_logs/2020-11-09T06_08_58_963Z-debug.log`

I just wonder if I did something wrong?

Thanks,

How to verify assertion response

I noticed that in order to be able to verify an assertion, an authenticator object needs to be passed.
The idea is that the counter of the authenticator needs to be checked, which is great. However, how can I know in advance which authenticator the user chose to authenticate, when multiple authenticators are available to a user?
It would be great if an array of authenticators would be supported. The selected authenticator would then be picked from that array based on response.base64CredentialID.

Apple attestation

A new attestation is existing now for Apple device

Maybe can solve some problems with TouchID / FaceID.

`rpId` is not set in `PublicKeyCredentialRequestOptions`

There's no interface to pass rpId in PublicKeyCredentialRequestOptions.

Missing stored data in server

As described in the Yubico developer Guide to backing up authenticator data, userHandle, metadata, and attestation data should be stored in the database.

For the attestation, see my comment

For the userHandle, the value exists and it's the user.id field during attestation generation phase - we have to store it during attestation verification phase inside AuthenticatorDevice object with others data and to do it, we have to keep it like challenge between both phases. see comment also.

For the metadata, the value should be returned by MDS but if it's not included, we should have at least this {"authenticator_attachment":"cross-platform"} or {"authenticator_attachment":"platform"} regarding the type of the authenticator registered. This can be very helpful to display dedicated section in the UI regarding the authenticator type.

All this new values should be stored inside AuthenticatorDevice object and in the database as well, like this they can be used during verification process.

Allow to override supportedCOSEAlgorithmIdentifiers

It would be useful to be able to override supportedCOSEAlgorithmIdentifiers here: https://github.com/MasterKale/SimpleWebAuthn/blob/master/packages/server/src/attestation/generateAttestationOptions.ts#L85-L88

And here: https://github.com/MasterKale/SimpleWebAuthn/blob/master/packages/server/src/attestation/verifyAttestationResponse.ts#L141-L145

For example to support only -7 ES256 and -257 RS256.

Unexpected attestation challenge

I just tested the challenge check introduced in #5 and always get the unexpected attestation challenge error. Maybe it is something on my end.

Example error: Unexpected attestation challenge "MFpYWTliNDk0Vzd4UGJxV05tci9MM0JQVElodW5IRGM1OURVN05odDd2VT0", expected "0ZXY9b494W7xPbqWNmr/L3BPTIhunHDc59DU7Nht7vU="

The expected challenge is correct. The client also gets the expected challenge correctly from the server in publicKey.challenge.

This is how I create the challenge: randomBytes(32).toString('base64').