@sourceregistry/node-webauthn

@sourceregistry/node-webauthn

TypeScript helpers for WebAuthn registration and authentication with dedicated server and client entrypoints.

Install

npm install @sourceregistry/node-webauthn

npx jsr add @sourceregistry/node-webauthn

Entry points

import createWebAuth from "@sourceregistry/node-webauthn/server";
import createWebAuthClient from "@sourceregistry/node-webauthn/client";

@sourceregistry/node-webauthn re-exports the server entry:

import createWebAuth from "@sourceregistry/node-webauthn";

Quick start

import createWebAuth from "@sourceregistry/node-webauthn/server";
import createWebAuthClient from "@sourceregistry/node-webauthn/client";
import {generateKeyPairSync} from "node:crypto";

const {privateKey, publicKey} = generateKeyPairSync("ec", {namedCurve: "P-256"});

const server = createWebAuth({
    keyPair: {
        kid: "main",
        private_key: privateKey,
        public_key: publicKey
    },
    issuer: "https://auth.example.com",
    rpId: "example.com",
    rpName: "Example"
});

const client = createWebAuthClient();

const registrationOptions = server.createRegistrationOptions({
    user: {
        id: server.toBase64Url("user-123"),
        name: "[e-mail]",
        displayName: "Example User"
    }
});

const credential = await client.startRegistration(registrationOptions);

const parsed = server.verifyRegistrationResponse({
    expected_challenge: registrationOptions.challenge,
    credential_id: credential.id,
    client_data_json: credential.client_data_json,
    attestation_object: credential.attestation_object,
    transports: credential.transports,
    client_extension_results: credential.client_extension_results,
    origin: "https://example.com",
    rp_id: "example.com",
    expected_algorithms: registrationOptions.pubKeyCredParams.map(item => item.alg)
});

Package layout

• @sourceregistry/node-webauthn Re-exports the server entry.
• @sourceregistry/node-webauthn/server Node.js option building, ceremony token, and verification helpers.
• @sourceregistry/node-webauthn/client Browser helpers for JSON conversion, WebAuthn calls, and credential serialization.

Examples

• Registration server flow: examples/registration-flow.ts
• Authentication server flow: examples/authentication-flow.ts
• Browser client flow: examples/browser-client.ts

Compliance snapshot

Area	Status	Notes
Server-generated registration/authentication options	Strong	createRegistrationOptions(...) and createAuthenticationOptions(...) are the intended entrypoints.
clientDataJSON validation	Strong	Checks ceremony type, challenge, origin allowlist, rejects unsupported cross-origin ceremonies, and normalizes malformed JSON into stable library errors.
Authenticator data parsing	Strong	Parses RP ID hash, flags, counters, attested credential data, and extension data.
Authentication assertion verification	Strong	Verifies signature, RP/appid hash, optional credential binding, UP/UV policy, counter progression, and allowed client extensions.
Registration verification core	Strong	Verifies RP ID hash, credential binding, requested algorithm policy, and attestation dispatch.
Attestation format coverage	Broad	Supports none, packed, fido-u2f, apple, android-key, android-safetynet, and tpm.
Attestation trust policy	Good	Supports none, permissive, and strict trust modes plus trust anchors, metadata hooks, CA/key-usage checks for issuing certs, and exact leaf pinning.
Extension support	Partial	Practical subset today: credProps, appid, appidExclude, and largeBlob.
Metadata / revocation	Partial	Metadata hooks exist, but there is no built-in FIDO MDS integration or revocation pipeline yet.
Cross-origin / advanced browser edge cases	Limited	Cross-origin ceremonies are intentionally rejected for now.
Full spec-tight attestation semantics	Partial	Some format-specific policy checks are still lighter than full ecosystem-grade verification.

Practical summary:

• This library is strong for common relying-party registration and authentication flows.
• It is not yet fully spec-tight in every attestation and trust-policy edge case.
• The largest remaining gaps are deeper attestation semantics, revocation, and metadata-backed trust.

Server API

createWebAuth(config)

Creates a reusable server helper with:

• generateChallenge(bytes?)
• createRegistrationOptions(input)
• createAuthenticationOptions(input)
• signRegistration(payload)
• verifyRegistration(token)
• signAuthentication(payload)
• verifyAuthentication(token)
• parseRegistration(input)
• verifyRegistrationResponse(input)
• verifyAuthenticationResponse(input)

createRegistrationOptions(input)

Returns JSON-safe registration options for the client helper.

createAuthenticationOptions(input)

Returns JSON-safe authentication options for the client helper.

verifyRegistrationResponse(input)

Validates:

• ceremony type
• challenge
• origin
• RP ID hash
• credential ID match
• requested algorithm policy
• attestation format and trust policy
• registration extension allowlist

Supported attestation formats:

• none
• packed
• fido-u2f
• apple
• android-key
• android-safetynet
• tpm

Attestation support status:

Format	Status	Notes
none	Strong	Suitable default for easy deployment.
packed	Strong	Supports self attestation and certificate-backed validation with optional trust anchors.
fido-u2f	Strong	Verified with optional trust anchors.
apple	Good	Verifies Apple nonce extension and credential public-key binding.
android-key	Partial	Core verification is present, but Android authorization-list policy checks are not exhaustive yet.
android-safetynet	Partial	Verifies JWS, nonce, timestamp, and CTS profile, but ecosystem trust/revocation remains lightweight.
tpm	Partial	Core certInfo / pubArea validation is present, but TPM certificate/profile checks are not exhaustive yet.

Registration results include:

• credential_id
• public_key
• aaguid
• counter
• attestation_format
• attestation_type
• attestation_trusted
• attestation_policy_accepted
• metadata_status

verifyAuthenticationResponse(input)

Validates:

• ceremony type
• challenge
• origin
• RP ID hash
• optional credential ID binding when credential_id and expected_credential_id are supplied
• signature
• counter progression
• user presence / verification policy
• authentication extension allowlist

Typical usage:

const result = server.verifyAuthenticationResponse({
    expected_challenge: publicKey.challenge,
    credential_id: credential.id,
    expected_credential_id: storedCredential.credential_id,
    client_data_json: credential.client_data_json,
    authenticator_data: credential.authenticator_data,
    signature: credential.signature,
    origin: "https://example.com",
    rp_id: "example.com",
    public_key: storedCredential.public_key,
    previous_counter: storedCredential.counter
});

Client API

createWebAuthClient()

Creates browser helpers with:

• toCreationOptions(json)
• toRequestOptions(json)
• startRegistration(json)
• startAuthentication(json)
• serializeRegistrationCredential(credential)
• serializeAuthenticationCredential(credential)
• toBase64Url(value)
• fromBase64Url(value)

End-to-end flow

Server begin step:

const publicKey = server.createRegistrationOptions({
    user: {
        id: server.toBase64Url("user-123"),
        name: "[e-mail]",
        displayName: "Example User"
    }
});

Client step:

const credential = await client.startRegistration(publicKey);

Server finish step:

const parsed = server.verifyRegistrationResponse({
    expected_challenge: publicKey.challenge,
    credential_id: credential.id,
    client_data_json: credential.client_data_json,
    attestation_object: credential.attestation_object,
    transports: credential.transports,
    client_extension_results: credential.client_extension_results,
    origin: "https://example.com",
    rp_id: "example.com",
    expected_algorithms: publicKey.pubKeyCredParams.map(item => item.alg)
});

Attestation policy

Simple format allowlist:

const server = createWebAuth({
    keyPair,
    rpId: "example.com",
    rpName: "Example",
    attestation: {
        allowed_formats: ["none", "packed"]
    }
});

Strict trust:

const server = createWebAuth({
    keyPair,
    rpId: "example.com",
    rpName: "Example",
    attestation: {
        allowed_formats: ["packed", "tpm"],
        trust_mode: "strict",
        trust_anchors: [rootCertificatePem]
    }
});

Metadata-backed policy:

const server = createWebAuth({
    keyPair,
    rpId: "example.com",
    rpName: "Example",
    attestation: {
        allowed_formats: ["android-key", "tpm"],
        metadata_provider: {
            getEntry({format}) {
                if (format === "android-key") {
                    return {status: "trusted", trusted: true};
                }

                return null;
            }
        }
    }
});

Extension policy

const server = createWebAuth({
    keyPair,
    rpId: "example.com",
    rpName: "Example",
    extensions: {
        allowed_registration_extensions: ["credProps"],
        allowed_authentication_extensions: ["appid", "largeBlob"]
    }
});

Documentation

• Compliance notes: docs/spec-notes.md
• Trust model: docs/trust-model.md

Toward fuller compliance

The remaining work is intentionally small and incremental so the API can stay easy to use.

• Tighten android-key verification with stronger authorization-list checks from the Android key attestation extension.
• Tighten tpm verification with more complete certificate/profile validation and TPM-specific policy checks.
• Strengthen android-safetynet trust handling with clearer certificate-policy validation and optional revocation hooks.
• Add optional FIDO Metadata Service integration behind the existing metadata_provider style trust model.
• Add optional revocation checking for attestation certificate chains.
• Expand extension semantics only where they matter for relying-party policy, instead of trying to support every extension by default.
• Add more conformance-style negative fixtures for attestation and trust-policy edge cases.

Notes

• The default API is intentionally small.
• Trust evaluation is optional by default and can be tightened with trust_mode, trust_anchors, and metadata_provider.