@agent-flow-board/bridge 0.2.0 → 0.4.0

package/dist/checks/login.js

@@ -0,0 +1,307 @@
+// `check login <NAME> --org <slug> [--seeded]`: SAVING A SIGN-IN FOR A REGISTRATION'S SITE, AND THE RULES FOR USING ONE
+// --seeded signs in with a seeded account (AFB_CHECKS_<NAME>_EMAIL and _PASSWORD) or the recipe's test user, through the app's own form.
+// Without --seeded a person signs in by hand in a visible browser window on their own desktop. It needs the owner's `login` approval (a code, from the board or a terminal),
+// used up before the window opens, and a desktop session to show the window on. The window is a fresh temporary browser profile with no debugging port, deleted afterwards,
+// and the bridge does not return what is typed into it to the agent. The wait ends when a new session cookie of the site appears, the window is closed, or the time runs out.
+// Nothing here starts a preview itself: the caller injects `target`, and the sign in function is injected too, so tests launch no browser.
+// A cookie, a password or a token is never printed.
+// -- DEP-MODULES -- //
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { consumeApproval, peekApproval } from './approve.js';
+import { loadPlaywright } from './browser.js';
+import { ORG_SLUG, registrationsDir } from './paths.js';
+import { expiryNote, loadProfileChecked, saveProfile } from './profiles.js';
+import { redact } from './redact.js';
+import { openSignin } from './signinKey.js';
+import { signInWithPassword } from './signin.js';
+// -- CONSTANTS -- //
+const NAME = /^[A-Za-z0-9_-]{1,32}$/;
+/** The window waits this long for a sign in (minutes), unless --timeout says otherwise. */
+const DEFAULT_TIMEOUT_MINUTES = 5;
+// -- FUNCTIONS -- //
+/** The variable names of a registration: AFB_CHECKS_<NAME upper, dash to underscore>_EMAIL and _PASSWORD. */
+export function envNames(name) {
+    const n = String(name).toUpperCase().replace(/-/g, '_');
+    return { email: `AFB_CHECKS_${n}_EMAIL`, password: `AFB_CHECKS_${n}_PASSWORD` };
+}
+/** The seeded account of a registration from the environment, or null when either variable is missing or empty. */
+export function seededAccount(name, env = process.env) {
+    const n = envNames(name);
+    const email = env[n.email];
+    const password = env[n.password];
+    return email && password ? { email, password } : null;
+}
+/**
+ * Whether a run uses a saved sign-in. Only when the script's header (or the check) names the very registration the run uses: a run that was
+ * routed there by a fallback, or a script that names another registration, opens signed out. Names compare without regard to case.
+ */
+export function chooseState(input) {
+    const { registration, scriptRegistration, profile } = input;
+    if (!profile || !scriptRegistration || !registration)
+        return 'none';
+    return scriptRegistration.toLowerCase() === registration.toLowerCase() ? 'saved' : 'none';
+}
+/** Pictures of a signed-in run are uploaded only when the owner opted in on the registration. A signed-out run uploads as usual. */
+export function pictureUploadAllowed(registration, signedIn) {
+    return !signedIn || registration.uploadSignedInPictures === true;
+}
+/** The saved sign-in a run should open with, with the expiry note, or null. Applies chooseState. */
+export function savedStateFor(input) {
+    const { profile, damaged } = loadProfileChecked(input.org, input.registration, input.bindKey);
+    // A saved sign-in that cannot be opened says so: the run would otherwise go signed out and fail on a sign-in page with no explanation
+    if (damaged)
+        return {
+            profile: null,
+            note: 'The saved sign-in is damaged, make it again (agent-flow-board check login).'
+        };
+    if (chooseState({ ...input, profile }) !== 'saved' || !profile)
+        return null;
+    return { profile, note: expiryNote(profile) };
+}
+/** Cookies and origins that belong to the site's hosts, nothing else (no other site's sign-in is saved). */
+export function keepRelated(state, hosts) {
+    const s = state;
+    const bare = (d) => d.replace(/^\./, '').toLowerCase();
+    const related = (d) => hosts.some((h) => {
+        const a = bare(d);
+        const b = h.toLowerCase();
+        return a === b || b.endsWith(`.${a}`) || a.endsWith(`.${b}`);
+    });
+    return {
+        cookies: (s?.cookies ?? []).filter((c) => related(String(c.domain ?? ''))),
+        origins: (s?.origins ?? []).filter((o) => {
+            try {
+                return related(new URL(String(o.origin)).hostname);
+            }
+            catch {
+                return false;
+            }
+        })
+    };
+}
+/**
+ * Whether this process can show a window to a person: null when it can. On Windows a service has no console session name; on Linux a desktop sets DISPLAY or WAYLAND_DISPLAY;
+ * on a Mac a shell opened over SSH is not the desktop. Otherwise one plain sentence says why a window cannot be shown.
+ */
+export function desktopProblem(env = process.env, platform = process.platform) {
+    const none = 'This process has no desktop to show a window on (for example it runs as a service or over a remote shell). Run the login from a terminal opened on the computer itself.';
+    if (platform === 'win32')
+        return env.SESSIONNAME ? null : none;
+    if (platform === 'darwin')
+        return env.SSH_CONNECTION || env.SSH_TTY ? none : null;
+    return env.DISPLAY || env.WAYLAND_DISPLAY ? null : none;
+}
+/** A cookie is told apart by its name and domain, never by its value. */
+const cookieId = (c) => {
+    const k = c;
+    return `${k.domain ?? ''}|${k.name ?? ''}`;
+};
+/**
+ * The headed login: a visible browser in a fresh temporary profile (no debugging port, deleted afterwards). It ends when a session cookie of the site appears that was not there
+ * when the page loaded, when the window is closed, or when the time runs out. Only cookies and origins of the site are kept.
+ */
+async function headedLogin(target, say, timeoutMs) {
+    const { chromium } = await loadPlaywright();
+    const profile = mkdtempSync(join(tmpdir(), 'afb-login-'));
+    const hosts = [new URL(target.baseUrl).hostname, ...(target.hosts ?? [])];
+    let context = null;
+    try {
+        context = await chromium.launchPersistentContext(profile, {
+            headless: false,
+            viewport: null,
+            baseURL: target.baseUrl
+        });
+        let closed = false;
+        context.on('close', () => void (closed = true));
+        const page = context.pages()[0] ?? (await context.newPage());
+        await page.goto(target.baseUrl);
+        const before = new Set(keepRelated(await context.storageState(), hosts).cookies.map(cookieId));
+        say(`A browser window is open on ${target.baseUrl}. Sign in there the way you normally do (a password or Google). The bridge does not return what you type to your agent.`);
+        const deadline = Date.now() + timeoutMs;
+        while (!closed && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 1000));
+            if (closed)
+                break;
+            let kept;
+            try {
+                kept = keepRelated(await context.storageState(), hosts);
+            }
+            catch {
+                break;
+            }
+            if (kept.cookies.some((c) => !before.has(cookieId(c)))) {
+                // A short settle, so a sign in that sets several cookies is kept whole
+                await new Promise((r) => setTimeout(r, 2000));
+                return { state: 'signed-in', storage: keepRelated(await context.storageState(), hosts) };
+            }
+        }
+        return closed ? { state: 'closed' } : { state: 'timeout' };
+    }
+    finally {
+        await context?.close().catch(() => undefined);
+        rmSync(profile, { recursive: true, force: true });
+    }
+}
+function loadRegistrationFile(org, name) {
+    try {
+        return JSON.parse(readFileSync(join(registrationsDir(), org, `${name}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The default target: only a live site needs no preview. A repo registration needs the caller to start its preview. */
+async function defaultTarget(registration) {
+    if (!registration.url)
+        throw new Error(`${registration.name} is built from a repo, so its sign-in needs a preview. Start one through the run command.`);
+    return {
+        baseUrl: registration.url,
+        hosts: registration.extraHosts ?? [],
+        stop: async () => undefined
+    };
+}
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+/** `check login <NAME> --org <slug> [--seeded]`. Exit code 0 saved, 1 a problem with what was asked, 2 could not run. */
+export async function loginCommand(args, ctx) {
+    const deps = {
+        signIn: (baseUrl, account) => signInWithPassword(baseUrl, account),
+        headed: headedLogin,
+        desktop: () => desktopProblem(),
+        approval: {
+            peek: (target, code) => peekApproval('login', target, code),
+            consume: (target, code) => consumeApproval('login', target, code)
+        },
+        env: process.env,
+        loadRegistration: loadRegistrationFile,
+        target: defaultTarget,
+        save: saveProfile,
+        ...ctx.deps
+    };
+    const say = (line) => ctx.log(line);
+    const flags = new Set(['--org']);
+    const positional = args.filter((a, i) => !a.startsWith('--') && !flags.has(args[i - 1] ?? ''));
+    const name = positional[0];
+    const org = flagValue(args, '--org');
+    const seeded = args.includes('--seeded');
+    // The sign in the owner typed on the board, encrypted to this machine: opened here in memory, never shown to the agent
+    const fromBoard = args.includes('--from-board');
+    if (!name || !org) {
+        say('Usage: check login <NAME> --org <slug> [--seeded | --from-board | --approval <code>]');
+        return 1;
+    }
+    if (!NAME.test(name) || !ORG_SLUG.test(org)) {
+        say('The registration name or the organisation is not a plain name.');
+        return 1;
+    }
+    // A headed login shows a window to a person: it needs the owner's login approval and a desktop to show it on, and stops at once without either
+    const approval = flagValue(args, '--approval');
+    const minutes = flagValue(args, '--timeout');
+    const timeoutMinutes = minutes === undefined ? DEFAULT_TIMEOUT_MINUTES : Number(minutes);
+    if (fromBoard && !ctx.board) {
+        say('Reading a sign in from the board needs the check command with --server and --org.');
+        return 1;
+    }
+    if (!seeded && !fromBoard) {
+        if (!Number.isFinite(timeoutMinutes) || timeoutMinutes < 1 || timeoutMinutes > 30) {
+            say('--timeout takes a number of minutes from 1 to 30.');
+            return 1;
+        }
+        const problem = deps.desktop();
+        if (problem) {
+            say(problem);
+            return 1;
+        }
+        if (!approval || !deps.approval.peek(`${org}/${name}`, approval)) {
+            say(`Signing in by hand needs the owner's approval. Ask for it: agent-flow-board check approve --request --action login --target ${org}/${name}, then pass --approval <code>. Or use --seeded with AFB_CHECKS_<NAME>_EMAIL and AFB_CHECKS_<NAME>_PASSWORD set.`);
+            return 1;
+        }
+    }
+    const registration = deps.loadRegistration(org, name);
+    if (!registration || registration.org !== org) {
+        say(`No registration "${name}" in ${org}.`);
+        return 1;
+    }
+    let target = null;
+    const secrets = [];
+    try {
+        target = await deps.target(registration);
+        const bindKey = new URL(target.baseUrl).origin;
+        let state;
+        if (fromBoard && ctx.board) {
+            const board = ctx.board();
+            const leased = await board.leaseSignins(name);
+            const envelope = leased.signins.find((e) => e.registration.toLowerCase() === name.toLowerCase());
+            if (!envelope) {
+                say(`No sign in is waiting on the board for ${name}. Run the login without --from-board to sign in in a window on this computer.`);
+                return 1;
+            }
+            let account = null;
+            try {
+                account = await openSignin(envelope, { orgId: leased.orgId, runnerId: leased.runnerId });
+                secrets.push(account.password);
+                state = await deps.signIn(target.baseUrl, account);
+            }
+            catch (e) {
+                // Only pass or fail goes back to the board, and the message never holds what was typed
+                await board.ackSignin({ id: envelope.id, result: 'fail' }).catch(() => undefined);
+                say(`That did not sign in. ${redact(e instanceof Error ? e.message : '', secrets).slice(0, 160)}`);
+                return 1;
+            }
+            finally {
+                if (account)
+                    account.password = '';
+            }
+            await board.ackSignin({ id: envelope.id, result: 'pass' }).catch(() => undefined);
+        }
+        else if (seeded) {
+            const account = seededAccount(name, deps.env) ?? target.testUser ?? null;
+            if (!account) {
+                const n = envNames(name);
+                say(`No account to sign in with. Set ${n.email} and ${n.password}, or give the recipe a test user.`);
+                return 1;
+            }
+            secrets.push(account.password);
+            state = await deps.signIn(target.baseUrl, account);
+        }
+        else {
+            // The approval is used up before the window opens, so a window never opens twice on one code
+            if (!deps.approval.consume(`${org}/${name}`, approval ?? '')) {
+                say('The owner code was used or ran out just now. Ask for a new one.');
+                return 1;
+            }
+            const outcome = await deps.headed(target, say, timeoutMinutes * 60_000);
+            if (outcome.state === 'closed') {
+                say('The window was closed before a sign in was seen, so nothing was saved.');
+                return 4;
+            }
+            if (outcome.state === 'timeout') {
+                say(`No sign in was seen within ${timeoutMinutes} minutes, so nothing was saved.`);
+                return 5;
+            }
+            state = outcome.storage;
+        }
+        const kept = state;
+        if (!kept || (!(kept.cookies?.length ?? 0) && !(kept.origins?.length ?? 0))) {
+            say('Nothing was saved because the browser holds no sign-in for this address.');
+            return 1;
+        }
+        deps.save(org, name, bindKey, state);
+        say(`Saved the sign-in for ${org}/${name} on ${bindKey}. It stays on this machine, sealed.`);
+        if (ctx.json)
+            ctx.out(JSON.stringify({ saved: true, registration: `${org}/${name}`, site: bindKey }));
+        return 0;
+    }
+    catch (e) {
+        say(redact(e instanceof Error ? e.message : String(e), secrets));
+        return 2;
+    }
+    finally {
+        await target?.stop().catch(() => undefined);
+    }
+}

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

@@ -25,6 +25,16 @@ 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;
@@ -59,3 +69,17 @@ export function isInside(parent, child) {
         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');