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

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,12 +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 { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions } from "./oauth-provider.mjs";
+import { AuthorizationURLResult, GrantAuthority, OAuth2Tokens, OAuth2UserInfo, OAuthIdTokenConfig, ProviderGrantAuthority, ProviderOptions, UpstreamProvider } from "./oauth-provider.mjs";
 import { TokenEndpointAuth, TokenEndpointAuthMethod, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
 import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { 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";
-export { CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, type PrivateKeyJwtClientAssertionGetterOptions, type PrivateKeyJwtSigningAlgorithm, type ProviderOptions, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { ResourceRequestInput, VerifyAccessTokenOptions, VerifyAccessTokenRequestOptions, getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { type AccessTokenAuthorization, type AccessTokenAuthorizationScheme, 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

@@ -1,10 +1,13 @@
+import { includesGrantedScope, normalizeScopes, parseScopeField, readGrantedScopes, resolveRequestedScopes, unionGrantedScopes } from "./scopes.mjs";
 import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
 import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
 import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
 import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
 import { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } from "./client-assertion.mjs";
 import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
+import { 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";
-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, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+import { getJwks, requestToResourceInput, verifyAccessTokenRequest, verifyBearerToken, verifyJwsAccessToken } from "./verify.mjs";
+import { supportsIdTokenSignIn, verifyProviderIdToken } from "./verify-id-token.mjs";
+export { BEARER_AUTHORIZATION_SCHEME, CLIENT_ASSERTION_TYPE, DPOP_AUTHORIZATION_SCHEME, DPOP_PROOF_TYPE, DPOP_SIGNING_ALGORITHMS, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createDpopBindingError, createDpopProofError, createDpopReplayStore, createInMemoryDpopReplayStore, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, deriveDpopAth, deriveDpopJkt, encodeBasicCredentials, enforceDpopBinding, generateCodeChallenge, getConfirmationJkt, getDpopJktFromPayload, getJwks, getOAuth2Tokens, getPrimaryClientId, 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

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

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

@@ -56,7 +56,7 @@ async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authen
 		accessToken: data.access_token,
 		refreshToken: data.refresh_token,
 		tokenType: data.token_type,
-		scopes: data.scope?.split(" "),
+		scopes: Array.isArray(data.scope) ? data.scope : data.scope?.split(" "),
 		idToken: data.id_token
 	};
 	if (data.expires_in) {