@better-auth/core 1.7.0-beta.1 → 1.7.0-beta.10

package/dist/oauth2/dpop.d.mts

@@ -0,0 +1,142 @@
+import { JWK, JWTPayload } from "jose";
+
+//#region src/oauth2/dpop.d.ts
+declare const DPOP_AUTHORIZATION_SCHEME = "DPoP";
+declare const BEARER_AUTHORIZATION_SCHEME = "Bearer";
+declare const DPOP_PROOF_TYPE = "dpop+jwt";
+declare const DPOP_SIGNING_ALGORITHMS: readonly ["EdDSA", "ES256", "ES512", "PS256", "RS256"];
+type DpopSigningAlgorithm = (typeof DPOP_SIGNING_ALGORITHMS)[number];
+type AccessTokenAuthorizationScheme = "Bearer" | "DPoP" | "Unknown";
+interface AccessTokenAuthorization {
+  scheme: AccessTokenAuthorizationScheme;
+  token: string;
+}
+type DpopProofErrorCode = "invalid_dpop_proof";
+type DpopProofError = Error & {
+  code: DpopProofErrorCode;
+};
+interface DpopReplayReservation {
+  key: string;
+  expiresAt: Date;
+  now: Date;
+}
+interface DpopReplayStore {
+  reserve: (reservation: DpopReplayReservation) => Promise<boolean> | boolean;
+}
+declare function createInMemoryDpopReplayStore(): DpopReplayStore;
+/**
+ * The single-use reservation capability a {@link createDpopReplayStore} needs:
+ * the auth context's `internalAdapter.reserveVerificationValue`. Kept structural
+ * so core does not depend on the adapter implementation.
+ */
+interface DpopReplayReservations {
+  reserveVerificationValue: (data: {
+    identifier: string;
+    value: string;
+    expiresAt: Date;
+  }) => Promise<boolean>;
+}
+/**
+ * Database-backed DPoP proof replay store built on the auth context's
+ * verification reservation primitive (`internalAdapter.reserveVerificationValue`),
+ * the same atomic single-use mechanism that guards SAML assertion ids and other
+ * one-time tokens. A replayed proof collides on the deterministic reservation id
+ * so `reserve` returns `false`, giving cross-instance anti-replay. Prefer this
+ * over {@link createInMemoryDpopReplayStore} for any multi-instance or serverless
+ * resource server. Requires database-backed verification storage; a
+ * secondary-storage-only deployment rejects the proof (fails closed).
+ */
+declare function createDpopReplayStore(reservations: DpopReplayReservations): DpopReplayStore;
+interface VerifyDpopProofOptions {
+  proofJwt: string;
+  method: string;
+  url: string;
+  accessToken?: string;
+  expectedJkt?: string;
+  requireAth?: boolean;
+  nowSeconds?: number;
+  proofMaxAgeSeconds?: number;
+  signingAlgorithms?: readonly string[];
+  replayStore?: DpopReplayStore;
+}
+interface VerifiedDpopProof {
+  jwk: JWK;
+  jkt: string;
+  jti: string;
+  htm: string;
+  htu: string;
+  iat: number;
+  ath?: string;
+  replayKey: string;
+  expiresAt: Date;
+}
+declare function createDpopProofError(code: DpopProofErrorCode, message: string): DpopProofError;
+declare function isDpopProofError(error: unknown): error is DpopProofError;
+declare function parseAccessTokenAuthorization(authorization: string | null | undefined): AccessTokenAuthorization | undefined;
+declare function stripAccessTokenAuthorizationScheme(token: string): string;
+declare function normalizeDpopHtu(url: string): string;
+declare function deriveDpopAth(accessToken: string): Promise<string>;
+declare function deriveDpopJkt(jwk: JWK): Promise<string>;
+/**
+ * Extracts the DPoP key thumbprint from an RFC 7800 `cnf` confirmation. The
+ * input is untrusted (a JWT claim, a JSON column), so any shape other than an
+ * object carrying a non-empty string `jkt` (a primitive, an array, a different
+ * confirmation method such as mTLS `x5t#S256`) yields `undefined` instead of
+ * throwing.
+ */
+declare function getConfirmationJkt(confirmation: unknown): string | undefined;
+declare function getDpopJktFromPayload(payload: JWTPayload): string | undefined;
+declare function verifyDpopProof({
+  proofJwt,
+  method,
+  url,
+  accessToken,
+  expectedJkt,
+  requireAth,
+  nowSeconds,
+  proofMaxAgeSeconds,
+  signingAlgorithms,
+  replayStore
+}: VerifyDpopProofOptions): Promise<VerifiedDpopProof>;
+type DpopBindingErrorCode = "invalid_token" | "invalid_dpop_proof";
+type DpopBindingError = Error & {
+  code: DpopBindingErrorCode;
+};
+declare function createDpopBindingError(code: DpopBindingErrorCode, message: string): DpopBindingError;
+declare function isDpopBindingError(error: unknown): error is DpopBindingError;
+interface EnforceDpopBindingParams {
+  /** The already-verified access-token payload (from JWKS or introspection). */
+  payload: JWTPayload;
+  /** The parsed `Authorization` header (scheme + token). */
+  authorization: AccessTokenAuthorization;
+  /** The `DPoP` proof header value, if any. */
+  proofJwt: string | null | undefined;
+  method: string;
+  url: string;
+  replayStore?: DpopReplayStore;
+  proofMaxAgeSeconds?: number;
+  signingAlgorithms?: readonly string[];
+}
+/**
+ * Enforces the RFC 9449 §7.1 sender-constraint check for a resource request,
+ * given an access-token payload that has already been validated (by JWKS or
+ * introspection). This is the single source of truth for the
+ * "is the token DPoP-bound? then require the DPoP scheme, a proof, and a
+ * matching key" decision, shared by every resource-server entry point.
+ *
+ * Throws a {@link DpopBindingError} on any mismatch so callers map the
+ * `invalid_token` / `invalid_dpop_proof` code into their own transport. Returns
+ * normally for a valid bearer token (no `cnf.jkt`, no DPoP scheme).
+ */
+declare function enforceDpopBinding({
+  payload,
+  authorization,
+  proofJwt,
+  method,
+  url,
+  replayStore,
+  proofMaxAgeSeconds,
+  signingAlgorithms
+}: EnforceDpopBindingParams): Promise<void>;
+//#endregion
+export { AccessTokenAuthorization, AccessTokenAuthorizationScheme, BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, DpopBindingError, DpopBindingErrorCode, DpopProofError, DpopProofErrorCode, DpopReplayReservation, DpopReplayReservations, DpopReplayStore, DpopSigningAlgorithm, EnforceDpopBindingParams, VerifiedDpopProof, VerifyDpopProofOptions, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, deriveDpopAth, deriveDpopJkt, enforceDpopBinding, getConfirmationJkt, getDpopJktFromPayload, isDpopBindingError, isDpopProofError, normalizeDpopHtu, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof };

package/dist/oauth2/dpop.mjs

@@ -0,0 +1,246 @@
+import { base64url, calculateJwkThumbprint, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+//#region src/oauth2/dpop.ts
+const DPOP_AUTHORIZATION_SCHEME = "DPoP";
+const BEARER_AUTHORIZATION_SCHEME = "Bearer";
+const DPOP_PROOF_TYPE = "dpop+jwt";
+const DPOP_SIGNING_ALGORITHMS = [
+	"EdDSA",
+	"ES256",
+	"ES512",
+	"PS256",
+	"RS256"
+];
+const DEFAULT_DPOP_PROOF_MAX_AGE_SECONDS = 300;
+const MAX_DPOP_JTI_LENGTH = 512;
+const JWK_PRIVATE_FIELDS = new Set([
+	"d",
+	"p",
+	"q",
+	"dp",
+	"dq",
+	"qi",
+	"oth",
+	"k"
+]);
+function createInMemoryDpopReplayStore() {
+	const reservations = /* @__PURE__ */ new Map();
+	return { reserve({ key, expiresAt, now }) {
+		const nowMs = now.getTime();
+		for (const [storedKey, expiresAtMs] of reservations) if (expiresAtMs <= nowMs) reservations.delete(storedKey);
+		if (reservations.has(key)) return false;
+		reservations.set(key, expiresAt.getTime());
+		return true;
+	} };
+}
+/**
+* Database-backed DPoP proof replay store built on the auth context's
+* verification reservation primitive (`internalAdapter.reserveVerificationValue`),
+* the same atomic single-use mechanism that guards SAML assertion ids and other
+* one-time tokens. A replayed proof collides on the deterministic reservation id
+* so `reserve` returns `false`, giving cross-instance anti-replay. Prefer this
+* over {@link createInMemoryDpopReplayStore} for any multi-instance or serverless
+* resource server. Requires database-backed verification storage; a
+* secondary-storage-only deployment rejects the proof (fails closed).
+*/
+function createDpopReplayStore(reservations) {
+	return { reserve: ({ key, expiresAt }) => reservations.reserveVerificationValue({
+		identifier: `dpop-proof:${key}`,
+		value: key,
+		expiresAt
+	}) };
+}
+function createDpopProofError(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+function isDpopProofError(error) {
+	return error instanceof Error && "code" in error && error.code === "invalid_dpop_proof";
+}
+function parseAccessTokenAuthorization(authorization) {
+	if (!authorization) return void 0;
+	const value = authorization.trim();
+	if (!value) return void 0;
+	const match = /^([A-Za-z][A-Za-z0-9!#$%&'*+.^_`|~-]*)\s+(.+)$/.exec(value);
+	if (!match) return {
+		scheme: "Unknown",
+		token: value
+	};
+	const scheme = match[1] ?? "";
+	const token = match[2]?.trim() ?? "";
+	if (scheme.toLowerCase() === "bearer") return {
+		scheme: "Bearer",
+		token
+	};
+	if (scheme.toLowerCase() === "dpop") return {
+		scheme: "DPoP",
+		token
+	};
+	return {
+		scheme: "Unknown",
+		token: value
+	};
+}
+function stripAccessTokenAuthorizationScheme(token) {
+	return parseAccessTokenAuthorization(token)?.token ?? token;
+}
+function normalizeDpopHtu(url) {
+	const parsed = new URL(url);
+	if (parsed.hash) throw new Error("DPoP proof htu must not contain a fragment");
+	return `${parsed.origin}${parsed.pathname}`;
+}
+async function deriveDpopAth(accessToken) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(accessToken));
+	return base64url.encode(new Uint8Array(digest));
+}
+async function deriveDpopJkt(jwk) {
+	return calculateJwkThumbprint(jwk, "sha256");
+}
+/**
+* Extracts the DPoP key thumbprint from an RFC 7800 `cnf` confirmation. The
+* input is untrusted (a JWT claim, a JSON column), so any shape other than an
+* object carrying a non-empty string `jkt` (a primitive, an array, a different
+* confirmation method such as mTLS `x5t#S256`) yields `undefined` instead of
+* throwing.
+*/
+function getConfirmationJkt(confirmation) {
+	if (!confirmation || typeof confirmation !== "object" || Array.isArray(confirmation)) return;
+	const jkt = confirmation.jkt;
+	return typeof jkt === "string" && jkt.length > 0 ? jkt : void 0;
+}
+function getDpopJktFromPayload(payload) {
+	return getConfirmationJkt(payload.cnf);
+}
+function getStringClaim(payload, claim) {
+	const value = payload[claim];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function getNumberClaim(payload, claim) {
+	const value = payload[claim];
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function assertSupportedDpopAlgorithm(alg, signingAlgorithms) {
+	if (!alg || alg === "none" || alg.startsWith("HS")) throw createDpopProofError("invalid_dpop_proof", "DPoP proof must use an asymmetric JWS algorithm");
+	if (!signingAlgorithms.includes(alg)) throw createDpopProofError("invalid_dpop_proof", "DPoP proof uses an unsupported JWS algorithm");
+}
+function assertPublicJwk(jwk) {
+	if (!jwk || typeof jwk !== "object" || Array.isArray(jwk)) throw createDpopProofError("invalid_dpop_proof", "DPoP proof header must include a public jwk");
+	if (jwk.kty === "oct") throw createDpopProofError("invalid_dpop_proof", "DPoP proof jwk must be asymmetric");
+	for (const field of JWK_PRIVATE_FIELDS) if (field in jwk) throw createDpopProofError("invalid_dpop_proof", "DPoP proof jwk must not contain private key material");
+}
+async function deriveDpopReplayKey(params) {
+	const input = `${params.jkt}\n${params.htm}\n${params.htu}\n${params.jti}`;
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+	return base64url.encode(new Uint8Array(digest));
+}
+async function reserveDpopReplay(replayStore, reservation) {
+	if (!replayStore) return;
+	if (!await replayStore.reserve(reservation)) throw createDpopProofError("invalid_dpop_proof", "DPoP proof jti has already been used");
+}
+async function verifyDpopProof({ proofJwt, method, url, accessToken, expectedJkt, requireAth = false, nowSeconds = Math.floor(Date.now() / 1e3), proofMaxAgeSeconds = DEFAULT_DPOP_PROOF_MAX_AGE_SECONDS, signingAlgorithms = DPOP_SIGNING_ALGORITHMS, replayStore }) {
+	if (!proofJwt || proofJwt.split(".").length !== 3) throw createDpopProofError("invalid_dpop_proof", "DPoP proof must be a compact JWT");
+	let protectedHeader;
+	try {
+		protectedHeader = decodeProtectedHeader(proofJwt);
+	} catch (error) {
+		throw createDpopProofError("invalid_dpop_proof", error instanceof Error ? error.message : "DPoP proof header is invalid");
+	}
+	if (protectedHeader.typ !== "dpop+jwt") throw createDpopProofError("invalid_dpop_proof", "DPoP proof typ must be \"dpop+jwt\"");
+	assertSupportedDpopAlgorithm(protectedHeader.alg, signingAlgorithms);
+	assertPublicJwk(protectedHeader.jwk);
+	let payload;
+	try {
+		payload = (await jwtVerify(proofJwt, await importJWK(protectedHeader.jwk, protectedHeader.alg), { typ: DPOP_PROOF_TYPE })).payload;
+	} catch (error) {
+		throw createDpopProofError("invalid_dpop_proof", error instanceof Error ? error.message : "DPoP proof signature is invalid");
+	}
+	const htm = getStringClaim(payload, "htm");
+	const htu = getStringClaim(payload, "htu");
+	const jti = getStringClaim(payload, "jti");
+	const iat = getNumberClaim(payload, "iat");
+	if (!htm || !htu || !jti || iat === void 0) throw createDpopProofError("invalid_dpop_proof", "DPoP proof must include htm, htu, jti, and iat claims");
+	if (jti.length > MAX_DPOP_JTI_LENGTH) throw createDpopProofError("invalid_dpop_proof", "DPoP proof jti is too large");
+	if (htm.toUpperCase() !== method.toUpperCase()) throw createDpopProofError("invalid_dpop_proof", "DPoP proof htm does not match the request method");
+	let normalizedHtu;
+	let proofHtu;
+	try {
+		normalizedHtu = normalizeDpopHtu(url);
+		proofHtu = normalizeDpopHtu(htu);
+	} catch (error) {
+		throw createDpopProofError("invalid_dpop_proof", error instanceof Error ? error.message : "DPoP proof htu is invalid");
+	}
+	if (proofHtu !== normalizedHtu) throw createDpopProofError("invalid_dpop_proof", "DPoP proof htu does not match the request URL");
+	if (iat > nowSeconds + 5 || nowSeconds - iat > proofMaxAgeSeconds) throw createDpopProofError("invalid_dpop_proof", "DPoP proof iat is outside the accepted window");
+	const ath = getStringClaim(payload, "ath");
+	if (requireAth && !ath) throw createDpopProofError("invalid_dpop_proof", "DPoP proof must include an ath claim");
+	if (accessToken !== void 0) {
+		if (ath !== await deriveDpopAth(accessToken)) throw createDpopProofError("invalid_dpop_proof", "DPoP proof ath does not match the access token");
+	}
+	const jkt = await deriveDpopJkt(protectedHeader.jwk);
+	if (expectedJkt !== void 0 && jkt !== expectedJkt) throw createDpopProofError("invalid_dpop_proof", "DPoP proof key does not match the bound token");
+	const replayKey = await deriveDpopReplayKey({
+		jkt,
+		htm: htm.toUpperCase(),
+		htu: normalizedHtu,
+		jti
+	});
+	const expiresAt = /* @__PURE__ */ new Date((iat + proofMaxAgeSeconds) * 1e3);
+	await reserveDpopReplay(replayStore, {
+		key: replayKey,
+		expiresAt,
+		now: /* @__PURE__ */ new Date(nowSeconds * 1e3)
+	});
+	return {
+		jwk: protectedHeader.jwk,
+		jkt,
+		jti,
+		htm,
+		htu: normalizedHtu,
+		iat,
+		ath,
+		replayKey,
+		expiresAt
+	};
+}
+function createDpopBindingError(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+function isDpopBindingError(error) {
+	return error instanceof Error && "code" in error && (error.code === "invalid_token" || error.code === "invalid_dpop_proof");
+}
+/**
+* Enforces the RFC 9449 §7.1 sender-constraint check for a resource request,
+* given an access-token payload that has already been validated (by JWKS or
+* introspection). This is the single source of truth for the
+* "is the token DPoP-bound? then require the DPoP scheme, a proof, and a
+* matching key" decision, shared by every resource-server entry point.
+*
+* Throws a {@link DpopBindingError} on any mismatch so callers map the
+* `invalid_token` / `invalid_dpop_proof` code into their own transport. Returns
+* normally for a valid bearer token (no `cnf.jkt`, no DPoP scheme).
+*/
+async function enforceDpopBinding({ payload, authorization, proofJwt, method, url, replayStore, proofMaxAgeSeconds, signingAlgorithms }) {
+	const dpopJkt = getDpopJktFromPayload(payload);
+	if (!dpopJkt) {
+		if (authorization.scheme === "DPoP") throw createDpopBindingError("invalid_token", "DPoP authorization requires a DPoP-bound access token");
+		return;
+	}
+	if (authorization.scheme !== "DPoP") throw createDpopBindingError("invalid_token", "DPoP-bound access token requires the DPoP authorization scheme");
+	if (!proofJwt) throw createDpopBindingError("invalid_dpop_proof", "DPoP proof header is required");
+	try {
+		await verifyDpopProof({
+			proofJwt,
+			method,
+			url,
+			accessToken: authorization.token,
+			expectedJkt: dpopJkt,
+			requireAth: true,
+			proofMaxAgeSeconds,
+			signingAlgorithms,
+			replayStore
+		});
+	} catch (error) {
+		if (isDpopProofError(error)) throw createDpopBindingError("invalid_dpop_proof", error.message);
+		throw error;
+	}
+}
+//#endregion
+export { BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, deriveDpopAth, deriveDpopJkt, enforceDpopBinding, getConfirmationJkt, getDpopJktFromPayload, isDpopBindingError, isDpopProofError, normalizeDpopHtu, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof };

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 } from "./utils.mjs";
-import { authorizationCodeRequest, createAuthorizationCodeRequest, 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, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+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 { OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthProvider, OAuthRefreshContext, ProviderOptions } 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 { AccessTokenAuthorization, AccessTokenAuthorizationScheme, BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, DpopBindingError, DpopBindingErrorCode, DpopProofError, DpopProofErrorCode, DpopReplayReservation, DpopReplayReservations, DpopReplayStore, DpopSigningAlgorithm, EnforceDpopBindingParams, VerifiedDpopProof, VerifyDpopProofOptions, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, deriveDpopAth, deriveDpopJkt, enforceDpopBinding, getConfirmationJkt, getDpopJktFromPayload, isDpopBindingError, isDpopProofError, normalizeDpopHtu, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof } from "./dpop.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes } from "./utils.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
+import { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { type AccessTokenAuthorization, type AccessTokenAuthorizationScheme, BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, type DpopBindingError, type DpopBindingErrorCode, type DpopProofError, type DpopProofErrorCode, type DpopReplayReservation, type DpopReplayReservations, type DpopReplayStore, type DpopSigningAlgorithm, type EnforceDpopBindingParams, type OAuth2Tokens, type OAuth2UserInfo, type OAuthIdTokenConfig, type OAuthProvider, type OAuthRefreshContext, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, type PrivateKeyJwtClientAssertionGetterOptions, type PrivateKeyJwtSigningAlgorithm, type ProviderOptions, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, type ResourceRequestInput, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, type VerifiedDpopProof, type VerifyAccessTokenOptions, type VerifyAccessTokenRequestOptions, type VerifyDpopProofOptions, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, 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 } 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 { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId, mergeScopes } 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 { BEARER_AUTHORIZATION_SCHEME, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, deriveDpopAth, deriveDpopJkt, enforceDpopBinding, getConfirmationJkt, getDpopJktFromPayload, isDpopBindingError, isDpopProofError, normalizeDpopHtu, parseAccessTokenAuthorization, stripAccessTokenAuthorizationScheme, verifyDpopProof } from "./dpop.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
+import { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, isDpopBindingError, isDpopProofError, mergeScopes, normalizeDpopHtu, parseAccessTokenAuthorization, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, 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,30 @@ type OAuth2UserInfo = {
   image?: string | undefined;
   emailVerified: boolean;
 };
+/**
+ * Request metadata available to provider refresh hooks.
+ *
+ * The refresh flow may be triggered by endpoints such as `getAccessToken` or
+ * `refreshToken`; this context gives provider hooks access to the triggering
+ * request without exposing the full endpoint implementation surface.
+ */
+interface OAuthRefreshContext {
+  headers?: Headers | undefined;
+  request?: Request | undefined;
+}
 interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O extends Record<string, any> = Partial<ProviderOptions>> {
   id: LiteralString;
+  /**
+   * Optional path under the resolved per-request `baseURL` where this
+   * provider's OAuth callback handler is mounted. Providers that use the
+   * shared `/callback/<id>` route can omit this.
+   *
+   * Custom paths must start with `/`.
+   *
+   * Endpoints compose `redirectURI = ctx.context.baseURL + callbackPath` per
+   * request, so the provider must not hardcode an origin or `baseURL` here.
+   */
+  callbackPath?: string | undefined;
   createAuthorizationURL: (data: {
     state: string;
     codeVerifier: string;
@@ -30,6 +100,19 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    /**
+     * OIDC nonce generated by the redirect initiator and persisted in OAuth
+     * state. Providers that set `requiresIdTokenNonce` must forward this to
+     * the authorization URL as the `nonce` parameter.
+     */
+    idTokenNonce?: string | undefined;
+    /**
+     * 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<URL>;
   name: string;
   validateAuthorizationCode: (data: {
@@ -39,6 +122,12 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
     deviceId?: string | undefined;
   }) => Promise<OAuth2Tokens | null>;
   getUserInfo: (token: OAuth2Tokens & {
+    /**
+     * OIDC nonce recovered from OAuth state. Providers that required an
+     * ID-token nonce must pass this to `verifyProviderIdToken` before
+     * trusting ID-token claims.
+     */
+    expectedIdTokenNonce?: string | undefined;
     /**
      * The user object from the provider
      * This is only available for some providers like Apple
@@ -55,23 +144,33 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
     data: T;
   } | null>;
   /**
-   * Custom function to refresh a token
+   * Custom function to refresh a token.
+   *
+   * Receives request metadata from the endpoint that triggered the refresh.
+   * Providers that don't need request-scoped data can ignore the second
+   * argument.
    */
-  refreshAccessToken?: ((refreshToken: string) => Promise<OAuth2Tokens>) | undefined;
+  refreshAccessToken?: ((refreshToken: string, ctx?: OAuthRefreshContext) => 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
    * against this value to prevent authorization server mix-up attacks.
    */
   issuer?: string | undefined;
+  /**
+   * Require shared OAuth redirect routes to bind ID-token verification to an
+   * authorization request nonce. When true, routes generate `idTokenNonce`,
+   * pass it to `createAuthorizationURL`, persist it in state, and provide it
+   * back to `getUserInfo` as `expectedIdTokenNonce`.
+   */
+  requiresIdTokenNonce?: boolean | undefined;
   /**
    * Disable implicit sign up for new users. When set to true for the provider,
    * sign-in need to be called with with requestSignUp as true to create new users.
@@ -81,6 +180,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 +200,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 +304,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 { OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthProvider, OAuthRefreshContext, ProviderOptions };