@multiplatform.one/web3 7.25.0 → 7.26.0

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);
+}