@jossuealcala/madre 0.7.2 → 1.0.0

package/src/bridge/devices.mjs

@@ -0,0 +1,202 @@
+// The phones that may reach this Mac, and the networks where they may.
+//
+// One file, `~/.pulse/devices.json`, owner-only, shared by every room on this Mac: any of them can
+// make an invitation and whichever hosts the bridge redeems it. What is kept of a phone is a
+// fingerprint of its token, never the token; what is kept of an invitation is a fingerprint of its
+// code. Both fingerprints are HMACs under one key that lives in `~/.pulse/credentials/bridge.key`
+// (docs/MOBILE.md, D-M01): MADRE's only key of its own, never in the config, a ledger or a log.
+//
+// Several rooms are separate processes, so every change takes a lock file, reads, changes and
+// writes the whole file back by rename. A reader never sees half a file.
+
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const OWNER_ONLY = 0o600;
+export const INVITE_MS = 10 * 60 * 1000;
+export const SESSION_MS = 30 * 24 * 60 * 60 * 1000;
+// A phone's last visit is written at most this often: every request would be a write.
+const SEEN_EVERY_MS = 60 * 60 * 1000;
+
+const storePath = (root) => join(root, 'devices.json');
+const lockPath = (root) => join(root, 'devices.lock');
+const keyPath = (root) => join(root, 'credentials', 'bridge.key');
+
+const empty = () => ({ version: 1, enabled: true, devices: [], invites: [], networks: [] });
+
+// The key is made the first time it is needed and never leaves this file.
+export async function bridgeKey(root) {
+  const file = keyPath(root);
+  try {
+    const hex = (await readFile(file, 'utf8')).trim();
+    if (/^[0-9a-f]{64}$/.test(hex)) return Buffer.from(hex, 'hex');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  await mkdir(join(root, 'credentials'), { recursive: true, mode: 0o700 });
+  const key = randomBytes(32);
+  // `wx`: two rooms making it at once keep the one that landed first.
+  try {
+    await writeFile(file, `${key.toString('hex')}\n`, { mode: OWNER_ONLY, flag: 'wx' });
+    return key;
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    return Buffer.from((await readFile(file, 'utf8')).trim(), 'hex');
+  }
+}
+
+const fingerprint = (key, purpose, secret) => createHmac('sha256', key).update(`${purpose}:${secret}`).digest('hex');
+const same = (a, b) => typeof a === 'string' && typeof b === 'string' && a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+const token = () => randomBytes(32).toString('base64url');
+
+function normalise(raw) {
+  const base = empty();
+  if (!raw || typeof raw !== 'object') return base;
+  return {
+    version: 1,
+    enabled: raw.enabled !== false,
+    devices: Array.isArray(raw.devices) ? raw.devices.filter((one) => one && typeof one.id === 'string' && typeof one.hash === 'string') : [],
+    invites: Array.isArray(raw.invites) ? raw.invites.filter((one) => one && typeof one.hash === 'string' && Number.isFinite(one.expiresAt)) : [],
+    networks: Array.isArray(raw.networks) ? raw.networks.filter((one) => one && typeof one.id === 'string') : [],
+  };
+}
+
+export async function readStore(root) {
+  try {
+    return normalise(JSON.parse(await readFile(storePath(root), 'utf8')));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return empty();
+    throw error;
+  }
+}
+
+async function lock(root) {
+  await mkdir(root, { recursive: true });
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try {
+      const handle = await open(lockPath(root), 'wx');
+      await handle.close();
+      return;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      // A lock left by a process that died mid-write is stale after a few seconds.
+      const held = await stat(lockPath(root)).catch(() => null);
+      if (held && Date.now() - held.mtimeMs > 5000) { await rm(lockPath(root), { force: true }); continue; }
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  }
+  throw new Error('The list of phones is busy; try again.');
+}
+
+// Read, change, write, under the lock. `change` mutates the store and returns what the caller wants.
+export async function withStore(root, change, { now = Date.now() } = {}) {
+  await lock(root);
+  try {
+    const store = await readStore(root);
+    // Lapsed invitations and phones are dropped on every write, so the file never grows.
+    store.invites = store.invites.filter((one) => (one.redeemedAt ? now - one.redeemedAt < INVITE_MS : one.expiresAt > now));
+    store.devices = store.devices.filter((one) => now - (one.seenAt ?? one.createdAt ?? 0) < SESSION_MS);
+    const result = await change(store);
+    const file = storePath(root);
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(store, null, 2)}\n`, { mode: OWNER_ONLY });
+    await rename(temporary, file);
+    return result;
+  } finally {
+    await rm(lockPath(root), { force: true });
+  }
+}
+
+// An invitation: a code that goes only into the QR, good once, for ten minutes.
+export async function createInvite(root, { now = Date.now(), ttlMs = INVITE_MS } = {}) {
+  const key = await bridgeKey(root);
+  const code = token();
+  const hash = fingerprint(key, 'invite', code);
+  const id = hash.slice(0, 12);
+  await withStore(root, (store) => { store.invites.push({ id, hash, createdAt: now, expiresAt: now + ttlMs }); }, { now });
+  return { id, code, expiresAt: now + ttlMs };
+}
+
+// What a phone says it is, from its user agent: only the kind, never the string itself.
+export function deviceKind(userAgent = '') {
+  if (/iPhone/i.test(userAgent)) return 'iphone';
+  if (/iPad/i.test(userAgent) || (/Macintosh/i.test(userAgent) && /Mobile/i.test(userAgent))) return 'ipad';
+  if (/Android/i.test(userAgent)) return /Mobile/i.test(userAgent) ? 'android' : 'android-tablet';
+  return 'other';
+}
+
+// The phone hands the code back; it becomes a phone with a token of its own. A code is spent the
+// moment it is used, even by a request that fails afterwards.
+export async function redeemInvite(root, code, { userAgent = '', now = Date.now() } = {}) {
+  if (typeof code !== 'string' || code.length < 20 || code.length > 100) return null;
+  const key = await bridgeKey(root);
+  const hash = fingerprint(key, 'invite', code);
+  return withStore(root, (store) => {
+    const invite = store.invites.find((one) => same(one.hash, hash));
+    if (!invite || invite.redeemedAt || invite.expiresAt <= now) return null;
+    const secret = token();
+    const device = { id: randomUUID(), kind: deviceKind(userAgent), createdAt: now, seenAt: now, hash: fingerprint(key, 'device', secret) };
+    store.devices.push(device);
+    invite.redeemedAt = now;
+    invite.device = device.id;
+    return { device: publicDevice(device), token: secret };
+  }, { now });
+}
+
+export const publicDevice = ({ id, kind, createdAt, seenAt }) => ({ id, kind, createdAt, seenAt });
+
+// The phone behind a token, or null. Its last visit is written at most once an hour.
+export async function deviceForToken(root, secret, { now = Date.now(), store = null } = {}) {
+  if (typeof secret !== 'string' || secret.length < 20 || secret.length > 100) return null;
+  const key = await bridgeKey(root);
+  const hash = fingerprint(key, 'device', secret);
+  const current = store ?? await readStore(root);
+  const device = current.devices.find((one) => same(one.hash, hash));
+  if (!device || now - (device.seenAt ?? device.createdAt) >= SESSION_MS) return null;
+  if (now - (device.seenAt ?? 0) >= SEEN_EVERY_MS) {
+    await withStore(root, (fresh) => {
+      const mine = fresh.devices.find((one) => one.id === device.id);
+      if (mine) mine.seenAt = now;
+    }, { now }).catch(() => null);
+  }
+  return publicDevice({ ...device, seenAt: Math.max(device.seenAt ?? 0, now) });
+}
+
+export async function forgetDevice(root, id) {
+  return withStore(root, (store) => {
+    const before = store.devices.length;
+    store.devices = store.devices.filter((one) => one.id !== id);
+    return store.devices.length < before;
+  });
+}
+
+export async function setEnabled(root, on) {
+  return withStore(root, (store) => { store.enabled = Boolean(on); return store.enabled; });
+}
+
+// A network is known by the fingerprint network.mjs makes of it; its name is the person's.
+export async function trustNetwork(root, { id, name = null, now = Date.now() }) {
+  if (typeof id !== 'string' || !id) throw new Error('No network to trust.');
+  return withStore(root, (store) => {
+    if (!store.networks.some((one) => one.id === id)) store.networks.push({ id, name: typeof name === 'string' ? name.slice(0, 60) : null, addedAt: now });
+    return store.networks;
+  }, { now });
+}
+
+export async function forgetNetwork(root, id) {
+  return withStore(root, (store) => {
+    store.networks = store.networks.filter((one) => one.id !== id);
+    return store.networks;
+  });
+}
+
+// What the Mac's own page may see: never a hash.
+export function storeView(store, { now = Date.now() } = {}) {
+  return {
+    enabled: store.enabled,
+    devices: store.devices.map(publicDevice),
+    invites: store.invites.filter((one) => one.expiresAt > now || one.redeemedAt).map(({ id, expiresAt, redeemedAt = null, device = null }) => ({ id, expiresAt, redeemedAt, device })),
+    networks: store.networks.map(({ id, name, addedAt }) => ({ id, name, addedAt })),
+  };
+}

package/src/bridge/handoff.mjs

@@ -0,0 +1,45 @@
+// Where the person was, on the Mac and on the phone (docs/MOBILE.md, MOV-005).
+//
+// One small file for the whole Mac, `~/.pulse/handoff.json`, owner-only: the last place each side
+// stood — which room, which conversation, the message at the top of the screen and what was left
+// in the box. The other side offers to pick it up from there. A draft is the person's own words,
+// so it is kept the way the ledger is kept, beside it, and only the latest one.
+
+import { randomUUID } from 'node:crypto';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const DRAFT_LIMIT = 4000;
+const SIDES = new Set(['mac', 'phone']);
+const file = (root) => join(root, 'handoff.json');
+
+export async function readHandoff(root) {
+  try {
+    const raw = JSON.parse(await readFile(file(root), 'utf8'));
+    return { mac: raw?.mac ?? null, phone: raw?.phone ?? null };
+  } catch {
+    return { mac: null, phone: null };
+  }
+}
+
+const text = (value, limit) => (typeof value === 'string' ? value.slice(0, limit) : null);
+
+export async function writeHandoff(root, side, entry, { now = Date.now() } = {}) {
+  if (!SIDES.has(side)) throw new Error('Unknown side.');
+  const current = await readHandoff(root);
+  current[side] = {
+    room: text(entry.room, 120),
+    project: text(entry.project, 120),
+    port: Number.isInteger(entry.port) ? entry.port : null,
+    chat: text(entry.chat, 40),
+    chatTitle: text(entry.chatTitle, 120),
+    anchor: text(entry.anchor, 80),
+    draft: text(entry.draft, DRAFT_LIMIT) ?? '',
+    kind: side === 'phone' ? text(entry.kind, 20) : null,
+    at: now,
+  };
+  const temporary = `${file(root)}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file(root));
+  return current[side];
+}

package/src/bridge/host.mjs

@@ -0,0 +1,82 @@
+// Who keeps the bridge up. Every room on this Mac offers to; the port decides.
+//
+// No process of its own and nothing to start: each room, every few seconds, asks whether a phone
+// should be able to reach this Mac right now — the phone is on, a phone is paired or a code is
+// waiting, and the network is one the person trusts — and if so tries to open the bridge's port.
+// The first room that gets it hosts the bridge; the others find it taken and leave it be. When the
+// hosting room closes, the next one to ask takes over. On a network nobody trusted, whoever hosts
+// it closes it.
+
+import { readStore } from './devices.mjs';
+import { currentNetwork } from './network.mjs';
+import { BRIDGE_PORT, createBridge } from './server.mjs';
+
+// `allowed`: whether this Mac offers the phone at all (MADRE 1.0 keeps it a preview, src/server.mjs).
+export function hostBridge({ root, publicDirectory, port = BRIDGE_PORT, every = 15_000, network = currentNetwork, listenHost = '0.0.0.0', allowed = async () => true, log = (line) => console.error(line) }) {
+  let server = null;
+  let running = null;
+  let timer = null;
+  let last = { network: null, trusted: false, wanted: false };
+
+  const open = () => new Promise((resolve) => {
+    const candidate = createBridge({ root, port, publicDirectory });
+    candidate.once('error', (error) => resolve(error.code === 'EADDRINUSE' ? null : (log(`MADRE bridge: ${error.message}`), null)));
+    candidate.listen(port, listenHost, () => resolve(candidate));
+  });
+  const close = () => new Promise((resolve) => {
+    if (!server) return resolve();
+    const closing = server;
+    server = null;
+    closing.closeAllConnections?.();
+    closing.close(() => resolve());
+  });
+
+  async function settle() {
+    const store = await readStore(root);
+    const now = Date.now();
+    const waiting = store.invites.some((one) => !one.redeemedAt && one.expiresAt > now);
+    const wanted = (await allowed()) && store.enabled && (store.devices.length > 0 || waiting);
+    const here = wanted ? await network().catch(() => null) : null;
+    const trusted = Boolean(here && store.networks.some((one) => one.id === here.id));
+    last = { network: here, trusted, wanted };
+    if (wanted && trusted && !server) server = await open();
+    else if ((!wanted || !trusted) && server) await close();
+    return status();
+  }
+
+  // One at a time: a tick asked for while another runs waits for it and runs again.
+  function tick() {
+    running = (running ?? Promise.resolve()).then(settle, settle).catch((error) => { log(`MADRE bridge: ${error.message}`); return status(); });
+    return running;
+  }
+
+  function status() {
+    return { hosting: Boolean(server), port, network: last.network, trusted: last.trusted, wanted: last.wanted };
+  }
+
+  return {
+    start() {
+      if (timer) return;
+      timer = setInterval(() => { void tick(); }, every);
+      timer.unref?.();
+      void tick();
+    },
+    tick,
+    status,
+    async stop() {
+      clearInterval(timer);
+      timer = null;
+      await close();
+    },
+  };
+}
+
+// Is a bridge up on this Mac, whichever room hosts it?
+export async function bridgeAnswers(port = BRIDGE_PORT) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/bridge/ping`, { signal: AbortSignal.timeout(600) });
+    return response.ok && (await response.json()).madre === true;
+  } catch {
+    return false;
+  }
+}

package/src/bridge/network.mjs

@@ -0,0 +1,133 @@
+// Which network this Mac is on, and how a phone on it reaches the Mac.
+//
+// A network is known by its router: the hardware address of the default gateway, hashed. Two
+// cafés both handing out 192.168.1.1 are still two routers. Nothing here asks for a permission:
+// macOS answers `route`, `arp` and `ipconfig` for anyone, and Linux keeps both tables in /proc.
+// Where MADRE cannot read the router's address the network is unknown, and an unknown network is
+// never a trusted one, so the phone simply is not offered there.
+
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { createSocket } from 'node:dgram';
+import { readFile } from 'node:fs/promises';
+import { networkInterfaces } from 'node:os';
+
+const run = (file, args) => new Promise((resolve) => {
+  execFile(file, args, { timeout: 2000, windowsHide: true }, (error, stdout) => resolve(error ? '' : String(stdout)));
+});
+
+// `0:1a:2b:…` and `00:1A:2B:…` are the same router.
+export function normaliseMac(mac) {
+  if (typeof mac !== 'string') return null;
+  const parts = mac.trim().toLowerCase().split(/[:-]/);
+  if (parts.length !== 6 || parts.some((part) => !/^[0-9a-f]{1,2}$/.test(part))) return null;
+  const out = parts.map((part) => part.padStart(2, '0')).join(':');
+  return out === '00:00:00:00:00:00' || out === 'ff:ff:ff:ff:ff:ff' ? null : out;
+}
+
+export function parseDarwinRoute(raw) {
+  const text = String(raw ?? '');
+  const gateway = text.match(/^\s*gateway:\s*(\S+)/m)?.[1] ?? null;
+  const device = text.match(/^\s*interface:\s*(\S+)/m)?.[1] ?? null;
+  return gateway && /^\d+\.\d+\.\d+\.\d+$/.test(gateway) ? { gateway, device } : null;
+}
+
+export const parseDarwinArp = (text) => normaliseMac(String(text ?? '').match(/ at ([0-9a-f:]+) /i)?.[1] ?? null);
+
+// `ipconfig getsummary` names the router by its hardware address twice when the network speaks
+// IPv6: in the router advertisement's source link-address and in the DHCPv6 server's DUID. A
+// process macOS will not show the neighbour table to (the case for anything Node starts) can
+// still read this.
+export function parseDarwinSummary(raw) {
+  const text = String(raw ?? '');
+  const advertised = text.match(/source link-address option[^\n]*?:\s*([0-9a-f]{1,2}(?::[0-9a-f]{1,2}){5})/i)?.[1];
+  const server = text.match(/SERVERID[^\n]*?Addr\s+([0-9a-f]{1,2}(?::[0-9a-f]{1,2}){5})/i)?.[1];
+  return normaliseMac(advertised ?? null) ?? normaliseMac(server ?? null);
+}
+
+// /proc/net/route keeps the gateway as little-endian hex.
+export function parseLinuxRoute(text) {
+  for (const line of text.split('\n').slice(1)) {
+    const [device, destination, gateway] = line.trim().split(/\s+/);
+    if (destination !== '00000000' || !gateway || gateway === '00000000') continue;
+    const bytes = gateway.match(/../g).map((pair) => parseInt(pair, 16)).reverse();
+    return { gateway: bytes.join('.'), device };
+  }
+  return null;
+}
+
+export function parseLinuxArp(text, ip) {
+  for (const line of text.split('\n').slice(1)) {
+    const [address, , , mac] = line.trim().split(/\s+/);
+    if (address === ip) return normaliseMac(mac);
+  }
+  return null;
+}
+
+// The system forgets a router it has not talked to in a while; one packet to it makes the system
+// look it up again. On macOS one ping (it needs no privilege there); elsewhere one empty datagram
+// to the discard port, where nothing listens and nothing answers.
+const datagram = (gateway) => new Promise((resolve) => {
+  try {
+    const socket = createSocket('udp4');
+    socket.once('error', () => { socket.close(); resolve(); });
+    socket.send(Buffer.alloc(1), 9, gateway, () => { socket.close(); setTimeout(resolve, 300); });
+  } catch {
+    resolve();
+  }
+});
+
+const nudge = (gateway, platform = process.platform) => (platform === 'darwin' ? run('/sbin/ping', ['-c', '1', '-t', '1', gateway]) : datagram(gateway));
+
+const networkId = (mac) => createHash('sha256').update(`network:${mac}`).digest('hex').slice(0, 16);
+
+// The network this Mac is on now: { id, gateway, device } or null when it cannot be told.
+export async function currentNetwork({ platform = process.platform, exec = run, read = (file) => readFile(file, 'utf8'), poke = nudge } = {}) {
+  let route = null;
+  let lookup = null;
+  if (platform === 'darwin') {
+    route = parseDarwinRoute(await exec('/sbin/route', ['-n', 'get', 'default']));
+    lookup = async () => parseDarwinArp(await exec('/usr/sbin/arp', ['-n', route.gateway]))
+      ?? (/^[a-z0-9]+$/.test(route.device ?? '') ? parseDarwinSummary(await exec('/usr/sbin/ipconfig', ['getsummary', route.device])) : null);
+  } else if (platform === 'linux') {
+    route = parseLinuxRoute(await read('/proc/net/route').catch(() => ''));
+    lookup = async () => parseLinuxArp(await read('/proc/net/arp').catch(() => ''), route.gateway);
+  }
+  if (!route) return null;
+  let mac = await lookup();
+  if (!mac) {
+    await poke(route.gateway, platform);
+    mac = await lookup();
+  }
+  if (!mac) return null;
+  return { id: networkId(mac), gateway: route.gateway, device: route.device };
+}
+
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+// Loopback, the private ranges and link-local: the only addresses a phone on the same Wi-Fi has.
+// Anything else reached the bridge from outside the network, through a forwarded port or worse.
+export function isPrivateAddress(raw) {
+  if (typeof raw !== 'string') return false;
+  const address = raw.startsWith('::ffff:') ? raw.slice(7) : raw;
+  const v4 = address.match(IPV4);
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+  }
+  const v6 = address.toLowerCase();
+  return v6 === '::1' || /^f[cd][0-9a-f]{2}:/.test(v6) || /^fe[89ab][0-9a-f]:/.test(v6);
+}
+
+// This Mac's addresses on the local network, the one on the default route's interface first.
+export function lanAddresses({ device = null, interfaces = networkInterfaces() } = {}) {
+  const out = [];
+  for (const [name, entries] of Object.entries(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (entry.internal || entry.family !== 'IPv4' || !isPrivateAddress(entry.address) || entry.address.startsWith('169.254.')) continue;
+      out.push({ name, address: entry.address });
+    }
+  }
+  out.sort((a, b) => Number(b.name === device) - Number(a.name === device));
+  return out.map((one) => one.address);
+}

package/src/bridge/policy.mjs

@@ -0,0 +1,89 @@
+// What a phone may do in a room (docs/MOBILE.md, section 4).
+//
+// A list of what passes, not of what does not: a route the room grows tomorrow stays on the Mac
+// until somebody decides it belongs on the phone too. Reading is wide; acting is everything a
+// conversation needs. From the phone a person asks up to #2 CREATE, answers what an agent asks
+// (a mode up to #2), runs a line an agent proposed, undoes, stops anything, opens or starts a
+// conversation, changes settings and switches MADRE's own modules on or off. What stays on the
+// Mac: #3 CONTROL (its key is checked with crypto.subtle, which a page on plain http does not
+// have) and #4 AIRLOCK, permissions and the key that opens them, the keys of a provider,
+// installing code somebody wrote, forgetting memories and editing files. The room checks the
+// parts a path cannot say — which module, which mode was asked — on its own side as well.
+
+import { normalizeMode } from '../capabilities.mjs';
+import { t } from '../i18n.mjs';
+
+// Every file the room's page loads: one missing here and app.js cannot import it, so the whole page
+// stops on the phone (test/phone-bridge.test.mjs reads app.js's imports to keep this whole).
+const STATIC = new Set(['/', '/app.js', '/nostromo-engine.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js', '/syntax.js', '/editor.js', '/routing.js', '/abduction.js', '/styles.css', '/review-ask.js', '/loader.js', '/tour.js', '/tour-chapters.js', '/touch.js']);
+
+const READ = new Set([
+  '/api/state', '/api/events', '/api/chats', '/api/version', '/api/whats-new', '/api/glance', '/api/handoff',
+  '/api/memory', '/api/memory/about', '/api/memory/dashboard',
+  '/api/tree', '/api/tree/search', '/api/files',
+  '/api/questions', '/api/decisions', '/api/turns', '/api/models', '/api/commands', '/api/mother', '/api/briefing',
+  '/api/settings', '/api/privacy', '/api/extensions', '/api/sentinel', '/api/maturity', '/api/maturity/exams',
+  // The servers on the Mac, to be seen; they open on the Mac.
+  '/api/ports',
+  // Modules that only read on GET.
+  '/api/ollama', '/api/intents',
+]);
+const READ_PATTERNS = [
+  /^\/assets\/[a-z0-9/_.-]+$/i,
+  /^\/preview\/(project|attachments)\/.+$/,
+  /^\/api\/memory\/\d+\/traffic$/,
+];
+
+const ACT = new Set([
+  'POST /api/messages', 'POST /api/messages/rate', 'POST /api/attachments',
+  'POST /api/stop-all', 'POST /api/stop-turn', 'POST /api/runs', 'POST /api/runs/stop',
+  'POST /api/chats', 'POST /api/whats-new/seen', 'POST /api/memory/ask/dismiss', 'POST /api/handoff',
+  'POST /api/intents/suggest',
+  // Settings, minus what the body asks about permissions (see below).
+  'POST /api/settings', 'POST /api/turns', 'POST /api/language', 'POST /api/privacy', 'POST /api/updates/settings', 'POST /api/sentinel/settings',
+  'POST /api/ollama/settings', 'POST /api/ollama/probe', 'POST /api/ollama/start',
+]);
+const ACT_PATTERNS = [
+  ['POST', /^\/api\/plans\/[0-9a-f-]+\/stop$/],
+  ['POST', /^\/api\/chats\/[a-z0-9]+$/],
+  ['PATCH', /^\/api\/chats\/[a-z0-9]+$/],
+  ['POST', /^\/api\/eyecat\/(confirm|dismiss)$/],
+  ['POST', /^\/api\/control\/[\w-]+\/undo$/],
+  // A mode an agent asked for: the room refuses a grant above #2 from a phone.
+  ['POST', /^\/api\/modes\/[\w-]+\/decide$/],
+  // MADRE's own modules, on or off: the room refuses anything that would install code.
+  ['POST', /^\/api\/extensions\/[a-z0-9-]+\/(install|settings)$/],
+  ['POST', /^\/api\/intents(\/[a-z0-9/-]+)?$/],
+];
+
+// The highest mode a phone may arm, and the rule's own words.
+export const PHONE_MAX_MODE = 2;
+const ON_THE_MAC = 'This is done on the Mac.';
+const MODE_ON_THE_MAC = '#3 EDIT and #4 FULL ACCESS are opened from the Mac.';
+const PERMISSIONS_ON_THE_MAC = 'Permissions are changed on the Mac.';
+
+// The only bodies the bridge reads before passing them on.
+export const inspects = (method, pathname) => method === 'POST' && (pathname === '/api/messages' || pathname === '/api/settings');
+
+// A mode written in the message is the mode, as on the Mac: «#3» at a word's edge — in what the
+// person wrote, not in the answer they quote above it (the page's «↩ @agent: “…”» line).
+const MODE_TOKEN = /(^|\s)#([0-4])(?=\s|$)/;
+export const writtenMode = (text) => (typeof text === 'string' ? Number(text.replace(/^↩ [^\n]*\n/, '').match(MODE_TOKEN)?.[2] ?? -1) : -1);
+
+export function phonePolicy({ method = 'GET', pathname = '/', body = null } = {}) {
+  const verb = String(method).toUpperCase();
+  if (verb === 'GET' || verb === 'HEAD') {
+    if (STATIC.has(pathname) || READ.has(pathname) || READ_PATTERNS.some((pattern) => pattern.test(pathname))) return { allow: true };
+    return { allow: false, status: 403, error: t(ON_THE_MAC) };
+  }
+  const acts = ACT.has(`${verb} ${pathname}`) || ACT_PATTERNS.some(([want, pattern]) => want === verb && pattern.test(pathname));
+  if (!acts) return { allow: false, status: 403, error: t(ON_THE_MAC) };
+  if (pathname === '/api/settings' && body && (body.scopes !== undefined || body.override !== undefined)) return { allow: false, status: 403, error: t(PERMISSIONS_ON_THE_MAC) };
+  if (verb === 'POST' && pathname === '/api/messages') {
+    // Read as the room reads it (src/capabilities.mjs): «"4"» is #4 there, so it is #4 here (TEL-01).
+    const asked = normalizeMode(body?.mode, body?.create === true ? 2 : 1);
+    const written = writtenMode(body?.text);
+    if (Math.max(asked, written) > PHONE_MAX_MODE) return { allow: false, status: 403, error: t(MODE_ON_THE_MAC) };
+  }
+  return { allow: true };
+}