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

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,14 +1,15 @@
 import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
 import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
 import { CLIENT_ASSERTION_TYPE, ClientAssertionContext, ClientAssertionGetter, ClientAssertionGrantType, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, PrivateKeyJwtClientAssertionGetterOptions, PrivateKeyJwtSigningAlgorithm, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } from "./client-assertion.mjs";
-import { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider } from "./oauth-provider.mjs";
+import { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthRefreshContext, ProviderGrantAuthority, ProviderOptions, UpstreamProvider } from "./oauth-provider.mjs";
 import { TokenEndpointAuth, TokenEndpointAuthMethod, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
 import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { 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, type OAuthRefreshContext, 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/oauth-provider.d.mts

@@ -69,6 +69,17 @@ 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;
+}
 /**
  * The result of building a provider authorization URL.
  *
@@ -128,6 +139,12 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     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,
@@ -144,6 +161,12 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     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
@@ -160,9 +183,13 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
     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;
   /**
    * Declarative id_token verification config consumed by the shared
    * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
@@ -175,6 +202,13 @@ interface UpstreamProvider<T extends Record<string, any> = Record<string, any>,
    * 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.
@@ -333,4 +367,4 @@ type ProviderOptions<Profile extends Record<string, any> = any> = {
   requireEmailVerification?: boolean | undefined;
 };
 //#endregion
-export { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider };
+export { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, OAuthRefreshContext, ProviderGrantAuthority, ProviderOptions, UpstreamProvider };

package/dist/oauth2/refresh-access-token.mjs

@@ -1,6 +1,13 @@
 import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/refresh-access-token.ts
+const BLOCKED_REFRESH_TOKEN_PARAMS_SET = new Set([
+	"grant_type",
+	"refresh_token",
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
 async function refreshAccessTokenRequest({ refreshToken, options, authentication, tokenEndpointAuth, tokenEndpoint, extraParams, resource }) {
 	options = typeof options === "function" ? await options() : options;
 	const request = buildRefreshAccessTokenRequest({
@@ -20,6 +27,13 @@ async function refreshAccessTokenRequest({ refreshToken, options, authentication
 	});
 	return request;
 }
+function applyRefreshExtraParams(body, extraParams) {
+	if (!extraParams) return;
+	for (const [key, value] of Object.entries(extraParams)) {
+		if (BLOCKED_REFRESH_TOKEN_PARAMS_SET.has(key)) continue;
+		body.set(key, value);
+	}
+}
 function buildRefreshAccessTokenRequest({ refreshToken, options, extraParams, resource }) {
 	const body = new URLSearchParams();
 	const headers = {
@@ -30,7 +44,7 @@ function buildRefreshAccessTokenRequest({ refreshToken, options, extraParams, re
 	body.set("refresh_token", refreshToken);
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
-	if (extraParams) for (const [key, value] of Object.entries(extraParams)) body.set(key, value);
+	if (extraParams) applyRefreshExtraParams(body, extraParams);
 	return {
 		body,
 		headers

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 };