Errors

type KnownJWTErrorCode =
  | "ERR_JWT_EXPIRED"
  | "ERR_JWT_NBF"
  | "ERR_JWT_CLAIM_INVALID"
  | "ERR_JWT_CLAIM_MISSING"
  | "ERR_JWS_INVALID"
  | "ERR_JWS_INVALID_SERIALIZATION"
  | "ERR_JWS_SIGNATURE_INVALID"
  | "ERR_JWS_ALG_NOT_ALLOWED"
  | "ERR_JWS_ALG_MISSING"
  | "ERR_JWS_SIGNER_ALG_INFERENCE"
  | "ERR_JWS_NO_MATCHING_SIGNER"
  | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT"
  | "ERR_JWS_B64_INCONSISTENT"
  | "ERR_JWE_INVALID"
  | "ERR_JWE_INVALID_SERIALIZATION"
  | "ERR_JWE_DECRYPTION_FAILED"
  | "ERR_JWE_ALG_NOT_ALLOWED"
  | "ERR_JWE_ALG_MISSING"
  | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI"
  | "ERR_JWE_ENC_MISSING"
  | "ERR_JWE_RECIPIENT_ALG_INFERENCE"
  | "ERR_JWE_NO_MATCHING_RECIPIENT"
  | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT"
  | "ERR_JWK_INVALID"
  | "ERR_JWK_KEY_NOT_FOUND"
  | "ERR_JWK_UNSUPPORTED"
  | "ERR_SESSION_TOKEN_INVALID"
  | "ERR_SESSION_READONLY_EVENT"
  | "ERR_SESSION_KEY_INVALID"
  | "ERR_SESSION_CONFIG_INVALID"
  | "ERR_INVALID_OPTION";

type JWTErrorCode = KnownJWTErrorCode | (string & {});

interface JWTErrorCauseMap {
  ERR_JWT_EXPIRED: { jti?: string; iat?: number; exp?: number };
}

class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
  readonly name: "JWTError";
  readonly code: TCode;
  readonly cause?: unknown;
  constructor(message: string, code: TCode, cause?: unknown);
}

function isJWTError<T extends keyof JWTErrorCauseMap>(
  error: unknown,
  code: T,
): error is JWTError<T> & { cause: JWTErrorCauseMap[T] };
function isJWTError<T extends KnownJWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
function isJWTError(error: unknown): error is JWTError;

import { generateJWK } from "unjwt/jwk";
import { sign, verify, isJWTError } from "unjwt/jws";

const key = await generateJWK("HS256");
const token = await sign({ sub: "u1", jti: "t-1", iat: 1700000000, exp: 1700000600 }, key);

try {
  await verify(token, key);
} catch (error) {
  if (isJWTError(error, "ERR_JWT_EXPIRED")) {
    console.log(error.message);
    // JWT "exp" (Expiration Time) Claim validation failed: Token has expired (exp: 2023-11-14T22:23:20.000Z)
    console.log(error.cause);
    // { jti: "t-1", iat: 1700000000, exp: 1700000600 }
  }
}

import { generateJWK } from "unjwt/jwk";
import { sign, verify, isJWTError, isUnsecureError } from "unjwt/jws";

const key = await generateJWK("HS256");
const [header, payload, signature] = (await sign({ sub: "u1" }, key)).split(".");
const tampered = `${header}=.${payload}.${signature}`;

const error = await verify(tampered, key).catch((e: unknown) => e);
if (isJWTError(error, "ERR_JWS_INVALID")) {
  console.log(error.message); // Invalid JWS: Protected header could not be decoded.
  if (isUnsecureError(error.cause, "MALFORMED")) {
    console.log(error.cause.message); // Base64.parse: unexpected "=" padding.
  }
}

import { H3 } from "h3";
import { useJWSSession, generateJWK } from "unjwt/adapters/h3v2";
import { isJWTError } from "unjwt/jws";

const key = await generateJWK("HS256");

const app = new H3().get("/", async (event) => {
  const session = await useJWSSession(event, {
    key,
    hooks: {
      onError({ error }) {
        if (isJWTError(error, "ERR_SESSION_TOKEN_INVALID") && isJWTError(error.cause)) {
          console.log(error.message); // [unjwt/h3] Invalid session token: Invalid JWS: Must contain three parts separated by dots.
          console.log(error.cause.code); // ERR_JWS_INVALID
        }
      },
    },
  });
  return { id: session.id ?? null };
});

const request = new Request("http://localhost/", { headers: { cookie: "h3-jws=not-a-token" } });
console.log(await (await app.fetch(request)).json()); // { id: null }

import { generateJWK } from "unjwt/jwk";
import { sign, verify, isJWTError } from "unjwt/jws";

const key = await generateJWK("HS256");
const otherKey = await generateJWK("HS256");
const token = await sign({ sub: "u1" }, key);

async function check(token: string, options?: Parameters<typeof verify>[2]) {
  try {
    await verify(token, key, options);
    return "ok";
  } catch (error) {
    if (isJWTError(error, "ERR_JWT_EXPIRED")) return `expired: ${error.cause.exp}`;
    if (isJWTError(error, "ERR_JWS_SIGNATURE_INVALID")) return "bad signature";
    if (isJWTError(error, "ERR_JWS_ALG_NOT_ALLOWED")) return `refused: ${error.message}`;
    if (isJWTError(error)) return `${error.code}: ${error.message}`;
    throw error;
  }
}

console.log(await check(token)); // ok
console.log(await check(await sign({ sub: "u1" }, otherKey))); // bad signature
console.log(await check(token, { algorithms: ["HS512"] })); // refused: Algorithm not allowed: HS256
console.log(await check("abc.def")); // ERR_JWS_INVALID: Invalid JWS: Must contain three parts separated by dots.
console.log(await check(await sign({ exp: 1700000600 }, key))); // expired: 1700000600

if (isJWTError(error, "ERR_JWS_INVALD")) {
}
// error TS2769: No overload matches this call.
//   Argument of type '"ERR_JWS_INVALD"' is not assignable to parameter of type 'KnownJWTErrorCode'.