chore: wip

* tweak types, fix typos

* filter non-oauth files when generating provider types

* allow implicit config invoke

* remove workaround for multiple cookie settings in Next.js

* feat: return `null` when session does not exist

* error on missing checks when configured

packages/core/scripts/generate-providers.js

@@ -5,10 +5,11 @@ const providersPath = join(process.cwd(), "src/providers")
 
 const files = readdirSync(providersPath, "utf8")
 
+const nonOAuthFile = ["oauth-types", "oauth", "index", "email", "credentials"]
 const providers = files.map((file) => {
   const strippedProviderName = file.substring(0, file.indexOf("."))
   return `"${strippedProviderName}"`
-}).filter((provider) => provider !== '"oauth-types"' && provider !== '"index"')
+}).filter((provider) => !nonOAuthFile.includes(provider.replace(/"/g, '')))
 
 const result = `
 // THIS FILE IS AUTOGENERATED. DO NOT EDIT.

packages/core/src/errors.ts

@@ -1,6 +1,5 @@
 interface ErrorCause extends Record<string, unknown> {}
 
-/** @internal */
 export class AuthError extends Error {
   constructor(message: string | Error | ErrorCause, cause?: ErrorCause) {
     if (message instanceof Error) {
@@ -91,7 +90,7 @@ export class InvalidCallbackUrl extends AuthError {}
 export class InvalidEndpoints extends AuthError {}
 
 /** @todo */
-export class InvalidState extends AuthError {}
+export class InvalidCheck extends AuthError {}
 
 /** @todo */
 export class JWTSessionError extends AuthError {}

packages/core/src/jwt.ts

@@ -48,9 +48,10 @@ const DEFAULT_MAX_AGE = 30 * 24 * 60 * 60 // 30 days
 const now = () => (Date.now() / 1000) | 0
 
 /** Issues a JWT. By default, the JWT is encrypted using "A256GCM". */
-export async function encode(params: JWTEncodeParams) {
+export async function encode<Payload = JWT>(params: JWTEncodeParams<Payload>) {
   const { token = {}, secret, maxAge = DEFAULT_MAX_AGE } = params
   const encryptionSecret = await getDerivedEncryptionKey(secret)
+  // @ts-expect-error `jose` allows any object as payload.
   return await new EncryptJWT(token)
     .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
     .setIssuedAt()
@@ -60,14 +61,16 @@ export async function encode(params: JWTEncodeParams) {
 }
 
 /** Decodes a Auth.js issued JWT. */
-export async function decode(params: JWTDecodeParams): Promise<JWT | null> {
+export async function decode<Payload = JWT>(
+  params: JWTDecodeParams
+): Promise<Payload | null> {
   const { token, secret } = params
   if (!token) return null
   const encryptionSecret = await getDerivedEncryptionKey(secret)
   const { payload } = await jwtDecrypt(token, encryptionSecret, {
     clockTolerance: 15,
   })
-  return payload
+  return payload as Payload
 }
 
 export interface GetTokenParams<R extends boolean = false> {
@@ -179,9 +182,9 @@ export interface DefaultJWT extends Record<string, unknown> {
  */
 export interface JWT extends Record<string, unknown>, DefaultJWT {}
 
-export interface JWTEncodeParams {
+export interface JWTEncodeParams<Payload = JWT> {
   /** The JWT payload. */
-  token?: JWT
+  token?: Payload
   /** The secret used to encode the Auth.js issued JWT. */
   secret: string
   /**

packages/core/src/lib/assert.ts

@@ -101,7 +101,8 @@ export function assertConfig(
     )
   }
 
-  for (const provider of options.providers) {
+  for (const p of options.providers) {
+    const provider = typeof p === "function" ? p() : p
     if (
       (provider.type === "oauth" || provider.type === "oidc") &&
       !(provider.issuer ?? provider.options?.issuer)
@@ -127,7 +128,7 @@ export function assertConfig(
   if (hasCredentials) {
     const dbStrategy = options.session?.strategy === "database"
     const onlyCredentials = !options.providers.some(
-      (p) => p.type !== "credentials"
+      (p) => (typeof p === "function" ? p() : p).type !== "credentials"
     )
     if (dbStrategy && onlyCredentials) {
       return new UnsupportedStrategy(
@@ -135,9 +136,10 @@ export function assertConfig(
       )
     }
 
-    const credentialsNoAuthorize = options.providers.some(
-      (p) => p.type === "credentials" && !p.authorize
-    )
+    const credentialsNoAuthorize = options.providers.some((p) => {
+      const provider = typeof p === "function" ? p() : p
+      return provider.type === "credentials" && !provider.authorize
+    })
     if (credentialsNoAuthorize) {
       return new MissingAuthorize(
         "Must define an authorize() handler to use credentials authentication provider"

packages/core/src/lib/index.ts

@@ -11,6 +11,7 @@ import type {
   ResponseInternal,
 } from "../types.js"
 
+/** @internal */
 export async function AuthInternal<
   Body extends string | Record<string, any> | any[]
 >(

packages/core/src/lib/oauth/callback.ts

@@ -73,7 +73,7 @@ export async function handleOAuth(
 
   const state = await checks.state.use(cookies, resCookies, options)
 
-  const parameters = o.validateAuthResponse(
+  const codeGrantParams = o.validateAuthResponse(
     as,
     client,
     new URLSearchParams(query),
@@ -81,36 +81,22 @@ export async function handleOAuth(
   )
 
   /** https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1 */
-  if (o.isOAuth2Error(parameters)) {
+  if (o.isOAuth2Error(codeGrantParams)) {
     logger.debug("OAuthCallbackError", {
       providerId: provider.id,
-      ...parameters,
+      ...codeGrantParams,
     })
-    throw new OAuthCallbackError(parameters.error)
+    throw new OAuthCallbackError(codeGrantParams.error)
   }
 
-  const codeVerifier = await checks.pkce.use(
-    cookies?.[options.cookies.pkceCodeVerifier.name],
-    options
-  )
-
-  if (codeVerifier) resCookies.push(codeVerifier.cookie)
-
-  // TODO:
-  const nonce = await checks.nonce.use(
-    cookies?.[options.cookies.nonce.name],
-    options
-  )
-  if (nonce && provider.type === "oidc") {
-    resCookies.push(nonce.cookie)
-  }
+  const codeVerifier = await checks.pkce.use(cookies, resCookies, options)
 
   let codeGrantResponse = await o.authorizationCodeGrantRequest(
     as,
     client,
-    parameters,
+    codeGrantParams,
     provider.callbackUrl,
-    codeVerifier?.codeVerifier ?? "auth" // TODO: review fallback code verifier
+    codeVerifier ?? "auth" // TODO: review fallback code verifier
   )
 
   if (provider.token?.conform) {
@@ -131,11 +117,12 @@ export async function handleOAuth(
   let tokens: TokenSet
 
   if (provider.type === "oidc") {
+    const nonce = await checks.nonce.use(cookies, resCookies, options)
     const result = await o.processAuthorizationCodeOpenIDResponse(
       as,
       client,
       codeGrantResponse,
-      nonce?.value ?? o.expectNoNonce
+      nonce ?? o.expectNoNonce
     )
 
     if (o.isOAuth2Error(result)) {

packages/core/src/lib/oauth/checks.ts

@@ -1,14 +1,17 @@
 import * as o from "oauth4webapi"
-import * as jwt from "../../jwt.js"
+import { InvalidCheck } from "../../errors.js"
+import { encode, decode } from "../../jwt.js"
 
 import type {
+  CookiesOptions,
   InternalOptions,
   RequestInternal,
-  CookiesOptions,
 } from "../../types.js"
 import type { Cookie } from "../cookie.js"
 
-import { InvalidState } from "../../errors.js"
+interface CheckPayload {
+  value: string
+}
 
 /** Returns a signed cookie. */
 export async function signCookie(
@@ -25,7 +28,11 @@ export async function signCookie(
   expires.setTime(expires.getTime() + maxAge * 1000)
   return {
     name: cookies[type].name,
-    value: await jwt.encode({ ...options.jwt, maxAge, token: { value } }),
+    value: await encode<CheckPayload>({
+      ...options.jwt,
+      maxAge,
+      token: { value },
+    }),
     options: { ...cookies[type].options, expires },
   }
 }
@@ -44,34 +51,43 @@ export const pkce = {
     )
     return { cookie, value }
   },
-
   /**
-   * Returns code_verifier if provider uses PKCE,
+   * Returns code_verifier if the provider is configured to use PKCE,
    * and clears the container cookie afterwards.
+   * An error is thrown if the code_verifier is missing or invalid.
+   * @see https://www.rfc-editor.org/rfc/rfc7636
+   * @see https://danielfett.de/2020/05/16/pkce-vs-nonce-equivalent-or-not/#pkce
    */
   async use(
-    codeVerifier: string | undefined,
+    cookies: RequestInternal["cookies"],
+    resCookies: Cookie[],
     options: InternalOptions<"oauth">
-  ): Promise<{ codeVerifier: string; cookie: Cookie } | undefined> {
-    const { cookies, provider } = options
+  ): Promise<string | undefined> {
+    const { provider } = options
 
-    if (!provider?.checks?.includes("pkce") || !codeVerifier) {
-      return
-    }
+    if (!provider?.checks?.includes("pkce")) return
 
-    const pkce = (await jwt.decode({
+    const codeVerifier = cookies?.[options.cookies.pkceCodeVerifier.name]
+
+    if (!codeVerifier)
+      throw new InvalidCheck("PKCE code_verifier cookie was missing.")
+
+    const value = await decode<CheckPayload>({
       ...options.jwt,
       token: codeVerifier,
-    })) as any
+    })
 
-    return {
-      codeVerifier: pkce?.value ?? undefined,
-      cookie: {
-        name: cookies.pkceCodeVerifier.name,
-        value: "",
-        options: { ...cookies.pkceCodeVerifier.options, maxAge: 0 },
-      },
-    }
+    if (!value?.value)
+      throw new InvalidCheck("PKCE code_verifier value could not be parsed.")
+
+    // Clear the pkce code verifier cookie after use
+    resCookies.push({
+      name: options.cookies.pkceCodeVerifier.name,
+      value: "",
+      options: { ...options.cookies.pkceCodeVerifier.options, maxAge: 0 },
+    })
+
+    return value.value
   },
 }
 
@@ -86,26 +102,29 @@ export const state = {
     return { cookie, value }
   },
   /**
-   * Returns state from the saved cookie
-   * if the provider supports states,
+   * Returns state if the provider is configured to use state,
    * and clears the container cookie afterwards.
+   * An error is thrown if the state is missing or invalid.
+   * @see https://www.rfc-editor.org/rfc/rfc6749#section-10.12
+   * @see https://www.rfc-editor.org/rfc/rfc6749#section-4.1.1
    */
   async use(
     cookies: RequestInternal["cookies"],
     resCookies: Cookie[],
     options: InternalOptions<"oauth">
   ): Promise<string | undefined> {
-    const { provider, jwt } = options
+    const { provider } = options
     if (!provider.checks.includes("state")) return
 
     const state = cookies?.[options.cookies.state.name]
 
-    if (!state) throw new InvalidState("State was missing from the cookies.")
+    if (!state) throw new InvalidCheck("State cookie was missing.")
 
     // IDEA: Let the user do something with the returned state
-    const value = (await jwt.decode({ ...options.jwt, token: state })) as any
+    const value = await decode<CheckPayload>({ ...options.jwt, token: state })
 
-    if (!value?.value) throw new InvalidState("Could not parse state cookie.")
+    if (!value?.value)
+      throw new InvalidCheck("State value could not be parsed.")
 
     // Clear the state cookie after use
     resCookies.push({
@@ -128,28 +147,36 @@ export const nonce = {
     return { cookie, value }
   },
   /**
-   * Returns nonce from if the provider supports nonce,
+   * Returns nonce if the provider is configured to use nonce,
    * and clears the container cookie afterwards.
+   * An error is thrown if the nonce is missing or invalid.
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes
+   * @see https://danielfett.de/2020/05/16/pkce-vs-nonce-equivalent-or-not/#nonce
    */
   async use(
-    nonce: string | undefined,
+    cookies: RequestInternal["cookies"],
+    resCookies: Cookie[],
     options: InternalOptions<"oauth">
-  ): Promise<{ value: string; cookie: Cookie } | undefined> {
-    const { cookies, provider } = options
+  ): Promise<string | undefined> {
+    const { provider } = options
 
-    if (!provider?.checks?.includes("nonce") || !nonce) {
-      return
-    }
+    if (!provider?.checks?.includes("nonce")) return
 
-    const value = (await jwt.decode({ ...options.jwt, token: nonce })) as any
+    const nonce = cookies?.[options.cookies.nonce.name]
+    if (!nonce) throw new InvalidCheck("Nonce cookie was missing.")
 
-    return {
-      value: value?.value ?? undefined,
-      cookie: {
-        name: cookies.nonce.name,
-        value: "",
-        options: { ...cookies.nonce.options, maxAge: 0 },
-      },
-    }
+    const value = await decode<CheckPayload>({ ...options.jwt, token: nonce })
+
+    if (!value?.value)
+      throw new InvalidCheck("Nonce value could not be parsed.")
+
+    // Clear the nonce cookie after use
+    resCookies.push({
+      name: options.cookies.nonce.name,
+      value: "",
+      options: { ...options.cookies.nonce.options, maxAge: 0 },
+    })
+
+    return value.value
   },
 }

packages/core/src/lib/providers.ts

@@ -23,7 +23,8 @@ export default function parseProviders(params: {
 } {
   const { url, providerId } = params
 
-  const providers = params.providers.map((provider) => {
+  const providers = params.providers.map((p) => {
+    const provider = typeof p === "function" ? p() : p
     const { options: userOptions, ...defaults } = provider
 
     const id = (userOptions?.id ?? defaults.id) as string

packages/core/src/lib/routes/callback.ts

@@ -139,7 +139,6 @@ export async function callback(params: {
         })
       }
 
-      // @ts-expect-error
       await events.signIn?.({ user, account, profile, isNewUser })
 
       // Handle first logins on new accounts

packages/core/src/lib/routes/session.ts

@@ -9,7 +9,7 @@ import type { SessionStore } from "../cookie.js"
 export async function session(
   sessionStore: SessionStore,
   options: InternalOptions
-): Promise<ResponseInternal<Session | {}>> {
+): Promise<ResponseInternal<Session | null>> {
   const {
     adapter,
     jwt,
@@ -19,8 +19,8 @@ export async function session(
     session: { strategy: sessionStrategy, maxAge: sessionMaxAge },
   } = options
 
-  const response: ResponseInternal<Session | {}> = {
-    body: {},
+  const response: ResponseInternal<Session | null> = {
+    body: null,
     headers: { "Content-Type": "application/json" },
     cookies: [],
   }

packages/core/src/lib/web.ts

@@ -78,7 +78,6 @@ export function toResponse(res: ResponseInternal): Response {
     const cookieHeader = serialize(name, value, options)
     if (headers.has("Set-Cookie")) headers.append("Set-Cookie", cookieHeader)
     else headers.set("Set-Cookie", cookieHeader)
-    // headers.set("Set-Cookie", cookieHeader) // TODO: Remove. Seems to be a bug with Headers in the runtime
   })
 
   let body = res.body

packages/core/src/providers/apple.ts

@@ -1,22 +1,19 @@
 /**
- * <div style={{backgroundColor: "#000", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Apple</b> integration.</span>
- * <a href="https://apple.com">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/apple-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Apple</b> integration.
+ * </span>
+ * <a href="https://apple.com" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/apple-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/apple
  */
 
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
-/**
- * See more at:
- * [Retrieve the User's Information from Apple ID Servers
-](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple#3383773)
- */
+/** The returned user profile from Apple when using the profile callback. */
 export interface AppleProfile extends Record<string, any> {
   /**
    * The issuer registered claim identifies the principal that issued the identity token.
@@ -99,6 +96,44 @@ export interface AppleProfile extends Record<string, any> {
   auth_time: number
 }
 
+/**
+ * ## Setup
+ *
+ * Import the provider and configure it in your **Auth.js** initialization file:
+ *
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AppleProvider from "next-auth/providers/apple"
+ *
+ * export default NextAuth({
+ *   providers: [
+ *     AppleProvider({
+ *       clientId: process.env.GITHUB_ID,
+ *       clientSecret: process.env.GITHUB_SECRET,
+ *     }),
+ *   ],
+ * })
+ * ```
+ * 
+ * ## Resources
+ * 
+ * - Sign in with Apple [Overview](https://developer.apple.com/sign-in-with-apple/get-started/)
+ * - Sign in with Apple [REST API](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api)
+ * - [How to retrieve](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple#3383773) the user's information from Apple ID servers
+ * - [Learn more about OAuth](https://authjs.dev/concepts/oauth)
+
+ * ## Notes
+ * 
+ * The Apple provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/apple.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * ## Help
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ */
 export default function Apple<P extends AppleProfile>(
   options: Omit<OAuthUserConfig<P>, "clientSecret"> & {
     /**

packages/core/src/providers/asgardeo.ts

@@ -1,95 +1,100 @@
 /**
- * <div style={{backgroundColor: "#24292f", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Asgardeo</b> integration.</span>
- * <a href="https://wso2.com/asgardeo/">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/asgardeo-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Asgardeo</b> integration.
+ * </span>
+ * <a href="https://wso2.com/asgardeo/" style={{backgroundColor: "#ECEFF1", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/asgardeo-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/asgardeo
  */
 
 import type { OIDCConfig, OIDCUserConfig } from "./index.js"
 
-export interface AsgardeoProfile {
+/** The returned user profile from Asgardeo when using the profile callback. */
+export interface AsgardeoProfile extends Record<string, any> {
+  /**
+   * The user Asgardeo account ID
+   */
   sub: string
+  /**
+   * The user name
+   */
   given_name: string
+  /**
+   * The user email
+   */
   email: string
+  /**
+   * The user profile picture
+   */
   picture: string
 }
 
 /**
- * Add Asgardeo login to your page.
- * ## Documentation
  *
- * https://wso2.com/asgardeo/docs/guides/authentication
+ * ## Setup
  *
+ * Import the provider and configure it in your **Auth.js** initialization file:
  *
- * ## Instructions
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AsgardeoProvider from "next-auth/providers/asgardeo";
  *
- * - Log into https://console.asgardeo.io.
- * - Next, go to "Application" tab (More info: https://wso2.com/asgardeo/docs/guides/applications/register-oidc-web-app/).
- * - Register standard based - Open id connect, application.
- * - Add callback URL: http://localhost:3000/api/auth/callback/asgardeo and https://your-domain.com/api/auth/callback/asgardeo
- * - After registering the application, go to protocol tab.
- * - Check `code` grant type.
- * - Add Authorized redirect URLs & Allowed origins fields.
- * - Make Email, First Name, Photo URL user attributes mandatory from the console.
- *
- * Create a `.env` file in the project root add the following entries:
- *
- * These values can be collected from the application created.
- *
- * ```
- * ASGARDEO_CLIENT_ID=<Copy client ID from protocol tab here>
- * ASGARDEO_CLIENT_SECRET=<Copy client from protocol tab here>
- * ASGARDEO_ISSUER=<Copy the issuer url from the info tab here>
+ * export default NextAuth({
+ *  providers: [
+ *    AsgardeoProvider({
+ *      clientId: process.env.ASGARDEO_CLIENT_ID,
+ *      clientSecret: process.env.ASGARDEO_CLIENT_SECRET,
+ *      issuer: process.env.ASGARDEO_ISSUER
+ *    }),
+ *  ],
+ * })
  * ```
  *
- * In `pages/api/auth/[...nextauth].js` find or add the `Asgardeo` entries:
+ * ### Configuring Asgardeo
  *
- * ```js
- * import Asgardeo from "next-auth/providers/asgardeo";
- * ...
- * providers: [
- *   Asgardeo({
- *     clientId: process.env.ASGARDEO_CLIENT_ID,
- *     clientSecret: process.env.ASGARDEO_CLIENT_SECRET,
- *     issuer: process.env.ASGARDEO_ISSUER
- *   }),
- * ],
+ * Follow these steps:
  *
- * ...
+ * 1. Log into the [Asgardeo console](https://console.asgardeo.io)
+ * 2. Next, go to "Application" tab (more info [here](https://wso2.com/asgardeo/docs/guides/applications/register-oidc-web-app/))
+ * 3. Register a standard based, Open ID connect, application
+ * 4. Add the **callback URLs**: `http://localhost:3000/api/auth/callback/asgardeo` (development) and `https://{YOUR_DOMAIN}.com/api/auth/callback/asgardeo` (production)
+ * 5. After registering the application, go to "Protocol" tab.
+ * 6. Check `code` as the grant type.
+ * 7. Add "Authorized redirect URLs" & "Allowed origins fields"
+ * 8. Make Email, First Name, Photo URL user attributes mandatory from the console.
+ *
+ * Then, create a `.env` file in the project root add the following entries:
+ *
+ * ```
+ * ASGARDEO_CLIENT_ID="Copy client ID from protocol tab here"
+ * ASGARDEO_CLIENT_SECRET="Copy client from protocol tab here"
+ * ASGARDEO_ISSUER="Copy the issuer url from the info tab here"
  * ```
  *
  * ## Resources
  *
- * @see [Asgardeo - Authentication Guide](https://wso2.com/asgardeo/docs/guides/authentication)
- * @see [Learn more about OAuth](https://authjs.dev/concepts/oauth)
- * @see [Source code](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts)
+ * - [Asgardeo - Authentication Guide](https://wso2.com/asgardeo/docs/guides/authentication)
+ * - [Learn more about OAuth](https://authjs.dev/concepts/oauth)
  *
  * ## Notes
  *
- * By default, Auth.js assumes that the Asgardeo provider is
- * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification.
- *
- * :::tip
- *
- * The Asgardeo provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts).
- * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ * The Asgardeo provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
  *
+ * :::info
+ * By default, Auth.js assumes that the Asgardeo provider is based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) spec
  * :::
  *
- * :::info **Disclaimer**
+ * ## Help
  *
  * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
  *
  * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
  * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
  * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
- *
- * :::
  */
 export default function Asgardeo(
   config: OIDCUserConfig<AsgardeoProfile>

packages/core/src/providers/atlassian.ts

@@ -1,12 +1,72 @@
+/**
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Atlassian</b> integration.
+ * </span>
+ * <a href="https://www.atlassian.com/" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/atlassian.svg" width="24" style={{ marginTop: "-3px"}} />
+ * </a>
+ * </div>
+ *
+ * @module providers/atlassian
+ */
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
-interface AtlassianProfile extends Record<string, any> {
+/** The returned user profile from Atlassian when using the profile callback. */
+export interface AtlassianProfile extends Record<string, any> {
+  /**
+   * The user's atlassian account ID
+   */
   account_id: string
+  /**
+   * The user name
+   */
   name: string
+  /**
+   * The user's email
+   */
   email: string
+  /**
+   * The user's profile picture
+   */
   picture: string
 }
 
+/**
+ * ## Setup
+ *
+ * Import the provider and configure it in your **Auth.js** initialization file:
+ *
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AtlassianProvider from "next-auth/providers/atlassian"
+ *
+ * export default NextAuth({
+ *   providers: [
+ *     AtlassianProvider({
+ *       clientId: process.env.ATLASSIAN_ID,
+ *       clientSecret: process.env.ATLASSIAN_SECRET,
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * ## Resources
+ *
+ * - [Atlassian docs](https://developer.atlassian.com/server/jira/platform/oauth/)
+ *
+ * ## Notes
+ *
+ * The Atlassian provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/atlassian.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * ## Help
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ */
 export default function Atlassian<P extends AtlassianProfile>(
   options: OAuthUserConfig<P>
 ): OAuthConfig<P> {

packages/core/src/providers/auth0.ts

@@ -1,19 +1,19 @@
 /**
- * <div style={{backgroundColor: "#EB5424", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Auth0</b> integration.</span>
- * <a href="https://auth0.com">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/auth0-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Auth0</b> integration.
+ * </span>
+ * <a href="https://auth0.com" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/auth0-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/auth0
  */
-
 import type { OIDCConfig, OIDCUserConfig } from "./index.js"
 
-/** @see [User Profile Structure](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure) */
-export interface Auth0Profile {
+/** The returned user profile from Auth0 when using the profile callback. [Reference](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure). */
+export interface Auth0Profile extends Record<string, any> {
   /** The user's unique identifier. */
   sub: string
   /** Custom fields that store info about a user that influences the user's access, such as support plan, security roles (if not using the Authorization Core feature set), or access control groups. To learn more, read Metadata Overview. */
@@ -75,51 +75,40 @@ export interface Auth0Profile {
 }
 
 /**
- * Add Auth0 login to your page.
+ * ## Setup
  *
- * ## Example
+ * Import the provider and configure it in your **Auth.js** initialization file:
  *
- * ```ts
- * import { Auth } from "@auth/core"
- * import Auth0 from "@auth/core/providers/auth0"
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import Auth0Provider from "next-auth/providers/auth0"
  *
- * const request = new Request("https://example.com")
- * const response = await Auth(request, {
- *   providers: [Auth0({ clientId: "", clientSecret: "", issuer: "" })],
+ * export default NextAuth({
+ *   providers: [
+ *     Auth0Provider({
+ *       clientId: process.env.AUTH0_ID,
+ *       clientSecret: process.env.AUTH0_SECRET,
+ *     }),
+ *   ],
  * })
  * ```
  *
- * ---
- *
  * ## Resources
  *
- * - [Authenticate - Auth0 docs](https://auth0.com/docs/authenticate)
- *
- * ---
+ * - [Auth0 docs](https://auth0.com/docs/authenticate)
  *
  * ## Notes
  *
- * By default, Auth.js assumes that the Auth0 provider is
- * based on the [OIDC](https://openid.net/specs/openid-connect-core-1_0.html) specification.
+ * The Auth0 provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/auth0.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
  *
- * :::tip
- *
- * The Auth0 provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/auth0.ts).
- * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
- *
- * :::
- *
- * :::info **Disclaimer**
+ * ## Help
  *
  * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
  *
  * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
  * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
  * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
- *
- * :::
  */
-
 export default function Auth0(
   config: OIDCUserConfig<Auth0Profile>
 ): OIDCConfig<Auth0Profile> {

packages/core/src/providers/index.ts

@@ -44,6 +44,12 @@ export interface CommonProviderOptions {
   type: ProviderType
 }
 
+interface InternalProviderOptions {
+  /** Used to deep merge user-provided config with the default config
+   */
+  options?: Record<string, unknown>
+}
+
 /**
  * Must be a supported authentication provider config:
  * - {@link OAuthConfig}
@@ -57,17 +63,14 @@ export interface CommonProviderOptions {
  * @see [Credentials guide](https://authjs.dev/guides/providers/credentials)
  */
 export type Provider<P extends Profile = Profile> = (
-  | OIDCConfig<P>
-  | OAuth2Config<P>
-  | EmailConfig
-  | CredentialsConfig
-) & {
-  /**
-   * Used to deep merge user-provided config with the default config
-   * @internal
-   */
-  options: Record<string, unknown>
-}
+  | ((OIDCConfig<P> | OAuth2Config<P> | EmailConfig | CredentialsConfig) &
+      InternalProviderOptions)
+  | ((
+      ...args: any
+    ) => (OAuth2Config<P> | OIDCConfig<P> | EmailConfig | CredentialsConfig) &
+      InternalProviderOptions)
+) &
+  InternalProviderOptions
 
 export type BuiltInProviders = Record<
   OAuthProviderType,

packages/core/src/providers/oauth.ts

@@ -19,7 +19,7 @@ type UrlParams = Record<string, unknown>
 
 type EndpointRequest<C, R, P> = (
   context: C & {
-    /** Provider is passed for convenience, ans also contains the `callbackUrl`. */
+    /** Provider is passed for convenience, and also contains the `callbackUrl`. */
     provider: OAuthConfigInternal<P> & {
       signinUrl: string
       callbackUrl: string
@@ -183,7 +183,6 @@ export type OAuthEndpointType = "authorization" | "token" | "userinfo"
 /**
  * We parsed `authorization`, `token` and `userinfo`
  * to always contain a valid `URL`, with the params
- * @internal
  */
 export type OAuthConfigInternal<Profile> = Omit<
   OAuthConfig<Profile>,
@@ -193,6 +192,7 @@ export type OAuthConfigInternal<Profile> = Omit<
   token?: {
     url: URL
     request?: TokenEndpointHandler["request"]
+    /** @internal */
     conform?: TokenEndpointHandler["conform"]
   }
   userinfo?: { url: URL; request?: UserinfoEndpointHandler["request"] }

packages/core/src/providers/reddit.js

@@ -7,6 +7,7 @@ export default function Reddit(options) {
     authorization: "https://www.reddit.com/api/v1/authorize?scope=identity",
     token: "https://www.reddit.com/api/v1/access_token",
     userinfo: "https://oauth.reddit.com/api/v1/me",
+    checks: ["state"],
     style: {
       logo: "/reddit.svg",
       bg: "#fff",

packages/core/src/providers/salesforce.ts

@@ -1,3 +1,48 @@
+/**
+ * Add Salesforce login to your page.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Auth } from "@auth/core"
+ * import Salesforce from "@auth/core/providers/salesforce"
+ *
+ * const request = new Request("https://example.com")
+ * const response = await AuthHandler(request, {
+ *   providers: [Salesforce({ clientId: "", clientSecret: "" })],
+ * })
+ * ```
+ *
+ * ---
+ *
+ * ## Resources
+ *
+ * - [](https://example.com)
+ *
+ * ---
+ *
+ * ## Notes
+ *
+ * By default, Auth.js assumes that the Salesforce provider is
+ * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification.
+ *
+ * :::tip
+ *
+ * The Salesforce provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/.ts).
+ * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * :::
+ *
+ * :::info **Disclaimer**
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ *
+ * :::
+ */
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
 export interface SalesforceProfile extends Record<string, any> {

packages/core/src/types.ts

@@ -121,10 +121,10 @@ export interface Account extends Partial<OpenIDTokenEndpointResponse> {
 
 /** The OAuth profile returned from your provider */
 export interface Profile {
-  sub?: string
-  name?: string
-  email?: string
-  image?: string
+  sub?: string | null
+  name?: string | null
+  email?: string | null
+  image?: string | null
 }
 
 /** [Documentation](https://authjs.dev/guides/basics/callbacks) */
@@ -406,7 +406,7 @@ export interface RequestInternal {
 
 /** @internal */
 export interface ResponseInternal<
-  Body extends string | Record<string, any> | any[] = any
+  Body extends string | Record<string, any> | any[] | null = any
 > {
   status?: number
   headers?: Headers | HeadersInit