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

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

@@ -5,10 +5,11 @@ import { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, O
 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 { 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";
+import { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
 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 };
+export { type AccessTokenAuthorization, type AccessTokenAuthorizationScheme, type AuthorizationURLResult, 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 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 ResourceRequestInput, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, type UpstreamProvider, 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, includesGrantedScope, isDpopBindingError, isDpopProofError, normalizeDpopHtu, normalizeScopes, parseAccessTokenAuthorization, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/index.mjs

@@ -5,8 +5,9 @@ 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, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
+import { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
 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 };
+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, includesGrantedScope, isDpopBindingError, isDpopProofError, normalizeDpopHtu, normalizeScopes, parseAccessTokenAuthorization, parseScopeField, readGrantedScopes, refreshAccessToken, refreshAccessTokenRequest, requestToResourceInput, resolveClientAssertionParams, resolveRequestedScopes, signPrivateKeyJwtClientAssertion, stripAccessTokenAuthorizationScheme, supportsIdTokenSignIn, unionGrantedScopes, validateAuthorizationCode, validateToken, verifyAccessTokenRequest, verifyBearerToken, verifyDpopProof, verifyJwsAccessToken, verifyProviderIdToken };

package/dist/oauth2/verify.d.mts

@@ -1,6 +1,19 @@
+import { DpopReplayStore } from "./dpop.mjs";
 import { JSONWebKeySet, JWTPayload, JWTVerifyOptions } from "jose";
 
 //#region src/oauth2/verify.d.ts
+type JwksFetchOptions = {
+  /** Jwks url or promise of a Jwks */jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
+  /**
+   * Stable object to cache the result of a function `jwksFetch` under,
+   * with the same TTL and kid-miss refetch rules as string sources.
+   * Without it, a function source is fetched on every verification.
+   */
+  jwksCacheKey?: object;
+};
+/**
+ * @internal
+ */
 interface VerifyAccessTokenRemote {
   /** Full url of the introspect endpoint. Should end with `/oauth2/introspect` */
   introspectUrl: string;
@@ -29,28 +42,74 @@ interface VerifyAccessTokenRemote {
    */
   allowMissingAudience?: boolean;
 }
+interface VerifyAccessTokenOptions {
+  /** Verify options */
+  verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+  /** Scopes to additionally verify. Token must include all but not exact. */
+  scopes?: string[];
+  /** Required to verify access token locally */
+  jwksUrl?: string;
+  /** If provided, can verify a token remotely */
+  remoteVerify?: VerifyAccessTokenRemote;
+}
+interface VerifyAccessTokenRequestOptions extends VerifyAccessTokenOptions {
+  dpop?: {
+    proofMaxAgeSeconds?: number;
+    /**
+     * Store used to reject replayed DPoP proof `jti` values.
+     *
+     * Defaults to a process-local in-memory store, which is only safe for a
+     * single-instance deployment: it shares no state across instances and
+     * resets on cold start, so a captured proof can be replayed against
+     * another instance within the proof's lifetime. Supply a shared,
+     * persistent store (for example one backed by your database) for any
+     * multi-instance or serverless resource server.
+     */
+    replayStore?: DpopReplayStore;
+    signingAlgorithms?: readonly string[];
+  };
+}
+interface ResourceRequestInput {
+  authorizationHeader: string | null | undefined;
+  dpopProofJwt?: string | null | undefined;
+  method: string;
+  url: string;
+}
+/**
+ * Builds a {@link ResourceRequestInput} from a standard `Request`, reading the
+ * `Authorization` and `DPoP` headers and the request method and URL. Resource
+ * servers share this so every entry point maps the wire request the same way.
+ */
+declare function requestToResourceInput(request: Request): ResourceRequestInput;
 /**
  * Performs local verification of an access token for your APIs.
  *
  * Can also be configured for remote verification.
  */
-declare function verifyJwsAccessToken(token: string, opts: {
-  /** Jwks url or promise of a Jwks */jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>); /** Verify options */
-  verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+declare function verifyJwsAccessToken(token: string, opts: JwksFetchOptions & {
+  /** Verify options */verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
 }): Promise<JWTPayload>;
-declare function getJwks(token: string, opts: {
-  /** Jwks url or promise of a Jwks */jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
-}): Promise<JSONWebKeySet>;
+declare function getJwks(token: string, opts: JwksFetchOptions): Promise<JSONWebKeySet>;
 /**
- * Performs local verification of an access token for your API.
+ * Performs local verification of a bearer access token for your API.
  *
- * Can also be configured for remote verification.
+ * Can also be configured for remote verification. DPoP-bound access tokens
+ * require {@link verifyAccessTokenRequest}, because sender-constraining cannot
+ * be verified without the HTTP method, URL, Authorization scheme, DPoP proof,
+ * and access-token hash. This function rejects DPoP-bound tokens; reach for it
+ * only when you hold a raw token string and intentionally accept bearer tokens
+ * alone.
  */
-declare function verifyAccessToken(token: string, opts: {
-  /** Verify options */verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>; /** Scopes to additionally verify. Token must include all but not exact. */
-  scopes?: string[]; /** Required to verify access token locally */
-  jwksUrl?: string; /** If provided, can verify a token remotely */
-  remoteVerify?: VerifyAccessTokenRemote;
-}): Promise<JWTPayload>;
+declare function verifyBearerToken(token: string, opts: VerifyAccessTokenOptions): Promise<JWTPayload>;
+/**
+ * Verifies an HTTP resource request carrying an OAuth access token. This is the
+ * recommended resource-server entry point: it handles both bearer and
+ * DPoP-bound tokens, the bearer case being the request with no DPoP proof.
+ *
+ * It performs the same token validation as {@link verifyBearerToken}, then adds
+ * the RFC 9449 sender-constraint checks that need request context: authorization
+ * scheme, method, URL, DPoP proof, `ath`, and `cnf.jkt` binding.
+ */
+declare function verifyAccessTokenRequest(request: ResourceRequestInput, opts: VerifyAccessTokenRequestOptions): Promise<JWTPayload>;
 //#endregion
-export { getJwks, verifyAccessToken, verifyJwsAccessToken };
+export { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };

package/dist/oauth2/verify.mjs

@@ -1,4 +1,5 @@
 import { logger } from "../env/logger.mjs";
+import { createInMemoryDpopReplayStore, enforceDpopBinding, getDpopJktFromPayload, isDpopBindingError, parseAccessTokenAuthorization } from "./dpop.mjs";
 import { APIError } from "better-call";
 import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 import { betterFetch } from "@better-fetch/fetch";
@@ -11,13 +12,65 @@ const joseInfrastructureErrorCodes = new Set([
 function isJoseInfrastructureError(error) {
 	return joseInfrastructureErrorCodes.has(error.code);
 }
+/**
+* @internal
+*/
 const jwksCache = /* @__PURE__ */ new Map();
 /**
+* Cache for function jwks sources, keyed by a caller-provided stable object.
+* Entries are released with their key, so per-request keys cannot accumulate.
+*/
+const functionJwksCache = /* @__PURE__ */ new WeakMap();
+/**
 * How long a cached JWKS is trusted before it is refetched
 *
 * @internal
 */
 const JWKS_CACHE_TTL_MS = 300 * 1e3;
+const JWKS_NO_KID_REFETCH_COOLDOWN_MS = 30 * 1e3;
+/**
+* Returns the cached key set when it is within the TTL. When the token carries
+* `kid`, the cached set must contain that key id; without `kid`, key selection
+* is deferred to JOSE because RFC 7515 makes the header parameter optional.
+*/
+function getFreshJwksWithKid(cached, kid) {
+	if (!cached) return void 0;
+	if (Date.now() - cached.fetchedAt >= JWKS_CACHE_TTL_MS) return void 0;
+	if (kid && !cached.jwks.keys.some((jwk) => jwk.kid === kid)) return;
+	return cached.jwks;
+}
+function shouldRefetchCachedJwksWithoutKid(error, resolved) {
+	if (!(resolved.fromCache && !resolved.kid && (error instanceof errors.JWKSNoMatchingKey || error instanceof errors.JWSSignatureVerificationFailed))) return false;
+	if (!resolved.noKidRefetchedAt) return true;
+	return Date.now() - resolved.noKidRefetchedAt >= JWKS_NO_KID_REFETCH_COOLDOWN_MS;
+}
+async function fetchJwks(jwksFetch) {
+	const jwks = typeof jwksFetch === "string" ? await betterFetch(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 jwksFetch();
+	if (!jwks) throw new Error("No jwks found");
+	return jwks;
+}
+/**
+* Builds a {@link ResourceRequestInput} from a standard `Request`, reading the
+* `Authorization` and `DPoP` headers and the request method and URL. Resource
+* servers share this so every entry point maps the wire request the same way.
+*/
+function requestToResourceInput(request) {
+	return {
+		authorizationHeader: request.headers.get("authorization"),
+		dpopProofJwt: request.headers.get("dpop"),
+		method: request.method,
+		url: request.url
+	};
+}
+/**
+* Process-local, single-instance replay store. See the warning on
+* {@link VerifyAccessTokenRequestOptions.dpop.replayStore}; multi-instance
+* resource servers must pass their own shared store.
+*/
+const defaultDpopReplayStore = createInMemoryDpopReplayStore();
 /**
 * Performs local verification of an access token for your APIs.
 *
@@ -25,7 +78,17 @@ const JWKS_CACHE_TTL_MS = 300 * 1e3;
 */
 async function verifyJwsAccessToken(token, opts) {
 	try {
-		const jwt = await jwtVerify(token, createLocalJWKSet(await getJwks(token, opts)), opts.verifyOptions);
+		const resolved = await getJwksForVerification(token, opts);
+		let jwt;
+		try {
+			jwt = await jwtVerify(token, createLocalJWKSet(resolved.jwks), opts.verifyOptions);
+		} catch (error) {
+			if (shouldRefetchCachedJwksWithoutKid(error, resolved)) jwt = await jwtVerify(token, createLocalJWKSet((await getJwksForVerification(token, {
+				...opts,
+				forceRefresh: true
+			})).jwks), opts.verifyOptions);
+			else throw error;
+		}
 		if (jwt.payload.azp) jwt.payload.client_id = jwt.payload.azp;
 		return jwt.payload;
 	} catch (error) {
@@ -34,6 +97,9 @@ async function verifyJwsAccessToken(token, opts) {
 	}
 }
 async function getJwks(token, opts) {
+	return (await getJwksForVerification(token, opts)).jwks;
+}
+async function getJwksForVerification(token, opts) {
 	let jwtHeaders;
 	try {
 		jwtHeaders = decodeProtectedHeader(token);
@@ -41,32 +107,65 @@ async function getJwks(token, opts) {
 		if (error instanceof Error) throw error;
 		throw new Error(error);
 	}
-	if (!jwtHeaders.kid) throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
 	const kid = jwtHeaders.kid;
+	if (typeof opts.jwksFetch !== "string") {
+		const cacheKey = opts.jwksCacheKey;
+		if (!cacheKey) {
+			const jwks = await opts.jwksFetch();
+			if (!jwks) throw new Error("No jwks found");
+			return {
+				jwks,
+				fromCache: false,
+				kid
+			};
+		}
+		const cached = functionJwksCache.get(cacheKey);
+		const cachedJwks = opts.forceRefresh ? void 0 : getFreshJwksWithKid(cached, kid);
+		if (cachedJwks) return {
+			jwks: cachedJwks,
+			fromCache: true,
+			kid,
+			noKidRefetchedAt: cached?.noKidRefetchedAt
+		};
+		const jwks = await opts.jwksFetch();
+		if (!jwks) throw new Error("No jwks found");
+		const fetchedAt = Date.now();
+		functionJwksCache.set(cacheKey, {
+			jwks,
+			fetchedAt,
+			...opts.forceRefresh && !kid ? { noKidRefetchedAt: fetchedAt } : {}
+		});
+		return {
+			jwks,
+			fromCache: false,
+			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");
+	const cachedJwks = opts.forceRefresh ? void 0 : getFreshJwksWithKid(cached, kid);
+	if (!cachedJwks) {
+		const jwks = await fetchJwks(opts.jwksFetch);
+		const fetchedAt = Date.now();
 		jwksCache.set(cacheKey, {
 			jwks,
-			fetchedAt: Date.now()
+			fetchedAt,
+			...opts.forceRefresh && !kid ? { noKidRefetchedAt: fetchedAt } : {}
 		});
-		return jwks;
+		return {
+			jwks,
+			fromCache: false,
+			kid
+		};
 	}
-	return cached.jwks;
+	return {
+		jwks: cachedJwks,
+		fromCache: true,
+		kid,
+		noKidRefetchedAt: cached?.noKidRefetchedAt
+	};
 }
-/**
-* Performs local verification of an access token for your API.
-*
-* Can also be configured for remote verification.
-*/
-async function verifyAccessToken(token, opts) {
+async function verifyAccessTokenPayload(token, opts) {
 	let payload;
 	if (opts.jwksUrl && !opts?.remoteVerify?.force) try {
 		payload = await verifyJwsAccessToken(token, {
@@ -114,5 +213,58 @@ async function verifyAccessToken(token, opts) {
 	}
 	return payload;
 }
+function throwDpopUnauthorized(message, error) {
+	throw new APIError("UNAUTHORIZED", error ? {
+		message,
+		error,
+		error_description: message
+	} : { message });
+}
+/**
+* Performs local verification of a bearer access token for your API.
+*
+* Can also be configured for remote verification. DPoP-bound access tokens
+* require {@link verifyAccessTokenRequest}, because sender-constraining cannot
+* be verified without the HTTP method, URL, Authorization scheme, DPoP proof,
+* and access-token hash. This function rejects DPoP-bound tokens; reach for it
+* only when you hold a raw token string and intentionally accept bearer tokens
+* alone.
+*/
+async function verifyBearerToken(token, opts) {
+	const payload = await verifyAccessTokenPayload(token, opts);
+	if (getDpopJktFromPayload(payload)) throwDpopUnauthorized("DPoP-bound access token requires verifyAccessTokenRequest", "invalid_token");
+	return payload;
+}
+/**
+* Verifies an HTTP resource request carrying an OAuth access token. This is the
+* recommended resource-server entry point: it handles both bearer and
+* DPoP-bound tokens, the bearer case being the request with no DPoP proof.
+*
+* It performs the same token validation as {@link verifyBearerToken}, then adds
+* the RFC 9449 sender-constraint checks that need request context: authorization
+* scheme, method, URL, DPoP proof, `ath`, and `cnf.jkt` binding.
+*/
+async function verifyAccessTokenRequest(request, opts) {
+	const authorization = parseAccessTokenAuthorization(request.authorizationHeader);
+	if (!authorization?.token) throwDpopUnauthorized("missing authorization header");
+	if (authorization.scheme === "Unknown") throwDpopUnauthorized("authorization scheme must be Bearer or DPoP", "invalid_token");
+	const payload = await verifyAccessTokenPayload(authorization.token, opts);
+	try {
+		await enforceDpopBinding({
+			payload,
+			authorization,
+			proofJwt: request.dpopProofJwt,
+			method: request.method,
+			url: request.url,
+			replayStore: opts.dpop?.replayStore ?? defaultDpopReplayStore,
+			proofMaxAgeSeconds: opts.dpop?.proofMaxAgeSeconds,
+			signingAlgorithms: opts.dpop?.signingAlgorithms
+		});
+	} catch (error) {
+		if (isDpopBindingError(error)) throwDpopUnauthorized(error.message, error.code);
+		throw error;
+	}
+	return payload;
+}
 //#endregion
-export { getJwks, verifyAccessToken, verifyJwsAccessToken };
+export { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken };

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

@@ -473,6 +473,7 @@ declare const socialProviders: {
       audience: string | string[];
       maxTokenAge: string;
       issuer: string | undefined;
+      verifyClaims: (claims: Record<string, unknown>) => boolean;
     };
     getUserInfo(token: OAuth2Tokens & {
       user?: {

package/dist/social-providers/microsoft-entra-id.d.mts

@@ -172,6 +172,16 @@ declare const microsoft: (options: MicrosoftOptions) => {
      * @see https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints
      */
     issuer: string | undefined;
+    /**
+     * The multi-tenant endpoints (common/organizations/consumers) skip the
+     * issuer check above because the issuer varies per tenant, and the
+     * organizations and consumers JWKS sets overlap. Enforce the tenant
+     * binding explicitly so a token from a disallowed account class cannot
+     * pass: the issuer must name the token's own tenant, and the account
+     * class must match the configured restriction.
+     * @see https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference
+     */
+    verifyClaims: (claims: Record<string, unknown>) => boolean;
   };
   getUserInfo(token: OAuth2Tokens & {
     user?: {