webauthn

go-webauthn/webauthn implements the server (relying party) side of the W3C Web Authentication specification for Go applications, letting a backend issue and verify FIDO2/WebAuthn credentials for passwordless, passkey, and multi-factor login flows. It handles the full ceremony lifecycle: generating registration and assertion challenges, parsing and validating client responses, verifying attestation statements against supported formats, and tracking credential sign counters and flags across logins.

The library is deliberately storage- and framework-agnostic — callers implement a small User interface and persist the returned Credential/SessionData structs however they like, with no assumptions about session storage, database, or HTTP framework. It supports discoverable (passkey) and non-discoverable credentials, multiple attestation formats (packed, TPM, Android Key, Apple, FIDO U2F, and compound attestation), extension inputs/outputs, related-origin requests, and optional integration with the FIDO Alliance Metadata Service for authenticator trust verification.

What You Get

• A WebAuthn client built from a Config (RPID, RPOrigins, timeouts) that drives registration and login ceremonies via Begin*/Finish* method pairs
• Support for discoverable credentials (passkeys), non-discoverable multi-factor credentials, and mediated/conditional UI flows
• Parsing and validation of client attestation and assertion responses, including packed, TPM, Android Key, Apple, FIDO U2F, and compound attestation formats
• Functional option types (RegistrationOption, LoginOption, extension options) for customizing conveyance preference, authenticator selection, exclusions, and WebAuthn extensions
• Optional integration with the FIDO Alliance Metadata Service (metadata package) to verify authenticator trust and certification status
• A documented Credential/SessionData storage contract with JSON and MessagePack field mappings so implementers know exactly what to persist and write back after each ceremony

Common Use Cases

• Adding passkey (passwordless) sign-up and sign-in to a Go web application or API backend
• Adding WebAuthn as a second factor alongside an existing password or OTP-based login flow
• Building an identity or auth service that needs to verify hardware security keys or platform authenticators (Touch ID, Windows Hello, Android biometrics)
• Migrating an existing credential store to a newer WebAuthn Level 3 credential record shape using the library’s documented field mappings
• Implementing multi-origin relying parties that need to validate ceremonies across several permitted origins from one backend

Under The Hood

Architecture The module is split into three layered packages: protocol (the largest, ~85 files) owns wire-level parsing, CBOR/COSE decoding, and validation of every WebAuthn message type and attestation format independent of any ceremony state; webauthn (the public entry point) exposes Config, the WebAuthn client, and the Begin*/Finish* ceremony methods that orchestrate challenge generation, session-data handling, and credential persistence via a caller-implemented User interface; and metadata provides optional, decoupled integration with the FIDO Alliance Metadata Service for authenticator trust verification. Ceremony customization runs through a functional-options pattern (RegistrationOption, LoginOption, extension options), and the public API is explicitly storage-agnostic — callers own persistence of Credential and SessionData rather than the library assuming a session store or database.

Tech Stack Built for Go 1.25+ with an explicit toolchain directive pinning newer language features. Dependencies are narrow and purpose-built rather than broad frameworks: fxamacker/cbor for CBOR/COSE key and attestation object decoding, google/go-tpm for TPM attestation verification, golang-jwt/jwt for Apple’s JWT-based attestation, tinylib/msgp for generated MessagePack marshaling (an alternative to JSON for credential storage), go-webauthn/x as a sibling crypto-helpers module, and stretchr/testify plus go.uber.org/mock for the test suite. No HTTP framework or database driver is pulled in, keeping the library embeddable in any Go web stack.

Code Quality The repository carries near one-to-one test-to-source file counts, with dedicated example tests (example_new_test.go, example_passkey_test.go, example_multifactor_test.go, example_extensions_test.go) that double as compiled, runnable documentation. CI runs CodeQL static analysis, a dependency-review gate, and a strict golangci-lint configuration enabling gosec, gocritic, gocyclo, revive, prealloc, and whitespace/style linters (wsl_v5), backed by pre-commit hooks and Codecov coverage reporting. Exported types and functions carry extensive godoc comments with cross-references between related symbols, and a standalone MIGRATION.md tracks breaking changes across releases in detail.

API Design The API favors explicit, composable primitives over magic: ceremonies are two-step Begin/Finish pairs, customization happens through typed functional options rather than sprawling config structs, and the User interface deliberately exposes only the handful of methods (WebAuthnID, WebAuthnName, WebAuthnCredentials, etc.) the library actually needs, leaving storage and session mechanics entirely to the caller. The tradeoff is a real learning curve — correctly wiring session persistence and credential storage requires reading the documented field-mapping table rather than following a single quick-start snippet — but the payoff is a library that drops into any existing auth architecture without imposing one.