Merge remote-tracking branch 'origin/main' into desktop-keychain

Merge pull request #30: Windows smoke test (#19)

.gitea/workflows/windows-smoke.yml

@@ -0,0 +1,136 @@
+# cinny-desktop #19: smoke-test the Windows app on the `windows` runner.
+#
+# Installs the NSIS bundle silently, starts the installed app with WebView2's
+# DevTools port open, and drives its real page with scripts/windows-smoke.mjs
+# (playwright-core over CDP): boots to the login screen, local server address,
+# microphone permission for the app and not for a foreign page, the call page's
+# own origin + isolation, the Credential Manager round trip. Features a build
+# doesn't have are reported "n/a".
+#
+# Run it from the Actions tab (workflow_dispatch):
+# - no `ref`: tests the published nightly installer (a couple of minutes);
+# - `ref` = a branch (e.g. a PR branch): builds that branch, then tests it.
+name: Windows smoke
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Branch to build and test (empty: test the published nightly)'
+        required: false
+        default: ''
+
+env:
+  GITEA_URL: ${{ github.server_url }}
+  REPO: ${{ github.repository }}
+
+jobs:
+  smoke:
+    runs-on: windows
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
+      - name: Download the published nightly installer
+        if: ${{ inputs.ref == '' }}
+        shell: powershell
+        run: |
+          New-Item -ItemType Directory -Force -Path smoke-installer | Out-Null
+          Invoke-WebRequest -Uri "$env:GITEA_URL/$env:REPO/releases/download/latest/LotusChat-x86_64-setup.exe" -OutFile smoke-installer\setup.exe
+          Get-Item smoke-installer\setup.exe | Select-Object Name, Length
+
+      # A second actions/checkout in one job trips over the host runner's
+      # action cache on Windows ("Access is denied" on its pack files), so
+      # fetch the branch into a worktree with plain git instead.
+      - name: Check out the branch to build
+        if: ${{ inputs.ref != '' }}
+        shell: powershell
+        run: |
+          git fetch --depth=1 origin "${{ inputs.ref }}"
+          git worktree add --force build-src FETCH_HEAD
+          git -C build-src log --oneline -1
+
+      - name: Build the branch
+        if: ${{ inputs.ref != '' }}
+        shell: powershell
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ''
+          NODE_OPTIONS: '--max_old_space_size=4096'
+          CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
+          CARGO_HTTP_MULTIPLEXING: 'false'
+          CARGO_NET_RETRY: '5'
+        run: |
+          cd build-src
+          git submodule update --init --depth=1
+          cd cinny; npm ci; cd ..
+          node scripts/sync-web-config.mjs
+          npm ci
+          $env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH"
+          $toolchain = Get-ChildItem "$env:USERPROFILE\.rustup\toolchains" -Directory -ErrorAction SilentlyContinue |
+                       Where-Object { $_.Name -match 'stable' } | Select-Object -First 1
+          if ($toolchain) { $env:PATH = "$($toolchain.FullName)\bin;$env:PATH" }
+          npm run tauri -- build --bundles nsis
+          New-Item -ItemType Directory -Force -Path ..\smoke-installer | Out-Null
+          $exe = Get-ChildItem src-tauri\target\release\bundle\nsis\*-setup.exe | Select-Object -First 1
+          Copy-Item $exe.FullName ..\smoke-installer\setup.exe
+
+      - name: Install silently
+        shell: powershell
+        run: |
+          Get-Process cinny -ErrorAction SilentlyContinue | Stop-Process -Force
+          Start-Process smoke-installer\setup.exe -ArgumentList '/S' -Wait
+          $app = Join-Path $env:LOCALAPPDATA 'Lotus Chat\cinny.exe'
+          if (-not (Test-Path $app)) { Write-Error "not installed at $app"; exit 1 }
+          (Get-Item $app).VersionInfo | Select-Object ProductVersion, FileVersion
+
+      - name: Start the app and smoke test it
+        shell: powershell
+        run: |
+          New-Item -ItemType Directory -Force -Path smoke-deps | Out-Null
+          Push-Location smoke-deps
+          npm init -y | Out-Null
+          npm install --no-audit --no-fund playwright-core@1 | Out-Null
+          Pop-Location
+          Copy-Item scripts\windows-smoke.mjs smoke-deps\windows-smoke.mjs
+          # Same step as the test: a process started in an earlier step may be
+          # cleaned up when that step ends.
+          # The app sets its own WebView2 arguments, so WebView2's env var doesn't
+          # apply; the app opens the DevTools port itself when asked (#19).
+          $env:LOTUS_WEBVIEW2_DEBUG_PORT = '9222'
+          $app = Join-Path $env:LOCALAPPDATA 'Lotus Chat\cinny.exe'
+          Start-Process $app
+          Start-Sleep -Seconds 15
+          Write-Host "--- processes"
+          Get-Process cinny, msedgewebview2 -ErrorAction SilentlyContinue | Select-Object Name, Id, SessionId | Format-Table | Out-String | Write-Host
+          Write-Host "--- listening ports 9222/44548"
+          Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue | Where-Object { $_.LocalPort -in 9222, 44548 } | Select-Object LocalAddress, LocalPort, OwningProcess | Format-Table | Out-String | Write-Host
+          Write-Host "--- WebView2 runtime"
+          Get-ItemProperty 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}' -ErrorAction SilentlyContinue | Select-Object pv | Out-String | Write-Host
+          Write-Host "--- whoami: $(whoami)"
+          Write-Host "--- webview2 command lines"
+          Get-CimInstance Win32_Process -Filter "Name='msedgewebview2.exe'" | Select-Object -First 2 | ForEach-Object { Write-Host $_.CommandLine.Substring(0, [Math]::Min(600, $_.CommandLine.Length)) }
+          Write-Host "--- netstat"
+          netstat -ano | Select-String "LISTENING" | Select-String ":9222 |:44548 " | ForEach-Object { Write-Host $_ }
+          Write-Host "--- http probes"
+          try { (Invoke-WebRequest -UseBasicParsing http://127.0.0.1:9222/json/version -TimeoutSec 5).Content | Write-Host } catch { Write-Host "9222: $($_.Exception.Message)" }
+          try { (Invoke-WebRequest -UseBasicParsing http://localhost:44548/ -TimeoutSec 5).StatusCode | Write-Host } catch { Write-Host "44548: $($_.Exception.Message)" }
+          node smoke-deps\windows-smoke.mjs smoke-out
+
+      - name: Stop the app
+        if: ${{ always() }}
+        shell: powershell
+        run: |
+          Get-Process cinny -ErrorAction SilentlyContinue | Stop-Process -Force
+          if (Test-Path smoke-out\results.json) { Get-Content smoke-out\results.json }
+
+      - name: Upload results and screenshots
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: windows-smoke
+          path: smoke-out

config.json

@@ -24,5 +24,16 @@
     "basename": "/"
   },
   "gifApiKey": "",
-  "webAppUrl": "https://chat.lotusguild.org"
+  "webAppUrl": "https://chat.lotusguild.org",
+  "statusPages": {
+    "matrix.lotusguild.org": {
+      "url": "https://isitup.lotusguild.org",
+      "slug": "matrix",
+      "groups": {
+        "homeserver": "Homeserver",
+        "calls": "Voice calls",
+        "login": "Login"
+      }
+    }
+  }
 }

scripts/windows-smoke.mjs

@@ -0,0 +1,175 @@
+// cinny-desktop #19: Windows smoke test against the INSTALLED app.
+//
+// The app is started with WebView2's DevTools port open
+// (WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222) and this
+// script drives its real page over CDP with playwright-core. No login: every
+// check runs on the login screen or through the app's own Tauri commands.
+//
+//   node scripts/windows-smoke.mjs <outDir>
+//
+// Checks whose feature isn't in the build under test are reported "n/a"
+// instead of failing, so the same script runs on main and on PR branches.
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { chromium } from 'playwright-core';
+
+const OUT = process.argv[2] || 'smoke-out';
+mkdirSync(OUT, { recursive: true });
+const APP = 'http://localhost:44548';
+const results = [];
+const record = (name, status, detail = '') => {
+  results.push({ name, status, detail });
+  console.log(`${status.toUpperCase().padEnd(4)} ${name}${detail ? ` — ${detail}` : ''}`);
+};
+
+const until = async (fn, ms, step = 500) => {
+  const end = Date.now() + ms;
+  for (;;) {
+    let v;
+    try {
+      v = await fn();
+    } catch {
+      v = undefined;
+    }
+    if (v || Date.now() > end) return v;
+    await new Promise((r) => setTimeout(r, step));
+  }
+};
+
+// 1. Connect to the running app's WebView2.
+const browser = await until(() => chromium.connectOverCDP('http://127.0.0.1:9222'), 60_000, 1000);
+if (!browser) {
+  record('connect to the app over CDP', 'fail', 'no DevTools endpoint on :9222');
+  writeFileSync(`${OUT}/results.json`, JSON.stringify(results, null, 2));
+  process.exit(1);
+}
+const page = await until(
+  () => browser.contexts().flatMap((c) => c.pages()).find((p) => p.url().startsWith(APP)),
+  60_000,
+);
+if (!page) {
+  record('app page found', 'fail', browser.contexts().flatMap((c) => c.pages()).map((p) => p.url()).join(', '));
+  process.exit(1);
+}
+record('app page found', 'pass', page.url());
+
+// 2. Boots to the login screen.
+const booted = await until(async () => /Login|Homeserver/.test(await page.locator('body').innerText()), 60_000);
+record('boots to the login screen', booted ? 'pass' : 'fail');
+await page.screenshot({ path: `${OUT}/01-login.png` });
+
+// 3. The local server's address (cinny #43 binds 127.0.0.1 explicitly).
+try {
+  const listen = execSync(
+    'powershell -NoProfile -Command "(Get-NetTCPConnection -LocalPort 44548 -State Listen).LocalAddress -join \',\'"',
+  )
+    .toString()
+    .trim();
+  record('local server listening', listen ? 'pass' : 'fail', listen);
+} catch (e) {
+  record('local server listening', 'fail', String(e).slice(0, 120));
+}
+
+const cfg = await page.evaluate(() => fetch('/config.json').then((r) => r.json()));
+
+// 4. Microphone for the app itself (WebView2 PermissionRequested handler, #22).
+const appMic = await page.evaluate(async () => {
+  try {
+    const s = await navigator.mediaDevices.getUserMedia({ audio: true });
+    s.getTracks().forEach((t) => t.stop());
+    return 'ok';
+  } catch (e) {
+    return `${e.name}: ${e.message}`;
+  }
+});
+record('microphone allowed for the app', appMic === 'ok' ? 'pass' : 'fail', appMic);
+
+// 5. Call page on its own origin, isolated from the app (cinny #43 / #27).
+if (cfg.desktopCallOrigin) {
+  const src = `${cfg.desktopCallOrigin}/public/element-call/index.html`;
+  await page.evaluate((s) => {
+    const f = document.createElement('iframe');
+    f.id = 'smoke-call';
+    f.src = s;
+    f.allow = 'microphone; camera; display-capture; autoplay; clipboard-write;';
+    f.sandbox = 'allow-forms allow-scripts allow-same-origin allow-popups allow-modals allow-downloads';
+    document.body.appendChild(f);
+  }, src);
+  const frame = await until(() => page.frames().find((f) => f.url().startsWith(src)), 30_000);
+  if (!frame) {
+    record('call page loads from its own origin', 'fail', 'frame did not load (CSP?)');
+  } else {
+    await frame.waitForLoadState('domcontentloaded').catch(() => undefined);
+    const iso = await frame.evaluate(async () => {
+      const r = { origin: location.origin };
+      try {
+        r.parentStorage = String(parent.localStorage.length);
+      } catch (e) {
+        r.parentStorage = e.name;
+      }
+      try {
+        const s = await navigator.mediaDevices.getUserMedia({ audio: true });
+        s.getTracks().forEach((t) => t.stop());
+        r.mic = 'ok';
+      } catch (e) {
+        r.mic = e.name;
+      }
+      return r;
+    });
+    record('call page loads from its own origin', 'pass', iso.origin);
+    record('call page cannot read the app storage', iso.parentStorage === 'SecurityError' ? 'pass' : 'fail', iso.parentStorage);
+    record('call page gets the microphone', iso.mic === 'ok' ? 'pass' : 'fail', iso.mic);
+  }
+} else {
+  record('call page on its own origin', 'n/a', 'desktopCallOrigin not set in this build');
+}
+
+// 6. OS keychain round trip (cinny #105, step 1).
+const kc = await page.evaluate(async () => {
+  const inv = window.__TAURI_INTERNALS__?.invoke;
+  if (!inv) return { error: 'no Tauri bridge' };
+  try {
+    const supported = await inv('secure_session_supported');
+    if (!supported) return { supported };
+    const tokens = { userId: '@smoke:ci.invalid', deviceId: 'SMOKE', accessToken: `smoke-${Date.now()}` };
+    const before = await inv('secure_session_get');
+    await inv('secure_session_set', { tokens });
+    const back = await inv('secure_session_get');
+    // Put back whatever was there (nothing, on a clean runner).
+    if (before) await inv('secure_session_set', { tokens: before });
+    else await inv('secure_session_clear');
+    const after = await inv('secure_session_get');
+    return { supported, roundTrip: back?.accessToken === tokens.accessToken, restored: JSON.stringify(after) === JSON.stringify(before ?? null) };
+  } catch (e) {
+    return { error: String(e).slice(0, 160) };
+  }
+});
+if (kc.error && /not found/i.test(kc.error)) record('keychain round trip', 'n/a', 'commands not in this build');
+else if (kc.error) record('keychain round trip', 'fail', kc.error);
+else if (!kc.supported) record('keychain round trip', 'fail', 'secure_session_supported = false on Windows');
+else record('keychain round trip', kc.roundTrip && kc.restored ? 'pass' : 'fail', JSON.stringify(kc));
+
+// 7. A foreign page loaded in the window must not get the microphone (#22).
+await page.goto('https://example.com/').catch(() => undefined);
+const foreignMic = await page.evaluate(async () => {
+  try {
+    const s = await navigator.mediaDevices.getUserMedia({ audio: true });
+    s.getTracks().forEach((t) => t.stop());
+    return 'ok';
+  } catch (e) {
+    return e.name;
+  }
+});
+record(
+  'microphone refused to a foreign page',
+  foreignMic === 'NotAllowedError' ? 'pass' : 'info',
+  `${foreignMic}${foreignMic === 'ok' ? ' (build without the #22 origin check)' : ''}`,
+);
+await page.goto(APP).catch(() => undefined);
+await page.screenshot({ path: `${OUT}/02-end.png` }).catch(() => undefined);
+
+writeFileSync(`${OUT}/results.json`, JSON.stringify(results, null, 2));
+await browser.close().catch(() => undefined);
+const failed = results.filter((r) => r.status === 'fail');
+console.log(`\n${results.filter((r) => r.status === 'pass').length} passed, ${failed.length} failed`);
+process.exit(failed.length ? 1 : 0);

src-tauri/Cargo.lock

@@ -498,6 +498,7 @@ checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
 name = "cinny"
 version = "4.12.2"
 dependencies = [
+ "keyring",
  "serde",
  "serde_json",
  "tauri",
@@ -2090,6 +2091,18 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "keyring"
+version = "3.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
+dependencies = [
+ "byteorder",
+ "log",
+ "windows-sys 0.60.2",
+ "zeroize",
+]
+
 [[package]]
 name = "kuchikiki"
 version = "0.8.8-speedreader"

src-tauri/Cargo.toml

@@ -38,6 +38,10 @@ tauri-plugin-single-instance = "2"
 tauri-plugin-autostart = "2" # P6-1 launch-on-login
 # Update retry backoff (already in the tree via tauri; adds only the timer).
 tokio = { version = "1", features = ["time"] }
+# cinny #105: login tokens in the OS keychain. Without a platform feature
+# the crate only has its in-memory mock store (used by the tests); Windows
+# turns on Credential Manager below.
+keyring = "3.6"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 # P6-1 desktop parity: screensaver inhibit (no-sleep in calls) + Unity launcher
@@ -50,6 +54,7 @@ zbus = "5"
 webkit2gtk = "2.0"
 
 [target.'cfg(target_os = "windows")'.dependencies]
+keyring = { version = "3.6", features = ["windows-native"] }
 webview2-com = "0.38"
 window-vibrancy = "0.6"
 windows = { version = "0.61", features = [

src-tauri/src/lib.rs

@@ -13,6 +13,7 @@ use tauri_plugin_opener::OpenerExt;
 
 pub mod gpu_workarounds;
 mod native;
+mod secure_session;
 
 /// Bring the main window to the foreground from the tray / a hidden /
 /// minimized state. Shared by the tray, single-instance, and deep-link paths.
@@ -952,6 +953,10 @@ pub fn run() {
             native::focus_assist::get_focus_assist,
             native::hotkeys::global_hotkeys_supported,
             native::hotkeys::set_global_hotkeys,
+            secure_session::secure_session_supported,
+            secure_session::secure_session_set,
+            secure_session::secure_session_get,
+            secure_session::secure_session_clear,
         ])
         .plugin(tauri_plugin_localhost::Builder::new(port).build())
         .plugin(
@@ -1128,9 +1133,9 @@ pub fn run() {
                 // Tauri's default WebView2 args (setting this overrides them) and
                 // appends the Chromium background-throttling disables. Windows-only
                 // in effect; harmless elsewhere. Does not block system sleep.
-                .additional_browser_args(
+                .additional_browser_args(&webview2_browser_args(
-                    "--disable-features=msWebOOUI,msPdfOOUI --disable-background-timer-throttling --disable-renderer-backgrounding --disable-backgrounding-occluded-windows",
+                    std::env::var("LOTUS_WEBVIEW2_DEBUG_PORT").ok().as_deref(),
-                )
+                ))
                 .on_page_load(move |window, payload| {
                     if matches!(payload.event(), PageLoadEvent::Finished) {
                         // Reveal only on the FIRST settle: later page loads (e.g. a
@@ -1289,6 +1294,50 @@ pub fn run() {
         .expect("error while building tauri application");
 }
 
+/// WebView2 browser arguments. Setting them replaces Tauri's defaults, so
+/// they're kept, plus the Chromium background-throttling disables (P5-42).
+///
+/// cinny-desktop #19: `LOTUS_WEBVIEW2_DEBUG_PORT=<port>` in the environment
+/// opens WebView2's DevTools port on localhost so the Windows smoke test can
+/// drive the installed app, and gives it Chromium's fake capture devices (the
+/// CI VM has no microphone; permission requests still go through the app's
+/// real PermissionRequested handler). WebView2's own
+/// `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` doesn't apply because the app sets
+/// its arguments explicitly. Off unless the variable holds a valid port; only
+/// whoever launches the app can set it.
+pub(crate) fn webview2_browser_args(debug_port: Option<&str>) -> String {
+    let mut args = String::from(
+        "--disable-features=msWebOOUI,msPdfOOUI --disable-background-timer-throttling --disable-renderer-backgrounding --disable-backgrounding-occluded-windows",
+    );
+    if let Some(port) = debug_port
+        .and_then(|p| p.trim().parse::<u16>().ok())
+        .filter(|p| *p >= 1024)
+    {
+        eprintln!("webview: DevTools port {port} open (LOTUS_WEBVIEW2_DEBUG_PORT)");
+        args.push_str(&format!(
+            " --remote-debugging-port={port} --use-fake-device-for-media-stream"
+        ));
+    }
+    args
+}
+
+#[cfg(test)]
+mod webview2_args_tests {
+    use super::webview2_browser_args;
+
+    #[test]
+    fn debug_port_only_when_asked_for_and_valid() {
+        let base = webview2_browser_args(None);
+        assert!(base.contains("--disable-renderer-backgrounding"));
+        assert!(!base.contains("remote-debugging"));
+        assert!(webview2_browser_args(Some("9222"))
+            .ends_with(" --remote-debugging-port=9222 --use-fake-device-for-media-stream"));
+        for bad in ["", "abc", "80", "70000", "9222 --evil", "-1"] {
+            assert_eq!(webview2_browser_args(Some(bad)), base, "{bad}");
+        }
+    }
+}
+
 #[cfg(test)]
 mod tray_tests {
     use super::*;

src-tauri/src/secure_session.rs

@@ -0,0 +1,181 @@
+//! Login tokens in the OS keychain (cinny #105, step 1).
+//!
+//! Step 1 only MIRRORS the session tokens into the keychain (Windows
+//! Credential Manager): the web client keeps reading its session from
+//! localStorage exactly as before, so nothing about login changes and a
+//! keychain problem can't log anyone out. Once the mirror has proven itself on
+//! real installs, step 2 switches reads to the keychain and drops the tokens
+//! from localStorage.
+//!
+//! Only the secrets are stored (user id + device id to match them to the
+//! session, the access token and the refresh token); the rest of the session
+//! stays in localStorage. Windows caps a credential at 2560 bytes, so the
+//! serialized value is limited well below that.
+//!
+//! Other platforms: not supported yet (Linux Secret Service can prompt to
+//! unlock a wallet at startup; that needs its own testing), and the commands
+//! say so instead of failing.
+
+use serde::{Deserialize, Serialize};
+
+#[cfg_attr(not(any(target_os = "windows", test)), allow(dead_code))]
+pub(crate) const SERVICE: &str = "Lotus Chat";
+#[cfg_attr(not(any(target_os = "windows", test)), allow(dead_code))]
+pub(crate) const ACCOUNT: &str = "session";
+/// Serialized-length cap (chars). Windows' limit is 2560 bytes; staying under
+/// 1200 chars keeps us safe whether the value is stored as UTF-8 or UTF-16.
+pub(crate) const MAX_LEN: usize = 1200;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionTokens {
+    pub user_id: String,
+    pub device_id: String,
+    pub access_token: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub refresh_token: Option<String>,
+}
+
+pub(crate) fn store(entry: &keyring::Entry, tokens: &SessionTokens) -> Result<(), String> {
+    if tokens.user_id.is_empty() || tokens.device_id.is_empty() || tokens.access_token.is_empty() {
+        return Err("incomplete session".into());
+    }
+    let value = serde_json::to_string(tokens).map_err(|e| e.to_string())?;
+    if value.chars().count() > MAX_LEN {
+        return Err(format!(
+            "session too large for the keychain ({} chars)",
+            value.chars().count()
+        ));
+    }
+    entry.set_password(&value).map_err(|e| e.to_string())
+}
+
+pub(crate) fn load(entry: &keyring::Entry) -> Result<Option<SessionTokens>, String> {
+    match entry.get_password() {
+        Ok(value) => serde_json::from_str(&value)
+            .map(Some)
+            .map_err(|e| format!("unreadable keychain entry: {e}")),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(e) => Err(e.to_string()),
+    }
+}
+
+pub(crate) fn clear(entry: &keyring::Entry) -> Result<(), String> {
+    match entry.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(e) => Err(e.to_string()),
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn entry() -> Result<keyring::Entry, String> {
+    keyring::Entry::new(SERVICE, ACCOUNT).map_err(|e| e.to_string())
+}
+
+#[cfg(not(target_os = "windows"))]
+fn entry() -> Result<keyring::Entry, String> {
+    Err("not supported on this platform".into())
+}
+
+/// Keychain calls can block (credential store, AV scanners): keep them off
+/// the main thread.
+async fn blocking<T: Send + 'static>(
+    f: impl FnOnce() -> Result<T, String> + Send + 'static,
+) -> Result<T, String> {
+    tauri::async_runtime::spawn_blocking(f)
+        .await
+        .map_err(|e| e.to_string())?
+}
+
+/// Whether this platform stores the session in the keychain.
+#[tauri::command]
+pub fn secure_session_supported() -> bool {
+    cfg!(target_os = "windows")
+}
+
+#[tauri::command]
+pub async fn secure_session_set(tokens: SessionTokens) -> Result<(), String> {
+    blocking(move || store(&entry()?, &tokens)).await
+}
+
+#[tauri::command]
+pub async fn secure_session_get() -> Result<Option<SessionTokens>, String> {
+    blocking(|| load(&entry()?)).await
+}
+
+#[tauri::command]
+pub async fn secure_session_clear() -> Result<(), String> {
+    blocking(|| clear(&entry()?)).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn mock_entry() -> keyring::Entry {
+        keyring::set_default_credential_builder(keyring::mock::default_credential_builder());
+        keyring::Entry::new(SERVICE, ACCOUNT).unwrap()
+    }
+
+    fn tokens() -> SessionTokens {
+        SessionTokens {
+            user_id: "@alice:lotusguild.org".into(),
+            device_id: "ABCDEFGHIJ".into(),
+            access_token: "syt_YWxpY2U_abcdefghijklmnopqrst_0AbCdE".into(),
+            refresh_token: None,
+        }
+    }
+
+    #[test]
+    fn round_trip_and_clear() {
+        let e = mock_entry();
+        assert_eq!(load(&e).unwrap(), None);
+        store(&e, &tokens()).unwrap();
+        assert_eq!(load(&e).unwrap(), Some(tokens()));
+        let mut oidc = tokens();
+        oidc.refresh_token = Some("mar_refresh_token_value_0123456789".into());
+        store(&e, &oidc).unwrap();
+        assert_eq!(load(&e).unwrap(), Some(oidc));
+        clear(&e).unwrap();
+        assert_eq!(load(&e).unwrap(), None);
+        // Clearing an empty keychain is fine (logout twice, or never mirrored).
+        clear(&e).unwrap();
+    }
+
+    #[test]
+    fn rejects_incomplete_or_oversized_sessions() {
+        let e = mock_entry();
+        let mut t = tokens();
+        t.access_token = String::new();
+        assert!(store(&e, &t).is_err());
+        let mut big = tokens();
+        big.access_token = "x".repeat(MAX_LEN);
+        assert!(store(&e, &big).unwrap_err().contains("too large"));
+        assert_eq!(load(&e).unwrap(), None, "nothing written on error");
+    }
+
+    #[test]
+    fn serialized_shape_matches_the_web_client() {
+        let json = serde_json::to_value(tokens()).unwrap();
+        assert_eq!(json["userId"], "@alice:lotusguild.org");
+        assert_eq!(json["deviceId"], "ABCDEFGHIJ");
+        assert!(json.get("refreshToken").is_none());
+        let back: SessionTokens = serde_json::from_str(
+            r#"{"userId":"@a:b","deviceId":"D","accessToken":"t","refreshToken":"r"}"#,
+        )
+        .unwrap();
+        assert_eq!(back.refresh_token.as_deref(), Some("r"));
+    }
+
+    #[test]
+    fn a_realistic_oidc_session_fits() {
+        let e = mock_entry();
+        let t = SessionTokens {
+            user_id: format!("@{}:matrix.lotusguild.org", "a".repeat(60)),
+            device_id: "X".repeat(40),
+            access_token: "mat_".to_string() + &"A".repeat(200),
+            refresh_token: Some("mar_".to_string() + &"B".repeat(200)),
+        };
+        store(&e, &t).unwrap();
+    }
+}