![\"webauthx\"](\"https://raw.githubusercontent.com/wevm/webauthx/refs/heads/main/.github/banner-light.svg\")
\n\nTools for server ↔ client WebAuthn ceremony orchestration.
\n\n\n Quickprompt · Install · Usage Walkthrough · API Reference · License\n
\n\n## Quickprompt\n\nPrompt your agent:\n\n```\nAdd passkey authentication to my app using https://raw.githubusercontent.com/wevm/webauthx/refs/heads/main/SKILL.md, and add it to my skills.\n```\n\n## Install\n\n```bash\nnpm i webauthx\n```\n\n```bash\npnpm i webauthx\n```\n\n```bash\nbun i webauthx\n```\n\n## Usage Walkthrough\n\n### Registration (Sign up)\n\nRegister a new passkey credential for a user. The server generates a challenge, the client creates the credential, and the server verifies it.\n\n#### 1. Generate Options (Server)\n\n```ts\nimport { Registration } from 'webauthx/server'\n\napp.post('/register/options', async (request) => {\n const { name } = await request.json()\n\n // Generate a challenge and WebAuthn options for the client.\n const { challenge, options } = Registration.getOptions({\n name,\n rp: { id: 'example.com', name: 'Example' },\n })\n\n // Persist challenge for verification in the next step.\n await store.storeChallenge(challenge)\n\n // Send WebAuthn options to the client.\n return Response.json({ options })\n})\n```\n\n#### 2. Create Credential (Client)\n\n```ts\nimport { Registration } from 'webauthx/client'\n\n// Fetch WebAuthn options from the server.\nconst { options } = await fetch('/register/options', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ name: 'alice' }),\n}).then((r) => r.json())\n\n// Prompt the user to create a passkey.\nconst credential = await Registration.create({ options })\n\n// Send the credential to the server for verification.\nawait fetch('/register/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ credential }),\n})\n```\n\n#### 3. Verify Credential (Server)\n\n```ts\nimport { Registration } from 'webauthx/server'\n\napp.post('/register/verify', async (request) => {\n const { credential } = await request.json()\n\n // Consume the stored challenge (single-use).\n const challenge = await store.consumeChallenge(request)\n\n // Verify attestation & extract the public key.\n const result = Registration.verify(credential, {\n challenge,\n origin: 'https://example.com',\n rpId: 'example.com',\n })\n\n // Persist the credential for future authentication.\n await store.storeCredential({\n ...result.credential,\n aaguid: result.aaguid,\n })\n})\n```\n\n#### 4. Resolve Authenticator Name (Optional)\n\n```ts\nimport { Aaguid } from 'webauthx/server'\n\nconst info = await Aaguid.lookup({ id: storedCredential.aaguid })\n// => { name: '1Password', iconLight?: 'data:image/...', iconDark?: 'data:image/...' }\n// => null\n```\n\n### Authentication (Log in)\n\nAuthenticate a returning user with their existing passkey. The server generates a challenge, the client signs it, and the server verifies the signature.\n\n#### 1. Generate Options (Server)\n\n```ts\nimport { Authentication } from 'webauthx/server'\n\napp.post('/auth/options', async (request) => {\n const { credentialId } = await request.json()\n\n // Generate a challenge and WebAuthn options for the client.\n const { challenge, options } = Authentication.getOptions({\n credentialId,\n rpId: 'example.com',\n })\n\n // Persist challenge for verification in the next step.\n await store.storeChallenge(challenge)\n\n // Send WebAuthn options to the client.\n return Response.json({ options })\n})\n```\n\n#### 2. Sign Challenge (Client)\n\n```ts\nimport { Authentication } from 'webauthx/client'\n\n// Fetch WebAuthn options from the server.\nconst { options } = await fetch('/auth/options', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ credentialId }),\n}).then((r) => r.json())\n\n// Prompt the user to sign the challenge with their passkey.\nconst response = await Authentication.sign({ options })\n\n// Send the response to the server for verification.\nawait fetch('/auth/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ response }),\n})\n```\n\n#### 3. Verify Signature (Server)\n\n```ts\nimport { Authentication } from 'webauthx/server'\n\napp.post('/auth/verify', async (request) => {\n const { response } = await request.json()\n\n // Consume the stored challenge (single-use).\n const challenge = await store.consumeChallenge(request)\n\n // Look up the stored public key for this credential.\n const credential = await store.getCredential(response.id)\n\n // Verify the P-256 signature.\n const valid = Authentication.verify(response, {\n challenge,\n publicKey: credential.publicKey,\n origin: 'https://example.com',\n rpId: 'example.com',\n })\n})\n```\n\n## API Reference\n\n### `webauthx/client`\n\n#### `Authentication.sign`\n\nSigns a challenge via `navigator.credentials.get`. Accepts WebAuthn options from the server and returns a response ready to send back.\n\n##### Usage\n\n```ts\nimport { Authentication } from 'webauthx/client'\n\nconst response = await Authentication.sign({ options })\n```\n\n##### Parameters\n\n| Parameter | Type | Description |\n| --------- | -------------------------- | -------------------------------------------------- |\n| `getFn` | `function` | Custom credential request function (for testing). |\n| `options` | `CredentialRequestOptions` | WebAuthn options from `Authentication.getOptions`. |\n\n##### Return Value\n\n`Promise