3. If you use path aliases, map jose to the barrel file:

{
  "compilerOptions": {
    "paths": {
      "jose": ["./src/vendor/jose/index.ts"]
    }
  }
}

4. If consuming the npm package directly instead of the source, no path alias is needed. Node.js >= 18 is required for the native Web Crypto implementation (globalThis.crypto).

5. No environment variables are required. For remote JWKS (createRemoteJWKSet), ensure outbound HTTP(S) is allowed from your runtime.

Public API

SignJWT

import { SignJWT } from './src/vendor/jose/index.ts'

const jwt = await new SignJWT({ sub: 'user-id', role: 'admin' })
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuedAt()
  .setExpirationTime('2h')
  .sign(privateKey)

A builder class for creating signed compact JWTs. Chain setter methods to configure claims, then call .sign(key) with a CryptoKey or KeyLike. Use this whenever you need to mint a JWT with a specific algorithm and claims set.

jwtVerify

import { jwtVerify } from './src/vendor/jose/index.ts'
import type { JWTVerifyOptions } from './src/vendor/jose/index.ts'

const { payload, protectedHeader } = await jwtVerify(token, publicKey, {
  audience: 'my-api',
  issuer: 'https://auth.example.com',
} satisfies JWTVerifyOptions)

Verifies a compact JWT's signature and validates its standard claims (issuer, audience, expiry). Returns the decoded payload and protected header. Use with a static CryptoKey, a JWKS getter from createRemoteJWKSet, or any JWTVerifyGetKey callback.

createRemoteJWKSet

import { createRemoteJWKSet } from './src/vendor/jose/index.ts'
import type { RemoteJWKSetOptions } from './src/vendor/jose/index.ts'

const JWKS = createRemoteJWKSet(new URL('https://auth.example.com/.well-known/jwks.json'), {
  cacheMaxAge: 600_000,
} satisfies RemoteJWKSetOptions)

const { payload } = await jwtVerify(token, JWKS)

Fetches and caches a remote JWKS, automatically refreshing when a key is missing. Returns a key getter compatible with jwtVerify, compactVerify, and jwtDecrypt. Use this in any service that validates tokens from a third-party identity provider.

generateKeyPair

import { generateKeyPair } from './src/vendor/jose/index.ts'

const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true })

Generates an asymmetric key pair suitable for the named algorithm. Works for RSA, EC, and OKP families. Pass extractable: true if you need to export the key afterwards with exportJWK or exportPKCS8.

EncryptJWT

import { EncryptJWT } from './src/vendor/jose/index.ts'

const token = await new EncryptJWT({ sub: 'user-id' })
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .setIssuedAt()
  .setExpirationTime('1h')
  .encrypt(recipientPublicKey)

Builder class for creating encrypted compact JWTs (JWE). Use when the payload must remain confidential to third parties, not just tamper-evident.

Working examples

Scenario - Sign and verify a JWT with an EC key pair

Generate a key pair, sign a token, then verify it in the same process. Suitable for testing or self-contained microservices.

import {
  generateKeyPair,
  SignJWT,
  jwtVerify,
  exportJWK,
  importJWK,
} from './src/vendor/jose/index.ts'

const { privateKey, publicKey } = await generateKeyPair('ES256')

const token = await new SignJWT({ sub: '42', role: 'editor' })
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuer('https://example.com')
  .setAudience('api')
  .setIssuedAt()
  .setExpirationTime('15m')
  .sign(privateKey)

console.log('JWT:', token)

const { payload } = await jwtVerify(token, publicKey, {
  issuer: 'https://example.com',
  audience: 'api',
})

console.log('Payload:', payload)

Scenario - Validate a third-party JWT using a remote JWKS

Consume tokens issued by an external provider (e.g. Auth0, Okta) by fetching the JWKS endpoint at runtime.

import { createRemoteJWKSet, jwtVerify } from './src/vendor/jose/index.ts'

const JWKS = createRemoteJWKSet(
  new URL('https://YOUR_DOMAIN/.well-known/jwks.json'),
)

async function verifyToken(rawToken: string) {
  const { payload, protectedHeader } = await jwtVerify(rawToken, JWKS, {
    issuer: 'https://YOUR_DOMAIN/',
    audience: 'YOUR_API_IDENTIFIER',
  })
  return payload
}

// Express middleware example
import type { Request, Response, NextFunction } from 'express'

export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const auth = req.headers.authorization
  if (!auth?.startsWith('Bearer ')) return res.status(401).end()
  try {
    const payload = await verifyToken(auth.slice(7))
    ;(req as any).user = payload
    next()
  } catch {
    res.status(401).end()
  }
}

Scenario - Encrypted JWT (JWE) round-trip

Encrypt a JWT so that only the holder of the private key can read the claims. Useful for stateless session tokens containing sensitive data.

import {
  generateKeyPair,
  EncryptJWT,
  jwtDecrypt,
} from './src/vendor/jose/index.ts'

const { privateKey, publicKey } = await generateKeyPair('RSA-OAEP-256')

const encrypted = await new EncryptJWT({ userId: 'u_123', email: 'user@example.com' })
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .setIssuedAt()
  .setExpirationTime('1h')
  .encrypt(publicKey)

console.log('Encrypted token:', encrypted)

const { payload } = await jwtDecrypt(encrypted, privateKey)
console.log('Decrypted payload:', payload)

Scenario - Import a PEM public key and decode a JWT header

Parse an existing SPKI public key, then inspect a token's header without verifying it first.

import { importSPKI, decodeProtectedHeader, decodeJwt } from './src/vendor/jose/index.ts'

const pem = `-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYFK4EEAAoDQgAE...
-----END PUBLIC KEY-----`

const publicKey = await importSPKI(pem, 'ES256')

const token = 'eyJhbGciOiJFUzI1NiJ9...'

const header = decodeProtectedHeader(token)
console.log('alg:', header.alg) // 'ES256'

const claims = decodeJwt(token) // no verification - for inspection only
console.log('sub:', claims.sub)

File walkthrough

• index.ts - Barrel file; re-exports every public symbol. Import from here.
• types.d.ts - Shared interfaces: JWKParameters, JWK_EC_Public, JWK_OKP_Public, etc.
• jwe/compact/ - compactDecrypt / CompactEncrypt for the standard eyJ... JWE format.
• jwe/flattened/ - flattenedDecrypt / FlattenedEncrypt for JSON flattened JWE serialization.
• jwe/general/ - generalDecrypt / GeneralEncrypt for multi-recipient JWE.
• jwk/embedded.ts - EmbeddedJWK: extracts JWK from a token's own header for verification.
• jwk/thumbprint.ts - calculateJwkThumbprint / calculateJwkThumbprintUri per RFC 7638.
• jwks/local.ts - createLocalJWKSet: builds a key getter from an in-memory JWKS object.
• jwks/remote.ts - createRemoteJWKSet: fetches, caches, and auto-refreshes a remote JWKS.
• jws/compact/ - CompactSign / compactVerify for compact JWS (non-JWT).
• jws/flattened/ - FlattenedSign / flattenedVerify for flattened JWS serialization.
• jws/general/ - GeneralSign / generalVerify for multi-signature JWS.
• jwt/decrypt.ts - jwtDecrypt: decrypts a JWE-based JWT and validates its claims.
• jwt/encrypt.ts - EncryptJWT: fluent builder for encrypted JWTs.
• jwt/sign.ts - SignJWT: fluent builder for signed JWTs.
• jwt/unsecured.ts - UnsecuredJWT: produces/parses JWTs with alg: none (use with caution).
• jwt/verify.ts - jwtVerify: verifies a signed JWT and validates standard claims.
• key/export.ts - exportJWK, exportPKCS8, exportSPKI: serialise CryptoKey to portable formats.
• key/generate_key_pair.ts - generateKeyPair: async asymmetric key pair generation.
• key/generate_secret.ts - generateSecret: generates a symmetric secret key.
• key/import.ts - importJWK, importSPKI, importPKCS8, importX509: parse keys from PEM/JWK.
• lib/ - Internal helpers: AES-GCM, AES-KW, ECDH-ES, RSA, PBES2, signing, type checks. Not part of the public API.
• util/base64url.ts - Base64url encode/decode utilities.
• util/decode_jwt.ts - decodeJwt: decode JWT claims without verification.
• util/decode_protected_header.ts - decodeProtectedHeader: parse any JWS/JWE protected header.
• util/errors.ts - Typed error classes (JWTExpired, JWTInvalid, JOSENotSupported, etc.).

Common pitfalls and fixes

• Node.js < 18 lacks globalThis.crypto: upgrade to Node.js 18+ or polyfill with import { webcrypto } from 'crypto'; globalThis.crypto = webcrypto.
• ESM-only source in a CJS project: set "type": "module" in package.json or use a bundler (esbuild, Rollup) to transpile; bare require() will not work.
• .js extensions in import paths: the source uses .js extensions in imports (e.g. ./jwe/compact/decrypt.js). If you reference source .ts files directly, configure your bundler/TS to resolve .js -> .ts (e.g. "allowImportingTsExtensions": true or use path rewriting).
• UnsecuredJWT (alg: none) accepted by jwtVerify: it is not - use UnsecuredJWT.decode() explicitly; passing an unsecured token to jwtVerify will throw.
• Remote JWKS rate-limiting on key rotation: createRemoteJWKSet caches aggressively; if your provider rotates keys frequently, tune cacheMaxAge and cooldownDuration in RemoteJWKSetOptions.
• Algorithm mismatch errors: always set { alg } in setProtectedHeader to match the key type; omitting it causes a JOSENotSupported error at runtime.

Vibe-coding prompt template

I have dropped the jose JOSE library source into src/vendor/jose/ in my project.
The barrel file is src/vendor/jose/index.ts and a full integration guide is in USAGE.md.
The upstream package is user@example.com (zero dependencies, Web Crypto based).

Please help me integrate it into my project step by step:

1. Read USAGE.md and src/vendor/jose/index.ts to understand every available export.
2. Update tsconfig.json so TypeScript resolves imports from src/vendor/jose/index.ts correctly,
   including the .js extension rewriting needed for the internal relative imports.
3. Create a src/auth/jwt.ts module that:
   - Signs JWTs using SignJWT with ES256 and a generated key pair
   - Verifies incoming JWTs using jwtVerify with proper issuer/audience validation
   - Exports typed helpers: signToken(payload) and verifyToken(raw: string)
4. Wire authMiddleware (Express) using createRemoteJWKSet for production and
   the local key pair for development/test.
5. Show me how to handle jose error types from util/errors.ts (JWTExpired, etc.)
   in an Express error handler.
6. Do not invent any API surface - use only exports visible in src/vendor/jose/index.ts.

License and credit

jose is published under the MIT License (see source/LICENSE if present in this block, or verify at the npm registry). The upstream project is maintained by @panva. This AVCP block vendors user@example.com without modification.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free