@dexterai/connect 0.20.0 → 0.21.0

package/README.md

@@ -157,10 +157,42 @@ import { VerifyPersonhood } from '@dexterai/connect/worldid';
 `useVerifyPersonhood` is the headless version. Requires the optional
 `@worldcoin/idkit` peer.
 
+## Wallet-only sign-in (no account session)
+
+`recoverWallet` re-points a browser at an existing Dexter Wallet — the wallet
+IS the sign-in; nothing else is minted. Use it when your surface treats the
+wallet as the identity (the dexter.cash header does exactly this):
+
+```ts
+import { recoverWallet } from '@dexterai/connect';
+
+const outcome = await recoverWallet({ preferImmediate: true }); // fire on TAP, never on mount
+if (outcome.ok) {
+  // outcome.vault.swigAddress, outcome.vault.walletLabel — the store + every
+  // useIdentity/useDexterWallet surface is already updated.
+} else if (outcome.reason === 'no_credential') {
+  // this device has no wallet passkey → offer your create flow
+} else if (outcome.reason === 'cancelled') {
+  // the user dismissed the sheet → stay silent
+}
+```
+
+It returns a discriminated outcome instead of throwing: user cancel is a
+normal result in WebAuthn, not an exception. `preferImmediate` uses Chrome
+149+'s immediate UI mode to fast-fail instantly when the device holds no
+passkey (no empty account-picker sheet); everywhere else it falls back to the
+normal modal. Works from any website — off dexter.cash the ceremony runs in
+the hosted popup automatically.
+
+React: `<SignInWithDexter mode="recover" preferImmediate onRecovered={…} />`
+(after a successful recover the element renders null — show identity with
+`DexterWalletChip` over `useIdentity`), or `useSignInWithDexter().recover()`.
+
 ## Wallet lifecycle
 
 - `createWallet` mints a brand-new named passkey + vault; `passkeyLogin` signs
-  an existing one in; `continueWithDexter` resumes a known wallet.
+  an existing one in; `continueWithDexter` resumes a known wallet;
+  `recoverWallet` restores the wallet with no account session.
 - The **wallet store** (`getActiveHandle`, `listWallets`, `switchWallet`,
   `ejectActiveWallet`, `forgetWallet`, `subscribeWallet`) is the canonical
   owner of the active-wallet handle. Read and write through it rather than

package/dist/{chunk-2QZ5QLGI.js → chunk-MOC5AVY7.js}

@@ -166,6 +166,7 @@ function openCeremonyPopup(op, config = {}) {
   const params = new URLSearchParams({ v: "1", op, requestId, origin: openerOrigin });
   if (config.name) params.set("name", config.name);
   if (config.apiBase) params.set("apiBase", config.apiBase);
+  if (config.preferImmediate) params.set("preferImmediate", "1");
   const url = `${host}?${params.toString()}`;
   return new Promise((resolve, reject) => {
     const popup = window.open(url, "dexter-connect", popupFeatures());
@@ -230,6 +231,16 @@ function makeNonce() {
   return `rid-${new URL(location.href).searchParams.get("v") ?? ""}-${typeof performance !== "undefined" ? performance.now() : 0}`;
 }
 
+// src/httpError.ts
+async function readErrorCode(res) {
+  try {
+    const body = await res.json();
+    if (body?.error) return body.error;
+  } catch {
+  }
+  return `http_${res.status}`;
+}
+
 // src/enroll.ts
 var DEFAULT_API_BASE = "https://api.dexter.cash";
 var DEFAULT_RP_ID = "dexter.cash";
@@ -327,14 +338,6 @@ async function initializeVault(apiBase, userHandle, credentialId, spendPolicy) {
   if (!res.ok) throw new ConnectError(await readErrorCode(res), `initialize ${res.status}`);
   return await res.json();
 }
-async function readErrorCode(res) {
-  try {
-    const body = await res.json();
-    if (body?.error) return body.error;
-  } catch {
-  }
-  return `http_${res.status}`;
-}
 
 // src/relay.ts
 import { startAuthentication, browserSupportsWebAuthn } from "@simplewebauthn/browser";
@@ -414,7 +417,7 @@ async function submitLogin(apiBase, response) {
     body: JSON.stringify({ credential: response })
   });
   if (!res.ok) {
-    throw new ConnectError(await readErrorCode2(res), `passkey-login ${res.status}`);
+    throw new ConnectError(await readErrorCode(res), `passkey-login ${res.status}`);
   }
   const data = await res.json();
   const session = {
@@ -426,14 +429,6 @@ async function submitLogin(apiBase, response) {
   };
   return data.vault ? { session, vault: data.vault } : { session };
 }
-async function readErrorCode2(res) {
-  try {
-    const body = await res.json();
-    if (body?.error) return body.error;
-  } catch {
-  }
-  return `http_${res.status}`;
-}
 
 // src/base64.ts
 function base64ToBytes(s) {
@@ -506,7 +501,7 @@ function createAnonServerPolicy(apiBase = DEFAULT_API_BASE3) {
           operationHash: bytesToBase64url(operationHash)
         })
       });
-      if (!res.ok) throw new ConnectError(await readErrorCode3(res), `challenge ${res.status}`);
+      if (!res.ok) throw new ConnectError(await readErrorCode(res), `challenge ${res.status}`);
       const data = await res.json();
       const options = data?.options;
       if (!options?.challenge) {
@@ -543,7 +538,7 @@ function createAnonServerPolicy(apiBase = DEFAULT_API_BASE3) {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ credential, userHandle: bytesToBase64url(userHandle) })
       });
-      if (!res.ok) throw new ConnectError(await readErrorCode3(res), `verify ${res.status}`);
+      if (!res.ok) throw new ConnectError(await readErrorCode(res), `verify ${res.status}`);
       const data = await res.json();
       if (data?.verified === false) {
         throw new ConnectError("verification_failed", "server returned verified=false");
@@ -551,14 +546,6 @@ function createAnonServerPolicy(apiBase = DEFAULT_API_BASE3) {
     }
   };
 }
-async function readErrorCode3(res) {
-  try {
-    const body = await res.json();
-    if (body?.error) return body.error;
-  } catch {
-  }
-  return `http_${res.status}`;
-}
 
 // src/signer.ts
 import { DexterApiBrowserPasskeySigner } from "@dexterai/vault/signers/browser";
@@ -585,6 +572,181 @@ function resolveIdentity(input) {
   return { kind, userHandle, accountToken, hasPasskeyVault, hasAccount, hasWallet };
 }
 
+// src/recover.ts
+import { startAuthentication as startAuthentication2, browserSupportsWebAuthn as browserSupportsWebAuthn2 } from "@simplewebauthn/browser";
+
+// src/immediate.ts
+var immediateCapPromise = null;
+function immediateGetSupported() {
+  if (!immediateCapPromise) {
+    immediateCapPromise = (async () => {
+      try {
+        if (typeof window === "undefined") return false;
+        const pkc2 = window.PublicKeyCredential;
+        if (!pkc2 || typeof pkc2.getClientCapabilities !== "function") return false;
+        const caps = await pkc2.getClientCapabilities.call(pkc2);
+        return caps?.immediateGet === true;
+      } catch {
+        return false;
+      }
+    })();
+  }
+  return immediateCapPromise;
+}
+function primeImmediateSupport() {
+  void immediateGetSupported();
+}
+async function immediateAuthentication(options) {
+  const getOptions = {
+    publicKey: {
+      challenge: base64urlToBytes(options.challenge),
+      rpId: options.rpId,
+      timeout: options.timeout,
+      userVerification: options.userVerification,
+      allowCredentials: options.allowCredentials?.map((c) => ({
+        id: base64urlToBytes(c.id),
+        type: c.type,
+        transports: c.transports
+      }))
+    }
+  };
+  getOptions.uiMode = "immediate";
+  const cred = await navigator.credentials.get(getOptions);
+  if (!cred) throw new DOMException("no credential", "NotAllowedError");
+  const a = cred.response;
+  return {
+    id: cred.id,
+    rawId: bytesToBase64url(new Uint8Array(cred.rawId)),
+    response: {
+      clientDataJSON: bytesToBase64url(new Uint8Array(a.clientDataJSON)),
+      authenticatorData: bytesToBase64url(new Uint8Array(a.authenticatorData)),
+      signature: bytesToBase64url(new Uint8Array(a.signature)),
+      userHandle: a.userHandle ? bytesToBase64url(new Uint8Array(a.userHandle)) : void 0
+    },
+    clientExtensionResults: cred.getClientExtensionResults?.() ?? {},
+    type: "public-key",
+    authenticatorAttachment: cred.authenticatorAttachment ?? void 0
+  };
+}
+function classifyWebAuthnRejection(err) {
+  const e = err;
+  if (!e) return false;
+  const blob = [e.name, e.cause?.name, typeof e.code === "string" ? e.code : "", e.message].filter(Boolean).join(" ").toLowerCase();
+  return /notallowed|not ?allowed|abort|cancel|timed out|timeout|denied|ceremony/.test(blob);
+}
+
+// src/recover.ts
+var DEFAULT_API_BASE4 = "https://api.dexter.cash";
+var ANON_SIGN_BASE3 = "/api/passkey-anon/sign";
+primeImmediateSupport();
+async function recoverWallet(config = {}) {
+  if (shouldUsePopup(config.transport)) {
+    let outcome;
+    try {
+      outcome = await openCeremonyPopup("recover", {
+        connectHost: config.connectHost,
+        apiBase: config.apiBase,
+        preferImmediate: config.preferImmediate
+      });
+    } catch (err) {
+      const ce = err instanceof ConnectError ? err : new ConnectError("popup_failed", err instanceof Error ? err.message : String(err));
+      if (ce.code === "popup_closed") return { ok: false, reason: "cancelled" };
+      return { ok: false, reason: "error", error: ce };
+    }
+    if (outcome.ok) {
+      setActiveHandle(outcome.userHandle, outcome.vault.walletLabel ?? void 0, outcome.credentialId);
+    }
+    return outcome;
+  }
+  if (typeof navigator === "undefined" || !browserSupportsWebAuthn2()) {
+    return {
+      ok: false,
+      reason: "error",
+      error: new ConnectError("webauthn_unsupported", "WebAuthn unavailable in this environment")
+    };
+  }
+  const apiBase = (config.apiBase ?? DEFAULT_API_BASE4).replace(/\/$/, "");
+  const onPhase = config.onPhase;
+  onPhase?.("challenge");
+  let options;
+  try {
+    const res = await fetch(`${apiBase}${ANON_SIGN_BASE3}/recover-challenge`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}"
+    });
+    if (!res.ok) return { ok: false, reason: "error", error: new ConnectError(await readErrorCode(res)) };
+    options = (await res.json()).options;
+  } catch (err) {
+    return netError("recover_challenge_failed", err);
+  }
+  onPhase?.("passkey");
+  const useImmediate = Boolean(config.preferImmediate) && await immediateGetSupported();
+  let credential;
+  try {
+    credential = useImmediate ? await immediateAuthentication(options) : await startAuthentication2({ optionsJSON: options });
+  } catch (err) {
+    if (classifyWebAuthnRejection(err)) {
+      return { ok: false, reason: useImmediate ? "no_credential" : "cancelled" };
+    }
+    return {
+      ok: false,
+      reason: "error",
+      error: new ConnectError("webauthn_failed", err instanceof Error ? err.message : String(err))
+    };
+  }
+  onPhase?.("verifying");
+  let userHandle;
+  let credentialId;
+  try {
+    const res = await fetch(`${apiBase}${ANON_SIGN_BASE3}/recover-verify`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ credential })
+    });
+    if (res.status === 404) return { ok: false, reason: "no_credential" };
+    if (!res.ok) return { ok: false, reason: "error", error: new ConnectError(await readErrorCode(res)) };
+    const data = await res.json();
+    userHandle = data.userHandle;
+    credentialId = data.credentialId;
+  } catch (err) {
+    return netError("recover_verify_failed", err);
+  }
+  let vault;
+  try {
+    const res = await fetch(
+      `${apiBase}/api/passkey-vault-anon/status?user_handle=${encodeURIComponent(userHandle)}`
+    );
+    if (!res.ok) return { ok: false, reason: "error", error: new ConnectError(await readErrorCode(res)) };
+    const data = await res.json();
+    if (!data.hasVault || !data.vault) {
+      return {
+        ok: false,
+        reason: "error",
+        error: new ConnectError("vault_not_found", "this sign-in key has no wallet attached")
+      };
+    }
+    vault = {
+      vaultPda: data.vault.vaultPda,
+      swigAddress: data.vault.swigAddress,
+      receiveAddress: data.vault.receiveAddress ?? null,
+      isActivated: Boolean(data.vault.isActivated),
+      walletLabel: data.vault.walletLabel ?? null
+    };
+  } catch (err) {
+    return netError("vault_status_failed", err);
+  }
+  setActiveHandle(userHandle, vault.walletLabel ?? void 0, credentialId);
+  return { ok: true, userHandle, credentialId, vault };
+}
+function netError(code, err) {
+  return {
+    ok: false,
+    reason: "error",
+    error: new ConnectError(code, err instanceof Error ? err.message : String(err))
+  };
+}
+
 // src/phase.ts
 var PHASE_LABEL = {
   challenge: "Preparing\u2026",
@@ -678,6 +840,7 @@ export {
   createAnonServerPolicy,
   createPasskeySigner,
   resolveIdentity,
+  recoverWallet,
   ceremonyPhaseLabel,
   passkeySignalSupport,
   renamePasskey,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SignInResult, C as CreateWalletResult, a as CreateWalletConfig, b as CeremonyPhase, D as DexterConnectConfig, c as ConnectVault, I as IdentityKind } from './signals-qc4rDyQ6.js';
-export { A as ACTIVE_WALLET_STORAGE_KEY, d as ConnectError, e as IdentityInput, P as PasskeyLoginTokens, f as PasskeySignalSupport, R as ResolvedIdentity, g as SESSION_TTL_30D, h as SpendPolicy, i as StoredWallet, j as authoredPolicy, k as createWallet, l as ejectActiveWallet, m as forgetWallet, n as getActiveHandle, o as getCredentialId, p as listWallets, q as passkeySignalSupport, r as prunePasskey, s as renamePasskey, t as resolveIdentity, u as setActiveHandle, v as subscribeWallet, w as switchWallet, x as syncAcceptedPasskeys, y as usdToAtomic } from './signals-qc4rDyQ6.js';
+import { S as SignInResult, C as CreateWalletResult, a as CreateWalletConfig, b as CeremonyPhase, D as DexterConnectConfig, c as ConnectVault, R as RecoverWalletConfig, d as RecoverOutcome, I as IdentityKind } from './signals-pjh3z6N8.js';
+export { A as ACTIVE_WALLET_STORAGE_KEY, e as ConnectError, f as IdentityInput, P as PasskeyLoginTokens, g as PasskeySignalSupport, h as RecoverVault, i as ResolvedIdentity, j as SESSION_TTL_30D, k as SpendPolicy, l as StoredWallet, m as authoredPolicy, n as createWallet, o as ejectActiveWallet, p as forgetWallet, q as getActiveHandle, r as getCredentialId, s as listWallets, t as passkeySignalSupport, u as prunePasskey, v as renamePasskey, w as resolveIdentity, x as setActiveHandle, y as subscribeWallet, z as switchWallet, B as syncAcceptedPasskeys, E as usdToAtomic } from './signals-pjh3z6N8.js';
 import { DexterApiBrowserPasskeySigner } from '@dexterai/vault/signers/browser';
 
 /**
@@ -82,6 +82,8 @@ declare function createPasskeySigner(vault: ConnectVault, apiBase?: string, opts
     __assertion?: AssertionLike;
 }): DexterApiBrowserPasskeySigner;
 
+declare function recoverWallet(config?: RecoverWalletConfig): Promise<RecoverOutcome>;
+
 /**
  * Human-readable label for a ceremony phase — the live "connecting step" copy.
  * ONE source of truth so sign-in (SignInWithDexter) and create (consumer setup
@@ -221,4 +223,4 @@ interface EnableAgentSpendResult {
  */
 declare function enableAgentSpend(id: AgentSpendIdentity, vaultPda: string, apiOrigin: string, credentialId?: string | null): Promise<EnableAgentSpendResult>;
 
-export { AgentSpendError, type AgentSpendIdentity, type AgentSpendStatus, type AgentSpendTab, type AnonChallengeResult, type AnonServerPolicy, type AutomaticAgentSpend, CeremonyPhase, ConnectVault, type ContinueResult, CreateWalletConfig, CreateWalletResult, DexterConnectConfig, type EnableAgentSpendResult, IdentityKind, type RawAgentSpendSession, type RawAgentSpendStatus, type RevokeAgentSpendResult, SignInResult, assembleAgentSpendStatus, ceremonyPhaseLabel, continueWithDexter, createAnonServerPolicy, createPasskeySigner, describeAgentSpendError, enableAgentSpend, passkeyLogin, revokeAgentSpend };
+export { AgentSpendError, type AgentSpendIdentity, type AgentSpendStatus, type AgentSpendTab, type AnonChallengeResult, type AnonServerPolicy, type AutomaticAgentSpend, CeremonyPhase, ConnectVault, type ContinueResult, CreateWalletConfig, CreateWalletResult, DexterConnectConfig, type EnableAgentSpendResult, IdentityKind, type RawAgentSpendSession, type RawAgentSpendStatus, RecoverOutcome, RecoverWalletConfig, type RevokeAgentSpendResult, SignInResult, assembleAgentSpendStatus, ceremonyPhaseLabel, continueWithDexter, createAnonServerPolicy, createPasskeySigner, describeAgentSpendError, enableAgentSpend, passkeyLogin, recoverWallet, revokeAgentSpend };

package/dist/index.js

@@ -18,6 +18,7 @@ import {
   passkeyLogin,
   passkeySignalSupport,
   prunePasskey,
+  recoverWallet,
   renamePasskey,
   resolveIdentity,
   setActiveHandle,
@@ -25,7 +26,7 @@ import {
   switchWallet,
   syncAcceptedPasskeys,
   usdToAtomic
-} from "./chunk-2QZ5QLGI.js";
+} from "./chunk-MOC5AVY7.js";
 
 // src/agentSpend.ts
 import { PublicKey } from "@solana/web3.js";
@@ -196,6 +197,7 @@ export {
   passkeyLogin,
   passkeySignalSupport,
   prunePasskey,
+  recoverWallet,
   renamePasskey,
   resolveIdentity,
   revokeAgentSpend,

package/dist/react.d.ts

@@ -1,5 +1,6 @@
 import { DexterApiBrowserPasskeySigner } from '@dexterai/vault/signers/browser';
-import { b as CeremonyPhase, S as SignInResult, P as PasskeyLoginTokens, c as ConnectVault, d as ConnectError, i as StoredWallet, f as PasskeySignalSupport, R as ResolvedIdentity, C as CreateWalletResult } from './signals-qc4rDyQ6.js';
+import { b as CeremonyPhase, S as SignInResult, d as RecoverOutcome, P as PasskeyLoginTokens, c as ConnectVault, e as ConnectError, l as StoredWallet, g as PasskeySignalSupport, i as ResolvedIdentity, C as CreateWalletResult } from './signals-pjh3z6N8.js';
+export { h as RecoverVault } from './signals-pjh3z6N8.js';
 import { ReactElement, ReactNode } from 'react';
 
 type ConnectStatus = 'idle' | 'pending' | 'done' | 'error';
@@ -8,6 +9,16 @@ interface UseSignInWithDexterConfig {
     apiBase?: string;
     /** RPC for the connected-chip balance read. Default: Dexter's Helius proxy. */
     rpcUrl?: string;
+    /** Ceremony transport (both verbs). 'auto' (default) = inline on dexter.cash,
+     *  popup anywhere else. Exposed so tests/staging can force a leg —
+     *  CreateWalletPanel already had this knob; the sign-in surface was the odd
+     *  one out. */
+    transport?: 'auto' | 'popup' | 'inline';
+    /** Hosted ceremony page for the popup transport. Default dexter.cash/connect. */
+    connectHost?: string;
+    /** Chrome-149+ immediate UI mode for the wallet-only verb: instant fast-fail
+     *  when this device holds no passkey. Ignored by signIn(). */
+    preferImmediate?: boolean;
 }
 interface UseSignInWithDexter {
     status: ConnectStatus;
@@ -18,6 +29,14 @@ interface UseSignInWithDexter {
     /** Run the ceremony. Resolves with the result; throws ConnectError on failure
      *  (error is also captured in `error` + `status==='error'` for declarative UI). */
     signIn: () => Promise<SignInResult>;
+    /** Wallet-only sign-in (P0c): re-points this browser at an existing wallet,
+     *  mints NO session. Returns a discriminated outcome — cancel is a normal
+     *  result, never a throw. Identity surfaces (useIdentity/useDexterWallet)
+     *  light up via the wallet store; `session`/`vault` here stay null. Fire on
+     *  tap only — never on mount (iOS gesture rule). */
+    recover: () => Promise<RecoverOutcome>;
+    /** Last recover outcome; null until recover() settles. */
+    recovered: RecoverOutcome | null;
     disconnect: () => void;
     session: PasskeyLoginTokens | null;
     vault: ConnectVault | null;
@@ -45,8 +64,18 @@ interface UseSignInWithDexter {
 declare function useSignInWithDexter(config?: UseSignInWithDexterConfig): UseSignInWithDexter;
 
 interface SignInWithDexterProps extends UseSignInWithDexterConfig {
+    /** 'signin' (default) = full sign-in minting the account session.
+     *  'recover' = wallet-only: re-points this browser at an existing wallet and
+     *  mints NOTHING else (the wallet IS the sign-in). After a successful
+     *  recover the element renders null — identity display belongs to
+     *  DexterWalletChip/useIdentity, which light up via the wallet store. */
+    mode?: 'signin' | 'recover';
     /** Fired with the result the moment sign-in completes. */
     onSuccess?: (result: SignInResult) => void;
+    /** Recover mode: fired with EVERY settled outcome (ok, no_credential,
+     *  cancelled, error) — the single channel; onError is not used in this mode.
+     *  Branch on `reason`: no_credential → offer create; cancelled → stay silent. */
+    onRecovered?: (outcome: RecoverOutcome) => void;
     /** Fired with the typed error if the ceremony fails. */
     onError?: (error: ConnectError) => void;
     /** Button label when signed out. Default "Sign in with Dexter". */
@@ -200,4 +229,4 @@ interface CreateWalletPanelProps {
 /** The turnkey consent-at-birth create panel. */
 declare function CreateWalletPanel(props: CreateWalletPanelProps): ReactElement;
 
-export { AllowanceChips, type AllowanceChipsProps, type ConnectStatus, CreateWalletPanel, type CreateWalletPanelProps, DexterButton, type DexterButtonProps, DexterMark, DexterWalletChip, type DexterWalletChipProps, DexterWalletMenu, type DexterWalletMenuProps, SignInWithDexter, type SignInWithDexterProps, type UseDexterWallet, type UseIdentityConfig, type UseSignInWithDexter, type UseSignInWithDexterConfig, useDexterWallet, useIdentity, useSignInWithDexter };
+export { AllowanceChips, type AllowanceChipsProps, type ConnectStatus, CreateWalletPanel, type CreateWalletPanelProps, DexterButton, type DexterButtonProps, DexterMark, DexterWalletChip, type DexterWalletChipProps, DexterWalletMenu, type DexterWalletMenuProps, RecoverOutcome, SignInWithDexter, type SignInWithDexterProps, type UseDexterWallet, type UseIdentityConfig, type UseSignInWithDexter, type UseSignInWithDexterConfig, useDexterWallet, useIdentity, useSignInWithDexter };

package/dist/react.js

@@ -11,12 +11,13 @@ import {
   passkeyLogin,
   passkeySignalSupport,
   prunePasskey,
+  recoverWallet,
   renamePasskey,
   resolveIdentity,
   setActiveHandle,
   subscribe,
   switchWallet
-} from "./chunk-2QZ5QLGI.js";
+} from "./chunk-MOC5AVY7.js";
 import {
   DexterButton,
   DexterMark,
@@ -67,13 +68,14 @@ function base64ToBytes(s) {
 // src/useSignInWithDexter.ts
 var DEFAULT_RPC = "https://api.dexter.cash/proxy/helius/rpc";
 function useSignInWithDexter(config = {}) {
-  const { apiBase, rpcUrl = DEFAULT_RPC } = config;
+  const { apiBase, rpcUrl = DEFAULT_RPC, transport, connectHost, preferImmediate } = config;
   const [status, setStatus] = useState("idle");
   const [phase, setPhase] = useState(null);
   const [session, setSession] = useState(null);
   const [vault, setVault] = useState(null);
   const [usdcBalance, setUsdcBalance] = useState(null);
   const [error, setError] = useState(null);
+  const [recovered, setRecovered] = useState(null);
   const refreshBalance = useCallback(async () => {
     const ata = vault?.usdcAta;
     if (!ata) return;
@@ -84,7 +86,14 @@ function useSignInWithDexter(config = {}) {
     setPhase(null);
     setStatus("pending");
     try {
-      const result = await passkeyLogin(apiBase ? { apiBase } : {}, setPhase);
+      const result = await passkeyLogin(
+        {
+          ...apiBase ? { apiBase } : {},
+          ...transport ? { transport } : {},
+          ...connectHost ? { connectHost } : {}
+        },
+        setPhase
+      );
       setSession(result.session);
       setVault(result.vault ?? null);
       setStatus("done");
@@ -97,12 +106,36 @@ function useSignInWithDexter(config = {}) {
       setPhase(null);
       throw e;
     }
-  }, [apiBase]);
+  }, [apiBase, transport, connectHost]);
+  const recover = useCallback(async () => {
+    setError(null);
+    setPhase(null);
+    setStatus("pending");
+    const outcome = await recoverWallet({
+      ...apiBase ? { apiBase } : {},
+      ...transport ? { transport } : {},
+      ...connectHost ? { connectHost } : {},
+      ...preferImmediate ? { preferImmediate } : {},
+      onPhase: setPhase
+    });
+    setPhase(null);
+    setRecovered(outcome);
+    if (outcome.ok) {
+      setStatus("done");
+    } else if (outcome.reason === "error") {
+      setError(outcome.error ?? new ConnectError("recover_failed"));
+      setStatus("error");
+    } else {
+      setStatus("idle");
+    }
+    return outcome;
+  }, [apiBase, transport, connectHost, preferImmediate]);
   const disconnect = useCallback(() => {
     setSession(null);
     setVault(null);
     setUsdcBalance(null);
     setError(null);
+    setRecovered(null);
     setStatus("idle");
   }, []);
   const passkeySigner = useMemo(
@@ -117,6 +150,8 @@ function useSignInWithDexter(config = {}) {
     phase,
     isVaultConnected: status === "done" && vault !== null,
     signIn,
+    recover,
+    recovered,
     disconnect,
     session,
     vault,
@@ -141,8 +176,10 @@ function formatUsd(n) {
 }
 function SignInWithDexter(props) {
   const {
+    mode = "signin",
     onSuccess,
     onError,
+    onRecovered,
     label = "Sign in with Dexter",
     variant = "primary",
     block = false,
@@ -153,12 +190,17 @@ function SignInWithDexter(props) {
   useEffect2(ensureDexterButtonStyles, []);
   const c = useSignInWithDexter(config);
   const handleClick = async () => {
+    if (mode === "recover") {
+      onRecovered?.(await c.recover());
+      return;
+    }
     try {
       onSuccess?.(await c.signIn());
     } catch (err) {
       onError?.(err);
     }
   };
+  if (mode === "recover" && c.recovered?.ok) return null;
   if (c.isVaultConnected) {
     if (!showConnectedChip) return null;
     return /* @__PURE__ */ jsxs("span", { className: cx("dx-chip", className), children: [

package/dist/{signals-qc4rDyQ6.d.ts → signals-pjh3z6N8.d.ts}

@@ -38,6 +38,47 @@ interface SignInResult {
  *   challenge → passkey (the OS prompt) → verifying → finalizing (create only).
  */
 type CeremonyPhase = 'challenge' | 'passkey' | 'verifying' | 'finalizing';
+/**
+ * Vault identity on the wallet-only recover leg, as reported by
+ * /api/passkey-vault-anon/status. Narrower than ConnectVault on purpose —
+ * the status endpoint carries no publicKey/usdcAta, so a recover cannot
+ * construct a passkey signer; it re-points this browser at the wallet and
+ * lets useIdentity/useDexterWallet light the UI.
+ */
+interface RecoverVault {
+    vaultPda: string;
+    /** Swig state address, base58 — the user-facing Dexter Wallet address. */
+    swigAddress: string;
+    /** Deposit address; null until the swig is deployed. */
+    receiveAddress: string | null;
+    isActivated: boolean;
+    walletLabel: string | null;
+}
+/**
+ * Result of a wallet-only recover ceremony. A discriminated RESULT, not a
+ * throw: user-cancel is a normal outcome in WebAuthn, and consumers branch on
+ * `reason` (no_credential → offer create; cancelled → stay silent; error →
+ * retry copy). `no_credential` covers both the immediate-mode instant
+ * rejection (no passkey on this device) and a verify 404 (a passkey the
+ * server has no row for).
+ */
+type RecoverOutcome = {
+    ok: true;
+    userHandle: string;
+    credentialId: string;
+    vault: RecoverVault;
+} | {
+    ok: false;
+    reason: 'no_credential' | 'cancelled' | 'error';
+    error?: ConnectError;
+};
+interface RecoverWalletConfig extends DexterConnectConfig {
+    /** Chrome-149+ immediate UI mode: instant fast-fail when this device has no
+     *  discoverable passkey (no empty account-picker sheet). Falls back to the
+     *  normal modal wherever unsupported. */
+    preferImmediate?: boolean;
+    onPhase?: (phase: CeremonyPhase) => void;
+}
 interface DexterConnectConfig {
     /** dexter-api base. Default https://api.dexter.cash. */
     apiBase?: string;
@@ -229,4 +270,4 @@ declare function syncAcceptedPasskeys(args: {
     rpId?: string;
 }): Promise<boolean>;
 
-export { ACTIVE_WALLET_STORAGE_KEY as A, type CreateWalletResult as C, type DexterConnectConfig as D, type IdentityKind as I, type PasskeyLoginTokens as P, type ResolvedIdentity as R, type SignInResult as S, type CreateWalletConfig as a, type CeremonyPhase as b, type ConnectVault as c, ConnectError as d, type IdentityInput as e, type PasskeySignalSupport as f, SESSION_TTL_30D as g, type SpendPolicy as h, type StoredWallet as i, authoredPolicy as j, createWallet as k, ejectActiveWallet as l, forgetWallet as m, getActiveHandle as n, getCredentialId as o, listWallets as p, passkeySignalSupport as q, prunePasskey as r, renamePasskey as s, resolveIdentity as t, setActiveHandle as u, subscribe as v, switchWallet as w, syncAcceptedPasskeys as x, usdToAtomic as y };
+export { ACTIVE_WALLET_STORAGE_KEY as A, syncAcceptedPasskeys as B, type CreateWalletResult as C, type DexterConnectConfig as D, usdToAtomic as E, type IdentityKind as I, type PasskeyLoginTokens as P, type RecoverWalletConfig as R, type SignInResult as S, type CreateWalletConfig as a, type CeremonyPhase as b, type ConnectVault as c, type RecoverOutcome as d, ConnectError as e, type IdentityInput as f, type PasskeySignalSupport as g, type RecoverVault as h, type ResolvedIdentity as i, SESSION_TTL_30D as j, type SpendPolicy as k, type StoredWallet as l, authoredPolicy as m, createWallet as n, ejectActiveWallet as o, forgetWallet as p, getActiveHandle as q, getCredentialId as r, listWallets as s, passkeySignalSupport as t, prunePasskey as u, renamePasskey as v, resolveIdentity as w, setActiveHandle as x, subscribe as y, switchWallet as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dexterai/connect",
-  "version": "0.20.0",
-  "description": "Sign in with Dexter — passkey connector. Composes @dexterai/vault.",
+  "version": "0.21.0",
+  "description": "Sign in with Dexter \u2014 passkey connector. Composes @dexterai/vault.",
   "type": "module",
   "exports": {
     ".": {