@wtfalch/desktop 0.1.2 → 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,6 +92,36 @@ 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
@@ -127,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.2",
+  "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/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

@@ -33,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,
@@ -54,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);
@@ -109,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) {
@@ -138,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()),
@@ -220,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(() => {})
@@ -271,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;
@@ -385,6 +388,7 @@ export function run(config) {
           });
 
         const signOut = async (notice) => {
+          if (isLocal) return;
           cancelSignIn();
           const leaving = company;
           company = undefined;
@@ -425,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, {
@@ -447,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 () => {},
+  };
+}