@godot-mcp/bridge-client 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Godot MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# @godot-mcp/bridge-client
+# Godot MCP
 
-Namespace bootstrap only. Install the first supported release from the `latest` tag.
+Godot MCP is an open-source, security-first MCP server and Godot editor addon. Phase 7 provides reversible installation, authenticated Godot 4.7 editor attachment, six default observe-only tools, explicitly gated runtime/input surfaces, permission-scoped editor authoring, native read-only GDScript debugging, and bounded structured performance evidence.
+
+## Requirements
+
+- macOS (the currently certified platform)
+- Node.js 22
+- pnpm 11.13.0
+- Godot 4.7 stable
+
+Compatibility is evidence-gated by `release/compatibility-matrix.json`. Godot 4.4–4.6 and Linux/Windows remain experimental until their exact matrix cells carry trusted certification receipts; pending cells are not advertised as supported.
+
+## Source quick start
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js init --project /absolute/path/to/godot-project
+node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js doctor --project /absolute/path/to/godot-project
+node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js editor --project /absolute/path/to/godot-project
+```
+
+For a verified release-to-release replacement, run `godot-mcp upgrade --project /absolute/path/to/godot-project --source /absolute/path/to/new/addons/godot_mcp`. Upgrade and rollback refuse independently modified installed files and preserve the original uninstall preimage.
+
+Use the `editor` command for the Phase 7-certified launch. It writes a short-lived owner-only startup attestation, then starts Godot with the authenticated editor debugger and native DAP assigned to one loopback port; the debugger binds first, so unauthenticated DAP never acquires a listener. The addon consumes the attestation and connects outward only when a matching MCP runtime publishes a short-lived pairing descriptor. Opening the project through another launcher keeps earlier editor features available, but runtime debugging fails closed because secure startup cannot be proven by copied user arguments alone.
+
+Register the source checkout with Codex using absolute paths:
+
+```bash
+codex mcp add godot -- node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js connect --project /absolute/path/to/godot-project
+```
+
+The default registration remains observe-only. To opt into one MCP-owned instrumented runtime, explicitly grant both its tier and pack:
+
+```bash
+codex mcp add godot-runtime -- node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js connect --project /absolute/path/to/godot-project --grant runtime_control --pack runtime
+```
+
+To launch and automate the owned runtime, grant the input pack separately:
+
+```bash
+codex mcp add godot-runtime-input -- node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js connect --project /absolute/path/to/godot-project --grant runtime_control --pack runtime --pack input
+```
+
+To preview and apply bounded editor mutations, explicitly grant both the mutation tier and editor pack:
+
+```bash
+codex mcp add godot-editor -- node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js connect --project /absolute/path/to/godot-project --grant project_mutate --pack editor
+```
+
+Start a fresh Codex task after registration so the newly registered MCP server is exposed. To stop using the addon while retaining its files, or remove the verified installation completely:
+
+```bash
+node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js disable --project /absolute/path/to/godot-project
+node /absolute/path/to/godot-mcp/packages/cli/dist/bin.js uninstall --project /absolute/path/to/godot-project
+```
+
+Uninstall refuses to remove the addon, project configuration, or `project.godot` if they changed independently after installation.
+
+## Implemented MCP tools
+
+- `godot_session` — attachment, project identity, versions, and grants
+- `godot_capabilities` — currently visible observe/core capabilities
+- `godot_doctor` — installation, plugin, identity, and attachment diagnostics
+- `godot_help` — built-in usage and security-boundary help
+- `godot_query` — bounded editor state, open scene/tree/node metadata, indexed resources, approved project settings, and redacted diagnostics
+- `godot_capture` — bounded PNG from the current 2D or selected 3D editor viewport, returned as MCP image content and persisted as session evidence
+
+The default six tools are read-only and closed-world. A runtime-authorized session additionally exposes:
+
+- `godot_runtime` — launch, bounded runtime queries/control, native GDScript breakpoints/stacks/variables/selector watches, monitor snapshots, and cancellable structured profiles for one authenticated child runtime
+- `godot_runtime_capture` — one to eight ordered running-game PNG frames with verified evidence metadata
+- `godot_input` — bounded events, frame-indexed sequences, non-passive recording, and deterministic replay for the owned runtime
+- `godot_editor` — preview, apply, undo, and redo one bounded scene/node/resource/source authoring batch with durable idempotency and native editor history
+
+For example:
+
+```json
+{ "operation": "scene_tree", "scenePath": "res://main.tscn", "maxDepth": 8, "maxNodes": 250 }
+{ "viewport": "2d", "maxWidth": 1280, "maxHeight": 720 }
+{ "operation": "launch", "scenePath": "res://main.tscn" }
+{ "operation": "debug_breakpoints_set", "handle": { "runId": "<run UUID>", "generation": 1 }, "breakpoints": [{ "sourcePath": "res://player.gd", "line": 42 }] }
+{ "operation": "profile_start", "handle": { "runId": "<run UUID>", "generation": 1 }, "durationMs": 1000, "intervalFrames": 1, "groups": ["frame", "memory"], "retainRaw": false }
+{ "operation": "sequence", "handle": { "runId": "<run UUID>", "generation": 1 }, "mode": "deterministic", "events": [{ "frameOffset": 0, "event": { "type": "action", "action": "jump", "pressed": true, "strengthMillionths": 1000000 } }, { "frameOffset": 1, "event": { "type": "action", "action": "jump", "pressed": false, "strengthMillionths": 0 } }] }
+```
+
+Runtime control and input are off unless their explicit flags are present. Deterministic sequences/replay require a paused owned runtime; offsets are zero-based, so offsets 0–1 process across two rendered frames and leave it paused. Recording captures only MCP-injected events. Receipts and audit summaries omit raw action names, keycodes, coordinates, and trace payloads. There is no OS-global/editor input, arbitrary text, process, filesystem, network, method-call, or GDScript-evaluation primitive.
+
+## Development and certification
+
+```bash
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-0-1
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-2
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-3
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-4
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-5
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-6
+GODOT_BIN=/opt/homebrew/bin/godot pnpm qa:phase-7
+```
+
+The Phase 7 gate certifies secure shared-port editor startup, native-DAP inertness, authenticated editor-session debugging, breakpoints/stacks/variables/selector watches, bounded public monitor snapshots, completed and cancelled profiles, hostile-input rejection, published stdio behavior, and zero owned-state or fixture residue. Earlier gates remain required regressions. See [Phase 7 testing](docs/testing/phase-7.md), [Phase 6 testing](docs/testing/phase-6.md), the [threat model](docs/security/threat-model.md), the [bridge protocol](docs/protocol/bridge-v1.md), and the [master design](docs/superpowers/specs/2026-07-15-godot-mcp-master-design.md).
+
+## Roadmap
+
+Later phases add declarative playtests, imports/builds/exports, evidence retrieval, compatibility lanes, and explicitly gated disposable-fixture unsafe mode. None of those capabilities are claimed by Phase 7.

package/dist/bridgeServer.d.ts

@@ -0,0 +1,24 @@
+import type { AddressInfo } from "node:net";
+import { type AuditSink, type SessionGrants } from "@godot-mcp/control-plane";
+import type { ProjectIdentity } from "@godot-mcp/protocol";
+import { BridgeSession } from "./bridgeSession.js";
+export interface StartBridgeServerOptions {
+    project: ProjectIdentity;
+    grants: SessionGrants;
+    addonManifestSha256: string;
+    auditSink: AuditSink;
+    handshakeTimeoutMs?: number;
+    now?: () => number;
+    onAttached?: (session: BridgeSession) => void;
+    onDisconnected?: () => void;
+}
+export interface BridgeServer {
+    readonly port: number;
+    readonly address: AddressInfo;
+    readonly descriptorPath: string;
+    readonly session: BridgeSession | null;
+    waitForAttachment(timeoutMs: number): Promise<BridgeSession>;
+    close(): Promise<void>;
+}
+export declare function startBridgeServer(options: StartBridgeServerOptions): Promise<BridgeServer>;
+//# sourceMappingURL=bridgeServer.d.ts.map

package/dist/bridgeServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeServer.d.ts","sourceRoot":"","sources":["../src/bridgeServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuJhG"}

package/dist/bridgeServer.js

@@ -0,0 +1,147 @@
+import { access, rm } from "node:fs/promises";
+import { createPairingDescriptor, GodotMcpException, } from "@godot-mcp/control-plane";
+import { WebSocketServer } from "ws";
+import { BridgeSession } from "./bridgeSession.js";
+import { performHandshake, rejectHandshake } from "./handshake.js";
+export async function startBridgeServer(options) {
+    const websocket = new WebSocketServer({
+        host: "127.0.0.1",
+        port: 0,
+        path: "/bridge",
+        maxPayload: 1_048_576,
+        perMessageDeflate: false,
+        clientTracking: true,
+    });
+    await new Promise((resolvePromise, reject) => {
+        websocket.once("listening", resolvePromise);
+        websocket.once("error", reject);
+    });
+    const address = websocket.address();
+    let pairing;
+    try {
+        pairing = await createPairingDescriptor(options.project, address.port, options.grants);
+    }
+    catch (error) {
+        await new Promise((resolvePromise) => websocket.close(() => resolvePromise()));
+        throw error;
+    }
+    let currentSession = null;
+    let pendingSocket = null;
+    let pairingConsumed = false;
+    let closePromise = null;
+    const attachmentWaiters = new Set();
+    const now = options.now ?? Date.now;
+    const audit = async (event, outcome, argumentsValue, errorCode) => {
+        await options.auditSink.append({
+            sessionId: currentSession?.sessionId ?? null,
+            projectId: options.project.projectId,
+            event,
+            outcome,
+            permissionTier: "observe",
+            arguments: argumentsValue,
+            errorCode,
+        });
+    };
+    websocket.on("connection", (socket, request) => {
+        socket.on("error", (error) => {
+            if (/max payload size exceeded/i.test(error.message)) {
+                void audit("transport.limit", "rejected", { limit: "maxPayload" }, "PAYLOAD_TOO_LARGE");
+            }
+        });
+        if (request.socket.remoteAddress !== "127.0.0.1" ||
+            pendingSocket !== null ||
+            currentSession !== null ||
+            pairingConsumed ||
+            closePromise !== null) {
+            void audit("pair.rejected", "rejected", { reason: "connection_state" }, "AUTHENTICATION_FAILED");
+            socket.close(1008, "connection rejected");
+            return;
+        }
+        pendingSocket = socket;
+        void (async () => {
+            try {
+                const handshake = await performHandshake(socket, {
+                    descriptor: pairing.descriptor,
+                    descriptorPath: pairing.path,
+                    addonManifestSha256: options.addonManifestSha256,
+                    timeoutMs: options.handshakeTimeoutMs ?? 5_000,
+                    now,
+                });
+                pairingConsumed = true;
+                const session = new BridgeSession(socket, handshake.key, handshake.verifier, {
+                    sessionId: handshake.sessionId,
+                    project: options.project,
+                    grants: options.grants,
+                    godotVersion: handshake.godotVersion,
+                    addonManifestSha256: options.addonManifestSha256,
+                });
+                currentSession = session;
+                pendingSocket = null;
+                options.onAttached?.(session);
+                session.onClose(() => {
+                    if (currentSession === session)
+                        currentSession = null;
+                    options.onDisconnected?.();
+                    void audit("session.closed", "success", {}, null);
+                });
+                session.onRejected((code) => {
+                    void audit("session.rejected", "rejected", {}, code);
+                });
+                await audit("pair.succeeded", "success", { godotVersion: handshake.godotVersion }, null);
+                for (const resolveWaiter of attachmentWaiters)
+                    resolveWaiter(session);
+                attachmentWaiters.clear();
+                session.send("pair.complete", { attached: true }, now() + 5_000);
+            }
+            catch (error) {
+                pendingSocket = null;
+                pairingConsumed ||= await access(pairing.path).then(() => false, () => true);
+                const code = error instanceof GodotMcpException ? error.code : "AUTHENTICATION_FAILED";
+                await audit("pair.rejected", "rejected", {}, code);
+                rejectHandshake(socket, error);
+            }
+        })();
+    });
+    return {
+        port: address.port,
+        address,
+        descriptorPath: pairing.path,
+        get session() {
+            return currentSession;
+        },
+        waitForAttachment(timeoutMs) {
+            if (currentSession)
+                return Promise.resolve(currentSession);
+            return new Promise((resolvePromise, reject) => {
+                const resolveAttachment = (session) => {
+                    clearTimeout(timeout);
+                    attachmentWaiters.delete(resolveAttachment);
+                    resolvePromise(session);
+                };
+                const timeout = setTimeout(() => {
+                    attachmentWaiters.delete(resolveAttachment);
+                    reject(new Error(`Godot addon did not attach within ${timeoutMs}ms`));
+                }, timeoutMs);
+                attachmentWaiters.add(resolveAttachment);
+            });
+        },
+        close() {
+            if (closePromise)
+                return closePromise;
+            closePromise = (async () => {
+                await rm(pairing.path, { force: true });
+                if (pendingSocket) {
+                    pendingSocket.terminate();
+                    pendingSocket = null;
+                }
+                if (currentSession)
+                    await currentSession.close();
+                for (const client of websocket.clients)
+                    client.terminate();
+                await new Promise((resolvePromise) => websocket.close(() => resolvePromise()));
+            })();
+            return closePromise;
+        },
+    };
+}
+//# sourceMappingURL=bridgeServer.js.map

package/dist/bridgeServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeServer.js","sourceRoot":"","sources":["../src/bridgeServer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAsBnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAiC;IACvE,MAAM,SAAS,GAAG,IAAI,eAAe,CAAC;QACpC,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,SAAS;QACf,UAAU,EAAE,SAAS;QACrB,iBAAiB,EAAE,KAAK;QACxB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IACH,MAAM,IAAI,OAAO,CAAO,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE;QACjD,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QAC5C,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,EAAiB,CAAC;IACnD,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,OAAO,CAAO,CAAC,cAAc,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;QACrF,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,cAAc,GAAyB,IAAI,CAAC;IAChD,IAAI,aAAa,GAAqB,IAAI,CAAC;IAC3C,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,IAAI,YAAY,GAAyB,IAAI,CAAC;IAC9C,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAoC,CAAC;IACtE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAEpC,MAAM,KAAK,GAAG,KAAK,EACjB,KAAa,EACb,OAAe,EACf,cAAuB,EACvB,SAAwB,EACT,EAAE;QACjB,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC;YAC7B,SAAS,EAAE,cAAc,EAAE,SAAS,IAAI,IAAI;YAC5C,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS;YACpC,KAAK;YACL,OAAO;YACP,cAAc,EAAE,SAAS;YACzB,SAAS,EAAE,cAAc;YACzB,SAAS;SACV,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;QAC7C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrD,KAAK,KAAK,CAAC,iBAAiB,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,mBAAmB,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IACE,OAAO,CAAC,MAAM,CAAC,aAAa,KAAK,WAAW;YAC5C,aAAa,KAAK,IAAI;YACtB,cAAc,KAAK,IAAI;YACvB,eAAe;YACf,YAAY,KAAK,IAAI,EACrB,CAAC;YACD,KAAK,KAAK,CACR,eAAe,EACf,UAAU,EACV,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAC9B,uBAAuB,CACxB,CAAC;YACF,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QACD,aAAa,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE;oBAC/C,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,cAAc,EAAE,OAAO,CAAC,IAAI;oBAC5B,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;oBAChD,SAAS,EAAE,OAAO,CAAC,kBAAkB,IAAI,KAAK;oBAC9C,GAAG;iBACJ,CAAC,CAAC;gBACH,eAAe,GAAG,IAAI,CAAC;gBACvB,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE;oBAC3E,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,YAAY,EAAE,SAAS,CAAC,YAAY;oBACpC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;iBACjD,CAAC,CAAC;gBACH,cAAc,GAAG,OAAO,CAAC;gBACzB,aAAa,GAAG,IAAI,CAAC;gBACrB,OAAO,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC9B,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;oBACnB,IAAI,cAAc,KAAK,OAAO;wBAAE,cAAc,GAAG,IAAI,CAAC;oBACtD,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;oBAC3B,KAAK,KAAK,CAAC,gBAAgB,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;gBACpD,CAAC,CAAC,CAAC;gBACH,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE;oBAC1B,KAAK,KAAK,CAAC,kBAAkB,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;gBACvD,CAAC,CAAC,CAAC;gBACH,MAAM,KAAK,CAAC,gBAAgB,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,IAAI,CAAC,CAAC;gBACzF,KAAK,MAAM,aAAa,IAAI,iBAAiB;oBAAE,aAAa,CAAC,OAAO,CAAC,CAAC;gBACtE,iBAAiB,CAAC,KAAK,EAAE,CAAC;gBAC1B,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;YACnE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,aAAa,GAAG,IAAI,CAAC;gBACrB,eAAe,KAAK,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CACjD,GAAG,EAAE,CAAC,KAAK,EACX,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;gBACF,MAAM,IAAI,GAAG,KAAK,YAAY,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,uBAAuB,CAAC;gBACvF,MAAM,KAAK,CAAC,eAAe,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;gBACnD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;QACP,cAAc,EAAE,OAAO,CAAC,IAAI;QAC5B,IAAI,OAAO;YACT,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,iBAAiB,CAAC,SAAiB;YACjC,IAAI,cAAc;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;YAC3D,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE;gBAC5C,MAAM,iBAAiB,GAAG,CAAC,OAAsB,EAAQ,EAAE;oBACzD,YAAY,CAAC,OAAO,CAAC,CAAC;oBACtB,iBAAiB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;oBAC5C,cAAc,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC,CAAC;gBACF,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC9B,iBAAiB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;oBAC5C,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,SAAS,IAAI,CAAC,CAAC,CAAC;gBACxE,CAAC,EAAE,SAAS,CAAC,CAAC;gBACd,iBAAiB,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK;YACH,IAAI,YAAY;gBAAE,OAAO,YAAY,CAAC;YACtC,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;gBACzB,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxC,IAAI,aAAa,EAAE,CAAC;oBAClB,aAAa,CAAC,SAAS,EAAE,CAAC;oBAC1B,aAAa,GAAG,IAAI,CAAC;gBACvB,CAAC;gBACD,IAAI,cAAc;oBAAE,MAAM,cAAc,CAAC,KAAK,EAAE,CAAC;gBACjD,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,OAAO;oBAAE,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC3D,MAAM,IAAI,OAAO,CAAO,CAAC,cAAc,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YACvF,CAAC,CAAC,EAAE,CAAC;YACL,OAAO,YAAY,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/bridgeSession.d.ts

@@ -0,0 +1,45 @@
+import { type EnvelopeVerifier, type SessionGrants } from "@godot-mcp/control-plane";
+import { type BridgeEnvelope, type ProjectIdentity } from "@godot-mcp/protocol";
+import { WebSocket } from "ws";
+export interface BridgeSessionInfo {
+    sessionId: string;
+    project: ProjectIdentity;
+    grants: SessionGrants;
+    godotVersion: string;
+    addonManifestSha256: string;
+}
+export interface BridgeRequestOptions {
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    correlationId?: string;
+}
+export interface BridgeCommandResult<T> {
+    requestId: string;
+    data: T;
+    binary?: Uint8Array;
+    binarySha256?: string;
+}
+export declare class BridgeSession {
+    private readonly socket;
+    private readonly key;
+    private readonly verifier;
+    readonly info: BridgeSessionInfo;
+    private readonly events;
+    private readonly pending;
+    private sendSequence;
+    constructor(socket: WebSocket, key: Uint8Array, verifier: EnvelopeVerifier, info: BridgeSessionInfo);
+    get sessionId(): string;
+    onEnvelope(listener: (envelope: BridgeEnvelope) => void): () => void;
+    onClose(listener: () => void): () => void;
+    onRejected(listener: (code: "AUTHENTICATION_FAILED" | "INVALID_REQUEST") => void): () => void;
+    send(method: string, params: unknown, deadlineUnixMs?: number): BridgeEnvelope;
+    request<T>(method: "editor.query" | "editor.capture" | "editor.mutate" | "project.operation" | "runtime.prepare" | "runtime.command" | "runtime.capture" | "runtime.cleanup", params: unknown, options?: BridgeRequestOptions): Promise<BridgeCommandResult<T>>;
+    close(code?: number, reason?: string): Promise<void>;
+    private readonly handleMessage;
+    private handleCommandChunk;
+    private handleCommandResult;
+    private rejectPending;
+    private finishPending;
+    private rejectAllPending;
+}
+//# sourceMappingURL=bridgeSession.d.ts.map

package/dist/bridgeSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeSession.d.ts","sourceRoot":"","sources":["../src/bridgeSession.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAgB,MAAM,IAAI,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAsCD,qBAAa,aAAa;IAMtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IARlC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,YAAY,CAAK;gBAGN,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,gBAAgB,EAClC,IAAI,EAAE,iBAAiB;IASlC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAKpE,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,UAAU,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,uBAAuB,GAAG,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI;IAK7F,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,SAAsB,GAAG,cAAc;IAc3F,OAAO,CAAC,CAAC,EACP,MAAM,EACF,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,EACrB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAyClC,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAsB5B;IAEF,OAAO,CAAC,kBAAkB;IAiC1B,OAAO,CAAC,mBAAmB;IAmE3B,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,gBAAgB;CAKzB"}

package/dist/bridgeSession.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { GodotMcpException, signEnvelope, } from "@godot-mcp/control-plane";
+import { BridgeCommandChunkSchema, BridgeCommandResultSchema, } from "@godot-mcp/protocol";
+import { WebSocket } from "ws";
+const MAX_PENDING_REQUESTS = 16;
+const MAX_CHUNK_BYTES = 512 * 1024;
+const DEFAULT_MAX_RESPONSE_BYTES = 512 * 1024;
+function bridgeError(code, message, retryable = false, correlationId = randomUUID(), facts = {}) {
+    const input = {
+        code,
+        message,
+        retryable,
+        correlationId,
+        partialEffects: facts.partialEffects ?? false,
+        rollback: facts.rollback ?? "not_needed",
+    };
+    if (facts.failedPhase !== undefined)
+        input.failedPhase = facts.failedPhase;
+    if (facts.safeRecovery !== undefined)
+        input.safeRecovery = facts.safeRecovery;
+    return new GodotMcpException(input);
+}
+export class BridgeSession {
+    socket;
+    key;
+    verifier;
+    info;
+    events = new EventEmitter();
+    pending = new Map();
+    sendSequence = 0;
+    constructor(socket, key, verifier, info) {
+        this.socket = socket;
+        this.key = key;
+        this.verifier = verifier;
+        this.info = info;
+        socket.on("message", this.handleMessage);
+        socket.once("close", () => {
+            this.rejectAllPending("NOT_ATTACHED", "Bridge session disconnected");
+            this.events.emit("close");
+        });
+    }
+    get sessionId() {
+        return this.info.sessionId;
+    }
+    onEnvelope(listener) {
+        this.events.on("envelope", listener);
+        return () => this.events.off("envelope", listener);
+    }
+    onClose(listener) {
+        this.events.on("close", listener);
+        return () => this.events.off("close", listener);
+    }
+    onRejected(listener) {
+        this.events.on("rejected", listener);
+        return () => this.events.off("rejected", listener);
+    }
+    send(method, params, deadlineUnixMs = Date.now() + 30_000) {
+        if (this.socket.readyState !== WebSocket.OPEN)
+            throw new Error("Bridge session is closed");
+        this.sendSequence += 1;
+        const envelope = signEnvelope(this.key, {
+            sessionId: this.sessionId,
+            sequence: this.sendSequence,
+            deadlineUnixMs,
+            method,
+            params,
+        });
+        this.socket.send(JSON.stringify(envelope));
+        return envelope;
+    }
+    request(method, params, options = {}) {
+        if (this.pending.size >= MAX_PENDING_REQUESTS) {
+            return Promise.reject(bridgeError("CONFLICT", "Bridge request queue is full"));
+        }
+        const requestId = options.correlationId ?? randomUUID();
+        const timeoutMs = Math.min(Math.max(options.timeoutMs ?? 30_000, 1), 60_000);
+        const maxResponseBytes = Math.min(Math.max(options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES, 1), 8 * 1024 * 1024);
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(requestId);
+                reject(bridgeError("TIMEOUT", `Bridge request timed out after ${timeoutMs}ms`, true, requestId));
+            }, timeoutMs);
+            this.pending.set(requestId, {
+                resolve: resolve,
+                reject,
+                timeout,
+                maxResponseBytes,
+                chunks: [],
+                nextChunkIndex: 0,
+                receivedBytes: 0,
+            });
+            try {
+                this.send(method, { requestId, arguments: params }, Date.now() + timeoutMs);
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                this.pending.delete(requestId);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    close(code = 1001, reason = "server closing") {
+        if (this.socket.readyState === WebSocket.CLOSED)
+            return Promise.resolve();
+        return new Promise((resolvePromise) => {
+            const timeout = setTimeout(() => this.socket.terminate(), 1_000);
+            this.socket.once("close", () => {
+                clearTimeout(timeout);
+                resolvePromise();
+            });
+            this.socket.close(code, reason);
+        });
+    }
+    handleMessage = (data, isBinary) => {
+        if (isBinary) {
+            this.events.emit("rejected", "INVALID_REQUEST");
+            this.socket.close(1008, "binary frames are not allowed");
+            return;
+        }
+        try {
+            const envelope = this.verifier.verify(JSON.parse(data.toString()));
+            if (envelope.sessionId !== this.sessionId)
+                throw new Error("Session ID mismatch");
+            if (envelope.method === "command.chunk") {
+                this.handleCommandChunk(envelope.params);
+                return;
+            }
+            if (envelope.method === "command.result") {
+                this.handleCommandResult(envelope.params);
+                return;
+            }
+            this.events.emit("envelope", envelope);
+        }
+        catch {
+            this.events.emit("rejected", "AUTHENTICATION_FAILED");
+            this.socket.close(1008, "invalid signed envelope");
+        }
+    };
+    handleCommandChunk(input) {
+        let parsed;
+        try {
+            parsed = BridgeCommandChunkSchema.parse(input);
+        }
+        catch {
+            const requestId = typeof input === "object" && input !== null && "requestId" in input
+                ? String(input.requestId)
+                : undefined;
+            if (requestId)
+                this.rejectPending(requestId, "INVALID_REQUEST", "Malformed command chunk");
+            else
+                this.socket.close(1008, "malformed command chunk");
+            return;
+        }
+        const pending = this.pending.get(parsed.requestId);
+        if (!pending)
+            return;
+        const bytes = Buffer.from(parsed.data, "base64url");
+        if (parsed.index !== pending.nextChunkIndex ||
+            bytes.length > MAX_CHUNK_BYTES ||
+            (pending.totalChunks !== undefined && pending.totalChunks !== parsed.total) ||
+            (pending.binarySha256 !== undefined && pending.binarySha256 !== parsed.sha256) ||
+            pending.receivedBytes + bytes.length > pending.maxResponseBytes) {
+            this.rejectPending(parsed.requestId, "INVALID_REQUEST", "Invalid command chunk stream");
+            return;
+        }
+        pending.totalChunks = parsed.total;
+        pending.binarySha256 = parsed.sha256;
+        pending.chunks.push(bytes);
+        pending.receivedBytes += bytes.length;
+        pending.nextChunkIndex += 1;
+    }
+    handleCommandResult(input) {
+        let parsed;
+        try {
+            parsed = BridgeCommandResultSchema.parse(input);
+        }
+        catch {
+            const requestId = typeof input === "object" && input !== null && "requestId" in input
+                ? String(input.requestId)
+                : undefined;
+            if (requestId)
+                this.rejectPending(requestId, "INVALID_REQUEST", "Malformed command result");
+            else
+                this.socket.close(1008, "malformed command result");
+            return;
+        }
+        const pending = this.pending.get(parsed.requestId);
+        if (!pending)
+            return;
+        if (!parsed.ok) {
+            const error = parsed.error;
+            const facts = error === undefined ? {} : {
+                failedPhase: error.failedPhase,
+                partialEffects: error.partialEffects,
+                rollback: error.rollback,
+                safeRecovery: error.safeRecovery,
+            };
+            this.finishPending(parsed.requestId, undefined, bridgeError(error?.code ?? "GODOT_RUNTIME_ERROR", error?.message ?? "Godot command failed", error?.retryable ?? false, parsed.requestId, facts));
+            return;
+        }
+        let binary;
+        if (parsed.binary) {
+            binary = Buffer.concat(pending.chunks);
+            const digest = createHash("sha256").update(binary).digest("hex");
+            if (pending.nextChunkIndex !== parsed.binary.chunks ||
+                pending.totalChunks !== parsed.binary.chunks ||
+                pending.binarySha256 !== parsed.binary.sha256 ||
+                binary.length !== parsed.binary.size ||
+                digest !== parsed.binary.sha256) {
+                this.rejectPending(parsed.requestId, "INVALID_REQUEST", "Command binary verification failed");
+                return;
+            }
+        }
+        else if (pending.chunks.length > 0) {
+            this.rejectPending(parsed.requestId, "INVALID_REQUEST", "Command result omitted binary metadata");
+            return;
+        }
+        const value = {
+            requestId: parsed.requestId,
+            data: parsed.data,
+        };
+        if (binary !== undefined && parsed.binary !== undefined) {
+            value.binary = binary;
+            value.binarySha256 = parsed.binary.sha256;
+        }
+        this.finishPending(parsed.requestId, value);
+    }
+    rejectPending(requestId, code, message) {
+        this.finishPending(requestId, undefined, bridgeError(code, message, false, requestId));
+    }
+    finishPending(requestId, value, error) {
+        const pending = this.pending.get(requestId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeout);
+        this.pending.delete(requestId);
+        pending.chunks.length = 0;
+        if (error)
+            pending.reject(error);
+        else if (value)
+            pending.resolve(value);
+    }
+    rejectAllPending(code, message) {
+        for (const requestId of [...this.pending.keys()]) {
+            this.rejectPending(requestId, code, message);
+        }
+    }
+}
+//# sourceMappingURL=bridgeSession.js.map

package/dist/bridgeSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridgeSession.js","sourceRoot":"","sources":["../src/bridgeSession.ts"],"names":[],"mappings":"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"}

package/dist/handshake.d.ts

@@ -0,0 +1,29 @@
+import { EnvelopeVerifier, type SessionDescriptor } from "@godot-mcp/control-plane";
+import { WebSocket } from "ws";
+export interface PairRequest {
+    method: "pair";
+    token: string;
+    sessionNonce: string;
+    protocolVersion: string;
+    productVersion: string;
+    project: SessionDescriptor["project"];
+    addonManifestSha256: string;
+    godotVersion: string;
+}
+export interface HandshakeOptions {
+    descriptor: SessionDescriptor;
+    descriptorPath: string;
+    addonManifestSha256: string;
+    timeoutMs: number;
+    now: () => number;
+}
+export interface HandshakeResult {
+    sessionId: string;
+    serverNonce: string;
+    godotVersion: string;
+    verifier: EnvelopeVerifier;
+    key: Buffer;
+}
+export declare function performHandshake(socket: WebSocket, options: HandshakeOptions): Promise<HandshakeResult>;
+export declare function rejectHandshake(socket: WebSocket, error: unknown): void;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAGhB,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,SAAS,EAAgB,MAAM,IAAI,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACtC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAsFD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAgE1B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAYvE"}

package/dist/handshake.js

@@ -0,0 +1,145 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { EnvelopeVerifier, GodotMcpException, deriveSessionKey, } from "@godot-mcp/control-plane";
+import { BRIDGE_PROTOCOL_VERSION, PRODUCT_VERSION, ProjectIdentitySchema, canonicalJson, } from "@godot-mcp/protocol";
+import { WebSocket } from "ws";
+function authenticationFailed(message) {
+    return protocolFailure("AUTHENTICATION_FAILED", message);
+}
+function protocolFailure(code, message) {
+    return new GodotMcpException({
+        code,
+        message,
+        retryable: false,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+function sameSecret(left, right) {
+    const leftBytes = Buffer.from(left, "utf8");
+    const rightBytes = Buffer.from(right, "utf8");
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function nextTextMessage(socket, timeoutMs) {
+    return new Promise((resolvePromise, reject) => {
+        const cleanup = () => {
+            clearTimeout(timeout);
+            socket.off("message", onMessage);
+            socket.off("close", onClose);
+            socket.off("error", onError);
+        };
+        const onMessage = (data, isBinary) => {
+            cleanup();
+            if (isBinary)
+                reject(authenticationFailed("Binary handshake frames are not allowed"));
+            else
+                resolvePromise(data.toString());
+        };
+        const onClose = () => {
+            cleanup();
+            reject(authenticationFailed("Pairing connection closed before authentication"));
+        };
+        const onError = () => {
+            cleanup();
+            reject(authenticationFailed("Pairing transport failed"));
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(authenticationFailed("Pairing handshake timed out"));
+        }, timeoutMs);
+        socket.on("message", onMessage);
+        socket.once("close", onClose);
+        socket.once("error", onError);
+    });
+}
+function parsePairRequest(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw protocolFailure("INVALID_REQUEST", "Pairing request is not valid JSON");
+    }
+    if (typeof value !== "object" || value === null) {
+        throw protocolFailure("INVALID_REQUEST", "Pairing request must be an object");
+    }
+    const request = value;
+    if (request.method !== "pair" ||
+        typeof request.token !== "string" ||
+        typeof request.sessionNonce !== "string" ||
+        typeof request.protocolVersion !== "string" ||
+        typeof request.productVersion !== "string" ||
+        !ProjectIdentitySchema.safeParse(request.project).success ||
+        typeof request.addonManifestSha256 !== "string" ||
+        typeof request.godotVersion !== "string") {
+        throw protocolFailure("INVALID_REQUEST", "The only allowed unauthenticated message is a complete pair request");
+    }
+    return request;
+}
+export async function performHandshake(socket, options) {
+    const request = parsePairRequest(await nextTextMessage(socket, options.timeoutMs));
+    const descriptor = options.descriptor;
+    if (descriptor.expiresAtUnixMs < options.now())
+        throw authenticationFailed("Pairing descriptor expired");
+    if (!sameSecret(request.token, descriptor.token))
+        throw authenticationFailed("Pairing token is invalid");
+    if (!sameSecret(request.sessionNonce, descriptor.sessionNonce)) {
+        throw authenticationFailed("Pairing session nonce is invalid");
+    }
+    if (request.protocolVersion !== BRIDGE_PROTOCOL_VERSION ||
+        request.productVersion !== PRODUCT_VERSION) {
+        throw authenticationFailed("Pairing protocol or product version does not match");
+    }
+    if (canonicalJson(request.project) !== canonicalJson(descriptor.project)) {
+        if (request.project.projectId === descriptor.project.projectId &&
+            request.project.rootRealPath === descriptor.project.rootRealPath &&
+            request.project.projectConfigSha256 !== descriptor.project.projectConfigSha256) {
+            throw protocolFailure("PROJECT_CHANGED", "Pairing project contents changed");
+        }
+        throw authenticationFailed("Pairing project identity does not match");
+    }
+    if (request.addonManifestSha256 !== options.addonManifestSha256) {
+        throw authenticationFailed("Pairing addon manifest does not match");
+    }
+    if (!request.godotVersion.startsWith("4.7.stable")) {
+        throw authenticationFailed("Godot 4.7.stable is required");
+    }
+    await rm(options.descriptorPath, { force: true });
+    const sessionId = `session_${randomUUID()}`;
+    const serverNonce = randomBytes(32).toString("base64url");
+    const serverProof = createHmac("sha256", Buffer.from(descriptor.token, "base64url"))
+        .update(`godot-mcp:server-proof:v1\n${sessionId}\n${serverNonce}`)
+        .digest("hex");
+    const key = deriveSessionKey(descriptor.token, descriptor.sessionNonce, serverNonce);
+    socket.send(JSON.stringify({
+        method: "pair_ok",
+        sessionId,
+        serverNonce,
+        grants: descriptor.grants,
+        serverProof,
+    }));
+    const verifier = new EnvelopeVerifier(key, { now: options.now });
+    const acknowledgment = verifier.verify(JSON.parse(await nextTextMessage(socket, options.timeoutMs)));
+    const params = acknowledgment.params;
+    if (acknowledgment.sessionId !== sessionId ||
+        acknowledgment.method !== "pair.ack" ||
+        typeof params !== "object" ||
+        params === null ||
+        typeof params.serverProof !== "string" ||
+        !sameSecret(params.serverProof, serverProof)) {
+        throw authenticationFailed("Signed pairing acknowledgment is invalid");
+    }
+    return { sessionId, serverNonce, godotVersion: request.godotVersion, verifier, key };
+}
+export function rejectHandshake(socket, error) {
+    if (socket.readyState === WebSocket.OPEN) {
+        const code = error instanceof GodotMcpException ? error.code : "AUTHENTICATION_FAILED";
+        socket.send(JSON.stringify({
+            method: "pair_rejected",
+            code,
+            message: error instanceof Error ? error.message : "Pairing rejected",
+        }), () => socket.close(1008, "authentication failed"));
+    }
+}
+//# sourceMappingURL=handshake.js.map

package/dist/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { startBridgeServer, type BridgeServer, type StartBridgeServerOptions, } from "./bridgeServer.js";
+export { BridgeSession, type BridgeCommandResult, type BridgeRequestOptions, type BridgeSessionInfo, } from "./bridgeSession.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { startBridgeServer, } from "./bridgeServer.js";
+export { BridgeSession, } from "./bridgeSession.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAGlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,GAId,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,11 +1,31 @@
 {
   "name": "@godot-mcp/bridge-client",
-  "version": "0.0.0",
-  "description": "Namespace bootstrap for the Godot MCP bridge-client package.",
+  "version": "0.1.0",
   "type": "module",
-  "main": "index.js",
-  "files": ["index.js", "README.md"],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@godot-mcp/control-plane": "0.1.0",
+    "@godot-mcp/protocol": "0.1.0",
+    "ws": "8.21.0"
+  },
   "license": "MIT",
-  "repository": "git+https://github.com/k0nkupa/godot-mcp.git",
-  "publishConfig": { "access": "public", "tag": "bootstrap" }
+  "engines": {
+    "node": ">=22 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0nkupa/godot-mcp.git"
+  }
 }

package/index.js

@@ -1 +0,0 @@
-export {};