shadow-claw 1.24.0 → 1.25.0

package/README.md

@@ -383,6 +383,7 @@ E2E test architecture: [`e2e/README.md`](e2e/README.md)
 
 ```bash
 npm run dev                  # Dev server (watch mode)
+npm run dev -- --https       # Dev server with opt-in HTTPS (auto-generates self-signed cert)
 npm start                    # Express server
 npm test                     # Jest (*.test.ts files live next to source)
 npm run e2e                  # Playwright E2E tests (e2e/*.test.ts)
@@ -413,7 +414,7 @@ npx shadow-claw webrtc listen                        # Start headless WebRTC Dat
 npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
 ```
 
-Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag. The control plane endpoint and token are printed to the console on server start.
+Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag, and supports HTTPS endpoints via `--https` (and `--insecure` for self-signed certs). The control plane endpoint and token are printed to the console on server start.
 
 ## License
 

package/bin/cli.mjs

@@ -173,6 +173,36 @@ async function handleDev(portArg, options) {
         .filter(Boolean),
     );
 
+    const isHttps = Boolean(
+      options.https ||
+      ["1", "true", "yes"].includes(
+        (process.env.SHADOWCLAW_HTTPS || "").toLowerCase().trim(),
+      ),
+    );
+    const certPath =
+      options.cert ||
+      (
+        process.env.SHADOWCLAW_TLS_CERT ||
+        process.env.SHADOWCLAW_CERT ||
+        ""
+      ).trim() ||
+      undefined;
+    const keyPath =
+      options.key ||
+      (
+        process.env.SHADOWCLAW_TLS_KEY ||
+        process.env.SHADOWCLAW_KEY ||
+        ""
+      ).trim() ||
+      undefined;
+    const sslDir = path.resolve(
+      contentRoot,
+      options.sslDir ||
+        process.env.SHADOWCLAW_SSL_DIR ||
+        process.env.SHADOWCLAW_TLS_DIR ||
+        ".cache/tls",
+    );
+
     await startServer({
       port,
       bindHost: host,
@@ -183,9 +213,14 @@ async function handleDev(portArg, options) {
       rootPath: distPublicDir,
       databaseDir,
       allowPrivateProxy: Boolean(options.allowPrivateProxy),
+      https: isHttps,
+      certPath,
+      keyPath,
+      sslDir,
     });
 
-    const localUrl = `http://${host}:${port}`;
+    const protocol = isHttps ? "https" : "http";
+    const localUrl = `${protocol}://${host}:${port}`;
     if (options.open) {
       openBrowser(localUrl);
     }
@@ -218,6 +253,13 @@ program
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--https", "Enable HTTPS dev server", false)
+  .option("--cert <path>", "Path to existing TLS certificate file")
+  .option("--key <path>", "Path to existing TLS private key file")
+  .option(
+    "--ssl-dir <path>",
+    "Directory for TLS certificate generation/storage",
+  )
   .option("-v, --verbose", "Enable verbose request/proxy logging", false)
   .option("--open", "Automatically open default browser", false)
   .action(handleDev);
@@ -245,6 +287,13 @@ program
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--https", "Enable HTTPS dev server", false)
+  .option("--cert <path>", "Path to existing TLS certificate file")
+  .option("--key <path>", "Path to existing TLS private key file")
+  .option(
+    "--ssl-dir <path>",
+    "Directory for TLS certificate generation/storage",
+  )
   .option("-v, --verbose", "Enable verbose request/proxy logging", false)
   .option("--open", "Automatically open default browser", false)
   .action(handleDev);
@@ -276,6 +325,13 @@ program
     "Allow proxy to reach private/loopback addresses",
     false,
   )
+  .option("--https", "Enable HTTPS dev server", false)
+  .option("--cert <path>", "Path to existing TLS certificate file")
+  .option("--key <path>", "Path to existing TLS private key file")
+  .option(
+    "--ssl-dir <path>",
+    "Directory for TLS certificate generation/storage",
+  )
   .option("-v, --verbose", "Enable verbose request/proxy logging", false)
   .option("--open", "Automatically open default browser", false)
   .action(async (portArg, options) => {
@@ -328,6 +384,36 @@ program
           .filter(Boolean),
       );
 
+      const isHttps = Boolean(
+        options.https ||
+        ["1", "true", "yes"].includes(
+          (process.env.SHADOWCLAW_HTTPS || "").toLowerCase().trim(),
+        ),
+      );
+      const certPath =
+        options.cert ||
+        (
+          process.env.SHADOWCLAW_TLS_CERT ||
+          process.env.SHADOWCLAW_CERT ||
+          ""
+        ).trim() ||
+        undefined;
+      const keyPath =
+        options.key ||
+        (
+          process.env.SHADOWCLAW_TLS_KEY ||
+          process.env.SHADOWCLAW_KEY ||
+          ""
+        ).trim() ||
+        undefined;
+      const sslDir = path.resolve(
+        contentRoot,
+        options.sslDir ||
+          process.env.SHADOWCLAW_SSL_DIR ||
+          process.env.SHADOWCLAW_TLS_DIR ||
+          ".cache/tls",
+      );
+
       await startServer({
         port,
         bindHost: host,
@@ -338,9 +424,14 @@ program
         rootPath: distPublicDir,
         databaseDir,
         allowPrivateProxy: Boolean(options.allowPrivateProxy),
+        https: isHttps,
+        certPath,
+        keyPath,
+        sslDir,
       });
 
-      const localUrl = `http://${host}:${port}`;
+      const protocol = isHttps ? "https" : "http";
+      const localUrl = `${protocol}://${host}:${port}`;
       if (options.open) {
         openBrowser(localUrl);
       }
@@ -478,6 +569,11 @@ program
     "Use TLS (wss://) for the signaling server (for listen)",
     false,
   )
+  .option(
+    "--https",
+    "Alias for --secure: use TLS (wss://) for the signaling server",
+    false,
+  )
   .option(
     "--trusted-peer <id>",
     "Accept connections only from this peer ID (repeatable, for listen)",
@@ -486,6 +582,11 @@ program
   )
   .option("--verbose", "Verbose connection logging (for listen)", false)
   .option("--renew-peer-id", "Renew CLI peer ID before listening", false)
+  .option(
+    "-k, --insecure",
+    "Allow self-signed TLS certificates for the signaling server (wss://)",
+    true,
+  )
   .action(async (action, customId, options) => {
     if (action === "listen") {
       await runWebRtcListenCommand(options);
@@ -507,6 +608,8 @@ program
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
+  .option("--https", "Connect to server via HTTPS", false)
+  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(
@@ -530,6 +633,8 @@ program
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
+  .option("--https", "Connect to server via HTTPS", false)
+  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option("--renew-peer-id", "Renew WebRTC CLI peer ID before sending", false)
@@ -552,6 +657,8 @@ program
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
+  .option("--https", "Connect to server via HTTPS", false)
+  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(
@@ -575,6 +682,8 @@ program
   .option("--host <host>", "Control plane host")
   .option("--port <port>", "Control plane port")
   .option("--token <token>", "Control token")
+  .option("--https", "Connect to server via HTTPS", false)
+  .option("-k, --insecure", "Allow self-signed TLS certificates", true)
   .option("--transport <transport>", "Transport to use: http | webrtc", "http")
   .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
   .option(

package/bin/commands/webrtc-listen.mjs

@@ -156,7 +156,23 @@ export async function runWebRtcListenCommand(options = {}) {
     ? parseInt(options.port, 10)
     : parseInt(process.env.SHADOWCLAW_PORT || "8888", 10);
   const peerPath = options.path || "/";
-  const secure = Boolean(options.secure);
+  const secure = Boolean(
+    options.secure ||
+    options.https ||
+    ["1", "true", "yes"].includes(
+      (process.env.SHADOWCLAW_HTTPS || "").toLowerCase().trim(),
+    ),
+  );
+  // --insecure / -k: allow self-signed TLS certificates (default: true for dev)
+  const rejectUnauthorized =
+    options.insecure === false ||
+    ["0", "false", "no"].includes(
+      (process.env.SHADOWCLAW_TLS_REJECT_UNAUTHORIZED || "")
+        .toLowerCase()
+        .trim(),
+    )
+      ? true
+      : false;
   const trustedPeerIds = options.trustedPeer
     ? Array.isArray(options.trustedPeer)
       ? options.trustedPeer
@@ -169,6 +185,9 @@ export async function runWebRtcListenCommand(options = {}) {
   console.log(
     `Signaling server   : ${secure ? "wss" : "ws"}://${host}:${port}${peerPath}`,
   );
+  if (secure && !rejectUnauthorized) {
+    console.log(`TLS verification   : disabled (self-signed cert allowed)`);
+  }
   if (trustedPeerIds.length > 0) {
     console.log(`Trusted peers      : ${trustedPeerIds.join(", ")}`);
   } else {
@@ -186,6 +205,7 @@ export async function runWebRtcListenCommand(options = {}) {
     port,
     path: peerPath,
     secure,
+    rejectUnauthorized,
     trustedPeerIds,
     peerId: options.peerId,
     cacheDir: options.cacheDir,

package/bin/utils/control-client.mjs

@@ -72,7 +72,17 @@ export class CliControlClient {
     this.port =
       options.port || parseInt(process.env.SHADOWCLAW_PORT || "8888", 10);
     this.token = options.token || resolveControlToken(options.token);
-    this.protocol = options.protocol || "http";
+    const isHttps = Boolean(
+      options.https ||
+      ["1", "true", "yes"].includes(
+        (process.env.SHADOWCLAW_HTTPS || "").toLowerCase().trim(),
+      ),
+    );
+    this.protocol = options.protocol || (isHttps ? "https" : "http");
+    this.rejectUnauthorized =
+      options.rejectUnauthorized !== undefined
+        ? Boolean(options.rejectUnauthorized)
+        : Boolean(options.insecure === false);
     this.transport = options.transport || "http";
     this._webrtcClient =
       this.transport === "webrtc"
@@ -81,6 +91,7 @@ export class CliControlClient {
             port: this.port,
             path: options.peerPath || "/",
             secure: this.protocol === "https",
+            rejectUnauthorized: this.rejectUnauthorized,
             peerId: options.peerId,
             cacheDir: options.cacheDir,
             renewPeerId: Boolean(options.renewPeerId),
@@ -99,35 +110,38 @@ export class CliControlClient {
         headers["x-control-token"] = this.token;
       }
 
-      const req = client.request(
-        {
-          hostname: this.host,
-          port: this.port,
-          path: reqPath,
-          method,
-          headers,
-          timeout,
-        },
-        (res) => {
-          let data = "";
-          res.on("data", (chunk) => (data += chunk));
-          res.on("end", () => {
-            let parsed = data;
-            try {
-              parsed = JSON.parse(data);
-            } catch (_) {}
-
-            if (res.statusCode >= 200 && res.statusCode < 300) {
-              resolve(parsed);
-            } else {
-              const errMsg =
-                parsed?.error ||
-                `HTTP request failed with status ${res.statusCode}: ${data}`;
-              reject(new Error(errMsg));
-            }
-          });
-        },
-      );
+      const reqOptions = {
+        hostname: this.host,
+        port: this.port,
+        path: reqPath,
+        method,
+        headers,
+        timeout,
+      };
+
+      if (this.protocol === "https") {
+        reqOptions.rejectUnauthorized = this.rejectUnauthorized;
+      }
+
+      const req = client.request(reqOptions, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          let parsed = data;
+          try {
+            parsed = JSON.parse(data);
+          } catch (_) {}
+
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(parsed);
+          } else {
+            const errMsg =
+              parsed?.error ||
+              `HTTP request failed with status ${res.statusCode}: ${data}`;
+            reject(new Error(errMsg));
+          }
+        });
+      });
 
       req.on("error", (err) => {
         reject(

package/bin/utils/control-client.test.mjs

@@ -80,4 +80,14 @@ describe("CliControlClient", () => {
     const backups = await client.listBackups();
     expect(Array.isArray(backups)).toBe(true);
   });
+
+  it("detects HTTPS protocol from options and environment", () => {
+    const client1 = new CliControlClient({ https: true });
+    expect(client1.protocol).toBe("https");
+
+    process.env.SHADOWCLAW_HTTPS = "1";
+    const client2 = new CliControlClient();
+    expect(client2.protocol).toBe("https");
+    delete process.env.SHADOWCLAW_HTTPS;
+  });
 });

package/bin/utils/webrtc-control-client.mjs

@@ -203,6 +203,7 @@ export class CliWebRtcControlClient {
       options.port || parseInt(process.env.SHADOWCLAW_PORT || "8888", 10);
     this.path = options.path || "/";
     this.secure = options.secure ?? false;
+    this.rejectUnauthorized = options.rejectUnauthorized ?? false;
     this.peer = null;
     this.cacheDir = options.cacheDir;
     this.cliPeerId =
@@ -221,12 +222,19 @@ export class CliWebRtcControlClient {
     const Peer = mod.default?.Peer || mod.default || mod.Peer;
 
     return new Promise((resolve, reject) => {
-      const peer = new Peer(this.cliPeerId, {
+      const peerConfig = {
         host: this.host,
         port: this.port,
         path: this.path,
         secure: this.secure,
-      });
+      };
+
+      if (this.secure) {
+        peerConfig.config = { iceServers: [] };
+        peerConfig.wsOptions = { rejectUnauthorized: this.rejectUnauthorized };
+      }
+
+      const peer = new Peer(this.cliPeerId, peerConfig);
 
       this.peer = peer;
 
@@ -409,6 +417,7 @@ export class CliWebRtcListener {
       options.port || parseInt(process.env.SHADOWCLAW_PORT || "8888", 10);
     this.path = options.path || "/";
     this.secure = options.secure ?? false;
+    this.rejectUnauthorized = options.rejectUnauthorized ?? false;
     this.cacheDir = options.cacheDir;
     this.verbose = options.verbose ?? false;
     this.handlers = options.handlers || {};
@@ -602,12 +611,22 @@ export class CliWebRtcListener {
     return new Promise((resolve, reject) => {
       let isOpened = false;
 
-      const peer = new Peer(this.cliPeerId, {
+      const peerConfig = {
         host: this.host,
         port: this.port,
         path: this.path,
         secure: this.secure,
-      });
+      };
+
+      // When using self-signed certificates (typical for local dev), Node's
+      // WebSocket client rejects the connection by default. Pass rejectUnauthorized
+      // via PeerJS's ws-specific config option to allow self-signed certs.
+      if (this.secure) {
+        peerConfig.config = { iceServers: [] };
+        peerConfig.wsOptions = { rejectUnauthorized: this.rejectUnauthorized };
+      }
+
+      const peer = new Peer(this.cliPeerId, peerConfig);
 
       this._peer = peer;
       this._running = true;

package/dist/public/AGENTS.md

@@ -106,6 +106,13 @@ To prevent infinite execution loops, the system enforces a strict recursion guar
 - Do not call `executeTool` from provider loops without passing the active enabled tool list (`allowedTools`). Runtime allowlist checks are enforced in `executeTool` and are required even when schemas already constrain generation.
 - Conversation-level `pinnedMaxTokens` overrides are optional and must remain model-aware (clamped to provider/model output limits).
 
+### Private Network Access & Loopback Connections
+
+- **Service Worker Loopback Bypass:** The Service Worker fetch proxy (`src/service-worker/fetch-proxy-rules.ts`) unconditionally bypasses all loopback (`localhost`, `127.0.0.1`, `::1`, `[::1]`) and private IP ranges (`10.x`, `172.16-31.x`, `192.168.x`) so browser tabs hosted on static platforms (such as GitHub Pages or Cloudflare Pages) can connect directly to local servers without Service Worker interception.
+- **Client `targetAddressSpace` Signaling:** Outgoing client fetch requests targeting local or private network endpoints (`control-plane-client.ts`, `backup-controller.ts`, `push-client.ts`, `task.ts`, and `fetch-proxy.ts`) must supply `targetAddressSpace: 'loopback'` (or `'private'`) for Chromium Private Network Access (PNA) compliance.
+- **Server PNA & Cross-Origin Headers:** Server endpoints set `Access-Control-Allow-Private-Network: true` on both preflight (`OPTIONS`) and cross-origin responses, and trust `.github.io` / `.pages.dev` / `allowedOrigins` origins for browser integration.
+
+
 ### HTML Sanitization & Trusted Types
 
 - **Explicit Pre-Sanitization:** All dynamically rendered HTML, inline SVGs, or iframe `srcdoc` values must be sanitized using DOMPurify (e.g., `sanitizeToTrustedHtml` or `sanitizeSrcdocHtml`) **before** being passed to the Trusted Types policy.
@@ -152,7 +159,7 @@ Markdown and HTML preview work should preserve the Settings-backed iframe host a
 ### CLI & Dual-Root Build Pipeline
 
 - **Dual-Root Path Resolution:** The build toolchain (`bin/build/build.mjs`) cleanly decouples `toolchainRoot` (the ShadowClaw package/repo root) from `contentRoot` (the consumer template project). In-repo builds (`resolve(contentRoot) === resolve(toolchainRoot)`) preserve the standalone in-tree compilation path. CLI/template consumer builds read pre-bundled web assets from `toolchainRoot/dist/public` and inject `pages/`, `site-config.json`, `assets/`, `.agents/`, and pretty routes from `contentRoot`, outputting to `<contentRoot>/dist/public`.
-- **CLI Commands (`bin/cli.mjs`):** The `shadow-claw` / `shadowclaw` CLI provides `build`, `dev`, `run`, `serve`, `init`, `clients`, `send`, `backup`, `tasks`, `webrtc`, and `peer-id` commands. It supports running dev servers programmatically via `startServer` (`src/server/server.ts`) with custom `--root-path` and `--database-dir` arguments.
+- **CLI Commands (`bin/cli.mjs`):** The `shadow-claw` / `shadowclaw` CLI provides `build`, `dev`, `run`, `serve`, `init`, `clients`, `send`, `backup`, `tasks`, `webrtc`, and `peer-id` commands. It supports running dev servers programmatically via `startServer` (`src/server/server.ts`) with custom `--root-path` and `--database-dir` arguments. Dev/run/serve commands accept `--https`, `--cert <path>`, `--key <path>`, and `--ssl-dir <path>` for opt-in HTTPS with auto-generated self-signed certs; control plane commands (`clients`, `send`, `backup`, `tasks`) accept `--https` and `-k, --insecure` to reach an HTTPS control plane server.
 - **Naming Conventions:** Refer to the product/brand in prose and documentation as **ShadowClaw**. Use kebab-case **`shadow-claw`** for package name, CLI commands (`npx shadow-claw`), repositories, directory paths, and custom elements.
 
 ## What to Avoid

package/dist/public/README.md

@@ -383,6 +383,7 @@ E2E test architecture: [`e2e/README.md`](e2e/README.md)
 
 ```bash
 npm run dev                  # Dev server (watch mode)
+npm run dev -- --https       # Dev server with opt-in HTTPS (auto-generates self-signed cert)
 npm start                    # Express server
 npm test                     # Jest (*.test.ts files live next to source)
 npm run e2e                  # Playwright E2E tests (e2e/*.test.ts)
@@ -413,7 +414,7 @@ npx shadow-claw webrtc listen                        # Start headless WebRTC Dat
 npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
 ```
 
-Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag. The control plane endpoint and token are printed to the console on server start.
+Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag, and supports HTTPS endpoints via `--https` (and `--insecure` for self-signed certs). The control plane endpoint and token are printed to the console on server start.
 
 ## License