@multiplatform.one/web3 7.23.2 → 7.24.0

package/src/keycloak/keycloakWallet.spec.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from "vitest";
+import { buildWalletMessage } from "../message";
+import {
+  deriveKeycloakFromLocation,
+  keycloakWallet,
+  pkceChallenge,
+  toCredentials,
+} from "./keycloakWallet";
+import { fakeKeycloak } from "../../tests/fakeKeycloak";
+
+function nonceServer() {
+  let issued = 0;
+  return fakeKeycloak({
+    "/nonce": () => {
+      issued += 1;
+      return new Response(`nonce-${issued}\n`, {
+        headers: { "set-cookie": `KEYCLOAK_SESSION_SIWW=key-${issued}; Path=/; HttpOnly` },
+      });
+    },
+  });
+}
+
+describe("keycloakWallet", () => {
+  it("resolves the realm, resource and token URLs; siww by default, wallet on request", () => {
+    const siww = keycloakWallet({ baseUrl: "https://kc.example.com/auth/", realm: "main" });
+    expect(siww.resourceUrl).toBe("https://kc.example.com/auth/realms/main/siww");
+    expect(siww.tokenUrl).toBe(
+      "https://kc.example.com/auth/realms/main/protocol/openid-connect/token",
+    );
+    const wallet = keycloakWallet({
+      baseUrl: "https://kc.example.com",
+      realm: "main",
+      resource: "wallet",
+    });
+    expect(wallet.resourceUrl).toBe("https://kc.example.com/realms/main/wallet");
+  });
+
+  describe("browserLoginUrl", () => {
+    const kc = keycloakWallet({ baseUrl: "https://kc.example.com/auth", realm: "main" });
+
+    it("is the realm's authorization-code login with state and PKCE S256, for the profile-incomplete fallback", () => {
+      const login = kc.browserLoginUrl({
+        clientId: "wallet-onboarding",
+        redirectUri: "quickcam://auth/callback",
+      });
+      const url = new URL(login.url);
+      expect(url.origin + url.pathname).toBe(
+        "https://kc.example.com/auth/realms/main/protocol/openid-connect/auth",
+      );
+      expect(Object.fromEntries(url.searchParams)).toEqual({
+        client_id: "wallet-onboarding",
+        redirect_uri: "quickcam://auth/callback",
+        response_type: "code",
+        scope: "openid",
+        state: login.state,
+        code_challenge: pkceChallenge(login.codeVerifier),
+        code_challenge_method: "S256",
+      });
+      expect(login.codeVerifier).toMatch(/^[A-Za-z0-9_-]{43}$/);
+      expect(login.state).toMatch(/^[A-Za-z0-9_-]{22}$/);
+    });
+
+    it("draws a fresh state and verifier every call", () => {
+      const a = kc.browserLoginUrl({ clientId: "app", redirectUri: "app://auth" });
+      const b = kc.browserLoginUrl({ clientId: "app", redirectUri: "app://auth" });
+      expect(a.state).not.toBe(b.state);
+      expect(a.codeVerifier).not.toBe(b.codeVerifier);
+    });
+
+    it("joins a scope list", () => {
+      const { url } = kc.browserLoginUrl({
+        clientId: "app",
+        redirectUri: "https://app.example.com/cb",
+        scope: ["openid", "email"],
+      });
+      expect(new URL(url).searchParams.get("scope")).toBe("openid email");
+    });
+
+    it("keeps a redirectUri carrying &client_id= encoded inside redirect_uri", () => {
+      const redirectUri = "https://app.example.com/cb?x=1&client_id=evil#frag";
+      const { url } = kc.browserLoginUrl({ clientId: "app", redirectUri });
+      const params = new URL(url).searchParams;
+      expect(params.getAll("client_id")).toEqual(["app"]);
+      expect(params.get("redirect_uri")).toBe(redirectUri);
+      expect(url).toContain(
+        "redirect_uri=https%3A%2F%2Fapp.example.com%2Fcb%3Fx%3D1%26client_id%3Devil%23frag",
+      );
+      expect(url).not.toContain("&client_id=evil");
+    });
+
+    it("pkceChallenge matches RFC 7636 appendix B", () => {
+      expect(pkceChallenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")).toBe(
+        "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
+      );
+    });
+  });
+
+  describe("nonce memo", () => {
+    it("shares one nonce between callers until reset, since each /nonce replaces the last", async () => {
+      const server = nonceServer();
+      const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+      const [a, b] = await Promise.all([kc.getNonce(), kc.getNonce()]);
+      expect([a, b, await kc.getNonce()]).toEqual(["nonce-1", "nonce-1", "nonce-1"]);
+      expect(server.requests).toHaveLength(1);
+      expect(server.requests[0].url).toBe("https://kc/realms/main/siww/nonce");
+      expect(server.requests[0].credentials).toBe("include");
+      kc.resetNonce();
+      expect(await kc.getNonce()).toBe("nonce-2");
+      expect(server.requests).toHaveLength(2);
+    });
+
+    it("a failed fetch is not memoized", async () => {
+      let fail = true;
+      const server = fakeKeycloak({
+        "/nonce": () => (fail ? new Response("", { status: 503 }) : new Response("abc")),
+      });
+      const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+      await expect(kc.getNonce()).rejects.toThrow(/503/);
+      fail = false;
+      await expect(kc.getNonce()).resolves.toBe("abc");
+    });
+
+    it("tells nonce-reset subscribers, through both provider configs, until they unsubscribe", async () => {
+      const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main" });
+      const onSign = async () => true;
+      const resets: string[] = [];
+      const offSiwe = kc.siweConfig(onSign).subscribeNonceReset!(() => resets.push("siwe"));
+      const offGpg = kc.gpgConfig(onSign).subscribeNonceReset(() => resets.push("gpg"));
+      kc.resetNonce();
+      expect(resets).toEqual(["siwe", "gpg"]);
+      offSiwe();
+      kc.resetNonce();
+      expect(resets).toEqual(["siwe", "gpg", "gpg"]);
+      offGpg();
+      kc.resetNonce();
+      expect(resets).toHaveLength(3);
+    });
+
+    it("rejects an empty nonce", async () => {
+      const server = fakeKeycloak({ "/nonce": () => new Response("  ") });
+      const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+      await expect(kc.getNonce()).rejects.toThrow(/empty nonce/);
+    });
+  });
+
+  it("replays the nonce session cookie where fetch exposes Set-Cookie (native, node)", async () => {
+    const server = nonceServer();
+    const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+    await kc.getNonce();
+    await kc.request(kc.tokenUrl, { method: "POST" });
+    expect(server.requests[1].headers.get("cookie")).toBe("KEYCLOAK_SESSION_SIWW=key-1");
+    kc.resetNonce();
+    await kc.getNonce();
+    await kc.request(kc.tokenUrl, { method: "POST" });
+    expect(server.requests[3].headers.get("cookie")).toBe("KEYCLOAK_SESSION_SIWW=key-2");
+  });
+
+  it("builds messages with its explicit domain for SIWE and GPG", () => {
+    const kc = keycloakWallet({
+      baseUrl: "https://kc",
+      realm: "main",
+      domain: "app.example.com",
+      uri: "https://app.example.com",
+    });
+    const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
+    const siwe = kc.siweConfig(async () => true);
+    const message = siwe.createMessage({ nonce: "n1", address, chainId: 1 }) as string;
+    const issuedAt = message.match(/Issued At: (.*)$/)?.[1];
+    expect(message).toBe(
+      buildWalletMessage("eth", {
+        nonce: "n1",
+        address,
+        domain: "app.example.com",
+        uri: "https://app.example.com",
+        issuedAt,
+      }),
+    );
+    const gpg = kc.gpgMessage({ nonce: "n2" });
+    expect(gpg.split("\n")[0]).toBe("app.example.com wants you to sign in with your GPG key.");
+  });
+
+  it("siweConfig and gpgConfig hand the providers the shared nonce and the given onSign", async () => {
+    const server = nonceServer();
+    const kc = keycloakWallet({ baseUrl: "https://kc", realm: "main", fetch: server.fetch });
+    const onSign = async () => true;
+    const siwe = kc.siweConfig(onSign);
+    const gpg = kc.gpgConfig(onSign);
+    expect(siwe.onSign).toBe(onSign);
+    expect(gpg.onSign).toBe(onSign);
+    expect(await siwe.getNonce()).toBe(await gpg.getNonce());
+    expect(server.requests).toHaveLength(1);
+  });
+});
+
+describe("toCredentials", () => {
+  it("base64s the UTF-8 message without btoa", () => {
+    const message = "héllo ✓";
+    const creds = toCredentials({ signature: "0xsig", message });
+    expect(creds.username).toBe("0xsig");
+    expect(Buffer.from(creds.password, "base64").toString("utf8")).toBe(message);
+  });
+});
+
+describe("deriveKeycloakFromLocation", () => {
+  it("reads base and realm off a Keycloak page", () => {
+    expect(
+      deriveKeycloakFromLocation({
+        origin: "https://account.example.com",
+        pathname: "/auth/realms/main/login-actions/authenticate",
+      }),
+    ).toEqual({ baseUrl: "https://account.example.com/auth", realm: "main" });
+    expect(
+      deriveKeycloakFromLocation({ origin: "https://example.com", pathname: "/dashboard" }),
+    ).toBeUndefined();
+  });
+});

package/src/keycloak/keycloakWallet.ts

@@ -0,0 +1,275 @@
+import { sha256, type Address } from "viem";
+import { bytesToBase64 } from "../bridge/base64";
+import { createWalletMessage } from "../connectkit/connectors/createWalletMessage";
+import type { SIWEConfig } from "../connectkit/siwe/SIWEContext";
+import { buildWalletMessage } from "../message";
+import { browserFlow, type BrowserFlowOptions } from "./browserFlow";
+import { createDirectGrant, type DirectGrant, type DirectGrantOptions } from "./directGrant";
+import {
+  createWalletRegistration,
+  type RegisterWalletOptions,
+  type WalletRegistration,
+} from "./registerWallet";
+import { KeycloakWalletError, type KeycloakWalletResource, type OnSign } from "./types";
+
+export interface KeycloakWalletOptions {
+  /** Keycloak base URL, e.g. `https://account.example.com` or `http://localhost:8080/auth`. */
+  baseUrl: string;
+  realm: string;
+  /** Defaults to `siww` (SHC Keycloak); mpo's own SPI mounts `wallet`. */
+  resource?: KeycloakWalletResource;
+  /**
+   * Domain written into every sign-in message. Defaults to the page host. A
+   * WebView or native caller passes the hosted page's host the realm allows.
+   */
+  domain?: string;
+  /** URI written into every sign-in message. Defaults to the page origin or `https://<domain>`. */
+  uri?: string;
+  fetch?: typeof fetch;
+}
+
+export interface BrowserLoginUrlOptions {
+  /**
+   * A public client with `standardFlowEnabled` and `redirectUri` registered
+   * exactly, no wildcard. A direct-grant client such as mpo's `siwe-public`
+   * or `siws-public` (`standardFlowEnabled: false`) is refused; mpo's realm
+   * carries `wallet-onboarding` for this.
+   */
+  clientId: string;
+  /** Where Keycloak sends the browser back: the app's deep link or page. */
+  redirectUri: string;
+  /** Default `openid`. */
+  scope?: string | string[];
+}
+
+export interface BrowserLogin {
+  url: string;
+  /** Keep it, and accept the redirect back only when its `state` matches. */
+  state: string;
+  /** The PKCE S256 verifier behind the URL's `code_challenge`, for the code exchange. */
+  codeVerifier: string;
+}
+
+export interface KeycloakWallet {
+  readonly baseUrl: string;
+  readonly realm: string;
+  readonly resource: KeycloakWalletResource;
+  readonly realmUrl: string;
+  readonly resourceUrl: string;
+  readonly tokenUrl: string;
+  /**
+   * A server nonce, shared by every caller until `resetNonce()`. Each `/nonce`
+   * call replaces the previous nonce server side (and rotates its cookie), so
+   * two flows fetching their own would leave one signing a dead nonce.
+   */
+  getNonce(): Promise<string>;
+  /** Drop the shared nonce (the server consumed or rotated it) and tell every subscriber. */
+  resetNonce(): void;
+  /**
+   * Call `listener` on every `resetNonce()`. SIWEProvider and GpgProvider
+   * subscribe through the configs below and refetch their cached copy, so a
+   * second sign-in never signs a nonce the server has already dropped.
+   */
+  subscribeNonceReset(listener: () => void): () => void;
+  /** `SIWEConfig.createMessage`, with this wallet's domain and uri. */
+  createMessage(args: { nonce: string; address: string; chainId: number }): string;
+  /** `GpgConfig.buildMessage`, with this wallet's domain and uri. */
+  gpgMessage(args: { nonce: string }): string;
+  /** Props for `<SIWEProvider>` that sign through `onSign` (a browser flow, direct grant or registration). */
+  siweConfig(onSign: OnSign): SIWEConfig;
+  /** Props for `<GpgProvider>` that sign through `onSign`. */
+  gpgConfig(onSign: OnSign): {
+    getNonce: () => Promise<string>;
+    buildMessage: (args: { nonce: string }) => string;
+    onSign: OnSign;
+    subscribeNonceReset: (listener: () => void) => () => void;
+  };
+  browserFlow(opts?: BrowserFlowOptions): OnSign;
+  directGrant(opts: DirectGrantOptions): DirectGrant;
+  /**
+   * The realm's authorization-code login, with a fresh `state` and PKCE S256
+   * pair. Open `url` in the system browser or a WebView when a direct grant
+   * rejects with `ProfileIncompleteError`: Keycloak's own login runs the
+   * pending required actions (the profile form), and the next direct grant
+   * succeeds.
+   */
+  browserLoginUrl(opts: BrowserLoginUrlOptions): BrowserLogin;
+  registerWallet(opts: RegisterWalletOptions): WalletRegistration;
+  /** `fetch` against Keycloak carrying the nonce session cookie. */
+  request(url: string, init?: RequestInit): Promise<Response>;
+}
+
+const sessionCookie = /(KEYCLOAK_SESSION_[A-Z]+)=([^;,\s]+)/;
+
+function readSessionCookie(res: Response): string | undefined {
+  const headers = res.headers as Headers & { getSetCookie?: () => string[] };
+  const values = headers.getSetCookie?.() ?? [headers.get("set-cookie") ?? ""];
+  for (const value of values) {
+    const match = value.match(sessionCookie);
+    if (match) return `${match[1]}=${match[2]}`;
+  }
+  return undefined;
+}
+
+const base64Url = (bytes: Uint8Array) =>
+  bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+function randomBase64Url(size: number): string {
+  const crypto = globalThis.crypto;
+  if (!crypto?.getRandomValues) {
+    throw new Error(
+      "browserLoginUrl needs crypto.getRandomValues (react-native-get-random-values on Hermes)",
+    );
+  }
+  return base64Url(crypto.getRandomValues(new Uint8Array(size)));
+}
+
+/** RFC 7636 S256: base64url(SHA-256(ASCII(verifier))). */
+export function pkceChallenge(codeVerifier: string): string {
+  return base64Url(sha256(new TextEncoder().encode(codeVerifier), "bytes"));
+}
+
+/** `username`/`password` for a signature over `message`, base64 done without btoa so it runs on Hermes. */
+export function toCredentials(args: { signature: string; message: string }) {
+  return {
+    username: args.signature,
+    password: bytesToBase64(new TextEncoder().encode(args.message)),
+    message: args.message,
+  };
+}
+
+export function keycloakWallet(options: KeycloakWalletOptions): KeycloakWallet {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const resource = options.resource ?? "siww";
+  const realmUrl = `${baseUrl}/realms/${encodeURIComponent(options.realm)}`;
+  const resourceUrl = `${realmUrl}/${resource}`;
+  const tokenUrl = `${realmUrl}/protocol/openid-connect/token`;
+  const fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  let cookie: string | undefined;
+  let nonce: Promise<string> | undefined;
+  const nonceListeners = new Set<() => void>();
+
+  const request = (url: string, init: RequestInit = {}) => {
+    const headers = new Headers(init.headers);
+    if (cookie && !headers.has("cookie")) headers.set("cookie", cookie);
+    return fetchImpl(url, { credentials: "include", ...init, headers });
+  };
+
+  const fetchNonce = async () => {
+    const res = await request(`${resourceUrl}/nonce`);
+    if (!res.ok) {
+      throw new KeycloakWalletError(`Keycloak nonce request failed (${res.status})`, res.status);
+    }
+    cookie = readSessionCookie(res) ?? cookie;
+    const value = (await res.text()).trim();
+    if (!value) throw new KeycloakWalletError("Keycloak returned an empty nonce", res.status);
+    return value;
+  };
+
+  const kc: KeycloakWallet = {
+    baseUrl,
+    realm: options.realm,
+    resource,
+    realmUrl,
+    resourceUrl,
+    tokenUrl,
+    request,
+    getNonce() {
+      if (!nonce) {
+        const pending = fetchNonce();
+        nonce = pending;
+        pending.catch(() => {
+          if (nonce === pending) nonce = undefined;
+        });
+      }
+      return nonce;
+    },
+    resetNonce() {
+      nonce = undefined;
+      for (const listener of nonceListeners) listener();
+    },
+    subscribeNonceReset(listener) {
+      nonceListeners.add(listener);
+      return () => {
+        nonceListeners.delete(listener);
+      };
+    },
+    createMessage({ nonce: value, address, chainId }) {
+      return createWalletMessage({
+        address,
+        chainId,
+        nonce: value,
+        domain: options.domain,
+        uri: options.uri,
+      });
+    },
+    gpgMessage({ nonce: value }) {
+      return buildWalletMessage("gpg", { nonce: value, domain: options.domain, uri: options.uri });
+    },
+    siweConfig(onSign) {
+      return {
+        getNonce: () => kc.getNonce(),
+        createMessage: ({
+          nonce: value,
+          address,
+          chainId,
+        }: {
+          nonce: string;
+          address: Address;
+          chainId: number;
+        }) => kc.createMessage({ nonce: value, address, chainId }),
+        onSign,
+        subscribeNonceReset: kc.subscribeNonceReset,
+        verifyMessage: async () => true,
+        getSession: async () => null,
+        signOut: async () => true,
+      };
+    },
+    gpgConfig(onSign) {
+      return {
+        getNonce: () => kc.getNonce(),
+        buildMessage: (args) => kc.gpgMessage(args),
+        onSign,
+        subscribeNonceReset: kc.subscribeNonceReset,
+      };
+    },
+    browserFlow(opts) {
+      return browserFlow(opts);
+    },
+    directGrant(opts) {
+      return createDirectGrant(kc, opts);
+    },
+    browserLoginUrl({ clientId, redirectUri, scope }) {
+      const state = randomBase64Url(16);
+      const codeVerifier = randomBase64Url(32);
+      const params = new URLSearchParams({
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        scope: Array.isArray(scope) ? scope.join(" ") : (scope ?? "openid"),
+        state,
+        code_challenge: pkceChallenge(codeVerifier),
+        code_challenge_method: "S256",
+      });
+      return { url: `${realmUrl}/protocol/openid-connect/auth?${params}`, state, codeVerifier };
+    },
+    registerWallet(opts) {
+      return createWalletRegistration(kc, opts);
+    },
+  };
+  return kc;
+}
+
+/**
+ * Keycloak base URL and realm of a page Keycloak serves (`<base>/realms/<realm>/...`),
+ * or undefined off such a page.
+ */
+export function deriveKeycloakFromLocation(
+  location: { origin: string; pathname: string } | undefined = (
+    globalThis as { location?: { origin: string; pathname: string } }
+  ).location,
+): { baseUrl: string; realm: string } | undefined {
+  const match = location?.pathname.match(/^(.*)\/realms\/([^/]+)\//);
+  if (!location || !match) return undefined;
+  return { baseUrl: location.origin + match[1], realm: decodeURIComponent(match[2]) };
+}

package/src/keycloak/mount.native.ts

@@ -0,0 +1,11 @@
+import type { KeycloakWalletLoginProps } from "./KeycloakWalletLogin";
+import type { MountedKeycloakWalletLogin } from "./mount";
+
+export type { MountedKeycloakWalletLogin };
+
+export function mount(
+  _target: string | Element,
+  _opts?: KeycloakWalletLoginProps,
+): MountedKeycloakWalletLogin {
+  throw new Error("MpoKeycloakWallet.mount is web only");
+}

package/src/keycloak/mount.tsx

@@ -0,0 +1,45 @@
+import { createRoot } from "react-dom/client";
+import type { Config } from "wagmi";
+import {
+  KeycloakWalletLogin,
+  type KeycloakWalletLoginProps,
+  createKeycloakWalletConfig,
+} from "./KeycloakWalletLogin";
+
+export interface MountedKeycloakWalletLogin {
+  /** The wagmi config the login signs with. */
+  readonly config: Config;
+  unmount(): void;
+}
+
+const mounted = new WeakMap<Element, MountedKeycloakWalletLogin>();
+
+/**
+ * Render `<KeycloakWalletLogin>` into `target` under its own React root, so a
+ * Keycloak theme on another React (or none) can host it. Mounting an element
+ * that already holds one returns that one: a second root would fetch a second
+ * nonce and rotate the session cookie under the first. `unmount()` frees the
+ * element for a fresh mount.
+ */
+export function mount(
+  target: string | Element,
+  opts: KeycloakWalletLoginProps = {},
+): MountedKeycloakWalletLogin {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) throw new Error(`MpoKeycloakWallet.mount: nothing matches ${String(target)}`);
+  const existing = mounted.get(el);
+  if (existing) return existing;
+  const config = opts.wagmiConfig ?? createKeycloakWalletConfig(opts);
+  const root = createRoot(el);
+  root.render(<KeycloakWalletLogin {...opts} wagmiConfig={config} />);
+  const handle: MountedKeycloakWalletLogin = {
+    config,
+    unmount() {
+      if (mounted.get(el) !== handle) return;
+      mounted.delete(el);
+      root.unmount();
+    },
+  };
+  mounted.set(el, handle);
+  return handle;
+}