@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/auth/createCoreAuth.js

@@ -0,0 +1,96 @@
+/*
+  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 { getAuthorizationHeaders } from '@lowdefy/client-core';
+import { type } from '@lowdefy/helpers';
+
+/**
+ * The auth client the core's auth actions call (client-core createAuthMethods), as the web's is
+ * its Better Auth client: each method calls a Better Auth route with the session token as a bearer
+ * token and resolves with Better Auth's `{ data, error }`. Calls go through the watched fetch, so
+ * a 401 ends the session on the phone as any other call's does.
+ *
+ * The session the shell holds (the caller, its roles and organisation, and the pages it may open)
+ * is the app session's last sync. A switch of organisation syncs it before the action resolves, so
+ * the switch takes effect at once; UpdateSession syncs it too.
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The app server's URL.
+ * @param {Function} params.fetch The watched fetch (watchSession).
+ * @param {Function} params.getSession The app session (createAppSession), once started.
+ * @param {{ get }} params.tokenStore The session token store.
+ */
+function createCoreAuth({ apiBase, fetch, getSession, tokenStore }) {
+  async function call({ body = {}, method = 'POST', path }) {
+    const headers = getAuthorizationHeaders({ host: { authTransport: 'bearer', tokenStore } });
+    const init = { method, headers };
+    if (method !== 'GET') {
+      init.headers = { ...headers, 'Content-Type': 'application/json' };
+      init.body = JSON.stringify(body);
+    }
+    const res = await fetch(`${apiBase}/api/auth${path}`, init);
+    // A route an app's org policy disables answers 404 with no JSON body.
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const details = type.isObject(data) ? data : {};
+      return { data: null, error: { ...details, status: res.status, statusText: res.statusText } };
+    }
+    return { data, error: null };
+  }
+
+  async function sync() {
+    await getSession().sync();
+  }
+
+  function listOrganizations() {
+    return call({ method: 'GET', path: '/organization/list' });
+  }
+
+  async function setActiveOrganization({ organizationId, organizationSlug }) {
+    const result = await call({
+      path: '/organization/set-active',
+      body: { organizationId, organizationSlug },
+    });
+    if (result.error === null) {
+      await sync();
+    }
+    return result;
+  }
+
+  function refreshSession() {
+    return call({ method: 'GET', path: '/get-session' });
+  }
+
+  async function getResolvedUser() {
+    await sync();
+    return { user: getSession().getState().user };
+  }
+
+  function signOut() {
+    return call({ path: '/sign-out' });
+  }
+
+  return {
+    authConfig: {},
+    getResolvedUser,
+    listOrganizations,
+    refreshSession,
+    setActiveOrganization,
+    signOut,
+  };
+}
+
+export default createCoreAuth;

package/src/auth/createCoreAuth.test.js

@@ -0,0 +1,188 @@
+/*
+  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 createAppSession from '../session/createAppSession.js';
+import createCoreAuth from './createCoreAuth.js';
+import createFakeServer, { header } from '../test/createFakeServer.js';
+import createMemoryCacheStore from '../test/createMemoryCacheStore.js';
+import createMemoryStore from '../host/createMemoryStore.js';
+import { createPages, createRoot } from '../test/fixtures.js';
+
+const apiBase = 'https://field.example.com';
+const token = 'session-token.signature';
+
+const organizations = [
+  { id: 'org-1', name: 'Acme', slug: 'acme' },
+  { id: 'org-2', name: 'Globex', slug: 'globex' },
+];
+
+// The app's server: Better Auth's organization routes over the bearer token, with the caller
+// and user /api/user resolves moving to the organisation set-active makes active.
+function authRoutes(server) {
+  return function answer({ path, init }) {
+    if (header(init, 'authorization') !== `Bearer ${token}`) {
+      return { status: 401, body: { code: 'UNAUTHORIZED', message: 'Unauthorized' } };
+    }
+    if (path === '/organization/list') {
+      return { body: organizations };
+    }
+    if (path === '/organization/set-active') {
+      const { organizationId } = JSON.parse(init.body);
+      if (!organizations.some((org) => org.id === organizationId)) {
+        return {
+          status: 403,
+          body: { code: 'USER_IS_NOT_A_MEMBER_OF_THE_ORGANIZATION', message: 'Not a member.' },
+        };
+      }
+      server.state.caller = `c-ana-${organizationId}; roles=r-${organizationId}`;
+      server.state.user = { id: 'ana', organization_id: organizationId, roles: ['editor'] };
+      return { body: organizations.find((org) => org.id === organizationId) };
+    }
+    if (path === '/get-session') {
+      return { body: { session: { id: 's1' }, user: { id: 'ana' } } };
+    }
+    if (path === '/sign-out') {
+      return { body: { success: true } };
+    }
+    return { status: 404, body: null };
+  };
+}
+
+async function setup({ heldToken = token } = {}) {
+  const server = createFakeServer({
+    caller: 'c-ana-org-1; roles=r-org-1',
+    user: { id: 'ana', organization_id: 'org-1', roles: ['viewer'] },
+    root: createRoot(),
+    rootEtag: '"root-1"',
+    pages: createPages([['today', 'today', '"p-today-1"']]),
+  });
+  server.state.auth = authRoutes(server);
+  const tokenStore = { get: () => heldToken };
+  const session = createAppSession({
+    apiBase,
+    app: { id: 'field' },
+    cacheStore: createMemoryCacheStore(),
+    fetch: server.fetch,
+    kv: createMemoryStore(),
+    tokenStore,
+  });
+  await session.start();
+  const coreAuth = createCoreAuth({
+    apiBase,
+    fetch: server.fetch,
+    getSession: () => session,
+    tokenStore,
+  });
+  return { coreAuth, server, session };
+}
+
+function authCalls(server) {
+  return server.fetch.mock.calls
+    .filter(([url]) => url.startsWith(`${apiBase}/api/auth/`))
+    .map(([url, init]) => ({
+      path: url.slice(`${apiBase}/api/auth`.length),
+      method: init.method,
+      authorization: header(init, 'authorization'),
+      body: init.body === undefined ? undefined : JSON.parse(init.body),
+    }));
+}
+
+test('listOrganizations lists the memberships with the session token as a bearer', async () => {
+  const { coreAuth, server } = await setup();
+  expect(await coreAuth.listOrganizations()).toEqual({ data: organizations, error: null });
+  expect(authCalls(server)).toEqual([
+    {
+      path: '/organization/list',
+      method: 'GET',
+      authorization: `Bearer ${token}`,
+      body: undefined,
+    },
+  ]);
+});
+
+test('setActiveOrganization switches the organisation and syncs the session the shell holds', async () => {
+  const { coreAuth, server, session } = await setup();
+  const { generation, homeRequests } = session.getState();
+  expect(await coreAuth.setActiveOrganization({ organizationId: 'org-2' })).toEqual({
+    data: organizations[1],
+    error: null,
+  });
+  expect(authCalls(server)).toEqual([
+    {
+      path: '/organization/set-active',
+      method: 'POST',
+      authorization: `Bearer ${token}`,
+      body: { organizationId: 'org-2' },
+    },
+  ]);
+  const state = session.getState();
+  expect(state.user).toEqual({ id: 'ana', organization_id: 'org-2', roles: ['editor'] });
+  // Another caller: every screen is rebuilt for the new organisation, from its home page.
+  expect(state.generation).toBe(generation + 1);
+  expect(state.homeRequests).toBe(homeRequests + 1);
+});
+
+test('setActiveOrganization gives a refused switch as an error and leaves the session', async () => {
+  const { coreAuth, server, session } = await setup();
+  const before = session.getState();
+  const syncs = server.fetch.mock.calls.length;
+  expect(await coreAuth.setActiveOrganization({ organizationId: 'org-9' })).toEqual({
+    data: null,
+    error: {
+      code: 'USER_IS_NOT_A_MEMBER_OF_THE_ORGANIZATION',
+      message: 'Not a member.',
+      status: 403,
+      statusText: undefined,
+    },
+  });
+  expect(server.fetch.mock.calls).toHaveLength(syncs + 1);
+  expect(session.getState()).toBe(before);
+});
+
+test('an organisation route an app disables answers as an error with its status', async () => {
+  const { coreAuth, server } = await setup();
+  server.state.auth = () => ({ status: 404, body: null });
+  expect(await coreAuth.listOrganizations()).toEqual({
+    data: null,
+    error: { status: 404, statusText: undefined },
+  });
+});
+
+test('refreshSession reads the session and getResolvedUser syncs the caller', async () => {
+  const { coreAuth, server } = await setup();
+  expect(await coreAuth.refreshSession()).toEqual({
+    data: { session: { id: 's1' }, user: { id: 'ana' } },
+    error: null,
+  });
+  server.state.user = { id: 'ana', organization_id: 'org-1', roles: ['admin'] };
+  expect(await coreAuth.getResolvedUser()).toEqual({
+    user: { id: 'ana', organization_id: 'org-1', roles: ['admin'] },
+  });
+});
+
+test('signOut ends the session on the server with the bearer token', async () => {
+  const { coreAuth, server } = await setup();
+  expect(await coreAuth.signOut()).toEqual({ data: { success: true }, error: null });
+  expect(authCalls(server)).toEqual([
+    { path: '/sign-out', method: 'POST', authorization: `Bearer ${token}`, body: {} },
+  ]);
+});
+
+test('a call with no session token held sends no authorization', async () => {
+  const { coreAuth, server } = await setup({ heldToken: null });
+  expect((await coreAuth.listOrganizations()).error.status).toBe(401);
+  expect(authCalls(server)[0].authorization).toBe(null);
+});

package/src/auth/createSessionStores.js

@@ -0,0 +1,45 @@
+/*
+  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.
+*/
+
+/**
+ * The page cache and device store the app's session writes through. Once the session has ended
+ * (isEnded), a sync or page load still in flight writes nothing: the person's pages arriving after
+ * their sign-out are dropped, not cached.
+ */
+function createSessionStores({ cacheStore, isEnded, kv }) {
+  function unlessEnded(write) {
+    return async (params) => {
+      if (isEnded()) return;
+      await write(params);
+    };
+  }
+  return {
+    cacheStore: {
+      read: async (cacheKey) => (isEnded() ? null : cacheStore.read(cacheKey)),
+      writeRoot: unlessEnded(cacheStore.writeRoot),
+      writePage: unlessEnded(cacheStore.writePage),
+      removePages: unlessEnded(cacheStore.removePages),
+    },
+    kv: {
+      get: (key) => kv.get(key),
+      set: (key, value) => {
+        if (!isEnded()) kv.set(key, value);
+      },
+    },
+  };
+}
+
+export default createSessionStores;

package/src/auth/createTokenStore.js

@@ -0,0 +1,103 @@
+/*
+  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 * as SecureStore from 'expo-secure-store';
+
+import getTokenStoreOptions from './getTokenStoreOptions.js';
+
+const PROTECTED = 'protected';
+
+/**
+ * The session token store a bearer host gives the core (validateAuthTransport): one token per app
+ * in the Keychain or Keystore (getTokenStoreOptions), read once per unlock and held in memory, so
+ * `get` is synchronous.
+ *
+ * Whether the stored token is behind biometrics is kept beside it in the device store (not a
+ * secret), since it must be read with the options it was written with.
+ *
+ * `set` and `clear` tell subscribers: a token cleared anywhere (the core on a 401, a Logout
+ * action, the shell's own sign-out) is how the shell hears the session ended. `load` and `unload`
+ * (a lock drops the protected token from memory) tell no one.
+ *
+ * @param {Object} params
+ * @param {string} params.appId The app, from shell.json.
+ * @param {boolean} params.background The shell does background work (isBackgroundShell).
+ * @param {Function} params.getBiometric Whether a new token goes behind biometrics.
+ * @param {{ get, set, remove }} params.kv The device store.
+ */
+function createTokenStore({ appId, background, getBiometric, kv }) {
+  const key = `lowdefy-session-token.${appId.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+  const modeKey = `lowdefy-shell:token-mode:${appId}`;
+  const listeners = new Set();
+  let token = null;
+
+  function notify() {
+    listeners.forEach((listener) => listener(token));
+  }
+
+  function isProtected() {
+    return !background && kv.get(modeKey) === PROTECTED;
+  }
+
+  return {
+    isProtected,
+    async load() {
+      token = await SecureStore.getItemAsync(
+        key,
+        getTokenStoreOptions({ background, biometric: isProtected() })
+      );
+    },
+    get() {
+      return token;
+    },
+    async set(value) {
+      const biometric = !background && getBiometric();
+      if (biometric !== isProtected()) {
+        await SecureStore.deleteItemAsync(
+          key,
+          getTokenStoreOptions({ background, biometric: !biometric })
+        );
+      }
+      await SecureStore.setItemAsync(key, value, getTokenStoreOptions({ background, biometric }));
+      kv.set(modeKey, biometric ? PROTECTED : 'plain');
+      token = value;
+      notify();
+    },
+    unload() {
+      token = null;
+    },
+    async clear() {
+      const held = token !== null;
+      token = null;
+      // Both forms, so a token written before a change of unlock mode never outlives sign-out.
+      await SecureStore.deleteItemAsync(key, getTokenStoreOptions({ background, biometric: true }));
+      await SecureStore.deleteItemAsync(
+        key,
+        getTokenStoreOptions({ background, biometric: false })
+      );
+      kv.remove(modeKey);
+      if (held) {
+        notify();
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export default createTokenStore;

package/src/auth/createTokenStore.test.js

@@ -0,0 +1,116 @@
+/*
+  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 createMemoryStore from '../host/createMemoryStore.js';
+import createTokenStore from './createTokenStore.js';
+
+jest.mock('expo-secure-store', () =>
+  jest.requireActual('../test/createFakeSecureStore.js').default()
+);
+
+const SecureStore = jest.requireMock('expo-secure-store');
+
+const KEY = 'lowdefy-session-token.field';
+
+beforeEach(() => {
+  SecureStore.items.clear();
+});
+
+function create({ background = false, biometric = false, kv = createMemoryStore() } = {}) {
+  return {
+    kv,
+    store: createTokenStore({ appId: 'field', background, getBiometric: () => biometric, kv }),
+  };
+}
+
+test('a shell without background work keeps the token readable only while the phone is unlocked', async () => {
+  const { store } = create();
+  await store.set('token-1');
+  expect(SecureStore.items.get(`${KEY}|no-auth`)).toEqual({
+    value: 'token-1',
+    options: { keychainAccessible: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY' },
+  });
+  expect(store.isProtected()).toBe(false);
+});
+
+test('with biometric unlock the token is kept behind Face ID or a fingerprint', async () => {
+  const { store } = create({ biometric: true });
+  await store.set('token-1');
+  expect(SecureStore.items.get(`${KEY}|auth`).options).toEqual({
+    keychainAccessible: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+    requireAuthentication: true,
+    authenticationPrompt: 'Unlock to continue',
+  });
+  expect(store.isProtected()).toBe(true);
+});
+
+test('a shell with background work keeps the token readable after first unlock, biometrics or not', async () => {
+  const { store } = create({ background: true, biometric: true });
+  await store.set('token-1');
+  expect(SecureStore.items.get(`${KEY}|no-auth`).options).toEqual({
+    keychainAccessible: 'AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY',
+  });
+  expect(store.isProtected()).toBe(false);
+});
+
+test('the token is read once, with the options it was written with, and held in memory', async () => {
+  const kv = createMemoryStore();
+  await create({ biometric: true, kv }).store.set('token-1');
+  const { store } = create({ biometric: true, kv });
+  expect(store.get()).toBeNull();
+  await store.load();
+  expect(SecureStore.getItemAsync).toHaveBeenLastCalledWith(
+    KEY,
+    expect.objectContaining({ requireAuthentication: true })
+  );
+  SecureStore.getItemAsync.mockClear();
+  expect(store.get()).toBe('token-1');
+  expect(store.get()).toBe('token-1');
+  expect(SecureStore.getItemAsync).not.toHaveBeenCalled();
+  store.unload();
+  expect(store.get()).toBeNull();
+});
+
+test('a change of unlock mode moves the token, leaving no copy behind', async () => {
+  let biometric = false;
+  const store = createTokenStore({
+    appId: 'field',
+    background: false,
+    getBiometric: () => biometric,
+    kv: createMemoryStore(),
+  });
+  await store.set('token-1');
+  biometric = true;
+  await store.set('token-2');
+  expect([...SecureStore.items.keys()]).toEqual([`${KEY}|auth`]);
+});
+
+test('set and clear tell subscribers; clear removes every copy of the token', async () => {
+  const { kv, store } = create();
+  const listener = jest.fn();
+  store.subscribe(listener);
+  await store.set('token-1');
+  expect(listener).toHaveBeenLastCalledWith('token-1');
+  await store.clear();
+  expect(listener).toHaveBeenLastCalledWith(null);
+  expect(SecureStore.items.size).toBe(0);
+  expect(kv.keys()).toEqual([]);
+  listener.mockClear();
+  await store.clear();
+  expect(listener).not.toHaveBeenCalled();
+});

package/src/auth/getAuthSettings.js

@@ -0,0 +1,24 @@
+/*
+  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.
+*/
+
+// The mobile.auth settings the app's server sends in the mobile root (emailCode, unlock,
+// unlockAfter, sharedDevice), or null when the app has no auth: the shell then opens it without a
+// sign-in screen.
+function getAuthSettings(root) {
+  return root?.auth ?? null;
+}
+
+export default getAuthSettings;

package/src/auth/getAuthView.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 getAuthSettings from './getAuthSettings.js';
+
+/**
+ * What the app shows for its auth state and session state:
+ * - `lock`: the lock screen, before any page;
+ * - `loading`: the token is being read;
+ * - `signIn`: the app has auth and nobody is signed in;
+ * - `app`: the app's pages (or the session's own loading and error screens).
+ */
+function getAuthView({ auth, session }) {
+  if (auth.status === 'locked') {
+    return 'lock';
+  }
+  if (auth.status === 'starting') {
+    return 'loading';
+  }
+  if (session.status === 'ready' && getAuthSettings(session.root) !== null && !auth.hasToken) {
+    return 'signIn';
+  }
+  return 'app';
+}
+
+export default getAuthView;

package/src/auth/getAuthView.test.js

@@ -0,0 +1,52 @@
+/*
+  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 getAuthView from './getAuthView.js';
+import shouldLock from './shouldLock.js';
+
+const settings = { emailCode: true, unlock: 'none', unlockAfter: 300, sharedDevice: false };
+const ready = { status: 'ready', root: { auth: settings } };
+
+test('getAuthView shows the lock screen before anything else', () => {
+  expect(getAuthView({ auth: { status: 'locked', hasToken: true }, session: ready })).toBe('lock');
+});
+
+test('getAuthView waits while the token is read', () => {
+  expect(getAuthView({ auth: { status: 'starting', hasToken: false }, session: ready })).toBe(
+    'loading'
+  );
+});
+
+test('getAuthView asks for sign-in when the app has auth and nobody is signed in', () => {
+  expect(getAuthView({ auth: { status: 'open', hasToken: false }, session: ready })).toBe('signIn');
+  expect(getAuthView({ auth: { status: 'open', hasToken: true }, session: ready })).toBe('app');
+});
+
+test('getAuthView opens an app without auth, and leaves loading and errors to the app', () => {
+  const open = { status: 'open', hasToken: false };
+  expect(getAuthView({ auth: open, session: { status: 'ready', root: { auth: null } } })).toBe(
+    'app'
+  );
+  expect(getAuthView({ auth: open, session: { status: 'loading', root: null } })).toBe('app');
+  expect(getAuthView({ auth: open, session: { status: 'error', root: null } })).toBe('app');
+});
+
+test('shouldLock locks after unlockAfter seconds in the background, not before', () => {
+  expect(shouldLock({ backgroundedAt: null, now: 1e9, unlockAfter: 0 })).toBe(false);
+  expect(shouldLock({ backgroundedAt: 1000, now: 300_999, unlockAfter: 300 })).toBe(false);
+  expect(shouldLock({ backgroundedAt: 1000, now: 301_000, unlockAfter: 300 })).toBe(true);
+  expect(shouldLock({ backgroundedAt: 1000, now: 1000, unlockAfter: 0 })).toBe(true);
+});