@agent-flow-board/bridge 0.0.0-stage → 0.2.0

package/dist/queue.js

@@ -0,0 +1,175 @@
+// THE OFFLINE WRITE QUEUE (SPEC 6.3). A WRITE WHILE THE BOARD IS UNREACHABLE IS QUEUED AND SAID TO BE QUEUED, NEVER ANSWERED WITH A MADE UP RESULT.
+// Replay keeps the original order. A write that fails on replay holds the later writes for the same item; other items continue.
+// -- DEP-MODULES -- //
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+// -- CONSTANTS -- //
+/** A lock file older than this belongs to a process that died inside the lock, because the work inside it takes milliseconds. */
+export const LOCK_STALE_MS = 10_000;
+/** The longest a caller waits for the lock before it takes the lock over. */
+export const LOCK_WAIT_MS = 5_000;
+// -- FUNCTIONS -- //
+/** Waits without spinning, for the sync methods of the queue. */
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+export class Queue {
+    file;
+    lockTimes;
+    constructor(file, lockTimes = {
+        staleMs: LOCK_STALE_MS,
+        waitMs: LOCK_WAIT_MS
+    }) {
+        this.file = file;
+        this.lockTimes = lockTimes;
+    }
+    /**
+     * Runs fn while this process holds the lock file next to the queue (an exclusive create). Two bridges of two tools share one
+     * queue file, and without the lock their read, change, write steps can overwrite each other. A lock left by a dead process
+     * is taken over once it is stale.
+     */
+    withLock(fn) {
+        const lock = `${this.file}.lock`;
+        mkdirSync(dirname(this.file), { recursive: true });
+        const giveUp = Date.now() + this.lockTimes.waitMs;
+        for (;;) {
+            try {
+                const fd = openSync(lock, 'wx', 0o600);
+                writeSync(fd, String(process.pid));
+                closeSync(fd);
+                break;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+                let stale = Date.now() > giveUp;
+                try {
+                    stale ||= Date.now() - statSync(lock).mtimeMs > this.lockTimes.staleMs;
+                }
+                catch {
+                    continue; // The holder just let go
+                }
+                if (stale) {
+                    // Renaming is atomic, so when two callers find the same stale lock only one of them removes it
+                    const aside = `${lock}.stale-${process.pid}-${Date.now()}`;
+                    try {
+                        renameSync(lock, aside);
+                        rmSync(aside, { force: true });
+                    }
+                    catch {
+                        /* Another caller took it over first */
+                    }
+                    continue;
+                }
+                sleepSync(20);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            rmSync(lock, { force: true });
+        }
+    }
+    read() {
+        if (!existsSync(this.file))
+            return [];
+        try {
+            return JSON.parse(readFileSync(this.file, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    write(list) {
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(this.file, JSON.stringify(list, null, 1), { mode: 0o600 });
+    }
+    list = () => this.read();
+    enqueue(name, args) {
+        return this.withLock(() => this.enqueueLocked(name, args));
+    }
+    enqueueLocked(name, args) {
+        const list = this.read();
+        const id = `q${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+        const key = String(args.item ?? args.id ?? args.sessionId ?? 'none');
+        // The id doubles as the request id, so replaying after a half finished send can never write twice
+        const entry = {
+            id,
+            at: new Date().toISOString(),
+            name,
+            args: {
+                ...args,
+                requestId: typeof args.requestId === 'string' ? args.requestId : `afb-${id}`
+            },
+            key,
+            state: 'queued'
+        };
+        list.push(entry);
+        this.write(list);
+        return entry;
+    }
+    drop(id) {
+        return this.withLock(() => {
+            const list = this.read();
+            const next = list.filter((e) => e.id !== id);
+            if (next.length === list.length)
+                return false;
+            this.write(next);
+            return true;
+        });
+    }
+    /** Puts a held write back in the line so the next replay tries it again. */
+    retry(id) {
+        return this.withLock(() => {
+            const list = this.read();
+            const e = list.find((x) => x.id === id);
+            if (!e)
+                return false;
+            e.state = 'queued';
+            delete e.reason;
+            this.write(list);
+            return true;
+        });
+    }
+    /** Sends queued writes in order. Stops at the first sign the board is still unreachable. */
+    async replay(send) {
+        // The lock is not held while writes are sent, which can take long. What was decided is merged into the file afterwards.
+        const list = this.read();
+        const gone = new Set();
+        const heldNow = new Map();
+        const heldKeys = new Set(list.filter((e) => e.state === 'held').map((e) => e.key));
+        let sent = 0;
+        let held = 0;
+        let offline = false;
+        for (const e of list) {
+            if (offline || e.state === 'held' || heldKeys.has(e.key)) {
+                if (!offline && e.state !== 'held')
+                    held++;
+                continue;
+            }
+            const r = await send(e);
+            if (r.kind === 'ok') {
+                sent++;
+                gone.add(e.id);
+            }
+            else if (r.kind === 'refused') {
+                heldNow.set(e.id, r.reason);
+                heldKeys.add(e.key);
+                held++;
+            }
+            else {
+                offline = true;
+            }
+        }
+        this.withLock(() => {
+            const current = this.read();
+            const next = current
+                .filter((e) => !gone.has(e.id))
+                .map((e) => {
+                const reason = heldNow.get(e.id);
+                return reason === undefined ? e : { ...e, state: 'held', reason };
+            });
+            this.write(next);
+        });
+        return { sent, held, offline };
+    }
+}

package/dist/tokenStore.js

@@ -0,0 +1,177 @@
+// WHERE THE BRIDGE KEEPS ITS TOKEN. THE OS KEYCHAIN WHERE ONE EXISTS, AN ENCRYPTED FILE WHERE NONE DOES (SSH SESSIONS, CONTAINERS)
+// Backends: macOS Keychain (security), Linux Secret Service (secret-tool), Windows DPAPI (bound to the signed in user),
+// and an AES-256-GCM file with its key in a separate file readable only by its owner.
+// -- DEP-MODULES -- //
+import { execFileSync } from 'node:child_process';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// -- CONSTANTS -- //
+const SERVICE = 'agent-flow-board';
+// -- FUNCTIONS -- //
+/**
+ * The name a sign in is stored under: the server host, plus the organisation when one is chosen, so two organisations on one
+ * board keep separate sign ins. Without an organisation it is the plain host, as before.
+ */
+export const accountKey = (server, org) => org ? `${new URL(server).host}/${org}` : new URL(server).host;
+export const configDir = () => process.env.AFB_BRIDGE_HOME ?? join(homedir(), '.agent-flow-board');
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+const has = (cmd, args = ['--version']) => {
+    try {
+        execFileSync(cmd, args, { stdio: 'ignore', timeout: 4000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** AES-256-GCM in a file. The key sits in its own file with owner only permissions. Better than plain text, weaker than a keychain. */
+export function fileStore(dir = configDir()) {
+    const keyFile = join(dir, 'key');
+    const dataFile = (account) => join(dir, `token-${account.replace(/[^A-Za-z0-9._-]/g, '_')}.enc`);
+    const key = () => {
+        ensureDir(dir);
+        if (!existsSync(keyFile)) {
+            writeFileSync(keyFile, randomBytes(32), { mode: 0o600 });
+            chmodSync(keyFile, 0o600);
+        }
+        return readFileSync(keyFile);
+    };
+    return {
+        kind: 'file',
+        get(account) {
+            const f = dataFile(account);
+            if (!existsSync(f))
+                return null;
+            try {
+                const raw = readFileSync(f);
+                const d = createDecipheriv('aes-256-gcm', key(), raw.subarray(0, 12));
+                d.setAuthTag(raw.subarray(12, 28));
+                return Buffer.concat([d.update(raw.subarray(28)), d.final()]).toString('utf8');
+            }
+            catch {
+                // A changed key or a damaged file means the token cannot be read, so the person signs in again
+                return null;
+            }
+        },
+        set(account, secret) {
+            const iv = randomBytes(12);
+            const c = createCipheriv('aes-256-gcm', key(), iv);
+            const enc = Buffer.concat([c.update(secret, 'utf8'), c.final()]);
+            writeFileSync(dataFile(account), Buffer.concat([iv, c.getAuthTag(), enc]), { mode: 0o600 });
+        },
+        delete(account) {
+            rmSync(dataFile(account), { force: true });
+        }
+    };
+}
+function macStore() {
+    return {
+        kind: 'macos',
+        get(account) {
+            try {
+                return (execFileSync('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w'], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'ignore']
+                }).trim() || null);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(account, secret) {
+            execFileSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-w', secret], { stdio: 'ignore' });
+        },
+        delete(account) {
+            try {
+                execFileSync('security', ['delete-generic-password', '-s', SERVICE, '-a', account], {
+                    stdio: 'ignore'
+                });
+            }
+            catch {
+                /* Nothing stored */
+            }
+        }
+    };
+}
+function linuxStore() {
+    return {
+        kind: 'linux',
+        get(account) {
+            try {
+                return (execFileSync('secret-tool', ['lookup', 'service', SERVICE, 'account', account], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'ignore']
+                }).trim() || null);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(account, secret) {
+            execFileSync('secret-tool', ['store', '--label', SERVICE, 'service', SERVICE, 'account', account], { input: secret, stdio: ['pipe', 'ignore', 'ignore'] });
+        },
+        delete(account) {
+            try {
+                execFileSync('secret-tool', ['clear', 'service', SERVICE, 'account', account], {
+                    stdio: 'ignore'
+                });
+            }
+            catch {
+                /* Nothing stored */
+            }
+        }
+    };
+}
+/** Windows keeps the secret as a DPAPI blob, which only the same user on the same machine can open. */
+function windowsStore(dir = configDir()) {
+    const file = (account) => join(dir, `token-${account.replace(/[^A-Za-z0-9._-]/g, '_')}.dpapi`);
+    const ps = (script, input) => execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        encoding: 'utf8',
+        input,
+        stdio: ['pipe', 'pipe', 'ignore']
+    }).trim();
+    return {
+        kind: 'windows',
+        get(account) {
+            if (!existsSync(file(account)))
+                return null;
+            try {
+                const out = ps(`$s = ConvertTo-SecureString (Get-Content -Raw -LiteralPath '${file(account)}'); [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))`);
+                return out || null;
+            }
+            catch {
+                return null;
+            }
+        },
+        set(account, secret) {
+            ensureDir(dir);
+            const blob = ps('ConvertFrom-SecureString (ConvertTo-SecureString -String ([Console]::In.ReadLine()) -AsPlainText -Force)', secret + '\n');
+            writeFileSync(file(account), blob, { mode: 0o600 });
+        },
+        delete(account) {
+            rmSync(file(account), { force: true });
+        }
+    };
+}
+/** Picks the best store for this machine. AFB_BRIDGE_STORE=file forces the encrypted file (SSH, containers). */
+export function pickStore() {
+    const forced = process.env.AFB_BRIDGE_STORE;
+    if (forced === 'file')
+        return fileStore();
+    if (process.platform === 'darwin' && has('security', ['help']))
+        return macStore();
+    if (process.platform === 'win32' && has('powershell', ['-NoProfile', '-Command', 'exit 0']))
+        return windowsStore();
+    // No display or session bus (SSH) means the Secret Service is not usable, so the file is used
+    if (process.platform === 'linux' &&
+        !process.env.SSH_CONNECTION &&
+        process.env.DBUS_SESSION_BUS_ADDRESS &&
+        has('secret-tool'))
+        return linuxStore();
+    return fileStore();
+}
+export { windowsStore };

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@agent-flow-board/bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@agent-flow-board/bridge",
+	"version": "0.2.0",
+	"type": "module",
+	"description": "Local bridge to an agent-flow-board server: forwards MCP calls over stdio, runs the coding tool hooks, writes the editor status and runs browser checks on this machine. It holds no board tool code.",
+	"license": "MIT",
+	"homepage": "https://afb.arbenger.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ArbenApura/agent-flow-board.git",
+		"directory": "packages/bridge"
+	},
+	"keywords": [
+		"agent-flow-board",
+		"mcp",
+		"claude-code",
+		"hooks"
+	],
+	"bin": {
+		"agent-flow-board": "dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"prepublishOnly": "tsc -p tsconfig.json"
+	}
+}