passkeys

Documentation

Overview

Package passkeys provides WebAuthn/FIDO2 passkey registration and authentication using the go-webauthn library.

All credential IDs are encoded as base64url (unpadded) per the WebAuthn spec. Public keys are stored as standard base64 (with padding) for compactness.

Security:

• Never log public keys or credential data in full
• Challenge comparison is handled by go-webauthn (constant-time)
• Sign count verification detects cloned authenticators

Index

• func ExtractCredentialID(credentialJSON string) (string, error)
• type Config
• type RegistrationResult
• type WebAuthnService
  • func NewWebAuthnService(cfg Config) (*WebAuthnService, error)
  • func (s *WebAuthnService) BeginAuthentication(allowedCredIDs []string) (optionsJSON string, challenge string, err error)
  • func (s *WebAuthnService) BeginRegistration(userID, userEmail, userDisplayName string, existingCredIDs []string) (optionsJSON string, challenge string, err error)
  • func (s *WebAuthnService) CompleteAuthentication(credentialJSON string, expectedChallenge string, storedPublicKeyB64 string, ...) (newSignCount uint32, err error)
  • func (s *WebAuthnService) CompleteRegistration(credentialJSON string, expectedChallenge string) (result *RegistrationResult, err error)
• type WebAuthnUser
  • func (u *WebAuthnUser) WebAuthnCredentials() []webauthn.Credential
  • func (u *WebAuthnUser) WebAuthnDisplayName() string
  • func (u *WebAuthnUser) WebAuthnID() []byte
  • func (u *WebAuthnUser) WebAuthnName() string

Functions

func ExtractCredentialID

func ExtractCredentialID(credentialJSON string) (string, error)

ExtractCredentialID extracts the credential ID from a raw credential JSON response (from navigator.credentials.get() or .create()). The returned value is base64url-encoded without padding.

Types

type Config

type Config struct {
	RPID   string // e.g. "localhost" or "glassa.work"
	RPName string // e.g. "Glassa Work"
	Origin string // e.g. "https://glassa.work" or "http://localhost:9002"
}

Config for the WebAuthn relying party.

type RegistrationResult

type RegistrationResult struct {
	CredentialID   string // base64url (unpadded)
	PublicKey      string // base64 (standard, with padding)
	SignCount      uint32
	AAGUID         string
	Transports     string // comma-separated
	BackupEligible bool   // WebAuthn BE flag — persist + replay at login
	BackupState    bool   // WebAuthn BS flag — persist + replay at login
}

RegistrationResult holds the verified credential data after a successful registration ceremony. All fields are in their storage-friendly encoding.

type WebAuthnService

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

WebAuthnService wraps go-webauthn for registration and authentication ceremonies. It is safe for concurrent use.

func NewWebAuthnService

func NewWebAuthnService(cfg Config) (*WebAuthnService, error)

NewWebAuthnService creates a WebAuthnService from the given Config. Returns an error if the configuration is invalid.

func (*WebAuthnService) BeginAuthentication

func (s *WebAuthnService) BeginAuthentication(
	allowedCredIDs []string,
) (optionsJSON string, challenge string, err error)

BeginAuthentication generates PublicKeyCredentialRequestOptions for navigator.credentials.get().

allowedCredIDs contains base64url credential IDs the user has registered. If empty, the authenticator may use any discoverable (resident) credential — i.e. the usernameless flow.

Returns optionsJSON and challenge (base64url).

func (*WebAuthnService) BeginRegistration

func (s *WebAuthnService) BeginRegistration(
	userID, userEmail, userDisplayName string,
	existingCredIDs []string,
) (optionsJSON string, challenge string, err error)

BeginRegistration generates PublicKeyCredentialCreationOptions for navigator.credentials.create().

existingCredIDs contains base64url credential IDs to exclude (the user's already-registered devices).

Returns optionsJSON (the serialized options to send to the frontend) and challenge (base64url for server-side storage).

func (*WebAuthnService) CompleteAuthentication

func (s *WebAuthnService) CompleteAuthentication(
	credentialJSON string,
	expectedChallenge string,
	storedPublicKeyB64 string,
	storedSignCount uint32,
	storedCredentialID string,
	userID string,
	backupEligible bool,
	backupState bool,
) (newSignCount uint32, err error)

CompleteAuthentication verifies the assertion response from navigator.credentials.get().

It validates the signature against the stored public key and checks the sign count for cloned authenticator detection.

Returns the new sign count on success.

func (*WebAuthnService) CompleteRegistration

func (s *WebAuthnService) CompleteRegistration(
	credentialJSON string,
	expectedChallenge string,
) (result *RegistrationResult, err error)

CompleteRegistration verifies the attestation response from the browser after navigator.credentials.create() completes.

credentialJSON is the JSON-serialized credential from the browser. expectedChallenge is the base64url challenge stored server-side during BeginRegistration.

Returns a RegistrationResult with the verified credential data.

type WebAuthnUser

type WebAuthnUser struct {
	ID          []byte
	Name        string
	DisplayName string
	Credentials []webauthn.Credential
}

WebAuthnUser is a minimal implementation of the webauthn.User interface. It carries just enough data for the go-webauthn library to generate registration and authentication options.

func (*WebAuthnUser) WebAuthnCredentials

func (u *WebAuthnUser) WebAuthnCredentials() []webauthn.Credential

WebAuthnCredentials returns the user's registered credentials.

func (*WebAuthnUser) WebAuthnDisplayName

func (u *WebAuthnUser) WebAuthnDisplayName() string

WebAuthnDisplayName returns the human-friendly display name.

func (*WebAuthnUser) WebAuthnID

func (u *WebAuthnUser) WebAuthnID() []byte

WebAuthnID returns the user handle (opaque byte sequence).

func (*WebAuthnUser) WebAuthnName

func (u *WebAuthnUser) WebAuthnName() string

WebAuthnName returns the user's account identifier (typically email).