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

package/dist/oauth2/scopes.d.mts

@@ -0,0 +1,76 @@
+import { ProviderOptions } from "./oauth-provider.mjs";
+
+//#region src/oauth2/scopes.d.ts
+/**
+ * Parse a provider's `scope` token-response field into a string array.
+ *
+ * RFC 6749 §3.3 defines `scope` as a space-delimited string, but providers
+ * vary: some (e.g. Twitch) return an already-split array. Accept both, plus the
+ * omitted/empty case, without ever calling `.split` on a non-string. Returns
+ * `[]` when no scope is present.
+ *
+ * @see https://github.com/better-auth/better-auth/issues/9076
+ */
+declare function parseScopeField(scope: unknown): string[];
+/**
+ * Normalize a scope set into a single deduped, sorted array.
+ *
+ * Scope order is insignificant per RFC 6749 §3.3, so normalize for idempotent
+ * writes and trivial comparisons: trim each token, drop empties, dedupe, and
+ * sort ascending. Returns `[]` when the union is empty.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ */
+declare function normalizeScopes(stored: string[] | null | undefined, incoming?: string[] | undefined): string[];
+/**
+ * Union the stored granted-scope set with the scopes observed on an
+ * authorization or token exchange.
+ *
+ * The provider's echoed `scope` is authoritative when present. RFC 6749 §3.3
+ * and §5.1 say an omitted or empty echo means the grant equals what was
+ * requested, so fall back to `requested` in that case. The result unions onto
+ * the stored grant (never narrows on a normal write) and is normalized per
+ * {@link normalizeScopes}.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+declare function unionGrantedScopes(stored: string[] | null | undefined, echoed: string[] | undefined, requested: string[] | undefined): string[];
+/**
+ * Coerce a stored granted-scope value into a usable array.
+ *
+ * `account.grantedScopes` is nullable (legacy rows and non-OAuth accounts read
+ * as unset), and on dialects that store the array as a JSON string a malformed
+ * operator backfill could deserialize to a non-array. Both collapse to `[]`
+ * here so every reader works against a real `string[]` without re-deriving the
+ * guard.
+ */
+declare function readGrantedScopes(stored: string[] | null | undefined): string[];
+/**
+ * Test whether a normalized granted-scope set contains a specific scope.
+ *
+ * Matching is exact and case-sensitive per RFC 6749 §3.3. The argument is the
+ * normalized `account.grantedScopes` array; a raw provider `scope` string must
+ * be run through {@link parseScopeField} first.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+ */
+declare function includesGrantedScope(granted: string[] | null | undefined, scope: string): boolean;
+/**
+ * Compose the effective scope set to encode in a single authorization URL.
+ *
+ * Precedence: the provider's built-in defaults (unless `disableDefaultScope`),
+ * then the integrator's configured `options.scope`, then the per-request
+ * `scopes`. The result is the value persisted into OAuth state as the RFC 6749
+ * §5.1 fallback, so it is preserved verbatim (not normalized) to match what is
+ * sent to the provider.
+ *
+ * `defaultScopes` is a parameter rather than a provider-contract field so the
+ * runtime-synthesized generic OAuth provider, which has no static default set,
+ * can pass its configured scopes here.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+ */
+declare function resolveRequestedScopes(options: Pick<ProviderOptions, "scope" | "disableDefaultScope"> | undefined, defaultScopes: string[], perRequestScopes: string[] | undefined): string[];
+//#endregion
+export { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes };

package/dist/oauth2/scopes.mjs

@@ -0,0 +1,96 @@
+//#region src/oauth2/scopes.ts
+/**
+* Parse a provider's `scope` token-response field into a string array.
+*
+* RFC 6749 §3.3 defines `scope` as a space-delimited string, but providers
+* vary: some (e.g. Twitch) return an already-split array. Accept both, plus the
+* omitted/empty case, without ever calling `.split` on a non-string. Returns
+* `[]` when no scope is present.
+*
+* @see https://github.com/better-auth/better-auth/issues/9076
+*/
+function parseScopeField(scope) {
+	if (Array.isArray(scope)) return scope.filter((s) => typeof s === "string" && s !== "");
+	if (typeof scope === "string") return scope.split(" ").filter(Boolean);
+	return [];
+}
+/**
+* Normalize a scope set into a single deduped, sorted array.
+*
+* Scope order is insignificant per RFC 6749 §3.3, so normalize for idempotent
+* writes and trivial comparisons: trim each token, drop empties, dedupe, and
+* sort ascending. Returns `[]` when the union is empty.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+*/
+function normalizeScopes(stored, incoming) {
+	const normalized = /* @__PURE__ */ new Set();
+	for (const scope of [...stored ?? [], ...incoming ?? []]) {
+		const trimmed = scope.trim();
+		if (trimmed) normalized.add(trimmed);
+	}
+	return [...normalized].sort();
+}
+/**
+* Union the stored granted-scope set with the scopes observed on an
+* authorization or token exchange.
+*
+* The provider's echoed `scope` is authoritative when present. RFC 6749 §3.3
+* and §5.1 say an omitted or empty echo means the grant equals what was
+* requested, so fall back to `requested` in that case. The result unions onto
+* the stored grant (never narrows on a normal write) and is normalized per
+* {@link normalizeScopes}.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+* @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+*/
+function unionGrantedScopes(stored, echoed, requested) {
+	return normalizeScopes(stored, echoed?.length ? echoed : requested);
+}
+/**
+* Coerce a stored granted-scope value into a usable array.
+*
+* `account.grantedScopes` is nullable (legacy rows and non-OAuth accounts read
+* as unset), and on dialects that store the array as a JSON string a malformed
+* operator backfill could deserialize to a non-array. Both collapse to `[]`
+* here so every reader works against a real `string[]` without re-deriving the
+* guard.
+*/
+function readGrantedScopes(stored) {
+	return Array.isArray(stored) ? stored : [];
+}
+/**
+* Test whether a normalized granted-scope set contains a specific scope.
+*
+* Matching is exact and case-sensitive per RFC 6749 §3.3. The argument is the
+* normalized `account.grantedScopes` array; a raw provider `scope` string must
+* be run through {@link parseScopeField} first.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
+*/
+function includesGrantedScope(granted, scope) {
+	return granted?.includes(scope) ?? false;
+}
+/**
+* Compose the effective scope set to encode in a single authorization URL.
+*
+* Precedence: the provider's built-in defaults (unless `disableDefaultScope`),
+* then the integrator's configured `options.scope`, then the per-request
+* `scopes`. The result is the value persisted into OAuth state as the RFC 6749
+* §5.1 fallback, so it is preserved verbatim (not normalized) to match what is
+* sent to the provider.
+*
+* `defaultScopes` is a parameter rather than a provider-contract field so the
+* runtime-synthesized generic OAuth provider, which has no static default set,
+* can pass its configured scopes here.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6749#section-5.1
+*/
+function resolveRequestedScopes(options, defaultScopes, perRequestScopes) {
+	const scopes = options?.disableDefaultScope ? [] : [...defaultScopes];
+	if (options?.scope) scopes.push(...options.scope);
+	if (perRequestScopes) scopes.push(...perRequestScopes);
+	return scopes;
+}
+//#endregion
+export { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes };

package/dist/oauth2/utils.mjs

@@ -1,3 +1,4 @@
+import { parseScopeField } from "./scopes.mjs";
 import { base64Url } from "@better-auth/utils/base64";
 //#region src/oauth2/utils.ts
 function getOAuth2Tokens(data) {
@@ -11,7 +12,7 @@ function getOAuth2Tokens(data) {
 		refreshToken: data.refresh_token,
 		accessTokenExpiresAt: data.expires_in ? getDate(data.expires_in) : void 0,
 		refreshTokenExpiresAt: data.refresh_token_expires_in ? getDate(data.refresh_token_expires_in) : void 0,
-		scopes: data?.scope ? typeof data.scope === "string" ? data.scope.split(" ") : data.scope : [],
+		scopes: parseScopeField(data.scope),
 		idToken: data.id_token,
 		raw: data
 	};

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

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

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

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

package/dist/oauth2/verify.d.mts

@@ -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;
@@ -14,29 +27,89 @@ interface VerifyAccessTokenRemote {
    * is also still active.
    */
   force?: boolean;
+  /**
+   * Accept introspection responses that omit the `aud` claim even when a
+   * required `audience` is configured in `verifyOptions`.
+   *
+   * By default verification fails closed: if you configure an `audience` and
+   * the introspection response has no `aud` (or a mismatching one), the token
+   * is rejected. Some authorization servers legitimately omit `aud` from
+   * introspection responses (it is OPTIONAL per RFC 7662 §2.2); only enable
+   * this if you trust the issuer to bind the token to this resource through
+   * another mechanism, as it skips the audience check in that case.
+   *
+   * @default false
+   */
+  allowMissingAudience?: boolean;
+}
+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,8 +12,65 @@ const joseInfrastructureErrorCodes = new Set([
 function isJoseInfrastructureError(error) {
 	return joseInfrastructureErrorCodes.has(error.code);
 }
-/** Last fetched jwks used locally in getJwks @internal */
-let jwks;
+/**
+* @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.
 *
@@ -20,7 +78,17 @@ let jwks;
 */
 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) {
@@ -29,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);
@@ -36,22 +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" });
-	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
-		jwks = typeof opts.jwksFetch === "string" ? await betterFetch(opts.jwksFetch, { headers: { Accept: "application/json" } }).then(async (res) => {
-			if (res.error) throw new Error(`Jwks failed: ${res.error.message ?? res.error.statusText}`);
-			return res.data;
-		}) : await opts.jwksFetch();
+	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
+		};
 	}
-	return jwks;
+	const cacheKey = opts.jwksFetch;
+	const cached = jwksCache.get(cacheKey);
+	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,
+			...opts.forceRefresh && !kid ? { noKidRefetchedAt: fetchedAt } : {}
+		});
+		return {
+			jwks,
+			fromCache: false,
+			kid
+		};
+	}
+	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, {
@@ -85,8 +199,9 @@ async function verifyAccessToken(token, opts) {
 		if (!introspect.active) throw new APIError("UNAUTHORIZED", { message: "token inactive" });
 		try {
 			const unsecuredJwt = new UnsecuredJWT(introspect).encode();
-			const { audience: _audience, ...verifyOptions } = opts.verifyOptions;
-			payload = (introspect.aud ? UnsecuredJWT.decode(unsecuredJwt, opts.verifyOptions) : UnsecuredJWT.decode(unsecuredJwt, verifyOptions)).payload;
+			const { audience: _audience, ...verifyOptionsNoAudience } = opts.verifyOptions;
+			const skipAudience = !introspect.aud && opts.remoteVerify.allowMissingAudience === true;
+			payload = UnsecuredJWT.decode(unsecuredJwt, skipAudience ? verifyOptionsNoAudience : opts.verifyOptions).payload;
 		} catch (error) {
 			throw new Error(error);
 		}
@@ -98,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 };