1.0.0

Highlights

• Security fixes – Addressed issues that could affect correctness and error handling in production.
• Documentation – README and examples updated for accuracy and consistency.

Security & correctness

• RSA-PSS key handling – Fixed a bug where the key’s algorithm object was mutated during use, which could lead to
  wrong algorithm usage or cryptographic errors. The library now uses a copy when adapting the key.
• Validation error handling – validateJWT now handles JSON.parse failures safely and no longer leaks raw parse
  errors. Error messages from unsafeParseJWT and unsafeParseJOSEHeader are sanitized while still throwing
  JWTParseError as before.

Documentation

• Removed “Experimental” labels from exportPEMKey and importPEMKey in the README.
• Fixed PEM export/import example (filename consistency).
• Reviewed and updated README examples and API documentation.

Other

• License – Copyright year updated to 2024–2026.
• CI – Lint, format, and tests passing; CodeQL security scan clean.

Upgrade from 0.6.x

No breaking API changes. You can upgrade by updating your dependency to 1.0.0 (or ^1.0.0). If you use RSA-PSS or
rely on specific error messages from the unsafe parse functions, behavior is improved rather than changed in a breaking
way.

What's Changed

• Prepare library for 1.0 release by @Copilot in #8

New Contributors

• @Copilot made their first contribution in #8

Full Changelog: 0.6.0...1.0.0

0.6.0

v0.6.0

This release introduces an error handling system with safe API variants, making @cross/jwt more robust and
suitable for functional programming patterns.

Result Type Driven Function Alternatives

• New *Safe function variants that return Result<T, JWTError> instead of throwing exceptions
• Perfect for functional programming patterns and better type safety
• Available for all core operations: signJWTSafe, validateJWTSafe, generateKeySafe, etc.

New Examples

• examples/basic-usage.ts - Traditional throwing API usage
• examples/result-type-usage.ts - Safe Result-based API usage

Backward Compatibility

• All existing APIs remain unchanged
• Safe variants are additive, not replacements
• Gradual migration path available

0.5.2

Bug Fixes

• TypeScript Compatibility: Fixed BufferSource type compatibility issues in cryptographic functions by adding proper type casting for textEncode() output
• Error Handling: Extended JWT validation error handling to properly catch and convert RangeError exceptions from Base64URL decoding to JWTFormatError

Technical Details

The release addresses two important compatibility and reliability issues:

1. TypeScript Strict Mode Support: The textEncode() function returns Uint8Array<ArrayBufferLike>, but the Web Crypto API expects BufferSource. Added explicit type casting (as BufferSource) in all cryptographic operations to ensure compatibility with strict TypeScript configurations.

2. Robust Error Handling: The JWT validation was only catching TypeError from Base64URL decoding, but invalid Base64URL strings (like those with incorrect length) throw RangeError. Updated error handling to catch both error types and properly convert them to JWTFormatError for consistent error reporting.

0.5.1

What's Changed

• dependency updates
• chore: add jsr prefix for deno by @ClaudiuCeia in #7

New Contributors

• @ClaudiuCeia made their first contribution in #7

Full Changelog: 0.5.0...0.5.1

0.5.0

• New function unsafeParseJOSEHeader() - "unsafely" parse the JOSE header of a JWT without cryptokey.
• New JWTOption additionalHeaderClaims - Additional claims to include/override as part of the JWT's JOSE header.

Working with JWT Headers

Some usage scenarios, such as interoperating with OIDC providers that set key identifier (kid) header claims in the JWTs they issue, require JWT header introspection. Similarly, it is sometimes necessary to create tokens with additional header claims or override existing claims (e.g., the typ claim).

The additionalHeaderClaims property in the JWTOptions provide the means to set/override header claims in tokens created through signJWT. Conversely, the unsafeParseJOSEHeader function reads the header claims of a token without validating it.

What's Changed

• Add support for additional header claims in signJWT() function by @cwirving in #5
• Add the ability to provide arbitrary custom header claims by @cwirving in #6

New Contributors

• @cwirving made their first contribution in #5

Full Changelog: 0.4.9...0.5.0

0.4.9

Cross runtime bug fix: Use crypto global object

Full Changelog: 0.4.8...0.4.9

0.4.8

Adding support and tests for expiresIn and notBefore helper options.
They translate into exp and nbf standard claims on payload signing.

const options: JWTOptions = {
    expiresIn: "1h",
    notBefore: "5m",
};

Full Changelog: 0.4.7...0.4.8

0.4.7

Changes to exportPEMKey(), now accepts options as an optional second

Function signature

async function exportPEMKey(key: CryptoKey, filePathOrOptions?: string | ExportPEMKeyOptions): Promise<string>

Options object

interface ExportPEMKeyOptions {
    /**
     * Optional path to write the PEM-formatted key to
     */
    filePath?: string;
    /**
     * Optional for file write mode
     */
    mode?: number;
}

Full Changelog: 0.4.6...0.4.7

0.4.6

publish version

0.4.5

• typo fix

Full Changelog: 0.4.4...0.4.5