feat(protocol): current user details signal constructor (#766)

NewSignalCurrentUserDetails completes the trio alongside NewSignalAllAcceptedCredentials and CredentialDescriptor.SignalUnknownCredential. It takes CurrentUserDetailsUser, a subset of webauthn.User, so the user value the ceremony methods already take satisfies it without an adapter, and a compile time assertion in the webauthn tests keeps that true. The Config.EncodeUserIDAsString comment now also records that the options it produces are not the PublicKeyCredentialCreationOptionsJSON form and are rejected by parseCreationOptionsFromJSON, since user.id must be a Base64URLString there.

Author: james-d-elliott

protocol/signals.go

@@ -1,9 +1,28 @@
 package protocol
 
+import (
+	"reflect"
+)
+
+func signalUserIsNil(user any) bool {
+	if user == nil {
+		return true
+	}
+
+	switch value := reflect.ValueOf(user); value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}
+
 // NewSignalAllAcceptedCredentials creates a new SignalAllAcceptedCredentials struct that can simply be encoded with
 // json.Marshal.
+//
+// A nil user, including a nil pointer carried in a non-nil interface, yields a nil result.
 func NewSignalAllAcceptedCredentials(rpid string, user AllAcceptedCredentialsUser) *SignalAllAcceptedCredentials {
-	if user == nil {
+	if signalUserIsNil(user) {
 		return nil
 	}
 
@@ -29,6 +48,27 @@ type SignalAllAcceptedCredentials struct {
 	UserID                   URLEncodedBase64   `json:"userId"`
 }
 
+// NewSignalCurrentUserDetails creates a new SignalCurrentUserDetails struct that can simply be encoded with
+// json.Marshal. It is the counterpart of [NewSignalAllAcceptedCredentials] for the signal a Relying Party sends
+// after the name or display name of a user account changes.
+//
+// A [github.com/go-webauthn/webauthn/webauthn.User] satisfies [CurrentUserDetailsUser] as it stands, so the user
+// value the ceremony methods already take can be passed straight through.
+//
+// A nil user, including a nil pointer carried in a non-nil interface, yields a nil result.
+func NewSignalCurrentUserDetails(rpid string, user CurrentUserDetailsUser) *SignalCurrentUserDetails {
+	if signalUserIsNil(user) {
+		return nil
+	}
+
+	return &SignalCurrentUserDetails{
+		DisplayName: user.WebAuthnDisplayName(),
+		Name:        user.WebAuthnName(),
+		RPID:        rpid,
+		UserID:      user.WebAuthnID(),
+	}
+}
+
 // SignalCurrentUserDetails is a struct which represents the CDDL of the same name.
 type SignalCurrentUserDetails struct {
 	DisplayName string           `json:"displayName"`
@@ -49,3 +89,12 @@ type AllAcceptedCredentialsUser interface {
 	WebAuthnID() []byte
 	WebAuthnCredentialIDs() [][]byte
 }
+
+// CurrentUserDetailsUser is an interface that can be implemented by a user to provide the details a Relying Party
+// signals after they change. It is a subset of [github.com/go-webauthn/webauthn/webauthn.User], which therefore
+// satisfies it without any additional method.
+type CurrentUserDetailsUser interface {
+	WebAuthnID() []byte
+	WebAuthnName() string
+	WebAuthnDisplayName() string
+}

protocol/signals_test.go

@@ -51,9 +51,85 @@ func TestNewSignalAllAcceptedCredentials(t *testing.T) {
 	}
 }
 
+func TestNewSignalCurrentUserDetails(t *testing.T) {
+	testCases := []struct {
+		name         string
+		rpid         string
+		have         CurrentUserDetailsUser
+		expected     *SignalCurrentUserDetails
+		expectedJSON string
+	}{
+		{
+			"ShouldHandleNil",
+			"example.com",
+			nil,
+			nil,
+			"null",
+		},
+		{
+			"ShouldHandleStandard",
+			"example.com",
+			&signalUser{
+				id:          []byte("123"),
+				name:        "alex",
+				displayName: "Alex Müller",
+			},
+			&SignalCurrentUserDetails{
+				DisplayName: "Alex Müller",
+				Name:        "alex",
+				RPID:        "example.com",
+				UserID:      []byte("123"),
+			},
+			`{"displayName":"Alex Müller","name":"alex","rpId":"example.com","userId":"MTIz"}`,
+		},
+		{
+			"ShouldHandleEmptyDetails",
+			"example.com",
+			&signalUser{
+				id: []byte("123"),
+			},
+			&SignalCurrentUserDetails{
+				RPID:   "example.com",
+				UserID: []byte("123"),
+			},
+			`{"displayName":"","name":"","rpId":"example.com","userId":"MTIz"}`,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			actual := NewSignalCurrentUserDetails(tc.rpid, tc.have)
+
+			assert.Equal(t, tc.expected, actual)
+
+			data, err := json.Marshal(actual)
+			assert.NoError(t, err)
+			assert.Equal(t, tc.expectedJSON, string(data))
+		})
+	}
+}
+
+func TestNewSignalTypedNilUser(t *testing.T) {
+	var user *signalUser
+
+	t.Run("ShouldHandleAllAcceptedCredentials", func(t *testing.T) {
+		assert.NotPanics(t, func() {
+			assert.Nil(t, NewSignalAllAcceptedCredentials("example.com", user))
+		})
+	})
+
+	t.Run("ShouldHandleCurrentUserDetails", func(t *testing.T) {
+		assert.NotPanics(t, func() {
+			assert.Nil(t, NewSignalCurrentUserDetails("example.com", user))
+		})
+	})
+}
+
 type signalUser struct {
 	id          []byte
 	credentials [][]byte
+	name        string
+	displayName string
 }
 
 func (u *signalUser) WebAuthnID() []byte {
@@ -63,3 +139,11 @@ func (u *signalUser) WebAuthnID() []byte {
 func (u *signalUser) WebAuthnCredentialIDs() [][]byte {
 	return u.credentials
 }
+
+func (u *signalUser) WebAuthnName() string {
+	return u.name
+}
+
+func (u *signalUser) WebAuthnDisplayName() string {
+	return u.displayName
+}

webauthn/types.go

@@ -104,6 +104,22 @@ type Config struct {
 	// EncodeUserIDAsString ensures the user.id value during registrations is encoded as a raw UTF8 string. This is
 	// useful when you only use printable ASCII characters for the random user.id but the browser library does not
 	// decode the URL Safe Base64 data.
+	//
+	// The resulting options are not the PublicKeyCredentialCreationOptionsJSON form, which requires user.id to be a
+	// Base64URLString, so a client which passes them to PublicKeyCredential.parseCreationOptionsFromJSON() does one
+	// of two things with them, neither of them what the Relying Party intended:
+	//
+	//   - A value outside the base64url alphabet, such as "alice@example.com", fails to decode and the call throws.
+	//     So does one whose length is one more than a multiple of four, such as "a" or "alice", since that is not a
+	//     length any base64 encoding produces.
+	//   - A value which happens to be valid base64url is accepted and decoded into unrelated bytes. "user123" is
+	//     one such value, and arrives at the authenticator as the five bytes ba c7 ab d7 6d, so the user handle
+	//     stored against the credential is not the one that was sent.
+	//
+	// The second outcome is the dangerous one, since nothing reports it. Enable this only for a client which does
+	// its own decoding, which is the situation it exists for.
+	//
+	// Specification: §5.1.8. Deserialize Registration Ceremony Options (https://www.w3.org/TR/webauthn-3/#sctn-parseCreationOptionsFromJSON)
 	EncodeUserIDAsString bool
 
 	// Timeouts configures various timeouts.

webauthn/types_test.go

@@ -562,6 +562,8 @@ type defaultUser struct {
 
 var _ User = (*defaultUser)(nil)
 
+var _ protocol.CurrentUserDetailsUser = (User)(nil)
+
 func (user *defaultUser) WebAuthnID() []byte {
 	return user.id
 }