@horus-wallet/sdk-react 0.1.0-beta.2 → 0.3.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @horus-wallet/sdk-react
 
-React provider + hooks + drop-in components for the Horus embedded-wallet platform. Sign-in, wallets, signing, and on-chain transfers in **15 minutes**.
+React provider + hooks + drop-in components for the Horus embedded-wallet platform. Sign-in, wallets, signing, and on-chain transfers in **5 minutes**.
 
 ```tsx
 import { HorusProvider, useHorusAuth, useWallets, HorusLoginButton } from '@horus-wallet/sdk-react';
@@ -30,16 +30,17 @@ function Page() {
 }
 ```
 
-That's it. Sign-in, token persistence, auto-refresh, and wallet fetching all happen inside the provider.
+That's it. **No partner backend, no proxy.** The SDK calls Horus directly with your publishable `app_*` identifier. Sign-in, token persistence, auto-refresh, and wallet fetching all happen inside the provider.
 
 ## What you get
 
-- **Drop-in React DX** — one provider, a handful of hooks, no wallet-management code in your app
+- **Browser-direct** — wrap your app once, you're done. Same shape as Privy / Stripe Elements
+- **Drop-in React DX** — one provider, a handful of hooks, no wallet code in your app
 - **Built-in auth** — email + password, magic-link email, Google / Apple / phone via popup
 - **Multi-chain wallets** — EVM, Bitcoin, ICP, Casper, Aeternity — same hook, pick `network`
 - **Signing + transfers** — `signMessage`, native + ERC-20 transfers, all behind a hook
 - **Token persistence** — sessions survive page reloads; cross-tab sync; auto-refresh near expiry
-- **Drop-in components** — `<HorusLoginButton>` for one-click signin if you don't want to build the UI yourself
+- **Drop-in components** — `<HorusLoginButton>` for one-click signin if you don't want to build the UI
 - **White-label friendly** — partner branding (logo, colors, terms links) flows through to the sign-in popup
 
 ## Install
@@ -50,7 +51,7 @@ npm install @horus-wallet/sdk-react
 
 Peer dependency: React 17+. Works in React 18, Next.js (App Router and Pages), Vite, Remix.
 
-## Quick setup (3 steps)
+## Quick setup
 
 ### 1. Wrap your app in `<HorusProvider>`
 
@@ -66,7 +67,7 @@ export function App({ children }) {
 }
 ```
 
-You get `appId` from Horus during onboarding.
+You get `appId` from Horus during onboarding (format `app_<16-hex>`). Register the domains you'll serve the SDK from on the same app record — that allow-list is the security boundary that stops anyone else from using your `app_*`.
 
 ### 2. Mount a sign-in button
 
@@ -80,30 +81,28 @@ import { HorusLoginButton } from '@horus-wallet/sdk-react';
 
 Or build your own form and call `useHorusAuth()` methods directly (see hooks below).
 
-### 3. Add a server-side proxy
+### 3. There is no step 3.
 
-The React SDK calls **your backend** so your secret API key never reaches the browser:
-
-```
-React app ──► Your backend (~50 lines) ──► api.horuswallet.com
-```
-
-The proxy is a thin pass-through. Reference implementations for Express and Next.js are below.
+You're integrated.
 
 ## Provider config
 
 ```tsx
 <HorusProvider
-  appId="app_acme123"             // required — server-assigned during onboarding
-  apiBase="/api/horus"            // where YOUR backend exposes the proxy. Default: /api/horus
-  
+  appId="app_acme123"             // required — your publishable app identifier
+
+  // Optional — defaults to https://api.horuswallet.com (prod).
+  // Override for dev / staging:
+  //   apiBase="https://dev-api.horuswallet.com"
+  apiBase={process.env.NEXT_PUBLIC_HORUS_API_BASE}
+
   branding={{                     // optional — passed to the sign-in popup
     logoUrl: 'https://acme.com/logo.png',
     brandName: 'Acme',
     primaryColor: '#FF5733',
     showPoweredByHorus: false,    // requires the white-label tier
   }}
-  
+
   tokenStorage="localStorage"     // 'localStorage' | 'sessionStorage' | 'memory'
   autoRefresh={true}              // refresh tokens before expiry; default true
 >
@@ -120,18 +119,18 @@ const {
   ready,            // true once the provider has hydrated from storage
   authenticated,    // true if user is signed in
   user,             // { uid, email, displayName, ... } or undefined
-  
+
   // Headless flows — your form, your UI
   loginWithEmail,   // ({ email, password }) => Promise<User>
   signUpWithEmail,  // ({ email, password }) => Promise<User>
   sendEmailLink,    // ({ email, continueUrl }) => Promise<void>
   verifyEmailLink,  // ({ email, oobCode }) => Promise<User>
-  
+
   // Popup flows — Horus-hosted UI for OAuth providers
   loginWithGoogle,  // () => Promise<User>
   loginWithEmailLink, // popup variant of email-link
   loginWithPhone,   // ({ phone? }) => Promise<User>
-  
+
   logout,           // clears tokens
   refresh,          // manual token refresh
 } = useHorusAuth();
@@ -198,152 +197,6 @@ const { txHash } = await token({
 
 For total UI control, skip the component and call `useHorusAuth()` methods from your own form.
 
-## Backend setup (the proxy)
-
-A thin pass-through that forwards SDK calls to Horus, holding your secret key server-side. Roughly **50 lines**.
-
-### Express / Connect
-
-```ts
-// server/horus-proxy.ts
-import express from 'express';
-import { HorusClient } from '@horus-wallet/sdk';
-
-export function horusProxy() {
-  const router = express.Router();
-
-  // Per-request client — picks up the user's auth token from the SDK header.
-  const clientFor = (req: express.Request) =>
-    new HorusClient({
-      baseUrl: process.env.HORUS_BASE_URL!,
-      apiKey: process.env.HORUS_API_KEY!,           // hk_sk_*
-      getIdToken: async () => req.header('x-horus-id-token') ?? '',
-    });
-
-  // Auth — unauthenticated; mints tokens on success
-  router.post('/auth/email/signup', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.signUpWithEmail(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/auth/email/signin', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.signInWithEmail(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/auth/email-link/send', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.sendEmailLink(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/auth/email-link/verify', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.verifyEmailLink(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/auth/oauth', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.signInWithOAuth(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/auth/refresh', async (req, res, next) => {
-    try { res.json(await clientFor(req).auth.refresh(req.body.refreshToken)); }
-    catch (err) { next(err); }
-  });
-
-  // Wallet ops — authenticated; SDK forwards the user's token
-  router.get('/wallets', async (req, res, next) => {
-    try { res.json(await clientFor(req).wallets.get()); }
-    catch (err) { next(err); }
-  });
-  router.post('/sign-message', async (req, res, next) => {
-    try { res.json(await clientFor(req).wallets.signMessage(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/transfer/native', async (req, res, next) => {
-    try { res.json(await clientFor(req).transfers.native(req.body)); }
-    catch (err) { next(err); }
-  });
-  router.post('/transfer/token', async (req, res, next) => {
-    try { res.json(await clientFor(req).transfers.token(req.body)); }
-    catch (err) { next(err); }
-  });
-
-  return router;
-}
-```
-
-Mount it:
-
-```ts
-import express from 'express';
-import { horusProxy } from './horus-proxy';
-
-const app = express();
-app.use(express.json());
-app.use('/api/horus', horusProxy());
-app.listen(3001);
-```
-
-That's the whole backend integration.
-
-### Next.js (App Router)
-
-```tsx
-// app/providers.tsx
-'use client';
-import { HorusProvider } from '@horus-wallet/sdk-react';
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <HorusProvider appId={process.env.NEXT_PUBLIC_HORUS_APP_ID!}>
-      {children}
-    </HorusProvider>
-  );
-}
-
-// app/layout.tsx
-import { Providers } from './providers';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return <html><body><Providers>{children}</Providers></body></html>;
-}
-```
-
-```ts
-// app/api/horus/[...path]/route.ts
-import { HorusClient } from '@horus-wallet/sdk';
-
-const client = (req: Request) =>
-  new HorusClient({
-    baseUrl: process.env.HORUS_BASE_URL!,
-    apiKey: process.env.HORUS_API_KEY!,
-    getIdToken: async () => req.headers.get('x-horus-id-token') ?? '',
-  });
-
-const handlers: Record<string, (req: Request, body: any) => Promise<unknown>> = {
-  'auth/email/signin':      (req, body) => client(req).auth.signInWithEmail(body),
-  'auth/email/signup':      (req, body) => client(req).auth.signUpWithEmail(body),
-  'auth/email-link/send':   (req, body) => client(req).auth.sendEmailLink(body),
-  'auth/email-link/verify': (req, body) => client(req).auth.verifyEmailLink(body),
-  'auth/oauth':             (req, body) => client(req).auth.signInWithOAuth(body),
-  'auth/refresh':           (req, body) => client(req).auth.refresh(body.refreshToken),
-  'wallets':                (req)       => client(req).wallets.get(),
-  'sign-message':           (req, body) => client(req).wallets.signMessage(body),
-  'transfer/native':        (req, body) => client(req).transfers.native(body),
-  'transfer/token':         (req, body) => client(req).transfers.token(body),
-};
-
-async function dispatch(req: Request, ctx: { params: { path: string[] } }) {
-  const fn = handlers[ctx.params.path.join('/')];
-  if (!fn) return Response.json({ message: 'Not found' }, { status: 404 });
-  try {
-    const body = req.headers.get('content-type')?.includes('json') ? await req.json() : undefined;
-    return Response.json(await fn(req, body));
-  } catch (err: any) {
-    return Response.json({ message: err.message }, { status: err.status ?? 500 });
-  }
-}
-
-export const GET = dispatch;
-export const POST = dispatch;
-```
-
 ## Errors
 
 ```tsx
@@ -367,11 +220,15 @@ The hooks (`useWallets`, `useSignMessage`, `useTransfer`) also expose `error` as
 
 ## Security
 
-- The `hk_sk_*` secret stays on your backend — it never reaches the browser
+- The `app_*` identifier is **publishable** — safe to embed in your frontend bundle, source code, or environment variable. It is bounded by the `allowedOrigins` allow-list you register on the app record, so a leaked `app_*` cannot be used from a domain you don't control
 - Tokens persist in `localStorage` by default. For stricter privacy, use `sessionStorage` (cleared on tab close) or `memory` (RAM only) via the `tokenStorage` prop
 - The popup flows pin their `postMessage` target origin to the partner's window — tokens cannot be exfiltrated to other origins
 - White-label settings (hiding the Horus footer in the popup) are server-enforced — partners on the standard tier always see the footer regardless of client config
 
+## Server-side use
+
+This package is browser-only. For signing flows that need to run on your backend (cron jobs, server-rendered payment receipts, etc.), use the sibling [`@horus-wallet/sdk`](https://www.npmjs.com/package/@horus-wallet/sdk) package with a secret `hk_sk_*` key.
+
 ## Coming from Privy / Magic / Web3Auth?
 
 | Privy | Horus |
@@ -384,15 +241,117 @@ The hooks (`useWallets`, `useSignMessage`, `useTransfer`) also expose `error` as
 | Hosted modal | `<HorusLoginButton>` (popup) |
 | Backend SDK | `@horus-wallet/sdk` |
 
-Conceptual differences:
-- Horus uses a **partner-backend proxy** so your secret never leaves your server. Privy talks to its API directly from the browser.
-- **More chains supported** — EVM + Bitcoin + ICP + Casper + Aeternity all in one SDK.
+Conceptually identical to Privy's browser-direct model. Horus adds **more chains** out of the box — EVM + Bitcoin + ICP + Casper + Aeternity all in one SDK.
+
+## Inline auth modal — `<HorusAuthModal>`
+
+For partners who prefer an inline iframe over the popup flow:
+
+```tsx
+import { HorusAuthModal } from '@horus-wallet/sdk-react';
+
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Sign in</button>
+<HorusAuthModal
+  flow="google"
+  open={open}
+  onClose={() => setOpen(false)}
+  onSuccess={(user) => console.log('signed in:', user)}
+/>
+```
+
+Same security boundaries as `<HorusLoginButton>`: tokens flow via
+postMessage pinned to the iframe's origin; partner JS never sees the
+auth-page DOM.
+
+## Wallet export — `useExportWallet`
+
+Two-step flow that displays the user's private key in a Horus-hosted
+iframe so partner JS never touches the key material:
+
+```tsx
+import { useExportWallet, HorusRevealModal } from '@horus-wallet/sdk-react';
+
+function ExportButton() {
+  const { reveal, pending, error } = useExportWallet();
+  const [revealToken, setRevealToken] = useState<string | null>(null);
+
+  return (
+    <>
+      <button
+        disabled={pending}
+        onClick={async () => {
+          const password = prompt('Wallet password');
+          if (password === null) return;
+          const { revealToken } = await reveal({
+            network: 'EVM',
+            networkType: 'MAINNET',
+            password,
+          });
+          setRevealToken(revealToken);
+        }}
+      >
+        Export private key
+      </button>
+      <HorusRevealModal
+        revealToken={revealToken}
+        open={revealToken !== null}
+        onClose={() => setRevealToken(null)}
+        onComplete={(viewed) => console.log('user viewed key:', viewed)}
+      />
+    </>
+  );
+}
+```
+
+The reveal modal re-prompts for the password inside its own iframe
+(at `auth.horuswallet.com`). The private key is rendered there, behind
+a tap-to-reveal blur, and a "Done" button returns control without
+crossing the iframe → parent boundary with any key material.
+
+## External wallets (MetaMask / Coinbase Wallet / etc.)
+
+Opt-in sub-entrypoint — `import from '@horus-wallet/sdk-react/connect'`.
+Partners who only use embedded wallets don't pay the bundle cost.
+
+```tsx
+import {
+  useConnectWallet,
+  useExternalSignMessage,
+} from '@horus-wallet/sdk-react/connect';
+
+function ConnectButton() {
+  const { wallet, connect, available } = useConnectWallet();
+  const { signMessage } = useExternalSignMessage();
+
+  if (!available) return <p>Install MetaMask to continue.</p>;
+  if (!wallet) return <button onClick={connect}>Connect wallet</button>;
+  return (
+    <button onClick={async () => {
+      const sig = await signMessage(wallet, 'Sign in to Acme — nonce 1234');
+      console.log(sig);
+    }}>
+      Sign with {wallet.walletName}
+    </button>
+  );
+}
+```
+
+The external-wallet path NEVER calls Horus — keys stay in the user's
+extension. You can mix embedded + external in the same app (e.g.,
+"Sign in with Horus" alongside "Connect MetaMask").
+
+v1 supports any injected EIP-1193 provider (MetaMask, Coinbase Wallet,
+Rabby, Brave). WalletConnect is on the roadmap as a separate opt-in
+peer-dep.
 
 ## What's not yet here
 
-- External wallet connect (MetaMask / WalletConnect) — coming
+- WalletConnect (separate peer-dep, opt-in)
 - Mobile SDKs (iOS / Android / React Native) — coming
-- Drop-in `<HorusAuthModal>` (inline UI without popup) — coming
-- Pre-generated wallets for unsigned-in users — coming
+- Mnemonic export (current export is private key; mnemonic requires a
+  forward-only schema change)
+- Account linking + MFA (identity-model rework, planned)
 
 For partner integration questions: `info@horuswallet.com`.

package/dist/connect.cjs

@@ -0,0 +1,218 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/connect/index.ts
+var connect_exports = {};
+__export(connect_exports, {
+  useConnectWallet: () => useConnectWallet,
+  useExternalSendTransaction: () => useExternalSendTransaction,
+  useExternalSignMessage: () => useExternalSignMessage,
+  useExternalSignTypedData: () => useExternalSignTypedData
+});
+module.exports = __toCommonJS(connect_exports);
+
+// src/connect/useConnectWallet.ts
+var import_react = require("react");
+function detectProvider() {
+  if (typeof window === "undefined") return null;
+  const provider = window.ethereum;
+  return provider ?? null;
+}
+function nameFor(provider) {
+  if (provider.isMetaMask) return "MetaMask";
+  if (provider.isCoinbaseWallet) return "Coinbase Wallet";
+  if (provider.isRabby) return "Rabby";
+  if (provider.isBraveWallet) return "Brave Wallet";
+  return "Injected Wallet";
+}
+function useConnectWallet() {
+  const [wallet, setWallet] = (0, import_react.useState)(null);
+  const [pending, setPending] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(void 0);
+  const [available, setAvailable] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    setAvailable(detectProvider() !== null);
+  }, []);
+  (0, import_react.useEffect)(() => {
+    const provider = detectProvider();
+    if (!provider || !provider.on) return;
+    const onAccountsChanged = (accounts) => {
+      if (!accounts || accounts.length === 0) {
+        setWallet(null);
+        return;
+      }
+      setWallet((prev) => prev ? { ...prev, address: accounts[0] } : prev);
+    };
+    const onChainChanged = (chainIdHex) => {
+      const chainId = Number(chainIdHex);
+      if (!Number.isFinite(chainId)) return;
+      setWallet((prev) => prev ? { ...prev, chainId } : prev);
+    };
+    provider.on("accountsChanged", onAccountsChanged);
+    provider.on("chainChanged", onChainChanged);
+    return () => {
+      provider.removeListener?.("accountsChanged", onAccountsChanged);
+      provider.removeListener?.("chainChanged", onChainChanged);
+    };
+  }, []);
+  const connect = (0, import_react.useCallback)(async () => {
+    const provider = detectProvider();
+    if (!provider) {
+      const err = new Error(
+        "No injected wallet provider detected. Install MetaMask (or similar) and reload."
+      );
+      setError(err);
+      throw err;
+    }
+    setPending(true);
+    setError(void 0);
+    try {
+      const accounts = await provider.request({
+        method: "eth_requestAccounts"
+      });
+      if (!accounts || accounts.length === 0) {
+        throw new Error("No accounts returned from wallet.");
+      }
+      const chainIdHex = await provider.request({
+        method: "eth_chainId"
+      });
+      const chainId = Number(chainIdHex);
+      const next = {
+        address: accounts[0],
+        chainId: Number.isFinite(chainId) ? chainId : 0,
+        walletName: nameFor(provider),
+        provider
+      };
+      setWallet(next);
+      return next;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      setError(e);
+      throw e;
+    } finally {
+      setPending(false);
+    }
+  }, []);
+  const disconnect = (0, import_react.useCallback)(() => {
+    setWallet(null);
+  }, []);
+  return { wallet, pending, error, available, connect, disconnect };
+}
+
+// src/connect/useExternalSign.ts
+var import_react2 = require("react");
+function useExternalSignMessage() {
+  const [pending, setPending] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(void 0);
+  const signMessage = (0, import_react2.useCallback)(
+    async (wallet, message) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        const sig = await wallet.provider.request({
+          method: "personal_sign",
+          params: [message, wallet.address]
+        });
+        return sig;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { signMessage, pending, error };
+}
+function useExternalSignTypedData() {
+  const [pending, setPending] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(void 0);
+  const signTypedData = (0, import_react2.useCallback)(
+    async (wallet, typedData) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        const sig = await wallet.provider.request({
+          method: "eth_signTypedData_v4",
+          params: [wallet.address, JSON.stringify(typedData)]
+        });
+        return sig;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { signTypedData, pending, error };
+}
+function useExternalSendTransaction() {
+  const [pending, setPending] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(void 0);
+  const sendTransaction = (0, import_react2.useCallback)(
+    async (wallet, tx) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        if (tx.chainId && tx.chainId !== wallet.chainId) {
+          await wallet.provider.request({
+            method: "wallet_switchEthereumChain",
+            params: [{ chainId: `0x${tx.chainId.toString(16)}` }]
+          });
+        }
+        const params = {
+          from: wallet.address,
+          to: tx.to
+        };
+        if (tx.value !== void 0) params.value = toHex(tx.value);
+        if (tx.data !== void 0) params.data = tx.data;
+        if (tx.gas !== void 0) params.gas = toHex(tx.gas);
+        const hash = await wallet.provider.request({
+          method: "eth_sendTransaction",
+          params: [params]
+        });
+        return { hash };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { sendTransaction, pending, error };
+}
+function toHex(v) {
+  if (v.startsWith("0x")) return v;
+  return `0x${BigInt(v).toString(16)}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useConnectWallet,
+  useExternalSendTransaction,
+  useExternalSignMessage,
+  useExternalSignTypedData
+});