@multiplatform.one/auth 7.7.2

package/src/index.ts

@@ -0,0 +1,665 @@
+/**
+ * @multiplatform.one/auth
+ *
+ * Better Auth helpers for multiplatform.one apps with Keycloak.
+ * Provides factory functions for auth instances, route handlers, and session helpers.
+ *
+ * @example
+ * ```ts
+ * import { createAuth, createAuthRouteHandler, createSessionHelpers } from "@multiplatform.one/auth";
+ *
+ * export const auth = createAuth();
+ * export const { GET, POST } = createAuthRouteHandler(auth);
+ * export const { verifyAuth, getSession } = createSessionHelpers(auth);
+ * ```
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { betterAuth, matchesHostPattern } from "better-auth";
+import type { BetterAuthPlugin } from "better-auth";
+import {
+  APIError,
+  createAuthEndpoint,
+  createAuthMiddleware,
+  getSessionFromCtx,
+  isAPIError,
+} from "better-auth/api";
+import { deleteSessionCookie, getAccountCookie } from "better-auth/cookies";
+import { genericOAuth, keycloak } from "better-auth/plugins";
+import { expo } from "@better-auth/expo";
+import { FAILED_TO_GET_ACCESS_TOKEN, TOKEN_REFRESH_UNAVAILABLE } from "./accessTokenRefresh";
+
+export {
+  ACCESS_TOKEN_RETRY_DELAYS_MS,
+  FAILED_TO_GET_ACCESS_TOKEN,
+  TOKEN_REFRESH_UNAVAILABLE,
+  classifyAccessTokenResponse,
+  retryWhileTransient,
+  watchDocumentVisible,
+} from "./accessTokenRefresh";
+export type { AccessTokenFailureKind, RetryAttemptResult } from "./accessTokenRefresh";
+
+/**
+ * Origin of the request currently being handled (dev only). better-auth's
+ * genericOAuth plugin builds OAuth redirect URIs from the context captured at
+ * INIT time, so a dev server reachable on several hosts (localhost + LAN IP +
+ * *.local) would pin callbacks to one of them — and the session cookie from a
+ * callback on the wrong host never reaches the origin the visitor is actually
+ * browsing. The route handler stores each request's origin here, and the dev
+ * redirect-URI getter (see createAuth) resolves against it per request.
+ */
+const requestOriginStorage = new AsyncLocalStorage<string>();
+
+/**
+ * The visitor origin for the request being handled. The app may sit behind
+ * the bench's dev proxy (browser → :8000 → one server :3456), where
+ * `req.url` shows the proxy target — so prefer `X-Forwarded-Proto/Host`
+ * (the bench proxy sets them for exactly this purpose), then the browser's
+ * `Origin` header, then the request URL. Forwarded/origin hosts are only
+ * honored when they match the private-network dev allowlist, so a spoofed
+ * header can never steer OAuth redirects at a public host.
+ */
+function deriveRequestOrigin(req: Request): string | undefined {
+  const isDevHost = (host: string) =>
+    DEV_LAN_HOST_PATTERNS.some((pattern) => matchesHostPattern(host, pattern));
+
+  const forwardedHost = req.headers.get("x-forwarded-host");
+  if (forwardedHost && isDevHost(forwardedHost)) {
+    const proto = req.headers.get("x-forwarded-proto") === "https" ? "https" : "http";
+    return `${proto}://${forwardedHost}`;
+  }
+
+  const originHeader = req.headers.get("origin");
+  if (originHeader) {
+    try {
+      const url = new URL(originHeader);
+      if (isDevHost(url.host)) return url.origin;
+    } catch {
+      // fall through to the request URL
+    }
+  }
+
+  try {
+    return new URL(req.url).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export interface KeycloakOptions {
+  baseUrl?: string;
+  realm?: string;
+  clientId?: string;
+  clientSecret?: string;
+}
+
+export interface CreateAuthOptions {
+  /** Base path for auth routes (default: "/api/auth") */
+  basePath?: string;
+  /** Base URL of the app (reads BASE_URL env var, or defaults to localhost:ONE_PORT) */
+  baseUrl?: string;
+  /** Auth secret (reads SECRET env var) */
+  secret?: string;
+  /** Trusted origins for CORS (auto-includes baseUrl and keycloak URL) */
+  trustedOrigins?: string[];
+  /** Keycloak configuration (reads env vars by default) */
+  keycloak?: KeycloakOptions;
+  /** Session cookie max age in seconds (default: 7 days) */
+  sessionMaxAge?: number;
+  /** Include @better-auth/expo plugin (default: true) */
+  enableExpo?: boolean;
+  /** Additional better-auth plugins */
+  plugins?: Parameters<typeof betterAuth>[0]["plugins"];
+  /**
+   * Database URL or Kysely adapter.
+   * Defaults to a SQLite file at `$DATA_DIR/better-auth.db` (or `./better-auth.db`).
+   */
+  database?: Parameters<typeof betterAuth>[0]["database"];
+}
+
+/** Structural type for a Better Auth instance used by helpers. */
+export interface AuthLike {
+  handler: (request: Request) => Promise<Response> | Response;
+  api: {
+    getSession: (opts: { headers: Headers }) => Promise<unknown>;
+  };
+}
+
+// ─── createAuth ─────────────────────────────────────────────────────
+
+/**
+ * Private-network host patterns (loopback, RFC1918 ranges, mDNS) that dev
+ * builds accept for LAN access — opening the app from another device (or the
+ * dev machine's own LAN IP, e.g. http://10.x.x.x:3456) must not 403 sign-in
+ * or build OAuth callbacks against localhost. Matched by better-auth's
+ * wildcard matcher against the request host (which includes the port).
+ * Never applied in production.
+ */
+const DEV_LAN_HOST_PATTERNS = [
+  "localhost",
+  "localhost:*",
+  "127.0.0.1",
+  "127.0.0.1:*",
+  "10.*",
+  "192.168.*",
+  "172.*",
+  "*.local",
+  "*.local:*",
+];
+
+// ─── Keycloak SSO plugin (front-channel logout + token resilience) ──
+
+interface KeycloakSsoPluginOptions {
+  /** Realm name (for OIDC endpoint paths). */
+  realm: string;
+  /** OAuth client id sent to the end-session endpoint. */
+  clientId: string;
+  /** OAuth client secret (for the refresh-failure classification replay). */
+  clientSecret: string;
+  /** Backchannel issuer (server-to-server), e.g. http://localhost:8080/auth/realms/myrealm */
+  issuer: string;
+  /** Fallback visitor origin when none can be derived from the request. */
+  baseUrl: string;
+  /** Browser-facing Keycloak base for a visitor origin (proxy-aware). */
+  publicKeycloakBaseFor: (requestOrigin?: string) => string | undefined;
+}
+
+/** Minimal shape of a stored OAuth account used by the SSO plugin. */
+interface KeycloakAccountLike {
+  providerId?: string;
+  idToken?: string | null;
+  refreshToken?: string | null;
+}
+
+/**
+ * Better Auth plugin wiring real single-sign-out and refresh resilience for
+ * the Keycloak provider:
+ *
+ * - `GET /sign-out/sso`: browser-navigable sign-out that ends the Better Auth
+ *   session AND the Keycloak SSO session. It clears the local session, then
+ *   302s through Keycloak's end-session endpoint (same-origin /auth proxy,
+ *   `id_token_hint` + `post_logout_redirect_uri`) so revisiting an SSO-first
+ *   login page shows Keycloak's login form instead of silently re-logging in.
+ *   Use `?callbackURL=/path` to choose the post-logout landing page.
+ *   Native clients pass `?mode=json`: their Better Auth cookies live in a
+ *   SecureStore jar (attachable to a fetch, but NOT to the system browser
+ *   that holds the Keycloak SSO cookie), so instead of a 302 the endpoint
+ *   answers `{ redirect, url }` — the same end-session URL, which the app
+ *   then rides through the system browser itself. Session deletion and
+ *   cookie clearing behave identically in both modes.
+ *
+ * - after-hook on `/get-access-token`: better-auth collapses every refresh
+ *   failure into `FAILED_TO_GET_ACCESS_TOKEN` (400). We reclassify:
+ *     • DEFINITIVE (`invalid_grant` / `invalid_token`, or no refresh token):
+ *       revoke the Better Auth session, clear cookies, keep the 400 so
+ *       clients sign out instead of silently degrading to guest requests.
+ *     • TRANSIENT (Keycloak unreachable, 5xx, or the replay itself succeeded
+ *       — the original failure happened after the token exchange): rewrite
+ *       to `TOKEN_REFRESH_UNAVAILABLE` (5xx) and KEEP the session. Clients
+ *       retry with backoff (see `retryWhileTransient`) so a Keycloak bounce
+ *       never looks like a logout.
+ */
+function createKeycloakSsoPlugin(options: KeycloakSsoPluginOptions) {
+  const { realm, clientId, clientSecret, issuer, baseUrl, publicKeycloakBaseFor } = options;
+  const tokenEndpoint = `${issuer}/protocol/openid-connect/token`;
+
+  /** Visitor origin for the current request (route-handler ALS, then headers). */
+  const resolveVisitorOrigin = (request?: Request): string | undefined =>
+    requestOriginStorage.getStore() ?? (request ? deriveRequestOrigin(request) : undefined);
+
+  /**
+   * Replay the refresh against Keycloak to classify a failure. Only an
+   * explicit OAuth `invalid_grant`/`invalid_token` answer is definitive —
+   * anything else (network error, 5xx, or even success, e.g. the original
+   * failure happened after the token exchange) is treated as transient.
+   */
+  const isRefreshDefinitivelyDead = async (refreshToken: string): Promise<boolean> => {
+    try {
+      const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+          client_id: clientId,
+          client_secret: clientSecret,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) return false;
+      if (res.status !== 400 && res.status !== 401) return false;
+      const body = (await res.json().catch(() => null)) as { error?: string } | null;
+      return body?.error === "invalid_grant" || body?.error === "invalid_token";
+    } catch {
+      return false;
+    }
+  };
+
+  const signOutSso = createAuthEndpoint("/sign-out/sso", { method: "GET" }, async (ctx) => {
+    const visitorOrigin = resolveVisitorOrigin(ctx.request) ?? baseUrl;
+    const searchParams = ctx.request ? new URL(ctx.request.url).searchParams : undefined;
+    const rawCallback = searchParams?.get("callbackURL") ?? null;
+    // Native answer mode: JSON body instead of a 302 (see plugin doc above).
+    const jsonMode = searchParams?.get("mode") === "json";
+    const answer = (url: string, redirect: boolean) => {
+      if (jsonMode) return ctx.json({ redirect, url });
+      throw ctx.redirect(url);
+    };
+    const callbackURL = rawCallback || "/";
+    // OIDC requires an absolute post_logout_redirect_uri; app-relative paths
+    // resolve against the origin the visitor is actually on.
+    const postLogoutRedirect = callbackURL.startsWith("/")
+      ? `${visitorOrigin}${callbackURL}`
+      : callbackURL;
+
+    // Capture the id_token BEFORE the session dies: with it Keycloak logs
+    // out without a confirmation screen (expired id_tokens are accepted).
+    // Tokens are stored unencrypted here (account.encryptOAuthTokens is not
+    // enabled by createAuth); the account cookie covers sessions whose DB
+    // rows vanished (e.g. dev-server restart with the memory adapter).
+    let idTokenHint: string | undefined;
+    const sessionToken = await ctx.getSignedCookie(
+      ctx.context.authCookies.sessionToken.name,
+      ctx.context.secret,
+    );
+    const session = await getSessionFromCtx(ctx).catch(() => null);
+    if (session) {
+      const accounts = (await ctx.context.internalAdapter
+        .findAccounts(session.user.id)
+        .catch(() => [])) as KeycloakAccountLike[];
+      idTokenHint =
+        accounts.find((account) => account.providerId === "keycloak")?.idToken ?? undefined;
+    }
+    if (!idTokenHint) {
+      const accountCookie = (await getAccountCookie(ctx).catch(
+        () => null,
+      )) as KeycloakAccountLike | null;
+      if (accountCookie?.providerId === "keycloak" && accountCookie.idToken) {
+        idTokenHint = accountCookie.idToken;
+      }
+    }
+
+    if (sessionToken) {
+      await ctx.context.internalAdapter.deleteSession(sessionToken).catch((error: unknown) => {
+        ctx.context.logger.error("Failed to delete session during SSO sign-out", error);
+      });
+    }
+    deleteSessionCookie(ctx);
+
+    // Had a Better Auth session (cookie and/or id_token) → the browser must
+    // ride Keycloak's end-session endpoint. Skipping that when getSession
+    // misses but the session cookie was present is what made logout look
+    // like it stuck locally while the next Log in silently SSO'd back in.
+    // Without id_token_hint Keycloak may show a confirmation; still correct.
+    const keycloakBase = publicKeycloakBaseFor(visitorOrigin);
+    if (!keycloakBase || (!session && !idTokenHint && !sessionToken)) {
+      return answer(postLogoutRedirect, false);
+    }
+
+    const endSession = new URL(`${keycloakBase}/realms/${realm}/protocol/openid-connect/logout`);
+    endSession.searchParams.set("post_logout_redirect_uri", postLogoutRedirect);
+    endSession.searchParams.set("client_id", clientId);
+    if (idTokenHint) endSession.searchParams.set("id_token_hint", idTokenHint);
+    return answer(endSession.toString(), true);
+  });
+
+  return {
+    id: "keycloak-sso",
+    endpoints: {
+      signOutSso,
+    },
+    hooks: {
+      after: [
+        {
+          matcher: (ctx) => ctx.path === "/get-access-token",
+          handler: createAuthMiddleware(async (ctx) => {
+            const returned = ctx.context.returned;
+            if (!isAPIError(returned)) return;
+            const body = returned.body as { code?: string; message?: string } | undefined;
+            if (body?.code !== FAILED_TO_GET_ACCESS_TOKEN) return;
+            const providerId = (ctx.body as { providerId?: string } | undefined)?.providerId;
+            if (providerId && providerId !== "keycloak") return;
+
+            const session = await getSessionFromCtx(ctx).catch(() => null);
+            if (!session) return;
+
+            // Classify: prefer the stored account's refresh token, falling
+            // back to the account cookie (memory-adapter dev restarts). A
+            // session with no refresh token anywhere can never recover.
+            const accounts = (await ctx.context.internalAdapter
+              .findAccounts(session.user.id)
+              .catch(() => [])) as KeycloakAccountLike[];
+            let refreshToken = accounts.find(
+              (account) => account.providerId === "keycloak",
+            )?.refreshToken;
+            if (!refreshToken) {
+              const accountCookie = (await getAccountCookie(ctx).catch(
+                () => null,
+              )) as KeycloakAccountLike | null;
+              if (accountCookie?.providerId === "keycloak") {
+                refreshToken = accountCookie.refreshToken;
+              }
+            }
+            const definitive = refreshToken ? await isRefreshDefinitivelyDead(refreshToken) : true;
+            if (!definitive) {
+              // Distinct from FAILED_TO_GET_ACCESS_TOKEN: the session is still
+              // good, Keycloak is just bouncing. Clients retry this code and
+              // must not start the signed-out cooldown.
+              return new APIError("INTERNAL_SERVER_ERROR", {
+                message: "Keycloak token refresh temporarily unavailable",
+                code: TOKEN_REFRESH_UNAVAILABLE,
+              });
+            }
+
+            ctx.context.logger.warn(
+              "Keycloak refresh token is dead (invalid_grant); revoking the stale Better Auth session",
+            );
+            const sessionToken = await ctx.getSignedCookie(
+              ctx.context.authCookies.sessionToken.name,
+              ctx.context.secret,
+            );
+            if (sessionToken) {
+              await ctx.context.internalAdapter
+                .deleteSession(sessionToken)
+                .catch((error: unknown) => {
+                  ctx.context.logger.error("Failed to delete stale session", error);
+                });
+            }
+            deleteSessionCookie(ctx);
+            // Replace the returned error so the cookie deletions ride its OWN
+            // headers too: when the failing endpoint accumulated no response
+            // headers, better-call's toResponse falls back to the APIError's
+            // headers — without this the clearing Set-Cookie would be lost.
+            const headers = new Headers();
+            const accumulated = (ctx as unknown as { responseHeaders?: Headers }).responseHeaders;
+            accumulated?.getSetCookie().forEach((cookie) => {
+              headers.append("set-cookie", cookie);
+            });
+            return new APIError(
+              "BAD_REQUEST",
+              {
+                message: body?.message || "Failed to get a valid access token",
+                code: FAILED_TO_GET_ACCESS_TOKEN,
+              },
+              headers,
+            );
+          }),
+        },
+      ],
+    },
+  } satisfies BetterAuthPlugin;
+}
+
+/**
+ * Create a Better Auth instance configured for Keycloak.
+ * Keycloak is expected at ${BASE_URL}/auth (proxied by Frappe in dev).
+ */
+export function createAuth(options: CreateAuthOptions = {}) {
+  const baseUrl =
+    options.baseUrl || process.env.BASE_URL || `http://localhost:${process.env.ONE_PORT || "3000"}`;
+  const isProduction = process.env.NODE_ENV === "production";
+
+  // In production Keycloak is proxied at /auth by Frappe, so default to ${baseUrl}/auth.
+  // In dev (no proxy), use KEYCLOAK_BACKCHANNEL_URL (server-to-server direct address).
+  const keycloakBaseUrl =
+    options.keycloak?.baseUrl || process.env.KEYCLOAK_BACKCHANNEL_URL || `${baseUrl}/auth`;
+  const keycloakRealm = options.keycloak?.realm || process.env.KEYCLOAK_REALM || "master";
+  const issuer = `${keycloakBaseUrl}/realms/${keycloakRealm}`;
+
+  const keycloakClientId = options.keycloak?.clientId || process.env.KEYCLOAK_CLIENT_ID || "";
+  const keycloakClientSecret =
+    options.keycloak?.clientSecret || process.env.KEYCLOAK_CLIENT_SECRET || "";
+
+  const expoPlugin = options.enableExpo !== false ? expo() : undefined;
+
+  const basePath = options.basePath || "/api/auth";
+
+  const keycloakProviderConfig = {
+    ...keycloak({
+      clientId: keycloakClientId,
+      clientSecret: keycloakClientSecret,
+      issuer,
+    }),
+    // Backchannel token/userinfo: `/get-access-token` refresh keeps these
+    // when discovery fails (Keycloak restart), so we don't depend on the
+    // well-known document coming up in the same instant as the token
+    // endpoint. Browser-facing authorize/issuer stay on the public /auth
+    // proxy (getters below).
+    tokenUrl: `${issuer}/protocol/openid-connect/token`,
+    userInfoUrl: `${issuer}/protocol/openid-connect/userinfo`,
+    // Wallet (SIWE-style) users authenticate by signature and have NO email —
+    // Keycloak issues them a username = wallet address and no email claim.
+    // better-auth's genericOAuth callback hard-rejects a user with no email
+    // ("email_is_missing"), so synthesize a stable, unique placeholder from the
+    // wallet address / subject. `.wallet` is a non-routable placeholder domain;
+    // the address stays the stable identity.
+    mapProfileToUser: (profile: Record<string, any>) => {
+      const handle = profile.preferred_username || profile.sub || profile.id || profile.name;
+      const email = profile.email || (handle ? `${handle}@wallet` : undefined);
+      return {
+        ...profile,
+        email,
+        emailVerified: profile.email_verified ?? true,
+        name: profile.name || handle,
+      };
+    },
+  };
+  // Path prefix (e.g. /auth) signals the same-origin proxy pattern; a bare
+  // Keycloak origin keeps the discovery-resolved absolute URL.
+  const keycloakPublicPath = (() => {
+    try {
+      const path = new URL(keycloakBaseUrl).pathname.replace(/\/+$/, "");
+      return path && path !== "/" ? path : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+
+  /**
+   * Browser-facing Keycloak base for a visitor origin. With the /auth proxy
+   * pattern this is the canonical app URL's proxy (baseUrl + path); in dev
+   * only the HOSTNAME follows the visitor so every app on a hostname shares
+   * one Keycloak SSO session (see the authorization-URL getter below). A
+   * bare-origin Keycloak (no proxy) is public already.
+   */
+  const publicKeycloakBaseFor = (requestOrigin?: string): string | undefined => {
+    if (!keycloakPublicPath) return keycloakBaseUrl;
+    try {
+      const url = new URL(baseUrl);
+      if (!isProduction && requestOrigin) {
+        url.hostname = new URL(requestOrigin).hostname;
+      }
+      return `${url.origin}${keycloakPublicPath}`;
+    } catch {
+      return undefined;
+    }
+  };
+
+  if (!isProduction) {
+    // Dev: the OAuth redirect URI follows the origin of the request being
+    // handled (localhost, LAN IP, *.local — see requestOriginStorage), so the
+    // callback and its session cookie land on the host the visitor is on.
+    // `options.redirectURI` wins over the plugin's init-pinned fallback in
+    // both createAuthorizationURL and validateAuthorizationCode, and the
+    // getter is evaluated per call. Falls back to the plugin default (static
+    // baseURL) when no request is in scope.
+    Object.defineProperty(keycloakProviderConfig, "redirectURI", {
+      enumerable: true,
+      get() {
+        const origin = requestOriginStorage.getStore();
+        return origin ? `${origin}${basePath}/oauth2/callback/keycloak` : undefined;
+      },
+    });
+
+    // Dev: the browser-facing AUTHORIZATION endpoint rides Keycloak's ONE
+    // public home per hostname — the canonical app URL's /auth proxy (the
+    // bench) — with only the HOSTNAME following the visitor. Pointing each
+    // app at its own origin's proxy instead would mint Keycloak identity
+    // cookies bound to per-PORT issuers, so a login on the app (:3456)
+    // would not be recognized by the bench flow (:8000) and vice versa —
+    // the user gets asked for a password twice. One public origin per
+    // hostname = one Keycloak SSO session shared by every app on that
+    // hostname (cookies ignore ports), still reachable from any LAN device.
+    // Only under the same-origin proxy pattern (path-prefixed Keycloak).
+    // `/sign-in/social` (the path the web + native clients use) prefers
+    // an explicit `authorizationUrl` and falls back to discovery when the
+    // getter yields undefined (no request in scope). `/sign-in/oauth2`
+    // still overwrites with discovery — that route is unused here.
+    // Token/userinfo exchanges are server-side: we pin `tokenUrl` /
+    // `userInfoUrl` to the BACKCHANNEL so a discovery blip during a
+    // Keycloak restart cannot block refresh (refreshAccessToken overwrites
+    // with discovery when discovery SUCCEEDS, and keeps tokenUrl when it
+    // fails).
+    /** Canonical public Keycloak base (baseUrl + path), on the visitor's hostname. */
+    const keycloakPublicBase = (): string | undefined => {
+      const origin = requestOriginStorage.getStore();
+      if (!origin || !keycloakPublicPath) return undefined;
+      return publicKeycloakBaseFor(origin);
+    };
+    if (keycloakPublicPath) {
+      Object.defineProperty(keycloakProviderConfig, "authorizationUrl", {
+        enumerable: true,
+        get() {
+          const base = keycloakPublicBase();
+          return base ? `${base}/realms/${keycloakRealm}/protocol/openid-connect/auth` : undefined;
+        },
+      });
+      // Keycloak derives its issuer from the forwarded visitor host (the
+      // canonical /auth proxy forwards it so KC's login pages stay on the
+      // visitor's hostname), so the RFC 9207 `iss` on the callback follows
+      // the same public base. Explicit `issuer` wins over the discovery
+      // document's in the callback's issuer check; undefined (no request
+      // in scope) falls back to discovery. better-auth performs no
+      // id_token iss check.
+      Object.defineProperty(keycloakProviderConfig, "issuer", {
+        enumerable: true,
+        get() {
+          const base = keycloakPublicBase();
+          return base ? `${base}/realms/${keycloakRealm}` : undefined;
+        },
+      });
+    }
+  }
+
+  // Passed by reference (NOT spread): spreading would evaluate the dev
+  // redirectURI getter once at startup instead of per request.
+  const oauthPlugin = genericOAuth({
+    config: [keycloakProviderConfig as Parameters<typeof genericOAuth>[0]["config"][number]],
+  });
+
+  const keycloakSsoPlugin = createKeycloakSsoPlugin({
+    realm: keycloakRealm,
+    clientId: keycloakClientId,
+    clientSecret: keycloakClientSecret,
+    issuer,
+    baseUrl,
+    publicKeycloakBaseFor,
+  });
+
+  const plugins: any[] = [
+    ...(expoPlugin ? [expoPlugin] : []),
+    oauthPlugin,
+    keycloakSsoPlugin,
+    ...(options.plugins ?? []),
+  ];
+
+  // Database for session/account storage.
+  // Reads DATABASE_URL env var, or uses an explicit option.
+  const database = options.database ?? (process.env.DATABASE_URL || undefined);
+
+  return betterAuth({
+    basePath,
+    // Static on purpose: better-auth's dynamic `baseURL` config (allowedHosts)
+    // is not honored by the genericOAuth plugin — it pins redirect URIs at
+    // init time, which turned them relative and bounced callbacks to the
+    // Keycloak host. Dev multi-host support comes from the per-request
+    // redirectURI getter above + the LAN trustedOrigins below instead.
+    baseURL: baseUrl,
+    ...(database ? { database } : {}),
+    secret: options.secret || process.env.SECRET || "",
+    trustedOrigins: options.trustedOrigins || [
+      baseUrl,
+      keycloakBaseUrl,
+      // In dev, ONE_PORT may differ from BASE_URL; ensure the dev server origin is trusted.
+      ...(process.env.ONE_PORT && !baseUrl.includes(`:${process.env.ONE_PORT}`)
+        ? [`http://localhost:${process.env.ONE_PORT}`]
+        : []),
+      "multiplatform-one://",
+      // Expo Go (dev) receives OAuth returns on the exp:// scheme — the app
+      // derives its callbackURL via Linking.createURL, which yields
+      // exp://<host>:<port>/--/ there. Never trusted in production builds.
+      // Dev also trusts private-network origins (see DEV_LAN_HOST_PATTERNS)
+      // so sign-in from a phone / the machine's LAN IP is not rejected.
+      ...(isProduction ? [] : ["exp://", ...DEV_LAN_HOST_PATTERNS.map((host) => `http://${host}`)]),
+    ],
+    session: {
+      cookieCache: {
+        enabled: true,
+        maxAge: options.sessionMaxAge ?? 7 * 24 * 60 * 60,
+        strategy: "jwe",
+        refreshCache: true,
+      },
+    },
+    account: {
+      storeStateStrategy: "cookie",
+      storeAccountCookie: true,
+    },
+    plugins,
+  });
+}
+
+/** The return type of `createAuth()`. */
+export type AuthInstance = ReturnType<typeof createAuth>;
+
+// ─── createAuthRouteHandler ─────────────────────────────────────────
+
+/**
+ * Create GET and POST route handlers for One framework `+api.ts` files.
+ *
+ * @example
+ * ```ts
+ * // lib/server/auth.ts
+ * export const { GET, POST } = createAuthRouteHandler(auth);
+ *
+ * // routes/api/auth/[route]+api.ts
+ * export { GET, POST } from "../../../lib/server/auth";
+ * ```
+ */
+export function createAuthRouteHandler(auth: AuthLike) {
+  // Every auth request runs inside an AsyncLocalStorage scope carrying its
+  // visitor origin (proxy-aware; see deriveRequestOrigin), so the dev
+  // redirect-URI/authorization-URL getters (createAuth) can follow the host
+  // the visitor is actually on (survives the awaits inside better-auth).
+  const handler = (req: Request) => {
+    const origin = deriveRequestOrigin(req);
+    return origin ? requestOriginStorage.run(origin, () => auth.handler(req)) : auth.handler(req);
+  };
+  return { GET: handler, POST: handler } as const;
+}
+
+// ─── Session helpers ────────────────────────────────────────────────
+
+/**
+ * Create session verification helpers bound to an auth instance.
+ *
+ * @returns `verifyAuth` (throws 401 Response) and `getSession` (returns session or null)
+ */
+export function createSessionHelpers(auth: AuthLike) {
+  /** Get session from request. Returns session or null when unauthenticated. */
+  async function getSession(req: Request) {
+    return auth.api.getSession({ headers: req.headers });
+  }
+
+  /** Verify auth session. Returns session or throws a 401 Response. */
+  async function verifyAuth(req: Request) {
+    const session = await auth.api.getSession({ headers: req.headers });
+    if (!session) {
+      throw new Response("Unauthorized", { status: 401 });
+    }
+    return session;
+  }
+
+  return { verifyAuth, getSession };
+}