wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28_NOTES.md

@@ -72,6 +72,8 @@ May 14 live deployment QA proved the custom Bitcoin OAuth path through Supabase
 
 Fresh-nuke onboarding then exposed a timing gap: Supabase Auth and the empty trigger-created profile existed immediately, while Bitcode's wallet projection appeared only after the app remounted the Wallet pane and replayed the locally signed proof. V28 now treats that gap as unacceptable for first-run readiness. A route-global wallet session persistence bridge must replay any locally signed Bitcoin wallet proof once a Supabase session exists, so callback-to-root, hard refresh, or Terminal landing all converge on the same `user_profiles.settings.bitcodeProfile.walletBinding` and `user_connections` projection before GitHub onboarding proceeds.
 
+Live staging OAuth also exposed two callback hardening requirements. First, the custom wallet authorize page must not rely on a single provider scan at first render because browser wallet extensions can inject provider globals after the route has already hydrated; `/tps/wallet/authorize` must retry discovery, expose an explicit rescan, and preserve the provider hint fallback so Leather/Xverse can still open even when the first scan is empty. Second, the Supabase callback exchange must be idempotent: if the first exchange succeeds and hydration recovery or remount tries to exchange the same code again after the PKCE verifier was consumed, the callback must prefer the already-established session over redirecting to a false login error. Staging URL configuration must also allow both `https://bitcode.exchange` and `https://www.bitcode.exchange` callback routes until a single canonical host redirect is enforced.
+
 ### Deterministic Model Boundary
 
 V28 must remove the idea that a user can choose ledgerized Bitcode synthesis models.

BITCODE_V28_QA.md

@@ -17,6 +17,7 @@ Exchange and the website Conversations interface are no longer V28 QA surfaces.
 | Latest resume | 2026-05-13 |
 | Mock app URL | `http://127.0.0.1:3000` |
 | Testnet-readiness app URL | `http://127.0.0.1:3001` when a second dev server is running |
+| Live staging URL | `https://bitcode.exchange`; current QA may also enter through `https://www.bitcode.exchange` while host canonicalization is being settled |
 | Server mode | manual QA now prioritizes real staging-testnet with mocks off; mock mode remains a deterministic regression harness that must stay synchronized |
 | Active canon pointer | `BITCODE_SPEC.txt` -> `V27` |
 | Draft target | `V28` |
@@ -158,6 +159,19 @@ For every staging-testnet pass, paste back:
 6. Supabase SQL results from the queries below.
 7. A short classification for each issue: V28 blocker, V29 Terminal depth, V31 Auxillaries depth, V32 provation/testing, V33 interfaces, V34 deployment, V35 telemetry/docs, or V36+ Exchange/Conversations.
 
+### Live Staging Host And Callback Checks
+
+For wallet onboarding on the deployed staging-testnet host, Supabase Auth must accept both hostnames until Bitcode enforces one canonical host:
+
+- `https://bitcode.exchange/tps/supabase/callback`
+- `https://www.bitcode.exchange/tps/supabase/callback`
+- `https://bitcode.exchange/auxillaries/wallet`
+- `https://www.bitcode.exchange/auxillaries/wallet`
+
+When Wallet opens `/tps/wallet/authorize`, the page should show Leather and Xverse if both extensions are installed and unlocked. If it initially says no provider was detected, wait a few seconds or click `Rescan wallets`; provider injection after hydration is a V28-observed browser-extension timing behavior. The fallback button may still open the hinted provider, but the expected MVP state is explicit Leather/Xverse choices plus a working fallback.
+
+After signing, a transient root URL containing `loginError=server_error` and `both auth code and code verifier should be non-empty` is a callback idempotency failure if the session nevertheless exists. V28 expects the callback to treat an already-established Supabase session as success and continue to Wallet without showing a false login error.
+
 ### Supabase SQL Checks
 
 Run these in the staging Supabase SQL editor after each milestone and paste the result rows or any table/permission errors.

supabase/config.toml

@@ -46,6 +46,8 @@ site_url = "https://bitcode.exchange"
 additional_redirect_urls = [
   "https://bitcode.exchange/tps/supabase/callback",
   "https://bitcode.exchange/auxillaries/wallet",
+  "https://www.bitcode.exchange/tps/supabase/callback",
+  "https://www.bitcode.exchange/auxillaries/wallet",
   "http://localhost:3000/tps/supabase/callback",
   "http://localhost:3001/tps/supabase/callback",
 ]

uapi/app/login/callback/LoginCallbackClient.tsx

@@ -21,9 +21,11 @@ export default function LoginCallbackClient({
   codeKind = 'none',
   nextPath = '/',
 }: LoginCallbackClientProps) {
+  const [mounted, setMounted] = useState(false);
   const [copied, setCopied] = useState(false);
   const [redirecting, setRedirecting] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
+  const callbackStartedRef = useRef(false);
 
   // Determine if this is an OTP flow (magic-link) or an OAuth redirect
   const isOtpFlow = codeKind === 'token_hash' && Boolean(code && code.trim().length > 0);
@@ -33,6 +35,11 @@ export default function LoginCallbackClient({
   const my = useMotionValue(0);
   const mxPx = useMotionTemplate`${mx}px`;
   const myPx = useMotionTemplate`${my}px`;
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
   useEffect(() => {
     const node = containerRef.current;
     if (!node) return;
@@ -91,6 +98,9 @@ export default function LoginCallbackClient({
    * are never stranded on this screen.
    */
   useEffect(() => {
+    if (callbackStartedRef.current) return;
+    callbackStartedRef.current = true;
+
     let cleanup: (() => void) | undefined;
 
     (async () => {
@@ -116,21 +126,61 @@ export default function LoginCallbackClient({
         }, 600);
       };
 
+      const callbackKey =
+        codeKind === 'oauth_code' && code
+          ? `bitcode.supabase.callback.exchanged.${code.slice(0, 80)}`
+          : null;
+
+      const completeIfSessionExists = async () => {
+        let session;
+        try {
+          const { data } = await supabase.auth.getSession();
+          session = data.session;
+        } catch {
+          session = null;
+        }
+        if (!session) return false;
+        if (callbackKey) {
+          try {
+            window.sessionStorage.setItem(callbackKey, '1');
+          } catch {}
+        }
+        complete();
+        return true;
+      };
+
       // 1️⃣ First, attempt to capture the session from the URL fragment –
       // this is required for implicit/#access_token flows used by Google.
       // 1️⃣ Attempt to extract tokens from the URL hash (implicit flow
       // `#access_token=…`).  Supabase doesn’t parse the hash automatically in
       // the browser SDK, so we do it manually and call `setSession()`.
       const hash = typeof window !== 'undefined' ? window.location.hash || '' : '';
       if (codeKind === 'oauth_code' && code) {
+        if (callbackKey) {
+          try {
+            if (window.sessionStorage.getItem(callbackKey) === '1' && await completeIfSessionExists()) {
+              return;
+            }
+          } catch {}
+        }
+
         try {
           const { error } = await supabase.auth.exchangeCodeForSession(code);
           if (error) throw error;
+          if (callbackKey) {
+            try {
+              window.sessionStorage.setItem(callbackKey, '1');
+            } catch {}
+          }
           complete();
           return;
         } catch (exchangeError) {
+          if (await completeIfSessionExists()) return;
+          await new Promise((resolve) => setTimeout(resolve, 300));
+          if (await completeIfSessionExists()) return;
+
           const message = exchangeError instanceof Error ? exchangeError.message : String(exchangeError);
-          window.location.href = `/?loginError=server_error&loginErrorDescription=${encodeURIComponent(message)}`;
+          window.location.replace(`/?loginError=server_error&loginErrorDescription=${encodeURIComponent(message)}`);
           return;
         }
       }
@@ -192,6 +242,21 @@ export default function LoginCallbackClient({
     return () => window.removeEventListener('keydown', escHandler);
   }, [nextPath]);
 
+  if (!mounted) {
+    return (
+      <div className="fixed inset-0 z-50 flex items-center justify-center bg-black text-white">
+        <div className="text-center">
+          <p className="text-[11px] font-semibold uppercase tracking-[0.28em] text-gray-400">
+            Bitcode authentication
+          </p>
+          <h1 className="mt-4 text-4xl font-light text-[rgba(103,254,183,0.9)]">
+            Verifying…
+          </h1>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <motion.div
       ref={containerRef}

uapi/app/tps/wallet/authorize/BitcoinWalletAuthorizeClient.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { useEffect, useMemo, useState } from 'react';
+import React from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import {
   connectBitcoinWallet,
@@ -23,6 +24,13 @@ type BitcoinWalletAuthorizeClientProps = {
 };
 
 const supportedHints = new Set(['xverse', 'leather', 'unisat', 'okx-bitcoin']);
+const providerLabels: Record<BitcoinWalletProviderId, string> = {
+  xverse: 'Xverse',
+  leather: 'Leather',
+  unisat: 'UniSat',
+  'okx-bitcoin': 'OKX Bitcoin',
+};
+const providerScanRetryDelays = [0, 250, 1000, 2500] as const;
 
 function normalizeProviderHint(value: string): BitcoinWalletProviderId | undefined {
   const normalized = value.trim().toLowerCase();
@@ -50,32 +58,51 @@ export default function BitcoinWalletAuthorizeClient({
   const [scanState, setScanState] = useState<'checking' | 'ready' | 'none'>('checking');
   const [status, setStatus] = useState<'idle' | 'requesting' | 'redirecting'>('idle');
   const [error, setError] = useState<string | null>(null);
+  const mountedRef = useRef(true);
+  const latestProvidersRef = useRef<BitcoinWalletProviderSummary[]>([]);
 
   const preferredProvider = useMemo(() => normalizeProviderHint(walletProviderHint), [walletProviderHint]);
   const hasRequiredParams = Boolean(clientId && redirectUri && (!responseType || responseType === 'code'));
 
-  useEffect(() => {
-    let cancelled = false;
-    inspectBitcoinWalletProviders()
-      .then((detected) => {
-        if (cancelled) return;
-        setProviders(detected);
-        setScanState(detected.length > 0 ? 'ready' : 'none');
-        bitcodeQaTelemetry('info', 'wallet-oauth', 'provider-scan', detected);
-      })
-      .catch((scanError) => {
-        if (cancelled) return;
-        setProviders([]);
-        setScanState('none');
-        bitcodeQaTelemetry('warn', 'wallet-oauth', 'provider-scan-failed', {
-          message: scanError instanceof Error ? scanError.message : 'unknown',
-        });
+  const scanProviders = useCallback(async (reason: string) => {
+    if (reason === 'manual' || latestProvidersRef.current.length === 0) {
+      setScanState('checking');
+    }
+    try {
+      const detected = await inspectBitcoinWalletProviders();
+      if (!mountedRef.current) return;
+      const nextProviders = detected.length > 0 ? detected : latestProvidersRef.current;
+      latestProvidersRef.current = nextProviders;
+      setProviders(nextProviders);
+      setScanState(nextProviders.length > 0 ? 'ready' : 'none');
+      bitcodeQaTelemetry('info', 'wallet-oauth', 'provider-scan', {
+        reason,
+        detected,
+        retained: detected.length === 0 && nextProviders.length > 0,
+      });
+    } catch (scanError) {
+      if (!mountedRef.current) return;
+      setProviders(latestProvidersRef.current);
+      setScanState(latestProvidersRef.current.length > 0 ? 'ready' : 'none');
+      bitcodeQaTelemetry('warn', 'wallet-oauth', 'provider-scan-failed', {
+        reason,
+        message: scanError instanceof Error ? scanError.message : 'unknown',
       });
+    }
+  }, []);
 
+  useEffect(() => {
+    mountedRef.current = true;
+    const timers = providerScanRetryDelays.map((delay) =>
+      window.setTimeout(() => {
+        void scanProviders(delay === 0 ? 'mount' : `retry-${delay}ms`);
+      }, delay),
+    );
     return () => {
-      cancelled = true;
+      mountedRef.current = false;
+      timers.forEach((timer) => window.clearTimeout(timer));
     };
-  }, []);
+  }, [scanProviders]);
 
   const authorize = async (providerId?: BitcoinWalletProviderId) => {
     setError(null);
@@ -154,6 +181,8 @@ export default function BitcoinWalletAuthorizeClient({
     return [preferred, ...providers.filter((provider) => provider.id !== preferredProvider)];
   }, [preferredProvider, providers]);
 
+  const fallbackProviderLabel = preferredProvider ? providerLabels[preferredProvider] : 'Bitcoin wallet';
+
   return (
     <main className="min-h-screen bg-[#050912] text-white">
       <section className="mx-auto flex min-h-screen w-full max-w-3xl flex-col justify-center px-6 py-12">
@@ -208,9 +237,19 @@ export default function BitcoinWalletAuthorizeClient({
                 disabled={status !== 'idle'}
                 className="inline-flex items-center justify-center rounded-full border border-orange-300/34 bg-orange-400/14 px-5 py-2.5 text-[11px] font-semibold uppercase tracking-[0.18em] text-orange-50 transition hover:border-orange-300/54 hover:bg-orange-400/22 disabled:cursor-wait disabled:opacity-60"
               >
-                {status === 'requesting' ? 'Opening Bitcoin wallet' : 'Continue with Bitcoin wallet'}
+                {status === 'requesting'
+                  ? `Opening ${fallbackProviderLabel}`
+                  : `Continue with ${fallbackProviderLabel}`}
               </button>
             )}
+            <button
+              type="button"
+              onClick={() => scanProviders('manual')}
+              disabled={status !== 'idle' || scanState === 'checking'}
+              className="inline-flex items-center justify-center rounded-full border border-white/12 bg-white/6 px-4 py-2.5 text-[11px] font-semibold uppercase tracking-[0.18em] text-white/66 transition hover:border-white/24 hover:bg-white/10 disabled:cursor-wait disabled:opacity-45"
+            >
+              {scanState === 'checking' ? 'Scanning wallets' : 'Rescan wallets'}
+            </button>
           </div>
 
           {error ? (
@@ -228,4 +267,3 @@ export default function BitcoinWalletAuthorizeClient({
     </main>
   );
 }
-

uapi/jest.config.cjs

@@ -134,6 +134,7 @@ module.exports = {
     '<rootDir>/tests/walletPane.initialFlow.test.tsx',
     '<rootDir>/tests/walletPane.test.tsx',
     '<rootDir>/tests/walletSessionPersistenceBridge.test.tsx',
+    '<rootDir>/tests/bitcoinWalletAuthorizeClient.test.tsx',
     '<rootDir>/tests/externalsPane.dataShareFlow.test.tsx',
     '<rootDir>/tests/walletPane.integration.test.tsx',
     '<rootDir>/tests/navPublicShell.test.tsx',

uapi/lib/bitcoin-wallet-client.ts

@@ -203,6 +203,22 @@ function readWindowRecord() {
   return window as typeof window & UnknownRecord;
 }
 
+function readProviderRegistryCandidates(value: unknown): UnknownRecord[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => {
+      const record = asRecord(entry);
+      return record ? [record] : [];
+    });
+  }
+
+  const record = asRecord(value);
+  if (!record) return [];
+  return Object.values(record).flatMap((entry) => {
+    const candidate = asRecord(entry);
+    return candidate ? [candidate] : [];
+  });
+}
+
 function detectDirectBitcoinWalletProviders(): BitcoinWalletProvider[] {
   const windowRecord = readWindowRecord();
   if (!windowRecord) return [];
@@ -279,6 +295,27 @@ async function detectXverseProvider(): Promise<Extract<BitcoinWalletProvider, {
   }
 
   const windowRecord = readWindowRecord();
+  const registryCandidates = [
+    ...readProviderRegistryCandidates(windowRecord?.btc_providers),
+    ...readProviderRegistryCandidates(windowRecord?.webbtc_providers),
+  ];
+  const registryProvider = registryCandidates.find((candidate) => {
+    const id = readString(candidate.id) ?? readString(candidate.providerId) ?? '';
+    const name = readString(candidate.name) ?? readString(candidate.label) ?? '';
+    return /xverse/i.test(id) || /xverse/i.test(name) || id === 'BitcoinProvider';
+  });
+  if (registryProvider) {
+    return {
+      id: 'xverse',
+      label: 'Xverse',
+      providerId:
+        readString(registryProvider.id) ??
+        readString(registryProvider.providerId) ??
+        'BitcoinProvider',
+      request: bindFunction(registryProvider, registryProvider.request),
+    };
+  }
+
   const xverseProvider = asRecord(asRecord(windowRecord?.XverseProviders)?.BitcoinProvider);
   if (xverseProvider) {
     return {