✨ Introduce oauthLogin function

.vscode/settings.json

@@ -2,7 +2,7 @@
 	"editor.defaultFormatter": "esbenp.prettier-vscode",
 	"editor.formatOnSave": true,
 	"editor.codeActionsOnSave": {
-		"source.fixAll": true
+		"source.fixAll": "explicit"
 	},
 	"[svelte]": {
 		"editor.defaultFormatter": "esbenp.prettier-vscode"

packages/hub/README.md

@@ -89,6 +89,26 @@ for await (const fileInfo of listFiles({repo})) {
 await deleteRepo({ repo, credentials });
 ```
 
+## OAuth Login
+
+It's possible to login using OAuth (["Sign in with HF"](https://huggingface.co/docs/hub/oauth)).
+
+This will allow you get an access token to use some of the API, depending of the scopes set inside the Space or the OAuth App.
+
+```ts
+import { oauthLogin, oauthHandleRedirectIfPresent } from "@huggingface/hub";
+
+const oauthResult = await oauthHandleRedirectIfPresent();
+
+if (!oauthResult) {
+  // If the user is not logged in, redirect to the login page
+  oauthLogin();
+}
+
+// You can use oauthResult.accessToken and oauthResult.userInfo
+console.log(oauthResult);
+```
+
 ## Performance considerations
 
 When uploading large files, you may want to run the `commit` calls inside a worker, to offload the sha256 computations.

packages/hub/src/lib/index.ts

@@ -10,6 +10,8 @@ export * from "./list-datasets";
 export * from "./list-files";
 export * from "./list-models";
 export * from "./list-spaces";
+export * from "./oauth-handle-redirect";
+export * from "./oauth-login";
 export * from "./parse-safetensors-metadata";
 export * from "./upload-file";
 export * from "./upload-files";

packages/hub/src/lib/list-datasets.spec.ts

@@ -7,6 +7,9 @@ describe("listDatasets", () => {
 		const results: DatasetEntry[] = [];
 
 		for await (const entry of listDatasets({ search: { owner: "hf-doc-build" } })) {
+			if (entry.name === "hf-doc-build/doc-build-dev-test") {
+				continue;
+			}
 			if (typeof entry.downloads === "number") {
 				entry.downloads = 0;
 			}

packages/hub/src/lib/oauth-handle-redirect.ts

@@ -0,0 +1,203 @@
+import { HUB_URL } from "../consts";
+import { createApiError } from "../error";
+
+export interface OAuthResult {
+	accessToken: string;
+	accessTokenExpiresAt: Date;
+	userInfo: {
+		id: string;
+		name: string;
+		fullname: string;
+		email?: string;
+		emailVerified?: boolean;
+		avatarUrl: string;
+		websiteUrl?: string;
+		isPro: boolean;
+		orgs: Array<{
+			name: string;
+			isEnterprise: boolean;
+		}>;
+	};
+	/**
+	 * State passed to the OAuth provider in the original request to the OAuth provider.
+	 */
+	state?: string;
+	/**
+	 * Granted scope
+	 */
+	scope: string;
+}
+
+/**
+ * To call after the OAuth provider redirects back to the app.
+ */
+export async function oauthHandleRedirect(opts?: { hubUrl?: string }): Promise<OAuthResult> {
+	if (typeof window === "undefined") {
+		throw new Error("oauthHandleRedirect is only available in the browser");
+	}
+
+	const searchParams = new URLSearchParams(window.location.search);
+
+	const [error, errorDescription] = [searchParams.get("error"), searchParams.get("error_description")];
+
+	if (error) {
+		throw new Error(`${error}: ${errorDescription}`);
+	}
+
+	const code = searchParams.get("code");
+	const nonce = localStorage.getItem("huggingface.co:oauth:nonce");
+
+	if (!code) {
+		throw new Error("Missing oauth code from query parameters in redirected URL");
+	}
+
+	if (!nonce) {
+		throw new Error("Missing oauth nonce from localStorage");
+	}
+
+	const codeVerifier = localStorage.getItem("huggingface.co:oauth:code_verifier");
+
+	if (!codeVerifier) {
+		throw new Error("Missing oauth code_verifier from localStorage");
+	}
+
+	const state = searchParams.get("state");
+
+	if (!state) {
+		throw new Error("Missing oauth state from query parameters in redirected URL");
+	}
+
+	let parsedState: { nonce: string; redirectUri: string; state?: string };
+
+	try {
+		parsedState = JSON.parse(state);
+	} catch {
+		throw new Error("Invalid oauth state in redirected URL, unable to parse JSON: " + state);
+	}
+
+	if (parsedState.nonce !== nonce) {
+		throw new Error("Invalid oauth state in redirected URL");
+	}
+
+	const hubUrl = opts?.hubUrl || HUB_URL;
+
+	const openidConfigUrl = `${new URL(hubUrl).origin}/.well-known/openid-configuration`;
+	const openidConfigRes = await fetch(openidConfigUrl, {
+		headers: {
+			Accept: "application/json",
+		},
+	});
+
+	if (!openidConfigRes.ok) {
+		throw await createApiError(openidConfigRes);
+	}
+
+	const opendidConfig: {
+		authorization_endpoint: string;
+		token_endpoint: string;
+		userinfo_endpoint: string;
+	} = await openidConfigRes.json();
+
+	const tokenRes = await fetch(opendidConfig.token_endpoint, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+		},
+		body: new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: parsedState.redirectUri,
+			code_verifier: codeVerifier,
+		}).toString(),
+	});
+
+	localStorage.removeItem("huggingface.co:oauth:code_verifier");
+	localStorage.removeItem("huggingface.co:oauth:nonce");
+
+	if (!tokenRes.ok) {
+		throw await createApiError(tokenRes);
+	}
+
+	const token: {
+		access_token: string;
+		expires_in: number;
+		id_token: string;
+		// refresh_token: string;
+		scope: string;
+		token_type: string;
+	} = await tokenRes.json();
+
+	const accessTokenExpiresAt = new Date(Date.now() + token.expires_in * 1000);
+
+	const userInfoRes = await fetch(opendidConfig.userinfo_endpoint, {
+		headers: {
+			Authorization: `Bearer ${token.access_token}`,
+		},
+	});
+
+	if (!userInfoRes.ok) {
+		throw await createApiError(userInfoRes);
+	}
+
+	const userInfo: {
+		sub: string;
+		name: string;
+		preferred_username: string;
+		email_verified?: boolean;
+		email?: string;
+		picture: string;
+		website?: string;
+		isPro: boolean;
+		orgs?: Array<{
+			name: string;
+			isEnterprise: boolean;
+		}>;
+	} = await userInfoRes.json();
+
+	return {
+		accessToken: token.access_token,
+		accessTokenExpiresAt,
+		userInfo: {
+			id: userInfo.sub,
+			name: userInfo.name,
+			fullname: userInfo.preferred_username,
+			email: userInfo.email,
+			emailVerified: userInfo.email_verified,
+			avatarUrl: userInfo.picture,
+			websiteUrl: userInfo.website,
+			isPro: userInfo.isPro,
+			orgs: userInfo.orgs || [],
+		},
+		state: parsedState.state,
+		scope: token.scope,
+	};
+}
+
+// if (code && !nonce) {
+//   console.warn("Missing oauth nonce from localStorage");
+// }
+
+export async function oauthHandleRedirectIfPresent(opts?: { hubUrl?: string }): Promise<OAuthResult | false> {
+	if (typeof window === "undefined") {
+		throw new Error("oauthHandleRedirect is only available in the browser");
+	}
+
+	const searchParams = new URLSearchParams(window.location.search);
+
+	if (searchParams.has("error")) {
+		return oauthHandleRedirect(opts);
+	}
+
+	if (searchParams.has("code")) {
+		if (!localStorage.getItem("huggingface.co:oauth:nonce")) {
+			console.warn(
+				"Missing oauth nonce from localStorage. This can happen when the user refreshes the page after logging in, without changing the URL."
+			);
+			return false;
+		}
+
+		return oauthHandleRedirect(opts);
+	}
+
+	return false;
+}

packages/hub/src/lib/oauth-login.ts

@@ -0,0 +1,119 @@
+import { base64FromBytes } from "../../../shared/src";
+import { HUB_URL } from "../consts";
+import { createApiError } from "../error";
+
+/**
+ * Use "Sign in with Hub" to authenticate a user, and get oauth user info / access token.
+ *
+ * - First, call `oauthLogin` to trigger the redirect to huggingface.co
+ * - Then, after the redirect, call `oauthHandleRedirect` to get the oauth user info / access token
+ *
+ * There is also `oauthHandleRedirectIfPresent`, which will call `oauthHandleRedirect` if the URL contains an oauth code.
+ *
+ * When called from inside a static Space with OAuth enabled, it will load the config from the space.
+ *
+ * (Theoretically, this function could be used to authenticate a user for any OAuth provider supporting PKCE and OpenID Connect by changing `hubUrl`,
+ * but it is currently only tested with the Hugging Face Hub.)
+ */
+export async function oauthLogin(opts?: {
+	/**
+	 * OAuth client ID.
+	 *
+	 * For static Spaces, you can omit this and it will be loaded from the Space config, as long as `hf_oauth: true` is present in the README.md's metadata.
+	 * For other Spaces, it is available to the backend in the OAUTH_CLIENT_ID environment variable, as long as `hf_oauth: true` is present in the README.md's metadata.
+	 *
+	 * You can also create a Developer Application at https://huggingface.co/settings/connected-applications and use its client ID.
+	 */
+	clientId?: string;
+	hubUrl?: string;
+	/**
+	 * OAuth scope, a list of space separate scopes.
+	 *
+	 * For static Spaces, you can omit this and it will be loaded from the Space config, as long as `hf_oauth: true` is present in the README.md's metadata.
+	 * For other Spaces, it is available to the backend in the OAUTH_SCOPES environment variable, as long as `hf_oauth: true` is present in the README.md's metadata.
+	 *
+	 * Defaults to "openid profile".
+	 *
+	 * You can also create a Developer Application at https://huggingface.co/settings/connected-applications and use its scopes.
+	 *
+	 * See https://huggingface.co/docs/hub/oauth for a list of available scopes.
+	 */
+	scopes?: string;
+	/**
+	 * Redirect URI, defaults to the current URL.
+	 *
+	 * For Spaces, any URL within the Space is allowed.
+	 *
+	 * For Developer Applications, you can add any URL you want to the list of allowed redirect URIs at https://huggingface.co/settings/connected-applications.
+	 */
+	redirectUri?: string;
+	/**
+	 * State to pass to the OAuth provider, which will be returned in the call to `oauthLogin` after the redirect.
+	 */
+	state?: string;
+}): Promise<void> {
+	if (typeof window === "undefined") {
+		throw new Error("oauthLogin is only available in the browser");
+	}
+
+	const hubUrl = opts?.hubUrl || HUB_URL;
+	const openidConfigUrl = `${new URL(hubUrl).origin}/.well-known/openid-configuration`;
+	const openidConfigRes = await fetch(openidConfigUrl, {
+		headers: {
+			Accept: "application/json",
+		},
+	});
+
+	if (!openidConfigRes.ok) {
+		throw await createApiError(openidConfigRes);
+	}
+
+	const opendidConfig: {
+		authorization_endpoint: string;
+		token_endpoint: string;
+		userinfo_endpoint: string;
+	} = await openidConfigRes.json();
+
+	const newNonce = crypto.randomUUID();
+	// Two random UUIDs concatenated together, because min length is 43 and max length is 128
+	const newCodeVerifier = crypto.randomUUID() + crypto.randomUUID();
+
+	localStorage.setItem("huggingface.co:oauth:nonce", newNonce);
+	localStorage.setItem("huggingface.co:oauth:code_verifier", newCodeVerifier);
+
+	const redirectUri = opts?.redirectUri || window.location.href;
+	const state = JSON.stringify({
+		nonce: newNonce,
+		redirectUri,
+		state: opts?.state,
+	});
+
+	// @ts-expect-error window.huggingface is defined inside static Spaces.
+	const variables: Record<string, string> | null = window?.huggingface?.variables ?? null;
+
+	const clientId = opts?.clientId || variables?.OAUTH_CLIENT_ID;
+
+	if (!clientId) {
+		if (variables) {
+			throw new Error("Missing clientId, please add hf_oauth: true to the README.md's metadata in your static Space");
+		}
+		throw new Error("Missing clientId");
+	}
+
+	const challenge = base64FromBytes(
+		new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(newCodeVerifier)))
+	)
+		.replace(/[+]/g, "-")
+		.replace(/[/]/g, "_")
+		.replace(/=/g, "");
+
+	window.location.href = `${opendidConfig.authorization_endpoint}?${new URLSearchParams({
+		client_id: clientId,
+		scope: opts?.scopes || "openid profile",
+		response_type: "code",
+		redirect_uri: redirectUri,
+		state,
+		code_challenge: challenge,
+		code_challenge_method: "S256",
+	}).toString()}`;
+}