@multiplatform.one/web3 7.23.1 → 7.24.0

package/src/keycloak/directGrant.spec.ts

@@ -0,0 +1,331 @@
+import { describe, expect, it } from "vitest";
+import { fakeKeycloak, json, type RecordedRequest } from "../../tests/fakeKeycloak";
+import { keycloakWallet } from "./keycloakWallet";
+import { KeycloakWalletError, ProfileIncompleteError } from "./types";
+
+const t0 = Date.parse("2026-09-26T21:00:00Z");
+
+interface ServerOptions {
+  reject?: boolean;
+  /** Answers every password grant instead of issuing tokens. */
+  password?: () => Response;
+  /** Answers every refresh-token grant instead of issuing tokens. */
+  refresh?: () => Response | Promise<Response>;
+}
+
+function tokenServer(opts: ServerOptions = {}) {
+  let n = 0;
+  const token = (req: RecordedRequest) => {
+    const form = new URLSearchParams(req.body);
+    if (form.get("grant_type") === "password" && opts.password) return opts.password();
+    if (opts.reject && form.get("grant_type") === "password") {
+      return json({ error: "invalid_grant", error_description: "Invalid user credentials" }, 401);
+    }
+    if (form.get("grant_type") === "refresh_token" && form.get("refresh_token") === "revoked") {
+      return json({ error: "invalid_grant", error_description: "Token is not active" }, 400);
+    }
+    if (form.get("grant_type") === "refresh_token" && opts.refresh) return opts.refresh();
+    n += 1;
+    return json({
+      access_token: `access-${n}`,
+      refresh_token: `refresh-${n}`,
+      id_token: `id-${n}`,
+      token_type: "Bearer",
+      scope: form.get("scope") ?? "openid profile",
+      expires_in: 300,
+      refresh_expires_in: 1800,
+    });
+  };
+  return fakeKeycloak({
+    "/nonce": () =>
+      new Response("nonce", { headers: { "set-cookie": "KEYCLOAK_SESSION_WALLET=abc; Path=/" } }),
+    "/protocol/openid-connect/token": token,
+    "/protocol/openid-connect/logout": () => new Response(null, { status: 204 }),
+  });
+}
+
+function setup(opts: ServerOptions & { now?: () => number } = {}) {
+  const server = tokenServer(opts);
+  const kc = keycloakWallet({
+    baseUrl: "https://kc.example.com",
+    realm: "main",
+    resource: "wallet",
+    fetch: server.fetch,
+  });
+  const grant = kc.directGrant({
+    clientId: "wallet-app",
+    scope: ["openid", "email"],
+    now: opts.now ?? (() => t0),
+  });
+  return { server, kc, grant };
+}
+
+describe("directGrant", () => {
+  it("trades signature + base64(message) for tokens on the password grant, with the nonce cookie", async () => {
+    const { server, kc, grant } = setup();
+    await kc.getNonce();
+    const tokens = await grant.login({ username: "0xsig", password: "bWVzc2FnZQ==" });
+    const req = server.requests.find((r) => r.url.endsWith("/token"))!;
+    expect(req.url).toBe("https://kc.example.com/realms/main/protocol/openid-connect/token");
+    expect(req.method).toBe("POST");
+    expect(req.headers.get("content-type")).toBe("application/x-www-form-urlencoded");
+    expect(req.headers.get("cookie")).toBe("KEYCLOAK_SESSION_WALLET=abc");
+    expect(Object.fromEntries(new URLSearchParams(req.body))).toEqual({
+      client_id: "wallet-app",
+      grant_type: "password",
+      username: "0xsig",
+      password: "bWVzc2FnZQ==",
+      scope: "openid email",
+    });
+    expect(tokens).toEqual({
+      accessToken: "access-1",
+      refreshToken: "refresh-1",
+      idToken: "id-1",
+      tokenType: "Bearer",
+      scope: "openid email",
+      expiresAt: t0 + 300_000,
+      refreshExpiresAt: t0 + 1_800_000,
+    });
+    expect(grant.tokens).toEqual(tokens);
+  });
+
+  it("onSign is the SIWEProvider/GpgProvider hook: resolves true and stores the tokens", async () => {
+    const { grant } = setup();
+    const seen: unknown[] = [];
+    grant.subscribe((state) => seen.push(state.tokens?.accessToken));
+    await expect(
+      grant.onSign({ username: "0xsig", password: "bWVzc2FnZQ==", message: "message" }),
+    ).resolves.toBe(true);
+    expect(grant.tokens?.accessToken).toBe("access-1");
+    expect(seen).toEqual(["access-1"]);
+  });
+
+  it("a rejected login throws KeycloakWalletError with Keycloak's error, and records it", async () => {
+    const { grant } = setup({ reject: true });
+    const error = await grant.login({ username: "0xsig", password: "x" }).catch((e) => e);
+    expect(error).toBeInstanceOf(KeycloakWalletError);
+    expect(error).toMatchObject({
+      status: 401,
+      error: "invalid_grant",
+      message: "Invalid user credentials",
+    });
+    expect(grant.state.error).toBe(error);
+    expect(grant.tokens).toBeNull();
+  });
+
+  it("an account with required actions left rejects with ProfileIncompleteError", async () => {
+    const { grant } = setup({
+      password: () =>
+        json({ error: "invalid_grant", error_description: "Account is not fully set up" }, 400),
+    });
+    const error = await grant.login({ username: "0xsig", password: "x" }).catch((e) => e);
+    expect(error).toBeInstanceOf(ProfileIncompleteError);
+    expect(error).toBeInstanceOf(KeycloakWalletError);
+    expect(error).toMatchObject({
+      name: "ProfileIncompleteError",
+      status: 400,
+      error: "invalid_grant",
+      message: "Account is not fully set up",
+    });
+    expect(grant.state.error).toBe(error);
+  });
+
+  it("maps the resolve_required_actions error code the same way", async () => {
+    const { grant } = setup({
+      password: () => json({ error: "resolve_required_actions" }, 400),
+    });
+    await expect(grant.login({ username: "0xsig", password: "x" })).rejects.toBeInstanceOf(
+      ProfileIncompleteError,
+    );
+  });
+
+  it("other invalid_grant refusals stay plain KeycloakWalletErrors", async () => {
+    const { grant } = setup({
+      password: () =>
+        json({ error: "invalid_grant", error_description: "Invalid user credentials" }, 400),
+    });
+    const error = await grant.login({ username: "0xsig", password: "x" }).catch((e) => e);
+    expect(error).toBeInstanceOf(KeycloakWalletError);
+    expect(error).not.toBeInstanceOf(ProfileIncompleteError);
+  });
+
+  it("every login round trip drops the memoized nonce, so the next sign-in gets a fresh one", async () => {
+    const { server, kc, grant } = setup({ reject: true });
+    await kc.getNonce();
+    await grant.login({ username: "0xsig", password: "x" }).catch(() => undefined);
+    await kc.getNonce();
+    expect(server.requests.filter((r) => r.url.endsWith("/nonce"))).toHaveLength(2);
+  });
+
+  it("refresh uses the stored refresh token and replaces the tokens", async () => {
+    const { server, grant } = setup();
+    await grant.login({ username: "0xsig", password: "x" });
+    const refreshed = await grant.refresh();
+    const req = server.requests.filter((r) => r.url.endsWith("/token"))[1];
+    expect(Object.fromEntries(new URLSearchParams(req.body))).toEqual({
+      client_id: "wallet-app",
+      grant_type: "refresh_token",
+      refresh_token: "refresh-1",
+    });
+    expect(refreshed.accessToken).toBe("access-2");
+    expect(grant.tokens?.refreshToken).toBe("refresh-2");
+  });
+
+  it("concurrent refreshes share one request", async () => {
+    const { server, grant } = setup();
+    await grant.login({ username: "0xsig", password: "x" });
+    const [a, b] = await Promise.all([grant.refresh(), grant.refresh()]);
+    expect(a).toBe(b);
+    expect(server.requests.filter((r) => r.url.endsWith("/token"))).toHaveLength(2);
+  });
+
+  it("a refused refresh (400 invalid_grant) clears the session", async () => {
+    const { grant } = setup();
+    await grant.login({ username: "0xsig", password: "x" });
+    await expect(grant.refresh("revoked")).rejects.toBeInstanceOf(KeycloakWalletError);
+    expect(grant.tokens).toBeNull();
+    expect(grant.state.error?.message).toBe("Token is not active");
+    await expect(grant.refresh()).rejects.toThrow(/no refresh token/);
+  });
+
+  it("a 401 on refresh clears the session", async () => {
+    const { grant } = setup({
+      refresh: () =>
+        json({ error: "unauthorized_client", error_description: "Invalid client" }, 401),
+    });
+    await grant.login({ username: "0xsig", password: "x" });
+    await expect(grant.refresh()).rejects.toMatchObject({ status: 401 });
+    expect(grant.tokens).toBeNull();
+  });
+
+  it.each([502, 503])(
+    "a %i on refresh (Keycloak restarting) keeps the tokens and surfaces the error",
+    async (status) => {
+      const { grant } = setup({ refresh: () => new Response("Bad Gateway", { status }) });
+      await grant.login({ username: "0xsig", password: "x" });
+      const error = await grant.refresh().catch((e) => e);
+      expect(error).toBeInstanceOf(KeycloakWalletError);
+      expect(error.status).toBe(status);
+      expect(grant.tokens?.refreshToken).toBe("refresh-1");
+      expect(grant.state.error).toBe(error);
+    },
+  );
+
+  it("a 400 other than invalid_grant keeps the tokens", async () => {
+    const { grant } = setup({
+      refresh: () =>
+        json({ error: "invalid_request", error_description: "Missing parameter" }, 400),
+    });
+    await grant.login({ username: "0xsig", password: "x" });
+    await expect(grant.refresh()).rejects.toMatchObject({ status: 400, error: "invalid_request" });
+    expect(grant.tokens?.accessToken).toBe("access-1");
+  });
+
+  it("a network failure on refresh keeps the tokens", async () => {
+    const { server, kc } = setup();
+    let down = false;
+    const flaky = keycloakWallet({
+      baseUrl: kc.baseUrl,
+      realm: kc.realm,
+      resource: kc.resource,
+      fetch: (input, init) =>
+        down ? Promise.reject(new TypeError("Failed to fetch")) : server.fetch(input, init),
+    }).directGrant({ clientId: "wallet-app", now: () => t0 });
+    await flaky.login({ username: "0xsig", password: "x" });
+    down = true;
+    await expect(flaky.refresh()).rejects.toThrow("Failed to fetch");
+    expect(flaky.tokens?.accessToken).toBe("access-1");
+  });
+
+  it("the next refresh after a kept 503 succeeds with the same refresh token", async () => {
+    let fail = true;
+    const { server, grant } = setup({
+      refresh: () =>
+        fail ? new Response("", { status: 503 }) : json({ access_token: "access-9" }),
+    });
+    await grant.login({ username: "0xsig", password: "x" });
+    await expect(grant.refresh()).rejects.toMatchObject({ status: 503 });
+    fail = false;
+    await expect(grant.refresh()).resolves.toMatchObject({ accessToken: "access-9" });
+    const refreshes = server.requests
+      .filter((r) => r.url.endsWith("/token"))
+      .map((r) => new URLSearchParams(r.body))
+      .filter((form) => form.get("grant_type") === "refresh_token");
+    expect(refreshes.map((form) => form.get("refresh_token"))).toEqual(["refresh-1", "refresh-1"]);
+    expect(grant.state.error).toBeNull();
+  });
+
+  describe("a login that lands while a refresh is in flight", () => {
+    function slowRefresh(answer: () => Response) {
+      let release!: () => void;
+      const gate = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      return {
+        release,
+        refresh: () => gate.then(answer),
+      };
+    }
+
+    it("wins over the refresh's tokens", async () => {
+      const slow = slowRefresh(() => json({ access_token: "stale", refresh_token: "stale" }));
+      const { grant } = setup({ refresh: slow.refresh });
+      await grant.login({ username: "0xsig", password: "x" });
+      const pending = grant.refresh();
+      const newer = await grant.login({ username: "0xsig2", password: "y" });
+      slow.release();
+      await expect(pending).resolves.toBe(newer);
+      expect(grant.tokens).toBe(newer);
+      expect(grant.tokens?.accessToken).not.toBe("stale");
+    });
+
+    it("is not cleared by the old refresh token's refusal", async () => {
+      const slow = slowRefresh(() =>
+        json({ error: "invalid_grant", error_description: "Token is not active" }, 400),
+      );
+      const { grant } = setup({ refresh: slow.refresh });
+      await grant.login({ username: "0xsig", password: "x" });
+      const pending = grant.refresh();
+      const newer = await grant.login({ username: "0xsig2", password: "y" });
+      slow.release();
+      await expect(pending).resolves.toBe(newer);
+      expect(grant.tokens).toBe(newer);
+      expect(grant.state.error).toBeNull();
+    });
+
+    it("a logout during the refresh stays signed out", async () => {
+      const slow = slowRefresh(() => json({ access_token: "stale", refresh_token: "stale" }));
+      const { grant } = setup({ refresh: slow.refresh });
+      await grant.login({ username: "0xsig", password: "x" });
+      const pending = grant.refresh();
+      await grant.logout();
+      slow.release();
+      await expect(pending).rejects.toThrow(/signed out/);
+      expect(grant.tokens).toBeNull();
+    });
+  });
+
+  it("getAccessToken refreshes an access token about to expire", async () => {
+    let now = t0;
+    const { grant } = setup({ now: () => now });
+    await grant.login({ username: "0xsig", password: "x" });
+    expect(await grant.getAccessToken()).toBe("access-1");
+    now = t0 + 290_000;
+    expect(await grant.getAccessToken()).toBe("access-2");
+    expect(await grant.getAccessToken({ minValiditySeconds: 0 })).toBe("access-2");
+  });
+
+  it("logout ends the Keycloak session and clears the tokens", async () => {
+    const { server, grant } = setup();
+    await grant.login({ username: "0xsig", password: "x" });
+    await grant.logout();
+    const req = server.requests.at(-1)!;
+    expect(req.url).toBe("https://kc.example.com/realms/main/protocol/openid-connect/logout");
+    expect(Object.fromEntries(new URLSearchParams(req.body))).toEqual({
+      client_id: "wallet-app",
+      refresh_token: "refresh-1",
+    });
+    expect(grant.tokens).toBeNull();
+    expect(await grant.getAccessToken()).toBeNull();
+  });
+});

package/src/keycloak/directGrant.ts

@@ -0,0 +1,214 @@
+import type { KeycloakWallet } from "./keycloakWallet";
+import {
+  KeycloakWalletError,
+  ProfileIncompleteError,
+  type KeycloakTokens,
+  type OnSign,
+  type WalletSignIn,
+} from "./types";
+
+export interface DirectGrantOptions {
+  clientId: string;
+  /** Default `openid`. */
+  scope?: string | string[];
+  /** Confidential clients only; a native or browser app is a public client. */
+  clientSecret?: string;
+  now?: () => number;
+}
+
+export interface DirectGrantState {
+  tokens: KeycloakTokens | null;
+  error: Error | null;
+}
+
+export interface DirectGrant {
+  readonly state: DirectGrantState;
+  readonly tokens: KeycloakTokens | null;
+  /** `onSign` for `<SIWEProvider>` / `<GpgProvider>`: exchanges the credential for tokens. */
+  onSign: OnSign;
+  /**
+   * Password grant with `username` = signature (or GPG blob) and `password` =
+   * base64(message). Rejects with `ProfileIncompleteError` when the account
+   * still has required actions; see that class for the browser fallback.
+   */
+  login(credentials: Pick<WalletSignIn, "username" | "password">): Promise<KeycloakTokens>;
+  /**
+   * Refresh-token grant; defaults to the stored refresh token. Keycloak
+   * refusing the token (400 invalid_grant, 401) clears the stored tokens; any
+   * other failure keeps them and only records the error. A login or logout
+   * that lands while the refresh is in flight wins: the refresh's answer is
+   * dropped and it resolves with the newer tokens (or rejects when signed out).
+   */
+  refresh(refreshToken?: string): Promise<KeycloakTokens>;
+  /** A valid access token, refreshed first when it expires within `minValiditySeconds` (default 30). */
+  getAccessToken(opts?: { minValiditySeconds?: number }): Promise<string | null>;
+  /** Ends the Keycloak session behind the refresh token and clears the stored tokens. */
+  logout(): Promise<void>;
+  subscribe(listener: (state: DirectGrantState) => void): () => void;
+}
+
+interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  id_token?: string;
+  token_type?: string;
+  scope?: string;
+  expires_in?: number;
+  refresh_expires_in?: number;
+  error?: string;
+  error_description?: string;
+}
+
+/**
+ * Keycloak refused the refresh token itself (revoked, expired, session gone)
+ * or the client: the stored tokens are dead. Anything else, a 5xx while
+ * Keycloak restarts or a dropped connection, leaves them worth retrying.
+ */
+function refreshRefused(error: unknown): boolean {
+  if (!(error instanceof KeycloakWalletError)) return false;
+  return error.status === 401 || (error.status === 400 && error.error === "invalid_grant");
+}
+
+/**
+ * Keycloak's answer when the credential is good but required actions are
+ * pending: 400 invalid_grant "Account is not fully set up". Older releases
+ * and some proxies surface the event name, resolve_required_actions, instead.
+ */
+function profileIncomplete(status: number, data: TokenResponse): boolean {
+  if (data.error === "resolve_required_actions") return true;
+  return (
+    status === 400 &&
+    data.error === "invalid_grant" &&
+    /not fully set up/i.test(data.error_description ?? "")
+  );
+}
+
+export function createDirectGrant(kc: KeycloakWallet, opts: DirectGrantOptions): DirectGrant {
+  const now = opts.now ?? Date.now;
+  const scope = Array.isArray(opts.scope) ? opts.scope.join(" ") : (opts.scope ?? "openid");
+  const listeners = new Set<(state: DirectGrantState) => void>();
+  let state: DirectGrantState = { tokens: null, error: null };
+  let refreshing: Promise<KeycloakTokens> | undefined;
+
+  const setState = (next: DirectGrantState) => {
+    state = next;
+    for (const listener of listeners) listener(state);
+  };
+
+  const form = (params: Record<string, string>) =>
+    new URLSearchParams({
+      client_id: opts.clientId,
+      ...params,
+      ...(opts.clientSecret ? { client_secret: opts.clientSecret } : {}),
+    }).toString();
+
+  const tokenRequest = async (params: Record<string, string>): Promise<KeycloakTokens> => {
+    const res = await kc.request(kc.tokenUrl, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: form(params),
+    });
+    const data = (await res.json().catch(() => ({}))) as TokenResponse;
+    if (!res.ok || !data.access_token) {
+      const Refusal = profileIncomplete(res.status, data)
+        ? ProfileIncompleteError
+        : KeycloakWalletError;
+      throw new Refusal(
+        data.error_description || data.error || `Keycloak token request failed (${res.status})`,
+        res.status,
+        { error: data.error, errorDescription: data.error_description },
+      );
+    }
+    const issuedAt = now();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      idToken: data.id_token,
+      tokenType: data.token_type ?? "Bearer",
+      scope: data.scope,
+      expiresAt: issuedAt + (data.expires_in ?? 0) * 1000,
+      refreshExpiresAt: data.refresh_expires_in
+        ? issuedAt + data.refresh_expires_in * 1000
+        : undefined,
+    };
+  };
+
+  const grant: DirectGrant = {
+    get state() {
+      return state;
+    },
+    get tokens() {
+      return state.tokens;
+    },
+    async login({ username, password }) {
+      try {
+        const tokens = await tokenRequest({ grant_type: "password", username, password, scope });
+        setState({ tokens, error: null });
+        return tokens;
+      } catch (error) {
+        setState({ tokens: state.tokens, error: error as Error });
+        throw error;
+      } finally {
+        kc.resetNonce();
+      }
+    },
+    onSign: async (credentials) => {
+      await grant.login(credentials);
+      return true;
+    },
+    refresh(refreshToken) {
+      const token = refreshToken ?? state.tokens?.refreshToken;
+      if (!token) return Promise.reject(new Error("no refresh token"));
+      if (!refreshing) {
+        const startedWith = state.tokens;
+        const superseded = (error: Error) => {
+          if (state.tokens) return state.tokens;
+          throw error;
+        };
+        refreshing = tokenRequest({ grant_type: "refresh_token", refresh_token: token })
+          .then(
+            (tokens) => {
+              if (state.tokens !== startedWith) {
+                return superseded(new Error("signed out while the refresh was in flight"));
+              }
+              setState({ tokens, error: null });
+              return tokens;
+            },
+            (error: Error) => {
+              if (state.tokens !== startedWith) return superseded(error);
+              setState({ tokens: refreshRefused(error) ? null : state.tokens, error });
+              throw error;
+            },
+          )
+          .finally(() => {
+            refreshing = undefined;
+          });
+      }
+      return refreshing;
+    },
+    async getAccessToken({ minValiditySeconds = 30 } = {}) {
+      const tokens = state.tokens;
+      if (!tokens) return null;
+      if (tokens.expiresAt - minValiditySeconds * 1000 > now()) return tokens.accessToken;
+      if (!tokens.refreshToken) return null;
+      return (await grant.refresh()).accessToken;
+    },
+    async logout() {
+      const token = state.tokens?.refreshToken;
+      setState({ tokens: null, error: null });
+      if (!token) return;
+      await kc.request(`${kc.realmUrl}/protocol/openid-connect/logout`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: form({ refresh_token: token }),
+      });
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+  return grant;
+}

package/src/keycloak/iife.ts

@@ -0,0 +1,3 @@
+import { mount } from "./mount";
+
+(globalThis as { MpoKeycloakWallet?: { mount: typeof mount } }).MpoKeycloakWallet = { mount };

package/src/keycloak/index.ts

@@ -0,0 +1,44 @@
+export {
+  keycloakWallet,
+  deriveKeycloakFromLocation,
+  toCredentials,
+  pkceChallenge,
+  type BrowserLogin,
+  type BrowserLoginUrlOptions,
+  type KeycloakWallet,
+  type KeycloakWalletOptions,
+} from "./keycloakWallet";
+export { browserFlow, type BrowserFlowOptions } from "./browserFlow";
+export {
+  createDirectGrant,
+  type DirectGrant,
+  type DirectGrantOptions,
+  type DirectGrantState,
+} from "./directGrant";
+export {
+  createWalletRegistration,
+  type RegisterWalletOptions,
+  type WalletRegistration,
+} from "./registerWallet";
+export {
+  useDirectLogin,
+  type DirectLoginStatus,
+  type UseDirectLoginResult,
+} from "./useDirectLogin";
+export {
+  useWalletLogin,
+  type UseWalletLoginOptions,
+  type UseWalletLoginResult,
+} from "./useWalletLogin";
+export { KeycloakWalletLogin, type KeycloakWalletLoginProps } from "./KeycloakWalletLogin";
+export { mount, type MountedKeycloakWalletLogin } from "./mount";
+export { hasUserActivation, isMobileBrowser } from "./device";
+export {
+  KeycloakWalletError,
+  ProfileIncompleteError,
+  type KeycloakTokens,
+  type KeycloakWalletResource,
+  type OnSign,
+  type WalletSignIn,
+} from "./types";
+export { StatusState } from "../connectkit/siwe/SIWEContext";