# WebAuthn

Utilities for WebAuthn credentials, credential-bound PRFs, and
[NIST P256](https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf)
signatures.

## Examples

Below are some examples demonstrating common usages of the `WebAuthn` module:

* [Creating Credentials](#creating-credentials)

* [Signing Payloads](#signing-payloads)

* [Verifying Signatures](#verifying-signatures)

### Creating Credentials

Credentials can be created using [`WebAuthn.createCredential`](/api/WebAuthn/createCredential):

```ts twoslash
import { WebAuthn } from 'ox'

const credential = await WebAuthn.createCredential({
  name: 'Example'
}) // [!code focus]
// @log: {
// @log:   id: 'oZ48...',
// @log:   publicKey: { x: 51421...5123n, y: 12345...6789n },
// @log:   raw: PublicKeyCredential {},
// @log: }

const { metadata, signature } = await WebAuthn.sign({
  credentialId: credential.id,
  challenge: '0xdeadbeef'
})
```

### Signing Payloads

Payloads can be signed using [`WebAuthn.sign`](/api/WebAuthn/sign):

```ts twoslash
import { WebAuthn } from 'ox'

const credential = await WebAuthn.createCredential({
  name: 'Example'
})

const { metadata, signature } = await WebAuthn.sign({
  // [!code focus]
  credentialId: credential.id, // [!code focus]
  challenge: '0xdeadbeef' // [!code focus]
}) // [!code focus]
// @log: {
// @log:   metadata: {
// @log:     authenticatorData: '0x49960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d97630500000000',
// @log:     clientDataJSON: '{"type":"webauthn.get","challenge":"9jEFijuhEWrM4SOW-tChJbUEHEP44VcjcJ-Bqo1fTM8","origin":"http://localhost:5173","crossOrigin":false}',
// @log:     challengeIndex: 23,
// @log:     typeIndex: 1,
// @log:     userVerificationRequired: true,
// @log:   },
// @log:   signature: { r: 51231...4215n, s: 12345...6789n },
// @log: }
```

### Verifying Signatures

Signatures can be verified using [`WebAuthn.verify`](/api/WebAuthn/verify):

```ts twoslash
import { WebAuthn } from 'ox'

const credential = await WebAuthn.createCredential({
  name: 'Example'
})

const { metadata, signature } = await WebAuthn.sign({
  credentialId: credential.id,
  challenge: '0xdeadbeef'
})

const result = await WebAuthn.verify({
  // [!code focus]
  metadata, // [!code focus]
  challenge: '0xdeadbeef', // [!code focus]
  publicKey: credential.publicKey, // [!code focus]
  signature // [!code focus]
}) // [!code focus]
// @log: true
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebAuthn.createCredential`](/api/WebAuthn/createCredential) | Creates a WebAuthn credential and optionally returns its credential-bound PRF output. |
| [`WebAuthn.getCredential`](/api/WebAuthn/getCredential) | Requests a WebAuthn credential and returns its credential-bound PRF output. |
| [`WebAuthn.sign`](/api/WebAuthn/sign) | Signs a challenge using a stored WebAuthn P256 Credential. If no Credential is provided, a prompt will be displayed for the user to select an existing Credential that was previously registered. |
| [`WebAuthn.verify`](/api/WebAuthn/verify) | Verifies a signature using the Credential's public key and the challenge which was signed. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebAuthn.GetCredentialFailedError`](/api/WebAuthn/errors#webauthngetcredentialfailederror) | Thrown when a WebAuthn credential request fails. |
| [`WebAuthn.InvalidExtensionError`](/api/WebAuthn/errors#webauthninvalidextensionerror) | Thrown when a caller supplies the managed `prf` extension. |
| [`WebAuthn.InvalidOptionsError`](/api/WebAuthn/errors#webauthninvalidoptionserror) | Thrown when raw credential options are combined with managed PRF evaluation. |
| [`WebAuthn.InvalidPrfOutputError`](/api/WebAuthn/errors#webauthninvalidprfoutputerror) | Thrown when a WebAuthn PRF result is not a valid 32-byte output. |
| [`WebAuthn.PrfEvaluationFailedError`](/api/WebAuthn/errors#webauthnprfevaluationfailederror) | Thrown when WebAuthn PRF evaluation fails after a credential ceremony. |
| [`WebAuthn.PrfNotSupportedError`](/api/WebAuthn/errors#webauthnprfnotsupportederror) | Thrown when a created credential does not support PRF evaluation. |
| [`WebAuthn.PrfUnavailableError`](/api/WebAuthn/errors#webauthnprfunavailableerror) | Thrown when a credential assertion does not return a PRF output. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebAuthn.AttestationConveyancePreference`](/api/WebAuthn/types#webauthnattestationconveyancepreference) |  |
| [`WebAuthn.AuthenticatorAttachment`](/api/WebAuthn/types#webauthnauthenticatorattachment) |  |
| [`WebAuthn.AuthenticatorTransport`](/api/WebAuthn/types#webauthnauthenticatortransport) |  |
| [`WebAuthn.BufferSource`](/api/WebAuthn/types#webauthnbuffersource) |  |
| [`WebAuthn.COSEAlgorithmIdentifier`](/api/WebAuthn/types#webauthncosealgorithmidentifier) |  |
| [`WebAuthn.CredentialMediationRequirement`](/api/WebAuthn/types#webauthncredentialmediationrequirement) |  |
| [`WebAuthn.LargeBlobSupport`](/api/WebAuthn/types#webauthnlargeblobsupport) |  |
| [`WebAuthn.P256Credential`](/api/WebAuthn/types#webauthnp256credential) | A WebAuthn-flavored P256 credential. |
| [`WebAuthn.Prf`](/api/WebAuthn/types#webauthnprf) | Configuration for evaluating a WebAuthn credential-bound PRF. |
| [`WebAuthn.PrfExtension`](/api/WebAuthn/types#webauthnprfextension) | Inputs for the WebAuthn PRF extension. |
| [`WebAuthn.PublicKeyCredential`](/api/WebAuthn/types#webauthnpublickeycredential) |  |
| [`WebAuthn.PublicKeyCredentialType`](/api/WebAuthn/types#webauthnpublickeycredentialtype) |  |
| [`WebAuthn.ResidentKeyRequirement`](/api/WebAuthn/types#webauthnresidentkeyrequirement) |  |
| [`WebAuthn.SignMetadata`](/api/WebAuthn/types#webauthnsignmetadata) | Metadata for a WebAuthn P256 signature. |
| [`WebAuthn.UserVerificationRequirement`](/api/WebAuthn/types#webauthnuserverificationrequirement) |  |