@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/mailguard-hook.cjs

@@ -0,0 +1,216 @@
+"use strict";
+// MAIL GUARD, THE RUNTIME HOOK. The tool, never a recipe, loads this file into the start step of a preview that has sealed mail settings (NODE_OPTIONS=--require). It stands
+// between the app and Postmark: every send to a Postmark host is rewritten to go to the ONE test inbox the owner named, and anything it cannot read and rewrite is refused.
+// Each rewrite and each refusal is a line in the run log (addresses masked) and a JSON line in AFB_MAIL_FENCE_LOG, which the tool counts into the run's result.
+//
+// WHAT THIS DOES AND DOES NOT PROTECT. It is a fence against mistakes (an app that mails the people in a test database), not against the repo's own code: code the agent wrote
+// can load another HTTP client, spawn a process or call a mail API this file does not know. The owner's word that the token is a test token is what covers that, and it is in
+// the audit chain. This file is CommonJS (a .cts compiled to .cjs) because --require loads CommonJS only; import-equals keeps the real module objects so they can be patched.
+Object.defineProperty(exports, "__esModule", { value: true });
+// import-equals is the only form that keeps the real CommonJS module objects, so the guard can patch them (a --require hook is CommonJS)
+/* eslint-disable @typescript-eslint/no-require-imports */
+const fs = require("node:fs");
+const path = require("node:path");
+const net = require("node:net");
+const http = require("node:http");
+const https = require("node:https");
+// -- CONSTANTS -- //
+const INBOX = String(process.env.AFB_MAIL_FENCE_INBOX || '')
+    .trim()
+    .toLowerCase();
+const LOG = process.env.AFB_MAIL_FENCE_LOG || '';
+const POSTMARK = /(^|\.)postmarkapp\.com\.?$/i;
+const SEND_PATHS = new Set([
+    '/email',
+    '/email/batch',
+    '/email/withtemplate',
+    '/email/batchwithtemplates'
+]);
+const ADDRESS = /[^<>\s,;"]+@[^<>\s,;"]+/g;
+// -- FUNCTIONS -- //
+const record = (event) => {
+    const line = JSON.stringify({ at: new Date().toISOString(), pid: process.pid, ...event });
+    try {
+        if (LOG)
+            fs.appendFileSync(LOG, line + '\n');
+    }
+    catch {
+        // a log that cannot be written must not take the preview down; the console line below still shows
+    }
+    if (event.event !== 'loaded' && event.event !== 'listening')
+        process.stderr.write(`[afb-checks mail guard] ${event.event}: ${event.note || ''}\n`);
+};
+const mask = (a) => String(a).replace(/^(.).*@/, '$1***@');
+const addresses = (v) => (typeof v === 'string' ? v.match(ADDRESS) || [] : []);
+record({
+    event: 'loaded',
+    exe: path.basename(String(process.argv[1] || process.argv[0] || '')),
+    inbox: INBOX ? mask(INBOX) : null
+});
+/** One Postmark message: only the test inbox stays as a recipient; Cc and Bcc go; the subject says who it would have gone to (masked). */
+function rewriteMessage(m) {
+    if (!m || typeof m !== 'object' || Array.isArray(m))
+        return { ok: false, why: 'a message the guard could not read' };
+    const msg = m;
+    // A recipient field in another spelling (cc, TO) could still be read by Postmark: the whole message is refused
+    if (Object.keys(msg).some((k) => /^(to|cc|bcc)$/i.test(k) && !['To', 'Cc', 'Bcc'].includes(k)))
+        return { ok: false, why: 'a recipient field spelled in a way the guard does not rewrite' };
+    const all = ['To', 'Cc', 'Bcc'].flatMap((k) => addresses(msg[k]));
+    if (!all.length)
+        return { ok: false, why: 'a message with no recipient it could read' };
+    if (all.every((a) => a.toLowerCase() === INBOX) && !msg.Cc && !msg.Bcc)
+        return { ok: true, message: msg, changed: false };
+    const out = { ...msg, To: INBOX };
+    delete out.Cc;
+    delete out.Bcc;
+    if (typeof msg.Subject === 'string')
+        out.Subject = `[afb-checks test, would go to ${[...new Set(all.map(mask))].join(', ')}] ${msg.Subject}`;
+    return { ok: true, message: out, changed: true, was: all.map(mask) };
+}
+function rewriteBody(text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, why: 'a body that is not JSON' };
+    }
+    const wrapped = json &&
+        typeof json === 'object' &&
+        !Array.isArray(json) &&
+        Array.isArray(json.Messages);
+    const list = Array.isArray(json)
+        ? json
+        : wrapped
+            ? json.Messages
+            : [json];
+    const done = list.map(rewriteMessage);
+    for (const d of done)
+        if (!d.ok)
+            return { ok: false, why: d.why };
+    const messages = done.map((d) => (d.ok ? d.message : {}));
+    const body = Array.isArray(json)
+        ? messages
+        : wrapped
+            ? { ...json, Messages: messages }
+            : messages[0];
+    return {
+        ok: true,
+        body: JSON.stringify(body),
+        count: done.length,
+        changed: done.filter((d) => d.ok && d.changed).length
+    };
+}
+const refusal = (why) => new Response(JSON.stringify({
+    ErrorCode: 300,
+    Message: `afb-checks mail guard refused this send: ${why}. Mail from a preview goes only to the test inbox.`
+}), { status: 422, headers: { 'content-type': 'application/json' } });
+const realFetch = globalThis.fetch;
+if (typeof realFetch === 'function') {
+    globalThis.fetch = async function guardedFetch(input, init) {
+        let url;
+        try {
+            const raw = typeof input === 'object' &&
+                input !== null &&
+                'url' in input &&
+                typeof input.url === 'string'
+                ? input.url
+                : String(input);
+            url = new URL(raw);
+        }
+        catch {
+            // An address the guard cannot read is not sent on: it could be a mail host written in a way it does not know
+            record({ event: 'refused', note: 'an address the guard could not read' });
+            return refusal('an address the guard could not read');
+        }
+        if (!POSTMARK.test(url.hostname))
+            return realFetch.call(this, input, init);
+        const asRequest = typeof input === 'object' && input !== null && 'method' in input ? input : null;
+        const method = String((init && init.method) || (asRequest && asRequest.method) || 'GET').toUpperCase();
+        // Reading the server's own settings or a message's status sends nothing
+        if (method === 'GET' || method === 'HEAD')
+            return realFetch.call(this, input, init);
+        const key = url.pathname.replace(/\/+$/, '').toLowerCase();
+        if (!INBOX) {
+            record({ event: 'refused', note: 'no test inbox was given to the guard' });
+            return refusal('the guard has no test inbox');
+        }
+        if (method !== 'POST' || !SEND_PATHS.has(key)) {
+            record({
+                event: 'refused',
+                note: `${method} ${url.pathname} is not a send the guard can rewrite`
+            });
+            return refusal(`${method} ${url.pathname} is not a send the guard can rewrite`);
+        }
+        let text = null;
+        try {
+            if (init && init.body !== undefined && init.body !== null)
+                text = typeof init.body === 'string' ? init.body : null;
+            else if (asRequest && typeof asRequest.clone === 'function')
+                text = await asRequest.clone().text();
+        }
+        catch {
+            text = null;
+        }
+        if (typeof text !== 'string') {
+            record({ event: 'refused', note: 'the body was not plain text the guard could read' });
+            return refusal('the body was not plain text');
+        }
+        const r = rewriteBody(text);
+        if (!r.ok) {
+            record({ event: 'refused', note: r.why });
+            return refusal(r.why);
+        }
+        record({
+            event: 'sent',
+            note: `${r.count} message(s) to the test inbox, ${r.changed} rewritten`,
+            count: r.count,
+            rewritten: r.changed
+        });
+        const headers = new Headers((init && init.headers) || (asRequest && asRequest.headers) || {});
+        headers.delete('content-length');
+        return realFetch.call(this, url.toString(), { method: 'POST', headers, body: r.body });
+    };
+}
+// The tool counts the guard as loaded only when a process that has it listens on the preview's port, so a launcher (yarn, cross-env) or another runtime cannot stand in for the app
+const realListen = net.Server.prototype.listen;
+net.Server.prototype.listen = function guardedListen(...args) {
+    this.once('listening', () => {
+        const a = this.address();
+        if (a && typeof a === 'object')
+            record({ event: 'listening', port: a.port });
+    });
+    return realListen.apply(this, args);
+};
+// Another way into Postmark that cannot be rewritten (node:http, node:https) is refused outright
+const hostOf = (name, a) => {
+    try {
+        if (typeof a === 'string')
+            return new URL(a.startsWith('//') ? `${name}:${a}` : a).hostname;
+        if (a instanceof URL)
+            return a.hostname;
+        if (a && typeof a === 'object') {
+            const o = a;
+            return String(o.hostname || String(o.host || '').split(':')[0] || '');
+        }
+        return '';
+    }
+    catch {
+        return '';
+    }
+};
+for (const [name, mod] of [
+    ['http', http],
+    ['https', https]
+]) {
+    for (const fn of ['request', 'get']) {
+        const real = mod[fn];
+        mod[fn] = function guarded(...args) {
+            if (POSTMARK.test(hostOf(name, args[0]))) {
+                record({ event: 'refused', note: `node:${name} ${fn} to a mail host` });
+                throw new Error('afb-checks mail guard refused a direct request to a mail host. Mail from a preview goes only to the test inbox, through fetch.');
+            }
+            return real.apply(this, args);
+        };
+    }
+}

package/dist/checks/mailguard.js

@@ -0,0 +1,98 @@
+// THE TOOL SIDE OF THE MAIL GUARD. The guard itself is mailguard-hook.cts (compiled to mailguard-hook.cjs), loaded into the preview's start step. Here the tool decides when it
+// is on (the registration has sealed mail settings), gives it the one test inbox, reads back what it did, and applies the fail-closed rule over the WHOLE mail set: a mail
+// setting that did not come from the sealed store is never given to a preview, and a run with sealed mail settings counts only when the guard reported listening on the preview port.
+// A recipe cannot ask for the guard, change it or turn it off: the environment is built here after every recipe check.
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// -- MODULES -- //
+import { EMAIL, MAIL_SET_NAME } from './sealedNames.js';
+// -- CONSTANTS -- //
+/** The run's own mail setting: the mailer is told to only log. It is set by the tool, so it is never counted as an unsealed mail setting. */
+const RUN_OWN_MAIL = new Set(['EMAIL_PROVIDER']);
+// -- FUNCTIONS -- //
+/** The hook file next to this module (dist/checks/mailguard-hook.cjs once built). */
+export const GUARD_FILE = join(dirname(fileURLToPath(import.meta.url)), 'mailguard-hook.cjs');
+const maskAddress = (a) => String(a).replace(/^(.).*@/, '$1***@');
+/** Every variable of the whole mail set: POSTMARK, SMTP, SENDGRID, MAILGUN, RESEND, SES and anything with MAIL in its name. */
+export const mailSetNames = (env) => Object.keys(env).filter((k) => MAIL_SET_NAME.test(k) && !RUN_OWN_MAIL.has(k.toUpperCase()));
+/**
+ * Fail closed over the whole mail set. `sealed` is the list of names that were filled from the sealed store (SealedResolution.filled). Any other mail-set name in `env`
+ * is stripped ('strip', the default) or listed as a problem so the run refuses ('refuse'). Names only, never a value.
+ */
+export function enforceMailSet(env, sealed, mode = 'strip') {
+    const out = { ...env };
+    const stripped = [];
+    const problems = [];
+    for (const k of mailSetNames(env)) {
+        if (sealed.includes(k))
+            continue;
+        if (mode === 'strip') {
+            delete out[k];
+            stripped.push(k);
+        }
+        else
+            problems.push(`${k} is a mail setting that did not come from the sealed store, so this run does not start. Import the mail settings with a test inbox, or remove it.`);
+    }
+    return { env: out, stripped, problems };
+}
+/**
+ * The start environment with the guard loaded and told its inbox. `--require <hook>` is appended to NODE_OPTIONS LAST, so nothing earlier can unload it; a NODE_OPTIONS
+ * that was already there is kept in front. A variable spelled in another case (Windows) is folded into the one NODE_OPTIONS.
+ */
+export function withMailGuard(env, { inbox, log, hookFile = GUARD_FILE }) {
+    if (!EMAIL.test(inbox))
+        throw new Error('The mail guard needs one test inbox that is an email address.');
+    if (!log)
+        throw new Error('The mail guard needs a log file to report to.');
+    const out = {};
+    let previous = '';
+    for (const [k, v] of Object.entries(env)) {
+        if (k.toUpperCase() === 'NODE_OPTIONS')
+            previous = [previous, v].filter(Boolean).join(' ');
+        else
+            out[k] = v;
+    }
+    const req = `--require "${hookFile.replace(/\\/g, '/')}"`;
+    out.NODE_OPTIONS = [previous, req].filter(Boolean).join(' ');
+    out.AFB_MAIL_FENCE_INBOX = inbox;
+    out.AFB_MAIL_FENCE_LOG = log;
+    return out;
+}
+/**
+ * What the guard wrote: whether a process of the app loaded it, and how many messages it sent on (rewritten to the test inbox) and refused. `port` is the preview's port:
+ * the guard counts as loaded only when a process that has it is listening there, so a launcher (yarn, cross-env) or another runtime cannot stand in for the app.
+ */
+export function readFence(log, port = null) {
+    const out = { loaded: false, sends: 0, rewritten: 0, refused: 0 };
+    if (!log || !existsSync(log))
+        return out;
+    for (const line of readFileSync(log, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e.event === 'listening' && port !== null && Number(e.port) === Number(port))
+                out.loaded = true;
+            else if (e.event === 'sent') {
+                out.sends += Number(e.count) || 0;
+                out.rewritten += Number(e.rewritten) || 0;
+            }
+            else if (e.event === 'refused')
+                out.refused += 1;
+        }
+        catch {
+            /* A line the guard did not write completely */
+        }
+    }
+    return out;
+}
+/** The sentence that stops a run, or null when it may count: sealed mail settings were given and the guard did not report listening on the preview port. */
+export function fenceProblem(mailGiven, fence) {
+    if (!mailGiven || fence.loaded)
+        return null;
+    return 'The mail guard did not report listening on the preview port, so mail may not have been fenced. The run does not count.';
+}
+/** One plain sentence for the run log. */
+export const describeFence = (inbox, f) => `Mail guard on: mail goes only to ${maskAddress(inbox)}. ${f.sends} message(s) sent there (${f.rewritten} rewritten from another recipient), ${f.refused} refused.`;

package/dist/checks/paths.js

@@ -0,0 +1,85 @@
+// WHERE THE CHECK COMMANDS KEEP THEIR STATE: ONE FOLDER UNDER THE BRIDGE HOME, NEVER INSIDE A REPO
+// The bridge home also holds the token store (key and token files). Nothing here ever names those, and the sandboxed child of a check is
+// given read access to the scripts folder, its own run folder and the Playwright runtime only (see sandbox.ts).
+// -- DEP-MODULES -- //
+import { mkdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+// -- MODULES -- //
+import { configDir } from '../tokenStore.js';
+// -- CONSTANTS -- //
+/** The version of the conversation between the board and the check tool. The board refuses a tool older than its minimum. */
+export const TOOL_PROTOCOL = 2;
+/** Item references and check keys: letters, digits, dash and underscore only, so a name can never leave its folder. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** An organisation slug as the app writes it. */
+export const ORG_SLUG = /^[a-z0-9][a-z0-9-]{1,38}$/;
+// -- FUNCTIONS -- //
+/** The folder of all check state. AFB_BRIDGE_HOME moves it, which is how the tests get a throwaway one. */
+export const checksHome = () => join(configDir(), 'checks');
+/** Check scripts: scripts/<org>/<item>/<key>.mjs. Written by the agent, never fetched and run from the board. */
+export const scriptsDir = () => join(checksHome(), 'scripts');
+/** One folder per run, named by the run id. */
+export const runsDir = () => join(checksHome(), 'runs');
+export const locksDir = () => join(checksHome(), 'locks');
+export const auditFile = () => join(checksHome(), 'audit.log');
+export const bindingsFile = () => join(checksHome(), 'bindings.json');
+/** Private copies of repos, one per run, kept so a crashed run can be swept. */
+export const copiesDir = () => join(checksHome(), 'copies');
+/**
+ * The live and end markers of runs, written by the tool only. The sandboxed child can write its run folder, so a marker kept there could be forged and make a later
+ * sweep kill a process or remove a container: markers live here, outside every folder the child may read or write.
+ */
+export const markersDir = () => join(checksHome(), 'markers');
+export const markerPath = (runId) => join(markersDir(), `${assertName(runId, 'run id')}.json`);
+export const endedPath = (runId) => join(markersDir(), `${assertName(runId, 'run id')}.ended`);
+/** Build, install and preview logs and the mail guard's log: they can hold values the app printed, so they are kept where the child cannot read. */
+export const logsDir = () => join(checksHome(), 'logs');
+export const logDirFor = (runId) => join(logsDir(), assertName(runId, 'run id'));
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** Refuses a name that is not a plain name (a path separator, a dot dot, an empty string). */
+export function assertName(value, what) {
+    if (!NAME.test(value))
+        throw new Error(`${what} "${value.slice(0, 40)}" is not a plain name (letters, digits, dash, underscore).`);
+    return value;
+}
+/** Joins parts below a base and proves the result stays below it. Throws when it does not. */
+export function under(base, ...parts) {
+    const full = resolve(base, ...parts);
+    const rel = relative(resolve(base), full);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        throw new Error('That path leaves its folder.');
+    return full;
+}
+/** The path of a check script. */
+export function scriptPath(org, item, key) {
+    if (!ORG_SLUG.test(org))
+        throw new Error('The organisation is not a slug.');
+    return under(scriptsDir(), org, assertName(item, 'item reference'), `${assertName(key, 'check key')}.mjs`);
+}
+/** True when `child` is `parent` or inside it, compared by real path so a link cannot step outside. */
+export function isInside(parent, child) {
+    try {
+        const rel = relative(realpathSync(parent), realpathSync(child));
+        return (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.split(sep).includes('..')));
+    }
+    catch {
+        return false;
+    }
+}
+// -- REGISTRATIONS, SECRETS, CACHES AND POOLS (AFB-20261108-0925) -- //
+/** One JSON file per registration: registrations/<org>/<NAME>.json. */
+export const registrationsDir = () => join(checksHome(), 'registrations');
+/** Everything one registration owns apart from its definition: sealed secrets, sign-ins, kept builds. Never shared with another registration. */
+export const stateDirFor = (org, name) => join(checksHome(), 'state', org, name);
+/** Kept dependencies and builds of one registration. */
+export const cacheDirFor = (org, name) => join(stateDirFor(org, name), 'cache');
+/** The machine broker: slot files with a heartbeat, shared by `check run` processes and the worker. */
+export const brokerDir = () => join(checksHome(), 'broker');
+/** The shared browser and database pools of this machine, found through files here. */
+export const poolDir = () => join(checksHome(), 'pool');
+/** Owner approvals: single-use codes (hashed) and the approved roots. */
+export const approvalsFile = () => join(checksHome(), 'approvals.json');
+export const rootsFile = () => join(checksHome(), 'roots.json');