@didtools/key-webauthn

Webauthn AuthMethod and Verifier

Implements support to authenticate, authorize and verify blocks produced
by webauthn/passkey compatible hardware authenticators and OS/software implementations.

Installation

``
npm install --save @didtools/key-webauthn
`

Auth Usage

This module is designed to run in browser environments.

Create a Credential for first time use:
`js
import { WebauthnAuth } from '@didtools/key-webauthn'

const did = await WebauthnAuth.createDid('app-user')

const authMethod = await WebauthnAuth.getAuthMethod({ did })
const session = await DIDSession.authorize(authMethod, { resources: ['ceramic://nil'] })
`

Verifier Usage

Verifiers are needed to verify different did:pkh signed payloads using CACAO. Libraries that need them will
consume a verifiers map allowing your to register the verifiers you want to support.

`js
import { Cacao } from '@didtools/cacao'
import { WebauthnAuth } from '@didtools/key-webauthn'
import { DID } from 'dids'

const verifiers = {
...WebauthnAuth.getVerifier()
}

// Directly with cacao
Cacao.verify(cacao, { verifiers, ...opts})

// With DIDS, reference DIDS for more details
const dids = // configured dids instance
await dids.verifyJWS(jws, { capability, verifiers, ...opts})
`

Caveat: DID selection

The webauthn+fido2 standard was originally developed for use with databases and at that time
a pesudo random CredentialID was preferred over the use of public keys.

The public key is exported only once when the credential is created - spec limitation.
There are 3 options for getAuthMethod()

#### Option 1. Known DID

`js
import { WebauthnAuth } from '@didtools/key-webauthn'

const authMethod = WebauthnAuth.getAuthMethod({ did: 'did:key:zDn...' })
`

#### Option 2. Probe

Probe the authenticator for public keys by asking user to sign a nonce:

`js
import { WebauthnAuth } from '@didtools/key-webauthn'

const dids = await WebauthnAuth.probeDIDs()
const authMethod = WebauthnAuth.getAuthMethod({ dids })
`

#### Option 3. Callback

Use a callback with the following call signature:

`ts
(did1: string, did2: string) => Promise
`

Example that probes on-demand:
`js
import { WebauthnAuth } from '@didtools/key-webauthn'

const selectDIDs = async (did1, did2) {
const dids = await WebauthnAuth.probeDIDs()
if (dids.includes(did1)) return did1
else return did2
}

const authMethod = WebauthnAuth.getAuthMethod({ selectDIDs })
`

Compatibility

Tests done via demo.

| Browser | Version | OS | Device | Authenticator | Works | Remark |
|---------------|---------|----------------|---------|--------------------|-------|---------|
| Chrome | 107 | Mac OS 10.15.7 | Desktop | Yubikey v5 (USB-C) | ✅ | |
| Safari | 15.6 | Mac OS 10.15.7 | Desktop | Yubikey v5 (USB-C) | ✅ | |
| Safari | 15.6 | Mac OS 10.15.7 | Desktop | OS-Authenticator | ✅ | |
| Brave | 119 | Mac OS 10.15.7 | Desktop | 1password | ✅ | |
| Mobile Safari | 16.6 | iOS 16.6 | Mobile | Yubikey v5 (USB-C) | ✅ | |
| Mobile Safari | 16.6 | iOS 16.6 | Mobile | OS-Authenticator | ✅ | |
| Chrome | 122 | Windows 10 | Desktop | Yubikey v5 | ✅ | |
| Chrome | 122 | Windows 10 | Desktop | GPM+Android device | ❌ | Timeout |
| Firefox | 84 | Windows 10 | Desktop | Yubikey v5 | ❌ | e1 |
| Firefox | 120 | Windows 10 | Desktop | Yubikey v5 | ✅ | |
| Chrome | 116 | Linux | Desktop | Yubikey v5 | ✅ | |
| Firefox | 115 | Linux | Desktop | Yubikey v5 | ✅ | |
| Chrome | 120 | Android 10 | Mobile | Yubikey v5 | ✅ | e2 |
| Chrome | 120 | Android 10 | Mobile | OS-Authenticator | ✅ | |
| Firefox | 114 | Android 10 | Mobile | Yubikey v5 | ✅ | e2 |
| Firefox | 114 | Android 10 | Mobile | OS-Authenticator | ✅ | |

e1 - An attempt was made to use an object that is not, or is no longer available
e2` - OTG cable was used, when attempting NFC an error message was shown urging USB connection.

License

Apache-2.0 OR MIT