@auth0/auth0-server-js 1.6.1 → 1.7.0

package/dist/index.js

@@ -122,10 +122,24 @@ function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointR
 import {
   TokenForConnectionError,
   AuthClient,
+  PasswordlessStartError,
+  PasswordlessVerifyError,
   TokenByRefreshTokenError
 } from "@auth0/auth0-auth-js";
 
 // src/utils.ts
+var DEFAULT_SCOPES = "openid profile email offline_access";
+var ensureOpenIdScope = (scope) => {
+  const normalizedScope = scope?.trim();
+  if (!normalizedScope) {
+    return DEFAULT_SCOPES;
+  }
+  const scopes = normalizedScope.split(/\s+/);
+  if (!scopes.includes("openid")) {
+    scopes.unshift("openid");
+  }
+  return scopes.join(" ");
+};
 var compareScopes = (scopes, requiredScopes) => {
   if (scopes === requiredScopes) {
     return true;
@@ -149,7 +163,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.6.1"
+    version: config?.version ?? "1.7.0"
   };
 }
 
@@ -233,8 +247,99 @@ var ServerMfaClient = class {
   }
 };
 
+// src/passkey/server-passkey-client.ts
+var ServerPasskeyClient = class {
+  #options;
+  /**
+   * @internal
+   */
+  constructor(options) {
+    this.#options = options;
+  }
+  /**
+   * 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.
+   */
+  async register(options, storeOptions) {
+    const domain = await this.#options.resolveDomain(storeOptions);
+    const authClient = this.#options.getAuthClient(domain);
+    return authClient.passkey.register(options);
+  }
+  /**
+   * 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.
+   */
+  async challenge(options, storeOptions) {
+    const domain = await this.#options.resolveDomain(storeOptions);
+    const authClient = this.#options.getAuthClient(domain);
+    return authClient.passkey.challenge(options);
+  }
+  /**
+   * 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).
+   */
+  async getToken(options, storeOptions) {
+    const scope = ensureOpenIdScope(options.scope ?? this.#options.defaultScope);
+    const audience = options.audience ?? this.#options.defaultAudience;
+    const domain = await this.#options.resolveDomain(storeOptions);
+    const authClient = this.#options.getAuthClient(domain);
+    const tokenEndpointResponse = await authClient.passkey.getTokenByPasskey({
+      ...options,
+      scope,
+      audience
+    });
+    const existingStateData = await this.#options.stateStore.get(this.#options.stateStoreIdentifier, storeOptions);
+    const stateData = updateStateData(audience ?? "default", existingStateData, tokenEndpointResponse, { domain });
+    await this.#options.stateStore.set(this.#options.stateStoreIdentifier, stateData, true, storeOptions);
+    return {
+      authorizationDetails: tokenEndpointResponse.authorizationDetails
+    };
+  }
+};
+
 // src/server-client.ts
-var DEFAULT_SCOPES = "openid profile email offline_access";
 var normalizeDomain = (value) => {
   const trimmed = value.trim();
   const parsed = trimmed.startsWith("http") ? new URL(trimmed) : new URL(`https://${trimmed}`);
@@ -248,16 +353,6 @@ var decodeIssuer = (token) => {
     return void 0;
   }
 };
-var ensureOpenIdScope = (scope) => {
-  if (!scope) {
-    return DEFAULT_SCOPES;
-  }
-  const scopes = scope.split(" ");
-  if (!scopes.includes("openid")) {
-    scopes.unshift("openid");
-  }
-  return scopes.join(" ");
-};
 var ServerClient = class {
   #options;
   #transactionStore;
@@ -268,6 +363,7 @@ var ServerClient = class {
   #staticDomain;
   #authClient;
   #mfaClient;
+  #passkeyClient;
   /**
    * 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.
@@ -302,6 +398,19 @@ var ServerClient = class {
     }
     return this.#mfaClient;
   }
+  /**
+   * 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() {
+    return this.#passkeyClient;
+  }
   constructor(options) {
     this.#options = options;
     this.#stateStoreIdentifier = this.#options.stateIdentifier || "__a0_session";
@@ -343,6 +452,14 @@ var ServerClient = class {
         defaultAudience: this.#options.authorizationParams?.audience ?? "default"
       });
     }
+    this.#passkeyClient = new ServerPasskeyClient({
+      resolveDomain: (storeOptions) => this.#resolveDomain(storeOptions),
+      getAuthClient: (domain) => this.#getAuthClient(domain),
+      stateStore: this.#stateStore,
+      stateStoreIdentifier: this.#stateStoreIdentifier,
+      defaultScope: this.#options.authorizationParams?.scope,
+      defaultAudience: this.#options.authorizationParams?.audience
+    });
   }
   async #resolveDomain(storeOptions) {
     if (typeof this.#options.domain === "function") {
@@ -447,6 +564,7 @@ var ServerClient = class {
     const domain = transactionData.domain ?? await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
     const tokenEndpointResponse = await authClient.getTokenByCode(url, {
+      // TransactionData.codeVerifier is optional only to accommodate magic-link transactions.
       codeVerifier: transactionData.codeVerifier
     });
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
@@ -610,6 +728,178 @@ var ServerClient = class {
       authorizationDetails: tokenEndpointResponse.authorizationDetails
     };
   }
+  /**
+   * 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',
+   * });
+   */
+  async startPasswordless(options, storeOptions) {
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    if (options.connection === "sms") {
+      await authClient.passwordless.sendSms({
+        phoneNumber: options.phoneNumber,
+        language: options.language
+      });
+      return;
+    }
+    if (options.send !== "link") {
+      await authClient.passwordless.sendEmail({
+        email: options.email,
+        send: "code",
+        language: options.language
+      });
+      return;
+    }
+    if (!options.redirectUri || typeof options.redirectUri !== "string") {
+      throw new PasswordlessStartError("redirectUri is required to start a passwordless magic-link login.");
+    }
+    const state = crypto.randomUUID();
+    const scope = ensureOpenIdScope(options.scope ?? this.#options.authorizationParams?.scope);
+    const audience = options.audience ?? this.#options.authorizationParams?.audience;
+    await authClient.passwordless.sendEmail({
+      email: options.email,
+      send: "link",
+      language: options.language,
+      authParams: {
+        ...options.authParams,
+        redirect_uri: options.redirectUri,
+        response_type: "code",
+        scope,
+        ...audience ? { audience } : {},
+        state
+      }
+    });
+    const transactionState = {
+      audience,
+      domain,
+      state
+    };
+    await this.#transactionStore.set(this.#transactionStoreIdentifier, transactionState, false, storeOptions);
+  }
+  /**
+   * 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).
+   */
+  async completePasswordless(options, storeOptions) {
+    const scope = ensureOpenIdScope(options.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
+    const audience = options.authorizationParams?.audience ?? this.#options.authorizationParams?.audience;
+    const domain = await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    const tokenEndpointResponse = options.connection === "sms" ? await authClient.getTokenByPasswordlessSms({
+      phoneNumber: options.phoneNumber,
+      code: options.verificationCode,
+      audience,
+      scope
+    }) : await authClient.getTokenByPasswordlessEmail({
+      email: options.email,
+      code: options.verificationCode,
+      audience,
+      scope
+    });
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const stateData = updateStateData(
+      this.#options.authorizationParams?.audience ?? "default",
+      existingStateData,
+      tokenEndpointResponse,
+      { domain }
+    );
+    await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    return {
+      authorizationDetails: tokenEndpointResponse.authorizationDetails
+    };
+  }
+  /**
+   * 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);
+   */
+  async completePasswordlessMagicLink(url, storeOptions) {
+    const transactionData = await this.#transactionStore.get(this.#transactionStoreIdentifier, storeOptions);
+    if (!transactionData) {
+      throw new MissingTransactionError();
+    }
+    const expectedState = typeof transactionData.state === "string" ? transactionData.state : void 0;
+    const returnedState = url.searchParams.get("state");
+    if (!returnedState || !expectedState || returnedState !== expectedState) {
+      throw new PasswordlessVerifyError("State mismatch on magic-link callback");
+    }
+    const domain = transactionData.domain ?? await this.#resolveDomain(storeOptions);
+    const authClient = this.#getAuthClient(domain);
+    const tokenEndpointResponse = await authClient.getTokenByMagicLinkCode(url, { expectedState });
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const stateData = updateStateData(transactionData.audience ?? "default", existingStateData, tokenEndpointResponse, {
+      domain
+    });
+    await this.#stateStore.set(this.#stateStoreIdentifier, stateData, true, storeOptions);
+    await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
+    return {
+      authorizationDetails: tokenEndpointResponse.authorizationDetails
+    };
+  }
   /**
    * 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.
@@ -649,16 +939,29 @@ var ServerClient = class {
   /**
    * 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.
+   *
+   * When `options.audience` and/or `options.scope` are provided, the SDK uses the session's refresh token to
+   * request an access token for that audience/scope (Multi-Resource Refresh Tokens). Tokens are cached per
+   * audience and scope combination.
+   *
+   * @param options Optional options for requesting a specific audience/scope.
    * @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.
    */
-  async getAccessToken(storeOptions) {
-    const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
-    const audience = this.#options.authorizationParams?.audience ?? "default";
-    const scope = this.#options.authorizationParams?.scope;
+  async getAccessToken(tokenOptionsOrStoreOptions, storeOptions) {
+    const hasTokenOptions = (
+      // If second arg exists, first arg must be GetAccessTokenOptions
+      storeOptions !== void 0 || // OR if first arg has audience/scope properties
+      !!tokenOptionsOrStoreOptions && typeof tokenOptionsOrStoreOptions === "object" && ("audience" in tokenOptionsOrStoreOptions || "scope" in tokenOptionsOrStoreOptions)
+    );
+    const [resolvedOptions, resolvedStoreOptions] = hasTokenOptions ? [tokenOptionsOrStoreOptions, storeOptions] : [void 0, tokenOptionsOrStoreOptions];
+    const stateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
+    const requestedAudience = resolvedOptions?.audience ?? this.#options.authorizationParams?.audience;
+    const audience = requestedAudience ?? "default";
+    const scope = resolvedOptions?.scope ?? this.#options.authorizationParams?.scope;
     const sessionDomain = stateData ? this.#getSessionDomain(stateData) : this.#staticDomain;
     if (this.#isResolverMode()) {
       if (!stateData) {
@@ -667,7 +970,7 @@ var ServerClient = class {
       if (!sessionDomain) {
         throw new MissingSessionError("Session domain does not match the current domain.");
       }
-      const resolvedDomain = await this.#resolveDomain(storeOptions);
+      const resolvedDomain = await this.#resolveDomain(resolvedStoreOptions);
       if (sessionDomain !== resolvedDomain) {
         throw new MissingSessionError("Session domain does not match the current domain.");
       }
@@ -684,14 +987,21 @@ var ServerClient = class {
       );
     }
     const domainForSession = sessionDomain;
-    const tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenByRefreshToken({
-      refreshToken: stateData.refreshToken
-    });
-    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
+    const tokenByRefreshTokenOptions = {
+      refreshToken: stateData.refreshToken,
+      // Only forward audience/scope to Auth0 when token options were explicitly supplied, and
+      // never send the synthetic 'default' cache-key audience as a real request parameter.
+      ...hasTokenOptions && {
+        ...requestedAudience && { audience: requestedAudience },
+        ...scope && { scope }
+      }
+    };
+    const tokenEndpointResponse = await this.#getAuthClient(domainForSession).getTokenByRefreshToken(tokenByRefreshTokenOptions);
+    const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, resolvedStoreOptions);
     const updatedStateData = updateStateData(audience, existingStateData, tokenEndpointResponse, {
       domain: domainForSession
     });
-    await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, storeOptions);
+    await this.#stateStore.set(this.#stateStoreIdentifier, updatedStateData, false, resolvedStoreOptions);
     return {
       accessToken: tokenEndpointResponse.accessToken,
       scope: tokenEndpointResponse.scope,
@@ -1203,6 +1513,14 @@ import {
   MfaVerifyError,
   isMfaRequiredError
 } from "@auth0/auth0-auth-js";
+
+// src/passkey/index.ts
+import {
+  PasskeyRegisterError,
+  PasskeyChallengeError,
+  PasskeyGetTokenError,
+  OrganizationValidationError
+} from "@auth0/auth0-auth-js";
 export {
   AbstractStateStore,
   AbstractTransactionStore,
@@ -1218,8 +1536,13 @@ export {
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
+  OrganizationValidationError,
+  PasskeyChallengeError,
+  PasskeyGetTokenError,
+  PasskeyRegisterError,
   ServerClient,
   ServerMfaClient,
+  ServerPasskeyClient,
   StartLinkUserError,
   StatefulStateStore,
   StatelessStateStore,