Server error codes

Proposal

It would be great if server lib had codes for errors.
There are such error codes for frontend - #367 .

Consider example -

you want to run some logic if counter is lower than expected,
and you want to run another logic if origin mismathes
else rethrow

I want to it to look like this in my code:

			try {
				const verification = await verifyAuthenticationResponse({
				...
				});
			} catch (error: WebAuthnError) {
			        if (error.code === 'COUNTER_TOO_LOW') {
			            // logout user
			            // delete passkey
			        } else if (error.code === 'ORIGIN_MISMATCH'){
			            throw new Error('I'm a teapot');
                                } else {
                                    throw error;
                                }
			}

Just say what do you think about it generally and we can start discussing implementation details.
I want to contribute.

P.S.: thank you for such great library

@Mykhailo-Sichkaruk

Hello @Mykhailo-Sichkaruk, thanks for the suggestion! This is a great idea, I see how it'd be nice to bring some order to the many more errors that @simplewebauthn/server might raise. I'll begin thinking about this and try to implement a custom error like @simplewebauthn/browser's WebAuthnError from #367 like you called out... 🤔

Thanks for considering this feature 😊
I'm also thinking how we can improve error handling

I have a related idea: grouping errors to handle not just one error but set of related errors.

For example, a PublicKeyError category could group all public key-related issues, such as:

PublicKeyMissingAlgError
PublicKeyInvalidAlgError
other

This could be implemented with inheritance:

class PublicKeyError extends WebAuthnError {}
class PublicKeyInvalidAlgError extends PublicKeyError {}

Or, alternatively, using a list of error codes:

const PublicKeyErrors = ['public_key_invalid_alg', 'public_key_missing_alg', ...];

This can help not only in handling errors, but also in understanding for users of the lib how errors relate to each other and how they should be handled.

Ran into this today, had to write some regex to match the message string passed into an error deep in this library.

Luckily it's open source, and I wrote some unit tests to check for regressions if I ever update and the message changes.

I noticed pull requests are locked. Would you be interested in taking a patch if I have some time to work on it?

@junderw

Thanks for keeping this issue alive @junderw. I still think this is worth doing. I'm trying to get v14.0.0 out the door, but it's got enough features in it that I'm going to wait till after that goes out to begin working on this as a "v14.1.0" release.

I noticed pull requests are locked. Would you be interested in taking a patch if I have some time to work on it?

I appreciate the offer but will respectfully decline. I'm all ears for any proposals you might have for how to pull this off though. My game plan remains to add something like @simplewebauthn/browser's WebAuthnError into @simplewebauthn/server, with a code property that gets set to some enum string like ERROR_CEREMONY_ABORTED, etc... Then I'd update everything to consistently throw WebAuthnError.

Browser's WebAuthnError is perfect. Can't wait to get rid of all those regression tests against error messages (AI helped a lot though).

No rush. Just don't change the error messages until then! 😆

Perhaps this starts the progress on #646

I always think of this issue when I throw new Error(...) in @simplwebauthn/server. So while working on #800 I thought it might be possible to establish a pattern that'll finally address this issue (not with #800, but definitely in the short term):

https://github.com/MasterKale/SimpleWebAuthn/blob/10b4f53802290c867edcdc67072be069fa2ed8a3/packages/server/src/errors/index.ts

export class SimpleWebAuthnError extends Error {
  code: SimpleWebAuthnErrorCode;

  constructor({ message, code, cause }: {
    message: string;
    code: SimpleWebAuthnErrorCode;
    cause?: Error;
  }) {
    super(message, { cause });
    this.name = 'SimpleWebAuthnError';
    this.code = code;
  }
}

export class PQCNotSupportedError extends SimpleWebAuthnError {
  constructor(alg: COSEALG) {
    const webCryptoAlg = mapCoseAlgToWebCryptoKeyAlgName(alg);
    const message = `This runtime's WebCrypto.subtle does not support use of ${webCryptoAlg}`;
    super({ message, code: 'RUNTIME_NO_PQC_SUPPORT' });
  }
}

export type SimpleWebAuthnErrorCode = 'RUNTIME_NO_PQC_SUPPORT';

Then even if I get fancy with subclasses of SimpleWebAuthnError users of the library could still use a simple error instanceof SimpleWebAuthnError to know it's something out of this library 🤔

And in @simplewebauthn/browser I could add a simple subclass of Error so that even the existing WebAuthnError in that library could be detected with error instanceof SimpleWebAuthnError without breaking existing code that handles WebAuthnError:

export class SimpleWebAuthnError extends Error {}

export class WebAuthnError extends SimpleWebAuthnError {
  // ...
}

Thanks for the ongoing discussion on structured server errors. We have a related use case involving signature-counter anomalies and multi-device passkeys.

In @simplewebauthn/server@14.0.3, the non-increasing counter check occurs before signature verification. This means a relying party cannot safely distinguish a validly signed assertion with a counter anomaly from an invalid signature by catching the counter exception.

We ran an isolated synthetic experiment that changed the internal verifier to calculate the existing counter-anomaly predicate separately, then continued through the original verification flow. Valid signatures with anomalous counters could reach a separate risk assessment, while invalid signatures remained invalid. This was an experimental patch, not a supported API or a production-ready fork.

Would the maintainers consider a supported API that exposes a structured counter assessment only alongside the normal verification result, while preserving all signature, challenge, origin, RP ID, and authenticator-flag checks?

We would expect the current strict behavior to remain the default. Any alternative policy should be explicitly documented as a relying-party risk decision, not as replay protection. Durable, one-time challenge consumption and authorization would remain application responsibilities.

We believe this could complement the structured error work in this issue without requiring relying parties to patch internal verifier code or depend on error-message strings.

Thank you for considering it.

Navigation Menu

Server error codes #646

Proposal

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Server error codes #646

Description

Proposal

Activity

MasterKale commented on Dec 6, 2024

Mykhailo-Sichkaruk commented on Dec 9, 2024

junderw commented on Aug 25, 2026

MasterKale commented on Aug 29, 2026

junderw commented on Sep 3, 2026

MasterKale commented on Sep 4, 2026

MasterKale commented on Sep 4, 2026

sin047 commented on Oct 22, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions