@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/client/auth/AuthConfigured.jsx

@@ -14,60 +14,245 @@
   limitations under the License.
 */
 
-/* eslint-disable react/jsx-props-no-spreading */
-
-import React, { useEffect, useRef } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
+import { createAuthClient } from 'better-auth/react';
 import {
-  authConfigManager,
-  getSession,
-  SessionProvider,
-  signIn,
-  signOut,
-  useSession,
-} from '@hono/auth-js/react';
+  adminClient,
+  emailOTPClient,
+  magicLinkClient,
+  organizationClient,
+  phoneNumberClient,
+  twoFactorClient,
+} from 'better-auth/client/plugins';
+import { oauthProviderClient } from '@better-auth/oauth-provider/client';
+import { passkeyClient } from '@better-auth/passkey/client';
 
-import { serializer } from '@lowdefy/helpers';
+import claimCallerReload from '@lowdefy/client/claimCallerReload.js';
+import { normalizeCaller } from '@lowdefy/helpers';
 
-import rawLowdefyConfig from '../../../build/config.json';
+import bundleBuildId from '../bundleBuildId.js';
+import createFetchCheckingBuild from './createFetchCheckingBuild.js';
 
-const lowdefyConfig = serializer.deserialize(rawLowdefyConfig);
+// The app basePath, from Vite's BASE_URL (`${config.basePath}/`, set in
+// vite.config.js). build/config.json is server-only - it carries every
+// deployment environment's settings - so it is never imported into the client.
+const basePath = import.meta.env.BASE_URL.replace(/\/$/, '');
 
-// @hono/auth-js/react configures its fetch paths through a module-level
-// manager instead of SessionProvider props.
-if (lowdefyConfig.basePath) {
-  authConfigManager.setConfig({ basePath: `${lowdefyConfig.basePath}/api/auth` });
-}
+// Reloads a tab whose auth call fails against a newer build.
+const fetchCheckingBuild = createFetchCheckingBuild({ buildId: bundleBuildId });
+
+// GenericOAuth providers have no client plugin here. BetterAuth 1.7.0 dropped
+// genericOAuthClient, and the server plugin's own routes with it: a generic
+// provider is registered as a social provider keyed by its providerId, so it
+// signs in through signIn.social and returns on /callback/:id like any
+// built-in one. The client's path proxy would still turn a signIn.oauth2 call
+// into POST /sign-in/oauth2, a route no 1.7 server serves.
+const authClient = createAuthClient({
+  baseURL: `${window.location.origin}${basePath}/api/auth`,
+  fetchOptions: { customFetchImpl: fetchCheckingBuild },
+  plugins: [
+    adminClient(),
+    emailOTPClient(),
+    magicLinkClient(),
+    oauthProviderClient(),
+    organizationClient(),
+    passkeyClient(),
+    phoneNumberClient(),
+    twoFactorClient(),
+  ],
+});
 
-function Session({ children }) {
-  const wasAuthenticated = useRef(false);
-  const { data: session, status } = useSession();
-  wasAuthenticated.current = wasAuthenticated.current || status === 'authenticated';
+// UpdateSession owns session freshness - suppress BetterAuth's own
+// signal-driven refetch on the calls that would otherwise fire one, so
+// nothing competes with (and aborts) the refetch UpdateSession awaits.
+// Only calls that mutate an existing session are suppressed - calls that
+// can establish one (the sign-ins, and the two-factor, phone-number,
+// email-otp and passkey verifies) keep their signal: its refetch is what makes the store
+// notice a login when no navigation follows.
+// disableSignal silences all atomListeners for the call, including the
+// organization plugin's org atoms - none are exposed to app config, so a
+// future design exposing one must refresh it through its own action.
+const sessionScoped = (params) => ({
+  ...params,
+  fetchOptions: { ...params?.fetchOptions, disableSignal: true },
+});
+
+// The server resolves the caller per request and embeds it in the page
+// config, so the first render never flashes unauthenticated. The BetterAuth
+// client store takes over once its session fetch settles.
+//
+// Roles and merged attributes resolve server-side from the active member row
+// - the base session carries neither. The last server-resolved caller is
+// held in state: while the session user is unchanged it stays authoritative
+// for the fields the session does not carry, and UpdateSession refreshes it
+// from /api/user after a change (e.g. SetActiveOrganization). Holding it in
+// state, not a ref, re-renders Session when it changes so _user recomputes -
+// the same reactive footing the session half already stands on.
+//
+// Only the session half is passed through normalizeCaller. BetterAuth's store
+// returns camelCase keys whatever the columns are named, so untransformed it
+// would sit emailVerified beside the resolved caller's email_verified on one
+// object; anything arriving from the server is already snake_case.
+function Session({ children, reloadSuppressedRef, serverUser }) {
+  const { data: session, isPending } = authClient.useSession();
+  const [resolvedUser, setResolvedUser] = useState(serverUser);
+  const wasAuthenticated = useRef(Boolean(serverUser));
 
   useEffect(() => {
-    if (wasAuthenticated.current && status === 'unauthenticated') {
+    if (session) {
+      wasAuthenticated.current = true;
+    }
+    // An auth call that navigates away (a logout or sign-in with a callback)
+    // suppresses both reloads below - its own navigation would otherwise race
+    // them.
+    if (reloadSuppressedRef.current) {
+      return;
+    }
+    // Reload after sign-out (or session revocation) so the server can apply
+    // the page auth fork - a protected page redirects to the login page.
+    if (wasAuthenticated.current && !isPending && !session) {
       window.location.reload();
+      return;
     }
-  }, [status]);
+    // The session now names another person than the caller this page renders
+    // (a sign-in as someone else, here or in another tab). Reload so the server
+    // renders the page for the new person, rather than keep showing the
+    // previous person's page and data. At most once per reload interval
+    // (claimCallerReload): past it the previous caller stays rendered, and its
+    // requests fail when the server answers as the new person.
+    if (
+      session?.user &&
+      resolvedUser &&
+      session.user.id !== resolvedUser.id &&
+      claimCallerReload({ window })
+    ) {
+      window.location.reload();
+    }
+  }, [session, isPending, resolvedUser]);
 
-  // If session is passed to SessionProvider from the server-rendered config
-  // we won't have a loading state here, but unauthenticated first loads do.
-  if (status === 'loading') {
-    return '';
+  if (isPending) {
+    return children(resolvedUser, setResolvedUser);
+  }
+  if (!session?.user) {
+    return children(null, setResolvedUser);
+  }
+  const resolved = resolvedUser;
+  if (!resolved) {
+    return children({ roles: [], ...normalizeCaller(session.user) }, setResolvedUser);
+  }
+  if (resolved.id !== session.user.id) {
+    // The session names another person than the resolved caller; the effect
+    // above reloads the page. Until it unloads, render the last resolved
+    // caller whole rather than mixing the new session user with the previous
+    // person's resolved fields, or falling back to a caller with no roles -
+    // blocks re-evaluate operators on render, so a role-guarded page would act
+    // on an empty role list.
+    return children(resolved, setResolvedUser);
   }
-  return children(session);
+  // _user is one object with one meaning on both sides: the resolved caller is
+  // spread whole, so every field resolveAuthentication emits is readable in app
+  // config without this file naming it. session.user is the floor - the client
+  // store may hold a fresher one than the resolved state, and the resolved
+  // object wins wherever both carry a key.
+  const user = { ...normalizeCaller(session.user), ...resolved };
+  return children(user, setResolvedUser);
 }
 
-function AuthConfigured({ authConfig, children, serverSession }) {
-  const auth = { authConfig, getSession, signIn, signOut };
+function AuthConfigured({ authConfig, children, serverUser }) {
+  const reloadSuppressedRef = useRef(false);
+  const auth = {
+    authConfig,
+    getSession: ({ disableCookieCache } = {}) =>
+      authClient.getSession(disableCookieCache ? { query: { disableCookieCache: true } } : {}),
+    // Refetches the session through the session atom - the store's only
+    // writer - and resolves only after the store is written. fetchSession
+    // returns undefined and never rejects (failures are written into the
+    // atom), so the atom's own { data, error } is read back and returned,
+    // keeping unwrap working and surfacing a failed refresh to the action.
+    refreshSession: async ({ disableCookieCache } = {}) => {
+      const sessionAtom = authClient.$store.atoms.session;
+      await sessionAtom
+        .get()
+        .refetch(disableCookieCache ? { query: { disableCookieCache: true } } : undefined);
+      const { data, error } = sessionAtom.get();
+      return { data, error };
+    },
+    // The server-resolved caller - roles from the active member row and the
+    // merged attributes bag - for re-syncing after session changes.
+    getResolvedUser: async () => {
+      const response = await fetchCheckingBuild(`${basePath}/api/user`, {
+        credentials: 'same-origin',
+      });
+      if (!response.ok) {
+        // /api/user itself always answers 200 { user } - user: null when no
+        // caller is admitted, which updateSession branches on. A non-OK
+        // response is a transport failure (gateway error page, 5xx) with no
+        // parsable body.
+        throw new Error(`Failed to fetch the resolved user (HTTP ${response.status}).`);
+      }
+      return response.json();
+    },
+    suppressSessionReload: () => {
+      reloadSuppressedRef.current = true;
+    },
+    acceptInvitation: (params) => authClient.organization.acceptInvitation(sessionScoped(params)),
+    // addPasskey runs the WebAuthn browser ceremony itself - options fetch,
+    // authenticator prompt, verification.
+    addPasskey: (params) => authClient.passkey.addPasskey(params),
+    changePassword: (params) => authClient.changePassword(sessionScoped(params)),
+    deletePasskey: (params) => authClient.passkey.deletePasskey(params),
+    updatePasskey: (params) => authClient.passkey.updatePasskey(params),
+    leaveOrganization: (params) => authClient.organization.leave(sessionScoped(params)),
+    // The caller's memberships from the org plugin, keyed on the session
+    // alone - not the active organization. sessionScoped so the list read
+    // does not also fire the org-list atom's own refetch of the same route.
+    listOrganizations: () => authClient.organization.list(sessionScoped()),
+    // POST /oauth2/consent. The signed authorization query is not passed
+    // here - the oauthProviderClient fetch plugin stamps it onto the body as
+    // oauth_query from window.location.search, so the call must run while
+    // the page still holds the query the oauth-provider redirect arrived
+    // with.
+    oauth2Consent: (params) => authClient.oauth2.consent(params),
+    // POST /oauth2/continue - resumes the authorization after the post-login
+    // organization choice (the page runs SetActiveOrganization first). Same
+    // oauth_query contract as oauth2Consent: the signed query rides from
+    // window.location.search, so the call must run before any navigation.
+    oauth2Continue: (params) => authClient.oauth2.continue(params),
+    // The one-time email code: send, then sign in with it.
+    emailOtpSend: (params) => authClient.emailOtp.sendVerificationOtp(params),
+    emailOtpVerify: (params) => authClient.signIn.emailOtp(params),
+    phoneNumberRequestPasswordReset: (params) =>
+      authClient.phoneNumber.requestPasswordReset(params),
+    phoneNumberResetPassword: (params) => authClient.phoneNumber.resetPassword(params),
+    phoneNumberSendOtp: (params) => authClient.phoneNumber.sendOtp(params),
+    phoneNumberVerify: (params) => authClient.phoneNumber.verify(params),
+    requestPasswordReset: (params) => authClient.requestPasswordReset(params),
+    resetPassword: (params) => authClient.resetPassword(params),
+    revokeOtherSessions: () => authClient.revokeOtherSessions(sessionScoped()),
+    sendVerificationEmail: (params) => authClient.sendVerificationEmail(params),
+    setActiveOrganization: (params) => authClient.organization.setActive(sessionScoped(params)),
+    signInEmail: (params) => authClient.signIn.email(params),
+    signInMagicLink: (params) => authClient.signIn.magicLink(params),
+    signInPasskey: (params) => authClient.signIn.passkey(params),
+    signInPhoneNumber: (params) => authClient.signIn.phoneNumber(params),
+    signInSocial: (params) => authClient.signIn.social(params),
+    signOut: () => authClient.signOut(),
+    signUpEmail: (params) => authClient.signUp.email(params),
+    twoFactorDisable: (params) => authClient.twoFactor.disable(sessionScoped(params)),
+    twoFactorEnable: (params) => authClient.twoFactor.enable(sessionScoped(params)),
+    twoFactorGenerateBackupCodes: (params) =>
+      authClient.twoFactor.generateBackupCodes(sessionScoped(params)),
+    twoFactorVerifyBackupCode: (params) => authClient.twoFactor.verifyBackupCode(params),
+    twoFactorVerifyTotp: (params) => authClient.twoFactor.verifyTotp(params),
+  };
   return (
-    <SessionProvider session={serverSession}>
-      <Session>
-        {(session) => {
-          auth.session = session;
-          return children(auth);
-        }}
-      </Session>
-    </SessionProvider>
+    <Session reloadSuppressedRef={reloadSuppressedRef} serverUser={serverUser}>
+      {(user, setResolvedUser) => {
+        auth.user = user;
+        auth.updateResolvedUser = (resolved) => setResolvedUser(resolved);
+        return children(auth);
+      }}
+    </Session>
   );
 }
 

package/lib/client/auth/AuthNotConfigured.js

@@ -13,18 +13,59 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
-/* eslint-disable react/jsx-props-no-spreading */
+
+import { ConfigError } from '@lowdefy/errors';
 
 function authNotConfigured() {
-  throw new Error('Auth not configured.');
+  throw new ConfigError(
+    'Auth is not configured. Add an "auth" section to lowdefy.yaml to use auth actions.'
+  );
 }
 
-function AuthNotConfigured({ authConfig, children }) {
+// Every key AuthConfigured exposes must be present here, or an auth action in an
+// app without an auth section fails with "auth.x is not a function" instead of
+// the ConfigError that names the missing config.
+function AuthNotConfigured({ authConfig, children, user = null }) {
   const auth = {
     authConfig,
+    user,
+    acceptInvitation: authNotConfigured,
+    addPasskey: authNotConfigured,
+    changePassword: authNotConfigured,
+    deletePasskey: authNotConfigured,
+    getResolvedUser: authNotConfigured,
     getSession: authNotConfigured,
-    signIn: authNotConfigured,
+    leaveOrganization: authNotConfigured,
+    listOrganizations: authNotConfigured,
+    oauth2Consent: authNotConfigured,
+    oauth2Continue: authNotConfigured,
+    emailOtpSend: authNotConfigured,
+    emailOtpVerify: authNotConfigured,
+    phoneNumberRequestPasswordReset: authNotConfigured,
+    phoneNumberResetPassword: authNotConfigured,
+    phoneNumberSendOtp: authNotConfigured,
+    phoneNumberVerify: authNotConfigured,
+    refreshSession: authNotConfigured,
+    requestPasswordReset: authNotConfigured,
+    resetPassword: authNotConfigured,
+    revokeOtherSessions: authNotConfigured,
+    sendVerificationEmail: authNotConfigured,
+    setActiveOrganization: authNotConfigured,
+    signInEmail: authNotConfigured,
+    signInMagicLink: authNotConfigured,
+    signInPasskey: authNotConfigured,
+    signInPhoneNumber: authNotConfigured,
+    signInSocial: authNotConfigured,
     signOut: authNotConfigured,
+    signUpEmail: authNotConfigured,
+    suppressSessionReload: authNotConfigured,
+    twoFactorDisable: authNotConfigured,
+    twoFactorEnable: authNotConfigured,
+    twoFactorGenerateBackupCodes: authNotConfigured,
+    twoFactorVerifyBackupCode: authNotConfigured,
+    twoFactorVerifyTotp: authNotConfigured,
+    updatePasskey: authNotConfigured,
+    updateResolvedUser: authNotConfigured,
   };
 
   return children(auth);

package/lib/client/auth/authNotConfiguredParity.test.mjs

@@ -0,0 +1,61 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import AuthNotConfigured from './AuthNotConfigured.js';
+
+const authDir = path.dirname(fileURLToPath(import.meta.url));
+
+// The keys of the `const auth = { ... }` literal plus the `auth.x =` assignments
+// made after it - both reach the app through the same context object.
+function readExposedKeys(source) {
+  const literal = source.slice(source.indexOf('const auth = {'), source.indexOf('\n  };'));
+  const keys = [...literal.matchAll(/^ {4}([a-zA-Z0-9_]+)[:,]/gm)].map((match) => match[1]);
+  const assigned = [...source.matchAll(/^ +auth\.([a-zA-Z0-9_]+) =/gm)].map((match) => match[1]);
+  return [...new Set([...keys, ...assigned])].sort();
+}
+
+function callAuthNotConfigured() {
+  let auth;
+  AuthNotConfigured({ authConfig: { enabled: false }, children: (value) => (auth = value) });
+  return auth;
+}
+
+// An app with no auth section still renders every block and action. A method
+// AuthConfigured exposes but AuthNotConfigured omits surfaces as
+// "auth.x is not a function" instead of the ConfigError naming the missing config.
+test('AuthNotConfigured exposes every key AuthConfigured exposes', async () => {
+  const source = await readFile(path.join(authDir, 'AuthConfigured.jsx'), 'utf8');
+  const auth = callAuthNotConfigured();
+  expect(Object.keys(auth).sort()).toEqual(readExposedKeys(source));
+});
+
+test('AuthNotConfigured keeps authConfig and a null user', () => {
+  const auth = callAuthNotConfigured();
+  expect(auth.authConfig).toEqual({ enabled: false });
+  expect(auth.user).toBeNull();
+});
+
+test('AuthNotConfigured methods throw a ConfigError naming the missing auth config', () => {
+  const auth = callAuthNotConfigured();
+  expect(() => auth.signInEmail({})).toThrow(
+    'Auth is not configured. Add an "auth" section to lowdefy.yaml to use auth actions.'
+  );
+  expect(() => auth.signInEmail({})).toThrow(expect.objectContaining({ name: 'ConfigError' }));
+});

package/lib/client/auth/authTemplateSync.test.mjs

@@ -0,0 +1,40 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const devAuthDir = path.dirname(fileURLToPath(import.meta.url));
+const prodAuthDir = path.resolve(devAuthDir, '../../../../server/lib/client/auth');
+
+// The dev and prod server templates each carry their own copy of the auth
+// components, kept in sync by hand. A change applied to one and not the
+// other ships dev-only or prod-only - the app then behaves differently
+// between lowdefy dev and a production build, which no unit test of either
+// copy can catch.
+test('the auth client templates are byte-identical between server and server-dev', async () => {
+  const isTemplate = (file) => !file.includes('.test.');
+  const devFiles = (await readdir(devAuthDir)).filter(isTemplate).sort();
+  const prodFiles = (await readdir(prodAuthDir)).filter(isTemplate).sort();
+  expect(prodFiles).toEqual(devFiles);
+  for (const file of devFiles) {
+    const dev = await readFile(path.join(devAuthDir, file), 'utf8');
+    const prod = await readFile(path.join(prodAuthDir, file), 'utf8');
+    // Compared per file so a failure names the file that diverged.
+    expect({ file, content: prod }).toEqual({ file, content: dev });
+  }
+});

package/lib/client/auth/betterAuthSessionContract.test.mjs

@@ -0,0 +1,181 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { createAuthClient } from 'better-auth/client';
+
+// AuthConfigured.jsx depends on behaviours of better-auth's client internals
+// that no public API documents:
+//   1. authClient.$store.atoms.session is the real session store, and its
+//      value exposes an awaitable refetch - the store's only writer.
+//   2. A getSession path call never writes the store (/get-session is not in
+//      the atomListeners matcher) - the defect refreshSession exists to work
+//      around.
+//   3. A failed refetch resolves normally (it never rejects) and writes the
+//      error into the atom - why refreshSession reads { data, error } back
+//      instead of using the refetch's return value.
+//   4. The proxy fires a signal-driven background session fetch shortly
+//      after a matched endpoint succeeds, aborting any refetch already in
+//      flight, and fetchOptions.disableSignal suppresses it - the
+//      sessionScoped mechanism, and why it is required rather than merely
+//      awaiting the refetch.
+// A better-auth upgrade that changes any of these breaks UpdateSession the
+// way the original defect did - visibly only in a running app. These tests
+// pin the contract so the break surfaces here instead.
+
+const USER_1 = { id: 'user-1', email: 'user-1@example.com' };
+const USER_2 = { id: 'user-2', email: 'user-2@example.com' };
+
+function jsonResponse(payload, { status = 200 } = {}) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function sessionPayload(user) {
+  return { session: { id: 'session-1', userId: user.id }, user };
+}
+
+function createClient(handleGetSession) {
+  const requests = [];
+  const client = createAuthClient({
+    baseURL: 'http://localhost:3000/api/auth',
+    fetchOptions: {
+      customFetchImpl: async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        if (url.includes('/get-session')) {
+          if (handleGetSession) {
+            return handleGetSession(url, init);
+          }
+          return jsonResponse(sessionPayload(USER_1));
+        }
+        return jsonResponse({ status: true });
+      },
+    },
+  });
+  // Mount the session atom with a never-removed subscription, mirroring the
+  // app - Session's useSession() keeps it mounted, and mounting is what
+  // makes the signal subscription live. It also keeps the store mounted for
+  // bare .get() calls: on an unmounted onMount store, .get() temporarily
+  // mounts it and schedules nanostores' delayed unmount on a timer that
+  // outlives the jest worker. The mount's own initial fetch is skipped in
+  // node (isServer), so no request is recorded here.
+  client.$store.atoms.session.subscribe(() => {});
+  const getSessionRequests = () => requests.filter((r) => r.url.includes('/get-session'));
+  return { client, getSessionRequests };
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+test('the session store is reachable at $store.atoms.session and exposes an awaitable refetch', () => {
+  const { client } = createClient();
+  const value = client.$store.atoms.session.get();
+  expect(value).toMatchObject({ data: null, error: null, isPending: true });
+  expect(typeof value.refetch).toBe('function');
+});
+
+test('a getSession path call resolves the session without ever writing the store', async () => {
+  const { client } = createClient();
+  const sessionAtom = client.$store.atoms.session;
+  const { data } = await client.getSession({ query: { disableCookieCache: true } });
+  expect(data.user).toEqual(USER_1);
+  expect(sessionAtom.get().data).toBe(null);
+});
+
+test('an awaited refetch writes the store before resolving, carrying the disableCookieCache query', async () => {
+  const { client, getSessionRequests } = createClient();
+  const sessionAtom = client.$store.atoms.session;
+  const result = await sessionAtom.get().refetch({ query: { disableCookieCache: true } });
+  // The refetch resolves to undefined - its outcome is only readable from
+  // the atom, which is why refreshSession returns the atom's { data, error }.
+  expect(result).toBeUndefined();
+  const { data, error, isPending } = sessionAtom.get();
+  expect(data.user).toEqual(USER_1);
+  expect(error).toBe(null);
+  expect(isPending).toBe(false);
+  expect(getSessionRequests()).toHaveLength(1);
+  expect(getSessionRequests()[0].url).toContain('disableCookieCache=true');
+});
+
+test('a failed refetch resolves normally and writes the error into the atom', async () => {
+  const { client } = createClient(() =>
+    jsonResponse({ message: 'Internal error.' }, { status: 500 })
+  );
+  const sessionAtom = client.$store.atoms.session;
+  await expect(sessionAtom.get().refetch()).resolves.toBeUndefined();
+  const { error } = sessionAtom.get();
+  expect(error).not.toBe(null);
+  expect(error.status).toBe(500);
+});
+
+test('a matched endpoint fires one background session refetch shortly after success', async () => {
+  const { client, getSessionRequests } = createClient();
+  await client.changePassword({ currentPassword: 'old', newPassword: 'new' });
+  expect(getSessionRequests()).toHaveLength(0);
+  // The proxy flips $sessionSignal on a 10ms setTimeout after success.
+  await wait(100);
+  expect(getSessionRequests()).toHaveLength(1);
+});
+
+test('fetchOptions.disableSignal suppresses the background refetch - the sessionScoped mechanism', async () => {
+  const { client, getSessionRequests } = createClient();
+  await client.changePassword({
+    currentPassword: 'old',
+    newPassword: 'new',
+    fetchOptions: { disableSignal: true },
+  });
+  await wait(100);
+  expect(getSessionRequests()).toHaveLength(0);
+});
+
+test('a competing session fetch aborts an in-flight refetch, which resolves having written nothing', async () => {
+  let getSessionCalls = 0;
+  const { client } = createClient((url, init) => {
+    getSessionCalls += 1;
+    if (getSessionCalls === 1) {
+      // The first refetch's request: rejects on abort like a real fetch,
+      // with a slow success fallback so the test stays deterministic even
+      // if the abort signal is not forwarded - the aborted-controller check
+      // must prevent the write either way.
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(jsonResponse(sessionPayload(USER_1))), 80);
+        init?.signal?.addEventListener('abort', () => {
+          clearTimeout(timer);
+          reject(new Error('aborted'));
+        });
+      });
+    }
+    return jsonResponse(sessionPayload(USER_2));
+  });
+  const sessionAtom = client.$store.atoms.session;
+  const first = sessionAtom.get().refetch({ query: { disableCookieCache: true } });
+  // The store dispatches the fetch on a microtask, and a competitor that
+  // arrives first cancels the flight before its request is ever issued -
+  // then the mock's first /get-session call would belong to the second
+  // refetch. Yield one macrotask so the first request is genuinely in
+  // flight, which is the race UpdateSession's awaited refetch loses.
+  await wait(0);
+  const second = sessionAtom.get().refetch();
+  await expect(first).resolves.toBeUndefined();
+  await second;
+  // Only the second fetch's write landed - the first was aborted mid-flight
+  // and wrote nothing, which is why UpdateSession must be the only session
+  // refresher for its awaited refetch to mean anything.
+  expect(sessionAtom.get().data.user).toEqual(USER_2);
+});