@lowdefy/server-dev 5.5.1 → 6.0.0

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.
+//
+// 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;
+
+async function getDevSession(c) {
+  const user = getMockUser() ?? getHeadlessUser(c);
+  if (!user) {
+    return undefined;
+  }
+  // Without auth configured nothing is protected and there is no session
+  // callback pipeline to run — a dev session would not match any prod
+  // behaviour. (A configured mock user already threw in getMockUser.)
+  if (authJson.configured !== true) {
+    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;

package/lib/server/auth/getDevSession.test.mjs

@@ -0,0 +1,138 @@
+/*
+  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 fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { jest } from '@jest/globals';
+
+// Only the auth build artifact is mocked — createSessionCallback is the REAL
+// @lowdefy/api pipeline, because prod parity is exactly what these tests
+// exist to prove: a dev session must be shaped by the same userFields
+// mapping, roles validation, and hashed_id stamping as a real sign-in.
+jest.unstable_mockModule('../../build/auth.js', () => ({
+  default: {
+    configured: true,
+    callbacks: [],
+    userFields: {
+      id: 'user.id',
+      roles: 'user.roles',
+      global_attributes: 'user.global_attributes',
+    },
+  },
+}));
+
+// getDevSession statically imports the app build's auth callbacks module,
+// which only exists in a built app (build/** is gitignored). Materialize an
+// empty one — exactly what a build without custom auth callback plugins
+// writes — so the import resolves; clean up only if this test created it.
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const callbacksDir = path.resolve(dirname, '../../../build/plugins/auth');
+const callbacksPath = path.join(callbacksDir, 'callbacks.js');
+const createdCallbacksFixture = !fs.existsSync(callbacksPath);
+if (createdCallbacksFixture) {
+  fs.mkdirSync(callbacksDir, { recursive: true });
+  fs.writeFileSync(callbacksPath, 'export default {};\n');
+}
+
+afterAll(() => {
+  if (createdCallbacksFixture) {
+    fs.rmSync(callbacksPath, { force: true });
+  }
+});
+
+const { default: getDevSession } = await import('./getDevSession.js');
+const { HEADLESS_USER_COOKIE, headlessUser } = await import('./headlessUser.js');
+
+function createContext({ cookie } = {}) {
+  return { req: { header: (name) => (name === 'cookie' ? (cookie ?? '') : undefined) } };
+}
+
+function headlessCookie(user = headlessUser) {
+  return `${HEADLESS_USER_COOKIE}=${Buffer.from(JSON.stringify(user)).toString('base64')}`;
+}
+
+const originalDevUser = process.env.LOWDEFY_DEV_USER;
+
+afterEach(() => {
+  if (originalDevUser === undefined) {
+    delete process.env.LOWDEFY_DEV_USER;
+  } else {
+    process.env.LOWDEFY_DEV_USER = originalDevUser;
+  }
+});
+
+test('getDevSession returns undefined with no mock user and no headless cookie', async () => {
+  delete process.env.LOWDEFY_DEV_USER;
+  expect(await getDevSession(createContext())).toBe(undefined);
+});
+
+test('mock user session is built by the real session callback — userFields, hashed_id, expires', async () => {
+  // The claim shape a consuming app's tenant convention uses (e.g.
+  // global_attributes.company_ids) must survive to session.user on BOTH the
+  // server request path and the client session endpoint — this session is
+  // what both serve.
+  process.env.LOWDEFY_DEV_USER = JSON.stringify({
+    id: 'dev-user',
+    sub: 'dev-user',
+    name: 'Dev User',
+    roles: ['admin'],
+    global_attributes: { company_ids: ['C-1'] },
+  });
+
+  const session = await getDevSession(createContext());
+  expect(session.user.id).toEqual('dev-user');
+  expect(session.user.name).toEqual('Dev User');
+  expect(session.user.roles).toEqual(['admin']);
+  expect(session.user.global_attributes).toEqual({ company_ids: ['C-1'] });
+  // Prod-session markers from the real pipeline:
+  expect(typeof session.hashed_id).toBe('string');
+  expect(session.hashed_id.length).toBeGreaterThan(0);
+  expect(new Date(session.expires).getTime()).toBeGreaterThan(Date.now());
+});
+
+test('headless cookie session runs through the same pipeline as a real sign-in', async () => {
+  delete process.env.LOWDEFY_DEV_USER;
+
+  const session = await getDevSession(createContext({ cookie: headlessCookie() }));
+  expect(session.user.id).toEqual(headlessUser.id);
+  expect(session.user.roles).toEqual([]);
+  expect(typeof session.hashed_id).toBe('string');
+});
+
+test('mock user takes precedence over the headless cookie', async () => {
+  process.env.LOWDEFY_DEV_USER = JSON.stringify({ id: 'mock-wins', roles: [] });
+
+  const session = await getDevSession(createContext({ cookie: headlessCookie() }));
+  expect(session.user.id).toEqual('mock-wins');
+});
+
+test('invalid roles are rejected by the real pipeline, exactly as in prod', async () => {
+  process.env.LOWDEFY_DEV_USER = JSON.stringify({ id: 'bad', roles: 'admin' });
+
+  await expect(getDevSession(createContext())).rejects.toThrow(
+    'session.user.roles must be an array of strings.'
+  );
+});
+
+test('invalid JSON in LOWDEFY_DEV_USER throws a clear error', async () => {
+  process.env.LOWDEFY_DEV_USER = 'not json';
+
+  await expect(getDevSession(createContext())).rejects.toThrow(
+    'Invalid JSON in LOWDEFY_DEV_USER environment variable.'
+  );
+});

package/lib/server/auth/getHeadlessUser.js

@@ -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 { HEADLESS_USER_COOKIE } from './headlessUser.js';
+
+// Decodes the headless renderer's user cookie (set by getBrowser.js openPage
+// on its own browser context, base64-encoded JSON) into the raw user object.
+// Returns just the user; getDevSession.js turns it into a session through
+// the same pipeline a real sign-in uses, so headless requests carry a
+// prod-shaped session while the developer's real browser (no cookie) is
+// unaffected.
+function getHeadlessUser(c) {
+  const cookieHeader = c.req.header('cookie') ?? '';
+  const match = cookieHeader.match(new RegExp(`${HEADLESS_USER_COOKIE}=([^;]+)`));
+  if (!match) {
+    return undefined;
+  }
+
+  try {
+    const decoded = Buffer.from(decodeURIComponent(match[1]), 'base64').toString();
+    return JSON.parse(decoded);
+  } catch {
+    return undefined;
+  }
+}
+
+export default getHeadlessUser;

package/lib/server/auth/{getMockSession.js → getMockUser.js}

@@ -14,13 +14,15 @@
   limitations under the License.
 */
 
-import { createSessionCallback } from '@lowdefy/api';
 import { serializer } from '@lowdefy/helpers';
 
 import authJson from '../../build/auth.js';
-import callbacks from '../../../build/plugins/auth/callbacks.js';
 
-async function getMockSession() {
+// Resolves the raw mock user object — LOWDEFY_DEV_USER env var first (the
+// `lowdefy dev --mock-user` flag sets it), then auth.dev.mockUser from the
+// build config. Returns just the user object; getDevSession.js turns it into
+// a session through the same pipeline a real sign-in uses.
+function getMockUser() {
   const mockUserJson = process.env.LOWDEFY_DEV_USER;
   let mockUser;
 
@@ -38,9 +40,6 @@ async function getMockSession() {
     return undefined;
   }
 
-  // Deserialize to restore arrays from ~arr markers and remove other build markers
-  mockUser = serializer.deserialize(mockUser);
-
   if (authJson.configured !== true) {
     throw new Error(
       'Mock user configured but auth is not configured in lowdefy.yaml. ' +
@@ -48,20 +47,8 @@ async function getMockSession() {
     );
   }
 
-  // Create session callback to transform mock user
-  const sessionCallback = createSessionCallback({
-    authConfig: authJson,
-    plugins: { callbacks },
-  });
-
-  // Transform mock user through session callback (mock user acts as token)
-  const session = await sessionCallback({
-    session: { user: {} },
-    token: mockUser,
-    user: mockUser,
-  });
-
-  return session;
+  // Deserialize to restore arrays from ~arr markers and remove other build markers
+  return serializer.deserialize(mockUser);
 }
 
-export default getMockSession;
+export default getMockUser;

package/lib/server/auth/headlessUser.js

@@ -0,0 +1,29 @@
+/*
+  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.
+*/
+
+// Shared between the headless renderer (getBrowser.js, which sets the cookie on
+// its browser context) and the dev session resolution (getHeadlessUser.js, which
+// decodes it) so the cookie name and injected user shape live in one place.
+const HEADLESS_USER_COOKIE = 'lowdefy_headless_user';
+
+const headlessUser = {
+  sub: 'lowdefy-headless',
+  id: 'lowdefy-headless',
+  name: 'Lowdefy Headless',
+  roles: [],
+};
+
+export { HEADLESS_USER_COOKIE, headlessUser };

package/lib/server/auth/resolveHeadlessUser.js

@@ -0,0 +1,38 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+import { headlessUser } from './headlessUser.js';
+
+// The default headless caller is roleless, so role-gated pages and requests are
+// refused for it. A per-call `user` merges over that default, which keeps the
+// default id/name for the common `{ roles: [...] }` case while still allowing a
+// full caller (email, profile, attributes) for config that reads those - nothing
+// derives them for an injected caller, since no auth engine runs. Each headless
+// call gets its own browser context and cookie jar, so callers do not share an
+// identity.
+function resolveHeadlessUser({ user }) {
+  if (type.isNone(user)) {
+    return headlessUser;
+  }
+  if (!type.isObject(user)) {
+    throw new Error(`Headless "user" must be an object. Received ${JSON.stringify(user)}.`);
+  }
+  return { ...headlessUser, ...user };
+}
+
+export default resolveHeadlessUser;

package/lib/server/auth/resolveHeadlessUser.test.mjs

@@ -0,0 +1,78 @@
+/*
+  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 resolveHeadlessUser from './resolveHeadlessUser.js';
+import { headlessUser } from './headlessUser.js';
+
+test('resolveHeadlessUser returns the default roleless user when no user is given', () => {
+  expect(resolveHeadlessUser({})).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'lowdefy-headless',
+    name: 'Lowdefy Headless',
+    roles: [],
+  });
+});
+
+test('resolveHeadlessUser returns the default roleless user when user is null', () => {
+  expect(resolveHeadlessUser({ user: null })).toEqual(headlessUser);
+});
+
+test('resolveHeadlessUser merges roles over the default, keeping the default id and name', () => {
+  expect(resolveHeadlessUser({ user: { roles: ['user-admin'] } })).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'lowdefy-headless',
+    name: 'Lowdefy Headless',
+    roles: ['user-admin'],
+  });
+});
+
+test('resolveHeadlessUser keeps caller fields the app reads, like email and profile', () => {
+  expect(
+    resolveHeadlessUser({
+      user: { id: 'agent', email: 'agent@example.com', profile: { name: 'Agent' } },
+    })
+  ).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'agent',
+    name: 'Lowdefy Headless',
+    email: 'agent@example.com',
+    profile: { name: 'Agent' },
+    roles: [],
+  });
+});
+
+test('resolveHeadlessUser does not mutate the default user between calls', () => {
+  resolveHeadlessUser({ user: { id: 'first', roles: ['admin'] } });
+
+  expect(resolveHeadlessUser({})).toEqual({
+    sub: 'lowdefy-headless',
+    id: 'lowdefy-headless',
+    name: 'Lowdefy Headless',
+    roles: [],
+  });
+});
+
+test('resolveHeadlessUser throws when user is not an object', () => {
+  expect(() => resolveHeadlessUser({ user: 'admin' })).toThrow(
+    'Headless "user" must be an object. Received "admin".'
+  );
+});
+
+test('resolveHeadlessUser throws when user is an array', () => {
+  expect(() => resolveHeadlessUser({ user: ['admin'] })).toThrow(
+    'Headless "user" must be an object. Received ["admin"].'
+  );
+});

package/lib/server/auth/session.js

@@ -0,0 +1,39 @@
+/*
+  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 { getAuthUser } from '@hono/auth-js';
+
+import authJson from '../../build/auth.js';
+import getDevSession from './getDevSession.js';
+
+// Replaces getServerSession.js — dev sessions (mock user, headless renderer)
+// first, then the session from the Hono context populated by initAuthConfig.
+// getDevSession is the same function the client's GET /api/auth/session is
+// answered from (routes/auth.js), so server and client sessions match by
+// construction.
+async function getSession(c) {
+  const devSession = await getDevSession(c);
+  if (devSession) {
+    return devSession;
+  }
+  if (authJson.configured !== true) {
+    return undefined;
+  }
+  const authUser = await getAuthUser(c);
+  return authUser?.session ?? undefined;
+}
+
+export default getSession;

package/lib/server/auth/strategies.js

@@ -0,0 +1,47 @@
+/*
+  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 { getAuthStrategies, resolveStrategyCaller } from '@lowdefy/api';
+import { getSecretsFromEnv } from '@lowdefy/node-utils';
+
+import appMeta from '../../build/appMeta.js';
+import authJson from '../../build/auth.js';
+import strategies from '../../../build/plugins/auth/strategies.js';
+
+// Secrets are process-static env, so read once at module load rather than
+// on every sessionless request.
+const secrets = getSecretsFromEnv();
+
+// API auth strategies (apiKey/jwt headers) let MCP and service clients that
+// cannot hold a session cookie authenticate. Tried only when no session
+// resolved; a match is synthesized as session.user so createAuthorize and
+// _user work unchanged.
+async function getStrategyCaller(c, logger) {
+  const authStrategies = getAuthStrategies({
+    appMeta,
+    authJson,
+    logger,
+    plugins: { strategies },
+    secrets,
+  });
+  return resolveStrategyCaller({
+    headers: c.req.raw.headers,
+    logger,
+    strategies: authStrategies,
+  });
+}
+
+export default getStrategyCaller;