Merge pull request 'Device-security nudge: verify this device / key backup (#110, #123)' (#258) from security-nudge into lotus

Merge pull request #258

e2e/security-nudge.spec.ts

@@ -0,0 +1,74 @@
+import { test, expect, Page } from '@playwright/test';
+import { HS, ensureUser, hsReachable, loginUI, TestUser, uniq } from './localHs';
+
+// [Gitea #110, #123] The device-security nudge. A fresh account has no key
+// backup and no cross-signing → "Set up key backup", but only after the 24 h
+// grace period on this device; "Not now" snoozes it.
+const strip = (page: Page) => page.getByRole('status').filter({ hasText: /encryption keys/ });
+
+/** Back-date this device's first-seen record past the 24 h grace period, then reload. */
+async function pastGrace(page: Page) {
+  await page.evaluate(() => {
+    const { deviceId } = JSON.parse(localStorage.getItem('cinny_session_v1') ?? '{}');
+    localStorage.setItem(
+      `lotus-security-nudge-${deviceId}`,
+      JSON.stringify({ firstSeen: Date.now() - 2 * 86_400_000, dismissals: {} }),
+    );
+  });
+  await page.reload();
+}
+
+/** The nudge waits until sync has settled (after "Connecting…"). */
+async function settled(page: Page) {
+  await page
+    .getByText('Connecting...')
+    .first()
+    .waitFor({ timeout: 30_000 })
+    .catch(() => undefined);
+  await page.getByText('Connecting...').first().waitFor({ state: 'detached', timeout: 90_000 });
+  await page.waitForTimeout(2000);
+}
+
+test.describe('security nudge (#110, #123)', () => {
+  let user: TestUser;
+
+  test.beforeAll(async () => {
+    test.skip(!(await hsReachable()), `no local homeserver at ${HS} (set E2E_LOCAL_HS)`);
+  });
+
+  test.beforeEach(async () => {
+    user = await ensureUser(uniq('e2e_nudge_'));
+  });
+
+  test('nothing during the first 24 h on a device', async ({ page }) => {
+    test.setTimeout(150_000);
+    await loginUI(page, user);
+    await settled(page);
+    // Past the point where the nudge shows once the grace period is over (~5 s).
+    await page.waitForTimeout(8000);
+    await expect(strip(page)).toHaveCount(0);
+  });
+
+  test('no key backup: "Set up key backup" opens Settings → Devices', async ({ page }) => {
+    test.setTimeout(150_000);
+    await loginUI(page, user);
+    await pastGrace(page);
+    await settled(page);
+    const nudge = strip(page);
+    await expect(nudge).toContainText("Your encryption keys aren't backed up");
+    await nudge.getByRole('button', { name: 'Set up' }).click();
+    await expect(page.getByText('Device Verification').first()).toBeVisible();
+  });
+
+  test('"Not now" snoozes it across a reload', async ({ page }) => {
+    test.setTimeout(200_000);
+    await loginUI(page, user);
+    await pastGrace(page);
+    await settled(page);
+    await strip(page).getByRole('button', { name: 'Not now' }).click();
+    await expect(strip(page)).toHaveCount(0);
+    await page.reload();
+    await settled(page);
+    await expect(strip(page)).toHaveCount(0);
+  });
+});

package-lock.json

@@ -5026,9 +5026,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.18",
+      "version": "1.1.21",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",

src/app/features/security-nudge/SecurityBanner.tsx

@@ -0,0 +1,137 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import { useAtomValue, useSetAtom } from 'jotai';
+import { SyncState } from 'matrix-js-sdk';
+import { CryptoApi } from 'matrix-js-sdk/lib/crypto-api';
+import { Icons } from 'folds';
+import { ErrorBoundary } from 'react-error-boundary';
+import { useMatrixClient } from '../../hooks/useMatrixClient';
+import { useCrossSigningActive } from '../../hooks/useCrossSigning';
+import {
+  useDeviceVerificationStatus,
+  VerificationStatus,
+} from '../../hooks/useDeviceVerificationStatus';
+import { useKeyBackupInfo, useKeyBackupStatusChange } from '../../hooks/useKeyBackup';
+import { useAlive } from '../../hooks/useAlive';
+import { useSyncState } from '../../hooks/useSyncState';
+import { settingsRequestAtom } from '../../state/settingsRequest';
+import { serverStatusAtom } from '../../state/serverStatus';
+import { pickBanner } from '../../utils/kumaStatus';
+import {
+  dismissNudge,
+  NUDGE_COPY,
+  NUDGE_KEY_PREFIX,
+  nudgeFor,
+  NudgeRecord,
+  parseNudgeRecord,
+  shouldShowNudge,
+} from '../../utils/securityNudge';
+import { StatusStrip } from '../server-status/ServerStatusBanner';
+
+/** This device's backup connection: undefined until known, then true/false. */
+const useBackupActive = (crypto: CryptoApi): boolean | undefined => {
+  const alive = useAlive();
+  const [active, setActive] = useState<boolean>();
+  useEffect(() => {
+    crypto.getActiveSessionBackupVersion().then((v) => {
+      if (alive()) setActive(typeof v === 'string');
+    });
+  }, [crypto, alive]);
+  useKeyBackupStatusChange(useCallback((enabled: boolean) => setActive(enabled), []));
+  return active;
+};
+
+const readRecord = (key: string): NudgeRecord => {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem(key);
+  } catch {
+    /* storage unavailable */
+  }
+  const record = parseNudgeRecord(raw, Date.now());
+  if (!raw) {
+    try {
+      localStorage.setItem(key, JSON.stringify(record));
+    } catch {
+      /* best effort */
+    }
+  }
+  return record;
+};
+
+function SecurityBannerFor({ crypto }: { crypto: CryptoApi }) {
+  const mx = useMatrixClient();
+  const deviceId = mx.getDeviceId() ?? undefined;
+  const crossSigning = useCrossSigningActive();
+  const status = useDeviceVerificationStatus(crypto, mx.getSafeUserId(), deviceId);
+  const backupInfo = useKeyBackupInfo(crypto);
+  const backupActive = useBackupActive(crypto);
+  const { status: serverStatus, syncLost } = useAtomValue(serverStatusAtom);
+  const requestSettings = useSetAtom(settingsRequestAtom);
+  // Not urgent: wait until sync has settled (two SYNCING in a row), so it
+  // never stacks under the "Connecting…" strip at startup.
+  const [settled, setSettled] = useState(false);
+  useSyncState(
+    mx,
+    useCallback((state: SyncState | null, prev?: SyncState | null) => {
+      setSettled(state === SyncState.Syncing && prev === SyncState.Syncing);
+    }, []),
+  );
+
+  const key = `${NUDGE_KEY_PREFIX}${deviceId ?? 'unknown'}`;
+  const [record, setRecord] = useState(() => readRecord(key));
+
+  let deviceVerified: boolean | undefined;
+  if (status === VerificationStatus.Verified) deviceVerified = true;
+  else if (status === VerificationStatus.Unverified) deviceVerified = false;
+  const kind = nudgeFor({
+    crossSigning,
+    deviceVerified,
+    backupOnServer: backupInfo === undefined ? undefined : backupInfo !== null,
+    backupActive,
+  });
+
+  // One strip at a time: outages, maintenance and a lost connection win.
+  const otherStrip = syncLost || !!pickBanner(serverStatus, { syncLost, where: 'client' });
+  if (!settled || !deviceId || !kind || otherStrip || !shouldShowNudge(kind, record, Date.now()))
+    return null;
+
+  const copy = NUDGE_COPY[kind];
+  const dismiss = () => {
+    const next = dismissNudge(kind, record, Date.now());
+    try {
+      localStorage.setItem(key, JSON.stringify(next));
+    } catch {
+      /* dismissed for this session only */
+    }
+    setRecord(next);
+  };
+  return (
+    <StatusStrip
+      banner={{ key: kind, tone: 'Primary', text: copy.text, dismissable: true }}
+      icon={Icons.ShieldUser}
+      action={{ label: copy.action, onClick: () => requestSettings('devices') }}
+      dismissLabel="Not now"
+      onDismiss={dismiss}
+    />
+  );
+}
+
+/**
+ * [Gitea #110, #123] The device-security nudge: verify this device, connect
+ * it to the key backup, or set up key backup. See utils/securityNudge.ts.
+ */
+function SecurityBannerInner() {
+  const mx = useMatrixClient();
+  const crypto = mx.getCrypto();
+  if (!crypto) return null;
+  return <SecurityBannerFor crypto={crypto} />;
+}
+
+// A nudge must never take the app down: any error just hides it.
+export function SecurityBanner() {
+  return (
+    <ErrorBoundary fallback={null}>
+      <SecurityBannerInner />
+    </ErrorBoundary>
+  );
+}

src/app/features/server-status/ServerStatusBanner.tsx

@@ -22,7 +22,7 @@ const readDismissed = (): string[] => {
   }
 };
 
-const bannerIcon = (b: StatusBanner): IconSrc => {
+const bannerIcon = (b: StripContent): IconSrc => {
   if (b.kind === 'maintenance') return Icons.Setting;
   if (b.tone === 'Primary') return Icons.Info;
   return Icons.Warning;
@@ -32,12 +32,28 @@ const bannerIcon = (b: StatusBanner): IconSrc => {
  * [Gitea #124] One status strip, in the same slot and style as the sync and
  * clock banners. Presentational: the caller picks the banner.
  */
+export type StripContent = Pick<
+  StatusBanner,
+  'key' | 'tone' | 'text' | 'detail' | 'dismissable'
+> & {
+  kind?: StatusBanner['kind'];
+};
+
 export function StatusStrip({
   banner,
   onDismiss,
+  icon,
+  action,
+  dismissLabel,
 }: {
-  banner: StatusBanner;
+  banner: StripContent;
   onDismiss?: () => void;
+  /** Overrides the icon picked from the banner's tone/kind. */
+  icon?: IconSrc;
+  /** A primary action button (e.g. "Verify"). */
+  action?: { label: string; onClick: () => void };
+  /** A text button instead of the ✕ for dismissing (e.g. "Not now"). */
+  dismissLabel?: string;
 }) {
   const [open, setOpen] = useState(false);
   const mobile = useScreenSizeContext() === ScreenSize.Mobile;
@@ -59,8 +75,8 @@ export function StatusStrip({
           gap="200"
           style={{ minHeight: config.size.X300 }}
         >
-          <Icon size="100" src={bannerIcon(banner)} />
+          <Icon size="100" src={icon ?? bannerIcon(banner)} />
-          <Text size="L400" truncate={mobile && !open} style={{ minWidth: 0 }}>
+          <Text size="L400" truncate={mobile && !!banner.detail && !open} style={{ minWidth: 0 }}>
             {banner.text}
           </Text>
           {banner.detail && (
@@ -78,7 +94,31 @@ export function StatusStrip({
               </Text>
             </Button>
           )}
-          {banner.dismissable && onDismiss && (
+          {action && (
+            <Button
+              size="300"
+              variant={banner.tone}
+              fill="Solid"
+              radii="300"
+              onClick={action.onClick}
+              style={{ flexShrink: 0 }}
+            >
+              <Text size="B300">{action.label}</Text>
+            </Button>
+          )}
+          {banner.dismissable && onDismiss && dismissLabel && (
+            <Button
+              size="300"
+              variant={banner.tone}
+              fill="None"
+              radii="300"
+              onClick={onDismiss}
+              style={{ flexShrink: 0 }}
+            >
+              <Text size="B300">{dismissLabel}</Text>
+            </Button>
+          )}
+          {banner.dismissable && onDismiss && !dismissLabel && (
             <IconButton
               size="300"
               variant={banner.tone}

src/app/features/settings/general/General.tsx

@@ -112,7 +112,13 @@ import {
 import { chromeTranslationEngine } from '../../../utils/translation/chromeEngine';
 import { SequenceCardStyle } from '../styles.css';
 import { UpdateProgress, useTauriUpdater } from '../../../hooks/useTauriUpdater';
-import { describeUpdateError, manualDownloadUrl } from '../../../utils/updateErrors';
+import {
+  describeUpdateError,
+  isPackageManagedError,
+  manualDownloadUrl,
+  packageUpdateHelp,
+} from '../../../utils/updateErrors';
+import { copyToClipboard } from '../../../utils/dom';
 import { isTauri as isTauriEnv, invokeTauri, tauriInvoke } from '../../../hooks/useTauri';
 import { useKeychainMirrorStatus } from '../../../state/keychainMirror';
 import { isSafeGlobalToggleKey } from '../../../hooks/useCallHotkeys';
@@ -2794,12 +2800,76 @@ function updateProgressText(progress: UpdateProgress | undefined): string {
   return `Downloading update… ${pct}% (${formatMb(downloaded)} of ${formatMb(total)})${attempt}`;
 }
 
-function AppUpdates() {
+/**
-  const { isTauri, status, check, install } = useTauriUpdater();
+ * A Linux package install is updated with its package manager (the in-app
-  if (!isTauri) return null;
+ * updater can't write to /usr/bin): the command, Copy and a download link.
+ */
+function PackageUpdate({ help }: { help: NonNullable<ReturnType<typeof packageUpdateHelp>> }) {
+  const [copied, setCopied] = useState<'no' | 'yes' | 'failed'>('no');
+  const copy = () => {
+    const text = help.command ?? '';
+    if (!navigator.clipboard) {
+      copyToClipboard(text);
+      setCopied('yes');
+      return;
+    }
+    navigator.clipboard.writeText(text).then(
+      () => setCopied('yes'),
+      () => setCopied('failed'),
+    );
+  };
+  let copyLabel = 'Copy command';
+  if (copied === 'yes') copyLabel = 'Copied';
+  else if (copied === 'failed') copyLabel = 'Copy failed: select it above';
+  return (
+    <Box direction="Column" gap="200">
+      <Text size="T200">
+        Lotus Chat was installed as a system package, so update it the same way
+        {help.command ? ' (your chats and settings are kept):' : '.'}
+      </Text>
+      {help.command && (
+        <Text
+          size="T200"
+          style={{ fontFamily: 'monospace', wordBreak: 'break-all', userSelect: 'all' }}
+        >
+          {help.command}
+        </Text>
+      )}
+      <Box gap="200" wrap="Wrap">
+        {help.command && (
+          <Button size="300" radii="300" variant="Secondary" onClick={copy}>
+            <Text size="B300">{copyLabel}</Text>
+          </Button>
+        )}
+        <Button
+          size="300"
+          radii="300"
+          variant="Secondary"
+          fill="None"
+          outlined
+          onClick={() => window.open(help.url, '_blank')}
+        >
+          <Text size="B300">{help.download}</Text>
+        </Button>
+      </Box>
+    </Box>
+  );
+}
 
-  const description =
+function AppUpdates() {
-    status.state === 'checking'
+  const { isTauri, status, check, install, installKind } = useTauriUpdater();
+  if (!isTauri) return null;
+  const packageHelp = packageUpdateHelp(installKind);
+  const packageUpdate =
+    !!packageHelp &&
+    (status.state === 'available' ||
+      (status.state === 'error' && isPackageManagedError(status.message)));
+
+  const description = packageUpdate
+    ? status.state === 'available'
+      ? `Update available: v${status.version}`
+      : 'An update is available.'
+    : status.state === 'checking'
       ? 'Checking for updates...'
       : status.state === 'up-to-date'
         ? 'Lotus Chat is up to date.'
@@ -2816,8 +2886,7 @@ function AppUpdates() {
     else check();
   };
 
-  const after =
+  const after = packageUpdate ? undefined : status.state === 'available' ? (
-    status.state === 'available' ? (
     <Button size="300" radii="300" onClick={() => install()}>
       <Text size="B300">Install &amp; Restart</Text>
     </Button>
@@ -2852,7 +2921,8 @@ function AppUpdates() {
       <Text size="L400">App Updates</Text>
       <SequenceCard className={SequenceCardStyle} variant="SurfaceVariant" direction="Column">
         <SettingTile title="Check for Updates" description={description} after={after} />
-        {status.state === 'error' && (
+        {packageUpdate && packageHelp && <PackageUpdate help={packageHelp} />}
+        {status.state === 'error' && !packageUpdate && (
           <Text size="T200" priority="300" style={{ wordBreak: 'break-word' }}>
             Details: {status.message}
           </Text>

src/app/hooks/useTauriUpdater.ts

@@ -1,7 +1,7 @@
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
 import { atom, useAtom, useSetAtom } from 'jotai';
 import { useTauriEvent } from './useTauri';
-import { UpdatePhase, parseUpdateError } from '../utils/updateErrors';
+import { InstallKind, UpdatePhase, parseUpdateError, toInstallKind } from '../utils/updateErrors';
 
 type TauriInternals = { invoke: (cmd: string, args?: Record<string, unknown>) => Promise<unknown> };
 const tauriInvoke = (): TauriInternals['invoke'] | undefined =>
@@ -36,6 +36,11 @@ export type UpdateFailure = { phase: UpdatePhase; message: string };
 // mid-request by the resolve/reject below, so nothing gets stuck.
 const updateStatusAtom = atom<UpdateStatus>({ state: 'idle' });
 
+// How this install gets updated; asked once. A desktop build without the
+// command (older than it) rejects the call: keep the old in-app behaviour.
+const installKindAtom = atom<InstallKind | undefined>(undefined);
+let installKindRequested = false;
+
 /**
  * Mirror native download progress into the status. Mounted once (in
  * TauriUpdateFeature) so the listener isn't duplicated per consumer.
@@ -50,6 +55,16 @@ export function useTauriUpdateProgress(): void {
 export function useTauriUpdater() {
   const isTauri = !!tauriInvoke();
   const [status, setStatus] = useAtom(updateStatusAtom);
+  const [installKind, setInstallKind] = useAtom(installKindAtom);
+
+  useEffect(() => {
+    const invoke = tauriInvoke();
+    if (!invoke || installKindRequested) return;
+    installKindRequested = true;
+    invoke('update_install_kind')
+      .then((kind) => setInstallKind(toInstallKind(kind)))
+      .catch(() => setInstallKind('in-app'));
+  }, [setInstallKind]);
 
   const check = useCallback(async () => {
     const invoke = tauriInvoke();
@@ -89,5 +104,5 @@ export function useTauriUpdater() {
     }
   }, [setStatus]);
 
-  return { isTauri, status, check, install };
+  return { isTauri, status, check, install, installKind: installKind ?? 'in-app' };
 }

src/app/pages/client/ClientNonUIFeatures.tsx

@@ -69,6 +69,7 @@ import { dismissToastAtom, toastQueueAtom } from '../../state/toast';
 import { useReminders } from '../../hooks/useReminders';
 import { getRoomRetentionMs, isExpired } from '../../utils/retention';
 import { useTauriUpdateProgress, useTauriUpdater } from '../../hooks/useTauriUpdater';
+import { settingsRequestAtom } from '../../state/settingsRequest';
 import { isNetworkUpdateError } from '../../utils/updateErrors';
 import { invokeTauri, isTauri as isTauriApp, useTauriEvent } from '../../hooks/useTauri';
 import { CloseBehaviorPrompt } from '../../components/CloseBehaviorPrompt';
@@ -913,7 +914,8 @@ const UPDATE_PROGRESS_TOAST = 'tauri-update-progress';
 const UPDATE_FAILED_TOAST = 'tauri-update-failed';
 
 function TauriUpdateFeature() {
-  const { isTauri, status, check, install } = useTauriUpdater();
+  const { isTauri, status, check, install, installKind } = useTauriUpdater();
+  const requestSettings = useSetAtom(settingsRequestAtom);
   useTauriUpdateProgress();
   const setToast = useSetAtom(toastQueueAtom);
   const dismissToast = useSetAtom(dismissToastAtom);
@@ -972,18 +974,24 @@ function TauriUpdateFeature() {
     if (status.state !== 'available') return;
     if (firedRef.current === status.version) return;
     firedRef.current = status.version;
+    // A Linux package install can't be updated in place: point at the
+    // package-manager command in Settings instead of an install that fails.
+    const viaPackage = installKind !== 'in-app';
     setToast({
       id: `tauri-update-${status.version}`,
       displayName: '⬆ Update Available',
-      body: `Lotus Chat ${status.version} is ready. Click to install and restart.`,
+      body: viaPackage
+        ? `Lotus Chat ${status.version} is available. Click for the command to update it with your package manager.`
+        : `Lotus Chat ${status.version} is ready. Click to install and restart.`,
       roomName: 'System',
       roomId: '',
       onClick: () => {
-        installFromToast();
+        if (viaPackage) requestSettings('general');
+        else installFromToast();
       },
       sticky: true,
     });
-  }, [status, setToast, installFromToast]);
+  }, [status, setToast, installFromToast, installKind, requestSettings]);
 
   // [cinny-desktop #6] Mirror a pending update into the tray ("Restart to
   // update" + tooltip) so a dismissed toast isn't the only reminder. Kept while

src/app/pages/client/ClientRoot.tsx

@@ -48,6 +48,7 @@ import {
   ServerStatusBanner,
   ServerStatusFeature,
 } from '../../features/server-status/ServerStatusBanner';
+import { SecurityBanner } from '../../features/security-nudge/SecurityBanner';
 import { AuthMetadataProvider } from '../../hooks/useAuthMetadata';
 import { getFallbackSession, removeFallbackSession } from '../../state/sessions';
 import { pushSessionToSW } from '../../../sw-session';
@@ -313,6 +314,8 @@ export function ClientRoot({ children }: ClientRootProps) {
           <ClientRootLoading />
         ) : (
           <MatrixClientProvider value={mx}>
+            {/* [Gitea #110/#123] Needs the client context (its hooks read it). */}
+            {!syncError && <SecurityBanner />}
             <ServerConfigsLoader>
               {(serverConfigs) => (
                 <CapabilitiesProvider value={serverConfigs.capabilities ?? {}}>

src/app/state/plaintextCaches.ts

@@ -8,6 +8,7 @@ import { clearNavToActivePathStore } from './navToActivePath';
 import { DRAFT_MSG_KEY_PREFIX } from '../utils/draft';
 import { clearCallSession } from '../utils/callRejoin';
 import { clearOutbox } from '../utils/outbox';
+import { NUDGE_KEY_PREFIX } from '../utils/securityNudge';
 
 /**
  * [Gitea #41] Wipe every persisted composer draft (`draft-msg-<roomId>`). Drafts
@@ -77,7 +78,11 @@ const clearStatusMessage = (): void => {
     return;
   }
   keys.forEach((key) => {
-    if (key.startsWith('lotus-status-msg-') || key.startsWith('lotus-status-expiry-')) {
+    if (
+      key.startsWith('lotus-status-msg-') ||
+      key.startsWith('lotus-status-expiry-') ||
+      key.startsWith(NUDGE_KEY_PREFIX)
+    ) {
       try {
         localStorage.removeItem(key);
       } catch {

src/app/utils/securityNudge.test.ts

@@ -0,0 +1,81 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  dismissNudge,
+  NUDGE_GRACE_MS,
+  NUDGE_SNOOZE_MS,
+  nudgeFor,
+  parseNudgeRecord,
+  SecurityState,
+  shouldShowNudge,
+} from './securityNudge';
+
+const healthy: SecurityState = {
+  crossSigning: true,
+  deviceVerified: true,
+  backupOnServer: true,
+  backupActive: true,
+};
+
+test('the #123 table: which nudge for which state', () => {
+  // E: healthy → nothing, ever.
+  assert.equal(nudgeFor(healthy), undefined);
+  // B: cross-signing, this device unverified, backup on server → verify first.
+  assert.equal(nudgeFor({ ...healthy, deviceVerified: false }), 'verify-device');
+  // C: cross-signing, unverified, no backup → still verify first.
+  assert.equal(
+    nudgeFor({ ...healthy, deviceVerified: false, backupOnServer: false }),
+    'verify-device',
+  );
+  // D: verified, no backup → #110's set-up nudge.
+  assert.equal(nudgeFor({ ...healthy, backupOnServer: false }), 'setup-backup');
+  // #110 state 2: backup exists, this device not using it.
+  assert.equal(nudgeFor({ ...healthy, backupActive: false }), 'connect-backup');
+  // A: never set up cross-signing, no backup → set up (the flow does both).
+  assert.equal(
+    nudgeFor({
+      crossSigning: false,
+      deviceVerified: false,
+      backupOnServer: false,
+      backupActive: false,
+    }),
+    'setup-backup',
+  );
+});
+
+test('nothing while crypto is still loading (F)', () => {
+  assert.equal(nudgeFor({ ...healthy, deviceVerified: undefined }), undefined);
+  assert.equal(nudgeFor({ ...healthy, backupOnServer: undefined }), undefined);
+  assert.equal(nudgeFor({ ...healthy, backupActive: undefined }), undefined);
+  // Unknown backup connection doesn't hide a known "no backup at all".
+  assert.equal(
+    nudgeFor({ ...healthy, backupOnServer: false, backupActive: undefined }),
+    'setup-backup',
+  );
+});
+
+test('timing: 24 h grace, 7-day snooze, stop after 3 dismissals', () => {
+  const t0 = 1_700_000_000_000;
+  let record = parseNudgeRecord(null, t0);
+  assert.equal(shouldShowNudge('verify-device', record, t0), false, 'first launch');
+  assert.equal(shouldShowNudge('verify-device', record, t0 + NUDGE_GRACE_MS - 1), false);
+  let now = t0 + NUDGE_GRACE_MS;
+  assert.equal(shouldShowNudge('verify-device', record, now), true, 'after 24 h');
+  for (let i = 1; i <= 3; i += 1) {
+    record = dismissNudge('verify-device', record, now);
+    assert.equal(shouldShowNudge('verify-device', record, now), false, `snoozed after #${i}`);
+    now += NUDGE_SNOOZE_MS;
+    assert.equal(shouldShowNudge('verify-device', record, now), i < 3, `after 7 days (#${i})`);
+  }
+  // Dismissing one nudge doesn't hide another.
+  assert.equal(shouldShowNudge('setup-backup', record, now), true);
+});
+
+test('stored record: round trip, and garbage starts a fresh grace period', () => {
+  const t0 = 1_700_000_000_000;
+  const r = dismissNudge('setup-backup', parseNudgeRecord(null, t0 - 5), t0);
+  assert.deepEqual(parseNudgeRecord(JSON.stringify(r), t0 + 1), r);
+  for (const bad of ['{', 'null', '"x"', '{"firstSeen":"yesterday"}', '{"firstSeen":1}']) {
+    assert.deepEqual(parseNudgeRecord(bad, t0), { firstSeen: t0, dismissals: {} }, bad);
+  }
+});

src/app/utils/securityNudge.ts

@@ -0,0 +1,94 @@
+/**
+ * [Gitea #110, #123] One "security" nudge for this device, in priority order:
+ *
+ * - verify-device: the account has cross-signing but THIS device isn't signed.
+ *   It can't unlock backed-up history and shows as untrusted to others.
+ *   Verifying with the recovery key also connects the backup, so it comes first.
+ * - connect-backup: a key backup exists on the server but this device isn't
+ *   backing up to it (`getActiveSessionBackupVersion()` null).
+ * - setup-backup: no key backup at all (includes accounts that never set up
+ *   cross-signing: the setup flow does both).
+ *
+ * Anything not yet known (crypto still loading) → no nudge. Timing: not in
+ * the first 24 h on a device (onboarding), "Not now" snoozes 7 days, three
+ * dismissals of a nudge stop it for good; a healthy device never sees one.
+ */
+
+export type NudgeKind = 'verify-device' | 'connect-backup' | 'setup-backup';
+
+export type SecurityState = {
+  /** m.cross_signing.master account data present. */
+  crossSigning: boolean;
+  /** This device cross-signing-verified; undefined while crypto isn't ready. */
+  deviceVerified: boolean | undefined;
+  /** A key backup version on the server; undefined while loading. */
+  backupOnServer: boolean | undefined;
+  /** This device is backing up to it; undefined while loading. */
+  backupActive: boolean | undefined;
+};
+
+export const nudgeFor = (s: SecurityState): NudgeKind | undefined => {
+  if (s.crossSigning) {
+    if (s.deviceVerified === undefined) return undefined;
+    if (!s.deviceVerified) return 'verify-device';
+  }
+  if (s.backupOnServer === undefined) return undefined;
+  if (!s.backupOnServer) return 'setup-backup';
+  if (s.backupActive === undefined) return undefined;
+  return s.backupActive ? undefined : 'connect-backup';
+};
+
+export const NUDGE_GRACE_MS = 24 * 60 * 60 * 1000;
+export const NUDGE_SNOOZE_MS = 7 * 24 * 60 * 60 * 1000;
+export const NUDGE_MAX_DISMISSALS = 3;
+
+export type NudgeRecord = {
+  /** When this device was first seen by the nudge (ms). */
+  firstSeen: number;
+  dismissals: Partial<Record<NudgeKind, { count: number; last: number }>>;
+};
+
+export const shouldShowNudge = (kind: NudgeKind, record: NudgeRecord, now: number): boolean => {
+  if (now - record.firstSeen < NUDGE_GRACE_MS) return false;
+  const d = record.dismissals[kind];
+  if (!d) return true;
+  return d.count < NUDGE_MAX_DISMISSALS && now - d.last >= NUDGE_SNOOZE_MS;
+};
+
+export const dismissNudge = (kind: NudgeKind, record: NudgeRecord, now: number): NudgeRecord => ({
+  ...record,
+  dismissals: {
+    ...record.dismissals,
+    [kind]: { count: (record.dismissals[kind]?.count ?? 0) + 1, last: now },
+  },
+});
+
+export const NUDGE_KEY_PREFIX = 'lotus-security-nudge-';
+
+/** Parse a stored record; anything unexpected starts a fresh one (grace period from now). */
+export const parseNudgeRecord = (raw: string | null, now: number): NudgeRecord => {
+  try {
+    const v = JSON.parse(raw ?? '');
+    if (v && typeof v.firstSeen === 'number' && v.dismissals && typeof v.dismissals === 'object') {
+      return { firstSeen: v.firstSeen, dismissals: v.dismissals };
+    }
+  } catch {
+    /* fresh record below */
+  }
+  return { firstSeen: now, dismissals: {} };
+};
+
+export const NUDGE_COPY: Record<NudgeKind, { text: string; action: string }> = {
+  'verify-device': {
+    text: 'Verify this device so you can read your older encrypted messages and others see it as trusted.',
+    action: 'Verify',
+  },
+  'connect-backup': {
+    text: "This device isn't using your key backup yet. Connect it so your encrypted messages stay readable if you lose it.",
+    action: 'Connect',
+  },
+  'setup-backup': {
+    text: "Your encryption keys aren't backed up. Set up key backup so you don't lose your encrypted messages if you log out or lose this device.",
+    action: 'Set up',
+  },
+};

src/app/utils/updateErrors.test.ts

@@ -55,3 +55,36 @@ test('manual download link: Windows gets the installer, others the release page'
   );
   assert.equal(manualDownloadUrl('Mozilla/5.0 (X11; Linux x86_64)'), MANUAL_DOWNLOAD_URL.other);
 });
+
+test('install kinds: anything unknown keeps the in-app updater', async () => {
+  const { toInstallKind } = await import('./updateErrors');
+  assert.equal(toInstallKind('pacman'), 'pacman');
+  assert.equal(toInstallKind('deb'), 'deb');
+  assert.equal(toInstallKind('manual'), 'manual');
+  assert.equal(toInstallKind('in-app'), 'in-app');
+  assert.equal(toInstallKind(undefined), 'in-app', 'older desktop build without the command');
+  assert.equal(toInstallKind('rpm'), 'in-app');
+});
+
+test('package installs get their package manager’s command, not an Install button', async () => {
+  const { packageUpdateHelp, isPackageManagedError } = await import('./updateErrors');
+  const pacman = packageUpdateHelp('pacman')!;
+  // Not `pacman -U <url>`: that also wants `<url>.sig`, which we don't publish.
+  assert.equal(
+    pacman.command,
+    'curl -LO https://code.lotusguild.org/LotusGuild/cinny-desktop/releases/download/latest/LotusChat-x86_64.pkg.tar.zst && sudo pacman -U ./LotusChat-x86_64.pkg.tar.zst',
+  );
+  assert.match(pacman.url, /LotusChat-x86_64\.pkg\.tar\.zst$/);
+  const deb = packageUpdateHelp('deb')!;
+  assert.match(deb.command!, /sudo apt install \.\/LotusChat-x86_64\.deb$/);
+  assert.equal(packageUpdateHelp('manual')?.command, undefined);
+  assert.equal(packageUpdateHelp('in-app'), undefined);
+  assert.equal(
+    isPackageManagedError('package-managed (pacman): update Lotus Chat with your package manager'),
+    true,
+  );
+  assert.equal(
+    isPackageManagedError('Permission denied (os error 13) at path "/usr/bin/tauri_current_app"'),
+    false,
+  );
+});

src/app/utils/updateErrors.ts

@@ -47,3 +47,46 @@ export const describeUpdateError = (phase: UpdatePhase, message: string): string
   }
   return 'The update downloaded but couldn’t be installed. Download the installer yourself and run it; your chats and settings are kept.';
 };
+
+/**
+ * How this desktop install gets updated (cinny-desktop `update_install_kind`).
+ * Linux package installs can't be replaced in place by the in-app updater
+ * (it tried to write into /usr/bin: "Permission denied (os error 13)"), so
+ * they get their package manager's command instead of an Install button.
+ */
+export type InstallKind = 'in-app' | 'pacman' | 'deb' | 'manual';
+
+const RELEASE_DOWNLOAD =
+  'https://code.lotusguild.org/LotusGuild/cinny-desktop/releases/download/latest';
+
+export const toInstallKind = (value: unknown): InstallKind =>
+  value === 'pacman' || value === 'deb' || value === 'manual' ? value : 'in-app';
+
+export type PackageUpdateHelp = { command?: string; url: string; download: string };
+
+export const packageUpdateHelp = (kind: InstallKind): PackageUpdateHelp | undefined => {
+  if (kind === 'pacman') {
+    const url = `${RELEASE_DOWNLOAD}/LotusChat-x86_64.pkg.tar.zst`;
+    // Download first, then install the local file: `pacman -U <url>` also
+    // fetches `<url>.sig` and fails without it (we don't sign packages),
+    // while a local file falls under LocalFileSigLevel (signature optional).
+    return {
+      command: `curl -LO ${url} && sudo pacman -U ./LotusChat-x86_64.pkg.tar.zst`,
+      url,
+      download: 'Download package',
+    };
+  }
+  if (kind === 'deb') {
+    const url = `${RELEASE_DOWNLOAD}/LotusChat-x86_64.deb`;
+    return {
+      command: `curl -LO ${url} && sudo apt install ./LotusChat-x86_64.deb`,
+      url,
+      download: 'Download package',
+    };
+  }
+  if (kind === 'manual') return { url: MANUAL_DOWNLOAD_URL.other, download: 'Open downloads' };
+  return undefined;
+};
+
+/** The native side refuses an in-app install on a package install. */
+export const isPackageManagedError = (message: string): boolean => /package-managed/.test(message);