aegiscode 7.0.12 → 7.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -466,6 +466,70 @@ const RATE_LIMIT_MAX_WAIT_MS = 30000;
466
466
  /** Base for the exponential fallback when the server sends no `Retry-After`. */
467
467
  const RATE_LIMIT_BASE_WAIT_MS = 1000;
468
468
 
469
+ /**
470
+ * aegis1's chat-completions generator (`app.py` `nexus_chat_completions`'s
471
+ * `generate()`) wraps the whole upstream provider call in one `except
472
+ * Exception`, and on ANY failure forwards `str(e)` as a mid-stream SSE error
473
+ * frame: `{"error": {"message": str(e)[:200], "type": "server_error"}}`.
474
+ * Headers are already sent 200 OK by then, so there is no status code to
475
+ * tell a reset upstream socket apart from a real bug — both arrive as
476
+ * `postStream` throwing with `status: 200` and the CLI/desktop host showing
477
+ * `(backend error: [Errno 104] Connection reset by peer)` mid-turn.
478
+ *
479
+ * Narrowed to the Python exception messages a dropped TCP connection
480
+ * actually produces (ConnectionResetError/BrokenPipeError/ConnectionAbortedError
481
+ * and their usual Errno numbers), not every empty-turn error — a model that
482
+ * legitimately returned nothing must still fail on the first try, not retry
483
+ * forever. Only safe to retry when nothing streamed yet (`fullText` empty at
484
+ * the throw site below): no visible content can be duplicated by redoing the
485
+ * whole request from scratch.
486
+ */
487
+ const TRANSIENT_STREAM_ERROR_PATTERN =
488
+ /connection reset by peer|broken pipe|connection aborted|errno 104|errno 32|errno 54|econnreset|epipe/i;
489
+ const TRANSIENT_STREAM_RETRIES = 2;
490
+ const TRANSIENT_STREAM_BASE_WAIT_MS = 500;
491
+
492
+ /**
493
+ * The sentence aegis1 puts in a mid-stream error frame when the UPSTREAM
494
+ * provider call it was relaying hit its own deadline. Deliberately kept out of
495
+ * TRANSIENT_STREAM_ERROR_PATTERN: a socket reset is worth re-issuing at once,
496
+ * but a provider timeout has already spent a full deadline, so the same retry
497
+ * would make a stuck upstream cost three of them before anything was said.
498
+ *
499
+ * It still has to be CLASSIFIED, not passed through raw. The frame arrives
500
+ * after the stream's own 200 OK, so `res.status` is 200 — the throw used to be
501
+ * stamped with that and reached the desktop host as `{ status: 200 }`, which
502
+ * reads as a success to every downstream branch (engine.js keys its recovery
503
+ * on `status === 402`/`400`; the renderer keys "waited too long" on status 0).
504
+ */
505
+ const SSE_UPSTREAM_TIMEOUT_PATTERN = /request timed out|timed out waiting|upstream timeout/i;
506
+
507
+ /**
508
+ * The message for a provider timeout, stating whose deadline expired.
509
+ *
510
+ * This used to read "the provider returned no answer within the 60s stream
511
+ * budget (raise AEGIS_SSE_IDLE_TIMEOUT_MS for a slower provider)". Measured
512
+ * live, that sentence was false in the one case it fired: the provider gave up
513
+ * in ~11-13s and aegis1 relayed it, so the client's own watchdog never fired at
514
+ * all — `sseError` is only ever set from a `json.error` frame, and our stall
515
+ * raises its own `stream stalled - …` error from `readWithIdleTimeout` instead.
516
+ * The advice pointed at an env var that provably cannot help, which is worse
517
+ * than saying nothing: a user follows it, restarts, and the turn still fails.
518
+ *
519
+ * So the message separates the two deadlines and names elapsed time, which is
520
+ * the fact that tells a reader which one it was without trusting the prose.
521
+ * `elapsedMs` is omitted when the caller has no measured start (the
522
+ * non-streaming path), rather than inventing one.
523
+ */
524
+ function upstreamTimeoutMessage(base, elapsedMs) {
525
+ const took = Number(elapsedMs) > 0 ? ` after ${(Number(elapsedMs) / 1000).toFixed(1)}s` : '';
526
+ return (
527
+ `${base} — the upstream provider gave up before answering${took}. ` +
528
+ "That is the provider's own deadline, not this client's stream budget, so " +
529
+ 'raising AEGIS_SSE_IDLE_TIMEOUT_MS cannot help'
530
+ );
531
+ }
532
+
469
533
  /**
470
534
  * .mcp.json / Electron pass config as "${VAR}" template refs. When the var is
471
535
  * unset, hosts have been observed to leave the template literally unexpanded
@@ -505,6 +569,78 @@ function createClient(opts = {}) {
505
569
  return value.split(apiKey).join('[redacted]');
506
570
  }
507
571
 
572
+ /**
573
+ * Transport failure codes → what actually happened, in words that point at
574
+ * the culprit. Names, not errno numbers, because "ECONNRESET" tells a user
575
+ * nothing while "the connection was reset mid-request" tells them to retry.
576
+ */
577
+ const AEGIS_NETWORK_ERROR_HINTS = {
578
+ ECONNRESET: 'connection reset by the backend',
579
+ ECONNREFUSED: 'connection refused — is the backend running?',
580
+ EPIPE: 'connection closed while sending the request',
581
+ ETIMEDOUT: 'connection timed out',
582
+ ENOTFOUND: 'host not found — check the endpoint URL',
583
+ EAI_AGAIN: 'DNS lookup failed temporarily',
584
+ EHOSTUNREACH: 'host unreachable',
585
+ ENETUNREACH: 'network unreachable',
586
+ CERT_HAS_EXPIRED: 'TLS certificate has expired',
587
+ DEPTH_ZERO_SELF_SIGNED_CERT: 'TLS certificate is self-signed',
588
+ UND_ERR_SOCKET: 'the socket closed before the response finished',
589
+ UND_ERR_CLOSED: 'the connection was closed',
590
+ UND_ERR_CONNECT_TIMEOUT: 'timed out connecting to the backend',
591
+ UND_ERR_HEADERS_TIMEOUT: 'the backend accepted the connection but never sent a response',
592
+ UND_ERR_BODY_TIMEOUT: 'the backend stalled mid-response',
593
+ UND_ERR_ABORTED: 'the request was aborted',
594
+ };
595
+
596
+ /**
597
+ * Turn a raw transport failure into something a person can act on.
598
+ *
599
+ * Node's undici raises `TypeError: fetch failed` for every socket-level
600
+ * fault and puts the real reason on `err.cause` (`ECONNRESET`,
601
+ * `UND_ERR_SOCKET`, `HeadersTimeoutError`, `ENOTFOUND`, …). Rethrown
602
+ * untouched, the user sees the literal string `fetch failed`, which names
603
+ * no component, no cause and no next step — and, worse, hides the fact that
604
+ * the backend is the thing that dropped us rather than a bad request.
605
+ *
606
+ * The cause code, when there is one, is the single most useful fact here,
607
+ * so it is promoted into `message` and kept on `cause`/`networkCode` for
608
+ * callers that want to branch on it. Everything else about the error is
609
+ * left alone.
610
+ */
611
+ function networkFailureError(err, base) {
612
+ const reraised = err instanceof Error ? err : new Error(String(err));
613
+ // The caller's own cancellation is not a failure and must stay untouched.
614
+ const name = reraised && reraised.name;
615
+ if (name === 'AbortError' || name === 'TimeoutError') return err;
616
+ const detail = describeNetworkCause(reraised);
617
+ const target = base || 'the backend';
618
+ const e = new Error(
619
+ detail
620
+ ? `Could not reach ${target} (${detail}).`
621
+ : `Could not reach ${target}: ${reraised.message || 'network failure'}.`
622
+ );
623
+ e.status = 0;
624
+ e.code = 'network';
625
+ e.networkCode = detail || null;
626
+ e.data = null;
627
+ e.cause = reraised;
628
+ return e;
629
+ }
630
+
631
+ /** The innermost human-meaningful reason from an undici error chain. */
632
+ function describeNetworkCause(err, depth = 0) {
633
+ if (!err || depth > 4) return null;
634
+ const code = err.code || (err.cause && err.cause.code);
635
+ const inner = err.cause;
636
+ const innerDetail = inner ? describeNetworkCause(inner, depth + 1) : null;
637
+ if (AEGIS_NETWORK_ERROR_HINTS[code]) return AEGIS_NETWORK_ERROR_HINTS[code];
638
+ if (innerDetail) return innerDetail;
639
+ // An undici cause often carries only a message ("other side closed").
640
+ if (inner && inner.message && inner.message !== err.message) return inner.message;
641
+ return code || null;
642
+ }
643
+
508
644
  /**
509
645
  * A bounded `fetch`: caller signal where there is one, an aborting timeout
510
646
  * where there is not. Returns the caller's abort untouched (so a host that
@@ -549,7 +685,7 @@ function createClient(opts = {}) {
549
685
  e.data = null;
550
686
  throw e;
551
687
  }
552
- throw err;
688
+ throw networkFailureError(err, apiBase);
553
689
  } finally {
554
690
  // The timeout is time-to-*headers* only, so it is cleared the moment the
555
691
  // response resolves: a long generation must never be cut off by it.
@@ -652,6 +788,30 @@ function createClient(opts = {}) {
652
788
  await sleep(wait, init && init.signal);
653
789
  res = await boundedFetch(url, init);
654
790
  }
791
+ // The NON-streaming twin of postStream's mid-stream transient retry below:
792
+ // aegis1's chat-completions route drains the same generate() generator
793
+ // itself when the caller sent `stream: false`, and on the SAME exception
794
+ // (a reset socket to the provider) returns it as a plain 503 —
795
+ // `{"error":{"message":"[Errno 104] Connection reset by peer","type":
796
+ // "server_error"}}` — not a 200 SSE frame, because no response has been
797
+ // sent yet on this branch. Peeked via a clone so a non-matching body (a
798
+ // real 503 — insufficient balance, "not configured" — is untouched for
799
+ // `parseResponse` to read and surface normally, unretried.
800
+ for (
801
+ let attempt = 0;
802
+ res && res.status >= 500 && res.status < 600 && attempt < TRANSIENT_STREAM_RETRIES;
803
+ attempt++
804
+ ) {
805
+ let text = '';
806
+ try {
807
+ text = await readCappedText(res.clone());
808
+ } catch {
809
+ break; // body already disturbed or unclonable — surface res as-is
810
+ }
811
+ if (!TRANSIENT_STREAM_ERROR_PATTERN.test(text)) break;
812
+ await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, attempt), init && init.signal);
813
+ res = await boundedFetch(url, init);
814
+ }
655
815
  return res;
656
816
  }
657
817
 
@@ -863,7 +1023,32 @@ function createClient(opts = {}) {
863
1023
  (data && (data.error?.message || data.error || data.message)) ||
864
1024
  `HTTP ${res.status}`;
865
1025
  const err = new Error(redact(typeof msg === 'string' ? msg : JSON.stringify(msg)));
866
- err.status = res.status;
1026
+ // The buffered twin of postStream's upstream-timeout classification.
1027
+ //
1028
+ // Aegis1 answers a NON-streaming request by draining the same generator
1029
+ // itself, so the provider's deadline arrives here as a plain 503 carrying
1030
+ // the same sentence a streaming caller gets as an error frame. Without
1031
+ // this the one failure had two shapes depending on wire form: the stream
1032
+ // path said `status 0 / code timeout` with an explanation, while the
1033
+ // buffered path said `status 503 / code undefined` and nothing else —
1034
+ // measured live, same provider, same 10s wall, ~10.8s either way. A host
1035
+ // gating on `code === 'timeout'` therefore saw it on one path only.
1036
+ //
1037
+ // Status becomes 0 for the same reason as the stream path: this is
1038
+ // "waited too long", which every downstream branch already reads as
1039
+ // status 0 + code, and a 5xx would instead be taken as a server fault.
1040
+ // The server's own number is preserved on `serverStatus`, because 5xx is
1041
+ // worth knowing even when it means the same thing to the caller.
1042
+ const upstreamTimeout =
1043
+ res.status >= 500 && res.status < 600 && SSE_UPSTREAM_TIMEOUT_PATTERN.test(err.message);
1044
+ if (upstreamTimeout) {
1045
+ err.serverStatus = res.status;
1046
+ err.status = 0;
1047
+ err.code = 'timeout';
1048
+ err.message = upstreamTimeoutMessage(err.message);
1049
+ } else {
1050
+ err.status = res.status;
1051
+ }
867
1052
  err.data = data;
868
1053
  throw err;
869
1054
  }
@@ -1066,7 +1251,14 @@ function createClient(opts = {}) {
1066
1251
  else if (mode) body.mode = mode;
1067
1252
  const headers = authHeaders(agentKey ? { 'X-AEGIS-Agent-Key': agentKey } : undefined);
1068
1253
  if (!stream || typeof onStream !== 'function') {
1069
- return decodeDsmlInResult(await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers));
1254
+ // `signal` must be forwarded here. It was not, and the consequence was
1255
+ // silent: a caller that aborted a non-streaming turn saw the abort
1256
+ // ignored, the request ran on to its timeout, and the eventual error was
1257
+ // a timeout the user never asked for. postStream's own fallback at the
1258
+ // bottom of this function always forwarded it — only this branch did not.
1259
+ return decodeDsmlInResult(
1260
+ await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers, { signal })
1261
+ );
1070
1262
  }
1071
1263
  // An OpenAI-compatible SSE response carries no `usage` unless the caller
1072
1264
  // asks for it (`stream_options.include_usage`). Without this the streamed
@@ -1136,6 +1328,29 @@ function createClient(opts = {}) {
1136
1328
  baseURL,
1137
1329
  } = {}) {
1138
1330
  const key = providerKey !== undefined ? providerKey : opts.providerKey;
1331
+ // `custom` is the one catalog provider whose address the server does NOT
1332
+ // know: every other id maps to a host aegis1 has baked in, and `custom`
1333
+ // travels as `base_url` on each request instead. So a custom call that
1334
+ // names no endpoint is not "a provider we can guess a default for" — there
1335
+ // is no default to guess, and aegis1 answers 400 (`_byok_custom_base_url`
1336
+ // refuses it). Refusing HERE turns that server-side 400 into a client-side
1337
+ // sentence naming the missing half, which is the difference between "custom
1338
+ // is broken" and "you saved a key but never saved the endpoint".
1339
+ //
1340
+ // Reachable without the card: `/byok-key custom <key>` saves a key alone,
1341
+ // and a hand-edited row can hold a key with no address. Guarded on the
1342
+ // value actually being absent (`!baseURL`), never on the provider alone, so
1343
+ // a correctly-saved custom row is untouched.
1344
+ if (provider === 'custom' && !baseURL) {
1345
+ const err = new Error(
1346
+ 'the "custom" provider dials the endpoint you name, and this call names none — ' +
1347
+ 'save the address first: /model-add custom <https-base-url> <api-key> <model-id>, ' +
1348
+ 'or the endpoint field in Settings › Provider (custom).'
1349
+ );
1350
+ err.status = 400;
1351
+ err.code = 'custom_endpoint_missing';
1352
+ throw err;
1353
+ }
1139
1354
  // Same rule as the pooled path above: omit `max_tokens` entirely when the
1140
1355
  // caller states none, rather than inventing a default. The server treats a
1141
1356
  // body max_tokens as a ceiling *over* its own ladder, so a defaulted 4096
@@ -1237,7 +1452,10 @@ function createClient(opts = {}) {
1237
1452
  * This keeps streaming purely additive for hosts that opt in.
1238
1453
  */
1239
1454
  async function postStream(path, body, headers, onStream, signal, streamOpts) {
1240
- const { onReasoning, idleTimeoutMs, retryWithoutStreamOptions } = streamOpts || {};
1455
+ const {
1456
+ onReasoning, idleTimeoutMs, retryWithoutStreamOptions,
1457
+ _transientStreamAttempt: transientStreamAttempt = 0,
1458
+ } = streamOpts || {};
1241
1459
  const request = (payload) =>
1242
1460
  // `boundedFetch` here bounds time-to-*headers* only: fetch resolves when
1243
1461
  // the status line lands, and the timer is cleared in its `finally`, so a
@@ -1377,6 +1595,11 @@ function createClient(opts = {}) {
1377
1595
  // moves `lastPayloadAt` below.
1378
1596
  const idleMs = idleBudgetFor(res, idleTimeoutMs);
1379
1597
  let lastPayloadAt = Date.now();
1598
+ // When this response began, for the one place that needs to tell the two
1599
+ // deadlines apart: a provider timeout frame carries no duration, and the
1600
+ // elapsed time is what separates "the upstream gave up" (seconds, well
1601
+ // inside our budget) from "our own watchdog fired" (the full budget).
1602
+ const streamStartedAt = lastPayloadAt;
1380
1603
  let keepAlives = 0;
1381
1604
  async function readWithIdleTimeout() {
1382
1605
  let timer;
@@ -1545,8 +1768,49 @@ function createClient(opts = {}) {
1545
1768
  }
1546
1769
 
1547
1770
  if (!fullText && sseError) {
1548
- const err = new Error(sseError);
1549
- err.status = res.status;
1771
+ if (
1772
+ transientStreamAttempt < TRANSIENT_STREAM_RETRIES
1773
+ && TRANSIENT_STREAM_ERROR_PATTERN.test(sseError)
1774
+ ) {
1775
+ await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, transientStreamAttempt), signal);
1776
+ return postStream(path, body, headers, onStream, signal, {
1777
+ ...streamOpts,
1778
+ _transientStreamAttempt: transientStreamAttempt + 1,
1779
+ });
1780
+ }
1781
+ // Deliberately NOT retried: this sentence is aegis1 relaying an upstream
1782
+ // abort ("Provider request timed out") as a mid-stream error frame with
1783
+ // the headers already 200 OK — the same frame shape as the reset above,
1784
+ // but the stall has already cost the caller a full provider deadline, and
1785
+ // re-issuing would make a stuck upstream cost three of them before the
1786
+ // host could say anything. One attempt, classified, and out.
1787
+ //
1788
+ // What must NOT happen is the shape this used to be thrown in: `res.status`
1789
+ // here is the SSE response's own 200 (the headers landed long before the
1790
+ // error frame did), so the rejection carried "success" as its status and
1791
+ // nothing downstream could classify it — the desktop host printed the raw
1792
+ // stack with `{ status: 200 }` for a turn that never produced a byte. A
1793
+ // timeout is stated in the shape every other "waited too long" on this
1794
+ // lane uses (status 0 + a code), which is what engine.js's `status === 402`
1795
+ // / `status === 400` branches already key off and what local.js translates
1796
+ // its own two clocks into — so "waited too long" stays one branch for
1797
+ // every class.
1798
+ //
1799
+ // Message: the budget is NOT named as the cause any more, because this
1800
+ // branch cannot be our own watchdog. `sseError` comes only from a
1801
+ // `json.error` frame the server sent; our watchdog raises `stream
1802
+ // stalled - …` out of readWithIdleTimeout and never reaches this code.
1803
+ // So every error here is the provider's deadline, already expired, and
1804
+ // the elapsed time says so as a fact rather than as prose — see
1805
+ // upstreamTimeoutMessage().
1806
+ const timedOut = SSE_UPSTREAM_TIMEOUT_PATTERN.test(sseError);
1807
+ const err = new Error(
1808
+ timedOut
1809
+ ? upstreamTimeoutMessage(sseError, Date.now() - streamStartedAt)
1810
+ : sseError
1811
+ );
1812
+ err.status = timedOut ? 0 : res.status;
1813
+ if (timedOut) err.code = 'timeout';
1550
1814
  throw err;
1551
1815
  }
1552
1816
 
@@ -1763,6 +2027,32 @@ function createClient(opts = {}) {
1763
2027
  });
1764
2028
  }
1765
2029
 
2030
+ /**
2031
+ * aegis1's stored Google Drive connection for this account (`GET
2032
+ * /api/drive/token` — app.py's `get_drive_token`), authenticated with the
2033
+ * ordinary API key (the same header `authHeaders()` already sends, which
2034
+ * that route accepts alongside its session-cookie path). Resolves
2035
+ * `{connected, access_token, email}` — `connected: false` with no error
2036
+ * when this account has never run the browser's `/connect/drive` consent
2037
+ * screen (the route's 404: a real account, just nothing saved yet), since
2038
+ * "not yet connected" is the expected answer on every account until it
2039
+ * does. A 401 is a DIFFERENT fact — this key is not valid at all — so it is
2040
+ * left to throw rather than folded into the same "not connected" reading,
2041
+ * which would hide a real credential problem behind the normal first-run
2042
+ * state. The access token is refreshed server-side from the stored refresh
2043
+ * token on every call, so a caller never has to reason about expiry.
2044
+ */
2045
+ async function driveToken() {
2046
+ try {
2047
+ return await apiGet('/api/drive/token');
2048
+ } catch (e) {
2049
+ if (e && e.status === 404) {
2050
+ return { connected: false, access_token: null, email: null };
2051
+ }
2052
+ throw e;
2053
+ }
2054
+ }
2055
+
1766
2056
  return {
1767
2057
  apiBase,
1768
2058
  get apiKey() {
@@ -1798,6 +2088,7 @@ function createClient(opts = {}) {
1798
2088
  conversationSyncPush,
1799
2089
  conversationSyncPull,
1800
2090
  importConversation,
2091
+ driveToken,
1801
2092
  randomUUID,
1802
2093
  };
1803
2094
  }
@@ -0,0 +1,112 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-or-later
2
+ // Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
3
+ // AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
4
+ // Conveying a modified copy, or running one as a network service, owes the
5
+ // corresponding source under this licence (§5/§13) — see LICENSING.md.
6
+ 'use strict';
7
+
8
+ /**
9
+ * drive-connect.js — the desktop half of aegis1's Google Drive OAuth.
10
+ *
11
+ * aegis1 already runs the full web side of this: `/connect/drive` sends the
12
+ * browser through Google's consent screen with the `drive.file` scope, saves
13
+ * the resulting tokens on whichever account that Google identity resolves
14
+ * to, and lands on a static "connected" page. `/api/drive/token` then hands
15
+ * back a fresh (server-refreshed) access token for that account, authenticated
16
+ * with the ordinary AEGIS API key — see `client/aegis.js`'s `driveToken()`.
17
+ *
18
+ * Unlike `/auth/google` (see `client/google-signin.js`), `/connect/drive` has
19
+ * no desktop round-trip: it never redirects back to a local callback, so
20
+ * there is nothing here to listen for. This module does the other honest
21
+ * thing instead — open the browser to it, and POLL the status endpoint
22
+ * (this machine's own API key) until the account shows connected, or give up
23
+ * after a timeout. The caller provides the actual browser-opening (Electron's
24
+ * `shell.openExternal`); this module is Electron-free so it can be driven by
25
+ * a test with a stub `aegis` client and no network.
26
+ *
27
+ * ONE PRECONDITION THIS MODULE DOES NOT ENFORCE, BECAUSE IT CANNOT:
28
+ * `/connect/drive` resolves the account by Google identity (google_id, then
29
+ * email), not by whatever account this machine's API key already belongs to.
30
+ * So polling only ever reports connected when THIS machine is already signed
31
+ * in with that same Google identity — otherwise the browser attaches the
32
+ * Drive tokens to a different account than the one being polled, and the
33
+ * poll simply times out. `desktop/lib/google-connect.js` is what sequences
34
+ * "sign in with Google first" ahead of this.
35
+ */
36
+
37
+ /** `${apiBase}/connect/drive` — the one URL this flow opens. */
38
+ function driveConnectUrl(apiBase) {
39
+ return `${String(apiBase || '').replace(/\/+$/, '')}/connect/drive`;
40
+ }
41
+
42
+ /**
43
+ * One status check: is a Drive token on file for this account, and is the
44
+ * account tied to a Google identity at all?
45
+ *
46
+ * `googleLinked` comes from the server (`/api/drive/token`'s `google_linked`,
47
+ * derived from `users.google_id`) and is NOT the same question as "does this
48
+ * machine have an API key". Every install auto-provisions an anonymous device
49
+ * key, so a key always exists while the account behind it may never have
50
+ * touched Google. Connecting Drive in that state attaches the tokens to
51
+ * whatever Google account the browser happens to hold — a different account
52
+ * than the one this machine polls — and the poll just times out. Callers need
53
+ * this flag to refuse that ordering.
54
+ *
55
+ * Older servers answer `google_linked` not at all; a connected account is
56
+ * proof enough (only a Google round-trip can store those tokens), so a
57
+ * missing flag next to a live token reads as linked rather than as a
58
+ * regression that would disable the button for everyone.
59
+ *
60
+ * @param {{driveToken: () => Promise<{connected:boolean, email?:string, google_linked?:boolean}>}} aegis
61
+ */
62
+ async function driveStatus(aegis) {
63
+ const data = await aegis.driveToken();
64
+ const connected = Boolean(data && data.connected);
65
+ const raw = data && data.google_linked;
66
+ // Did the server actually answer the question? A server that predates the
67
+ // field omits it entirely, and an account with no Drive token answers 404
68
+ // with no flag — both look exactly like an explicit `false` once collapsed
69
+ // to a boolean. Callers that must not block a real sign-in need to tell
70
+ // "not linked" apart from "nobody asked the server".
71
+ const known = typeof raw === 'boolean';
72
+ return {
73
+ connected,
74
+ googleLinked: connected || raw === true,
75
+ googleLinkedKnown: known || connected,
76
+ email: (data && data.email) || null,
77
+ };
78
+ }
79
+
80
+ /**
81
+ * Poll `driveStatus` until it reports connected, or time out.
82
+ *
83
+ * The browser round-trip has no signal of its own to wait on (unlike
84
+ * `startGoogleSignIn`'s local callback server), so this is the only way the
85
+ * caller learns the user actually finished the consent screen — or gave up
86
+ * on it, which is why this is bounded rather than polled forever.
87
+ *
88
+ * @param {object} aegis a client exposing `driveToken()`
89
+ * @param {{timeoutMs?:number, pollMs?:number, signal?:AbortSignal}} [opts]
90
+ */
91
+ async function waitForDriveConnected(aegis, opts = {}) {
92
+ const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 3 * 60 * 1000;
93
+ const pollMs = Number(opts.pollMs) > 0 ? Number(opts.pollMs) : 2000;
94
+ const signal = opts.signal || null;
95
+ const deadline = Date.now() + timeoutMs;
96
+
97
+ for (;;) {
98
+ const status = await driveStatus(aegis);
99
+ if (status.connected) return status;
100
+ if (signal && signal.aborted) {
101
+ const e = new Error('cancelled');
102
+ e.name = 'AbortError';
103
+ throw e;
104
+ }
105
+ if (Date.now() >= deadline) {
106
+ throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for Google Drive to connect`);
107
+ }
108
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
109
+ }
110
+ }
111
+
112
+ module.exports = { driveConnectUrl, driveStatus, waitForDriveConnected };
@@ -0,0 +1,176 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-or-later
2
+ // Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
3
+ // AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
4
+ // Conveying a modified copy, or running one as a network service, owes the
5
+ // corresponding source under this licence (§5/§13) — see LICENSING.md.
6
+ 'use strict';
7
+
8
+ /**
9
+ * drive-upload.js — a Drive v3 REST client, scoped to exactly one job:
10
+ * keep a single memory-backup file, in a single app folder, up to date.
11
+ *
12
+ * This talks to Google's API directly with the access token
13
+ * `client/drive-connect.js` obtains (via `/api/drive/token`) — it never goes
14
+ * through aegis1, and aegis1 never sees the memory content this uploads.
15
+ *
16
+ * Scoped to `drive.file` (the scope `/connect/drive` requests): that grant
17
+ * only ever sees files this app itself creates, which is why every write
18
+ * here goes through `findOrCreateFolder`/`findFileInFolder` rather than
19
+ * assuming some well-known id — there is no well-known id this scope could
20
+ * resolve, and a file this app did not create is invisible to it even by
21
+ * name. One stable file is overwritten in place on every sync rather than
22
+ * creating a new one each time, so a daily backup habit does not pile up a
23
+ * thousand same-named files with no way to tell them apart.
24
+ */
25
+
26
+ const DRIVE_FILES_URL = 'https://www.googleapis.com/drive/v3/files';
27
+ const DRIVE_UPLOAD_URL = 'https://www.googleapis.com/upload/drive/v3/files';
28
+ const FOLDER_MIME = 'application/vnd.google-apps.folder';
29
+ const BOUNDARY = 'aegiscode-drive-upload-boundary';
30
+
31
+ const DEFAULT_FOLDER = 'AEGIS Memory';
32
+ const DEFAULT_FILE = 'aegis-memory-backup.json';
33
+
34
+ function resolveFetch(fetchImpl) {
35
+ const f = fetchImpl || (typeof fetch === 'function' ? fetch : null);
36
+ if (!f) throw new Error('drive: this Node has no global fetch — upgrade to Node 22+');
37
+ return f;
38
+ }
39
+
40
+ /** Escape a value for Drive's `q=` string-literal quoting rules. */
41
+ function escapeQ(value) {
42
+ return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
43
+ }
44
+
45
+ async function driveRequest(fetchImpl, url, { method = 'GET', accessToken, body, headers } = {}) {
46
+ const f = resolveFetch(fetchImpl);
47
+ const res = await f(url, {
48
+ method,
49
+ headers: { Authorization: `Bearer ${accessToken}`, ...(headers || {}) },
50
+ body,
51
+ });
52
+ const text = await res.text();
53
+ let data = null;
54
+ try {
55
+ data = text ? JSON.parse(text) : null;
56
+ } catch {
57
+ data = null;
58
+ }
59
+ if (!res.ok) {
60
+ const rawMsg = (data && data.error && (data.error.message || data.error)) || text.slice(0, 200) || `HTTP ${res.status}`;
61
+ const err = new Error(`drive: ${method} ${url.split('?')[0]} failed — ${typeof rawMsg === 'string' ? rawMsg : JSON.stringify(rawMsg)}`);
62
+ err.status = res.status;
63
+ err.data = data;
64
+ throw err;
65
+ }
66
+ return data || {};
67
+ }
68
+
69
+ /** The first file matching an exact query, or null. */
70
+ async function findOne(fetchImpl, accessToken, query) {
71
+ const url = `${DRIVE_FILES_URL}?q=${encodeURIComponent(query)}&fields=${encodeURIComponent('files(id,name)')}&pageSize=1`;
72
+ const data = await driveRequest(fetchImpl, url, { accessToken });
73
+ const files = Array.isArray(data.files) ? data.files : [];
74
+ return files[0] || null;
75
+ }
76
+
77
+ /** This app's folder by name, creating it the first time. Returns its id. */
78
+ async function findOrCreateFolder(accessToken, name, { fetchImpl } = {}) {
79
+ const query = `mimeType='${FOLDER_MIME}' and name='${escapeQ(name)}' and trashed=false`;
80
+ const existing = await findOne(fetchImpl, accessToken, query);
81
+ if (existing) return existing.id;
82
+ const created = await driveRequest(fetchImpl, DRIVE_FILES_URL, {
83
+ method: 'POST',
84
+ accessToken,
85
+ headers: { 'Content-Type': 'application/json' },
86
+ body: JSON.stringify({ name, mimeType: FOLDER_MIME }),
87
+ });
88
+ return created.id;
89
+ }
90
+
91
+ /** One file by name inside a given folder, or null. */
92
+ async function findFileInFolder(accessToken, name, folderId, { fetchImpl } = {}) {
93
+ const query = `'${escapeQ(folderId)}' in parents and name='${escapeQ(name)}' and trashed=false`;
94
+ return findOne(fetchImpl, accessToken, query);
95
+ }
96
+
97
+ /**
98
+ * Create a new file: a multipart/related body (metadata part naming the
99
+ * parent folder, content part carrying the bytes) — the shape Drive's
100
+ * `uploadType=multipart` requires for a create, since a plain media upload
101
+ * has nowhere to say which folder the file belongs in.
102
+ */
103
+ async function createFile(accessToken, { name, folderId, content, mimeType }, { fetchImpl } = {}) {
104
+ const metadata = JSON.stringify({ name, parents: [folderId] });
105
+ const body =
106
+ `--${BOUNDARY}\r\n` +
107
+ `Content-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n` +
108
+ `--${BOUNDARY}\r\n` +
109
+ `Content-Type: ${mimeType}\r\n\r\n${content}\r\n` +
110
+ `--${BOUNDARY}--`;
111
+ return driveRequest(
112
+ fetchImpl,
113
+ `${DRIVE_UPLOAD_URL}?uploadType=multipart&fields=${encodeURIComponent('id,webViewLink')}`,
114
+ {
115
+ method: 'POST',
116
+ accessToken,
117
+ headers: { 'Content-Type': `multipart/related; boundary=${BOUNDARY}` },
118
+ body,
119
+ }
120
+ );
121
+ }
122
+
123
+ /**
124
+ * Overwrite an existing file's content in place. A plain media upload is
125
+ * enough here — the name and parent folder never change on a resync, so
126
+ * there is nothing a metadata part would need to say.
127
+ */
128
+ async function updateFileContent(accessToken, fileId, content, mimeType, { fetchImpl } = {}) {
129
+ return driveRequest(
130
+ fetchImpl,
131
+ `${DRIVE_UPLOAD_URL}/${encodeURIComponent(fileId)}?uploadType=media&fields=${encodeURIComponent('id,webViewLink')}`,
132
+ {
133
+ method: 'PATCH',
134
+ accessToken,
135
+ headers: { 'Content-Type': mimeType },
136
+ body: content,
137
+ }
138
+ );
139
+ }
140
+
141
+ /**
142
+ * Upload (create or overwrite) one memory backup file in the user's Drive.
143
+ *
144
+ * @param {string} accessToken a live Drive access token (client/drive-connect.js / aegis.driveToken())
145
+ * @param {string} content the file's bytes — the caller serialises; this module never shapes the memory export itself
146
+ * @param {{folderName?:string, fileName?:string, mimeType?:string, fetchImpl?:Function}} [opts]
147
+ * @returns {Promise<{fileId:string, webViewLink:string|null, updated:boolean}>}
148
+ */
149
+ async function uploadMemoryBackup(accessToken, content, opts = {}) {
150
+ const folderName = opts.folderName || DEFAULT_FOLDER;
151
+ const fileName = opts.fileName || DEFAULT_FILE;
152
+ const mimeType = opts.mimeType || 'application/json';
153
+ const fetchImpl = opts.fetchImpl;
154
+
155
+ const folderId = await findOrCreateFolder(accessToken, folderName, { fetchImpl });
156
+ const existing = await findFileInFolder(accessToken, fileName, folderId, { fetchImpl });
157
+ const result = existing
158
+ ? await updateFileContent(accessToken, existing.id, content, mimeType, { fetchImpl })
159
+ : await createFile(accessToken, { name: fileName, folderId, content, mimeType }, { fetchImpl });
160
+
161
+ return {
162
+ fileId: result.id || (existing && existing.id) || null,
163
+ webViewLink: result.webViewLink || null,
164
+ updated: Boolean(existing),
165
+ };
166
+ }
167
+
168
+ module.exports = {
169
+ DEFAULT_FOLDER,
170
+ DEFAULT_FILE,
171
+ findOrCreateFolder,
172
+ findFileInFolder,
173
+ createFile,
174
+ updateFileContent,
175
+ uploadMemoryBackup,
176
+ };