JwsError / ErrorCode

Every recoverable failure raised by @exortek/jws is a JwsError with a stable code from the ErrorCode enum and a status — the HTTP response status a middleware layer would use when translating the error.

Branch on code, never on the message. Messages are human-readable, free-form, and may drift across versions.

import { verify, JwsError, ErrorCode } from '@exortek/jws'
 
try {
  await verify(token, key, { alg: ['ES256'] })
} catch (err) {
  if (!(err instanceof JwsError)) throw err
 
  switch (err.code) {
    case ErrorCode.MISSING_ALG_ALLOWLIST:
      // Config bug — allowlist required.
      break
    case ErrorCode.ALGORITHM_MISMATCH:
      // Token alg outside caller's allowlist.
      break
    case ErrorCode.ALGORITHM_NONE_FORBIDDEN:
      // Refused unconditionally.
      break
    case ErrorCode.INVALID_SIGNATURE:
      // Tampered token.
      break
    // …
  }
}

ErrorCode catalogue

Verify-side failures default to HTTP 401 — the token itself is untrustworthy. Configuration failures (missing allowlist, unsupported alg) default to 400. Override with the constructor:

throw new JwsError(ErrorCode.INVALID_KEY, 'signing key retired', { status: 410 })

The JwsError shape

class JwsError extends Error {
  name: 'JwsError'
  code: ErrorCode
  status: number   // HTTP status hint
  cause?: unknown  // upstream error (e.g. the node:crypto rejection)
}

cause is populated when the failure originates in node:crypto — you get both the actionable JWS-level message and the original OpenSSL / Node error for debugging.

CVE-class coverage

The security-labelled tests in this package pin the following:

• CVE-2015-9235 — algorithm confusion (RSA public key used as HMAC secret) surfaces as INVALID_KEY at the key boundary. Both Buffer and JWK RSA input shapes are guarded.
• CVE-2015-2951 — alg: 'none' acceptance is refused with ALGORITHM_NONE_FORBIDDEN. Mixed-case (None, NONE) lands in UNSUPPORTED_ALGORITHM / ALGORITHM_MISMATCH.
• Silent-allowlist regressions — every verify call without a proper options.alg array raises MISSING_ALG_ALLOWLIST before any parsing.