@better-auth/core 1.7.0-beta.3 → 1.7.0-beta.5

package/dist/oauth2/validate-authorization-code.mjs

@@ -1,39 +1,32 @@
-import { resolveAssertionParams } from "./client-assertion.mjs";
 import { getOAuth2Tokens } from "./utils.mjs";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { createRemoteJWKSet, jwtVerify } from "jose";
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/validate-authorization-code.ts
-async function authorizationCodeRequest({ code, codeVerifier, redirectURI, options, authentication, clientAssertion, tokenEndpoint, deviceId, headers, additionalParams = {}, resource }) {
+async function authorizationCodeRequest({ code, codeVerifier, redirectURI, options, authentication, tokenEndpointAuth, tokenEndpoint, deviceId, headers, additionalParams = {}, resource }) {
 	options = typeof options === "function" ? await options() : options;
-	if (authentication === "private_key_jwt") {
-		if (!clientAssertion) throw new Error("private_key_jwt authentication requires a clientAssertion configuration");
-		const assertionParams = await resolveAssertionParams({
-			clientAssertion,
-			clientId: Array.isArray(options.clientId) ? options.clientId[0] : options.clientId,
-			tokenEndpoint
-		});
-		additionalParams = {
-			...additionalParams,
-			...assertionParams
-		};
-	}
-	return createAuthorizationCodeRequest({
+	const request = buildAuthorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
-		authentication,
 		deviceId,
 		headers,
 		additionalParams,
 		resource
 	});
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "authorization_code",
+		tokenEndpointAuth,
+		authentication
+	});
+	return request;
 }
-/**
-* @deprecated use async'd authorizationCodeRequest instead
-*/
-function createAuthorizationCodeRequest({ code, codeVerifier, redirectURI, options, authentication, deviceId, headers, additionalParams = {}, resource }) {
+function buildAuthorizationCodeRequest({ code, codeVerifier, redirectURI, options, deviceId, headers, additionalParams = {}, resource }) {
 	const body = new URLSearchParams();
 	const requestHeaders = {
 		"content-type": "application/x-www-form-urlencoded",
@@ -48,26 +41,20 @@ function createAuthorizationCodeRequest({ code, codeVerifier, redirectURI, optio
 	body.set("redirect_uri", options.redirectURI || redirectURI);
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
-	const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
-	if (authentication === "basic") requestHeaders["authorization"] = `Basic ${base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`)}`;
-	else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) body.set("client_secret", options.clientSecret);
-	}
 	for (const [key, value] of Object.entries(additionalParams)) if (!body.has(key)) body.append(key, value);
 	return {
 		body,
 		headers: requestHeaders
 	};
 }
-async function validateAuthorizationCode({ code, codeVerifier, redirectURI, options, tokenEndpoint, authentication, clientAssertion, deviceId, headers, additionalParams = {}, resource }) {
+async function validateAuthorizationCode({ code, codeVerifier, redirectURI, options, tokenEndpoint, authentication, tokenEndpointAuth, deviceId, headers, additionalParams = {}, resource }) {
 	const { body, headers: requestHeaders } = await authorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		deviceId,
 		headers,
@@ -89,4 +76,4 @@ async function validateToken(token, jwksEndpoint, options) {
 	});
 }
 //#endregion
-export { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken };
+export { authorizationCodeRequest, validateAuthorizationCode, validateToken };

package/dist/oauth2/verify-id-token.d.mts

@@ -0,0 +1,26 @@
+import { UpstreamProvider } from "./oauth-provider.mjs";
+
+//#region src/oauth2/verify-id-token.d.ts
+/**
+ * Whether a provider can verify a client-submitted id_token.
+ *
+ * A provider supports id_token sign-in when it declares an {@link UpstreamProvider.idToken}
+ * verification config, or when the integrator supplies a `verifyIdToken` override on the
+ * provider options. A provider whose options set `disableIdTokenSignIn`, or that declares
+ * neither, rejects the client id_token sign-in path with `ID_TOKEN_NOT_SUPPORTED`.
+ */
+declare function supportsIdTokenSignIn(provider: UpstreamProvider<any, any>): boolean;
+/**
+ * Verify a client-submitted id_token against a provider's verification config.
+ *
+ * This is the single id_token verifier for every social provider. Providers no longer
+ * implement their own boolean `verifyIdToken`; they declare an {@link UpstreamProvider.idToken}
+ * config and this function performs the cryptographic check. The contract is fail-closed: a
+ * provider without a config (and without an integrator `verifyIdToken` override) returns
+ * `false`, so a forged token can never be accepted by omission.
+ *
+ * @returns `true` only when the token is authentic for the provider.
+ */
+declare function verifyProviderIdToken(provider: UpstreamProvider<any, any>, token: string, nonce?: string): Promise<boolean>;
+//#endregion
+export { supportsIdTokenSignIn, verifyProviderIdToken };

package/dist/oauth2/verify-id-token.mjs

@@ -0,0 +1,62 @@
+import { decodeProtectedHeader, jwtVerify } from "jose";
+//#region src/oauth2/verify-id-token.ts
+async function sha256Hex(value) {
+	const data = new TextEncoder().encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function nonceMatches(claimNonce, nonce, comparison = "exact") {
+	if (typeof claimNonce !== "string") return false;
+	if (claimNonce === nonce) return true;
+	if (comparison === "exact-or-sha256") return claimNonce === await sha256Hex(nonce);
+	return false;
+}
+/**
+* Whether a provider can verify a client-submitted id_token.
+*
+* A provider supports id_token sign-in when it declares an {@link UpstreamProvider.idToken}
+* verification config, or when the integrator supplies a `verifyIdToken` override on the
+* provider options. A provider whose options set `disableIdTokenSignIn`, or that declares
+* neither, rejects the client id_token sign-in path with `ID_TOKEN_NOT_SUPPORTED`.
+*/
+function supportsIdTokenSignIn(provider) {
+	const options = provider.options ?? {};
+	if (options.disableIdTokenSignIn) return false;
+	return Boolean(provider.idToken || options.verifyIdToken);
+}
+/**
+* Verify a client-submitted id_token against a provider's verification config.
+*
+* This is the single id_token verifier for every social provider. Providers no longer
+* implement their own boolean `verifyIdToken`; they declare an {@link UpstreamProvider.idToken}
+* config and this function performs the cryptographic check. The contract is fail-closed: a
+* provider without a config (and without an integrator `verifyIdToken` override) returns
+* `false`, so a forged token can never be accepted by omission.
+*
+* @returns `true` only when the token is authentic for the provider.
+*/
+async function verifyProviderIdToken(provider, token, nonce) {
+	const options = provider.options ?? {};
+	if (options.disableIdTokenSignIn) return false;
+	try {
+		if (options.verifyIdToken) return await options.verifyIdToken(token, nonce);
+		const config = provider.idToken;
+		if (!config) return false;
+		if ("verify" in config) return await config.verify(token, nonce);
+		if (token.split(".").length !== 3) return config.allowOpaqueToken === true;
+		const { alg } = decodeProtectedHeader(token);
+		const { payload } = await jwtVerify(token, config.jwks, {
+			issuer: config.issuer,
+			audience: config.audience,
+			algorithms: config.algorithms ?? (alg ? [alg] : void 0),
+			maxTokenAge: config.maxTokenAge
+		});
+		if (nonce && !await nonceMatches(payload.nonce, nonce, config.nonceComparison)) return false;
+		if (config.verifyClaims && !config.verifyClaims(payload)) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { supportsIdTokenSignIn, verifyProviderIdToken };

package/dist/oauth2/verify.d.mts

@@ -14,6 +14,20 @@ interface VerifyAccessTokenRemote {
    * is also still active.
    */
   force?: boolean;
+  /**
+   * Accept introspection responses that omit the `aud` claim even when a
+   * required `audience` is configured in `verifyOptions`.
+   *
+   * By default verification fails closed: if you configure an `audience` and
+   * the introspection response has no `aud` (or a mismatching one), the token
+   * is rejected. Some authorization servers legitimately omit `aud` from
+   * introspection responses (it is OPTIONAL per RFC 7662 §2.2); only enable
+   * this if you trust the issuer to bind the token to this resource through
+   * another mechanism, as it skips the audience check in that case.
+   *
+   * @default false
+   */
+  allowMissingAudience?: boolean;
 }
 /**
  * Performs local verification of an access token for your APIs.

package/dist/oauth2/verify.mjs

@@ -1,10 +1,23 @@
 import { logger } from "../env/logger.mjs";
 import { APIError } from "better-call";
-import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
+import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/verify.ts
-/** Last fetched jwks used locally in getJwks @internal */
-let jwks;
+const joseInfrastructureErrorCodes = new Set([
+	errors.JWKSTimeout.code,
+	errors.JWKSInvalid.code,
+	errors.JWKSMultipleMatchingKeys.code
+]);
+function isJoseInfrastructureError(error) {
+	return joseInfrastructureErrorCodes.has(error.code);
+}
+const jwksCache = /* @__PURE__ */ new Map();
+/**
+* How long a cached JWKS is trusted before it is refetched
+*
+* @internal
+*/
+const JWKS_CACHE_TTL_MS = 300 * 1e3;
 /**
 * Performs local verification of an access token for your APIs.
 *
@@ -28,15 +41,25 @@ async function getJwks(token, opts) {
 		if (error instanceof Error) throw error;
 		throw new Error(error);
 	}
-	if (!jwtHeaders.kid) throw new Error("Missing jwt kid");
-	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
-		jwks = typeof opts.jwksFetch === "string" ? await betterFetch(opts.jwksFetch, { headers: { Accept: "application/json" } }).then(async (res) => {
+	if (!jwtHeaders.kid) throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
+	const kid = jwtHeaders.kid;
+	const cacheKey = opts.jwksFetch;
+	const cached = jwksCache.get(cacheKey);
+	const isFresh = cached ? Date.now() - cached.fetchedAt < JWKS_CACHE_TTL_MS : false;
+	const hasKid = cached?.jwks.keys.some((jwk) => jwk.kid === kid) ?? false;
+	if (!cached || !isFresh || !hasKid) {
+		const jwks = typeof opts.jwksFetch === "string" ? await betterFetch(opts.jwksFetch, { headers: { Accept: "application/json" } }).then(async (res) => {
 			if (res.error) throw new Error(`Jwks failed: ${res.error.message ?? res.error.statusText}`);
 			return res.data;
 		}) : await opts.jwksFetch();
 		if (!jwks) throw new Error("No jwks found");
+		jwksCache.set(cacheKey, {
+			jwks,
+			fetchedAt: Date.now()
+		});
+		return jwks;
 	}
-	return jwks;
+	return cached.jwks;
 }
 /**
 * Performs local verification of an access token for your API.
@@ -51,9 +74,11 @@ async function verifyAccessToken(token, opts) {
 			verifyOptions: opts.verifyOptions
 		});
 	} catch (error) {
-		if (error instanceof Error) if (error.name === "TypeError" || error.name === "JWSInvalid") {} else if (error.name === "JWTExpired") throw new APIError("UNAUTHORIZED", { message: "token expired" });
-		else if (error.name === "JWTInvalid") throw new APIError("UNAUTHORIZED", { message: "token invalid" });
-		else throw error;
+		if (error instanceof Error) if (error.name === "TypeError" || error.name === "JWSInvalid") {} else if (error instanceof errors.JWTExpired) throw new APIError("UNAUTHORIZED", { message: "token expired" });
+		else if (error instanceof errors.JOSEError) {
+			if (isJoseInfrastructureError(error)) throw error;
+			throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
+		} else throw error;
 		else throw new Error(error);
 	}
 	if (opts?.remoteVerify) {
@@ -75,8 +100,9 @@ async function verifyAccessToken(token, opts) {
 		if (!introspect.active) throw new APIError("UNAUTHORIZED", { message: "token inactive" });
 		try {
 			const unsecuredJwt = new UnsecuredJWT(introspect).encode();
-			const { audience: _audience, ...verifyOptions } = opts.verifyOptions;
-			payload = (introspect.aud ? UnsecuredJWT.decode(unsecuredJwt, opts.verifyOptions) : UnsecuredJWT.decode(unsecuredJwt, verifyOptions)).payload;
+			const { audience: _audience, ...verifyOptionsNoAudience } = opts.verifyOptions;
+			const skipAudience = !introspect.aud && opts.remoteVerify.allowMissingAudience === true;
+			payload = UnsecuredJWT.decode(unsecuredJwt, skipAudience ? verifyOptionsNoAudience : opts.verifyOptions).payload;
 		} catch (error) {
 			throw new Error(error);
 		}

package/dist/social-providers/apple.d.mts

@@ -1,4 +1,6 @@
 import { OAuth2Tokens, ProviderOptions } from "../oauth2/oauth-provider.mjs";
+import * as jose from "jose";
+
 //#region src/social-providers/apple.d.ts
 interface AppleProfile {
   /**
@@ -67,10 +69,12 @@ interface AppleOptions extends ProviderOptions<AppleProfile> {
 declare const apple: (options: AppleOptions) => {
   id: "apple";
   name: string;
+  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
-    redirectURI
+    redirectURI,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -78,7 +82,11 @@ declare const apple: (options: AppleOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
-  }): Promise<URL>;
+    additionalParams?: Record<string, string> | undefined;
+  }): Promise<{
+    url: URL;
+    requestedScopes: string[];
+  }>;
   validateAuthorizationCode: ({
     code,
     codeVerifier,
@@ -89,27 +97,17 @@ declare const apple: (options: AppleOptions) => {
     codeVerifier?: string | undefined;
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens>;
-  verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+  idToken: {
+    jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+    issuer: string;
+    audience: string | string[];
+    maxTokenAge: string;
+    nonceComparison: "exact-or-sha256";
+  };
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
     user?: {
-      name /**
-            * An Integer value that indicates whether the user appears to be a real
-            * person. Use the value of this claim to mitigate fraud. The possible
-            * values are: 0 (or Unsupported), 1 (or Unknown), 2 (or LikelyReal). For
-            * more information, see ASUserDetectionStatus. This claim is present only
-            * in iOS 14 and later, macOS 11 and later, watchOS 7 and later, tvOS 14
-            * and later. The claim isn’t present or supported for web-based apps.
-            */?
-      /**
-      * An Integer value that indicates whether the user appears to be a real
-      * person. Use the value of this claim to mitigate fraud. The possible
-      * values are: 0 (or Unsupported), 1 (or Unknown), 2 (or LikelyReal). For
-      * more information, see ASUserDetectionStatus. This claim is present only
-      * in iOS 14 and later, macOS 11 and later, watchOS 7 and later, tvOS 14
-      * and later. The claim isn’t present or supported for web-based apps.
-      */
-      : {
+      name?: {
         firstName?: string;
         lastName?: string;
       };

package/dist/social-providers/apple.mjs

@@ -1,34 +1,35 @@
 import { APIError, BetterAuthError } from "../error/index.mjs";
 import { logger } from "../env/logger.mjs";
+import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { getPrimaryClientId } from "../oauth2/utils.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { decodeJwt, importJWK } from "jose";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/apple.ts
+const APPLE_DEFAULT_SCOPES = ["email", "name"];
 const apple = (options) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";
 	return {
 		id: "apple",
 		name: "Apple",
-		async createAuthorizationURL({ state, scopes, redirectURI }) {
+		callbackPath: "/callback/apple",
+		async createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error("Client ID and client secret are required for Apple. Make sure to provide them in the options.");
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
 			}
-			const _scope = options.disableDefaultScope ? [] : ["email", "name"];
-			if (options.scope) _scope.push(...options.scope);
-			if (scopes) _scope.push(...scopes);
-			return await createAuthorizationURL({
+			return createAuthorizationURL({
 				id: "apple",
 				options,
 				authorizationEndpoint: "https://appleid.apple.com/auth/authorize",
-				scopes: _scope,
+				scopes: resolveRequestedScopes(options, APPLE_DEFAULT_SCOPES, scopes),
 				state,
 				redirectURI,
 				responseMode: "form_post",
-				responseType: "code id_token"
+				responseType: "code id_token",
+				additionalParams
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
@@ -40,26 +41,12 @@ const apple = (options) => {
 				tokenEndpoint
 			});
 		},
-		async verifyIdToken(token, nonce) {
-			if (options.disableIdTokenSignIn) return false;
-			if (options.verifyIdToken) return options.verifyIdToken(token, nonce);
-			try {
-				const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
-				if (!kid || !jwtAlg) return false;
-				const { payload: jwtClaims } = await jwtVerify(token, await getApplePublicKey(kid), {
-					algorithms: [jwtAlg],
-					issuer: "https://appleid.apple.com",
-					audience: options.audience && options.audience.length ? options.audience : options.appBundleIdentifier ? options.appBundleIdentifier : options.clientId,
-					maxTokenAge: "1h"
-				});
-				["email_verified", "is_private_email"].forEach((field) => {
-					if (jwtClaims[field] !== void 0) jwtClaims[field] = Boolean(jwtClaims[field]);
-				});
-				if (nonce && jwtClaims.nonce !== nonce) return false;
-				return !!jwtClaims;
-			} catch {
-				return false;
-			}
+		idToken: {
+			jwks: (header) => getApplePublicKey(header.kid),
+			issuer: "https://appleid.apple.com",
+			audience: options.audience && options.audience.length ? options.audience : options.appBundleIdentifier ? options.appBundleIdentifier : options.clientId,
+			maxTokenAge: "1h",
+			nonceComparison: "exact-or-sha256"
 		},
 		refreshAccessToken: options.refreshAccessToken ? options.refreshAccessToken : async (refreshToken) => {
 			return refreshAccessToken({

package/dist/social-providers/atlassian.d.mts

@@ -21,11 +21,13 @@ interface AtlassianOptions extends ProviderOptions<AtlassianProfile> {
 declare const atlassian: (options: AtlassianOptions) => {
   id: "atlassian";
   name: string;
+  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
     codeVerifier,
-    redirectURI
+    redirectURI,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -33,7 +35,11 @@ declare const atlassian: (options: AtlassianOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
-  }): Promise<URL>;
+    additionalParams?: Record<string, string> | undefined;
+  }): Promise<{
+    url: URL;
+    requestedScopes: string[];
+  }>;
   validateAuthorizationCode: ({
     code,
     codeVerifier,

package/dist/social-providers/atlassian.mjs

@@ -1,33 +1,36 @@
 import { BetterAuthError } from "../error/index.mjs";
 import { logger } from "../env/logger.mjs";
+import { resolveRequestedScopes } from "../oauth2/scopes.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/atlassian.ts
+const ATLASSIAN_DEFAULT_SCOPES = ["read:jira-user", "offline_access"];
 const atlassian = (options) => {
 	const tokenEndpoint = "https://auth.atlassian.com/oauth/token";
 	return {
 		id: "atlassian",
 		name: "Atlassian",
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		callbackPath: "/callback/atlassian",
+		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI, additionalParams }) {
 			if (!options.clientId || !options.clientSecret) {
 				logger.error("Client Id and Secret are required for Atlassian");
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
 			}
 			if (!codeVerifier) throw new BetterAuthError("codeVerifier is required for Atlassian");
-			const _scopes = options.disableDefaultScope ? [] : ["read:jira-user", "offline_access"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
 			return createAuthorizationURL({
 				id: "atlassian",
 				options,
 				authorizationEndpoint: "https://auth.atlassian.com/authorize",
-				scopes: _scopes,
+				scopes: resolveRequestedScopes(options, ATLASSIAN_DEFAULT_SCOPES, scopes),
 				state,
 				codeVerifier,
 				redirectURI,
-				additionalParams: { audience: "api.atlassian.com" },
+				additionalParams: {
+					...additionalParams ?? {},
+					audience: "api.atlassian.com"
+				},
 				prompt: options.prompt
 			});
 		},

package/dist/social-providers/cognito.d.mts

@@ -1,4 +1,6 @@
 import { OAuth2Tokens, ProviderOptions } from "../oauth2/oauth-provider.mjs";
+import * as jose from "jose";
+
 //#region src/social-providers/cognito.d.ts
 interface CognitoProfile {
   sub: string;
@@ -30,15 +32,30 @@ interface CognitoOptions extends ProviderOptions<CognitoProfile> {
   region: string;
   userPoolId: string;
   requireClientSecret?: boolean | undefined;
+  /**
+   * Skip the Cognito hosted-UI identity-provider picker by preselecting an
+   * IdP (maps to the `identity_provider` query parameter on the authorize
+   * request). Accepts `"COGNITO"`, a SAML/OIDC provider name configured on
+   * the User Pool, or one of the social providers (`"Google"`, `"Facebook"`,
+   * `"LoginWithAmazon"`, `"SignInWithApple"`).
+   *
+   * Per-request overrides via `signIn.social({ additionalParams: { identity_provider } })`
+   * take precedence over this value.
+   *
+   * @see https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html
+   */
+  identityProvider?: string | undefined;
 }
 declare const cognito: (options: CognitoOptions) => {
   id: "cognito";
   name: string;
+  callbackPath: string;
   createAuthorizationURL({
     state,
     scopes,
     codeVerifier,
-    redirectURI
+    redirectURI,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -46,7 +63,11 @@ declare const cognito: (options: CognitoOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
-  }): Promise<URL>;
+    additionalParams?: Record<string, string> | undefined;
+  }): Promise<{
+    url: URL;
+    requestedScopes: string[];
+  }>;
   validateAuthorizationCode: ({
     code,
     codeVerifier,
@@ -58,7 +79,12 @@ declare const cognito: (options: CognitoOptions) => {
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
-  verifyIdToken(token: string, nonce: string | undefined): Promise<boolean>;
+  idToken: {
+    jwks: (header: jose.JWTHeaderParameters) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
+    issuer: string;
+    audience: string | string[];
+    maxTokenAge: string;
+  };
   getUserInfo(token: OAuth2Tokens & {
     user?: {
       name?: {