feat(passkeys): add configuration, error codes, and schemas

Author: fadymak

internal/api/apierrors/errorcode.go

@@ -112,4 +112,15 @@ const (
 
 	ErrorCodeCustomProviderNotFound  ErrorCode = "custom_provider_not_found"
 	ErrorCodeOverCustomProviderQuota ErrorCode = "over_custom_provider_quota"
+
+	// Passkey feature-level errors
+	ErrorCodePasskeyDisabled ErrorCode = "passkey_disabled"
+	ErrorCodeTooManyPasskeys ErrorCode = "too_many_passkeys"
+
+	// WebAuthn protocol-level errors (shared between passkeys and MFA WebAuthn)
+	ErrorCodeWebAuthnCredentialNotFound ErrorCode = "webauthn_credential_not_found"
+	ErrorCodeWebAuthnChallengeNotFound  ErrorCode = "webauthn_challenge_not_found"
+	ErrorCodeWebAuthnChallengeExpired   ErrorCode = "webauthn_challenge_expired"
+	ErrorCodeWebAuthnVerificationFailed ErrorCode = "webauthn_verification_failed"
+	ErrorCodeWebAuthnCredentialExists   ErrorCode = "webauthn_credential_exists"
 )

internal/api/middleware.go

@@ -355,6 +355,14 @@ func (a *API) requireManualLinkingEnabled(w http.ResponseWriter, req *http.Reque
 	return ctx, nil
 }
 
+func (a *API) requirePasskeyEnabled(w http.ResponseWriter, req *http.Request) (context.Context, error) {
+	ctx := req.Context()
+	if !a.config.Passkey.Enabled {
+		return nil, apierrors.NewNotFoundError(apierrors.ErrorCodePasskeyDisabled, "Passkeys are disabled")
+	}
+	return ctx, nil
+}
+
 func (a *API) databaseCleanup(cleanup models.Cleaner) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/api/settings.go

@@ -38,6 +38,7 @@ type Settings struct {
 	PhoneAutoconfirm  bool             `json:"phone_autoconfirm"`
 	SmsProvider       string           `json:"sms_provider"`
 	SAMLEnabled       bool             `json:"saml_enabled"`
+	PasskeysEnabled   bool             `json:"passkeys_enabled"`
 }
 
 func (a *API) Settings(w http.ResponseWriter, r *http.Request) error {
@@ -77,5 +78,6 @@ func (a *API) Settings(w http.ResponseWriter, r *http.Request) error {
 		PhoneAutoconfirm:  config.Sms.Autoconfirm,
 		SmsProvider:       config.Sms.Provider,
 		SAMLEnabled:       config.SAML.Enabled,
+		PasskeysEnabled:   config.Passkey.Enabled,
 	})
 }

internal/conf/configuration.go

@@ -177,6 +177,50 @@ type MFAConfiguration struct {
 	WebAuthn                    MFAFactorTypeConfiguration   `split_words:"true"`
 }
 
+type WebAuthnConfiguration struct {
+	RPID                    string        `json:"rp_id" split_words:"true" envconfig:"WEBAUTHN_RP_ID"`
+	RPDisplayName           string        `json:"rp_display_name" split_words:"true" envconfig:"WEBAUTHN_RP_DISPLAY_NAME"`
+	RPOrigins               []string      `json:"rp_origins" split_words:"true" envconfig:"WEBAUTHN_RP_ORIGINS"`
+	ChallengeExpiryDuration time.Duration `json:"challenge_expiry_duration" split_words:"true" default:"5m"`
+}
+
+func (w *WebAuthnConfiguration) Validate() error {
+	if w.RPID == "" {
+		return errors.New("conf: GOTRUE_WEBAUTHN_RP_ID is required when passkeys are enabled")
+	}
+
+	if w.RPDisplayName == "" {
+		return errors.New("conf: GOTRUE_WEBAUTHN_RP_DISPLAY_NAME is required when passkeys are enabled")
+	}
+
+	if len(w.RPOrigins) == 0 {
+		return errors.New("conf: GOTRUE_WEBAUTHN_RP_ORIGINS is required when passkeys are enabled")
+	}
+
+	for _, origin := range w.RPOrigins {
+		u, err := url.Parse(origin)
+		if err != nil {
+			return fmt.Errorf("conf: invalid WebAuthn RP origin %q: %w", origin, err)
+		}
+
+		if u.Scheme == "http" {
+			host := u.Hostname()
+			if host != "localhost" && host != "127.0.0.1" {
+				return fmt.Errorf("conf: WebAuthn RP origin %q must use HTTPS (http is only allowed for localhost/127.0.0.1)", origin)
+			}
+		} else if u.Scheme != "https" {
+			return fmt.Errorf("conf: WebAuthn RP origin %q must use HTTPS", origin)
+		}
+	}
+
+	return nil
+}
+
+type PasskeyConfiguration struct {
+	Enabled            bool `json:"enabled" default:"false"`
+	MaxPasskeysPerUser int  `json:"max_passkeys_per_user" split_words:"true" default:"10"`
+}
+
 type APIConfiguration struct {
 	Host               string
 	Port               string `envconfig:"PORT" default:"8081"`
@@ -358,6 +402,8 @@ type GlobalConfiguration struct {
 	Sessions        SessionsConfiguration    `json:"sessions"`
 	MFA             MFAConfiguration         `json:"MFA"`
 	SAML            SAMLConfiguration        `json:"saml"`
+	WebAuthn        WebAuthnConfiguration    `json:"webauthn"`
+	Passkey         PasskeyConfiguration     `json:"passkey"`
 	CORS            CORSConfiguration        `json:"cors"`
 	IndexWorker     IndexWorkerConfiguration `json:"index_worker" split_words:"true"`
 
@@ -1285,6 +1331,12 @@ func (c *GlobalConfiguration) Validate() error {
 		}
 	}
 
+	if c.Passkey.Enabled {
+		if err := c.WebAuthn.Validate(); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 

internal/conf/configuration_test.go

@@ -1253,6 +1253,113 @@ func TestLoading(t *testing.T) {
 	}
 }
 
+func TestWebAuthnConfigurationValidate(t *testing.T) {
+	// Empty RPID → error
+	{
+		w := &WebAuthnConfiguration{
+			RPDisplayName: "Test",
+			RPOrigins:     []string{"https://example.com"},
+		}
+		err := w.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "GOTRUE_WEBAUTHN_RP_ID is required")
+	}
+
+	// Empty RPDisplayName → error
+	{
+		w := &WebAuthnConfiguration{
+			RPID:      "example.com",
+			RPOrigins: []string{"https://example.com"},
+		}
+		err := w.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "GOTRUE_WEBAUTHN_RP_DISPLAY_NAME is required")
+	}
+
+	// Empty RPOrigins → error
+	{
+		w := &WebAuthnConfiguration{
+			RPID:          "example.com",
+			RPDisplayName: "Example",
+		}
+		err := w.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "GOTRUE_WEBAUTHN_RP_ORIGINS is required")
+	}
+
+	// HTTP origin (not localhost) → error
+	{
+		w := &WebAuthnConfiguration{
+			RPID:          "example.com",
+			RPDisplayName: "Example",
+			RPOrigins:     []string{"http://example.com"},
+		}
+		err := w.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "must use HTTPS")
+	}
+
+	// HTTP localhost is allowed
+	{
+		w := &WebAuthnConfiguration{
+			RPID:          "localhost",
+			RPDisplayName: "Localhost",
+			RPOrigins:     []string{"http://localhost:3000"},
+		}
+		err := w.Validate()
+		require.NoError(t, err)
+	}
+
+	// HTTP 127.0.0.1 is allowed
+	{
+		w := &WebAuthnConfiguration{
+			RPID:          "localhost",
+			RPDisplayName: "Localhost",
+			RPOrigins:     []string{"http://127.0.0.1:3000"},
+		}
+		err := w.Validate()
+		require.NoError(t, err)
+	}
+
+	// Valid HTTPS origins pass
+	{
+		w := &WebAuthnConfiguration{
+			RPID:          "example.com",
+			RPDisplayName: "Example",
+			RPOrigins:     []string{"https://example.com", "https://app.example.com"},
+		}
+		err := w.Validate()
+		require.NoError(t, err)
+	}
+
+	// Conditional validation: disabled passkey skips WebAuthn validation
+	{
+		cfg := &GlobalConfiguration{
+			SiteURL: "https://example.com",
+			API:     APIConfiguration{ExternalURL: "https://example.com"},
+			JWT:     JWTConfiguration{Secret: "a"},
+		}
+		cfg.Passkey.Enabled = false
+		require.NoError(t, cfg.ApplyDefaults())
+		err := cfg.Validate()
+		require.NoError(t, err)
+	}
+
+	// Conditional validation: enabled passkey requires WebAuthn config
+	{
+		cfg := &GlobalConfiguration{
+			SiteURL: "https://example.com",
+			API:     APIConfiguration{ExternalURL: "https://example.com"},
+			JWT:     JWTConfiguration{Secret: "a"},
+		}
+		cfg.Passkey.Enabled = true
+		require.NoError(t, cfg.ApplyDefaults())
+		err := cfg.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "GOTRUE_WEBAUTHN_RP_ID is required")
+	}
+}
+
 func toPtr[T any](v T) *T {
 	return &(&([1]T{T(v)}))[0]
 }

internal/models/cleanup.go

@@ -41,6 +41,7 @@ func NewCleanup(config *conf.GlobalConfiguration) *Cleanup {
 	tableMFAChallenges := Challenge{}.TableName()
 	tableMFAFactors := Factor{}.TableName()
 	tableOAuthClientStates := OAuthClientState{}.TableName()
+	tableWebAuthnChallenges := WebAuthnChallenge{}.TableName()
 
 	c := &Cleanup{}
 
@@ -60,6 +61,7 @@ func NewCleanup(config *conf.GlobalConfiguration) *Cleanup {
 		fmt.Sprintf("delete from %q where id in (select id from %q where created_at < now() - interval '24 hours' limit 100 for update skip locked);", tableOAuthClientStates, tableOAuthClientStates),
 		fmt.Sprintf("delete from %q where id in (select id from %q where created_at < now() - interval '24 hours' limit 100 for update skip locked);", tableMFAChallenges, tableMFAChallenges),
 		fmt.Sprintf("delete from %q where id in (select id from %q where created_at < now() - interval '24 hours' and status = 'unverified' limit 100 for update skip locked);", tableMFAFactors, tableMFAFactors),
+		fmt.Sprintf("delete from %q where id in (select id from %q where expires_at < now() limit 100 for update skip locked);", tableWebAuthnChallenges, tableWebAuthnChallenges),
 	)
 
 	if config.External.AnonymousUsers.Enabled {

internal/models/connection.go

@@ -51,6 +51,8 @@ func TruncateAll(conn *storage.Connection) error {
 			(&pop.Model{Value: OneTimeToken{}}).TableName(),
 			(&pop.Model{Value: OAuthServerClient{}}).TableName(),
 			(&pop.Model{Value: CustomOAuthProvider{}}).TableName(),
+			(&pop.Model{Value: WebAuthnCredential{}}).TableName(),
+			(&pop.Model{Value: WebAuthnChallenge{}}).TableName(),
 		}
 
 		for _, tableName := range tables {

internal/models/errors.go

@@ -170,3 +170,25 @@ func (e CustomOAuthProviderNotFoundError) Error() string {
 func (e CustomOAuthProviderNotFoundError) Is(target error) bool {
 	return target == errNotFound
 }
+
+// WebAuthnCredentialNotFoundError represents when a WebAuthn credential can't be found.
+type WebAuthnCredentialNotFoundError struct{}
+
+func (e WebAuthnCredentialNotFoundError) Error() string {
+	return "WebAuthn credential not found"
+}
+
+func (e WebAuthnCredentialNotFoundError) Is(target error) bool {
+	return target == errNotFound
+}
+
+// WebAuthnChallengeNotFoundError represents when a WebAuthn challenge can't be found.
+type WebAuthnChallengeNotFoundError struct{}
+
+func (e WebAuthnChallengeNotFoundError) Error() string {
+	return "WebAuthn challenge not found"
+}
+
+func (e WebAuthnChallengeNotFoundError) Is(target error) bool {
+	return target == errNotFound
+}

internal/models/factor.go

@@ -150,16 +150,16 @@ type Factor struct {
 	Challenge                 []Challenge                `json:"-" has_many:"challenges"`
 	Phone                     storage.NullString         `json:"phone" db:"phone"`
 	LastChallengedAt          *time.Time                 `json:"last_challenged_at" db:"last_challenged_at"`
-	WebAuthnCredential        *WebAuthnCredential        `json:"-" db:"web_authn_credential"`
+	WebAuthnCredential        *MFAWebAuthnCredential     `json:"-" db:"web_authn_credential"`
 	WebAuthnAAGUID            *uuid.UUID                 `json:"web_authn_aaguid,omitempty" db:"web_authn_aaguid"`
 	LastWebAuthnChallengeData *LastWebAuthnChallengeData `json:"last_webauthn_challenge_data,omitempty" db:"last_webauthn_challenge_data"`
 }
 
-type WebAuthnCredential struct {
+type MFAWebAuthnCredential struct {
 	webauthn.Credential
 }
 
-func (wc *WebAuthnCredential) Value() (driver.Value, error) {
+func (wc *MFAWebAuthnCredential) Value() (driver.Value, error) {
 	if wc == nil {
 		return nil, nil
 	}
@@ -200,7 +200,7 @@ func (lwcd *LastWebAuthnChallengeData) Scan(value interface{}) error {
 	return json.Unmarshal(data, lwcd)
 }
 
-func (wc *WebAuthnCredential) Scan(value interface{}) error {
+func (wc *MFAWebAuthnCredential) Scan(value interface{}) error {
 	if value == nil {
 		wc.Credential = webauthn.Credential{}
 		return nil
@@ -283,7 +283,7 @@ func (f *Factor) GetSecret(decryptionKeys map[string]string, encrypt bool, encry
 }
 
 func (f *Factor) SaveWebAuthnCredential(tx *storage.Connection, credential *webauthn.Credential) error {
-	f.WebAuthnCredential = &WebAuthnCredential{
+	f.WebAuthnCredential = &MFAWebAuthnCredential{
 		Credential: *credential,
 	}
 

internal/models/webauthn_challenge.go

@@ -0,0 +1,60 @@
+package models
+
+import (
+	"database/sql"
+	"time"
+
+	"github.com/gofrs/uuid"
+	"github.com/pkg/errors"
+	"github.com/supabase/auth/internal/storage"
+)
+
+const (
+	WebAuthnChallengeTypeSignup         = "signup"
+	WebAuthnChallengeTypeRegistration   = "registration"
+	WebAuthnChallengeTypeAuthentication = "authentication"
+)
+
+// WebAuthnChallenge maps to the webauthn_challenges table.
+type WebAuthnChallenge struct {
+	ID            uuid.UUID            `json:"id" db:"id"`
+	UserID        *uuid.UUID           `json:"user_id,omitempty" db:"user_id"`
+	ChallengeType string               `json:"challenge_type" db:"challenge_type"`
+	SessionData   *WebAuthnSessionData `json:"session_data" db:"session_data"`
+	CreatedAt     time.Time            `json:"created_at" db:"created_at"`
+	ExpiresAt     time.Time            `json:"expires_at" db:"expires_at"`
+}
+
+func (WebAuthnChallenge) TableName() string {
+	return "webauthn_challenges"
+}
+
+func NewWebAuthnChallenge(userID *uuid.UUID, challengeType string, sessionData *WebAuthnSessionData, expiresAt time.Time) *WebAuthnChallenge {
+	id := uuid.Must(uuid.NewV4())
+	return &WebAuthnChallenge{
+		ID:            id,
+		UserID:        userID,
+		ChallengeType: challengeType,
+		SessionData:   sessionData,
+		ExpiresAt:     expiresAt,
+	}
+}
+
+func FindWebAuthnChallengeByID(conn *storage.Connection, id uuid.UUID) (*WebAuthnChallenge, error) {
+	var challenge WebAuthnChallenge
+	err := conn.Find(&challenge, id)
+	if err != nil && errors.Cause(err) == sql.ErrNoRows {
+		return nil, WebAuthnChallengeNotFoundError{}
+	} else if err != nil {
+		return nil, err
+	}
+	return &challenge, nil
+}
+
+func (c *WebAuthnChallenge) IsExpired() bool {
+	return time.Now().After(c.ExpiresAt)
+}
+
+func (c *WebAuthnChallenge) Delete(tx *storage.Connection) error {
+	return tx.Destroy(c)
+}