DOMException to reason for failure commentary

Hey just found this library while looking through suggested repos and was reading this comment: https://github.com/MasterKale/SimpleWebAuthn/issues/160#issuecomment-950263415

I wanted to discuss it but didn’t want to derail that thread so figure this would be the ideal.

Unless I misunderstood the discussion or the specification, identifying the cause of why a failure occurred is technically possible as I read the spec. Providing (and of course this may not happen) browsers throw the correct DOMException depending on the exception and the task being performed, here is my notes as commented code as to what each exception means:

function getAttestationResultFromDOMException(exception: DOMException): AttestationResult {
    // Docs for this section:
    // https://w3c.github.io/webauthn/#sctn-op-make-cred
    switch (exception.name) {
        case "UnknownError":
            // § 6.3.2 Step 1 and Step 8.
            return AttestationResult.FailureSyntax;
        case "NotSupportedError":
            // § 6.3.2 Step 2.
            return AttestationResult.FailureSupport;
        case "InvalidStateError":
            // § 6.3.2 Step 3.
            return AttestationResult.FailureExcluded;
        case "NotAllowedError":
            // § 6.3.2 Step 3 and Step 6.
            return AttestationResult.FailureUserConsent;
        case "ConstraintError":
            // § 6.3.2 Step 4.
            return AttestationResult.FailureUserVerificationOrResidentKey;
        default:
            console.error(`Unhandled DOMException occurred during WebAuthN attestation: ${exception}`);
            return AttestationResult.FailureUnknown;
    }
}

function getAssertionResultFromDOMException(
    exception: DOMException,
    requestOptions: PublicKeyCredentialRequestOptions,
): AssertionResult {
    // Docs for this section:
    // https://w3c.github.io/webauthn/#sctn-op-get-assertion
    switch (exception.name) {
        case "UnknownError":
            // § 6.3.3 Step 1 and Step 12.
            return AssertionResult.FailureSyntax;
        case "NotAllowedError":
            // § 6.3.3 Step 6 and Step 7.
            return AssertionResult.FailureUserConsent;
        case "SecurityError":
            // § 10.1 and 10.2 Step 3.
            if (requestOptions.extensions?.appid !== undefined) {
                return AssertionResult.FailureU2FFacetID;
            } else {
                return AssertionResult.FailureUnknownSecurity;
            }
        default:
            console.error(`Unhandled DOMException occurred during WebAuthN assertion: ${exception}`);
            return AssertionResult.FailureUnknown;
    }
}

[MasterKale]

One of the first things I did after joining Duo was to discover all of the possible errors that could come out of .create() and .get() and what would throw them, and from that effort came a real ugly picture of how much understanding we could glean from any of the eight discrete errors defined in the spec. I don’t have anything I can publicly share from that work yet (I plan on publishing this work to the Duo blog but no ETA), suffice to say InvalidStateError ended up being relatively straight forward to understand the user tried to re-register an authenticator matching one of the credentials in excludeCredentials during .create(). That was sufficient for our use case and so I never had to try and make sense of the other error states.

Thank you for taking the time to write out that code. Looking over it I see that it’s not all that unreasonable to try and derive what actually went wrong. Comparing your examples to the notes I left myself from my earlier research, I can actually see a path forward for making it possible to offer more insight into most of the reasons an error was thrown.

Let me think on this and see how many other errors could also be intuited. It feels like a great way to make consuming WebAuthn simpler, and I’m all for that.

[MasterKale]

This functionality is now available in the newly-published @simplewebauthn/browser@5.0.0 🚀