0.17.0 (2026-04-21)

• fix!: split attestation type and format (#658) (3c1e870), closes #658 #476
• feat!: tighten cross-origin defaults (#647) (80cc224), closes #647

Bug Fixes

• protocol: short-circuit apple attestation extension lookup (#664) (5296bc7)

Features

• webauthn: add authenticator registration filtering (#668) (0be632e)
• webauthn: credential message pack (#660) (c7d933c)

BREAKING CHANGES

• A bug with the Credential Record which was introduced early in the libraries lifecycle has resulted in a breaking change to the Credential struct. If you are manually serializing this struct instead of using encoding/json you will be required to make manual changes; though Integrators should consider these notes regardless.

  • protocol.CredentialTypeFIDOU2F has been removed; replace uses with protocol.AttestationFormatFIDOUniversalSecondFactor (cast to string where the destination field is a plain string).

  • The semantics of the AttestationType field on webauthn.Credential and protocol.CredentialDescriptor have changed. Integrators that inspect this field to detect a format (typically checking for "fido-u2f") must switch to the new AttestationFormat field; the FIDO-U2F AppID and AppIDExclude extension helpers now key on AttestationFormat, so a descriptor literal constructed with AttestationType: "fido-u2f" will no longer trigger them.

  • Stored Credential JSON records are migrated transparently by the new UnmarshalJSON, but re-marshaled records will carry attestationFormat rather than a format string in attestationType; downstream consumers that parsed the legacy shape directly should be updated.

  • The Credential.Verify method has been updated and may fail in previous scenarios where it passed previously. It will also update the AttestationType value as a side-effect when used.

• The Cross-Origin verification semantics have changed significantly due to the stabilization of the WebAuthn Level 3 specification. It is no longer possible to disable verification, and Cross-Origin ceremonies must explicitly be allowed in this release.

  • protocol.TopOriginIgnoreVerificationMode has been removed. Code that referenced it must switch to one of the other constants as there is no longer a mode which disables the Top Origin verification such as:

    • TopOriginExplicitVerificationMode; match against RPTopOrigins only (recommended, and the new coerced default)
    • TopOriginAutoVerificationMode; match against the union of RPTopOrigins and RPOrigins
    • TopOriginImplicitVerificationMode; match against RPOrigins only

  • webauthn.Config.validate now rewrites a zero-valued RPTopOriginVerificationMode to TopOriginExplicitVerificationMode. Integrators that left the field unset previously got ignore-mode semantics (any Top Origin accepted); they now get strict matching against RPTopOrigins and must populate that list, or explicitly select a different mode; for Cross-Origin flows to succeed.

  • Cross-Origin ceremonies (those where the authenticator reports crossOrigin = true in the ClientData) are rejected by default. Integrators that rely on iframe-embedded or other Cross-Origin WebAuthn flows must set webauthn.Config.RPAllowCrossOrigin = true. The library continues to enforce Top Origin verification on accepted Cross-Origin ceremonies per the configured mode.

  • protocol.CollectedClientData.Verify no longer accepts TopOriginIgnoreVerificationMode; callers that pass an unknown mode receive ErrNotImplemented with detail "unknown Top Origin verification mode".