feat(core): add dynamic session maxAge support

[jae1jeong]

☕️ Reasoning

This PR introduces dynamic session maxAge support to NextAuth.js, addressing a long-standing limitation where developers couldn't implement "Remember Me" functionality natively.

Problem

NextAuth.js previously only supported static session durations, forcing developers to use complex workarounds for common UX patterns like:

• Remember Me checkboxes (persistent vs session cookies)
• Role-based session durations (shorter for admins, longer for users)
• Device-based session management (shorter on public devices)

Solution

Allow session.maxAge to be a function that returns dynamic values based on user data, roles, or preferences. This enables use cases like:

• Remember Me functionality (persistent vs session cookies)
• Role-based session durations
• Device-based session management

The maxAge can now be:

• A static number (seconds)
• "session" for browser session cookies
• An async function returning either value

Example Usage

export default {
  session: {
    maxAge: async ({ token }) => {
      // Remember Me functionality
      if (token?.rememberMe) {
        return 30 * 24 * 60 * 60 // 30 days
      }
      return "session" // Browser session cookie
    }
  },
  callbacks: {
    jwt({ token, user, trigger }) {
      if (trigger === "signIn" && user) {
        token.rememberMe = user.rememberMe
      }
      return token
    }
  }
}

🧢 Checklist

• Documentation - Added comprehensive guide in extending-the-session.mdx with real-world examples
• Tests - Added 152 lines of test coverage including edge cases for both JWT and database sessions
• Ready to be merged - All tests pass, backward compatible, type-safe implementation

🎫 Affected issues

This PR addresses several community requests for Remember Me functionality:

• Resolves common workaround patterns mentioned in discussions
• Enables native support for session persistence preferences
• Provides foundation for advanced session management patterns

📌 Resources

• Security guidelines
• Contributing guidelines
• Code of conduct
• Contributing to Open Source

---

Technical Details

Files Changed:

• packages/core/src/index.ts - Enhanced AuthConfig type definitions
• packages/core/src/lib/actions/callback/index.ts - Dynamic maxAge resolution logic
• packages/core/src/lib/actions/session.ts - Session cookie handling for dynamic values
• docs/pages/guides/extending-the-session.mdx - User documentation with examples
• packages/core/test/actions/session.test.ts - Comprehensive test suite

Backward Compatibility:

• ✅ All existing static maxAge configurations work unchanged
• ✅ No breaking changes to existing APIs
• ✅ Maintains type safety with enhanced TypeScript definitions

Performance:

• Minimal overhead - dynamic resolution only occurs during session operations
• Efficient caching of resolved values
• No impact on existing static configurations

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
auth-docs	Error			Aug 26, 2025 5:26am

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
next-auth-docs	Ignored	Preview		Aug 26, 2025 5:26am

[vercel]

@jae1jeong is attempting to deploy a commit to the authjs Team on Vercel.

A member of the Team first needs to authorize it.