@multiplatform.one/web3 7.24.0 → 7.26.0

package/src/core/index.ts

@@ -0,0 +1,47 @@
+// Core contracts of mpo web3 (MPO-385): the family registry, the connection
+// driver interface, the connection store and the message registry. Nothing here
+// imports a chain SDK; each family package brings its own driver and message.
+export {
+  createFamilyRegistry,
+  defineWalletFamily,
+  type FamilyRegistry,
+  type WalletFamily,
+  type WalletFamilyDefinition,
+} from "./family";
+export {
+  createMessageRegistry,
+  formatWalletMessage,
+  type MessageFamily,
+  type WalletMessageRegistry,
+  type WalletMessageSpec,
+} from "./message";
+export {
+  createConnectionStore,
+  defaultConnectionStorageKey,
+  type ConnectionStore,
+  type ConnectionStoreOptions,
+  type FamilyConnector,
+} from "./store";
+export {
+  ConnectionProvider,
+  useConnection,
+  useConnectionStore,
+  type ConnectionProviderProps,
+} from "./react";
+export type {
+  ConnectionDriver,
+  ConnectionState,
+  ConnectionStatus,
+  ConnectionStorage,
+  DriverAccount,
+  DriverConnectOptions,
+  DriverState,
+  SavedConnection,
+  WalletConnector,
+} from "./types";
+export {
+  UnsupportedClientMethodError,
+  type ChainClient,
+  type ClientCapability,
+  type ClientFamily,
+} from "../clients/types";

package/src/core/message.spec.ts

@@ -0,0 +1,178 @@
+import { getAddress } from "viem";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildWalletMessage, type SignerFamily } from "../message/buildWalletMessage";
+import { createMessageRegistry, formatWalletMessage, type MessageFamily } from "./message";
+
+// The five families as their packages will register them. Kept in step with
+// buildWalletMessage, which every Keycloak golden test already pins.
+const families: MessageFamily[] = [
+  {
+    id: "eth",
+    aliases: ["evm"],
+    message: {
+      header: "wants you to sign in with your Ethereum account:",
+      statement: "Sign in With Ethereum.",
+      chainId: "1",
+      numericChainId: true,
+      keepStatementLine: true,
+      normalizeAddress: (address) => getAddress(address),
+    },
+  },
+  {
+    id: "sol",
+    aliases: ["solana"],
+    message: {
+      header: "wants you to sign in with your Solana account:",
+      statement: "Sign in With Solana.",
+      chainId: "solana:mainnet",
+    },
+  },
+  {
+    id: "sui",
+    message: {
+      header: "wants you to sign in with your Sui account:",
+      statement: "Sign in With Sui.",
+      chainId: "sui:mainnet",
+    },
+  },
+  {
+    id: "btc",
+    aliases: ["bitcoin"],
+    message: {
+      header: "wants you to sign in with your Bitcoin account:",
+      statement: "Sign in With Bitcoin.",
+      chainId: "bitcoin",
+    },
+  },
+  {
+    id: "gpg",
+    message: {
+      header: "wants you to sign in with your GPG key.",
+      statement: null,
+      chainId: null,
+      address: false,
+    },
+  },
+];
+
+const registry = createMessageRegistry(families);
+const names: SignerFamily[] = ["eth", "evm", "sol", "solana", "sui", "btc", "bitcoin", "gpg"];
+const base = {
+  domain: "app.multiplatform.one",
+  uri: "https://app.multiplatform.one/login",
+  nonce: "ohY7vD2Kq9",
+  issuedAt: "2026-09-26T20:48:18.648Z",
+  address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
+};
+
+const outcome = (build: () => string) => {
+  try {
+    return { message: build() };
+  } catch {
+    return { threw: true };
+  }
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("the core message registry", () => {
+  it("builds the same bytes as buildWalletMessage for every family, alias and option", () => {
+    let compared = 0;
+    for (const family of names) {
+      for (const statement of [undefined, null, "", "Custom statement."]) {
+        for (const chainId of [undefined, 137, "solana:devnet", 900001]) {
+          for (const version of [undefined, "2"]) {
+            const opts = { ...base, statement, chainId, version };
+            expect(registry.build(family, opts), `${family} ${JSON.stringify(opts)}`).toBe(
+              buildWalletMessage(family, opts),
+            );
+            compared++;
+          }
+        }
+      }
+    }
+    expect(compared).toBe(256);
+  });
+
+  it("refuses what buildWalletMessage refuses", () => {
+    for (const family of names) {
+      for (const opts of [
+        { ...base, address: undefined },
+        { ...base, domain: "evil.example\nURI: https://evil.example" },
+        { ...base, uri: "https://a\nb" },
+        { ...base, statement: "two\nlines" },
+      ]) {
+        expect(outcome(() => registry.build(family, opts))).toEqual(
+          outcome(() => buildWalletMessage(family, opts)),
+        );
+      }
+    }
+  });
+
+  it("takes domain and uri from the page like buildWalletMessage", () => {
+    for (const location of [
+      { host: "shop.example", origin: "https://shop.example" },
+      { host: "file.example", origin: "null" },
+      { host: "", origin: "" },
+    ]) {
+      vi.stubGlobal("location", location);
+      for (const family of names) {
+        const opts = { nonce: base.nonce, issuedAt: base.issuedAt, address: base.address };
+        expect(outcome(() => registry.build(family, opts))).toEqual(
+          outcome(() => buildWalletMessage(family, opts)),
+        );
+      }
+    }
+  });
+
+  it("resolves aliases and lists families in registration order", () => {
+    expect(registry.families).toEqual(["eth", "sol", "sui", "btc", "gpg"]);
+    expect(registry.resolve("evm")).toBe("eth");
+    expect(registry.resolve("cosmos")).toBeUndefined();
+    expect(registry.spec("bitcoin")?.chainId).toBe("bitcoin");
+  });
+
+  it("names the registered families when asked for another", () => {
+    expect(() => registry.build("cosmos", base)).toThrow(
+      "no wallet message for family cosmos; registered: eth, sol, sui, btc, gpg",
+    );
+    expect(() => createMessageRegistry([]).build("eth", base)).toThrow(/registered: none/);
+  });
+
+  it("a new family needs only a spec", () => {
+    const cosmos = createMessageRegistry([
+      {
+        id: "cosmos",
+        message: {
+          header: "wants you to sign in with your Cosmos account:",
+          statement: "Sign in With Cosmos.",
+          chainId: "cosmoshub-4",
+        },
+      },
+    ]);
+    expect(cosmos.build("cosmos", { ...base, address: "cosmos1abc" }).split("\n")).toEqual([
+      "app.multiplatform.one wants you to sign in with your Cosmos account:",
+      "cosmos1abc",
+      "",
+      "Sign in With Cosmos.",
+      "",
+      "URI: https://app.multiplatform.one/login",
+      "Version: 1",
+      "Chain ID: cosmoshub-4",
+      "Nonce: ohY7vD2Kq9",
+      "Issued At: 2026-09-26T20:48:18.648Z",
+    ]);
+  });
+
+  it("formatWalletMessage names the family in its errors", () => {
+    expect(() =>
+      formatWalletMessage(
+        { header: "wants you to sign in:", statement: null, chainId: null },
+        { ...base, address: undefined },
+        "sol",
+      ),
+    ).toThrow("wallet message: sol needs an address");
+  });
+});

package/src/core/message.ts

@@ -0,0 +1,119 @@
+import type { WalletMessageOptions } from "../message/buildWalletMessage";
+import { nameTable } from "./names";
+
+/**
+ * How one family's sign-in message differs from the shared envelope. A family
+ * package defines its spec; the envelope (domain line, statement, URI, Version,
+ * Chain ID, Nonce, Issued At) is the same bytes the Keycloak verifiers parse.
+ */
+export interface WalletMessageSpec {
+  /** First-line text after the domain, which the verifiers content-sniff. */
+  readonly header: string;
+  /** Default statement. Null means none. */
+  readonly statement: string | null;
+  /** The `Chain ID:` value when the caller gives none. Null omits the line. */
+  readonly chainId: string | null;
+  /** Whether the message names the signer's address. GPG's identity is its key. Default true. */
+  readonly address?: boolean;
+  /**
+   * Honour a numeric `chainId` option. Only EVM chain ids are numbers; elsewhere
+   * a number is a connector's synthetic id and is ignored.
+   */
+  readonly numericChainId?: boolean;
+  /** EIP-4361 keeps an empty line where an omitted statement would be. */
+  readonly keepStatementLine?: boolean;
+  /** Canonical address form, such as EIP-55 for EVM. */
+  readonly normalizeAddress?: (address: string) => string;
+}
+
+export interface MessageFamily {
+  readonly id: string;
+  readonly aliases?: readonly string[];
+  readonly message: WalletMessageSpec;
+}
+
+export interface WalletMessageRegistry {
+  /** Registered family ids, in registration order. */
+  readonly families: readonly string[];
+  /** The family id for an id or alias, or undefined. */
+  resolve(family: string): string | undefined;
+  spec(family: string): WalletMessageSpec | undefined;
+  /** Builds the sign-in message. Throws for a family nobody registered. */
+  build(family: string, opts: WalletMessageOptions): string;
+}
+
+function singleLine(field: string, value: string | null | undefined) {
+  if (value && /[\r\n]/.test(value)) {
+    throw new Error(`wallet message: ${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 ?? "" };
+}
+
+/** Builds one sign-in message from a family spec. `family` only names the family in errors. */
+export function formatWalletMessage(
+  spec: WalletMessageSpec,
+  opts: WalletMessageOptions,
+  family = "wallet",
+): string {
+  const page = pageLocation();
+  const domain = opts.domain ?? page.host;
+  if (!domain) {
+    throw new Error(
+      "wallet message: 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 (spec.address !== false) {
+    if (!opts.address) throw new Error(`wallet message: ${family} needs an address`);
+    lines.push(spec.normalizeAddress ? spec.normalizeAddress(opts.address) : opts.address);
+  }
+  lines.push("");
+  if (statement) lines.push(statement, "");
+  else if (spec.keepStatementLine) lines.push("");
+  lines.push(`URI: ${uri}`, `Version: ${opts.version ?? "1"}`);
+  if (spec.chainId !== null) {
+    const chainId = spec.numericChainId
+      ? (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");
+}
+
+/** The message half of the family registry: family id or alias to spec. */
+export function createMessageRegistry(families: Iterable<MessageFamily>): WalletMessageRegistry {
+  const list = [...families];
+  const names = nameTable(list);
+  const specs = new Map(list.map((family) => [family.id, family.message]));
+  const spec = (family: string) => {
+    const id = names.get(family);
+    return id === undefined ? undefined : specs.get(id);
+  };
+  return {
+    families: list.map((family) => family.id),
+    resolve: (family) => names.get(family),
+    spec,
+    build(family, opts) {
+      const found = spec(family);
+      if (found === undefined) {
+        throw new Error(
+          `no wallet message for family ${family}; registered: ${list.map((entry) => entry.id).join(", ") || "none"}`,
+        );
+      }
+      return formatWalletMessage(found, opts, names.get(family));
+    },
+  };
+}

package/src/core/names.ts

@@ -0,0 +1,29 @@
+const pattern = /^[a-z][a-z0-9-]*$/;
+
+export function assertName(kind: string, name: unknown): asserts name is string {
+  if (typeof name !== "string" || !pattern.test(name)) {
+    throw new Error(`${kind} must be lowercase letters, digits and dashes: ${String(name)}`);
+  }
+}
+
+/** Maps every id and alias to its entry's id, refusing a name two entries claim. */
+export function nameTable(
+  entries: Iterable<{ readonly id: string; readonly aliases?: readonly string[] }>,
+): Map<string, string> {
+  const table = new Map<string, string>();
+  const claim = (name: string, id: string) => {
+    const owner = table.get(name);
+    if (owner === undefined) table.set(name, id);
+    else if (owner !== id) {
+      throw new Error(`wallet family name "${name}" is claimed by ${owner} and ${id}`);
+    }
+  };
+  for (const entry of entries) {
+    if (table.get(entry.id) === entry.id) {
+      throw new Error(`wallet family ${entry.id} is registered twice`);
+    }
+    claim(entry.id, entry.id);
+    for (const alias of entry.aliases ?? []) claim(alias, entry.id);
+  }
+  return table;
+}

package/src/core/react.spec.tsx

@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import { testDriver } from "../../tests/core/testDriver";
+import { defineWalletFamily } from "./family";
+import { ConnectionProvider, useConnection, useConnectionStore } from "./react";
+import { createConnectionStore } from "./store";
+
+function setup() {
+  const sol = testDriver("solana", [{ id: "phantom", name: "Phantom" }], {
+    phantom: { address: "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV", chainId: "solana:mainnet" },
+  });
+  const store = createConnectionStore({
+    storage: null,
+    families: [
+      defineWalletFamily({
+        id: "sol",
+        label: "Solana",
+        message: { header: "wants you to sign in:", statement: null, chainId: null },
+        driver: () => sol,
+      }),
+    ],
+  });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <ConnectionProvider store={store}>{children}</ConnectionProvider>
+  );
+  return { store, sol, wrapper };
+}
+
+describe("useConnection", () => {
+  it("renders the store's state and follows connect, account changes and disconnect", async () => {
+    const { store, sol, wrapper } = setup();
+    const { result } = renderHook(() => useConnection(), { wrapper });
+    expect(result.current.status).toBe("disconnected");
+
+    await act(() => store.connect("sol", "phantom"));
+    expect(result.current).toMatchObject({
+      status: "connected",
+      family: "sol",
+      connector: { id: "phantom", name: "Phantom" },
+      address: "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
+      chainId: "solana:mainnet",
+    });
+    expect(result.current.client?.family).toBe("solana");
+
+    act(() =>
+      sol.emit({
+        status: "connected",
+        connectorId: "phantom",
+        account: {
+          address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+          chainId: "solana:devnet",
+        },
+      }),
+    );
+    expect(result.current).toMatchObject({
+      address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+      chainId: "solana:devnet",
+    });
+
+    await act(() => store.disconnect());
+    expect(result.current.status).toBe("disconnected");
+  });
+
+  it("useConnectionStore hands back the provided store", () => {
+    const { store, wrapper } = setup();
+    const { result } = renderHook(() => useConnectionStore(), { wrapper });
+    expect(result.current).toBe(store);
+  });
+
+  it("refuses to run outside a ConnectionProvider", () => {
+    expect(() => renderHook(() => useConnection())).toThrow(/needs a ConnectionProvider/);
+  });
+});

package/src/core/react.ts

@@ -0,0 +1,34 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import type { ConnectionStore } from "./store";
+import type { ConnectionState } from "./types";
+
+const ConnectionStoreContext = createContext<ConnectionStore | null>(null);
+
+export interface ConnectionProviderProps {
+  store: ConnectionStore;
+  children?: ReactNode;
+}
+
+/** Makes one connection store the app's. Web3Provider mounts this once it owns a store. */
+export function ConnectionProvider({ store, children }: ConnectionProviderProps) {
+  return createElement(ConnectionStoreContext.Provider, { value: store }, children);
+}
+
+/** The store under the nearest ConnectionProvider, for connect, disconnect and reconnect. */
+export function useConnectionStore(): ConnectionStore {
+  const store = useContext(ConnectionStoreContext);
+  if (!store) throw new Error("useConnectionStore needs a ConnectionProvider above it");
+  return store;
+}
+
+/** The active connection: status, family, connector, address, chainId and client. */
+export function useConnection(): ConnectionState {
+  const store = useConnectionStore();
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}