shadow-claw 1.27.0 → 1.28.0

package/src/server/routes/mcp.ts

@@ -16,6 +16,7 @@ import { McpServer } from "../mcp/mcp-server.js";
 import { registerBuiltInTools } from "../mcp/tools/built-in-tools.js";
 import { createClientToolRelay } from "../mcp/tools/client-tool-relay.js";
 import { getOrCreateControlToken } from "../client-registry.js";
+import { getPackageVersion } from "../utils/packageVersion.js";
 
 export interface McpRouteOptions {
   mcpServer?: McpServer;
@@ -36,7 +37,6 @@ export function registerMcpRoutes(
     options.mcpServer ||
     new McpServer({
       name: "shadow-claw",
-      version: "1.25.0",
     });
 
   // Register ShadowClaw built-in and client-relayed tools
@@ -143,7 +143,7 @@ export function registerMcpRoutes(
   }
 
   if (app && typeof app.post === "function") {
-    app.post("/mcp", async (req: Request, res: Response) => {
+    const mcpPostHandler = async (req: Request, res: Response) => {
       // 1. Origin header security check for DNS rebinding protection
       const origin = req.headers.origin;
       if (origin && !isTrustedOrigin(origin, req.headers.host)) {
@@ -165,6 +165,15 @@ export function registerMcpRoutes(
         : isLocalRequest(req);
 
       if (!isAuthenticated) {
+        const scheme =
+          req.secure || req.headers["x-forwarded-proto"] === "https"
+            ? "https"
+            : "http";
+        const host = req.headers.host || "127.0.0.1";
+        res.setHeader(
+          "WWW-Authenticate",
+          `Bearer resource_metadata="${scheme}://${host}/.well-known/oauth-protected-resource"`,
+        );
         res.status(401).json({
           jsonrpc: "2.0",
           id: req.body?.id ?? null,
@@ -222,7 +231,134 @@ export function registerMcpRoutes(
       }
 
       res.status(statusCode).json(response);
+    };
+
+    app.post("/mcp", mcpPostHandler);
+    app.post("/.well-known/mcp", mcpPostHandler);
+  }
+
+  if (app && typeof app.get === "function") {
+    const getBaseUrl = (req: Request) => {
+      const scheme =
+        req.secure || req.headers["x-forwarded-proto"] === "https"
+          ? "https"
+          : "http";
+      const host = req.headers.host || "127.0.0.1";
+      return `${scheme}://${host}`;
+    };
+
+    // MCP Server Card Discovery (SEP-2127 / well-known discovery)
+    const handleServerCard = (req: Request, res: Response) => {
+      const origin = getBaseUrl(req);
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.json({
+        $schema: "https://modelcontextprotocol.io/schemas/server-card/v1.json",
+        name: "shadow-claw",
+        version: getPackageVersion(),
+        description:
+          "Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution.",
+        title: "ShadowClaw MCP Server",
+        websiteUrl: `${origin}/shadow-claw/`,
+        repository: {
+          url: "https://github.com/xt-ml/shadow-claw",
+          source: "github",
+        },
+        icons: [
+          {
+            src: `${origin}/assets/icons/favicon.svg`,
+            mimeType: "image/svg+xml",
+            sizes: ["any"],
+          },
+          {
+            src: `${origin}/assets/icons/512.png`,
+            mimeType: "image/png",
+            sizes: ["512x512"],
+          },
+        ],
+        remotes: [
+          {
+            type: "streamable-http",
+            url: `${origin}/mcp`,
+            supportedProtocolVersions: [
+              "2026-07-28",
+              "2025-11-25",
+              "2024-11-05",
+            ],
+            headers: [
+              {
+                name: "MCP-Protocol-Version",
+                default: "2026-07-28",
+                isRequired: false,
+              },
+              {
+                name: "x-control-token",
+                description: "Control plane token for authorized client access",
+                isSecret: true,
+                isRequired: false,
+              },
+            ],
+          },
+        ],
+      });
+    };
+
+    app.get("/.well-known/mcp", handleServerCard);
+    app.get("/.well-known/mcp.json", handleServerCard);
+    app.get("/mcp/server-card", handleServerCard);
+
+    // AI Catalog Discovery (SEP-2127)
+    app.get("/.well-known/ai-catalog.json", (req: Request, res: Response) => {
+      const origin = getBaseUrl(req);
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.json({
+        $schema: "https://agent-card.github.io/schemas/ai-catalog/v1.json",
+        version: "1.0",
+        name: "ShadowClaw AI Catalog",
+        servers: [
+          {
+            name: "shadow-claw",
+            card: `${origin}/.well-known/mcp.json`,
+          },
+        ],
+      });
     });
+
+    // MCP Servers Manifest (Discussion #1147)
+    app.get("/.well-known/mcp/servers.json", (req: Request, res: Response) => {
+      const origin = getBaseUrl(req);
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.json({
+        version: "1.0",
+        servers: [
+          {
+            name: "shadow-claw",
+            description: "ShadowClaw Browser-Native AI Assistant MCP Server",
+            endpoint: `${origin}/mcp`,
+            capabilities: ["tools", "extensions"],
+            card: `${origin}/.well-known/mcp.json`,
+          },
+        ],
+      });
+    });
+
+    // Protected Resource Metadata (RFC 9728)
+    const handleProtectedResource = (req: Request, res: Response) => {
+      const origin = getBaseUrl(req);
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.json({
+        resource: `${origin}/mcp`,
+        authorization_servers: [origin],
+        bearer_methods_supported: ["header"],
+        resource_documentation:
+          "https://xt-ml.github.io/shadow-claw/docs/subsystems/mcp-server.md",
+      });
+    };
+
+    app.get("/.well-known/oauth-protected-resource", handleProtectedResource);
+    app.get(
+      "/.well-known/oauth-protected-resource.json",
+      handleProtectedResource,
+    );
   }
 
   return mcpServer;

package/src/server/utils/packageVersion.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "@jest/globals";
+import { getPackageVersion } from "./packageVersion.js";
+
+describe("packageVersion", () => {
+  it("resolves the current package.json version as a valid semver string", () => {
+    const version = getPackageVersion();
+    expect(typeof version).toBe("string");
+    expect(version).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});

package/src/server/utils/packageVersion.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let cachedVersion: string | null = null;
+
+export function getPackageVersion(): string {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+
+  try {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    let dir = currentDir;
+    while (dir && dir !== path.dirname(dir)) {
+      const candidate = path.join(dir, "package.json");
+      if (fs.existsSync(candidate)) {
+        const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
+        if (pkg.version) {
+          const versionStr = String(pkg.version);
+          cachedVersion = versionStr;
+          return versionStr;
+        }
+      }
+      dir = path.dirname(dir);
+    }
+  } catch {}
+
+  const fallback = "1.27.1";
+  cachedVersion = fallback;
+  return fallback;
+}

package/src/service-worker/fetch-proxy-rules.test.ts

@@ -105,4 +105,77 @@ describe("shouldBypassFetchProxy", () => {
       shouldBypassFetchProxy(classAUrl, "https://xt-ml.github.io/shadow-claw/"),
     ).toBe(true);
   });
+
+  it("bypasses single-label local hostnames like hostname", () => {
+    const pushUrl = new URL("https://hostname:8888/push/vapid-public-key");
+    expect(
+      shouldBypassFetchProxy(pushUrl, "https://xt-ml.github.io/shadow-claw/"),
+    ).toBe(true);
+
+    const taskUrl = new URL("https://hostname:8888/schedule/tasks");
+    expect(
+      shouldBypassFetchProxy(taskUrl, "https://xt-ml.github.io/shadow-claw/"),
+    ).toBe(true);
+  });
+
+  it("bypasses mDNS .local and local network domain endpoints", () => {
+    const localDomainUrl = new URL(
+      "https://hostname.local:8888/api/control/events",
+    );
+    expect(
+      shouldBypassFetchProxy(
+        localDomainUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+      ),
+    ).toBe(true);
+
+    const lanDomainUrl = new URL("https://server.lan:8888/schedule/tasks");
+    expect(
+      shouldBypassFetchProxy(
+        lanDomainUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+      ),
+    ).toBe(true);
+  });
+
+  it("bypasses built-in backend routes even on custom domains", () => {
+    const pushSubscribeUrl = new URL(
+      "https://custom.example.com/push/subscribe",
+    );
+    expect(
+      shouldBypassFetchProxy(
+        pushSubscribeUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+      ),
+    ).toBe(true);
+
+    const scheduleUrl = new URL("https://custom.example.com/schedule/tasks");
+    expect(
+      shouldBypassFetchProxy(
+        scheduleUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+      ),
+    ).toBe(true);
+
+    const controlUrl = new URL(
+      "https://custom.example.com/api/control/messages",
+    );
+    expect(
+      shouldBypassFetchProxy(
+        controlUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+      ),
+    ).toBe(true);
+  });
+
+  it("bypasses requests destined for the proxy server itself", () => {
+    const targetUrl = new URL("https://proxy.example.com:9000/api/custom");
+    expect(
+      shouldBypassFetchProxy(
+        targetUrl,
+        "https://xt-ml.github.io/shadow-claw/",
+        "https://proxy.example.com:9000/proxy",
+      ),
+    ).toBe(true);
+  });
 });

package/src/service-worker/fetch-proxy-rules.ts

@@ -16,14 +16,49 @@ const BYPASS_PROVIDERS = [
   "api.telegram.org",
 ];
 
+const BACKEND_ROUTE_PREFIXES = [
+  "/api/control/",
+  "/api/backup/",
+  "/api/activity-log/",
+  "/api/health",
+  "/push/",
+  "/schedule/",
+  "/mcp",
+  "/ws/",
+  "/peerjs/",
+];
+
+const LOCAL_DOMAINS = [".local", ".lan", ".home", ".internal"];
+
 export function shouldBypassFetchProxy(
   requestUrl: URL,
   locationOrigin: string,
+  proxyUrl?: string,
 ): boolean {
   if (requestUrl.origin === locationOrigin) {
     return true;
   }
 
+  // Never proxy requests directed to the proxy host itself (avoids self-proxy loops)
+  if (proxyUrl) {
+    try {
+      const proxyOrigin = new URL(proxyUrl, locationOrigin).origin;
+      if (requestUrl.origin === proxyOrigin) {
+        return true;
+      }
+    } catch (_) {}
+  }
+
+  // Never proxy requests to ShadowClaw built-in backend infrastructure routes
+  const pathname = requestUrl.pathname;
+  if (
+    BACKEND_ROUTE_PREFIXES.some(
+      (prefix) => pathname === prefix || pathname.startsWith(prefix),
+    )
+  ) {
+    return true;
+  }
+
   const hostname = requestUrl.hostname.toLowerCase();
 
   if (
@@ -62,5 +97,14 @@ export function shouldBypassFetchProxy(
     return true;
   }
 
+  // Local/private hostnames: single-label (no dots, e.g. "hostname") or local network domain suffixes
+  const isLocalHostname =
+    !hostname.includes(".") ||
+    LOCAL_DOMAINS.some((domain) => hostname.endsWith(domain));
+
+  if (isLocalHostname) {
+    return true;
+  }
+
   return false;
 }

package/src/service-worker/fetch-proxy.ts

@@ -239,7 +239,7 @@ self.addEventListener("fetch", (event: FetchEvent) => {
     }
   }
 
-  if (shouldBypassFetchProxy(requestUrl, location.origin)) {
+  if (shouldBypassFetchProxy(requestUrl, location.origin, proxyUrl)) {
     return;
   }
 

package/src/subsystems/channels/imessage.test.ts

@@ -291,4 +291,40 @@ describe("IMessageChannel", () => {
     const mode = await channel.ensureApiMode();
     expect(mode).toBe("beeper-desktop");
   });
+
+  it("ensureConnected aborts hanging poll, resets backoff, and launches fresh poll", async () => {
+    const channel = new IMessageChannel();
+    channel.configure("https://bridge.example", "secret", []);
+
+    let pollCount = 0;
+    jest.spyOn(channel, "requestJson").mockImplementation((async (
+      _path: string,
+      _opts: any,
+      _timeout: number,
+      signal?: AbortSignal,
+    ) => {
+      pollCount++;
+      return new Promise((_resolve, reject) => {
+        signal?.addEventListener("abort", () => {
+          reject(new DOMException("Aborted", "AbortError"));
+        });
+      });
+    }) as any);
+
+    channel.start();
+    expect(channel.running).toBe(true);
+    expect(pollCount).toBe(1);
+
+    // Simulate high backoff
+    channel.reconnectDelayMs = 30000;
+    const oldAbort = channel.abortController;
+
+    channel.ensureConnected();
+
+    expect(channel.reconnectDelayMs).toBe(1000);
+    expect(oldAbort?.signal.aborted).toBe(true);
+    expect(pollCount).toBe(2);
+
+    channel.stop();
+  });
 });

package/src/subsystems/channels/imessage.ts

@@ -134,6 +134,17 @@ export class IMessageChannel implements Channel {
     void this.poll();
   }
 
+  ensureConnected(): void {
+    if (!this.isConfigured() || !this.running) {
+      return;
+    }
+
+    this.reconnectDelayMs = 1000;
+    this.abortController?.abort();
+    this.abortController = new AbortController();
+    void this.poll();
+  }
+
   stop(): void {
     this.running = false;
     this.abortController?.abort();

package/src/subsystems/channels/peerjs.test.ts

@@ -38,11 +38,19 @@ class MockDataConnection {
 
 class MockPeer {
   destroyed = false;
+  disconnected = false;
+  open = true;
   id: string;
+  reconnect = jest.fn(() => {
+    this.disconnected = false;
+    this.open = true;
+    this.emit("open", this.id);
+  });
   private handlers: Map<string, EventHandler[]> = new Map();
 
   constructor(id: string, _opts?: unknown) {
     this.id = id;
+    this.open = true;
     setTimeout(() => this.emit("open", id), 0);
   }
 
@@ -55,6 +63,7 @@ class MockPeer {
 
   destroy() {
     this.destroyed = true;
+    this.open = false;
     this.emit("disconnected");
   }
 
@@ -829,5 +838,52 @@ describe("PeerJsChannel", () => {
       expect((ch as any)._isTrustedPeer("cli-12345")).toBe(true);
       expect((ch as any)._isTrustedPeer("other-12345")).toBe(false);
     });
+
+    it("ensureConnected reconnects disconnected peer and resets backoff", async () => {
+      const ch = new PeerJsChannel();
+      ch.configure("my-test-peer", []);
+      ch.start();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const peer = (ch as any).peer as MockPeer;
+      expect(peer).toBeDefined();
+
+      // Simulate disconnect
+      peer.disconnected = true;
+      peer.open = false;
+      (ch as any)._reconnectAttempts = 3;
+      (ch as any)._reconnectTimer = setTimeout(() => {}, 8000);
+
+      ch.ensureConnected(false);
+
+      expect((ch as any)._reconnectTimer).toBeNull();
+      expect((ch as any)._reconnectAttempts).toBe(0);
+      expect(peer.reconnect).toHaveBeenCalled();
+
+      ch.stop();
+    });
+
+    it("ensureConnected re-initializes a destroyed peer instance", async () => {
+      const ch = new PeerJsChannel();
+      ch.configure("my-test-peer-2", []);
+      ch.start();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const initialPeer = (ch as any).peer as MockPeer;
+      expect(initialPeer).toBeDefined();
+
+      // Destroy peer instance
+      initialPeer.destroy();
+      expect(initialPeer.destroyed).toBe(true);
+
+      ch.ensureConnected(true);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      const newPeer = (ch as any).peer as MockPeer;
+      expect(newPeer).not.toBe(initialPeer);
+      expect(newPeer.destroyed).toBe(false);
+
+      ch.stop();
+    });
   });
 });

package/src/subsystems/channels/peerjs.ts

@@ -346,6 +346,35 @@ export class PeerJsChannel implements Channel {
     this._initPeer();
   }
 
+  ensureConnected(force: boolean = false): void {
+    if (!this.running || !this.isConfigured()) {
+      return;
+    }
+
+    if (this._reconnectTimer !== null) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    this._reconnectAttempts = 0;
+
+    const peer = this.peer as any;
+    if (!peer || peer.destroyed || (force && !peer.open)) {
+      if (peer && !peer.destroyed) {
+        try {
+          peer.destroy();
+        } catch (_) {}
+      }
+      this.peer = null;
+      this._initPeer();
+    } else if (peer.disconnected) {
+      try {
+        peer.reconnect?.();
+      } catch {
+        this._initPeer();
+      }
+    }
+  }
+
   stop(): void {
     this.running = false;
     if (this._reconnectTimer !== null) {

package/src/subsystems/channels/telegram.test.ts

@@ -508,4 +508,42 @@ describe("TelegramChannel", () => {
       ),
     ).toBe(true);
   });
+
+  it("ensureConnected aborts hanging poll, resets backoff, and launches fresh poll", async () => {
+    const channel = new TelegramChannel();
+    channel.configure("test-token", ["123"]);
+
+    let fetchCount = 0;
+    jest.spyOn(globalThis, "fetch").mockImplementation((async (
+      _url: any,
+      opts: any,
+    ) => {
+      fetchCount++;
+      // Return a promise that hangs until aborted
+      return new Promise((_resolve, reject) => {
+        opts?.signal?.addEventListener("abort", () => {
+          reject(new DOMException("Aborted", "AbortError"));
+        });
+      });
+    }) as any);
+
+    channel.start();
+    expect(channel.running).toBe(true);
+    expect(fetchCount).toBe(1);
+
+    // Simulate high backoff delay
+    channel.pollRetryDelayMs = 30_000;
+
+    const oldSessionId = channel.pollSessionId;
+    const oldAbort = channel.abortController;
+
+    channel.ensureConnected();
+
+    expect(channel.pollRetryDelayMs).toBe(1_000);
+    expect(oldAbort?.signal.aborted).toBe(true);
+    expect(channel.pollSessionId).toBe(oldSessionId + 1);
+    expect(fetchCount).toBe(2);
+
+    channel.stop();
+  });
 });

package/src/subsystems/channels/telegram.ts

@@ -117,6 +117,19 @@ export class TelegramChannel implements Channel {
     void this.poll(sessionId, controller);
   }
 
+  ensureConnected(): void {
+    if (!this.token || !this.running) {
+      return;
+    }
+
+    this.resetPollBackoff();
+    this.abortController?.abort();
+    const sessionId = ++this.pollSessionId;
+    const controller = new AbortController();
+    this.abortController = controller;
+    void this.poll(sessionId, controller);
+  }
+
   stop(): void {
     this.running = false;
     this.resetPollBackoff();

package/src/subsystems/channels/types.ts

@@ -26,8 +26,10 @@ export type KnownChannelType =
   | "telegram";
 
 export interface Channel {
+  ensureConnected?(force?: boolean): void;
   onMessage(callback: ChannelMessageCallback): void;
   onTyping?(callback: ChannelTypingCallback): void;
+  running?: boolean;
   send(
     groupId: string,
     text: string,