@better-auth/oauth-provider 1.7.0-beta.1 → 1.7.0-beta.2

package/dist/client-resource.mjs

@@ -1,6 +1,6 @@
 import { t as handleMcpErrors } from "./mcp-CYnz-MXn.mjs";
 import { o as getJwtPlugin, s as getOAuthProviderPlugin } from "./utils-Cx_XnD9i.mjs";
-import { t as PACKAGE_VERSION } from "./version-DIwdpXrQ.mjs";
+import { t as PACKAGE_VERSION } from "./version-CZxZ64qJ.mjs";
 import { verifyAccessToken } from "better-auth/oauth2";
 import { APIError } from "better-call";
 import { logger } from "@better-auth/core/env";

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { n as oauthProvider } from "./oauth-B_qonG53.mjs";
+import { n as oauthProvider } from "./oauth-DJcZ8MMZ.mjs";
 import * as _better_fetch_fetch0 from "@better-fetch/fetch";
 
 //#region src/client.d.ts

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-DIwdpXrQ.mjs";
+import { t as PACKAGE_VERSION } from "./version-CZxZ64qJ.mjs";
 import { safeJSONParse } from "@better-auth/core/utils/json";
 //#region src/client.ts
 function parseSignedQuery(search) {

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { _ as Scope, a as OIDCMetadata, b as Awaitable, c as AuthorizePrompt, d as OAuthConsent, f as OAuthOpaqueAccessToken, g as SchemaClient, h as Prompt, i as OAuthClient, l as ClientDiscovery, m as OAuthRefreshToken, n as AuthServerMetadata, o as ResourceServerMetadata, p as OAuthOptions, r as GrantType, s as TokenEndpointAuthMethod, t as AuthMethod, u as OAuthAuthorizationQuery, v as StoreTokenType, y as VerificationValue } from "./oauth-CU79t-eG.mjs";
-import { n as oauthProvider, t as getOAuthProviderState } from "./oauth-B_qonG53.mjs";
+import { a as OAuthErrorCode, c as OAuthRedirectOnError, i as OAuthEndpointRedirectContext, n as oauthProvider, o as OAuthFieldErrorCode, r as OAuthEndpointErrorResult, s as OAuthFieldErrorCodeMap, t as getOAuthProviderState } from "./oauth-DJcZ8MMZ.mjs";
 import { verifyAccessToken } from "better-auth/oauth2";
 import { JWSAlgorithms, JwtOptions } from "better-auth/plugins";
 import { JWTPayload } from "jose";
@@ -105,4 +105,4 @@ declare function checkOAuthClient(client: OAuthClient, opts: OAuthOptions<Scope[
  */
 declare function oauthToSchema(input: OAuthClient): SchemaClient<Scope[]>;
 //#endregion
-export { AuthServerMetadata, AuthorizePrompt, ClientDiscovery, OAuthAuthorizationQuery, OAuthClient, OAuthConsent, OAuthOpaqueAccessToken, OAuthOptions, OAuthRefreshToken, OIDCMetadata, Prompt, ResourceServerMetadata, SchemaClient, Scope, StoreTokenType, VerificationValue, authServerMetadata, checkOAuthClient, getOAuthProviderState, mcpHandler, oauthProvider, oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata, oauthToSchema, oidcServerMetadata };
+export { AuthServerMetadata, AuthorizePrompt, ClientDiscovery, OAuthAuthorizationQuery, OAuthClient, OAuthConsent, type OAuthEndpointErrorResult, type OAuthEndpointRedirectContext, type OAuthErrorCode, type OAuthFieldErrorCode, type OAuthFieldErrorCodeMap, OAuthOpaqueAccessToken, OAuthOptions, type OAuthRedirectOnError, OAuthRefreshToken, OIDCMetadata, Prompt, ResourceServerMetadata, SchemaClient, Scope, StoreTokenType, VerificationValue, authServerMetadata, checkOAuthClient, getOAuthProviderState, mcpHandler, oauthProvider, oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata, oauthToSchema, oidcServerMetadata };

package/dist/index.mjs

@@ -1,12 +1,13 @@
 import { n as isPrivateHostname } from "./client-assertion-CderPEmR.mjs";
 import { n as mcpHandler } from "./mcp-CYnz-MXn.mjs";
 import { _ as storeClientSecret, a as getClient, b as validateClientCredentials, c as getStoredToken, d as normalizeTimestampValue, f as parseClientMetadata, g as searchParamsToQuery, h as resolveSubjectIdentifier, i as extractClientCredentials, l as isPKCERequired, m as resolveSessionAuthTime, n as deleteFromPrompt, o as getJwtPlugin, p as parsePrompt, r as destructureCredentials, t as decryptStoredClientSecret, u as mergeDiscoveryMetadata, v as storeToken, x as verifyOAuthQueryParams, y as toClientDiscoveryArray } from "./utils-Cx_XnD9i.mjs";
-import { t as PACKAGE_VERSION } from "./version-DIwdpXrQ.mjs";
+import { t as PACKAGE_VERSION } from "./version-CZxZ64qJ.mjs";
 import { APIError, createAuthEndpoint, createAuthMiddleware, getOAuthState, getSessionFromCtx, sessionMiddleware } from "better-auth/api";
 import { generateCodeChallenge, getJwks, verifyJwsAccessToken } from "better-auth/oauth2";
 import { APIError as APIError$1 } from "better-call";
 import { ASSERTION_SIGNING_ALGORITHMS } from "@better-auth/core/oauth2";
 import { isBrowserFetchRequest } from "@better-auth/core/utils/fetch-metadata";
+import { isLoopbackHost, isLoopbackIP } from "@better-auth/core/utils/host";
 import { generateRandomString, makeSignature } from "better-auth/crypto";
 import { defineRequestState } from "@better-auth/core/context";
 import { logger } from "@better-auth/core/env";
@@ -162,9 +163,6 @@ const DANGEROUS_SCHEMES = [
 	"data:",
 	"vbscript:"
 ];
-function isLocalhost(hostname) {
-	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname.endsWith(".localhost");
-}
 /**
 * Runtime schema for OAuthAuthorizationQuery.
 * Uses passthrough to tolerate fields added by future extensions (PAR, FPA, etc.)
@@ -203,7 +201,7 @@ const verificationValueSchema = z.object({
 /**
 * Reusable URL validation for OAuth redirect URIs.
 * - Blocks dangerous schemes (javascript:, data:, vbscript:)
-* - For http/https: requires HTTPS (HTTP allowed only for localhost)
+* - For http/https: requires HTTPS (HTTP allowed only for loopback hosts: 127.0.0.0/8, [::1], *.localhost per RFC 6761)
 * - Allows custom schemes for mobile apps (e.g., myapp://callback)
 */
 const SafeUrlSchema = z.url().superRefine((val, ctx) => {
@@ -223,12 +221,10 @@ const SafeUrlSchema = z.url().superRefine((val, ctx) => {
 		});
 		return;
 	}
-	if (u.protocol === "http:" || u.protocol === "https:") {
-		if (u.protocol === "http:" && !isLocalhost(u.hostname)) ctx.addIssue({
-			code: "custom",
-			message: "Redirect URI must use HTTPS (HTTP allowed only for localhost)"
-		});
-	}
+	if (u.protocol === "http:" && !isLoopbackHost(u.host)) ctx.addIssue({
+		code: "custom",
+		message: "Redirect URI must use HTTPS (HTTP allowed only for loopback hosts)"
+	});
 });
 //#endregion
 //#region src/userinfo.ts
@@ -259,11 +255,7 @@ function userNormalClaims(user, scopes) {
 * Handles the /oauth2/userinfo endpoint
 */
 async function userInfoEndpoint(ctx, opts) {
-	if (!ctx.request) throw new APIError("UNAUTHORIZED", {
-		error_description: "request not found",
-		error: "invalid_request"
-	});
-	const authorization = ctx.request.headers.get("authorization");
+	const authorization = ctx.headers?.get("authorization");
 	const token = typeof authorization === "string" && authorization?.startsWith("Bearer ") ? authorization?.replace("Bearer ", "") : authorization;
 	if (!token?.length) throw new APIError("UNAUTHORIZED", {
 		error_description: "authorization header not found",
@@ -309,8 +301,8 @@ async function userInfoEndpoint(ctx, opts) {
 * the grant types
 */
 async function tokenEndpoint(ctx, opts) {
-	const grantType = ctx.body?.grant_type;
-	if (opts.grantTypes && grantType && !opts.grantTypes.includes(grantType)) throw new APIError("BAD_REQUEST", {
+	const grantType = ctx.body.grant_type;
+	if (opts.grantTypes && !opts.grantTypes.includes(grantType)) throw new APIError("BAD_REQUEST", {
 		error_description: `unsupported grant_type ${grantType}`,
 		error: "unsupported_grant_type"
 	});
@@ -318,14 +310,6 @@ async function tokenEndpoint(ctx, opts) {
 		case "authorization_code": return handleAuthorizationCodeGrant(ctx, opts);
 		case "client_credentials": return handleClientCredentialsGrant(ctx, opts);
 		case "refresh_token": return handleRefreshTokenGrant(ctx, opts);
-		case void 0: throw new APIError("BAD_REQUEST", {
-			error_description: "missing required grant_type",
-			error: "unsupported_grant_type"
-		});
-		default: throw new APIError("BAD_REQUEST", {
-			error_description: `unsupported grant_type ${grantType}`,
-			error: "unsupported_grant_type"
-		});
 	}
 }
 async function createJwtAccessToken(ctx, opts, user, client, audience, scopes, referenceId, overrides) {
@@ -1016,6 +1000,7 @@ async function resolveIntrospectionSub(opts, payload, client) {
 }
 async function introspectEndpoint(ctx, opts) {
 	let { token, token_type_hint } = ctx.body;
+	if (token_type_hint !== "access_token" && token_type_hint !== "refresh_token") token_type_hint = void 0;
 	const { clientId: client_id, clientSecret: client_secret, preVerifiedClient } = destructureCredentials(await extractClientCredentials(ctx, opts, `${ctx.context.baseURL}/oauth2/introspect`));
 	if (!client_id || !client_secret && !preVerifiedClient) throw new APIError$1("UNAUTHORIZED", {
 		error_description: "missing required credentials",
@@ -1173,6 +1158,109 @@ async function rpInitiatedLogoutEndpoint(ctx, opts) {
 	}
 }
 //#endregion
+//#region src/oauth-endpoint.ts
+/**
+* Wraps `createAuthEndpoint` so zod schemas stay the single source of truth
+* for body/query shape while validation failures serialize as the RFC 6749
+* §5.2 error envelope `{ error, error_description }`.
+*
+* A failing issue is routed by its first path segment via `errorCodesByField`:
+* - missing required (`invalid_type` + "received undefined") → `.missing`
+* - unsupported value (`invalid_value`) → `.invalid`
+* - anything else (wrong type, duplicated params, bad format) → `defaultError`
+*
+* For enum fields that need to distinguish missing from unsupported, compose
+* as `z.string().pipe(z.enum([...]))` so duplicated params fail the outer
+* `z.string()` as `invalid_type` instead of masquerading as an unsupported
+* enum value.
+*/
+function createOAuthEndpoint(path, options, handler) {
+	const { redirectOnError, onValidationError: userHook, errorCodesByField, defaultError = "invalid_request", ...rest } = options;
+	if (!redirectOnError) return createAuthEndpoint(path, {
+		...rest,
+		onValidationError: async (args) => {
+			if (userHook) await userHook(args);
+			throw new APIError$1("BAD_REQUEST", { ...mapIssuesToOAuthError(args.issues, errorCodesByField, defaultError) });
+		}
+	}, handler);
+	const redirect = redirectOnError;
+	const { body: bodySchema, query: querySchema, ...forwarded } = rest;
+	async function validateSlot(ctx, slot, schema) {
+		if (!schema) return { ok: true };
+		const result = await schema.safeParseAsync(ctx[slot] ?? {});
+		if (result.success) {
+			ctx[slot] = result.data;
+			return { ok: true };
+		}
+		if (userHook) await userHook({
+			message: result.error.message,
+			issues: result.error.issues
+		});
+		return {
+			ok: false,
+			response: redirect({
+				...mapIssuesToOAuthError(result.error.issues, errorCodesByField, defaultError),
+				ctx
+			})
+		};
+	}
+	return createAuthEndpoint(path, forwarded, async (ctx) => {
+		const body = await validateSlot(ctx, "body", bodySchema);
+		if (!body.ok) return body.response;
+		const query = await validateSlot(ctx, "query", querySchema);
+		if (!query.ok) return query.response;
+		return handler(ctx);
+	});
+}
+function mapIssuesToOAuthError(issues, errorCodesByField, defaultError = "invalid_request") {
+	const issue = issues[0];
+	if (!issue) return {
+		error: defaultError,
+		error_description: "Invalid request."
+	};
+	const first = issue.path?.[0];
+	const fieldKey = typeof first === "string" ? first : void 0;
+	const mapping = fieldKey ? errorCodesByField?.[fieldKey] : void 0;
+	const field = issue.path?.length ? z.core.toDotPath(issue.path) : "";
+	return {
+		error: resolveErrorCode(issue, mapping, defaultError),
+		error_description: describeIssue(issue, field)
+	};
+}
+function resolveErrorCode(issue, mapping, defaultError) {
+	if (typeof mapping === "string") return mapping;
+	if (isMissingValueIssue(issue)) return mapping?.missing ?? defaultError;
+	if (issue.code === "invalid_value") return mapping?.invalid ?? defaultError;
+	return defaultError;
+}
+/**
+* Returns `true` for issues that represent an absent required value. Zod v4
+* strips `input` from published issues, so the signal is the `invalid_type`
+* code combined with a message suffix of "received undefined". The suffix is
+* pinned by a regression test so a zod rephrase fails the test instead of
+* silently reclassifying missing fields.
+*
+* Assumes the default zod error map. Consumers that install a localized map
+* via `z.setErrorMap()` will break this check, collapsing missing-field
+* failures to `defaultError`.
+*/
+function isMissingValueIssue(issue) {
+	return issue.code === "invalid_type" && issue.message.endsWith("received undefined");
+}
+function describeIssue(issue, field) {
+	if (!field) return issue.message;
+	if (issue.code === "invalid_type") {
+		if (issue.message.endsWith("received undefined")) return `${field} is required`;
+		if (issue.message.endsWith("received array")) return `${field} must not appear more than once`;
+		return `${field} must be a ${issue.expected ?? "valid value"}`;
+	}
+	if (issue.code === "invalid_value") {
+		const values = issue.values;
+		if (Array.isArray(values) && values.length > 0) return `${field} must be one of: ${values.join(", ")}`;
+	}
+	return `${field}: ${issue.message}`;
+}
+//#endregion
 //#region src/middleware/index.ts
 const publicSessionMiddleware = (opts) => createAuthMiddleware(async (ctx) => {
 	if (!opts.allowPublicClientPrelogin) throw new APIError("BAD_REQUEST");
@@ -1458,14 +1546,8 @@ function schemaToOAuth(input) {
 //#region src/oauthClient/endpoints.ts
 async function getClientEndpoint(ctx, opts) {
 	const session = await getSessionFromCtx(ctx);
+	await assertClientPrivileges(ctx, session, opts, "read");
 	if (!session) throw new APIError("UNAUTHORIZED");
-	if (!ctx.headers) throw new APIError("BAD_REQUEST");
-	if (opts.clientPrivileges && !await opts.clientPrivileges({
-		headers: ctx.headers,
-		action: "read",
-		session: session.session,
-		user: session.user
-	})) throw new APIError("UNAUTHORIZED");
 	const client = await getClient(ctx, opts, ctx.query.client_id);
 	if (!client) throw new APIError("NOT_FOUND", {
 		error_description: "client not found",
@@ -1506,14 +1588,8 @@ async function getClientPublicEndpoint(ctx, opts, clientId) {
 }
 async function getClientsEndpoint(ctx, opts) {
 	const session = await getSessionFromCtx(ctx);
+	await assertClientPrivileges(ctx, session, opts, "list");
 	if (!session) throw new APIError("UNAUTHORIZED");
-	if (!ctx.headers) throw new APIError("BAD_REQUEST");
-	if (opts.clientPrivileges && !await opts.clientPrivileges({
-		headers: ctx.headers,
-		action: "list",
-		session: session.session,
-		user: session.user
-	})) throw new APIError("UNAUTHORIZED");
 	const referenceId = await opts.clientReference?.(session);
 	if (referenceId) return await ctx.context.adapter.findMany({
 		model: "oauthClient",
@@ -1547,14 +1623,8 @@ async function getClientsEndpoint(ctx, opts) {
 }
 async function deleteClientEndpoint(ctx, opts) {
 	const session = await getSessionFromCtx(ctx);
+	await assertClientPrivileges(ctx, session, opts, "delete");
 	if (!session) throw new APIError("UNAUTHORIZED");
-	if (!ctx.headers) throw new APIError("BAD_REQUEST");
-	if (opts.clientPrivileges && !await opts.clientPrivileges({
-		headers: ctx.headers,
-		action: "delete",
-		session: session.session,
-		user: session.user
-	})) throw new APIError("UNAUTHORIZED");
 	const clientId = ctx.body.client_id;
 	if (opts.cachedTrustedClients?.has(clientId)) throw new APIError("INTERNAL_SERVER_ERROR", {
 		error_description: "trusted clients must be updated manually",
@@ -1580,14 +1650,8 @@ async function deleteClientEndpoint(ctx, opts) {
 }
 async function updateClientEndpoint(ctx, opts) {
 	const session = await getSessionFromCtx(ctx);
+	await assertClientPrivileges(ctx, session, opts, "update");
 	if (!session) throw new APIError("UNAUTHORIZED");
-	if (!ctx.headers) throw new APIError("BAD_REQUEST");
-	if (opts.clientPrivileges && !await opts.clientPrivileges({
-		headers: ctx.headers,
-		action: "update",
-		session: session.session,
-		user: session.user
-	})) throw new APIError("UNAUTHORIZED");
 	const clientId = ctx.body.client_id;
 	if (opts.cachedTrustedClients?.has(clientId)) throw new APIError("INTERNAL_SERVER_ERROR", {
 		error_description: "trusted clients must be updated manually",
@@ -1641,14 +1705,8 @@ async function updateClientEndpoint(ctx, opts) {
 }
 async function rotateClientSecretEndpoint(ctx, opts) {
 	const session = await getSessionFromCtx(ctx);
+	await assertClientPrivileges(ctx, session, opts, "rotate");
 	if (!session) throw new APIError("UNAUTHORIZED");
-	if (!ctx.headers) throw new APIError("BAD_REQUEST");
-	if (opts.clientPrivileges && !await opts.clientPrivileges({
-		headers: ctx.headers,
-		action: "rotate",
-		session: session.session,
-		user: session.user
-	})) throw new APIError("UNAUTHORIZED");
 	const clientId = ctx.body.client_id;
 	if (opts.cachedTrustedClients?.has(clientId)) throw new APIError("INTERNAL_SERVER_ERROR", {
 		error_description: "trusted clients must be updated manually",
@@ -1690,6 +1748,16 @@ async function rotateClientSecretEndpoint(ctx, opts) {
 		clientSecret: (opts.prefix?.clientSecret ?? "") + clientSecret
 	});
 }
+async function assertClientPrivileges(ctx, session, opts, action) {
+	if (!session) throw new APIError("UNAUTHORIZED");
+	if (!ctx.headers) throw new APIError("BAD_REQUEST");
+	if (opts.clientPrivileges && !await opts.clientPrivileges({
+		headers: ctx.headers,
+		action,
+		session: session.session,
+		user: session.user
+	})) throw new APIError("UNAUTHORIZED");
+}
 //#endregion
 //#region src/oauthClient/index.ts
 const adminCreateOAuthClient = (opts) => createAuthEndpoint("/admin/oauth2/create-client", {
@@ -1875,6 +1943,7 @@ const adminCreateOAuthClient = (opts) => createAuthEndpoint("/admin/oauth2/creat
 		}
 	}
 }, async (ctx) => {
+	await assertClientPrivileges(ctx, await getSessionFromCtx(ctx), opts, "create");
 	return createOAuthClientEndpoint(ctx, opts, { isRegister: false });
 });
 const createOAuthClient = (opts) => createAuthEndpoint("/oauth2/create-client", {
@@ -2047,6 +2116,7 @@ const createOAuthClient = (opts) => createAuthEndpoint("/oauth2/create-client",
 		} }
 	} }
 }, async (ctx) => {
+	await assertClientPrivileges(ctx, await getSessionFromCtx(ctx), opts, "create");
 	return createOAuthClientEndpoint(ctx, opts, { isRegister: false });
 });
 const getOAuthClient = (opts) => createAuthEndpoint("/oauth2/get-client", {
@@ -2459,6 +2529,7 @@ async function revokeAccessToken(ctx, opts, clientId, token) {
 }
 async function revokeEndpoint(ctx, opts) {
 	let { token, token_type_hint } = ctx.body;
+	if (token_type_hint !== "access_token" && token_type_hint !== "refresh_token") token_type_hint = void 0;
 	const { clientId: client_id, clientSecret: client_secret, preVerifiedClient } = destructureCredentials(await extractClientCredentials(ctx, opts, `${ctx.context.baseURL}/oauth2/revoke`));
 	if (!client_id) throw new APIError$1("UNAUTHORIZED", {
 		error_description: "missing required credentials",
@@ -2927,19 +2998,19 @@ const oauthProvider = (options) => {
 				if (opts.scopes && !opts.scopes.includes("openid")) throw new APIError("NOT_FOUND");
 				return oidcServerMetadata(ctx, opts);
 			}),
-			oauth2Authorize: createAuthEndpoint("/oauth2/authorize", {
+			oauth2Authorize: createOAuthEndpoint("/oauth2/authorize", {
 				method: "GET",
 				query: z.object({
-					response_type: z.enum(["code"]).optional(),
+					response_type: z.string().pipe(z.enum(["code"])).optional(),
 					client_id: z.string(),
 					redirect_uri: SafeUrlSchema.optional(),
 					scope: z.string().optional(),
 					state: z.string().optional(),
 					request_uri: z.string().optional(),
 					code_challenge: z.string().optional(),
-					code_challenge_method: z.enum(["S256"]).optional(),
+					code_challenge_method: z.string().pipe(z.enum(["S256"])).optional(),
 					nonce: z.string().optional(),
-					prompt: z.enum([
+					prompt: z.string().pipe(z.enum([
 						"none",
 						"consent",
 						"login",
@@ -2947,8 +3018,10 @@ const oauthProvider = (options) => {
 						"select_account",
 						"login consent",
 						"select_account consent"
-					]).optional()
+					])).optional()
 				}),
+				redirectOnError: authorizeRedirectOnError(opts),
+				errorCodesByField: { response_type: { invalid: "unsupported_response_type" } },
 				metadata: { openapi: {
 					description: "Authorize an OAuth2 request",
 					parameters: [
@@ -3107,14 +3180,14 @@ const oauthProvider = (options) => {
 			}, async (ctx) => {
 				return continueEndpoint(ctx, opts);
 			}),
-			oauth2Token: createAuthEndpoint("/oauth2/token", {
+			oauth2Token: createOAuthEndpoint("/oauth2/token", {
 				method: "POST",
 				body: z.object({
-					grant_type: z.enum([
+					grant_type: z.string().pipe(z.enum([
 						"authorization_code",
 						"client_credentials",
 						"refresh_token"
-					]),
+					])),
 					client_id: z.string().optional(),
 					client_secret: z.string().optional(),
 					client_assertion: z.string().optional(),
@@ -3126,6 +3199,10 @@ const oauthProvider = (options) => {
 					resource: z.string().optional(),
 					scope: z.string().optional()
 				}),
+				errorCodesByField: { grant_type: {
+					missing: "invalid_request",
+					invalid: "unsupported_grant_type"
+				} },
 				metadata: {
 					allowedMediaTypes: ["application/x-www-form-urlencoded"],
 					openapi: {
@@ -3238,7 +3315,7 @@ const oauthProvider = (options) => {
 			}, async (ctx) => {
 				return tokenEndpoint(ctx, opts);
 			}),
-			oauth2Introspect: createAuthEndpoint("/oauth2/introspect", {
+			oauth2Introspect: createOAuthEndpoint("/oauth2/introspect", {
 				method: "POST",
 				body: z.object({
 					client_id: z.string().optional(),
@@ -3246,7 +3323,7 @@ const oauthProvider = (options) => {
 					client_assertion: z.string().optional(),
 					client_assertion_type: z.string().optional(),
 					token: z.string(),
-					token_type_hint: z.enum(["access_token", "refresh_token"]).optional()
+					token_type_hint: z.string().optional()
 				}),
 				metadata: {
 					allowedMediaTypes: ["application/x-www-form-urlencoded"],
@@ -3271,8 +3348,7 @@ const oauthProvider = (options) => {
 									},
 									token_type_hint: {
 										type: "string",
-										enum: ["access_token", "refresh_token"],
-										description: "Hint about the type of the token submitted for introspection"
+										description: "Hint about the token type. Recognized values: `access_token`, `refresh_token`."
 									},
 									resource: {
 										type: "string",
@@ -3358,7 +3434,7 @@ const oauthProvider = (options) => {
 			}, async (ctx) => {
 				return introspectEndpoint(ctx, opts);
 			}),
-			oauth2Revoke: createAuthEndpoint("/oauth2/revoke", {
+			oauth2Revoke: createOAuthEndpoint("/oauth2/revoke", {
 				method: "POST",
 				body: z.object({
 					client_id: z.string().optional(),
@@ -3366,7 +3442,7 @@ const oauthProvider = (options) => {
 					client_assertion: z.string().optional(),
 					client_assertion_type: z.string().optional(),
 					token: z.string(),
-					token_type_hint: z.enum(["access_token", "refresh_token"]).optional()
+					token_type_hint: z.string().optional()
 				}),
 				metadata: {
 					allowedMediaTypes: ["application/x-www-form-urlencoded"],
@@ -3391,8 +3467,7 @@ const oauthProvider = (options) => {
 									},
 									token_type_hint: {
 										type: "string",
-										enum: ["access_token", "refresh_token"],
-										description: "Hint about the type of the token submitted for revocation"
+										description: "Hint about the token type. Recognized values: `access_token`, `refresh_token`."
 									}
 								},
 								required: ["token"]
@@ -3513,7 +3588,7 @@ const oauthProvider = (options) => {
 			}, async (ctx) => {
 				return userInfoEndpoint(ctx, opts);
 			}),
-			oauth2EndSession: createAuthEndpoint("/oauth2/end-session", {
+			oauth2EndSession: createOAuthEndpoint("/oauth2/end-session", {
 				method: "GET",
 				query: z.object({
 					id_token_hint: z.string(),
@@ -3544,7 +3619,7 @@ const oauthProvider = (options) => {
 			}, async (ctx) => {
 				return rpInitiatedLogoutEndpoint(ctx, opts);
 			}),
-			registerOAuthClient: createAuthEndpoint("/oauth2/register", {
+			registerOAuthClient: createOAuthEndpoint("/oauth2/register", {
 				method: "POST",
 				body: z.object({
 					redirect_uris: z.array(SafeUrlSchema).min(1).min(1),
@@ -3581,6 +3656,12 @@ const oauthProvider = (options) => {
 					subject_type: z.enum(["public", "pairwise"]).optional(),
 					skip_consent: z.never({ error: "skip_consent cannot be set during dynamic client registration" }).optional()
 				}),
+				errorCodesByField: {
+					redirect_uris: "invalid_redirect_uri",
+					post_logout_redirect_uris: "invalid_redirect_uri",
+					software_statement: "invalid_software_statement"
+				},
+				defaultError: "invalid_client_metadata",
 				metadata: { openapi: {
 					description: "Register an OAuth2 application",
 					responses: { "200": {
@@ -3773,17 +3854,37 @@ const oauthProvider = (options) => {
 //#endregion
 //#region src/authorize.ts
 /**
-* Formats an error url
+* Formats an error url. Per OIDC Core 1.0 §5 / RFC 6749 §4.2.2.1, errors on
+* implicit and hybrid flows are delivered in the URL fragment, not the query.
+* Callers on the code flow (default) omit `mode` and get query delivery.
 */
-function formatErrorURL(url, error, description, state, iss) {
+function formatErrorURL(url, error, description, state, iss, mode = "query") {
 	const searchParams = new URLSearchParams({
 		error,
 		error_description: description
 	});
 	state && searchParams.append("state", state);
 	iss && searchParams.append("iss", iss);
+	if (mode === "fragment") return `${url}#${searchParams.toString()}`;
 	return `${url}${url.includes("?") ? "&" : "?"}${searchParams.toString()}`;
 }
+/**
+* Selects the response mode for an error redirect to the RP. OIDC Core 1.0 §5
+* defines defaults based on response_type: `code` → query, types containing
+* `token` / `id_token` → fragment. An explicit `response_mode` overrides.
+*
+* When `response_type` is duplicated (array) or absent, we can't trust the
+* caller's intent, so we default to query — the safer channel for
+* unrecognized shapes.
+*/
+function deriveResponseMode(raw) {
+	const responseMode = typeof raw.response_mode === "string" ? raw.response_mode : void 0;
+	if (responseMode === "fragment") return "fragment";
+	if (responseMode === "query") return "query";
+	const responseType = typeof raw.response_type === "string" ? raw.response_type : void 0;
+	if (responseType && /\b(token|id_token)\b/.test(responseType)) return "fragment";
+	return "query";
+}
 const handleRedirect = (ctx, uri) => {
 	const fromFetch = isBrowserFetchRequest(ctx.request?.headers);
 	const acceptJson = ctx.headers?.get("accept")?.includes("application/json");
@@ -3807,8 +3908,7 @@ function redirectWithPromptNoneError(ctx, opts, query, error, description) {
 function validateIssuerUrl(issuer) {
 	try {
 		const url = new URL(issuer);
-		const isLocalhost = url.hostname === "localhost" || url.hostname === "127.0.0.1";
-		if (url.protocol !== "https:" && !isLocalhost) url.protocol = "https:";
+		if (url.protocol !== "https:" && !isLoopbackHost(url.host)) url.protocol = "https:";
 		url.search = "";
 		url.hash = "";
 		return url.toString().replace(/\/$/, "");
@@ -3836,6 +3936,64 @@ function getIssuer(ctx, opts) {
 function getErrorURL(ctx, error, description) {
 	return formatErrorURL(ctx.context.options.onAPIError?.errorURL || `${ctx.context.baseURL}/error`, error, description);
 }
+/**
+* Finds the matching entry in a client's registered redirect_uris for a
+* requested redirect_uri. Honors RFC 8252 §7.3 loopback port variance for
+* the full 127.0.0.0/8 range and [::1], matching on scheme+host+path+query
+* and ignoring port. DNS names like "localhost" are excluded per §8.3.
+*/
+function findRegisteredRedirectUri(registered, requested) {
+	if (!registered || !requested) return void 0;
+	let req;
+	try {
+		req = new URL(requested);
+	} catch {}
+	return registered.find((url) => {
+		if (url === requested) return true;
+		if (!req) return false;
+		try {
+			const reg = new URL(url);
+			return isLoopbackIP(reg.hostname) && reg.hostname === req.hostname && reg.pathname === req.pathname && reg.protocol === req.protocol && reg.search === req.search;
+		} catch {
+			return false;
+		}
+	});
+}
+/**
+* Loads the client, verifies it's enabled, and returns the requested
+* redirect_uri when it matches a registered entry. Returns null whenever the
+* RP cannot be safely reached, so callers can fall back to the server error
+* page (avoiding open-redirect risk on validation failures).
+*/
+async function resolveTrustedRedirectUri(ctx, opts, clientId, redirectUri) {
+	if (!clientId || !redirectUri) return null;
+	let client;
+	try {
+		client = await getClient(ctx, opts, clientId);
+	} catch {
+		return null;
+	}
+	if (!client || client.disabled) return null;
+	return findRegisteredRedirectUri(client.redirectUris, redirectUri) ? redirectUri : null;
+}
+/**
+* `redirectOnError` callback for `/oauth2/authorize`. Per RFC 6749 §4.1.2.1,
+* authorize errors MUST be delivered to the client's `redirect_uri` with
+* `error`, `error_description`, `state`, and (RFC 9207) `iss`. The clause
+* carves out one case: a missing/invalid `redirect_uri` or `client_id` MUST
+* NOT redirect to the requested URI. We implement the carve-out via
+* `resolveTrustedRedirectUri`, falling back to the server error page.
+*
+* Channel (query vs fragment) follows OIDC Core §5 via `deriveResponseMode`.
+*/
+function authorizeRedirectOnError(opts) {
+	return async ({ error, error_description, ctx }) => {
+		const raw = ctx.query ?? {};
+		const trusted = await resolveTrustedRedirectUri(ctx, opts, typeof raw.client_id === "string" ? raw.client_id : void 0, typeof raw.redirect_uri === "string" ? raw.redirect_uri : void 0);
+		if (trusted) return handleRedirect(ctx, formatErrorURL(trusted, error, error_description, typeof raw.state === "string" ? raw.state : void 0, getIssuer(ctx, opts), deriveResponseMode(raw)));
+		return handleRedirect(ctx, getErrorURL(ctx, error, error_description));
+	};
+}
 async function authorizeEndpoint(ctx, opts, settings) {
 	if (opts.grantTypes && !opts.grantTypes.includes("authorization_code")) throw new APIError$1("NOT_FOUND");
 	if (!ctx.request) throw new APIError$1("UNAUTHORIZED", {
@@ -3866,15 +4024,7 @@ async function authorizeEndpoint(ctx, opts, settings) {
 	const client = await getClient(ctx, opts, query.client_id);
 	if (!client) return handleRedirect(ctx, getErrorURL(ctx, "invalid_client", "client_id is required"));
 	if (client.disabled) return handleRedirect(ctx, getErrorURL(ctx, "client_disabled", "client is disabled"));
-	if (!client.redirectUris?.find((url) => {
-		if (url === query.redirect_uri) return true;
-		try {
-			const registered = new URL(url);
-			const requested = new URL(query.redirect_uri);
-			if ((registered.hostname === "127.0.0.1" || registered.hostname === "[::1]") && registered.hostname === requested.hostname && registered.pathname === requested.pathname && registered.protocol === requested.protocol && registered.search === requested.search) return true;
-		} catch {}
-		return false;
-	}) || !query.redirect_uri) return handleRedirect(ctx, getErrorURL(ctx, "invalid_redirect", "invalid redirect uri"));
+	if (!findRegisteredRedirectUri(client.redirectUris, query.redirect_uri) || !query.redirect_uri) return handleRedirect(ctx, getErrorURL(ctx, "invalid_redirect", "invalid redirect uri"));
 	let requestedScopes = query.scope?.split(" ").filter((s) => s);
 	if (requestedScopes) {
 		const validScopes = new Set(client.scopes ?? opts.scopes);

package/dist/{oauth-B_qonG53.d.mts → oauth-DJcZ8MMZ.d.mts}

@@ -5,6 +5,36 @@ import * as better_auth_plugins0 from "better-auth/plugins";
 import * as jose from "jose";
 import * as better_auth0 from "better-auth";
 
+//#region src/oauth-endpoint.d.ts
+/**
+ * Canonical OAuth 2.0 / OpenID Connect error codes. The union is the single
+ * vocabulary for every error-emitting surface in this plugin: token, authorize,
+ * revoke, introspect, register, userinfo, logout, consent, and the redirect
+ * error channel. Entries are grouped by source RFC so the declaration doubles
+ * as a specification map.
+ *
+ * The trailing `(string & {})` keeps the type open for product-specific codes
+ * (e.g. `"invalid_verification"`, `"invalid_user"`) while preserving editor
+ * autocomplete for the listed standard codes. Prefer a standard code whenever
+ * one applies; fall back to a custom string only for states no RFC covers.
+ */
+type OAuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "unsupported_response_type" | "invalid_scope" | "access_denied" | "server_error" | "temporarily_unavailable" | "invalid_token" | "unsupported_token_type" | "invalid_redirect_uri" | "invalid_client_metadata" | "invalid_software_statement" | "unapproved_software_statement" | "invalid_target" | "invalid_request_object" | "login_required" | "consent_required" | "interaction_required" | "account_selection_required" | "invalid_request_uri" | "request_not_supported" | "request_uri_not_supported" | "registration_not_supported" | (string & {});
+type OAuthFieldErrorCodeMap = {
+  missing?: OAuthErrorCode;
+  invalid?: OAuthErrorCode;
+};
+type OAuthFieldErrorCode = OAuthErrorCode | OAuthFieldErrorCodeMap;
+interface OAuthEndpointErrorResult {
+  error: OAuthErrorCode;
+  error_description: string;
+}
+interface OAuthEndpointRedirectContext<Ctx = unknown> {
+  error: OAuthErrorCode;
+  error_description: string;
+  ctx: Ctx;
+}
+type OAuthRedirectOnError<Ctx = any> = (result: OAuthEndpointRedirectContext<Ctx>) => unknown;
+//#endregion
 //#region src/oauth.d.ts
 declare module "@better-auth/core" {
   interface BetterAuthPluginRegistry<AuthOptions, Options> {
@@ -160,20 +190,20 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
     oauth2Authorize: better_call0.StrictEndpoint<"/oauth2/authorize", {
       method: "GET";
       query: z.ZodObject<{
-        response_type: z.ZodOptional<z.ZodEnum<{
+        response_type: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEnum<{
           code: "code";
-        }>>;
+        }>>>;
         client_id: z.ZodString;
         redirect_uri: z.ZodOptional<z.ZodURL>;
         scope: z.ZodOptional<z.ZodString>;
         state: z.ZodOptional<z.ZodString>;
         request_uri: z.ZodOptional<z.ZodString>;
         code_challenge: z.ZodOptional<z.ZodString>;
-        code_challenge_method: z.ZodOptional<z.ZodEnum<{
+        code_challenge_method: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEnum<{
           S256: "S256";
-        }>>;
+        }>>>;
         nonce: z.ZodOptional<z.ZodString>;
-        prompt: z.ZodOptional<z.ZodEnum<{
+        prompt: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEnum<{
           none: "none";
           consent: "consent";
           login: "login";
@@ -181,8 +211,14 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
           select_account: "select_account";
           "login consent": "login consent";
           "select_account consent": "select_account consent";
-        }>>;
+        }>>>;
       }, z.core.$strip>;
+      redirectOnError: OAuthRedirectOnError<better_auth0.GenericEndpointContext>;
+      errorCodesByField: {
+        response_type: {
+          invalid: "unsupported_response_type";
+        };
+      };
       metadata: {
         openapi: {
           description: string;
@@ -378,11 +414,11 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
     oauth2Token: better_call0.StrictEndpoint<"/oauth2/token", {
       method: "POST";
       body: z.ZodObject<{
-        grant_type: z.ZodEnum<{
+        grant_type: z.ZodPipe<z.ZodString, z.ZodEnum<{
           authorization_code: "authorization_code";
           client_credentials: "client_credentials";
           refresh_token: "refresh_token";
-        }>;
+        }>>;
         client_id: z.ZodOptional<z.ZodString>;
         client_secret: z.ZodOptional<z.ZodString>;
         client_assertion: z.ZodOptional<z.ZodString>;
@@ -394,6 +430,12 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
         resource: z.ZodOptional<z.ZodString>;
         scope: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>;
+      errorCodesByField: {
+        grant_type: {
+          missing: "invalid_request";
+          invalid: "unsupported_grant_type";
+        };
+      };
       metadata: {
         allowedMediaTypes: string[];
         openapi: {
@@ -530,10 +572,7 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
         client_assertion: z.ZodOptional<z.ZodString>;
         client_assertion_type: z.ZodOptional<z.ZodString>;
         token: z.ZodString;
-        token_type_hint: z.ZodOptional<z.ZodEnum<{
-          refresh_token: "refresh_token";
-          access_token: "access_token";
-        }>>;
+        token_type_hint: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>;
       metadata: {
         allowedMediaTypes: string[];
@@ -560,7 +599,6 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
                     };
                     token_type_hint: {
                       type: string;
-                      enum: string[];
                       description: string;
                     };
                     resource: {
@@ -669,10 +707,7 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
         client_assertion: z.ZodOptional<z.ZodString>;
         client_assertion_type: z.ZodOptional<z.ZodString>;
         token: z.ZodString;
-        token_type_hint: z.ZodOptional<z.ZodEnum<{
-          refresh_token: "refresh_token";
-          access_token: "access_token";
-        }>>;
+        token_type_hint: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>;
       metadata: {
         allowedMediaTypes: string[];
@@ -699,7 +734,6 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
                     };
                     token_type_hint: {
                       type: string;
-                      enum: string[];
                       description: string;
                     };
                   };
@@ -951,6 +985,12 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
         }>>;
         skip_consent: z.ZodOptional<z.ZodNever>;
       }, z.core.$strip>;
+      errorCodesByField: {
+        redirect_uris: "invalid_redirect_uri";
+        post_logout_redirect_uris: "invalid_redirect_uri";
+        software_statement: "invalid_software_statement";
+      };
+      defaultError: "invalid_client_metadata";
       metadata: {
         openapi: {
           description: string;
@@ -2196,4 +2236,4 @@ declare const oauthProvider: <O extends OAuthOptions<Scope[]>>(options: O) => {
   })[];
 };
 //#endregion
-export { oauthProvider as n, getOAuthProviderState as t };
+export { OAuthErrorCode as a, OAuthRedirectOnError as c, OAuthEndpointRedirectContext as i, oauthProvider as n, OAuthFieldErrorCode as o, OAuthEndpointErrorResult as r, OAuthFieldErrorCodeMap as s, getOAuthProviderState as t };

package/dist/{version-DIwdpXrQ.mjs → version-CZxZ64qJ.mjs}

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/version.ts
-const PACKAGE_VERSION = "1.7.0-beta.1";
+const PACKAGE_VERSION = "1.7.0-beta.2";
 //#endregion
 export { PACKAGE_VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/oauth-provider",
-  "version": "1.7.0-beta.1",
+  "version": "1.7.0-beta.2",
   "description": "An oauth provider plugin for Better Auth",
   "type": "module",
   "license": "MIT",
@@ -64,15 +64,15 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "listhen": "^1.9.0",
     "tsdown": "0.21.1",
-    "@better-auth/core": "1.7.0-beta.1",
-    "better-auth": "1.7.0-beta.1"
+    "@better-auth/core": "1.7.0-beta.2",
+    "better-auth": "1.7.0-beta.2"
   },
   "peerDependencies": {
     "@better-auth/utils": "0.4.0",
     "@better-fetch/fetch": "1.1.21",
     "better-call": "1.3.5",
-    "@better-auth/core": "^1.7.0-beta.1",
-    "better-auth": "^1.7.0-beta.1"
+    "@better-auth/core": "^1.7.0-beta.2",
+    "better-auth": "^1.7.0-beta.2"
   },
   "scripts": {
     "build": "tsdown",