total-recall-brain 3.21.2 → 3.22.0

package/src/core/browser-session.mjs

@@ -0,0 +1,185 @@
+/**
+ * Authenticated browser sessions for TR.
+ *
+ * TR's existing Playwright use (source-adapters.playwrightScrape) is stateless
+ * scraping: `chromium.launch()` with a throwaway context. Provider consoles
+ * require a logged-in session, so rotation needs a *persistent* profile that
+ * survives across runs — you log in once per provider, and the daemon can drive
+ * rotations later without re-auth.
+ *
+ * SECURITY: the profile directory holds live session cookies for Stripe,
+ * GitHub, etc. It is at least as sensitive as secrets.enc and is created 0700.
+ * Never copy it, never sync it, never log its contents.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PROFILE_DIRNAME = 'browser-profile';
+
+const PROFILE_README = `# TR browser profile — DO NOT SYNC, DO NOT COPY
+
+This directory holds live authenticated sessions (Stripe, GitHub, cloud consoles)
+used by \`total-recall secret rotate-auto\`.
+
+Treat it as equivalent to secrets.enc:
+  - never commit it
+  - never include it in backups that leave this machine
+  - delete it with \`total-recall secret browser-logout\` when no longer needed
+`;
+
+/**
+ * Load chromium if playwright is installed. Mirrors source-adapters.getPlaywright
+ * so browser support stays an optional dependency.
+ * @returns {Promise<any|null>}
+ */
+export async function getChromium() {
+  try {
+    const pw = await import('playwright');
+    return pw.chromium || pw.default?.chromium || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} brainDir
+ * @returns {string}
+ */
+export function resolveProfileDir(brainDir) {
+  return path.join(brainDir, PROFILE_DIRNAME);
+}
+
+/**
+ * Create the profile dir with restrictive permissions if absent.
+ * @param {string} brainDir
+ */
+export function ensureProfileDir(brainDir) {
+  const dir = resolveProfileDir(brainDir);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(dir, 'README.md'), PROFILE_README, { mode: 0o600 });
+  }
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    /* best effort on exotic filesystems */
+  }
+  return dir;
+}
+
+/**
+ * Launch a persistent, authenticated browser context.
+ *
+ * @param {string} brainDir
+ * @param {{ headless?: boolean, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ ok: boolean, context?: any, error?: string, profileDir?: string }>}
+ */
+export async function launchRotationContext(brainDir, opts = {}) {
+  const chromium = await getChromium();
+  if (!chromium) {
+    return {
+      ok: false,
+      error:
+        'playwright is not installed. Run: npm install playwright && npx playwright install chromium',
+    };
+  }
+
+  const profileDir = ensureProfileDir(brainDir);
+  // Headed by default: provider logins routinely require human 2FA, and a
+  // headless first-run would simply hang on an invisible challenge.
+  const headless = opts.headless === true;
+
+  try {
+    const context = await chromium.launchPersistentContext(profileDir, {
+      headless,
+      viewport: { width: 1440, height: 900 },
+      args: ['--disable-blink-features=AutomationControlled', '--no-first-run'],
+    });
+    context.setDefaultTimeout(opts.timeoutMs ?? 30_000);
+    return { ok: true, context, profileDir };
+  } catch (err) {
+    return { ok: false, error: `failed to launch browser profile: ${err.message}`, profileDir };
+  }
+}
+
+/**
+ * Navigate to a console and report whether the session is authenticated.
+ *
+ * Recipes describe authentication by what is visible, not by URL alone, because
+ * most consoles redirect to a login page rather than returning an error status.
+ *
+ * @param {any} context
+ * @param {{ console_url: string, signed_in?: string, signed_out?: string }} recipe
+ * @returns {Promise<{ page: any, authenticated: boolean, url: string }>}
+ */
+export async function openConsole(context, recipe) {
+  const page = context.pages()[0] || (await context.newPage());
+  await page.goto(recipe.console_url, { waitUntil: 'domcontentloaded' });
+  // Consoles are SPA-heavy; give client-side auth redirects a beat to settle.
+  await page.waitForTimeout(1500);
+
+  const authenticated = await isAuthenticated(page, recipe);
+  return { page, authenticated, url: page.url() };
+}
+
+/**
+ * @param {any} page
+ * @param {{ signed_in?: string, signed_out?: string }} recipe
+ * @returns {Promise<boolean>}
+ */
+export async function isAuthenticated(page, recipe) {
+  // A visible signed-out marker (login form, "Sign in" CTA) is decisive.
+  if (recipe.signed_out) {
+    const out = await page.locator(recipe.signed_out).first().isVisible().catch(() => false);
+    if (out) return false;
+  }
+  if (recipe.signed_in) {
+    return page.locator(recipe.signed_in).first().isVisible().catch(() => false);
+  }
+  return true;
+}
+
+/**
+ * Wait for a human to complete login/2FA in the headed window.
+ *
+ * @param {any} page
+ * @param {object} recipe
+ * @param {{ timeoutMs?: number, pollMs?: number, onWait?: (s:number)=>void }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function waitForLogin(page, recipe, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 180_000;
+  const pollMs = opts.pollMs ?? 2000;
+  const started = Date.now();
+
+  while (Date.now() - started < timeoutMs) {
+    if (await isAuthenticated(page, recipe)) return true;
+    opts.onWait?.(Math.round((Date.now() - started) / 1000));
+    await page.waitForTimeout(pollMs);
+  }
+  return false;
+}
+
+/**
+ * Close a context without throwing.
+ * @param {any} context
+ */
+export async function closeContext(context) {
+  try {
+    await context?.close();
+  } catch {
+    /* already closed */
+  }
+}
+
+/**
+ * Delete the persistent profile (logout everywhere).
+ * @param {string} brainDir
+ */
+export function clearProfile(brainDir) {
+  const dir = resolveProfileDir(brainDir);
+  if (!fs.existsSync(dir)) return { removed: false, path: dir };
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { removed: true, path: dir };
+}

package/src/core/daemon-loop.mjs

@@ -232,9 +232,25 @@ async function main() {
     logger.info({ subsystem: 'daemon-loop', message: `Boot repo-sync failed: ${err.message}` });
   }
 
+  // Automatic mesh enrollment — a node that never authenticated to the control
+  // server has no mesh IP, so this must run before the first mesh patch.
+  try {
+    const { ensureEnrolled } = await import('./mesh-enroll.mjs');
+    const enrollment = await ensureEnrolled({ brainDir: BRAIN_DIR });
+    if (!enrollment.skipped) {
+      logger.info({
+        subsystem: 'daemon-loop',
+        message: `Boot mesh enrollment: ok=${enrollment.ok} state=${enrollment.state} method=${enrollment.method || 'n/a'}`,
+      });
+    }
+  } catch (err) {
+    logger.info({ subsystem: 'daemon-loop', message: `Boot mesh enrollment failed: ${err.message}` });
+  }
+
   // Initial mesh patch
   try {
-    const { patchOwnMeshNode } = await import('./mesh.mjs');
+    const { clearMeshStatusCache, patchOwnMeshNode } = await import('./mesh.mjs');
+    clearMeshStatusCache();
     await patchOwnMeshNode();
     logger.info({ subsystem: 'daemon-loop', message: 'Mesh node patched on boot' });
   } catch (err) {
@@ -306,6 +322,17 @@ async function main() {
       // Periodically patch own mesh node (heartbeat)
       if (taskCount > 0 && taskCount % (60000 / TASK_SLEEP_MS) === 0) {
         try {
+          // Self-heal enrollment: a node that dropped off the control server
+          // (logged out, expired node key) rejoins without user intervention.
+          // Internally throttled, so this is cheap on every heartbeat.
+          const { ensureEnrolled } = await import('./mesh-enroll.mjs');
+          const enrollment = await ensureEnrolled({ brainDir: BRAIN_DIR });
+          if (enrollment.changed) {
+            logger.info({
+              subsystem: 'daemon-loop',
+              message: `Mesh re-enrolled via ${enrollment.method || 'unknown'}`,
+            });
+          }
           const { patchOwnMeshNode } = await import('./mesh.mjs');
           await patchOwnMeshNode();
           // renewLease is a no-op shim (re-checks isLeader); kept for API stability.

package/src/core/embeddings.mjs

@@ -6,8 +6,13 @@
  *
  * Index file: .agent/memory-derived/embeddings.db
  *
- * Embedding model: gemini-embedding-2 (Google, 768 dims, free tier)
- *   Auth: GOOGLE_API_KEY env var
+ * Providers, in order: Ollama (local/mesh) → OpenRouter → Google → OpenAI.
+ * Ollama leads because it needs no key, costs nothing, and keeps working when
+ * a hosted provider is out of credit — the cloud providers are the fallback,
+ * not the default.
+ *
+ * Every provider must return EMBEDDING_DIMS-wide vectors; the vss0 index is
+ * declared at that width and a mismatch corrupts search silently.
  */
 
 import fs from 'node:fs';
@@ -22,9 +27,21 @@ import {
 
 import { googleApiKey, openRouterApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
 import { logger } from './logger.mjs';
+import {
+  resolveOllamaEndpoint,
+  selectEmbeddingModel,
+  getOllamaEmbedding,
+} from './ollama-embeddings.mjs';
 
 const DEFAULT_EMBED_MODEL = embedModel;
 
+/**
+ * Vector width of the vault index. The vss0 virtual tables are declared at this
+ * width, so it is a storage constraint rather than a tuning knob — changing it
+ * requires rebuilding every stored embedding.
+ */
+export const EMBEDDING_DIMS = 768;
+
 /** Resolve API keys at call time so tests can set env after import. */
 function resolveGoogleApiKey() {
   return googleApiKey || process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY || null;
@@ -111,10 +128,10 @@ function getDb(derivedDir) {
   if (vssOk) {
     db.exec(`
       CREATE VIRTUAL TABLE IF NOT EXISTS vss_vault_embeddings USING vss0(
-        embedding(768)
+        embedding(${EMBEDDING_DIMS})
       );
       CREATE VIRTUAL TABLE IF NOT EXISTS vss_session_embeddings USING vss0(
-        embedding(768)
+        embedding(${EMBEDDING_DIMS})
       );
     `);
   }
@@ -242,9 +259,9 @@ async function getOpenRouterEmbedding(text, model = 'openai/text-embedding-3-sma
       'Content-Type': 'application/json',
       'Authorization': `Bearer ${openRouterKey}`,
     },
-    // Request 768 dims to match the existing vault vss0(embedding(768)) schema
-    // and stay comparable against previously-stored Google embeddings.
-    body: JSON.stringify({ model, input: text, dimensions: 768 }),
+    // Match the vault's declared vector width so results stay comparable
+    // against previously-stored embeddings.
+    body: JSON.stringify({ model, input: text, dimensions: EMBEDDING_DIMS }),
   }, 20000);
 
   if (!res.ok) {
@@ -296,10 +313,32 @@ export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
 
   let embedding;
 
-  // OpenRouter first: standing preference (Gemini's budget is exhausted, so
+  // Local/mesh Ollama first: no key, no spend, no rate limit, and unaffected by
+  // a hosted provider running out of credit. The model is discovered from the
+  // server at call time rather than named here.
+  try {
+    const baseUrl = await resolveOllamaEndpoint();
+    if (baseUrl) {
+      const ollamaModel = await selectEmbeddingModel(baseUrl, {
+        dims: EMBEDDING_DIMS,
+        preferred: process.env.TR_OLLAMA_EMBED_MODEL || null,
+      });
+      if (ollamaModel) {
+        embedding = await getOllamaEmbedding(input, {
+          baseUrl,
+          model: ollamaModel,
+          dims: EMBEDDING_DIMS,
+        });
+      }
+    }
+  } catch (err) {
+    logger.debug('embeddings: Ollama unavailable, trying hosted providers', { err: err.message });
+  }
+
+  // OpenRouter next: standing preference (Gemini's budget is exhausted, so
   // Google is a near-guaranteed slow failure right now — trying it first just
   // taxes every call with a ~15-20s timeout before falling through).
-  if (openRouterKey) {
+  if (!embedding && openRouterKey) {
     try {
       embedding = await getOpenRouterEmbedding(input);
     } catch (err) {
@@ -325,7 +364,10 @@ export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   }
 
   if (!embedding) {
-    throw new Error('No embedding provider available. Set OPENROUTER_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.');
+    throw new Error(
+      'No embedding provider available. Run Ollama with an embedding model (optionally set TR_OLLAMA_URL / TR_OLLAMA_EMBED_MODEL), ' +
+        'or set OPENROUTER_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.',
+    );
   }
 
   return embedding;

package/src/core/headscale-client.mjs

@@ -0,0 +1,227 @@
+/**
+ * Headscale control-server client.
+ *
+ * Single implementation shared by the REST proxy (`routes/headscale.mjs`) and
+ * automatic node enrollment (`mesh-enroll.mjs`). No control-server URL is ever
+ * hardcoded here — it is resolved from the operator's own secret entry or
+ * environment, so this works against any Headscale (or Tailscale SaaS) install.
+ */
+import { getSecretsCatalog, getSecret } from './secrets-store.mjs';
+import { throttledFetch } from './throttled-fetch.mjs';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Env override so headless/CI installs can point at a control server without a secret. */
+export function headscaleUrlFromEnv() {
+  const raw = process.env.TR_HEADSCALE_URL || process.env.TR_LOGIN_SERVER || '';
+  return raw.trim() || null;
+}
+
+/**
+ * Reject non-HTTPS control servers (loopback excepted for local development).
+ * Bearer tokens must never travel in cleartext over a network hop.
+ */
+export function assertSecureControlUrl(url) {
+  const parsed = new URL(url);
+  const isLoopback = ['localhost', '127.0.0.1', '::1'].includes(parsed.hostname);
+  if (parsed.protocol !== 'https:' && !(isLoopback && parsed.protocol === 'http:')) {
+    throw new Error('Headscale URL must use HTTPS (HTTP is allowed only for loopback development)');
+  }
+  return parsed;
+}
+
+/** Strip a trailing slash so path joining stays predictable. */
+export function normalizeControlUrl(url) {
+  const value = String(url || '').trim();
+  return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+
+/**
+ * Locate the operator's headscale credential without knowing its key name.
+ * Any secret whose provider is `headscale` is treated as the control-server token.
+ */
+export async function findHeadscaleKeyMeta(brainDir) {
+  const catalog = await getSecretsCatalog(brainDir);
+  return catalog.keys.find((k) => k.provider === 'headscale') || null;
+}
+
+/**
+ * Resolve `{ url, token }` for the control server.
+ * Throws when no credential is configured — callers that must degrade
+ * gracefully should use `describeHeadscaleAvailability()` instead.
+ */
+export async function resolveHeadscaleConfig(brainDir) {
+  const meta = await findHeadscaleKeyMeta(brainDir);
+  if (!meta) {
+    throw new Error('Headscale API Key not configured in ApiKeysPage');
+  }
+
+  const got = await getSecret(brainDir, meta.key, {
+    action: 'use',
+    actor: 'headscale-client',
+  });
+  if (!got.found || !got.value) {
+    throw new Error('Headscale API Key token value is empty or not set');
+  }
+
+  const url = normalizeControlUrl(meta.headscale_url || headscaleUrlFromEnv() || '');
+  if (!url) {
+    throw new Error('Headscale control server URL is not set on the headscale API key');
+  }
+
+  return { url, token: got.value, keyName: meta.key };
+}
+
+/**
+ * Non-throwing capability probe used by enrollment and status endpoints:
+ * reports whether an automated (pre-auth key) enrollment path is possible.
+ */
+export async function describeHeadscaleAvailability(brainDir) {
+  try {
+    const meta = await findHeadscaleKeyMeta(brainDir);
+    if (!meta) {
+      return { configured: false, reason: 'no-headscale-api-key', url: headscaleUrlFromEnv() };
+    }
+    const url = normalizeControlUrl(meta.headscale_url || headscaleUrlFromEnv() || '');
+    if (!url) {
+      return { configured: false, reason: 'no-control-url', url: null, keyName: meta.key };
+    }
+    if (!meta.set) {
+      return { configured: false, reason: 'api-key-value-empty', url, keyName: meta.key };
+    }
+    return { configured: true, reason: null, url, keyName: meta.key };
+  } catch (err) {
+    return { configured: false, reason: err.message || 'headscale-probe-failed', url: null };
+  }
+}
+
+/**
+ * Authenticated request against the control server's API.
+ * `brainDir` is required so the caller's brain scope selects the credential.
+ */
+export async function headscaleFetch(path, options = {}, brainDir) {
+  const { url, token } = await resolveHeadscaleConfig(brainDir);
+  assertSecureControlUrl(url);
+
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  const targetUrl = `${normalizeControlUrl(url)}${cleanPath}`;
+
+  const res = await throttledFetch(
+    targetUrl,
+    {
+      ...options,
+      headers: {
+        ...options.headers,
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+    },
+    options.timeoutMs || DEFAULT_TIMEOUT_MS,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => '');
+    const error = new Error(`Headscale API error (${res.status} ${res.statusText})`);
+    error.status = res.status;
+    error.detail = errorText.slice(0, 500);
+    throw error;
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) {
+    return res.json();
+  }
+  return { success: true };
+}
+
+/**
+ * Headscale renamed `/machine` to `/node`; retry the legacy path on 404 so one
+ * client works across control-server versions.
+ */
+export async function headscaleFetchWithLegacyFallback(currentPath, legacyPath, options, brainDir) {
+  try {
+    return await headscaleFetch(currentPath, options, brainDir);
+  } catch (err) {
+    if (err.status !== 404 || !legacyPath) throw err;
+    return headscaleFetch(legacyPath, options, brainDir);
+  }
+}
+
+/**
+ * Resolve a control-server user to both of its identifying forms.
+ *
+ * Headscale 0.26 made `/api/v1/preauthkey` take a numeric user **id** where
+ * older releases took the user **name**, so callers need both to stay
+ * version-agnostic. With no `requested` user, the first user is used.
+ */
+export async function resolveHeadscaleUser(brainDir, requested) {
+  const data = await headscaleFetch('/api/v1/user', {}, brainDir);
+  const users = data?.users || [];
+
+  if (requested) {
+    const match = users.find(
+      (u) =>
+        String(u.id) === String(requested) ||
+        u.name === requested ||
+        (u.email && u.email === requested),
+    );
+    if (match) return { id: String(match.id), name: match.name };
+    // Unknown to us — pass it through and let the control server decide.
+    return { id: String(requested), name: String(requested) };
+  }
+
+  if (!users.length) return null;
+  return { id: String(users[0].id), name: users[0].name };
+}
+
+/**
+ * Mint a pre-auth key for unattended enrollment.
+ *
+ * Defaults are deliberately narrow: single-use, non-ephemeral, short-lived —
+ * an enrollment key that leaks should expire before it is useful.
+ *
+ * The user field is tried as id first, then name: Headscale >=0.26 rejects the
+ * name with 400, and older releases reject the id the same way, so one client
+ * works against both without the operator pinning a version.
+ */
+export async function createHeadscalePreAuthKey(options = {}, brainDir) {
+  const ttlMinutes = Number.isFinite(options.ttlMinutes) ? options.ttlMinutes : 10;
+  const expiration =
+    options.expiration || new Date(Date.now() + ttlMinutes * 60_000).toISOString();
+
+  const ref = options.userRef || (await resolveHeadscaleUser(brainDir, options.user));
+  const attempts = [];
+  if (ref?.id) attempts.push(String(ref.id));
+  if (ref?.name && String(ref.name) !== String(ref.id)) attempts.push(String(ref.name));
+  if (!attempts.length) attempts.push(String(options.user || 'default'));
+
+  let lastError = null;
+  for (const user of attempts) {
+    try {
+      const data = await headscaleFetch(
+        '/api/v1/preauthkey',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            user,
+            reusable: options.reusable === true,
+            ephemeral: options.ephemeral === true,
+            expiration,
+            aclTags: options.aclTags || [],
+          }),
+        },
+        brainDir,
+      );
+
+      const key = data?.preAuthKey?.key || data?.preauthkey?.key || data?.key || null;
+      if (!key) throw new Error('Headscale did not return a pre-auth key');
+      return { key, expiration, user, raw: data };
+    } catch (err) {
+      lastError = err;
+      // Only the id-vs-name mismatch is worth retrying; anything else is real.
+      if (err.status !== 400) throw err;
+    }
+  }
+  throw lastError || new Error('Headscale did not return a pre-auth key');
+}