@multiplatform.one/web3 7.23.2 → 7.25.0

package/src/keycloak/useWalletLogin.ts

@@ -0,0 +1,99 @@
+import { useModal } from "@multiplatform.one/connectkit";
+import { useCallback, useContext, useEffect, useRef } from "react";
+import { useAccount } from "wagmi";
+import { useConnectorLauncher } from "../connectkit/openConnector";
+import { SIWEContext, StatusState } from "../connectkit/siwe/SIWEContext";
+import { hasUserActivation, isMobileBrowser } from "./device";
+
+export interface UseWalletLoginOptions {
+  /** sessionStorage key of the pending-login mark. One per button on a page. */
+  intentKey?: string;
+  /** How long a connect started by `login()` may still drive the signature. Default 90 s. */
+  intentTtlMs?: number;
+}
+
+export interface UseWalletLoginResult {
+  /** Connect if needed, then sign through SIWEProvider. One press, no Continue step. */
+  login(): Promise<void>;
+  status: StatusState;
+  isConnected: boolean;
+  address?: string;
+}
+
+function readIntent(key: string, ttl: number): boolean {
+  try {
+    const raw = globalThis.sessionStorage?.getItem(key);
+    if (raw === null || raw === undefined) return false;
+    globalThis.sessionStorage.removeItem(key);
+    const at = Number(raw);
+    return Number.isFinite(at) && Date.now() - at < ttl;
+  } catch {
+    return false;
+  }
+}
+
+function writeIntent(key: string, value: string | null) {
+  try {
+    if (value === null) globalThis.sessionStorage?.removeItem(key);
+    else globalThis.sessionStorage?.setItem(key, value);
+  } catch {
+    // Storage off (private mode): the login falls back to a second press.
+  }
+}
+
+/**
+ * A wallet login button's behaviour. Pressing it while disconnected opens the
+ * connect modal, or on a phone with ConnectKit's `mobile.preferredConnector`
+ * that wallet straight away, so call `login()` synchronously in the click
+ * handler. The press is marked in sessionStorage (the wallet bounce can reload
+ * the page); once the wallet connects the signature starts by itself.
+ * Only a fresh mark drives it, so a wallet that reconnects on a later visit
+ * never signs unasked. A phone browser opens the wallet for a signature only
+ * from a tap, so without one the user presses again.
+ */
+export function useWalletLogin(opts: UseWalletLoginOptions = {}): UseWalletLoginResult {
+  const { intentKey = "mpo:wallet-login-intent", intentTtlMs = 90_000 } = opts;
+  const siwe = useContext(SIWEContext);
+  const { setOpen } = useModal();
+  const launcher = useConnectorLauncher();
+  const { address, isConnected } = useAccount();
+  const signingRef = useRef(false);
+
+  const sign = useCallback(async () => {
+    if (!siwe) throw new Error("useWalletLogin must be used inside a SIWEProvider");
+    if (signingRef.current) return;
+    signingRef.current = true;
+    try {
+      await siwe.signIn();
+    } finally {
+      signingRef.current = false;
+    }
+  }, [siwe]);
+
+  const login = useCallback(async () => {
+    if (isConnected) {
+      await sign();
+      return;
+    }
+    writeIntent(intentKey, String(Date.now()));
+    // No await above: a phone's preferred wallet opens from inside the tap.
+    if (launcher?.openPreferredConnector()) return;
+    setOpen(true);
+  }, [isConnected, sign, intentKey, setOpen, launcher]);
+
+  useEffect(() => {
+    if (!isConnected || !readIntent(intentKey, intentTtlMs)) return;
+    if (isMobileBrowser() && !hasUserActivation()) return;
+    setOpen(false);
+    void sign();
+  }, [isConnected, intentKey, intentTtlMs, setOpen, sign]);
+
+  useEffect(() => () => writeIntent(intentKey, null), [intentKey]);
+
+  return {
+    login,
+    status: siwe?.status ?? StatusState.ERROR,
+    isConnected,
+    address,
+  };
+}

package/src/message/buildWalletMessage.spec.ts

@@ -0,0 +1,291 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createWalletMessage } from "../connectkit/connectors/createWalletMessage";
+import { SOLANA_CHAIN_ID } from "../connectkit/connectors/syntheticChains";
+import { createSiwsMessage } from "../siws/message";
+import { buildWalletMessage } from "./buildWalletMessage";
+
+const common = {
+  domain: "app.multiplatform.one",
+  uri: "https://app.multiplatform.one",
+  nonce: "ohY7vD2Kq9",
+  issuedAt: "2026-09-26T20:48:18.648Z",
+};
+
+describe("buildWalletMessage", () => {
+  it("eth: EIP-4361 with the EIP-55 address and no optional fields", () => {
+    expect(
+      buildWalletMessage("eth", {
+        ...common,
+        address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
+        chainId: 137,
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Ethereum account:\n" +
+        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n" +
+        "\n" +
+        "Sign in With Ethereum.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: 137\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("eth: chain id defaults to 1 and the evm alias builds the same bytes", () => {
+    const opts = { ...common, address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" };
+    const message = buildWalletMessage("eth", opts);
+    expect(message).toContain("\nChain ID: 1\n");
+    expect(buildWalletMessage("evm", opts)).toBe(message);
+  });
+
+  it("sol: SIWS", () => {
+    expect(
+      buildWalletMessage("sol", {
+        ...common,
+        address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Solana account:\n" +
+        "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS\n" +
+        "\n" +
+        "Sign in With Solana.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: solana:mainnet\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("sui", () => {
+    expect(
+      buildWalletMessage("sui", {
+        ...common,
+        address: "0x7a1e0b5c2d3f4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Sui account:\n" +
+        "0x7a1e0b5c2d3f4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a\n" +
+        "\n" +
+        "Sign in With Sui.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: sui:mainnet\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("btc", () => {
+    expect(
+      buildWalletMessage("btc", {
+        ...common,
+        address: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Bitcoin account:\n" +
+        "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq\n" +
+        "\n" +
+        "Sign in With Bitcoin.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: bitcoin\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("gpg: no address or chain line, the GpgProvider default envelope", () => {
+    expect(buildWalletMessage("gpg", common)).toBe(
+      "app.multiplatform.one wants you to sign in with your GPG key.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("gpg: a statement sits between the header and the fields", () => {
+    expect(buildWalletMessage("gpg", { ...common, statement: "Hello." })).toBe(
+      "app.multiplatform.one wants you to sign in with your GPG key.\n" +
+        "\n" +
+        "Hello.\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it("a null statement drops the statement lines", () => {
+    expect(
+      buildWalletMessage("sol", {
+        ...common,
+        address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+        statement: null,
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Solana account:\n" +
+        "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: solana:mainnet\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it.each([null, ""])("eth: a %j statement keeps EIP-4361's empty statement line", (statement) => {
+    expect(
+      buildWalletMessage("eth", {
+        ...common,
+        address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+        statement,
+      }),
+    ).toBe(
+      "app.multiplatform.one wants you to sign in with your Ethereum account:\n" +
+        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n" +
+        "\n" +
+        "\n" +
+        "URI: https://app.multiplatform.one\n" +
+        "Version: 1\n" +
+        "Chain ID: 1\n" +
+        "Nonce: ohY7vD2Kq9\n" +
+        "Issued At: 2026-09-26T20:48:18.648Z",
+    );
+  });
+
+  it.each([
+    ["statement", { statement: "Sign in.\nURI: https://evil.example" }],
+    ["statement", { statement: "Sign in.\r" }],
+    ["uri", { uri: "https://app.multiplatform.one\nNonce: forged" }],
+    ["domain", { domain: "app.multiplatform.one\nevil.example" }],
+  ])("refuses a %s with a line break", (field, override) => {
+    for (const family of ["eth", "sol", "gpg"] as const) {
+      expect(() =>
+        buildWalletMessage(family, {
+          ...common,
+          address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+          ...override,
+        }),
+      ).toThrow(`${field} must be a single line`);
+    }
+  });
+
+  it("a numeric chain id on a non-EVM family is a connector's synthetic id and is ignored", () => {
+    const message = buildWalletMessage("sol", {
+      ...common,
+      address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+      chainId: SOLANA_CHAIN_ID,
+    });
+    expect(message).toContain("\nChain ID: solana:mainnet\n");
+    expect(
+      buildWalletMessage("sol", {
+        ...common,
+        address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+        chainId: "solana:devnet",
+      }),
+    ).toContain("\nChain ID: solana:devnet\n");
+  });
+
+  describe("page defaults", () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+      vi.useRealTimers();
+    });
+
+    it("takes domain and uri from the page", () => {
+      vi.stubGlobal("location", { host: "login.example.com", origin: "https://login.example.com" });
+      const message = buildWalletMessage("gpg", { nonce: "n", issuedAt: common.issuedAt });
+      expect(message.split("\n")[0]).toBe(
+        "login.example.com wants you to sign in with your GPG key.",
+      );
+      expect(message).toContain("\nURI: https://login.example.com\n");
+    });
+
+    it("an explicit domain wins, and a page with no origin (file://) falls back to https://<domain>", () => {
+      vi.stubGlobal("location", { host: "", origin: "null" });
+      const message = buildWalletMessage("gpg", {
+        nonce: "n",
+        domain: "wallet.example.com",
+        issuedAt: common.issuedAt,
+      });
+      expect(message.split("\n")[0]).toBe(
+        "wallet.example.com wants you to sign in with your GPG key.",
+      );
+      expect(message).toContain("\nURI: https://wallet.example.com\n");
+    });
+
+    it("refuses to build without a domain", () => {
+      vi.stubGlobal("location", { host: "", origin: "null" });
+      expect(() => buildWalletMessage("gpg", { nonce: "n" })).toThrow(/no domain/);
+    });
+
+    it("issuedAt defaults to now", () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2026-01-02T03:04:05.006Z"));
+      expect(buildWalletMessage("gpg", { ...common, issuedAt: undefined })).toMatch(
+        /\nIssued At: 2026-01-02T03:04:05\.006Z$/,
+      );
+    });
+  });
+
+  it("requires an address for wallet families", () => {
+    expect(() => buildWalletMessage("eth", common)).toThrow(/needs an address/);
+  });
+});
+
+describe("builders that delegate to buildWalletMessage", () => {
+  it("createWalletMessage picks the family from the connector's chain id", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(common.issuedAt));
+    const sol = createWalletMessage({
+      ...common,
+      address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+      chainId: SOLANA_CHAIN_ID,
+    });
+    expect(sol).toBe(
+      buildWalletMessage("sol", {
+        ...common,
+        address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+      }),
+    );
+    const eth = createWalletMessage({
+      ...common,
+      address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
+      chainId: 10,
+    });
+    expect(eth).toBe(
+      buildWalletMessage("eth", {
+        ...common,
+        address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+        chainId: 10,
+      }),
+    );
+    vi.useRealTimers();
+  });
+
+  it("createSiwsMessage keeps its output (statement optional)", () => {
+    const params = {
+      domain: common.domain,
+      uri: common.uri,
+      nonce: common.nonce,
+      issuedAt: common.issuedAt,
+      address: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+    };
+    expect(createSiwsMessage({ ...params, statement: "Sign in With Solana." })).toBe(
+      buildWalletMessage("sol", params),
+    );
+    expect(createSiwsMessage(params)).toBe(
+      buildWalletMessage("sol", { ...params, statement: null }),
+    );
+  });
+});

package/src/message/buildWalletMessage.ts

@@ -0,0 +1,150 @@
+import { getAddress } from "viem";
+
+/**
+ * The signer families a wallet sign-in message can be built for. The Keycloak
+ * SPIs (SHC `siww`, mpo `wallet`) content-sniff exactly these headers.
+ */
+export type WalletMessageFamily = "eth" | "sol" | "sui" | "btc" | "gpg";
+
+/** Ecosystem names the connectors use; accepted as aliases of the short family. */
+export type WalletMessageEcosystem = "evm" | "solana" | "sui" | "bitcoin";
+
+export type SignerFamily = WalletMessageFamily | WalletMessageEcosystem;
+
+export interface WalletMessageOptions {
+  nonce: string;
+  /** Signer address. Required for every family except `gpg`, whose identity comes from the key. */
+  address?: string;
+  /**
+   * Host the user signs in to, checked against the realm's frontend host and
+   * `siww.allowedDomains` / `wallet.allowedDomains`. Defaults to
+   * `window.location.host`; pass it explicitly from a WebView or native page,
+   * where that host is empty or not the one the realm allows.
+   */
+  domain?: string;
+  /** Defaults to `window.location.origin`, or `https://<domain>` when the page has no origin. */
+  uri?: string;
+  /**
+   * Defaults to the family's statement; `null` or `""` omits it. `eth` then
+   * keeps the empty line EIP-4361 puts in its place.
+   */
+  statement?: string | null;
+  /** Defaults to now. */
+  issuedAt?: string;
+  /**
+   * `eth`: the chain id (default 1). Other families keep their fixed `Chain ID:`
+   * value (`solana:mainnet`, ...) unless given a string; a number there is a
+   * connector's synthetic chain id and is ignored.
+   */
+  chainId?: number | string;
+  version?: string;
+}
+
+interface FamilySpec {
+  header: string;
+  statement: string | null;
+  chainId: string | null;
+  normalize?: (address: string) => string;
+}
+
+const specs: Record<WalletMessageFamily, FamilySpec> = {
+  eth: {
+    header: "wants you to sign in with your Ethereum account:",
+    statement: "Sign in With Ethereum.",
+    chainId: "1",
+    normalize: (address) => getAddress(address),
+  },
+  sol: {
+    header: "wants you to sign in with your Solana account:",
+    statement: "Sign in With Solana.",
+    chainId: "solana:mainnet",
+  },
+  sui: {
+    header: "wants you to sign in with your Sui account:",
+    statement: "Sign in With Sui.",
+    chainId: "sui:mainnet",
+  },
+  btc: {
+    header: "wants you to sign in with your Bitcoin account:",
+    statement: "Sign in With Bitcoin.",
+    chainId: "bitcoin",
+  },
+  gpg: {
+    header: "wants you to sign in with your GPG key.",
+    statement: null,
+    chainId: null,
+  },
+};
+
+const aliases: Record<SignerFamily, WalletMessageFamily> = {
+  eth: "eth",
+  sol: "sol",
+  sui: "sui",
+  btc: "btc",
+  gpg: "gpg",
+  evm: "eth",
+  solana: "sol",
+  bitcoin: "btc",
+};
+
+/** Map an ecosystem name (`evm`, `solana`, `bitcoin`) or a short family to the short family. */
+export function toWalletMessageFamily(family: SignerFamily): WalletMessageFamily {
+  const resolved = aliases[family];
+  if (!resolved) throw new Error(`unknown wallet message family: ${String(family)}`);
+  return resolved;
+}
+
+function singleLine(field: string, value: string | null | undefined) {
+  if (value && /[\r\n]/.test(value)) {
+    throw new Error(`buildWalletMessage: ${field} must be a single line`);
+  }
+}
+
+function pageLocation(): { host: string; origin: string } {
+  const location = (globalThis as { location?: { host?: string; origin?: string } }).location;
+  return { host: location?.host ?? "", origin: location?.origin ?? "" };
+}
+
+/**
+ * Build the sign-in message for one signer family. This is the only builder in
+ * mpo web3: EIP-4361 for `eth` (EIP-55 address, no optional fields), SIWS for
+ * `sol`, and the same envelope for `sui`, `btc` and `gpg`, in the exact bytes
+ * the Keycloak verifiers parse.
+ */
+export function buildWalletMessage(family: SignerFamily, opts: WalletMessageOptions): string {
+  const key = toWalletMessageFamily(family);
+  const spec = specs[key];
+  const page = pageLocation();
+  const domain = opts.domain ?? page.host;
+  if (!domain) {
+    throw new Error(
+      "buildWalletMessage: no domain. Pass opts.domain; a file:// or native page has no host.",
+    );
+  }
+  const pageOrigin = page.origin && page.origin !== "null" ? page.origin : "";
+  const uri = opts.uri ?? (pageOrigin || `https://${domain}`);
+  const statement = opts.statement === undefined ? spec.statement : opts.statement;
+  singleLine("domain", domain);
+  singleLine("uri", uri);
+  singleLine("statement", statement);
+  const lines = [`${domain} ${spec.header}`];
+  if (key !== "gpg") {
+    if (!opts.address) throw new Error(`buildWalletMessage: ${key} needs an address`);
+    lines.push(spec.normalize ? spec.normalize(opts.address) : opts.address);
+  }
+  lines.push("");
+  if (statement) lines.push(statement, "");
+  else if (key === "eth") lines.push("");
+  lines.push(`URI: ${uri}`, `Version: ${opts.version ?? "1"}`);
+  if (spec.chainId !== null) {
+    const chainId =
+      key === "eth"
+        ? (opts.chainId ?? spec.chainId)
+        : typeof opts.chainId === "string"
+          ? opts.chainId
+          : spec.chainId;
+    lines.push(`Chain ID: ${chainId}`);
+  }
+  lines.push(`Nonce: ${opts.nonce}`, `Issued At: ${opts.issuedAt ?? new Date().toISOString()}`);
+  return lines.join("\n");
+}

package/src/message/index.ts

@@ -0,0 +1,8 @@
+export {
+  buildWalletMessage,
+  toWalletMessageFamily,
+  type SignerFamily,
+  type WalletMessageEcosystem,
+  type WalletMessageFamily,
+  type WalletMessageOptions,
+} from "./buildWalletMessage";