@auth/core
Version:
Authentication for the Web.
522 lines • 21.7 kB
TypeScript
/**
*
* :::warning Experimental
* `@auth/core` is under active development.
* :::
*
* This is the main entry point to the Auth.js library.
*
* Based on the {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Request}
* and {@link https://developer.mozilla.org/en-US/docs/Web/API/Response Response} Web standard APIs.
* Primarily used to implement [framework](https://authjs.dev/getting-started/integrations)-specific packages,
* but it can also be used directly.
*
* ## Installation
*
* ```bash npm2yarn
* npm install @auth/core
* ```
*
* ## Usage
*
* ```ts
* import { Auth } from "@auth/core"
*
* const request = new Request("https://example.com")
* const response = await Auth(request, {...})
*
* console.log(response instanceof Response) // true
* ```
*
* ## Resources
*
* - [Getting started](https://authjs.dev/getting-started)
* - [Guides](https://authjs.dev/guides)
*
* @module @auth/core
*/
import { raw, skipCSRFCheck } from "./lib/index.js";
import { setEnvDefaults, createActionURL } from "./lib/utils/env.js";
import { type LoggerInstance } from "./lib/utils/logger.js";
import type { Adapter, AdapterSession, AdapterUser } from "./adapters.js";
import type { Account, Awaitable, CookiesOptions, DefaultSession, PagesOptions, Profile, ResponseInternal, Session, Theme, User } from "./types.js";
import type { CredentialInput, Provider } from "./providers/index.js";
import { JWT, JWTOptions } from "./jwt.js";
import { isAuthAction } from "./lib/utils/actions.js";
export { skipCSRFCheck, raw, setEnvDefaults, createActionURL, isAuthAction };
export declare function Auth(request: Request, config: AuthConfig & {
raw: typeof raw;
}): Promise<ResponseInternal>;
export declare function Auth(request: Request, config: Omit<AuthConfig, "raw">): Promise<Response>;
/**
* Configure the {@link Auth} method.
*
* @example
* ```ts
* import Auth, { type AuthConfig } from "@auth/core"
*
* export const authConfig: AuthConfig = {...}
*
* const request = new Request("https://example.com")
* const response = await AuthHandler(request, authConfig)
* ```
*
* @see [Initialization](https://authjs.dev/reference/core/types#authconfig)
*/
export interface AuthConfig {
/**
* List of authentication providers for signing in
* (e.g. Google, Facebook, Twitter, GitHub, Email, etc) in any order.
* This can be one of the built-in providers or an object with a custom provider.
*
* @default []
*/
providers: Provider[];
/**
* A random string used to hash tokens, sign cookies and generate cryptographic keys.
*
* To generate a random string, you can use the Auth.js CLI: `npx auth secret`
*
* @note
* You can also pass an array of secrets, in which case the first secret that successfully
* decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions.
* The newer secret should be added to the start of the array, which will be used for all new sessions.
*
*/
secret?: string | string[];
/**
* Configure your session like if you want to use JWT or a database,
* how long until an idle session expires, or to throttle write operations in case you are using a database.
*/
session?: {
/**
* Choose how you want to save the user session.
* The default is `"jwt"`, an encrypted JWT (JWE) in the session cookie.
*
* If you use an `adapter` however, we default it to `"database"` instead.
* You can still force a JWT session by explicitly defining `"jwt"`.
*
* When using `"database"`, the session cookie will only contain a `sessionToken` value,
* which is used to look up the session in the database.
*
* [Documentation](https://authjs.dev/reference/core#authconfig#session) | [Adapter](https://authjs.dev/reference/core#authconfig#adapter) | [About JSON Web Tokens](https://authjs.dev/concepts/session-strategies#jwt-session)
*/
strategy?: "jwt" | "database";
/**
* Relative time from now in seconds when to expire the session
*
* @default 2592000 // 30 days
*/
maxAge?: number;
/**
* How often the session should be updated in seconds.
* If set to `0`, session is updated every time.
*
* @default 86400 // 1 day
*/
updateAge?: number;
/**
* Generate a custom session token for database-based sessions.
* By default, a random UUID or string is generated depending on the Node.js version.
* However, you can specify your own custom string (such as CUID) to be used.
*
* @default `randomUUID` or `randomBytes.toHex` depending on the Node.js version
*/
generateSessionToken?: () => string;
};
/**
* JSON Web Tokens are enabled by default if you have not specified an {@link AuthConfig.adapter}.
* JSON Web Tokens are encrypted (JWE) by default. We recommend you keep this behaviour.
*/
jwt?: Partial<JWTOptions>;
/**
* Specify URLs to be used if you want to create custom sign in, sign out and error pages.
* Pages specified will override the corresponding built-in page.
*
* @default {}
* @example
*
* ```ts
* pages: {
* signIn: '/auth/signin',
* signOut: '/auth/signout',
* error: '/auth/error',
* verifyRequest: '/auth/verify-request',
* newUser: '/auth/new-user'
* }
* ```
*/
pages?: Partial<PagesOptions>;
/**
* Callbacks are asynchronous functions you can use to control what happens when an action is performed.
* Callbacks are *extremely powerful*, especially in scenarios involving JSON Web Tokens
* as they **allow you to implement access controls without a database** and to **integrate with external databases or APIs**.
*/
callbacks?: {
/**
* Controls whether a user is allowed to sign in or not.
* Returning `true` continues the sign-in flow.
* Returning `false` or throwing an error will stop the sign-in flow and redirect the user to the error page.
* Returning a string will redirect the user to the specified URL.
*
* Unhandled errors will throw an `AccessDenied` with the message set to the original error.
*
* [`AccessDenied`](https://authjs.dev/reference/core/errors#accessdenied)
*
* @example
* ```ts
* callbacks: {
* async signIn({ profile }) {
* // Only allow sign in for users with email addresses ending with "yourdomain.com"
* return profile?.email?.endsWith("@yourdomain.com")
* }
* ```
*/
signIn?: (params: {
user: User | AdapterUser;
account: Account | null;
/**
* If OAuth provider is used, it contains the full
* OAuth profile returned by your provider.
*/
profile?: Profile;
/**
* If Email provider is used, on the first call, it contains a
* `verificationRequest: true` property to indicate it is being triggered in the verification request flow.
* When the callback is invoked after a user has clicked on a sign in link,
* this property will not be present. You can check for the `verificationRequest` property
* to avoid sending emails to addresses or domains on a blocklist or to only explicitly generate them
* for email address in an allow list.
*/
email?: {
verificationRequest?: boolean;
};
/** If Credentials provider is used, it contains the user credentials */
credentials?: Record<string, CredentialInput>;
}) => Awaitable<boolean | string>;
/**
* This callback is called anytime the user is redirected to a callback URL (i.e. on signin or signout).
* By default only URLs on the same host as the origin are allowed.
* You can use this callback to customise that behaviour.
*
* [Documentation](https://authjs.dev/reference/core/types#redirect)
*
* @example
* callbacks: {
* async redirect({ url, baseUrl }) {
* // Allows relative callback URLs
* if (url.startsWith("/")) return `${baseUrl}${url}`
*
* // Allows callback URLs on the same origin
* if (new URL(url).origin === baseUrl) return url
*
* return baseUrl
* }
* }
*/
redirect?: (params: {
/** URL provided as callback URL by the client */
url: string;
/** Default base URL of site (can be used as fallback) */
baseUrl: string;
}) => Awaitable<string>;
/**
* This callback is called whenever a session is checked.
* (i.e. when invoking the `/api/session` endpoint, using `useSession` or `getSession`).
* The return value will be exposed to the client, so be careful what you return here!
* If you want to make anything available to the client which you've added to the token
* through the JWT callback, you have to explicitly return it here as well.
*
* :::note
* ⚠ By default, only a subset (email, name, image)
* of the token is returned for increased security.
* :::
*
* The token argument is only available when using the jwt session strategy, and the
* user argument is only available when using the database session strategy.
*
* [`jwt` callback](https://authjs.dev/reference/core/types#jwt)
*
* @example
* ```ts
* callbacks: {
* async session({ session, token, user }) {
* // Send properties to the client, like an access_token from a provider.
* session.accessToken = token.accessToken
*
* return session
* }
* }
* ```
*/
session?: (params: ({
session: {
user: AdapterUser;
} & AdapterSession;
/** Available when {@link AuthConfig.session} is set to `strategy: "database"`. */
user: AdapterUser;
} & {
session: Session;
/** Available when {@link AuthConfig.session} is set to `strategy: "jwt"` */
token: JWT;
}) & {
/**
* Available when using {@link AuthConfig.session} `strategy: "database"` and an update is triggered for the session.
*
* :::note
* You should validate this data before using it.
* :::
*/
newSession: any;
trigger?: "update";
}) => Awaitable<Session | DefaultSession>;
/**
* This callback is called whenever a JSON Web Token is created (i.e. at sign in)
* or updated (i.e whenever a session is accessed in the client). Anything you
* return here will be saved in the JWT and forwarded to the session callback.
* There you can control what should be returned to the client. Anything else
* will be kept from your frontend. The JWT is encrypted by default via your
* AUTH_SECRET environment variable.
*
* [`session` callback](https://authjs.dev/reference/core/types#session)
*/
jwt?: (params: {
/**
* When `trigger` is `"signIn"` or `"signUp"`, it will be a subset of {@link JWT},
* `name`, `email` and `image` will be included.
*
* Otherwise, it will be the full {@link JWT} for subsequent calls.
*/
token: JWT;
/**
* Either the result of the {@link OAuthConfig.profile} or the {@link CredentialsConfig.authorize} callback.
* @note available when `trigger` is `"signIn"` or `"signUp"`.
*
* Resources:
* - [Credentials Provider](https://authjs.dev/getting-started/authentication/credentials)
* - [User database model](https://authjs.dev/guides/creating-a-database-adapter#user-management)
*/
user: User | AdapterUser;
/**
* Contains information about the provider that was used to sign in.
* Also includes {@link TokenSet}
* @note available when `trigger` is `"signIn"` or `"signUp"`
*/
account: Account | null;
/**
* The OAuth profile returned from your provider.
* (In case of OIDC it will be the decoded ID Token or /userinfo response)
* @note available when `trigger` is `"signIn"`.
*/
profile?: Profile;
/**
* Check why was the jwt callback invoked. Possible reasons are:
* - user sign-in: First time the callback is invoked, `user`, `profile` and `account` will be present.
* - user sign-up: a user is created for the first time in the database (when {@link AuthConfig.session}.strategy is set to `"database"`)
* - update event: Triggered by the `useSession().update` method.
* In case of the latter, `trigger` will be `undefined`.
*/
trigger?: "signIn" | "signUp" | "update";
/** @deprecated use `trigger === "signUp"` instead */
isNewUser?: boolean;
/**
* When using {@link AuthConfig.session} `strategy: "jwt"`, this is the data
* sent from the client via the `useSession().update` method.
*
* ⚠ Note, you should validate this data before using it.
*/
session?: any;
}) => Awaitable<JWT | null>;
};
/**
* Events are asynchronous functions that do not return a response, they are useful for audit logging.
* You can specify a handler for any of these events below - e.g. for debugging or to create an audit log.
* The content of the message object varies depending on the flow
* (e.g. OAuth or Email authentication flow, JWT or database sessions, etc),
* but typically contains a user object and/or contents of the JSON Web Token
* and other information relevant to the event.
*
* @default {}
*/
events?: {
/**
* If using a `credentials` type auth, the user is the raw response from your
* credential provider.
* For other providers, you'll get the User object from your adapter, the account,
* and an indicator if the user was new to your Adapter.
*/
signIn?: (message: {
user: User;
account: Account | null;
profile?: Profile;
isNewUser?: boolean;
}) => Awaitable<void>;
/**
* The message object will contain one of these depending on
* if you use JWT or database persisted sessions:
* - `token`: The JWT for this session.
* - `session`: The session object from your adapter that is being ended.
*/
signOut?: (message: {
session: Awaited<ReturnType<Required<Adapter>["deleteSession"]>>;
} | {
token: Awaited<ReturnType<JWTOptions["decode"]>>;
}) => Awaitable<void>;
createUser?: (message: {
user: User;
}) => Awaitable<void>;
updateUser?: (message: {
user: User;
}) => Awaitable<void>;
linkAccount?: (message: {
user: User | AdapterUser;
account: Account;
profile: User | AdapterUser;
}) => Awaitable<void>;
/**
* The message object will contain one of these depending on
* if you use JWT or database persisted sessions:
* - `token`: The JWT for this session.
* - `session`: The session object from your adapter.
*/
session?: (message: {
session: Session;
token: JWT;
}) => Awaitable<void>;
};
/** You can use the adapter option to pass in your database adapter. */
adapter?: Adapter;
/**
* Set debug to true to enable debug messages for authentication and database operations.
*
* - ⚠ If you added a custom {@link AuthConfig.logger}, this setting is ignored.
*
* @default false
*/
debug?: boolean;
/**
* Override any of the logger levels (`undefined` levels will use the built-in logger),
* and intercept logs in NextAuth. You can use this option to send NextAuth logs to a third-party logging service.
*
* @example
*
* ```ts
* // /auth.ts
* import log from "logging-service"
*
* export const { handlers, auth, signIn, signOut } = NextAuth({
* logger: {
* error(code, ...message) {
* log.error(code, message)
* },
* warn(code, ...message) {
* log.warn(code, message)
* },
* debug(code, ...message) {
* log.debug(code, message)
* }
* }
* })
* ```
*
* - ⚠ When set, the {@link AuthConfig.debug} option is ignored
*
* @default console
*/
logger?: Partial<LoggerInstance>;
/** Changes the theme of built-in {@link AuthConfig.pages}. */
theme?: Theme;
/**
* When set to `true` then all cookies set by NextAuth.js will only be accessible from HTTPS URLs.
* This option defaults to `false` on URLs that start with `http://` (e.g. http://localhost:3000) for developer convenience.
* You can manually set this option to `false` to disable this security feature and allow cookies
* to be accessible from non-secured URLs (this is not recommended).
*
* - ⚠ **This is an advanced option.** Advanced options are passed the same way as basic options,
* but **may have complex implications** or side effects.
* You should **try to avoid using advanced options** unless you are very comfortable using them.
*
* The default is `false` HTTP and `true` for HTTPS sites.
*/
useSecureCookies?: boolean;
/**
* You can override the default cookie names and options for any of the cookies used by Auth.js.
* You can specify one or more cookies with custom properties
* and missing options will use the default values defined by Auth.js.
* If you use this feature, you will likely want to create conditional behavior
* to support setting different cookies policies in development and production builds,
* as you will be opting out of the built-in dynamic policy.
*
* - ⚠ **This is an advanced option.** Advanced options are passed the same way as basic options,
* but **may have complex implications** or side effects.
* You should **try to avoid using advanced options** unless you are very comfortable using them.
*
* @default {}
*/
cookies?: Partial<CookiesOptions>;
/**
* Auth.js relies on the incoming request's `host` header to function correctly. For this reason this property needs to be set to `true`.
*
* Make sure that your deployment platform sets the `host` header safely.
*
* :::note
* Official Auth.js-based libraries will attempt to set this value automatically for some deployment platforms (eg.: Vercel) that are known to set the `host` header safely.
* :::
*/
trustHost?: boolean;
skipCSRFCheck?: typeof skipCSRFCheck;
raw?: typeof raw;
/**
* When set, during an OAuth sign-in flow,
* the `redirect_uri` of the authorization request
* will be set based on this value.
*
* This is useful if your OAuth Provider only supports a single `redirect_uri`
* or you want to use OAuth on preview URLs (like Vercel), where you don't know the final deployment URL beforehand.
*
* The url needs to include the full path up to where Auth.js is initialized.
*
* @note This will auto-enable the `state` {@link OAuth2Config.checks} on the provider.
*
* @example
* ```
* "https://authjs.example.com/api/auth"
* ```
*
* You can also override this individually for each provider.
*
* @example
* ```ts
* GitHub({
* ...
* redirectProxyUrl: "https://github.example.com/api/auth"
* })
* ```
*
* @default `AUTH_REDIRECT_PROXY_URL` environment variable
*
* See also: [Guide: Securing a Preview Deployment](https://authjs.dev/getting-started/deployment#securing-a-preview-deployment)
*/
redirectProxyUrl?: string;
/**
* Use this option to enable experimental features.
* When enabled, it will print a warning message to the console.
* @note Experimental features are not guaranteed to be stable and may change or be removed without notice. Please use with caution.
* @default {}
*/
experimental?: {
/**
* Enable WebAuthn support.
*
* @default false
*/
enableWebAuthn?: boolean;
};
/**
* The base path of the Auth.js API endpoints.
*
* @default "/api/auth" in "next-auth"; "/auth" with all other frameworks
*/
basePath?: string;
}
//# sourceMappingURL=index.d.ts.map