@hfunlabs/hypurr-connect 0.1.21 → 0.1.23

package/README.md

@@ -44,10 +44,12 @@ pnpm add @hfunlabs/hyperliquid @protobuf-ts/grpcweb-transport @protobuf-ts/runti
 import { HypurrConnectProvider } from "@hfunlabs/hypurr-connect";
 
 const config = {
+  clientId: "your-client-id",
   isTestnet: false,
   grpcUrl: "https://grpc.hypurr.fun",
   telegram: {
     authHubUrl: "https://auth.hypurr.fun/login",
+    // tokenUrl defaults to https://auth.hypurr.fun/token
     scope: [
       "telegram:user:read",
       "telegram:wallet:read",
@@ -118,12 +120,14 @@ function AppShell() {
 
 ```typescript
 interface HypurrConnectConfig {
+  clientId: string; // Auth hub client identifier
   grpcUrl?: string; // gRPC-web base URL (default: https://grpc.hypurr.fun)
   mediaUrl?: string; // Media base URL (default: https://media.hypurr.fun)
   grpcTimeout?: number; // Request timeout in ms (default: 15000)
   isTestnet?: boolean; // Use testnet endpoints (default: false)
   telegram: {
     authHubUrl?: string; // Auth hub URL (default: https://auth.hypurr.fun/login)
+    tokenUrl?: string; // Token exchange URL (default: auth hub /token)
     returnTo?: string | (() => string); // Callback URL (default: current page)
     scope?: string | string[]; // Requested JWT scopes
   };
@@ -132,7 +136,8 @@ interface HypurrConnectConfig {
 
 The SDK no longer renders Telegram's login widget or opens `oauth.telegram.org`
 directly. Telegram login is delegated to the Hypurr auth hub in a popup, and the
-popup posts the scoped JWT back to the original page.
+popup posts either a legacy scoped JWT or an authorization code back to the
+original page.
 
 ### Dependencies
 
@@ -144,17 +149,20 @@ for generated protobuf service clients.
 ### Telegram Login
 
 1. User clicks "Telegram" in the `LoginModal`.
-2. The SDK opens the configured auth hub in a popup with `return_to`, `state`,
-   and requested `scope`.
+2. The SDK opens the configured auth hub in a popup with `client_id`,
+   `return_to`, `state`, requested `scope`, `code_challenge`, and
+   `code_challenge_method=S256`.
 3. The auth hub performs Telegram login and redirects back to `return_to` with
-   a scoped JWT.
-4. The popup callback page posts `{ token, state }` to the opener with
-   `postMessage` and closes.
-5. The opener validates `state`, stores the JWT, and calls the Hypurr gRPC
-   backend with `Authorization: Bearer <jwt>` metadata.
-6. An `ExchangeClient` is created with `GrpcExchangeTransport`; exchange
+   either a legacy scoped JWT or an authorization code.
+4. The popup callback page posts `{ token, state }` or `{ code, state }` to the
+   opener with `postMessage` and closes.
+5. The opener validates `state`. Legacy tokens are stored directly; auth codes
+   are exchanged at the configured token URL with the stored PKCE verifier.
+6. The SDK calls the Hypurr gRPC backend with `Authorization: Bearer <jwt>`
+   metadata.
+7. An `ExchangeClient` is created with `GrpcExchangeTransport`; exchange
    actions are still signed server-side by the Hypurr backend.
-7. The JWT session is persisted in localStorage (`hypurr-connect-tg-jwt`).
+8. The JWT session is persisted in localStorage (`hypurr-connect-tg-jwt`).
 
 If the popup is blocked, the SDK falls back to a full-page redirect. The
 default `returnTo` is the current page with auth query params removed; custom
@@ -579,8 +587,8 @@ Creates a gRPC-Web client for the Telegram service.
 
 Creates a gRPC-Web client for the Static service.
 
-Both use `GrpcWebFetchTransport` with `config.grpcUrl` as `baseUrl` and
-`config.grpcTimeout` as `timeout`.
+Both use `GrpcWebFetchTransport` with `config.grpcUrl` or the default gRPC URL
+as `baseUrl`, and `config.grpcTimeout` as `timeout`.
 
 ## localStorage Keys
 

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
 import { AbstractViemLocalAccount } from '@hfunlabs/hyperliquid/signing';
 
 interface HypurrConnectConfig {
+    /** Auth hub client identifier. Sent as `client_id` during Telegram login. */
+    clientId: string;
     /** gRPC-web base URL. Defaults to https://grpc.hypurr.fun. */
     grpcUrl?: string;
     /** Media base URL for user-uploaded assets. Defaults to https://media.hypurr.fun. */
@@ -25,6 +27,8 @@ interface HypurrConnectConfig {
     telegram?: {
         /** Auth hub login URL. Defaults to https://auth.hypurr.fun/login. */
         authHubUrl?: string;
+        /** Auth hub token exchange URL. Defaults to the auth hub login URL with `/login` replaced by `/token`. */
+        tokenUrl?: string;
         /** Optional callback URL. Defaults to the current page without auth query params. */
         returnTo?: string | (() => string);
         /** Requested hub scopes. Defaults to the scopes required by this SDK. */

package/dist/index.js

@@ -140,9 +140,12 @@ import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import { StaticClient } from "hypurr-grpc/ts/hypurr/static/static_service.client";
 import { TelegramClient } from "hypurr-grpc/ts/hypurr/telegram/telegram_service.client";
 var DEFAULT_GRPC_URL = "https://grpc.hypurr.fun";
+function resolveGrpcUrl(config) {
+  return config.grpcUrl?.trim() || DEFAULT_GRPC_URL;
+}
 function createTransport(config) {
   return new GrpcWebFetchTransport({
-    baseUrl: config.grpcUrl ?? DEFAULT_GRPC_URL,
+    baseUrl: resolveGrpcUrl(config),
     timeout: config.grpcTimeout ?? 15e3
   });
 }
@@ -292,6 +295,8 @@ import { jsx } from "react/jsx-runtime";
 var TELEGRAM_STORAGE_KEY = "hypurr-connect-tg-jwt";
 var LEGACY_TELEGRAM_STORAGE_KEY = "hypurr-connect-tg-user";
 var TELEGRAM_AUTH_STATE_KEY = "hypurr-connect-auth-state";
+var TELEGRAM_AUTH_CODE_VERIFIER_PREFIX = "hypurr-connect-auth-code-verifier:";
+var TELEGRAM_AUTH_RETURN_TO_PREFIX = "hypurr-connect-auth-return-to:";
 var TELEGRAM_AUTH_MESSAGE = "hypurr-connect:telegram-auth";
 var DEFAULT_AUTH_HUB_URL = "https://auth.hypurr.fun/login";
 var DEFAULT_MEDIA_URL = "https://media.hypurr.fun";
@@ -427,6 +432,9 @@ function withExpectedFrom(transaction, address) {
 function currentReturnTo() {
   const url = new URL(window.location.href);
   for (const param of [
+    "code",
+    "error",
+    "error_description",
     "token",
     "token_type",
     "token_source",
@@ -437,6 +445,29 @@ function currentReturnTo() {
   }
   return url.toString();
 }
+function cleanAuthCallbackUrl() {
+  const cleanUrl = new URL(window.location.href);
+  for (const param of [
+    "code",
+    "error",
+    "error_description",
+    "token",
+    "token_type",
+    "token_source",
+    "state",
+    "scope"
+  ]) {
+    cleanUrl.searchParams.delete(param);
+  }
+  window.history.replaceState({}, document.title, cleanUrl.toString());
+}
+function base64UrlEncode(bytes) {
+  let value = "";
+  for (const byte of bytes) {
+    value += String.fromCharCode(byte);
+  }
+  return btoa(value).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 function randomState() {
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
@@ -444,12 +475,148 @@ function randomState() {
     ""
   );
 }
+function randomCodeVerifier() {
+  const bytes = new Uint8Array(64);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function createCodeChallenge(codeVerifier) {
+  if (!crypto.subtle) {
+    throw new Error(
+      "[HypurrConnect] Web Crypto API is required for Telegram auth."
+    );
+  }
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(codeVerifier)
+  );
+  return base64UrlEncode(new Uint8Array(digest));
+}
 function normalizeScopes(scope) {
   if (Array.isArray(scope)) return scope.join(" ");
   return scope?.trim() || DEFAULT_TELEGRAM_SCOPES.join(" ");
 }
+function normalizeClientId(clientId) {
+  const normalized = typeof clientId === "string" ? clientId.trim() : "";
+  if (!normalized) {
+    throw new Error("[HypurrConnect] config.clientId is required.");
+  }
+  return normalized;
+}
+function codeVerifierStorageKey(state) {
+  return `${TELEGRAM_AUTH_CODE_VERIFIER_PREFIX}${state}`;
+}
+function returnToStorageKey(state) {
+  return `${TELEGRAM_AUTH_RETURN_TO_PREFIX}${state}`;
+}
+function storeTelegramAuthSession(state, codeVerifier, returnTo) {
+  const previousState = sessionStorage.getItem(TELEGRAM_AUTH_STATE_KEY);
+  if (previousState) {
+    sessionStorage.removeItem(codeVerifierStorageKey(previousState));
+    sessionStorage.removeItem(returnToStorageKey(previousState));
+  }
+  sessionStorage.setItem(TELEGRAM_AUTH_STATE_KEY, state);
+  sessionStorage.setItem(codeVerifierStorageKey(state), codeVerifier);
+  sessionStorage.setItem(returnToStorageKey(state), returnTo);
+}
+function clearTelegramAuthSession(state) {
+  sessionStorage.removeItem(TELEGRAM_AUTH_STATE_KEY);
+  sessionStorage.removeItem(codeVerifierStorageKey(state));
+  sessionStorage.removeItem(returnToStorageKey(state));
+}
+function takeTelegramAuthSession(state) {
+  const expectedState = sessionStorage.getItem(TELEGRAM_AUTH_STATE_KEY);
+  sessionStorage.removeItem(TELEGRAM_AUTH_STATE_KEY);
+  if (!expectedState || state !== expectedState) {
+    if (expectedState) {
+      sessionStorage.removeItem(codeVerifierStorageKey(expectedState));
+      sessionStorage.removeItem(returnToStorageKey(expectedState));
+    }
+    return null;
+  }
+  const codeVerifierKey = codeVerifierStorageKey(state);
+  const returnToKey = returnToStorageKey(state);
+  const codeVerifier = sessionStorage.getItem(codeVerifierKey);
+  const returnTo = sessionStorage.getItem(returnToKey);
+  sessionStorage.removeItem(codeVerifierKey);
+  sessionStorage.removeItem(returnToKey);
+  return { codeVerifier, returnTo };
+}
+function resolveAuthTokenUrl(authHubUrl, tokenUrl) {
+  const configuredTokenUrl = tokenUrl?.trim();
+  if (configuredTokenUrl) return configuredTokenUrl;
+  const url = new URL(authHubUrl || DEFAULT_AUTH_HUB_URL);
+  const pathWithoutTrailingSlash = url.pathname.replace(/\/+$/, "");
+  const basePath = pathWithoutTrailingSlash.replace(/\/[^/]*$/, "");
+  url.pathname = `${basePath}/token`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+function getTokenFromExchangeResponse(data) {
+  if (typeof data === "string") {
+    const token = data.trim();
+    return token || null;
+  }
+  if (typeof data !== "object" || data === null) return null;
+  const response = data;
+  for (const token of [response.token, response.access_token, response.jwt]) {
+    if (typeof token === "string" && token.trim()) return token.trim();
+  }
+  return null;
+}
+async function exchangeTelegramAuthCode({
+  authHubUrl,
+  clientId,
+  code,
+  codeVerifier,
+  returnTo,
+  tokenUrl
+}) {
+  const body = new URLSearchParams({
+    client_id: clientId,
+    code,
+    code_verifier: codeVerifier,
+    grant_type: "authorization_code",
+    return_to: returnTo
+  });
+  const response = await fetch(resolveAuthTokenUrl(authHubUrl, tokenUrl), {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/x-www-form-urlencoded"
+    },
+    body
+  });
+  const responseText = await response.text();
+  if (!response.ok) {
+    const detail = responseText.trim();
+    throw new Error(
+      detail ? `[HypurrConnect] Auth code exchange failed: ${detail}` : `[HypurrConnect] Auth code exchange failed with HTTP ${response.status}.`
+    );
+  }
+  let responseData = responseText;
+  if (responseText) {
+    try {
+      responseData = JSON.parse(responseText);
+    } catch {
+      responseData = responseText;
+    }
+  }
+  const token = getTokenFromExchangeResponse(responseData);
+  if (!token) {
+    throw new Error("[HypurrConnect] Auth code exchange did not return a JWT.");
+  }
+  return token;
+}
 function isTelegramAuthMessage(data) {
-  return typeof data === "object" && data !== null && "type" in data && "token" in data && "state" in data && data.type === TELEGRAM_AUTH_MESSAGE && typeof data.token === "string" && typeof data.state === "string";
+  if (typeof data !== "object" || data === null) return false;
+  if (!("type" in data) || !("state" in data)) return false;
+  const message = data;
+  const hasToken = typeof message.token === "string";
+  const hasCode = typeof message.code === "string";
+  const hasError = typeof message.error === "string";
+  return message.type === TELEGRAM_AUTH_MESSAGE && typeof message.state === "string" && (hasToken || hasCode || hasError);
 }
 var HypurrConnectContext = createContext(null);
 function useHypurrConnect() {
@@ -507,6 +674,49 @@ function HypurrConnectProvider({
     localStorage.setItem(TELEGRAM_STORAGE_KEY, token);
     localStorage.removeItem(LEGACY_TELEGRAM_STORAGE_KEY);
   }, []);
+  const handleTelegramAuthCallback = useCallback(
+    (callback) => {
+      const authSession = takeTelegramAuthSession(callback.state);
+      if (!authSession) {
+        setTgError("Invalid auth callback state.");
+        return;
+      }
+      if (callback.error) {
+        setTgError(callback.error);
+        return;
+      }
+      if (callback.code) {
+        if (!authSession.codeVerifier) {
+          setTgError("Missing auth code verifier.");
+          return;
+        }
+        setTgLoading(true);
+        setTgError(null);
+        void exchangeTelegramAuthCode({
+          authHubUrl: config.telegram?.authHubUrl,
+          clientId: normalizeClientId(config.clientId),
+          code: callback.code,
+          codeVerifier: authSession.codeVerifier,
+          returnTo: authSession.returnTo || currentReturnTo(),
+          tokenUrl: config.telegram?.tokenUrl
+        }).then(acceptTelegramToken).catch(
+          (err) => setTgError(err instanceof Error ? err.message : String(err))
+        ).finally(() => setTgLoading(false));
+        return;
+      }
+      if (callback.token) {
+        acceptTelegramToken(callback.token);
+        return;
+      }
+      setTgError("Invalid auth callback.");
+    },
+    [
+      acceptTelegramToken,
+      config.clientId,
+      config.telegram?.authHubUrl,
+      config.telegram?.tokenUrl
+    ]
+  );
   useEffect(() => {
     if (typeof document === "undefined" || !document.fonts) return;
     for (const face of [
@@ -522,57 +732,37 @@ function HypurrConnectProvider({
   useEffect(() => {
     const params = new URLSearchParams(window.location.search);
     const token = params.get("token");
-    if (!token) {
+    const code = params.get("code");
+    const error = params.get("error_description") || params.get("error") || void 0;
+    if (!token && !code && !error) {
       localStorage.removeItem(LEGACY_TELEGRAM_STORAGE_KEY);
       return;
     }
     const callbackState = params.get("state") ?? "";
+    const callback = {
+      code: code || void 0,
+      error,
+      state: callbackState,
+      token: token || void 0,
+      type: TELEGRAM_AUTH_MESSAGE
+    };
     if (window.opener && window.opener !== window) {
-      window.opener.postMessage(
-        {
-          type: TELEGRAM_AUTH_MESSAGE,
-          token,
-          state: callbackState
-        },
-        window.location.origin
-      );
+      window.opener.postMessage(callback, window.location.origin);
       window.close();
       return;
     }
-    const expectedState = sessionStorage.getItem(TELEGRAM_AUTH_STATE_KEY);
-    sessionStorage.removeItem(TELEGRAM_AUTH_STATE_KEY);
-    if (!expectedState || callbackState !== expectedState) {
-      setTgError("Invalid auth callback state.");
-      return;
-    }
-    acceptTelegramToken(token);
-    const cleanUrl = new URL(window.location.href);
-    for (const param of [
-      "token",
-      "token_type",
-      "token_source",
-      "state",
-      "scope"
-    ]) {
-      cleanUrl.searchParams.delete(param);
-    }
-    window.history.replaceState({}, document.title, cleanUrl.toString());
-  }, [acceptTelegramToken]);
+    cleanAuthCallbackUrl();
+    handleTelegramAuthCallback(callback);
+  }, [handleTelegramAuthCallback]);
   useEffect(() => {
     function onMessage(event) {
       if (event.origin !== window.location.origin) return;
       if (!isTelegramAuthMessage(event.data)) return;
-      const expectedState = sessionStorage.getItem(TELEGRAM_AUTH_STATE_KEY);
-      sessionStorage.removeItem(TELEGRAM_AUTH_STATE_KEY);
-      if (!expectedState || event.data.state !== expectedState) {
-        setTgError("Invalid auth callback state.");
-        return;
-      }
-      acceptTelegramToken(event.data.token);
+      handleTelegramAuthCallback(event.data);
     }
     window.addEventListener("message", onMessage);
     return () => window.removeEventListener("message", onMessage);
-  }, [acceptTelegramToken]);
+  }, [handleTelegramAuthCallback]);
   useEffect(() => {
     if (!tgAuthToken || !telegramRpcOptions) return;
     let cancelled = false;
@@ -1307,21 +1497,16 @@ function HypurrConnectProvider({
   const closeLoginModal = useCallback(() => setLoginModalOpen(false), []);
   const loginTelegram = useCallback(() => {
     const state = randomState();
-    sessionStorage.setItem(TELEGRAM_AUTH_STATE_KEY, state);
+    const codeVerifier = randomCodeVerifier();
     const configuredReturnTo = config.telegram?.returnTo;
     const returnTo = typeof configuredReturnTo === "function" ? configuredReturnTo() : configuredReturnTo || currentReturnTo();
-    const authUrl = new URL(
-      config.telegram?.authHubUrl || DEFAULT_AUTH_HUB_URL
-    );
-    authUrl.searchParams.set("return_to", returnTo);
-    authUrl.searchParams.set("state", state);
-    authUrl.searchParams.set("scope", normalizeScopes(config.telegram?.scope));
+    storeTelegramAuthSession(state, codeVerifier, returnTo);
     const width = 520;
     const height = 720;
     const left = window.screenX + Math.max(0, (window.outerWidth - width) / 2);
     const top = window.screenY + Math.max(0, (window.outerHeight - height) / 2);
     const popup = window.open(
-      authUrl.toString(),
+      "about:blank",
       "hypurr_telegram_auth",
       [
         `width=${width}`,
@@ -1332,12 +1517,40 @@ function HypurrConnectProvider({
         "scrollbars=yes"
       ].join(",")
     );
-    if (popup) {
-      popup.focus();
-      return;
-    }
-    window.location.assign(authUrl.toString());
+    void (async () => {
+      try {
+        const authUrl = new URL(
+          config.telegram?.authHubUrl || DEFAULT_AUTH_HUB_URL
+        );
+        authUrl.searchParams.set(
+          "client_id",
+          normalizeClientId(config.clientId)
+        );
+        authUrl.searchParams.set("return_to", returnTo);
+        authUrl.searchParams.set("state", state);
+        authUrl.searchParams.set(
+          "scope",
+          normalizeScopes(config.telegram?.scope)
+        );
+        authUrl.searchParams.set(
+          "code_challenge",
+          await createCodeChallenge(codeVerifier)
+        );
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        if (popup) {
+          popup.location.assign(authUrl.toString());
+          popup.focus();
+          return;
+        }
+        window.location.assign(authUrl.toString());
+      } catch (err) {
+        clearTelegramAuthSession(state);
+        if (popup && !popup.closed) popup.close();
+        setTgError(err instanceof Error ? err.message : String(err));
+      }
+    })();
   }, [
+    config.clientId,
     config.telegram?.authHubUrl,
     config.telegram?.returnTo,
     config.telegram?.scope