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.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Automation, Utilities & Developer Tools

무료