@lowdefy/shell 3.23.2 → 7.2.0

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);
+});

package/src/auth/getSheetReturnUrl.js

@@ -0,0 +1,35 @@
+/*
+  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.
+*/
+
+/**
+ * Where the sign-in sheet returns to the shell with its one-time token: on iOS the shell's scheme,
+ * <scheme>://auth, which ASWebAuthenticationSession hands only to the app that opened the sheet;
+ * on Android the app's https app link, <app url>/auth/mobile/callback, which Android opens only in
+ * the shell the app's assetlinks.json names (app.config.ts declares it, authCallbackIntentFilters).
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The app server's URL.
+ * @param {'ios'|'android'} params.platform
+ * @param {{ scheme }} params.shell The shell config.
+ */
+function getSheetReturnUrl({ apiBase, platform, shell }) {
+  if (platform === 'android') {
+    return `${apiBase.replace(/\/$/, '')}/auth/mobile/callback`;
+  }
+  return `${shell.scheme}://auth`;
+}
+
+export default getSheetReturnUrl;

package/src/auth/getTokenStoreOptions.js

@@ -0,0 +1,46 @@
+/*
+  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';
+
+/**
+ * How the session token is kept in the Keychain or Keystore: on this device only, never in a
+ * backup.
+ *
+ * - A shell with background work (location reports while the phone is locked) keeps it readable
+ *   after the phone's first unlock, so its background task can call the server. Biometrics then
+ *   guard the screens only.
+ * - Any other shell keeps it readable only while the phone is unlocked, and, with biometric
+ *   unlock, behind Face ID or a fingerprint: reading it is the unlock prompt. A change to the
+ *   phone's biometrics makes it unreadable, and the person signs in again.
+ *
+ * A protected item is read and deleted with the same requireAuthentication it was written with.
+ */
+function getTokenStoreOptions({ background, biometric }) {
+  if (background) {
+    return { keychainAccessible: SecureStore.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY };
+  }
+  if (biometric) {
+    return {
+      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      requireAuthentication: true,
+      authenticationPrompt: 'Unlock to continue',
+    };
+  }
+  return { keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY };
+}
+
+export default getTokenStoreOptions;

package/src/auth/isBackgroundShell.js

@@ -0,0 +1,26 @@
+/*
+  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 shell profile that reports location in the background (shell.json `profile`). Its
+// background task calls the server while the phone is locked, so its session token must stay
+// readable then, and biometrics guard only its screens.
+const BACKGROUND_PROFILES = ['field-tracking'];
+
+function isBackgroundShell(shell) {
+  return BACKGROUND_PROFILES.includes(shell.profile);
+}
+
+export default isBackgroundShell;

package/src/auth/isSheetReturnLink.js

@@ -0,0 +1,35 @@
+/*
+  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 link without its query or fragment. React Native's URL has no working pathname, so the
+// link is cut by hand, as parseQuery reads its query.
+function stripQuery(link) {
+  const end = link.search(/[?#]/);
+  return end === -1 ? link : link.slice(0, end);
+}
+
+/**
+ * Whether a link the router is opening is the sign-in sheet's return: the Android app link
+ * <app url>/auth/mobile/callback (getSheetReturnUrl). signInWithSheet reads it from the sheet's
+ * result, so the router must not open it as a page: its query holds the one-time token.
+ *
+ * @param {string} link The URL, or the path, Expo Router received.
+ */
+function isSheetReturnLink(link) {
+  return /^(https:\/\/[^/]+)?(\/.*)?\/auth\/mobile\/callback\/?$/.test(stripQuery(link));
+}
+
+export default isSheetReturnLink;

package/src/auth/parseQuery.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.
+*/
+
+// The query of a URL as { name: value }. React Native's URL has no working searchParams, and the
+// sheet's redirect URL is a custom scheme.
+function parseQuery(url) {
+  const start = url.indexOf('?');
+  if (start === -1) {
+    return {};
+  }
+  const end = url.indexOf('#', start);
+  const query = url.slice(start + 1, end === -1 ? undefined : end);
+  const params = {};
+  query
+    .split('&')
+    .filter((part) => part.length > 0)
+    .forEach((part) => {
+      const separator = part.indexOf('=');
+      const name = separator === -1 ? part : part.slice(0, separator);
+      const value = separator === -1 ? '' : part.slice(separator + 1);
+      params[decodeURIComponent(name)] = decodeURIComponent(value.replace(/\+/g, ' '));
+    });
+  return params;
+}
+
+export default parseQuery;

package/src/auth/purgeAppData.js

@@ -0,0 +1,80 @@
+/*
+  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 { Image } from 'expo-image';
+import { appStorageKey } from '@lowdefy/helpers';
+import { getDeviceFeature, hasDeviceFeature } from '@lowdefy/blocks-native/device';
+
+import getLastCacheKeyName from '../cache/getLastCacheKeyName.js';
+
+/**
+ * Removes everything the shell keeps for one app's signed-in person: the session token, every
+ * cached root and page of the app (all its callers), the last cache key, and the person's keys in
+ * the device store (SetLocalStorage's user keys, which the core puts under one prefix per app),
+ * the requests the offline queue still held for them, and the phone's work for them: background
+ * location and geofences stop and their backlog goes, scheduled notifications are cancelled and
+ * the badge cleared (on shells that carry those features), and the images expo-image cached for
+ * them, avatar photos and Markdown images that loaded with their token, leave memory and disk.
+ * Device preferences stay. Nothing a person saw outlives their sign-out.
+ *
+ * @param {Object} params
+ * @param {string} params.appId The app.
+ * @param {Object} params.cacheStore The page cache.
+ * @param {{ keys, remove }} params.kv The device store.
+ * @param {{ removeApp }} params.queueStore The offline request queue.
+ * @param {string|null} params.slug The app's slug (lowdefyApp.slug), which names its storage keys.
+ * @param {{ clear }} params.tokenStore The session token store.
+ */
+// The tracking feature's keys (src/device/tracking): the device store holds one tracking config and
+// backlog for the shell, not one per person.
+const TRACKING_KEYS = ['lowdefy-shell:tracking', 'lowdefy-shell:tracking-backlog'];
+
+// Calls a device feature the shell may not carry; a feature that fails does not stop the purge.
+async function callFeature(feature, call) {
+  if (!hasDeviceFeature(feature)) return;
+  try {
+    await call(getDeviceFeature({ feature, action: 'SignOut' }));
+  } catch (error) {
+    // The rest of the purge still runs.
+  }
+}
+
+async function purgeAppData({ appId, cacheStore, kv, queueStore, slug, tokenStore }) {
+  await callFeature('tracking', (tracking) => tracking.stopTracking());
+  await callFeature('tracking', (tracking) => tracking.stopGeofencing());
+  TRACKING_KEYS.forEach((key) => kv.remove(key));
+  await callFeature('notifications', async (notifications) => {
+    await notifications.cancel({ all: true });
+    await notifications.setBadgeCount({ count: 0 });
+  });
+  await tokenStore.clear();
+  await cacheStore.removeApp({ appId });
+  await queueStore.removeApp({ appId });
+  kv.remove(getLastCacheKeyName(appId));
+  // The shell renders every page with basePath '' (PageScreen).
+  const userPrefix = appStorageKey({ basePath: '', name: 'lowdefy_user:', slug });
+  kv.keys()
+    .filter((key) => key.startsWith(userPrefix))
+    .forEach((key) => kv.remove(key));
+  try {
+    await Promise.all([Image.clearMemoryCache(), Image.clearDiskCache()]);
+  } catch (error) {
+    // The session and its data are already gone; an image cache that fails to clear is not worth
+    // failing the sign-out for.
+  }
+}
+
+export default purgeAppData;

package/src/auth/purgeAppData.test.js

@@ -0,0 +1,104 @@
+/*
+  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 { Image } from 'expo-image';
+import { installDevice } from '@lowdefy/blocks-native/device';
+
+import purgeAppData from './purgeAppData.js';
+
+function memoryKv(entries) {
+  const values = new Map(Object.entries(entries));
+  return {
+    keys: () => [...values.keys()],
+    remove: (key) => values.delete(key),
+    values,
+  };
+}
+
+function purge(kv) {
+  return purgeAppData({
+    appId: 'app',
+    cacheStore: { removeApp: jest.fn() },
+    kv,
+    queueStore: { removeApp: jest.fn() },
+    slug: null,
+    tokenStore: { clear: jest.fn() },
+  });
+}
+
+test('a sign-out stops tracking and geofencing, drops the backlog and clears notifications', async () => {
+  const tracking = { stopTracking: jest.fn(), stopGeofencing: jest.fn() };
+  const notifications = { cancel: jest.fn(), setBadgeCount: jest.fn() };
+  const removeDevice = installDevice({ notifications, tracking });
+  const kv = memoryKv({
+    'lowdefy-shell:tracking': '{}',
+    'lowdefy-shell:tracking-backlog': '[]',
+    'lowdefy-shell:preferences': '{}',
+  });
+  await purge(kv);
+  removeDevice();
+  expect(tracking.stopTracking).toHaveBeenCalled();
+  expect(tracking.stopGeofencing).toHaveBeenCalled();
+  expect(notifications.cancel).toHaveBeenCalledWith({ all: true });
+  expect(notifications.setBadgeCount).toHaveBeenCalledWith({ count: 0 });
+  expect([...kv.values.keys()]).toEqual(['lowdefy-shell:preferences']);
+});
+
+test('a sign-out clears the images expo-image cached in memory and on disk', async () => {
+  const clearMemoryCache = jest.spyOn(Image, 'clearMemoryCache');
+  const clearDiskCache = jest.spyOn(Image, 'clearDiskCache');
+  await purge(memoryKv({}));
+  expect(clearMemoryCache).toHaveBeenCalled();
+  expect(clearDiskCache).toHaveBeenCalled();
+  clearMemoryCache.mockRestore();
+  clearDiskCache.mockRestore();
+});
+
+test('an image cache that fails to clear does not fail the sign-out', async () => {
+  const clearDiskCache = jest
+    .spyOn(Image, 'clearDiskCache')
+    .mockRejectedValue(new Error('disk cache busy'));
+  const kv = memoryKv({ 'lowdefy-shell:tracking-backlog': '[]' });
+  await expect(purge(kv)).resolves.toBeUndefined();
+  expect([...kv.values.keys()]).toEqual([]);
+  clearDiskCache.mockRestore();
+});
+
+test('a sign-out on a shell without tracking or notifications still purges', async () => {
+  const kv = memoryKv({ 'lowdefy-shell:tracking-backlog': '[]' });
+  await purge(kv);
+  expect([...kv.values.keys()]).toEqual([]);
+});
+
+test('a feature that fails to stop does not stop the purge', async () => {
+  const tracking = {
+    stopTracking: jest.fn().mockRejectedValue(new Error('denied')),
+    stopGeofencing: jest.fn(),
+  };
+  const removeDevice = installDevice({ tracking });
+  const tokenStore = { clear: jest.fn() };
+  await purgeAppData({
+    appId: 'app',
+    cacheStore: { removeApp: jest.fn() },
+    kv: memoryKv({}),
+    queueStore: { removeApp: jest.fn() },
+    slug: null,
+    tokenStore,
+  });
+  removeDevice();
+  expect(tracking.stopGeofencing).toHaveBeenCalled();
+  expect(tokenStore.clear).toHaveBeenCalled();
+});

package/src/auth/shouldLock.js

@@ -0,0 +1,26 @@
+/*
+  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.
+*/
+
+// Whether the app locks on coming back: it was in the background for unlockAfter seconds or
+// longer. backgroundedAt is null when it never left.
+function shouldLock({ backgroundedAt, now, unlockAfter }) {
+  if (backgroundedAt === null) {
+    return false;
+  }
+  return now - backgroundedAt >= unlockAfter * 1000;
+}
+
+export default shouldLock;

package/src/auth/signInWithSheet.js

@@ -0,0 +1,97 @@
+/*
+  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 Crypto from 'expo-crypto';
+import * as WebBrowser from 'expo-web-browser';
+import { Platform } from 'react-native';
+import { createPkceChallenge } from '@lowdefy/client-core';
+
+import getSheetReturnUrl from './getSheetReturnUrl.js';
+import parseQuery from './parseQuery.js';
+
+const VERIFIER_BYTES = 64;
+
+function sha256(data) {
+  return Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, data);
+}
+
+/**
+ * Signs in through the app's own sign-in page in a system sheet: every method the web app offers
+ * (passkeys, SSO, magic links, a second factor).
+ *
+ * - The sheet opens /auth/mobile with a random state, a PKCE S256 challenge and the platform. On
+ *   iOS it is ephemeral (no cookies shared with Safari).
+ * - Once the person is signed in, the page asks them to confirm. On Continue the server returns a
+ *   one-time token for a new phone session, bound to the challenge: on iOS to
+ *   <scheme>://auth?token=&state=, which ASWebAuthenticationSession hands only to this app; on
+ *   Android to the verified app link <app url>/auth/mobile/callback?token=&state=, which Android
+ *   opens only in this shell (getSheetReturnUrl).
+ * - The shell checks state is its own, then exchanges the token with the code verifier for the
+ *   session token. A return with another state is refused, so a link this sign-in did not start is
+ *   never exchanged. The verifier lives in this call only: it is in no URL and never stored.
+ *
+ * Returns { status }: `signedIn`, `cancelled` (the person closed the sheet or pressed Cancel) or
+ * `failed`.
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The app server's URL.
+ * @param {Object} params.authApi createAuthApi.
+ * @param {{ id, scheme }} params.shell The shell config.
+ */
+async function signInWithSheet({ apiBase, authApi, shell }) {
+  const state = Crypto.randomUUID();
+  const { codeVerifier, codeChallenge, codeChallengeMethod } = await createPkceChallenge({
+    verifierBytes: Crypto.getRandomBytes(VERIFIER_BYTES),
+    sha256,
+  });
+  const platform = Platform.OS === 'android' ? 'android' : 'ios';
+  const query = [
+    ['shell', shell.id],
+    ['state', state],
+    ['code_challenge', codeChallenge],
+    ['code_challenge_method', codeChallengeMethod],
+    ['platform', platform],
+  ]
+    .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+    .join('&');
+  const returnUrl = getSheetReturnUrl({ apiBase, platform, shell });
+  const result = await WebBrowser.openAuthSessionAsync(
+    `${apiBase}/auth/mobile?${query}`,
+    returnUrl,
+    {
+      preferEphemeralSession: true,
+    }
+  );
+  if (result.type !== 'success') {
+    return { status: 'cancelled' };
+  }
+  if (!result.url.startsWith(returnUrl)) {
+    return { status: 'failed' };
+  }
+  const params = parseQuery(result.url);
+  if (params.state !== state) {
+    return { status: 'failed' };
+  }
+  if (params.error === 'cancelled') {
+    return { status: 'cancelled' };
+  }
+  if (!params.token) {
+    return { status: 'failed' };
+  }
+  return authApi.exchangeToken({ token: params.token, codeVerifier });
+}
+
+export default signInWithSheet;