@dieulc/pi-office-bridge 0.1.0 → 0.3.0

package/src/bridge-server.ts

@@ -8,14 +8,22 @@
  */
 
 import { WebSocketServer, WebSocket } from "ws";
-import type { Server as HttpServer } from "node:http";
+import type {
+  IncomingMessage,
+  Server as HttpServer,
+  ServerResponse,
+} from "node:http";
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 
 import {
   BRIDGE_PROTOCOL_VERSION,
+  CATALOG_VERSION,
+  LEGACY_V1_OPS,
+  OFFICE_CATALOG_BY_OP,
   nextCallId,
   parseClientMessage,
+  type BridgeCapability,
   type ClientMessage,
   type OfficeHostApp,
   type ServerMessage,
@@ -31,11 +39,26 @@ export interface AttachedPane {
   lastSeen: number;
   model?: string;
   provider?: string;
+  /**
+   * Ops this pane advertised in `hello` (validated against the server catalog
+   * and normalized to `<host>.<op>` ids). `null` means a legacy pane that did
+   * not advertise an `ops` list — only the v1 op set is allowed for it.
+   */
+  ops: readonly string[] | null;
+  /** Catalog version the pane derived its ops from, when advertised. */
+  catalogVersion: number | null;
+  /** Count of advertised ops dropped because they are unknown to this server. */
+  opsIgnoredCount: number;
 }
 
 export interface BridgeServerHandlers {
   /** A user typed a prompt in the add-in sidebar. */
   onUserMessage(text: string, pane: AttachedPane): void;
+  /**
+   * A pane attached or detached. Lets the host (Pi) refresh its status line
+   * immediately instead of waiting for the next session event.
+   */
+  onPanesChanged?(panes: readonly AttachedPane[]): void;
 }
 
 export interface CallOfficeToolResult {
@@ -49,6 +72,16 @@ const HEARTBEAT_INTERVAL_MS = 30_000;
 const MAX_TEXT_CHARS = 50_000;
 const MAX_DETAILS_BYTES = 1_000_000;
 
+/** Extra browser origins for the /health CORS gate, from env (comma-separated). */
+function parseExtraOrigins(): string[] {
+  const raw = process.env.PI_OFFICE_BRIDGE_ALLOWED_ORIGINS;
+  if (!raw) return [];
+  return raw
+    .split(/[,\s]+/u)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 interface PendingCall {
   resolve(result: CallOfficeToolResult): void;
   reject(error: Error): void;
@@ -56,10 +89,15 @@ interface PendingCall {
 }
 
 export class OfficeBridgeServer {
+  /** Capabilities advertised in `welcome` and `GET /health`. */
+  static readonly CAPABILITIES: readonly BridgeCapability[] = ["http-health"];
+
   private readonly port: number;
   private readonly handlers: BridgeServerHandlers;
   private readonly serverName: string;
+  private readonly serverVersion: string;
   private readonly piVersion: string | null;
+  private readonly startedAt = Date.now();
 
   private httpServer: HttpServer | null = null;
   private wss: WebSocketServer | null = null;
@@ -71,11 +109,13 @@ export class OfficeBridgeServer {
   constructor(options: {
     port: number;
     serverName?: string;
+    serverVersion?: string;
     piVersion?: string | null;
     handlers: BridgeServerHandlers;
   }) {
     this.port = options.port;
     this.serverName = options.serverName ?? "pi-office-bridge";
+    this.serverVersion = options.serverVersion ?? "unknown";
     this.piVersion = options.piVersion ?? null;
     this.handlers = options.handlers;
   }
@@ -86,7 +126,9 @@ export class OfficeBridgeServer {
 
   get actualPort(): number | null {
     const addr = this.httpServer?.address();
-    return typeof addr === "object" && addr !== null ? (addr as AddressInfo).port : null;
+    return typeof addr === "object" && addr !== null
+      ? (addr as AddressInfo).port
+      : null;
   }
 
   /** Pane list copy (ordered by most recent connection first). */
@@ -98,8 +140,13 @@ export class OfficeBridgeServer {
   start(): Promise<void> {
     if (this.wss) return Promise.resolve();
 
-    const httpServer = createServer();
-    const wss = new WebSocketServer({ server: httpServer, maxPayload: 16 * 1024 * 1024 });
+    const httpServer = createServer((req, res) =>
+      this.handleHttpRequest(req, res),
+    );
+    const wss = new WebSocketServer({
+      server: httpServer,
+      maxPayload: 16 * 1024 * 1024,
+    });
 
     this.httpServer = httpServer;
     this.wss = wss;
@@ -153,6 +200,7 @@ export class OfficeBridgeServer {
       pane.ws.close(1001, "bridge shutting down");
     }
     this.panes.length = 0;
+    this.notifyPanesChanged();
 
     return new Promise((resolve) => {
       wss.close(() => resolve());
@@ -184,18 +232,45 @@ export class OfficeBridgeServer {
       );
     }
 
+    const opId = `${host}.${op}`;
+    // Capability gate: a pane may only execute ops it advertised (or, for
+    // legacy panes that advertise nothing, only the v1 op set).
+    if (pane.ops !== null) {
+      if (!pane.ops.includes(opId)) {
+        return Promise.reject(
+          new Error(
+            `office-bridge: the attached ${host} pane does not advertise "${opId}" ` +
+              `(it supports ${pane.ops.length} ops). ` +
+              "Reload the pi-for-office add-in to enable this tool.",
+          ),
+        );
+      }
+    } else if (!LEGACY_V1_OPS.includes(opId)) {
+      return Promise.reject(
+        new Error(
+          `office-bridge: "${opId}" requires a newer add-in. ` +
+            "The attached pane is a legacy client (no capability list); update " +
+            "pi-for-office and reload the document to enable this tool.",
+        ),
+      );
+    }
+
     const id = nextCallId("tool");
     const message: ServerMessage = {
       type: "tool_call",
       id,
-      tool: `${host}.${op}`,
+      tool: opId,
       args,
     };
 
     return new Promise<CallOfficeToolResult>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`office-bridge: ${op} timed out after ${timeoutMs / 1000}s`));
+        reject(
+          new Error(
+            `office-bridge: ${op} timed out after ${timeoutMs / 1000}s`,
+          ),
+        );
       }, timeoutMs);
 
       this.pending.set(id, { resolve, reject, timer });
@@ -217,7 +292,11 @@ export class OfficeBridgeServer {
       if (!this.sendToPane(pane, message)) {
         clearTimeout(timer);
         this.pending.delete(id);
-        reject(new Error("office-bridge: pane disconnected before the tool call was sent"));
+        reject(
+          new Error(
+            "office-bridge: pane disconnected before the tool call was sent",
+          ),
+        );
       }
     });
   }
@@ -229,13 +308,164 @@ export class OfficeBridgeServer {
     }
   }
 
+  /* ── HTTP (health/diagnostics, loopback-only) ─────────────────────── */
+
+  /**
+   * Browser origins allowed to read this loopback HTTP surface. The add-in
+   * task pane runs at these origins (dev Vite server + hosted GitHub Pages).
+   * Extend with the PI_OFFICE_BRIDGE_ALLOWED_ORIGINS env var
+   * (comma-separated) when the add-in is hosted elsewhere.
+   */
+  private static readonly ALLOWED_ORIGINS: ReadonlySet<string> = new Set([
+    "https://localhost:3141",
+    "https://pi-excel.localhost",
+    "https://dieuluucanh.github.io",
+    ...parseExtraOrigins(),
+  ]);
+
+  private static resolveAllowOrigin(req: IncomingMessage): string | null {
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || origin.trim().length === 0) {
+      // Non-browser client (curl / tests / server tooling) — no CORS gate.
+      return "*";
+    }
+    if (OfficeBridgeServer.ALLOWED_ORIGINS.has(origin)) return origin;
+    return null; // Unknown browser origin → omit header; browser blocks.
+  }
+
+  /**
+   * Minimal loopback HTTP surface used by the add-in's "Test connection"
+   * probe and by curl. WebSocket upgrades are handled by `ws` at the server
+   * level; ordinary requests (GET /health, OPTIONS preflight) land here.
+   * The endpoint is unauthenticated but exposes only bridge metadata.
+   */
+  private handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
+    const urlRaw = req.url ?? "/";
+    let url: URL;
+    try {
+      url = new URL(urlRaw, "http://127.0.0.1");
+    } catch {
+      this.writeHttp(res, 400, { ok: false, error: "bad_request" }, req);
+      return;
+    }
+    const allowOrigin = OfficeBridgeServer.resolveAllowOrigin(req);
+
+    if (req.method === "OPTIONS") {
+      this.writeHttp(res, 204, null, req, allowOrigin);
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/health") {
+      const panes = this.attachedPanes().map((p) => ({
+        host: p.host,
+        paneId: p.paneId,
+        clientName: p.clientName,
+        connectedAt: p.connectedAt,
+        lastSeen: p.lastSeen,
+        model: p.model,
+        provider: p.provider,
+        ops: p.ops,
+        catalogVersion: p.catalogVersion,
+        opsIgnoredCount: p.opsIgnoredCount,
+      }));
+
+      this.writeHttp(
+        res,
+        200,
+        {
+          ok: true,
+          service: this.serverName,
+          serverVersion: this.serverVersion,
+          capabilities: OfficeBridgeServer.CAPABILITIES,
+          protocolVersion: BRIDGE_PROTOCOL_VERSION,
+          piVersion: this.piVersion,
+          port: this.actualPort,
+          uptimeMs: Date.now() - this.startedAt,
+          catalogVersion: CATALOG_VERSION,
+          panes,
+        },
+        req,
+        allowOrigin,
+      );
+      return;
+    }
+
+    this.writeHttp(
+      res,
+      404,
+      { ok: false, error: "not_found" },
+      req,
+      allowOrigin,
+    );
+  }
+
+  private writeHttp(
+    res: ServerResponse,
+    status: number,
+    body: unknown,
+    _req?: IncomingMessage,
+    allowOrigin: string | null = "*",
+  ): void {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+      // Loopback-only server. The Private-Network header keeps the probe
+      // working from the hosted GitHub Pages origin (public → localhost).
+      "Access-Control-Allow-Methods": "GET, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+      "Access-Control-Allow-Private-Network": "true",
+    };
+    if (allowOrigin !== null) {
+      headers["Access-Control-Allow-Origin"] = allowOrigin;
+      headers["Vary"] = "Origin";
+    }
+    res.writeHead(status, headers);
+    if (status === 204 || body === null) {
+      res.end();
+      return;
+    }
+    res.end(JSON.stringify(body));
+  }
+
   /* ── Internals ─────────────────────────────────────────────────────── */
 
   private findPane(host: OfficeHostApp): AttachedPane | null {
-    const sorted = [...this.panes].sort((a, b) => b.connectedAt - a.connectedAt);
+    const sorted = [...this.panes].sort(
+      (a, b) => b.connectedAt - a.connectedAt,
+    );
     return sorted.find((p) => p.host === host) ?? null;
   }
 
+  /**
+   * Normalize a pane's advertised ops against the server catalog: keep only
+   * ops that exist in the catalog and belong to the pane's host; return null
+   * when the pane advertised nothing (legacy client).
+   */
+  private normalizeAdvertisedOps(
+    host: OfficeHostApp,
+    advertised: readonly string[] | undefined,
+  ): readonly string[] | null {
+    if (advertised === undefined || advertised.length === 0) return null;
+    const known = new Set<string>();
+    for (const op of advertised) {
+      const entry = OFFICE_CATALOG_BY_OP.get(op);
+      if (entry && entry.host === host) known.add(op);
+    }
+    return known.size > 0 ? [...known] : null;
+  }
+
+  /** Count ops the pane advertised that this server dropped as unknown/host-mismatched. */
+  private countIgnoredOps(
+    host: OfficeHostApp,
+    advertised: readonly string[] | undefined,
+  ): number {
+    if (advertised === undefined) return 0;
+    return advertised.filter((op) => {
+      const entry = OFFICE_CATALOG_BY_OP.get(op);
+      return entry === undefined || entry.host !== host;
+    }).length;
+  }
+
   private handleConnection(ws: WebSocket): void {
     let pane: AttachedPane | null = null;
 
@@ -272,6 +502,12 @@ export class OfficeBridgeServer {
             clientName: msg.clientName,
             connectedAt: Date.now(),
             lastSeen: Date.now(),
+            // Normalize advertised ops against the server catalog: entries the
+            // server does not know (or that belong to a different host) are
+            // dropped and counted so the operator can see the mismatch.
+            ops: this.normalizeAdvertisedOps(msg.host, msg.ops),
+            catalogVersion: msg.catalogVersion ?? null,
+            opsIgnoredCount: this.countIgnoredOps(msg.host, msg.ops),
           };
           // A pane reconnecting replaces any older pane with the same paneId.
           this.panes.splice(
@@ -286,7 +522,10 @@ export class OfficeBridgeServer {
             protocolVersion: BRIDGE_PROTOCOL_VERSION,
             piVersion: this.piVersion,
             serverName: this.serverName,
+            serverVersion: this.serverVersion,
+            capabilities: [...OfficeBridgeServer.CAPABILITIES],
           });
+          this.notifyPanesChanged();
           break;
         }
         case "ping": {
@@ -333,7 +572,9 @@ export class OfficeBridgeServer {
     // Only the pane that received the call may answer it.
     const pane = this.panes.find((p) => p.ws === ws);
     if (!pane) {
-      call.reject(new Error("office-bridge: pane disconnected before answering"));
+      call.reject(
+        new Error("office-bridge: pane disconnected before answering"),
+      );
       return;
     }
 
@@ -341,25 +582,42 @@ export class OfficeBridgeServer {
     this.pending.delete(msg.id);
 
     if (!msg.ok) {
-      call.reject(new Error(`office-bridge: ${msg.error ?? "office tool failed"}`));
+      call.reject(
+        new Error(`office-bridge: ${msg.error ?? "office tool failed"}`),
+      );
       return;
     }
 
-    const text = msg.text.length > MAX_TEXT_CHARS
-      ? `${msg.text.slice(0, MAX_TEXT_CHARS)}\n…[truncated: ${msg.text.length - MAX_TEXT_CHARS} chars]`
-      : msg.text;
+    const text =
+      msg.text.length > MAX_TEXT_CHARS
+        ? `${msg.text.slice(0, MAX_TEXT_CHARS)}\n…[truncated: ${msg.text.length - MAX_TEXT_CHARS} chars]`
+        : msg.text;
 
     let details: unknown = msg.details;
     if (details !== undefined) {
       const bytes = Buffer.byteLength(JSON.stringify(details));
       if (bytes > MAX_DETAILS_BYTES) {
-        details = { truncated: true, note: `details exceeded ${MAX_DETAILS_BYTES} bytes` };
+        details = {
+          truncated: true,
+          note: `details exceeded ${MAX_DETAILS_BYTES} bytes`,
+        };
       }
     }
 
     call.resolve({ text, details });
   }
 
+  /** Notify the host that the attached-pane set changed. Never throws. */
+  private notifyPanesChanged(): void {
+    try {
+      this.handlers.onPanesChanged?.(this.attachedPanes());
+    } catch (error) {
+      console.error(
+        `[office-bridge] onPanesChanged handler failed: ${String(error)}`,
+      );
+    }
+  }
+
   private detachPane(pane: AttachedPane): void {
     const idx = this.panes.findIndex((p) => p === pane);
     if (idx >= 0) this.panes.splice(idx, 1);
@@ -368,9 +626,15 @@ export class OfficeBridgeServer {
     // reject them — tracked separately so we sweep all on disconnect).
     for (const [id, call] of this.pending) {
       clearTimeout(call.timer);
-      call.reject(new Error("office-bridge: pane disconnected while the tool was running"));
+      call.reject(
+        new Error(
+          "office-bridge: pane disconnected while the tool was running",
+        ),
+      );
       this.pending.delete(id);
     }
+
+    this.notifyPanesChanged();
   }
 
   private startHeartbeat(): void {
@@ -387,7 +651,10 @@ export class OfficeBridgeServer {
     }, HEARTBEAT_INTERVAL_MS);
   }
 
-  private sendToPane(pane: WebSocket | AttachedPane, message: ServerMessage): boolean {
+  private sendToPane(
+    pane: WebSocket | AttachedPane,
+    message: ServerMessage,
+  ): boolean {
     const ws = pane instanceof WebSocket ? pane : pane.ws;
     if (ws.readyState !== WebSocket.OPEN) return false;
     try {