@auth0/auth0-server-js 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1,13 +1,32 @@
-import { AuthorizationDetails, AuthClient } from '@auth0/auth0-auth-js';
+import { AuthorizationDetails, DiscoveryCacheOptions, TelemetryConfig, AuthClient } from '@auth0/auth0-auth-js';
+export { DiscoveryCacheOptions, TelemetryConfig } from '@auth0/auth0-auth-js';
 import { JWTPayload } from 'jose';
 
+/**
+ * Resolves the Auth0 custom domain at runtime using request-specific context.
+ *
+ * Should return a custom domain hostname (for example,
+ * `brand-1.custom-domain.com`) without protocol.
+ *
+ * The resolver receives a context object from SDK method calls (typically
+ * the same `storeOptions` object passed by the application).
+ * Resolved custom domains must be trusted and must belong to the same Auth0 tenant.
+ * Do not derive the returned domain directly from untrusted request input.
+ *
+ * The resolver must return a non-empty domain string. If it returns `null`,
+ * `undefined`, or an empty string at runtime, the SDK throws
+ * `InvalidConfigurationError`.
+ */
+type DomainResolver<TStoreOptions> = (context?: TStoreOptions) => Promise<string> | string;
+
 interface ServerClientOptions<TStoreOptions = unknown> {
-    domain: string;
+    domain: string | DomainResolver<TStoreOptions>;
     clientId: string;
     clientSecret?: string;
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
     /**
@@ -22,6 +41,11 @@ interface ServerClientOptions<TStoreOptions = unknown> {
      * When set to `true`, using a `customFetch` is required.
      */
     useMtls?: boolean;
+    /**
+     * Optional telemetry configuration.
+     * Telemetry is enabled by default and sends the Auth0-Client header with package name and version.
+     */
+    telemetry?: TelemetryConfig;
 }
 interface UserClaims {
     sub: string;
@@ -67,11 +91,13 @@ interface SessionData {
     refreshToken: string | undefined;
     tokenSets: TokenSet[];
     connectionTokenSets?: ConnectionTokenSet[];
+    domain?: string;
     [key: string]: unknown;
 }
 interface TransactionData {
     audience?: string;
     codeVerifier: string;
+    domain?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -79,9 +105,16 @@ interface AbstractDataStore<TData, TStoreOptions = unknown> {
     get(identifier: string, options?: TStoreOptions): Promise<TData | undefined>;
     delete(identifier: string, options?: TStoreOptions): Promise<void>;
 }
+/**
+ * Claims used to identify sessions for Backchannel Logout.
+ *
+ * `iss` is optional for backward compatibility, but is included by resolver-mode
+ * implementations to disambiguate sessions across multiple issuers/domains.
+ */
 type LogoutTokenClaims = {
     sub?: string;
     sid?: string;
+    iss?: string;
 };
 interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateData, TStoreOptions> {
     deleteByLogoutToken(claims: LogoutTokenClaims, options?: TStoreOptions): Promise<void>;
@@ -89,7 +122,11 @@ interface StateStore<TStoreOptions = unknown> extends AbstractDataStore<StateDat
 interface TransactionStore<TStoreOptions = unknown> extends AbstractDataStore<TransactionData, TStoreOptions> {
 }
 interface EncryptedStoreOptions {
-    secret: string;
+    /**
+     * The secret(s) to use for encryption and decryption. Can be a single string or an array of strings for secret rotation support.
+     * When using an array of secrets, the first one is used for encryption, while all secrets are tried, in-order, for decryption.
+     */
+    secret: string | string[];
 }
 interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
@@ -110,6 +147,25 @@ interface AccessTokenForConnectionOptions {
     connection: string;
     loginHint?: string;
 }
+/**
+ * Options for retrieving an access token with MRRT support.
+ * Allows requesting tokens for specific audiences and scopes at runtime.
+ */
+interface GetAccessTokenOptions {
+    /**
+     * Optional audience for the requested access token.
+     * If not provided, falls back to configuration audience or 'default'.
+     * @example 'https://api.example.com'
+     */
+    audience?: string;
+    /**
+     * Optional scope for the requested access token.
+     * If not provided, falls back to configuration scope.
+     * Space-separated scope string.
+     * @example 'read:data write:data'
+     */
+    scope?: string;
+}
 interface LogoutOptions {
     returnTo: string;
 }
@@ -173,7 +229,7 @@ interface SessionCookieOptions {
      *
      * Default: `lax`.
      */
-    sameSite?: "strict" | "lax" | "none";
+    sameSite?: 'strict' | 'lax' | 'none';
     /**
      * The secure attribute of the session cookie.
      *
@@ -202,9 +258,13 @@ declare class ServerClient<TStoreOptions = unknown> {
      * The underlying `authClient` instance that can be used to interact with the Auth0 Authentication API.
      * Generally, you should prefer to use the higher-level methods exposed on the `ServerClient` instance.
      *
+     * This property can only be used when `domain` is configured as a static string.
+     * In resolver mode (`domain` as a function), the SDK resolves the domain per request,
+     * so use `ServerClient` methods instead.
+     *
      * Important: the methods exposed on the `authClient` instance do not handle any session or state management.
      */
-    readonly authClient: AuthClient;
+    get authClient(): AuthClient;
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
@@ -303,7 +363,7 @@ declare class ServerClient<TStoreOptions = unknown> {
     /**
      * Retrieve the user session from the store, or undefined if no session found.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
-     * @returns The sessionm or undefined if no session found in the store.
+     * @returns The session or undefined if no session found in the store.
      */
     getSession(storeOptions?: TStoreOptions): Promise<SessionData | undefined>;
     /**
@@ -360,7 +420,7 @@ declare abstract class AbstractStore<TData extends JWTPayload, TStoreOptions = u
     abstract get(identifier: string, options?: TStoreOptions | undefined): Promise<TData | undefined>;
     abstract delete(identifier: string, options?: TStoreOptions | undefined): Promise<void>;
     protected encrypt<TData extends JWTPayload>(identifier: string, stateData: TData, expiration: number): Promise<string>;
-    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData>;
+    protected decrypt<TData>(identifier: string, encryptedStateData: string): Promise<TData | undefined>;
 }
 
 /**
@@ -386,6 +446,13 @@ interface CookieSerializeOptions {
     domain?: string;
     expires?: Date;
     httpOnly?: boolean;
+    /**
+     * MaxAge value of the cookie in seconds.
+     *
+     * Note for implementors of {@link CookieHandler}: this value is always in seconds.
+     * Some frameworks (e.g. Express) expect `maxAge` in milliseconds, so you may need to convert
+     * before passing it to the underlying framework (e.g. `maxAge * 1000`).
+     */
     maxAge?: number;
     path?: string;
     secure?: boolean;
@@ -503,5 +570,19 @@ declare class MissingSessionError extends Error {
     code: string;
     constructor(message: string);
 }
+/**
+ * Error thrown when a configuration is invalid.
+ */
+declare class InvalidConfigurationError extends Error {
+    code: string;
+    constructor(message: string);
+}
+/**
+ * Error thrown when the issuer validation fails.
+ */
+declare class IssuerValidationError extends Error {
+    code: string;
+    constructor(message: string);
+}
 
-export { type AbstractDataStore, AbstractStateStore, AbstractTransactionStore, type AccessTokenForConnectionOptions, type AuthorizationParameters, BackchannelLogoutError, type ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type EncryptedStoreOptions, type InternalStateData, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, 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 ConnectionTokenSet, type CookieHandler, type CookieSerializeOptions, CookieTransactionStore, type DomainResolver, type EncryptedStoreOptions, type GetAccessTokenOptions, type InternalStateData, InvalidConfigurationError, IssuerValidationError, type LoginBackchannelOptions, type LoginBackchannelResult, type LogoutOptions, type LogoutTokenClaims, MissingRequiredArgumentError, MissingSessionError, MissingTransactionError, ServerClient, type ServerClientOptions, 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 };