fix(metadata): honour status report order and effective dates (#736)

Status reports are a history rather than a set. Desired statuses are now matched against the current status only, so an authenticator which is presently revoked no longer satisfies a certification level it held previously. Undesired statuses remain matched against every report in effect as a compromise is not retracted by a later report.

The effectiveDate and sunsetDate values are now honoured, excluding reports which have not come into effect and those which have expired.

BREAKING CHANGE: the desired statuses given to ValidateStatusReports are now a
set of acceptable current statuses rather than a set which must all appear
somewhere in the report history.

Author: james-d-elliott

metadata/providers/memory/provider_test.go

@@ -207,7 +207,19 @@ func TestProvider_ValidateStatusReports(t *testing.T) {
 				WithStatusUndesired(nil),
 			},
 			reports: []metadata.StatusReport{{Status: metadata.NotFidoCertified}},
-			err:     "The following desired status reports were absent: FIDO_CERTIFIED",
+			err:     "the current status report 'NOT_FIDO_CERTIFIED' was not one of the desired statuses: FIDO_CERTIFIED",
+		},
+		{
+			// The desired status must be the current one rather than merely present in the history.
+			name: "ShouldFailWithDesiredStatusSuperseded",
+			opts: []Option{
+				WithMetadata(map[uuid.UUID]*metadata.Entry{}),
+				WithValidateStatus(true),
+				WithStatusDesired([]metadata.AuthenticatorStatus{metadata.FidoCertifiedL2}),
+				WithStatusUndesired(nil),
+			},
+			reports: []metadata.StatusReport{{Status: metadata.FidoCertifiedL2}, {Status: metadata.Revoked}},
+			err:     "the current status report 'REVOKED' was not one of the desired statuses: FIDO_CERTIFIED_L2",
 		},
 	}
 

metadata/status.go

@@ -3,62 +3,175 @@ package metadata
 import (
 	"fmt"
 	"strings"
+	"time"
 )
 
-// ValidateStatusReports checks a list of [StatusReport] structs against a list of desired and undesired [AuthenticatorStatus]
-// values. If the reports contain all of the desired and none of the undesired status reports then no error is returned
-// otherwise an error describing the issue is returned.
+// InEffectAt returns true if this [StatusReport] is in effect at the given time.
 //
-//nolint:gocyclo
+// A report which has an effective date in the future has not come into effect yet, and a report which has reached its
+// sunset date has expired. An absent effective date means the report is in effect while present, and an absent sunset
+// date means it has no scheduled expiry.
+//
+// See: https://fidoalliance.org/specs/mds/fido-metadata-service-v3.1.1-rd-20251016.html#sctn-stat-rep
+func (r StatusReport) InEffectAt(at time.Time) bool {
+	if r.EffectiveDate != nil && r.EffectiveDate.After(at) {
+		return false
+	}
+
+	if r.SunsetDate != nil && !r.SunsetDate.After(at) {
+		return false
+	}
+
+	return true
+}
+
+// EffectiveStatusReports returns the subset of the given [StatusReport] values which are in effect at the given time,
+// preserving their original order. See [StatusReport.InEffectAt] for the rules applied.
+func EffectiveStatusReports(reports []StatusReport, at time.Time) (effective []StatusReport) {
+	for _, report := range reports {
+		if report.InEffectAt(at) {
+			effective = append(effective, report)
+		}
+	}
+
+	return effective
+}
+
+// CurrentStatusReportAt returns the [StatusReport] which reflects the current status of the authenticator at the given
+// time, or nil if no report is in effect. See [currentStatusReport] for how the current report is selected.
+func CurrentStatusReportAt(reports []StatusReport, at time.Time) (current *StatusReport) {
+	return currentStatusReport(EffectiveStatusReports(reports, at))
+}
+
+// currentStatusReport returns the report reflecting the current status from a set of reports already known to be in
+// effect, or nil if there are none.
+//
+// MDS3 requires that the latest entry reflects the current status, so the last element wins by default. Where both
+// candidates carry an effective date that date is preferred over the document order, which keeps the selection correct
+// for a blob whose reports are not listed oldest first. Ties resolve to the later element.
+func currentStatusReport(effective []StatusReport) (current *StatusReport) {
+	for i := range effective {
+		report := &effective[i]
+
+		if current == nil || current.EffectiveDate == nil || report.EffectiveDate == nil {
+			current = report
+
+			continue
+		}
+
+		if !report.EffectiveDate.Before(*current.EffectiveDate) {
+			current = report
+		}
+	}
+
+	return current
+}
+
+// ValidateStatusReports checks a list of [StatusReport] structs against a list of desired and undesired
+// [AuthenticatorStatus] values as at the current time. See [ValidateStatusReportsAt] for the validation performed.
 func ValidateStatusReports(reports []StatusReport, desired, undesired []AuthenticatorStatus) (err error) {
-	if len(desired) == 0 && (len(undesired) == 0 || len(reports) == 0) {
+	return ValidateStatusReportsAt(reports, desired, undesired, time.Now())
+}
+
+// ValidateStatusReportsAt checks a list of [StatusReport] structs against a list of desired and undesired
+// [AuthenticatorStatus] values as at the given time. If the reports satisfy the desired statuses and contain none of
+// the undesired statuses then no error is returned, otherwise an error describing the issue is returned.
+//
+// Reports which are not in effect at the given time are excluded from consideration entirely, i.e. those with an
+// effective date in the future and those which have reached their sunset date.
+//
+// The desired statuses are matched against the current status only, and are treated as a set of acceptable statuses of
+// which one must match. MDS3 requires that the latest report reflects the current status, so an authenticator formerly
+// certified at some level but since revoked does not satisfy a desired status naming that certification level.
+//
+// The undesired statuses are matched against every report in effect rather than the current one alone. Statuses such as
+// [AttestationKeyCompromise] and [UserKeyPhysicalCompromise] describe a weakness discovered in the authenticator model
+// which a later report does not retract; the sunset date honored above is the mechanism by which such a report stops
+// applying.
+//
+// Note that a compromise reported against a specific attestation certificate, i.e. where [StatusReport.Certificate] or
+// [StatusReport.BatchCertificate] is set, applies only to that batch of authenticators. This function has no visibility
+// of the attestation statement being validated, so it conservatively treats such a report as applying to every
+// authenticator of the model.
+func ValidateStatusReportsAt(reports []StatusReport, desired, undesired []AuthenticatorStatus, at time.Time) (err error) {
+	if len(desired) == 0 && len(undesired) == 0 {
 		return nil
 	}
 
-	var present, absent []string
+	effective := EffectiveStatusReports(reports, at)
+
+	var present []string
 
 	if len(undesired) != 0 {
-		for _, report := range reports {
-			for _, status := range undesired {
-				if report.Status == status {
-					present = append(present, string(status))
+		seen := make(map[AuthenticatorStatus]struct{}, len(undesired))
 
-					continue
-				}
+		for _, report := range effective {
+			if _, ok := seen[report.Status]; ok {
+				continue
+			}
+
+			if hasStatus(report.Status, undesired) {
+				seen[report.Status] = struct{}{}
+
+				present = append(present, string(report.Status))
 			}
 		}
 	}
 
+	var (
+		current     *StatusReport
+		unsatisfied bool
+	)
+
 	if len(desired) != 0 {
-	desired:
-		for _, status := range desired {
-			for _, report := range reports {
-				if report.Status == status {
-					continue desired
-				}
-			}
+		current = currentStatusReport(effective)
 
-			absent = append(absent, string(status))
-		}
+		unsatisfied = current == nil || !hasStatus(current.Status, desired)
 	}
 
 	switch {
-	case len(present) == 0 && len(absent) == 0:
+	case len(present) == 0 && !unsatisfied:
 		return nil
-	case len(present) != 0 && len(absent) == 0:
+	case len(present) != 0 && !unsatisfied:
 		return &Error{
 			Type:    "invalid_status",
 			Details: fmt.Sprintf("The following undesired status reports were present: %s", strings.Join(present, ", ")),
 		}
-	case len(present) == 0 && len(absent) != 0:
+	case len(present) == 0:
 		return &Error{
 			Type:    "invalid_status",
-			Details: fmt.Sprintf("The following desired status reports were absent: %s", strings.Join(absent, ", ")),
+			Details: describeDesiredUnsatisfied(current, desired),
 		}
 	default:
 		return &Error{
 			Type:    "invalid_status",
-			Details: fmt.Sprintf("The following undesired status reports were present: %s; the following desired status reports were absent: %s", strings.Join(present, ", "), strings.Join(absent, ", ")),
+			Details: fmt.Sprintf("The following undesired status reports were present: %s; %s", strings.Join(present, ", "), describeDesiredUnsatisfied(current, desired)),
 		}
 	}
 }
+
+// hasStatus returns true if the given status is a member of the given values.
+func hasStatus(status AuthenticatorStatus, values []AuthenticatorStatus) bool {
+	for _, value := range values {
+		if value == status {
+			return true
+		}
+	}
+
+	return false
+}
+
+// describeDesiredUnsatisfied renders the reason the desired statuses were not satisfied by the current status report.
+func describeDesiredUnsatisfied(current *StatusReport, desired []AuthenticatorStatus) string {
+	statuses := make([]string, len(desired))
+
+	for i, status := range desired {
+		statuses[i] = string(status)
+	}
+
+	if current == nil {
+		return fmt.Sprintf("no status report was in effect so none of the desired statuses could be satisfied: %s", strings.Join(statuses, ", "))
+	}
+
+	return fmt.Sprintf("the current status report '%s' was not one of the desired statuses: %s", current.Status, strings.Join(statuses, ", "))
+}