@sxl-studio/bridge 1.2.0 → 1.3.2

package/README.md

@@ -5,86 +5,93 @@ Node.js process that connects **Cursor (or any MCP client)** and **HTTP clients*
 ## What it does
 
 1. **WebSocket** — plugin UI iframe connects here and forwards `remote-command` / results.
-2. **MCP (stdio)** — Cursor Agent calls tools (`export_variables`, `inspect_selection`, …); each tool maps to one plugin command.
-3. **HTTP** — same command queue for scripts and other tools.
+2. **MCP (Streamable HTTP + stdio)** — Cursor / Claude Desktop / any MCP client calls typed tools (`export_variables`, `export_composition_json`, `get_codegen`, `compose_from_url`, …); each tool maps to one plugin command or an orchestration that chains several.
+3. **HTTP** — same command queue for scripts, CI, curl, idempotency-safe retries, audit log.
 
-Official [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/) does not run your plugin code. Use **both**: Figma MCP for file/design context; **this bridge** for SXL-specific operations (compositions, token export, mappings, etc.).
+Official [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/) does not run your plugin code. Use **both**: Figma MCP for file/design context; **this bridge** for SXL-specific operations (compositions, token export, mappings, Git, Dev Mode codegen).
 
 ### Figma MCP vs SXL Bridge (product split)
 
-Figma documents the hosted and desktop MCP in the Help Center: [Guide to the Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server). **Remote** MCP is the default in their guidance; some client features (for example write-to-canvas flows in their compatibility matrix) are oriented toward **remote** MCP rather than a local-only server.
-
 | Need | Use |
 |------|-----|
-| Native file operations where Figma’s MCP tools are enough (context, many canvas writes, variables in supported flows) | **Official Figma MCP** (often remote `https://mcp.figma.com/mcp` per Figma docs) |
-| Plugin-only workflows: compositions, plugin token/Git APIs, whitelisted node helpers that run in **this** plugin | **SXL Studio Bridge** + plugin Remote Connect |
+| Native file operations where Figma’s MCP tools are enough (context, many canvas writes, variables in supported flows) | **Official Figma MCP** (often remote `https://mcp.figma.com/mcp`) |
+| Plugin-only workflows: compositions, plugin token/Git APIs, whitelisted node helpers, Dev Mode codegen parity | **SXL Studio Bridge** + plugin Remote Connect |
 
-Bridge forwards `commandType` + `payload` over WebSocket; **execution is always in the plugin** (whitelist + handlers). Adding an MCP tool in Bridge without the matching plugin handler will not work.
+Bridge forwards `commandType` + `payload` over WebSocket; **execution is always in the plugin** (whitelist + handlers). Adding an MCP tool in Bridge without the matching plugin handler will return `not_whitelisted`.
 
 ### Version compatibility (npm Bridge ⟷ plugin)
 
-When you add or change remote commands:
-
-1. Implement the command in the **plugin** (`WHITELISTED_COMMANDS`, `remote/canvas/` or `remote/sxl/`, etc.).
-2. Register the matching MCP tool (and payload shape) in **Bridge** `src/tools/`.
-3. Bump **Bridge** semver (`package.json`) and document the minimum **plugin** build users need.
-
-| `@sxl-studio/bridge` (npm) | SXL Studio plugin |
-|---------------------------|-------------------|
-| `1.0.x` | Same-era plugin with base remote node tools (`create_frame`, `set_node_fill`, …) |
-| `1.1.x` | Plugin build that includes `set_node_fill_variable` and extended `create_frame` / `create_text` (`parentId`, Auto Layout–related optional fields) |
-| `1.2.x` | Plugin build that includes Remote module split (`dispatch/`, `canvas/`, `sxl/`), MCP `instructions`, base canvas tools (`create_rectangle`, `set_auto_layout`, `duplicate_subtree`, `create_component_instance`, `apply_documentation_payload`), plus **extended** Remote Connect canvas tools registered from `src/tools/figma-rc-extended.ts`. Bridge **1.2.0+** reads `package.json` for startup version, aligns **timeouts** with plugin `COMMAND_TIMEOUTS`, and validates **`POST /api/command`** bodies (`commandType` + object `payload`). |
+| `@sxl-studio/bridge` (npm) | SXL Studio plugin | Highlights |
+|---------------------------|-------------------|------------|
+| `1.0.x` | same-era | Base remote node tools (`create_frame`, `set_node_fill`, …) |
+| `1.1.x` | same-era | `set_node_fill_variable`, extended `create_frame` / `create_text` (`parentId`, Auto Layout fields) |
+| `1.2.x` | same-era | Remote module split (`dispatch/`, `canvas/`, `sxl/`), MCP instructions, base canvas tools, validated `POST /api/command`, aligned `COMMAND_TIMEOUTS` |
+| **`1.3.x`** | **`2.1.0+`** | Dev Mode codegen bridge (`get_codegen`, `export_composition_json`), **full token workspace CRUD** (`create_token_file`, `delete_token_file`, `move_token_file`, `save_tokens_config`, upsert `save_token_file`), **Variables CRUD** (modes, scopes, codeSyntax), **Styles CRUD**, **orchestration** (`compose_from_url`, `generate_code_from_url`, `document_component`), **MCP Resources** (`sxl://…`), typed errors (`EDITOR_MODE_READONLY` + structured envelope), `BRIDGE_AUTH_TOKEN`, **Idempotency-Key** on `/api/command`, `/api/log` audit trail, `/api/tools` + `list_tools` meta-tool, editor-mode write-guard with typed propagation. |
 
-The plugin’s own `version` in `Plugin/package.json` may differ from marketing labels; treat **feature alignment** by changelog or release tag, not npm name alone.
-
-### Remote node API strategy
-
-New canvas automation is shipped as **small atomic** remote commands (variable-bound fills, optional `parentId`, Auto Layout fields) so Bridge and HTTP clients stay in sync with the whitelist. A single high-level command such as `generate_palette_documentation` remains a possible future optimization if you want fewer round-trips for one specific workflow.
+Treat feature alignment by changelog or release tag, not npm name alone.
 
 ## Ports
 
-**One TCP port** (`BRIDGE_PORT`, default **`37830`** — avoids many apps that bind `3100` on macOS): plugin **WebSocket**, **HTTP REST** (`/api/*`), and **MCP Streamable HTTP** (`/mcp`) share it. Override with `BRIDGE_PORT=3100 npm start` if you need the legacy port (update plugin build + `mcp.json` to match).
+**One TCP port** (`BRIDGE_PORT`, default **`37830`**): plugin **WebSocket**, **HTTP REST** (`/api/*`), and **MCP Streamable HTTP** (`/mcp`) share it. Override with `BRIDGE_PORT=3100 npm start` if needed (update plugin build + `mcp.json` to match).
 
 | On port `BRIDGE_PORT` | URL (default) |
 |----------------------|---------------|
 | Plugin UI | `ws://127.0.0.1:37830` |
-| REST | `http://127.0.0.1:37830/api/status`, `POST …/api/command`, … |
+| REST | `http://127.0.0.1:37830/api/{status,session,tools,log,command,disconnect}` |
 | Cursor MCP | `http://127.0.0.1:37830/mcp` |
 
+### Optional: shared-secret auth
+
+Set `BRIDGE_AUTH_TOKEN` in the environment and every `/api/*` and `/mcp` request must send `Authorization: Bearer <token>`. Requests without the header return `401 BRIDGE_UNAUTHORIZED`. Useful when running Bridge on a shared machine, or behind a local proxy.
+
+```bash
+BRIDGE_AUTH_TOKEN=s3cret npm start
+```
+
 ### Cursor MCP (recommended)
 
-Same pattern as [Figma’s MCP URL](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/): add **`http://127.0.0.1:37830/mcp`** (or `http://127.0.0.1:{BRIDGE_PORT}/mcp`). **Start Bridge first** (`cd Bridge && npm run build && npm start`, or from repo root `npm run bridge` after `npm run bridge:build`). Then enable Remote Connect in the SXL Studio plugin.
+Add `http://127.0.0.1:37830/mcp` to `.cursor/mcp.json`. Start Bridge **first** (`cd Utils/bridge && npm run build && npm start`). Then enable Remote Connect in the SXL Studio plugin.
 
-Official **Figma MCP** (`http://127.0.0.1:3845/mcp`) reads design context from the file; it does **not** run SXL Studio plugin commands. For `create_frame`, `export_variables`, compositions, etc., use **this** Bridge MCP (or `POST /api/command`).
+Official **Figma MCP** (`http://127.0.0.1:3845/mcp`) reads design context from the file; it does **not** run SXL Studio plugin commands.
 
 ## Run locally
 
 ```bash
-cd Bridge
+cd Utils/bridge
 npm install
 npm run build
 node dist/index.js
 ```
 
-If you see **`EADDRINUSE`**, pick a free port: `BRIDGE_PORT=39999 npm start`, then use **`http://127.0.0.1:39999/mcp`** in Cursor and rebuild the plugin so `remoteBridge.ts` default matches (or keep defaults in sync via env in your workflow). Check listeners: `lsof -nP -iTCP:37830 -sTCP:LISTEN`.
+If you see `EADDRINUSE`, pick a free port: `BRIDGE_PORT=39999 npm start`, then use `http://127.0.0.1:39999/mcp` in Cursor and rebuild the plugin so `remoteBridge.ts` default matches.
 
-The repo **`.cursor/mcp.json`** points Cursor at **`http://127.0.0.1:37830/mcp`**. You must **run Bridge** before opening Agent chat. Optional: stdio spawn via `node scripts/run-sxl-bridge.mjs`. See `Plugin/docs/ru/60-remote-connect.md`.
+The repo `.cursor/mcp.json` points Cursor at `http://127.0.0.1:37830/mcp`. Bridge must run **before** opening Agent chat.
 
-**MCP + stdout:** the Model Context Protocol uses **stdout** for JSON-RPC. Do not use `console.log` in this process (it corrupts the stream). Use **`console.error`** for diagnostics.
+**MCP + stdout:** the Model Context Protocol uses **stdout** for JSON-RPC. Do not use `console.log` in this process (it corrupts the stream). Use `console.error` for diagnostics.
 
 ## MCP configuration (Cursor)
 
 Example `.cursor/mcp.json`:
 
+```json
+{
+  "mcpServers": {
+    "sxl-studio": {
+      "url": "http://127.0.0.1:37830/mcp"
+    }
+  }
+}
+```
+
+stdio variant (if preferred):
+
 ```json
 {
   "mcpServers": {
     "sxl-studio": {
       "command": "node",
-      "args": ["/absolute/path/to/repo/Bridge/dist/index.js"],
-      "env": {
-        "BRIDGE_PORT": "37830"
-      }
+      "args": ["/absolute/path/to/repo/Utils/bridge/dist/index.js"],
+      "env": { "BRIDGE_PORT": "37830" }
     }
   }
 }
@@ -92,31 +99,59 @@ Example `.cursor/mcp.json`:
 
 ## HTTP API examples
 
-Requires the plugin open in Figma, Remote Connect enabled, and bridge running.
+Requires the plugin open in Figma, Remote Connect enabled, and Bridge running.
 
-**Status** (JSON includes `mcpStreamableHttp` and `ports`; WebSocket and HTTP use the **same** port number)
+### Status
 
 ```bash
 curl -s http://127.0.0.1:37830/api/status
 ```
 
-**Read token file (after you know `fileId` from MCP `list_token_files`)**
+Returns `ports`, `mcpStreamableHttp`, `session`, `queueLength`, `currentCommand`, `authEnabled`.
+
+### Tool catalogue
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/tools?category=tokens'
+curl -s 'http://127.0.0.1:37830/api/tools?devModeReadableOnly=true'
+```
+
+Returns entries `{ name, category, description, requiresDesignMode, requiresComposition }`. MCP clients can call the equivalent `list_tools` meta-tool.
+
+### Audit trail
+
+```bash
+curl -s 'http://127.0.0.1:37830/api/log?limit=50'
+```
+
+Ring buffer of executed commands: `commandType`, `status`, `durationMs`, `payloadKeys`, `idempotencyKey`, `timestamp`.
+
+### Read token file (after `list_token_files`)
 
 ```bash
 curl -s -X POST http://127.0.0.1:37830/api/command \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $BRIDGE_AUTH_TOKEN" \
+  -H "Idempotency-Key: 01HXYZ1234" \
   -d '{"commandType":"get_token_file_content","payload":{"fileId":"tf_..."}}'
 ```
 
-**Save token file**
+Repeat requests with the same `Idempotency-Key` (within 10 minutes) return the cached response without touching the plugin — safe for retries.
+
+### Save token file (upsert)
 
 ```bash
 curl -s -X POST http://127.0.0.1:37830/api/command \
   -H "Content-Type: application/json" \
-  -d '{"commandType":"save_token_file","payload":{"fileId":"tf_...","content":"{}"}}'
+  -d '{
+    "commandType": "save_token_file",
+    "payload": { "name": "buttons", "folder": "components", "content": "{\"$type\":\"composition\"}" }
+  }'
 ```
 
-**Export composition JSON from current selection**
+If a file with that `name`+`folder` exists, it is updated. Otherwise it is created.
+
+### Export composition JSON from current selection
 
 ```bash
 curl -s -X POST http://127.0.0.1:37830/api/command \
@@ -126,15 +161,54 @@ curl -s -X POST http://127.0.0.1:37830/api/command \
 
 Optional `payload.nodeId` selects a specific node instead of the first selected node.
 
+### Typed errors
+
+Failures return a structured envelope:
+
+```json
+{
+  "status": "failed",
+  "error": "{\"code\":\"EDITOR_MODE_READONLY\",\"message\":\"Command \\\"create_frame\\\" requires Figma Design mode.\",\"retryable\":false,\"details\":{\"editorType\":\"dev\",\"mode\":\"default\",\"isDevMode\":true}}"
+}
+```
+
+Known codes: `EDITOR_MODE_READONLY`, `BRIDGE_TIMEOUT`, `BRIDGE_CANCELLED`, `BRIDGE_UNAUTHORIZED`, `BRIDGE_ERROR`. MCP tools decode the envelope before returning to the agent.
+
 ## MCP tools (summary)
 
-Registered in `src/mcp-server.ts` via `tools/*.ts`, including:
+Registered in `src/mcp-factory.ts` via `tools/*.ts`:
+
+- **Diagnostics / meta:** `get_plugin_status`, `is_dev_mode`, `get_selection_summary`, `get_drift_status`, `list_tools`.
+- **Tokens / workspace:** `list_token_files`, `get_token_file_content`, `save_token_file` (upsert), `create_token_file`, `delete_token_file`, `move_token_file`, `rename_token_file`, `get_tokens_config`, `save_tokens_config`, `export_variables`, `reset_diff*`, `reapply_token_bindings`, `cross_file_sync_*`, `get_applied_tokens`.
+- **Composition:** `export_composition_json`, `get_codegen`, `list_compositions`, `generate_composition`, `apply_composition`, `preview_composition`, `check_composition_linked`, `inspect_selection`.
+- **Variables:** `get_variables`, `create_variable_collection`, `create_variable`, `bind_variable`, `rename_variable`, `delete_variable`, `rename_variable_collection`, `delete_variable_collection`, `add_variable_mode`, `remove_variable_mode`, `rename_variable_mode`, `set_variable_mode_value`, `set_variable_scopes`, `set_variable_code_syntax`.
+- **Styles:** `get_local_styles`, `create_paint_style`, `create_text_style`, `create_effect_style`, `set_text_style`, `set_effect_style`, `set_stroke_style`, `set_fill_style`, `import_style_by_key`.
+- **Data / nodes:** `apply_mapping`, `apply_all_mappings`, `count_apply_targets`, `generate_instances`, `apply_image`, plus direct node helpers in `data.ts` / `figma-nodes.ts` (`set_node_fill_variable`, `create_rectangle`, `set_auto_layout`, `duplicate_subtree`, `create_component_instance`, `apply_documentation_payload`, extended `create_frame` / `create_text`).
+- **Git:** `git_pull`, `git_hard_pull`, `git_push`.
+- **Orchestration:** `generate_code_from_url`, `compose_from_url`, `document_component`.
+
+### MCP Resources
+
+| URI | Contents |
+|-----|----------|
+| `sxl://figma/status` | Plugin status snapshot |
+| `sxl://figma/selection` | Current Figma selection |
+| `sxl://tokens/config` | Raw `config.json` |
+| `sxl://tokens/files` | Token file index |
+| `sxl://tokens/files/{fileId}` | Raw token file body |
+| `sxl://compositions/index` | Composition JSON index |
+
+Cursor / Claude can attach these as context without calling tools.
+
+## Dev Mode support
+
+| Context | Reads | Canvas writes | Token/config/git writes |
+|---------|-------|---------------|--------------------------|
+| Figma Design | ✔︎ | ✔︎ | ✔︎ |
+| Figma Dev Mode (UI, `mode: "default"`) | ✔︎ | ✘ (plugin returns `EDITOR_MODE_READONLY`) | ✔︎ |
+| Figma Dev Mode (Inspect → Code sandbox) | read-only codegen callback; Remote Connect unavailable | ✘ | ✘ |
 
-- **Tokens:** `export_variables`, `reset_diff*`, `reapply_token_bindings`, `cross_file_sync_*`, `get_token_file_content`, `save_token_file`
-- **Composition:** `generate_composition`, `apply_composition`, `preview_composition`, `check_composition_linked`, `inspect_selection`, `export_composition_json`
-- **Data / nodes:** `apply_mapping`, `apply_all_mappings`, `count_apply_targets`, `generate_instances`, `apply_image`, direct node helpers in `data.ts` / `figma-nodes.ts` (including `set_node_fill_variable`, `create_rectangle`, `set_auto_layout`, `duplicate_subtree`, `create_component_instance`, `apply_documentation_payload`, extended `create_frame` / `create_text`)
-- **Git:** `git_pull`, `git_hard_pull`, `git_push`
-- **Diagnostics:** plugin status, selection, drift, Code Connect, etc.
+`get_codegen` (Bridge) and the Dev Mode Inspect → Code panel (plugin) share the exact same `routeCodegenGenerate` pipeline. Output is byte-identical.
 
 ## Development
 

package/dist/audit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Audit ring buffer for Bridge commands.
+ *
+ * Every command dispatched via POST /api/command is recorded with its
+ * commandType, status, duration and a short payload-keys preview (no values
+ * — to avoid leaking secrets). GET /api/log returns the most recent entries.
+ * This is in-memory, per-process, and capped to 200 entries.
+ */
+import type { CommandResult } from "./types.js";
+export type AuditEntry = {
+    at: number;
+    commandId: string;
+    commandType: string;
+    status: CommandResult["status"];
+    durationMs: number | null;
+    error: string | null;
+    payloadKeys: string[];
+    idempotencyKey: string | null;
+};
+export declare function recordAudit(entry: AuditEntry): void;
+export declare function getAuditSnapshot(limit?: number): AuditEntry[];

package/dist/audit.js

@@ -0,0 +1,24 @@
+/**
+ * Audit ring buffer for Bridge commands.
+ *
+ * Every command dispatched via POST /api/command is recorded with its
+ * commandType, status, duration and a short payload-keys preview (no values
+ * — to avoid leaking secrets). GET /api/log returns the most recent entries.
+ * This is in-memory, per-process, and capped to 200 entries.
+ */
+const BUFFER_SIZE = 200;
+const buffer = [];
+export function recordAudit(entry) {
+    buffer.push(entry);
+    if (buffer.length > BUFFER_SIZE) {
+        buffer.splice(0, buffer.length - BUFFER_SIZE);
+    }
+    // Structured log line for operators tailing the console.
+    // eslint-disable-next-line no-console
+    console.error(`[Audit] ${new Date(entry.at).toISOString()} ${entry.commandType} -> ${entry.status}${typeof entry.durationMs === "number" ? ` (${entry.durationMs}ms)` : ""}${entry.error ? ` — ${entry.error}` : ""}`);
+}
+export function getAuditSnapshot(limit = 50) {
+    const clamped = Math.max(1, Math.min(limit, BUFFER_SIZE));
+    return buffer.slice(-clamped).reverse();
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,MAAM,GAAiB,EAAE,CAAC;AAEhC,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,MAAM,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;IAChD,CAAC;IACD,yDAAyD;IACzD,sCAAsC;IACtC,OAAO,CAAC,KAAK,CACX,WAAW,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,WAAW,OAAO,KAAK,CAAC,MAAM,GACjF,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,EACtE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAK,GAAG,EAAE;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;AAC1C,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bridge authentication — optional shared-token gate.
+ *
+ * Activated when BRIDGE_AUTH_TOKEN env var is set. Requests must then carry
+ * `Authorization: Bearer <token>` (case-insensitive header name, case-sensitive token).
+ * Applies to both REST /api/* and MCP Streamable HTTP at /mcp.
+ *
+ * Disabled by default to preserve zero-config "run and connect Cursor" UX.
+ */
+import type { IncomingMessage } from "node:http";
+export declare function getBridgeAuthToken(): string | null;
+export declare function checkAuth(req: IncomingMessage): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function isAuthEnabled(): boolean;

package/dist/auth.js

@@ -0,0 +1,39 @@
+/**
+ * Bridge authentication — optional shared-token gate.
+ *
+ * Activated when BRIDGE_AUTH_TOKEN env var is set. Requests must then carry
+ * `Authorization: Bearer <token>` (case-insensitive header name, case-sensitive token).
+ * Applies to both REST /api/* and MCP Streamable HTTP at /mcp.
+ *
+ * Disabled by default to preserve zero-config "run and connect Cursor" UX.
+ */
+export function getBridgeAuthToken() {
+    const raw = process.env["BRIDGE_AUTH_TOKEN"];
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function checkAuth(req) {
+    const token = getBridgeAuthToken();
+    if (!token)
+        return { ok: true };
+    const header = req.headers["authorization"] ??
+        req.headers["Authorization"];
+    if (!header) {
+        return { ok: false, reason: "Missing Authorization header" };
+    }
+    const [scheme, ...rest] = header.split(" ");
+    if (scheme?.toLowerCase() !== "bearer") {
+        return { ok: false, reason: "Authorization header must use Bearer scheme" };
+    }
+    const provided = rest.join(" ").trim();
+    if (provided !== token) {
+        return { ok: false, reason: "Invalid bearer token" };
+    }
+    return { ok: true };
+}
+export function isAuthEnabled() {
+    return getBridgeAuthToken() !== null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,UAAU,kBAAkB;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAoB;IAC5C,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAChC,MAAM,MAAM,GACT,GAAG,CAAC,OAAO,CAAC,eAAe,CAAwB;QACnD,GAAG,CAAC,OAAO,CAAC,eAAe,CAAmC,CAAC;IAClE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IAC/D,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6CAA6C,EAAE,CAAC;IAC9E,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,EAAE,KAAK,IAAI,CAAC;AACvC,CAAC"}

package/dist/http-api.d.ts

@@ -3,6 +3,19 @@
  *
  * Also serves MCP Streamable HTTP at GET|POST /mcp (recommended for Cursor — same pattern
  * as Figma's official MCP: add server URL in Cursor settings).
+ *
+ * Endpoints:
+ *   GET  /api/status      — server + plugin session snapshot
+ *   GET  /api/session     — detailed session info
+ *   GET  /api/tools       — authoritative catalogue of MCP tools
+ *   GET  /api/log?limit=N — audit trail of recent commands (ring buffer)
+ *   POST /api/command     — execute a plugin command (with optional Idempotency-Key)
+ *   POST /api/disconnect  — close the current plugin socket
+ *   ANY  /mcp             — MCP Streamable HTTP
+ *
+ * Security:
+ *   When BRIDGE_AUTH_TOKEN is set, all /api/* and /mcp requests require
+ *   `Authorization: Bearer <token>`.
  */
 import type { BridgeWSServer } from "./ws-server.js";
 export declare function startHttpApi(bridgePort: number, wsServer: BridgeWSServer): Promise<void>;

package/dist/http-api.js

@@ -3,11 +3,29 @@
  *
  * Also serves MCP Streamable HTTP at GET|POST /mcp (recommended for Cursor — same pattern
  * as Figma's official MCP: add server URL in Cursor settings).
+ *
+ * Endpoints:
+ *   GET  /api/status      — server + plugin session snapshot
+ *   GET  /api/session     — detailed session info
+ *   GET  /api/tools       — authoritative catalogue of MCP tools
+ *   GET  /api/log?limit=N — audit trail of recent commands (ring buffer)
+ *   POST /api/command     — execute a plugin command (with optional Idempotency-Key)
+ *   POST /api/disconnect  — close the current plugin socket
+ *   ANY  /mcp             — MCP Streamable HTTP
+ *
+ * Security:
+ *   When BRIDGE_AUTH_TOKEN is set, all /api/* and /mcp requests require
+ *   `Authorization: Bearer <token>`.
  */
 import { createServer } from "node:http";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createBridgeMcpServer } from "./mcp-factory.js";
+import { StreamableHTTPServerTransport } from "../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/streamableHttp.js";
+import { getAuditSnapshot, recordAudit } from "./audit.js";
+import { checkAuth, isAuthEnabled } from "./auth.js";
 import { parseHttpCommandBody } from "./command-http.js";
+import { getIdempotent, putIdempotent } from "./idempotency.js";
+import { createBridgeMcpServer } from "./mcp-factory.js";
+import { bootstrapBridgeToolCatalogue } from "./tools/catalogue-bootstrap.js";
+import { getBridgeToolCatalogue } from "./tools/registry.js";
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let body = "";
@@ -23,7 +41,7 @@ function sendJson(res, status, data) {
         "Content-Type": "application/json",
         "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-        "Access-Control-Allow-Headers": "Content-Type, Accept, Authorization, Mcp-Session-Id, mcp-protocol-version",
+        "Access-Control-Allow-Headers": "Content-Type, Accept, Authorization, Mcp-Session-Id, mcp-protocol-version, Idempotency-Key",
     });
     res.end(JSON.stringify(data, null, 2));
 }
@@ -35,9 +53,19 @@ function pathnameOnly(reqUrl) {
         return "/";
     }
 }
+function searchParamsOf(reqUrl) {
+    try {
+        return new URL(reqUrl || "/", "http://127.0.0.1").searchParams;
+    }
+    catch {
+        return new URLSearchParams();
+    }
+}
 export async function startHttpApi(bridgePort, wsServer) {
     const queue = wsServer.commandQueue;
     const session = wsServer.session;
+    // Keep catalogue + MCP server init symmetric for both stdio and HTTP.
+    bootstrapBridgeToolCatalogue();
     const mcpHttpServer = createBridgeMcpServer(queue);
     const mcpTransport = new StreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
@@ -56,11 +84,21 @@ export async function startHttpApi(bridgePort, wsServer) {
                 "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
                 "Access-Control-Allow-Headers": typeof reqHdr === "string" && reqHdr.length > 0
                     ? reqHdr
-                    : "Content-Type, Accept, Authorization, Mcp-Session-Id, mcp-protocol-version",
+                    : "Content-Type, Accept, Authorization, Mcp-Session-Id, mcp-protocol-version, Idempotency-Key",
             });
             res.end();
             return;
         }
+        // Optional shared-secret auth (BRIDGE_AUTH_TOKEN).
+        const auth = checkAuth(req);
+        if (!auth.ok) {
+            sendJson(res, 401, {
+                code: "BRIDGE_UNAUTHORIZED",
+                message: auth.reason,
+                retryable: false,
+            });
+            return;
+        }
         try {
             // MCP Streamable HTTP (Cursor, same idea as Figma MCP URL in docs)
             if (pathname === "/mcp") {
@@ -91,7 +129,7 @@ export async function startHttpApi(bridgePort, wsServer) {
                     queueLength: queue.queueLength,
                     currentCommand: queue.currentCommand,
                 };
-                sendJson(res, 200, status);
+                sendJson(res, 200, { ...status, authEnabled: isAuthEnabled() });
                 return;
             }
             // GET /api/session
@@ -99,6 +137,31 @@ export async function startHttpApi(bridgePort, wsServer) {
                 sendJson(res, 200, session.info);
                 return;
             }
+            // GET /api/tools — authoritative catalogue (same as list_tools MCP tool)
+            if (req.method === "GET" && pathname === "/api/tools") {
+                const sp = searchParamsOf(req.url || "/");
+                const category = sp.get("category");
+                const devModeReadableOnly = sp.get("devModeReadableOnly") === "true";
+                let entries = [...getBridgeToolCatalogue()];
+                if (category)
+                    entries = entries.filter((e) => e.category === category);
+                if (devModeReadableOnly)
+                    entries = entries.filter((e) => !e.requiresDesignMode);
+                sendJson(res, 200, {
+                    count: entries.length,
+                    categories: Array.from(new Set(entries.map((e) => e.category))),
+                    tools: entries,
+                });
+                return;
+            }
+            // GET /api/log — recent audit entries (ring buffer)
+            if (req.method === "GET" && pathname === "/api/log") {
+                const sp = searchParamsOf(req.url || "/");
+                const rawLimit = parseInt(sp.get("limit") ?? "", 10);
+                const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : 50;
+                sendJson(res, 200, { entries: getAuditSnapshot(limit) });
+                return;
+            }
             // POST /api/command
             if (req.method === "POST" && pathname === "/api/command") {
                 if (!session.connected) {
@@ -111,7 +174,37 @@ export async function startHttpApi(bridgePort, wsServer) {
                     sendJson(res, parsed.status, { error: parsed.error });
                     return;
                 }
+                // Idempotency: header wins, body fallback.
+                const headerKey = req.headers["idempotency-key"] ??
+                    req.headers["Idempotency-Key"] ??
+                    null;
+                const bodyKeyRaw = JSON.parse(body || "{}")?.idempotencyKey;
+                const idempotencyKey = (typeof headerKey === "string" && headerKey.length > 0 ? headerKey : null) ??
+                    (typeof bodyKeyRaw === "string" && bodyKeyRaw.length > 0 ? bodyKeyRaw : null);
+                if (idempotencyKey) {
+                    const cached = getIdempotent(idempotencyKey);
+                    if (cached) {
+                        sendJson(res, 200, { ...cached, idempotent: "hit" });
+                        return;
+                    }
+                }
+                const startedAt = Date.now();
                 const result = await queue.execute(parsed.commandType, parsed.payload);
+                recordAudit({
+                    at: startedAt,
+                    commandId: result.commandId,
+                    commandType: parsed.commandType,
+                    status: result.status,
+                    durationMs: typeof result.durationMs === "number"
+                        ? result.durationMs
+                        : Date.now() - startedAt,
+                    error: result.error ?? null,
+                    payloadKeys: Object.keys(parsed.payload ?? {}),
+                    idempotencyKey,
+                });
+                if (idempotencyKey) {
+                    putIdempotent(idempotencyKey, result);
+                }
                 sendJson(res, 200, result);
                 return;
             }
@@ -139,6 +232,9 @@ export async function startHttpApi(bridgePort, wsServer) {
         });
         server.listen(bridgePort, "127.0.0.1", () => {
             console.error(`[Bridge] Listening on http://127.0.0.1:${bridgePort}  (REST /api/*, MCP /mcp, plugin ws://127.0.0.1:${bridgePort})`);
+            if (isAuthEnabled()) {
+                console.error("[Bridge] Auth enabled — require Authorization: Bearer <BRIDGE_AUTH_TOKEN>");
+            }
             resolve();
         });
     });

package/dist/http-api.js.map

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

package/dist/idempotency.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Idempotency cache for POST /api/command.
+ *
+ * Clients may pass an `Idempotency-Key` HTTP header (or top-level
+ * `idempotencyKey` in the JSON body). Repeating the same key within the TTL
+ * window returns the original response without re-dispatching the command to
+ * the plugin — avoiding duplicate side effects on network retries.
+ *
+ * Cache is in-memory, per-process, and intentionally small.
+ */
+import type { CommandResult } from "./types.js";
+export declare function getIdempotent(key: string): CommandResult | null;
+export declare function putIdempotent(key: string, result: CommandResult): void;