@lowdefy/shell 3.23.2 → 7.2.0

package/src/auth/createAppAuth.test.js

@@ -0,0 +1,424 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import createAppAuth from './createAppAuth.js';
+import createAppSession from '../session/createAppSession.js';
+import createFakeServer, { header } from '../test/createFakeServer.js';
+import createMemoryCacheStore from '../test/createMemoryCacheStore.js';
+import createMemoryStore from '../host/createMemoryStore.js';
+import getAuthView from './getAuthView.js';
+import { createPages, createRoot } from '../test/fixtures.js';
+
+jest.mock('expo-secure-store', () =>
+  jest.requireActual('../test/createFakeSecureStore.js').default()
+);
+jest.mock('expo-crypto', () => ({ getRandomBytes: (count) => new Uint8Array(count).fill(7) }));
+jest.mock('expo-web-browser', () => ({}));
+jest.mock('expo-local-authentication', () => ({}));
+
+const SecureStore = jest.requireMock('expo-secure-store');
+
+const apiBase = 'https://field.example.com';
+const app = { id: 'field', name: 'Field', urls: { production: apiBase } };
+const standardShell = { id: 'field', scheme: 'com.example.field', profile: 'standard' };
+const trackingShell = { ...standardShell, profile: 'field-tracking' };
+const SIGNED_IN = 'c-ana; session=s1; roles=r1';
+
+const settings = { emailCode: true, unlock: 'none', unlockAfter: 300, sharedDevice: false };
+
+function response({ body = {}, headers = {}, status = 200 }) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name) => headers[name.toLowerCase()] ?? null },
+    json: async () => structuredClone(body),
+  };
+}
+
+// The fake Lowdefy server, with Better Auth's sign-in and sign-out routes and sessions: a call
+// answers as the person its bearer token belongs to, or as the signed-out caller.
+function createServer({ auth = settings } = {}) {
+  const sessions = new Set();
+  const server = createFakeServer({
+    root: createRoot({ auth }),
+    rootEtag: '"root-1"',
+    pages: createPages([
+      ['today', 'today', '"p-today-1"'],
+      ['jobs', 'jobs', '"p-jobs-1"'],
+      ['jobs/{job_id}', 'job', '"p-job-1"'],
+    ]),
+  });
+  const serve = server.fetch.getMockImplementation();
+  server.fetch.mockImplementation(async (url, init = {}) => {
+    const { pathname } = new URL(url);
+    const body = init.body ? JSON.parse(init.body) : {};
+    const token = header(init, 'authorization')?.slice('Bearer '.length) ?? null;
+    const signedIn = token !== null && sessions.has(token);
+    if (pathname === '/api/auth/sign-in/email-otp') {
+      if (body.otp !== '123456') return response({ status: 400, body: { code: 'INVALID_OTP' } });
+      sessions.add('token-1');
+      return response({ body: { token: 'unsigned' }, headers: { 'set-auth-token': 'token-1' } });
+    }
+    if (pathname === '/api/auth/sign-out') {
+      sessions.delete(token);
+      return response({ body: { success: true } });
+    }
+    if (pathname === '/api/endpoints/admin') {
+      return response({ status: 403, headers: { 'x-lowdefy-caller': SIGNED_IN } });
+    }
+    if (pathname.startsWith('/api/request/') && !signedIn) {
+      return response({ status: 401, headers: { 'x-lowdefy-caller': '' } });
+    }
+    server.state.caller = signedIn ? SIGNED_IN : '';
+    server.state.user = signedIn ? { id: 'ana' } : null;
+    return serve(url, init);
+  });
+  return { server, sessions };
+}
+
+function createFakeAppState() {
+  let listener = null;
+  return {
+    addEventListener: (type, fn) => {
+      listener = fn;
+      return { remove: () => (listener = null) };
+    },
+    emit: (next) => listener?.(next),
+  };
+}
+
+async function until(check) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (check()) return;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  throw new Error('Timed out.');
+}
+
+async function setup({
+  cacheStore = createMemoryCacheStore(),
+  kv = createMemoryStore(),
+  queueStore = { removeApp: jest.fn(async () => undefined) },
+  server = createServer().server,
+  shell = standardShell,
+  streamFetch = jest.fn(),
+} = {}) {
+  const clock = { now: 0 };
+  const appState = createFakeAppState();
+  const localAuthentication = { authenticateAsync: jest.fn(async () => ({ success: true })) };
+  const onSignedOut = jest.fn();
+  const auth = createAppAuth({
+    apiBase,
+    app,
+    appState,
+    cacheStore,
+    fetch: server.fetch,
+    kv,
+    localAuthentication,
+    now: () => clock.now,
+    onSignedOut,
+    queueStore,
+    shell,
+    streamFetch,
+  });
+  const session = createAppSession({
+    apiBase,
+    app,
+    cacheStore: auth.sessionStores.cacheStore,
+    fetch: auth.fetch,
+    kv: auth.sessionStores.kv,
+    tokenStore: auth.tokenStore,
+  });
+  await auth.start({ session });
+  const view = () => getAuthView({ auth: auth.getState(), session: session.getState() });
+  return { appState, auth, cacheStore, clock, kv, localAuthentication, onSignedOut, session, view };
+}
+
+async function signIn(context) {
+  await until(() => context.view() === 'signIn');
+  expect(await context.auth.signInWithCode({ email: 'ana@example.com', otp: '123456' })).toEqual({
+    status: 'signedIn',
+  });
+  await until(() => context.session.getState().cacheKey === 'field:c-ana:r1');
+  await until(() => context.session.getState().status === 'ready');
+}
+
+beforeEach(() => {
+  SecureStore.items.clear();
+});
+
+test('an app with auth asks for sign-in when nobody is signed in, and keeps its settings', async () => {
+  const context = await setup();
+  await until(() => context.view() === 'signIn');
+  expect(JSON.parse(context.kv.get('lowdefy-shell:auth:field'))).toEqual({
+    settings,
+    slug: 'field',
+  });
+});
+
+test('an app without auth opens without a sign-in screen', async () => {
+  const context = await setup({ server: createServer({ auth: null }).server });
+  await until(() => context.session.getState().status === 'ready');
+  expect(context.view()).toBe('app');
+});
+
+test('signing in by email code keeps the token and opens the app as the person', async () => {
+  const context = await setup();
+  await signIn(context);
+  expect(context.auth.tokenStore.get()).toBe('token-1');
+  expect(SecureStore.items.get('lowdefy-session-token.field|no-auth').value).toBe('token-1');
+  expect(context.view()).toBe('app');
+  expect(context.session.getState().user).toEqual({ id: 'ana' });
+});
+
+test('a wrong code signs nobody in', async () => {
+  const context = await setup();
+  await until(() => context.view() === 'signIn');
+  expect(await context.auth.signInWithCode({ email: 'ana@example.com', otp: '000000' })).toEqual({
+    status: 'invalid',
+  });
+  expect(context.auth.tokenStore.get()).toBeNull();
+  expect(context.view()).toBe('signIn');
+});
+
+function keepPersonData(kv) {
+  kv.set('lowdefy:field::lowdefy_user:ana:draft', '{"note":"x"}');
+  kv.set('lowdefy:field::theme', 'dark');
+}
+
+// Only the phone's device key outlives a sign-out: it marks this phone, not the person.
+function expectOnlyDeviceKey() {
+  const left = [...SecureStore.items.keys()].filter(
+    (key) => !key.startsWith('lowdefy-device-key.')
+  );
+  expect(left).toEqual([]);
+}
+
+function expectPurged(context) {
+  expect(context.auth.tokenStore.get()).toBeNull();
+  expectOnlyDeviceKey();
+  expect([...context.cacheStore.roots.keys()]).toEqual([]);
+  expect(context.kv.get('lowdefy-shell:last-cache-key:field')).toBeNull();
+  expect(context.kv.get('lowdefy:field::lowdefy_user:ana:draft')).toBeNull();
+  expect(context.kv.get('lowdefy:field::theme')).toBe('dark');
+}
+
+test('sign-out ends the session on the server and removes the person from the phone', async () => {
+  const { server, sessions } = createServer();
+  const context = await setup({ server });
+  await signIn(context);
+  keepPersonData(context.kv);
+  await context.auth.signOut();
+  const signOutCall = server.fetch.mock.calls.find(([url]) => url.endsWith('/api/auth/sign-out'));
+  expect(header(signOutCall[1], 'authorization')).toBe('Bearer token-1');
+  expect(sessions.size).toBe(0);
+  expectPurged(context);
+  expect(context.onSignedOut).toHaveBeenCalledTimes(1);
+});
+
+test('a 401 to a call that carried the token removes the person and asks for sign-in again', async () => {
+  const { server, sessions } = createServer();
+  const context = await setup({ server });
+  await signIn(context);
+  keepPersonData(context.kv);
+  sessions.clear();
+  const res = await context.auth.fetch(`${apiBase}/api/request/today/get_jobs`, {
+    method: 'POST',
+    headers: { Authorization: 'Bearer token-1' },
+  });
+  expect(res.status).toBe(401);
+  await until(() => context.onSignedOut.mock.calls.length === 1);
+  expectPurged(context);
+  // The session was already gone: the shell does not call sign-out.
+  expect(server.fetch.mock.calls.some(([url]) => url.endsWith('/api/auth/sign-out'))).toBe(false);
+});
+
+test('a 401 to a streamed chat call that carried the token ends the session too', async () => {
+  const { server } = createServer();
+  const streamFetch = jest.fn(async () => response({ status: 401 }));
+  const context = await setup({ server, streamFetch });
+  await signIn(context);
+  keepPersonData(context.kv);
+  const res = await context.auth.streamFetch(`${apiBase}/api/agent/chat/assistant`, {
+    method: 'POST',
+    headers: { Authorization: 'Bearer token-1' },
+  });
+  expect(res.status).toBe(401);
+  expect(streamFetch).toHaveBeenCalledWith(`${apiBase}/api/agent/chat/assistant`, {
+    method: 'POST',
+    headers: { Authorization: 'Bearer token-1' },
+  });
+  await until(() => context.onSignedOut.mock.calls.length === 1);
+  expectPurged(context);
+});
+
+test('an answer as the signed-out caller to a call with the token ends the session', async () => {
+  const { server, sessions } = createServer();
+  const context = await setup({ server });
+  await signIn(context);
+  keepPersonData(context.kv);
+  sessions.clear();
+  await context.session.sync().catch(() => {});
+  await until(() => context.onSignedOut.mock.calls.length === 1);
+  expectPurged(context);
+});
+
+test('the token cleared by the core (a Logout action) is a sign-out too', async () => {
+  const context = await setup();
+  await signIn(context);
+  keepPersonData(context.kv);
+  await context.auth.tokenStore.clear();
+  await until(() => context.onSignedOut.mock.calls.length === 1);
+  expectPurged(context);
+});
+
+test('a 403 drops the cache of the organisation that refused the person, and only that', async () => {
+  const context = await setup();
+  await signIn(context);
+  expect(context.cacheStore.roots.has('field:c-ana:r1')).toBe(true);
+  expect(context.cacheStore.roots.has('field::')).toBe(true);
+  await context.auth.fetch(`${apiBase}/api/endpoints/admin`, {
+    method: 'POST',
+    headers: { Authorization: 'Bearer token-1' },
+  });
+  await until(() => !context.cacheStore.roots.has('field:c-ana:r1'));
+  expect(context.cacheStore.roots.has('field::')).toBe(true);
+  expect(context.onSignedOut).not.toHaveBeenCalled();
+});
+
+test('with biometric unlock the app locks after unlockAfter seconds in the background', async () => {
+  const { server } = createServer({ auth: { ...settings, unlock: 'biometric', unlockAfter: 60 } });
+  const context = await setup({ server });
+  await signIn(context);
+  expect(context.auth.tokenStore.isProtected()).toBe(true);
+
+  context.appState.emit('background');
+  context.clock.now = 59_999;
+  context.appState.emit('active');
+  expect(context.view()).toBe('app');
+
+  context.appState.emit('background');
+  context.clock.now += 60_000;
+  context.appState.emit('active');
+  expect(context.view()).toBe('lock');
+  // The protected token leaves memory; reading it again is the unlock prompt.
+  expect(context.auth.tokenStore.get()).toBeNull();
+  expect(context.onSignedOut).not.toHaveBeenCalled();
+
+  SecureStore.getItemAsync.mockClear();
+  expect(await context.auth.unlock()).toBe(true);
+  expect(SecureStore.getItemAsync).toHaveBeenCalledWith(
+    'lowdefy-session-token.field',
+    expect.objectContaining({ requireAuthentication: true })
+  );
+  expect(context.auth.tokenStore.get()).toBe('token-1');
+  expect(context.view()).toBe('app');
+});
+
+test('a cancelled unlock prompt keeps the app locked', async () => {
+  const { server } = createServer({ auth: { ...settings, unlock: 'biometric', unlockAfter: 0 } });
+  const context = await setup({ server });
+  await signIn(context);
+  context.appState.emit('background');
+  context.appState.emit('active');
+  SecureStore.getItemAsync.mockRejectedValueOnce(new Error('User canceled the authentication'));
+  expect(await context.auth.unlock()).toBe(false);
+  expect(context.view()).toBe('lock');
+});
+
+test('an app opened with a protected token shows the lock screen before reading it', async () => {
+  const kv = createMemoryStore();
+  const cacheStore = createMemoryCacheStore();
+  const { server } = createServer({ auth: { ...settings, unlock: 'biometric' } });
+  const first = await setup({ cacheStore, kv, server });
+  await signIn(first);
+  first.auth.dispose();
+
+  SecureStore.getItemAsync.mockClear();
+  const context = await setup({ cacheStore, kv, server });
+  expect(context.view()).toBe('lock');
+  expect(SecureStore.getItemAsync).not.toHaveBeenCalled();
+  expect(context.session.getState().status).toBe('loading');
+  expect(await context.auth.unlock()).toBe(true);
+  await until(() => context.session.getState().cacheKey === 'field:c-ana:r1');
+  expect(context.view()).toBe('app');
+});
+
+test('a shell with background work locks with the device biometrics and keeps its token', async () => {
+  const { server } = createServer({ auth: { ...settings, unlock: 'biometric', unlockAfter: 0 } });
+  const context = await setup({ server, shell: trackingShell });
+  await signIn(context);
+  expect(context.auth.tokenStore.isProtected()).toBe(false);
+  context.appState.emit('background');
+  context.appState.emit('active');
+  expect(context.view()).toBe('lock');
+  expect(context.auth.tokenStore.get()).toBe('token-1');
+  context.localAuthentication.authenticateAsync.mockResolvedValueOnce({ success: false });
+  expect(await context.auth.unlock()).toBe(false);
+  expect(context.view()).toBe('lock');
+  expect(await context.auth.unlock()).toBe(true);
+  expect(context.localAuthentication.authenticateAsync).toHaveBeenLastCalledWith({
+    promptMessage: 'Unlock Field',
+  });
+  expect(context.view()).toBe('app');
+});
+
+test('a shared device signs out when the app closes, and skips biometrics', async () => {
+  const { server } = createServer({
+    auth: { ...settings, unlock: 'biometric', unlockAfter: 0, sharedDevice: true },
+  });
+  const context = await setup({ server });
+  await signIn(context);
+  expect(context.auth.tokenStore.isProtected()).toBe(false);
+  keepPersonData(context.kv);
+  context.appState.emit('background');
+  await until(() => context.onSignedOut.mock.calls.length === 1);
+  expectPurged(context);
+});
+
+test('a shared device signs out on start when its token was stored behind biometrics', async () => {
+  const kv = createMemoryStore();
+  const first = await setup({
+    kv,
+    server: createServer({ auth: { ...settings, unlock: 'biometric' } }).server,
+  });
+  await signIn(first);
+  expect(first.auth.tokenStore.isProtected()).toBe(true);
+  first.auth.dispose();
+  // The app became a shared device, and the shell kept the new settings, before it was killed.
+  const shared = { ...settings, unlock: 'biometric', sharedDevice: true };
+  kv.set('lowdefy-shell:auth:field', JSON.stringify({ settings: shared, slug: 'field' }));
+  const context = await setup({
+    kv,
+    server: createServer({ auth: shared }).server,
+  });
+  expect(context.onSignedOut).toHaveBeenCalledTimes(1);
+  expect(context.localAuthentication.authenticateAsync).not.toHaveBeenCalled();
+  expectOnlyDeviceKey();
+});
+
+test('a shared device signs out on start when the app was closed without going to the background', async () => {
+  const kv = createMemoryStore();
+  const { server } = createServer({ auth: { ...settings, sharedDevice: true } });
+  const first = await setup({ kv, server });
+  await signIn(first);
+  first.auth.dispose();
+  const context = await setup({ kv, server });
+  expect(context.onSignedOut).toHaveBeenCalledTimes(1);
+  expectOnlyDeviceKey();
+});

package/src/auth/createAuthApi.js

@@ -0,0 +1,115 @@
+/*
+  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 readServerError from '../host/readServerError.js';
+
+/**
+ * The app server's Better Auth routes the shell signs in and out with. Calls carry no cookie
+ * (withoutCookies) and no Origin, so the server answers a sign-in with the session token in the
+ * bearer plugin's set-auth-token header, which goes to the token store.
+ *
+ * Results are what the screens act on:
+ * - sendCode: `sent` (also for an address the app does not admit: the server never says),
+ *   `unavailable` (the app has no email code sign-in: open the sheet), `rateLimited`.
+ * - signInWithCode: `signedIn`, `twoFactor` (finish in the sheet), `invalid` (a wrong or expired
+ *   code), `rateLimited`.
+ * - exchangeToken: `signedIn`, or `failed` when the server refuses the one-time token.
+ * Any other answer throws.
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The app server's URL.
+ * @param {Function} params.fetch The shell's fetch, without the session watch.
+ * @param {() => Promise<string>} params.getDeviceKey This phone's device key (createDeviceKey),
+ *   sent on the email-code calls so the server can tell this phone from a stranger.
+ * @param {{ set }} params.tokenStore The session token store.
+ */
+function createAuthApi({ apiBase, fetch, getDeviceKey, tokenStore }) {
+  function post({ body, headers = {}, path }) {
+    return fetch(`${apiBase}/api/auth${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async function keepSessionToken(res) {
+    const token = res.headers.get('set-auth-token');
+    if (type.isNone(token)) {
+      throw new Error("The app's server signed you in but sent no session token.");
+    }
+    await tokenStore.set(token);
+  }
+
+  function unexpected(res, what) {
+    return readServerError({
+      res,
+      message: `The app's server answered ${res.status} to the ${what}.`,
+    });
+  }
+
+  async function deviceKeyHeader() {
+    return { 'x-lowdefy-device-key': await getDeviceKey() };
+  }
+
+  async function sendCode({ email }) {
+    const res = await post({
+      path: '/email-otp/send-verification-otp',
+      body: { email, type: 'sign-in' },
+      headers: await deviceKeyHeader(),
+    });
+    if (res.ok) return { status: 'sent' };
+    if (res.status === 404) return { status: 'unavailable' };
+    if (res.status === 429) return { status: 'rateLimited' };
+    throw await unexpected(res, 'sign-in code request');
+  }
+
+  async function signInWithCode({ email, otp }) {
+    const res = await post({
+      path: '/sign-in/email-otp',
+      body: { email, otp },
+      headers: await deviceKeyHeader(),
+    });
+    if (res.status === 429) return { status: 'rateLimited' };
+    if (res.status >= 400 && res.status < 500) return { status: 'invalid' };
+    if (!res.ok) throw await unexpected(res, 'sign-in');
+    const body = await res.json();
+    if (body?.twoFactorRedirect === true) return { status: 'twoFactor' };
+    await keepSessionToken(res);
+    return { status: 'signedIn' };
+  }
+
+  async function exchangeToken({ token, codeVerifier }) {
+    const res = await post({
+      path: '/one-time-token/verify',
+      body: { token, code_verifier: codeVerifier },
+    });
+    if (res.status >= 400 && res.status < 500) return { status: 'failed' };
+    if (!res.ok) throw await unexpected(res, 'sign-in');
+    await keepSessionToken(res);
+    return { status: 'signedIn' };
+  }
+
+  // Ends the session on the server: its row is deleted, so the token is dead everywhere.
+  function signOut({ token }) {
+    return post({ path: '/sign-out', body: {}, headers: { Authorization: `Bearer ${token}` } });
+  }
+
+  return { exchangeToken, sendCode, signInWithCode, signOut };
+}
+
+export default createAuthApi;

package/src/auth/createAuthApi.test.js

@@ -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 { jest } from '@jest/globals';
+
+import createAuthApi from './createAuthApi.js';
+import withoutCookies from './withoutCookies.js';
+
+const apiBase = 'https://field.example.com';
+const DEVICE_KEY = 'a1'.repeat(32);
+
+function response({ body = {}, headers = {}, status = 200 }) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name) => headers[name] ?? null },
+    json: async () => body,
+  };
+}
+
+function setup(answer) {
+  const fetch = jest.fn(async () => response(answer));
+  const tokenStore = { set: jest.fn(async () => undefined) };
+  const getDeviceKey = async () => DEVICE_KEY;
+  return { api: createAuthApi({ apiBase, fetch, getDeviceKey, tokenStore }), fetch, tokenStore };
+}
+
+function sent(fetch) {
+  const [url, init] = fetch.mock.calls[0];
+  return { path: url.slice(apiBase.length), body: JSON.parse(init.body), headers: init.headers };
+}
+
+test('sendCode asks Better Auth for a sign-in code', async () => {
+  const { api, fetch } = setup({ body: { success: true } });
+  expect(await api.sendCode({ email: 'ana@example.com' })).toEqual({ status: 'sent' });
+  expect(sent(fetch)).toEqual({
+    path: '/api/auth/email-otp/send-verification-otp',
+    body: { email: 'ana@example.com', type: 'sign-in' },
+    headers: { 'Content-Type': 'application/json', 'x-lowdefy-device-key': DEVICE_KEY },
+  });
+});
+
+test('sendCode tells an app without email codes, and a rate limit, from a sent code', async () => {
+  expect(await setup({ status: 404 }).api.sendCode({ email: 'a@b.c' })).toEqual({
+    status: 'unavailable',
+  });
+  expect(await setup({ status: 429 }).api.sendCode({ email: 'a@b.c' })).toEqual({
+    status: 'rateLimited',
+  });
+  await expect(setup({ status: 500 }).api.sendCode({ email: 'a@b.c' })).rejects.toThrow(
+    "The app's server answered 500 to the sign-in code request."
+  );
+});
+
+test('signInWithCode keeps the session token from set-auth-token', async () => {
+  const { api, fetch, tokenStore } = setup({ headers: { 'set-auth-token': 'token-1' } });
+  expect(await api.signInWithCode({ email: 'ana@example.com', otp: '123456' })).toEqual({
+    status: 'signedIn',
+  });
+  expect(sent(fetch).path).toBe('/api/auth/sign-in/email-otp');
+  expect(sent(fetch).headers['x-lowdefy-device-key']).toBe(DEVICE_KEY);
+  expect(tokenStore.set).toHaveBeenCalledWith('token-1');
+});
+
+test('signInWithCode hands a second factor to the sheet and keeps no token', async () => {
+  const { api, tokenStore } = setup({ body: { twoFactorRedirect: true } });
+  expect(await api.signInWithCode({ email: 'a@b.c', otp: '123456' })).toEqual({
+    status: 'twoFactor',
+  });
+  expect(tokenStore.set).not.toHaveBeenCalled();
+});
+
+test('signInWithCode reads a refused code as invalid', async () => {
+  const { api, tokenStore } = setup({ status: 400, body: { code: 'INVALID_OTP' } });
+  expect(await api.signInWithCode({ email: 'a@b.c', otp: '000000' })).toEqual({
+    status: 'invalid',
+  });
+  expect(tokenStore.set).not.toHaveBeenCalled();
+});
+
+test('a sign-in answered without a session token fails', async () => {
+  const { api } = setup({ body: {} });
+  await expect(api.signInWithCode({ email: 'a@b.c', otp: '123456' })).rejects.toThrow(
+    "The app's server signed you in but sent no session token."
+  );
+});
+
+test('exchangeToken sends the one-time token with the code verifier', async () => {
+  const { api, fetch, tokenStore } = setup({ headers: { 'set-auth-token': 'token-1' } });
+  expect(await api.exchangeToken({ token: 'ott-1', codeVerifier: 'verifier' })).toEqual({
+    status: 'signedIn',
+  });
+  expect(sent(fetch)).toMatchObject({
+    path: '/api/auth/one-time-token/verify',
+    body: { token: 'ott-1', code_verifier: 'verifier' },
+  });
+  expect(tokenStore.set).toHaveBeenCalledWith('token-1');
+});
+
+test('exchangeToken fails when the server refuses the token', async () => {
+  const { api, tokenStore } = setup({ status: 400, body: { message: 'Invalid token' } });
+  expect(await api.exchangeToken({ token: 'ott-1', codeVerifier: 'wrong' })).toEqual({
+    status: 'failed',
+  });
+  expect(tokenStore.set).not.toHaveBeenCalled();
+});
+
+test('signOut ends the session the token names', async () => {
+  const { api, fetch } = setup({ body: { success: true } });
+  await api.signOut({ token: 'token-1' });
+  expect(sent(fetch)).toEqual({
+    path: '/api/auth/sign-out',
+    body: {},
+    headers: { 'Content-Type': 'application/json', Authorization: 'Bearer token-1' },
+  });
+});
+
+test('every shell call omits cookies', async () => {
+  const fetch = jest.fn(async () => response({}));
+  await withoutCookies(fetch)('https://field.example.com/api/user', { method: 'GET' });
+  expect(fetch).toHaveBeenCalledWith('https://field.example.com/api/user', {
+    method: 'GET',
+    credentials: 'omit',
+  });
+});