@lowdefy/server-dev 0.0.0-experimental-20260909201552 → 0.0.0-experimental-20260910082708

package/client/App.jsx

@@ -144,7 +144,7 @@ function App({ config, router }) {
                   />
                 }
               >
-                <Auth user={config?.user}>
+                <Auth session={config.devSession}>
                   {(auth) => {
                     return <Routing auth={auth} lowdefy={lowdefyRef.current} router={router} />;
                   }}

package/client/Inspector.jsx

@@ -123,7 +123,7 @@ async function bootstrapFromCheckpoint({ basePath, pageId, checkpointName, isCan
     context._internal.update();
   } catch (error) {
     // eslint-disable-next-line no-console
-    console.error(`Failed to load checkpoint "${checkpointName}":`, error);
+    console.error('Failed to load checkpoint "%s":', checkpointName, error);
   }
 }
 

package/client/Page.jsx

@@ -20,7 +20,6 @@ import Client from '@lowdefy/client';
 
 import BuildErrorPage from '../lib/client/BuildErrorPage.jsx';
 import InstallingPluginsPage from '../lib/client/InstallingPluginsPage.jsx';
-import RedirectingPage from '../lib/client/RedirectingPage.jsx';
 import usePageConfig from '../lib/client/utils/usePageConfig.js';
 
 const Page = ({
@@ -47,22 +46,10 @@ const Page = ({
     }
   }, [pageConfig?._warnings, lowdefy]);
 
-  // Full load to the sign-in page so it can return here after sign-in — an
-  // effect, not a fetcher side effect, so the redirect re-fires if the same
-  // cached result renders again.
-  useEffect(() => {
-    if (pageConfig?.authRedirect) {
-      window.location.assign(pageConfig.authRedirect);
-    }
-  }, [pageConfig?.authRedirect]);
-
   if (!pageConfig) {
     router.replace({ pathname: '/404' });
     return '';
   }
-  if (pageConfig.authRedirect) {
-    return <RedirectingPage redirect={pageConfig.authRedirect} />;
-  }
   if (pageConfig.buildError) {
     return (
       <BuildErrorPage

package/lib/client/auth/Auth.jsx

@@ -14,6 +14,8 @@
   limitations under the License.
 */
 
+/* eslint-disable react/jsx-props-no-spreading */
+
 import React from 'react';
 import AuthConfigured from './AuthConfigured.jsx';
 import AuthNotConfigured from './AuthNotConfigured.js';
@@ -23,24 +25,24 @@ import { serializer } from '@lowdefy/helpers';
 // Client code imports the build JSON directly — Vite handles JSON imports;
 // the lib/build/*.js wrappers are server-only (they read from disk).
 // Deserialize to restore arrays from their ~arr build markers (providers
-// must be a real array for provider lookups in createAuthMethods).
+// must be a real array for single-provider inference in createAuthMethods).
 import rawAuthConfig from '../../../build/auth.json';
 
 const authConfig = serializer.deserialize(rawAuthConfig);
 
-function Auth({ children, user }) {
+function Auth({ children, session }) {
   if (authConfig.configured === true) {
     return (
-      <AuthConfigured serverUser={user} authConfig={authConfig}>
+      <AuthConfigured serverSession={session} authConfig={authConfig}>
         {(auth) => children(auth)}
       </AuthConfigured>
     );
   }
   // An app whose only auth key is auth.dev has no auth stack, but the dev
-  // server still resolves a caller for auth.dev.mockUser - pass it through so
-  // _user reads the same identity in the browser as on the server.
+  // server still resolves a session for auth.dev.mockUser - pass it through
+  // so _user reads the same identity in the browser as on the server.
   return (
-    <AuthNotConfigured authConfig={authConfig} user={user}>
+    <AuthNotConfigured authConfig={authConfig} session={session}>
       {(auth) => children(auth)}
     </AuthNotConfigured>
   );

package/lib/client/auth/AuthConfigured.jsx

@@ -14,223 +14,60 @@
   limitations under the License.
 */
 
-import React, { useEffect, useRef, useState } from 'react';
-import { createAuthClient } from 'better-auth/react';
+/* eslint-disable react/jsx-props-no-spreading */
+
+import React, { useEffect, useRef } from 'react';
 import {
-  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';
+  authConfigManager,
+  getSession,
+  SessionProvider,
+  signIn,
+  signOut,
+  useSession,
+} from '@hono/auth-js/react';
 
-import { normalizeCaller, serializer } from '@lowdefy/helpers';
+import { serializer } from '@lowdefy/helpers';
 
 import rawLowdefyConfig from '../../../build/config.json';
 
 const lowdefyConfig = serializer.deserialize(rawLowdefyConfig);
 
-// GenericOAuth providers have no client plugin here. BetterAuth 1.7.0 dropped
-// genericOAuthClient from better-auth/client/plugins, and nothing replaces it:
-// through 1.6.x it was a marker plugin carrying only an id, a version, an empty
-// $InferServerPlugin for TypeScript inference, and the generic-oauth error
-// codes - no actions, atoms, fetch plugins or path methods. signIn.oauth2 is
-// resolved by the client's dynamic path proxy from the call itself
-// (signIn.oauth2 -> POST /sign-in/oauth2, POST because providerId is always
-// sent), so the sign-in a Lowdefy GenericOAuth provider makes is unaffected.
-const authClient = createAuthClient({
-  baseURL: `${window.location.origin}${lowdefyConfig.basePath ?? ''}/api/auth`,
-  plugins: [
-    adminClient(),
-    emailOTPClient(),
-    magicLinkClient(),
-    oauthProviderClient(),
-    organizationClient(),
-    passkeyClient(),
-    phoneNumberClient(),
-    twoFactorClient(),
-  ],
-});
-
-// 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 },
-});
+// @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` });
+}
 
-// 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));
+function Session({ children }) {
+  const wasAuthenticated = useRef(false);
+  const { data: session, status } = useSession();
+  wasAuthenticated.current = wasAuthenticated.current || status === 'authenticated';
 
   useEffect(() => {
-    if (session) {
-      wasAuthenticated.current = true;
-    }
-    // Reload after sign-out (or session revocation) so the server can apply
-    // the page auth fork - a protected page redirects to the login page.
-    // A logout with a callbackUrl suppresses the reload - its own navigation
-    // would otherwise race this one.
-    if (wasAuthenticated.current && !isPending && !session && !reloadSuppressedRef.current) {
+    if (wasAuthenticated.current && status === 'unauthenticated') {
       window.location.reload();
     }
-  }, [session, isPending]);
+  }, [status]);
 
-  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 ref has not caught up with a changed session user - a sign-in as a
-    // different person lands between the session refetch and the /api/user
-    // result. 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. UpdateSession closes
-    // the window when it lands the new caller; a flow that changes the session
-    // user without chaining it leaves the previous caller rendered until the
-    // next page load.
-    return children(resolved, setResolvedUser);
+  // 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 '';
   }
-  // _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);
+  return children(session);
 }
 
-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 fetch(`${lowdefyConfig.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();
-    },
-    suppressSignOutReload: () => {
-      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),
-    signInOauth2: (params) => authClient.signIn.oauth2(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),
-  };
+function AuthConfigured({ authConfig, children, serverSession }) {
+  const auth = { authConfig, getSession, signIn, signOut };
   return (
-    <Session reloadSuppressedRef={reloadSuppressedRef} serverUser={serverUser}>
-      {(user, setResolvedUser) => {
-        auth.user = user;
-        auth.updateResolvedUser = (resolved) => setResolvedUser(resolved);
-        return children(auth);
-      }}
-    </Session>
+    <SessionProvider session={serverSession}>
+      <Session>
+        {(session) => {
+          auth.session = session;
+          return children(auth);
+        }}
+      </Session>
+    </SessionProvider>
   );
 }
 

package/lib/client/auth/AuthNotConfigured.js

@@ -13,6 +13,7 @@
   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';
 
@@ -22,51 +23,17 @@ function authNotConfigured() {
   );
 }
 
-// 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 }) {
+// A dev mock user reaches the browser through this component: an app whose
+// only auth key is auth.dev has no auth stack, but the dev server still
+// resolves a session for it, so _user reads the same identity in the browser
+// as on the server.
+function AuthNotConfigured({ authConfig, children, session = null }) {
   const auth = {
     authConfig,
-    user,
-    acceptInvitation: authNotConfigured,
-    addPasskey: authNotConfigured,
-    changePassword: authNotConfigured,
-    deletePasskey: authNotConfigured,
-    getResolvedUser: authNotConfigured,
+    session,
     getSession: 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,
-    signInOauth2: authNotConfigured,
-    signInPasskey: authNotConfigured,
-    signInPhoneNumber: authNotConfigured,
-    signInSocial: authNotConfigured,
+    signIn: authNotConfigured,
     signOut: authNotConfigured,
-    signUpEmail: authNotConfigured,
-    suppressSignOutReload: authNotConfigured,
-    twoFactorDisable: authNotConfigured,
-    twoFactorEnable: authNotConfigured,
-    twoFactorGenerateBackupCodes: authNotConfigured,
-    twoFactorVerifyBackupCode: authNotConfigured,
-    twoFactorVerifyTotp: authNotConfigured,
-    updatePasskey: authNotConfigured,
-    updateResolvedUser: authNotConfigured,
   };
 
   return children(auth);

package/lib/client/utils/usePageConfig.js

@@ -30,7 +30,6 @@ function parseJsModule(text) {
 }
 
 export async function fetchPageConfig(url) {
-  const basePath = url.replace(/\/api\/page\/.*$/, '');
   // A stalled request (server restart mid-request, exhausted sockets) must
   // become a visible error, never an eternal Suspense fallback — the reload
   // recovery path cannot fire while the page tree is suspended.
@@ -51,20 +50,6 @@ export async function fetchPageConfig(url) {
   if (res.status === 404) {
     return null;
   }
-  if (res.status === 401 || res.status === 403) {
-    // 401: logged-out navigation to a protected page. 403: authorised but second
-    // factor not yet enrolled. Page renders a redirect screen and full-loads to
-    // the destination so it can return here afterwards. Returning a settled value
-    // (never a parked promise) keeps the SWR key healthy: if the navigation is
-    // dropped, the tab still recovers on the next reload event or via the manual
-    // link on the redirect screen.
-    const { redirect } = await res.json();
-    const authRedirect = redirect ?? `${basePath}/404`;
-    console.warn(
-      `Lowdefy dev: "${url}" returned ${res.status} - redirecting to "${authRedirect}".`
-    );
-    return { authRedirect };
-  }
   const data = await res.json();
   if (data?.buildError) {
     return data;

package/lib/docs/getBrowser.test.mjs

@@ -67,6 +67,7 @@ test('openPage injects the default roleless user when no user is given', async (
   await openPage({ browser, origin: 'http://localhost:3001', pageId: 'home' });
 
   expect(decodeUserCookie(addCookies)).toEqual({
+    sub: 'lowdefy-headless',
     id: 'lowdefy-headless',
     name: 'Lowdefy Headless',
     roles: [],
@@ -84,6 +85,7 @@ test('openPage injects a per-call user with roles', async () => {
   });
 
   expect(decodeUserCookie(addCookies)).toEqual({
+    sub: 'lowdefy-headless',
     id: 'agent',
     name: 'Lowdefy Headless',
     roles: ['user-admin'],

package/lib/docs/runEndpoint.test.mjs

@@ -159,7 +159,7 @@ test('runEndpoint defaults the payload to an empty object', async () => {
 });
 
 test('runEndpoint passes the user to createLowdefyContext and logs the run', async () => {
-  const user = { roles: ['admin'], organization_id: 'org_1' };
+  const user = { roles: ['admin'], id: 'user_1' };
 
   await runEndpoint({ endpointId: 'create_order', user, honoContext });
 

package/lib/docs/runRequest.test.mjs

@@ -38,7 +38,6 @@ jest.unstable_mockModule('../server/createLowdefyContext.js', () => ({
   default: mockCreateLowdefyContext,
 }));
 
-const { ConfigError } = await import('@lowdefy/errors');
 const { default: runRequest } = await import('./runRequest.js');
 
 const honoContext = { req: { path: '/lowdefy-docs/run-request' } };
@@ -57,7 +56,7 @@ beforeEach(() => {
 });
 
 test('runRequest passes a user object to createLowdefyContext', async () => {
-  const user = { roles: ['admin'], organization_id: 'org_1' };
+  const user = { roles: ['admin'], id: 'user_1' };
 
   const result = await runRequest({
     pageId: 'home',
@@ -84,10 +83,10 @@ test('runRequest logs the user it ran the request as', async () => {
   });
 });
 
-test('runRequest throws a ConfigError when user is not an object', async () => {
+test('runRequest throws when user is not an object', async () => {
   await expect(
     runRequest({ pageId: 'home', requestId: 'get_rows', user: 'admin', honoContext })
-  ).rejects.toThrow(ConfigError);
+  ).rejects.toThrow(/run_request "user" must be an object/);
   await expect(
     runRequest({ pageId: 'home', requestId: 'get_rows', user: ['admin'], honoContext })
   ).rejects.toThrow(/run_request "user" must be an object/);

package/lib/server/auth/{getStrategies.js → getAuthConfig.js}

@@ -14,27 +14,25 @@
   limitations under the License.
 */
 
-import { getAuthStrategies } from '@lowdefy/api';
+import { getAuthConfig as getApiAuthConfig } from '@lowdefy/api';
 import { getSecretsFromEnv } from '@lowdefy/node-utils';
 
+import adapters from '../../../build/plugins/auth/adapters.js';
 import appMeta from '../../build/appMeta.js';
 import authJson from '../../build/auth.js';
-import strategyTypes from '../../../build/plugins/auth/strategies.js';
+import callbacks from '../../../build/plugins/auth/callbacks.js';
+import events from '../../../build/plugins/auth/events.js';
+import providers from '../../../build/plugins/auth/providers.js';
 
-// Returns the API auth strategy verifiers (memoized in @lowdefy/api), or an
-// empty list when auth is not configured - resolveAuthentication tries them
-// in config order when no session resolves.
-function getStrategies({ logger }) {
-  if (authJson.configured !== true) {
-    return [];
-  }
-  return getAuthStrategies({
+function getAuthConfig({ logger }) {
+  return getApiAuthConfig({
     appMeta,
     authJson,
+    dev: true,
     logger,
-    plugins: { strategies: strategyTypes },
+    plugins: { adapters, callbacks, events, providers },
     secrets: getSecretsFromEnv(),
   });
 }
 
-export default getStrategies;
+export default getAuthConfig;

package/lib/server/auth/getDevSession.js

@@ -0,0 +1,70 @@
+/*
+  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 { createSessionCallback } from '@lowdefy/api';
+
+import authJson from '../../build/auth.js';
+import callbacks from '../../../build/plugins/auth/callbacks.js';
+import getHeadlessUser from './getHeadlessUser.js';
+import getMockUser from './getMockUser.js';
+
+// THE single source of dev sessions (mock user, headless renderer). Two
+// invariants live here, by construction rather than by convention:
+//
+// 1. Prod parity: the dev user runs through the identical Auth.js session
+//    callback a real sign-in uses (OIDC claim copy, userFields mapping,
+//    custom session-callback plugins, roles validation, hashed_id) — so what
+//    a mock or headless session sees is exactly what a real authenticated
+//    user would see in production, and dev validates prod behaviour.
+// 2. Client/server parity: every consumer — the server request context
+//    (session.js) and the browser client's GET /api/auth/session
+//    (routes/auth.js) — obtains the session from this one function, so the
+//    two can never diverge.
+//
+// A dev user needs no auth stack behind it: an app whose only auth key is
+// auth.dev is not an auth configuration (auth.configured is false), and its
+// mock user is still the caller here and in the browser.
+//
+// Auth.js sessions carry an expires timestamp (the client SessionProvider
+// schedules refetches off it); dev sessions never expire while the server
+// runs, a day keeps polling calm.
+const DEV_SESSION_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+// An explicit `user` is a per-call caller (createLowdefyContext's `user`
+// option, used by the headless agent tools): it wins over the ambient mock
+// user and headless cookie, and runs through the same session pipeline.
+async function getDevSession(c, { user: injectedUser } = {}) {
+  const user = injectedUser ?? getMockUser() ?? getHeadlessUser(c);
+  if (!user) {
+    return undefined;
+  }
+  const sessionCallback = createSessionCallback({
+    authConfig: authJson,
+    plugins: { callbacks },
+  });
+
+  // The dev user acts as both token and user, exactly how a decoded JWT
+  // reaches the session callback on a real request.
+  const session = await sessionCallback({
+    session: { user: {} },
+    token: user,
+    user,
+  });
+  session.expires = new Date(Date.now() + DEV_SESSION_MAX_AGE_MS).toISOString();
+  return session;
+}
+
+export default getDevSession;