# WebAuthnP256

Utility functions for [NIST P256](https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf) ECDSA cryptography using the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)

## Examples

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

* [Creating Credentials](#creating-credentials)

* [Signing Payloads](#signing-payloads)

* [Verifying Signatures](#verifying-signatures)

### Creating Credentials

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

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

const credential = await WebAuthnP256.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 WebAuthnP256.sign({
  credentialId: credential.id,
  challenge: '0xdeadbeef'
})
```

### Signing Payloads

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

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

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

const { metadata, signature } = await WebAuthnP256.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 [`WebAuthnP256.verify`](/api/WebAuthnP256/verify):

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

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

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

const result = await WebAuthnP256.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                         |
| ------------------- | ----------------------------------- |
| [`WebAuthnP256.createCredential`](/api/WebAuthnP256/createCredential) | Creates a new WebAuthn P256 Credential, which can be stored and later used for signing. |
| [`WebAuthnP256.sign`](/api/WebAuthnP256/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. |
| [`WebAuthnP256.verify`](/api/WebAuthnP256/verify) | Verifies a signature using the Credential's public key and the challenge which was signed. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebAuthnP256.AttestationConveyancePreference`](/api/WebAuthnP256/types#webauthnp256attestationconveyancepreference) |  |
| [`WebAuthnP256.AuthenticatorAttachment`](/api/WebAuthnP256/types#webauthnp256authenticatorattachment) |  |
| [`WebAuthnP256.AuthenticatorTransport`](/api/WebAuthnP256/types#webauthnp256authenticatortransport) |  |
| [`WebAuthnP256.BufferSource`](/api/WebAuthnP256/types#webauthnp256buffersource) |  |
| [`WebAuthnP256.COSEAlgorithmIdentifier`](/api/WebAuthnP256/types#webauthnp256cosealgorithmidentifier) |  |
| [`WebAuthnP256.CredentialMediationRequirement`](/api/WebAuthnP256/types#webauthnp256credentialmediationrequirement) |  |
| [`WebAuthnP256.LargeBlobSupport`](/api/WebAuthnP256/types#webauthnp256largeblobsupport) |  |
| [`WebAuthnP256.P256Credential`](/api/WebAuthnP256/types#webauthnp256p256credential) | A WebAuthn-flavored P256 credential. |
| [`WebAuthnP256.PrfExtension`](/api/WebAuthnP256/types#webauthnp256prfextension) |  |
| [`WebAuthnP256.PublicKeyCredential`](/api/WebAuthnP256/types#webauthnp256publickeycredential) |  |
| [`WebAuthnP256.PublicKeyCredentialType`](/api/WebAuthnP256/types#webauthnp256publickeycredentialtype) |  |
| [`WebAuthnP256.ResidentKeyRequirement`](/api/WebAuthnP256/types#webauthnp256residentkeyrequirement) |  |
| [`WebAuthnP256.SignMetadata`](/api/WebAuthnP256/types#webauthnp256signmetadata) | Metadata for a WebAuthn P256 signature. |
| [`WebAuthnP256.UserVerificationRequirement`](/api/WebAuthnP256/types#webauthnp256userverificationrequirement) |  |