HuggingfaceClient.Hub.OAuth (huggingface_client v0.1.0)

PKCE OAuth 2.0 login flow for HuggingFace Hub.

Implements the Authorization Code flow with Proof Key for Code Exchange (PKCE) as required by the HuggingFace OAuth provider.

Usage

# Step 1 — build the redirect URL
{:ok, %{url: url, state: state, nonce: nonce, code_verifier: verifier}} =
  HuggingfaceClient.Hub.OAuth.login_url(client_id: "my-app-id")

# Redirect the user to `url`, storing state/nonce/verifier in session.

# Step 2 — after the user is redirected back, exchange the code
{:ok, %{"access_token" => token}} =
  HuggingfaceClient.Hub.OAuth.handle_redirect(
    code:          params["code"],
    state:         params["state"],
    stored_state:  session["state"],
    nonce:         session["nonce"],
    code_verifier: session["code_verifier"],
    client_id:     "my-app-id"
  )

Summary

Functions

handle_redirect(opts)

Validates the OAuth callback and exchanges the code for tokens.

login_url(opts \\ [])

Generates a PKCE authorization URL to start the OAuth login flow.

Functions

handle_redirect(opts)

@spec handle_redirect(keyword()) :: {:ok, map()} | {:error, Exception.t()}

Validates the OAuth callback and exchanges the code for tokens.

Required options

:code — authorization code from the callback params
:state — state from the callback params
:stored_state — state saved in session before redirect
:code_verifier — PKCE verifier saved in session before redirect
:client_id — same client ID used in login_url/1

Optional options

:redirect_uri, :hub_url, :client_secret

Returns {:error, InputError.t()} on state mismatch or missing code.

login_url(opts \\ [])

@spec login_url(keyword()) ::
  {:ok,
   %{
     url: String.t(),
     state: String.t(),
     nonce: String.t(),
     code_verifier: String.t()
   }}
  | {:error, HuggingfaceClient.Error.InputError.t()}

Generates a PKCE authorization URL to start the OAuth login flow.

Required options

:client_id — your registered OAuth application client ID

Optional options

:redirect_uri — callback URL (must match what's registered)
:scope — space-separated OAuth scopes (default: "openid profile")
:hub_url — override the HF Hub base URL

Returns

{:ok, %{url: binary, state: binary, nonce: binary, code_verifier: binary}} or {:error, InputError.t()} if client_id is missing.