@hammadj/better-auth-core 1.5.0-beta.9

package/src/error/codes.ts

@@ -0,0 +1,58 @@
+import { defineErrorCodes } from "../utils/error-codes";
+
+export const BASE_ERROR_CODES = defineErrorCodes({
+	USER_NOT_FOUND: "User not found",
+	FAILED_TO_CREATE_USER: "Failed to create user",
+	FAILED_TO_CREATE_SESSION: "Failed to create session",
+	FAILED_TO_UPDATE_USER: "Failed to update user",
+	FAILED_TO_GET_SESSION: "Failed to get session",
+	INVALID_PASSWORD: "Invalid password",
+	INVALID_EMAIL: "Invalid email",
+	INVALID_EMAIL_OR_PASSWORD: "Invalid email or password",
+	INVALID_USER: "Invalid user",
+	SOCIAL_ACCOUNT_ALREADY_LINKED: "Social account already linked",
+	PROVIDER_NOT_FOUND: "Provider not found",
+	INVALID_TOKEN: "Invalid token",
+	TOKEN_EXPIRED: "Token expired",
+	ID_TOKEN_NOT_SUPPORTED: "id_token not supported",
+	FAILED_TO_GET_USER_INFO: "Failed to get user info",
+	USER_EMAIL_NOT_FOUND: "User email not found",
+	EMAIL_NOT_VERIFIED: "Email not verified",
+	PASSWORD_TOO_SHORT: "Password too short",
+	PASSWORD_TOO_LONG: "Password too long",
+	USER_ALREADY_EXISTS: "User already exists.",
+	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL:
+		"User already exists. Use another email.",
+	EMAIL_CAN_NOT_BE_UPDATED: "Email can not be updated",
+	CREDENTIAL_ACCOUNT_NOT_FOUND: "Credential account not found",
+	SESSION_EXPIRED: "Session expired. Re-authenticate to perform this action.",
+	FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account",
+	ACCOUNT_NOT_FOUND: "Account not found",
+	USER_ALREADY_HAS_PASSWORD:
+		"User already has a password. Provide that to delete the account.",
+	CROSS_SITE_NAVIGATION_LOGIN_BLOCKED:
+		"Cross-site navigation login blocked. This request appears to be a CSRF attack.",
+	VERIFICATION_EMAIL_NOT_ENABLED: "Verification email isn't enabled",
+	EMAIL_ALREADY_VERIFIED: "Email is already verified",
+	EMAIL_MISMATCH: "Email mismatch",
+	SESSION_NOT_FRESH: "Session is not fresh",
+	LINKED_ACCOUNT_ALREADY_EXISTS: "Linked account already exists",
+	INVALID_ORIGIN: "Invalid origin",
+	INVALID_CALLBACK_URL: "Invalid callbackURL",
+	INVALID_REDIRECT_URL: "Invalid redirectURL",
+	INVALID_ERROR_CALLBACK_URL: "Invalid errorCallbackURL",
+	INVALID_NEW_USER_CALLBACK_URL: "Invalid newUserCallbackURL",
+	MISSING_OR_NULL_ORIGIN: "Missing or null Origin",
+	CALLBACK_URL_REQUIRED: "callbackURL is required",
+	FAILED_TO_CREATE_VERIFICATION: "Unable to create verification",
+	FIELD_NOT_ALLOWED: "Field not allowed to be set",
+	ASYNC_VALIDATION_NOT_SUPPORTED: "Async validation is not supported",
+	VALIDATION_ERROR: "Validation Error",
+	MISSING_FIELD: "Field is required",
+	METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED:
+		"POST method requires deferSessionRefresh to be enabled in session config",
+	BODY_MUST_BE_AN_OBJECT: "Body must be an object",
+	PASSWORD_ALREADY_SET: "User already has a password set",
+});
+
+export type APIErrorCode = keyof typeof BASE_ERROR_CODES;

package/src/error/index.ts

@@ -0,0 +1,35 @@
+import { APIError as BaseAPIError } from "better-call/error";
+
+export class BetterAuthError extends Error {
+	constructor(message: string, options?: { cause?: unknown | undefined }) {
+		super(message, options);
+		this.name = "BetterAuthError";
+		this.message = message;
+		this.stack = "";
+	}
+}
+
+export { type APIErrorCode, BASE_ERROR_CODES } from "./codes";
+
+export class APIError extends BaseAPIError {
+	constructor(...args: ConstructorParameters<typeof BaseAPIError>) {
+		super(...args);
+	}
+
+	static fromStatus(
+		status: ConstructorParameters<typeof BaseAPIError>[0],
+		body?: ConstructorParameters<typeof BaseAPIError>[1],
+	) {
+		return new APIError(status, body);
+	}
+
+	static from(
+		status: ConstructorParameters<typeof BaseAPIError>[0],
+		error: { code: string; message: string },
+	) {
+		return new APIError(status, {
+			message: error.message,
+			code: error.code,
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./types";

package/src/oauth2/client-credentials-token.ts

@@ -0,0 +1,102 @@
+import { base64Url } from "@better-auth/utils/base64";
+import { betterFetch } from "@better-fetch/fetch";
+import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+
+export function createClientCredentialsTokenRequest({
+	options,
+	scope,
+	authentication,
+	resource,
+}: {
+	options: ProviderOptions & { clientSecret: string };
+	scope?: string | undefined;
+	authentication?: ("basic" | "post") | undefined;
+	resource?: (string | string[]) | undefined;
+}) {
+	const body = new URLSearchParams();
+	const headers: Record<string, any> = {
+		"content-type": "application/x-www-form-urlencoded",
+		accept: "application/json",
+	};
+
+	body.set("grant_type", "client_credentials");
+	scope && body.set("scope", scope);
+	if (resource) {
+		if (typeof resource === "string") {
+			body.append("resource", resource);
+		} else {
+			for (const _resource of resource) {
+				body.append("resource", _resource);
+			}
+		}
+	}
+	if (authentication === "basic") {
+		const primaryClientId = Array.isArray(options.clientId)
+			? options.clientId[0]
+			: options.clientId;
+		const encodedCredentials = base64Url.encode(
+			`${primaryClientId}:${options.clientSecret}`,
+		);
+		headers["authorization"] = `Basic ${encodedCredentials}`;
+	} else {
+		const primaryClientId = Array.isArray(options.clientId)
+			? options.clientId[0]
+			: options.clientId;
+		body.set("client_id", primaryClientId);
+		body.set("client_secret", options.clientSecret);
+	}
+
+	return {
+		body,
+		headers,
+	};
+}
+
+export async function clientCredentialsToken({
+	options,
+	tokenEndpoint,
+	scope,
+	authentication,
+	resource,
+}: {
+	options: ProviderOptions & { clientSecret: string };
+	tokenEndpoint: string;
+	scope: string;
+	authentication?: ("basic" | "post") | undefined;
+	resource?: (string | string[]) | undefined;
+}): Promise<OAuth2Tokens> {
+	const { body, headers } = createClientCredentialsTokenRequest({
+		options,
+		scope,
+		authentication,
+		resource,
+	});
+
+	const { data, error } = await betterFetch<{
+		access_token: string;
+		expires_in?: number | undefined;
+		token_type?: string | undefined;
+		scope?: string | undefined;
+	}>(tokenEndpoint, {
+		method: "POST",
+		body,
+		headers,
+	});
+	if (error) {
+		throw error;
+	}
+	const tokens: OAuth2Tokens = {
+		accessToken: data.access_token,
+		tokenType: data.token_type,
+		scopes: data.scope?.split(" "),
+	};
+
+	if (data.expires_in) {
+		const now = new Date();
+		tokens.accessTokenExpiresAt = new Date(
+			now.getTime() + data.expires_in * 1000,
+		);
+	}
+
+	return tokens;
+}

package/src/oauth2/create-authorization-url.ts

@@ -0,0 +1,87 @@
+import type { ProviderOptions } from "./index";
+import { generateCodeChallenge } from "./utils";
+
+export async function createAuthorizationURL({
+	id,
+	options,
+	authorizationEndpoint,
+	state,
+	codeVerifier,
+	scopes,
+	claims,
+	redirectURI,
+	duration,
+	prompt,
+	accessType,
+	responseType,
+	display,
+	loginHint,
+	hd,
+	responseMode,
+	additionalParams,
+	scopeJoiner,
+}: {
+	id: string;
+	options: ProviderOptions;
+	redirectURI: string;
+	authorizationEndpoint: string;
+	state: string;
+	codeVerifier?: string | undefined;
+	scopes?: string[] | undefined;
+	claims?: string[] | undefined;
+	duration?: string | undefined;
+	prompt?: string | undefined;
+	accessType?: string | undefined;
+	responseType?: string | undefined;
+	display?: string | undefined;
+	loginHint?: string | undefined;
+	hd?: string | undefined;
+	responseMode?: string | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	scopeJoiner?: string | undefined;
+}) {
+	const url = new URL(options.authorizationEndpoint || authorizationEndpoint);
+	url.searchParams.set("response_type", responseType || "code");
+	const primaryClientId = Array.isArray(options.clientId)
+		? options.clientId[0]
+		: options.clientId;
+	url.searchParams.set("client_id", primaryClientId);
+	url.searchParams.set("state", state);
+	if (scopes) {
+		url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
+	}
+	url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
+	duration && url.searchParams.set("duration", duration);
+	display && url.searchParams.set("display", display);
+	loginHint && url.searchParams.set("login_hint", loginHint);
+	prompt && url.searchParams.set("prompt", prompt);
+	hd && url.searchParams.set("hd", hd);
+	accessType && url.searchParams.set("access_type", accessType);
+	responseMode && url.searchParams.set("response_mode", responseMode);
+	if (codeVerifier) {
+		const codeChallenge = await generateCodeChallenge(codeVerifier);
+		url.searchParams.set("code_challenge_method", "S256");
+		url.searchParams.set("code_challenge", codeChallenge);
+	}
+	if (claims) {
+		const claimsObj = claims.reduce(
+			(acc, claim) => {
+				acc[claim] = null;
+				return acc;
+			},
+			{} as Record<string, null>,
+		);
+		url.searchParams.set(
+			"claims",
+			JSON.stringify({
+				id_token: { email: null, email_verified: null, ...claimsObj },
+			}),
+		);
+	}
+	if (additionalParams) {
+		Object.entries(additionalParams).forEach(([key, value]) => {
+			url.searchParams.set(key, value);
+		});
+	}
+	return url;
+}

package/src/oauth2/index.ts

@@ -0,0 +1,26 @@
+export {
+	clientCredentialsToken,
+	createClientCredentialsTokenRequest,
+} from "./client-credentials-token";
+export { createAuthorizationURL } from "./create-authorization-url";
+export type {
+	OAuth2Tokens,
+	OAuth2UserInfo,
+	OAuthProvider,
+	ProviderOptions,
+} from "./oauth-provider";
+export {
+	createRefreshAccessTokenRequest,
+	refreshAccessToken,
+} from "./refresh-access-token";
+export { generateCodeChallenge, getOAuth2Tokens } from "./utils";
+export {
+	createAuthorizationCodeRequest,
+	validateAuthorizationCode,
+	validateToken,
+} from "./validate-authorization-code";
+export {
+	getJwks,
+	verifyAccessToken,
+	verifyJwsAccessToken,
+} from "./verify";

package/src/oauth2/oauth-provider.ts

@@ -0,0 +1,222 @@
+import type { Awaitable, LiteralString } from "../types";
+
+export interface OAuth2Tokens {
+	tokenType?: string | undefined;
+	accessToken?: string | undefined;
+	refreshToken?: string | undefined;
+	accessTokenExpiresAt?: Date | undefined;
+	refreshTokenExpiresAt?: Date | undefined;
+	scopes?: string[] | undefined;
+	idToken?: string | undefined;
+	/**
+	 * Raw token response from the provider.
+	 * Preserves provider-specific fields that are not part of the standard OAuth2 token response.
+	 */
+	raw?: Record<string, unknown> | undefined;
+}
+
+export type OAuth2UserInfo = {
+	id: string | number;
+	name?: string | undefined;
+	email?: (string | null) | undefined;
+	image?: string | undefined;
+	emailVerified: boolean;
+};
+
+export interface OAuthProvider<
+	T extends Record<string, any> = Record<string, any>,
+	O extends Record<string, any> = Partial<ProviderOptions>,
+> {
+	id: LiteralString;
+	createAuthorizationURL: (data: {
+		state: string;
+		codeVerifier: string;
+		scopes?: string[] | undefined;
+		redirectURI: string;
+		display?: string | undefined;
+		loginHint?: string | undefined;
+	}) => Awaitable<URL>;
+	name: string;
+	validateAuthorizationCode: (data: {
+		code: string;
+		redirectURI: string;
+		codeVerifier?: string | undefined;
+		deviceId?: string | undefined;
+	}) => Promise<OAuth2Tokens | null>;
+	getUserInfo: (
+		token: OAuth2Tokens & {
+			/**
+			 * The user object from the provider
+			 * This is only available for some providers like Apple
+			 */
+			user?:
+				| {
+						name?: {
+							firstName?: string;
+							lastName?: string;
+						};
+						email?: string;
+				  }
+				| undefined;
+		},
+	) => Promise<{
+		user: OAuth2UserInfo;
+		data: T;
+	} | null>;
+	/**
+	 * 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
+	 */
+	verifyIdToken?:
+		| ((token: string, nonce?: string) => Promise<boolean>)
+		| undefined;
+	/**
+	 * Disable implicit sign up for new users. When set to true for the provider,
+	 * sign-in need to be called with with requestSignUp as true to create new users.
+	 */
+	disableImplicitSignUp?: boolean | undefined;
+	/**
+	 * Disable sign up for new users.
+	 */
+	disableSignUp?: boolean | undefined;
+	/**
+	 * Options for the provider
+	 */
+	options?: O | undefined;
+}
+
+export type ProviderOptions<Profile extends Record<string, any> = any> = {
+	/**
+	 * The client ID of your application.
+	 *
+	 * This is usually a string but can be any type depending on the provider.
+	 */
+	clientId?: unknown | undefined;
+	/**
+	 * The client secret of your application
+	 */
+	clientSecret?: string | undefined;
+	/**
+	 * The scopes you want to request from the provider
+	 */
+	scope?: string[] | undefined;
+	/**
+	 * Remove default scopes of the provider
+	 */
+	disableDefaultScope?: boolean | undefined;
+	/**
+	 * The redirect URL for your application. This is where the provider will
+	 * redirect the user after the sign in process. Make sure this URL is
+	 * whitelisted in the provider's dashboard.
+	 */
+	redirectURI?: string | undefined;
+	/**
+	 * Custom authorization endpoint URL.
+	 * Use this to override the default authorization endpoint of the provider.
+	 * Useful for testing with local OAuth servers or using sandbox environments.
+	 */
+	authorizationEndpoint?: string | undefined;
+	/**
+	 * The client key of your application
+	 * Tiktok Social Provider uses this field instead of clientId
+	 */
+	clientKey?: string | undefined;
+	/**
+	 * Disable provider from allowing users to sign in
+	 * with this provider with an id token sent from the
+	 * client.
+	 */
+	disableIdTokenSignIn?: boolean | undefined;
+	/**
+	 * verifyIdToken function to verify the id token
+	 */
+	verifyIdToken?:
+		| ((token: string, nonce?: string) => Promise<boolean>)
+		| undefined;
+	/**
+	 * Custom function to get user info from the provider
+	 */
+	getUserInfo?:
+		| ((token: OAuth2Tokens) => Promise<{
+				user: {
+					id: string;
+					name?: string;
+					email?: string | null;
+					image?: string;
+					emailVerified: boolean;
+					[key: string]: any;
+				};
+				data: any;
+		  } | null>)
+		| undefined;
+	/**
+	 * Custom function to refresh a token
+	 */
+	refreshAccessToken?:
+		| ((refreshToken: string) => Promise<OAuth2Tokens>)
+		| undefined;
+	/**
+	 * Custom function to map the provider profile to a
+	 * user.
+	 */
+	mapProfileToUser?:
+		| ((profile: Profile) =>
+				| {
+						id?: string;
+						name?: string;
+						email?: string | null;
+						image?: string;
+						emailVerified?: boolean;
+						[key: string]: any;
+				  }
+				| Promise<{
+						id?: string;
+						name?: string;
+						email?: string | null;
+						image?: string;
+						emailVerified?: boolean;
+						[key: string]: any;
+				  }>)
+		| undefined;
+	/**
+	 * Disable implicit sign up for new users. When set to true for the provider,
+	 * sign-in need to be called with with requestSignUp as true to create new users.
+	 */
+	disableImplicitSignUp?: boolean | undefined;
+	/**
+	 * Disable sign up for new users.
+	 */
+	disableSignUp?: boolean | undefined;
+	/**
+	 * The prompt to use for the authorization code request
+	 */
+	prompt?:
+		| (
+				| "select_account"
+				| "consent"
+				| "login"
+				| "none"
+				| "select_account consent"
+		  )
+		| undefined;
+	/**
+	 * The response mode to use for the authorization code request
+	 */
+	responseMode?: ("query" | "form_post") | undefined;
+	/**
+	 * If enabled, the user info will be overridden with the provider user info
+	 * This is useful if you want to use the provider user info to update the user info
+	 *
+	 * @default false
+	 */
+	overrideUserInfoOnSignIn?: boolean | undefined;
+};

package/src/oauth2/refresh-access-token.ts

@@ -0,0 +1,124 @@
+import { base64 } from "@better-auth/utils/base64";
+import { betterFetch } from "@better-fetch/fetch";
+import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+
+export function createRefreshAccessTokenRequest({
+	refreshToken,
+	options,
+	authentication,
+	extraParams,
+	resource,
+}: {
+	refreshToken: string;
+	options: Partial<ProviderOptions>;
+	authentication?: ("basic" | "post") | undefined;
+	extraParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}) {
+	const body = new URLSearchParams();
+	const headers: Record<string, any> = {
+		"content-type": "application/x-www-form-urlencoded",
+		accept: "application/json",
+	};
+
+	body.set("grant_type", "refresh_token");
+	body.set("refresh_token", refreshToken);
+	// Use standard Base64 encoding for HTTP Basic Auth (OAuth2 spec, RFC 7617)
+	// Fixes compatibility with providers like Notion, Twitter, etc.
+	if (authentication === "basic") {
+		const primaryClientId = Array.isArray(options.clientId)
+			? options.clientId[0]
+			: options.clientId;
+		if (primaryClientId) {
+			headers["authorization"] =
+				"Basic " +
+				base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`);
+		} else {
+			headers["authorization"] =
+				"Basic " + base64.encode(`:${options.clientSecret ?? ""}`);
+		}
+	} else {
+		const primaryClientId = Array.isArray(options.clientId)
+			? options.clientId[0]
+			: options.clientId;
+		body.set("client_id", primaryClientId);
+		if (options.clientSecret) {
+			body.set("client_secret", options.clientSecret);
+		}
+	}
+
+	if (resource) {
+		if (typeof resource === "string") {
+			body.append("resource", resource);
+		} else {
+			for (const _resource of resource) {
+				body.append("resource", _resource);
+			}
+		}
+	}
+	if (extraParams) {
+		for (const [key, value] of Object.entries(extraParams)) {
+			body.set(key, value);
+		}
+	}
+
+	return {
+		body,
+		headers,
+	};
+}
+
+export async function refreshAccessToken({
+	refreshToken,
+	options,
+	tokenEndpoint,
+	authentication,
+	extraParams,
+}: {
+	refreshToken: string;
+	options: Partial<ProviderOptions>;
+	tokenEndpoint: string;
+	authentication?: ("basic" | "post") | undefined;
+	extraParams?: Record<string, string> | undefined;
+	/** @deprecated always "refresh_token" */
+	grantType?: string | undefined;
+}): Promise<OAuth2Tokens> {
+	const { body, headers } = createRefreshAccessTokenRequest({
+		refreshToken,
+		options,
+		authentication,
+		extraParams,
+	});
+
+	const { data, error } = await betterFetch<{
+		access_token: string;
+		refresh_token?: string | undefined;
+		expires_in?: number | undefined;
+		token_type?: string | undefined;
+		scope?: string | undefined;
+		id_token?: string | undefined;
+	}>(tokenEndpoint, {
+		method: "POST",
+		body,
+		headers,
+	});
+	if (error) {
+		throw error;
+	}
+	const tokens: OAuth2Tokens = {
+		accessToken: data.access_token,
+		refreshToken: data.refresh_token,
+		tokenType: data.token_type,
+		scopes: data.scope?.split(" "),
+		idToken: data.id_token,
+	};
+
+	if (data.expires_in) {
+		const now = new Date();
+		tokens.accessTokenExpiresAt = new Date(
+			now.getTime() + data.expires_in * 1000,
+		);
+	}
+
+	return tokens;
+}

package/src/oauth2/utils.ts

@@ -0,0 +1,38 @@
+import { base64Url } from "@better-auth/utils/base64";
+import type { OAuth2Tokens } from "./oauth-provider";
+
+export function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens {
+	const getDate = (seconds: number) => {
+		const now = new Date();
+		return new Date(now.getTime() + seconds * 1000);
+	};
+
+	return {
+		tokenType: data.token_type,
+		accessToken: data.access_token,
+		refreshToken: data.refresh_token,
+		accessTokenExpiresAt: data.expires_in
+			? getDate(data.expires_in)
+			: undefined,
+		refreshTokenExpiresAt: data.refresh_token_expires_in
+			? getDate(data.refresh_token_expires_in)
+			: undefined,
+		scopes: data?.scope
+			? typeof data.scope === "string"
+				? data.scope.split(" ")
+				: data.scope
+			: [],
+		idToken: data.id_token,
+		// Preserve the raw token response for provider-specific fields
+		raw: data,
+	};
+}
+
+export async function generateCodeChallenge(codeVerifier: string) {
+	const encoder = new TextEncoder();
+	const data = encoder.encode(codeVerifier);
+	const hash = await crypto.subtle.digest("SHA-256", data);
+	return base64Url.encode(new Uint8Array(hash), {
+		padding: false,
+	});
+}