From 1faa9bc7959a5ec9c41edcf05391fa2ec438ad66 Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Fri, 25 Sep 2026 23:32:00 +0200
Subject: [PATCH] docs: point the Lite bundle README at HTTPS and the update
 action

A live install of the Stalwart bundle on 1.0 and 0.16.23 showed four
gaps in the README it carries:

- It didn't say where the web admin's update action is. It is under
  **Actions > Update applications** on both versions.
- On a plain `http://` address other than `localhost` the browser has
  no Web Crypto API, so the PKCE sign-in can't run and the webmail
  falls back to a password session for the tab: "Remember me" does
  nothing and single sign-on can't work. It now asks for HTTPS.
- The local build command left out `--in-place`, without which the
  build refuses to run outside CI.
- The closing list named single sign-on as missing from this bundle,
  although the README's own section above describes how it works here.
---
 lib/__tests__/lite-scripts.test.ts | 11 +++++++++++
 scripts/lite/lib.mjs               | 18 ++++++++++++------
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/lib/__tests__/lite-scripts.test.ts b/lib/__tests__/lite-scripts.test.ts
index 2ad8b907d..7f600ce35 100644
--- a/lib/__tests__/lite-scripts.test.ts
+++ b/lib/__tests__/lite-scripts.test.ts
@@ -614,6 +614,17 @@ describe('Stalwart target: the entry document', () => {
     expect(readme).toMatch(/On every version, a restart after the cached copy\s+has expired/);
     expect(readme).toMatch(/check that `resourceUrl` downloads before running\s+`UpdateApps`/);
   });
+
+  it('names the web admin action, asks for HTTPS and keeps single sign-on off the missing list', () => {
+    const readme = buildStalwartReadme({ version: '1.10.0', commit: 'abc1234', locales: ['en'], buildId: 'b' });
+    expect(readme).toContain('**Actions > Update applications**');
+    // Without a secure context there is no crypto.subtle for PKCE, so the
+    // sign-in falls back to a tab-scoped password session.
+    expect(readme).toMatch(/Serve Stalwart over HTTPS\./);
+    // Outside CI the build refuses to delete files unless told the tree is throwaway.
+    expect(readme).toContain('npm run build:lite -- --in-place --target=stalwart');
+    expect(readme).not.toContain('OAuth/SSO via an external identity provider');
+  });
 });
 
 describe('Stalwart target: zip and emulator', () => {
diff --git a/scripts/lite/lib.mjs b/scripts/lite/lib.mjs
index a1265ab5b..8d5bd002e 100644
--- a/scripts/lite/lib.mjs
+++ b/scripts/lite/lib.mjs
@@ -1322,7 +1322,7 @@ it) and \`actionUpdateApps\`. Any of these is equivalent:
 
 - Web admin: **Settings > Web Applications > Create**, description
   \`Bulwark Webmail\`, resource URL \`${url}\`, URL prefix \`/webmail\`; then run
-  the update-applications action (or restart Stalwart).
+  **Actions > Update applications** (or restart Stalwart).
 - CLI:
 
   \`\`\`bash
@@ -1397,6 +1397,11 @@ Passwords (and TOTP codes) go to Stalwart's \`/api/auth\` and are exchanged at
 origin. "Remember me" keeps the refresh token in localStorage, otherwise it
 lives with the tab.
 
+Serve Stalwart over HTTPS. On a plain \`http://\` address other than
+\`localhost\`, browsers withhold the Web Crypto API this sign-in needs, so the
+webmail falls back to a password sign-in that lasts only as long as the tab:
+"Remember me" has no effect and single sign-on does not work.
+
 The OAuth client id is the Application's \`oauthClientId\` (Stalwart writes it
 into index.html) or \`bulwark-webmail\` when that field is empty. If your
 server requires registered OAuth clients, register that client id with the
@@ -1435,8 +1440,8 @@ for every account.
 
 The bundle is read-only once Stalwart has unpacked it. To change the app
 name, turn "remember me" off or build any other variant, run the
-**Build Static Lite** workflow (or \`npm run build:lite -- --target=stalwart\`)
-with your settings, publish the resulting \`${STALWART_ZIP_NAME}\` at a URL
+**Build Static Lite** workflow (or, in a throwaway checkout,
+\`npm run build:lite -- --in-place --target=stalwart\`) with your settings, publish the resulting \`${STALWART_ZIP_NAME}\` at a URL
 you control, and use that URL as \`resourceUrl\`. \`config.json\` and
 \`policy.json\` inside the zip take the same keys as in the static-host build.
 
@@ -1451,9 +1456,10 @@ you control, and use that URL as \`resourceUrl\`. \`config.json\` and
 - \`manifest.json\` replaces \`manifest.webmanifest\` (Stalwart would serve the
   latter as \`application/octet-stream\`).
 
-Everything the static-host build leaves out (admin console, plugins,
-settings sync, OAuth/SSO via an external identity provider, web push, office
-editing, ICS subscriptions) is also missing here.
+Everything else the static-host build leaves out (admin console, plugins,
+settings sync, web push, office editing, ICS subscriptions) is also missing
+here. Single sign-on is the exception: it works in this bundle, as described
+above.
 `;
 }