@better-auth/oauth-provider 1.7.0-rc.2 → 1.7.0-rc.3

package/dist/{client-assertion-C-Cg0dCs.mjs → client-assertion-CsbEATZc.mjs}

@@ -1,4 +1,4 @@
-import { o as getClient } from "./resource-challenge-2qgK1B-a.mjs";
+import { N as getClientDiscoveries, a as getClient } from "./utils-GbnW6qPl.mjs";
 import { isPublicRoutableHost } from "@better-auth/core/utils/host";
 import { APIError } from "better-call";
 import { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS } from "@better-auth/core/oauth2";
@@ -17,18 +17,105 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
+//#region src/client-jwks.ts
+const EC_PRIVATE_KEY_JWT_ALGORITHM_BY_CURVE = {
+	"P-256": "ES256",
+	"P-384": "ES384",
+	"P-521": "ES512"
+};
+const OKP_PRIVATE_KEY_JWT_SIGNING_CURVES = ["Ed25519"];
+const PRIVATE_JWK_MEMBER_NAMES = [
+	"d",
+	"p",
+	"q",
+	"dp",
+	"dq",
+	"qi",
+	"oth"
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasStringMember(key, memberName) {
+	return typeof key[memberName] === "string" && key[memberName].length > 0;
+}
+function isSupportedEcSigningCurve(curve) {
+	return typeof curve === "string" && Object.prototype.hasOwnProperty.call(EC_PRIVATE_KEY_JWT_ALGORITHM_BY_CURVE, curve);
+}
+function isSupportedOkpSigningCurve(curve) {
+	return OKP_PRIVATE_KEY_JWT_SIGNING_CURVES.some((signingCurve) => signingCurve === curve);
+}
+function isSupportedPublicJwk(key) {
+	switch (key.kty) {
+		case "RSA": return hasStringMember(key, "n") && hasStringMember(key, "e");
+		case "EC": return isSupportedEcSigningCurve(key.crv) && hasStringMember(key, "x") && hasStringMember(key, "y");
+		case "OKP": return isSupportedOkpSigningCurve(key.crv) && hasStringMember(key, "x");
+		default: return false;
+	}
+}
+function hasSupportedPrivateKeyJwtAlgorithm(key) {
+	if (key.alg === void 0) return true;
+	if (typeof key.alg !== "string" || !PRIVATE_KEY_JWT_SIGNING_ALGORITHMS.some((algorithm) => algorithm === key.alg)) return false;
+	switch (key.kty) {
+		case "RSA": return key.alg.startsWith("RS") || key.alg.startsWith("PS");
+		case "EC": return isSupportedEcSigningCurve(key.crv) && EC_PRIVATE_KEY_JWT_ALGORITHM_BY_CURVE[key.crv] === key.alg;
+		case "OKP": return isSupportedOkpSigningCurve(key.crv) && key.alg === "EdDSA";
+		default: return false;
+	}
+}
+/**
+* Validates an OAuth client's public asymmetric JWK set.
+*
+* This boundary accepts only the RFC 7517 `{ keys: [...] }` representation.
+* It performs no I/O and returns the validated set for downstream JOSE
+* verification.
+*
+* @internal
+*/
+function validatePublicClientJwks(input) {
+	const keys = isRecord(input) && Array.isArray(input.keys) ? input.keys : void 0;
+	if (!keys?.length) return {
+		valid: false,
+		error: "jwks must be an RFC 7517 JWK Set object with a non-empty keys array"
+	};
+	for (const key of keys) {
+		if (!isRecord(key)) return {
+			valid: false,
+			error: "jwks keys must be supported public JWKs with required key parameters"
+		};
+		if (key.kty === "oct" || "k" in key || PRIVATE_JWK_MEMBER_NAMES.some((name) => name in key)) return {
+			valid: false,
+			error: "jwks must contain only public asymmetric keys"
+		};
+		if (!isSupportedPublicJwk(key)) return {
+			valid: false,
+			error: "jwks keys must be supported public JWKs with required key parameters"
+		};
+		if (!hasSupportedPrivateKeyJwtAlgorithm(key)) return {
+			valid: false,
+			error: "jwks key alg must be supported for private_key_jwt and compatible with its key type and signing curve"
+		};
+	}
+	return {
+		valid: true,
+		jwks: { keys }
+	};
+}
+//#endregion
 //#region src/utils/client-assertion.ts
 var client_assertion_exports = /* @__PURE__ */ __exportAll({
 	consumeClientAssertion: () => consumeClientAssertion,
 	isPrivateHostname: () => isPrivateHostname,
 	verifyClientAssertion: () => verifyClientAssertion
 });
-const jwksCache = /* @__PURE__ */ new Map();
+const jwksCaches = /* @__PURE__ */ new WeakMap();
 const JWKS_CACHE_TTL_MS = 300 * 1e3;
 const JWKS_CACHE_MAX_ENTRIES = 500;
 const JWKS_FETCH_TIMEOUT_MS = 5e3;
-function setJwksCache(uri, jwks, fetchedAt) {
-	jwksCache.set(uri, {
+const MAX_JWKS_RESPONSE_BYTES = 64 * 1024;
+const JSON_CONTENT_TYPE = /^application\/(?:[-\w.]+\+)?json\s*(?:;|$)/i;
+function setJwksCache(jwksCache, cacheKey, jwks, fetchedAt) {
+	jwksCache.set(cacheKey, {
 		jwks,
 		fetchedAt
 	});
@@ -37,6 +124,16 @@ function setJwksCache(uri, jwks, fetchedAt) {
 		if (oldest !== void 0) jwksCache.delete(oldest);
 	}
 }
+function getJwksCache(opts) {
+	const existingCache = jwksCaches.get(opts);
+	if (existingCache) return existingCache;
+	const cache = /* @__PURE__ */ new Map();
+	jwksCaches.set(opts, cache);
+	return cache;
+}
+function getJwksCacheKey(client) {
+	return `${client.clientDiscoveryId ?? "managed"}:${client.jwksUri ?? ""}`;
+}
 const ALGORITHMS_LIST = [...PRIVATE_KEY_JWT_SIGNING_ALGORITHMS];
 /**
 * SSRF gate for user-supplied server-side fetch targets (`jwks_uri`,
@@ -60,6 +157,14 @@ function validateJwksUri(ctx, jwksUri, clientIdUrlOrigin) {
 		error_description: "jwks_uri must use HTTPS",
 		error: "invalid_client"
 	});
+	if (parsed.username || parsed.password) throw new APIError("BAD_REQUEST", {
+		error_description: "jwks_uri must not contain credentials",
+		error: "invalid_client"
+	});
+	if (jwksUri.includes("#")) throw new APIError("BAD_REQUEST", {
+		error_description: "jwks_uri must not include a fragment component",
+		error: "invalid_client"
+	});
 	if (isPrivateHostname(parsed.hostname)) throw new APIError("BAD_REQUEST", {
 		error_description: "jwks_uri must not point to a private or reserved address",
 		error: "invalid_client"
@@ -71,63 +176,120 @@ function validateJwksUri(ctx, jwksUri, clientIdUrlOrigin) {
 	});
 }
 function urlClientIdOrigin(clientId) {
-	if (!clientId.startsWith("https://") && !clientId.startsWith("http://")) return;
 	try {
-		return new URL(clientId).origin;
+		const parsed = new URL(clientId);
+		if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return;
+		return parsed.origin;
 	} catch {
 		return;
 	}
 }
-async function fetchJwksFromUri(jwksUri) {
+async function readBoundedResponseBody(response) {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength !== null && Number.isFinite(Number(contentLength)) && Number(contentLength) > MAX_JWKS_RESPONSE_BYTES) {
+		await response.body?.cancel();
+		throw new Error("JWKS response exceeds 64 KiB");
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let totalBytes = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		totalBytes += value.byteLength;
+		if (totalBytes > MAX_JWKS_RESPONSE_BYTES) {
+			await reader.cancel();
+			throw new Error("JWKS response exceeds 64 KiB");
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(totalBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+async function fetchJwksFromUri(jwksUri, fetchClientMetadataResource = globalThis.fetch) {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), JWKS_FETCH_TIMEOUT_MS);
 	try {
-		const response = await fetch(jwksUri, {
+		const response = await fetchClientMetadataResource(jwksUri, {
 			signal: controller.signal,
 			headers: { accept: "application/json" },
 			redirect: "error"
 		});
-		if (!response.ok) throw new Error(`JWKS fetch returned ${response.status}`);
-		const jwks = await response.json();
-		if (!jwks.keys || !Array.isArray(jwks.keys)) throw new Error("JWKS response missing keys array");
-		return jwks;
+		if (response.redirected) throw new Error("JWKS fetch redirected");
+		if (response.status !== 200) throw new Error(`JWKS fetch returned ${response.status}`);
+		const contentType = response.headers.get("content-type");
+		if (!contentType || !JSON_CONTENT_TYPE.test(contentType)) throw new Error("JWKS response must use a JSON media type");
+		const responseBody = await readBoundedResponseBody(response);
+		let parsedBody;
+		try {
+			parsedBody = JSON.parse(responseBody);
+		} catch {
+			return { valid: false };
+		}
+		const result = validatePublicClientJwks(parsedBody);
+		if (!result.valid) return { valid: false };
+		return {
+			valid: true,
+			jwks: result.jwks
+		};
 	} finally {
 		clearTimeout(timeout);
 	}
 }
-async function fetchClientJwks(ctx, client) {
+function createClientJwksFetchError() {
+	return new APIError("BAD_REQUEST", {
+		error_description: "failed to fetch client JWKS",
+		error: "invalid_client"
+	});
+}
+async function fetchClientJwks(ctx, opts, client) {
 	if (client.jwks) return JSON.parse(client.jwks);
 	if (!client.jwksUri) throw new APIError("BAD_REQUEST", {
 		error_description: "client has no JWKS configured",
 		error: "invalid_client"
 	});
-	validateJwksUri(ctx, client.jwksUri, urlClientIdOrigin(client.clientId));
+	const discovery = client.clientDiscoveryId ? getClientDiscoveries(opts).find((candidate) => candidate.id === client.clientDiscoveryId) : void 0;
+	if (client.clientDiscoveryId && !discovery?.fetchClientMetadataResource) throw new APIError("BAD_REQUEST", {
+		error_description: "client discovery does not provide a metadata resource transport",
+		error: "invalid_client"
+	});
+	validateJwksUri(ctx, client.jwksUri, client.clientDiscoveryId ? urlClientIdOrigin(client.clientId) : void 0);
 	const now = Date.now();
-	const cached = jwksCache.get(client.jwksUri);
+	const cacheKey = getJwksCacheKey(client);
+	const jwksCache = getJwksCache(opts);
+	const cached = jwksCache.get(cacheKey);
 	if (cached && now - cached.fetchedAt < JWKS_CACHE_TTL_MS) return cached.jwks;
+	let result;
 	try {
-		const jwks = await fetchJwksFromUri(client.jwksUri);
-		setJwksCache(client.jwksUri, jwks, now);
-		return jwks;
+		result = await fetchJwksFromUri(client.jwksUri, discovery?.fetchClientMetadataResource);
 	} catch {
 		const staleLimitMs = JWKS_CACHE_TTL_MS * 2;
 		if (cached && now - cached.fetchedAt < staleLimitMs) return cached.jwks;
-		throw new APIError("BAD_REQUEST", {
-			error_description: "failed to fetch client JWKS",
-			error: "invalid_client"
-		});
+		throw createClientJwksFetchError();
 	}
+	if (!result.valid) throw createClientJwksFetchError();
+	setJwksCache(jwksCache, cacheKey, result.jwks, now);
+	return result.jwks;
 }
 /**
 * Refetch JWKS from jwks_uri when signature verification fails with cached keys.
 * Handles key rotation: the client may have published a new key that isn't in our cache yet.
 */
-async function refetchClientJwks(client) {
+async function refetchClientJwks(opts, client) {
 	if (!client.jwksUri) return null;
+	const discovery = client.clientDiscoveryId ? getClientDiscoveries(opts).find((candidate) => candidate.id === client.clientDiscoveryId) : void 0;
+	if (client.clientDiscoveryId && !discovery?.fetchClientMetadataResource) return null;
 	try {
-		const jwks = await fetchJwksFromUri(client.jwksUri);
-		setJwksCache(client.jwksUri, jwks, Date.now());
-		return jwks;
+		const result = await fetchJwksFromUri(client.jwksUri, discovery?.fetchClientMetadataResource);
+		if (!result.valid) return null;
+		setJwksCache(getJwksCache(opts), getJwksCacheKey(client), result.jwks, Date.now());
+		return result.jwks;
 	} catch {
 		return null;
 	}
@@ -265,7 +427,7 @@ async function verifyClientAssertion(ctx, opts, clientAssertion, clientAssertion
 		error_description: "client is not registered for private_key_jwt authentication",
 		error: "invalid_client"
 	});
-	const jwks = await fetchClientJwks(ctx, client);
+	const jwks = await fetchClientJwks(ctx, opts, client);
 	const audience = expectedAudience ?? `${ctx.context.baseURL}/oauth2/token`;
 	const verifyOpts = {
 		issuer: clientId,
@@ -278,7 +440,7 @@ async function verifyClientAssertion(ctx, opts, clientAssertion, clientAssertion
 		({payload} = await jwtVerify(clientAssertion, createLocalJWKSet(jwks), verifyOpts));
 	} catch (verifyErr) {
 		if (verifyErr instanceof Error && /no matching key|no applicable key/i.test(verifyErr.message)) {
-			const refreshed = await refetchClientJwks(client);
+			const refreshed = await refetchClientJwks(opts, client);
 			if (refreshed) try {
 				({payload} = await jwtVerify(clientAssertion, createLocalJWKSet(refreshed), verifyOpts));
 			} catch {
@@ -304,4 +466,4 @@ async function verifyClientAssertion(ctx, opts, clientAssertion, clientAssertion
 	return { clientId };
 }
 //#endregion
-export { __exportAll as i, consumeClientAssertion as n, isPrivateHostname as r, client_assertion_exports as t };
+export { __exportAll as a, validatePublicClientJwks as i, consumeClientAssertion as n, isPrivateHostname as r, client_assertion_exports as t };

package/dist/client-resource.d.mts

@@ -1,4 +1,4 @@
-import { c as ResourceServerMetadata } from "./oauth-CSzjH7fO.mjs";
+import { c as ResourceServerMetadata } from "./oauth-Bi2PA_d1.mjs";
 import { ResourceRequestInput, VerifyAccessTokenRequestOptions } from "better-auth/oauth2";
 import { JWTPayload, JWTVerifyOptions } from "jose";
 import { BetterAuthOptions } from "better-auth/types";
@@ -72,7 +72,8 @@ type VerifyAccessTokenOutput<T> = T extends undefined ? (token: string | undefin
 type VerifyAccessTokenRequestOutput<T> = T extends undefined ? (request: Request | ResourceRequestInput, opts: VerifyAccessTokenRequestNoAuthOpts) => Promise<JWTPayload> : (request: Request | ResourceRequestInput, opts?: VerifyAccessTokenRequestAuthOpts) => Promise<JWTPayload>;
 type VerifyAccessTokenAuthOpts = {
   verifyOptions?: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience">>;
-  scopes?: string[];
+  requiredScopes?: readonly string[];
+  isScopeSatisfied?: VerifyAccessTokenRequestOptions["isScopeSatisfied"];
   jwksUrl?: string;
   remoteVerify?: VerifyAccessTokenRemote;
   /** Maps non-url (ie urn, client) resources to resource_metadata */
@@ -83,14 +84,16 @@ type VerifyAccessTokenRequestAuthOpts = VerifyAccessTokenAuthOpts & {
 };
 type VerifyAccessTokenNoAuthOpts = {
   verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-  scopes?: string[];
+  requiredScopes?: readonly string[];
+  isScopeSatisfied?: VerifyAccessTokenRequestOptions["isScopeSatisfied"];
   jwksUrl: string;
   remoteVerify?: VerifyAccessTokenRemote;
   /** Maps non-url (ie urn, client) resources to resource_metadata */
   resourceMetadataMappings?: Record<string, string>;
 } | {
   verifyOptions: JWTVerifyOptions & Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-  scopes?: string[];
+  requiredScopes?: readonly string[];
+  isScopeSatisfied?: VerifyAccessTokenRequestOptions["isScopeSatisfied"];
   jwksUrl?: string;
   remoteVerify: VerifyAccessTokenRemote;
   /** Maps non-url (ie urn, client) resources to resource_metadata */

package/dist/client-resource.mjs

@@ -1,5 +1,6 @@
-import { c as getOAuthProviderPlugin, s as getJwtPlugin, t as raiseResourceServerChallenge } from "./resource-challenge-2qgK1B-a.mjs";
-import { t as PACKAGE_VERSION } from "./version-C0y8aPv-.mjs";
+import { o as getJwtPlugin, s as getOAuthProviderPlugin } from "./utils-GbnW6qPl.mjs";
+import { t as PACKAGE_VERSION } from "./version-xoFrTW0m.mjs";
+import { t as createResourceServerChallenge } from "./resource-challenge-CiJTlsEh.mjs";
 import { APIError } from "better-call";
 import { logger } from "@better-auth/core/env";
 import { BetterAuthError } from "@better-auth/core/error";
@@ -63,10 +64,12 @@ const oauthProviderResourceClient = (auth) => {
 						if (!token?.length) throw new APIError("UNAUTHORIZED", { message: "missing authorization header" });
 						return await verifyBearerToken(token, verifyOptions);
 					} catch (error) {
-						raiseResourceServerChallenge(error, verifyOptions.verifyOptions.audience, {
+						const challenge = createResourceServerChallenge(error, verifyOptions.verifyOptions.audience, {
 							resourceMetadataMappings: opts?.resourceMetadataMappings,
 							dpopSigningAlgorithms: DPOP_SIGNING_ALGORITHMS
 						});
+						if (challenge) throw challenge;
+						throw error;
 					}
 				}),
 				/**
@@ -80,10 +83,12 @@ const oauthProviderResourceClient = (auth) => {
 					try {
 						return await verifyAccessTokenRequest(toResourceRequestInput(request), verifyOptions);
 					} catch (error) {
-						raiseResourceServerChallenge(error, verifyOptions.verifyOptions.audience, {
+						const challenge = createResourceServerChallenge(error, verifyOptions.verifyOptions.audience, {
 							resourceMetadataMappings: opts?.resourceMetadataMappings,
 							dpopSigningAlgorithms: opts?.dpop?.signingAlgorithms ?? DPOP_SIGNING_ALGORITHMS
 						});
+						if (challenge) throw challenge;
+						throw error;
 					}
 				}),
 				/**

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { r as oauthProvider } from "./oauth-DdSU0qF6.mjs";
+import { r as oauthProvider } from "./oauth-CgWbnA8o.mjs";
 //#region src/client.d.ts
 declare const oauthProviderClient: () => {
   id: "oauth-provider-client";

package/dist/client.mjs

@@ -1,4 +1,5 @@
-import { n as buildSignedOAuthQuery, t as PACKAGE_VERSION } from "./version-C0y8aPv-.mjs";
+import { t as buildSignedOAuthQuery } from "./signed-query-BQAwsV_w.mjs";
+import { t as PACKAGE_VERSION } from "./version-xoFrTW0m.mjs";
 import { safeJSONParse } from "@better-auth/core/utils/json";
 //#region src/client.ts
 const oauthProviderClient = () => {

package/dist/index.d.mts

@@ -1,8 +1,45 @@
-import { A as OAuthProviderExtension, B as StoreTokenType, C as OAuthConsent, D as OAuthOpaqueAccessToken, E as OAuthMetadataExtensionInput, F as OAuthTokenResponse, H as VerificationValue, I as OAuthUserInfoExtensionInput, L as Prompt, M as OAuthResource, N as OAuthResourceInput, O as OAuthOptions, P as OAuthTokenIssueParams, R as SchemaClient, S as OAuthClientResource, T as OAuthExtensionGrantHandlerInput, U as ClientRegistrationRequest, V as StoredAuthorizationQuery, W as ResourceUriSchema, _ as OAuthClaimExtensionInput, a as GrantType, b as OAuthClientAuthenticationResult, c as ResourceServerMetadata, d as ActiveAccessTokenPayload, f as AuthorizePrompt, g as OAuthAuthorizationQuery, h as OAuthAuthenticatedClient, i as Confirmation, j as OAuthRefreshToken, k as OAuthProviderApi, l as TokenEndpointAuthMethod, m as InitialAccessTokenAuthorization, n as AuthServerMetadata, o as OAuthClient, p as ClientDiscovery, r as BearerMethodsSupported, s as OIDCMetadata, t as AuthMethod, u as TokenType, v as OAuthClientAuthenticationInput, w as OAuthExtensionGrantHandler, x as OAuthClientAuthenticationStrategy, y as OAuthClientAuthenticationRequest, z as Scope } from "./oauth-CSzjH7fO.mjs";
-import { a as OAuthEndpointErrorResult, c as OAuthFieldErrorCode, i as getIssuer, l as OAuthFieldErrorCodeMap, n as getOAuthProviderState, o as OAuthEndpointRedirectContext, r as oauthProvider, s as OAuthErrorCode, t as DEFAULT_OAUTH_SCOPES, u as OAuthRedirectOnError } from "./oauth-DdSU0qF6.mjs";
-import { getSessionFromCtx } from "better-auth/api";
+import { A as OAuthOpaqueAccessToken, B as Prompt, C as OAuthClientAuthenticationStrategy, D as OAuthExtensionGrantHandler, E as OAuthConsent, F as OAuthResource, G as VerificationValue, H as Scope, I as OAuthResourceInput, J as ResourceUriSchema, K as ClientRegistrationRequest, L as OAuthTokenIssueParams, M as OAuthProviderApi, N as OAuthProviderExtension, O as OAuthExtensionGrantHandlerInput, P as OAuthRefreshToken, R as OAuthTokenResponse, S as OAuthClientAuthenticationResult, T as OAuthClientResource, U as StoreTokenType, V as SchemaClient, W as StoredAuthorizationQuery, Y as oauthClientMetadataSchema, _ as OAuthAuthorizationQuery, a as GrantType, b as OAuthClientAuthenticationInput, c as ResourceServerMetadata, d as ActiveAccessTokenPayload, f as AuthorizePrompt, g as OAuthAuthenticatedClient, h as InitialAccessTokenAuthorization, i as Confirmation, j as OAuthOptions, k as OAuthMetadataExtensionInput, l as TokenEndpointAuthMethod, m as ClientMetadataResourceFetch, n as AuthServerMetadata, o as OAuthClient, p as ClientDiscovery, q as OAuthClientMetadata, r as BearerMethodsSupported, s as OIDCMetadata, t as AuthMethod, u as TokenType, v as OAuthClaimExtensionInput, w as OAuthClientRegistrationResponse, x as OAuthClientAuthenticationRequest, y as OAuthClientAdministrativeResponse, z as OAuthUserInfoExtensionInput } from "./oauth-Bi2PA_d1.mjs";
+import { a as OAuthEndpointErrorResult, c as OAuthFieldErrorCode, i as getIssuer, l as OAuthFieldErrorCodeMap, n as getOAuthProviderState, o as OAuthEndpointRedirectContext, r as oauthProvider, s as OAuthErrorCode, t as DEFAULT_OAUTH_SCOPES, u as OAuthRedirectOnError } from "./oauth-CgWbnA8o.mjs";
+import { APIError } from "better-call";
 import { JWSAlgorithms, JwtOptions } from "better-auth/plugins";
+import { BetterAuthPlugin } from "better-auth/types";
 import { AuthContext, GenericEndpointContext } from "@better-auth/core";
+//#region src/device-code.d.ts
+/**
+ * RFC 8628 device authorization grant type. A registered OAuth client polls the
+ * token endpoint with this `grant_type` to exchange an approved device code for
+ * a first-class OAuth token set.
+ */
+declare const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/**
+ * Bridges the {@link https://datatracker.ietf.org/doc/html/rfc8628 RFC 8628}
+ * device authorization grant into the OAuth Provider. Pair it with the
+ * `device-authorization` plugin (which owns the `/device/code` request endpoint,
+ * the user verification flow, and the `deviceCode` table) and the
+ * `oauthProvider` plugin: this registers a `device_code` token grant on
+ * `/oauth2/token` that issues real OAuth tokens for a registered OAuth client,
+ * and advertises `device_authorization_endpoint` in discovery metadata.
+ *
+ * First-party device login (the device-authorization plugin's own
+ * `/device/token`, which mints a Better Auth session token) keeps working
+ * unchanged. To stop a registered OAuth client's device code from being redeemed
+ * there for a session token, a `before` hook rejects `/device/token` requests
+ * whose `client_id` resolves to a registered OAuth client, directing them to
+ * `/oauth2/token`.
+ *
+ * @example
+ * ```ts
+ * const auth = betterAuth({
+ *   plugins: [
+ *     deviceAuthorization(),
+ *     oauthProvider({ ...  }),
+ *     deviceCodeGrant(),
+ *   ],
+ * });
+ * ```
+ */
+declare function deviceCodeGrant(): BetterAuthPlugin;
+//#endregion
 //#region src/extensions.d.ts
 /**
  * Registers an {@link OAuthProviderExtension} with the OAuth Provider plugin
@@ -17,8 +54,8 @@ import { AuthContext, GenericEndpointContext } from "@better-auth/core";
  * twice. It throws if the oauth-provider plugin is not installed, if a grant
  * type or assertion type is not an absolute URI, if a client authentication
  * method reuses a built-in name, or if the extension registers a grant type,
- * auth method, or assertion type that another extension already registered
- * (contributions must be disjoint).
+ * auth method, assertion type, or client discovery identifier that another
+ * extension already registered (contributions must be disjoint).
  *
  * @example
  * ```ts
@@ -116,39 +153,37 @@ declare const oauthProviderOpenIdConfigMetadata: <Auth extends {
   headers?: HeadersInit;
 }) => (request: Request) => Promise<Response>;
 //#endregion
-//#region src/register.d.ts
-declare function checkOAuthClient(client: OAuthClient, opts: OAuthOptions<Scope[]>, settings?: {
-  isRegister?: boolean;
-  ctx?: GenericEndpointContext;
-}): Promise<void>;
-/**
- * Converts an OAuth 2.0 Dynamic Client Schema to a Database Schema
- *
- * @param input
- * @returns
- */
-declare function oauthToSchema(input: OAuthClient): SchemaClient<Scope[]>;
-//#endregion
 //#region src/resource-challenge.d.ts
 /**
- * Raise an OAuth resource-server challenge for a failed access-token request.
+ * Create an OAuth resource-server challenge for a failed access-token request.
  *
  * Missing/invalid bearer credentials are reported with RFC 6750 plus the RFC
- * 9728 `resource_metadata` pointer. DPoP-bound-token failures are reported with
- * RFC 9449's `DPoP` challenge so clients know which proof algorithms to use.
- * Non-URL resources (for example a `urn:` or a client id) resolve their
- * metadata URL through `resourceMetadataMappings`.
+ * 9728 `resource_metadata` pointer. Insufficient-scope failures (built with
+ * `createInsufficientScopeError`) are reported with RFC 6750 §3.1's
+ * `insufficient_scope` challenge on a 403 naming the scopes the token lacks, so
+ * clients can step up their authorization. DPoP-bound-token failures are
+ * reported with RFC 9449's `DPoP` challenge so clients know which proof
+ * algorithms to use. Non-URL resources (for example a `urn:` or a client id)
+ * resolve their metadata URL through `resourceMetadataMappings`.
  *
- * @internal
+ * Every other error returns `undefined`, including a plain `FORBIDDEN`: a
+ * permission denial that re-authorizing cannot fix must not be answered with a
+ * challenge that sends the user through consent for scopes they already hold.
+ *
+ * @external
  */
-declare function raiseResourceServerChallenge(error: unknown, resource: string | string[], opts?: {
+declare function createResourceServerChallenge(error: unknown, resource: string | string[], opts?: {
   /** Maps non-URL (urn, client) resources to their resource_metadata URL. */
   resourceMetadataMappings?: Record<string, string>;
   /** DPoP JWS algorithms to advertise in RFC 9449 challenges. */
   dpopSigningAlgorithms?: readonly string[];
-  /** Space-delimited scopes to advertise in RFC 6750 bearer challenges. */
-  scope?: string;
-}): never;
+  /**
+   * Scopes to advertise in RFC 6750 bearer challenges,
+   * hinting what an unauthenticated client should request. An
+   * insufficient-scope failure advertises the scopes it names instead.
+   */
+  challengeScopes?: readonly string[];
+}): APIError | undefined;
 //#endregion
 //#region src/token.d.ts
 /**
@@ -195,4 +230,4 @@ declare function consumeClientAssertion(ctx: GenericEndpointContext, opts: OAuth
   expectedAudience: string;
 }): Promise<void>;
 //#endregion
-export { type ActiveAccessTokenPayload, type AuthMethod, type AuthServerMetadata, type AuthorizePrompt, type BearerMethodsSupported, type ClientDiscovery, type ClientRegistrationRequest, type Confirmation, DEFAULT_OAUTH_SCOPES, type GrantType, type InitialAccessTokenAuthorization, type OAuthAuthenticatedClient, type OAuthAuthorizationQuery, type OAuthClaimExtensionInput, type OAuthClient, type OAuthClientAuthenticationInput, type OAuthClientAuthenticationRequest, type OAuthClientAuthenticationResult, type OAuthClientAuthenticationStrategy, type OAuthClientResource, type OAuthConsent, type OAuthEndpointErrorResult, type OAuthEndpointRedirectContext, type OAuthErrorCode, type OAuthExtensionGrantHandler, type OAuthExtensionGrantHandlerInput, type OAuthFieldErrorCode, type OAuthFieldErrorCodeMap, type OAuthMetadataExtensionInput, type OAuthOpaqueAccessToken, type OAuthOptions, type OAuthProviderApi, type OAuthProviderExtension, type OAuthRedirectOnError, type OAuthRefreshToken, type OAuthResource, type OAuthResourceInput, type OAuthTokenIssueParams, type OAuthTokenResponse, type OAuthUserInfoExtensionInput, type OIDCMetadata, type Prompt, type ResourceServerMetadata, ResourceUriSchema, type SchemaClient, type Scope, type StoreTokenType, type StoredAuthorizationQuery, type TokenEndpointAuthMethod, type TokenType, type VerificationValue, authServerMetadata, checkOAuthClient, consumeClientAssertion, extendOAuthProvider, getIssuer, getOAuthProviderApi, getOAuthProviderState, metadataResponse, oauthAuthorizationServerMetadata, oauthProvider, oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata, oauthToSchema, oidcServerMetadata, raiseResourceServerChallenge };
+export { type ActiveAccessTokenPayload, type AuthMethod, type AuthServerMetadata, type AuthorizePrompt, type BearerMethodsSupported, type ClientDiscovery, type ClientMetadataResourceFetch, type ClientRegistrationRequest, type Confirmation, DEFAULT_OAUTH_SCOPES, DEVICE_CODE_GRANT_TYPE, type GrantType, type InitialAccessTokenAuthorization, type OAuthAuthenticatedClient, type OAuthAuthorizationQuery, type OAuthClaimExtensionInput, type OAuthClient, type OAuthClientAdministrativeResponse, type OAuthClientAuthenticationInput, type OAuthClientAuthenticationRequest, type OAuthClientAuthenticationResult, type OAuthClientAuthenticationStrategy, type OAuthClientMetadata, type OAuthClientRegistrationResponse, type OAuthClientResource, type OAuthConsent, type OAuthEndpointErrorResult, type OAuthEndpointRedirectContext, type OAuthErrorCode, type OAuthExtensionGrantHandler, type OAuthExtensionGrantHandlerInput, type OAuthFieldErrorCode, type OAuthFieldErrorCodeMap, type OAuthMetadataExtensionInput, type OAuthOpaqueAccessToken, type OAuthOptions, type OAuthProviderApi, type OAuthProviderExtension, type OAuthRedirectOnError, type OAuthRefreshToken, type OAuthResource, type OAuthResourceInput, type OAuthTokenIssueParams, type OAuthTokenResponse, type OAuthUserInfoExtensionInput, type OIDCMetadata, type Prompt, type ResourceServerMetadata, ResourceUriSchema, type SchemaClient, type Scope, type StoreTokenType, type StoredAuthorizationQuery, type TokenEndpointAuthMethod, type TokenType, type VerificationValue, authServerMetadata, consumeClientAssertion, createResourceServerChallenge, deviceCodeGrant, extendOAuthProvider, getIssuer, getOAuthProviderApi, getOAuthProviderState, metadataResponse, oauthAuthorizationServerMetadata, oauthClientMetadataSchema, oauthProvider, oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata, oidcServerMetadata };