@auth0/auth0-server-js 1.6.1 → 1.7.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { ExchangeProfileOptions, AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, TokenResponse } from '@auth0/auth0-auth-js';
-export { ActClaim, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OtpEnrollmentResponse, TelemetryConfig, TokenExchangeError, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, ExchangeProfileOptions, DiscoveryCacheOptions, TelemetryConfig, AuthClient, ListAuthenticatorsOptions, AuthenticatorResponse, EnrollAuthenticatorOptions, EnrollmentResponse, ChallengeOptions, ChallengeResponse, MfaVerifyOptions, PasskeySignupChallengeOptions, PasskeySignupChallengeResponse, PasskeyLoginChallengeOptions, PasskeyLoginChallengeResponse, GetTokenByPasskeyOptions, TokenResponse } from '@auth0/auth0-auth-js';
+export { ActClaim, AuthenticatorResponse, AuthenticatorType, ChallengeOptions, ChallengeResponse, DiscoveryCacheOptions, EnrollAuthenticatorOptions, EnrollEmailOptions, EnrollOobOptions, EnrollOtpOptions, EnrollmentResponse, ListAuthenticatorsOptions, MfaChallengeError, MfaEnrollmentError, MfaFactorType, MfaListAuthenticatorsError, MfaRequirements, MfaVerifyError, MfaVerifyOobOptions, MfaVerifyOptions, MfaVerifyOtpOptions, MfaVerifyRecoveryCodeOptions, MissingClientAuthError, OobChannel, OobEnrollmentResponse, OrganizationValidationError, OtpEnrollmentResponse, PasskeyChallengeError, PasskeyLoginChallengeOptions as PasskeyChallengeOptions, PasskeyLoginChallengeResponse as PasskeyChallengeResponse, PasskeyCreationOptions, PasskeyCredentialResponse, PasskeyGetTokenError, GetTokenByPasskeyOptions as PasskeyGetTokenOptions, PasskeyRegisterError, PasskeySignupChallengeOptions as PasskeyRegisterOptions, PasskeySignupChallengeResponse as PasskeyRegisterResponse, PasskeyRequestOptions, TelemetryConfig, TokenExchangeError, TokenResponse, isMfaRequiredError } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
 /**
@@ -96,7 +96,12 @@ interface SessionData {
 }
 interface TransactionData {
     audience?: string;
-    codeVerifier: string;
+    /**
+     * PKCE code verifier for interactive (authorization-code) logins. Optional because
+     * magic-link transactions are bound by anti-forgery `state` only and register no PKCE
+     * challenge, so they persist no verifier.
+     */
+    codeVerifier?: string;
     domain?: string;
     [key: string]: unknown;
 }
@@ -143,6 +148,126 @@ interface LoginBackchannelOptions {
 interface LoginBackchannelResult {
     authorizationDetails?: AuthorizationDetails[];
 }
+/**
+ *  Result of completing a passkey authentication flow (signup or login).
+ */
+interface PasskeyGetTokenResult {
+    authorizationDetails?: AuthorizationDetails[];
+}
+/**
+ * Options for starting an email passwordless flow by sending a one-time code (OTP).
+ *
+ * Complete it with {@link ServerClient#loginWithPasswordless}.
+ */
+interface StartPasswordlessEmailCodeOptions {
+    /** Discriminator: email connection. */
+    connection: 'email';
+    /** The destination email address. */
+    email: string;
+    /** Send a one-time code. Optional; this is the default for the email connection. */
+    send?: 'code';
+    /**
+     * BCP-47 language tag forwarded as `x-request-language` to localize the email template.
+     */
+    language?: string;
+}
+/**
+ * Options for starting an email passwordless magic-link flow.
+ *
+ * The SDK generates and persists an anti-forgery `state`, sends the link, and validates
+ * `state` on the callback. No PKCE is used. Complete it with
+ * {@link ServerClient#completePasswordlessMagicLink}.
+ */
+interface StartPasswordlessEmailLinkOptions {
+    /** Discriminator: email connection. */
+    connection: 'email';
+    /** The destination email address. */
+    email: string;
+    /** Send a magic link. Required literal to select link mode. */
+    send: 'link';
+    /**
+     * The callback URL Auth0 redirects to after the magic link is clicked. Embedded in the link
+     * as `redirect_uri`; must be registered on the application.
+     */
+    redirectUri: string;
+    /**
+     * Additional OAuth authorization parameters merged into the link. `client_id`, `response_type`,
+     * and `state` are set by the SDK and cannot be overridden.
+     */
+    authParams?: Record<string, unknown>;
+    /**
+     * Scope for the resulting tokens. `openid` is ensured. Include `offline_access` for a refresh token.
+     */
+    scope?: string;
+    /**
+     * Audience for the resulting access token.
+     */
+    audience?: string;
+    /**
+     * BCP-47 language tag forwarded as `x-request-language` to localize the email template.
+     */
+    language?: string;
+}
+/**
+ * Options for starting an SMS passwordless flow (one-time code only; SMS has no magic link).
+ *
+ * Complete it with {@link ServerClient#loginWithPasswordless}.
+ */
+interface StartPasswordlessSmsOptions {
+    /** Discriminator: sms connection. */
+    connection: 'sms';
+    /** Phone number in E.164 format, e.g. `+14155550100`. */
+    phoneNumber: string;
+    /**
+     * BCP-47 language tag forwarded as `x-request-language` to localize the SMS template.
+     */
+    language?: string;
+}
+/**
+ * Options for starting a passwordless flow. Discriminated on `connection` (and, for email,
+ * on `send`) to mirror the `@auth0/nextjs-auth0` `passwordless.start()` surface.
+ *
+ * - `{ connection: 'email', send?: 'code' }` — email OTP (default)
+ * - `{ connection: 'email', send: 'link', redirectUri }` — email magic link
+ * - `{ connection: 'sms' }` — SMS OTP
+ */
+type StartPasswordlessOptions = StartPasswordlessEmailCodeOptions | StartPasswordlessEmailLinkOptions | StartPasswordlessSmsOptions;
+/**
+ * Options for completing an email passwordless OTP login and establishing a session.
+ */
+interface CompletePasswordlessEmailOptions {
+    /** Discriminator: email connection. */
+    connection: 'email';
+    /** The email address the code was sent to. */
+    email: string;
+    /** The one-time code entered by the user. */
+    verificationCode: string;
+    authorizationParams?: AuthorizationParameters;
+}
+/**
+ * Options for completing an SMS passwordless OTP login and establishing a session.
+ */
+interface CompletePasswordlessSmsOptions {
+    /** Discriminator: sms connection. */
+    connection: 'sms';
+    /** The phone number the code was sent to, in E.164 format. */
+    phoneNumber: string;
+    /** The one-time code entered by the user. */
+    verificationCode: string;
+    authorizationParams?: AuthorizationParameters;
+}
+/**
+ * Options for completing a passwordless OTP login. Discriminated on `connection` to mirror the
+ * `@auth0/nextjs-auth0` `passwordless.verify()` surface.
+ */
+type CompletePasswordlessOptions = CompletePasswordlessEmailOptions | CompletePasswordlessSmsOptions;
+/**
+ * Result of a passwordless login (OTP or magic link). The session is persisted to the state
+ * store; `authorizationDetails` is included when Rich Authorization Requests (RAR) were used.
+ */
+interface CompletePasswordlessResult {
+    authorizationDetails?: AuthorizationDetails[];
+}
 interface AccessTokenForConnectionOptions {
     connection: string;
     loginHint?: string;
@@ -355,6 +480,89 @@ declare class ServerMfaClient<TStoreOptions = unknown> {
     verify(options: MfaVerifyOptions, storeOptions?: TStoreOptions): Promise<MfaVerifyResponse>;
 }
 
+/**
+ * @internal
+ * Options for constructing a ServerPasskeyClient.
+ *
+ * Unlike the MFA client, the passkey client resolves the domain per call so it
+ * keeps working in resolver (multi-tenant) mode. It therefore receives the
+ * parent client's `resolveDomain` and `getAuthClient` helpers instead of a
+ * fixed domain/authClient.
+ */
+interface ServerPasskeyClientOptions<TStoreOptions = unknown> {
+    resolveDomain: (storeOptions?: TStoreOptions) => Promise<string>;
+    getAuthClient: (domain: string) => AuthClient;
+    stateStore: StateStore<TStoreOptions>;
+    stateStoreIdentifier: string;
+    defaultScope?: string;
+    defaultAudience?: string;
+}
+
+declare class ServerPasskeyClient<TStoreOptions = unknown> {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(options: ServerPasskeyClientOptions<TStoreOptions>);
+    /**
+     * Requests a passkey signup challenge for a new user.
+     *
+     * Returns the `authSession` and the WebAuthn credential creation options
+     * (`authnParamsPublicKey`). The application must return these to the browser,
+     * pass `authnParamsPublicKey` to `navigator.credentials.create()`, and then
+     * call `getToken()` with the resulting credential to complete signup.
+     *
+     * This method does not create a session; no state is persisted.
+     *
+     * @param options User profile data and optional realm/organization.
+     * @param storeOptions Optional options used to resolve the domain (resolver mode).
+     *
+     * @throws {PasskeyRegisterError} If there was an issue requesting the signup challenge.
+     *
+     * @returns A promise resolving to the signup challenge.
+     */
+    register(options: PasskeySignupChallengeOptions, storeOptions?: TStoreOptions): Promise<PasskeySignupChallengeResponse>;
+    /**
+     * Requests a passkey login challenge for an existing user.
+     *
+     * Returns the `authSession` and the WebAuthn credential request options
+     * (`authnParamsPublicKey`). The application must return these to the browser,
+     * pass `authnParamsPublicKey` to `navigator.credentials.get()`, and then
+     * call `getToken()` with the resulting credential to complete login.
+     *
+     * This method does not create a session; no state is persisted.
+     *
+     * @param options Optional realm/organization configuration.
+     * @param storeOptions Optional options used to resolve the domain (resolver mode).
+     *
+     * @throws {PasskeyChallengeError} If there was an issue requesting the login challenge.
+     *
+     * @returns A promise resolving to the login challenge.
+     */
+    challenge(options?: PasskeyLoginChallengeOptions, storeOptions?: TStoreOptions): Promise<PasskeyLoginChallengeResponse>;
+    /**
+     * Completes a passkey authentication flow (signup or login) by exchanging the
+     * WebAuthn credential for tokens, and persists the resulting session.
+     *
+     * Call this after obtaining a credential from `navigator.credentials.create()`
+     * (signup) or `navigator.credentials.get()` (login), passing the `authSession`
+     * returned by `register()` / `challenge()` together with the serialized credential.
+     *
+     * In resolver (multi-tenant) mode, pass the same `storeOptions` you passed to
+     * `register()` / `challenge()` so the token exchange resolves the same tenant
+     * that issued the `authSession`; otherwise the exchange will fail.
+     *
+     * @param options The auth session, serialized credential, and optional realm/scope/audience/organization.
+     * @param storeOptions Optional options used to pass to the State Store (and to resolve the domain in resolver mode).
+     *
+     * @throws {PasskeyGetTokenError} If there was an issue exchanging the credential for tokens. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`. No session is persisted in this case.
+     * @throws {OrganizationValidationError} When `organization` is passed and the returned ID token's organization claim is missing or does not match. The error is thrown before the session is written, so no session is persisted in this case.
+     *
+     * @returns A promise resolving to an object containing the authorizationDetails (when RAR was used).
+     */
+    getToken(options: GetTokenByPasskeyOptions, storeOptions?: TStoreOptions): Promise<PasskeyGetTokenResult>;
+}
+
 declare class ServerClient<TStoreOptions = unknown> {
     #private;
     /**
@@ -381,6 +589,17 @@ declare class ServerClient<TStoreOptions = unknown> {
      * In resolver mode (`domain` as a function), MFA is not supported.
      */
     get mfa(): ServerMfaClient<TStoreOptions>;
+    /**
+     * The passkey client for signing up and logging in users with WebAuthn credentials.
+     *
+     * Provides `register()` and `challenge()` to request signup/login challenges, and
+     * `getToken()` to exchange the resulting credential for tokens and persist the session.
+     *
+     * Unlike `mfa`, this property is available in both static and resolver (multi-tenant)
+     * domain modes. In resolver mode, pass the same `storeOptions` to `register()`/`challenge()`
+     * and `getToken()` so the credential is exchanged against the tenant that issued it.
+     */
+    get passkey(): ServerPasskeyClient<TStoreOptions>;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
@@ -470,6 +689,86 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns A promise resolving to an object, containing the authorizationDetails (when RAR was used).
      */
     loginBackchannel(options: LoginBackchannelOptions, storeOptions?: TStoreOptions): Promise<LoginBackchannelResult>;
+    /**
+     * Starts a passwordless flow by sending a one-time code (OTP) or a magic link.
+     *
+     * Discriminated on `connection` (and, for email, `send`) to mirror the
+     * `@auth0/nextjs-auth0` `passwordless.start()` surface:
+     * - `{ connection: 'email' }` / `{ connection: 'email', send: 'code' }` — email OTP
+     * - `{ connection: 'email', send: 'link', redirectUri }` — email magic link
+     * - `{ connection: 'sms' }` — SMS OTP
+     *
+     * OTP modes are a stateless passthrough to the Authentication API (no session, no transaction);
+     * complete them with {@link ServerClient#completePasswordless}.
+     *
+     * Magic-link mode is stateful: the SDK generates an opaque anti-forgery `state`, sends the link
+     * with the OAuth parameters embedded (`redirect_uri`, `response_type=code`, `scope`, `state`),
+     * and persists a transaction carrying that `state`. NO PKCE challenge is registered, so the
+     * transaction holds no `codeVerifier`. Complete it with
+     * {@link ServerClient#completePasswordlessMagicLink}. Requires the tenant setting
+     * `allow_magiclink_verify_without_session: true` for server-side completion.
+     *
+     * @param options Discriminated start options.
+     * @param storeOptions Optional options passed to the resolver / stores.
+     *
+     * @throws {PasswordlessStartError} If the request fails, or if a magic link is requested without a `redirectUri`.
+     *
+     * @example
+     * // Email OTP
+     * await serverClient.startPasswordless({ connection: 'email', email: 'user@example.com' });
+     * // SMS OTP
+     * await serverClient.startPasswordless({ connection: 'sms', phoneNumber: '+14155550100' });
+     * // Email magic link
+     * await serverClient.startPasswordless({
+     *   connection: 'email',
+     *   email: 'user@example.com',
+     *   send: 'link',
+     *   redirectUri: 'https://app.example.com/auth/callback',
+     * });
+     */
+    startPasswordless(options: StartPasswordlessOptions, storeOptions?: TStoreOptions): Promise<void>;
+    /**
+     * Completes a passwordless OTP login and persists the resulting session.
+     *
+     * Discriminated on `connection` to mirror the `@auth0/nextjs-auth0` `passwordless.verify()`
+     * surface. Non-redirect flow: no PKCE and no transaction store (mirrors
+     * {@link ServerClient#loginBackchannel}). The `openid` scope is always ensured by this layer.
+     *
+     * Note: the state store is read-then-written; if your deployment performs concurrent
+     * logins for the same session identifier, use a state store with atomic/serializable
+     * writes to avoid last-write-wins races.
+     *
+     * @param options Discriminated completion options (`connection`, identifier, `verificationCode`).
+     * @param storeOptions Optional options passed to the resolver / stores.
+     *
+     * @throws {PasswordlessVerifyError} If the code is invalid, expired, or rate-limited. When the
+     *   connection requires MFA, the server responds with `mfa_required`; narrow the thrown error
+     *   with `isMfaRequiredError(error)` to read `cause.mfa_token`.
+     *
+     * @returns A promise resolving to the authorizationDetails (when RAR was used).
+     */
+    completePasswordless(options: CompletePasswordlessOptions, storeOptions?: TStoreOptions): Promise<CompletePasswordlessResult>;
+    /**
+     * Completes a passwordless magic-link login and persists the resulting session.
+     *
+     * Loads the transaction persisted by {@link ServerClient#startPasswordless} (magic-link mode), validates the
+     * `state` returned on the callback URL against the stored `state` (anti-forgery binding), exchanges
+     * the authorization code WITHOUT PKCE, writes the session, and deletes the transaction. The existing
+     * interactive login path ({@link ServerClient#completeInteractiveLogin}) is not used.
+     *
+     * @param url The callback URL containing the authorization `code` and `state`.
+     * @param storeOptions Optional options passed to the resolver / stores.
+     *
+     * @throws {MissingTransactionError} If no magic-link transaction was found.
+     * @throws {PasswordlessVerifyError} If the returned `state` is missing or does not match.
+     * @throws {TokenByCodeError} If the token exchange fails.
+     *
+     * @returns A promise resolving to the authorizationDetails (when RAR was used).
+     *
+     * @example
+     * const result = await serverClient.completePasswordlessMagicLink(callbackUrl, storeOptions);
+     */
+    completePasswordlessMagicLink(url: URL, storeOptions?: TStoreOptions): Promise<CompletePasswordlessResult>;
     /**
      * Retrieves the user from the store, or undefined if no user found.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
@@ -482,16 +781,8 @@ declare class ServerClient<TStoreOptions = unknown> {
      * @returns The session or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
-    /**
-     * Retrieves the access token from the store, or calls Auth0 when the access token is expired and a refresh token is available in the store.
-     * Also updates the store when a new token was retrieved from Auth0.
-     * @param storeOptions Optional options used to pass to the Transaction and State Store.
-     *
-     * @throws {TokenByRefreshTokenError} If the refresh token was not found or there was an issue requesting the access token. When the cause is `mfa_required`, use `isMfaRequiredError(error)` to narrow the error and read `cause.mfa_token`.
-     *
-     * @returns The Token Set, containing the access token, as well as additional information.
-     */
     getAccessToken(storeOptions?: TStoreOptions): Promise<TokenSet>;
+    getAccessToken(options: GetAccessTokenOptions, storeOptions?: TStoreOptions): Promise<TokenSet>;
     /**
      * Retrieves an access token for a connection.
      *
@@ -740,4 +1031,4 @@ declare class IssuerValidationError extends Error {
     constructor(message: string);
 }
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, ServerMfaClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };
+export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type CompletePasswordlessEmailOptions, type CompletePasswordlessOptions, type CompletePasswordlessResult, type CompletePasswordlessSmsOptions, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type CustomTokenExchangeOptions, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LoginWithCustomTokenExchangeOptions, type LoginWithCustomTokenExchangeResult, type LogoutOptions, type LogoutTokenClaims, type MfaVerifyResponse, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, type PasskeyGetTokenResult, ServerClient, type ServerClientOptions, ServerMfaClient, ServerPasskeyClient, type SessionConfiguration, type SessionCookieOptions, type SessionData, type SessionStore, type StartInteractiveLoginOptions, StartLinkUserError, type StartLinkUserOptions, type StartPasswordlessEmailCodeOptions, type StartPasswordlessEmailLinkOptions, type StartPasswordlessOptions, type StartPasswordlessSmsOptions, type StartUnlinkUserOptions, type StateData, type StateStore, StatefulStateStore, type StatefulStateStoreOptions, StatelessStateStore, type TokenSet, type TransactionData, type TransactionStore, type UserClaims };