Merge branch 'master' into feat-enhance-errors

.github/workflows/codeql.yml

@@ -41,7 +41,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
           egress-policy: audit
 
@@ -50,7 +50,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4
+        uses: github/codeql-action/init@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -60,7 +60,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4
+        uses: github/codeql-action/autobuild@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -73,6 +73,6 @@ jobs:
       #   ./location_of_script_within_repo/buildscript.sh
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4
+        uses: github/codeql-action/analyze@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/dependency-review.yml

@@ -17,11 +17,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
           egress-policy: audit
 
       - name: 'Checkout Repository'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@4081bf99e2866ebe428fc0477b69eb4fcda7220a # v4.4.0
+        uses: actions/dependency-review-action@3b139cfc5fae8b618d3eae3675e383bb1769c019 # v4.5.0

.github/workflows/go.yml

@@ -20,7 +20,7 @@ jobs:
       fail-fast: false
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
           egress-policy: audit
 

.github/workflows/scorecards.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
           egress-policy: audit
 
@@ -71,6 +71,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@ea9e4e37992a54ee68a9622e985e60c8e8f12d9f # v3.27.4
+        uses: github/codeql-action/upload-sarif@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
         with:
           sarif_file: results.sarif

README.md

@@ -313,6 +313,65 @@ table for more information. We also include JSON mappings for those that wish to
 |     attestationObject     |     Attestation.Object     |     attestation.object     | This field is a composite of the attestationObject and the relevant values to validate it |
 | attestationClientDataJSON | Attestation.ClientDataJSON | attestation.clientDataJSON |                                                                                           |
 
+### Flags
+
+It's important to note that the recommendations and requirements for flag storage have changed over the course of the
+evolution of the WebAuthn specification. We at the present time only make the flags classified like this available for
+easy storage however we also make the Protocol Value available. At such a time as these recommendations or requirements
+change we will adapt accordingly. The Protocol Value is a raw representation of the flags and as such is resistant to
+breaking changes whereas the other flags or lack thereof may not be. 
+
+Implementers are therefore encouraged to use
+[func (CredentialFlags) ProtocolValue](https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#CredentialFlags.ProtocolValue)
+to retrieve the raw value and 
+[webauthn.NewCredentialFlags](https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#NewCredentialFlags) to 
+restore it; and instead of using the individual flags to store the value store the Protocol Value, and only store the
+individual flags as a means to perform compliance related decisions.
+
+#### Notable Changes
+
+This contains some notable changes to the flags over the life of the library.
+
+##### v0.11.0
+
+In v0.11.0 we started validating the backup related flags to ensure that they were in a valid state as per the
+requirements in the spec. This introduced issues for some users as they had not been storing them and at least at one
+point the flag values were difficult to obtain.
+
+This has lead to an effective breaking change and a state where some credentials cannot be validated. The resolution to
+this particular issue is to adapt current storage methods so that the values of the flags or each individual flag default
+to a null-like value and manually perform an update to the storage and struct when a credential with null-like values is
+observed.
+
+The values can be obtained prior to validating the parsed response similar to the example below:
+
+```go
+package example
+
+import (
+	"net/http"
+
+	"github.com/go-webauthn/webauthn/protocol"
+	"github.com/go-webauthn/webauthn/webauthn"
+)
+
+func FinishLogin(w http.ResponseWriter, r *http.Request) {
+  // Abstract Business Logic: Get the WebAuthn User. 
+  user := datastore.GetUser()
+
+  // Abstract Business Logic: Get the WebAuthn Session Data. 
+  session := datastore.GetSession()
+
+  parsedResponse, err := protocol.ParseCredentialRequestResponse(r)
+  if err != nil {
+    // Handle Error and return.
+    return
+  }
+
+  // Handle updating the appropriate credential using the flags value.
+  flags := webauthn.NewCredentialFlags(parsedResponse.Response.AuthenticatorData.Flags)
+}
+```
 ### Storage
 
 It is also important to note that restoring the [webauthn.Credential] with the correct values will likely affect the

go.mod

@@ -11,7 +11,7 @@ require (
 	github.com/google/go-tpm v0.9.1
 	github.com/google/uuid v1.6.0
 	github.com/mitchellh/mapstructure v1.5.0
-	github.com/stretchr/testify v1.9.0
+	github.com/stretchr/testify v1.10.0
 )
 
 require (

go.sum

@@ -14,8 +14,8 @@ github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyua
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
 github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 golang.org/x/crypto v0.29.0 h1:L5SG1JTTXupVV3n6sUqMTeWbjAyfPwoda2DLX8J8FrQ=

protocol/base64.go

@@ -22,9 +22,8 @@ func (e *URLEncodedBase64) UnmarshalJSON(data []byte) error {
 		return nil
 	}
 
-	// TODO: Investigate this line. It is commented as trimming the leading spaces but appears to trim the leading and trailing double quotes instead.
-	// Trim the leading spaces.
-	data = bytes.Trim(data, "\"")
+	// Trim the leading and trailing quotes from raw JSON data (the whole value part)
+	data = bytes.Trim(data, `"`)
 
 	// Trim the trailing equal characters.
 	data = bytes.TrimRight(data, "=")

protocol/webauthncose/ed25519.go

@@ -1,5 +1,3 @@
-//go:build go1.13
-
 package webauthncose
 
 import (

webauthn/credential.go

@@ -35,6 +35,19 @@ type Credential struct {
 	Attestation CredentialAttestation `json:"attestation"`
 }
 
+// NewCredentialFlags is a utility function that is used to derive the Credential's Flags field. This allows
+// implementers to solely save the Raw field of the CredentialFlags to restore them appropriately for appropriate
+// processing without concern that changes forced upon implementers by the W3C will introduce breaking changes.
+func NewCredentialFlags(flags protocol.AuthenticatorFlags) CredentialFlags {
+	return CredentialFlags{
+		UserPresent:    flags.HasUserPresent(),
+		UserVerified:   flags.HasUserVerified(),
+		BackupEligible: flags.HasBackupEligible(),
+		BackupState:    flags.HasBackupState(),
+		raw:            flags,
+	}
+}
+
 type CredentialFlags struct {
 	// Flag UP indicates the users presence.
 	UserPresent bool `json:"userPresent"`
@@ -48,6 +61,14 @@ type CredentialFlags struct {
 	// Flag BS indicates the credential has been backed up and/or sync'd. This value can change but it's recommended
 	// that RP's keep track of this value.
 	BackupState bool `json:"backupState"`
+
+	raw protocol.AuthenticatorFlags
+}
+
+// ProtocolValue returns the underlying protocol.AuthenticatorFlags provided this CredentialFlags was created using
+// NewCredentialFlags.
+func (f CredentialFlags) ProtocolValue() protocol.AuthenticatorFlags {
+	return f.raw
 }
 
 type CredentialAttestation struct {
@@ -75,12 +96,7 @@ func NewCredential(clientDataHash []byte, c *protocol.ParsedCredentialCreationDa
 		PublicKey:       c.Response.AttestationObject.AuthData.AttData.CredentialPublicKey,
 		AttestationType: c.Response.AttestationObject.Format,
 		Transport:       c.Response.Transports,
-		Flags: CredentialFlags{
-			UserPresent:    c.Response.AttestationObject.AuthData.Flags.HasUserPresent(),
-			UserVerified:   c.Response.AttestationObject.AuthData.Flags.HasUserVerified(),
-			BackupEligible: c.Response.AttestationObject.AuthData.Flags.HasBackupEligible(),
-			BackupState:    c.Response.AttestationObject.AuthData.Flags.HasBackupState(),
-		},
+		Flags:           NewCredentialFlags(c.Response.AttestationObject.AuthData.Flags),
 		Authenticator: Authenticator{
 			AAGUID:     c.Response.AttestationObject.AuthData.AttData.AAGUID,
 			SignCount:  c.Response.AttestationObject.AuthData.Counter,