Extensive Cookie Configuration

[tusharpandey13]

Fixes #1889

Changes

This PR introduces enhanced configuration options for session cookies, allowing for finer control over their attributes.

• Added new SessionCookieOptions:
  • domain: Specifies the Domain attribute for the session cookie.
  • transient: If true, the maxAge attribute is omitted, making the cookie a session cookie (deleted when the browser closes). Defaults to false.
• Added support for Environment Variables: The SDK now reads the following environment variables to configure session cookies, providing an alternative to direct configuration:
  • AUTH0_COOKIE_DOMAIN
  • AUTH0_COOKIE_PATH
  • AUTH0_COOKIE_TRANSIENT
  • AUTH0_COOKIE_SECURE
  • AUTH0_COOKIE_SAME_SITE
• Updated setChunkedCookie: Logic adjusted to handle the transient option by omitting maxAge.
• Updated Auth0Client: Initialization logic now incorporates values from environment variables as defaults if direct configuration is not provided.
• Updated AbstractSessionStore: Now passes domain and transient options during cookie configuration.

Testing

• Added comprehensive unit tests in src/server/chunked-cookies.test.ts to verify the correct behavior of the new domain and transient options for both single and chunked cookies.
• Existing tests pass.

Usage

You can configure the new cookie options either through environment variables or directly in the SDK initialization.

1. Using Environment Variables:

Set the desired environment variables in your .env.local file or your deployment environment:

# .env.local
AUTH0_SECRET='LONG_RANDOM_STRING'
AUTH0_BASE_URL='http://localhost:3000'
AUTH0_ISSUER_BASE_URL='https://your-tenant.auth0.com'
AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'
AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

# New Cookie Options
AUTH0_COOKIE_DOMAIN='.example.com' # Set cookie for subdomains
AUTH0_COOKIE_PATH='/app'          # Limit cookie to /app path
AUTH0_COOKIE_TRANSIENT=true       # Make cookie transient (session-only)
AUTH0_COOKIE_SECURE=true          # Recommended for production
AUTH0_COOKIE_SAME_SITE='Lax'

The SDK will automatically pick up these values.

2. Using Auth0ClientOptions (App Router Example):

Configure the options directly when initializing the client handlers:

// app/api/auth/[auth0]/route.ts
import { handleAuth, handleLogin } from '@auth0/nextjs-auth0';

export const GET = handleAuth({
  login: handleLogin({
    authorizationParams: {
      audience: 'https://api.example.com/products' // or AUTH0_AUDIENCE
    }
  }),
  onError(req: Request, error: Error) {
    console.error(error);
  }
}, {
  session: {
    cookie: {
      domain: '.example.com',
      path: '/app',
      transient: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'Lax',
      // name: 'appSession', // Optional: custom cookie name
    }
  },
  secret: process.env.AUTH0_SECRET,
  baseURL: process.env.AUTH0_BASE_URL,
  clientID: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL
});

Note: Options provided directly in Auth0ClientOptions take precedence over environment variables.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.68%. Comparing base (da33ec8) to head (6dec246).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2059      +/-   ##
==========================================
+ Coverage   82.53%   82.68%   +0.15%     
==========================================
  Files          21       21              
  Lines        1941     1958      +17     
  Branches      342      347       +5     
==========================================
+ Hits         1602     1619      +17     
  Misses        333      333              
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[karth295]

Hey are there any blockers to merging and releasing this? Thanks for authoring this PR!

these changes have been made

[Copilot]

Pull Request Overview

This PR enhances the cookie configuration by introducing support for additional attributes (domain and transient), allowing finer control over session cookie behavior. Key changes include:

• Extending the SessionCookieOptions interface with new properties (domain and transient)
• Updating cookie setting logic in setChunkedCookie to omit the maxAge attribute when transient is enabled
• Adding environment variable support and updating corresponding documentation and tests

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/server/session/abstract-session-store.ts	Extends cookie options with domain and transient attributes.
src/server/cookies.ts	Adjusts setChunkedCookie logic to handle transient cookies.
src/server/client.ts	Updates session options to merge new cookie attributes with environment variable overrides.
src/server/chunked-cookies.test.ts	Adds tests to verify correct handling of domain and transient cookie configurations.
README.md	Updates documentation to detail the new cookie configuration options.
EXAMPLES.md	Provides updated examples on how to configure the new cookie options.