@wtfalch/desktop 0.0.0-stage → 0.1.1

package/src/deep-link.mjs

@@ -0,0 +1,69 @@
+// Main process only. Two kinds of link, each opt-in.
+//
+// parseLoginLink: the end of a browser sign-in, <scheme>://auth/done?id=<uuid v4>
+// (the cookie-handoff strategy). It returns the id or undefined. The link
+// carries no credential.
+//
+// resolveDeepLink and friends: a link that opens a page, <scheme>://<path> or
+// an https link to the app's own origin, for apps that configure
+// `navigationLinks` (from Agora). The target is rebuilt from the trusted
+// origin and a validated path, and must pass the same navigation rule as the
+// window, so a link reaches no more than the page could navigate to itself.
+import { allowedNavigation } from './security.mjs';
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function parseLoginLink(value, scheme) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  if (
+    url.protocol !== `${scheme}:` ||
+    url.host !== 'auth' ||
+    url.pathname !== '/done' ||
+    url.hash ||
+    url.username ||
+    url.password ||
+    url.port
+  )
+    return undefined;
+  const params = [...url.searchParams];
+  if (params.length !== 1 || params[0][0] !== 'id' || !UUID_V4.test(params[0][1])) return undefined;
+  return params[0][1].toLowerCase();
+}
+
+// <scheme>://h/<id>/... : the authority is the first path segment, so host and
+// pathname together reassemble the path.
+export function resolveDeepLink(value, origin, { scheme, pathPrefix }) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  let path;
+  if (url.protocol === `${scheme}:`) path = `/${url.host}${url.pathname}`;
+  else if (url.protocol === 'https:' && url.origin === origin) path = url.pathname;
+  else return undefined;
+  if (path !== pathPrefix && !path.startsWith(`${pathPrefix}/`)) return undefined;
+  const target = `${origin}${path}${url.search}${url.hash}`;
+  return allowedNavigation(target, origin) ? target : undefined;
+}
+
+export function findDeepLinkArg(argv, origin, options) {
+  for (const arg of argv) {
+    const target = resolveDeepLink(arg, origin, options);
+    if (target) return target;
+  }
+  return undefined;
+}
+
+// Cold start: a link macOS handed us via 'open-url' before the window existed
+// (queued) wins over one passed as a launch argument (argv): the queued one is
+// the more specific, more recent signal (Agora PR 308).
+export function initialDeepLink(queued, argv, origin, options) {
+  return findDeepLinkArg(queued, origin, options) ?? findDeepLinkArg(argv, origin, options);
+}

package/src/index.mjs

@@ -0,0 +1,15 @@
+// @wtfalch/desktop: the shared Electron shell. See README.md.
+export { welcomeDir } from './welcome-dir.mjs';
+export { validateConfig } from './config.mjs';
+export { cookieHandoff } from './strategies/cookie-handoff.mjs';
+export { runCheck } from './check-origin.mjs';
+export { isAccessHost, passedAccess } from './access.mjs';
+
+// Starts the shell in Electron's main process. `electron` is imported here,
+// not at the top, so that importing this package elsewhere stays possible.
+export async function startShell(config) {
+  const { validateConfig } = await import('./config.mjs');
+  validateConfig(config);
+  const { run } = await import('./shell.mjs');
+  run(config);
+}

package/src/lifecycle.mjs

@@ -0,0 +1,20 @@
+// Main process only. Mac keeps the app resident: closing the window hides it
+// instead of destroying it, the dock icon ('activate') shows it again, and
+// only a real quit (Cmd+Q, app.quit()) lets the window actually close. Other
+// platforms keep quitting on close; there is no tray to fall back to there.
+export function wireCloseBehavior(app, window, platform = process.platform) {
+  let quitting = false;
+  app.on('before-quit', () => {
+    quitting = true;
+  });
+  window.on('close', (event) => {
+    if (platform === 'darwin' && !quitting) {
+      event.preventDefault();
+      window.hide();
+    }
+  });
+  app.on('activate', () => window.show());
+  app.on('window-all-closed', () => {
+    if (platform !== 'darwin') app.quit();
+  });
+}

package/src/login.mjs

@@ -0,0 +1,215 @@
+// Main process only. The browser handoff, from the shell's side.
+//
+// The shell makes a random verifier and opens the system browser with its
+// sha256 as the challenge. The person signs in there. The browser ends on
+// <scheme>://auth/done?id=<id>; the shell then POSTs the id and the verifier and
+// receives the session cookies once, and installs them in the company's
+// partition. The link alone is worth nothing: only the verifier redeems it.
+// Any app can open a <scheme>:// link, so a link the server does not recognise
+// (404, 403, not_approved) is not ours: the sign-in keeps waiting, with the
+// same verifier, for the right one.
+import { createHash, randomBytes } from 'node:crypto';
+import { parseLoginLink } from './deep-link.mjs';
+import { readCapped } from './resolve.mjs';
+
+const SIGN_IN_MS = 5 * 60 * 1000;
+const REDEEM_GAP_MS = 1100; // the server allows one redeem a second per handoff
+const MAX_REDEEMS = 5;
+const MAX_COOKIES = 4;
+const MAX_MAX_AGE = 400 * 24 * 60 * 60;
+const SAME_SITE = { lax: 'lax', strict: 'strict' };
+const COOKIE_NAME = /^(__Host-)?[A-Za-z0-9_]+$/;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+
+// A code both the app and the server's confirm page derive from the challenge,
+// so the person can tell the sign-in they confirm in the browser is the one this
+// app started: the first 6 characters of the Crockford base32 of
+// sha256("boule-desktop-pair:" + challenge), 5 bits each, shown as ABC-DEF.
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function pairingCode(challenge) {
+  const digest = createHash('sha256').update(`boule-desktop-pair:${challenge}`).digest();
+  let code = '';
+  for (let bit = 0; bit < 30; bit += 5) {
+    const window = (digest[bit >> 3] << 8) | digest[(bit >> 3) + 1];
+    code += CROCKFORD[(window >> (11 - (bit & 7))) & 31];
+  }
+  return `${code.slice(0, 3)}-${code.slice(3)}`;
+}
+
+// Returns the arguments for session.cookies.set, or throws. The session cookie
+// is HttpOnly and Lax or Strict. On an https origin only a __Host- cookie is
+// accepted: secure, path "/", no domain.
+function checkedCookie(cookie, origin) {
+  const { name, value, path, httpOnly, secure, sameSite, maxAge } = cookie ?? {};
+  if (
+    typeof name !== 'string' ||
+    !COOKIE_NAME.test(name) ||
+    typeof value !== 'string' ||
+    Buffer.byteLength(value) > 4096 ||
+    CONTROL.test(value) ||
+    value.includes(';')
+  )
+    throw new Error('Invalid session cookie');
+  if (
+    httpOnly !== true ||
+    typeof secure !== 'boolean' ||
+    typeof path !== 'string' ||
+    !Object.hasOwn(SAME_SITE, sameSite) ||
+    (maxAge !== undefined && !(Number.isFinite(maxAge) && maxAge > 0 && maxAge <= MAX_MAX_AGE))
+  )
+    throw new Error('Invalid session cookie');
+  if (origin.startsWith('https:') && (!name.startsWith('__Host-') || !secure || path !== '/'))
+    throw new Error('Invalid session cookie');
+  return {
+    url: origin,
+    name,
+    value,
+    path,
+    httpOnly,
+    secure,
+    sameSite: SAME_SITE[sameSite],
+    ...(maxAge === undefined ? {} : { expirationDate: Date.now() / 1000 + maxAge }),
+  };
+}
+
+export class DesktopLogin {
+  #pending;
+  // `fetcher` is required and has no default: an app behind Cloudflare Access
+  // must send the redeem through the company partition's session.fetch, so the
+  // partition's cookies go along (see partitionFetcher in access.mjs).
+  constructor({
+    scheme,
+    origin,
+    partition,
+    openBrowser,
+    fetcher,
+    timeoutMs = SIGN_IN_MS,
+    redeemGapMs = REDEEM_GAP_MS,
+  }) {
+    if (typeof fetcher !== 'function') throw new Error('DesktopLogin needs a fetcher');
+    Object.assign(this, {
+      scheme,
+      origin,
+      partition,
+      openBrowser,
+      fetcher,
+      timeoutMs,
+      redeemGapMs,
+    });
+  }
+  get active() {
+    return Boolean(this.#pending);
+  }
+  // The pairing code of the sign-in in progress, set as soon as start() is called.
+  get code() {
+    return this.#pending?.code;
+  }
+
+  // Resolves once the cookies are in the partition. Rejects when cancelled,
+  // timed out, expired or out of redeem attempts.
+  // selectAccount asks the issuer to show its account chooser (after a sign-out).
+  async start(email, selectAccount = false) {
+    if (this.#pending) throw new Error('Sign-in already active');
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    const pending = {
+      verifier,
+      code: pairingCode(challenge),
+      cancelled: false,
+      error: undefined,
+      waiter: undefined,
+    };
+    this.#pending = pending;
+    const nextLink = () =>
+      pending.error
+        ? Promise.reject(pending.error)
+        : new Promise((resolve, reject) => {
+            pending.waiter = { resolve, reject };
+          });
+    const timer = setTimeout(() => this.cancel(pending, 'Sign-in timed out'), this.timeoutMs);
+    try {
+      const url = new URL('/auth/desktop/start', this.origin);
+      url.searchParams.set('challenge', challenge);
+      if (email) url.searchParams.set('login_hint', email);
+      if (selectAccount) url.searchParams.set('prompt', 'select_account');
+      await this.openBrowser(url.href);
+      let cookies;
+      let id;
+      let last = 0;
+      for (let attempts = 0; !cookies; attempts++) {
+        id ??= await nextLink(); // links that arrive while a redeem runs are ignored
+        if (attempts >= MAX_REDEEMS) throw new Error('Sign-in was refused');
+        await sleep(last + this.redeemGapMs - Date.now());
+        if (pending.error) throw pending.error;
+        last = Date.now();
+        const result = await this.#redeem(id, pending.verifier);
+        if (result === 'wrong') id = undefined;
+        else if (result !== 'retry')
+          cookies = result.map((cookie) => checkedCookie(cookie, this.origin));
+      }
+      // Cancelled while redeeming: the session was minted but is never installed.
+      if (pending.cancelled) throw new Error('Sign-in cancelled');
+      for (const cookie of cookies) await this.partition.cookies.set(cookie);
+    } finally {
+      clearTimeout(timer);
+      pending.verifier = '';
+      if (this.#pending === pending) this.#pending = undefined;
+    }
+  }
+
+  // The cookies, 'wrong' (not our link: wait for another) or 'retry'; throws
+  // when the sign-in is over.
+  async #redeem(id, verifier) {
+    let response;
+    try {
+      response = await this.fetcher(`${this.origin}/auth/desktop/redeem`, {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(10000),
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id, verifier }),
+      });
+    } catch {
+      return 'retry';
+    }
+    if (response.status === 200) {
+      const { cookies } = JSON.parse(await readCapped(response, 32 * 1024));
+      if (!Array.isArray(cookies) || !cookies.length || cookies.length > MAX_COOKIES)
+        throw new Error('Invalid sign-in response');
+      return cookies;
+    }
+    let code;
+    try {
+      code = JSON.parse(await readCapped(response, 1024)).error;
+    } catch {
+      /* no code */
+    }
+    const { status } = response;
+    if (status === 401 || status === 410 || (status === 409 && code === 'consumed'))
+      throw new Error('Sign-in expired. Start again.');
+    if (status === 429 || status >= 500) return 'retry';
+    return 'wrong'; // 400, 403, 404, 409 not_approved
+  }
+
+  // A deep link. Ignored unless a sign-in is waiting for one. It never ends the
+  // sign-in: a link the server refuses just means waiting for another.
+  handleDeepLink(value) {
+    const waiter = this.#pending?.waiter;
+    const id = waiter ? parseLoginLink(value, this.scheme) : undefined;
+    if (!id) return false;
+    this.#pending.waiter = undefined;
+    waiter.resolve(id);
+    return true;
+  }
+
+  cancel(pending = this.#pending, reason = 'Sign-in cancelled') {
+    if (!pending) return;
+    pending.cancelled = true;
+    pending.verifier = '';
+    pending.error = new Error(reason);
+    pending.waiter?.reject(pending.error);
+    pending.waiter = undefined;
+    if (this.#pending === pending) this.#pending = undefined;
+  }
+}

package/src/menu.mjs

@@ -0,0 +1,28 @@
+// The native menu template. A packaged app has no DevTools and no reload.
+export function menuTemplate({ appName, packaged, onCancel, onSignOut }) {
+  const view = packaged
+    ? {
+        label: 'View',
+        submenu: [
+          { role: 'resetZoom' },
+          { role: 'zoomIn' },
+          { role: 'zoomOut' },
+          { type: 'separator' },
+          { role: 'togglefullscreen' },
+        ],
+      }
+    : { role: 'viewMenu' };
+  return [
+    {
+      label: appName,
+      submenu: [
+        { label: 'Cancel sign-in', click: onCancel },
+        { label: 'Sign out', click: onSignOut },
+        { type: 'separator' },
+        { role: 'quit' },
+      ],
+    },
+    { role: 'editMenu' },
+    view,
+  ];
+}

package/src/resolve.mjs

@@ -0,0 +1,105 @@
+// Finds a company's app. Pure apart from the fetch passed to discover().
+// Origins are https. Plain http for localhost and 127.0.0.1 is accepted only
+// with { allowLocal: true }, which the app sets for unpackaged builds and tests.
+export class NotFoundError extends Error {
+  constructor(message = 'Nothing found there.') {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const HOST = `(?:${LABEL}\\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]`;
+const DOMAIN = new RegExp(`^${HOST}$`);
+const EMAIL = new RegExp(`^[a-z0-9._%+-]{1,64}@(${HOST})$`, 'i');
+const escapeDots = (value) => value.replaceAll('.', '\\.');
+const MAX_HOST = 253;
+const MAX_BODY = 16 * 1024;
+// Control, bidi and zero-width characters have no place in a company name.
+const HIDDEN = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+const isLocal = (hostname) => hostname === 'localhost' || hostname === '127.0.0.1';
+
+export const validName = (name) =>
+  typeof name === 'string' && Boolean(name.trim()) && name.length <= 100 && !HIDDEN.test(name);
+
+// With { hostPrefix: 'boule', sharedHost: { domain: 'oikos.host' } }:
+// ana@Acme.com -> https://boule.acme.com; ana@acme.oikos.host ->
+// https://acme-boule.oikos.host. The shared host is the platform's domain for
+// orgs without one of their own. Anything but a plain address throws.
+export function originForEmail(email, { hostPrefix, sharedHost }) {
+  const match = typeof email === 'string' ? EMAIL.exec(email.trim()) : null;
+  if (!match || match[1].length > MAX_HOST - 6)
+    throw new Error('That is not a work email address.');
+  const domain = match[1].toLowerCase();
+  const slug = sharedHost
+    ? new RegExp(`^(${LABEL})\\.${escapeDots(sharedHost.domain)}$`).exec(domain)?.[1]
+    : undefined;
+  return slug
+    ? `https://${slug}-${hostPrefix}.${sharedHost.domain}`
+    : `https://${hostPrefix}.${domain}`;
+}
+
+// What somebody typed for a company's address: `Boule.Acme.com/x`
+// gives https://boule.acme.com. A pasted scheme or path is dropped.
+export function originForAddress(input, { allowLocal = false } = {}) {
+  const trimmed = typeof input === 'string' ? input.trim() : '';
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(trimmed)?.[1].toLowerCase();
+  let url;
+  try {
+    url = new URL(scheme ? trimmed : `https://${trimmed}`);
+  } catch {
+    url = undefined;
+  }
+  if (!url || (scheme && scheme !== 'https' && scheme !== 'http') || url.username || url.password)
+    throw new Error(`${input} is not an address.`);
+  if (allowLocal && isLocal(url.hostname)) return `http://${url.host}`;
+  if (scheme === 'http' || url.hostname.length > MAX_HOST || !DOMAIN.test(url.hostname))
+    throw new Error(`${input} is not an address.`);
+  return `https://${url.host}`;
+}
+
+export async function readCapped(response, max) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('Empty response');
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > max) {
+      await reader.cancel();
+      throw new Error('Response too large');
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// The name check every well-known file gets unless the app passes its own
+// `validate`, which returns { name } or undefined.
+const defaultValidate = (json) => (validName(json?.name) ? { name: json.name } : undefined);
+
+// Confirms an app lives at origin and returns its name. Any failure, from
+// DNS to a redirect to a malformed file, is the same answer: not found.
+export async function discover(
+  origin,
+  fetcher,
+  { wellKnownPath, validate = defaultValidate, allowLocal = false },
+) {
+  try {
+    if (originForAddress(origin, { allowLocal }) !== origin) throw new NotFoundError();
+    const response = await fetcher(`${origin}${wellKnownPath}`, {
+      redirect: 'error',
+      signal: AbortSignal.timeout(8000),
+      headers: { accept: 'application/json' },
+    });
+    if (!response.ok) throw new NotFoundError();
+    const found = validate(JSON.parse(await readCapped(response, MAX_BODY)), origin);
+    if (!found || !validName(found.name)) throw new NotFoundError();
+    return { ...found, origin };
+  } catch (error) {
+    throw error instanceof NotFoundError ? error : new NotFoundError();
+  }
+}

package/src/security.mjs

@@ -0,0 +1,96 @@
+// The company window may only show the company's own pages. /auth/ and
+// /callback are for the system browser, never this window. The path is
+// normalised first so %61uth, /AUTH, //auth and \auth are the same as /auth
+// (Boule's rule; Agora's was case-sensitive and did not normalise).
+export function allowedNavigation(value, origin) {
+  try {
+    const url = new URL(value);
+    const path = decodeURIComponent(url.pathname)
+      .toLowerCase()
+      .replace(/[\\/]+/g, '/');
+    return (
+      url.origin === origin &&
+      !url.username &&
+      !url.password &&
+      !/^\/(auth|callback)(\/|$)/.test(path)
+    );
+  } catch {
+    return false;
+  }
+}
+// IPC from the welcome page: that window's own top frame, showing welcome.html.
+export function trustedWelcomeSender(event, contents, welcomeUrl) {
+  if (contents.isDestroyed?.()) return false;
+  return (
+    event.sender === contents &&
+    event.senderFrame === contents.mainFrame &&
+    event.senderFrame?.url.split('#')[0] === welcomeUrl
+  );
+}
+// IPC from the company page: its own top frame, on a page it may navigate to.
+export function trustedSender(event, contents, origin) {
+  if (contents.isDestroyed?.()) return false;
+  return (
+    event.sender === contents &&
+    event.senderFrame === contents.mainFrame &&
+    event.senderFrame?.origin === origin &&
+    allowedNavigation(event.senderFrame.url, origin)
+  );
+}
+// The partition denies every permission unless the app's config lists it, and
+// then only for the company's own origin: a page that navigated elsewhere never
+// gets a look. `media` is camera and microphone (Electron says which in the
+// media type); screen sharing is a display-capture request, not a permission
+// here. `permissions` is { notifications, media } from the config.
+export function allowedPermission(permission, requestingOrigin, origin, permissions, mediaTypes) {
+  if (requestingOrigin !== origin) return false;
+  if (permission === 'notifications') return permissions.notifications;
+  return (
+    permission === 'media' &&
+    permissions.media &&
+    mediaTypes?.length > 0 &&
+    mediaTypes.every((type) => type === 'audio' || type === 'video')
+  );
+}
+export function permissionCheckHandler(origin, permissions) {
+  return (_contents, permission, requestingOrigin, details) =>
+    allowedPermission(
+      permission,
+      requestingOrigin,
+      origin,
+      permissions,
+      details?.mediaType && [details.mediaType],
+    );
+}
+export function permissionRequestHandler(origin, permissions) {
+  return (_contents, permission, callback, details) => {
+    let requestingOrigin;
+    try {
+      requestingOrigin = new URL(details?.requestingUrl ?? '').origin;
+    } catch {
+      requestingOrigin = undefined;
+    }
+    callback(
+      allowedPermission(permission, requestingOrigin, origin, permissions, details?.mediaTypes),
+    );
+  };
+}
+// `allowed` decides which URLs the contents, and every frame in it, may ever
+// navigate to. `onBlocked` hears each refused top-level navigation or redirect.
+export function secureContents(contents, allowed, onBlocked = () => {}) {
+  contents.setWindowOpenHandler(() => ({ action: 'deny' }));
+  const top = (event, url) => {
+    if (!allowed(url)) {
+      event.preventDefault();
+      onBlocked(url);
+    }
+  };
+  contents.on('will-navigate', top);
+  contents.on('will-redirect', top);
+  contents.on('will-frame-navigate', (details) => {
+    if (allowed(details.url)) return;
+    details.preventDefault();
+    if (details.isMainFrame) onBlocked(details.url);
+  });
+  contents.on('will-attach-webview', (event) => event.preventDefault());
+}