aegis-desktop 0.3.0

package/lib/settings.js

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * settings.js — provider-config store for the desktop host (plan P1 §5.1).
+ * Holds base URLs and provider keys in the main process only. Keys are
+ * encrypted at rest via Electron safeStorage when available, otherwise stored
+ * base64 (best-effort; never real security) — and only masked previews ever
+ * cross the IPC bridge.
+ *
+ * The in-app AEGIS key lives in its own reserved namespace (AEGIS_KEY_NAMESPACE)
+ * with dedicated accessors, so the provider CRUD surface — and the Settings
+ * pane built on it — can never list it as a provider or remove it.
+ *
+ * Pure Node + injectable storage dir / safeStorage so it unit-tests without
+ * an Electron binary.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SETTINGS_FILE = 'settings.json';
+
+/**
+ * Reserved namespace for the in-app AEGIS API key. It deliberately does NOT
+ * look like a provider id: the provider-config surface (get/set/remove/list,
+ * and therefore the Settings pane and the model: IPC) must never be able to
+ * list it as a provider or delete it via "Remove" — that coupling is defect
+ * #1 of the AEGIS-key wiring review (settings.set('aegis', …) used the same
+ * namespace as user provider configs). Use the dedicated AEGIS accessors on
+ * the store (setAegisKey / aegisRawKey / aegisKey) to touch it.
+ */
+const AEGIS_KEY_NAMESPACE = '__aegis';
+
+/** Pre-fix builds persisted the AEGIS key as a plain provider named 'aegis';
+ *  migrateLegacyAegisKey() relocates it (and list() hides it meanwhile). */
+const LEGACY_AEGIS_NAMESPACE = 'aegis';
+
+/** Namespaces the provider-config surface must never see or mutate. */
+const RESERVED_NAMESPACES = Object.freeze([
+  AEGIS_KEY_NAMESPACE,
+  LEGACY_AEGIS_NAMESPACE,
+]);
+
+/** True for the AEGIS-key namespace(s) — provider CRUD must refuse these. */
+function isReservedNamespace(provider) {
+  return RESERVED_NAMESPACES.includes(provider);
+}
+
+/** Same masking shape as desktop/main.js so previews are consistent. */
+function maskKey(key) {
+  if (!key) return null;
+  if (key.length <= 10) return 'configured';
+  return `${key.slice(0, 9)}\u2026${key.slice(-4)}`;
+}
+
+function createSettingsStore({ dir, safeStorage } = {}) {
+  if (!dir) throw new Error('createSettingsStore requires a storage dir');
+  const file = path.join(dir, SETTINGS_FILE);
+
+  const safeAvailable = () =>
+    Boolean(
+      safeStorage &&
+        typeof safeStorage.isEncryptionAvailable === 'function' &&
+        safeStorage.isEncryptionAvailable()
+    );
+
+  function encrypt(value) {
+    if (value == null) return null;
+    if (safeAvailable()) {
+      return safeStorage.encryptString(String(value)).toString('base64');
+    }
+    return Buffer.from(String(value), 'utf8').toString('base64');
+  }
+
+  function decrypt(value) {
+    if (!value) return null;
+    try {
+      const buf = Buffer.from(String(value), 'base64');
+      if (safeAvailable()) return safeStorage.decryptString(buf);
+      return buf.toString('utf8');
+    } catch {
+      return null;
+    }
+  }
+
+  function load() {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+    } catch {
+      return {};
+    }
+  }
+
+  function save(data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file);
+  }
+
+  /** Provider CRUD must never touch a reserved (AEGIS-key) namespace. */
+  function assertNotReserved(provider) {
+    if (isReservedNamespace(provider)) {
+      throw new Error(
+        `reserved namespace "${provider}" is not a provider config — ` +
+          'use setAegisKey()/aegisRawKey() for the AEGIS key'
+      );
+    }
+  }
+
+  function get(provider) {
+    const cfg = (load()[provider]) || {};
+    const key = decrypt(cfg.key);
+    return {
+      provider,
+      baseURL: cfg.baseURL || '',
+      configured: Boolean(key),
+      keyMask: maskKey(key),
+    };
+  }
+
+  function set(provider, { baseURL, key } = {}) {
+    assertNotReserved(provider);
+    const data = load();
+    const cfg = data[provider] || {};
+    if (baseURL !== undefined) cfg.baseURL = baseURL;
+    if (key !== undefined) cfg.key = key ? encrypt(key) : null;
+    data[provider] = cfg;
+    save(data);
+    return get(provider);
+  }
+
+  function rawKey(provider) {
+    const cfg = load()[provider] || {};
+    return decrypt(cfg.key);
+  }
+
+  function remove(provider) {
+    assertNotReserved(provider);
+    const data = load();
+    delete data[provider];
+    save(data);
+    return { ok: true };
+  }
+
+  /** Every provider config, never the AEGIS key (defect #1). */
+  function list() {
+    const data = load();
+    return Object.keys(data)
+      .filter((p) => !isReservedNamespace(p))
+      .map((p) => get(p));
+  }
+
+  // --- AEGIS key: separate namespace, separate accessors -------------------
+
+  function aegisKey() {
+    const cfg = load()[AEGIS_KEY_NAMESPACE] || {};
+    const key = decrypt(cfg.key);
+    return { configured: Boolean(key), keyMask: maskKey(key) };
+  }
+
+  /** Main-process-only: the decrypted AEGIS key. Never crosses IPC. */
+  function aegisRawKey() {
+    const cfg = load()[AEGIS_KEY_NAMESPACE] || {};
+    return decrypt(cfg.key);
+  }
+
+  function setAegisKey(key) {
+    const data = load();
+    data[AEGIS_KEY_NAMESPACE] = {
+      ...(data[AEGIS_KEY_NAMESPACE] || {}),
+      key: key ? encrypt(key) : null,
+    };
+    save(data);
+    return aegisKey();
+  }
+
+  /**
+   * Relocate a pre-fix `settings['aegis'].key` into the reserved namespace and
+   * drop the pseudo-provider entry. Moved at ciphertext level (no decrypt /
+   * re-encrypt), so it is safe to run before Electron's app 'ready' — when
+   * safeStorage is not usable yet. Idempotent; never throws.
+   */
+  function migrateLegacyAegisKey() {
+    try {
+      const data = load();
+      if (!data[LEGACY_AEGIS_NAMESPACE]) return { migrated: false };
+      const legacy = data[LEGACY_AEGIS_NAMESPACE] || {};
+      const current = data[AEGIS_KEY_NAMESPACE] || {};
+      const next = { ...data };
+      if (legacy.key && !current.key) {
+        next[AEGIS_KEY_NAMESPACE] = { ...current, key: legacy.key };
+      }
+      delete next[LEGACY_AEGIS_NAMESPACE];
+      save(next);
+      return { migrated: true };
+    } catch {
+      return { migrated: false };
+    }
+  }
+
+  return {
+    file,
+    get,
+    set,
+    rawKey,
+    remove,
+    list,
+    maskKey,
+    aegisKey,
+    aegisRawKey,
+    setAegisKey,
+    migrateLegacyAegisKey,
+  };
+}
+
+module.exports = {
+  SETTINGS_FILE,
+  AEGIS_KEY_NAMESPACE,
+  LEGACY_AEGIS_NAMESPACE,
+  RESERVED_NAMESPACES,
+  isReservedNamespace,
+  maskKey,
+  createSettingsStore,
+};

package/lib/sync/memory-queue.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * memory-queue.js — local retry queue for cloud memory saves (plan P3 §7).
+ * When `aegis.memorySave()` fails (no key configured, offline), the entry is
+ * appended to <dir>/memory-queue.json instead of being dropped, so a later
+ * "Sync now" or heartbeat retry can flush it once the cloud is reachable.
+ * Pure Node + injectable dir, mirrors desktop/lib/sync/sessions.js.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function queueFile(dir) {
+  return path.join(dir, 'memory-queue.json');
+}
+
+function load(dir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(queueFile(dir), 'utf8'));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+function atomicWrite(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function save(dir, entries) {
+  atomicWrite(queueFile(dir), entries);
+}
+
+/** Queue a memory entry that a cloud save couldn't reach right now. */
+function enqueue(dir, entry) {
+  const entries = load(dir);
+  const queued = { ...entry, queuedAt: Date.now() };
+  entries.push(queued);
+  save(dir, entries);
+  return queued;
+}
+
+function listQueued(dir) {
+  return load(dir);
+}
+
+module.exports = {
+  queueFile,
+  load,
+  save,
+  enqueue,
+  listQueued,
+};

package/lib/sync/sessions.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * sessions.js — local conversation persistence (plan P1 §5.1 / P3 §7).
+ * Every session (any model class) persists to <dir>/sessions.json on each
+ * message with a crash-safe temp-file rename. Pure Node + injectable dir,
+ * so it unit-tests without Electron.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function sessionsFile(dir) {
+  return path.join(dir, 'sessions.json');
+}
+
+function load(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(sessionsFile(dir), 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Monotonic write counter stored in the file's `__seq` field. Every mutation
+ * bumps it, so sessions written in the same millisecond still order
+ * deterministically (listSessions sorts by updatedAt, then by seq).
+ */
+function nextSeq(sessions) {
+  const seq = (typeof sessions.__seq === 'number' ? sessions.__seq : 0) + 1;
+  sessions.__seq = seq;
+  return seq;
+}
+
+/**
+ * Normalize a remote `updated_at`/`updatedAt` to epoch milliseconds. The cloud
+ * returns an ISO-8601 string (e.g. "2026-07-16T14:20:00"); the local store
+ * uses `Date.now()` epoch-ms numbers. Comparing the two directly coerces the
+ * string to NaN, which breaks last-write-wins ordering. ISO strings are
+ * parsed; epoch-ms numbers pass through; anything else becomes 0.
+ */
+function toEpochMs(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim()) {
+    const ms = Date.parse(value);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return 0;
+}
+
+function atomicWrite(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function save(dir, sessions) {
+  atomicWrite(sessionsFile(dir), sessions);
+}
+
+/**
+ * Create or merge a full session record. Any local write (`upsertSession` /
+ * `appendMessage`) marks the session `pending: true` — it has local content
+ * the cloud hasn't seen yet. Only `markSynced()` clears the flag, so a push
+ * that fails (offline/no key) never silently drops the session from the
+ * retry queue.
+ */
+function upsertSession(dir, session) {
+  const id = session && session.id;
+  if (!id) throw new Error('session.id is required');
+  const sessions = load(dir);
+  const prev = sessions[id] || { messages: [] };
+  sessions[id] = { ...prev, ...session, id, pending: true };
+  if (!sessions[id].updatedAt) sessions[id].updatedAt = Date.now();
+  sessions[id].seq = nextSeq(sessions);
+  save(dir, sessions);
+  return sessions[id];
+}
+
+/** Append one message to a session (crash-safe). */
+function appendMessage(dir, sessionId, message) {
+  if (!sessionId) throw new Error('sessionId is required');
+  const sessions = load(dir);
+  const session = sessions[sessionId] || { id: sessionId, messages: [] };
+  const messages = Array.isArray(session.messages) ? session.messages : [];
+  session.messages = messages.concat(message);
+  session.updatedAt = Date.now();
+  session.pending = true;
+  session.seq = nextSeq(sessions);
+  sessions[sessionId] = session;
+  save(dir, sessions);
+  return session;
+}
+
+function listSessions(dir) {
+  const sessions = load(dir);
+  return Object.values(sessions)
+    .filter((s) => s && s.id)
+    .sort(
+      (a, b) =>
+        (b.updatedAt || 0) - (a.updatedAt || 0) ||
+        (b.seq || 0) - (a.seq || 0)
+    );
+}
+
+function getSession(dir, id) {
+  return load(dir)[id] || null;
+}
+
+function deleteSession(dir, id) {
+  const sessions = load(dir);
+  delete sessions[id];
+  save(dir, sessions);
+  return { ok: true };
+}
+
+/** Clear the pending flag after a successful cloud push. `remote.remoteId`,
+ *  when the server assigns its own conversation id, is stashed alongside. */
+function markSynced(dir, id, remote) {
+  const sessions = load(dir);
+  const session = sessions[id];
+  if (!session) return null;
+  session.pending = false;
+  session.lastSyncedAt = Date.now();
+  if (remote && remote.remoteId) session.remoteId = remote.remoteId;
+  session.seq = nextSeq(sessions);
+  sessions[id] = session;
+  save(dir, sessions);
+  return session;
+}
+
+/** Force a session back into the retry queue (e.g. a push that partially failed). */
+function markPending(dir, id) {
+  const sessions = load(dir);
+  const session = sessions[id];
+  if (!session) return null;
+  session.pending = true;
+  session.seq = nextSeq(sessions);
+  sessions[id] = session;
+  save(dir, sessions);
+  return session;
+}
+
+/** Sessions with local content the cloud hasn't confirmed yet (including
+ *  sessions predating this field, which default to pending). */
+function listPending(dir) {
+  return listSessions(dir).filter((s) => s.pending !== false);
+}
+
+/**
+ * Merge remote conversation-sync records into the local store (pull half of
+ * sync). Last-write-wins by `updatedAt`, but a local session with unsynced
+ * edits (`pending`) always wins over the remote copy — it will overwrite the
+ * remote copy on the next push instead.
+ */
+function mergeRemoteSessions(dir, remoteSessions) {
+  const list = Array.isArray(remoteSessions) ? remoteSessions : [];
+  const sessions = load(dir);
+  let merged = 0;
+  for (const remote of list) {
+    const id = remote && (remote.session_id || remote.id);
+    if (!id) continue;
+    const local = sessions[id];
+    const remoteUpdatedAt = toEpochMs(remote.updated_at ?? remote.updatedAt);
+    if (local && (local.pending || (local.updatedAt || 0) >= remoteUpdatedAt)) {
+      continue;
+    }
+    sessions[id] = {
+      id,
+      title: remote.title || (local && local.title) || '',
+      messages: Array.isArray(remote.messages) ? remote.messages : [],
+      updatedAt: remoteUpdatedAt || Date.now(),
+      pending: false,
+      lastSyncedAt: Date.now(),
+      remoteId: remote.session_id || remote.id,
+    };
+    sessions[id].seq = nextSeq(sessions);
+    merged += 1;
+  }
+  if (merged) save(dir, sessions);
+  return merged;
+}
+
+module.exports = {
+  sessionsFile,
+  load,
+  save,
+  upsertSession,
+  appendMessage,
+  listSessions,
+  getSession,
+  deleteSession,
+  markSynced,
+  markPending,
+  listPending,
+  mergeRemoteSessions,
+};