📣 Wristband Express Auth SDK 6.0.0 Release 🎉

Release v6.0.0

Breaking Changes

Migration Guide: https://github.com/wristband-dev/express-auth/blob/main/migration/v6/README.md

🔄 Authentication Middleware API Changes

The createRequireSessionAuth() method has been replaced with createAuthMiddleware() to support multiple authentication strategies.

Migration:

• createRequireSessionAuth() → createAuthMiddleware()
• Must explicitly specify authStrategies: ['SESSION']
• sessionOptions must now be provided in sessionConfig
• CSRF configuration now only in a single location -> sessionConfig.sessionOptions

📝 Tenant Parameter Standardization

Query Parameters:

• tenant_domain → tenant_name

URL Placeholders:

• {tenant_domain} → {tenant_name} ({tenant_domain} is deprecated but still supported for backward compatibility)

🔧 Type System Improvements

CallbackResultType:

• Enum replaced with string literal union type ('completed' | 'redirect_required')
• No need to import CallbackResultType enum anymore

AuthMiddlewareConfig:

• New nested configuration structure with authStrategies, sessionConfig, and jwtConfig
• enableCsrfProtection moved to sessionConfig.sessionOptions

New Features

✨ Multi-Strategy Authentication Middleware

New createAuthMiddleware() supports multiple authentication strategies with fallback behavior.

Supported Strategies:

• SESSION - Cookie-based session authentication with automatic token refresh
• JWT - Bearer token authentication with JWKS validation

Features:

• Try multiple strategies in order until one succeeds
• Automatic access token refresh for expired tokens (SESSION strategy)
• Optional CSRF token validation (SESSION strategy)
• Rolling session windows (SESSION strategy)
• Configurable JWKS caching (JWT strategy)

🔐 JWT Authentication Strategy

New JWT bearer token authentication powered by @wristband/typescript-jwt.

Features:

• Stateless JWT validation with JWKS
• Configurable JWK cache size and TTL
• Decoded JWT payload available in req.auth
• TypeScript support with Express Request augmentation

🔄 Callback Failure Reasons

CallbackResult now includes a reason field when type === 'redirect_required':

• missing_login_state - Login state cookie not found
• invalid_login_state - Login state validation failed
• login_required - Wristband returned login_required error
• invalid_grant - Authorization code was invalid or expired

For full documentation, see the README.