@httpx/jwt-verify

Install

$ npm install @httpx/jwt-verify
$ yarn add @httpx/jwt-verify
$ pnpm add @httpx/jwt-verify

Optionally: add @standard-schema/spec and the validation of your choice (zod, valibot...)

Features

• ✨  Customize payload validation with any standard-schema compatible library (ie: zod, valibot...).
• 🛡️  Rely on battle tested jose for jwt validation and decoding.
• ✨️  OIDC Discovery Fetcher to safely fetch and validate OIDC configurations (retries...).
• 🧪  Tested on node 20-25, bun, browser, cloudflare workers and runtime/edge.

Documentation

OIDC Verifier

import { JwtVerifier } from "@httpx/jwt-verify";
import * as v from "valibot";

const entraVerifier = new JwtVerifier({
  authorityHost: "https://login.microsoftonline.com",
  tenantId: "xxxxxx-xxx-xxxx-xxx-xxxxxxxx",
  clockToleranceSec: 60, // optional
});

const entraJwtToken = "..."; // The JWT token to verify

// Verify, validate and return the parsed token
const { value, error } = await entraVerifier.safeParse(entraJwtToken, {
  /**
   * Optional standard schema to validate the payload
   * If provided, only the properties defined in the schema will be
   * exposed in the `value.payload` object.
   */
  schema: v.object({
    // Add properties to validate, note that if you provide a schema, only
    // the properties defined in the schema will be available in the value.payload.
    oid: v.string(),
  }),
});

if (error) {
  // See error documentation for details about possible errors:
  // > NotATokenError, ExpiredTokenError, FetchError, SchemaValidationError, JwtVerifyError
  // > InvalidOidcConfigError
}

console.log("payload", value.payload);

OIDC Fetcher

OIDC Discovery Fetcher can be used to safely fetch and validate OIDC configurations.

import { OidcDiscoveryFetcher } from "@httpx/jwt-verify";

const fetchOptions = {
  // See options below
};

const fetcher = new OidcDiscoveryFetcher(
  // Optional default fetch options for all calls
  fetchOptions
);

// Any oidc discovery url
const oidcDiscoveryUrl =
  "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration";

const { data, error } = await fetcher.safeFetch(
  oidcDiscoveryUrl,
  // optional to override fetch options for this call
  fetchOptions
);

if (data) {
  console.log("Discovery Payload:", data);
}

if (error) {
  // FetchError | InvalidOidcConfigError
  console.error("Error fetching OIDC configuration:", error);
}

FetcherOptions

By default, the fetcher uses the following options:

const fetchOptions = {
  // These are the default options, you can customize them as needed
  // in the constructor or in safeFetch
  timeoutMs: 30_000,
  retry: {
    limit: 3,
    methods: ["get", "head", "options", "trace"],
    statusCodes: [408, 413, 429, 500, 502, 503, 504],
    afterStatusCodes: [413, 429, 503],
    maxRetryAfter: Number.POSITIVE_INFINITY,
    retryOnTimeout: true,
    delay: (attemptCount) => 0.3 * 2 ** (attemptCount - 1) * 1000,
  },
};

Benchmarks

Performance is continuously monitored thanks to codspeed.io.

See benchmark file for details.

Bundle size

Bundle size is tracked by a size-limit configuration

| Scenario (esm) | Size (compressed) | | --------------------------------------------------------- | ----------------: | | import { JwtVerifier } from '@httpx/jwt-verify | ~ 12.30KB | | import { OidcDiscoveryFetcher } from '@httpx/jwt-verify | ~ 5.20KB |

The total size accounts for the dependency on jose.

Compatibility

| Level | CI | Description | | ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Node | ✅ | CI for 20.x, 22.x, 24.x & 25.x. | | Browser | ✅ | Tested with latest chrome (vitest/playwright) | | Browserslist | ✅ | defaults, > 0.26%, last 2 versions, Firefox ESR, not dead | | Bun | ✅ | Tested with latest (at time of writing >= 1.3.3) | | Edge | ✅ | Ensured on CI with @vercel/edge-runtime. | | Cloudflare | ✅ | Ensured with @cloudflare/vitest-pool-workers (see wrangler.toml | | Typescript | ✅ | TS 5.0 + / are-the-type-wrong checks on CI. | | ES2022 | ✅ | Dist files checked with es-check | | Performance | ✅ | Monitored with codspeed.io |

For older browsers: most frontend frameworks can transpile the library (ie: nextjs...)

Comparison with other libraries

Contributors

Contributions are welcome. Have a look to the CONTRIBUTING document.

Sponsors

If my OSS work brightens your day, let's take it to new heights together! Sponsor, coffee, or star – any gesture of support fuels my passion to improve. Thanks for being awesome! 🙏❤️

Special thanks to

License

MIT © Sébastien Vanvelthem and contributors.