@wtfalch/desktop 0.1.1 → 0.2.0

package/README.md

@@ -69,7 +69,8 @@ type OriginConfig =
   | { kind: 'discover'; wellKnownPath: string; hostPrefix: string;
       sharedHost: { domain: string } | null;
       validate?: (json: unknown, origin: string) => { name: string } | undefined }
-  | { kind: 'fixed'; origin: string };
+  | { kind: 'fixed'; origin: string }
+  | { kind: 'local'; start(ctx: { session: Electron.Session }): Promise<string>; stop?(): Promise<void> };
 ```
 
 ### Origin: discover or fixed
@@ -91,21 +92,54 @@ 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.
 
+### Local origin
+
+`local` is for an app that runs its own server on the person's machine. The
+shell calls `start({ session })` once the app is ready. `session` is the
+window's own partition, so the app can set cookies on it before the first page
+loads. `start` resolves to the server's origin: `http://127.0.0.1:<port>` or
+`http://localhost:<port>`, with a port and no path, query or credentials;
+anything else throws and the app does not start. `stop()` is awaited once when
+the app quits.
+
+There is no discovery, welcome screen, Access probe or `check()`; the window
+loads `<origin><landingPath>` and is locked to that origin like any other. The
+partition name is `partitionPrefix` plus `local`, since the port changes on
+every start. Use it with `noSignIn({ scheme })`: a strategy whose login never
+starts and whose logout does nothing. Sign out and Cancel sign-in do nothing
+for a local origin. `fixed` still refuses http.
+
+```js
+origin: {
+  kind: 'local',
+  start: async ({ session }) => {
+    const port = await startServer();
+    await session.cookies.set({ url: `http://127.0.0.1:${port}`, name: 'reel', value: token });
+    return `http://127.0.0.1:${port}`;
+  },
+  stop: async () => stopServer(),
+},
+signIn: noSignIn({ scheme: 'reel' }),
+```
+
 ### 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.
+1. Every request the shell makes to the origin after the window exists goes
+   through that partition. The redeem and logout use its `session.fetch` with
+   `credentials: 'include'` (`partitionFetcher`). The Access probe uses
+   `net.request` on the same session with its cookies (`manualRedirectFetcher`),
+   because `session.fetch` rejects a `redirect: 'manual'` request that meets a
+   3xx with "Redirect was cancelled" (Electron 44.4.5), which would read Access's
+   own 302 as offline. 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
+   only (the `redirect` event names the target before anything is followed). 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
@@ -124,7 +158,7 @@ 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:
+`cookieHandoff({ scheme })` and `noSignIn({ scheme })` (for a `local` origin). Any object of this shape works:
 
 ```ts
 interface SignInStrategy {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/desktop",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "The shared Electron shell for wtfalch apps: sign-in handoff, welcome screen, locked company window, auto-update.",

package/src/access.mjs

@@ -51,6 +51,40 @@ export function accessNavigation(value, origin) {
 export const partitionFetcher = (partition) => (url, init) =>
   partition.fetch(url, { ...init, credentials: 'include' });
 
+// The probe's fetcher. Electron's session.fetch rejects a `redirect: 'manual'`
+// request that meets a 3xx with "Redirect was cancelled" (Electron 44.4.5), so
+// Access's own 302 would read as offline. net.request on the same partition
+// session names the target in its 'redirect' event instead, before anything is
+// followed. `request` is net.request bound to the partition, injected so this
+// module stays plain Node.
+export const manualRedirectFetcher =
+  (request) =>
+  (url, init = {}) =>
+    new Promise((resolve, reject) => {
+      const req = request({
+        url,
+        method: init.method ?? 'GET',
+        redirect: 'manual',
+        useSessionCookies: true,
+      });
+      const answer = (status, location) => {
+        req.abort();
+        resolve({ status, headers: new Headers(location ? { location } : {}) });
+      };
+      req.on('redirect', (status, _method, location) => answer(status, location));
+      req.on('response', (response) => answer(response.statusCode));
+      req.on('error', reject);
+      init.signal?.addEventListener(
+        'abort',
+        () => {
+          req.abort();
+          reject(init.signal.reason);
+        },
+        { once: true },
+      );
+      req.end();
+    });
+
 // 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).

package/src/check-origin.mjs

@@ -5,6 +5,10 @@ import { discover, originForAddress } from './resolve.mjs';
 
 export async function runCheck(config, typed) {
   validateConfig(config);
+  if (config.origin.kind === 'local') {
+    console.log('A local origin is started by the app itself; there is nothing to check.');
+    return 0;
+  }
   const fixed = config.origin.kind === 'fixed';
   const input =
     typed ?? process.env[config.devOriginEnv] ?? (fixed ? config.origin.origin : undefined);

package/src/config.mjs

@@ -4,7 +4,8 @@
 // @typedef {{ kind: 'discover', wellKnownPath: string, hostPrefix: string,
 //   sharedHost: { domain: string } | null,
 //   validate?: (json: unknown, origin: string) => { name: string } | undefined }
-//   | { kind: 'fixed', origin: string }} OriginConfig
+//   | { kind: 'fixed', origin: string }
+//   | { kind: 'local', start: ({ session }) => Promise<string>, stop?: () => Promise<void> }} OriginConfig
 //
 // @typedef {object} ShellConfig
 // @property {string} appName        Window title, menu label, welcome page text.
@@ -91,6 +92,11 @@ export function validateConfig(config) {
       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'");
+  } else if (origin?.kind === 'local') {
+    if (typeof origin.start !== 'function')
+      throw new Error('config.origin.start must be a function');
+    if (origin.stop !== undefined && typeof origin.stop !== 'function')
+      throw new Error('config.origin.stop must be a function');
+  } else throw new Error("config.origin.kind must be 'discover', 'fixed' or 'local'");
   return config;
 }

package/src/index.mjs

@@ -2,6 +2,7 @@
 export { welcomeDir } from './welcome-dir.mjs';
 export { validateConfig } from './config.mjs';
 export { cookieHandoff } from './strategies/cookie-handoff.mjs';
+export { noSignIn } from './strategies/no-sign-in.mjs';
 export { runCheck } from './check-origin.mjs';
 export { isAccessHost, passedAccess } from './access.mjs';
 

package/src/lifecycle.mjs

@@ -18,3 +18,25 @@ export function wireCloseBehavior(app, window, platform = process.platform) {
     if (platform !== 'darwin') app.quit();
   });
 }
+
+// Runs `stop` once when the app quits, and waits for it before the quit goes on.
+// A stop that has not finished after `timeoutMs` is given up on, so a hung
+// server cannot keep the app from quitting.
+export function stopOnQuit(app, stop, timeoutMs = 5000) {
+  let stopped = false;
+  app.on('will-quit', (event) => {
+    if (stopped) return;
+    stopped = true;
+    event.preventDefault();
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+    });
+    Promise.race([Promise.resolve().then(stop), timeout])
+      .catch((error) => console.error('stop failed:', error?.message ?? error))
+      .finally(() => {
+        clearTimeout(timer);
+        app.quit();
+      });
+  });
+}

package/src/resolve.mjs

@@ -59,6 +59,32 @@ export function originForAddress(input, { allowLocal = false } = {}) {
   return `https://${url.host}`;
 }
 
+// What an app's local server answered with: http, 127.0.0.1 or localhost, a
+// port, nothing else. Returns the origin or throws.
+export function localOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    url = undefined;
+  }
+  if (
+    typeof value !== 'string' ||
+    !url ||
+    url.protocol !== 'http:' ||
+    !isLocal(url.hostname) ||
+    !url.port ||
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    value !== url.origin
+  )
+    throw new Error(`${value} is not a local origin.`);
+  return url.origin;
+}
+
 export async function readCapped(response, max) {
   const reader = response.body?.getReader();
   if (!reader) throw new Error('Empty response');

package/src/shell.mjs

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 // Main process only; loaded by startShell() so that importing the package
 // outside Electron (tests, check scripts) never imports 'electron'.
 import {
+  net,
   BrowserWindow,
   Menu,
   WebContentsView,
@@ -16,7 +17,13 @@ import {
   shell,
 } from 'electron';
 import updaterPkg from 'electron-updater';
-import { accessNavigation, partitionFetcher, probeAccess, waitForAccess } from './access.mjs';
+import {
+  accessNavigation,
+  manualRedirectFetcher,
+  partitionFetcher,
+  probeAccess,
+  waitForAccess,
+} from './access.mjs';
 import {
   forgetCompany,
   loadCompany,
@@ -26,9 +33,9 @@ import {
 } from './company.mjs';
 import { validateConfig } from './config.mjs';
 import { findDeepLinkArg, initialDeepLink, resolveDeepLink } from './deep-link.mjs';
-import { wireCloseBehavior } from './lifecycle.mjs';
+import { stopOnQuit, wireCloseBehavior } from './lifecycle.mjs';
 import { menuTemplate } from './menu.mjs';
-import { discover, originForAddress, originForEmail } from './resolve.mjs';
+import { discover, localOrigin, originForAddress, originForEmail } from './resolve.mjs';
 import {
   allowedNavigation,
   permissionCheckHandler,
@@ -47,6 +54,7 @@ export function run(config) {
   validateConfig(config);
   const { appName, signIn } = config;
   const fixed = config.origin.kind === 'fixed';
+  const isLocal = config.origin.kind === 'local';
   const welcomeFile = join(welcomeDir, 'welcome.html');
   const welcomeUrl = pathToFileURL(welcomeFile).href;
   app.setName(appName);
@@ -102,7 +110,9 @@ export function run(config) {
   };
   const companyPartition = (origin) =>
     lockSession(
-      session.fromPartition(`${config.partitionPrefix}${Buffer.from(origin).toString('hex')}`),
+      session.fromPartition(
+        `${config.partitionPrefix}${isLocal ? 'local' : Buffer.from(origin).toString('hex')}`,
+      ),
       origin,
     );
   async function clearPartition(partition) {
@@ -131,12 +141,12 @@ export function run(config) {
         const companyFile = join(profile, 'company.json');
         const stateFile = join(profile, 'window-state.json');
         // A session left behind by a crash during sign-in or sign-out is cleared first.
-        const leftover = loadPendingClear(companyFile, local);
+        const leftover = isLocal ? undefined : loadPendingClear(companyFile, local);
         if (leftover) {
           await clearPartition(companyPartition(leftover)).catch(() => {});
           forgetCompany(companyFile);
         }
-        let company = loadCompany(companyFile, local);
+        let company = isLocal ? undefined : loadCompany(companyFile, local);
         const savedState = readWindowState(stateFile);
         const window = new BrowserWindow({
           ...clampBounds(savedState?.bounds, screen.getAllDisplays()),
@@ -213,7 +223,7 @@ export function run(config) {
         // The server sent the company window to its own sign-in page: the session is gone.
         let ending = false;
         const endSession = () => {
-          if (ending) return;
+          if (ending || isLocal) return;
           ending = true;
           void signOut('ended')
             .catch(() => {})
@@ -228,8 +238,11 @@ export function run(config) {
         // polls through the partition until the origin answers for itself.
         const passAccess = async (found) => {
           if (config.accessProbePath === null) return 'passed';
-          const { partition, fetcher } = context(found.origin);
-          const probe = () => probeAccess(fetcher, found.origin, config.accessProbePath);
+          const { partition } = context(found.origin);
+          const probeFetcher = manualRedirectFetcher((options) =>
+            net.request({ ...options, session: partition }),
+          );
+          const probe = () => probeAccess(probeFetcher, found.origin, config.accessProbePath);
           // Set before the first await so a second request cannot open a second gate.
           const mine = { cancelled: false };
           gate = mine;
@@ -261,7 +274,7 @@ export function run(config) {
         };
 
         const showCompany = async (found) => {
-          const access = await passAccess(found);
+          const access = isLocal ? 'passed' : await passAccess(found);
           if (access !== 'passed') {
             await showGateFailure(found, access);
             return;
@@ -375,6 +388,7 @@ export function run(config) {
           });
 
         const signOut = async (notice) => {
+          if (isLocal) return;
           cancelSignIn();
           const leaving = company;
           company = undefined;
@@ -415,6 +429,7 @@ export function run(config) {
           if (target) void view?.webContents.loadURL(target).catch(() => {});
         });
         app.on('before-quit', () => login?.cancel());
+        if (isLocal && config.origin.stop) stopOnQuit(app, config.origin.stop);
         wireCloseBehavior(app, window);
         window.on('close', () =>
           writeWindowState(stateFile, {
@@ -437,6 +452,14 @@ export function run(config) {
             navOptions && initialDeepLink(queuedLinks, process.argv, company.origin, navOptions);
           queuedLinks.length = 0;
           if (link) void view?.webContents.loadURL(link).catch(() => {});
+        } else if (isLocal) {
+          // The person runs the server themselves: no discovery, Access or sign-in.
+          // The partition is one fixed name, since the port changes on every start.
+          const partition = session.fromPartition(`${config.partitionPrefix}local`);
+          const origin = localOrigin(await config.origin.start({ session: partition }));
+          lockSession(partition, origin);
+          company = { origin, name: appName };
+          await showCompany(company);
         } else if (fixed) await signInFixed().catch(() => showWelcome('failed'));
         else {
           await showWelcome();

package/src/strategies/no-sign-in.mjs

@@ -0,0 +1,17 @@
+// The sign-in strategy for an app with nobody to sign in: the person runs the
+// server themselves. Meant for the `local` origin; nothing stops another kind
+// from using it, and then no sign-in is ever started.
+export function noSignIn({ scheme }) {
+  if (typeof scheme !== 'string' || !/^[a-z][a-z0-9+.-]*$/.test(scheme))
+    throw new Error('noSignIn needs a url scheme');
+  return {
+    scheme,
+    createLogin: () => ({
+      start: async () => {},
+      cancel: () => {},
+      handleDeepLink: () => false,
+      active: false,
+    }),
+    logout: async () => {},
+  };
+}