@wtfalch/desktop 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,258 @@
-# Temporary Holding Version
+# @wtfalch/desktop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared Electron shell for Boule, Archon and Agora. An app keeps
+its own packaging (electron-builder config, icons, signing) and calls one entry
+point, `startShell(config)`. The shell finds the app's address, signs the person
+in through the system browser, shows the app in a locked window, and updates
+itself.
+
+```
+pnpm install
+pnpm test             # node --test test/*.test.mjs
+pnpm test:electron    # real Electron against a local fixture app
+pnpm lint
+```
+
+## Wiring an app
+
+The app's `desktop/package.json` depends on `@wtfalch/desktop` (exact version)
+and `electron`, and electron-builder packs it from `node_modules`. The app's
+`main.mjs`:
+
+```js
+import { cookieHandoff, startShell } from '@wtfalch/desktop';
+
+await startShell({
+  appName: 'Boule', dataDirName: 'boule', partitionPrefix: 'persist:boule-',
+  origin: { kind: 'discover', wellKnownPath: '/.well-known/boule.json', hostPrefix: 'boule', sharedHost: { domain: 'oikos.host' } },
+  landingPath: '/dashboard', accessProbePath: null, feedUrl: null, updateChannel: null,
+  devOriginEnv: 'BOULE_URL', devFeedEnv: 'BOULE_UPDATE_FEED_URL',
+  permissions: { notifications: false, media: false }, navigationLinks: null,
+  signIn: cookieHandoff({ scheme: 'boule' }),
+});
+```
+
+A fixed-origin app (Archon, behind Cloudflare Access) differs in three values:
+`origin: { kind: 'fixed', origin: 'https://console.example.com' }`,
+`accessProbePath: '/api/health'` and its own names. The app's `check` script is
+`await runCheck(config, process.argv[2])` (exported), which walks the start of
+the sign-in against a deployed origin and names what is wrong.
+
+The app's `package.json` sets `"main": "main.mjs"`, the electron-builder
+`protocols` (scheme and bundle id are fixed once the first build ships) and
+`files` including `node_modules/@wtfalch/desktop/**`. `welcomeDir` is the
+absolute path of the welcome assets, for a packaging test that checks they ship.
+
+## The config
+
+Every value is required. The package has no defaults, and `validateConfig`
+refuses a missing or malformed one by name (`src/config.mjs`).
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `appName` | string | Window title, menu label, welcome page text, `app.setName`. |
+| `dataDirName` | string | Folder under `appData` holding `company.json` and `window-state.json`. |
+| `partitionPrefix` | string, starts `persist:` | The company's partition is this plus the hex of its origin. |
+| `origin` | `OriginConfig` | How the address is found, below. |
+| `landingPath` | string, starts `/` | Loaded after sign-in and on every launch. |
+| `accessProbePath` | string or null | Behind Cloudflare Access: a path the app answers without a redirect (Archon: `/api/health`). The shell probes it to tell whether Access let the person in, and passes Access in the window first (below). `null`: not behind Access. |
+| `feedUrl` | https string or null | Update feed set in code. Null uses the `app-update.yml` electron-builder bakes in. |
+| `updateChannel` | string or null | electron-updater channel (`<channel>-mac.yml` on the same feed). Never assigns a falsy channel; `allowDowngrade` is always false. |
+| `devOriginEnv` | string | Env var that overrides the origin. Unpackaged runs only. |
+| `devFeedEnv` | string | Env var that overrides the feed. Unpackaged runs only. |
+| `permissions` | `{ notifications, media }` | Granted to the company origin only; everything else is denied. `media` is camera and microphone. |
+| `navigationLinks` | `{ pathPrefix }` or null | `<scheme>://<path>` and same-origin https links under `pathPrefix` open that page (queued when they arrive before the window). Null: such links are ignored. |
+| `signIn` | `SignInStrategy` | How sign-in works, below. |
+
+```ts
+type OriginConfig =
+  | { kind: 'discover'; wellKnownPath: string; hostPrefix: string;
+      sharedHost: { domain: string } | null;
+      validate?: (json: unknown, origin: string) => { name: string } | undefined }
+  | { kind: 'fixed'; origin: string };
+```
+
+### Origin: discover or fixed
+
+`discover` is Boule's email discovery. The email's domain gives
+`https://<hostPrefix>.<domain>`; an email on `<slug>.<sharedHost.domain>` gives
+`https://<slug>-<hostPrefix>.<sharedHost.domain>`. The shell fetches
+`<origin><wellKnownPath>` with `redirect: 'error'`, a timeout and a 16 KB cap.
+By default it must be JSON `{ "name": "<1 to 100 characters>" }`; an app with a
+richer file passes `validate` (it gets the parsed JSON and the origin, returns
+`{ name }` or undefined, and may add fields). On "not found" the page asks for
+the address by hand.
+
+`fixed` has no email screen and no discovery: the app signs in straight away
+against that one origin, and the company name is `appName`. `devOriginEnv`
+may point an unpackaged run at a local origin.
+
+Origins are https only. Plain http is accepted for `localhost` and `127.0.0.1`
+in an unpackaged run. `company.json` stores `{ origin, name }`;
+a corrupt file means no company.
+
+### Origin behind Cloudflare Access
+
+Cloudflare Access answers a request without a `CF_Authorization` cookie with a
+redirect to `*.cloudflareaccess.com`. The cookie lives in the company partition,
+so:
+
+1. Every request the shell makes to the origin after the window exists (redeem,
+   logout, the Access probe) goes through that partition's `session.fetch` with
+   `credentials: 'include'` (`partitionFetcher`). Global `fetch` is never used
+   for them; `DesktopLogin` has no default fetcher.
+2. With `accessProbePath: '/api/health'`, before the system-browser sign-in starts (and
+   before a stored company loads) the shell asks the origin through the
+   partition with `redirect: 'manual'`, deciding from status and `Location`
+   only (Electron's `session.fetch` reports a wrong `response.url`, so it is never
+   read). A non-3xx answer, or a 3xx back to the origin itself, is a pass; a 3xx
+   to any other host (Access, or an identity provider) is not. A network failure
+   is not an Access answer: the window shows the "Could not reach" screen with
+   Try again. When Access wants a login, the window shows the origin so the person passes
+   Access there, and the shell polls every 1.5 s, up to 10 minutes, until a
+   request is answered by the origin itself. Then the handoff starts. Cancel
+   works during this wait. While it lasts the window may follow https redirects
+   anywhere (the identity provider); popups stay blocked.
+3. `redirect: 'error'` for the redeem is unchanged. The redeem is sent with
+   `credentials: 'include'` so `CF_Authorization` goes along; the server is
+   trusted for any `Set-Cookie` on its redeem answer. Cancelling the Access wait
+   clears the partition's storage and cache.
+
+Signing out clears the partition, `CF_Authorization` included, so the next
+sign-in passes Access again.
+
+## Sign-in strategies
+
+`config.signIn` is the one place an app's sign-in lives. The package ships
+`cookieHandoff({ scheme })`. Any object of this shape works:
+
+```ts
+interface SignInStrategy {
+  scheme: string;                       // URL scheme registered with the OS
+  createLogin(ctx: Context): Login;     // one per sign-in attempt
+  logout(ctx: Context): Promise<void>;  // best effort; the shell clears the partition afterwards
+  check?(origin: string): Promise<{ what: string; fix: string }[]>;  // for runCheck
+  preload?: string;                     // absolute path, preload for the company page
+  handlers?: Record<string, (ctx: Context, ...args) => unknown>;     // ipcMain channels, company page top frame only
+}
+interface Context {
+  origin: string;
+  partition: Electron.Session;
+  fetcher: (url, init) => Promise<Response>;   // the partition's session.fetch
+  openBrowser: (url: string) => Promise<void>;
+  userDataDir: string;                         // the app's data folder
+  safeStorage: Electron.SafeStorage;
+}
+interface Login {
+  start(opts: { email?: string; selectAccount: boolean }): Promise<void>; // resolves when signed in; rejects if cancelled, expired or refused
+  cancel(): void;
+  readonly active: boolean;
+  readonly code?: string;                      // pairing code the welcome page shows, if any
+  handleDeepLink(url: string): boolean;        // true if the link was ours and consumed
+}
+```
+
+The shell owns the window, the partition (clearing it, the crash-safe
+`pendingClear` marker), the company record and the welcome screen. The strategy
+owns what is sent to the server and where a credential is kept.
+
+### Mapping Agora's desktop-auth onto it
+
+Agora (`apps/desktop`, `client.mjs`, `vault.mjs`) signs in with a bearer token and
+a vault instead of cookies. It plugs in without changes to the package:
+
+| Strategy part | Agora's code |
+| --- | --- |
+| `scheme` | `'agora'` |
+| `createLogin(ctx)` | builds `Vault(join(ctx.userDataDir, 'session-<hex origin>'), ctx.safeStorage)` and `DesktopSession(ctx.origin, ctx.fetcher, ctx.partition, vault)`, calls `held.restore()`, and returns an adapter over `DesktopLogin(ctx.origin, held, ctx.openBrowser)`: `start` calls `login.start()`, `cancel` calls `login.cancel()`, `active` is true while `start` runs, `handleDeepLink` is `() => false` (Agora polls `redeem`; no link ends its sign-in), no `code`. |
+| `logout(ctx)` | `held.restore(); await held.logout()` (revokes the token, clears the vault). |
+| `check(origin)` | the body of Agora's `check-origin.mjs`, returning its problem list. |
+| `preload`, `handlers` | `preload.cjs` and the `agora:session`, `agora:sign-in`, `agora:sign-out`, `agora:version`, `agora:check-for-updates` channels (the page drives sign-in through `window.wtfalchDesktop`). The badge channel is app-specific and goes here too. |
+| `config.origin.validate` | Agora's `parseConfig` plus the issuer and mail-host trust checks. |
+| `config.permissions` | `{ notifications: true, media: true }` once the open camera and microphone work lands. |
+| `config.navigationLinks` | `{ pathPrefix: '/h' }` |
+
+Not covered, and left for Agora's migration: its separate welcome window with a
+confirm step and `restartAs` relaunch (the package's welcome is in-window and
+needs no relaunch), the dock-icon picker, and `app.setBadgeCount`. These need
+either an app-supplied hook or an Agora-side wrapper, and are not generic enough
+to decide here. `handlers` must be given a way to start a sign-in from the page
+before Agora's flow fits exactly; `ctx` does not carry one yet.
+
+## The handoff contract (cookie handoff: what the server provides)
+
+1. The shell makes a 32-byte random verifier (base64url, 43 characters) and opens
+   `<origin>/auth/desktop/start?challenge=<base64url sha256(verifier)>` in the
+   system browser, with `&login_hint=<email>` when an email is known, and
+   `&prompt=select_account` for the first sign-in after a sign-out.
+2. The person signs in there and confirms. The browser ends on
+   `<scheme>://auth/done?id=<uuid v4>`.
+3. The shell accepts only that exact scheme, host and path with a uuid v4 `id`,
+   and only while a sign-in is pending. Cancelling, or five minutes passing,
+   forgets the verifier; a later link does nothing.
+4. The shell sends `POST <origin>/auth/desktop/redeem` with JSON
+   `{ "id": "<id>", "verifier": "<verifier>" }` and `redirect: 'error'`, through
+   the partition's `session.fetch`.
+5. Success is `200` with JSON
+   `{ "cookies": [ { "name", "value", "path", "httpOnly", "secure", "sameSite", "maxAge" } ] }`.
+   At most 4 cookies. Every cookie is checked: the name matches
+   `/^(__Host-)?[A-Za-z0-9_]+$/`, the value is at most 4096 bytes without control
+   characters; on an https origin the name starts with `__Host-`, `secure` is true
+   and `path` is `/`. Nothing is installed unless every cookie passes.
+6. The cookies go into the company's partition and the window loads
+   `<origin><landingPath>`. The page needs no IPC: the session is a cookie.
+
+The pairing code (shown in the app and on the server's confirm page) is the first
+6 Crockford base32 characters of `sha256("boule-desktop-pair:" + challenge)`,
+shown as `ABC-DEF`. The `boule-desktop-pair:` label is fixed for every app so one
+server implementation serves all of them.
+
+Sign out (native menu) does a best-effort `POST <origin>/auth/logout` through the
+partition with an `Origin` header and `redirect: 'manual'` (the 303 to the issuer is
+never followed), clears the partition's storage and cache, forgets the company and
+shows the welcome screen. "Cancel sign-in" is in the same menu.
+
+A link the server does not recognise (404, 403, 409 `not_approved`) is not ours,
+since any app can open a `<scheme>://` link: the sign-in keeps waiting with the same
+verifier. 409 `consumed`, 410 and 401 end it ("Sign-in expired. Start again.");
+429, 5xx and network errors retry the same link. At most 5 redeems per sign-in,
+one at a time, at least 1.1 seconds apart.
+
+If the server sends the company window to its own `/auth/` pages, the session has
+ended: the shell signs out and shows "Your session ended. Sign in again." If the
+company cannot be reached the shell keeps the company and its session and offers
+"Try again". Nothing is downloaded, and every frame of the company page is held to
+the same origin rule as the page.
+
+A packaged app has no environment overrides and accepts only https origins. A
+packaged app has no DevTools and no reload.
+
+## Behaving like a Mac app
+
+Closing the window hides it; the app stays in the dock. Cmd+Q really quits and
+the dock icon shows the window again. Window position and size persist in
+`window-state.json`, clamped to a connected display. Navigation in the company
+window is locked to its origin, and `/auth/` and `/callback` are never loaded
+there (case, percent-encoding, repeated and back slashes are normalised first).
+
+## The welcome page
+
+A local page (`welcome/welcome.html`, strict CSP, no remote content, no inline
+script) in its own in-memory session. Its preload exposes `window.shellWelcome`:
+`config` (appName, fixed, host, hostPrefix), `resolveEmail` and `resolveAddress`.
+Main validates the input and accepts calls only from that window's own top frame.
+For a fixed origin the page starts at "Sign in to <appName>" and its button asks
+main to start the sign-in.
+
+## Updating itself
+
+electron-updater's generic provider: a static host serving `latest-mac.yml` (or
+`<channel>-mac.yml`) and the zip it names. A packaged app checks once after its
+window first shows; a failed check never blocks startup and is logged. Checksums
+are never turned off.
+
+## Releasing the package
+
+`.github/workflows/release.yml` publishes on a `v*` tag over OIDC with no stored
+token, as the estate's package template does. The first version is published by
+hand; set the npm trusted publisher for this repo before the first tag.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@wtfalch/desktop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "The shared Electron shell for wtfalch apps: sign-in handoff, welcome screen, locked company window, auto-update.",
+  "packageManager": "pnpm@10.0.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": ["LICENSE", "README.md", "src", "welcome"],
+  "exports": {
+    ".": "./src/index.mjs",
+    "./welcome": "./welcome/welcome.html",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:electron": "node test/electron/run.mjs",
+    "lint": "biome check .",
+    "check": "pnpm lint && pnpm test"
+  },
+  "dependencies": {
+    "electron-updater": "6.8.9"
+  },
+  "peerDependencies": {
+    "electron": ">=44"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "electron": "44.4.5"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["electron"]
+  }
+}

package/src/access.mjs

@@ -0,0 +1,90 @@
+// Cloudflare Access support. An origin behind Access answers a request with no
+// CF_Authorization cookie by redirecting to <team>.cloudflareaccess.com. The
+// cookie lives in the company partition, so every request the shell makes to
+// the origin goes through that partition's session.fetch, and the person
+// passes Access in the app window before the system-browser sign-in starts.
+// Everything here is pure or takes its effects as arguments.
+
+export const isAccessHost = (hostname) =>
+  hostname === 'cloudflareaccess.com' || hostname.endsWith('.cloudflareaccess.com');
+
+const hostOf = (value, base) => {
+  try {
+    return new URL(value, base).hostname;
+  } catch {
+    return undefined;
+  }
+};
+
+// Decides from status and Location only. Electron's session.fetch returns an
+// incorrect `.url` (electron.d.ts), so `response.url` is never read. With
+// `redirect: 'manual'` the shell sees the first answer itself: a non-3xx answer
+// is the origin talking, so Access let the request through. A 3xx whose Location
+// resolves to the origin itself is the app's own redirect (also past). A 3xx to
+// any other host is Access or an identity provider (instant auth): not yet.
+export function passedAccess(response, origin) {
+  if (!(response.status >= 300 && response.status < 400)) return true;
+  const location = response.headers?.get?.('location');
+  if (!location) return false;
+  try {
+    return new URL(location, `${origin}/`).origin === origin;
+  } catch {
+    return false;
+  }
+}
+
+// While the person logs in through Access, the window follows its redirects,
+// including to the identity provider, so any https page is allowed, plus the
+// origin itself (http only for a local development origin). Nothing else.
+export function accessNavigation(value, origin) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return false;
+    return url.origin === origin || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+// One request through the company partition's session. `credentials: 'include'`
+// makes the partition's cookies (CF_Authorization, the app session) go along.
+export const partitionFetcher = (partition) => (url, init) =>
+  partition.fetch(url, { ...init, credentials: 'include' });
+
+// Asks the origin, through the partition, whether Access lets this person in:
+// 'passed', 'access' (still being sent to log in) or 'offline' (the request
+// itself failed, so Access cannot be judged).
+export async function probeAccess(fetcher, origin, path) {
+  let response;
+  try {
+    response = await fetcher(`${origin}${path}`, {
+      method: 'GET',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(8000),
+    });
+  } catch {
+    return 'offline';
+  }
+  const passed = passedAccess(response, origin);
+  await response.body?.cancel().catch(() => {});
+  return passed ? 'passed' : 'access';
+}
+
+// Polls `probe` until it says 'passed'. Rejects when cancelled or out of time.
+// `sleep` and `now` are injected so tests need no clock.
+export async function waitForAccess({
+  probe,
+  isCancelled,
+  timeoutMs = 10 * 60 * 1000,
+  intervalMs = 1500,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = Date.now,
+}) {
+  const end = now() + timeoutMs;
+  for (;;) {
+    if (isCancelled()) throw new Error('Access cancelled');
+    if ((await probe()) === 'passed') return;
+    if (now() >= end) throw new Error('Access timed out');
+    await sleep(intervalMs);
+  }
+}

package/src/check-origin.mjs

@@ -0,0 +1,42 @@
+import { validateConfig } from './config.mjs';
+// Preflight for one deployed origin. An app's check script calls
+// runCheck(config, process.argv[2]). It signs nobody in.
+import { discover, originForAddress } from './resolve.mjs';
+
+export async function runCheck(config, typed) {
+  validateConfig(config);
+  const fixed = config.origin.kind === 'fixed';
+  const input =
+    typed ?? process.env[config.devOriginEnv] ?? (fixed ? config.origin.origin : undefined);
+  if (!input) {
+    console.error(`Usage: <check script> <${config.appName} address>`);
+    return 2;
+  }
+  const origin = originForAddress(input, { allowLocal: true });
+  const problems = [];
+  if (!fixed) {
+    const { wellKnownPath, validate } = config.origin;
+    try {
+      await discover(origin, fetch, { wellKnownPath, validate, allowLocal: true });
+    } catch {
+      problems.push({
+        what: `${origin}${wellKnownPath} is missing or malformed`,
+        fix: `Deploy a ${config.appName} release that serves it.`,
+      });
+    }
+  }
+  if (!problems.length) {
+    if (config.accessProbePath !== null)
+      console.log(
+        'Note: this origin is behind Cloudflare Access; the check cannot see past it without a service token.',
+      );
+    if (typeof config.signIn.check === 'function')
+      problems.push(...(await config.signIn.check(origin)));
+  }
+  if (!problems.length) {
+    console.log(`${origin} is ready for the desktop shell.`);
+    return 0;
+  }
+  for (const { what, fix } of problems) console.error(`${what}\n  ${fix}`);
+  return 1;
+}

package/src/company.mjs

@@ -0,0 +1,51 @@
+// Main process only. The one company (or fixed origin) this app holds, as JSON in userData.
+// A missing, corrupt or invalid file means no company. While a partition may
+// hold a session that is not (or no longer) a stored company's, the file holds
+// { pendingClear: <origin> } instead, so a crash cannot leave that session behind.
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { originForAddress, validName } from './resolve.mjs';
+
+const originOk = (value, options) => {
+  try {
+    return typeof value === 'string' && originForAddress(value, options) === value;
+  } catch {
+    return false;
+  }
+};
+const read = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+};
+const write = (path, value) => writeFileSync(path, JSON.stringify(value), { mode: 0o600 });
+
+export function loadCompany(path, options) {
+  const value = read(path);
+  if (!value || !originOk(value.origin, options) || !validName(value.name)) return undefined;
+  return {
+    origin: value.origin,
+    name: value.name,
+  };
+}
+
+export function saveCompany(path, company, options) {
+  if (!originOk(company?.origin, options) || !validName(company.name))
+    throw new Error('Invalid company');
+  write(path, {
+    origin: company.origin,
+    name: company.name,
+  });
+}
+
+export const markPendingClear = (path, origin) => write(path, { pendingClear: origin });
+
+export function loadPendingClear(path, options) {
+  const origin = read(path)?.pendingClear;
+  return originOk(origin, options) ? origin : undefined;
+}
+
+export function forgetCompany(path) {
+  rmSync(path, { force: true });
+}

package/src/config.mjs

@@ -0,0 +1,96 @@
+// The one config an app passes to startShell(). Every value is required: the
+// package holds no defaults, so an app's identity is visible in its own main.mjs.
+//
+// @typedef {{ kind: 'discover', wellKnownPath: string, hostPrefix: string,
+//   sharedHost: { domain: string } | null,
+//   validate?: (json: unknown, origin: string) => { name: string } | undefined }
+//   | { kind: 'fixed', origin: string }} OriginConfig
+//
+// @typedef {object} ShellConfig
+// @property {string} appName        Window title, menu label, welcome page text.
+// @property {string} dataDirName    Folder under appData for company.json and window-state.json.
+// @property {string} partitionPrefix e.g. 'persist:boule-'; the origin's hex is appended.
+// @property {OriginConfig} origin
+// @property {string} landingPath    e.g. '/dashboard'; loaded after sign-in.
+// @property {string|null} accessProbePath  Behind Cloudflare Access: a path the app answers without a redirect
+//   (e.g. '/api/health'), probed to tell whether Access let the person in. null: not behind Access.
+// @property {string|null} feedUrl   https feed baked into code, or null to use app-update.yml.
+// @property {string|null} updateChannel  electron-updater channel, or null.
+// @property {string} devOriginEnv   Unpackaged-only origin override, e.g. 'BOULE_URL'.
+// @property {string} devFeedEnv     Unpackaged-only feed override, e.g. 'BOULE_UPDATE_FEED_URL'.
+// @property {{ notifications: boolean, media: boolean }} permissions  Granted to the company origin only.
+// @property {{ pathPrefix: string } | null} navigationLinks  <scheme>://<path> links that open a page.
+// @property {SignInStrategy} signIn  See README.md, "Sign-in strategies".
+import { originForAddress } from './resolve.mjs';
+
+const text = (value, name) => {
+  if (typeof value !== 'string' || !value.trim())
+    throw new Error(`config.${name} must be a non-empty string`);
+};
+const flag = (value, name) => {
+  if (typeof value !== 'boolean') throw new Error(`config.${name} must be a boolean`);
+};
+
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object') throw new Error('startShell needs a config object');
+  for (const key of [
+    'appName',
+    'dataDirName',
+    'partitionPrefix',
+    'landingPath',
+    'devOriginEnv',
+    'devFeedEnv',
+  ])
+    text(config[key], key);
+  if (!/^[a-z0-9-]+$/i.test(config.dataDirName))
+    throw new Error('config.dataDirName must be a plain folder name');
+  if (!config.partitionPrefix.startsWith('persist:'))
+    throw new Error("config.partitionPrefix must start with 'persist:'");
+  if (!config.landingPath.startsWith('/'))
+    throw new Error("config.landingPath must start with '/'");
+  if (config.accessProbePath !== null && !/^\/[^/\\]/.test(String(config.accessProbePath)))
+    throw new Error("config.accessProbePath must be null or a path starting with '/'");
+  for (const key of ['feedUrl', 'updateChannel'])
+    if (config[key] !== null && typeof config[key] !== 'string')
+      throw new Error(`config.${key} must be a string or null`);
+  if (config.feedUrl !== null && !config.feedUrl.startsWith('https://'))
+    throw new Error('config.feedUrl must be https');
+  const p = config.permissions;
+  if (!p || typeof p.notifications !== 'boolean' || typeof p.media !== 'boolean')
+    throw new Error('config.permissions needs boolean notifications and media');
+  const nav = config.navigationLinks;
+  if (
+    nav !== null &&
+    (!nav || typeof nav.pathPrefix !== 'string' || !nav.pathPrefix.startsWith('/'))
+  )
+    throw new Error('config.navigationLinks must be null or { pathPrefix: "/..." }');
+  const signIn = config.signIn;
+  if (
+    !signIn ||
+    typeof signIn.createLogin !== 'function' ||
+    typeof signIn.logout !== 'function' ||
+    typeof signIn.scheme !== 'string'
+  )
+    throw new Error('config.signIn must be a sign-in strategy: { scheme, createLogin, logout }');
+  const origin = config.origin;
+  if (origin?.kind === 'fixed') {
+    let normal;
+    try {
+      normal = originForAddress(origin.origin);
+    } catch {
+      normal = undefined;
+    }
+    if (normal !== origin.origin)
+      throw new Error('config.origin.origin must be a plain https origin');
+  } else if (origin?.kind === 'discover') {
+    text(origin.wellKnownPath, 'origin.wellKnownPath');
+    if (!origin.wellKnownPath.startsWith('/'))
+      throw new Error("config.origin.wellKnownPath must start with '/'");
+    text(origin.hostPrefix, 'origin.hostPrefix');
+    if (origin.sharedHost !== null && typeof origin.sharedHost?.domain !== 'string')
+      throw new Error('config.origin.sharedHost must be null or { domain }');
+    if (origin.validate !== undefined && typeof origin.validate !== 'function')
+      throw new Error('config.origin.validate must be a function');
+  } else throw new Error("config.origin.kind must be 'discover' or 'fixed'");
+  return config;
+}