@multiplatform.one/web3 7.23.1 → 7.24.0

package/src/keycloak/KeycloakWalletLogin.spec.tsx

@@ -0,0 +1,168 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createConfig, createStorage, http } from "wagmi";
+import { mainnet } from "wagmi/chains";
+import { mock } from "wagmi/connectors";
+import { KeycloakWalletLogin, type KeycloakWalletLoginProps } from "./KeycloakWalletLogin";
+
+const ANDROID_UA =
+  "Mozilla/5.0 (Linux; Android 16; Pixel 9) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36";
+const DESKTOP_UA =
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36";
+const ACCOUNT = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
+const LOGIN_ACTION =
+  "https://kc.example.com/realms/main/login-actions/authenticate?session_code=sc&execution=ex&client_id=promanager&tab_id=tb";
+const PGP_BLOB =
+  "-----BEGIN PGP SIGNATURE-----\nsig\n-----END PGP SIGNATURE-----\n-----BEGIN PGP PUBLIC KEY BLOCK-----\nkey\n-----END PGP PUBLIC KEY BLOCK-----";
+
+function setUserAgent(ua: string) {
+  Object.defineProperty(window.navigator, "userAgent", { value: ua, configurable: true });
+}
+
+function memoryStorage() {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key: string) => map.get(key) ?? null,
+    setItem: (key: string, value: string) => void map.set(key, value),
+    removeItem: (key: string) => void map.delete(key),
+  };
+}
+
+function makeConfig() {
+  return createConfig({
+    chains: [mainnet],
+    connectors: [mock({ accounts: [ACCOUNT], features: {} })],
+    transports: { [mainnet.id]: http() },
+    storage: createStorage({ storage: memoryStorage() }),
+  });
+}
+
+function renderLogin(props: KeycloakWalletLoginProps = {}) {
+  const config = props.wagmiConfig ?? makeConfig();
+  const connectSpy = vi.spyOn(config.connectors[0], "connect");
+  render(
+    <KeycloakWalletLogin
+      baseUrl="https://kc.example.com"
+      realm="main"
+      resource="wallet"
+      wagmiConfig={config}
+      {...props}
+    />,
+  );
+  const walletButton = document.getElementById("mpo-wallet-login") as HTMLButtonElement;
+  return { config, connectSpy, walletButton };
+}
+
+const nonceRequests: string[] = [];
+
+beforeEach(() => {
+  nonceRequests.length = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/nonce")) {
+        nonceRequests.push(url);
+        return new Response("nonce123abc");
+      }
+      return new Response("not found", { status: 404 });
+    }),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  window.sessionStorage.clear();
+  document.querySelectorAll("form").forEach((form) => form.remove());
+  setUserAgent(DESKTOP_UA);
+});
+
+describe("KeycloakWalletLogin mobile.preferredConnector", () => {
+  it("a phone's tap goes straight to the preferred wallet, starting its connect inside the tap", async () => {
+    setUserAgent(ANDROID_UA);
+    const { config, connectSpy, walletButton } = renderLogin({
+      mobile: { preferredConnector: "mock" },
+    });
+
+    fireEvent.click(walletButton);
+    // Still inside the click's task: only microtasks have run, no timer.
+    for (let i = 0; i < 50 && connectSpy.mock.calls.length === 0; i++) await Promise.resolve();
+
+    expect(connectSpy).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText("Mock Connector")).not.toBeNull();
+    expect(document.querySelector("[data-screen-entry]")).toBeNull();
+    await waitFor(() => expect(config.state.status).toBe("connected"));
+  });
+
+  it("desktop keeps the wallet list and connects nothing on the tap", async () => {
+    setUserAgent(DESKTOP_UA);
+    const { connectSpy, walletButton } = renderLogin({ mobile: { preferredConnector: "mock" } });
+
+    fireEvent.click(walletButton);
+
+    await screen.findByText("Mock Connector");
+    expect(document.querySelector('[data-screen-entry="signInWithGpg"]')).not.toBeNull();
+    expect(connectSpy).not.toHaveBeenCalled();
+  });
+
+  it("a phone with no preferred connector gets the wallet list", async () => {
+    setUserAgent(ANDROID_UA);
+    const { connectSpy, walletButton } = renderLogin();
+
+    fireEvent.click(walletButton);
+
+    await screen.findByText("Mock Connector");
+    expect(connectSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("KeycloakWalletLogin gpg", () => {
+  it("gpg: false drops the GPG button and the GPG row in the wallet list", async () => {
+    const { walletButton } = renderLogin({ gpg: false });
+    expect(document.getElementById("mpo-gpg-login")).toBeNull();
+
+    fireEvent.click(walletButton);
+
+    await screen.findByText("Mock Connector");
+    expect(document.querySelector('[data-screen-entry="signInWithGpg"]')).toBeNull();
+    expect(screen.queryByText("GPG")).toBeNull();
+  });
+
+  it("offers GPG by default, as a button and as a row in the wallet list", async () => {
+    const { walletButton } = renderLogin();
+    expect(document.getElementById("mpo-gpg-login")).not.toBeNull();
+
+    fireEvent.click(walletButton);
+
+    await screen.findByText("Mock Connector");
+    expect(document.querySelector('[data-screen-entry="signInWithGpg"]')).not.toBeNull();
+  });
+});
+
+describe("KeycloakWalletLogin target", () => {
+  it("{ action } posts the credential to a keycloakify page's login action", async () => {
+    const submit = vi
+      .spyOn(HTMLFormElement.prototype, "submit")
+      .mockImplementation(function (this: HTMLFormElement) {});
+    renderLogin({ target: { action: LOGIN_ACTION } });
+
+    fireEvent.click(document.getElementById("mpo-gpg-login") as HTMLButtonElement);
+    const pasteBox = await screen.findByPlaceholderText(/BEGIN PGP SIGNATURE/);
+    await waitFor(() => expect(screen.queryByDisplayValue(/nonce123abc/)).not.toBeNull());
+    fireEvent.change(pasteBox, { target: { value: PGP_BLOB } });
+    fireEvent.click(screen.getByText("Sign in"));
+
+    await waitFor(() => expect(submit).toHaveBeenCalledTimes(1));
+    const form = submit.mock.contexts[0] as HTMLFormElement;
+    expect(form.action).toBe(LOGIN_ACTION);
+    expect(form.method).toBe("post");
+    const field = (name: string) =>
+      (form.querySelector(`input[name="${name}"]`) as HTMLInputElement | null)?.value;
+    expect(atob(field("username") ?? "")).toBe(PGP_BLOB);
+    expect(atob(field("password") ?? "")).toContain("nonce123abc");
+    expect(nonceRequests).toEqual(["https://kc.example.com/realms/main/wallet/nonce"]);
+  });
+});

package/src/keycloak/KeycloakWalletLogin.tsx

@@ -0,0 +1,251 @@
+import { GpgProvider } from "@multiplatform.one/gpg";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { type CSSProperties, useMemo } from "react";
+import type { Chain } from "viem";
+import { type Config, WagmiProvider, createConfig } from "wagmi";
+import { arbitrum, mainnet, optimism, polygon } from "wagmi/chains";
+import getDefaultConfig from "../connectkit/defaultConfig";
+import { SIWEProvider } from "../connectkit/siwe";
+import { StatusState } from "../connectkit/siwe/SIWEContext";
+import { useWeb3Modal } from "../connectkit/useWeb3Modal";
+import type { MobileConnectOptions } from "../connectkit/openConnector";
+import { ConnectKitProvider } from "../connectkit/web3Provider";
+import type { BrowserFlowOptions } from "./browserFlow";
+import { deriveKeycloakFromLocation, keycloakWallet } from "./keycloakWallet";
+import type { KeycloakWalletResource } from "./types";
+import { useWalletLogin } from "./useWalletLogin";
+
+export interface KeycloakWalletLoginProps {
+  /** Defaults to the Keycloak base of the page it runs on. */
+  baseUrl?: string;
+  /** Defaults to the realm of the page it runs on. */
+  realm?: string;
+  resource?: KeycloakWalletResource;
+  domain?: string;
+  uri?: string;
+  target?: BrowserFlowOptions["target"];
+  whenVisible?: boolean;
+  appName?: string;
+  appDescription?: string;
+  appUrl?: string;
+  appIcon?: string;
+  chains?: readonly [Chain, ...Chain[]];
+  /** Offer GPG sign-in: its button and its row in the wallet list. Default true. */
+  gpg?: boolean;
+  /**
+   * Phone behaviour of the wallet button. `{ preferredConnector: "metaMaskSDK" }`
+   * sends a phone straight to MetaMask from the tap, skipping the wallet list.
+   */
+  mobile?: MobileConnectOptions;
+  walletLabel?: string;
+  gpgLabel?: string;
+  className?: string;
+  /** Replaces the built-in button look, e.g. the theme's `kcButtonClass`. */
+  buttonClassName?: string;
+  /** The wagmi config to sign with; built from the app props and `chains` when absent. */
+  wagmiConfig?: Config;
+}
+
+const defaultChains: readonly [Chain, ...Chain[]] = [mainnet, polygon, optimism, arbitrum];
+
+/** The wagmi config `<KeycloakWalletLogin>` builds when it is given none. */
+export function createKeycloakWalletConfig({
+  appName = "Sign in",
+  appDescription = "Sign in with your wallet",
+  appUrl = (globalThis as { location?: Location }).location?.origin ?? "",
+  appIcon,
+  chains = defaultChains,
+}: Pick<
+  KeycloakWalletLoginProps,
+  "appName" | "appDescription" | "appUrl" | "appIcon" | "chains"
+> = {}): Config {
+  return createConfig(
+    getDefaultConfig({
+      appName,
+      appDescription,
+      appUrl,
+      appIcon,
+      chains,
+      // Aave Account signs through an app.family.co iframe, which a Keycloak
+      // page's default CSP (frame-src 'self') blocks.
+      enableAaveAccount: false,
+    }),
+  );
+}
+
+const buttonStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: 8,
+  width: "100%",
+  padding: "10px 14px",
+  marginTop: 8,
+  fontSize: 14,
+  cursor: "pointer",
+  border: "1px solid #c4c4c4",
+  borderRadius: 4,
+  background: "#fff",
+};
+
+/**
+ * Wallet and GPG sign-in for a Keycloak login page, on the browser flow: the
+ * signed credential posts to the page's authenticator. Carries its own wagmi,
+ * query client and ConnectKit modal, so it drops into any theme; a page that is
+ * not React 19 mounts it with the IIFE build's `MpoKeycloakWallet.mount`.
+ */
+export function KeycloakWalletLogin(props: KeycloakWalletLoginProps) {
+  const {
+    resource,
+    domain,
+    uri,
+    target = "ftl",
+    whenVisible = true,
+    appName,
+    appDescription,
+    appUrl,
+    appIcon,
+    chains,
+    gpg = true,
+    mobile,
+    wagmiConfig,
+  } = props;
+  const page = deriveKeycloakFromLocation();
+  const baseUrl = props.baseUrl ?? page?.baseUrl;
+  const realm = props.realm ?? page?.realm;
+  if (!baseUrl || !realm) {
+    throw new Error("KeycloakWalletLogin needs baseUrl and realm off a Keycloak page");
+  }
+  const action = typeof target === "string" ? undefined : target.action;
+
+  const kc = useMemo(
+    () => keycloakWallet({ baseUrl, realm, resource, domain, uri }),
+    [baseUrl, realm, resource, domain, uri],
+  );
+  const browserTarget = useMemo<BrowserFlowOptions["target"]>(
+    () => (action === undefined ? "ftl" : { action }),
+    [action],
+  );
+  const onSign = useMemo(
+    () => kc.browserFlow({ target: browserTarget, whenVisible }),
+    [kc, browserTarget, whenVisible],
+  );
+  const config = useMemo(
+    () =>
+      wagmiConfig ??
+      createKeycloakWalletConfig({ appName, appDescription, appUrl, appIcon, chains }),
+    [wagmiConfig, appName, appDescription, appUrl, appIcon, chains],
+  );
+  const connectKitOptions = useMemo(() => (mobile ? { mobile } : undefined), [mobile]);
+  const queryClient = useMemo(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: { refetchOnWindowFocus: false, refetchOnReconnect: false, staleTime: Infinity },
+        },
+      }),
+    [],
+  );
+
+  return (
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>
+        <GpgProvider {...kc.gpgConfig(onSign)} enabled={gpg}>
+          <SIWEProvider {...kc.siweConfig(onSign)}>
+            <ConnectKitProvider options={connectKitOptions}>
+              <LoginButtons {...props} />
+            </ConnectKitProvider>
+          </SIWEProvider>
+        </GpgProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}
+
+function LoginButtons({
+  gpg = true,
+  walletLabel = "Sign in with Wallet",
+  gpgLabel = "Sign in with GPG",
+  className,
+  buttonClassName,
+}: KeycloakWalletLoginProps) {
+  const { login, status } = useWalletLogin();
+  const { openGpg } = useWeb3Modal();
+  const style = buttonClassName ? undefined : buttonStyle;
+  const busy = status === StatusState.LOADING || status === StatusState.SUCCESS;
+  return (
+    <div className={className ?? "mpo-keycloak-wallet-login"}>
+      <button
+        type="button"
+        id="mpo-wallet-login"
+        className={buttonClassName}
+        style={style}
+        disabled={busy}
+        onClick={(e) => {
+          e.preventDefault();
+          void login();
+        }}
+      >
+        <WalletIcon />
+        <span>{busy ? "Signing…" : walletLabel}</span>
+      </button>
+      {gpg && (
+        <button
+          type="button"
+          id="mpo-gpg-login"
+          className={buttonClassName}
+          style={style}
+          onClick={(e) => {
+            e.preventDefault();
+            openGpg();
+          }}
+        >
+          <GpgIcon />
+          <span>{gpgLabel}</span>
+        </button>
+      )}
+    </div>
+  );
+}
+
+function WalletIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M19 7V4a1 1 0 0 0-1-1H5a2 2 0 0 0-2 2v0a2 2 0 0 0 2 2h13a1 1 0 0 1 1 1v4" />
+      <path d="M3 5v14a2 2 0 0 0 2 2h15a1 1 0 0 0 1-1v-4" />
+      <rect width="7" height="5" x="14" y="10" rx="1" />
+    </svg>
+  );
+}
+
+function GpgIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="7.5" cy="15.5" r="5.5" />
+      <path d="m21 2-9.6 9.6" />
+      <path d="m15.5 7.5 3 3L22 7l-3-3" />
+    </svg>
+  );
+}

package/src/keycloak/browserFlow.spec.ts

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { browserFlow } from "./browserFlow";
+
+let visibility: DocumentVisibilityState = "visible";
+const credentials = { username: "0xsig", password: "bWVzc2FnZQ==", message: "message" };
+
+function setVisibility(next: DocumentVisibilityState) {
+  visibility = next;
+  document.dispatchEvent(new Event("visibilitychange"));
+}
+
+function ftlPage() {
+  document.body.innerHTML = `
+    <form id="kc-form-login" action="https://kc.example.com/realms/main/login-actions/authenticate" method="post">
+      <input id="username" name="username" />
+      <input id="password" name="password" type="password" />
+    </form>`;
+  return document.getElementById("kc-form-login") as HTMLFormElement;
+}
+
+describe("browserFlow", () => {
+  let submitted: HTMLFormElement[];
+
+  beforeEach(() => {
+    visibility = "visible";
+    Object.defineProperty(document, "visibilityState", {
+      configurable: true,
+      get: () => visibility,
+    });
+    submitted = [];
+    vi.spyOn(HTMLFormElement.prototype, "submit").mockImplementation(
+      function (this: HTMLFormElement) {
+        submitted.push(this);
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    document.body.innerHTML = "";
+  });
+
+  it("ftl: writes the credential into the login form and submits it", async () => {
+    const form = ftlPage();
+    await expect(browserFlow()(credentials)).resolves.toBe(true);
+    expect(submitted).toEqual([form]);
+    expect((document.getElementById("username") as HTMLInputElement).value).toBe("0xsig");
+    expect((document.getElementById("password") as HTMLInputElement).value).toBe("bWVzc2FnZQ==");
+  });
+
+  it("ftl: resolves false when the page has no login form", async () => {
+    await expect(browserFlow()(credentials)).resolves.toBe(false);
+    expect(submitted).toEqual([]);
+  });
+
+  it("action: posts through a hidden form of its own and leaves the page's fields alone", async () => {
+    ftlPage();
+    const action = "https://kc.example.com/realms/main/login-actions/authenticate?session_code=x";
+    await browserFlow({ target: { action } })(credentials);
+    expect(submitted).toHaveLength(1);
+    const [form] = submitted;
+    expect(form.id).toBe("");
+    expect(form.action).toBe(action);
+    expect(form.method).toBe("post");
+    expect(form.style.display).toBe("none");
+    expect(Object.fromEntries(new FormData(form))).toEqual({
+      username: "0xsig",
+      password: "bWVzc2FnZQ==",
+    });
+    expect((document.getElementById("username") as HTMLInputElement).value).toBe("");
+  });
+
+  it("whenVisible: a signature that lands while the page is hidden waits until it shows", async () => {
+    ftlPage();
+    setVisibility("hidden");
+    let settled = false;
+    const done = browserFlow()(credentials).then((result) => {
+      settled = true;
+      return result;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(settled).toBe(false);
+    expect(submitted).toEqual([]);
+    setVisibility("hidden");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(submitted).toEqual([]);
+    setVisibility("visible");
+    await expect(done).resolves.toBe(true);
+    expect(submitted).toHaveLength(1);
+  });
+
+  it("whenVisible false submits at once, even hidden", async () => {
+    ftlPage();
+    setVisibility("hidden");
+    await expect(browserFlow({ whenVisible: false })(credentials)).resolves.toBe(true);
+    expect(submitted).toHaveLength(1);
+  });
+
+  it("submits once: a late second credential (a re-driven signature) does not post again", async () => {
+    ftlPage();
+    const onSign = browserFlow();
+    await onSign(credentials);
+    await expect(onSign({ ...credentials, username: "0xother" })).resolves.toBe(true);
+    expect(submitted).toHaveLength(1);
+    expect((document.getElementById("username") as HTMLInputElement).value).toBe("0xsig");
+  });
+});

package/src/keycloak/browserFlow.ts

@@ -0,0 +1,84 @@
+import type { OnSign } from "./types";
+
+export interface BrowserFlowOptions {
+  /**
+   * `ftl`: write the credential into the login page's own `#kc-form-login`
+   * (`#username` / `#password`) and submit it. `{ action }`: post it through a
+   * hidden form of its own to that login-action URL, leaving the page's
+   * visible fields alone.
+   */
+  target?: "ftl" | { action: string };
+  /**
+   * Hold the submit until the page is visible. Chrome on Android drops the
+   * redirect back to the app while the tab is in the background, so a
+   * signature that lands before the user switches back waits. Default true.
+   */
+  whenVisible?: boolean;
+  document?: Document;
+}
+
+function whenPageVisible(doc: Document): Promise<void> {
+  if (doc.visibilityState !== "hidden") return Promise.resolve();
+  return new Promise((resolve) => {
+    const onChange = () => {
+      if (doc.visibilityState === "hidden") return;
+      doc.removeEventListener("visibilitychange", onChange);
+      resolve();
+    };
+    doc.addEventListener("visibilitychange", onChange);
+  });
+}
+
+function ftlForm(doc: Document, username: string, password: string): HTMLFormElement | null {
+  const form = doc.getElementById("kc-form-login") as HTMLFormElement | null;
+  const user = doc.getElementById("username") as HTMLInputElement | null;
+  const pass = doc.getElementById("password") as HTMLInputElement | null;
+  if (!form || !user || !pass) return null;
+  user.value = username;
+  pass.value = password;
+  return form;
+}
+
+function actionForm(doc: Document, action: string, username: string, password: string) {
+  const form = doc.createElement("form");
+  form.method = "post";
+  form.action = action;
+  form.style.display = "none";
+  for (const [name, value] of [
+    ["username", username],
+    ["password", password],
+  ]) {
+    const input = doc.createElement("input");
+    input.type = "hidden";
+    input.name = name;
+    input.value = value;
+    form.appendChild(input);
+  }
+  doc.body.appendChild(form);
+  return form;
+}
+
+/**
+ * `onSign` for a Keycloak login page: posts the signed credential to the
+ * browser flow's authenticator, which verifies it and finishes the login. Pass
+ * it to `<SIWEProvider onSign>` or `<GpgProvider onSign>`. Resolves false when
+ * the `ftl` form is missing; a second credential after a submit is ignored.
+ */
+export function browserFlow(opts: BrowserFlowOptions = {}): OnSign {
+  const { target = "ftl", whenVisible = true } = opts;
+  let submitted = false;
+  return async ({ username, password }) => {
+    const doc = opts.document ?? (globalThis as { document?: Document }).document;
+    if (!doc) throw new Error("browserFlow needs a DOM");
+    if (whenVisible) await whenPageVisible(doc);
+    if (submitted) return true;
+    const form =
+      target === "ftl"
+        ? ftlForm(doc, username, password)
+        : actionForm(doc, target.action, username, password);
+    if (!form) return false;
+    submitted = true;
+    form.submit();
+    return true;
+  };
+}

package/src/keycloak/device.ts

@@ -0,0 +1,17 @@
+type NavigatorLike = {
+  userAgent?: string;
+  userAgentData?: { mobile?: boolean };
+  userActivation?: { isActive: boolean };
+};
+
+const nav = () => (globalThis as { navigator?: NavigatorLike }).navigator;
+
+export function isMobileBrowser(navigator: NavigatorLike | undefined = nav()): boolean {
+  if (typeof navigator?.userAgentData?.mobile === "boolean") return navigator.userAgentData.mobile;
+  return /Android|iPhone|iPad|iPod/i.test(navigator?.userAgent ?? "");
+}
+
+/** Whether the page holds a user gesture; true where the browser does not report it. */
+export function hasUserActivation(navigator: NavigatorLike | undefined = nav()): boolean {
+  return navigator?.userActivation ? navigator.userActivation.isActive : true;
+}