@better-auth/sso 1.8.0-beta.7 → 1.8.0-beta.9

package/dist/client.d.mts

@@ -1,6 +1,5 @@
-import { t as SSOPlugin } from "./index-BvKzNnKP.mjs";
+import { t as SSOPlugin } from "./index-BkypgbRt.mjs";
 import { DBFieldAttribute } from "better-auth/db";
-//#region src/client.d.ts
 interface SSOClientOptions {
   domainVerification?: {
     enabled: boolean;
@@ -29,5 +28,4 @@ export declare const ssoClient: <CO extends SSOClientOptions>(options?: CO | und
     "/sso/get-provider": "GET";
   };
 };
-//#endregion
 export {};

package/dist/client.mjs

@@ -1,5 +1,5 @@
-import { t as PACKAGE_VERSION } from "./version-B5en_Bdq.mjs";
-//#region src/client.ts
+import { t as PACKAGE_VERSION } from "./version-D4csRLQZ.mjs";
+// src/client.ts
 const ssoClient = (options) => {
 	return {
 		id: "sso-client",
@@ -11,5 +11,4 @@ const ssoClient = (options) => {
 		}
 	};
 };
-//#endregion
 export { ssoClient };

package/dist/{index-BvKzNnKP.d.mts → index-BkypgbRt.d.mts}

@@ -6,7 +6,6 @@ import { DBFieldAttribute, FieldAttributeToObject, InferAdditionalFieldsFromPlug
 import { Awaitable, DBTransactionAdapter, OAuth2Tokens, User } from "better-auth";
 import "@better-auth/core/db/adapter";
 import "@better-auth/core";
-//#region src/saml/algorithms.d.ts
 declare const SignatureAlgorithm: {
   readonly RSA_SHA1: "http://www.w3.org/2000/09/xmldsig#rsa-sha1";
   readonly RSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256";
@@ -44,8 +43,6 @@ interface AlgorithmValidationOptions {
   allowedKeyEncryptionAlgorithms?: string[];
   allowedDataEncryptionAlgorithms?: string[];
 }
-//#endregion
-//#region src/types.d.ts
 interface OIDCMapping {
   email?: string | undefined;
   emailVerified?: string | undefined;
@@ -238,7 +235,13 @@ type SSOUserResolution = {
   code: string;
   message?: string | undefined;
 };
-/** Normalized provider attributes available to an SSO user resolver. */
+/**
+ * Normalized provider attributes available to an SSO user resolver. When
+ * `mapProfileToUser` is set, `email`, `name`, and `image` hold its result,
+ * and `emailVerified` is `false` if it changed the email. The provider's own
+ * values remain in `providerClaims`, `verifiedIdTokenClaims`, or
+ * `providerAttributes`.
+ */
 type SSOProviderUserProfile = {
   email: string;
   emailVerified: boolean;
@@ -294,6 +297,68 @@ type SSOUserResolutionInput = SSOOIDCUserResolutionInput | SSOSAMLUserResolution
 interface SSOUserResolutionContext {
   database: DBTransactionAdapter;
 }
+interface BaseSSOProfileMappingInput {
+  providerId: string;
+  accountKey: BaseSSOUserResolutionInput["accountKey"];
+  /**
+   * Profile fields read from the provider with the provider's `mapping`.
+   * `email` is absent when the provider sent no usable email.
+   */
+  providerUser: {
+    email?: string | undefined;
+    /** Always `false` unless `trustEmailVerified` is enabled. */
+    emailVerified: boolean;
+    name?: string | undefined;
+    image?: string | undefined;
+  };
+}
+/** OIDC profile data available to `mapProfileToUser`. */
+interface SSOOIDCProfileMappingInput extends BaseSSOProfileMappingInput {
+  protocol: "oidc";
+  /** Raw claims from UserInfo, or the verified ID Token when UserInfo is absent. */
+  providerClaims: Record<string, unknown>;
+  /** Claims from the cryptographically verified ID Token, or `{}` when none was issued. */
+  verifiedIdTokenClaims: Record<string, unknown>;
+}
+/** SAML profile data available to `mapProfileToUser`. */
+interface SSOSAMLProfileMappingInput extends BaseSSOProfileMappingInput {
+  protocol: "saml";
+  /**
+   * Attributes from the verified assertion. Multi-valued attributes remain
+   * arrays and all scalar values remain strings.
+   */
+  providerAttributes: Record<string, string | readonly string[]>;
+  /** The verified assertion's NameID, which is also `accountKey.accountId`. */
+  nameID: string;
+  /** The NameID `Format` attribute, when the assertion sets one. */
+  nameIDFormat?: string | undefined;
+}
+/** Provider profile data available to `mapProfileToUser`. */
+type SSOProfileMappingInput = SSOOIDCProfileMappingInput | SSOSAMLProfileMappingInput;
+/**
+ * User fields an application can set from `mapProfileToUser`. Omitted or
+ * `undefined` fields keep the provider's value. Other keys are ignored; set
+ * additional user fields with the provider's `mapping.extraFields` or with
+ * `provisionUser`.
+ */
+interface SSOMappedUser {
+  /** The account subject always comes from the provider's `sub` claim or NameID. */
+  id?: never;
+  /**
+   * An email that differs from the provider's must be an email address and is
+   * stored unverified. Return `null` to refuse the email the provider sent;
+   * sign-in then fails with `missing_user_info`.
+   */
+  email?: string | null | undefined;
+  /**
+   * Not settable. The stored email is verified only when the provider asserts
+   * it with `trustEmailVerified` on. Domain verification lets an unverified
+   * email link to an existing user; it does not mark the email verified.
+   */
+  emailVerified?: never;
+  name?: string | undefined;
+  image?: string | undefined;
+}
 interface BaseSSOProviderMutationGuardInput {
   provider: {
     id: string;
@@ -323,13 +388,33 @@ interface SSOProviderMutationGuardContext {
   database: DBTransactionAdapter;
 }
 interface SSOOptions {
+  /**
+   * Map a provider profile to user fields before the user is looked up or
+   * created.
+   *
+   * Runs on every OIDC and SAML sign-in, after the provider's `mapping` is
+   * applied. Use it for providers that send no email: sign-in fails when
+   * neither the provider nor this callback yields one. A SAML NameID is used
+   * as the email only when its `Format` is
+   * `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. If the callback
+   * throws or returns an invalid result, sign-in redirects with
+   * `SSO_PROFILE_MAPPING_FAILED`.
+   *
+   * The returned email is used to find, link, and create the user, and to
+   * decide whether the provider's verified domain trusts it. An email that
+   * differs from the provider's is stored unverified. Return only addresses
+   * the provider vouches for, or a placeholder built with
+   * `createPlaceholderEmail` from `@better-auth/core/utils/email`.
+   */
+  mapProfileToUser?: ((input: SSOProfileMappingInput) => Awaitable<SSOMappedUser>) | undefined;
   /**
    * Resolve a verified provider identity to a Better Auth user.
    *
    * For OIDC, `accountKey` is derived from the validated ID Token. For SAML,
    * it contains the verified IdP entity ID and signed NameID. Profile fields,
    * raw OIDC claims, and SAML assertion attributes are protocol-accepted
-   * provider data and may require application-level validation.
+   * provider data and may require application-level validation. When
+   * `mapProfileToUser` is set, `providerUser` holds the mapped profile.
    *
    * The callback runs on every SSO sign-in inside the same native database
    * transaction as account finalization and session creation.
@@ -683,8 +768,6 @@ interface SSOOptions {
     idpInitiatedCallbackUrl?: string | undefined;
   };
 }
-//#endregion
-//#region src/routes/domain-verification.d.ts
 declare const requestDomainVerification: (options: SSOOptions) => import("better-call").StrictEndpoint<"/sso/request-domain-verification", {
   method: "POST";
   body: z.ZodObject<{
@@ -782,16 +865,12 @@ declare const verifyDomain: (options: SSOOptions) => import("better-call").Stric
     };
   }>>[];
 }, void>;
-//#endregion
-//#region src/utils.d.ts
 declare function parseCertificate(certPem: string): {
   fingerprintSha256: string;
   notBefore: string;
   notAfter: string;
   publicKeyAlgorithm: string;
 };
-//#endregion
-//#region src/routes/providers.d.ts
 type ParsedCert = ReturnType<typeof parseCertificate>;
 type SanitizedCert = ParsedCert | {
   error: string;
@@ -1150,8 +1229,6 @@ declare const deleteSSOProvider: (options?: SSOOptions) => import("better-call")
 }, {
   success: boolean;
 }>;
-//#endregion
-//#region src/routes/sso.d.ts
 declare const spMetadata: (options?: SSOOptions) => import("better-call").StrictEndpoint<"/sso/saml2/sp/metadata", {
   method: "GET";
   query: z.ZodObject<{
@@ -1200,7 +1277,9 @@ declare const registerSSOProvider: <O extends SSOOptions>(options: O) => import(
   }>>[];
   metadata: {
     $Infer: {
-      body: Record<string, any> & SSOProviderAdditionalFieldsInput<O>;
+      body: {
+        [x: string]: any;
+      } & SSOProviderAdditionalFieldsInput<O>;
     };
     openapi: {
       operationId: string;
@@ -1627,8 +1706,6 @@ declare const initiateSLO: (options?: SSOOptions) => import("better-call").Stric
     readonly scope: "server";
   };
 }, never>;
-//#endregion
-//#region src/constants.d.ts
 /**
  * Default clock skew tolerance (5 minutes).
  * Allows for minor time differences between IdP and SP servers.
@@ -1649,8 +1726,6 @@ declare const DEFAULT_MAX_SAML_RESPONSE_SIZE: number;
  * Protects against oversized metadata documents.
  */
 declare const DEFAULT_MAX_SAML_METADATA_SIZE: number;
-//#endregion
-//#region src/routes/helpers.d.ts
 interface SAMLServiceProviderPolicy {
   /** Effective assertion-signing requirement advertised by SP metadata. */
   wantAssertionsSigned: boolean;
@@ -1668,8 +1743,6 @@ declare function deriveSAMLServiceProviderPolicy(config: Pick<SAMLConfig, "spMet
  * parsing and manual-configuration validation as SAML authentication.
  */
 declare function deriveSAMLIdentityProviderEntityID(config: SAMLConfig): string;
-//#endregion
-//#region src/saml/timestamp.d.ts
 interface TimestampValidationOptions {
   clockSkew?: number;
   requireTimestamps?: boolean;
@@ -1688,8 +1761,6 @@ interface SAMLConditions {
  * @throws {APIError} If timestamps are invalid, expired, or not yet valid
  */
 declare function validateSAMLTimestamp(conditions: SAMLConditions | undefined, options?: TimestampValidationOptions): void;
-//#endregion
-//#region src/oidc/types.d.ts
 /**
  * OIDC Discovery Types
  *
@@ -1856,8 +1927,6 @@ interface DiscoverOIDCConfigParams {
  */
 declare const REQUIRED_DISCOVERY_FIELDS: readonly ["issuer", "authorization_endpoint", "token_endpoint", "jwks_uri"];
 type RequiredDiscoveryField = (typeof REQUIRED_DISCOVERY_FIELDS)[number];
-//#endregion
-//#region src/oidc/discovery.d.ts
 /**
  * Main entry point: Discover and hydrate OIDC configuration from an issuer.
  *
@@ -1957,8 +2026,6 @@ declare function selectTokenEndpointAuthMethod(doc: OIDCDiscoveryDocument, exist
  * @returns true if runtime discovery should be performed
  */
 declare function needsRuntimeDiscovery(config: Partial<HydratedOIDCConfig> | undefined): boolean;
-//#endregion
-//#region src/index.d.ts
 declare module "@better-auth/core" {
   interface BetterAuthPluginRegistry<AuthOptions, Options> {
     sso: {
@@ -2022,5 +2089,4 @@ declare function sso<O extends SSOOptions>(options?: O | undefined): {
   };
   options: NoInfer<O>;
 };
-//#endregion
-export { SAMLIdentityProviderMetadata as A, SSOUserResolutionContext as B, deriveSAMLIdentityProviderEntityID as C, DEFAULT_MAX_SAML_RESPONSE_SIZE as D, DEFAULT_MAX_SAML_METADATA_SIZE as E, SSOProviderMutationGuardInput as F, DigestAlgorithm as G, AlgorithmValidationOptions as H, SSOProviderReference as I, KeyEncryptionAlgorithm as K, SSOProviderUserProfile as L, SSOOptions as M, SSOProvider as N, OIDCConfig as O, SSOProviderMutationGuardContext as P, SSOSAMLUserResolutionInput as R, SAMLServiceProviderPolicy as S, DEFAULT_CLOCK_SKEW_MS as T, DataEncryptionAlgorithm as U, SSOUserResolutionInput as V, DeprecatedAlgorithmBehavior as W, REQUIRED_DISCOVERY_FIELDS as _, fetchDiscoveryDocument as a, TimestampValidationOptions as b, normalizeUrl as c, validateDiscoveryUrl as d, DiscoverOIDCConfigParams as f, OIDCDiscoveryDocument as g, HydratedOIDCConfig as h, discoverOIDCConfig as i, SSOOIDCUserResolutionInput as j, SAMLConfig as k, selectTokenEndpointAuthMethod as l, DiscoveryErrorCode as m, sso as n, needsRuntimeDiscovery as o, DiscoveryError as p, SignatureAlgorithm as q, computeDiscoveryUrl as r, normalizeDiscoveryUrls as s, SSOPlugin as t, validateDiscoveryDocument as u, RequiredDiscoveryField as v, deriveSAMLServiceProviderPolicy as w, validateSAMLTimestamp as x, SAMLConditions as y, SSOUserResolution as z };
+export { SAMLIdentityProviderMetadata as A, SSOProviderUserProfile as B, deriveSAMLIdentityProviderEntityID as C, DEFAULT_MAX_SAML_RESPONSE_SIZE as D, DEFAULT_MAX_SAML_METADATA_SIZE as E, SSOProfileMappingInput as F, SSOUserResolutionInput as G, SSOSAMLUserResolutionInput as H, SSOProvider as I, DeprecatedAlgorithmBehavior as J, AlgorithmValidationOptions as K, SSOProviderMutationGuardContext as L, SSOOIDCProfileMappingInput as M, SSOOIDCUserResolutionInput as N, OIDCConfig as O, SSOOptions as P, SSOProviderMutationGuardInput as R, SAMLServiceProviderPolicy as S, DEFAULT_CLOCK_SKEW_MS as T, SSOUserResolution as U, SSOSAMLProfileMappingInput as V, SSOUserResolutionContext as W, KeyEncryptionAlgorithm as X, DigestAlgorithm as Y, SignatureAlgorithm as Z, REQUIRED_DISCOVERY_FIELDS as _, fetchDiscoveryDocument as a, TimestampValidationOptions as b, normalizeUrl as c, validateDiscoveryUrl as d, DiscoverOIDCConfigParams as f, OIDCDiscoveryDocument as g, HydratedOIDCConfig as h, discoverOIDCConfig as i, SSOMappedUser as j, SAMLConfig as k, selectTokenEndpointAuthMethod as l, DiscoveryErrorCode as m, sso as n, needsRuntimeDiscovery as o, DiscoveryError as p, DataEncryptionAlgorithm as q, computeDiscoveryUrl as r, normalizeDiscoveryUrls as s, SSOPlugin as t, validateDiscoveryDocument as u, RequiredDiscoveryField as v, deriveSAMLServiceProviderPolicy as w, validateSAMLTimestamp as x, SAMLConditions as y, SSOProviderReference as z };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as SAMLIdentityProviderMetadata, B as SSOUserResolutionContext, C as deriveSAMLIdentityProviderEntityID, D as DEFAULT_MAX_SAML_RESPONSE_SIZE, E as DEFAULT_MAX_SAML_METADATA_SIZE, F as SSOProviderMutationGuardInput, G as DigestAlgorithm, H as AlgorithmValidationOptions, I as SSOProviderReference, K as KeyEncryptionAlgorithm, L as SSOProviderUserProfile, M as SSOOptions, N as SSOProvider, O as OIDCConfig, P as SSOProviderMutationGuardContext, R as SSOSAMLUserResolutionInput, S as SAMLServiceProviderPolicy, T as DEFAULT_CLOCK_SKEW_MS, U as DataEncryptionAlgorithm, V as SSOUserResolutionInput, W as DeprecatedAlgorithmBehavior, _ as REQUIRED_DISCOVERY_FIELDS, a as fetchDiscoveryDocument, b as TimestampValidationOptions, c as normalizeUrl, d as validateDiscoveryUrl, f as DiscoverOIDCConfigParams, g as OIDCDiscoveryDocument, h as HydratedOIDCConfig, i as discoverOIDCConfig, j as SSOOIDCUserResolutionInput, k as SAMLConfig, l as selectTokenEndpointAuthMethod, m as DiscoveryErrorCode, n as sso, o as needsRuntimeDiscovery, p as DiscoveryError, q as SignatureAlgorithm, r as computeDiscoveryUrl, s as normalizeDiscoveryUrls, t as SSOPlugin, u as validateDiscoveryDocument, v as RequiredDiscoveryField, w as deriveSAMLServiceProviderPolicy, x as validateSAMLTimestamp, y as SAMLConditions, z as SSOUserResolution } from "./index-BvKzNnKP.mjs";
-export { type AlgorithmValidationOptions, DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, type DeprecatedAlgorithmBehavior, DigestAlgorithm, type DiscoverOIDCConfigParams, DiscoveryError, type DiscoveryErrorCode, type HydratedOIDCConfig, KeyEncryptionAlgorithm, type OIDCConfig, type OIDCDiscoveryDocument, REQUIRED_DISCOVERY_FIELDS, type RequiredDiscoveryField, type SAMLConditions, type SAMLConfig, type SAMLIdentityProviderMetadata, type SAMLServiceProviderPolicy, type SSOOIDCUserResolutionInput, type SSOOptions, SSOPlugin, type SSOProvider, type SSOProviderMutationGuardContext, type SSOProviderMutationGuardInput, type SSOProviderReference, type SSOProviderUserProfile, type SSOSAMLUserResolutionInput, type SSOUserResolution, type SSOUserResolutionContext, type SSOUserResolutionInput, SignatureAlgorithm, type TimestampValidationOptions, computeDiscoveryUrl, deriveSAMLIdentityProviderEntityID, deriveSAMLServiceProviderPolicy, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };
+import { A as SAMLIdentityProviderMetadata, B as SSOProviderUserProfile, C as deriveSAMLIdentityProviderEntityID, D as DEFAULT_MAX_SAML_RESPONSE_SIZE, E as DEFAULT_MAX_SAML_METADATA_SIZE, F as SSOProfileMappingInput, G as SSOUserResolutionInput, H as SSOSAMLUserResolutionInput, I as SSOProvider, J as DeprecatedAlgorithmBehavior, K as AlgorithmValidationOptions, L as SSOProviderMutationGuardContext, M as SSOOIDCProfileMappingInput, N as SSOOIDCUserResolutionInput, O as OIDCConfig, P as SSOOptions, R as SSOProviderMutationGuardInput, S as SAMLServiceProviderPolicy, T as DEFAULT_CLOCK_SKEW_MS, U as SSOUserResolution, V as SSOSAMLProfileMappingInput, W as SSOUserResolutionContext, X as KeyEncryptionAlgorithm, Y as DigestAlgorithm, Z as SignatureAlgorithm, _ as REQUIRED_DISCOVERY_FIELDS, a as fetchDiscoveryDocument, b as TimestampValidationOptions, c as normalizeUrl, d as validateDiscoveryUrl, f as DiscoverOIDCConfigParams, g as OIDCDiscoveryDocument, h as HydratedOIDCConfig, i as discoverOIDCConfig, j as SSOMappedUser, k as SAMLConfig, l as selectTokenEndpointAuthMethod, m as DiscoveryErrorCode, n as sso, o as needsRuntimeDiscovery, p as DiscoveryError, q as DataEncryptionAlgorithm, r as computeDiscoveryUrl, s as normalizeDiscoveryUrls, t as SSOPlugin, u as validateDiscoveryDocument, v as RequiredDiscoveryField, w as deriveSAMLServiceProviderPolicy, x as validateSAMLTimestamp, y as SAMLConditions, z as SSOProviderReference } from "./index-BkypgbRt.mjs";
+export { type AlgorithmValidationOptions, DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, type DeprecatedAlgorithmBehavior, DigestAlgorithm, type DiscoverOIDCConfigParams, DiscoveryError, type DiscoveryErrorCode, type HydratedOIDCConfig, KeyEncryptionAlgorithm, type OIDCConfig, type OIDCDiscoveryDocument, REQUIRED_DISCOVERY_FIELDS, type RequiredDiscoveryField, type SAMLConditions, type SAMLConfig, type SAMLIdentityProviderMetadata, type SAMLServiceProviderPolicy, type SSOMappedUser, type SSOOIDCProfileMappingInput, type SSOOIDCUserResolutionInput, type SSOOptions, SSOPlugin, type SSOProfileMappingInput, type SSOProvider, type SSOProviderMutationGuardContext, type SSOProviderMutationGuardInput, type SSOProviderReference, type SSOProviderUserProfile, type SSOSAMLProfileMappingInput, type SSOSAMLUserResolutionInput, type SSOUserResolution, type SSOUserResolutionContext, type SSOUserResolutionInput, SignatureAlgorithm, type TimestampValidationOptions, computeDiscoveryUrl, deriveSAMLIdentityProviderEntityID, deriveSAMLServiceProviderPolicy, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { t as PACKAGE_VERSION } from "./version-B5en_Bdq.mjs";
-import { APIError, addOAuthServerContext, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, sessionMiddleware } from "better-auth/api";
+import { t as PACKAGE_VERSION } from "./version-D4csRLQZ.mjs";
+import { APIError, addOAuthServerContext, createAuthEndpoint, createAuthMiddleware, generateGenericState, getSessionFromCtx, parseGenericState, sessionMiddleware } from "better-auth/api";
 import { XMLParser, XMLValidator } from "fast-xml-parser";
 import { X509Certificate } from "node:crypto";
 import { getHostname } from "tldts";
@@ -17,12 +17,13 @@ import { DOMParser } from "@xmldom/xmldom";
 import samlifyDefault, * as samlifyNamespace from "samlify";
 import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
 import { parseInputData, toZodSchema } from "better-auth/db";
+import { HIDE_METADATA } from "@better-auth/core/api";
+import { PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, authorizationCodeRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, getOAuth2Tokens, parseStringBoolean } from "@better-auth/core/oauth2";
 import { isAPIError } from "@better-auth/core/utils/is-api-error";
 import { appendQueryParams } from "@better-auth/core/utils/url";
-import { HIDE_METADATA, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, authorizationCodeRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, generateGenericState, generateState, getOAuth2Tokens, parseGenericState, parseState } from "better-auth";
 import { deleteSessionCookie, setAccountCookie, setSessionCookie } from "better-auth/cookies";
-import { additionalAuthorizationParamsSchema, handleOAuthUserInfo } from "better-auth/oauth2";
-//#region src/constants.ts
+import { additionalAuthorizationParamsSchema, generateState, handleOAuthUserInfo, parseState } from "better-auth/oauth2";
+// src/constants.ts
 /**
 * SAML Constants
 *
@@ -61,8 +62,25 @@ const DEFAULT_MAX_SAML_RESPONSE_SIZE = 262144;
 * Protects against oversized metadata documents.
 */
 const DEFAULT_MAX_SAML_METADATA_SIZE = 102400;
-//#endregion
-//#region src/utils.ts
+/**
+* NameID format whose value is an email address. Other formats, such as
+* persistent and transient, are opaque identifiers.
+*
+* @see https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf (§8.3.2)
+*/
+const SAML_EMAIL_NAME_ID_FORMAT = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress";
+/**
+* Attributes read for the email, in order, when `samlConfig.mapping.email` is
+* not set and neither the `email` attribute nor an `emailAddress` NameID is
+* present: the claim URI many IdPs send by default, and the `mail` attribute
+* by name and by OID.
+*/
+const SAML_FALLBACK_EMAIL_ATTRIBUTES = [
+	"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+	"mail",
+	"urn:oid:0.9.2342.19200300.100.1.3"
+];
+// src/utils.ts
 const unsafeSAMLRedirectPathPrefix = /^\/(?:\/|\\|%2f|%5c)/i;
 const isSafeSAMLRedirectPath = (url) => url.startsWith("/") && !unsafeSAMLRedirectPathPrefix.test(url);
 /**
@@ -94,16 +112,6 @@ const domainMatches = (searchDomain, domainList) => {
 	return domains.some((domain) => search === domain || search.endsWith(`.${domain}`));
 };
 /**
-* Strictly parse a provider-supplied email-verification claim.
-*
-* OIDC userInfo, OIDC id-token, and SAML attribute values are frequently
-* strings, so a loose `Boolean(value)` or truthy fallback treats the string
-* `"false"` as verified. Only a boolean `true` or the exact string `"true"`
-* count as verified; every other value, including `"false"`, `"0"`, `""`,
-* numbers, arrays, and objects, is unverified.
-*/
-const parseProviderEmailVerified = (value) => value === true || value === "true";
-/**
 * Validates email domain against allowed domain(s).
 * Supports comma-separated domains for multi-domain SSO.
 */
@@ -151,8 +159,7 @@ function maskClientId(clientId) {
 	if (clientId.length <= 4) return "****";
 	return `****${clientId.slice(-4)}`;
 }
-//#endregion
-//#region src/linking/org-assignment.ts
+// src/linking/org-assignment.ts
 const VERIFIED_PROVIDER_PAGE_SIZE = 100;
 function getEmailDomain(email) {
 	const parts = email.trim().toLowerCase().split("@");
@@ -295,8 +302,7 @@ async function assignOrganizationByDomain(ctx, options) {
 		...options
 	});
 }
-//#endregion
-//#region src/oidc/types.ts
+// src/oidc/types.ts
 /**
 * Custom error class for OIDC discovery failures.
 * Can be caught and mapped to APIError at the edge.
@@ -321,8 +327,7 @@ const REQUIRED_DISCOVERY_FIELDS = [
 	"token_endpoint",
 	"jwks_uri"
 ];
-//#endregion
-//#region src/oidc/discovery.ts
+// src/oidc/discovery.ts
 /**
 * OIDC Discovery Pipeline
 *
@@ -788,8 +793,7 @@ async function ensureRuntimeDiscovery(config, issuer, isTrustedOrigin) {
 	await assertServerFetchedOIDCEndpointsAllowed(resolved, isTrustedOrigin);
 	return resolved;
 }
-//#endregion
-//#region src/oidc/errors.ts
+// src/oidc/errors.ts
 /**
 * OIDC Discovery Error Mapping
 *
@@ -869,8 +873,7 @@ function mapDiscoveryErrorToAPIError(error) {
 			});
 	}
 }
-//#endregion
-//#region src/provider-reference.ts
+// src/provider-reference.ts
 const SSO_PROVIDER_STATE_KEY = "ssoProviderReference";
 function serializeCanonical(value) {
 	if (value === null) return "null";
@@ -965,8 +968,7 @@ async function isCurrentSSOProviderReference(provider, reference) {
 	if (source.type === "persisted" && (reference.source.type !== "persisted" || source.recordId !== reference.source.recordId)) return false;
 	return reference.authenticationConfigurationFingerprint === await computeProviderAuthenticationFingerprint(provider);
 }
-//#endregion
-//#region src/saml/parser.ts
+// src/saml/parser.ts
 const xmlParser = new XMLParser({
 	ignoreAttributes: false,
 	attributeNamePrefix: "@_",
@@ -999,8 +1001,7 @@ function countAllNodes(obj, nodeName) {
 	else if (typeof value === "object" && value !== null) count += countAllNodes(value, nodeName);
 	return count;
 }
-//#endregion
-//#region src/saml/algorithms.ts
+// src/saml/algorithms.ts
 const SignatureAlgorithm = {
 	RSA_SHA1: "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
 	RSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
@@ -1177,8 +1178,7 @@ function validateConfigAlgorithms(config, options = {}) {
 	}
 }
 const saml = typeof samlifyNamespace.SPMetadata === "function" && typeof samlifyNamespace.setSchemaValidator === "function" ? samlifyNamespace : samlifyDefault ?? samlifyNamespace;
-//#endregion
-//#region src/saml/assertions.ts
+// src/saml/assertions.ts
 const SAML_ASSERTION_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:assertion";
 const SAML_PROTOCOL_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:protocol";
 const XML_SIGNATURE_NAMESPACE = "http://www.w3.org/2000/09/xmldsig#";
@@ -1254,8 +1254,7 @@ function verifySAMLAssertionSignature(samlContent, verificationOptions) {
 		throw assertionSignatureFailure();
 	}
 }
-//#endregion
-//#region src/saml/error-codes.ts
+// src/saml/error-codes.ts
 const SAML_ERROR_CODES = defineErrorCodes({
 	SINGLE_LOGOUT_NOT_ENABLED: "Single Logout is not enabled",
 	INVALID_LOGOUT_RESPONSE: "Invalid LogoutResponse",
@@ -1265,8 +1264,7 @@ const SAML_ERROR_CODES = defineErrorCodes({
 	SAML_PROVIDER_NOT_FOUND: "SAML provider not found",
 	CERT_SOURCE_MISSING: "samlConfig requires either a signing certificate (cert or idpMetadata.cert) or an idpMetadata.metadata XML document."
 });
-//#endregion
-//#region src/saml/cert.ts
+// src/saml/cert.ts
 /**
 * IdP signing-certificate rules for SAML configs. Centralized so the runtime
 * verification path (`createIdP`), the sanitizer (`getSSOProvider` and
@@ -1295,8 +1293,7 @@ function validateCertSources(config) {
 	const hasExplicitCert = config.idpMetadata?.cert !== void 0 || config.cert !== void 0;
 	if (!hasMetadataXml && !hasExplicitCert) throw APIError.from("BAD_REQUEST", SAML_ERROR_CODES.CERT_SOURCE_MISSING);
 }
-//#endregion
-//#region src/saml/response-binding.ts
+// src/saml/response-binding.ts
 const SAML_HTTP_POST_BINDING = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
 const SAML_BEARER_CONFIRMATION_METHOD = "urn:oasis:names:tc:SAML:2.0:cm:bearer";
 const SAML_METADATA_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:metadata";
@@ -1383,7 +1380,7 @@ function parseSAMLServiceProviderMetadata(metadata) {
 			if (value) nameIDFormats.push(value);
 		}
 		for (const service of directMetadataChildren(descriptor, "AssertionConsumerService")) {
-			if (service.getAttribute("Binding") !== "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST") continue;
+			if (service.getAttribute("Binding") !== SAML_HTTP_POST_BINDING) continue;
 			const location = service.getAttribute("Location")?.trim();
 			if (!location || !isAbsoluteHttpUrl(location)) throw new Error("Invalid SAML POST AssertionConsumerService");
 			postAssertionConsumerServiceUrls.push(location);
@@ -1436,6 +1433,15 @@ function validateAudienceRestrictions(assertion, expectedAudiences) {
 		code: "SAML_AUDIENCE_MISMATCH"
 	});
 }
+/**
+* Reads the user's email from a SAML assertion: the mapped attribute (default
+* `email`), then a NameID whose Format is `emailAddress`, then, without a
+* mapped attribute, the fallback email attributes. Other NameIDs are opaque or
+* unspecified, so they never become the email.
+*/
+function readSAMLEmail(attr, options) {
+	return attr(options.mappedAttribute || "email") || (options.nameIDFormat === "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" ? options.nameID : void 0) || (options.mappedAttribute ? void 0 : SAML_FALLBACK_EMAIL_ATTRIBUTES.map(attr).find(Boolean));
+}
 function getBearerSubjectConfirmationData(assertion) {
 	return toNodeArray(firstNode(assertion.Subject)?.SubjectConfirmation).filter((confirmation) => confirmation["@_Method"] === SAML_BEARER_CONFIRMATION_METHOD).map((confirmation) => firstNode(confirmation.SubjectConfirmationData)).filter((data) => !!data);
 }
@@ -1463,6 +1469,11 @@ function validateResponseDestination(response, expectedRecipients) {
 		code: "SAML_DESTINATION_MISMATCH"
 	});
 }
+/**
+* Validates that the assertion is bound to this Service Provider, then returns
+* the NameID format so user attribute extraction need not parse the response
+* again.
+*/
 function validateSAMLResponseBinding(samlContent, options) {
 	const expectedAudiences = toStringSet(options.expectedAudiences);
 	const expectedRecipients = toStringSet(options.expectedRecipients);
@@ -1472,9 +1483,10 @@ function validateSAMLResponseBinding(samlContent, options) {
 	validateAudienceRestrictions(assertion, expectedAudiences);
 	validateBearerRecipient(assertion, expectedRecipients);
 	validateResponseDestination(response, expectedRecipients);
+	const nameIDFormat = firstNode(firstNode(assertion.Subject)?.NameID)?.["@_Format"];
+	return { nameIDFormat: typeof nameIDFormat === "string" && nameIDFormat ? nameIDFormat : void 0 };
 }
-//#endregion
-//#region src/saml/response-validation.ts
+// src/saml/response-validation.ts
 function errorRedirectUrl(base, error, description) {
 	try {
 		const url = new URL(base);
@@ -1571,9 +1583,66 @@ function validateAudience(c, ctx) {
 		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Audience mismatch"));
 	}
 }
-//#endregion
-//#region src/user-resolution.ts
+// src/user-resolution.ts
 const SSO_AUTHENTICATION_FAILURE = Symbol("SSO_AUTHENTICATION_FAILURE");
+/**
+* Applies `mapProfileToUser` to the profile read from the provider. Only the
+* documented user fields are taken from the callback's result.
+*/
+async function mapSSOProfile(options, input, logger) {
+	if (!options?.mapProfileToUser) return input.providerUser;
+	let mappedUser;
+	try {
+		const result = await options.mapProfileToUser(structuredClone(input));
+		if (isRecord$1(result)) {
+			const { email, name, image } = result;
+			mappedUser = {
+				email,
+				name,
+				image
+			};
+		}
+	} catch (error) {
+		logFailure(logger, "SSO profile mapping failed", {
+			providerId: input.providerId,
+			protocol: input.protocol,
+			error
+		});
+		throw profileMappingFailure();
+	}
+	if (!isSSOMappedUser(mappedUser) || !isAcceptedEmail(mappedUser.email, input.providerUser.email)) {
+		logFailure(logger, "SSO profile mapper returned an invalid profile", {
+			providerId: input.providerId,
+			protocol: input.protocol
+		});
+		throw profileMappingFailure();
+	}
+	const { email, name, image } = mappedUser;
+	const providerUser = input.providerUser;
+	const mappedEmail = email === null ? void 0 : email ?? providerUser.email;
+	return {
+		email: mappedEmail,
+		emailVerified: providerUser.emailVerified && mappedEmail?.toLowerCase() === providerUser.email?.toLowerCase(),
+		name: name ?? providerUser.name,
+		image: image ?? providerUser.image
+	};
+}
+function isOptionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function isSSOMappedUser(value) {
+	return isRecord$1(value) && (value.email === null || isOptionalString(value.email)) && isOptionalString(value.name) && isOptionalString(value.image);
+}
+/** A changed email must be an address; the provider's own email passes as sent. */
+function isAcceptedEmail(email, providerEmail) {
+	return typeof email !== "string" || email.toLowerCase() === providerEmail?.toLowerCase() || z.email().safeParse(email).success;
+}
+function profileMappingFailure() {
+	return new APIError("INTERNAL_SERVER_ERROR", {
+		code: "SSO_PROFILE_MAPPING_FAILED",
+		message: "Unable to map the SSO profile"
+	});
+}
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1586,9 +1655,9 @@ function isSSOUserResolution(value) {
 	if (value.action === "link") return isNonEmptyString(value.userId) && (value.profile === "preserve" || value.profile === "update");
 	return value.action === "reject" && isNonEmptyString(value.code) && (value.message === void 0 || typeof value.message === "string");
 }
-function logFailure(logger, message) {
+function logFailure(logger, message, details) {
 	try {
-		logger.error(message);
+		logger.error(message, ...details ? [details] : []);
 	} catch {}
 }
 function resolutionFailure() {
@@ -1658,8 +1727,7 @@ function getFailedSSOAuthenticationResult(error) {
 	if (!(error instanceof Error) || !(SSO_AUTHENTICATION_FAILURE in error) || error[SSO_AUTHENTICATION_FAILURE] !== true || !("result" in error)) return;
 	return error.result;
 }
-//#endregion
-//#region src/routes/helpers.ts
+// src/routes/helpers.ts
 /**
 * Same as `normalizePem`, but applied across the resolved list of IdP signing
 * certificates so multi-cert rotation configs survive the line-trim step.
@@ -1693,6 +1761,7 @@ async function findSAMLProvider(providerId, options, adapter) {
 }
 function createSP(config, baseURL, providerId, opts) {
 	const spData = config.spMetadata;
+	const clockSkew = opts?.clockSkew ?? 3e5;
 	const sloLocation = `${baseURL}/sso/saml2/sp/slo/${providerId}`;
 	const acsUrl = `${baseURL}/sso/saml2/sp/acs/${providerId}`;
 	let metadata = spData?.metadata;
@@ -1725,7 +1794,7 @@ function createSP(config, baseURL, providerId, opts) {
 		encPrivateKey: normalizePem(spData?.encPrivateKey),
 		encPrivateKeyPass: spData?.encPrivateKeyPass,
 		relayState: opts?.relayState,
-		clockDrifts: opts?.clockSkew && opts?.clockSkew !== 0 ? [-opts.clockSkew, opts.clockSkew] : void 0
+		clockDrifts: [-clockSkew, clockSkew]
 	});
 }
 /**
@@ -1822,8 +1891,7 @@ function createSAMLPostForm(action, samlParam, samlValue, relayState) {
 	const html = `<!DOCTYPE html><html><body onload="document.forms[0].submit();"><form method="POST" action="${safeAction}"><input type="hidden" name="${safeSamlParam}" value="${safeSamlValue}" />${safeRelayState ? `<input type="hidden" name="RelayState" value="${safeRelayState}" />` : ""}<noscript><input type="submit" value="Continue" /></noscript></form></body></html>`;
 	return new Response(html, { headers: { "Content-Type": "text/html" } });
 }
-//#endregion
-//#region src/routes/schemas.ts
+// src/routes/schemas.ts
 const absoluteUrlSchema = z.url();
 const samlRedirectUrlSchema = z.string().refine((url) => isSafeSAMLRedirectPath(url) || absoluteUrlSchema.safeParse(url).success, { message: "Expected an absolute URL or a relative path starting with /" });
 function getSSOProviderAdditionalFields$1(options) {
@@ -1966,8 +2034,7 @@ function getUpdateSSOProviderBodySchema(options) {
 		...getSSOProviderAdditionalFieldsSchema(options).partial().shape
 	});
 }
-//#endregion
-//#region src/routes/providers.ts
+// src/routes/providers.ts
 const ADMIN_ROLES = ["owner", "admin"];
 const OIDC_IDENTITY_BOUNDARY_FIELDS = [
 	"authorizationEndpoint",
@@ -2518,8 +2585,7 @@ const deleteSSOProvider = (options) => {
 		return ctx.json({ success: true });
 	});
 };
-//#endregion
-//#region src/routes/domain-verification.ts
+// src/routes/domain-verification.ts
 const DNS_LABEL_MAX_LENGTH = 63;
 const DEFAULT_TOKEN_PREFIX = "better-auth-token";
 const domainVerificationBodySchema = z.object({ providerId: z.string() });
@@ -2648,8 +2714,7 @@ const verifyDomain = (options) => {
 		ctx.setStatus(204);
 	});
 };
-//#endregion
-//#region src/saml-state.ts
+// src/saml-state.ts
 async function generateRelayState(c, link, providerReference) {
 	const callbackURL = c.body.callbackURL;
 	if (!callbackURL) throw new APIError("BAD_REQUEST", { message: "callbackURL is required" });
@@ -2699,8 +2764,7 @@ async function parseRelayState(c) {
 	if (!parsedData.errorURL) parsedData.errorURL = errorURL;
 	return parsedData;
 }
-//#endregion
-//#region src/saml/timestamp.ts
+// src/saml/timestamp.ts
 /**
 * Validates SAML assertion timestamp conditions (NotBefore/NotOnOrAfter).
 * Prevents acceptance of expired or future-dated assertions.
@@ -2740,8 +2804,7 @@ function validateSAMLTimestamp(conditions, options = {}) {
 		});
 	}
 }
-//#endregion
-//#region src/routes/saml-pipeline.ts
+// src/routes/saml-pipeline.ts
 function isSameSSOProviderReference(left, right) {
 	if (left.providerId !== right.providerId || left.authenticationConfigurationFingerprint !== right.authenticationConfigurationFingerprint || left.source.type !== right.source.type) return false;
 	return left.source.type === "configured" ? true : right.source.type === "persisted" && left.source.recordId === right.source.recordId;
@@ -2806,17 +2869,12 @@ function getSAMLRedirectCandidates(relayStateCallbackUrl, samlConfig, samlOption
 		samlConfig?.callbackUrl
 	];
 }
-function toArray(value) {
-	if (Array.isArray(value)) return value;
-	return value ? [value] : [];
-}
-function getExpectedSAMLRecipients(config, baseURL, providerId, currentCallbackPath, assertionConsumerServiceUrl) {
+function getExpectedSAMLRecipients(config, baseURL, providerId, currentCallbackPath) {
 	const configuredPostAssertionConsumerServiceUrls = getSAMLPostAssertionConsumerServiceUrls(config.spMetadata?.metadata);
 	return [
 		currentCallbackPath,
 		`${baseURL}/sso/saml2/sp/acs/${providerId}`,
-		...configuredPostAssertionConsumerServiceUrls,
-		...toArray(assertionConsumerServiceUrl)
+		...configuredPostAssertionConsumerServiceUrls
 	];
 }
 async function getSAMLResponseBindingContent(sp, samlContent) {
@@ -2827,20 +2885,16 @@ async function getSAMLResponseBindingContent(sp, samlContent) {
 /**
 * Extracts the Assertion ID from a SAML response XML.
 * Used for replay protection per SAML 2.0 Core section 2.3.3.
+*
+* Reads the ID through the DOM so character references are decoded the same
+* way the signature check decodes them: re-spelling the ID keeps the
+* signature valid, so it must not change the replay key.
 */
 function extractAssertionId(samlContent) {
 	try {
-		const parsed = new XMLParser({
-			ignoreAttributes: false,
-			attributeNamePrefix: "@_",
-			removeNSPrefix: true
-		}).parse(samlContent);
-		const response = parsed.Response || parsed["samlp:Response"];
-		if (!response) return null;
-		const rawAssertion = response.Assertion || response["saml:Assertion"];
-		const assertion = Array.isArray(rawAssertion) ? rawAssertion[0] : rawAssertion;
-		if (!assertion) return null;
-		return assertion["@_ID"] || null;
+		const response = new DOMParser().parseFromString(samlContent, "text/xml").documentElement;
+		if (response?.localName !== "Response") return null;
+		return Array.from(response.childNodes).find((node) => node.nodeType === 1 && node.localName === "Assertion")?.getAttribute("ID") || null;
 	} catch {
 		return null;
 	}
@@ -2877,6 +2931,12 @@ async function processSAMLResponse(ctx, params, options) {
 	const samlRedirectUrl = getSafeRedirectUrl(redirectCandidates, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
 	const samlErrorRedirectUrl = getSafeRedirectUrl([relayState?.errorURL, samlRedirectUrl], currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
 	params.onErrorRedirectResolved?.(samlErrorRedirectUrl);
+	const redirectOnCodedAPIError = (e) => {
+		if (isAPIError(e) && e.body?.code) throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
+			error: e.body.code,
+			...e.body.message ? { error_description: e.body.message } : {}
+		}));
+	};
 	const stateProviderReference = parseSSOProviderReference(relayState?.serverContext?.[SSO_PROVIDER_STATE_KEY]);
 	validateSingleAssertion(SAMLResponse);
 	let parsedResponse;
@@ -2899,17 +2959,17 @@ async function processSAMLResponse(ctx, params, options) {
 		logger: ctx.context.logger
 	});
 	const expectedAudiences = [sp.entityMeta.getEntityID(), parsedSamlConfig.audience];
-	const assertionConsumerServiceUrl = sp.entityMeta.getAssertionConsumerService(SAML_HTTP_POST_BINDING);
-	const expectedRecipients = getExpectedSAMLRecipients(parsedSamlConfig, ctx.context.baseURL, providerId, currentCallbackPath, assertionConsumerServiceUrl);
+	const expectedRecipients = getExpectedSAMLRecipients(parsedSamlConfig, ctx.context.baseURL, providerId, currentCallbackPath);
 	const serviceProviderPolicy = deriveSAMLServiceProviderPolicy(parsedSamlConfig);
 	let samlBindingContent;
+	let boundAssertion;
 	try {
 		samlBindingContent = await getSAMLResponseBindingContent(sp, samlContent);
 		if (serviceProviderPolicy.wantAssertionsSigned) verifySAMLAssertionSignature(samlBindingContent, {
 			metadata: idp.entityMeta,
 			signatureAlgorithm: idp.entitySetting.requestSignatureAlgorithm
 		});
-		validateSAMLResponseBinding(samlBindingContent, {
+		boundAssertion = validateSAMLResponseBinding(samlBindingContent, {
 			expectedAudiences,
 			expectedRecipients
 		});
@@ -2995,6 +3055,7 @@ async function processSAMLResponse(ctx, params, options) {
 	for (const [name, value] of Object.entries(attributes)) if (typeof value === "string") providerAttributes[name] = value;
 	else if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) providerAttributes[name] = value;
 	const mapping = parsedSamlConfig.mapping ?? {};
+	const { nameIDFormat } = boundAssertion;
 	const attr = (key) => {
 		const value = attributes[key];
 		return Array.isArray(value) ? value[0] : value;
@@ -3002,34 +3063,63 @@ async function processSAMLResponse(ctx, params, options) {
 	const userInfo = {
 		...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, attributes[value]])),
 		id: extract.nameID,
-		email: (attr(mapping.email || "email") || extract.nameID || "").toLowerCase(),
-		name: [attr(mapping.firstName || "givenName"), attr(mapping.lastName || "surname")].filter(Boolean).join(" ") || attr(mapping.name || "displayName") || extract.nameID,
-		emailVerified: options?.trustEmailVerified && mapping.emailVerified ? parseProviderEmailVerified(attr(mapping.emailVerified)) : false
+		email: readSAMLEmail(attr, {
+			mappedAttribute: mapping.email,
+			nameID: extract.nameID,
+			nameIDFormat
+		}),
+		name: [attr(mapping.firstName || "givenName"), attr(mapping.lastName || "surname")].filter(Boolean).join(" ") || attr(mapping.name || "displayName") || void 0,
+		emailVerified: options?.trustEmailVerified && mapping.emailVerified ? parseStringBoolean(attr(mapping.emailVerified)) ?? false : false
 	};
-	if (!userInfo.id || !userInfo.email) {
-		ctx.context.logger.error("Missing essential user info from SAML response", {
+	const providerUserAttributes = Object.fromEntries(Object.entries(userInfo).filter(([key]) => key !== "id"));
+	const missingUserInfo = (hasNameId, providerSentEmail = false) => {
+		ctx.context.logger.error(providerSentEmail ? "mapProfileToUser refused the email the SAML provider sent" : hasNameId ? `SAML sign-in has no email. Send an email attribute, or a NameID with Format ${SAML_EMAIL_NAME_ID_FORMAT}, from the IdP; set samlConfig.mapping.email; or return an email from mapProfileToUser.` : "SAML response has no NameID", {
 			providerId,
 			attributeNames: Object.keys(attributes),
-			hasNameId: Boolean(userInfo.id),
-			hasEmail: Boolean(userInfo.email)
+			nameIDFormat
+		});
+		return new APIError("BAD_REQUEST", {
+			code: "MISSING_USER_INFO",
+			message: "Unable to extract user ID or email from SAML response. Map an email attribute, or create a placeholder with `mapProfileToUser`."
 		});
-		throw new APIError("BAD_REQUEST", { message: "Unable to extract user ID or email from SAML response" });
-	}
-	const providerUserAttributes = Object.fromEntries(Object.entries(userInfo).filter(([key]) => key !== "id"));
-	const providerUser = {
-		...providerUserAttributes,
-		email: userInfo.email,
-		name: userInfo.name || userInfo.email,
-		image: typeof providerUserAttributes.image === "string" ? providerUserAttributes.image : void 0,
-		emailVerified: userInfo.emailVerified
 	};
+	if (!userInfo.id) throw missingUserInfo(false);
 	const accountKey = {
 		issuer,
 		accountId: userInfo.id
 	};
-	const isTrustedProvider = "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(userInfo.email, provider.domain);
+	const mappedUser = await mapSSOProfile(options, {
+		protocol: "saml",
+		providerId,
+		accountKey,
+		providerUser: {
+			email: userInfo.email,
+			emailVerified: userInfo.emailVerified,
+			name: userInfo.name,
+			image: typeof providerUserAttributes.image === "string" ? providerUserAttributes.image : void 0
+		},
+		providerAttributes,
+		nameID: userInfo.id,
+		nameIDFormat
+	}, ctx.context.logger).catch((e) => {
+		redirectOnCodedAPIError(e);
+		throw e;
+	});
+	const email = mappedUser.email?.toLowerCase();
+	if (!email) throw missingUserInfo(true, Boolean(userInfo.email));
+	const providerUser = {
+		...providerUserAttributes,
+		email,
+		name: mappedUser.name || email,
+		image: mappedUser.image,
+		emailVerified: mappedUser.emailVerified
+	};
+	const mappedUserInfo = {
+		...providerUser,
+		id: accountKey.accountId
+	};
+	const isTrustedProvider = "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(email, provider.domain);
 	const callbackUrl = redirectCandidates.some(Boolean) ? samlRedirectUrl : ctx.context.baseURL;
-	const errorUrl = samlErrorRedirectUrl;
 	let result;
 	try {
 		if (options?.resolveUser) {
@@ -3057,10 +3147,7 @@ async function processSAMLResponse(ctx, params, options) {
 				...resolution.message === void 0 ? {} : { message: resolution.message }
 			});
 			const authentication = await handleOAuthUserInfo(ctx, {
-				userInfo: {
-					...providerUser,
-					id: userInfo.id
-				},
+				userInfo: mappedUserInfo,
 				account: {
 					providerId,
 					accountId: accountKey.accountId,
@@ -3092,17 +3179,16 @@ async function processSAMLResponse(ctx, params, options) {
 	} catch (e) {
 		const failedAuthentication = getFailedSSOAuthenticationResult(e);
 		if (failedAuthentication) result = failedAuthentication;
-		else if (isAPIError(e) && e.body?.code) throw ctx.redirect(buildSAMLRedirectUrl(errorUrl, {
-			error: e.body.code,
-			...e.body.message ? { error_description: e.body.message } : {}
-		}));
-		else throw e;
+		else {
+			redirectOnCodedAPIError(e);
+			throw e;
+		}
 	}
 	if (result.error) throw ctx.redirect(buildSAMLRedirectUrl(callbackUrl, { error: result.error.split(" ").join("_") }));
 	const { session, user } = result.data;
 	if (options?.provisionUser && (result.isRegister || options.provisionUserOnEveryLogin)) await options.provisionUser({
 		user,
-		userInfo,
+		userInfo: mappedUserInfo,
 		provider
 	});
 	await assignOrganizationFromProvider(ctx, {
@@ -3110,9 +3196,9 @@ async function processSAMLResponse(ctx, params, options) {
 		profile: {
 			providerType: "saml",
 			providerId,
-			accountId: userInfo.id,
-			email: userInfo.email,
-			emailVerified: userInfo.emailVerified,
+			accountId: accountKey.accountId,
+			email,
+			emailVerified: providerUser.emailVerified,
 			rawAttributes: attributes
 		},
 		provider,
@@ -3145,8 +3231,7 @@ async function processSAMLResponse(ctx, params, options) {
 	}
 	return samlRedirectUrl;
 }
-//#endregion
-//#region src/routes/sso.ts
+// src/routes/sso.ts
 const BUILT_IN_ACCOUNT_PROVIDER_IDS = [
 	"credential",
 	"email-otp",
@@ -3944,7 +4029,7 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 			...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, rawUserInfo[value]])),
 			id: readStringClaim(rawUserInfo, "sub"),
 			email: readEmailClaim(rawUserInfo),
-			emailVerified: options?.trustEmailVerified ? parseProviderEmailVerified(rawUserInfo[mapping.emailVerified || "email_verified"]) : false,
+			emailVerified: options?.trustEmailVerified ? parseStringBoolean(rawUserInfo[mapping.emailVerified || "email_verified"]) ?? false : false,
 			name: readStringClaim(rawUserInfo, mapping.name || "name"),
 			image: readStringClaim(rawUserInfo, mapping.image || "picture")
 		};
@@ -3955,24 +4040,47 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 			...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, idToken[value]])),
 			id: idToken.sub,
 			email: readEmailClaim(idToken),
-			emailVerified: options?.trustEmailVerified ? parseProviderEmailVerified(idToken[mapping.emailVerified || "email_verified"]) : false,
+			emailVerified: options?.trustEmailVerified ? parseStringBoolean(idToken[mapping.emailVerified || "email_verified"]) ?? false : false,
 			name: readStringClaim(idToken, mapping.name || "name"),
 			image: readStringClaim(idToken, mapping.image || "picture")
 		};
 	} else return redirectOIDCError("invalid_provider", "user_info_endpoint_not_found");
-	if (!userInfo.email || !userInfo.id) return redirectOIDCError("invalid_provider", "missing_user_info");
-	const userInfoEmail = userInfo.email;
-	const userInfoId = userInfo.id;
+	if (!userInfo.id) return redirectOIDCError("invalid_provider", "missing_user_info");
+	const accountKey = {
+		issuer: verifiedIdToken && readStringClaim(verifiedIdToken.payload, "iss") || provider.issuer,
+		accountId: userInfo.id
+	};
+	const mappedUser = await mapSSOProfile(options, {
+		protocol: "oidc",
+		providerId,
+		accountKey,
+		providerUser: {
+			email: userInfo.email,
+			emailVerified: userInfo.emailVerified === true,
+			name: userInfo.name,
+			image: userInfo.image
+		},
+		providerClaims: rawProfile ?? {},
+		verifiedIdTokenClaims: verifiedIdToken?.payload ?? {}
+	}, ctx.context.logger).catch((e) => {
+		if (isAPIError(e) && e.body?.code) redirectOIDCError(e.body.code, e.body.message);
+		throw e;
+	});
+	if (!mappedUser.email) {
+		ctx.context.logger.error("OIDC provider returned no email. Map an email claim, or create a placeholder with `mapProfileToUser`.", { providerId });
+		return redirectOIDCError("invalid_provider", "missing_user_info");
+	}
+	const userInfoEmail = mappedUser.email;
 	const providerUser = {
 		...Object.fromEntries(Object.entries(userInfo).filter(([key]) => key !== "id")),
 		email: userInfoEmail,
-		name: typeof userInfo.name === "string" ? userInfo.name : "",
-		image: typeof userInfo.image === "string" ? userInfo.image : void 0,
-		emailVerified: options?.trustEmailVerified ? userInfo.emailVerified === true : false
+		name: mappedUser.name ?? "",
+		image: mappedUser.image,
+		emailVerified: mappedUser.emailVerified
 	};
-	const accountKey = {
-		issuer: verifiedIdToken && readStringClaim(verifiedIdToken.payload, "iss") || provider.issuer,
-		accountId: userInfoId
+	const mappedUserInfo = {
+		...providerUser,
+		id: accountKey.accountId
 	};
 	const isTrustedProvider = "domainVerified" in provider && provider.domainVerified === true && validateEmailDomain(userInfoEmail, provider.domain);
 	let linked;
@@ -4003,19 +4111,12 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 				...resolution.message === void 0 ? {} : { message: resolution.message }
 			});
 			const authentication = await handleOAuthUserInfo(ctx, {
-				userInfo: {
-					...providerUser,
-					email: providerUser.email,
-					name: providerUser.name,
-					id: userInfoId,
-					image: providerUser.image,
-					emailVerified: providerUser.emailVerified
-				},
+				userInfo: mappedUserInfo,
 				account: {
 					idToken: tokenResponse.idToken,
 					accessToken: tokenResponse.accessToken,
 					refreshToken: tokenResponse.refreshToken,
-					accountId: userInfoId,
+					accountId: accountKey.accountId,
 					providerId: provider.providerId,
 					accessTokenExpiresAt: tokenResponse.accessTokenExpiresAt,
 					refreshTokenExpiresAt: tokenResponse.refreshTokenExpiresAt,
@@ -4054,7 +4155,7 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 	const { session, user } = linked.data;
 	if (options?.provisionUser && (linked.isRegister || options.provisionUserOnEveryLogin)) await options.provisionUser({
 		user,
-		userInfo,
+		userInfo: mappedUserInfo,
 		token: tokenResponse,
 		provider
 	});
@@ -4063,10 +4164,10 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 		profile: {
 			providerType: "oidc",
 			providerId: provider.providerId,
-			accountId: userInfoId,
+			accountId: accountKey.accountId,
 			email: userInfoEmail,
-			emailVerified: Boolean(userInfo.emailVerified),
-			rawAttributes: userInfo
+			emailVerified: providerUser.emailVerified,
+			rawAttributes: mappedUserInfo
 		},
 		provider,
 		token: tokenResponse,
@@ -4428,7 +4529,7 @@ const initiateSLO = (options) => {
 		const session = ctx.context.session;
 		const sessionLookupKey = `${SAML_SESSION_BY_ID_PREFIX}${session.session.id}`;
 		const sessionLookup = await ctx.context.internalAdapter.findVerificationValue(sessionLookupKey);
-		let nameID = session.user.email;
+		let nameID;
 		let sessionIndex;
 		let samlSessionKey;
 		if (sessionLookup) {
@@ -4437,11 +4538,15 @@ const initiateSLO = (options) => {
 			if (stored) {
 				const data = safeJsonParse(stored.value);
 				if (data) {
-					nameID = data.nameID || nameID;
+					nameID = data.nameID;
 					sessionIndex = data.sessionIndex;
 				}
 			}
 		}
+		if (!nameID) {
+			const [account] = (await ctx.context.internalAdapter.findAccounts(session.user.id)).filter((account) => account.providerId === providerId).sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+			nameID = account?.accountId ?? session.user.email;
+		}
 		const logoutRequest = sp.createLogoutRequest(idp, "redirect", {
 			logoutNameID: nameID,
 			sessionIndex,
@@ -4460,8 +4565,7 @@ const initiateSLO = (options) => {
 		throw ctx.redirect(logoutRequest.context);
 	});
 };
-//#endregion
-//#region src/index.ts
+// src/index.ts
 saml.setSchemaValidator({ async validate(xml) {
 	if (XMLValidator.validate(xml, { allowBooleanAttributes: true }) === true) return "SUCCESS_VALIDATE_XML";
 	throw "ERR_INVALID_XML";
@@ -4506,6 +4610,53 @@ function assertNoAdditionalFieldCollisions(options) {
 		if (builtInFieldNames.has(fieldName)) throw new Error(`ssoProvider additional field "${key}" maps to built-in field "${fieldName}"`);
 	}
 }
+const SAML_SESSION_RECORD_PAGE_SIZE = 100;
+async function findSAMLSessionRecord(ctx, identifier, isOwnRecord) {
+	for (let offset = 0;; offset += SAML_SESSION_RECORD_PAGE_SIZE) {
+		const page = await ctx.adapter.findMany({
+			model: "verification",
+			where: [{
+				field: "identifier",
+				value: identifier
+			}],
+			sortBy: {
+				field: "createdAt",
+				direction: "desc"
+			},
+			limit: SAML_SESSION_RECORD_PAGE_SIZE,
+			offset
+		});
+		const record = page.find(isOwnRecord);
+		if (record || page.length < SAML_SESSION_RECORD_PAGE_SIZE) return record;
+	}
+}
+/**
+* SLO records are written with the session's expiry at sign-in. Move it when a
+* refresh extends the session, so expired-row cleanup doesn't drop them early.
+*/
+async function extendSAMLSessionRecords(ctx, session) {
+	const lookupKey = `${SAML_SESSION_BY_ID_PREFIX}${session.id}`;
+	const lookup = await ctx.internalAdapter.findVerificationValue(lookupKey);
+	const expiresAt = new Date(session.expiresAt);
+	if (!lookup || new Date(lookup.expiresAt) >= expiresAt) return;
+	const isOwnRecord = (record) => safeJsonParse(record.value)?.sessionId === session.id;
+	const latest = await ctx.internalAdapter.findVerificationValue(lookup.value);
+	const secondaryStorageOnly = ctx.options.secondaryStorage && !ctx.options.verification?.storeInDatabase;
+	if (latest && secondaryStorageOnly) {
+		if (isOwnRecord(latest)) await ctx.internalAdapter.updateVerificationByIdentifier(lookup.value, { expiresAt });
+	} else if (latest) {
+		const record = await findSAMLSessionRecord(ctx, latest.identifier, isOwnRecord);
+		if (record) await ctx.adapter.update({
+			model: "verification",
+			where: [{
+				field: "id",
+				value: record.id
+			}],
+			update: { expiresAt }
+		});
+	}
+	await ctx.internalAdapter.updateVerificationByIdentifier(lookupKey, { expiresAt });
+}
 function sso(options) {
 	assertNoAdditionalFieldCollisions(options);
 	const optionsWithStore = options;
@@ -4538,8 +4689,13 @@ function sso(options) {
 		version: PACKAGE_VERSION,
 		init(ctx) {
 			const existing = ctx.skipOriginCheck;
-			if (existing === true) return {};
-			return { context: { skipOriginCheck: [...Array.isArray(existing) ? existing : [], ...SAML_SKIP_ORIGIN_CHECK_PATHS] } };
+			return {
+				...existing !== true && { context: { skipOriginCheck: [...Array.isArray(existing) ? existing : [], ...SAML_SKIP_ORIGIN_CHECK_PATHS] } },
+				options: { databaseHooks: { session: { update: { async after(session) {
+					if (!options?.saml?.enableSingleLogout) return;
+					await extendSAMLSessionRecords(ctx, session).catch((error) => ctx.logger.warn("Failed to extend SAML session records", { error }));
+				} } } } }
+			};
 		},
 		endpoints,
 		hooks: {
@@ -4629,5 +4785,4 @@ function sso(options) {
 		options
 	};
 }
-//#endregion
 export { DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, DigestAlgorithm, DiscoveryError, KeyEncryptionAlgorithm, REQUIRED_DISCOVERY_FIELDS, SignatureAlgorithm, computeDiscoveryUrl, deriveSAMLIdentityProviderEntityID, deriveSAMLServiceProviderPolicy, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };

package/dist/version-D4csRLQZ.mjs

@@ -0,0 +1,3 @@
+// src/version.ts
+const PACKAGE_VERSION = "1.8.0-beta.9";
+export { PACKAGE_VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/sso",
-  "version": "1.8.0-beta.7",
+  "version": "1.8.0-beta.9",
   "description": "SSO plugin for Better Auth",
   "type": "module",
   "license": "MIT",
@@ -64,24 +64,24 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
+    "@better-auth/core": "1.8.0-beta.9",
+    "@better-auth/kysely-adapter": "1.8.0-beta.9",
     "@types/body-parser": "^1.19.6",
     "@types/express": "^5.0.6",
+    "better-auth": "1.8.0-beta.9",
     "better-call": "1.4.5",
     "body-parser": "^2.3.0",
     "express": "^5.2.1",
     "kysely": "^0.28.17 || ^0.29.0",
     "oauth2-mock-server": "^9.0.0",
-    "tsdown": "0.23.1",
-    "@better-auth/kysely-adapter": "1.8.0-beta.7",
-    "better-auth": "1.8.0-beta.7",
-    "@better-auth/core": "1.8.0-beta.7"
+    "tsdown": "0.23.1"
   },
   "peerDependencies": {
+    "@better-auth/core": "^1.8.0-beta.9",
     "@better-auth/utils": "^0.4.2 || ^0.5.0",
     "@better-fetch/fetch": "1.3.3",
-    "better-call": "1.4.5",
-    "@better-auth/core": "^1.8.0-beta.7",
-    "better-auth": "^1.8.0-beta.7"
+    "better-auth": "^1.8.0-beta.9",
+    "better-call": "1.4.5"
   },
   "scripts": {
     "build": "tsdown",

package/dist/version-B5en_Bdq.mjs

@@ -1,5 +0,0 @@
-//#endregion
-//#region src/version.ts
-const PACKAGE_VERSION = "1.8.0-beta.7";
-//#endregion
-export { PACKAGE_VERSION as t };