@multiplatform.one/web3 7.23.1 → 7.24.0

package/src/keycloak/nonceReset.spec.tsx

@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+import { GpgContext, GpgProvider, type GpgContextValue } from "@multiplatform.one/gpg";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, render, renderHook, waitFor } from "@testing-library/react";
+import { connect } from "@wagmi/core";
+import { type ReactNode, useContext } from "react";
+import { describe, expect, it } from "vitest";
+import { WagmiProvider, createConfig, http } from "wagmi";
+import { mainnet } from "wagmi/chains";
+import { fakeKeycloak, json } from "../../tests/fakeKeycloak";
+import { SIWEProvider } from "../connectkit/siwe";
+import { SIWEContext, type SIWEContextValue } from "../connectkit/siwe/SIWEContext";
+import { createMockConnector } from "../providers/mockConnector";
+import { keycloakWallet } from "./keycloakWallet";
+import type { OnSign } from "./types";
+import { useDirectLogin } from "./useDirectLogin";
+
+/**
+ * A kc nonce is shared by SIWEProvider's and GpgProvider's cached copies. Every
+ * reset (a direct grant or registration that consumed it) must refetch both,
+ * or the next sign-in on either signs a nonce the server already dropped.
+ */
+function setup(
+  nonce: (n: number) => Response | Promise<Response> = (n) => new Response(`nonce-${n}`),
+) {
+  let issued = 0;
+  const server = fakeKeycloak({
+    "/nonce": () => {
+      issued += 1;
+      return nonce(issued);
+    },
+    "/register": () => json({ registered: true }),
+    "/protocol/openid-connect/token": () =>
+      json({ access_token: "at", refresh_token: "rt", expires_in: 300 }),
+  });
+  const kc = keycloakWallet({
+    baseUrl: "https://kc.example.com",
+    realm: "main",
+    domain: "app.example.com",
+    uri: "https://app.example.com",
+    fetch: server.fetch,
+  });
+  const config = createConfig({
+    chains: [mainnet],
+    connectors: [createMockConnector()],
+    transports: { [mainnet.id]: http() },
+  });
+  const nonceRequests = () => server.requests.filter((r) => r.url.endsWith("/nonce"));
+  return { server, kc, config, nonceRequests };
+}
+
+interface Seen {
+  siwe?: SIWEContextValue | null;
+  gpg?: GpgContextValue | null;
+}
+
+function Probe({ seen }: { seen: Seen }) {
+  seen.siwe = useContext(SIWEContext);
+  seen.gpg = useContext(GpgContext);
+  return null;
+}
+
+function providers(
+  kc: ReturnType<typeof setup>["kc"],
+  config: ReturnType<typeof setup>["config"],
+  onSign: OnSign,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } },
+  });
+  return ({ children }: { children: ReactNode }) => (
+    <WagmiProvider config={config} reconnectOnMount={false}>
+      <QueryClientProvider client={queryClient}>
+        <GpgProvider {...kc.gpgConfig(onSign)}>
+          <SIWEProvider {...kc.siweConfig(onSign)}>{children}</SIWEProvider>
+        </GpgProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}
+
+async function nonces(seen: Seen, expected: string) {
+  await waitFor(() => {
+    expect(seen.siwe?.nonce.data).toBe(expected);
+    expect(seen.gpg?.nonce.data).toBe(expected);
+  });
+  expect(seen.gpg?.message).toContain(`\nNonce: ${expected}\n`);
+}
+
+describe("nonce reset", () => {
+  it("a registration refetches both providers' nonce, so a second register signs a fresh one", async () => {
+    const { server, kc, config, nonceRequests } = setup();
+    const registration = kc.registerWallet({ accessToken: "at" });
+    const seen: Seen = {};
+    render(<Probe seen={seen} />, { wrapper: providers(kc, config, registration.onSign) });
+    await nonces(seen, "nonce-1");
+    expect(nonceRequests()).toHaveLength(1);
+
+    await act(async () => {
+      await connect(config, { connector: config.connectors[0] });
+    });
+    await waitFor(() => expect(seen.siwe?.nonce.data).toBe("nonce-1"));
+
+    const registered = () =>
+      server.requests
+        .filter((r) => r.url.endsWith("/register"))
+        .map((r) => (JSON.parse(r.body) as { message: string }).message);
+
+    await act(async () => {
+      expect(await seen.siwe!.signIn()).not.toBe(false);
+    });
+    await nonces(seen, "nonce-2");
+    await act(async () => {
+      expect(await seen.siwe!.signIn()).not.toBe(false);
+    });
+    await nonces(seen, "nonce-3");
+
+    expect(registered().map((message) => message.match(/\nNonce: (\S+)\n/)?.[1])).toEqual([
+      "nonce-1",
+      "nonce-2",
+    ]);
+    expect(nonceRequests()).toHaveLength(3);
+  });
+
+  it("a sign-in while the reset's refetch is in flight waits for the fresh nonce", async () => {
+    let release!: () => void;
+    const slow = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const { server, kc, config } = setup(async (n) => {
+      if (n === 2) await slow;
+      return new Response(`nonce-${n}`);
+    });
+    const registration = kc.registerWallet({ accessToken: "at" });
+    const seen: Seen = {};
+    render(<Probe seen={seen} />, { wrapper: providers(kc, config, registration.onSign) });
+    await nonces(seen, "nonce-1");
+    await act(async () => {
+      await connect(config, { connector: config.connectors[0] });
+    });
+    const registered = () =>
+      server.requests
+        .filter((r) => r.url.endsWith("/register"))
+        .map(
+          (r) => (JSON.parse(r.body) as { message: string }).message.match(/\nNonce: (\S+)\n/)?.[1],
+        );
+
+    await act(async () => {
+      expect(await seen.siwe!.signIn()).not.toBe(false);
+    });
+    await waitFor(() => expect(seen.siwe?.nonce.isFetching).toBe(true));
+    expect(seen.siwe?.nonce.data).toBe("nonce-1");
+
+    let second!: Promise<unknown>;
+    await act(async () => {
+      second = seen.siwe!.signIn();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+    expect(registered()).toEqual(["nonce-1"]);
+
+    release();
+    await act(async () => {
+      expect(await second).not.toBe(false);
+    });
+    expect(registered()).toEqual(["nonce-1", "nonce-2"]);
+  });
+
+  it("a direct login refetches GPG's nonce too, with one /nonce per attempt", async () => {
+    const { kc, config, nonceRequests } = setup();
+    const grant = kc.directGrant({ clientId: "app" });
+    const seen: Seen = {};
+    const wrapper = providers(kc, config, grant.onSign);
+    const { result } = renderHook(
+      () => {
+        seen.siwe = useContext(SIWEContext);
+        seen.gpg = useContext(GpgContext);
+        return useDirectLogin(grant);
+      },
+      { wrapper },
+    );
+    await nonces(seen, "nonce-1");
+    await act(async () => {
+      await connect(config, { connector: config.connectors[0] });
+    });
+
+    await act(async () => {
+      expect(await result.current.signIn()).toMatchObject({ accessToken: "at" });
+    });
+    await nonces(seen, "nonce-2");
+    expect(nonceRequests()).toHaveLength(2);
+  });
+
+  it("unsubscribes when the providers unmount", async () => {
+    const { kc, config, nonceRequests } = setup();
+    const seen: Seen = {};
+    const { unmount } = render(<Probe seen={seen} />, {
+      wrapper: providers(kc, config, async () => true),
+    });
+    await nonces(seen, "nonce-1");
+    unmount();
+    kc.resetNonce();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(nonceRequests()).toHaveLength(1);
+  });
+});

package/src/keycloak/registerWallet.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { fakeKeycloak, json } from "../../tests/fakeKeycloak";
+import { keycloakWallet } from "./keycloakWallet";
+import { KeycloakWalletError } from "./types";
+
+function setup(status = 200, body: unknown = { registered: true }) {
+  const server = fakeKeycloak({
+    "/nonce": () =>
+      new Response("nonce", { headers: { "set-cookie": "KEYCLOAK_SESSION_SIWW=k1; Path=/" } }),
+    "/register": () => json(body, status),
+  });
+  const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+  return { server, kc };
+}
+
+describe("registerWallet", () => {
+  it("POSTs message + signature with the user's bearer token and the nonce cookie", async () => {
+    const { server, kc } = setup();
+    await kc.getNonce();
+    const registration = kc.registerWallet({ accessToken: "at-1" });
+    await expect(
+      registration.register({ message: "the message", signature: "0xsig" }),
+    ).resolves.toEqual({ registered: true });
+    const req = server.requests.at(-1)!;
+    expect(req.url).toBe("https://kc/realms/main/siww/register");
+    expect(req.method).toBe("POST");
+    expect(req.headers.get("authorization")).toBe("Bearer at-1");
+    expect(req.headers.get("content-type")).toBe("application/json");
+    expect(req.headers.get("cookie")).toBe("KEYCLOAK_SESSION_SIWW=k1");
+    expect(JSON.parse(req.body)).toEqual({ message: "the message", signature: "0xsig" });
+  });
+
+  it("onSign takes the SIWEProvider credential and reads the token from a getter", async () => {
+    const { server, kc } = setup(200, { registered: false });
+    const registration = kc.registerWallet({ accessToken: async () => "at-2" });
+    await expect(
+      registration.onSign({ username: "0xsig", password: "ignored", message: "m" }),
+    ).resolves.toBe(true);
+    const req = server.requests.at(-1)!;
+    expect(req.headers.get("authorization")).toBe("Bearer at-2");
+    expect(JSON.parse(req.body)).toEqual({ message: "m", signature: "0xsig" });
+  });
+
+  it("a wallet another user owns is a 409 KeycloakWalletError", async () => {
+    const { kc } = setup(409, { message: "wallet already registered" });
+    const error = await kc
+      .registerWallet({ accessToken: "at" })
+      .register({ message: "m", signature: "s" })
+      .catch((e) => e);
+    expect(error).toBeInstanceOf(KeycloakWalletError);
+    expect(error).toMatchObject({ status: 409, message: "wallet already registered" });
+  });
+
+  it("refuses without a signed-in user", async () => {
+    const { server, kc } = setup();
+    await expect(
+      kc.registerWallet({ accessToken: () => null }).register({ message: "m", signature: "s" }),
+    ).rejects.toThrow(/access token/);
+    expect(server.requests.filter((r) => r.url.endsWith("/register"))).toHaveLength(0);
+  });
+
+  it("drops the memoized nonce after the attempt; the server consumed it", async () => {
+    const { server, kc } = setup();
+    await kc.getNonce();
+    await kc.registerWallet({ accessToken: "at" }).register({ message: "m", signature: "s" });
+    await kc.getNonce();
+    expect(server.requests.filter((r) => r.url.endsWith("/nonce"))).toHaveLength(2);
+  });
+
+  it.each([
+    [200, { registered: true }],
+    [409, { message: "wallet already registered" }],
+  ])(
+    "tells the providers to refetch after a %i, so a second register is not stale",
+    async (status, body) => {
+      const { kc } = setup(status, body);
+      let resets = 0;
+      kc.subscribeNonceReset(() => {
+        resets += 1;
+      });
+      await kc
+        .registerWallet({ accessToken: "at" })
+        .register({ message: "m", signature: "s" })
+        .catch(() => undefined);
+      expect(resets).toBe(1);
+    },
+  );
+});

package/src/keycloak/registerWallet.ts

@@ -0,0 +1,59 @@
+import type { KeycloakWallet } from "./keycloakWallet";
+import { KeycloakWalletError, type OnSign } from "./types";
+
+export interface RegisterWalletOptions {
+  /** The signed-in user's access token, or a getter such as `directGrant(...).getAccessToken`. */
+  accessToken: string | (() => string | null | Promise<string | null>);
+}
+
+export interface WalletRegistration {
+  /** `onSign` for `<SIWEProvider>`: proves the connected wallet and binds it to the signed-in user. */
+  onSign: OnSign;
+  /**
+   * POST `<resource>/register`. `registered` is false when the wallet was
+   * already this user's; another user's wallet is a 409.
+   */
+  register(args: { message: string; signature: string }): Promise<{ registered: boolean }>;
+}
+
+export function createWalletRegistration(
+  kc: KeycloakWallet,
+  opts: RegisterWalletOptions,
+): WalletRegistration {
+  const registration: WalletRegistration = {
+    async register({ message, signature }) {
+      const accessToken =
+        typeof opts.accessToken === "function" ? await opts.accessToken() : opts.accessToken;
+      if (!accessToken) throw new Error("registerWallet needs a signed-in user's access token");
+      try {
+        const res = await kc.request(`${kc.resourceUrl}/register`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${accessToken}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ message, signature }),
+        });
+        const data = (await res.json().catch(() => ({}))) as {
+          registered?: boolean;
+          message?: string;
+        };
+        if (!res.ok) {
+          throw new KeycloakWalletError(
+            data.message || `Keycloak wallet register failed (${res.status})`,
+            res.status,
+            { error: data.message },
+          );
+        }
+        return { registered: Boolean(data.registered) };
+      } finally {
+        kc.resetNonce();
+      }
+    },
+    onSign: async ({ username, message }) => {
+      await registration.register({ message, signature: username });
+      return true;
+    },
+  };
+  return registration;
+}

package/src/keycloak/types.ts

@@ -0,0 +1,66 @@
+/**
+ * The REST resource the Keycloak wallet SPI mounts under `/realms/<realm>/`:
+ * `siww` on the SHC Keycloak, `wallet` on mpo's own SPI.
+ */
+export type KeycloakWalletResource = "siww" | "wallet";
+
+/**
+ * What SIWEProvider and GpgProvider hand their `onSign`: `username` is the raw
+ * signature (or the GPG blob), `password` is base64(message).
+ */
+export interface WalletSignIn {
+  username: string;
+  password: string;
+  message: string;
+}
+
+export type OnSign = (credentials: WalletSignIn) => Promise<boolean>;
+
+export interface KeycloakTokens {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  tokenType: string;
+  scope?: string;
+  /** Epoch ms after which the access token is expired. */
+  expiresAt: number;
+  /** Epoch ms after which the refresh token is expired; absent for offline or non-expiring tokens. */
+  refreshExpiresAt?: number;
+}
+
+export class KeycloakWalletError extends Error {
+  readonly status: number;
+  readonly error?: string;
+  readonly errorDescription?: string;
+
+  constructor(
+    message: string,
+    status: number,
+    details: { error?: string; errorDescription?: string } = {},
+  ) {
+    super(message);
+    this.name = "KeycloakWalletError";
+    this.status = status;
+    this.error = details.error;
+    this.errorDescription = details.errorDescription;
+  }
+}
+
+/**
+ * Keycloak accepted the wallet but the account has required actions left (a
+ * new user's profile form, terms, a verified email), which a direct grant
+ * cannot run: Keycloak answers 400 invalid_grant "Account is not fully set
+ * up". Send the user through the browser login once
+ * (`kc.browserLoginUrl(...)` in the system browser or a WebView) so Keycloak
+ * shows its own forms; the direct grant succeeds after that.
+ */
+export class ProfileIncompleteError extends KeycloakWalletError {
+  constructor(
+    message: string,
+    status: number,
+    details: { error?: string; errorDescription?: string } = {},
+  ) {
+    super(message, status, details);
+    this.name = "ProfileIncompleteError";
+  }
+}

package/src/keycloak/useDirectLogin.spec.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import { fakeKeycloak, json } from "../../tests/fakeKeycloak";
+import { SIWEContext, StatusState, type SIWEContextValue } from "../connectkit/siwe/SIWEContext";
+import { keycloakWallet } from "./keycloakWallet";
+import { ProfileIncompleteError, type OnSign } from "./types";
+import { useDirectLogin } from "./useDirectLogin";
+
+function setup(tokenStatus = 200) {
+  const server = fakeKeycloak({
+    "/nonce": () => new Response("nonce"),
+    "/token": () =>
+      tokenStatus === 200
+        ? json({ access_token: "at", refresh_token: "rt", expires_in: 60 })
+        : tokenStatus === 400
+          ? json({ error: "invalid_grant", error_description: "Account is not fully set up" }, 400)
+          : json({ error: "invalid_grant", error_description: "Invalid user credentials" }, 401),
+  });
+  const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+  const grant = kc.directGrant({ clientId: "app" });
+  const siwe = (onSign: OnSign, signIn?: () => Promise<unknown>) =>
+    ({
+      onSign,
+      signIn:
+        signIn ??
+        (async () => {
+          try {
+            await onSign({ username: "0xsig", password: "bQ==", message: "m" });
+            return undefined;
+          } catch {
+            return false;
+          }
+        }),
+      status: StatusState.READY,
+    }) as unknown as SIWEContextValue;
+  const wrapper =
+    (value: SIWEContextValue) =>
+    ({ children }: { children: ReactNode }) => (
+      <SIWEContext.Provider value={value}>{children}</SIWEContext.Provider>
+    );
+  return { kc, grant, siwe, wrapper };
+}
+
+describe("useDirectLogin", () => {
+  it("signs through SIWEProvider and exposes the grant's tokens", async () => {
+    const { kc, grant, siwe, wrapper } = setup();
+    let resets = 0;
+    kc.subscribeNonceReset(() => {
+      resets += 1;
+    });
+    const { result } = renderHook(() => useDirectLogin(grant), {
+      wrapper: wrapper(siwe(grant.onSign)),
+    });
+    expect(result.current.status).toBe("idle");
+    let tokens: unknown;
+    await act(async () => {
+      tokens = await result.current.signIn();
+    });
+    expect(tokens).toMatchObject({ accessToken: "at", refreshToken: "rt" });
+    expect(result.current.status).toBe("signed-in");
+    expect(result.current.tokens?.accessToken).toBe("at");
+    expect(resets).toBe(1);
+    await act(async () => {
+      await result.current.signOut();
+    });
+    expect(result.current.status).toBe("idle");
+  });
+
+  it("a refused login resolves null and surfaces Keycloak's error", async () => {
+    const { grant, siwe, wrapper } = setup(401);
+    const { result } = renderHook(() => useDirectLogin(grant), {
+      wrapper: wrapper(siwe(grant.onSign)),
+    });
+    let tokens: unknown = "unset";
+    await act(async () => {
+      tokens = await result.current.signIn();
+    });
+    expect(tokens).toBeNull();
+    expect(result.current.status).toBe("error");
+    expect(result.current.error?.message).toBe("Invalid user credentials");
+  });
+
+  it("an account with required actions left reports profile-incomplete with the typed error", async () => {
+    const { grant, siwe, wrapper } = setup(400);
+    const { result } = renderHook(() => useDirectLogin(grant), {
+      wrapper: wrapper(siwe(grant.onSign)),
+    });
+    let tokens: unknown = "unset";
+    await act(async () => {
+      tokens = await result.current.signIn();
+    });
+    expect(tokens).toBeNull();
+    expect(result.current.status).toBe("profile-incomplete");
+    expect(result.current.error).toBeInstanceOf(ProfileIncompleteError);
+  });
+
+  it("refuses a SIWEProvider wired to some other onSign", async () => {
+    const { grant, siwe, wrapper } = setup();
+    const { result } = renderHook(() => useDirectLogin(grant), {
+      wrapper: wrapper(siwe(async () => true)),
+    });
+    await expect(result.current.signIn()).rejects.toThrow(/not this grant's/);
+  });
+
+  it("needs a SIWEProvider", async () => {
+    const { grant } = setup();
+    const { result } = renderHook(() => useDirectLogin(grant));
+    await expect(result.current.signIn()).rejects.toThrow(/inside a SIWEProvider/);
+  });
+});

package/src/keycloak/useDirectLogin.ts

@@ -0,0 +1,74 @@
+import { useCallback, useContext, useState, useSyncExternalStore } from "react";
+import { SIWEContext } from "../connectkit/siwe/SIWEContext";
+import type { DirectGrant } from "./directGrant";
+import { ProfileIncompleteError, type KeycloakTokens } from "./types";
+
+export type DirectLoginStatus = "idle" | "signing" | "signed-in" | "profile-incomplete" | "error";
+
+export interface UseDirectLoginResult {
+  /**
+   * `profile-incomplete`: Keycloak took the wallet but the account has
+   * required actions left, and `error` is the `ProfileIncompleteError`. Open
+   * `kc.browserLoginUrl(...)` (system browser or WebView) so Keycloak's own
+   * forms run, then `signIn()` again.
+   */
+  status: DirectLoginStatus;
+  tokens: KeycloakTokens | null;
+  error: Error | null;
+  /**
+   * Sign in with the connected wallet through SIWEProvider and exchange the
+   * signature for tokens. Resolves null when the wallet or Keycloak refused.
+   */
+  signIn(): Promise<KeycloakTokens | null>;
+  refresh(): Promise<KeycloakTokens>;
+  signOut(): Promise<void>;
+}
+
+/**
+ * Direct (browserless) wallet login: SIWEProvider signs, the grant trades the
+ * signature for Keycloak tokens. Mount it under
+ * `<SIWEProvider {...kc.siweConfig(grant.onSign)}>`; every login attempt resets
+ * the kc nonce, which refetches it in SIWEProvider and GpgProvider alike.
+ */
+export function useDirectLogin(grant: DirectGrant): UseDirectLoginResult {
+  const siwe = useContext(SIWEContext);
+  const state = useSyncExternalStore(
+    grant.subscribe,
+    () => grant.state,
+    () => grant.state,
+  );
+  const [signing, setSigning] = useState(false);
+
+  const signIn = useCallback(async () => {
+    if (!siwe) throw new Error("useDirectLogin must be used inside a SIWEProvider");
+    if (siwe.onSign !== grant.onSign) {
+      throw new Error("useDirectLogin: the SIWEProvider's onSign is not this grant's");
+    }
+    setSigning(true);
+    try {
+      const result = await siwe.signIn();
+      return result === false ? null : grant.tokens;
+    } finally {
+      setSigning(false);
+    }
+  }, [siwe, grant]);
+
+  const status: DirectLoginStatus = signing
+    ? "signing"
+    : state.tokens
+      ? "signed-in"
+      : state.error instanceof ProfileIncompleteError
+        ? "profile-incomplete"
+        : state.error
+          ? "error"
+          : "idle";
+
+  return {
+    status,
+    tokens: state.tokens,
+    error: state.error,
+    signIn,
+    refresh: useCallback(() => grant.refresh(), [grant]),
+    signOut: useCallback(() => grant.logout(), [grant]),
+  };
+}

package/src/keycloak/useWalletLogin.native.ts

@@ -0,0 +1,7 @@
+import type { UseWalletLoginOptions, UseWalletLoginResult } from "./useWalletLogin";
+
+export type { UseWalletLoginOptions, UseWalletLoginResult };
+
+export function useWalletLogin(_opts?: UseWalletLoginOptions): UseWalletLoginResult {
+  throw new Error("useWalletLogin is web only; a native app signs in with useDirectLogin");
+}