@bufinance/web3-signin 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @bufinance/web3-signin
+
+Headless, cross-app **Web3 wallet sign-in** for BUFI. One source of truth, consumed by both **desk-v1** and **defi-web-app** so the login surface stays DRY.
+
+It wraps three things:
+
+1. **EIP-6963 wallet discovery** — lists the browser wallets the user actually has (MetaMask, Coinbase Wallet, Brave, …). Each wallet ships its own name + icon; nothing is hardcoded.
+2. **Supabase Web3 auth** — `signInWithWeb3` (EIP-4361 "Sign in with Ethereum"). Supabase builds the SIWE message, the wallet signs, GoTrue verifies server-side and mints the session. No custom SIWE backend.
+3. **Turnstile CAPTCHA** (wallet logins only) — renders the Cloudflare Turnstile widget and hands the token to `signInWithWeb3` as `captchaToken`. **No siteverify Worker** — Supabase verifies the token with the secret set in its dashboard.
+
+## Install (GitHub Packages)
+
+```
+# .npmrc
+@bufinance:registry=https://npm.pkg.github.com
+
+bun add @bufinance/web3-signin
+```
+
+The package ships TypeScript source; consuming Next.js apps add it to `transpilePackages`.
+
+## Headless core
+
+```ts
+import { subscribeWallets, getWallets, signInWithWallet } from "@bufinance/web3-signin";
+```
+
+## React
+
+```tsx
+import { useWeb3SignIn, Turnstile } from "@bufinance/web3-signin/react";
+
+function WalletButtons({ supabase }) {
+  const [token, setToken] = useState<string>();
+  const { wallets, signIn, status, error, pendingRdns } = useWeb3SignIn({
+    supabase,
+    statement: "I accept the BUFI Terms of Service at https://bu.finance/terms",
+    onSignedIn: () => location.assign("/"),
+  });
+
+  return (
+    <>
+      <Turnstile sitekey={process.env.NEXT_PUBLIC_TURNSTILE_SITEKEY!} onToken={setToken} />
+      {wallets.map((w) => (
+        <button key={w.info.rdns} disabled={!token || pendingRdns === w.info.rdns}
+                onClick={() => signIn(w, token)}>
+          <img src={w.info.icon} width={20} height={20} alt="" /> {w.info.name}
+        </button>
+      ))}
+      {error && <p>{error}</p>}
+    </>
+  );
+}
+```
+
+## One-time project setup
+
+- Supabase dashboard → **Authentication → Providers → Web3 Wallet** → enable Ethereum.
+- Supabase dashboard → **Auth → Bot & Abuse Protection** → enable CAPTCHA → Turnstile → paste the **Secret key**.
+- Cloudflare → create a **Turnstile widget** for `bu.finance` (+ `localhost`); put the **Sitekey** in `NEXT_PUBLIC_TURNSTILE_SITEKEY` and the **Secret** in Supabase (above).
+- Both apps must point at the **same** Supabase project (`cmrpdkvogpxyneidmtnu` in prod).
+
+## Releasing
+
+This repo is the home. Bump `version`, commit, tag, and publish to GitHub Packages (`npm publish`). Both apps pick it up via their lockfile.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bufinance/web3-signin",
+  "version": "0.1.0",
+  "description": "Headless cross-app Web3 wallet sign-in for BUFI: EIP-6963 wallet discovery + Supabase signInWithWeb3 (EIP-4361) + Turnstile captcha. Shared by desk-v1 and defi-web-app. Source of truth lives here; both apps consume it.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react/index.ts"
+  },
+  "files": ["src"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": ">=2.62.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.108.2",
+    "@types/react": "^18",
+    "bun-types": "^1.1",
+    "react": "^18",
+    "typescript": "^5",
+    "viem": "2.45.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BuFi007/bufi-sign-in-web.git"
+  },
+  "license": "UNLICENSED"
+}

package/src/eip6963.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { __test, getWallets, getWalletByRdns } from "./eip6963";
+import { walletSortKey } from "./registry";
+import type { DiscoveredWallet, Eip1193Provider } from "./types";
+
+/** A tagged provider so tests can assert which instance won a de-dupe race. */
+type TaggedProvider = Eip1193Provider & { _tag: string };
+
+function fakeWallet(rdns: string, name: string, providerTag = "p"): DiscoveredWallet {
+  const provider: TaggedProvider = { request: async () => null, _tag: providerTag };
+  return {
+    info: { uuid: `${rdns}-${providerTag}`, name, icon: "data:image/svg+xml,x", rdns },
+    provider,
+  };
+}
+
+afterEach(() => __test.reset());
+
+describe("eip6963 discovery store", () => {
+  test("accumulates announced wallets", () => {
+    __test.announce(fakeWallet("io.metamask", "MetaMask"));
+    __test.announce(fakeWallet("com.coinbase.wallet", "Coinbase Wallet"));
+    expect(__test.count()).toBe(2);
+    expect(getWalletByRdns("io.metamask")?.info.name).toBe("MetaMask");
+  });
+
+  test("de-dupes by rdns; identical re-announce is a no-op", () => {
+    const w = fakeWallet("io.metamask", "MetaMask", "same");
+    __test.announce(w);
+    __test.announce(w); // same provider ref → ignored
+    expect(__test.count()).toBe(1);
+  });
+
+  test("newer provider for same rdns replaces (extension reload)", () => {
+    __test.announce(fakeWallet("io.metamask", "MetaMask", "old"));
+    __test.announce(fakeWallet("io.metamask", "MetaMask", "new"));
+    expect(__test.count()).toBe(1);
+    const provider = getWalletByRdns("io.metamask")?.provider as TaggedProvider | undefined;
+    expect(provider?._tag).toBe("new");
+  });
+
+  test("getWallets returns name-sorted list", () => {
+    __test.announce(fakeWallet("com.brave.wallet", "Brave"));
+    __test.announce(fakeWallet("io.metamask", "MetaMask"));
+    expect(getWallets().map((w) => w.info.name)).toEqual(["Brave", "MetaMask"]);
+  });
+
+  test("ignores announces with empty rdns", () => {
+    __test.announce({
+      info: { uuid: "", name: "X", icon: "", rdns: "" },
+      provider: { request: async () => null },
+    });
+    expect(__test.count()).toBe(0);
+  });
+});
+
+describe("walletSortKey — preferred wallets float to top", () => {
+  test("metamask before an unknown wallet", () => {
+    const mm = walletSortKey("io.metamask", "MetaMask");
+    const other = walletSortKey("xyz.unknown", "Zzz");
+    expect(mm[0]).toBeLessThan(other[0]);
+  });
+  test("coinbase before brave (preferred order)", () => {
+    expect(walletSortKey("com.coinbase.wallet", "Coinbase")[0]).toBeLessThan(
+      walletSortKey("com.brave.wallet", "Brave")[0],
+    );
+  });
+});

package/src/eip6963.ts

@@ -0,0 +1,78 @@
+/**
+ * EIP-6963 multi-injected-provider discovery — the standard way to list the
+ * browser wallets a user actually has (MetaMask, Coinbase Wallet, Brave, …)
+ * WITHOUT hardcoding any of them. Each wallet ships its own name + icon in the
+ * announce event, so the UI renders whatever is installed.
+ *
+ * Framework-agnostic store: call `subscribeWallets` (returns an unsubscribe) or
+ * read `getWallets()`. The React hook in ./react wraps this with useSyncExternalStore.
+ *
+ * Why a module-level store: EIP-6963 is request/announce. We dispatch
+ * `eip6963:requestProvider` once and accumulate `eip6963:announceProvider`
+ * events; wallets injected later (extension wakes up) announce again and we
+ * de-dupe by `rdns` (newest provider wins — handles extension reloads).
+ */
+import type { DiscoveredWallet, Eip6963AnnounceDetail } from "./types";
+
+const byRdns = new Map<string, DiscoveredWallet>();
+const listeners = new Set<() => void>();
+let started = false;
+
+function emit(): void {
+  for (const l of listeners) l();
+}
+
+function onAnnounce(event: Event): void {
+  const { detail } = event as CustomEvent<Eip6963AnnounceDetail>;
+  if (!detail?.info?.rdns || !detail.provider) return;
+  const prev = byRdns.get(detail.info.rdns);
+  // Replace if new (extension reload) or first sight; skip identical re-announce.
+  if (prev && prev.provider === detail.provider) return;
+  byRdns.set(detail.info.rdns, detail);
+  emit();
+}
+
+/** Begin listening + ask installed wallets to announce. Idempotent + SSR-safe. */
+export function startDiscovery(): void {
+  if (started || typeof window === "undefined") return;
+  started = true;
+  window.addEventListener("eip6963:announceProvider", onAnnounce as EventListener);
+  window.dispatchEvent(new Event("eip6963:requestProvider"));
+}
+
+/** Current discovered wallets, sorted by name (stable for rendering). */
+export function getWallets(): DiscoveredWallet[] {
+  return [...byRdns.values()].sort((a, b) => a.info.name.localeCompare(b.info.name));
+}
+
+/** Subscribe to discovery changes. Auto-starts discovery. Returns unsubscribe. */
+export function subscribeWallets(cb: () => void): () => void {
+  startDiscovery();
+  listeners.add(cb);
+  // Re-request: a wallet that already announced before we subscribed will
+  // re-announce on request, so late subscribers still get the full set.
+  if (typeof window !== "undefined") window.dispatchEvent(new Event("eip6963:requestProvider"));
+  return () => {
+    listeners.delete(cb);
+  };
+}
+
+/** Look up a discovered wallet by reverse-DNS id (e.g. "io.metamask"). */
+export function getWalletByRdns(rdns: string): DiscoveredWallet | undefined {
+  return byRdns.get(rdns);
+}
+
+/** Test-only: inject an announce event + reset. Not exported from the package root. */
+export const __test = {
+  reset(): void {
+    byRdns.clear();
+    listeners.clear();
+    started = false;
+  },
+  announce(detail: DiscoveredWallet): void {
+    onAnnounce(new CustomEvent("eip6963:announceProvider", { detail }));
+  },
+  count(): number {
+    return byRdns.size;
+  },
+};

package/src/index.ts

@@ -0,0 +1,32 @@
+// Headless core — framework-agnostic. React bindings live in "@bufi/web3-signin/react".
+export type {
+  Address,
+  BrandWallet,
+  BufiBrandWalletId,
+  DiscoveredWallet,
+  Eip1193EventMap,
+  Eip1193Provider,
+  Eip1193RequestArgs,
+  Eip6963ProviderInfo,
+  JsonValue,
+  ProviderRpcError,
+  TokenBalance,
+  WalletAccount,
+  WalletScope,
+} from "./types";
+export {
+  getWallets,
+  getWalletByRdns,
+  startDiscovery,
+  subscribeWallets,
+} from "./eip6963";
+export {
+  signInWithWallet,
+  type WalletSignInArgs,
+  type WalletSignInResult,
+} from "./sign-in";
+export {
+  BRAND_WALLETS,
+  PREFERRED_RDNS_ORDER,
+  walletSortKey,
+} from "./registry";

package/src/react/index.ts

@@ -0,0 +1,13 @@
+export { useInjectedWallets } from "./use-injected-wallets";
+export {
+  useWeb3SignIn,
+  type UseWeb3SignIn,
+  type UseWeb3SignInArgs,
+  type Web3SignInStatus,
+} from "./use-web3-signin";
+export { Turnstile, resetTurnstile, type TurnstileProps } from "./turnstile";
+export {
+  WalletDropdown,
+  type WalletDropdownProps,
+  type WalletDropdownClassNames,
+} from "./wallet-dropdown";

package/src/react/turnstile.tsx

@@ -0,0 +1,114 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Cloudflare Turnstile widget for the wallet-login CAPTCHA.
+ *
+ * IMPORTANT: for Supabase auth there is NO siteverify Worker. Supabase's GoTrue
+ * verifies this token server-side using the secret set in the Supabase
+ * dashboard. This component only renders the widget and hands the resulting
+ * token up via `onToken`, which the caller passes as `captchaToken` to
+ * `signInWithWeb3`. Reset it after each auth attempt (tokens are single-use).
+ */
+declare global {
+  interface Window {
+    turnstile?: {
+      render: (el: HTMLElement, opts: TurnstileRenderOpts) => string;
+      reset: (id?: string) => void;
+      remove: (id?: string) => void;
+    };
+  }
+}
+
+interface TurnstileRenderOpts {
+  sitekey: string;
+  callback: (token: string) => void;
+  "error-callback"?: () => void;
+  "expired-callback"?: () => void;
+  action?: string;
+  theme?: "auto" | "light" | "dark";
+  size?: "normal" | "flexible" | "compact";
+  appearance?: "always" | "execute" | "interaction-only";
+}
+
+const SCRIPT_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+let scriptPromise: Promise<void> | null = null;
+
+function loadScript(): Promise<void> {
+  if (typeof window === "undefined") return Promise.resolve();
+  if (window.turnstile) return Promise.resolve();
+  if (scriptPromise) return scriptPromise;
+  scriptPromise = new Promise<void>((resolve, reject) => {
+    const s = document.createElement("script");
+    s.src = SCRIPT_SRC;
+    s.async = true;
+    s.defer = true;
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error("turnstile script failed to load"));
+    document.head.appendChild(s);
+  });
+  return scriptPromise;
+}
+
+export interface TurnstileProps {
+  sitekey: string;
+  onToken: (token: string) => void;
+  onExpire?: () => void;
+  onError?: () => void;
+  theme?: "auto" | "light" | "dark";
+  appearance?: "always" | "execute" | "interaction-only";
+  className?: string;
+}
+
+export function Turnstile({
+  sitekey,
+  onToken,
+  onExpire,
+  onError,
+  theme = "auto",
+  appearance = "interaction-only",
+  className,
+}: TurnstileProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const widgetId = useRef<string | null>(null);
+  // Keep latest callbacks without re-rendering the widget.
+  const cb = useRef({ onToken, onExpire, onError });
+  cb.current = { onToken, onExpire, onError };
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!sitekey) return;
+    loadScript()
+      .then(() => {
+        if (cancelled || !ref.current || !window.turnstile) return;
+        widgetId.current = window.turnstile.render(ref.current, {
+          sitekey,
+          action: "bufi-wallet-login",
+          theme,
+          appearance,
+          callback: (t) => cb.current.onToken(t),
+          "expired-callback": () => cb.current.onExpire?.(),
+          "error-callback": () => cb.current.onError?.(),
+        });
+      })
+      .catch(() => cb.current.onError?.());
+    return () => {
+      cancelled = true;
+      if (widgetId.current && window.turnstile) {
+        try {
+          window.turnstile.remove(widgetId.current);
+        } catch {
+          /* widget already gone */
+        }
+        widgetId.current = null;
+      }
+    };
+  }, [sitekey, theme, appearance]);
+
+  return <div ref={ref} className={className} />;
+}
+
+/** Imperatively reset the rendered widget (tokens are single-use; reset after
+ *  each auth attempt). Pass the same sitekey instance's container. */
+export function resetTurnstile(): void {
+  if (typeof window !== "undefined") window.turnstile?.reset();
+}

package/src/react/use-injected-wallets.ts

@@ -0,0 +1,39 @@
+import { useSyncExternalStore } from "react";
+import { getWallets, subscribeWallets } from "../eip6963";
+import { walletSortKey } from "../registry";
+import type { DiscoveredWallet } from "../types";
+
+const EMPTY: DiscoveredWallet[] = [];
+let cache: DiscoveredWallet[] = EMPTY;
+let cacheKey = "";
+
+/** Stable snapshot: useSyncExternalStore needs referential stability between
+ *  renders when nothing changed, or React loops. We memo on a cheap key. */
+function snapshot(): DiscoveredWallet[] {
+  const wallets = getWallets();
+  const key = wallets.map((w) => w.info.rdns).join("|");
+  if (key !== cacheKey) {
+    cacheKey = key;
+    cache = wallets
+      .slice()
+      .sort((a, b) => {
+        const [ai, an] = walletSortKey(a.info.rdns, a.info.name);
+        const [bi, bn] = walletSortKey(b.info.rdns, b.info.name);
+        return ai - bi || an.localeCompare(bn);
+      });
+  }
+  return cache;
+}
+
+/**
+ * Live list of EIP-6963-discovered browser wallets (MetaMask, Coinbase, Brave,
+ * …), preferred-ordered. Each carries `.info.name`, `.info.icon` (the wallet's
+ * own icon), `.info.rdns`, and `.provider`. SSR-safe (empty on the server).
+ */
+export function useInjectedWallets(): DiscoveredWallet[] {
+  return useSyncExternalStore(
+    subscribeWallets,
+    snapshot,
+    () => EMPTY,
+  );
+}

package/src/react/use-web3-signin.ts

@@ -0,0 +1,67 @@
+import { useCallback, useState } from "react";
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { signInWithWallet, type WalletSignInResult } from "../sign-in";
+import type { DiscoveredWallet } from "../types";
+import { useInjectedWallets } from "./use-injected-wallets";
+
+export type Web3SignInStatus = "idle" | "signing" | "success" | "error";
+
+export interface UseWeb3SignInArgs {
+  supabase: SupabaseClient | null;
+  /** SIWE consent statement shown in the wallet prompt. */
+  statement: string;
+  /** Called once a session is established. */
+  onSignedIn?: (result: WalletSignInResult) => void;
+}
+
+export interface UseWeb3SignIn {
+  /** EIP-6963-discovered wallets (preferred-ordered). */
+  wallets: DiscoveredWallet[];
+  status: Web3SignInStatus;
+  error: string | null;
+  /** The rdns currently mid-sign, for per-button spinners. */
+  pendingRdns: string | null;
+  /** Trigger sign-in for a discovered wallet. `captchaToken` is required when
+   *  the project enforces CAPTCHA on Web3 sign-in (wallet logins do). */
+  signIn: (wallet: DiscoveredWallet, captchaToken?: string) => Promise<WalletSignInResult>;
+}
+
+/**
+ * One hook for the whole wallet-login surface: the discovered wallet list +
+ * a `signIn` that runs Supabase Web3 auth and tracks status. UI is the app's;
+ * this owns the logic so desk + defi-web stay DRY.
+ */
+export function useWeb3SignIn(args: UseWeb3SignInArgs): UseWeb3SignIn {
+  const { supabase, statement, onSignedIn } = args;
+  const wallets = useInjectedWallets();
+  const [status, setStatus] = useState<Web3SignInStatus>("idle");
+  const [error, setError] = useState<string | null>(null);
+  const [pendingRdns, setPendingRdns] = useState<string | null>(null);
+
+  const signIn = useCallback(
+    async (wallet: DiscoveredWallet, captchaToken?: string): Promise<WalletSignInResult> => {
+      if (!supabase) {
+        const r = { ok: false, error: "auth not configured" };
+        setStatus("error");
+        setError(r.error);
+        return r;
+      }
+      setStatus("signing");
+      setError(null);
+      setPendingRdns(wallet.info.rdns);
+      const result = await signInWithWallet({ supabase, wallet, statement, captchaToken });
+      setPendingRdns(null);
+      if (result.ok) {
+        setStatus("success");
+        onSignedIn?.(result);
+      } else {
+        setStatus("error");
+        setError(result.error ?? "sign-in failed");
+      }
+      return result;
+    },
+    [supabase, statement, onSignedIn],
+  );
+
+  return { wallets, status, error, pendingRdns, signIn };
+}

package/src/react/wallet-dropdown.tsx

@@ -0,0 +1,145 @@
+import { type ReactNode, useMemo, useState } from "react";
+import type { TokenBalance, WalletAccount, WalletScope } from "../types";
+
+/**
+ * Unified Stablecoin FX wallet pill + dropdown — one instance shared by
+ * defi-web (scope="personal") and desk (scope="all": Operations/Treasury/
+ * Personal). Presentational + auth-gated: when `authed` is false it renders
+ * NOTHING (no pill, no balances, no tabs). Balances are app-supplied (fx reads
+ * via wagmi, desk via its wallet context) and passed in as `accounts`, so this
+ * stays DRY and free of data-fetching.
+ *
+ * Theming is per-app via `classNames` (both apps' design tokens differ); the
+ * defaults are minimal and responsive.
+ */
+export interface WalletDropdownClassNames {
+  root?: string;
+  pill?: string;
+  panel?: string;
+  tabRow?: string;
+  tab?: string;
+  tabActive?: string;
+  accountRow?: string;
+  balanceRow?: string;
+}
+
+export interface WalletDropdownProps {
+  /** Auth gate. False → component renders nothing. */
+  authed: boolean;
+  /** App-supplied accounts (with their balances). */
+  accounts: WalletAccount[];
+  /** "personal" (defi-web) | "team" | "all" (desk shows every scope). */
+  scope?: WalletScope | "all";
+  /** Currency formatter for the USD total; defaults to en-US $. */
+  formatUsd?: (n: number) => string;
+  /** Extra content inside the open panel — desk injects gateway/hinkal/multisig. */
+  children?: ReactNode;
+  /** Shown when authed but no accounts yet (provisioning). */
+  emptyState?: ReactNode;
+  onSelectAccount?: (account: WalletAccount) => void;
+  classNames?: WalletDropdownClassNames;
+}
+
+const defaultFormatUsd = (n: number): string =>
+  `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+
+function totalUsd(balances: TokenBalance[]): number {
+  return balances.reduce((sum, b) => sum + (Number.isFinite(b.usd) ? b.usd : 0), 0);
+}
+
+export function WalletDropdown(props: WalletDropdownProps): ReactNode {
+  const {
+    authed,
+    accounts,
+    scope = "all",
+    formatUsd = defaultFormatUsd,
+    children,
+    emptyState,
+    onSelectAccount,
+    classNames = {},
+  } = props;
+
+  const visible = useMemo(
+    () => (scope === "all" ? accounts : accounts.filter((a) => a.scope === scope)),
+    [accounts, scope],
+  );
+
+  const [open, setOpen] = useState(false);
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  // Auth gate — the whole surface is hidden until sign-in passes.
+  if (!authed) return null;
+
+  const active = visible.find((a) => a.id === activeId) ?? visible[0];
+  const pillTotal = active ? totalUsd(active.balances) : 0;
+
+  return (
+    <div className={classNames.root} data-bufi-wallet>
+      <button
+        type="button"
+        aria-label="Open Stablecoin FX Wallet"
+        aria-expanded={open}
+        className={classNames.pill ?? "acct-mini"}
+        onClick={() => setOpen((v) => !v)}
+      >
+        {formatUsd(pillTotal)}
+      </button>
+
+      {open && (
+        <div role="menu" className={classNames.panel} data-bufi-wallet-panel>
+          {visible.length === 0
+            ? (emptyState ?? null)
+            : (
+              <>
+                {scope !== "personal" && visible.length > 1 && (
+                  <div className={classNames.tabRow} role="tablist">
+                    {visible.map((a) => {
+                      const isActive = a.id === active?.id;
+                      return (
+                        <button
+                          key={a.id}
+                          type="button"
+                          role="tab"
+                          aria-selected={isActive}
+                          className={`${classNames.tab ?? ""} ${isActive ? (classNames.tabActive ?? "") : ""}`.trim()}
+                          onClick={() => {
+                            setActiveId(a.id);
+                            onSelectAccount?.(a);
+                          }}
+                        >
+                          {a.label}
+                        </button>
+                      );
+                    })}
+                  </div>
+                )}
+
+                {active && (
+                  <div className={classNames.accountRow}>
+                    {active.balances.length === 0
+                      ? (emptyState ?? null)
+                      : active.balances
+                          .slice()
+                          .sort((x, y) => y.usd - x.usd)
+                          .map((b) => (
+                            <div
+                              key={`${b.chainId}:${b.symbol}`}
+                              className={classNames.balanceRow}
+                              data-bufi-balance
+                            >
+                              <span>{b.symbol}</span>
+                              <span>{b.amount}</span>
+                              <span>{b.chainName}</span>
+                            </div>
+                          ))}
+                  </div>
+                )}
+
+                {children}
+              </>
+            )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/registry.ts

@@ -0,0 +1,32 @@
+/**
+ * Wallet ordering + BUFI-brand entries.
+ *
+ * Injected wallets (MetaMask, Coinbase, Brave, …) come from EIP-6963 with their
+ * own icons — never hardcoded. This module only adds the two BUFI-brand options
+ * that aren't browser extensions (the embedded Circle UCW and ghost-mode), and
+ * a preferred display order so the common wallets float to the top.
+ */
+import type { BrandWallet } from "./types";
+
+/** Preferred top-of-list order by reverse-DNS id; everything else follows A-Z. */
+export const PREFERRED_RDNS_ORDER: readonly string[] = [
+  "io.metamask",
+  "com.coinbase.wallet",
+  "com.brave.wallet",
+  "app.phantom",
+  "com.okex.wallet",
+];
+
+/** Stable sort key: preferred wallets first (in PREFERRED order), then by name. */
+export function walletSortKey(rdns: string, name: string): [number, string] {
+  const i = PREFERRED_RDNS_ORDER.indexOf(rdns);
+  return [i === -1 ? PREFERRED_RDNS_ORDER.length : i, name.toLowerCase()];
+}
+
+/** The BUFI-brand non-injected options. Icons are supplied by the host app
+ *  (rabbit = embedded UCW, ghost = ghost-mode private routing) since they're
+ *  app-owned brand assets, not EIP-6963 data URIs. */
+export const BRAND_WALLETS: readonly BrandWallet[] = [
+  { id: "bufi-embedded", name: "BUFI Wallet", rdns: "finance.bu.embedded" },
+  { id: "bufi-ghost", name: "Ghost Mode", rdns: "finance.bu.ghost" },
+];

package/src/sign-in.ts

@@ -0,0 +1,82 @@
+/**
+ * Supabase Web3 wallet sign-in (EIP-4361 "Sign in with Ethereum").
+ *
+ * Supabase does the whole protocol natively: given a discovered wallet's
+ * provider, `signInWithWeb3` builds the SIWE message, asks the wallet to sign,
+ * and verifies the signature server-side (10-minute timestamp window) before
+ * minting the session. We do NOT build or verify SIWE ourselves, and we do NOT
+ * run a siteverify Worker for the captcha — GoTrue verifies the Turnstile token
+ * using the secret configured in the Supabase dashboard.
+ *
+ * Requirements (one-time, project side):
+ *   - Supabase dashboard → Auth providers → enable Web3 Wallet (Ethereum)
+ *   - Auth → Bot & Abuse Protection → enable CAPTCHA (Turnstile) + secret
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { DiscoveredWallet } from "./types";
+
+/** The exact credentials type Supabase's signInWithWeb3 accepts (derived from
+ *  the installed client — stays correct across supabase-js upgrades). */
+type Web3Credentials = Parameters<SupabaseClient["auth"]["signInWithWeb3"]>[0];
+
+export interface WalletSignInArgs {
+  supabase: SupabaseClient;
+  /** A wallet from EIP-6963 discovery. Omit to use the default window provider. */
+  wallet?: DiscoveredWallet;
+  /** Consent line shown in the SIWE message (e.g. "I accept the BUFI Terms…").
+   *  Must not contain newlines (SIWE statement rule). */
+  statement: string;
+  /** Cloudflare Turnstile token. Required when the project enforces CAPTCHA on
+   *  Web3 sign-in (we do, for wallet logins). */
+  captchaToken?: string;
+}
+
+export interface WalletSignInResult {
+  ok: boolean;
+  /** Supabase session user id (auth.users.id) on success. */
+  userId?: string;
+  /** The address that signed, lowercased. */
+  address?: string;
+  error?: string;
+}
+
+/**
+ * Sign in with a browser wallet via Supabase Web3 auth. One call: prompts the
+ * wallet to sign the SIWE message and returns the established session.
+ */
+export async function signInWithWallet(args: WalletSignInArgs): Promise<WalletSignInResult> {
+  const { supabase, wallet, statement, captchaToken } = args;
+  try {
+    // Built to match EthereumWeb3Credentials. The lone cast bridges Supabase's
+    // EthereumWallet type, which (as published) requires an `address` field that
+    // no real EIP-6963 / window.ethereum provider exposes — so the provider is
+    // adapted here, at the single library boundary, with no `unknown`/`any`.
+    const credentials = {
+      chain: "ethereum",
+      statement,
+      ...(wallet ? { wallet: wallet.provider } : {}),
+      ...(captchaToken ? { options: { captchaToken } } : {}),
+    } as Web3Credentials;
+
+    const { data, error } = await supabase.auth.signInWithWeb3(credentials);
+    if (error) return { ok: false, error: error.message };
+
+    const user = data.user;
+    const meta = user.user_metadata as Record<string, JsonLike> | undefined;
+    const rawAddress =
+      pickString(meta?.address) ?? pickString(meta?.wallet_address) ?? pickString(meta?.custom_claims);
+    return {
+      ok: true,
+      userId: user.id,
+      address: rawAddress ? rawAddress.toLowerCase() : undefined,
+    };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** user_metadata is loosely shaped by Supabase; read fields defensively without `any`. */
+type JsonLike = string | number | boolean | null | JsonLike[] | { [k: string]: JsonLike };
+function pickString(v: JsonLike | undefined): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Strict types — no `any`, no naked `unknown` in the public surface. Arbitrary
+ * JSON-RPC payloads are modeled as `JsonValue` (the honest type for "any JSON"),
+ * not `unknown`.
+ */
+
+/** Any JSON-serializable value — the precise type for EIP-1193 params/results. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** EIP-1193 request envelope. */
+export interface Eip1193RequestArgs {
+  readonly method: string;
+  readonly params?: readonly JsonValue[] | Record<string, JsonValue>;
+}
+
+/** EIP-1193 provider error (EIP-1193 §5). */
+export interface ProviderRpcError extends Error {
+  code: number;
+  data?: JsonValue;
+}
+
+/** Typed EIP-1193 event map (the events wallets actually emit). */
+export interface Eip1193EventMap {
+  accountsChanged: [accounts: string[]];
+  chainChanged: [chainId: string];
+  connect: [connectInfo: { chainId: string }];
+  disconnect: [error: ProviderRpcError];
+}
+
+/**
+ * Minimal, fully-typed EIP-1193 provider. The discovery store treats this
+ * opaquely (stores + compares by reference); only the Supabase sign-in bridge
+ * invokes `request`, and it does so through Supabase's own typed call.
+ */
+export interface Eip1193Provider {
+  request(args: Eip1193RequestArgs): Promise<JsonValue>;
+  on?<E extends keyof Eip1193EventMap>(event: E, listener: (...args: Eip1193EventMap[E]) => void): void;
+  removeListener?<E extends keyof Eip1193EventMap>(
+    event: E,
+    listener: (...args: Eip1193EventMap[E]) => void,
+  ): void;
+}
+
+/** EIP-6963 provider info, as announced by the wallet. */
+export interface Eip6963ProviderInfo {
+  /** Globally-unique per page load. */
+  uuid: string;
+  /** Human name, e.g. "MetaMask". */
+  name: string;
+  /** data: URI — the wallet ships its own icon; we never hardcode these. */
+  icon: string;
+  /** Reverse-DNS id, e.g. "io.metamask" — stable, used for de-dupe + ordering. */
+  rdns: string;
+}
+
+/** A discovered injected wallet: its announced info + the live provider. */
+export interface DiscoveredWallet {
+  info: Eip6963ProviderInfo;
+  provider: Eip1193Provider;
+}
+
+/** EIP-6963 announce event detail. */
+export type Eip6963AnnounceDetail = DiscoveredWallet;
+
+/**
+ * BUFI-brand non-injected options shown alongside discovered wallets: the
+ * embedded Circle UCW (rabbit) and ghost-mode private routing (ghost). Icons
+ * are app-owned brand assets, supplied by the host (not EIP-6963 data URIs).
+ */
+export type BufiBrandWalletId = "bufi-embedded" | "bufi-ghost";
+
+export interface BrandWallet {
+  id: BufiBrandWalletId;
+  name: string;
+  rdns: string; // synthetic, for stable keys/ordering
+}
+
+/** Which wallet surface to render (cross-repo: defi-web = personal; desk = team+personal). */
+export type WalletScope = "personal" | "team";
+
+// ── Unified wallet dropdown contract ────────────────────────────────────────
+// The pill + dropdown shell is shared; balances are app-supplied (fx reads via
+// wagmi, desk via its wallet context + gateway/hinkal), passed in as props.
+
+/** Address string (lowercased 0x). */
+export type Address = `0x${string}`;
+
+/** One stablecoin balance row on one chain. */
+export interface TokenBalance {
+  symbol: string; // "USDC", "EURC", …
+  chainId: number;
+  chainName: string;
+  /** Human-readable amount, already decimal-formatted by the host. */
+  amount: string;
+  /** USD-equivalent value (for the pill total + sorting). */
+  usd: number;
+}
+
+/** A selectable wallet within a scope. desk: Operations/Treasury/Personal;
+ *  defi-web: a single Personal account. */
+export interface WalletAccount {
+  id: string;
+  scope: WalletScope;
+  /** "Personal" | "Operations" | "Treasury" — shown as the row/tab label. */
+  label: string;
+  address: Address;
+  balances: TokenBalance[];
+}
+