feat(protocol): compound sub-statement scope (#742)

Adds the compound attestation policy which selects the sub-statements §8.9 requires to be verified for the attestation to be accepted, either all of them or any one of them, with the zero value evaluating as all so an unset policy remains the strictest behavior available. A sub-statement counts as verified only when its format's verification procedure succeeds and the trust path it produces is accepted by the Metadata Service, so the any scope tolerates a failure of either provided another sub-statement satisfies both, and conveys the attestation type of the sub-statement which was verified rather than that of one which failed. When no sub-statement can be verified the failures are conveyed together, each named alongside its format, and joined so the underlying errors remain reachable.

The scope applies only to the outcome of the verification procedures. A statement which does not satisfy the §8.9 CDDL, nests a compound sub-statement, or names an unsupported format is rejected under every scope.

Author: james-d-elliott

protocol/attestation_compound.go

@@ -2,7 +2,9 @@ package protocol
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"strings"
 
 	"github.com/google/uuid"
 
@@ -26,14 +28,12 @@ func init() {
 // nonCompoundAttStmt = { $$attStmtType } .within { fmt: text .ne "compound", * any => any }
 //
 // §8.9 leaves the handling of a sub-statement which fails verification, and the number which must succeed, to Relying
-// Party policy. The policy applied here is the strictest available: every sub-statement must verify, and the first
-// failure rejects the attestation.
+// Party policy. The scope carries that decision and the zero value selects the strictest behavior available: every
+// sub-statement must verify, and the first failure rejects the attestation. See [CompoundSubStatementScope].
 //
 // Specification: §8.9. Compound Attestation Statement Forma
 //
 // See: https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation
-//
-//nolint:gocyclo
 func attestationFormatValidationHandlerCompound(att AttestationObject, clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy) (attestationType string, x5cs []any, err error) {
 	var (
 		aaguid   uuid.UUID
@@ -91,20 +91,25 @@ func attestationFormatValidationHandlerCompound(att AttestationObject, clientDat
 		}
 	}
 
-	for i, attStmt := range attStmts {
-		object := AttestationObject{
-			Format:       attStmt.Format,
-			AttStatement: attStmt.AttStatement,
-			AuthData:     att.AuthData,
-			RawAuthData:  att.RawAuthData,
-		}
+	// The trust paths are not conveyed to the caller. Each is validated against the Metadata Service by the
+	// verification below alongside the format and attestation type it belongs to, which a single chain can't describe
+	// for more than one sub-statement, and the paths of independent sub-statements joined together describe no real
+	// chain.
+	if policy.Compound.SubStatementScope.any() {
+		return compoundVerifySubStatementsAny(att, attStmts, clientDataHash, mds, policy, aaguid)
+	}
+
+	return compoundVerifySubStatementsAll(att, attStmts, clientDataHash, mds, policy, aaguid)
+}
 
-		var (
-			cx5cs      []any
-			subAttType string
-		)
+// compoundVerifySubStatementsAll verifies every sub-statement, rejecting the attestation on the first which fails.
+//
+// This is the behavior of [CompoundSubStatementScopeAll].
+func compoundVerifySubStatementsAll(att AttestationObject, attStmts []NonCompoundAttestationObject, clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy, aaguid uuid.UUID) (attestationType string, x5cs []any, err error) {
+	for i, attStmt := range attStmts {
+		var subAttType string
 
-		if subAttType, cx5cs, err = attestationRegistry[AttestationFormat(object.Format)](object, clientDataHash, mds, policy); err != nil {
+		if subAttType, err = compoundVerifySubStatement(att, attStmt, clientDataHash, mds, policy, aaguid); err != nil {
 			return "", nil, err
 		}
 
@@ -113,18 +118,88 @@ func attestationFormatValidationHandlerCompound(att AttestationObject, clientDat
 		if i == 0 {
 			attestationType = subAttType
 		}
+	}
+
+	return attestationType, nil, nil
+}
+
+// compoundVerifySubStatementsAny verifies sub-statements until one of them succeeds, rejecting the attestation only
+// when none can be verified. The sub-statements after the first success are not verified as the scope is satisfied
+// by it, and the failures of the sub-statements before it are conveyed together so the reason the accepted one was
+// reached is not lost.
+//
+// This is the behavior of [CompoundSubStatementScopeAny].
+func compoundVerifySubStatementsAny(att AttestationObject, attStmts []NonCompoundAttestationObject, clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy, aaguid uuid.UUID) (attestationType string, x5cs []any, err error) {
+	var (
+		errs    = make([]error, 0, len(attStmts))
+		reasons = make([]string, 0, len(attStmts))
+	)
+
+	for _, attStmt := range attStmts {
+		var subAttType string
+
+		if subAttType, err = compoundVerifySubStatement(att, attStmt, clientDataHash, mds, policy, aaguid); err != nil {
+			errs = append(errs, err)
+			reasons = append(reasons, fmt.Sprintf("%s: %s", attStmt.Format, compoundSubStatementFailureReason(err)))
 
-		if mds == nil {
 			continue
 		}
 
-		if e := ValidateMetadata(context.Background(), mds, aaguid, subAttType, object.Format, cx5cs); e != nil {
-			return "", nil, ErrInvalidAttestation.WithInfo(fmt.Sprintf("Error occurred validating metadata during attestation validation: %+v", e)).WithDetails(e.DevInfo).WithError(e)
-		}
+		// The sub-statement which was verified is the one which describes an attestation which was obtained, so its
+		// type is the value recorded against the credential rather than that of a sub-statement which failed.
+		return subAttType, nil, nil
 	}
 
-	// The trust paths are not conveyed to the caller. Each is validated against the Metadata Service above alongside
-	// the format and attestation type it belongs to, which a single chain can't describe for more than one
-	// sub-statement, and the paths of independent sub-statements joined together describe no real chain.
-	return attestationType, nil, nil
+	return "", nil, ErrInvalidAttestation.
+		WithDetails(fmt.Sprintf("Compound statement does not contain any sub-statement which could be verified (%s)", strings.Join(reasons, "; "))).
+		WithError(errors.Join(errs...))
+}
+
+// compoundSubStatementFailureReason describes the failure of a sub-statement for the aggregate error of the any
+// scope. The details of an [Error] are preferred as they name the specific failure, falling back to the debug
+// information and then the type so that a failed sub-statement is never described by an empty string.
+func compoundSubStatementFailureReason(err error) string {
+	var e *Error
+
+	if !errors.As(err, &e) {
+		return err.Error()
+	}
+
+	switch {
+	case e.Details != "":
+		return e.Details
+	case e.DevInfo != "":
+		return e.DevInfo
+	default:
+		return e.Type
+	}
+}
+
+// compoundVerifySubStatement performs the verification procedure of a single sub-statement and validates the trust
+// path it produces against the Metadata Service. A sub-statement is verified in full or not at all, so a scope which
+// tolerates a failure treats a sub-statement whose trust path the Metadata Service rejects the same as one whose
+// verification procedure fails.
+func compoundVerifySubStatement(att AttestationObject, attStmt NonCompoundAttestationObject, clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy, aaguid uuid.UUID) (attestationType string, err error) {
+	object := AttestationObject{
+		Format:       attStmt.Format,
+		AttStatement: attStmt.AttStatement,
+		AuthData:     att.AuthData,
+		RawAuthData:  att.RawAuthData,
+	}
+
+	var cx5cs []any
+
+	if attestationType, cx5cs, err = attestationRegistry[AttestationFormat(object.Format)](object, clientDataHash, mds, policy); err != nil {
+		return "", err
+	}
+
+	if mds == nil {
+		return attestationType, nil
+	}
+
+	if e := ValidateMetadata(context.Background(), mds, aaguid, attestationType, object.Format, cx5cs); e != nil {
+		return "", ErrInvalidAttestation.WithInfo(fmt.Sprintf("Error occurred validating metadata during attestation validation: %+v", e)).WithDetails(e.DevInfo).WithError(e)
+	}
+
+	return attestationType, nil
 }