webauthnx

type AAGUIDPolicy ¶

type AAGUIDPolicy struct {
	Allow [][]byte
	// Roots is the trust-anchor pool used to verify an x5c-carrying
	// attestation leaf certificate (R10-2). REQUIRED whenever Allow is
	// non-empty — NewServer refuses to construct a Server with a
	// non-empty AAGUIDAllowList and a nil AttestationRoots, because
	// without it Enforce cannot distinguish a genuinely vendor-attested
	// authenticator from a self-signed forgery, making the allow-list a
	// theatre check on the reported AAGUID alone.
	Roots *x509.CertPool
}

AAGUIDPolicy enforces FedRAMP / NIST 800-63B AAL3 authenticator allow-lists. Empty Allow accepts everything (relevant for AAL1/AAL2 or for development).

R9-1 / R10-2: an allow-list is only as trustworthy as the AAGUID it compares against, and that AAGUID is only as trustworthy as the attestation that goes with it. go-webauthn populates webauthn.Credential.Authenticator.AAGUID straight from the registration response's attested credential data — a field the AUTHENTICATOR reports about itself:

• "none" attestation (metadata.None) and packed SELF attestation ("basic_surrogate": signed with the credential's own, registrant-controlled private key, per protocol/attestation_packed.go's handleSelfAttestation) carry NO external vouching for the AAGUID at all — the registrant fully controls both. Enforce fails closed on both shapes outright (R9-1, below).
• EVERY OTHER attestation type go-webauthn actually implements (basic_full/attca/anonca — anything with an x5c chain) is, BY ITSELF, no better: go-webauthn's own handleBasicAttestation (protocol/attestation_packed.go step 2.4) explicitly does not validate the x5c chain against any trust anchor ("We don't handle trust paths yet but we're done"), and wiring a metadata.Provider through Config.MetadataProvider does not close that gap either: go-webauthn's ValidateMetadata (protocol/metadata.go) skips x5c.Verify entirely whenever the attestation leaf is SELF-SIGNED (Subject.CommonName == Issuer.CommonName) — exactly the certificate shape an attacker mints trivially (generate a keypair, self-sign a cert meeting §8.2.1's shape requirements: version 3, ISO-3166 Subject.C, non-empty Subject.O, Subject.OU == "Authenticator Attestation", non-empty Subject.CN, IsCA:false). Without a chain check of its own this package inherits that same gap, at the cost of only "generate a self-signed cert with a fixed subject" instead of "flip 16 bytes" (R9-1's fix). Roots (below) closes it: Enforce independently re-parses the attestation object and verifies the x5c leaf against a real, operator-supplied trust anchor, rejecting a self-signed leaf unconditionally regardless of what MetadataProvider/mds does or doesn't do.

func (p AAGUIDPolicy) Enforce(c webauthn.Credential) error

type BeginLoginOut ¶

type BeginLoginOut struct {
	SessionID string
	Options   *protocol.CredentialAssertion
}

BeginLoginOut is the response shape for the assertion ceremony begin step.

type BeginRegistrationOut ¶

type BeginRegistrationOut struct {
	SessionID string
	Options   *protocol.CredentialCreation
}

BeginRegistrationOut is the response shape for the registration ceremony begin step.

type Config ¶

type Config struct {
	// RPID is the Relying Party identifier (effectively the apex domain).
	RPID string
	// RPDisplayName is shown by browsers and authenticators.
	RPDisplayName string
	// Origins lists the exact https origins the RP serves from. All
	// origins MUST be https except for "http://localhost*" which is
	// allowed by the WebAuthn spec.
	Origins []string

	// AAGUIDAllowList, if non-empty, restricts accepted authenticators by
	// AAGUID (see AAGUIDPolicy.Enforce, applied in FinishRegistration).
	// FedRAMP / NIST 800-63B AAL3 populate this with FIDO-certified
	// authenticator AAGUIDs. R9-1: an allow-list rejects "none"/self
	// attestation outright (the AAGUID has no attestation vouching for
	// it in either shape). R10-2: for every OTHER (x5c-carrying)
	// attestation type, AAGUIDPolicy.Enforce independently re-verifies
	// the attestation leaf certificate against AttestationRoots — which
	// is REQUIRED whenever AAGUIDAllowList is non-empty — and rejects a
	// self-signed leaf unconditionally. Neither go-webauthn's own
	// packed-attestation handler nor its MetadataProvider/MDS path can
	// be relied on for this: the former never validates the x5c chain
	// at all, and the latter (protocol/metadata.go's ValidateMetadata)
	// skips chain validation entirely whenever the leaf is self-signed —
	// exactly the certificate an attacker mints trivially. See
	// AAGUIDPolicy's doc for the full authenticator-binding guarantee
	// this now provides.
	AAGUIDAllowList [][]byte
	// AttestationRoots is the trust-anchor pool AAGUIDPolicy.Enforce
	// verifies an x5c-carrying attestation leaf certificate against
	// (R10-2). REQUIRED whenever AAGUIDAllowList is non-empty — NewServer
	// returns ErrInvalidConfig otherwise, since an allow-list with no
	// trust anchor to verify attestation chains against cannot
	// distinguish a genuinely vendor-attested authenticator from a
	// trivially self-signed forgery. Populate from your accepted FIDO
	// vendor attestation root certificates (e.g. via
	// security.webauthn.attestation_roots_path in a generated server).
	AttestationRoots *x509.CertPool
	// AttestationPreference: "none" | "indirect" | "direct" | "enterprise".
	// FedRAMP Moderate+ should use "direct" or "enterprise"; default "direct".
	// Note this is only a REQUEST to the client/authenticator — nothing in
	// this package or go-webauthn itself compares the returned attestation
	// statement's actual format against the preference that was requested,
	// so a response can still come back with weaker attestation (e.g.
	// "none") than requested. AAGUIDPolicy.Enforce's R9-1 fail-closed check
	// is what actually gates on the returned attestation, not this field.
	AttestationPreference string
	// UserVerification: "required" | "preferred" | "discouraged".
	// FedRAMP AAL3 requires "required".
	UserVerification string
	// RequireResidentKey makes registered credentials discoverable
	// (passkey-style); enable for usernameless flows.
	RequireResidentKey bool

	// MetadataProvider, when set, is passed through to the underlying
	// webauthn.Config.MDS, enabling go-webauthn's own ValidateMetadata
	// path (FIDO MDS status/trust-anchor lookups keyed by AAGUID) for
	// attestation types that carry a certificate chain. Optional, and —
	// as of R10-2 — NOT what closes the residual chain-verification gap
	// AAGUIDPolicy.Enforce is otherwise vulnerable to: AttestationRoots
	// (required whenever AAGUIDAllowList is non-empty) is what does
	// that, independently of whether MetadataProvider is configured.
	//
	// Two separate reasons MetadataProvider is not a substitute:
	//
	//  1. go-webauthn's ValidateMetadata (protocol/metadata.go) skips
	//     x5c chain validation entirely whenever the attestation leaf
	//     certificate is SELF-SIGNED (Subject.CommonName ==
	//     Issuer.CommonName) — precisely the shape an attacker mints
	//     trivially, satisfying the packed §8.2.1 certificate-shape
	//     rules without holding any real vendor attestation key. This
	//     holds true even with a maximally strict, fully-populated MDS
	//     provider.
	//  2. go-webauthn's metadata.Provider interface fails OPEN by
	//     default: protocol/metadata.go only errors on a missing MDS
	//     entry for an AAGUID when the provider's GetValidateEntry(ctx)
	//     method returns true. A permissive provider (one that returns
	//     false, or a stub/test double that doesn't implement real MDS
	//     lookups) validates NOTHING — GetEntry can return (nil, nil)
	//     and registration proceeds regardless of whether any genuine
	//     metadata backs the claimed AAGUID.
	MetadataProvider metadata.Provider

	Sessions    SessionStore
	Credentials CredentialStore
}

Config configures a Server.

type CredentialStore ¶

type CredentialStore interface {
	Add(ctx context.Context, tenantID, userID string, c webauthn.Credential) error
	GetByUser(ctx context.Context, tenantID, userID string) ([]webauthn.Credential, error)
	GetByID(ctx context.Context, tenantID string, credentialID []byte) (userID string, c webauthn.Credential, err error)
	UpdateSignCount(ctx context.Context, tenantID, userID string, credentialID []byte, count uint32) error
	Delete(ctx context.Context, tenantID, userID string, credentialID []byte) error
}

CredentialStore persists registered authenticators. Implementations MUST be safe for concurrent use. Every method takes a tenantID as the first key component; cross-tenant reads and writes MUST be impossible (REQ-0013 — mirrors devnw.dev/oidc internal/db/webauthn_credentials.go). This isolation MUST hold structurally — an implementation must not derive the tenant/user scope by concatenating the two into a single delimited string and re-splitting it, since neither tenantID nor userID is guaranteed delimiter-free (R11-2: a naive "tenant+'|'+user" key let (tenant="acme|x", user="bob") and (tenant="acme", user="x|bob") collapse onto the same row). NewMemoryCredentialStore's memCredStore satisfies this with a structured (tenant, user) map key rather than a composed string.

Add MUST be an upsert: a call with a credential ID that already has a stored row (scoped by tenantID+userID) MUST replace that row in place (MERGE-on-conflict semantics), never append a duplicate. Server calls Add again on every successful login to persist an advanced SignCount and refreshed Flags (see webauthnx.go FinishLogin, L-42) — an implementation that does not upsert accumulates one duplicate row per login for the same credential ID, which both grows the store unboundedly and makes GetByUser return an ever-larger duplicate set (R9-3). NewMemoryCredentialStore's memCredStore.Add satisfies this by scanning for a matching ID before appending.

Credential IDs MUST be unique per tenant (R10-1): Add MUST reject an ID already bound to a DIFFERENT userID within the same tenant, rather than silently creating a second row under a second user for the same credential ID. The credential ID is fully attacker/client-chosen (§5.4.3), so without this guarantee an attacker can register their own key under a victim's existing credential ID; GetByID (below) then has two candidate rows to resolve for the same ID, and which one it returns determines whose account a forged assertion signed by the attacker's key is reported as authenticating — see FinishLogin's discoverable-login resolution in webauthnx.go, which depends on GetByID returning a single, unambiguous owner per credential ID. NewMemoryCredentialStore's memCredStore.Add satisfies this by scanning every OTHER user's rows in the tenant before appending a new row and returning ErrCredentialAlreadyRegistered on a cross-user collision.

func NewMemoryCredentialStore() CredentialStore

type FinishLoginEvent ¶

type FinishLoginEvent struct {
	TenantID string
	// Subject is the authenticated user (the owner that began the
	// ceremony and the credential's user_id).
	Subject string
	// Credential is the credential that verified the assertion.
	// SignCount has already been advanced atomically by the store.
	Credential *webauthn.Credential
}

FinishLoginEvent captures the outcome of a verified WebAuthn login. The post-ceremony OnLoginVerified hook receives it so consumers can mint downstream artifacts (e.g. OIDC authorization codes, step-up JWTs) without apic taking on OAuth-specific responsibilities.

type FinishLoginOut ¶

type FinishLoginOut struct {
	UserID       []byte
	CredentialID []byte
	SignCount    uint32
	// Credential is the credential that verified the assertion. SignCount
	// has already been advanced atomically by the store. Exposed so the
	// generated handler can hand it to the OnLoginVerifiedHook (GENWA-W2)
	// without re-loading from the store.
	Credential *webauthn.Credential
}

FinishLoginOut is the response shape for the assertion ceremony complete step.

type FinishRegistrationOut ¶

type FinishRegistrationOut struct {
	CredentialID []byte
}

FinishRegistrationOut is the response shape for the registration ceremony complete step.

type OnLoginVerifiedHook ¶

type OnLoginVerifiedHook func(w http.ResponseWriter, r *http.Request, ev FinishLoginEvent) (body []byte, contentType string, err error)

OnLoginVerifiedHook is the post-ceremony hook signature. It runs AFTER FinishLogin verifies the assertion and updates sign-count. The returned bytes (when non-nil) become the response body — the generated handler writes them verbatim with the supplied Content- Type. Returning a non-nil error makes the handler emit the generic 403 envelope; the wrapped reason flows into obsx.LogAudit for operators but never to the client.

The hook receives r so consumers can read query params (e.g. OIDC state/redirect_uri/code_challenge), and w so they can set additional headers (Set-Cookie, Cache-Control: no-store, etc.). Returning (nil, nil) tells the handler to fall through to the generated default response.

type RecordingResponseWriter ¶

type RecordingResponseWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

RecordingResponseWriter wraps an http.ResponseWriter so a caller can later ask whether the wrapped writer committed any response bytes. Used by the generated webauthn_authenticate_complete handler to suppress a fallback WriteForbidden call when the post-ceremony hook already wrote a response AND THEN returned an error.

The wrapper records the call BEFORE forwarding to the inner writer so a panic in the inner WriteHeader/Write still leaves Wrote() == true; the handler must assume the wire has been touched.

func WrapRecording(w http.ResponseWriter) *RecordingResponseWriter

func (r *RecordingResponseWriter) Write(b []byte) (int, error)

func (r *RecordingResponseWriter) WriteHeader(status int)

func (r *RecordingResponseWriter) Wrote() bool

type Server ¶

type Server struct {
	// contains filtered or unexported fields
}

Server is the public façade for ceremonies.

func NewServer(cfg Config) (*Server, error)

func (s *Server) BeginLogin(ctx context.Context, tenantID, owner string, userID []byte) (*BeginLoginOut, error)

func (s *Server) BeginRegistration(ctx context.Context, tenantID, owner string, u User) (*BeginRegistrationOut, error)

func (s *Server) FinishLogin(ctx context.Context, tenantID, owner, sessionID string, body []byte) (*FinishLoginOut, error)

func (s *Server) FinishRegistration(ctx context.Context, tenantID, owner, sessionID string, body []byte) (*FinishRegistrationOut, error)

func (s *Server) RPID() string

type SessionStore ¶

type SessionStore interface {
	Put(ctx context.Context, tenantID string, sd webauthn.SessionData, owner string, ttl time.Duration) (string, error)
	Take(ctx context.Context, tenantID, id string) (sd webauthn.SessionData, owner string, err error)
}

SessionStore persists short-lived ceremony state. Implementations MUST treat Take() as one-shot — re-consuming the same session id MUST return ErrSessionNotFound (or ErrSessionConsumed). This protects against replay of the registration/authentication blob.

Every method takes a tenantID; cross-tenant Take MUST be indistinguishable from a missing row (ErrSessionNotFound). Put also records an owner string so Task 1.2 (GAP-0057) can enforce that the caller who completes the ceremony is the same subject that started it. Take returns the owner so callers can match it against the authenticated subject without a second round-trip.

func NewMemorySessionStore() SessionStore

type StepUpClaims ¶

type StepUpClaims struct {
	// Subject is the principal the step-up assertion is bound to.
	// RFC 7519 §4.1.2. Required.
	Subject string

	// AMR is the RFC 8176 Authentication Methods References list.
	// Apic WebAuthn FinishLogin mints AMR:["webauthn"]. Required —
	// a step-up token with no AMR conveys nothing the regular access
	// token doesn't already carry.
	AMR []string

	// Issuer ("iss") is optional. Resource servers configured with
	// JWTVerifyOptions.RequireIssuer will reject tokens that omit it,
	// so production deployments SHOULD set this.
	Issuer string

	// Audience ("aud") is optional. Same RequireAudience caveat as
	// Issuer. Apic callers typically pass their own service URL so
	// step-up tokens minted for service A cannot be replayed against
	// service B.
	Audience string

	// TTL bounds the lifetime of the assertion. Defaults to
	// defaultStepUpTTL when zero or negative; the helper does not
	// permit a token with TTL > 1 hour by accident — callers that
	// genuinely need a long-lived step-up should issue a regular
	// JWT, not a step-up one.
	TTL time.Duration
}

StepUpClaims captures the minimum claim set RFC 8176 §1 expects for an authentication-method-reference assertion. AMR is the list of auth methods the principal completed during this session; typical values are registered in the IANA "JSON Web Token Claims" registry — "webauthn", "pwd", "otp", "mfa", "hwk", "sc". When a downstream resource gates on "webauthn", the receiving server checks the claim with RequireAMR.

type User ¶

type User struct {
	ID          []byte
	Name        string
	DisplayName string
}

User is the minimal subject identity passed into a ceremony.