@jossuealcala/madre 0.5.2 → 0.7.0

package/src/server.mjs

@@ -1,11 +1,15 @@
 import http from 'node:http';
-import { readFile, realpath, writeFile, mkdir, rm } from 'node:fs/promises';
+import { readFile, realpath, writeFile, mkdir, rm, cp, rename, access } from 'node:fs/promises';
 import { rmSync } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { classifyListening, probePort, framable } from './ports.mjs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 import { detectAgents, toolsPrefix } from './runtime-detection.mjs';
 import { EventStore } from './event-store.mjs';
 import { RoomMemory } from './memory.mjs';
@@ -44,9 +48,11 @@ import { applyConfigToEnv, loadConfig } from './config.mjs';
 import { extensionById, findOnPath, runInstaller } from './extensions.mjs';
 import { accountNoteFor, installPlanFor, looksLikeAdminProblem, loginPlanFor, probeAgentAuth, probeAll, TAKES_KEY } from './auth-probe.mjs';
 import { applyKey, keyPlanFor } from './credentials.mjs';
+import { forgetSecret, summary as vaultSummary, writeSecret } from './vault.mjs';
 import { loadConfig as readConfig, updateConfig } from './config.mjs';
 import { Privacy, normalizeTerms, privacySettings } from './privacy.mjs';
 import { checkForUpdate, detectInstall, updateCommand, releaseUrl, applyCommand } from './updates.mjs';
+import { bootWhatsNew, markSeen, notesFor, whatsNew } from './whats-new.mjs';
 
 // Where a person reads the module contract, in the language the room is speaking.
 const SDK_PAGE = { es: 'https://madre.run/sdk/', en: 'https://madre.run/en/sdk/' };
@@ -58,11 +64,14 @@ import { discoverModels } from './models.mjs';
 import { setImageModule } from './capabilities.mjs';
 import { resolveGeminiKey } from './image-studio.mjs';
 import { commandByName, listCommands, parseCommand } from './commands.mjs';
-import { listDirectory, searchFiles, readServable, storeAttachment, MAX_ATTACHMENT_BYTES } from './files.mjs';
+import { listDirectory, searchFiles, readServable, storeAttachment, resolveInside, MAX_ATTACHMENT_BYTES } from './files.mjs';
+import { planFileOp, CREATIONS } from './file-ops.mjs';
 import { Eyecat } from './eyecat-watch.mjs';
 import { economy } from './room/economy.mjs';
 import { maturity } from './maturity.mjs';
+import { memoryDashboard } from './memory-dashboard.mjs';
 import { verdictFor } from './verdict.mjs';
+import { refuseForeign } from './request-guard.mjs';
 
 const sourceDirectory = dirname(fileURLToPath(import.meta.url));
 const publicDirectory = join(sourceDirectory, '..', 'public');
@@ -140,6 +149,9 @@ export async function createPulseServer({
   ollamaProbe = process.env.PULSE_OLLAMA === '0' ? async () => ({ running: false, host: null, models: [], embedModel: null, chatModel: null, disabled: true }) : probeOllama,
 }) {
   const root = stateRoot ?? process.env.PULSE_HOME ?? join(homedir(), '.pulse');
+  // Read before this run creates anything: whether this person used MADRE before decides whether
+  // an update has news to show them, or this is a first install with nothing to catch up on.
+  const novelty = await bootWhatsNew({ root, version: PACKAGE.version }).catch(() => ({ returning: false }));
   // ~/.pulse/config.json fills in whatever the environment did not set.
   applyConfigToEnv(await loadConfig(root));
   // What language the screens speak. The prompt the agents read is not one of them, and the
@@ -196,7 +208,7 @@ export async function createPulseServer({
   const install = detectInstall({ projectRoot: canonicalProjectRoot });
   async function versionView({ force = false } = {}) {
     const check = await checkForUpdate({ name: PACKAGE.name, current: PACKAGE.version, cacheFile: join(root, 'updates.json'), fetchImpl: reportFetch, enabled: updatesEnabled(), force });
-    return { project: canonicalProjectRoot, ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest, roomLanguage()) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
+    return { project: canonicalProjectRoot, ...check, notes: Boolean(notesFor(PACKAGE.version)), name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest, roomLanguage()) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
   }
   // Keeping the day's cache warm. MODULES is served from what is already on disk, so the looking
   // happens after the screen is answered, never in front of it: at most once an hour per room,
@@ -546,8 +558,8 @@ export async function createPulseServer({
   const startupConfig = await readConfig(root);
   room.setScopes(startupConfig.scopes ?? {});
   setImageModule(startupConfig.modules?.imageStudio ?? {});
-  // Rooms opened before Ash was renamed carry the old key; the human's switch is not lost.
-  room.setAsh(Boolean(startupConfig.modules?.ash?.enabled ?? startupConfig.modules?.ash?.enabled));
+  room.setAsh(Boolean(startupConfig.modules?.ash?.enabled));
+  room.setChoices(Boolean(startupConfig.modules?.choices?.enabled));
   const recoveredTurns = await room.reconcile();
   if (recoveredTurns) console.error(`MADRE recovered ${recoveredTurns} unfinished turn(s) from a previous run.`);
   const quotaMonitor = new QuotaMonitor({
@@ -842,14 +854,20 @@ export async function createPulseServer({
   }
 
   const server = http.createServer(async (request, response) => {
+    const foreign = refuseForeign(request);
+    if (foreign) return sendJson(response, 403, { error: t(foreign), guarded: true });
     const url = new URL(request.url, 'http://127.0.0.1');
+    // The project's own folder name, typed by the human. Declared at the top of the handler and
+    // not beside the first route that happened to need it: a const sits in its temporal dead zone
+    // until its own line runs, so any route above it threw instead of refusing.
+    const designationOk = (given) => typeof given === 'string' && given.trim().toLowerCase() === basename(canonicalProjectRoot).toLowerCase();
     try {
       if (request.method === 'GET' && url.pathname === '/') {
         const html = await readFile(join(publicDirectory, 'index.html'));
         response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
         return response.end(html);
       }
-      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js', '/syntax.js'].includes(url.pathname)) {
+      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js', '/syntax.js', '/routing.js', '/abduction.js'].includes(url.pathname)) {
         const js = await readFile(join(publicDirectory, url.pathname.slice(1)));
         response.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
         return response.end(js);
@@ -859,10 +877,28 @@ export async function createPulseServer({
         response.writeHead(200, { 'content-type': 'text/css; charset=utf-8' });
         return response.end(css);
       }
+      const abductionAssets = new Map([
+        ['/assets/abduction-cat.png', 'abduction-cat.png'],
+        ['/assets/abduction-cat-blink.png', 'abduction-cat-blink.png'],
+        ['/assets/abduction-cat-control-left.png', 'abduction-cat-control-left.png'],
+        ['/assets/abduction-cat-control-right.png', 'abduction-cat-control-right.png'],
+      ]);
+      if (request.method === 'GET' && abductionAssets.has(url.pathname)) {
+        const image = await readFile(join(publicDirectory, 'assets', abductionAssets.get(url.pathname)));
+        response.writeHead(200, {
+          'content-type': 'image/png',
+          'content-length': image.length,
+          'cache-control': 'public, max-age=86400',
+        });
+        return response.end(image);
+      }
       if (request.method === 'GET' && url.pathname === '/api/state') {
         return sendJson(response, 200, {
           projectRoot,
           platform: process.platform,
+          // Which MADRE this is. The page prints it in the corner: the one fact a bug report
+          // always needs and nobody ever remembers to ask for.
+          version: PACKAGE.version,
           // What language this machine set MADRE to, for a browser that has never chosen. It is
           // the language the room is SPEAKING, not the one written in the file: PULSE_LANGUAGE
           // wins over the config here as it does everywhere else, and reading the file again
@@ -872,6 +908,12 @@ export async function createPulseServer({
           chats: await listChats(roomDir),
           agents: agents.map((agent) => ({ ...agent, login: loginPlanFor(agent), install: installPlanFor(agent), key: keyPlanFor(agent.id), ...(accountNoteFor(agent.id) ?? {}) })),
           ash: { enabled: room.ashEnabled() },
+          choices: { enabled: room.choicesEnabled() },
+          // Read live, not from the config this process loaded at boot. A switch the human moves
+          // in MODULES while the room is open has to be the answer the room gives afterwards —
+          // otherwise the switch says on and the browser keeps refusing, which is how a setting
+          // stops being believed.
+          ripleyWeb: Boolean((await readConfig(root)).modules?.ripley?.web),
           ripley: { enabled: await ripleyOn() },
           softTokenBudget,
           timeouts: Object.fromEntries(agents.map((agent) => [agent.id, room.timeoutFor(agent.id)])),
@@ -912,6 +954,37 @@ export async function createPulseServer({
         void broadcastPending();
         return;
       }
+      // Copying and moving, by the human's own hand. Both ends are resolved inside the project
+      // after following symlinks, so no path typed or pasted can reach outside it; the zones the
+      // room guards from agents ask for the project's designation first.
+      if (request.method === 'POST' && url.pathname === '/api/tree/op') {
+        const payload = await body(request).catch(() => ({}));
+        const plan = planFileOp(payload);
+        if (!plan.ok) return sendJson(response, 400, { error: plan.error });
+        if (plan.guarded && !designationOk(payload.designation)) {
+          return sendJson(response, 403, { error: t('UNABLE TO COMPUTE. UNABLE TO CLARIFY.'), guarded: true });
+        }
+        const source = plan.from ? await resolveInside(canonicalProjectRoot, plan.from) : null;
+        if (plan.from && !source) return sendJson(response, 404, { error: t('Not found.') });
+        // The destination does not exist yet, so its PARENT is what has to be inside the project.
+        const targetDir = plan.to.includes('/') ? plan.to.slice(0, plan.to.lastIndexOf('/')) : '.';
+        const parent = await resolveInside(canonicalProjectRoot, targetDir);
+        if (!parent) return sendJson(response, 400, { error: t('The destination is outside this project.') });
+        const destination = join(parent, plan.to.slice(plan.to.lastIndexOf('/') + 1));
+        if (await access(destination).then(() => true, () => false)) {
+          return sendJson(response, 409, { error: t('There is already something at {path}.', { path: plan.to }) });
+        }
+        try {
+          if (plan.operation === 'new-folder') await mkdir(destination);
+          else if (plan.operation === 'new-file') await writeFile(destination, '', { flag: 'wx' });
+          else if (plan.operation === 'copy') await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
+          else await rename(source, destination);
+        } catch (error) {
+          return sendJson(response, 500, { error: error.message });
+        }
+        await room.record(CREATIONS.includes(plan.operation) ? 'project.file.created' : 'project.file.moved', { operation: plan.operation, from: plan.from, to: plan.to, guarded: plan.guarded });
+        return sendJson(response, 200, { ok: true, operation: plan.operation, from: plan.from, to: plan.to });
+      }
       if (request.method === 'GET' && url.pathname === '/api/tree/search') {
         const matches = await searchFiles(canonicalProjectRoot, url.searchParams.get('q') ?? '', { limit: Math.min(Number(url.searchParams.get('limit')) || 20, 50) });
         return sendJson(response, 200, { matches });
@@ -983,7 +1056,6 @@ export async function createPulseServer({
         return sendJson(response, 200, { settings: await applySettings(await body(request)) });
       }
       // NOSTROMO: the archive is behind the project designation, like CONTROL.
-      const designationOk = (given) => typeof given === 'string' && given.trim().toLowerCase() === basename(canonicalProjectRoot).toLowerCase();
       // Sentinel: reports, settings, the manual road (a prefilled issue) and the automatic one.
       if (request.method === 'GET' && url.pathname === '/api/sentinel') {
         return sendJson(response, 200, { reports: sentinel.reports(), settings: sentinel.settings(), environment: sentinel.environment(), feedbackUrl: sentinel.feedbackUrl(), formUrl: sentinel.formUrl() });
@@ -1017,6 +1089,65 @@ export async function createPulseServer({
       }
       // Where this room's tokens go: what each block of the briefing has cost, how much came back
       // from a CLI's own cache, and how many characters the room spends per token it is charged.
+      // What this project has settled, for the strip at the top of a conversation. Not gated
+      // behind the designation the archive is: these same sentences already appear in the room
+      // under any answer that recalled one.
+      // Open questions, for the strip under the composer. Read-only and ungated for the same
+      // reason the decisions are: these sentences already appear in the room whenever one is
+      // recalled. Dismissing one still happens in NOSTROMO, behind the designation.
+      // What is listening on loopback that answers HTTP, for RIPLEY's address bar. Reading only:
+      // lsof reports and changes nothing, nothing in the project is run, and a port that does not
+      // speak HTTP never reaches the list. Starting a server is not here — that runs a command.
+      // Whether an address agrees to be put behind glass. A page is entitled to refuse, and most
+      // serious ones do; what RIPLEY can do is ask before framing it, so the human gets MADRE's
+      // sentence and a real tab instead of the browser's bare "refused to connect".
+      //
+      // This is the one place the room itself reaches the web, and only after the human turned
+      // the web on and typed the address. The request goes through the same watched fetch as
+      // everything else, so it lands in the outbound log like any other departure.
+      if (request.method === 'GET' && url.pathname === '/api/can-frame') {
+        let target = null;
+        try { target = new URL(url.searchParams.get('url') ?? ''); } catch { return sendJson(response, 400, { error: t('That is not an address.') }); }
+        if (!/^https?:$/.test(target.protocol)) return sendJson(response, 400, { error: t('Only http and https.') });
+        const local = ['127.0.0.1', 'localhost', '[::1]'].includes(target.hostname);
+        if (!local && !(await readConfig(root)).modules?.ripley?.web) {
+          return sendJson(response, 403, { error: t('RIPLEY reaches this computer only · turn the web on in MODULES to open an address outside it') });
+        }
+        try {
+          const controller = new AbortController();
+          const timer = setTimeout(() => controller.abort(), 6000);
+          const probe = await reportFetch(target.href, { signal: controller.signal, redirect: 'follow' });
+          clearTimeout(timer);
+          return sendJson(response, 200, { framable: framable(probe.headers), status: probe.status });
+        } catch (error) {
+          return sendJson(response, 200, { framable: true, status: null, unreachable: true });
+        }
+      }
+      if (request.method === 'GET' && url.pathname === '/api/ports') {
+        if (!(await ripleyOn())) return sendJson(response, 412, { error: t('RIPLEY is off. Enable it in MODULES to render files.') });
+        let listening = { ports: [], wider: [] };
+        try {
+          const { stdout } = await execFileAsync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], { timeout: 4000, maxBuffer: 2 * 1024 * 1024 });
+          listening = classifyListening(stdout, { self: request.socket.localPort });
+        } catch { return sendJson(response, 200, { ports: [], wider: [], probed: false }); }
+        const ports = [];
+        for (const found of listening.ports.slice(0, 24)) {
+          const probe = await probePort(found.port, { fetchImpl: reportFetch });
+          if (probe.ok) ports.push({ ...found, status: probe.status, html: probe.html, contentType: probe.contentType, framable: probe.framable });
+        }
+        // What is listening on every interface travels too. It is not offered — this room does not
+        // help anyone frame something reachable from the network — but saying nothing about it is
+        // what made an empty list read as «there is nothing here» when there plainly was.
+        return sendJson(response, 200, { ports, wider: listening.wider.slice(0, 8).map(({ port, command }) => ({ port, command })), probed: true });
+      }
+      if (request.method === 'GET' && url.pathname === '/api/questions') {
+        const limit = Math.min(5, Math.max(1, Number(url.searchParams.get('limit') ?? 3) || 3));
+        return sendJson(response, 200, { questions: room.questions({ limit }) });
+      }
+      if (request.method === 'GET' && url.pathname === '/api/decisions') {
+        const limit = Math.min(5, Math.max(1, Number(url.searchParams.get('limit') ?? 3) || 3));
+        return sendJson(response, 200, { decisions: room.decisions({ limit }) });
+      }
       if (url.pathname === '/api/economy' && request.method === 'GET') {
         return sendJson(response, 200, economy(await store.readAll()));
       }
@@ -1142,6 +1273,15 @@ export async function createPulseServer({
         } catch (error) { return sendJson(response, 400, { error: error.message }); }
       }
       // Release channel: current, latest on npm, and the command for how this copy runs.
+      // What this version brings, once, to someone who came from an older one.
+      if (request.method === 'GET' && url.pathname === '/api/whats-new') {
+        const news = await whatsNew({ root, version: PACKAGE.version, returning: novelty.returning, any: url.searchParams.get('any') === '1' });
+        return sendJson(response, 200, { ...news, changes: { es: releaseUrl(PACKAGE.repository, PACKAGE.version, 'es'), en: releaseUrl(PACKAGE.repository, PACKAGE.version, 'en') } });
+      }
+      if (request.method === 'POST' && url.pathname === '/api/whats-new/seen') {
+        await markSeen(root, PACKAGE.version);
+        return sendJson(response, 200, { seen: PACKAGE.version });
+      }
       if (request.method === 'GET' && url.pathname === '/api/version') {
         return sendJson(response, 200, await versionView({ force: url.searchParams.get('force') === '1' }));
       }
@@ -1206,13 +1346,19 @@ export async function createPulseServer({
           verdict: verdictFor({ maturity: grown, exams: exams.last, cold: research?.cold, asks: research?.ask?.length ?? 0 }),
         });
       }
+      // The MEMORY dashboard: what the archive did day by day and what it is made of. Counts
+      // only, no text of any memory, so it is read like /api/maturity, without the designation.
+      if (request.method === 'GET' && url.pathname === '/api/memory/dashboard') {
+        return sendJson(response, 200, { dashboard: memoryDashboard({ activity: room.memoryActivity(), stats: room.memoryStats() }) });
+      }
       // Inside the core: the document MADRE writes in the human's name for the next turn, block
       // by block. Built on demand and stored nowhere; asking costs nothing and sends nothing.
       if (request.method === 'GET' && url.pathname === '/api/briefing') {
         const asked = url.searchParams.get('agent') ?? agents.find((agent) => agent.ready && !agent.local)?.id ?? agents[0]?.id;
         const mode = Math.min(4, Math.max(0, Number(url.searchParams.get('mode') ?? 1) || 0));
         const text = String(url.searchParams.get('text') ?? '').slice(0, 2000);
-        const briefing = await room.briefing({ agent: asked, mode, text });
+        const ash = url.searchParams.get('ash') === 'true';
+        const briefing = await room.briefing({ agent: asked, mode, text, ash });
         if (!briefing) return sendJson(response, 404, { error: `No agent "${asked}" on this computer.` });
         return sendJson(response, 200, {
           ...briefing,
@@ -1377,6 +1523,34 @@ export async function createPulseServer({
       }
       // A provider key for a CLI that signs in from its own prompt. Local connections only: a key
       // pasted from another machine would travel the network. It is written where that CLI looks
+      // A connector's secret. Same rule as an agent's key and for the same reason: it is accepted
+      // only from this computer, never over the network. What differs is where it lands — a
+      // connector has no CLI to hand it to, so MADRE holds it, in its own vault, `0600`, and never
+      // in the config, the ledger or a log. The ledger records that one was set and under which
+      // name; the value never leaves src/vault.mjs except to the module that owns it.
+      const vaultMatch = url.pathname.match(/^\/api\/x\/([a-z0-9-]+)\/secret$/);
+      if (vaultMatch && (request.method === 'POST' || request.method === 'DELETE')) {
+        const id = vaultMatch[1];
+        const address = request.socket.remoteAddress ?? '';
+        if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(address)) {
+          return sendJson(response, 403, { error: t('A key is only accepted from this computer, never over the network.') });
+        }
+        const module = moduleById(id);
+        if (!module) return sendJson(response, 404, { error: t('No module by that name is loaded.') });
+        const payload = await body(request).catch(() => ({}));
+        const name = String(payload.name ?? '');
+        if (request.method === 'DELETE') {
+          const gone = await forgetSecret(root, id, payload.name === undefined ? null : name);
+          if (!gone.ok) return sendJson(response, 400, { error: gone.error });
+          await room.record('module.secret.forgotten', { module: id, name: gone.forgot });
+          return sendJson(response, 200, { ok: true, held: await vaultSummary(root, id) });
+        }
+        const kept = await writeSecret(root, id, name, payload.secret);
+        if (!kept.ok) return sendJson(response, 400, { error: kept.error });
+        // The name and the length, never the secret — the same way privacy counts its terms.
+        await room.record('module.secret.kept', { module: id, name: kept.name, bytes: kept.bytes });
+        return sendJson(response, 200, { ok: true, held: await vaultSummary(root, id) });
+      }
       // for it and never reaches MADRE's config, its ledger or its logs.
       const keyMatch = request.method === 'POST' && url.pathname.match(/^\/api\/agents\/([a-z0-9-]+)\/key$/);
       if (keyMatch) {
@@ -1428,6 +1602,12 @@ export async function createPulseServer({
         await runInstaller({ command: opencode.path, args: ['models'], projectRoot: canonicalProjectRoot, timeoutMs: 20000, onLine: (line) => { if (/^[\w.-]+\/[\w.:-]+$/.test(line.trim())) models.push(line.trim()); } });
         return sendJson(response, 200, { models });
       }
+      // One answer, not the room. The master brake lives next door and means something else.
+      if (request.method === 'POST' && url.pathname === '/api/stop-turn') {
+        const payload = await body(request).catch(() => ({}));
+        const stopped = await room.stopTurn(String(payload.messageId ?? ''));
+        return sendJson(response, stopped ? 200 : 404, stopped ? { stopped: true } : { error: t('That turn is not running any more.') });
+      }
       if (request.method === 'POST' && url.pathname === '/api/stop-all') {
         const result = await room.stopAll();
         return sendJson(response, 202, { stopped: true, ...result });

package/src/smtp.mjs

@@ -0,0 +1,122 @@
+// SMTP, enough of it to send one message over TLS. No dependencies, by the same rule as the rest
+// of MADRE: a library that handles the human's mail password is a library somebody has to read.
+//
+// What it does: open a TLS socket, greet, authenticate, hand over one message, quit. What it does
+// NOT do: STARTTLS on a plaintext port (the session would begin in the clear), attachments,
+// multipart, or any form of queuing. One message, encrypted from the first byte, or nothing.
+//
+// The protocol is a dialogue of three-digit replies. A reply may span lines — `250-` continues,
+// `250 ` ends — and that is the only parsing subtlety here.
+
+import { connect } from 'node:tls';
+
+export const SMTP_PORT = 465;                  // implicit TLS. Never 25, never 587 without TLS.
+const CRLF = '\r\n';
+
+// A reply ends at the first COMPLETE line whose code is followed by a space rather than a hyphen:
+// `250-` continues, `250 ` ends. The line has to carry its own newline, or a chunk that split
+// mid-line would be read as a finished answer.
+const ENDS = /^(\d{3})(?: [^\r\n]*)?\r\n/m;
+
+// An address, strictly enough that it cannot carry a second one. A newline in a header is how a
+// message gets extra recipients nobody typed, so anything with control characters is refused
+// rather than escaped.
+const ADDRESS = /^[^\s<>@,;:"\\\u0000-\u001f]+@[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+export const validAddress = (value) => ADDRESS.test(String(value ?? '').trim());
+
+// A header value, with the one thing that must never survive: a line break. Folding is not
+// attempted — a long subject travels long — because a header that folds wrongly is a header that
+// injects.
+export const headerSafe = (value) => String(value ?? '').replace(/[\r\n\u0000]+/g, ' ').trim();
+
+// Anything non-ASCII in a header has to be encoded or it arrives as mojibake. RFC 2047, base64,
+// whole-value: simpler than word-splitting and correct for the subjects people actually write.
+export function encodeHeader(value) {
+  const clean = headerSafe(value);
+  if (!clean || /^[\x20-\x7e]*$/.test(clean)) return clean;
+  return `=?UTF-8?B?${Buffer.from(clean, 'utf8').toString('base64')}?=`;
+}
+
+// A line beginning with a dot ends the DATA stage. Doubling it is the protocol's own escape, and
+// forgetting it is how a message gets truncated by its own body.
+export const dotStuff = (body) => String(body ?? '').replace(/\r?\n/g, CRLF).replace(/^\./gm, '..');
+
+export function buildMessage({ from, fromName = '', to, subject, body, date = new Date() }) {
+  const sender = fromName ? `${encodeHeader(fromName)} <${from}>` : from;
+  const headers = [
+    `From: ${sender}`,
+    `To: ${to.join(', ')}`,
+    `Subject: ${encodeHeader(subject)}`,
+    `Date: ${date.toUTCString()}`,
+    `Message-ID: <${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}@${from.split('@')[1]}>`,
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=utf-8',
+    'Content-Transfer-Encoding: 8bit',
+  ];
+  return `${headers.join(CRLF)}${CRLF}${CRLF}${dotStuff(body)}`;
+}
+
+// One conversation. Every step says what it expects, so a refusal names the step it failed at
+// instead of surfacing as a bare three-digit code.
+export async function sendMail({ host = 'smtp.gmail.com', port = SMTP_PORT, user, password, from, fromName = '', to, subject, body, timeoutMs = 20000, connectImpl = connect, date = undefined }) {
+  const recipients = (Array.isArray(to) ? to : [to]).map((one) => String(one ?? '').trim()).filter(Boolean);
+  if (!validAddress(from)) throw Object.assign(new Error('The sending address is not an address.'), { code: 'BAD_FROM' });
+  if (!recipients.length) throw Object.assign(new Error('Say who it goes to.'), { code: 'NO_RECIPIENT' });
+  for (const one of recipients) {
+    if (!validAddress(one)) throw Object.assign(new Error(`That is not an address: ${one}`), { code: 'BAD_RECIPIENT' });
+  }
+  if (!password) throw Object.assign(new Error('There is no app password in the vault for this connector.'), { code: 'NO_SECRET' });
+
+  const socket = connectImpl({ host, port, servername: host });
+  socket.setEncoding('utf8');
+  socket.setTimeout(timeoutMs);
+
+  let buffer = '';
+  let waiting = null;
+  const fail = (error) => { if (waiting) { const { reject } = waiting; waiting = null; reject(error); } };
+  socket.on('error', (error) => fail(Object.assign(error, { code: error.code ?? 'SMTP_SOCKET' })));
+  socket.on('timeout', () => { socket.destroy(); fail(Object.assign(new Error(`${host} stopped answering.`), { code: 'SMTP_TIMEOUT' })); });
+  socket.on('close', () => fail(Object.assign(new Error(`${host} closed the connection.`), { code: 'SMTP_CLOSED' })));
+  socket.on('data', (chunk) => {
+    buffer += chunk;
+    const done = buffer.match(ENDS);
+    if (!done || !waiting) return;
+    const text = buffer.trim();
+    buffer = '';
+    const { resolve } = waiting;
+    waiting = null;
+    resolve({ code: Number(done[1]), text });
+  });
+
+  const read = () => new Promise((resolve, reject) => { waiting = { resolve, reject }; });
+  const say = async (line, expect, step) => {
+    if (line !== null) socket.write(`${line}${CRLF}`);
+    const reply = await read();
+    if (!expect.includes(reply.code)) {
+      socket.destroy();
+      throw Object.assign(new Error(`${host} refused at ${step}: ${reply.text.split(/\r?\n/)[0]}`), { code: `SMTP_${reply.code}`, step, reply: reply.text });
+    }
+    return reply;
+  };
+
+  try {
+    await say(null, [220], 'greeting');
+    await say(`EHLO ${from.split('@')[1]}`, [250], 'EHLO');
+    // AUTH LOGIN: the user and the password, each base64, each on its own line. Chosen over
+    // PLAIN because it is what Gmail documents for app passwords.
+    await say('AUTH LOGIN', [334], 'AUTH');
+    await say(Buffer.from(user ?? from, 'utf8').toString('base64'), [334], 'user');
+    await say(Buffer.from(password, 'utf8').toString('base64'), [235], 'password');
+    await say(`MAIL FROM:<${from}>`, [250], 'MAIL FROM');
+    for (const one of recipients) await say(`RCPT TO:<${one}>`, [250, 251], 'RCPT TO');
+    await say('DATA', [354], 'DATA');
+    const message = buildMessage({ from, fromName, to: recipients, subject, body, ...(date ? { date } : {}) });
+    const accepted = await say(`${message}${CRLF}.`, [250], 'message');
+    socket.write(`QUIT${CRLF}`);
+    socket.end();
+    return { ok: true, to: recipients, bytes: Buffer.byteLength(message, 'utf8'), reply: accepted.text.split(/\r?\n/)[0] };
+  } catch (error) {
+    socket.destroy();
+    throw error;
+  }
+}

package/src/vault.mjs

@@ -0,0 +1,100 @@
+// The vault: where a connector's secret lives.
+//
+// Until now MADRE held none. A key for Gemini or OpenCode is written where THAT CLI looks for it
+// and MADRE keeps no copy — which is a promise worth having, and it only works because there is a
+// CLI to hand it to. A connector has none: the module itself is what talks to the service, so if
+// MADRE does not hold the secret, nobody does.
+//
+// So it holds them, and the terms are these:
+//
+//   · One file per module, under `<stateRoot>/credentials/`, `0600` inside a `0700` directory.
+//   · Never in the config, never in the ledger, never in a log, never in a prompt. The ledger
+//     records that a secret was SET and under which name — never the value, the same way privacy
+//     counts how many terms it guards and never which.
+//   · Written only from this computer. The server refuses a secret arriving over the network.
+//   · `summary()` is what every other part of MADRE is allowed to see: names and sizes, no values.
+//
+// Nothing here reads a secret into a turn. A module asks for its own and hands it to the server it
+// spawns, through that process's environment — which is how a CLI gets one too.
+
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const OWNER_ONLY = 0o600;
+const OWNER_DIR = 0o700;
+const MAX_SECRET = 8000;
+
+export const vaultDir = (stateRoot) => join(stateRoot, 'credentials');
+const fileFor = (stateRoot, moduleId) => join(vaultDir(stateRoot), `${moduleId}.json`);
+
+// A module id and a secret name are both file-ish and both come from outside: anything that is
+// not plainly a name is refused rather than sanitised, because a sanitised path is a path that
+// looked wrong and was used anyway.
+const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+export const validName = (value) => NAME.test(String(value ?? ''));
+
+async function readAll(stateRoot, moduleId) {
+  try { return JSON.parse(await readFile(fileFor(stateRoot, moduleId), 'utf8')); }
+  catch { return {}; }
+}
+
+// What a module put away, for the module itself. The only function in MADRE that returns a value.
+export async function readSecret(stateRoot, moduleId, name) {
+  if (!validName(moduleId) || !validName(name)) return null;
+  const secret = (await readAll(stateRoot, moduleId))[name];
+  return typeof secret === 'string' && secret ? secret : null;
+}
+
+export async function writeSecret(stateRoot, moduleId, name, value) {
+  if (!validName(moduleId)) return { ok: false, error: 'That is not a module id.' };
+  if (!validName(name)) return { ok: false, error: 'That is not a secret name.' };
+  const secret = String(value ?? '').trim();
+  if (!secret) return { ok: false, error: 'Paste the secret first.' };
+  if (/\s/.test(secret)) return { ok: false, error: 'That does not look like a secret: it has spaces or line breaks.' };
+  if (secret.length > MAX_SECRET) return { ok: false, error: 'That is too long to be a secret.' };
+  const dir = vaultDir(stateRoot);
+  await mkdir(dir, { recursive: true, mode: OWNER_DIR });
+  // An older vault directory may predate this mode; set it either way rather than trust the
+  // creation flags of a directory that was already there.
+  await chmod(dir, OWNER_DIR).catch(() => {});
+  const all = await readAll(stateRoot, moduleId);
+  all[name] = secret;
+  await writeFile(fileFor(stateRoot, moduleId), JSON.stringify(all), { mode: OWNER_ONLY });
+  await chmod(fileFor(stateRoot, moduleId), OWNER_ONLY).catch(() => {});
+  return { ok: true, name, bytes: secret.length };
+}
+
+export async function forgetSecret(stateRoot, moduleId, name = null) {
+  if (!validName(moduleId)) return { ok: false, error: 'That is not a module id.' };
+  if (name === null) {
+    await rm(fileFor(stateRoot, moduleId), { force: true });
+    return { ok: true, forgot: 'all' };
+  }
+  if (!validName(name)) return { ok: false, error: 'That is not a secret name.' };
+  const all = await readAll(stateRoot, moduleId);
+  if (!(name in all)) return { ok: true, forgot: null };
+  delete all[name];
+  if (Object.keys(all).length) await writeFile(fileFor(stateRoot, moduleId), JSON.stringify(all), { mode: OWNER_ONLY });
+  else await rm(fileFor(stateRoot, moduleId), { force: true });
+  return { ok: true, forgot: name };
+}
+
+// What the room, the cards and the ledger may know: that a secret is there, what it is called and
+// how long it is. Never the secret. This is the only shape that leaves this file for anyone but
+// the module that owns it.
+export async function summary(stateRoot, moduleId = null) {
+  let files = [];
+  try { files = (await readdir(vaultDir(stateRoot))).filter((name) => name.endsWith('.json')); }
+  catch { return []; }
+  const held = [];
+  for (const file of files) {
+    const id = file.replace(/\.json$/, '');
+    if (moduleId && id !== moduleId) continue;
+    const all = await readAll(stateRoot, id);
+    for (const [name, secret] of Object.entries(all)) {
+      if (typeof secret !== 'string') continue;
+      held.push({ module: id, name, bytes: secret.length });
+    }
+  }
+  return held.sort((a, b) => `${a.module}${a.name}`.localeCompare(`${b.module}${b.name}`));
+}