Sign-counter regression detector

Purpose

Implements the W3C WebAuthn L3 §6.1.1 sign-counter regression check. Authenticators that maintain a monotonically-increasing counter MUST surface a larger value on every successful assertion; a counter that fails to increase indicates either a cloned authenticator or an authenticator software bug. The check is deliberately a pure function so the policy decision (accept-and-warn vs revoke-and-reject) lives in the caller's identity layer.

Features

Three-state semantics: stored=0 & asserted=0 (skip), asserted<=stored & at least one non-zero (regression), asserted>stored (ok).
Pure synchronous function — no IO, no observability emission, no exceptions.
Boundary-correct comparison: <= so the equal-counter case is also a regression, matching the W3C-defined behaviour for authenticators that never rotate their counter.

Usage: Basic Example

import { detectSignCounterRegression } from "@suaveplan/webauthn/verifier";

if (detectSignCounterRegression(stored.signCounter, result.signCount)) {
    revokeCredential(stored.id);
    throw new Error("sign-counter regression");
}

Usage: Advanced Example

import { detectSignCounterRegression } from "@suaveplan/webauthn/verifier";

function classifyAuthenticatorCounter(
    stored: number,
    asserted: number
): "static-counter-ok" | "regression" | "advanced" {
    if (stored === 0 && asserted === 0) {
        return "static-counter-ok";
    }
    return detectSignCounterRegression(stored, asserted)
        ? "regression"
        : "advanced";
}

API Reference

detectSignCounterRegression(stored: number, asserted: number): boolean — true if the assertion's counter regressed, false otherwise.

Implementation Notes

W3C deliberately keeps the policy ambiguous: an RP MAY treat regression as a soft warning (for testing-tier authenticators) or as a hard revoke (for production). The package surfaces the boolean and leaves the policy to the caller; verifyAssertion consumes this and returns { ok: false, code: SIGN_COUNTER_REGRESSION } so the caller can branch.
The zero-zero exception matters: several major authenticators (Touch ID, Windows Hello on platform-bound credentials) deliberately emit signCount === 0 on every assertion to avoid leaking usage frequency to the RP. Without the zero-zero exception every such login would falsely flag as a regression.
The function is intentionally branchless except for the two arithmetic comparisons so its execution time is invariant of the inputs — there is no plausible side-channel here, but the discipline is part of the package's no-naive-equality posture.

2.6 KiB Raw Blame History