@multiplatform.one/keycloak 6.7.0 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/keycloak",
-  "version": "6.7.0",
+  "version": "7.0.0",
   "description": "keycloak client for multiplatform.one ecosystem",
   "keywords": [
     "auth",
@@ -45,6 +45,11 @@
       "types": "./types/one.d.ts",
       "import": "./src/one.ts",
       "require": "./src/one.ts"
+    },
+    "./oauth": {
+      "types": "./types/oauth/index.d.ts",
+      "import": "./src/oauth/index.ts",
+      "require": "./src/oauth/index.ts"
     }
   },
   "publishConfig": {
@@ -54,11 +59,11 @@
     "@better-auth/expo": "^1.6.9",
     "better-auth": "^1.6.9",
     "jwt-decode": "^4.0.0",
-    "@multiplatform.one/keycloak-js": "6.7.0",
-    "@multiplatform.one/store": "6.7.0"
+    "@multiplatform.one/keycloak-js": "7.0.0",
+    "@multiplatform.one/store": "7.0.0"
   },
   "devDependencies": {
-    "@tamagui/build": "2.0.0-rc.41",
+    "@tamagui/build": "2.7.6",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/lodash.camelcase": "^4.3.9",
@@ -70,15 +75,15 @@
     "react": "19.2.5",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.7.0",
-    "@multiplatform.one/platform": "6.7.0",
-    "@multiplatform.one/logger": "6.7.0",
-    "@multiplatform.one/test-utils": "6.7.0"
+    "@multiplatform.one/config": "7.0.0",
+    "@multiplatform.one/platform": "7.0.0",
+    "@multiplatform.one/logger": "7.0.0",
+    "@multiplatform.one/test-utils": "7.0.0"
   },
   "peerDependencies": {
     "react": "^19.1.0",
-    "@multiplatform.one/logger": "^6.7.0",
-    "@multiplatform.one/platform": "^6.7.0"
+    "@multiplatform.one/logger": "^7.0.0",
+    "@multiplatform.one/platform": "^7.0.0"
   },
   "optionalDependencies": {
     "expo-linking": "^55.0.15",

package/src/betterAuth/expoAuthFlow.native.spec.ts

@@ -0,0 +1,307 @@
+/**
+ * Specs for the hand-rolled native Better Auth flow (expoAuthFlow.native.ts):
+ * SSO sign-in (social → expo-authorization-proxy → cookie hand-back),
+ * SSO sign-out (fetch-then-browser-ride), the plain sign-out fallback, and
+ * the loopback host rewrite for simulators/emulators.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const secureStore = new Map<string, string>();
+
+vi.mock("expo-linking", () => ({
+  createURL: (path: string) => `multiplatform-one://${path.replace(/^\//, "")}`,
+  addEventListener: vi.fn(() => ({ remove: vi.fn() })),
+  openURL: vi.fn(async () => {}),
+}));
+vi.mock("expo-secure-store", () => ({
+  getItem: (key: string) => secureStore.get(key) ?? null,
+  setItem: (key: string, value: string) => {
+    secureStore.set(key, value);
+  },
+}));
+const openAuthSessionAsync = vi.fn(async (..._args: unknown[]) => ({ type: "dismiss" }) as const);
+const dismissAuthSession = vi.fn();
+vi.mock("expo-web-browser", () => ({
+  openAuthSessionAsync: (...args: unknown[]) => openAuthSessionAsync(...args),
+  dismissAuthSession: (...args: unknown[]) => dismissAuthSession(...args),
+  maybeCompleteAuthSession: vi.fn(),
+}));
+
+import { Platform } from "react-native";
+import {
+  createExpoAuthFlow,
+  ensureReturnUrlAuthority,
+  extractCookieFromReturnUrl,
+  normalizeForReturnMatch,
+  rewriteLoopbackHostForNative,
+} from "./expoAuthFlow.native";
+
+const BASE = "http://127.0.0.1:9999";
+// The vitest resolver aliases react-native -> react-native-web (Platform.OS
+// "web"), which rides the iOS/default branches; assert against the actual
+// platform so the spec also holds under a real react-native resolution.
+const DEVICE_LOOPBACK = Platform.OS === "android" ? "10.0.2.2" : "127.0.0.1";
+
+function jsonResponse(body: unknown, init?: ResponseInit) {
+  return new Response(JSON.stringify(body), {
+    headers: { "content-type": "application/json" },
+    ...init,
+  });
+}
+
+describe("rewriteLoopbackHostForNative", () => {
+  it("rewrites localhost for the device", () => {
+    expect(rewriteLoopbackHostForNative("http://localhost:8000")).toBe(
+      `http://${DEVICE_LOOPBACK}:8000`,
+    );
+    expect(rewriteLoopbackHostForNative("http://127.0.0.1:8000/x")).toBe(
+      `http://${DEVICE_LOOPBACK}:8000/x`,
+    );
+  });
+
+  it("passes non-loopback hosts through untouched", () => {
+    expect(rewriteLoopbackHostForNative("http://10.1.2.3:8000")).toBe("http://10.1.2.3:8000");
+    expect(rewriteLoopbackHostForNative("https://bench.example.com")).toBe(
+      "https://bench.example.com",
+    );
+    expect(rewriteLoopbackHostForNative("not a url")).toBe("not a url");
+  });
+});
+
+describe("normalizeForReturnMatch", () => {
+  it("matches createURL's empty-authority form against iOS's delivered form", () => {
+    // Linking.createURL("/") yields ":///", iOS delivers "://?cookie=…".
+    const base = normalizeForReturnMatch("multiplatform-one:///");
+    expect(normalizeForReturnMatch("multiplatform-one://?cookie=abc").startsWith(base)).toBe(true);
+    expect(normalizeForReturnMatch("multiplatform-one:///?cookie=abc").startsWith(base)).toBe(true);
+    expect(normalizeForReturnMatch("other-scheme://?cookie=abc").startsWith(base)).toBe(false);
+  });
+
+  it("drops query and fragment before comparing", () => {
+    expect(normalizeForReturnMatch("exp://192.168.1.5:8081/--/?cookie=x#frag")).toBe(
+      "exp://192.168.1.5:8081/--",
+    );
+  });
+});
+
+describe("ensureReturnUrlAuthority", () => {
+  it("gives bare-scheme URLs a host segment (Keycloak UriBuilder needs one)", () => {
+    expect(ensureReturnUrlAuthority("multiplatform-one:///", "signed-out")).toBe(
+      "multiplatform-one://signed-out",
+    );
+    expect(ensureReturnUrlAuthority("multiplatform-one://", "signed-out")).toBe(
+      "multiplatform-one://signed-out",
+    );
+  });
+
+  it("leaves URLs with an authority untouched", () => {
+    expect(ensureReturnUrlAuthority("exp://192.168.1.5:8081/--/", "signed-out")).toBe(
+      "exp://192.168.1.5:8081/--/",
+    );
+    expect(ensureReturnUrlAuthority("multiplatform-one://home", "signed-out")).toBe(
+      "multiplatform-one://home",
+    );
+  });
+});
+
+describe("extractCookieFromReturnUrl", () => {
+  it("reads cookie from the iOS-delivered empty-authority form", () => {
+    expect(
+      extractCookieFromReturnUrl("multiplatform-one://?cookie=better-auth.session_token=tok"),
+    ).toBe("better-auth.session_token=tok");
+    expect(
+      extractCookieFromReturnUrl("multiplatform-one:///?cookie=better-auth.session_token=tok"),
+    ).toBe("better-auth.session_token=tok");
+  });
+
+  it("decodes and ignores fragment / extra params (Expo Go exp:// too)", () => {
+    expect(
+      extractCookieFromReturnUrl("exp://192.168.1.5:8081/--/?foo=1&cookie=name%3Dvalue%20x#frag"),
+    ).toBe("name=value x");
+  });
+
+  it("returns null when the return has no cookie", () => {
+    expect(extractCookieFromReturnUrl("multiplatform-one://signed-out")).toBeNull();
+    expect(extractCookieFromReturnUrl("multiplatform-one://?state=abc")).toBeNull();
+  });
+});
+
+describe("expoAuthFlow signOut (single sign-out)", () => {
+  beforeEach(() => {
+    secureStore.clear();
+    openAuthSessionAsync.mockClear();
+    // A live session cookie in the jar, as after a completed sign-in.
+    secureStore.set(
+      "better-auth_cookie",
+      JSON.stringify({
+        "better-auth.session_token": { value: "tok", expires: null },
+      }),
+    );
+  });
+
+  it("rides the Keycloak end-session URL through the auth browser and clears the jar", async () => {
+    const endSessionUrl =
+      "http://127.0.0.1:9999/auth/realms/myrealm/protocol/openid-connect/logout?id_token_hint=x";
+    const fetchMock = vi.fn(async (url: string | URL, _init?: RequestInit) => {
+      const href = String(url);
+      expect(href).toContain("/api/auth/sign-out/sso?mode=json");
+      expect(href).toContain(encodeURIComponent("multiplatform-one://"));
+      return jsonResponse({ redirect: true, url: endSessionUrl });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signOut();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    // The session cookie rode the sign-out fetch (that's what authenticates it).
+    const init = fetchMock.mock.calls[0][1];
+    expect((init?.headers as Record<string, string>).cookie).toContain(
+      "better-auth.session_token=tok",
+    );
+    // The browser ride hits the end-session URL, returning to the app scheme
+    // (with the authority segment Keycloak's redirect builder requires).
+    expect(openAuthSessionAsync).toHaveBeenCalledWith(
+      endSessionUrl,
+      "multiplatform-one://signed-out",
+      expect.anything(),
+    );
+    expect(secureStore.get("better-auth_cookie")).toBe("{}");
+  });
+
+  it("skips the browser ride when the server answers redirect:false", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({ redirect: false, url: "multiplatform-one://" })),
+    );
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signOut();
+    expect(openAuthSessionAsync).not.toHaveBeenCalled();
+    expect(secureStore.get("better-auth_cookie")).toBe("{}");
+  });
+
+  it("falls back to plain /sign-out when the sso endpoint is missing", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string | URL) => {
+        const href = String(url);
+        calls.push(href);
+        if (href.includes("/sign-out/sso")) return new Response("nope", { status: 404 });
+        return jsonResponse({ success: true });
+      }),
+    );
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signOut();
+    expect(calls.some((href) => href.endsWith("/api/auth/sign-out"))).toBe(true);
+    expect(openAuthSessionAsync).not.toHaveBeenCalled();
+    expect(secureStore.get("better-auth_cookie")).toBe("{}");
+  });
+
+  it("still clears the jar when the user backs out of the browser ride", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({ redirect: true, url: "http://kc/logout" })),
+    );
+    openAuthSessionAsync.mockResolvedValueOnce({ type: "cancel" } as never);
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signOut();
+    expect(secureStore.get("better-auth_cookie")).toBe("{}");
+  });
+});
+
+describe("expoAuthFlow signIn (OIDC URL/state machine)", () => {
+  beforeEach(() => {
+    secureStore.clear();
+    openAuthSessionAsync.mockReset();
+    openAuthSessionAsync.mockResolvedValue({ type: "dismiss" } as never);
+  });
+
+  it("POSTs /sign-in/social then opens the expo-authorization-proxy in the auth session", async () => {
+    const authz = "http://kc/realms/myrealm/protocol/openid-connect/auth?client_id=app";
+    const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
+      const href = String(url);
+      expect(href).toContain("/api/auth/sign-in/social");
+      expect(init?.method).toBe("POST");
+      const body = JSON.parse(String(init?.body));
+      expect(body.provider).toBe("keycloak");
+      expect(body.callbackURL).toContain("multiplatform-one://");
+      expect((init?.headers as Record<string, string>)["expo-origin"]).toContain(
+        "multiplatform-one://",
+      );
+      return jsonResponse({ url: authz, redirect: true });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    openAuthSessionAsync.mockResolvedValueOnce({
+      type: "success",
+      url: "multiplatform-one://?cookie=better-auth.session_token=sess",
+    } as never);
+
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signIn("keycloak");
+
+    expect(openAuthSessionAsync).toHaveBeenCalledTimes(1);
+    const [proxyUrl, returnUrl] = openAuthSessionAsync.mock.calls[0];
+    expect(String(proxyUrl)).toContain("/api/auth/expo-authorization-proxy?");
+    expect(String(proxyUrl)).toContain(encodeURIComponent(authz));
+    expect(String(returnUrl).startsWith("multiplatform-one://")).toBe(true);
+
+    const sessionFetch = vi.fn(async (url: string | URL, init?: RequestInit) => {
+      expect(String(url)).toContain("/api/auth/get-session");
+      expect((init?.headers as Record<string, string>).cookie).toContain(
+        "better-auth.session_token=sess",
+      );
+      return jsonResponse({ user: { id: "u1", name: "Test User" } });
+    });
+    vi.stubGlobal("fetch", sessionFetch);
+    const session = await flow.getSession();
+    expect(session?.user?.name).toBe("Test User");
+  });
+
+  it("forwards oauth_state from the jar on the proxy URL", async () => {
+    secureStore.set(
+      "better-auth_cookie",
+      JSON.stringify({
+        "better-auth.oauth_state": { value: "state-xyz", expires: null },
+      }),
+    );
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({ url: "http://kc/auth", redirect: true })),
+    );
+    openAuthSessionAsync.mockResolvedValueOnce({ type: "dismiss" } as never);
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signIn("keycloak");
+    const proxyUrl = String(openAuthSessionAsync.mock.calls[0][0]);
+    expect(proxyUrl).toContain("oauthState=state-xyz");
+  });
+
+  it("is a no-op when the user dismisses the auth session", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({ url: "http://kc/auth", redirect: true })),
+    );
+    const flow = createExpoAuthFlow(BASE);
+    await flow.signIn("keycloak");
+    expect(JSON.parse(secureStore.get("better-auth_cookie") || "{}")).toEqual({});
+  });
+
+  it("throws when the server omits the authorization url", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({})),
+    );
+    const flow = createExpoAuthFlow(BASE);
+    await expect(flow.signIn("keycloak")).rejects.toThrow(/no authorization url/);
+  });
+
+  it("throws on a failed social sign-in", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("nope", { status: 500 })),
+    );
+    const flow = createExpoAuthFlow(BASE);
+    await expect(flow.signIn("keycloak")).rejects.toThrow(/sign-in failed \(500\)/);
+  });
+});

package/src/betterAuth/expoAuthFlow.native.ts

@@ -1,6 +1,7 @@
 /**
- * Hand-rolled Better Auth flow for native (Expo) — fetch + expo-web-browser +
- * SecureStore, NO better-auth client packages.
+ * Hand-rolled Better Auth flow for native (Expo) — fetch + expo-web-browser
+ * (ASWebAuthenticationSession / Chrome Custom Tabs) + SecureStore, NO
+ * better-auth client packages.
  *
  * Why not @better-auth/expo/client: its import graph drags better-auth's
  * cookies module -> @better-auth/core db schema -> zod into the Hermes bundle,
@@ -16,6 +17,12 @@ import * as Linking from "expo-linking";
 import * as SecureStore from "expo-secure-store";
 import * as WebBrowser from "expo-web-browser";
 
+try {
+  WebBrowser.maybeCompleteAuthSession?.();
+} catch {
+  /* web-only redirect completion; native is a no-op */
+}
+
 const COOKIE_KEY = "better-auth_cookie";
 const SECURE_COOKIE_PREFIX = "__Secure-";
 
@@ -88,7 +95,14 @@ function getOAuthState(): string | null {
 
 export interface ExpoAuthFlow {
   signIn(provider: string, callbackURL?: string): Promise<void>;
-  signOut(): Promise<void>;
+  /**
+   * Ends the Better Auth session AND (when the server exposes the
+   * keycloak-sso plugin) the Keycloak SSO session, riding the OIDC
+   * end-session endpoint through the same browser that holds the SSO
+   * cookie. `postLogoutRedirectUri` is where that browser hands control
+   * back (defaults to the app's own runtime URL).
+   */
+  signOut(postLogoutRedirectUri?: string): Promise<void>;
   getSession(): Promise<{ user?: { id: string; email?: string; name?: string } } | null>;
   /** Valid provider access token (server refreshes when expired). */
   getAccessToken(
@@ -96,6 +110,144 @@ export interface ExpoAuthFlow {
   ): Promise<{ accessToken?: string; accessTokenExpiresAt?: string } | null>;
 }
 
+/**
+ * Rewrite a loopback host for the device the app actually runs on:
+ * `localhost` inside the iOS simulator can resolve to `::1`, where unrelated
+ * daemons may squat the port (the reason the web env pins 127.0.0.1), and
+ * Android emulators reach the host machine at 10.0.2.2, never loopback.
+ * Non-loopback hosts (LAN IPs, real domains) pass through untouched.
+ *
+ * String-based on purpose: React Native's minimal URL polyfill does not
+ * implement the `hostname` SETTER (reads work, mutation throws), so a
+ * new-URL-and-assign rewrite silently no-ops on device.
+ */
+export function rewriteLoopbackHostForNative(configured: string): string {
+  const deviceHost = Platform.OS === "android" ? "10.0.2.2" : "127.0.0.1";
+  return configured.replace(/^(https?:\/\/)(localhost|127\.0\.0\.1)(?=[:/]|$)/i, `$1${deviceHost}`);
+}
+
+/**
+ * Loosen a return URL for prefix matching: drop query/fragment and collapse
+ * the slash run after the scheme. `Linking.createURL("/")` yields
+ * `multiplatform-one:///` (empty authority) but iOS delivers the redirect as
+ * `multiplatform-one://?cookie=…` — a strict startsWith between the two
+ * misses, leaving the sign-in promise pending forever (observed on the
+ * 2026-08-13 simulator run).
+ */
+export function normalizeForReturnMatch(url: string): string {
+  return url
+    .split("?")[0]
+    .split("#")[0]
+    .replace(/:\/{2,}/, "://")
+    .replace(/\/+$/, "");
+}
+
+/**
+ * Give a bare-scheme URL (`multiplatform-one:///` — what Linking.createURL
+ * emits for custom app schemes: empty authority) a host segment. OIDC
+ * post-logout redirects need it: Keycloak's redirect builder (Java
+ * UriBuilder) throws "empty host" appending the `state` param to an
+ * authority-less URI, answering 500 "We are sorry" instead of returning to
+ * the app. URLs that already carry an authority (exp://host:port/…) pass
+ * through untouched.
+ */
+export function ensureReturnUrlAuthority(url: string, segment: string): string {
+  return url.replace(/^([a-z0-9.+-]+:)\/{2,3}(?=\?|#|$)/i, `$1//${segment}`);
+}
+
+/**
+ * Pull the Better Auth session cookie out of an OAuth return URL without
+ * `new URL()`. React Native's URL polyfill throws or drops search on
+ * authority-less custom schemes (`multiplatform-one://?cookie=…` — the
+ * shape iOS actually delivers). Mirrors `URLSearchParams.get("cookie")`
+ * including decodeURIComponent.
+ */
+export function extractCookieFromReturnUrl(returnUrl: string): string | null {
+  const q = returnUrl.indexOf("?");
+  if (q === -1) return null;
+  const query = returnUrl.slice(q + 1).split("#")[0];
+  for (const part of query.split("&")) {
+    const eq = part.indexOf("=");
+    const key = eq === -1 ? part : part.slice(0, eq);
+    let decodedKey: string;
+    try {
+      decodedKey = decodeURIComponent(key.replace(/\+/g, " "));
+    } catch {
+      decodedKey = key;
+    }
+    if (decodedKey !== "cookie") continue;
+    const raw = eq === -1 ? "" : part.slice(eq + 1);
+    try {
+      return decodeURIComponent(raw.replace(/\+/g, " "));
+    } catch {
+      return raw;
+    }
+  }
+  return null;
+}
+
+/**
+ * Open `url` in the platform OAuth-return browser (ASWebAuthenticationSession
+ * on iOS, Chrome Custom Tabs on Android — the Slack / Linear / Discord bar)
+ * and resolve with the custom-scheme return URL (or undefined when the user
+ * backs out).
+ *
+ * A Linking listener runs for the same window: iOS sometimes delivers the
+ * app-scheme return as a deep link while the auth session is still up (or
+ * reports dismiss a tick before the URL arrives). Whichever fires first
+ * wins. `preferEphemeralSession: false` so the Keycloak SSO cookie survives
+ * across the sign-in session and the matching sign-out end-session ride.
+ */
+async function openAuthBrowser(
+  url: string,
+  returnUrlBase: string,
+  options?: { timeoutMs?: number },
+): Promise<string | undefined> {
+  const returnBase = normalizeForReturnMatch(returnUrlBase);
+  let returned: string | undefined;
+  const linkSub = Linking.addEventListener("url", ({ url: next }) => {
+    if (!next || returned) return;
+    if (!normalizeForReturnMatch(next).startsWith(returnBase)) return;
+    returned = next;
+    try {
+      WebBrowser.dismissAuthSession();
+    } catch {
+      /* session already gone */
+    }
+  });
+  const timer = options?.timeoutMs
+    ? setTimeout(() => {
+        if (returned) return;
+        returned = "";
+        try {
+          WebBrowser.dismissAuthSession();
+        } catch {
+          /* session already gone */
+        }
+      }, options.timeoutMs)
+    : undefined;
+  try {
+    const result = await WebBrowser.openAuthSessionAsync(url, returnUrlBase, {
+      preferEphemeralSession: false,
+    });
+    if (!returned && result.type === "success" && "url" in result && result.url) {
+      returned = result.url;
+    }
+    if (!returned) {
+      // Late iOS deep-link after the session reports dismiss.
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return returned || undefined;
+  } finally {
+    if (timer) clearTimeout(timer);
+    try {
+      linkSub.remove();
+    } catch {
+      /* already removed */
+    }
+  }
+}
+
 // The app mounts ONE AuthProvider, which creates one flow. Expose it so
 // non-React consumers (the Frappe Bearer-token getter) can reach the same
 // cookie jar + base URL.
@@ -148,67 +300,49 @@ export function createExpoAuthFlow(baseURL: string, scheme?: string): ExpoAuthFl
       if (oauthState) params.append("oauthState", oauthState);
       const proxyURL = `${base}/api/auth/expo-authorization-proxy?${params.toString()}`;
 
-      // Which browser opens the Keycloak login page differs by platform, because
-      // the wallet deeplink (metamask://connect?channelId=…, a CUSTOM scheme
-      // emitted by the classic @metamask/sdk connector) must be able to app-switch
-      // to MetaMask from inside it:
-      //
-      //  - ANDROID: a Chrome Custom Tab (openAuthSessionAsync). Custom Tabs DO
-      //    launch other apps via custom schemes, and the tab is hosted by + returns
-      //    to THIS app, so it stays warm across the wallet bounce and the KC page
-      //    receives the MetaMask-SDK relay response, then hands the custom-scheme
-      //    return URL (to?cookie=…) back to us.
-      //  - iOS: ASWebAuthenticationSession (what openAuthSessionAsync maps to)
-      //    REFUSES to launch other apps via custom schemes — it's an OAuth-return
-      //    surface only, so "Open MetaMask" does nothing (verified on-device:
-      //    SafariViewService never app-switches to io.metamask). Full system Safari
-      //    via Linking.openURL DOES app-switch to MetaMask (iOS shows an "Open in
-      //    MetaMask?" prompt for custom schemes). The wallet signs over the SDK
-      //    relay, KC verifies + redirects to the custom-scheme return URL, and
-      //    Safari hands that back to the app, caught by a Linking listener.
+      // Platform-split browser choice: see openAuthBrowser.
       const toBase = to.split("?")[0];
-      let returnUrl: string | undefined;
-      if (Platform.OS === "ios") {
-        returnUrl = await new Promise<string | undefined>((resolve, reject) => {
-          let settled = false;
-          const linkSub = Linking.addEventListener("url", ({ url }) => {
-            if (settled || !url || !url.startsWith(toBase)) return;
-            settled = true;
-            try {
-              linkSub.remove();
-            } catch {
-              /* already removed */
-            }
-            resolve(url);
-          });
-          Linking.openURL(proxyURL).catch((e) => {
-            if (settled) return;
-            settled = true;
-            try {
-              linkSub.remove();
-            } catch {
-              /* already removed */
-            }
-            reject(e instanceof Error ? e : new Error(`sign-in openURL failed: ${e}`));
-          });
-        });
-      } else {
-        const result = await WebBrowser.openAuthSessionAsync(proxyURL, toBase, {
-          preferEphemeralSession: false, // keep the SSO + siww nonce cookie across the wallet bounce
-        });
-        returnUrl = result.type === "success" && "url" in result ? result.url : undefined;
-      }
+      const returnUrl = await openAuthBrowser(proxyURL, toBase);
       if (!returnUrl) {
         // dismissed / cancelled — treat as a no-op sign-in (user backed out)
         return;
       }
-      const cookie = new URL(returnUrl).searchParams.get("cookie");
+      const cookie = extractCookieFromReturnUrl(returnUrl);
       if (cookie) absorbSetCookie(cookie);
     },
 
-    async signOut() {
+    async signOut(postLogoutRedirectUri?: string) {
+      const to = ensureReturnUrlAuthority(
+        postLogoutRedirectUri || Linking.createURL("/"),
+        "signed-out",
+      );
       try {
-        await authFetch("/sign-out", { method: "POST", body: "{}" });
+        // Single sign-out via the server's keycloak-sso plugin: the fetch
+        // (carrying the SecureStore session cookies) revokes the Better Auth
+        // session and answers with the Keycloak end-session URL, which we
+        // then ride through the system browser — the ONLY place the KC SSO
+        // cookie lives. Without that ride the next sign-in silently
+        // re-authenticates.
+        const res = await authFetch(
+          `/sign-out/sso?mode=json&callbackURL=${encodeURIComponent(to)}`,
+          { method: "GET" },
+        );
+        if (!res.ok) throw new Error(`sign-out/sso failed (${res.status})`);
+        const data = (await res.json().catch(() => null)) as {
+          redirect?: boolean;
+          url?: string;
+        } | null;
+        if (data?.redirect && data.url) {
+          // User backing out of the browser is fine: the local session is
+          // already dead; only the KC SSO cookie may survive.
+          await openAuthBrowser(data.url, to.split("?")[0], { timeoutMs: 120_000 }).catch(
+            () => undefined,
+          );
+        }
+      } catch {
+        // Server without the keycloak-sso plugin (or unreachable): fall back
+        // to the plain Better Auth sign-out so the local session still dies.
+        await authFetch("/sign-out", { method: "POST", body: "{}" }).catch(() => undefined);
       } finally {
         writeJar({});
       }