@godot-mcp/control-plane 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/control-plane
+# 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/audit/jsonlAuditSink.d.ts

@@ -0,0 +1,33 @@
+import { type AuditRecord, type PermissionTier } from "@godot-mcp/protocol";
+export interface AuditInput {
+    auditId?: string;
+    correlationId?: string;
+    sessionId: string | null;
+    projectId: string;
+    event: string;
+    outcome: string;
+    permissionTier: PermissionTier;
+    protocolVersion?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    arguments: unknown;
+    errorCode: string | null;
+    evidence?: string[];
+    targetIdentities?: unknown[];
+    preconditions?: unknown[];
+    changes?: unknown[];
+    idempotencyKeySha256?: string | null;
+    partialEffects?: boolean;
+    rollback?: AuditRecord["rollback"];
+}
+export interface AuditSink {
+    append(input: AuditInput): Promise<AuditRecord>;
+}
+export declare class JsonlAuditSink implements AuditSink {
+    private readonly path;
+    private tail;
+    static forProject(projectRoot: string): JsonlAuditSink;
+    constructor(path: string);
+    append(input: AuditInput): Promise<AuditRecord>;
+}
+//# sourceMappingURL=jsonlAuditSink.d.ts.map

package/dist/audit/jsonlAuditSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonlAuditSink.d.ts","sourceRoot":"","sources":["../../src/audit/jsonlAuditSink.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAI7B,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjD;AA4BD,qBAAa,cAAe,YAAW,SAAS;IAOlC,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,IAAI,CAAuC;IAEnD,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc;gBAIzB,IAAI,EAAE,MAAM;IAEzC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;CAehD"}

package/dist/audit/jsonlAuditSink.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AuditRecordSchema, BRIDGE_PROTOCOL_VERSION, } from "@godot-mcp/protocol";
+import { redactAuditValue } from "./redact.js";
+function buildAuditRecord(input) {
+    const timestamp = new Date().toISOString();
+    return AuditRecordSchema.parse({
+        schemaVersion: 2,
+        auditId: input.auditId ?? randomUUID(),
+        correlationId: input.correlationId ?? randomUUID(),
+        sessionId: input.sessionId,
+        projectId: input.projectId,
+        event: input.event,
+        outcome: input.outcome,
+        permissionTier: input.permissionTier,
+        protocolVersion: input.protocolVersion ?? BRIDGE_PROTOCOL_VERSION,
+        startedAt: input.startedAt ?? timestamp,
+        finishedAt: input.finishedAt ?? timestamp,
+        arguments: redactAuditValue(input.arguments),
+        errorCode: input.errorCode,
+        evidence: input.evidence ?? [],
+        targetIdentities: input.targetIdentities ?? [],
+        preconditions: input.preconditions ?? [],
+        changes: input.changes ?? [],
+        idempotencyKeySha256: input.idempotencyKeySha256 ?? null,
+        partialEffects: input.partialEffects ?? false,
+        rollback: input.rollback ?? "not_needed",
+    });
+}
+export class JsonlAuditSink {
+    path;
+    tail = Promise.resolve();
+    static forProject(projectRoot) {
+        return new JsonlAuditSink(join(projectRoot, ".godot/evidence/godot-mcp/audit.jsonl"));
+    }
+    constructor(path) {
+        this.path = path;
+    }
+    append(input) {
+        const record = buildAuditRecord(input);
+        const write = this.tail.then(async () => {
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+            const handle = await open(this.path, "a", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            return record;
+        });
+        this.tail = write.catch(() => undefined);
+        return write;
+    }
+}
+//# sourceMappingURL=jsonlAuditSink.js.map

package/dist/audit/jsonlAuditSink.js.map

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

package/dist/audit/redact.d.ts

@@ -0,0 +1,2 @@
+export declare function redactAuditValue(value: unknown): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/audit/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/audit/redact.ts"],"names":[],"mappings":"AAmCA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAExD"}

package/dist/audit/redact.js

@@ -0,0 +1,44 @@
+const SECRET_KEY = /token|secret|password|authorization|cookie|private[_-]?key/i;
+function binaryLength(value) {
+    if (Buffer.isBuffer(value))
+        return value.byteLength;
+    if (value instanceof ArrayBuffer)
+        return value.byteLength;
+    if (ArrayBuffer.isView(value))
+        return value.byteLength;
+    return undefined;
+}
+function redact(value, ancestors) {
+    const bytes = binaryLength(value);
+    if (bytes !== undefined)
+        return `[BINARY ${bytes} bytes]`;
+    if (value === null || ["string", "number", "boolean"].includes(typeof value))
+        return value;
+    if (value === undefined)
+        return "[UNDEFINED]";
+    if (["bigint", "function", "symbol"].includes(typeof value)) {
+        return `[${(typeof value).toUpperCase()}]`;
+    }
+    const objectValue = value;
+    if (ancestors.has(objectValue))
+        return "[CIRCULAR]";
+    ancestors.add(objectValue);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => redact(item, ancestors));
+        if (value instanceof Date)
+            return value.toISOString();
+        const output = {};
+        for (const [key, item] of Object.entries(value)) {
+            output[key] = SECRET_KEY.test(key) ? "[REDACTED]" : redact(item, ancestors);
+        }
+        return output;
+    }
+    finally {
+        ancestors.delete(objectValue);
+    }
+}
+export function redactAuditValue(value) {
+    return redact(value, new Set());
+}
+//# sourceMappingURL=redact.js.map

package/dist/audit/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/audit/redact.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,6DAA6D,CAAC;AAEjF,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC;IACpD,IAAI,KAAK,YAAY,WAAW;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC;IAC1D,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC;IACvD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,MAAM,CAAC,KAAc,EAAE,SAAsB;IACpD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,KAAK,SAAS,CAAC;IAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAC9C,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC;IAC7C,CAAC;IAED,MAAM,WAAW,GAAG,KAAe,CAAC;IACpC,IAAI,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC;QAAE,OAAO,YAAY,CAAC;IACpD,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3B,IAAI,CAAC;QACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAC9E,IAAI,KAAK,YAAY,IAAI;YAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;QAEtD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC3E,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;AAC1C,CAAC"}

package/dist/auth/pairingDescriptor.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { SessionGrants } from "../policy/capabilities.js";
+export declare const PairingDescriptorSchema: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<"1.0">;
+    productVersion: z.ZodLiteral<"0.1.0">;
+    project: z.ZodObject<{
+        projectId: z.ZodUUID;
+        rootRealPath: z.ZodString;
+        projectConfigSha256: z.ZodString;
+        godotVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    port: z.ZodNumber;
+    sessionNonce: z.ZodString;
+    token: z.ZodString;
+    grants: z.ZodObject<{
+        tiers: z.ZodArray<z.ZodEnum<{
+            observe: "observe";
+            runtime_control: "runtime_control";
+            project_mutate: "project_mutate";
+            project_operate: "project_operate";
+            unsafe_fixture: "unsafe_fixture";
+        }>>;
+        packs: z.ZodArray<z.ZodEnum<{
+            input: "input";
+            unsafe: "unsafe";
+            debug: "debug";
+            core: "core";
+            runtime: "runtime";
+            editor: "editor";
+            visual: "visual";
+            project: "project";
+        }>>;
+    }, z.core.$strip>;
+    createdAtUnixMs: z.ZodNumber;
+    expiresAtUnixMs: z.ZodNumber;
+}, z.core.$strip>;
+export type SessionDescriptor = z.infer<typeof PairingDescriptorSchema>;
+export interface PairingMaterial {
+    path: string;
+    descriptor: SessionDescriptor;
+}
+export declare function createPairingDescriptor(project: SessionDescriptor["project"], port: number, grants: SessionGrants): Promise<PairingMaterial>;
+export declare function consumePairingDescriptor(path: string): Promise<SessionDescriptor>;
+//# sourceMappingURL=pairingDescriptor.d.ts.map

package/dist/auth/pairingDescriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingDescriptor.d.ts","sourceRoot":"","sources":["../../src/auth/pairingDescriptor.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG/D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAalC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAaD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BvF"}

package/dist/auth/pairingDescriptor.js

@@ -0,0 +1,91 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { BRIDGE_PROTOCOL_VERSION, CapabilityPackSchema, PermissionTierSchema, PRODUCT_VERSION, ProjectIdentitySchema, } from "@godot-mcp/protocol";
+import { z } from "zod";
+import { GodotMcpException } from "../errors.js";
+import { ensureRuntimeDirectory } from "./runtimeDirectory.js";
+export const PairingDescriptorSchema = z.object({
+    protocolVersion: z.literal(BRIDGE_PROTOCOL_VERSION),
+    productVersion: z.literal(PRODUCT_VERSION),
+    project: ProjectIdentitySchema,
+    port: z.number().int().min(1).max(65_535),
+    sessionNonce: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+    token: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+    grants: z.object({
+        tiers: z.array(PermissionTierSchema),
+        packs: z.array(CapabilityPackSchema),
+    }),
+    createdAtUnixMs: z.number().int().positive(),
+    expiresAtUnixMs: z.number().int().positive(),
+});
+function authenticationFailed(message) {
+    return new GodotMcpException({
+        code: "AUTHENTICATION_FAILED",
+        message,
+        retryable: false,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+export async function createPairingDescriptor(project, port, grants) {
+    const runtimeDirectory = await ensureRuntimeDirectory();
+    const now = Date.now();
+    const descriptor = PairingDescriptorSchema.parse({
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        productVersion: PRODUCT_VERSION,
+        project,
+        port,
+        sessionNonce: randomBytes(32).toString("base64url"),
+        token: randomBytes(32).toString("base64url"),
+        grants,
+        createdAtUnixMs: now,
+        expiresAtUnixMs: now + 60_000,
+    });
+    const path = join(runtimeDirectory, `pair-${project.projectId}.json`);
+    try {
+        await writeFile(path, `${JSON.stringify(descriptor)}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw authenticationFailed("A pairing descriptor already exists for this project");
+        }
+        throw error;
+    }
+    return { path, descriptor };
+}
+export async function consumePairingDescriptor(path) {
+    const consumingPath = join(dirname(path), `.consuming-${basename(path)}-${randomUUID()}`);
+    try {
+        await rename(path, consumingPath);
+    }
+    catch {
+        throw authenticationFailed("Pairing descriptor is missing or already consumed");
+    }
+    try {
+        const metadata = await lstat(consumingPath);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
+            throw authenticationFailed("Pairing descriptor permissions are invalid");
+        }
+        let descriptor;
+        try {
+            descriptor = PairingDescriptorSchema.parse(JSON.parse(await readFile(consumingPath, "utf8")));
+        }
+        catch {
+            throw authenticationFailed("Pairing descriptor is malformed");
+        }
+        if (descriptor.expiresAtUnixMs < Date.now()) {
+            throw authenticationFailed("Pairing descriptor has expired");
+        }
+        return descriptor;
+    }
+    finally {
+        await rm(consumingPath, { force: true });
+    }
+}
+//# sourceMappingURL=pairingDescriptor.js.map

package/dist/auth/pairingDescriptor.js.map

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

package/dist/auth/runtimeDirectory.d.ts

@@ -0,0 +1,3 @@
+export declare function runtimeDirectoryPath(environment?: NodeJS.ProcessEnv): string;
+export declare function ensureRuntimeDirectory(environment?: NodeJS.ProcessEnv): Promise<string>;
+//# sourceMappingURL=runtimeDirectory.d.ts.map

package/dist/auth/runtimeDirectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeDirectory.d.ts","sourceRoot":"","sources":["../../src/auth/runtimeDirectory.ts"],"names":[],"mappings":"AAiBA,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEzF;AAED,wBAAsB,sBAAsB,CAC1C,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/auth/runtimeDirectory.js

@@ -0,0 +1,30 @@
+import { lstat, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { GodotMcpException } from "../errors.js";
+function invalidRuntimeDirectory(message) {
+    return new GodotMcpException({
+        code: "AUTHENTICATION_FAILED",
+        message,
+        retryable: false,
+        correlationId: "runtime-directory",
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+export function runtimeDirectoryPath(environment = process.env) {
+    return join(environment.XDG_RUNTIME_DIR || tmpdir(), "godot-mcp");
+}
+export async function ensureRuntimeDirectory(environment = process.env) {
+    const path = runtimeDirectoryPath(environment);
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw invalidRuntimeDirectory("Godot MCP runtime path must be a private regular directory");
+    }
+    if ((metadata.mode & 0o077) !== 0) {
+        throw invalidRuntimeDirectory("Godot MCP runtime directory is accessible by other users");
+    }
+    return path;
+}
+//# sourceMappingURL=runtimeDirectory.js.map

package/dist/auth/runtimeDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeDirectory.js","sourceRoot":"","sources":["../../src/auth/runtimeDirectory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,SAAS,uBAAuB,CAAC,OAAe;IAC9C,OAAO,IAAI,iBAAiB,CAAC;QAC3B,IAAI,EAAE,uBAAuB;QAC7B,OAAO;QACP,SAAS,EAAE,KAAK;QAChB,aAAa,EAAE,mBAAmB;QAClC,cAAc,EAAE,KAAK;QACrB,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,cAAiC,OAAO,CAAC,GAAG;IAC/E,OAAO,IAAI,CAAC,WAAW,CAAC,eAAe,IAAI,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,cAAiC,OAAO,CAAC,GAAG;IAE5C,MAAM,IAAI,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;QACzD,MAAM,uBAAuB,CAAC,4DAA4D,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,uBAAuB,CAAC,0DAA0D,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/auth/sessionCrypto.d.ts

@@ -0,0 +1,18 @@
+import { type BridgeEnvelope } from "@godot-mcp/protocol";
+export type UnsignedBridgeEnvelope = Omit<BridgeEnvelope, "mac">;
+export interface EnvelopeVerificationOptions {
+    now?: () => number;
+    maxFutureMs?: number;
+}
+export declare function deriveSessionKey(token: string, sessionNonce: string, serverNonce: string): Buffer;
+export declare function envelopeSigningText(envelope: UnsignedBridgeEnvelope): string;
+export declare function signEnvelope(key: Uint8Array, envelope: UnsignedBridgeEnvelope): BridgeEnvelope;
+export declare function verifyEnvelope(key: Uint8Array, input: unknown, options?: EnvelopeVerificationOptions): BridgeEnvelope;
+export declare class EnvelopeVerifier {
+    private readonly key;
+    private readonly options;
+    private lastSequence;
+    constructor(key: Uint8Array, options?: EnvelopeVerificationOptions);
+    verify(input: unknown): BridgeEnvelope;
+}
+//# sourceMappingURL=sessionCrypto.d.ts.map

package/dist/auth/sessionCrypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionCrypto.d.ts","sourceRoot":"","sources":["../../src/auth/sessionCrypto.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAI7B,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuDD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,CAMR;AAYD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAE5E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,sBAAsB,GAAG,cAAc,CAI9F;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,2BAAgC,GACxC,cAAc,CAqBhB;AAED,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,YAAY,CAAK;gBAGN,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,2BAAgC;IAG5D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc;CAQvC"}

package/dist/auth/sessionCrypto.js

@@ -0,0 +1,118 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { BridgeEnvelopeSchema, canonicalFloat64Le, canonicalJson, decodeFloat64Le, } from "@godot-mcp/protocol";
+import { GodotMcpException } from "../errors.js";
+function authenticationFailed(message) {
+    return new GodotMcpException({
+        code: "AUTHENTICATION_FAILED",
+        message,
+        retryable: false,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+const FLOAT_WIRE_KEY = "$godotMcpFloat64Le";
+function isFloatWireShape(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) &&
+        Object.keys(value).length === 1 && FLOAT_WIRE_KEY in value;
+}
+function isFloatWireValue(value) {
+    return isFloatWireShape(value) && typeof value[FLOAT_WIRE_KEY] === "string" &&
+        /^[a-f0-9]{16}$/.test(value[FLOAT_WIRE_KEY]);
+}
+function encodeFloatParams(value, allowWireValues = false) {
+    if (typeof value === "number") {
+        if (Number.isFinite(value) && !Number.isSafeInteger(value)) {
+            return { [FLOAT_WIRE_KEY]: canonicalFloat64Le(value) };
+        }
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => encodeFloatParams(entry, allowWireValues));
+    if (value !== null && typeof value === "object") {
+        if (isFloatWireShape(value)) {
+            if (!allowWireValues)
+                throw new TypeError("Bridge parameters contain a reserved float wire value");
+            if (!isFloatWireValue(value))
+                throw new TypeError("Bridge parameters contain a malformed float wire value");
+            return value;
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, encodeFloatParams(entry, allowWireValues)]));
+    }
+    return value;
+}
+function decodeFloatParams(value) {
+    if (isFloatWireValue(value))
+        return decodeFloat64Le(value[FLOAT_WIRE_KEY]);
+    if (Array.isArray(value))
+        return value.map(decodeFloatParams);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, decodeFloatParams(entry)]));
+    }
+    return value;
+}
+export function deriveSessionKey(token, sessionNonce, serverNonce) {
+    const tokenBytes = Buffer.from(token, "base64url");
+    if (tokenBytes.length !== 32)
+        throw authenticationFailed("Pairing token length is invalid");
+    return createHmac("sha256", tokenBytes)
+        .update(`godot-mcp:v1\n${sessionNonce}\n${serverNonce}`, "utf8")
+        .digest();
+}
+function signingText(envelope, allowWireValues) {
+    return [
+        envelope.sessionId,
+        String(envelope.sequence),
+        String(envelope.deadlineUnixMs),
+        envelope.method,
+        canonicalJson(encodeFloatParams(envelope.params, allowWireValues)),
+    ].join("\n");
+}
+export function envelopeSigningText(envelope) {
+    return signingText(envelope, false);
+}
+export function signEnvelope(key, envelope) {
+    const wireEnvelope = { ...envelope, params: encodeFloatParams(envelope.params) };
+    const mac = createHmac("sha256", key).update(signingText(wireEnvelope, true), "utf8").digest("hex");
+    return BridgeEnvelopeSchema.parse({ ...wireEnvelope, mac });
+}
+export function verifyEnvelope(key, input, options = {}) {
+    let envelope;
+    try {
+        envelope = BridgeEnvelopeSchema.parse(input);
+    }
+    catch {
+        throw authenticationFailed("Signed envelope is malformed");
+    }
+    const expected = createHmac("sha256", key)
+        .update(signingText(envelope, true), "utf8")
+        .digest();
+    const received = Buffer.from(envelope.mac, "hex");
+    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
+        throw authenticationFailed("Signed envelope MAC is invalid");
+    }
+    const now = (options.now ?? Date.now)();
+    const maxFutureMs = options.maxFutureMs ?? 60_000;
+    if (envelope.deadlineUnixMs < now || envelope.deadlineUnixMs - now > maxFutureMs) {
+        throw authenticationFailed("Signed envelope deadline is invalid");
+    }
+    return BridgeEnvelopeSchema.parse({ ...envelope, params: decodeFloatParams(envelope.params) });
+}
+export class EnvelopeVerifier {
+    key;
+    options;
+    lastSequence = 0;
+    constructor(key, options = {}) {
+        this.key = key;
+        this.options = options;
+    }
+    verify(input) {
+        const envelope = verifyEnvelope(this.key, input, this.options);
+        if (envelope.sequence <= this.lastSequence) {
+            throw authenticationFailed("Signed envelope sequence was replayed or reordered");
+        }
+        this.lastSequence = envelope.sequence;
+        return envelope;
+    }
+}
+//# sourceMappingURL=sessionCrypto.js.map

package/dist/auth/sessionCrypto.js.map

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