@jossuealcala/madre 0.6.0 → 0.7.0

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}`));
+}

package/src/whats-new.mjs

@@ -0,0 +1,140 @@
+// What a version brings, said to the person who just got it.
+//
+// After an update the room opens once on a sheet of what is new: a few things, each said plainly,
+// each with where to find it, and a way to read every change. Once per version, for everyone who
+// came from an older one; never on a first install, where the tour does that job.
+//
+// Whether it has been seen lives in ~/.pulse/whats-new.json and not in the browser: the page's
+// storage belongs to one port, and the same person opening the room on another port has still
+// seen it. Nothing here touches the network; the link to every change is the release page the
+// room already knows (updates.mjs).
+//
+// The notes are written by hand, version by version, in both languages the room speaks. A minor
+// version cannot be closed without them (scripts/release.mjs); a patch may ship without, and then
+// nothing opens.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { compareVersions } from './updates.mjs';
+
+const FILE = 'whats-new.json';
+
+// `icon` names one of the room's 8-bit icons. `where` says where it lives, in the words the
+// screens use. `more` is the one thing nobody is told how to find.
+export const NOTES = {
+  '0.7.0': {
+    intro: {
+      es: 'Esta versión le da forma a la memoria de la sala: ahora la ves en tres dimensiones, la lees en un tablero y cada memoria te dice cómo está.',
+      en: 'This version gives the room’s memory a shape: you see it in three dimensions, read it on a dashboard, and every memory tells you how it is doing.',
+    },
+    items: [
+      {
+        icon: 'orbit',
+        title: { es: 'NOSTROMO en tres dimensiones', en: 'NOSTROMO in three dimensions' },
+        body: {
+          es: 'El archivo de memorias tiene forma de cerebro y lo giras con el ratón. Al elegir una memoria, la sala la pone de frente, la fija con una mira y atenúa todo lo demás.',
+          en: 'The memory archive is shaped like a brain and you turn it with the mouse. Choose a memory and the room brings it to face you, locks a sight on it and dims everything else.',
+        },
+        where: { es: 'MU/TH/UR › NOSTROMO · arrastra para girar, Shift + arrastra para moverte', en: 'MU/TH/UR › NOSTROMO · drag to turn, Shift + drag to move' },
+      },
+      {
+        icon: 'star',
+        title: { es: 'Cada memoria es una estrella', en: 'Every memory is a star' },
+        body: {
+          es: 'Su brillo dice cuánto la usa la sala; su superficie, si la confirmaste, si nadie la ha juzgado, si resultó falsa o si se está enfriando. En el centro, MOTHER: magma vivo.',
+          en: 'Its brightness says how much the room relies on it; its surface, whether you confirmed it, nobody has judged it yet, it turned out false, or it is cooling. At the centre, MOTHER: living magma.',
+        },
+        where: { es: 'MU/TH/UR › NOSTROMO', en: 'MU/TH/UR › NOSTROMO' },
+      },
+      {
+        icon: 'bars',
+        title: { es: 'Un tablero para la memoria', en: 'A dashboard for memory' },
+        body: {
+          es: 'Lo que el archivo hizo día a día, de qué está hecho, qué tan bien contesta y cuál es el siguiente paso, en una sola pantalla.',
+          en: 'What the archive did day by day, what it is made of, how well it answers and what to do next, on a single screen.',
+        },
+        where: { es: 'MU/TH/UR › MEMORIA', en: 'MU/TH/UR › MEMORY' },
+      },
+      {
+        icon: 'chip',
+        title: { es: 'Ideas para tu propio módulo', en: 'Ideas for a module of your own' },
+        body: {
+          es: 'Escribe /module y elige entre ocho ideas listas para editar: comandos, conectores con tus servicios y fichas propias. Un agente lo escribe y tú lo revisas antes de instalarlo.',
+          en: 'Type /module and pick one of eight ideas ready to edit: commands, connectors to your services and cards of your own. An agent writes it and you review it before it is installed.',
+        },
+        where: { es: 'En la caja de texto · escribe /module', en: 'In the message box · type /module' },
+      },
+      {
+        icon: 'stop',
+        title: { es: 'Detén una respuesta, no la sala', en: 'Stop one reply, not the room' },
+        body: {
+          es: 'Un botón DETENER detiene a un solo agente a mitad de su respuesta; los demás siguen trabajando.',
+          en: 'A STOP button halts one agent in the middle of its reply; the others keep working.',
+        },
+        where: { es: 'En la fila del turno en curso, junto a los segundos', en: 'On the row of the turn in progress, next to the seconds' },
+      },
+      {
+        icon: 'lock',
+        title: { es: 'Más protección desde el navegador', en: 'More protection from the browser' },
+        body: {
+          es: 'Ninguna página web que tengas abierta puede ya instalar un módulo en tu sala ni leer de ella.',
+          en: 'No web page you have open can install a module in your room or read from it anymore.',
+        },
+        where: { es: 'Siempre activo; no tienes que hacer nada', en: 'Always on; there is nothing to set up' },
+      },
+    ],
+    more: {
+      icon: 'ufo',
+      title: { es: 'Una cosa más…', en: 'One more thing…' },
+      body: {
+        es: 'Alguien más viaja a bordo. No está en ningún menú ni en ningún manual. Dicen que solo baja cuando llamas a la nave por su nombre, y por nada más.',
+        en: 'Someone else travels on board. Not in any menu, not in any manual. They say it only comes down when you call the ship by its name, and nothing else.',
+      },
+    },
+  },
+};
+
+export const notesFor = (version) => NOTES[version] ?? null;
+
+// Whether this person should see the sheet for this version. Someone who has seen an older one,
+// or who used the room before the sheet existed, sees it once; a first install never does.
+export function shouldShow({ version, seen = null, returning = false }) {
+  if (!notesFor(version)) return false;
+  if (seen) return compareVersions(version, seen) > 0;
+  return Boolean(returning);
+}
+
+export async function readSeen(root) {
+  try {
+    const value = JSON.parse(await readFile(join(root, FILE), 'utf8'))?.seen;
+    return typeof value === 'string' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function markSeen(root, version) {
+  await mkdir(root, { recursive: true });
+  await writeFile(join(root, FILE), `${JSON.stringify({ seen: version }, null, 2)}\n`);
+}
+
+// Read at start-up, before this run creates anything: a room that already had rooms used MADRE
+// before. A first install has nothing to catch up on, so it is marked as seen and never shown.
+export async function bootWhatsNew({ root, version }) {
+  const seen = await readSeen(root);
+  if (seen) return { seen, returning: true };
+  let returning = false;
+  if (existsSync(join(root, 'rooms'))) {
+    try { returning = (await readdir(join(root, 'rooms'))).length > 0; } catch { returning = false; }
+  }
+  if (!returning) await markSeen(root, version);
+  return { seen: returning ? null : version, returning };
+}
+
+// `any`: the sheet for this version whether or not it was seen, for when it is asked for.
+export async function whatsNew({ root, version, returning, any = false }) {
+  const seen = await readSeen(root);
+  const show = shouldShow({ version, seen, returning });
+  return { version, show, notes: show || any ? notesFor(version) : null };
+}