aegis-desktop 1.0.10 → 1.0.13

package/vendor/aegis.js

@@ -466,6 +466,29 @@ const RATE_LIMIT_MAX_WAIT_MS = 30000;
 /** Base for the exponential fallback when the server sends no `Retry-After`. */
 const RATE_LIMIT_BASE_WAIT_MS = 1000;
 
+/**
+ * aegis1's chat-completions generator (`app.py` `nexus_chat_completions`'s
+ * `generate()`) wraps the whole upstream provider call in one `except
+ * Exception`, and on ANY failure forwards `str(e)` as a mid-stream SSE error
+ * frame: `{"error": {"message": str(e)[:200], "type": "server_error"}}`.
+ * Headers are already sent 200 OK by then, so there is no status code to
+ * tell a reset upstream socket apart from a real bug — both arrive as
+ * `postStream` throwing with `status: 200` and the CLI/desktop host showing
+ * `(backend error: [Errno 104] Connection reset by peer)` mid-turn.
+ *
+ * Narrowed to the Python exception messages a dropped TCP connection
+ * actually produces (ConnectionResetError/BrokenPipeError/ConnectionAbortedError
+ * and their usual Errno numbers), not every empty-turn error — a model that
+ * legitimately returned nothing must still fail on the first try, not retry
+ * forever. Only safe to retry when nothing streamed yet (`fullText` empty at
+ * the throw site below): no visible content can be duplicated by redoing the
+ * whole request from scratch.
+ */
+const TRANSIENT_STREAM_ERROR_PATTERN =
+  /connection reset by peer|broken pipe|connection aborted|errno 104|errno 32|errno 54|econnreset|epipe/i;
+const TRANSIENT_STREAM_RETRIES = 2;
+const TRANSIENT_STREAM_BASE_WAIT_MS = 500;
+
 /**
  * .mcp.json / Electron pass config as "${VAR}" template refs. When the var is
  * unset, hosts have been observed to leave the template literally unexpanded
@@ -505,6 +528,78 @@ function createClient(opts = {}) {
     return value.split(apiKey).join('[redacted]');
   }
 
+  /**
+   * Transport failure codes → what actually happened, in words that point at
+   * the culprit. Names, not errno numbers, because "ECONNRESET" tells a user
+   * nothing while "the connection was reset mid-request" tells them to retry.
+   */
+  const AEGIS_NETWORK_ERROR_HINTS = {
+    ECONNRESET: 'connection reset by the backend',
+    ECONNREFUSED: 'connection refused — is the backend running?',
+    EPIPE: 'connection closed while sending the request',
+    ETIMEDOUT: 'connection timed out',
+    ENOTFOUND: 'host not found — check the endpoint URL',
+    EAI_AGAIN: 'DNS lookup failed temporarily',
+    EHOSTUNREACH: 'host unreachable',
+    ENETUNREACH: 'network unreachable',
+    CERT_HAS_EXPIRED: 'TLS certificate has expired',
+    DEPTH_ZERO_SELF_SIGNED_CERT: 'TLS certificate is self-signed',
+    UND_ERR_SOCKET: 'the socket closed before the response finished',
+    UND_ERR_CLOSED: 'the connection was closed',
+    UND_ERR_CONNECT_TIMEOUT: 'timed out connecting to the backend',
+    UND_ERR_HEADERS_TIMEOUT: 'the backend accepted the connection but never sent a response',
+    UND_ERR_BODY_TIMEOUT: 'the backend stalled mid-response',
+    UND_ERR_ABORTED: 'the request was aborted',
+  };
+
+  /**
+   * Turn a raw transport failure into something a person can act on.
+   *
+   * Node's undici raises `TypeError: fetch failed` for every socket-level
+   * fault and puts the real reason on `err.cause` (`ECONNRESET`,
+   * `UND_ERR_SOCKET`, `HeadersTimeoutError`, `ENOTFOUND`, …). Rethrown
+   * untouched, the user sees the literal string `fetch failed`, which names
+   * no component, no cause and no next step — and, worse, hides the fact that
+   * the backend is the thing that dropped us rather than a bad request.
+   *
+   * The cause code, when there is one, is the single most useful fact here,
+   * so it is promoted into `message` and kept on `cause`/`networkCode` for
+   * callers that want to branch on it. Everything else about the error is
+   * left alone.
+   */
+  function networkFailureError(err, base) {
+    const reraised = err instanceof Error ? err : new Error(String(err));
+    // The caller's own cancellation is not a failure and must stay untouched.
+    const name = reraised && reraised.name;
+    if (name === 'AbortError' || name === 'TimeoutError') return err;
+    const detail = describeNetworkCause(reraised);
+    const target = base || 'the backend';
+    const e = new Error(
+      detail
+        ? `Could not reach ${target} (${detail}).`
+        : `Could not reach ${target}: ${reraised.message || 'network failure'}.`
+    );
+    e.status = 0;
+    e.code = 'network';
+    e.networkCode = detail || null;
+    e.data = null;
+    e.cause = reraised;
+    return e;
+  }
+
+  /** The innermost human-meaningful reason from an undici error chain. */
+  function describeNetworkCause(err, depth = 0) {
+    if (!err || depth > 4) return null;
+    const code = err.code || (err.cause && err.cause.code);
+    const inner = err.cause;
+    const innerDetail = inner ? describeNetworkCause(inner, depth + 1) : null;
+    if (AEGIS_NETWORK_ERROR_HINTS[code]) return AEGIS_NETWORK_ERROR_HINTS[code];
+    if (innerDetail) return innerDetail;
+    // An undici cause often carries only a message ("other side closed").
+    if (inner && inner.message && inner.message !== err.message) return inner.message;
+    return code || null;
+  }
+
   /**
    * A bounded `fetch`: caller signal where there is one, an aborting timeout
    * where there is not. Returns the caller's abort untouched (so a host that
@@ -549,7 +644,7 @@ function createClient(opts = {}) {
         e.data = null;
         throw e;
       }
-      throw err;
+      throw networkFailureError(err, apiBase);
     } finally {
       // The timeout is time-to-*headers* only, so it is cleared the moment the
       // response resolves: a long generation must never be cut off by it.
@@ -652,6 +747,30 @@ function createClient(opts = {}) {
       await sleep(wait, init && init.signal);
       res = await boundedFetch(url, init);
     }
+    // The NON-streaming twin of postStream's mid-stream transient retry below:
+    // aegis1's chat-completions route drains the same generate() generator
+    // itself when the caller sent `stream: false`, and on the SAME exception
+    // (a reset socket to the provider) returns it as a plain 503 —
+    // `{"error":{"message":"[Errno 104] Connection reset by peer","type":
+    // "server_error"}}` — not a 200 SSE frame, because no response has been
+    // sent yet on this branch. Peeked via a clone so a non-matching body (a
+    // real 503 — insufficient balance, "not configured" — is untouched for
+    // `parseResponse` to read and surface normally, unretried.
+    for (
+      let attempt = 0;
+      res && res.status >= 500 && res.status < 600 && attempt < TRANSIENT_STREAM_RETRIES;
+      attempt++
+    ) {
+      let text = '';
+      try {
+        text = await readCappedText(res.clone());
+      } catch {
+        break; // body already disturbed or unclonable — surface res as-is
+      }
+      if (!TRANSIENT_STREAM_ERROR_PATTERN.test(text)) break;
+      await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, attempt), init && init.signal);
+      res = await boundedFetch(url, init);
+    }
     return res;
   }
 
@@ -1066,7 +1185,14 @@ function createClient(opts = {}) {
     else if (mode) body.mode = mode;
     const headers = authHeaders(agentKey ? { 'X-AEGIS-Agent-Key': agentKey } : undefined);
     if (!stream || typeof onStream !== 'function') {
-      return decodeDsmlInResult(await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers));
+      // `signal` must be forwarded here. It was not, and the consequence was
+      // silent: a caller that aborted a non-streaming turn saw the abort
+      // ignored, the request ran on to its timeout, and the eventual error was
+      // a timeout the user never asked for. postStream's own fallback at the
+      // bottom of this function always forwarded it — only this branch did not.
+      return decodeDsmlInResult(
+        await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers, { signal })
+      );
     }
     // An OpenAI-compatible SSE response carries no `usage` unless the caller
     // asks for it (`stream_options.include_usage`). Without this the streamed
@@ -1237,7 +1363,10 @@ function createClient(opts = {}) {
    * This keeps streaming purely additive for hosts that opt in.
    */
   async function postStream(path, body, headers, onStream, signal, streamOpts) {
-    const { onReasoning, idleTimeoutMs, retryWithoutStreamOptions } = streamOpts || {};
+    const {
+      onReasoning, idleTimeoutMs, retryWithoutStreamOptions,
+      _transientStreamAttempt: transientStreamAttempt = 0,
+    } = streamOpts || {};
     const request = (payload) =>
       // `boundedFetch` here bounds time-to-*headers* only: fetch resolves when
       // the status line lands, and the timer is cleared in its `finally`, so a
@@ -1545,6 +1674,16 @@ function createClient(opts = {}) {
     }
 
     if (!fullText && sseError) {
+      if (
+        transientStreamAttempt < TRANSIENT_STREAM_RETRIES
+        && TRANSIENT_STREAM_ERROR_PATTERN.test(sseError)
+      ) {
+        await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, transientStreamAttempt), signal);
+        return postStream(path, body, headers, onStream, signal, {
+          ...streamOpts,
+          _transientStreamAttempt: transientStreamAttempt + 1,
+        });
+      }
       const err = new Error(sseError);
       err.status = res.status;
       throw err;
@@ -1763,6 +1902,32 @@ function createClient(opts = {}) {
     });
   }
 
+  /**
+   * aegis1's stored Google Drive connection for this account (`GET
+   * /api/drive/token` — app.py's `get_drive_token`), authenticated with the
+   * ordinary API key (the same header `authHeaders()` already sends, which
+   * that route accepts alongside its session-cookie path). Resolves
+   * `{connected, access_token, email}` — `connected: false` with no error
+   * when this account has never run the browser's `/connect/drive` consent
+   * screen (the route's 404: a real account, just nothing saved yet), since
+   * "not yet connected" is the expected answer on every account until it
+   * does. A 401 is a DIFFERENT fact — this key is not valid at all — so it is
+   * left to throw rather than folded into the same "not connected" reading,
+   * which would hide a real credential problem behind the normal first-run
+   * state. The access token is refreshed server-side from the stored refresh
+   * token on every call, so a caller never has to reason about expiry.
+   */
+  async function driveToken() {
+    try {
+      return await apiGet('/api/drive/token');
+    } catch (e) {
+      if (e && e.status === 404) {
+        return { connected: false, access_token: null, email: null };
+      }
+      throw e;
+    }
+  }
+
   return {
     apiBase,
     get apiKey() {
@@ -1798,6 +1963,7 @@ function createClient(opts = {}) {
     conversationSyncPush,
     conversationSyncPull,
     importConversation,
+    driveToken,
     randomUUID,
   };
 }

package/vendor/credentials.js

@@ -382,8 +382,15 @@ function clientOptions(o = {}) {
   const { key } = resolveApiKey(o);
   const { token } = resolveMemoryToken(o);
   const opts = {};
-  if (key) opts.apiKey = key;
-  if (token) opts.memoryToken = token;
+  // Set explicitly, even when empty: `createClient` only re-checks its own
+  // (real, ambient) process.env when `apiKey`/`memoryToken` are `undefined`.
+  // Omitting an empty result here was indistinguishable from "not resolved
+  // yet" and let that fallback see the real environment's key even when an
+  // injected `o.env`/`o.dir` (tests, a hosted agent, a `--base` against a
+  // staging account — the reason this function takes them at all) had
+  // already and correctly resolved to "no key".
+  opts.apiKey = key;
+  opts.memoryToken = token;
   // The host names itself so upgrade prompts raised inside the shared client
   // are attributed to the right product. Unset means desktop, which matches
   // createClient's own default.

package/vendor/drive-connect.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * drive-connect.js — the desktop half of aegis1's Google Drive OAuth.
+ *
+ * aegis1 already runs the full web side of this: `/connect/drive` sends the
+ * browser through Google's consent screen with the `drive.file` scope, saves
+ * the resulting tokens on whichever account that Google identity resolves
+ * to, and lands on a static "connected" page. `/api/drive/token` then hands
+ * back a fresh (server-refreshed) access token for that account, authenticated
+ * with the ordinary AEGIS API key — see `client/aegis.js`'s `driveToken()`.
+ *
+ * Unlike `/auth/google` (see `client/google-signin.js`), `/connect/drive` has
+ * no desktop round-trip: it never redirects back to a local callback, so
+ * there is nothing here to listen for. This module does the other honest
+ * thing instead — open the browser to it, and POLL the status endpoint
+ * (this machine's own API key) until the account shows connected, or give up
+ * after a timeout. The caller provides the actual browser-opening (Electron's
+ * `shell.openExternal`); this module is Electron-free so it can be driven by
+ * a test with a stub `aegis` client and no network.
+ *
+ * ONE PRECONDITION THIS MODULE DOES NOT ENFORCE, BECAUSE IT CANNOT:
+ * `/connect/drive` resolves the account by Google identity (google_id, then
+ * email), not by whatever account this machine's API key already belongs to.
+ * So polling only ever reports connected when THIS machine is already signed
+ * in with that same Google identity — otherwise the browser attaches the
+ * Drive tokens to a different account than the one being polled, and the
+ * poll simply times out. `desktop/lib/google-connect.js` is what sequences
+ * "sign in with Google first" ahead of this.
+ */
+
+/** `${apiBase}/connect/drive` — the one URL this flow opens. */
+function driveConnectUrl(apiBase) {
+  return `${String(apiBase || '').replace(/\/+$/, '')}/connect/drive`;
+}
+
+/**
+ * One status check: is a Drive token on file for this account?
+ *
+ * @param {{driveToken: () => Promise<{connected:boolean, email?:string}>}} aegis
+ */
+async function driveStatus(aegis) {
+  const data = await aegis.driveToken();
+  return {
+    connected: Boolean(data && data.connected),
+    email: (data && data.email) || null,
+  };
+}
+
+/**
+ * Poll `driveStatus` until it reports connected, or time out.
+ *
+ * The browser round-trip has no signal of its own to wait on (unlike
+ * `startGoogleSignIn`'s local callback server), so this is the only way the
+ * caller learns the user actually finished the consent screen — or gave up
+ * on it, which is why this is bounded rather than polled forever.
+ *
+ * @param {object} aegis a client exposing `driveToken()`
+ * @param {{timeoutMs?:number, pollMs?:number, signal?:AbortSignal}} [opts]
+ */
+async function waitForDriveConnected(aegis, opts = {}) {
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 3 * 60 * 1000;
+  const pollMs = Number(opts.pollMs) > 0 ? Number(opts.pollMs) : 2000;
+  const signal = opts.signal || null;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const status = await driveStatus(aegis);
+    if (status.connected) return status;
+    if (signal && signal.aborted) {
+      const e = new Error('cancelled');
+      e.name = 'AbortError';
+      throw e;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for Google Drive to connect`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+module.exports = { driveConnectUrl, driveStatus, waitForDriveConnected };

package/vendor/drive-upload.js

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * drive-upload.js — a Drive v3 REST client, scoped to exactly one job:
+ * keep a single memory-backup file, in a single app folder, up to date.
+ *
+ * This talks to Google's API directly with the access token
+ * `client/drive-connect.js` obtains (via `/api/drive/token`) — it never goes
+ * through aegis1, and aegis1 never sees the memory content this uploads.
+ *
+ * Scoped to `drive.file` (the scope `/connect/drive` requests): that grant
+ * only ever sees files this app itself creates, which is why every write
+ * here goes through `findOrCreateFolder`/`findFileInFolder` rather than
+ * assuming some well-known id — there is no well-known id this scope could
+ * resolve, and a file this app did not create is invisible to it even by
+ * name. One stable file is overwritten in place on every sync rather than
+ * creating a new one each time, so a daily backup habit does not pile up a
+ * thousand same-named files with no way to tell them apart.
+ */
+
+const DRIVE_FILES_URL = 'https://www.googleapis.com/drive/v3/files';
+const DRIVE_UPLOAD_URL = 'https://www.googleapis.com/upload/drive/v3/files';
+const FOLDER_MIME = 'application/vnd.google-apps.folder';
+const BOUNDARY = 'aegiscode-drive-upload-boundary';
+
+const DEFAULT_FOLDER = 'AEGIS Memory';
+const DEFAULT_FILE = 'aegis-memory-backup.json';
+
+function resolveFetch(fetchImpl) {
+  const f = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!f) throw new Error('drive: this Node has no global fetch — upgrade to Node 22+');
+  return f;
+}
+
+/** Escape a value for Drive's `q=` string-literal quoting rules. */
+function escapeQ(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+async function driveRequest(fetchImpl, url, { method = 'GET', accessToken, body, headers } = {}) {
+  const f = resolveFetch(fetchImpl);
+  const res = await f(url, {
+    method,
+    headers: { Authorization: `Bearer ${accessToken}`, ...(headers || {}) },
+    body,
+  });
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+  if (!res.ok) {
+    const rawMsg = (data && data.error && (data.error.message || data.error)) || text.slice(0, 200) || `HTTP ${res.status}`;
+    const err = new Error(`drive: ${method} ${url.split('?')[0]} failed — ${typeof rawMsg === 'string' ? rawMsg : JSON.stringify(rawMsg)}`);
+    err.status = res.status;
+    err.data = data;
+    throw err;
+  }
+  return data || {};
+}
+
+/** The first file matching an exact query, or null. */
+async function findOne(fetchImpl, accessToken, query) {
+  const url = `${DRIVE_FILES_URL}?q=${encodeURIComponent(query)}&fields=${encodeURIComponent('files(id,name)')}&pageSize=1`;
+  const data = await driveRequest(fetchImpl, url, { accessToken });
+  const files = Array.isArray(data.files) ? data.files : [];
+  return files[0] || null;
+}
+
+/** This app's folder by name, creating it the first time. Returns its id. */
+async function findOrCreateFolder(accessToken, name, { fetchImpl } = {}) {
+  const query = `mimeType='${FOLDER_MIME}' and name='${escapeQ(name)}' and trashed=false`;
+  const existing = await findOne(fetchImpl, accessToken, query);
+  if (existing) return existing.id;
+  const created = await driveRequest(fetchImpl, DRIVE_FILES_URL, {
+    method: 'POST',
+    accessToken,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, mimeType: FOLDER_MIME }),
+  });
+  return created.id;
+}
+
+/** One file by name inside a given folder, or null. */
+async function findFileInFolder(accessToken, name, folderId, { fetchImpl } = {}) {
+  const query = `'${escapeQ(folderId)}' in parents and name='${escapeQ(name)}' and trashed=false`;
+  return findOne(fetchImpl, accessToken, query);
+}
+
+/**
+ * Create a new file: a multipart/related body (metadata part naming the
+ * parent folder, content part carrying the bytes) — the shape Drive's
+ * `uploadType=multipart` requires for a create, since a plain media upload
+ * has nowhere to say which folder the file belongs in.
+ */
+async function createFile(accessToken, { name, folderId, content, mimeType }, { fetchImpl } = {}) {
+  const metadata = JSON.stringify({ name, parents: [folderId] });
+  const body =
+    `--${BOUNDARY}\r\n` +
+    `Content-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n` +
+    `--${BOUNDARY}\r\n` +
+    `Content-Type: ${mimeType}\r\n\r\n${content}\r\n` +
+    `--${BOUNDARY}--`;
+  return driveRequest(
+    fetchImpl,
+    `${DRIVE_UPLOAD_URL}?uploadType=multipart&fields=${encodeURIComponent('id,webViewLink')}`,
+    {
+      method: 'POST',
+      accessToken,
+      headers: { 'Content-Type': `multipart/related; boundary=${BOUNDARY}` },
+      body,
+    }
+  );
+}
+
+/**
+ * Overwrite an existing file's content in place. A plain media upload is
+ * enough here — the name and parent folder never change on a resync, so
+ * there is nothing a metadata part would need to say.
+ */
+async function updateFileContent(accessToken, fileId, content, mimeType, { fetchImpl } = {}) {
+  return driveRequest(
+    fetchImpl,
+    `${DRIVE_UPLOAD_URL}/${encodeURIComponent(fileId)}?uploadType=media&fields=${encodeURIComponent('id,webViewLink')}`,
+    {
+      method: 'PATCH',
+      accessToken,
+      headers: { 'Content-Type': mimeType },
+      body: content,
+    }
+  );
+}
+
+/**
+ * Upload (create or overwrite) one memory backup file in the user's Drive.
+ *
+ * @param {string} accessToken a live Drive access token (client/drive-connect.js / aegis.driveToken())
+ * @param {string} content the file's bytes — the caller serialises; this module never shapes the memory export itself
+ * @param {{folderName?:string, fileName?:string, mimeType?:string, fetchImpl?:Function}} [opts]
+ * @returns {Promise<{fileId:string, webViewLink:string|null, updated:boolean}>}
+ */
+async function uploadMemoryBackup(accessToken, content, opts = {}) {
+  const folderName = opts.folderName || DEFAULT_FOLDER;
+  const fileName = opts.fileName || DEFAULT_FILE;
+  const mimeType = opts.mimeType || 'application/json';
+  const fetchImpl = opts.fetchImpl;
+
+  const folderId = await findOrCreateFolder(accessToken, folderName, { fetchImpl });
+  const existing = await findFileInFolder(accessToken, fileName, folderId, { fetchImpl });
+  const result = existing
+    ? await updateFileContent(accessToken, existing.id, content, mimeType, { fetchImpl })
+    : await createFile(accessToken, { name: fileName, folderId, content, mimeType }, { fetchImpl });
+
+  return {
+    fileId: result.id || (existing && existing.id) || null,
+    webViewLink: result.webViewLink || null,
+    updated: Boolean(existing),
+  };
+}
+
+module.exports = {
+  DEFAULT_FOLDER,
+  DEFAULT_FILE,
+  findOrCreateFolder,
+  findFileInFolder,
+  createFile,
+  updateFileContent,
+  uploadMemoryBackup,
+};

package/vendor/google-signin.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * Sign this machine in with the user's actual Google identity, instead of the
+ * anonymous per-machine key `auto-provision.js`/`connect.js` mint by default.
+ *
+ * aegis1 already runs the full web side of this (`app.py`: `/auth/google`,
+ * `/auth/callback/google`) including a desktop round-trip it was built for:
+ * pass `?callback=http://127.0.0.1:{port}` and, once the browser finishes the
+ * Google consent screen, aegis1 redirects the browser back to that local
+ * address with `token`, `username` and (when available) `memory_token` as
+ * query params. Nothing here talks to Google or to aegis1 directly — this
+ * module only runs the localhost half of that round-trip: open a one-shot
+ * HTTP server, hand the caller the URL to open, and resolve once the browser
+ * comes back to it.
+ *
+ * `token` IS the ordinary AEGIS API key for the account aegis1 resolved
+ * (looked up or created by `google_id`/email) — there is no second credential
+ * format to support. The caller saves it exactly as `register-device`'s key,
+ * through `credentials.saveApiKey`.
+ */
+
+const http = require('node:http');
+const { URL } = require('node:url');
+
+/** Escapes text placed into the one-shot HTML page — the values riding in the
+ * query string came back through the user's browser, so treat them as
+ * untrusted even though this server only ever talks to localhost. */
+function escapeHtml(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+function page({ ok, error, username }) {
+  const title = ok ? 'Signed in' : 'Sign-in failed';
+  const body = ok
+    ? `Signed in${username ? ` as <b>${escapeHtml(username)}</b>` : ''}. You can close this tab and return to the terminal.`
+    : `Sign-in failed: ${escapeHtml(error || 'no token was returned')}. You can close this tab and try again.`;
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${title} — AEGIS</title></head>` +
+    `<body style="font:16px sans-serif;max-width:32rem;margin:4rem auto;text-align:center;">` +
+    `<h2>${title}</h2><p>${body}</p></body></html>`;
+}
+
+/** `${apiBase}/auth/google?callback=${callbackUrl}` — the one URL this flow opens. */
+function buildAuthUrl(apiBase, callbackUrl) {
+  const url = new URL('/auth/google', apiBase);
+  url.searchParams.set('callback', callbackUrl);
+  return url.toString();
+}
+
+/**
+ * Starts the local callback server and returns the URL to open, plus a
+ * `wait()` that resolves once the browser lands on it.
+ *
+ * Only a request that carries `token` or `error` ends the wait — anything
+ * else (a browser pre-connect, `/favicon.ico`) gets a plain 404 and the
+ * server keeps listening for the real one.
+ *
+ * @returns {Promise<{url: string, wait: () => Promise<{apiKey:string, username:?string, memoryToken:?string}>}>}
+ */
+async function startGoogleSignIn({ apiBase, host = '127.0.0.1', timeoutMs = 5 * 60 * 1000 } = {}) {
+  if (!apiBase) throw new Error('startGoogleSignIn requires apiBase');
+
+  let settled = false;
+  let resolveResult;
+  let rejectResult;
+  const result = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const server = http.createServer((req, res) => {
+    let parsed;
+    try {
+      parsed = new URL(req.url, `http://${host}`);
+    } catch {
+      res.writeHead(400).end();
+      return;
+    }
+    const token = parsed.searchParams.get('token');
+    const username = parsed.searchParams.get('username');
+    const memoryToken = parsed.searchParams.get('memory_token');
+    const error = parsed.searchParams.get('error');
+
+    if (!token && !error) {
+      res.writeHead(404).end();
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(page({ ok: Boolean(token), error, username }));
+
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    server.close();
+    if (token) resolveResult({ apiKey: token, username: username || null, memoryToken: memoryToken || null });
+    else rejectResult(new Error(error || 'no token was returned'));
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, host, resolve);
+  });
+
+  const { port } = server.address();
+  const callbackUrl = `http://${host}:${port}`;
+  const url = buildAuthUrl(apiBase, callbackUrl);
+
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    server.close();
+    rejectResult(new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser sign-in`));
+  }, timeoutMs);
+  // A pending timer must not keep the process alive just for this wait.
+  if (typeof timer.unref === 'function') timer.unref();
+
+  return { url, wait: () => result };
+}
+
+module.exports = { startGoogleSignIn, buildAuthUrl };