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

package/src/oauth2/validate-authorization-code.ts

@@ -0,0 +1,149 @@
+import { base64 } from "@better-auth/utils/base64";
+import { betterFetch } from "@better-fetch/fetch";
+import type { JWK } from "jose";
+import { decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import type { ProviderOptions } from "./index";
+import { getOAuth2Tokens } from "./index";
+
+export function createAuthorizationCodeRequest({
+	code,
+	codeVerifier,
+	redirectURI,
+	options,
+	authentication,
+	deviceId,
+	headers,
+	additionalParams = {},
+	resource,
+}: {
+	code: string;
+	redirectURI: string;
+	options: Partial<ProviderOptions>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	authentication?: ("basic" | "post") | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}) {
+	const body = new URLSearchParams();
+	const requestHeaders: Record<string, any> = {
+		"content-type": "application/x-www-form-urlencoded",
+		accept: "application/json",
+		...headers,
+	};
+	body.set("grant_type", "authorization_code");
+	body.set("code", code);
+	codeVerifier && body.set("code_verifier", codeVerifier);
+	options.clientKey && body.set("client_key", options.clientKey);
+	deviceId && body.set("device_id", deviceId);
+	body.set("redirect_uri", options.redirectURI || redirectURI);
+	if (resource) {
+		if (typeof resource === "string") {
+			body.append("resource", resource);
+		} else {
+			for (const _resource of resource) {
+				body.append("resource", _resource);
+			}
+		}
+	}
+	// 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;
+		const encodedCredentials = base64.encode(
+			`${primaryClientId}:${options.clientSecret ?? ""}`,
+		);
+		requestHeaders["authorization"] = `Basic ${encodedCredentials}`;
+	} 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);
+		}
+	}
+
+	for (const [key, value] of Object.entries(additionalParams)) {
+		if (!body.has(key)) body.append(key, value);
+	}
+
+	return {
+		body,
+		headers: requestHeaders,
+	};
+}
+
+export async function validateAuthorizationCode({
+	code,
+	codeVerifier,
+	redirectURI,
+	options,
+	tokenEndpoint,
+	authentication,
+	deviceId,
+	headers,
+	additionalParams = {},
+	resource,
+}: {
+	code: string;
+	redirectURI: string;
+	options: Partial<ProviderOptions>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	tokenEndpoint: string;
+	authentication?: ("basic" | "post") | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}) {
+	const { body, headers: requestHeaders } = createAuthorizationCodeRequest({
+		code,
+		codeVerifier,
+		redirectURI,
+		options,
+		authentication,
+		deviceId,
+		headers,
+		additionalParams,
+		resource,
+	});
+
+	const { data, error } = await betterFetch<object>(tokenEndpoint, {
+		method: "POST",
+		body: body,
+		headers: requestHeaders,
+	});
+
+	if (error) {
+		throw error;
+	}
+	const tokens = getOAuth2Tokens(data);
+	return tokens;
+}
+
+export async function validateToken(token: string, jwksEndpoint: string) {
+	const { data, error } = await betterFetch<{
+		keys: JWK[];
+	}>(jwksEndpoint, {
+		method: "GET",
+		headers: {
+			accept: "application/json",
+		},
+	});
+	if (error) {
+		throw error;
+	}
+	const keys = data["keys"];
+	const header = decodeProtectedHeader(token);
+	const key = keys.find((k) => k.kid === header.kid);
+	if (!key) {
+		throw new Error("Key not found");
+	}
+	const cryptoKey = await importJWK(key, header.alg);
+	const verified = await jwtVerify(token, cryptoKey);
+	return verified;
+}

package/src/oauth2/validate-token.test.ts

@@ -0,0 +1,174 @@
+import { exportJWK, generateKeyPair, SignJWT } from "jose";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { validateToken } from "./validate-authorization-code";
+
+vi.mock("@better-fetch/fetch", () => ({
+	betterFetch: vi.fn(),
+}));
+
+import { betterFetch } from "@better-fetch/fetch";
+
+const mockedBetterFetch = vi.mocked(betterFetch);
+
+describe("validateToken", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	async function createTestJWKS(alg: string, crv?: string) {
+		const { publicKey, privateKey } = await generateKeyPair(alg, {
+			crv,
+			extractable: true,
+		});
+		const publicJWK = await exportJWK(publicKey);
+		const privateJWK = await exportJWK(privateKey);
+		const kid = `test-key-${Date.now()}`;
+		publicJWK.kid = kid;
+		privateJWK.kid = kid;
+		return { publicJWK, privateJWK, kid, publicKey, privateKey };
+	}
+
+	async function createSignedToken(
+		privateKey: CryptoKey,
+		alg: string,
+		kid: string,
+		payload: Record<string, unknown> = {},
+	) {
+		return await new SignJWT({
+			sub: "user-123",
+			email: "test@example.com",
+			iss: "https://example.com",
+			aud: "test-client",
+			...payload,
+		})
+			.setProtectedHeader({ alg, kid })
+			.setIssuedAt()
+			.setExpirationTime("1h")
+			.sign(privateKey);
+	}
+
+	it("should verify RS256 signed token", async () => {
+		const { publicJWK, privateKey, kid } = await createTestJWKS("RS256");
+		const token = await createSignedToken(privateKey, "RS256", kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [publicJWK] },
+			error: null,
+		});
+
+		const result = await validateToken(
+			token,
+			"https://example.com/.well-known/jwks",
+		);
+
+		expect(result).toBeDefined();
+		expect(result.payload.sub).toBe("user-123");
+		expect(result.payload.email).toBe("test@example.com");
+		expect(mockedBetterFetch).toHaveBeenCalledWith(
+			"https://example.com/.well-known/jwks",
+			expect.objectContaining({ method: "GET" }),
+		);
+	});
+
+	it("should verify ES256 signed token", async () => {
+		const { publicJWK, privateKey, kid } = await createTestJWKS("ES256");
+		const token = await createSignedToken(privateKey, "ES256", kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [publicJWK] },
+			error: null,
+		});
+
+		const result = await validateToken(
+			token,
+			"https://example.com/.well-known/jwks",
+		);
+
+		expect(result).toBeDefined();
+		expect(result.payload.sub).toBe("user-123");
+	});
+
+	it("should verify EdDSA (Ed25519) signed token", async () => {
+		const { publicJWK, privateKey, kid } = await createTestJWKS(
+			"EdDSA",
+			"Ed25519",
+		);
+		const token = await createSignedToken(privateKey, "EdDSA", kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [publicJWK] },
+			error: null,
+		});
+
+		const result = await validateToken(
+			token,
+			"https://example.com/.well-known/jwks",
+		);
+
+		expect(result).toBeDefined();
+		expect(result.payload.sub).toBe("user-123");
+	});
+
+	it("should throw 'Key not found' when kid doesn't match", async () => {
+		const { publicJWK, privateKey } = await createTestJWKS("RS256");
+		publicJWK.kid = "different-kid";
+		const token = await createSignedToken(privateKey, "RS256", "original-kid");
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [publicJWK] },
+			error: null,
+		});
+
+		await expect(
+			validateToken(token, "https://example.com/.well-known/jwks"),
+		).rejects.toThrow("Key not found");
+	});
+
+	it("should find correct key when multiple keys exist", async () => {
+		const key1 = await createTestJWKS("RS256");
+		const key2 = await createTestJWKS("RS256");
+		const key3 = await createTestJWKS("ES256");
+		const token = await createSignedToken(key2.privateKey, "RS256", key2.kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [key1.publicJWK, key2.publicJWK, key3.publicJWK] },
+			error: null,
+		});
+
+		const result = await validateToken(
+			token,
+			"https://example.com/.well-known/jwks",
+		);
+
+		expect(result).toBeDefined();
+		expect(result.payload.sub).toBe("user-123");
+	});
+
+	it("should throw when JWKS returns empty keys array", async () => {
+		const { privateKey, kid } = await createTestJWKS("RS256");
+		const token = await createSignedToken(privateKey, "RS256", kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: { keys: [] },
+			error: null,
+		});
+
+		await expect(
+			validateToken(token, "https://example.com/.well-known/jwks"),
+		).rejects.toThrow("Key not found");
+	});
+
+	it("should throw when JWKS fetch fails", async () => {
+		const { privateKey, kid } = await createTestJWKS("RS256");
+		const token = await createSignedToken(privateKey, "RS256", kid);
+
+		mockedBetterFetch.mockResolvedValueOnce({
+			data: null,
+			error: { status: 500, statusText: "Internal Server Error" },
+		});
+
+		await expect(
+			validateToken(token, "https://example.com/.well-known/jwks"),
+		).rejects.toBeDefined();
+	});
+});

package/src/oauth2/verify.ts

@@ -0,0 +1,221 @@
+import { betterFetch } from "@better-fetch/fetch";
+import { APIError } from "better-call";
+import type {
+	JSONWebKeySet,
+	JWTPayload,
+	JWTVerifyOptions,
+	ProtectedHeaderParameters,
+} from "jose";
+import {
+	createLocalJWKSet,
+	decodeProtectedHeader,
+	jwtVerify,
+	UnsecuredJWT,
+} from "jose";
+import { logger } from "../env";
+
+/** Last fetched jwks used locally in getJwks @internal */
+let jwks: JSONWebKeySet | undefined;
+
+export interface VerifyAccessTokenRemote {
+	/** Full url of the introspect endpoint. Should end with `/oauth2/introspect` */
+	introspectUrl: string;
+	/** Client Secret */
+	clientId: string;
+	/** Client Secret */
+	clientSecret: string;
+	/**
+	 * Forces remote verification of a token.
+	 * This ensures attached session (if applicable)
+	 * is also still active.
+	 */
+	force?: boolean;
+}
+
+/**
+ * Performs local verification of an access token for your APIs.
+ *
+ * Can also be configured for remote verification.
+ */
+export async function verifyJwsAccessToken(
+	token: string,
+	opts: {
+		/** Jwks url or promise of a Jwks */
+		jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
+		/** Verify options */
+		verifyOptions: JWTVerifyOptions &
+			Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+	},
+) {
+	try {
+		const jwks = await getJwks(token, opts);
+		const jwt = await jwtVerify<JWTPayload>(
+			token,
+			createLocalJWKSet(jwks),
+			opts.verifyOptions,
+		);
+		// Return the JWT payload in introspection format
+		// https://datatracker.ietf.org/doc/html/rfc7662#section-2.2
+		if (jwt.payload.azp) {
+			jwt.payload.client_id = jwt.payload.azp;
+		}
+		return jwt.payload;
+	} catch (error) {
+		if (error instanceof Error) throw error;
+		throw new Error(error as unknown as string);
+	}
+}
+
+export async function getJwks(
+	token: string,
+	opts: {
+		/** Jwks url or promise of a Jwks */
+		jwksFetch: string | (() => Promise<JSONWebKeySet | undefined>);
+	},
+) {
+	// Attempt to decode the token and find a matching kid in jwks
+	let jwtHeaders: ProtectedHeaderParameters | undefined;
+	try {
+		jwtHeaders = decodeProtectedHeader(token);
+	} catch (error) {
+		if (error instanceof Error) throw error;
+		throw new Error(error as unknown as string);
+	}
+
+	if (!jwtHeaders.kid) throw new Error("Missing jwt kid");
+
+	// Fetch jwks if not set or has a different kid than the one stored
+	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
+		jwks =
+			typeof opts.jwksFetch === "string"
+				? await betterFetch<JSONWebKeySet>(opts.jwksFetch, {
+						headers: {
+							Accept: "application/json",
+						},
+					}).then(async (res) => {
+						if (res.error)
+							throw new Error(
+								`Jwks failed: ${res.error.message ?? res.error.statusText}`,
+							);
+						return res.data;
+					})
+				: await opts.jwksFetch();
+		if (!jwks) throw new Error("No jwks found");
+	}
+
+	return jwks;
+}
+
+/**
+ * Performs local verification of an access token for your API.
+ *
+ * Can also be configured for remote verification.
+ */
+export async function verifyAccessToken(
+	token: string,
+	opts: {
+		/** Verify options */
+		verifyOptions: JWTVerifyOptions &
+			Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
+		/** Scopes to additionally verify. Token must include all but not exact. */
+		scopes?: string[];
+		/** Required to verify access token locally */
+		jwksUrl?: string;
+		/** If provided, can verify a token remotely */
+		remoteVerify?: VerifyAccessTokenRemote;
+	},
+) {
+	let payload: JWTPayload | undefined;
+	// Locally verify
+	if (opts.jwksUrl && !opts?.remoteVerify?.force) {
+		try {
+			payload = await verifyJwsAccessToken(token, {
+				jwksFetch: opts.jwksUrl,
+				verifyOptions: opts.verifyOptions,
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				if (error.name === "TypeError" || error.name === "JWSInvalid") {
+					// likely an opaque token (continue)
+				} else if (error.name === "JWTExpired") {
+					throw new APIError("UNAUTHORIZED", {
+						message: "token expired",
+					});
+				} else if (error.name === "JWTInvalid") {
+					throw new APIError("UNAUTHORIZED", {
+						message: "token invalid",
+					});
+				} else {
+					throw error;
+				}
+			} else {
+				throw new Error(error as unknown as string);
+			}
+		}
+	}
+
+	// Remote verify
+	if (opts?.remoteVerify) {
+		const { data: introspect, error: introspectError } = await betterFetch<
+			JWTPayload & {
+				active: boolean;
+			}
+		>(opts.remoteVerify.introspectUrl, {
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				"Content-Type": "application/x-www-form-urlencoded",
+			},
+			body: new URLSearchParams({
+				client_id: opts.remoteVerify.clientId,
+				client_secret: opts.remoteVerify.clientSecret,
+				token,
+				token_type_hint: "access_token",
+			}).toString(),
+		});
+		if (introspectError)
+			logger.error(
+				`Introspection failed: ${introspectError.message ?? introspectError.statusText}`,
+			);
+		if (!introspect)
+			throw new APIError("INTERNAL_SERVER_ERROR", {
+				message: "introspection failed",
+			});
+		if (!introspect.active)
+			throw new APIError("UNAUTHORIZED", {
+				message: "token inactive",
+			});
+		// Verifies payload using verify options (token valid through introspect)
+		try {
+			const unsecuredJwt = new UnsecuredJWT(introspect).encode();
+			const { audience: _audience, ...verifyOptions } = opts.verifyOptions;
+			const verify = introspect.aud
+				? UnsecuredJWT.decode(unsecuredJwt, opts.verifyOptions)
+				: UnsecuredJWT.decode(unsecuredJwt, verifyOptions);
+			payload = verify.payload;
+		} catch (error) {
+			throw new Error(error as unknown as string);
+		}
+	}
+
+	if (!payload)
+		throw new APIError("UNAUTHORIZED", {
+			message: `no token payload`,
+		});
+
+	// Check scopes if provided
+	if (opts.scopes) {
+		const validScopes = new Set(
+			(payload.scope as string | undefined)?.split(" "),
+		);
+		for (const sc of opts.scopes) {
+			if (!validScopes.has(sc)) {
+				throw new APIError("FORBIDDEN", {
+					message: `invalid scope ${sc}`,
+				});
+			}
+		}
+	}
+
+	return payload;
+}