@multiplatform.one/web3 7.26.0 → 7.28.0

package/src/core/signIn.spec.tsx

@@ -0,0 +1,305 @@
+// @vitest-environment happy-dom
+import { act, render, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { deferred, testDriver } from "../../tests/core/testDriver";
+import type { ChainClient } from "../clients/types";
+import { defineWalletFamily } from "./family";
+import { ConnectionProvider } from "./react";
+import {
+  SignInProvider,
+  signInWithConnection,
+  useOptionalSignIn,
+  useSignIn,
+  type SignInConfig,
+  type SignInCredential,
+} from "./signIn";
+import { createConnectionStore } from "./store";
+
+const SOL_ADDRESS = "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV";
+
+function setup() {
+  const sol = testDriver("solana", [{ id: "phantom", name: "Phantom" }], {
+    phantom: { address: SOL_ADDRESS, chainId: "solana:devnet" },
+  });
+  const store = createConnectionStore({
+    storage: null,
+    families: [
+      defineWalletFamily({
+        id: "sol",
+        label: "Solana",
+        message: {
+          header: "wants you to sign in with your Solana account:",
+          statement: "Sign in — with Solana.",
+          chainId: "solana:mainnet",
+        },
+        driver: () => sol,
+      }),
+    ],
+  });
+  let nonces = 0;
+  const onSign = vi.fn<(credential: SignInCredential) => boolean | void>(() => undefined);
+  const config: SignInConfig = {
+    getNonce: vi.fn(async () => `nonce-${++nonces}`),
+    onSign,
+    domain: "app.example.com",
+    uri: "https://app.example.com",
+  };
+  const wrapper =
+    (props: Partial<SignInConfig> = {}) =>
+    ({ children }: { children: ReactNode }) => (
+      <ConnectionProvider store={store}>
+        <SignInProvider {...config} {...props}>
+          {children}
+        </SignInProvider>
+      </ConnectionProvider>
+    );
+  return { sol, store, config, onSign, wrapper };
+}
+
+const decode = (base64: string) =>
+  new TextDecoder().decode(Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)));
+
+describe("signInWithConnection", () => {
+  it("signs the connected family's message with its client and hands onSign the credential", async () => {
+    const { store, config, onSign } = setup();
+    await store.connect("sol", "phantom");
+
+    const credential = await signInWithConnection(store, config);
+
+    const lines = credential.message.split("\n");
+    expect(lines.slice(0, 4)).toEqual([
+      "app.example.com wants you to sign in with your Solana account:",
+      SOL_ADDRESS,
+      "",
+      "Sign in — with Solana.",
+    ]);
+    expect(lines).toContain("URI: https://app.example.com");
+    expect(lines).toContain("Chain ID: solana:devnet");
+    expect(lines).toContain("Nonce: nonce-1");
+    expect(credential.username).toBe(`solana:${credential.message}`);
+    expect(decode(credential.password)).toBe(credential.message);
+    expect(onSign).toHaveBeenCalledExactlyOnceWith(credential);
+  });
+
+  it("takes the message from createMessage when the config has one", async () => {
+    const { store, config } = setup();
+    await store.connect("sol", "phantom");
+    const createMessage = vi.fn(() => "custom message");
+
+    const credential = await signInWithConnection(store, { ...config, createMessage });
+
+    expect(createMessage).toHaveBeenCalledExactlyOnceWith({
+      family: "sol",
+      address: SOL_ADDRESS,
+      chainId: "solana:devnet",
+      nonce: "nonce-1",
+    });
+    expect(credential.username).toBe("solana:custom message");
+  });
+
+  it("refuses without a connection, before asking for a nonce", async () => {
+    const { store, config } = setup();
+    await expect(signInWithConnection(store, config)).rejects.toThrow(/needs a connected wallet/);
+    expect(config.getNonce).not.toHaveBeenCalled();
+  });
+
+  it("does not ask the wallet when the connection changes while the nonce loads", async () => {
+    const { sol, store, config, onSign } = setup();
+    await store.connect("sol", "phantom");
+    const nonce = deferred<string>();
+    const signing = signInWithConnection(store, { ...config, getNonce: () => nonce.promise });
+
+    sol.emit({
+      status: "connected",
+      connectorId: "phantom",
+      account: {
+        address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+        chainId: "solana:devnet",
+      },
+    });
+    nonce.resolve("n");
+
+    await expect(signing).rejects.toThrow(/changed during sign-in/);
+    expect(onSign).not.toHaveBeenCalled();
+  });
+
+  it("waits for a client the driver hands the store after the connection opens", async () => {
+    const { sol, store, config, onSign } = setup();
+    const client = deferred<ReturnType<typeof sol.client>>();
+    const real = sol.client.getMockImplementation()!;
+    sol.client.mockImplementation(() => client.promise as never);
+    await store.connect("sol", "phantom");
+    expect(store.getState().client).toBeNull();
+
+    const signing = signInWithConnection(store, config);
+    client.resolve(real(sol.getState()));
+
+    await expect(signing).resolves.toMatchObject({ username: expect.stringMatching(/^solana:/) });
+    expect(onSign).toHaveBeenCalledTimes(1);
+  });
+
+  it("gives up on a client that never comes, and on a connection that goes while it waits", async () => {
+    vi.useFakeTimers();
+    try {
+      const { sol, store, config } = setup();
+      sol.client.mockImplementation(() => new Promise(() => {}) as never);
+      await store.connect("sol", "phantom");
+
+      const late = signInWithConnection(store, config);
+      const failed = expect(late).rejects.toThrow(/no client to sign with/);
+      await vi.advanceTimersByTimeAsync(10_000);
+      await failed;
+
+      const gone = signInWithConnection(store, config);
+      await store.disconnect();
+      await expect(gone).rejects.toThrow(/changed during sign-in/);
+      expect(config.getNonce).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("asks the store again for a client whose build failed once", async () => {
+    const { sol, store, config, onSign } = setup();
+    const real = sol.client.getMockImplementation()!;
+    sol.client.mockImplementationOnce(() => Promise.reject(new Error("transient")) as never);
+    await store.connect("sol", "phantom");
+    await Promise.resolve();
+    expect(store.getState().client).toBeNull();
+
+    await expect(signInWithConnection(store, config)).resolves.toMatchObject({
+      username: expect.stringMatching(/^solana:/),
+    });
+    expect(onSign).toHaveBeenCalledTimes(1);
+    sol.client.mockImplementation(real);
+  });
+
+  it("a false from onSign refuses the sign-in", async () => {
+    const { store, config } = setup();
+    await store.connect("sol", "phantom");
+    await expect(signInWithConnection(store, { ...config, onSign: () => false })).rejects.toThrow(
+      /rejected/,
+    );
+  });
+});
+
+describe("SignInProvider", () => {
+  it("goes loading then success, and joins a second press to the first", async () => {
+    const { store, config, onSign, wrapper } = setup();
+    await store.connect("sol", "phantom");
+    const nonce = deferred<string>();
+    const { result } = renderHook(() => useSignIn(), {
+      wrapper: wrapper({ getNonce: () => nonce.promise }),
+    });
+    expect(result.current.status).toBe("ready");
+
+    let first!: Promise<boolean>;
+    let second!: Promise<boolean>;
+    act(() => {
+      first = result.current.signIn();
+      second = result.current.signIn();
+    });
+    expect(second).toBe(first);
+    expect(result.current.status).toBe("loading");
+
+    await act(async () => {
+      nonce.resolve("n-1");
+      await first;
+    });
+    expect(await first).toBe(true);
+    expect(onSign).toHaveBeenCalledTimes(1);
+    expect(result.current.status).toBe("success");
+    expect(result.current.onSign).toBe(config.onSign);
+  });
+
+  it("a wallet's 4001 is rejected, anything else an error, and reset clears both", async () => {
+    const { sol, store, wrapper } = setup();
+    await store.connect("sol", "phantom");
+    const client = sol.client.getMockImplementation()!;
+    sol.client.mockImplementation((state) => {
+      const real = client(state) as ChainClient | null;
+      return real
+        ? { ...real, signMessage: async () => Promise.reject({ code: 4001, message: "no" }) }
+        : null;
+    });
+    const { result } = renderHook(() => useSignIn(), { wrapper: wrapper() });
+    // the store asks the driver for a client again only on a change
+    await act(async () => {
+      sol.emit({
+        status: "connected",
+        connectorId: "phantom",
+        account: { address: SOL_ADDRESS, chainId: "solana:mainnet" },
+      });
+    });
+
+    let accepted: boolean | undefined;
+    await act(async () => {
+      accepted = await result.current.signIn();
+    });
+    expect(accepted).toBe(false);
+    expect(result.current.status).toBe("rejected");
+    expect(result.current.error).toMatchObject({ code: 4001 });
+
+    act(() => result.current.reset());
+    expect(result.current.status).toBe("ready");
+    expect(result.current.error).toBeNull();
+
+    await act(() => store.disconnect());
+    await act(async () => {
+      accepted = await result.current.signIn();
+    });
+    expect(accepted).toBe(false);
+    expect(result.current.status).toBe("error");
+    expect(String(result.current.error)).toMatch(/needs a connected wallet/);
+  });
+
+  it("fetches a nonce ahead of the press, and again on every reset", () => {
+    const { config, wrapper } = setup();
+    const resets = new Set<() => void>();
+    const subscribeNonceReset = vi.fn((listener: () => void) => {
+      resets.add(listener);
+      return () => resets.delete(listener);
+    });
+    const { unmount } = renderHook(() => useSignIn(), {
+      wrapper: wrapper({ subscribeNonceReset }),
+    });
+    expect(config.getNonce).toHaveBeenCalledTimes(1);
+    for (const listener of resets) listener();
+    expect(config.getNonce).toHaveBeenCalledTimes(2);
+    unmount();
+    expect(resets.size).toBe(0);
+  });
+
+  it("a re-render fetches no nonce, even with an inline subscribeNonceReset", () => {
+    const { config, wrapper } = setup();
+    const listeners: (() => void)[] = [];
+    const { rerender } = renderHook(() => useSignIn(), {
+      wrapper: ({ children }: { children: ReactNode }) =>
+        wrapper({
+          subscribeNonceReset: (listener) => {
+            listeners.push(listener);
+            return () => undefined;
+          },
+        })({ children }),
+    });
+    rerender();
+    rerender();
+    expect(config.getNonce).toHaveBeenCalledTimes(1);
+    listeners.at(-1)?.();
+    expect(config.getNonce).toHaveBeenCalledTimes(2);
+  });
+
+  it("needs a connection store above it", () => {
+    const { config } = setup();
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(() => render(<SignInProvider {...config} />)).toThrow(
+      /Web3Provider or ConnectionProvider/,
+    );
+  });
+
+  it("useSignIn refuses outside a SignInProvider, useOptionalSignIn reads null", () => {
+    expect(() => renderHook(() => useSignIn())).toThrow(/needs a SignInProvider/);
+    expect(renderHook(() => useOptionalSignIn()).result.current).toBeNull();
+  });
+});

package/src/core/signIn.ts

@@ -0,0 +1,282 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import type { ChainClient } from "../clients/types";
+import { useOptionalConnectionStore } from "./react";
+import type { ConnectionStore } from "./store";
+import type { ConnectionState } from "./types";
+
+/** The values of the SIWE provider's `StatusState`, so a button reads either. */
+export type SignInStatus = "ready" | "loading" | "success" | "rejected" | "error";
+
+/** What a signed sign-in hands over: Keycloak takes it as the login form's username and password. */
+export interface SignInCredential {
+  /** The signature, in the family's own encoding. */
+  readonly username: string;
+  /** The signed message, UTF-8 then base64. */
+  readonly password: string;
+  readonly message: string;
+}
+
+export interface SignInMessageArgs {
+  readonly family: string;
+  readonly address: string;
+  readonly chainId: number | string | null;
+  readonly nonce: string;
+}
+
+/**
+ * How a sign-in gets its nonce and where the signed credential goes.
+ * `kc.signInConfig(onSign)` is one for a Keycloak browser flow, direct grant
+ * or wallet registration.
+ */
+export interface SignInConfig {
+  /**
+   * A server nonce, asked once per sign-in, and ahead of it on mount and on
+   * every nonce reset. Only a source that caches its nonce until a reset, as
+   * keycloakWallet's does, saves the press its round trip that way.
+   */
+  getNonce(): Promise<string>;
+  /** Takes the credential. Resolving false refuses the sign-in. */
+  onSign(credential: SignInCredential): Promise<boolean | void> | boolean | void;
+  /** Written into the message. Defaults to the page's host. */
+  domain?: string;
+  /** Defaults to the page's origin, or `https://<domain>`. */
+  uri?: string;
+  /** Defaults to the family's statement; null or "" leaves it out. */
+  statement?: string | null;
+  /** Builds the message in place of the connected family's own. */
+  createMessage?(args: SignInMessageArgs): string | Promise<string>;
+  /**
+   * Called with a listener on mount; the provider fetches a nonce ahead of
+   * the next press whenever it fires, as kc's resetNonce does after a direct
+   * grant spent one. Returns the unsubscribe.
+   */
+  subscribeNonceReset?(listener: () => void): () => void;
+}
+
+export interface SignIn {
+  readonly status: SignInStatus;
+  /** Why the last sign-in failed, or null. */
+  readonly error: unknown;
+  /**
+   * Signs the family's message with the active connection and hands the
+   * credential to `onSign`. Resolves false when the wallet, `onSign` or the
+   * connection refused, with `status` and `error` saying which. A call while
+   * one runs joins it.
+   */
+  signIn(): Promise<boolean>;
+  /** Back to `ready`, clearing the error. */
+  reset(): void;
+  /** The config's `onSign`, so a caller can check it signs for them. */
+  readonly onSign: SignInConfig["onSign"];
+}
+
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** UTF-8 then base64, without btoa or Buffer, so it runs on Hermes. */
+function utf8Base64(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += alphabet[b0 >> 2];
+    out += alphabet[((b0 & 0x03) << 4) | (b1 >> 4)];
+    out += i + 1 < bytes.length ? alphabet[((b1 & 0x0f) << 2) | (b2 >> 6)] : "=";
+    out += i + 2 < bytes.length ? alphabet[b2 & 0x3f] : "=";
+  }
+  return out;
+}
+
+/** The codes wallets reject a signature request with, as the SIWE provider reads them. */
+function isRejection(error: unknown): boolean {
+  for (let e = error, depth = 0; e && typeof e === "object" && depth < 4; depth += 1) {
+    const code = (e as { code?: unknown }).code;
+    if (code === 4001 || code === -32000 || code === "ACTION_REJECTED") return true;
+    e = (e as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+type Signable = ConnectionState & { family: string; address: string; client: ChainClient };
+
+/** How long a sign-in waits for a connection's client, which a driver may build after it connects. */
+const clientTimeout = 10_000;
+
+/**
+ * The active connection once its client is there. A driver can hand the
+ * store its client a moment after the connection opens, or fail to build it
+ * once, so the store asks the driver again; the sign-in gives up when the
+ * connection goes or no client comes.
+ */
+function signable(store: ConnectionStore): Promise<Signable> {
+  const ready = (state: ConnectionState): state is Signable =>
+    state.status === "connected" && !!state.family && !!state.address && !!state.client;
+  const first = store.getState();
+  if (ready(first)) return Promise.resolve(first);
+  if (first.status !== "connected" || !first.family || !first.address) {
+    return Promise.reject(new Error("sign-in needs a connected wallet"));
+  }
+  const { family, address } = first;
+  const noClient = () => new Error(`the ${family} connection has no client to sign with`);
+  const same = (state: ConnectionState) =>
+    state.status === "connected" && state.family === family && state.address === address;
+  return new Promise<Signable>((resolve, reject) => {
+    let done = false;
+    const finish = (settle: () => void) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      stop();
+      settle();
+    };
+    const timer = setTimeout(() => finish(() => reject(noClient())), clientTimeout);
+    const stop = store.subscribe(() => {
+      const state = store.getState();
+      if (ready(state) && same(state)) finish(() => resolve(state));
+      else if (!same(state)) {
+        finish(() => reject(new Error("the wallet connection changed during sign-in")));
+      }
+    });
+    store.client().then(
+      (client) => {
+        const state = store.getState();
+        if (!same(state)) {
+          finish(() => reject(new Error("the wallet connection changed during sign-in")));
+        } else if (client) finish(() => resolve({ ...state, client } as Signable));
+        else finish(() => reject(noClient()));
+      },
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}
+
+/**
+ * One sign-in on the store's active connection: nonce, the family's message,
+ * the connection's client signs it, `onSign` takes the credential. Throws
+ * when there is no connection, the connection changes before the wallet is
+ * asked, or `onSign` refuses.
+ */
+export async function signInWithConnection(
+  store: ConnectionStore,
+  config: SignInConfig,
+): Promise<SignInCredential> {
+  const { family, address, chainId, client } = await signable(store);
+  const nonce = await config.getNonce();
+  if (!nonce) throw new Error("sign-in: the nonce is empty");
+  const message = config.createMessage
+    ? await config.createMessage({ family, address, chainId, nonce })
+    : store.registry.messages.build(family, {
+        address,
+        nonce,
+        ...(chainId === null ? {} : { chainId }),
+        domain: config.domain,
+        uri: config.uri,
+        ...(config.statement === undefined ? {} : { statement: config.statement }),
+      });
+  const now = store.getState();
+  if (now.status !== "connected" || now.family !== family || now.address !== address) {
+    throw new Error("the wallet connection changed during sign-in");
+  }
+  const signature = await client.signMessage(message);
+  const credential: SignInCredential = {
+    username: signature,
+    password: utf8Base64(message),
+    message,
+  };
+  if ((await config.onSign(credential)) === false) throw new Error("Sign-in was rejected");
+  return credential;
+}
+
+const SignInContext = createContext<SignIn | null>(null);
+
+export interface SignInProviderProps extends SignInConfig {
+  children?: ReactNode;
+}
+
+/**
+ * Wallet sign-in on the connection store: whichever family holds the
+ * connection signs its own message through its client. It replaces
+ * SIWEProvider, and mounts anywhere under a Web3Provider or
+ * ConnectionProvider: `<SignInProvider {...kc.signInConfig(onSign)}>`.
+ */
+export function SignInProvider({ children, ...config }: SignInProviderProps) {
+  const store = useOptionalConnectionStore();
+  if (!store) {
+    throw new Error("SignInProvider needs a Web3Provider or ConnectionProvider above it");
+  }
+  const [status, setStatus] = useState<SignInStatus>("ready");
+  const [error, setError] = useState<unknown>(null);
+  const configRef = useRef(config);
+  configRef.current = config;
+  const running = useRef<Promise<boolean> | null>(null);
+
+  // A nonce fetched ahead of the press, as SIWEProvider fetched it, so a
+  // nonce source that caches it (keycloakWallet's) answers the press at once
+  // and a phone's wallet opens inside the tap. The press still asks
+  // getNonce, which decides whether a nonce is reused.
+  const prefetch = useCallback(() => {
+    configRef.current.getNonce().catch(() => undefined);
+  }, []);
+  useEffect(prefetch, [prefetch]);
+  const { subscribeNonceReset } = config;
+  useEffect(() => subscribeNonceReset?.(prefetch), [subscribeNonceReset, prefetch]);
+
+  const signIn = useCallback(() => {
+    if (running.current) return running.current;
+    setStatus("loading");
+    setError(null);
+    const attempt = signInWithConnection(store, configRef.current).then(
+      () => {
+        // success, not ready: a browser flow is about to navigate away, and
+        // ready would let the button submit twice in that window.
+        setStatus("success");
+        return true;
+      },
+      (e: unknown) => {
+        setError(e);
+        setStatus(isRejection(e) ? "rejected" : "error");
+        return false;
+      },
+    );
+    const settled = attempt.finally(() => {
+      if (running.current === settled) running.current = null;
+    });
+    running.current = settled;
+    return settled;
+  }, [store]);
+
+  const reset = useCallback(() => {
+    setStatus("ready");
+    setError(null);
+  }, []);
+
+  const { onSign } = config;
+  const value = useMemo<SignIn>(
+    () => ({ status, error, signIn, reset, onSign }),
+    [status, error, signIn, reset, onSign],
+  );
+  return createElement(SignInContext.Provider, { value }, children);
+}
+
+/** The nearest SignInProvider's sign-in. */
+export function useSignIn(): SignIn {
+  const value = useContext(SignInContext);
+  if (!value) throw new Error("useSignIn needs a SignInProvider above it");
+  return value;
+}
+
+/** The nearest SignInProvider's sign-in, or null where there is none. */
+export function useOptionalSignIn(): SignIn | null {
+  return useContext(SignInContext);
+}

package/src/core/store.spec.ts

@@ -279,6 +279,89 @@ describe("createConnectionStore", () => {
     expect(storage.map.size).toBe(0);
   });
 
+  describe("client()", () => {
+    it("asks the driver again for a client whose build failed, and keeps the one it gets", async () => {
+      const { store, sol } = setup();
+      const real = sol.client.getMockImplementation()!;
+      sol.client.mockImplementationOnce(() => Promise.reject(new Error("transient")) as never);
+      await store.connect("sol", "phantom");
+      await Promise.resolve();
+      expect(store.getState().client).toBeNull();
+
+      const client = await store.client();
+
+      expect(client).toMatchObject({ family: "solana", address: phantomAccount.address });
+      expect(store.getState().client).toBe(client);
+      expect(await store.client()).toBe(client);
+      expect(sol.client).toHaveBeenCalledTimes(2);
+      sol.client.mockImplementation(real);
+    });
+
+    it("is null with nothing connected, and rejects with the driver's error", async () => {
+      const { store, sol } = setup();
+      expect(await store.client()).toBeNull();
+      sol.client.mockImplementation(() => Promise.reject(new Error("wallet busy")) as never);
+      await store.connect("sol", "phantom");
+      await expect(store.client()).rejects.toThrow(/wallet busy/);
+    });
+  });
+
+  describe("a silent connect", () => {
+    it("takes a connection the wallet already granted through reconnect, with no prompt", async () => {
+      const storage = memoryStorage();
+      const { store, eth, sol, seen } = setup(storage);
+      await store.connect("eth", "metaMask");
+      const state = await store.connect("sol", "phantom", { silent: true });
+      expect(sol.reconnect).toHaveBeenCalledWith("phantom");
+      expect(sol.connect).not.toHaveBeenCalled();
+      expect(eth.disconnect).toHaveBeenCalledTimes(1);
+      expect(state).toMatchObject({
+        status: "connected",
+        family: "sol",
+        address: phantomAccount.address,
+      });
+      expect(seen.map((entry) => entry.status)).toContain("connecting");
+      expect(JSON.parse(storage.map.get(defaultConnectionStorageKey) ?? "")).toEqual({
+        family: "sol",
+        connectorId: "phantom",
+      });
+    });
+
+    it("rejects and stays disconnected when the wallet has not granted it, remembering nothing", async () => {
+      const storage = memoryStorage();
+      const { store, sol } = setup(storage);
+      sol.reconnect.mockResolvedValueOnce(null);
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /phantom.*not authorised/,
+      );
+      expect(sol.connect).not.toHaveBeenCalled();
+      expect(store.getState().status).toBe("disconnected");
+      expect(storage.map.size).toBe(0);
+    });
+
+    it("a refused one closes nothing: what the driver holds stays with whoever opened it", async () => {
+      const { store, sol } = setup();
+      sol.emit({ status: "connected", connectorId: "phantom", account: phantomAccount });
+      sol.reconnect.mockRejectedValueOnce(new Error("no such connector"));
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /no such connector/,
+      );
+      sol.reconnect.mockResolvedValueOnce(null);
+      await expect(store.connect("sol", "phantom", { silent: true })).rejects.toThrow(
+        /not authorised/,
+      );
+      expect(sol.disconnect).not.toHaveBeenCalled();
+      expect(sol.getState().status).toBe("connected");
+    });
+
+    it("never hands the silent flag to the driver", async () => {
+      const { store, eth } = setup();
+      const onDisplayUri = vi.fn();
+      await store.connect("eth", "metaMask", { onDisplayUri, silent: false });
+      expect(eth.connect).toHaveBeenCalledWith("metaMask", { onDisplayUri });
+    });
+  });
+
   it("refuses a connectionless family and an unregistered one", async () => {
     const { store } = setup();
     await expect(store.connect("gpg", "key")).rejects.toThrow(/connectionless/);