auth: publish self-hosted administration foundations

authwebauthn/service.go

@@ -190,7 +190,7 @@ func (service *Service) BeginEnrollment(ctx context.Context, enrollmentToken, la
 	if err != nil {
 		return BeginResult{}, err
 	}
-	return service.beginRegistration(ctx, user, label)
+	return service.beginRegistration(ctx, user, label, CeremonyRegistration, [32]byte{})
 }
 
 func (service *Service) BeginRegistration(ctx context.Context, userID, label string) (BeginResult, error) {
@@ -198,10 +198,28 @@ func (service *Service) BeginRegistration(ctx context.Context, userID, label str
 	if err != nil {
 		return BeginResult{}, err
 	}
-	return service.beginRegistration(ctx, user, label)
+	return service.beginRegistration(ctx, user, label, CeremonyRegistration, [32]byte{})
 }
 
-func (service *Service) beginRegistration(ctx context.Context, user auth.User, label string) (BeginResult, error) {
+// BeginPasswordMigration starts registration for an already authenticated
+// password-backed user. Completion atomically retires the password and revokes
+// all sessions, including the session that authorized this ceremony.
+func (service *Service) BeginPasswordMigration(ctx context.Context, userID, label string) (BeginResult, error) {
+	user, err := service.repository.UserByID(ctx, strings.TrimSpace(userID))
+	if err != nil {
+		return BeginResult{}, err
+	}
+	exists, err := service.repository.PasswordCredentialExists(ctx, user.ID)
+	if err != nil {
+		return BeginResult{}, err
+	}
+	if !exists {
+		return BeginResult{}, ErrPasswordNotAvailable
+	}
+	return service.beginRegistration(ctx, user, label, CeremonyRegistration, passwordMigrationBinding(user.ID))
+}
+
+func (service *Service) beginRegistration(ctx context.Context, user auth.User, label, kind string, binding [32]byte) (BeginResult, error) {
 	label, err := credentialLabel(label)
 	if err != nil {
 		return BeginResult{}, err
@@ -223,14 +241,35 @@ func (service *Service) beginRegistration(ctx context.Context, user auth.User, l
 	if err != nil {
 		return BeginResult{}, fmt.Errorf("authwebauthn: begin registration: %w", err)
 	}
-	return service.storeCeremony(ctx, CeremonyRegistration, user.ID, label, session, [32]byte{}, creation.Response, service.config.RegistrationTTL)
+	return service.storeCeremony(ctx, kind, user.ID, label, session, binding, creation.Response, service.config.RegistrationTTL)
 }
 
 func (service *Service) FinishRegistration(ctx context.Context, ceremonyToken string, response []byte) (Credential, error) {
+	return service.finishRegistration(ctx, ceremonyToken, CeremonyRegistration, [32]byte{}, response, false)
+}
+
+// FinishPasswordMigration verifies the new passkey and persists it together
+// with password retirement and session revocation in one storage transaction.
+func (service *Service) FinishPasswordMigration(ctx context.Context, ceremonyToken string, response []byte) (Credential, error) {
 	ceremony, err := service.takeCeremony(ctx, ceremonyToken, CeremonyRegistration)
 	if err != nil {
 		return Credential{}, err
 	}
+	return service.finishRegistrationCeremony(ctx, ceremony, passwordMigrationBinding(ceremony.UserID), response, true)
+}
+
+func (service *Service) finishRegistration(ctx context.Context, ceremonyToken, kind string, expectedBinding [32]byte, response []byte, retirePassword bool) (Credential, error) {
+	ceremony, err := service.takeCeremony(ctx, ceremonyToken, kind)
+	if err != nil {
+		return Credential{}, err
+	}
+	return service.finishRegistrationCeremony(ctx, ceremony, expectedBinding, response, retirePassword)
+}
+
+func (service *Service) finishRegistrationCeremony(ctx context.Context, ceremony Ceremony, expectedBinding [32]byte, response []byte, retirePassword bool) (Credential, error) {
+	if ceremony.BindingDigest != expectedBinding {
+		return Credential{}, ErrOperationBinding
+	}
 	if len(response) == 0 || len(response) > maxResponseBytes {
 		return Credential{}, errors.New("authwebauthn: registration response is invalid")
 	}
@@ -263,11 +302,20 @@ func (service *Service) FinishRegistration(ctx context.Context, ceremonyToken st
 	}
 	now := service.now().UTC()
 	record := Credential{ID: append([]byte(nil), verified.ID...), UserID: user.ID, Label: ceremony.Label, Data: encoded, CreatedAt: now}
-	audit, err := service.audit(user.ID, "auth.passkey.add", "passkey", base64.RawURLEncoding.EncodeToString(verified.ID), "A passkey was enrolled.")
+	action, summary := "auth.passkey.add", "A passkey was enrolled."
+	if retirePassword {
+		action, summary = "auth.passkey.migrate", "A passkey was enrolled and the legacy password credential was retired."
+	}
+	audit, err := service.audit(user.ID, action, "passkey", base64.RawURLEncoding.EncodeToString(verified.ID), summary)
 	if err != nil {
 		return Credential{}, err
 	}
-	if err = service.repository.SaveCredential(ctx, record, audit); err != nil {
+	if retirePassword {
+		err = service.repository.SaveCredentialAndRetirePassword(ctx, record, audit)
+	} else {
+		err = service.repository.SaveCredential(ctx, record, audit)
+	}
+	if err != nil {
 		return Credential{}, err
 	}
 	return record, nil
@@ -594,6 +642,10 @@ func credentialRemovalBinding(userID string, credentialID []byte) []byte {
 	return []byte("gamertan-web/passkey-remove/v1\x00" + userID + "\x00" + base64.RawURLEncoding.EncodeToString(credentialID))
 }
 
+func passwordMigrationBinding(userID string) [32]byte {
+	return BindingDigest([]byte("gamertan-web/password-to-passkey/v1\x00" + userID))
+}
+
 func validateOrigin(rpID, rawOrigin string) error {
 	if strings.TrimSpace(rpID) == "" || strings.TrimSpace(rawOrigin) == "" {
 		return errors.New("authwebauthn: relying-party ID and origin are required")

authwebauthn/service_test.go

@@ -4,6 +4,7 @@ package authwebauthn_test
 
 import (
 	"bytes"
+	"crypto/sha256"
 	"encoding/json"
 	"errors"
 	"io"
@@ -140,6 +141,51 @@ func TestRecoveryRevokesSessionsAndIssuesSingleUseEnrollment(t *testing.T) {
 	}
 }
 
+func TestPasswordMigrationCeremonyIsBoundAndUnavailableAfterRetirement(t *testing.T) {
+	now := time.Date(2026, 8, 27, 12, 0, 0, 0, time.UTC)
+	store, err := authsqlite.Open(t.TempDir() + "/auth.db")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	authService, err := auth.New(store, auth.Options{Random: &counterReader{}, Now: func() time.Time { return now }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	user, err := authService.CreateUser(t.Context(), auth.CreateUser{Username: "legacy.user", Email: "legacy@example.test", DisplayName: "Legacy User", Password: "legacy migration password"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	service, err := authwebauthn.New(store, authService, authwebauthn.Config{RPID: "observatory.test", RPDisplayName: "Observatory", Origin: "https://observatory.test", RequiredCredentialCount: 1, Random: &counterReader{}, Now: func() time.Time { return now }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	begin, err := service.BeginPasswordMigration(t.Context(), user.ID, "Primary passkey")
+	if err != nil {
+		t.Fatal(err)
+	}
+	digest := sha256.Sum256([]byte(begin.CeremonyToken))
+	ceremony, err := store.TakeCeremony(t.Context(), digest, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ceremony.Kind != authwebauthn.CeremonyRegistration || ceremony.BindingDigest == ([32]byte{}) || ceremony.UserID != user.ID {
+		t.Fatalf("unexpected migration ceremony: %+v", ceremony)
+	}
+	credential := wa.Credential{ID: bytes.Repeat([]byte{9}, 32), PublicKey: []byte{1, 2, 3}}
+	encoded, err := json.Marshal(credential)
+	if err != nil {
+		t.Fatal(err)
+	}
+	audit := auth.AuditEvent{ID: "migration-direct", ActorUserID: user.ID, Action: "auth.passkey.migrate", ResourceType: "passkey", ResourceID: "credential", Summary: "migration", CreatedAt: now}
+	if err = store.SaveCredentialAndRetirePassword(t.Context(), authwebauthn.Credential{ID: credential.ID, UserID: user.ID, Label: "Primary", Data: encoded, CreatedAt: now}, audit); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = service.BeginPasswordMigration(t.Context(), user.ID, "Replay"); !errors.Is(err, authwebauthn.ErrPasswordNotAvailable) {
+		t.Fatalf("retired password migration err=%v", err)
+	}
+}
+
 func TestConfigurationAndEntropyFailures(t *testing.T) {
 	store, err := authsqlite.Open(t.TempDir() + "/auth.db")
 	if err != nil {

authwebauthn/types.go

@@ -25,6 +25,7 @@ var (
 	ErrOperationBinding      = errors.New("authwebauthn: operation binding does not match")
 	ErrPasskeyReadiness      = errors.New("authwebauthn: at least two passkeys are required")
 	ErrUnsupportedCredential = errors.New("authwebauthn: credential algorithm is unsupported")
+	ErrPasswordNotAvailable  = errors.New("authwebauthn: password migration is not available")
 )
 
 const (
@@ -100,7 +101,9 @@ type Repository interface {
 	UserByIdentifier(context.Context, string) (auth.User, error)
 	UserByCredentialID(context.Context, []byte) (auth.User, error)
 	CredentialsByUserID(context.Context, string) ([]Credential, error)
+	PasswordCredentialExists(context.Context, string) (bool, error)
 	SaveCredential(context.Context, Credential, auth.AuditEvent) error
+	SaveCredentialAndRetirePassword(context.Context, Credential, auth.AuditEvent) error
 	UpdateCredential(context.Context, Credential) error
 	DeleteCredential(context.Context, string, []byte, int, auth.AuditEvent) error
 	CredentialCount(context.Context, string) (int, error)