Session Management For Next.js SDK

📣 Wristband Next.js Auth SDK 4.0.0 Release 🎉

New Features

For full documentation of all new features, refer to the SDK README.

✨ Built-in Session Management (Optional)

Optional encrypted cookie-based session management powered by @wristband/typescript-session .

Features:

AES-256-GCM encrypted sessions
Optional CSRF protection
TypeScript support with extensible SessionData interface
Context-specific helpers for App Router, Pages Router, Server Components, Server Actions, and Middleware
Automatic token refresh with rolling sessions

ℹ️
Note: Built-in session management is entirely optional and does not affect existing applications using other session libraries.

🔐 Authentication Middleware

New createMiddlewareAuth() function for protecting routes with multiple authentication strategies.

Features:

Support for SESSION and JWT authentication strategies (JWT validation supported by @wristband/typescript-jwt )
Automatic token refresh for expired access tokens
Optional CSRF token validation
Configurable protected API routes and pages
Custom unauthenticated handlers
Middleware chaining support

🛡️ Server Action Authentication

New createServerActionAuth() helper for protecting Server Actions with session validation and automatic token refresh.

📦 Session Helper Functions

New context-specific session helpers:

Session Helper Function	Router Type	Where to Use It
`getSessionFromRequest()`	App, Pages	App Router API routes and Next.js middleware/proxy
`getPagesRouterSession()`	Pages	Pages Router API routes and `getServerSideProps()`
`getReadOnlySessionFromCookies()`	App	Server Components (read-only)
`getMutableSessionFromCookies()`	App	Server Actions (read/write)
`saveSessionWithCookies()`	App	Persist session changes in Server Actions
`destroySessionWithCookies()`	App	Clear session in Server Actions

🔄 Callback Failure Reasons

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

Reason	Description
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

Breaking Changes

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

🔄 UserInfo Type Improvements

The SDK now provides a structured UserInfo type that transforms raw OIDC claims into camelCase properties for better type safety and JavaScript/TypeScript conventions.

Migration:

userinfo.sub → userinfo.userId
userinfo.tnt_id → userinfo.tenantId
userinfo.idp_name → userinfo.identityProviderName
userinfo.given_name → userinfo.givenName

📝 Property Renames for Consistency

WristbandAuth API:

pageRouter → pagesRouter

Query Parameters and URL Placeholders:

tenant_domain query param → tenant_name
{tenant_domain} URL placeholder → {tenant_name} ({tenant_domain} is deprecated but still supported; it will eventually be removed in future releases)

LoginConfig:

defaultTenantDomainName → defaultTenantName

CallbackData:

tenantDomainName → tenantName
userinfo now uses the new UserInfo type

CallbackResultType:

Enum replaced with string literal union type ('completed' | 'redirect_required')

LogoutConfig:

tenantDomainName → tenantName