brainferno-mcp-bridge 0.1.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+Brainferno MCP Bridge is licensed under the Apache License 2.0 (see `LICENSE`). It depends
+on, talks to, or was informed by the following third-party software and materials. None of
+the Adobe materials below are copied into this repository.
+
+## Runtime dependencies (bundled by `npm install`)
+
+| Package | License | Copyright |
+| --- | --- | --- |
+| `@modelcontextprotocol/sdk` | MIT | Anthropic, PBC |
+| `ws` | MIT | Einar Otto Stangvik and contributors |
+| `zod` | MIT | Colin McDonnell |
+
+Development-only dependencies (`typescript`, `vitest`, `tsx`, `@types/*`) are MIT or
+Apache-2.0 licensed and are not distributed with the product.
+
+## Adobe interfaces this software talks to (not distributed here)
+
+- **Adobe UXP** (Photoshop, Premiere Pro panels) and **Adobe CEP** (After Effects,
+  Audition panel), **ExtendScript**, the **Illustrator MCP server** built into Adobe
+  Illustrator, the **Adobe Media Encoder web service** (`ame_webservice_console`), and
+  **aerender**. These ship with the Adobe applications under Adobe's own terms; users need
+  their own licensed copies. Use of the Adobe developer platforms is governed by the Adobe
+  Developer Terms of Use (https://www.adobe.com/legal/terms/developer.html).
+- `@adobe/premierepro` (TypeScript type definitions, Apache-2.0, Adobe) was used as a
+  reference while writing the Premiere Pro panel. It is not bundled.
+- Adobe sample code was read for API behavior but not copied: `Adobe-CEP/Samples` (MIT,
+  Adobe), `AdobeDocs/uxp-premiere-pro-samples` (Apache-2.0, Adobe), and the Remote AME web
+  console assets shipped with Adobe Media Encoder.
+- `docs/api-dumps/audition-26.3.json` is a list of class, property and method names and
+  types obtained by ExtendScript reflection from Adobe Audition, recorded for
+  interoperability. Adobe-authored help text was removed before publishing.
+
+## Documentation consulted
+
+- Adobe Developer documentation for UXP, Premiere Pro, and Photoshop
+  (https://developer.adobe.com), Adobe's CEP resources (https://github.com/Adobe-CEP), and
+  the community-maintained *Adobe Media Encoder Scripting Guide*
+  (https://ame-scripting.docsforadobe.dev, © Adobe).
+
+## Optional external programs (not distributed here)
+
+- **ffmpeg / ffprobe** (https://ffmpeg.org; LGPL-2.1+ or GPL depending on the build) power
+  the `audio_*` tools. The user installs ffmpeg separately; this software only runs it.
+- **Node.js** (MIT-style license, https://github.com/nodejs/node/blob/main/LICENSE).
+
+## Trademarks
+
+Adobe, After Effects, Audition, Creative Cloud, Illustrator, Media Encoder, Photoshop, and
+Premiere Pro are either registered trademarks or trademarks of Adobe in the United States
+and/or other countries. Other names may be trademarks of their respective owners.

package/dist/bridge/handshake.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The handshake file solves two problems at once for the in-app panels:
+ * discovering which port the bridge bound, and learning the per-install token
+ * they must present. The server writes it once it is listening; each panel
+ * reads it (CEP via Node `fs`, UXP via `localFileSystem: "fullAccess"`) before
+ * dialing out.
+ *
+ * It is written mode-600 under the user's home directory. It carries a live
+ * secret, so it must never be world-readable and is removed on clean shutdown.
+ */
+export interface Handshake {
+    /** Wire protocol the server speaks; panels refuse a mismatch. */
+    protocolVersion: number;
+    /** Loopback port the bridge is listening on. */
+    port: number;
+    /** Shared secret the panel must present, or "" when auth is disabled. */
+    token: string;
+    /** Server process id, so a panel can detect a stale file. */
+    pid: number;
+}
+/** Default location of the handshake file. */
+export declare function defaultHandshakePath(): string;
+/**
+ * Writes the handshake file mode-600, creating its directory if needed.
+ *
+ * The default write flag ("w") follows symlinks and applies its mode only when
+ * creating a new file — so a pre-existing (or symlinked) file could see the
+ * token written through it with looser permissions. Remove any existing entry
+ * first and create exclusively ("wx", i.e. O_CREAT|O_EXCL, which refuses to
+ * follow an existing symlink) so the secret always lands in a fresh 600 file.
+ */
+export declare function writeHandshake(path: string, handshake: Handshake): void;
+/** Removes the handshake file, ignoring the case where it is already gone. */
+export declare function removeHandshake(path: string): void;

package/dist/bridge/handshake.js

@@ -0,0 +1,36 @@
+/**
+ * The handshake file solves two problems at once for the in-app panels:
+ * discovering which port the bridge bound, and learning the per-install token
+ * they must present. The server writes it once it is listening; each panel
+ * reads it (CEP via Node `fs`, UXP via `localFileSystem: "fullAccess"`) before
+ * dialing out.
+ *
+ * It is written mode-600 under the user's home directory. It carries a live
+ * secret, so it must never be world-readable and is removed on clean shutdown.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Default location of the handshake file. */
+export function defaultHandshakePath() {
+    return join(homedir(), ".brainferno-mcp-bridge", "bridge.json");
+}
+/**
+ * Writes the handshake file mode-600, creating its directory if needed.
+ *
+ * The default write flag ("w") follows symlinks and applies its mode only when
+ * creating a new file — so a pre-existing (or symlinked) file could see the
+ * token written through it with looser permissions. Remove any existing entry
+ * first and create exclusively ("wx", i.e. O_CREAT|O_EXCL, which refuses to
+ * follow an existing symlink) so the secret always lands in a fresh 600 file.
+ */
+export function writeHandshake(path, handshake) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    rmSync(path, { force: true });
+    writeFileSync(path, JSON.stringify(handshake, null, 2), { mode: 0o600, flag: "wx" });
+}
+/** Removes the handshake file, ignoring the case where it is already gone. */
+export function removeHandshake(path) {
+    rmSync(path, { force: true });
+}
+//# sourceMappingURL=handshake.js.map

package/dist/bridge/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/bridge/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAa1C,8CAA8C;AAC9C,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,wBAAwB,EAAE,aAAa,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,SAAoB;IAC/D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACvF,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/dist/bridge/script-escape.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Turning a runtime string into a literal that is safe to splice into generated
+ * host script source (ExtendScript ES3, or UXP JS).
+ *
+ * `JSON.stringify` is *not* a correct JS-source escaper: it emits U+2028 (LINE
+ * SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) verbatim, and both are line
+ * terminators to a JavaScript parser — an ES3 engine treats them as a newline
+ * mid-string and throws a syntax error (and, for attacker-influenced input such
+ * as a layer or comp name, it is a script-injection seam). Escape them, along
+ * with quotes, backslashes, and the other control characters, explicitly.
+ */
+/**
+ * Returns a double-quoted JavaScript string literal (quotes included) encoding
+ * `value`, safe to embed directly in generated script source.
+ */
+export declare function jsStringLiteral(value: string): string;

package/dist/bridge/script-escape.js

@@ -0,0 +1,47 @@
+/**
+ * Turning a runtime string into a literal that is safe to splice into generated
+ * host script source (ExtendScript ES3, or UXP JS).
+ *
+ * `JSON.stringify` is *not* a correct JS-source escaper: it emits U+2028 (LINE
+ * SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) verbatim, and both are line
+ * terminators to a JavaScript parser — an ES3 engine treats them as a newline
+ * mid-string and throws a syntax error (and, for attacker-influenced input such
+ * as a layer or comp name, it is a script-injection seam). Escape them, along
+ * with quotes, backslashes, and the other control characters, explicitly.
+ */
+const SIMPLE_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\v": "\\v",
+};
+/**
+ * Returns a double-quoted JavaScript string literal (quotes included) encoding
+ * `value`, safe to embed directly in generated script source.
+ */
+export function jsStringLiteral(value) {
+    let out = '"';
+    for (const ch of value) {
+        const mapped = SIMPLE_ESCAPES[ch];
+        if (mapped !== undefined) {
+            out += mapped;
+            continue;
+        }
+        const code = ch.codePointAt(0);
+        // U+2028 / U+2029 are JS line terminators; C0/C1 controls must not appear
+        // raw in source. All of these are in the BMP, so a 4-digit \uXXXX escape is
+        // always sufficient (and ES3-valid). Everything else passes through.
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029) {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out + '"';
+}
+//# sourceMappingURL=script-escape.js.map

package/dist/bridge/script-escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-escape.js","sourceRoot":"","sources":["../../src/bridge/script-escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,cAAc,GAA2B;IAC7C,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,GAAG,IAAI,MAAM,CAAC;YACd,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;QAChC,0EAA0E;QAC1E,4EAA4E;QAC5E,qEAAqE;QACrE,IAAI,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACxF,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,CAAC;AACnB,CAAC"}

package/dist/bridge/socket.d.ts

@@ -0,0 +1,79 @@
+import type { AppId } from "@brainferno/mcp-bridge-protocol";
+import { type AppBridge } from "./types.js";
+export interface BridgeServerOptions {
+    port: number;
+    /** Explicit shared secret. Ignored when `insecure` is set. */
+    token: string;
+    /** Disable authentication and skip the handshake file (debug/tests only). */
+    insecure?: boolean;
+    defaultTimeoutMs: number;
+    /** Ping cadence; 0 disables the heartbeat (tests). */
+    heartbeatIntervalMs?: number;
+    /** How long a fresh socket has to send a valid hello before it is closed. */
+    authDeadlineMs?: number;
+    /** Where to write the port+token handshake file. Skipped when `insecure`. */
+    handshakeFilePath?: string;
+    /** Extra Origins to accept, beyond loopback origins and the no-Origin case. */
+    allowedOrigins?: string[];
+    /** Maximum concurrent sockets before new upgrades are refused. */
+    maxConnections?: number;
+    /** Loopback only by default — this port evaluates arbitrary script. */
+    host?: string;
+}
+/**
+ * Accepts panel connections and routes commands to whichever application each
+ * panel authenticated as. One panel per application; a second authenticated
+ * connection for the same application replaces the first.
+ *
+ * Security posture (a localhost WebSocket is reachable by any local process and,
+ * because browsers exempt WebSockets from the same-origin policy, by any web
+ * page the user visits): the upgrade is Origin/Host-validated; every socket must
+ * present a valid token in its hello within a short deadline before any other
+ * frame is honored; and results are matched per-socket so one panel can never
+ * settle another's in-flight call.
+ */
+export declare class BridgeServer {
+    private readonly options;
+    private wss;
+    private readonly panels;
+    private readonly states;
+    /** Serializes commands per app: one script/modal scope per host at a time. */
+    private readonly appQueues;
+    private readonly token;
+    private readonly insecure;
+    private readonly heartbeatIntervalMs;
+    private readonly authDeadlineMs;
+    private readonly allowedOrigins;
+    private readonly maxConnections;
+    private heartbeat?;
+    constructor(options: BridgeServerOptions);
+    private listen;
+    /**
+     * Resolves once a listening socket is bound. If the preferred port is taken
+     * (typically a stale server instance still holding it), falls back to an
+     * OS-assigned port: panels discover the real port from the handshake file,
+     * so a fixed port is a preference, not a requirement.
+     */
+    ready(): Promise<void>;
+    private waitListening;
+    /** The bound port, or 0 before the server is listening. */
+    port(): number;
+    bridgeFor(appId: AppId): AppBridge;
+    connectedApps(): AppId[];
+    private onListening;
+    private verifyUpgrade;
+    private originAllowed;
+    private onConnection;
+    private onMessage;
+    private handleHello;
+    private tokenMatches;
+    private settle;
+    private onClose;
+    private pingAll;
+    private execute;
+    private dispatch;
+    private resolveTimeout;
+    private connectHint;
+    private send;
+    close(): Promise<void>;
+}