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

package/dist/oauth2/client-assertion.mjs

@@ -1,7 +1,7 @@
 import { SignJWT, importJWK, importPKCS8 } from "jose";
 //#region src/oauth2/client-assertion.ts
 /** Asymmetric signing algorithms compatible with private_key_jwt (RFC 7523). */
-const ASSERTION_SIGNING_ALGORITHMS = [
+const PRIVATE_KEY_JWT_SIGNING_ALGORITHMS = [
 	"RS256",
 	"RS384",
 	"RS512",
@@ -13,20 +13,46 @@ const ASSERTION_SIGNING_ALGORITHMS = [
 	"ES512",
 	"EdDSA"
 ];
+function assertSupportedPrivateKeyJwtAlgorithm(candidate) {
+	if (!PRIVATE_KEY_JWT_SIGNING_ALGORITHMS.includes(candidate)) throw new Error(`Unsupported private_key_jwt signing algorithm: ${candidate}. Use one of ${PRIVATE_KEY_JWT_SIGNING_ALGORITHMS.join(", ")}.`);
+}
+/**
+* Validates `private_key_jwt` options eagerly and returns the algorithm to
+* use for signing.
+*
+* Asserts that key material is configured, that any explicit `algorithm` is
+* supported, that any JWK-embedded `alg` is supported, and that the two
+* agree when both are set.
+*/
+function resolveValidPrivateKeyJwtOptions(options) {
+	if (!options.privateKeyJwk && !options.privateKeyPem) throw new Error("private_key_jwt requires either privateKeyJwk or privateKeyPem");
+	if (options.algorithm) assertSupportedPrivateKeyJwtAlgorithm(options.algorithm);
+	const jwkAlg = options.privateKeyJwk?.alg;
+	if (typeof jwkAlg === "string") assertSupportedPrivateKeyJwtAlgorithm(jwkAlg);
+	if (options.algorithm && typeof jwkAlg === "string" && options.algorithm !== jwkAlg) throw new Error(`JWK alg "${jwkAlg}" does not match configured algorithm "${options.algorithm}". Remove the JWK alg field, or pass an algorithm that matches the JWK.`);
+	return options.algorithm ?? (typeof jwkAlg === "string" ? jwkAlg : "RS256");
+}
 const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
 /**
 * Signs an RFC 7523 client assertion JWT for `private_key_jwt` authentication.
 *
-* The JWT contains: iss=clientId, sub=clientId, aud=tokenEndpoint,
-* exp=now+120s, jti=unique, iat=now.
+* The JWT contains these claims:
+*
+* - iss=clientId
+* - sub=clientId
+* - aud=tokenEndpoint
+* - exp=now + 120s
+* - jti=unique
+* - iat=now
 */
-async function signClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, privateKeyPem, kid, algorithm, expiresIn = 120 }) {
+async function signPrivateKeyJwtClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, privateKeyPem, kid, algorithm, expiresIn = 120 }) {
+	const resolvedAlg = resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk,
+		privateKeyPem,
+		algorithm
+	});
 	const resolvedKid = kid ?? privateKeyJwk?.kid;
-	const resolvedAlg = algorithm ?? privateKeyJwk?.alg ?? "RS256";
-	let key;
-	if (privateKeyJwk) key = await importJWK(privateKeyJwk, resolvedAlg);
-	else if (privateKeyPem) key = await importPKCS8(privateKeyPem, resolvedAlg);
-	else throw new Error("private_key_jwt requires either privateKeyJwk or privateKeyPem");
+	const key = privateKeyJwk ? await importJWK(privateKeyJwk, resolvedAlg) : await importPKCS8(privateKeyPem, resolvedAlg);
 	const now = Math.floor(Date.now() / 1e3);
 	const jti = crypto.randomUUID();
 	const header = {
@@ -37,28 +63,37 @@ async function signClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, pri
 	return new SignJWT({}).setProtectedHeader(header).setIssuer(clientId).setSubject(clientId).setAudience(tokenEndpoint).setIssuedAt(now).setExpirationTime(now + expiresIn).setJti(jti).sign(key);
 }
 /**
-* Resolves a ClientAssertionConfig into `client_assertion` + `client_assertion_type`
-* params for injection into a token request body.
+* Creates a client assertion getter for `private_key_jwt` authentication.
+*
+* Validates options eagerly (key material, supported algorithm, JWK alg
+* agreement) so misconfiguration surfaces at construction rather than on the
+* first token request. The returned function signs a fresh RFC 7523 JWT
+* assertion for every token endpoint request.
+*/
+function createPrivateKeyJwtClientAssertionGetter(options) {
+	resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk: options.privateKeyJwk,
+		privateKeyPem: options.privateKeyPem,
+		algorithm: options.algorithm
+	});
+	return ({ clientId, tokenEndpoint }) => signPrivateKeyJwtClientAssertion({
+		clientId,
+		tokenEndpoint,
+		privateKeyJwk: options.privateKeyJwk,
+		privateKeyPem: options.privateKeyPem,
+		kid: options.kid,
+		algorithm: options.algorithm,
+		expiresIn: options.expiresIn
+	});
+}
+/**
+* Resolves a client assertion getter into `client_assertion` + `client_assertion_type` params for injection into a token request body.
 */
-async function resolveAssertionParams({ clientAssertion, clientId, tokenEndpoint }) {
-	let assertion = clientAssertion.assertion;
-	if (!assertion) {
-		const audEndpoint = tokenEndpoint ?? clientAssertion.tokenEndpoint;
-		if (!audEndpoint) throw new Error("private_key_jwt requires a tokenEndpoint for the JWT audience claim");
-		assertion = await signClientAssertion({
-			clientId,
-			tokenEndpoint: audEndpoint,
-			privateKeyJwk: clientAssertion.privateKeyJwk,
-			privateKeyPem: clientAssertion.privateKeyPem,
-			kid: clientAssertion.kid,
-			algorithm: clientAssertion.algorithm,
-			expiresIn: clientAssertion.expiresIn
-		});
-	}
+async function resolveClientAssertionParams({ getClientAssertion, context }) {
 	return {
-		client_assertion: assertion,
+		client_assertion: await getClientAssertion(context),
 		client_assertion_type: CLIENT_ASSERTION_TYPE
 	};
 }
 //#endregion
-export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, resolveAssertionParams, signClientAssertion };
+export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion };

package/dist/oauth2/client-credentials-token.d.mts

@@ -1,59 +1,38 @@
-import { ClientAssertionConfig } from "./client-assertion.mjs";
 import { AwaitableFunction } from "../types/helper.mjs";
 import { OAuth2Tokens, ProviderOptions } from "./oauth-provider.mjs";
+import { TokenEndpointAuth, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
 
 //#region src/oauth2/client-credentials-token.d.ts
-declare function clientCredentialsTokenRequest({
-  options,
-  scope,
-  authentication,
-  clientAssertion,
-  tokenEndpoint,
-  resource
-}: {
+interface ClientCredentialsTokenRequestInput {
   options: AwaitableFunction<ProviderOptions>;
   scope?: string | undefined;
-  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-  clientAssertion?: ClientAssertionConfig | undefined; /** Token endpoint URL. Used as the JWT `aud` claim when signing assertions. */
+  authentication?: TokenEndpointSecretAuthentication | undefined;
+  tokenEndpointAuth?: TokenEndpointAuth | undefined;
   tokenEndpoint?: string | undefined;
   resource?: (string | string[]) | undefined;
-}): Promise<{
-  body: URLSearchParams;
-  headers: Record<string, any>;
-}>;
-/**
- * @deprecated use async'd clientCredentialsTokenRequest instead
- */
-declare function createClientCredentialsTokenRequest({
+}
+interface ClientCredentialsTokenInput extends ClientCredentialsTokenRequestInput {
+  tokenEndpoint: string;
+  scope: string;
+}
+declare function clientCredentialsTokenRequest({
   options,
   scope,
   authentication,
-  resource,
-  extraParams
-}: {
-  options: ProviderOptions;
-  scope?: string | undefined;
-  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-  resource?: (string | string[]) | undefined;
-  extraParams?: Record<string, string> | undefined;
-}): {
+  tokenEndpointAuth,
+  tokenEndpoint,
+  resource
+}: ClientCredentialsTokenRequestInput): Promise<{
   body: URLSearchParams;
-  headers: Record<string, any>;
-};
+  headers: Record<string, string>;
+}>;
 declare function clientCredentialsToken({
   options,
   tokenEndpoint,
   scope,
   authentication,
-  clientAssertion,
+  tokenEndpointAuth,
   resource
-}: {
-  options: AwaitableFunction<ProviderOptions>;
-  tokenEndpoint: string;
-  scope: string;
-  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-  clientAssertion?: ClientAssertionConfig | undefined;
-  resource?: (string | string[]) | undefined;
-}): Promise<OAuth2Tokens>;
+}: ClientCredentialsTokenInput): Promise<OAuth2Tokens>;
 //#endregion
-export { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest };
+export { clientCredentialsToken, clientCredentialsTokenRequest };

package/dist/oauth2/client-credentials-token.mjs

@@ -1,30 +1,25 @@
-import { resolveAssertionParams } from "./client-assertion.mjs";
-import { base64 } from "@better-auth/utils/base64";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/client-credentials-token.ts
-async function clientCredentialsTokenRequest({ options, scope, authentication, clientAssertion, tokenEndpoint, resource }) {
+async function clientCredentialsTokenRequest({ options, scope, authentication, tokenEndpointAuth, tokenEndpoint, resource }) {
 	options = typeof options === "function" ? await options() : options;
-	let extraParams;
-	if (authentication === "private_key_jwt") {
-		if (!clientAssertion) throw new Error("private_key_jwt authentication requires a clientAssertion configuration");
-		extraParams = await resolveAssertionParams({
-			clientAssertion,
-			clientId: Array.isArray(options.clientId) ? options.clientId[0] : options.clientId,
-			tokenEndpoint
-		});
-	}
-	return createClientCredentialsTokenRequest({
+	const request = buildClientCredentialsTokenRequest({
 		options,
 		scope,
-		authentication,
-		resource,
-		extraParams
+		resource
 	});
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "client_credentials",
+		tokenEndpointAuth,
+		authentication
+	});
+	return request;
 }
-/**
-* @deprecated use async'd clientCredentialsTokenRequest instead
-*/
-function createClientCredentialsTokenRequest({ options, scope, authentication, resource, extraParams }) {
+function buildClientCredentialsTokenRequest({ options, scope, resource, extraParams }) {
 	const body = new URLSearchParams();
 	const headers = {
 		"content-type": "application/x-www-form-urlencoded",
@@ -34,12 +29,6 @@ function createClientCredentialsTokenRequest({ options, scope, authentication, r
 	scope && body.set("scope", scope);
 	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") headers["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);
-	}
 	if (extraParams) {
 		for (const [key, value] of Object.entries(extraParams)) if (!body.has(key)) body.append(key, value);
 	}
@@ -48,12 +37,12 @@ function createClientCredentialsTokenRequest({ options, scope, authentication, r
 		headers
 	};
 }
-async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, clientAssertion, resource }) {
+async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, tokenEndpointAuth, resource }) {
 	const { body, headers } = await clientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		resource
 	});
@@ -75,4 +64,4 @@ async function clientCredentialsToken({ options, tokenEndpoint, scope, authentic
 	return tokens;
 }
 //#endregion
-export { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest };
+export { clientCredentialsToken, clientCredentialsTokenRequest };

package/dist/oauth2/create-authorization-url.d.mts

@@ -1,6 +1,14 @@
 import { AwaitableFunction } from "../types/helper.mjs";
 import { ProviderOptions } from "./oauth-provider.mjs";
 //#region src/oauth2/create-authorization-url.d.ts
+/**
+ * Query-parameter names that are populated by the framework as part of the
+ * authorization request and must not be overridden by caller-supplied
+ * `additionalParams`. Overriding `state`, PKCE, or `redirect_uri` would
+ * break the callback correlation and session pinning guarantees.
+ */
+declare const RESERVED_AUTHORIZATION_PARAMS: readonly ["state", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method", "scope"];
+declare const RESERVED_AUTHORIZATION_PARAMS_SET: ReadonlySet<string>;
 declare function createAuthorizationURL({
   id,
   options,
@@ -39,6 +47,9 @@ declare function createAuthorizationURL({
   responseMode?: string | undefined;
   additionalParams?: Record<string, string> | undefined;
   scopeJoiner?: string | undefined;
-}): Promise<URL>;
+}): Promise<{
+  url: URL;
+  requestedScopes: string[];
+}>;
 //#endregion
-export { createAuthorizationURL };
+export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/create-authorization-url.mjs

@@ -1,13 +1,30 @@
-import { generateCodeChallenge } from "./utils.mjs";
+import { generateCodeChallenge, getPrimaryClientId } from "./utils.mjs";
 //#region src/oauth2/create-authorization-url.ts
+/**
+* Query-parameter names that are populated by the framework as part of the
+* authorization request and must not be overridden by caller-supplied
+* `additionalParams`. Overriding `state`, PKCE, or `redirect_uri` would
+* break the callback correlation and session pinning guarantees.
+*/
+const RESERVED_AUTHORIZATION_PARAMS = [
+	"state",
+	"client_id",
+	"redirect_uri",
+	"response_type",
+	"code_challenge",
+	"code_challenge_method",
+	"scope"
+];
+const RESERVED_AUTHORIZATION_PARAMS_SET = new Set(RESERVED_AUTHORIZATION_PARAMS);
 async function createAuthorizationURL({ id, options, authorizationEndpoint, state, codeVerifier, scopes, claims, redirectURI, duration, prompt, accessType, responseType, display, loginHint, hd, responseMode, additionalParams, scopeJoiner }) {
 	options = typeof options === "function" ? await options() : options;
 	const url = new URL(options.authorizationEndpoint || authorizationEndpoint);
 	url.searchParams.set("response_type", responseType || "code");
-	const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	const primaryClientId = getPrimaryClientId(options.clientId);
+	if (!primaryClientId) throw new Error("OAuth provider requires clientId");
 	url.searchParams.set("client_id", primaryClientId);
 	url.searchParams.set("state", state);
-	if (scopes) url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
+	if (scopes?.length) url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
 	url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
 	duration && url.searchParams.set("duration", duration);
 	display && url.searchParams.set("display", display);
@@ -32,10 +49,14 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 			...claimsObj
 		} }));
 	}
-	if (additionalParams) Object.entries(additionalParams).forEach(([key, value]) => {
+	if (additionalParams) for (const [key, value] of Object.entries(additionalParams)) {
+		if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
 		url.searchParams.set(key, value);
-	});
-	return url;
+	}
+	return {
+		url,
+		requestedScopes: scopes ?? []
+	};
 }
 //#endregion
-export { createAuthorizationURL };
+export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/index.d.mts

@@ -1,9 +1,14 @@
-import { ASSERTION_SIGNING_ALGORITHMS, AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, ClientAssertionConfig, resolveAssertionParams, signClientAssertion } from "./client-assertion.mjs";
-import { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions } from "./oauth-provider.mjs";
-import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
-import { createAuthorizationURL } from "./create-authorization-url.mjs";
-import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
-import { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
-import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
+import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
+import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
+import { CLIENT_ASSERTION_TYPE, ClientAssertionContext, ClientAssertionGetter, ClientAssertionGrantType, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, PrivateKeyJwtClientAssertionGetterOptions, PrivateKeyJwtSigningAlgorithm, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } from "./client-assertion.mjs";
+import { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider } from "./oauth-provider.mjs";
+import { TokenEndpointAuth, TokenEndpointAuthMethod, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
+import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
+import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes } from "./scopes.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { ASSERTION_SIGNING_ALGORITHMS, type AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, type ClientAssertionConfig, type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, type ProviderOptions, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { type AuthorizationURLResult, CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, type GrantAuthority, type OAuth2Tokens, type OAuth2UserInfo, type OAuthIdTokenConfig, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, type PrivateKeyJwtClientAssertionGetterOptions, type PrivateKeyJwtSigningAlgorithm, type ProviderGrantAuthority, type ProviderOptions, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, type UpstreamProvider, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/index.mjs

@@ -1,8 +1,12 @@
-import { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, resolveAssertionParams, signClientAssertion } from "./client-assertion.mjs";
-import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
-import { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
-import { createAuthorizationURL } from "./create-authorization-url.mjs";
-import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
-import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
+import { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes } from "./scopes.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
+import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
+import { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } from "./client-assertion.mjs";
+import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/oauth-provider.d.mts

@@ -1,5 +1,53 @@
 import { Awaitable, LiteralString } from "../types/helper.mjs";
+import { JWTVerifyGetKey } from "jose";
+
 //#region src/oauth2/oauth-provider.d.ts
+/**
+ * id_token verification config for a social provider.
+ *
+ * Declares how a client-submitted id_token is verified. The shared verifier
+ * (`verifyProviderIdToken`) consumes this instead of each provider implementing its own
+ * boolean check, so verification is centralized and fail-closed: a provider without a config
+ * cannot accept a forged token by omission.
+ */
+type OAuthIdTokenConfig = {
+  /**
+   * JWKS resolver used to verify the JWS signature. Accepts a jose
+   * `createRemoteJWKSet` resolver or a key-resolving function
+   * `(protectedHeader) => key`.
+   */
+  jwks: JWTVerifyGetKey; /** Expected `iss`. Omit for providers whose issuer varies per tenant. */
+  issuer?: (string | string[]) | undefined; /** Expected `aud`, usually the client ID. */
+  audience: string | string[]; /** Permitted JWS algorithms. Defaults to the token's `alg` header. */
+  algorithms?: string[] | undefined; /** Maximum token age passed to jose (e.g. `"1h"`). */
+  maxTokenAge?: string | undefined;
+  /**
+   * How the `nonce` claim is compared to the expected nonce.
+   * - `"exact"` (default): strict equality.
+   * - `"exact-or-sha256"`: matches the raw nonce or its SHA-256 hex digest (Apple).
+   */
+  nonceComparison?: ("exact" | "exact-or-sha256") | undefined;
+  /**
+   * Accept non-JWS (opaque) tokens without signature verification. Identity is then
+   * resolved by getUserInfo from the access token via the provider userinfo endpoint,
+   * which validates it (e.g. Facebook Graph access tokens).
+   */
+  allowOpaqueToken?: boolean | undefined;
+  /**
+   * Provider-specific claim check applied after the signature, issuer,
+   * audience, max-age, and nonce checks pass. Return `false` to reject the
+   * token. Used to enforce constraints the standard checks cannot express,
+   * e.g. Google's hosted-domain (`hd`) restriction. Omitted by providers
+   * that have no extra claim requirement.
+   */
+  verifyClaims?: ((claims: Record<string, unknown>) => boolean) | undefined;
+} | {
+  /**
+   * Custom verifier for providers that cannot verify against a local JWKS, such as a
+   * remote verification endpoint (e.g. LINE).
+   */
+  verify: (token: string, nonce?: string) => Promise<boolean>;
+};
 interface OAuth2Tokens {
   tokenType?: string | undefined;
   accessToken?: string | undefined;
@@ -21,8 +69,58 @@ type OAuth2UserInfo = {
   image?: string | undefined;
   emailVerified: boolean;
 };
-interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
+/**
+ * The result of building a provider authorization URL.
+ *
+ * `requestedScopes` is the effective set of scopes encoded in the URL (the
+ * provider's built-in defaults + configured `options.scope` + per-request
+ * `scopes`, composed by `resolveRequestedScopes`). Callers persist it so the
+ * callback can fall back to the request when the provider omits `scope` from
+ * its token response (RFC 6749 §5.1).
+ */
+interface AuthorizationURLResult {
+  url: URL;
+  requestedScopes: string[];
+}
+/**
+ * How much an RP trusts a provider's echoed token-response `scope` when
+ * persisting `account.grantedScopes`.
+ *
+ * - `"full-grant"`: the echo is the user's complete current grant, so the seam
+ *   replaces the stored grant with it. This is the only path that may narrow
+ *   the grant. Declare it only for providers whose token response reports the
+ *   full combined grant, e.g. Google with `include_granted_scopes`.
+ * - `"projection"`: the echo is this request's subset, so the seam unions it
+ *   onto the stored grant. The safe default for every provider.
+ * - `"absent-echo"`: the provider omitted `scope`, so the grant equals what was
+ *   requested (RFC 6749 §5.1) and the seam unions the requested set. Resolved
+ *   at runtime by the persistence seam, never declared by a provider.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+type GrantAuthority = "full-grant" | "projection" | "absent-echo";
+/**
+ * The authority a provider may declare for its own echoed scope. `"absent-echo"`
+ * is excluded because it is a runtime condition (an omitted echo), not a
+ * provider trait.
+ */
+type ProviderGrantAuthority = Exclude<GrantAuthority, "absent-echo">;
+interface UpstreamProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
   id: LiteralString;
+  /**
+   * The path the provider redirects back to, relative to the app base URL,
+   * e.g. `/callback/google`.
+   */
+  callbackPath: string;
+  /**
+   * How the persistence seam treats this provider's echoed token-response
+   * `scope`. Declare `"full-grant"` only when the echo is the user's complete
+   * current grant (e.g. Google with `include_granted_scopes`); otherwise the
+   * echo is unioned onto the stored grant.
+   *
+   * @default "projection"
+   */
+  grantAuthority?: ProviderGrantAuthority | undefined;
   createAuthorizationURL: (data: {
     state: string;
     codeVerifier: string;
@@ -30,7 +128,14 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
-  }) => Awaitable<URL>;
+    /**
+     * Extra query parameters to append to the authorization URL.
+     * Providers forward these to the shared `createAuthorizationURL` helper,
+     * which drops any keys present in `RESERVED_AUTHORIZATION_PARAMS`
+     * before applying them.
+     */
+    additionalParams?: Record<string, string> | undefined;
+  }) => Awaitable<AuthorizationURLResult>;
   name: string;
   validateAuthorizationCode: (data: {
     code: string;
@@ -58,14 +163,12 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
    * Custom function to refresh a token
    */
   refreshAccessToken?: ((refreshToken: string) => Promise<OAuth2Tokens>) | undefined;
-  revokeToken?: ((token: string) => Promise<void>) | undefined;
   /**
-   * Verify the id token
-   * @param token - The id token
-   * @param nonce - The nonce
-   * @returns True if the id token is valid, false otherwise
+   * Declarative id_token verification config consumed by the shared
+   * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
+   * verify method, which keeps verification centralized and fail-closed.
    */
-  verifyIdToken?: ((token: string, nonce?: string) => Promise<boolean>) | undefined;
+  idToken?: OAuthIdTokenConfig | undefined;
   /**
    * The expected issuer identifier for this provider (RFC 9207).
    * When set, the callback handler validates the `iss` query parameter
@@ -81,6 +184,17 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
    * Disable sign up for new users.
    */
   disableSignUp?: boolean | undefined;
+  /**
+   * Accept callbacks that arrive without a `state` parameter. When true,
+   * the shared OAuth callback handler restarts the flow server-side with
+   * fresh `state` and PKCE instead of rejecting the request. Intended for
+   * providers that initiate OAuth without RP-side flow kickoff (e.g.
+   * Clever). Leave unset for any provider that always initiates from the
+   * RP.
+   *
+   * @default false
+   */
+  allowIdpInitiated?: boolean | undefined;
   /**
    * Options for the provider
    */
@@ -90,9 +204,10 @@ type ProviderOptions<Profile extends Record<string, any> = any> = {
   /**
    * The client ID of your application.
    *
-   * This is usually a string but can be any type depending on the provider.
+   * Some providers accept multiple platform client IDs. The first entry is the
+   * primary client ID used for token endpoint client authentication.
    */
-  clientId?: unknown | undefined;
+  clientId?: LiteralString | string[] | undefined;
   /**
    * The client secret of your application
    */
@@ -193,6 +308,29 @@ type ProviderOptions<Profile extends Record<string, any> = any> = {
    * @default false
    */
   overrideUserInfoOnSignIn?: boolean | undefined;
+  /**
+   * Require this provider's email to be verified before a session is created.
+   *
+   * When the provider reports the email as unverified, the user and account are
+   * still created/linked, but no session is issued: the OAuth callback redirects
+   * with `?error=email_not_verified` and id-token sign-in returns a `403`
+   * `EMAIL_NOT_VERIFIED`. A verification email is (re)sent per the
+   * `emailVerification` settings (`sendOnSignUp` / `sendOnSignIn`).
+   *
+   * The gate checks the local user's verification state, not the provider's
+   * claim on each request: a user already verified through another method (or a
+   * prior verified sign-in) keeps access even if the provider later reports the
+   * email as unverified.
+   *
+   * This is opt-in per provider and is independent of
+   * `emailAndPassword.requireEmailVerification`; enabling that does not gate
+   * social sign-in. Only enable it for providers that report a trustworthy
+   * `email_verified` signal: several providers always report the email as
+   * unverified, which would block every sign-in.
+   *
+   * @default false
+   */
+  requireEmailVerification?: boolean | undefined;
 };
 //#endregion
-export { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions };
+export { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider };