RFC: Improved environment detection (WIP)

[balazsorban44]

THIS IS A DRAFT

Background

Auth.js relies on contextual information about the environment it runs in., It needs to know if it is served from a trusted host (AUTH_TRUST_HOST), it needs a secret (AUTH_SECRET) value for generating JWTs, and working with OAuth providers, etc.

Auth.js is the next iteration on NextAuth.js, the library that was focused solely on Next.js/Node.js support.

The standard way of passing information in this context has been process.env¹.

Now that the ecosystem is growing and we want to support multiple frameworks and runtimes, there comes a challenge of fragmentation around environment variable handling.

• Next.js follows Node.js
• SvelteKit uses imports²

Goals

We want to make it easier to handle environment variables, by detecting them automatically, so they don't need to be passed manually in code.

Proposal

Introduce a with() method that can wrap AuthConfig (or can receive multiple arguments, where each argument is a provider config) and injects the values coming from the environment to the passed config to Auth.js for convenience.

Example:
Before:

import { Auth } from "@auth/nextjs"
import { GitHub } from "@auth/core/providers/github"
import { Auth0 } from "@auth/core/providers/auth0"

export default Auth({
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET
    }),
    Auth0({
      clientId: process.env.AUTH0_ID,
      clientSecret: process.env.AUTH0_SECRET,
      issuer: process.env.AUTH0_ISSUER
    }),
  ]
})

After:

import { Auth, with } from "@auth/nextjs"
import { GitHub } from "@auth/core/providers/github"
import { Auth0 } from "@auth/core/providers/auth0"

export default Auth(with(GitHub, Auth0))

or (still supporting any AuthConfig)

import { Auth, with } from "@auth/nextjs"
import { GitHub } from "@auth/core/providers/github"
import { Auth0 } from "@auth/core/providers/auth0"

export default Auth(with({
  providers: [
    GitHub,
    Auth0({
      profile(profile) {
        return ...
      }
    })
  ],
  ...
}))

To not interfere with existing variables, we would always assume an AUTH_ prefix, which is already the case for AUTH_SECRET and AUTH_TRUST_HOST.

For built-in OAuth providers, it would look like AUTH_GITHUB_ID and AUTH_GITHUB_SECRET, or in the case of OIDC providers, also check for AUTH_AUTH0_ISSUER. These variables need to be well-documented for all the providers.

Cons

Environment variable reading is different from framework to framework or even from runtime to runtime, so the with function needs to live in the specific framework's source code, referencing a bunch of environment variables. This would be much easier if a standard existed that each framework/runtime agreed on. At the time of writing this, there is only a WinterCG proposal.

Frameworks might also want to analyze variables statically, meaning we also cannot do things like const clientId = process.env[`AUTH_${provider.id.toUpperCase()}_ID`], so we would need to re-generate the with function each time a new built-in provider is added.

Footnotes

1. Next.js - Environment Variables ↩

2. https://kit.svelte.dev/docs/modules#$env-dynamic-private ↩