export defaultCookies

[clausreinke]

Goals

1. safer and future-proof manipulation of cookies option (start with next-auth defaults, only touch/change what is needed)
2. do not interfere with next-auth cookies handling or risk introducing security issues just to change cookie names
3. support common requests that have been raised as issues, such as port-specific cookie names Cookie session two next-auth applications #611, hiding plugin name in cookie names Easier Manipulation of Cookie prefixes #1603, safer and easier manipulation of cookies option Better cookie options #6942

as suggested in #6942 (comment), the combination of the existing cookies option and the not-yet-exported defaultCookies should make it easy to implement these and similar requests

Non-Goals

Background

• all of the previously mentioned requests have been rejected with a pointer to the cookies option,
• yet that option comes with a strongly worded warning and is actually contraindicated by the plugin authors;

next-auth is used to make authentication easier, but

• if one wanted to change anything about cookies one would have to take control of every aspect;
• copying the current defaults from the documentation is not future-proof but decouples the project from future plugin developments in this area;

there is clearly a gap between what next-auth users consider easy and what the authors consider such;

after search the existing discussions/issues, it was #6942 (comment) that seemed to offer an out of this stalemate, suggesting to start with defaultCookies:

next-auth/packages/next-auth/src/core/lib/cookie.ts

Lines 56 to 119 in 7ba986b

	export function defaultCookies(useSecureCookies: boolean): CookiesOptions {
	const cookiePrefix = useSecureCookies ? "__Secure-" : ""
	return {
	// default cookie options
	sessionToken: {
	name: `${cookiePrefix}next-auth.session-token`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	},
	},
	callbackUrl: {
	name: `${cookiePrefix}next-auth.callback-url`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	},
	},
	csrfToken: {
	// Default to __Host- for CSRF token for additional protection if using useSecureCookies
	// NB: The `__Host-` prefix is stricter than the `__Secure-` prefix.
	name: `${useSecureCookies ? "__Host-" : ""}next-auth.csrf-token`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	},
	},
	pkceCodeVerifier: {
	name: `${cookiePrefix}next-auth.pkce.code_verifier`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	maxAge: 60 * 15, // 15 minutes in seconds
	},
	},
	state: {
	name: `${cookiePrefix}next-auth.state`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	maxAge: 60 * 15, // 15 minutes in seconds
	},
	},
	nonce: {
	name: `${cookiePrefix}next-auth.nonce`,
	options: {
	httpOnly: true,
	sameSite: "lax",
	path: "/",
	secure: useSecureCookies,
	},
	}
	}
	}

unfortunately, this module is not exported from the package, which is what this feature request is trying to address, but here is an example of port-specific cookie names (with a hackish import to bypass the missing export; you'll need to address the option in both /pages/api/auth/[...nextauth].ts and in middleware.ts):

import { defaultCookies } from '../node_modules/next-auth/core/lib/cookie';

const augmentNames = (cookies: CookiesOptions, port: number) => {
  let augmentedCookies = {};
  for (const [key, value] of Object.entries(cookies)) {
    augmentedCookies[key] = {
      ...value,
      name: cookies[key].name.replace('next-auth', `next-auth-${port}`)
    };
  }
  console.log(augmentedCookies);
  return augmentedCookies;
};

const augmentedCookies = augmentNames(defaultCookies(false), 3010);

exporting defaultCookies has been suggested before #6043, #3568, with the argument against being #3568 (comment):

This is an advanced option and is purposefully made harder to configure.

I think this argument is clearly false:

• the cookies option is available for change
• there is a need to change this option, so people configure it, no matter how difficult it is
  • worst case, the configuration is created from scratch and interferes with next-auth ideas
  • not much better, the configuration starts with a copy of the current default, so may conflict after next-auth updates
  • currently best, but not good: circumvent the lack of export by {importing from node_modules directly](getSession call does not trigger session object update until window loses focus #596 (comment))
• making it difficult to configure correctly only increases the risk of security flaws

Proposal

make defaultCookies available as an export of package next-auth