@agent-flow-board/bridge 0.2.0 → 0.4.0

package/dist/checks/repoenv.js

@@ -0,0 +1,162 @@
+// THE WHOLE .env OF A REGISTRATION THAT THE OWNER OPTED IN (step 3.4, Registration.adoptEnv, set with an approval code). The registration's preview adopts every variable of the
+// repo's own .env files, so the app runs with the settings it was written for, EXCEPT the deny list (variables that load code or move the machine's own settings) and the
+// run's own settings (PORT, HOST, NODE_ENV). The files are read from the registered repo folder, never from the run's copy (a copy has no .env), and never printed: every
+// message here names variables and files, never values. The caller keeps what is returned in `startEnv` OUT of install and build (adopted values reach the START step only),
+// runs databaseProblems() (envrules.ts) over it, and puts `redactions` into the redaction needles.
+// -- DEP-MODULES -- //
+import { closeSync, fstatSync, lstatSync, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { expandRefs } from './envrules.js';
+// -- CONSTANTS -- //
+/** Read in this order, a later file overriding an earlier one (the order a production build of Vite and SvelteKit uses). .env.test is read only when none of these exist in that folder. */
+export const ADOPT_FILES = ['.env', '.env.local', '.env.production', '.env.production.local'];
+const FALLBACK = ['.env.test'];
+/** Variables that name the app's own address: pointed at the run's preview, because the value in .env is the live address and would make every form and redirect fail. */
+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 (the run sets EMAIL_PROVIDER to log itself). */
+const RUN_OWN = new Set(['PORT', 'HOST', 'NODE_ENV', 'EMAIL_PROVIDER']);
+/** Never adopted, whatever the file says: names that load code, change where programs and certificates come from, or move the machine's own settings. */
+const DENY_EXACT = new Set([
+    'NODE_OPTIONS',
+    'PATH',
+    'PATHEXT',
+    'COMSPEC',
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'SYSTEMROOT',
+    'TEMP',
+    'TMP',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'ALL_PROXY',
+    'NODE_EXTRA_CA_CERTS',
+    'NODE_TLS_REJECT_UNAUTHORIZED',
+    // Added beyond the plan's list: the same kind of danger
+    'NODE_PATH',
+    'NODE_REPL_EXTERNAL_MODULE'
+]);
+/** Prefixes are compared without case (npm_config_*, NPM_CONFIG_*, PNPM_*, YARN_*, LD_*). */
+const DENY_PREFIX = ['NPM_CONFIG_', 'PNPM_', 'YARN_', 'LD_', 'DYLD_', 'AFB_MAIL_FENCE_'];
+const MIN_REDACT = 8;
+const MAX_FILE_BYTES = 1_000_000;
+// -- FUNCTIONS -- //
+/** True when a variable may never be adopted. Compared without case, because a Windows environment has none. */
+export function isDeniedName(name) {
+    const upper = name.toUpperCase();
+    return DENY_EXACT.has(upper) || DENY_PREFIX.some((p) => upper.startsWith(p));
+}
+/** NAME=value lines. `export ` and one pair of quotes are allowed; a quoted value may run over several lines, and \n in a double-quoted value is a line break. Comments and lines that are not settings are skipped. */
+export function parseRepoEnvText(text) {
+    const out = new Map();
+    const body = String(text);
+    const lines = (body.charCodeAt(0) === 0xfeff ? body.slice(1) : body).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);
+            if (q === '"')
+                v = v.replace(/\\n/g, '\n');
+        }
+        else
+            v = v.replace(/\s+#.*$/, '');
+        out.set(m[1], v);
+    }
+    return out;
+}
+/** The text of a plain file, or null. A link, a folder or a file over 1 MB is not read (a link could point at a key outside the repo). */
+function readPlainFile(file) {
+    try {
+        const st = lstatSync(file);
+        if (!st.isFile() || st.isSymbolicLink() || st.size > MAX_FILE_BYTES)
+            return null;
+        const fd = openSync(file, 'r');
+        try {
+            const fst = fstatSync(fd);
+            if (!fst.isFile() || fst.size > MAX_FILE_BYTES)
+                return null;
+            return readFileSync(fd, 'utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/** The folders the env files may sit in, repo root first and the app folder after it (the app folder wins). */
+function foldersOf(repo, appDir) {
+    const out = [{ dir: repo, label: '' }];
+    if (appDir) {
+        const clean = appDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+        if (!clean || clean.split('/').includes('..') || /^([a-zA-Z]:|\/)/.test(clean))
+            throw new Error('The app folder of this registration is not a plain relative folder.');
+        out.push({ dir: join(repo, clean), label: `${clean}/` });
+    }
+    return out;
+}
+/**
+ * Every variable of the registration's .env files, with the run's own address filled in. Never throws for a missing file (no file is an empty result).
+ * `vars.baseUrl` is the run's preview address, put in every self-address variable.
+ */
+export function adoptRepoEnv(cfg, vars) {
+    const merged = new Map();
+    const files = [];
+    for (const { dir, label } of foldersOf(cfg.repo, cfg.appDir)) {
+        let found = ADOPT_FILES.filter((f) => readPlainFile(join(dir, f)) !== null);
+        if (!found.length)
+            found = FALLBACK.filter((f) => readPlainFile(join(dir, f)) !== null);
+        for (const f of found) {
+            const text = readPlainFile(join(dir, f));
+            if (text === null)
+                continue;
+            for (const [k, v] of parseRepoEnvText(text))
+                merged.set(k, v);
+            files.push(`${label}${f}`);
+        }
+    }
+    const result = { startEnv: {}, redactions: [], names: [], denied: [], files };
+    if (!merged.size)
+        return result;
+    // ${NAME} inside a value is filled from the same files (what dotenv-expand does), since the preview is given plain values
+    const plain = Object.fromEntries(merged);
+    for (const [k, v] of merged) {
+        if (RUN_OWN.has(k.toUpperCase()))
+            continue;
+        if (isDeniedName(k)) {
+            result.denied.push(k);
+            continue;
+        }
+        result.startEnv[k] =
+            SELF_ADDRESS.test(k) && /^https?:\/\//i.test(v) ? vars.baseUrl : expandRefs(v, plain);
+    }
+    result.names = Object.keys(result.startEnv);
+    const needles = new Set();
+    for (const v of Object.values(result.startEnv)) {
+        if (v.length >= MIN_REDACT)
+            needles.add(v);
+        if (v.includes('\n'))
+            for (const l of v.split('\n'))
+                if (l.trim().length >= MIN_REDACT)
+                    needles.add(l.trim());
+    }
+    result.redactions = [...needles];
+    return result;
+}

package/dist/checks/roots.js

@@ -0,0 +1,144 @@
+// THE ROOTS: THE FOLDERS THE OWNER APPROVED AS PARENTS OF REGISTERED REPOS. At most five, sealed with an HMAC so a hand-written list is refused. A root is never a drive,
+// the home folder (or a folder above it), the bridge home or a folder of keys and logins. Adding or removing one needs a single-use approval code (approve.ts).
+// -- DEP-MODULES -- //
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, parse, relative, resolve, sep } from 'node:path';
+// -- MODULES -- //
+import { appendAudit } from './audit.js';
+import { Refusal, consumeApproval, sameMac, seal, writeFileAtomic } from './approve.js';
+import { withLockSync } from './lock.js';
+import { rootsFile } from './paths.js';
+import { configDir } from '../tokenStore.js';
+// -- CONSTANTS -- //
+export const MAX_ROOTS = 5;
+const SECRET_FOLDERS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker'];
+// -- FUNCTIONS -- //
+function realOrResolved(p) {
+    try {
+        return realpathSync.native(resolve(p));
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/** True when `child` is `parent` or below it. Both are real paths already; Windows compares without case (path.relative does). */
+export function insideOrSame(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel));
+}
+/** The real path of a folder that may be a root, or a Refusal with one plain sentence. */
+export function cleanRoot(raw) {
+    const text = String(raw ?? '').trim();
+    if (!text)
+        throw new Refusal('No folder is given.');
+    let real;
+    try {
+        real = realpathSync.native(resolve(text));
+    }
+    catch {
+        throw new Refusal(`The folder ${resolve(text)} does not exist.`);
+    }
+    if (!statSync(real).isDirectory())
+        throw new Refusal(`${real} is not a folder.`);
+    if (parse(real).root === real)
+        throw new Refusal(`${real} is the top of a drive. Name the folder that holds your projects.`);
+    if (insideOrSame(real, realOrResolved(homedir())))
+        throw new Refusal(`${real} is your home folder or above it. Name a folder inside it that holds your projects.`);
+    const bridge = realOrResolved(configDir());
+    if (insideOrSame(real, bridge) || insideOrSame(bridge, real))
+        throw new Refusal(`${real} is or holds the bridge home, which holds the sign-in. It cannot be a root.`);
+    if (real.split(sep).some((s) => SECRET_FOLDERS.includes(s.toLowerCase())))
+        throw new Refusal(`${real} is in a folder that holds keys or logins (.ssh, .gnupg, .aws, .kube or .docker), so it cannot be a root.`);
+    return real;
+}
+const sealOf = (roots) => seal('roots', JSON.stringify({ version: 1, roots }));
+/** The roots and, when the file cannot be trusted, one sentence saying why (the list is then empty). */
+export function readRoots() {
+    const file = rootsFile();
+    if (!existsSync(file))
+        return { roots: [], problem: null };
+    try {
+        const doc = JSON.parse(readFileSync(file, 'utf8'));
+        const body = doc && typeof doc === 'object' ? doc.body : null;
+        const mac = doc && typeof doc === 'object' ? doc.mac : null;
+        const roots = body && typeof body === 'object' ? body.roots : null;
+        if (typeof mac !== 'string' ||
+            !Array.isArray(roots) ||
+            !roots.every((r) => typeof r === 'string'))
+            return {
+                roots: [],
+                problem: 'The roots file is not one this tool wrote, so no root counts.'
+            };
+        const list = roots;
+        if (!sameMac(sealOf(list), mac))
+            return {
+                roots: [],
+                problem: 'The roots file was not written by "check roots" on this machine, so no root counts.'
+            };
+        return { roots: list, problem: null };
+    }
+    catch {
+        return { roots: [], problem: 'The roots file cannot be read, so no root counts.' };
+    }
+}
+export const listRoots = () => readRoots().roots;
+function writeRoots(roots) {
+    writeFileAtomic(rootsFile(), JSON.stringify({ body: { version: 1, roots }, mac: sealOf(roots) }, null, 2) + '\n');
+}
+/**
+ * The root that holds `repo`, compared by real path so a link or a `..` cannot step out, or null. A root that was fine when it was added but now leads
+ * somewhere the rules forbid (a junction put in its place) no longer counts.
+ */
+export function rootHolding(repo, roots = listRoots()) {
+    let real;
+    try {
+        real = realpathSync.native(resolve(repo));
+    }
+    catch {
+        return null;
+    }
+    for (const r of roots) {
+        let root;
+        try {
+            root = cleanRoot(r);
+        }
+        catch {
+            continue;
+        }
+        if (insideOrSame(root, real))
+            return root;
+    }
+    return null;
+}
+/** Adds a root. Needs an approval code for the action "roots" and this folder. The code is used only when everything else is fine. */
+export function addRoot(dir, approval) {
+    const real = cleanRoot(dir);
+    return withLockSync('roots', () => {
+        const roots = readRoots().roots;
+        if (roots.some((r) => insideOrSame(r, real) && insideOrSame(real, r)))
+            return real;
+        if (roots.length >= MAX_ROOTS)
+            throw new Refusal(`There are already ${MAX_ROOTS} roots. Remove one first (check roots remove <folder> --approval <code>).`);
+        if (!approval || !consumeApproval('roots', real, approval))
+            throw new Refusal(`Adding a root needs a code from the owner: check approve --request --action roots --target "${real}", then --approval <code>.`);
+        writeRoots([...roots, real]);
+        appendAudit('root added', { folder: real, count: roots.length + 1 });
+        return real;
+    });
+}
+/** Removes a root. Needs an approval code too, so an agent cannot swap one root for another. */
+export function removeRoot(dir, approval) {
+    const real = realOrResolved(dir);
+    return withLockSync('roots', () => {
+        const roots = readRoots().roots;
+        const hit = roots.find((r) => insideOrSame(r, real) && insideOrSame(real, r));
+        if (!hit)
+            throw new Refusal(`${real} is not a root.`);
+        if (!approval || !consumeApproval('roots', real, approval))
+            throw new Refusal(`Removing a root needs a code from the owner: check approve --request --action roots --target "${real}", then --approval <code>.`);
+        writeRoots(roots.filter((r) => r !== hit));
+        appendAudit('root removed', { folder: hit, count: roots.length - 1 });
+        return hit;
+    });
+}

package/dist/checks/routing.js

@@ -0,0 +1,68 @@
+// WHICH REGISTRATION A RUN USES. Never a guess. In order: (1) the one named on the run, (2) the one saved on the check, (3) a "// afb-registration: NAME" line in the first 12 lines of
+// the script, (4) the only registration of the board project. Otherwise a refusal with a code an agent can act on and the list of choices.
+// -- MODULES -- //
+import { REGISTRATION_NAME, listRegistrations } from './registry.js';
+// -- CONSTANTS -- //
+const HEADER_LINES = 12;
+const HEADER = /^\s*\/\/\s*afb-registration:\s*([A-Za-z0-9_-]{1,32})\s*$/;
+// -- FUNCTIONS -- //
+/** A refusal that carries a code and the names the agent can choose from. */
+export class RegistrationError extends Error {
+    code;
+    registrations;
+    constructor(code, message, registrations = []) {
+        super(message);
+        this.code = code;
+        this.registrations = registrations;
+        this.name = 'RegistrationError';
+    }
+}
+/** The registration a check script names in a "// afb-registration: NAME" line among its first 12 lines, or null. */
+export function registrationHeader(source) {
+    for (const line of String(source ?? '')
+        .split(/\r?\n/)
+        .slice(0, HEADER_LINES)) {
+        const m = HEADER.exec(line);
+        if (m?.[1])
+            return m[1];
+    }
+    return null;
+}
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * The registration for a board project. `named` is the name a run, a check or a script header gave (or null). A name may carry its organisation (org/NAME), and then it
+ * must be this one. `all` is every registration of the organisation (the registry by default).
+ */
+export function pickRegistration(org, boardProject, named, all = listRegistrations(org)) {
+    const ofOrg = all.filter((r) => r.org === org);
+    const serving = ofOrg.filter((r) => same(r.boardProject, boardProject));
+    const list = serving.map((r) => r.name);
+    const choices = list.length
+        ? `Registrations of ${boardProject}: ${list.join(', ')}.`
+        : `${boardProject} has no registration here.`;
+    if (named) {
+        const parts = String(named).split('/');
+        if (parts.length > 2 || (parts.length === 2 && !same(parts[0] ?? '', org)))
+            throw new RegistrationError('REGISTRATION_UNKNOWN', `"${String(named).slice(0, 60)}" is not a registration name of ${org}. Write NAME or ${org}/NAME. ${choices}`, list);
+        const bare = parts[parts.length - 1] ?? '';
+        if (!REGISTRATION_NAME.test(bare))
+            throw new RegistrationError('REGISTRATION_UNKNOWN', `"${bare.slice(0, 40)}" is not a registration name. ${choices}`, list);
+        const hit = serving.find((r) => same(r.name, bare));
+        if (hit)
+            return hit;
+        const other = ofOrg.find((r) => same(r.name, bare));
+        if (other)
+            throw new RegistrationError('REGISTRATION_MISMATCH', `The registration ${other.name} serves the board project ${other.boardProject}, not ${boardProject}. ${choices}`, list);
+        throw new RegistrationError('REGISTRATION_UNKNOWN', `This machine has no registration ${bare} in ${org}. ${choices}`, list);
+    }
+    if (serving.length === 1 && serving[0])
+        return serving[0];
+    if (!serving.length)
+        throw new RegistrationError('REGISTRATION_UNKNOWN', `No registration serves ${boardProject} in ${org}. Register one: agent-flow-board check project <NAME> --org ${org} --repo <folder> --board-project ${boardProject}.`, []);
+    throw new RegistrationError('REGISTRATION_REQUIRED', `${boardProject} has ${serving.length} registrations (${list.join(', ')}) and none was named. Name one on the run, save one on the check, or put a "// afb-registration: <name>" line at the top of the check script.`, list);
+}
+/** Routes one run: the name on the run, else the name saved on the check, else the script's header, else the only registration. */
+export function routeRun(opts) {
+    const named = opts.run || opts.check || (opts.script ? registrationHeader(opts.script) : null);
+    return pickRegistration(opts.org, opts.boardProject, named, opts.all);
+}