@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/provision.js

@@ -0,0 +1,175 @@
+// A THROWAWAY DATABASE FOR ONE RUN: A NEW POSTGRES CONTAINER WITH ITS OWN NAME, ITS OWN VOLUME AND ITS OWN PORT. Docker is opt in (`--database tool`).
+// Nothing here can reach the container or the volume that holds a person's own database on port 5433: the port is refused, and every docker command
+// is checked before it runs so that it can only name a container that starts with `afb-checks-`.
+// -- DEP-MODULES -- //
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+// -- MODULES -- //
+import { FORBIDDEN_PORTS } from './guardrails.js';
+// -- CONSTANTS -- //
+/** The ports a check never binds or publishes: the dev server, the build preview and the local PostgreSQL. */
+const NEVER_PORTS = FORBIDDEN_PORTS;
+/** The local PostgreSQL of the person. No container of ours ever publishes on it. */
+const PERSON_DB_PORT = 5433;
+/** Every container this tool makes or removes starts with this. */
+export const CONTAINER_PREFIX = 'afb-checks-';
+const IMAGE = 'postgres:16-alpine';
+const DOCKER_COMMANDS = new Set(['version', 'run', 'rm', 'exec', 'inspect', 'logs']);
+// -- FUNCTIONS -- //
+/** Runs the real docker program. Never throws: a program that cannot start is a status of -1. */
+export const realDocker = (args) => new Promise((resolve) => {
+    execFile('docker', args, { windowsHide: true, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err
+            ? typeof err.code === 'number'
+                ? err.code
+                : -1
+            : 0;
+        resolve({ status: code, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+/**
+ * Refuses any docker command whose target is not ours. `run` must name its container with --name afb-checks-..., and `rm`, `exec`, `inspect` and `logs`
+ * may only name containers that start with afb-checks-. `-v` is a flag of `rm` here (remove the volumes of that container), and `run` never gets a
+ * host path or a named volume to mount, so the volume it makes is its own anonymous one.
+ */
+export function checkDockerArgs(args) {
+    const [cmd, ...rest] = args;
+    if (!cmd || !DOCKER_COMMANDS.has(cmd))
+        throw new Error('That docker command is not one the check tool runs.');
+    if (cmd === 'version')
+        return;
+    if (cmd === 'run') {
+        const i = rest.indexOf('--name');
+        const name = i >= 0 ? rest[i + 1] : undefined;
+        if (!name || !name.startsWith(CONTAINER_PREFIX))
+            throw new Error(`The check tool only starts containers named ${CONTAINER_PREFIX}...`);
+        if (rest.some((a) => a === '-v' || a === '--volume' || a === '--mount'))
+            throw new Error('The check tool never mounts a volume or folder into a container.');
+        const p = rest.indexOf('-p');
+        const publish = p >= 0 ? (rest[p + 1] ?? '').split(':') : [];
+        const hostPort = Number(publish.length === 3 ? publish[1] : publish[0]);
+        if (NEVER_PORTS.has(hostPort))
+            throw new Error('That port belongs to a dev server or to the person’s own database; the check tool never uses it.');
+        return;
+    }
+    // rm, exec, inspect, logs: a flag, a command word after the container, or the container name
+    const names = cmd === 'exec'
+        ? [rest.find((a) => !a.startsWith('-'))]
+        : rest.filter((a) => !a.startsWith('-'));
+    if (!names.length || names.some((n) => !n || !n.startsWith(CONTAINER_PREFIX)))
+        throw new Error(`The check tool only touches containers named ${CONTAINER_PREFIX}...`);
+}
+async function guarded(docker, args) {
+    checkDockerArgs(args);
+    return docker(args);
+}
+/** Binds 127.0.0.1:0, reads the port and closes it. Never returns a forbidden port or the person's database port. */
+export async function freePort() {
+    for (let i = 0; i < 25; i++) {
+        const port = await new Promise((resolve, reject) => {
+            const s = createServer();
+            s.once('error', reject);
+            s.listen(0, '127.0.0.1', () => {
+                const addr = s.address();
+                s.close(() => addr && typeof addr === 'object'
+                    ? resolve(addr.port)
+                    : reject(new Error('No port was given.')));
+            });
+        });
+        if (!NEVER_PORTS.has(port))
+            return port;
+    }
+    throw new Error('No free port was found that is allowed.');
+}
+/** Removes ONE container of ours and its volumes, by its exact name. Never throws. */
+export async function removeContainer(name, docker = realDocker) {
+    try {
+        await guarded(docker, ['rm', '-f', '-v', name]);
+    }
+    catch {
+        /* Not ours, already gone, or Docker is not running: nothing to remove */
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Starts a new postgres container for this run and registers its removal on the scope. When `runtimeRole` is given the database also gets that login role,
+ * and `databaseUrl` uses it while `ownerUrl` keeps the superuser (migrations need the owner).
+ */
+export async function makeThrowawayDatabase(runId, scope, log, opts = {}) {
+    const docker = opts.docker ?? realDocker;
+    const version = await docker(['version']);
+    if (version.status !== 0)
+        throw new Error('--database tool needs Docker, which is not running');
+    const port = await (opts.pickPort ?? freePort)();
+    if (port === PERSON_DB_PORT || NEVER_PORTS.has(port))
+        throw new Error(`Port ${port} is not one the check tool may use for a database.`);
+    const name = `${CONTAINER_PREFIX}${runId}`;
+    const password = randomBytes(18).toString('hex');
+    const args = [
+        'run',
+        '-d',
+        '--name',
+        name,
+        '-e',
+        `POSTGRES_PASSWORD=${password}`,
+        '-e',
+        'POSTGRES_DB=app',
+        '-p',
+        `127.0.0.1:${port}:5432`,
+        IMAGE
+    ];
+    const started = await guarded(docker, args);
+    // Registered at once: a failure from here on still removes what was made
+    const dispose = () => removeContainer(name, docker);
+    scope.add(`database ${name}`, dispose);
+    scope.setInfo?.({ containerName: name });
+    if (started.status !== 0)
+        throw new Error('The throwaway database could not be started.');
+    log(`Throwaway database ${name} started on port ${port}.`);
+    await waitReady(docker, name, opts.readyTimeoutMs ?? 60_000);
+    const ownerUrl = `postgresql://postgres:${password}@127.0.0.1:${port}/app`;
+    if (!opts.runtimeRole)
+        return { databaseUrl: ownerUrl, ownerUrl };
+    const role = opts.runtimeRole;
+    if (!/^[a-z_][a-z0-9_]{0,40}$/.test(role))
+        throw new Error('The runtime role is not a plain role name.');
+    const rolePassword = randomBytes(18).toString('hex');
+    const made = await guarded(docker, [
+        'exec',
+        name,
+        'psql',
+        '-U',
+        'postgres',
+        '-d',
+        'app',
+        '-c',
+        `CREATE ROLE ${role} LOGIN PASSWORD '${rolePassword}'`
+    ]);
+    if (made.status !== 0)
+        throw new Error('The runtime role of the throwaway database could not be made.');
+    return {
+        databaseUrl: `postgresql://${role}:${rolePassword}@127.0.0.1:${port}/app`,
+        ownerUrl,
+        roleName: role
+    };
+}
+async function waitReady(docker, name, timeoutMs) {
+    const until = Date.now() + timeoutMs;
+    while (Date.now() < until) {
+        // With -h the check only passes when the real server listens, not the temporary one of the first start
+        const r = await guarded(docker, [
+            'exec',
+            name,
+            'pg_isready',
+            '-U',
+            'postgres',
+            '-h',
+            '127.0.0.1'
+        ]);
+        if (r.status === 0)
+            return;
+        await sleep(500);
+    }
+    throw new Error('The throwaway database did not accept connections in time.');
+}

package/dist/checks/recipe.js

@@ -0,0 +1,246 @@
+// THE RECIPE: .afb-checks.json IN THE PROJECT'S OWN REPO SAYS HOW ITS PREVIEW IS BUILT, STARTED AND SET UP.
+// The repo is the one thing an agent edits, so the recipe is never trusted as it stands: it is pinned (bind.ts) and it is checked here
+// against constants of this package. A recipe cannot name another program, a port a check never uses, an env key outside the list, or a value
+// that is anything but a placeholder or a short plain word. It can only ask for less than the guardrails allow.
+// Sealed secrets ({secret:NAME}) are allowed only on Supabase-style and mail settings (sealedNames.ts), a mail setting takes only the sealed value of its own name, and a
+// service key never goes to a PUBLIC_, VITE_ or NEXT_PUBLIC_ name. The values are filled in by secrets.ts when the preview starts; this file only checks the shape.
+// -- DEP-MODULES -- //
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { FORBIDDEN_PORTS, checkRepoFolder, commandProblem } from './guardrails.js';
+import { MAIL_ENV_KEY, SECRET_ENV_KEY, placeholderProblems } from './sealedNames.js';
+// -- CONSTANTS -- //
+export const RECIPE_FILE = '.afb-checks.json';
+/** The only keys of a recipe. */
+// There is no migrate or seed step: the app migrates and seeds itself at start from its env (AFB_AUTO_MIGRATE, AFB_SEED_DEMO), and a key nothing reads is refused
+export const RECIPE_KEYS = [
+    'version',
+    'build',
+    'start',
+    'ready',
+    'needsDatabase',
+    'runtimeRole',
+    'testUser',
+    'env',
+    'appPaths',
+    'warm'
+];
+/** Env keys a recipe may name: the app's own settings and the database urls, never PATH, NODE_OPTIONS or anything that loads code. */
+const ENV_KEY = /^(AFB_[A-Z0-9_]{1,50}|BETTER_AUTH_SECRET|DATABASE_URL|DATABASE_OWNER_URL|EMAIL_PROVIDER|EMAIL_FROM|ORIGIN)$/;
+/** A browser-visible setting (SvelteKit PUBLIC_*, Vite VITE_*). It is inlined into the page's bundle, so it is never a secret. */
+const PUBLIC_ENV_KEY = /^(PUBLIC|VITE)_[A-Z0-9_]{1,60}$/;
+/** The values the tool fills in itself. */
+const PLACEHOLDER = /^\{(baseUrl|port|random|databaseUrl|databaseOwnerUrl)\}$/;
+/** Or a short plain word: no shell characters, no path, no url with a port. */
+const PLAIN = /^[A-Za-z0-9_.:@-]{0,60}$/;
+const READY_PATH = /^\/[A-Za-z0-9_\-./]*$/;
+const APP_PATH = /^[A-Za-z0-9_.\-/]+$/;
+/** The files that decide what runs, besides the config files found by pattern. */
+const FIXED_FILES = [
+    'package.json',
+    'yarn.lock',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    '.yarnrc.yml',
+    RECIPE_FILE
+];
+const CONFIG_FILE = /^(vite|svelte|next|astro|nuxt)\.config\.[A-Za-z]+$/;
+// -- FUNCTIONS -- //
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** The scripts of the package.json of a repo (only string bodies). An unreadable package.json has none. */
+function scriptsOf(repo) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8'));
+        const raw = isObject(parsed) && isObject(parsed.scripts) ? parsed.scripts : {};
+        const out = {};
+        for (const [k, v] of Object.entries(raw))
+            if (typeof v === 'string')
+                out[k] = v;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** The package manager the lockfile names. Yarn when there is none. */
+function packageManager(repo) {
+    if (existsSync(join(repo, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(repo, 'package-lock.json')))
+        return 'npm';
+    if (existsSync(join(repo, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    return 'yarn';
+}
+/** The recipe of a repo, parsed, or null when it has none. A recipe that is not valid JSON is an error, never ignored. */
+export function loadRecipe(repo) {
+    const file = join(repo, RECIPE_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error(`${RECIPE_FILE} in ${repo} is not valid JSON. Fix it; a recipe that cannot be read is never guessed at.`);
+    }
+}
+/** Every problem of a recipe, as plain sentences. An empty list means it may be used. */
+export function validateRecipe(recipe, scripts) {
+    const out = [];
+    if (!isObject(recipe))
+        return [`${RECIPE_FILE} must be a JSON object.`];
+    const extra = Object.keys(recipe).filter((k) => !RECIPE_KEYS.includes(k));
+    if (extra.length)
+        out.push(`${RECIPE_FILE} names ${extra.join(', ')}, which a recipe may not set (it may set ${RECIPE_KEYS.join(', ')}).`);
+    if (recipe.version !== 1)
+        out.push(`${RECIPE_FILE} needs "version": 1.`);
+    for (const key of ['build', 'start']) {
+        const value = recipe[key];
+        if (value === undefined) {
+            if (key === 'start')
+                out.push(`${RECIPE_FILE} needs a "start" command.`);
+            continue;
+        }
+        const bad = commandProblem(value, scripts, `The recipe's ${key} command`);
+        if (bad)
+            out.push(bad);
+        for (const p of FORBIDDEN_PORTS)
+            if (new RegExp(`(^|[^0-9])${p}([^0-9]|$)`).test(String(value)))
+                out.push(`The recipe's ${key} command mentions port ${p}, which a check never uses.`);
+    }
+    if (recipe.ready !== undefined && !READY_PATH.test(String(recipe.ready)))
+        out.push("The recipe's ready path must start with / and hold only plain path characters.");
+    for (const p of FORBIDDEN_PORTS)
+        if (new RegExp(`(^|[^0-9])${p}([^0-9]|$)`).test(String(recipe.ready ?? '')))
+            out.push(`The recipe's ready path mentions port ${p}, which a check never uses.`);
+    if (recipe.needsDatabase !== undefined && typeof recipe.needsDatabase !== 'boolean')
+        out.push('"needsDatabase" must be true or false.');
+    if (recipe.runtimeRole !== undefined &&
+        !/^[a-z_][a-z0-9_]{0,40}$/.test(String(recipe.runtimeRole)))
+        out.push('"runtimeRole" must be a plain lower case role name.');
+    if (recipe.testUser !== undefined) {
+        const u = recipe.testUser;
+        const email = isObject(u) ? String(u.email ?? '') : '';
+        const password = isObject(u) ? String(u.password ?? '') : '';
+        const ok = isObject(u) &&
+            Object.keys(u).every((k) => ['email', 'password'].includes(k)) &&
+            PLAIN.test(email) &&
+            email.includes('@') &&
+            PLAIN.test(password) &&
+            password.length >= 8;
+        if (!ok)
+            out.push('"testUser" must be { "email": ..., "password": ... } with a plain email and a password of 8 or more plain characters. It is a preview-only account, public by design.');
+    }
+    // Warm previews are not wired in this version (the benchmark rule waived them), so the key is refused instead of being accepted and ignored
+    if (recipe.warm !== undefined) {
+        if (typeof recipe.warm !== 'boolean')
+            out.push('"warm" must be true or false.');
+        else if (recipe.warm)
+            out.push('"warm": warm previews are not enabled in this version.');
+    }
+    if (recipe.appPaths !== undefined &&
+        !(Array.isArray(recipe.appPaths) &&
+            recipe.appPaths.every((p) => typeof p === 'string' && APP_PATH.test(p) && !p.includes('..'))))
+        out.push('"appPaths" must be a list of plain folder or file names inside the repo.');
+    if (recipe.env !== undefined) {
+        if (!isObject(recipe.env))
+            out.push('"env" must be an object of setting names and values.');
+        else
+            for (const [k, v] of Object.entries(recipe.env)) {
+                if (!ENV_KEY.test(k) && !PUBLIC_ENV_KEY.test(k) && !SECRET_ENV_KEY.test(k))
+                    out.push(`The recipe sets ${k}, which is not an env key a recipe may set.`);
+                // A sealed value only on a Supabase-style or mail setting, and only a key of that kind: never a database, NODE_OPTIONS or a path
+                else if (typeof v === 'string' && v.startsWith('{secret:'))
+                    out.push(...placeholderProblems(k, v));
+                // A mail setting is never written in the recipe: its value comes from the sealed store, behind the mail guard
+                else if (MAIL_ENV_KEY.test(k))
+                    out.push(`The recipe gives ${k}, a mail setting, a value that is not its own sealed value ({secret:${k}}).`);
+                else if (typeof v !== 'string' || !(PLACEHOLDER.test(v) || PLAIN.test(v)))
+                    out.push(`The recipe gives ${k} a value that is not a placeholder ({baseUrl}, {port}, {random}, {databaseUrl}, {databaseOwnerUrl}) or a short plain word.`);
+                else if (/^\d+$/.test(v) && FORBIDDEN_PORTS.has(Number(v)))
+                    out.push(`The recipe gives ${k} the port ${v}, which a check never uses.`);
+            }
+    }
+    return out;
+}
+/** The files that decide what runs, as relative names that exist in the repo, sorted. */
+export function decidingFiles(repo) {
+    const found = FIXED_FILES.filter((f) => existsSync(join(repo, f)));
+    let names = [];
+    try {
+        names = readdirSync(repo).filter((n) => CONFIG_FILE.test(n));
+    }
+    catch {
+        /* An unreadable folder has no config files */
+    }
+    return [...new Set([...found, ...names])].sort();
+}
+/** A sha256 over the names and the line-ending-normalised contents of the deciding files. Any change to them changes the pin. */
+export function pinFiles(repo) {
+    const hash = createHash('sha256');
+    for (const name of decidingFiles(repo)) {
+        const text = readFileSync(join(repo, name), 'utf8').replace(/\r\n/g, '\n');
+        hash.update(`${name}\0${text}\0`);
+    }
+    return hash.digest('hex');
+}
+/**
+ * What a run needs to know about a repo: the checked folder, then the recipe when there is one, else plain detection from package.json.
+ * Throws one plain sentence when the folder, the recipe or the commands are refused.
+ */
+export function resolveProjectConfig(repo) {
+    const folder = checkRepoFolder(repo);
+    if (folder)
+        throw new Error(folder);
+    const scripts = scriptsOf(repo);
+    const recipe = loadRecipe(repo);
+    if (recipe !== null) {
+        const problems = validateRecipe(recipe, scripts);
+        if (problems.length)
+            throw new Error(problems[0]);
+        const r = recipe;
+        const config = {
+            repo,
+            start: String(r.start),
+            needsDatabase: r.needsDatabase === true,
+            env: isObject(r.env)
+                ? Object.fromEntries(Object.entries(r.env).map(([k, v]) => [k, String(v)]))
+                : {},
+            appPaths: Array.isArray(r.appPaths) ? r.appPaths.map(String) : []
+        };
+        if (typeof r.build === 'string')
+            config.build = r.build;
+        if (typeof r.ready === 'string')
+            config.ready = r.ready;
+        if (typeof r.runtimeRole === 'string')
+            config.runtimeRole = r.runtimeRole;
+        if (isObject(r.testUser))
+            config.testUser = { email: String(r.testUser.email), password: String(r.testUser.password) };
+        return config;
+    }
+    // No recipe: detect plainly. npm needs `run` and a `--` before flags; yarn and pnpm run a script by its name.
+    const pm = packageManager(repo);
+    const run = (script) => (pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`);
+    if (!Object.prototype.hasOwnProperty.call(scripts, 'preview'))
+        throw new Error(`${repo} has no "preview" script. Add a ${RECIPE_FILE} that says how to build and start the app, or add a preview script.`);
+    const config = {
+        repo,
+        start: pm === 'npm' ? 'npm run preview -- --port {port}' : `${run('preview')} --port {port}`,
+        needsDatabase: false,
+        env: {},
+        appPaths: []
+    };
+    if (Object.prototype.hasOwnProperty.call(scripts, 'build'))
+        config.build = run('build');
+    const startBad = commandProblem(config.start, scripts, 'The start command');
+    if (startBad)
+        throw new Error(startBad);
+    if (config.build) {
+        const buildBad = commandProblem(config.build, scripts, 'The build command');
+        if (buildBad)
+            throw new Error(buildBad);
+    }
+    return config;
+}

package/dist/checks/redact.js

@@ -0,0 +1,52 @@
+// REDACTION: NOTHING THAT LOOKS LIKE A SECRET, AND NOTHING THE RUN WAS TOLD IS A SECRET, REACHES A LOG, A RESULT OR AN UPLOAD.
+// This file imports nothing, so the sandboxed child can load it without touching the token store.
+// -- CONSTANTS -- //
+/** The shapes of tokens, whatever their value. */
+const PATTERNS = [
+    /\b(?:afx|afb|afrun)_[A-Za-z0-9._-]{12,}/g, // A board runner or bridge token
+    /\bsb_(?:secret|publishable)_[A-Za-z0-9_-]{16,}/g, // A Supabase key of the new kind
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, // A JWT
+    /\b(?:set-cookie|cookie|authorization)\s*:\s*[^\r\n]+/gi
+];
+/** user:password@host in any address: the password is hidden whatever it is, so a database url in a log never shows it. */
+const USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:@/]+):[^\s@/]+@/gi;
+/** A needle shorter than this is ignored, because removing a 3 letter word would wipe the text. */
+const MIN_NEEDLE = 6;
+/** Variables whose value is a secret by the look of their name. */
+const SECRET_NAME = /(PASSWORD|SECRET|TOKEN|KEY|URL|URI)$/i;
+const MIN_ENV_VALUE = 8;
+// -- FUNCTIONS -- //
+/** Masks what looks like a token, a cookie header or a password inside an address. */
+export function redactPatterns(text) {
+    let out = String(text);
+    for (const p of PATTERNS)
+        out = out.replace(p, '[hidden]');
+    return out.replace(USERINFO, '$1:[hidden]@');
+}
+/** Every spelling of a needle that could show up in a log: raw, as in a URL, and as base64 (padded and not). */
+function forms(needle) {
+    const b64 = Buffer.from(needle, 'utf8').toString('base64');
+    return [...new Set([needle, encodeURIComponent(needle), b64, b64.replace(/=+$/, '')])].filter((f) => f.length >= MIN_NEEDLE);
+}
+/** needles: exact strings (a typed password, a token) to remove wherever they appear, then the token shapes. */
+export function redact(text, needles = []) {
+    let out = String(text);
+    // Longest first, so a needle that contains another is removed whole
+    const all = needles
+        .filter((n) => typeof n === 'string' && n.length >= MIN_NEEDLE)
+        .flatMap(forms)
+        .sort((a, b) => b.length - a.length);
+    for (const f of all)
+        out = out.split(f).join('[hidden]');
+    return redactPatterns(out);
+}
+/** The values of the variables that look like secrets (by name), ready to be used as needles. */
+export function needlesFromEnv(env) {
+    const out = new Set();
+    for (const [name, value] of Object.entries(env)) {
+        if (typeof value === 'string' && value.length >= MIN_ENV_VALUE && SECRET_NAME.test(name))
+            out.add(value);
+    }
+    return [...out];
+}