RFC: AuthRequest and AuthResponse

[balazsorban44]

UPDATE: The implementation of this RFC can be found here: #6254, it will be updated accordingly, if feedback is received.

Background

Auth.js builds on Request¹ and Response² as its input and output respectively. This is crucial to achieving its goal to be runtime and framework agnostic.

Each incoming request is associated with one of the following actions:

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

Lines 420 to 428 in e6a320b

	export type AuthAction =
	| "providers"
	| "session"
	| "csrf"
	| "signin"
	| "signout"
	| "callback"
	| "verify-request"
	| "error"

Based on the incoming request action (encoded in Request#input as part of a URL³) and a RequestInit#method (currently either GET or POST⁴), Auth.js always returns a particular response.

For example, a request to https://example.com/api/auth/session will always return a JSON response, with the decoded session data, or https://example.com/api/auth/providers returns an array of the configured providers with minimal client-safe information.

Frameworks will usually catch all relevant actions and hand over the requests to Auth.js. However, in some situations, you might already know about the specific action you want to perform.

Such an example is the unstable_getServerSession method⁵, which can be used to extract the session info from the passed request.

Goals

This proposal builds on the same idea as unstable_getServerSession but brings a bit more flexibility and a more streamlined API to better support any of the actions where it makes sense.

Initially, we would support the following actions:

1. session: SessionRequest -> SessionResponse
2. providers: ProvidersRequest -> ProviderResponse

Other candidates:

Eventually, we could support any action+method combination, as long as it makes sense and there is interest, please leave a comment and upvote the ones you would like to see, and if you have a proposed API for it.

Proposal

We are drawing inspiration from NextRequest⁶ and NextResponse⁷. The idea is to extend the standard Request but make it easier to configure Auth.js and indicate, we are expecting a certain type of response.

Here is an example of session retrieval:

import { Auth, SessionRequest } from "@auth/core"

// coming from the framework/runtime
// Think Next.js API routes, SvelteKit server routes, etc.

async function handler(req: Request) {

  const response = await Auth(new SessionRequest(req), { ... })

  // "response instanceof Response" would return true

  // SessionResponse#session is a method that simplifies getting the parsed session object
  const session = await response.session()
  if (response.ok && session) {
    // The user is authenticated, do something with the data

    // It is recommended to forward the headers to preserve the cookies handled by Auth.js
    return new Response("Authenticated.", { headers: response.headers })
  }

  return new Response("Unauthenticated.", { status: 401 })
}

Framework packages like @auth/sveltekit, @auth/solid-start etc. could abstract these into eg. getSession for convenience (similar to unstable_getServerSession), if there is interest, but the initial proposal is only for @auth/core.

Footnotes

1. Request - Web API ↩

2. Response - Web API ↩

3. URL - Web API ↩

4. https://github.com/nextauthjs/next-auth/blob/e6a320bb0f883dd513904d66d5c4e1ecf09f5b18/packages/core/src/lib/web.ts#L43-L45 ↩

5. unstable_getServerSession in NextAuth.js ↩

6. NextRequest ↩

7. NextResponse ↩

[balazsorban44]

@sergiodxa could you expand? 🙏

[sergiodxa]

I was checking Auth.JS to see how I could leverage it for Remix Auth, specially to benefit from the list of OAuth2 providers.

I like a lot that Auth.JS now uses standard Request and Response objects and I think creating a AuthRequest and AuthResponse is going against that (I think the same about NextRequest and NextResponse)

If any the framework specific implementations could wrap the standard ones, but for example in Remix I wouldn’t need to have the response.session method because Remix itself provides a way to work with sessions.

[balazsorban44]

Note that these are absolutely not needed for the integration with frameworks, in fact they aren't used today either. Example: https://github.com/nextauthjs/next-auth/blob/main/packages/frameworks-sveltekit/src/lib/index.ts#L198, but would just make the API cleaner.

The same goes for NextRequest and NextResponse they are not going against the spec in any way (in fact both respectively extend RequestandResponse`), just augmenting them with utility functions/properties.

[sergiodxa]

just augmenting them with utility functions/properties

This goes against the spec, because the spec doesn't include those functions/properties.

I think any extra function should be implemented as a helper, like getSomethingFromRequest(request)

The moment you stop using Request/Response and have CustomRequest/CustomResponse you make interoperability not possible, for example it wouldn't be possible to just use it with something like Cloudflare Workers.

[balazsorban44]

Again, note that this is not a requirement for implementing/using Auth.js.

It does not go against the spec since it's not touching the global Request or Response in any way, just extending it via something that you explicitly import, so it's fully opt-in. But even then, I am not sure why it would not work on Cloudflare Workers, as long as it's using web standards in its implementation as well. Which it does, see the linked PR:

https://github.com/nextauthjs/next-auth/blob/471471b30351887d6ccc405663afadb26f1f58d9/packages/core/src/lib/web-extension.ts

getSomethingFromRequest is essentially the same, are we discussing the actual public API design?

The problem with that is it does not really tell Auth.js what action it should execute. We are not trying to get anything from the request, but rather the response. So we need to specify the action in the request.

We could have gone with adding an action: AuthAction option to AuthConfig, but then the Auth() call would either have to return something else than a Response, or on a new line, you would have to getSomethingFromResponse, essentially defining twice the action you wanted to execute.

With the current design, you get a Response instance which you can use as you would use a regular response, or you can call the session or providers methods that will execute some logic for you for cleanliness, all while explicitly telling Auth() to do a certain action. But if you rather do it yourself, you just do it manually, either is fine, this RFC introduces a more convenient way to do this:

next-auth/packages/frameworks-sveltekit/src/lib/index.ts

Lines 198 to 215 in 5cf580d

	export async function getSession(
	req: Request,
	config: AuthConfig
	): ReturnType<App.Locals["getSession"]> {
	config.secret ??= env.AUTH_SECRET
	config.trustHost ??= true
	const url = new URL("/api/auth/session", req.url)
	const request = new Request(url, { headers: req.headers })
	const response = await Auth(request, config)
	const { status = 200 } = response
	const data = await response.json()
	if (!data || !Object.keys(data).length) return null
	if (status === 200) return data
	throw new Error(data.message)
	}

Let me know if this makes sense!

[utsavbusa]

This is the worst documentation I have ever seen for any framework or library. You are number one in being bad at this. Please improve this!

[iMrDJAi]

@balazsorban44 I believe that whether we switch to AuthRequest and AuthResponse or stick to the standard Request and Response, helper functions should be provided to users to convert request/response objects from popular libraries/frameworks (e.g. express) to something that the Auth() handler may work with.

[balazsorban44]

It's out of scope for @auth/core to add framework/runtime helpers (the framework should be providing core with a standard Request), but I've been thinking about this the comments by @sergiodxa and I want to see if I have an alternative API proposal.

[sergiodxa]

@balazsorban44 I have been trying to use @auth/core to build a Remix wrapper, and what I have found is that I actually don't want Auth() to give me back a Response object.

For example, Auth() gives me a Response and sets the cookies for the session, but I want to use the SessionStorage implementation of Remix since that's how sessions are typically handled by Remix, if Auth() gives me an object with everything I need to construct the Response I could do it myself, maybe even give me a helper to create the Response from that object in case I don't have opinion about that.

[balazsorban44]

@sergiodxa Circulating back at this, I decided to implement something similar to what you have been asking for, as this has come up elsewhere out of necessity.

You can see: 7ff4d9d

This will return a response-like object instead.

Now you can add

// Some framework code
import { Auth, raw } from "@auth/core"

const rawResponse = await Auth(new Request("https://example.com"), { raw })

This is similar to #6379

It uses a Symbol instead of a boolean, and requiring an import from @auth/core makes it very explicit that this is intended for those who want a non-standard return type.

Will have to fix types later.

This is available in @auth/[email protected]