@lookworld4/edge-jwt-lite

Decode and verify JWTs using Web Crypto only (globalThis.crypto.subtle). There are no imports from Node’s crypto, buffer, or other Node-only primitives, so the same code runs in Cloudflare Workers, Vercel Edge Functions, browsers, Deno with Web Crypto, and other constrained runtimes.

Why use this?

Many JWT libraries rely on Node’s cryptographic APIs. Edge platforms often disallow those entirely. This library keeps the surface small — compact JWS verification for HS256, RS256, and ES256 — and stays inside the cryptographic APIs your Edge runtime already provides.

Installation

npm install @lookworld4/edge-jwt-lite

Requires a runtime where globalThis.crypto.subtle and atob are available (standard on Workers and modern browsers).

Quick start

Verify (recommended for authorization decisions):

import { verifyJwt } from '@lookworld4/edge-jwt-lite';

// HS256 shared secret (UTF-8 string or Uint8Array)
const { header, payload } = await verifyJwt(token, {
  algorithm: 'HS256',
  secret: process.env.JWT_SECRET!, // Workers: env binding
});

// RS256 PEM public key (SPKI, -----BEGIN PUBLIC KEY-----)
await verifyJwt(token, {
  algorithm: 'RS256',
  publicKeyPem: PEM,
});

// Optional standard claim checks (after signature verifies)
await verifyJwt(
  token,
  { algorithm: 'HS256', secret },
  {
    issuer: 'https://idp.example.com',
    audience: 'my-api',
    clockToleranceSeconds: 60,
  }
);

Decode only (inspection — never trust the payload without verifying first):

import { decodeJwt } from '@lookworld4/edge-jwt-lite';

const { header, payload } = decodeJwt(token);

API

| Export | Purpose | |------------------|---------| | verifyJwt() | Verifies signature via Web Crypto, then validates exp / nbf when present. iss / aud are checked only when you pass them in options. | | decodeJwt() | Parses header and payload JSON; no cryptographic verification. | | decodeJwtSegments() | Lower-level access to base64url parts and header.payload signing string. |

Key objects are typed as JwtHs256Secret, JwtRs256PublicKey, or JwtEs256PublicKey (see exported types).

Algorithms and security notes

• HS256: HMAC-SHA256 using your secret interpreted as UTF-8 when given a string.
• RS256 / ES256: Public key must be PEM SubjectPublicKeyInfo (BEGIN PUBLIC KEY). ES256 signatures in JWT are ASN.1 DER ECDSA signatures; internally they are converted to the IEEE P1363 form Web Crypto expects.
• The JWT alg header must match your key (HS256, RS256, or ES256). Passing allowedAlgorithms can further tighten which algorithms you accept.

This is intentionally lite: no JWKS fetching, no JWE, no none algorithm. Prefer a full-featured library on Node servers when you need those.

Scripts

npm run build   # tsup → dist (CJS + ESM + types)
npm test        # node --test (uses Web Crypto in Node 18+)

License

MIT — see LICENSE.