Allow the re-use of internal parts to simplify customization

[jrmyio]

When trying to extend or modify next-auth default behaviors I ran into several problems where the core does not seem to be flexible enough and there seem to be no way to re-use some of its parts. In a PR (#4036) I tried to add more flexibility but as @balazsorban44 mentioned adding more configuration is probably not the right way to do this.

The docs recommend using a high-level method: initialization#advanced-initialization. However, this code is ran BEFORE next-auth does its internal magic, thus you miss out on some of the internal implementations and framework agnostic abstractions.

In an attempt to build things on top of next-auth I ran into the following problems with its internals:

Problem 1: Redirect responses instead of errors

When consuming next-auth as a Rest API one would want JSON responses that describes the errors with a message and/or code. However, the internal route handling currently (only) returns 'redirects' with error messages embedded.

Example:

next-auth/packages/next-auth/src/core/routes/signin.ts

Lines 70 to 75 in 3d0c68d

	return {
	redirect: `${url}/error?${new URLSearchParams({
	error: error as string,
	})}`,
	}
	}

Possible solution:

Introduce an error object (possibly with an Error.type = enum) on OutgoingResponse that can then be used in favor of the redirect for rest APIs.

Problem 2: Initialization function of next-auth configuration is not exported

The initialization of the next-auth configuration is being done pretty deep (just before the route handling):

next-auth/packages/next-auth/src/core/index.ts

Lines 72 to 81 in a72f1b6

	const { options, cookies } = await init({
	userOptions,
	action,
	providerId,
	host: req.host,
	callbackUrl: req.body?.callbackUrl ?? req.query?.callbackUrl,
	csrfToken: req.body?.csrfToken,
	cookies: req.cookies,
	isPost: method === "POST",
	})

But when making custom routes (as explained in initialization#advanced-initialization, one does not have access to an asserted and initialization next-auth configuration yet (just the userOptions).

Possible solution:

Export the init function and assetConfig in next-auth built package.

Note: It might also be good to move any config related code (init, assert, related errors) to different folder, for example: /packages/next-auth/src/core/config.

Problem 3: Request/Response transformation to framework agnostic code not reusable

The IncomingRequest:

next-auth/packages/next-auth/src/core/index.ts

Lines 13 to 24 in a72f1b6

	export interface IncomingRequest {
	/** @default "http://localhost:3000" */
	host?: string
	method?: string
	cookies?: Record<string, string>
	headers?: Record<string, any>
	query?: Record<string, any>
	body?: Record<string, any>
	action: NextAuthAction
	providerId?: string
	error?: string
	}

and OutgoingResponse:

next-auth/packages/next-auth/src/core/index.ts

Lines 31 to 39 in a72f1b6

	export interface OutgoingResponse<
	Body extends string | Record<string, any> | any[] = any
	> {
	status?: number
	headers?: NextAuthHeader[]
	body?: Body
	redirect?: string
	cookies?: Cookie[]
	}

are nice abstractions to create framework agnostic request/response.

However, since the transformation from and to these types are done internally here, you have to re-implement
them when you want to extend next-auth (in next.js) as proposed in initialization#advanced-initialization.

Related question: When devs want create additional framework agnostic functionality do we expect them to implement on these IncomingRequest/OutgoingResponse abstractions?

Possible solution:

Extract the transformation in a seperate function that can be called manually when required.

Notes

If the internals are not set in stone yet, and as a result exporting internal parts of next-auth is not an option because of BC, I suggest the use of next-auth/internals instead of next-auth until the types are fleshed out while warning people about next-auth/internals being subject to change with each next-auth version.

Contributing 🙌🏽

Yes, I am willing to help implement this feature in a PR.

[longlostnick]

@jrmyio appreciate you listing this all out! Did you ever get any of this figured out? My biggest problem right now is #2. Even having just this ability would unlock all sorts of flexibility.