@agent-flow-board/bridge 0.1.0 → 0.2.0

package/dist/checks/envPolicy.js

@@ -0,0 +1,163 @@
+// THE ENVIRONMENT OF A PREVIEW. Owner rule: a check never runs against a database URL that came from a .env file, and never sends mail through a real provider.
+// The repo's own .env files are read from the SOURCE repo (the private copy has none) and adopted, so the app runs with the settings it was written for,
+// EXCEPT database and connection variables (stripped) and mail provider variables (stripped, and the mailer is told to only log). Nothing is
+// ever printed here with its value: notes and the stripped list name variables only.
+// -- DEP-MODULES -- //
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+// -- CONSTANTS -- //
+/** Read in this order, a later file overriding an earlier one (the order a production build of Vite and SvelteKit uses). */
+const FILES = ['.env', '.env.local', '.env.production', '.env.production.local'];
+/** A name that points at a database or another data store. Any such variable is stripped, whatever its value. */
+const DATABASE_NAME = /(DATABASE|DB|POSTGRES|PG|SUPABASE_SERVICE|REDIS|MONGO|MYSQL).*(URL|URI|HOST|PASSWORD|USER|NAME)?/i;
+/** A value that is a connection string: scheme://user@... or a database scheme. */
+const CONNECTION_VALUE = /^[a-z][a-z0-9+.-]*:\/\/[^\s@]*@/i;
+const DATABASE_SCHEME = /^(postgres(ql)?|mysql|mongodb(\+srv)?|redis|rediss):\/\//i;
+/** A name of a mail provider setting. SES must be a whole word (SESSION_SECRET is not mail). */
+const MAIL_NAME = /(MAIL|SMTP|POSTMARK|SENDGRID|MAILGUN|RESEND)|(^|_)SES(_|$)/i;
+/** What the app's own mailer accepts for "log only" (src/env.ts: EMAIL_PROVIDER is log, resend, postmark or smtp). */
+const MAIL_LOG_ONLY = 'log';
+/** Variables that name the app's own address: pointed at the run's preview, because the value in .env is the live address. */
+const SELF_ADDRESS = /^(ORIGIN|BETTER_AUTH_URL|AUTH_URL|NEXTAUTH_URL|APP_URL|SITE_URL|BASE_URL|(PUBLIC_|VITE_|NEXT_PUBLIC_)(APP|SITE|BASE)_URL)$/;
+/** Never taken from a file: the run's own settings. */
+const RUN_OWN = new Set(['PORT', 'HOST', 'NODE_ENV', 'EMAIL_PROVIDER']);
+/** What a package manager and a build need from the machine. Nothing else of the process environment is passed (no AFB_TOKEN, no *_TOKEN, *_SECRET or *_KEY). */
+const SYSTEM = [
+    'PATH',
+    'SYSTEMROOT',
+    'TEMP',
+    'TMP',
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'COMSPEC',
+    'PATHEXT'
+];
+// -- FUNCTIONS -- //
+/** NAME=value lines. `export ` and one pair of quotes are allowed; a quoted value may run over several lines. No expansion, no substitution. */
+export function parseEnvText(text) {
+    const out = new Map();
+    const lines = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = (lines[i] ?? '').trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)$/.exec(line);
+        if (!m || m[1] === undefined)
+            continue;
+        let v = (m[2] ?? '').trim();
+        const q = v[0];
+        if (q === '"' || q === "'" || q === '`') {
+            let body = v.slice(1);
+            let end = body.indexOf(q);
+            while (end < 0 && i + 1 < lines.length) {
+                body += '\n' + (lines[++i] ?? '');
+                end = body.indexOf(q);
+            }
+            v = end < 0 ? body : body.slice(0, end);
+        }
+        else
+            v = v.replace(/\s+#.*$/, '');
+        out.set(m[1], v);
+    }
+    return out;
+}
+const isFile = (f) => {
+    try {
+        return existsSync(f) && statSync(f).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** The merged variables of the repo's env files, a later file winning. A missing file is skipped. */
+function readRepoEnv(repo) {
+    const merged = new Map();
+    for (const f of FILES) {
+        const file = join(repo, f);
+        if (!isFile(file))
+            continue;
+        for (const [k, v] of parseEnvText(readFileSync(file, 'utf8')))
+            merged.set(k, v);
+    }
+    return merged;
+}
+const looksLikeConnection = (name, value) => DATABASE_NAME.test(name) || CONNECTION_VALUE.test(value) || DATABASE_SCHEME.test(value);
+/** Fills the recipe placeholders. A placeholder that needs a database that was not made is left empty and named in the notes. */
+function fill(value, vars, name, notes) {
+    return value.replace(/\{(baseUrl|port|random|databaseUrl|databaseOwnerUrl)\}/g, (_all, key) => {
+        if (key === 'random')
+            return randomBytes(24).toString('hex');
+        const v = vars[key];
+        if (v === undefined) {
+            notes.push(`The recipe variable ${name} needs {${key}}, which this run does not have; it is empty.`);
+            return '';
+        }
+        return v;
+    });
+}
+export function buildPreviewEnv(input) {
+    const notes = [];
+    const stripped = [];
+    const env = {};
+    // -- SYSTEM -- //
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined && SYSTEM.includes(k.toUpperCase()))
+            env[k] = v;
+    }
+    // -- THE REPO'S OWN ENV FILES -- //
+    const fromFiles = readRepoEnv(input.repo);
+    let adopted = 0;
+    let mailStripped = false;
+    for (const [name, value] of fromFiles) {
+        if (RUN_OWN.has(name))
+            continue;
+        if (SELF_ADDRESS.test(name) && /^https?:\/\//i.test(value)) {
+            env[name] = input.baseUrl;
+            adopted++;
+            continue;
+        }
+        if (looksLikeConnection(name, value)) {
+            stripped.push(name);
+            continue;
+        }
+        if (MAIL_NAME.test(name)) {
+            stripped.push(name);
+            mailStripped = true;
+            continue;
+        }
+        env[name] = value;
+        adopted++;
+    }
+    if (fromFiles.size)
+        notes.push(`Adopted ${adopted} variable(s) from the repo's env files.`);
+    if (stripped.length)
+        notes.push(`Stripped ${stripped.length} database or mail variable(s): ${stripped.join(', ')}.`);
+    // -- THE RECIPE -- //
+    const vars = {
+        baseUrl: input.baseUrl,
+        port: String(input.port),
+        databaseUrl: input.databaseUrl,
+        databaseOwnerUrl: input.databaseOwnerUrl
+    };
+    for (const [name, value] of Object.entries(input.recipeEnv)) {
+        if (RUN_OWN.has(name))
+            continue;
+        env[name] = fill(value, vars, name, notes);
+    }
+    // -- THE RUN'S OWN SETTINGS -- //
+    env.PORT = String(input.port);
+    env.HOST = '127.0.0.1';
+    env.NODE_ENV = 'production';
+    // The app's own address is always the preview's (SvelteKit's node adapter needs ORIGIN for form posts)
+    env.ORIGIN = input.baseUrl;
+    env.EMAIL_PROVIDER = MAIL_LOG_ONLY;
+    notes.push(`EMAIL_PROVIDER is set to ${MAIL_LOG_ONLY}, the value the app accepts for "log only"${mailStripped ? ' (mail provider variables were stripped)' : ''}.`);
+    if (input.databaseUrl !== undefined)
+        env.DATABASE_URL = input.databaseUrl;
+    if (input.databaseOwnerUrl !== undefined)
+        env.DATABASE_OWNER_URL = input.databaseOwnerUrl;
+    return { env, stripped, notes };
+}

package/dist/checks/guard.js

@@ -0,0 +1,188 @@
+// GUARDS: WHAT A PAGE MAY REACH, WHAT IT MAY CHANGE, AND WHAT A CHECK IS HANDED.
+// Layer one is the browser itself: every host except the preview's is unresolvable (see browser.ts), whatever a check does with routes.
+// Layer two counts and stops writes. Layer three hands a check a facade of the page that cannot lead back to the context or the cookies.
+// This file imports nothing at runtime, so the sandboxed child can load it. Playwright is only described here by the few members it calls.
+// -- CONSTANTS -- //
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const HIDDEN = new Set([
+    'context',
+    'request',
+    'route',
+    'unroute',
+    'unrouteAll',
+    'routeFromHAR',
+    'routeWebSocket',
+    'addInitScript',
+    'exposeFunction',
+    'exposeBinding',
+    'video',
+    'pause',
+    'browser',
+    'page',
+    'mainFrame',
+    'frames',
+    'frame',
+    'parentFrame',
+    'childFrames',
+    'opener',
+    'storageState',
+    'cookies',
+    'addCookies',
+    'clearCookies',
+    'newPage',
+    'newContext',
+    'newCDPSession'
+]);
+// Only Playwright's own objects are wrapped: plain data (what evaluate returns) is handed over as it is
+const WRAPPED = /^_?(Locator|FrameLocator|Frame|ElementHandle|JSHandle|Response|Request|Keyboard|Mouse|Touchscreen|Dialog|Download|FileChooser|ConsoleMessage|Worker|WebSocket|Page)$/;
+const NODE_MODULES = 'fs|fs/promises|child_process|net|http|https|http2|dgram|dns|tls|worker_threads|vm|os|cluster|module|v8|inspector|repl|readline|stream|zlib|crypto|perf_hooks|async_hooks|wasi|tty|process';
+const UNSAFE = [
+    [/\bchild_process\b/, 'child_process'],
+    [/node:(net|http|https|http2|dgram|dns|tls|worker_threads|vm)\b/, 'a network or process module'],
+    [/\brequire\s*\(/, 'require()'],
+    [
+        new RegExp(`\\bfrom\\s+['"](?:node:)?(?:${NODE_MODULES})['"]`),
+        'a module of Node other than path and url'
+    ],
+    [
+        new RegExp(`\\bimport\\s+['"](?:node:)?(?:${NODE_MODULES})['"]`),
+        'a module of Node other than path and url'
+    ],
+    [/\bprocess\.(env|binding|kill|exit|getBuiltinModule)\b/, 'process'],
+    [/\bfetch\s*\(/, 'fetch()'],
+    [/\bXMLHttpRequest\b/, 'XMLHttpRequest'],
+    [/\bWebSocket\b/, 'WebSocket'],
+    // A dynamic import is fine only for a file next to the check (a relative name written out in full)
+    [/\bimport\s*\(\s*(?!['"]\.{1,2}\/)/, 'a dynamic import of a name that is not a relative file'],
+    [/node:fs|\bfrom\s+['"]fs['"]/, 'the file system'],
+    [/\bprofiles\b/, 'the profiles folder'],
+    [
+        /\.(page|context|browser|cookies|storageState|mainFrame|frames|frame|newPage|newContext|route|unroute|routeFromHAR|routeWebSocket|addInitScript|exposeFunction|exposeBinding)\s*\(|\.request\b/,
+        'a way back to the browser context'
+    ],
+    [
+        /\bgetBuiltinModule\b|\bglobalThis\b|\bFunction\s*\(|\beval\s*\(|\[\s*['"]constructor['"]\s*\]/,
+        'a way around the checks'
+    ]
+];
+// -- FUNCTIONS -- //
+export const hostOf = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return '';
+    }
+};
+const sameOrigin = (url, origin) => {
+    try {
+        return new URL(url).origin === origin;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Stops every write and counts what it stopped. A page that submits a form is answered with nothing so it stays where it is.
+ * Writes are only let through when the person said so for this run (allowWrites).
+ */
+export async function guardContext(ctx, { origin, allowWrites = false, extraHosts = [], onBlocked = () => { } }) {
+    const counts = { writes: 0, outside: 0 };
+    await ctx.route('**/*', async (route) => {
+        const req = route.request();
+        const url = req.url();
+        if (url.startsWith('data:') || url.startsWith('blob:'))
+            return route.continue();
+        if (!sameOrigin(url, origin) && !extraHosts.includes(hostOf(url))) {
+            counts.outside++;
+            onBlocked(`blocked a request to ${hostOf(url)}`);
+            return route.abort();
+        }
+        if (!READ_METHODS.has(req.method()) && !allowWrites) {
+            counts.writes++;
+            onBlocked(`stopped a ${req.method()} to ${new URL(url).pathname}`);
+            return req.resourceType() === 'document'
+                ? route.fulfill({ status: 204, body: '' })
+                : route.abort();
+        }
+        return route.continue();
+    });
+    return counts;
+}
+const refuse = (prop) => () => {
+    throw new Error(`${prop} is not available to a check. Checks drive the page; the tool keeps the session and the network rules.`);
+};
+const isThenable = (v) => typeof v.then === 'function';
+/** Wraps something a page returned (a locator, a response, a promise of one) so it can never lead back to the context. */
+function wrap(value, guard) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (isThenable(value))
+        return value.then((v) => wrap(v, guard));
+    if (Array.isArray(value))
+        return value.map((v) => wrap(v, guard));
+    const name = value.constructor?.name ?? '';
+    if (!WRAPPED.test(name))
+        return value;
+    return proxy(value, guard);
+}
+const originals = new WeakMap();
+/** The real object behind something a check was handed, for the tool's own use (expect needs the real locator). */
+export const unwrap = (v) => typeof v === 'object' && v !== null ? (originals.get(v) ?? v) : v;
+function proxy(value, guard) {
+    const made = new Proxy(value, {
+        get(target, prop) {
+            if (typeof prop === 'string' && HIDDEN.has(prop))
+                return new Proxy(refuse(prop), {
+                    get: refuse(prop),
+                    apply: refuse(prop),
+                    set: refuse(prop)
+                });
+            // expect() talks to a locator through its internal _expect and nothing else
+            if (typeof prop === 'string' && prop.startsWith('_') && prop !== '_expect')
+                return undefined;
+            const v = Reflect.get(target, prop, target);
+            // Symbols and the constructor are handed over as they are, so instanceof checks and expect() still recognise a locator
+            if (typeof prop === 'symbol' || prop === 'constructor')
+                return v;
+            if (typeof v !== 'function')
+                return wrap(v, guard);
+            return (...args) => {
+                if (prop === 'goto')
+                    guard.assertNavigable(args[0]);
+                return wrap(v.apply(target, args), guard);
+            };
+        }
+    });
+    originals.set(made, value);
+    return made;
+}
+/** What a check receives instead of the real page: no context, no cookies, no request client, no routes, and no way back to them through a frame, a locator or a response. */
+export function pageForCheck(page, { origin, extraHosts = [] } = {}) {
+    const guard = {
+        assertNavigable(url) {
+            const u = String(url ?? '');
+            if (u.startsWith('/') && !u.startsWith('//'))
+                return;
+            let parsed;
+            try {
+                parsed = new URL(u);
+            }
+            catch {
+                throw new Error(`The check tried to open "${u.slice(0, 60)}", which is not an address of the app under test.`);
+            }
+            if (!['http:', 'https:'].includes(parsed.protocol) ||
+                (origin && parsed.origin !== origin && !extraHosts.includes(parsed.hostname)))
+                throw new Error(`The check tried to open ${parsed.protocol}//${parsed.host}, which is not the app under test.`);
+        }
+    };
+    return proxy(page, guard);
+}
+/** A speed bump, not a wall: names what a check does that a check has no business doing. Refused unless the person says --allow-unsafe. */
+export function lintCheck(source) {
+    const found = [];
+    for (const [re, label] of UNSAFE)
+        if (re.test(source) && !found.includes(label))
+            found.push(label);
+    return found;
+}

package/dist/checks/guardrails.js

@@ -0,0 +1,155 @@
+// THE GUARDRAILS OF THE CHECK COMMANDS. THEY ARE CONSTANTS IN THIS FILE, NEVER DATA: NOTHING IN THE REPO UNDER TEST OR IN A RECIPE CAN WIDEN THEM.
+// WHAT THIS DOES AND DOES NOT PROTECT. The preview runs the code of the repo under test, and the agent writes that code. So no rule here can
+// stop an agent that means harm: it could put anything in the app. The rules stop mistakes and keep real things safe: the database that holds
+// real data, the ports of the servers a person runs, the programs a build is allowed to start, and folders that were never meant to be built.
+// -- DEP-MODULES -- //
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+// -- MODULES -- //
+import { configDir } from '../tokenStore.js';
+// -- CONSTANTS -- //
+/** Never used by a check: the dev server, the build preview that is served, and the local Docker PostgreSQL that holds real data. */
+export const FORBIDDEN_PORTS = new Set([5180, 5190, 5433]);
+/** The only flags of a build or start command, besides the script name. Anything else could run a file the agent wrote. */
+const ARG_OK = /^(--port|\{port\}|--host|127\.0\.0\.1|--strictPort|--)$/;
+/** The one word a script may be given besides flags: what a database command should do. */
+const SUBCOMMAND_OK = /^migrate$/;
+const WORD = /^[A-Za-z0-9_:.@-]+$/;
+/**
+ * What the body of a package.json script may be: a known build or preview program with a plain command and plain flags. A body that runs a
+ * file, chains commands or sets variables is refused, because that is where an arbitrary program would hide.
+ */
+const BODY_OK = /^(vite|svelte-kit|next|astro|nuxt|nuxi|remix) [a-z][a-z-]*( --?[A-Za-z][A-Za-z-]*( [A-Za-z0-9_.:{}/-]+)?){0,4}$/;
+/** Folders that hold keys and logins: a build never runs inside or at one of them. */
+const SECRET_FOLDERS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker'];
+// -- FUNCTIONS -- //
+const hasPort = (text, port) => new RegExp(`(^|[^0-9])${port}([^0-9]|$)`).test(text);
+/** Paths compare without case on Windows only. */
+const same = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const insideOrSame = (parent, child) => {
+    const p = process.platform === 'win32' ? parent.toLowerCase() : parent;
+    const c = process.platform === 'win32' ? child.toLowerCase() : child;
+    return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+};
+/** One plain sentence when a package.json script is not a plain build or preview command, else null. */
+export function scriptBodyProblem(name, scripts) {
+    const body = String(scripts[name] ?? '');
+    if (!BODY_OK.test(body))
+        return `The script "${name}" runs "${body}", which is not a plain build or preview command (vite, svelte-kit, next, astro, nuxt or remix with plain flags).`;
+    // A script body may not name a port a check never uses, nor bind to anything but this machine
+    for (const p of FORBIDDEN_PORTS)
+        if (hasPort(body, p))
+            return `The script "${name}" mentions port ${p}, which a check never uses.`;
+    const host = /--host(?:\s+(\S+))?/.exec(body);
+    if (host && host[1] !== '127.0.0.1')
+        return `The script "${name}" binds the preview to something other than 127.0.0.1.`;
+    // A pre or post script runs by itself around it, so it is held to the same rule
+    for (const hook of [`pre${name}`, `post${name}`])
+        if (Object.prototype.hasOwnProperty.call(scripts, hook) && !BODY_OK.test(String(scripts[hook])))
+            return `The script "${hook}" runs by itself around "${name}" and is "${scripts[hook]}", which is not a plain build or preview command.`;
+    return null;
+}
+/**
+ * One plain sentence when a build or start command is outside the allowed forms, else null. Allowed: `yarn|npm|pnpm [run] <script>` where the
+ * script is named in package.json and its body is a plain build or preview command, with only the flags above. No shell characters, no `..`,
+ * no other program, and not `node <file>`: a file is where the agent's own program would run.
+ */
+export function commandProblem(cmd, scripts, what) {
+    const text = String(cmd ?? '').trim();
+    if (!text)
+        return `${what} is empty.`;
+    if (/[&|;<>`$()\\\r\n"'*?%^!]/.test(text) || text.includes('..'))
+        return `${what} "${text}" has a character a shell would act on.`;
+    const t = text.split(/\s+/);
+    if (!['yarn', 'npm', 'pnpm'].includes(t[0]))
+        return `${what} "${text}" starts with ${t[0]}. Only yarn, npm or pnpm running a package.json script are allowed.`;
+    let i = 1;
+    if (t[i] === 'run')
+        i++;
+    const script = t[i];
+    if (!script || !WORD.test(script))
+        return `${what} "${text}" names no package.json script.`;
+    if (!Object.prototype.hasOwnProperty.call(scripts, script))
+        return `${what} "${text}" runs "${script}", which is not a script in package.json.`;
+    const body = scriptBodyProblem(script, scripts);
+    if (body)
+        return `${what} "${text}": ${body}`;
+    const rest = t.slice(i + 1);
+    for (let j = 0; j < rest.length; j++) {
+        if (j === 0 && SUBCOMMAND_OK.test(rest[j]))
+            continue;
+        if (!ARG_OK.test(rest[j]))
+            return `${what} "${text}" has the argument ${rest[j]}, which is not one of --port, --host 127.0.0.1 or --strictPort.`;
+        if (rest[j] === '--host' && rest[j + 1] !== '127.0.0.1')
+            return `${what} "${text}" binds the preview to something other than 127.0.0.1.`;
+        if (rest[j] === '--port' && rest[j + 1] !== '{port}')
+            return `${what} "${text}" fixes the port. It must be {port}, so the tool picks a free one.`;
+    }
+    return null;
+}
+/** True when the folder is a git project or sits inside one (a .git folder or file here or in a parent). */
+function insideGit(folder) {
+    let dir = folder;
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return true;
+        const up = dirname(dir);
+        if (up === dir)
+            return false;
+        dir = up;
+    }
+}
+/** The real path of a folder, or its plain resolved path when it cannot be read. */
+function realOrResolved(folder) {
+    try {
+        return realpathSync.native(folder);
+    }
+    catch {
+        return resolve(folder);
+    }
+}
+/**
+ * One plain sentence when the folder may not be built by a check, else null. The rules: it is a folder that exists, a git project (or inside
+ * one), not a drive root, the home folder, the bridge home or a folder of keys and logins, it has no link in its path (a symlink or a Windows
+ * junction would let the build leave the folder the person named), and it holds a package.json.
+ */
+export function checkRepoFolder(folder) {
+    if (typeof folder !== 'string' || !folder.trim())
+        return 'No folder is given.';
+    const resolved = resolve(folder);
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        return `The folder ${resolved} does not exist.`;
+    }
+    if (!stat.isDirectory())
+        return `${resolved} is not a folder.`;
+    if (parse(resolved).root === resolved)
+        return `${resolved} is the top of a drive. Pick the project's own folder.`;
+    // The real path must be the path as written, component by component: any link on the way is refused
+    let real;
+    try {
+        real = realpathSync.native(resolved);
+    }
+    catch {
+        return `The folder ${resolved} cannot be read.`;
+    }
+    if (!same(real, resolved))
+        return `${resolved} goes through a link (it really is ${real}). Give the real folder path.`;
+    if (same(resolved, resolve(homedir())))
+        return 'That is the home folder. Pick the project folder inside it.';
+    if (insideOrSame(realOrResolved(configDir()), real))
+        return 'That folder is the bridge home, which holds the sign-in. A check never builds there.';
+    for (const part of resolved.split(sep)) {
+        if (SECRET_FOLDERS.includes(part.toLowerCase()))
+            return `${resolved} is inside a ${part} folder, which holds keys or logins. A check never builds there.`;
+    }
+    if (!insideGit(resolved))
+        return `${resolved} is not a git project (no .git here or above it).`;
+    if (!existsSync(join(resolved, 'package.json')))
+        return `${resolved} has no package.json.`;
+    return null;
+}