fix(policy): switch npm preset to L4 tunnel for undici CONNECT compatibility (#3024)

Switch npm/Yarn registry policy to L4 pass-through so Node 22 undici can use CONNECT tunnels through HTTPS_PROXY without REST-mode method inspection resetting tarball downloads.\n\nKeep PyPI on REST GET/HEAD rules, add regression coverage for npm L4 behavior, and update the security guidance to document the npm-specific L4 compatibility exception.\n\nSigned-off-by: Yimo Jiang <yimoj@nvidia.com>\nSigned-off-by: Aaron Erickson <aerickson@nvidia.com>

Author: yimoj

docs/security/best-practices.md

@@ -161,7 +161,7 @@ Endpoint rules restrict allowed HTTP methods and URL paths.
 
 | Aspect | Detail |
 |---|---|
-| Default | Some endpoints allow GET and POST on `/**` (for example, `clawhub.ai`). Others restrict methods and paths to specific API routes (for example, `integrate.api.nvidia.com` allows POST only to inference and embedding paths and GET to model listings). Read-only endpoints such as `docs.openclaw.ai` allow GET only. The `npm_registry` baseline entry and the `npm`/`pypi` presets are GET-only (plus HEAD for PyPI). |
+| Default | Some endpoints allow GET and POST on `/**` (for example, `clawhub.ai`). Others restrict methods and paths to specific API routes (for example, `integrate.api.nvidia.com` allows POST only to inference and embedding paths and GET to model listings). Read-only endpoints such as `docs.openclaw.ai`, the `npm_registry` baseline entry, and the `pypi` preset allow GET only (PyPI also allows HEAD). The `npm` preset is an intentional exception: npm/Yarn registry traffic uses L4 pass-through for Node 22 undici CONNECT compatibility. |
 | What you can change | Add methods (PUT, DELETE, PATCH) or restrict paths to specific prefixes. |
 | Risk if relaxed | Allowing all methods on an API endpoint gives the agent write and delete access. For example, allowing DELETE on `api.github.com` lets the agent delete repositories. |
 | Recommendation | Use GET-only rules for endpoints that the agent only reads. Add write methods only for endpoints where the agent must create or modify resources. Restrict paths to specific API routes when possible. |
@@ -176,7 +176,7 @@ The `protocol` field on an endpoint controls whether the proxy also inspects ind
 | Default | Endpoints without a `protocol` field use L4-only enforcement: the proxy checks host, port, and binary identity, then relays the TCP stream without inspecting payloads. Setting `protocol: rest` enables L7 inspection: the proxy auto-detects and terminates TLS, then evaluates each HTTP request's method and path against the endpoint's `rules` or `access` preset. |
 | What you can change | Add `protocol: rest` to an endpoint to enable per-request HTTP inspection. Use the `access` preset (`full`, `read-only`, `read-write`) or explicit `rules` to control allowed methods and paths. |
 | Risk if relaxed | L4-only endpoints (no `protocol` field) allow the agent to send any data through the tunnel after the initial connection is permitted. The proxy cannot see or filter the HTTP method, path, or body. The `access: full` preset with `protocol: rest` enables inspection but allows all methods and paths, so it does not restrict what the agent can do at the HTTP level. |
-| Recommendation | Use `protocol: rest` with specific `rules` for REST APIs where you want method and path control. Use `protocol: rest` with `access: read-only` for read-only endpoints. Omit `protocol` only for non-HTTP protocols (WebSocket, gRPC streaming) or endpoints that do not need HTTP inspection. |
+| Recommendation | Use `protocol: rest` with specific `rules` for REST APIs where you want method and path control. Use `protocol: rest` with `access: read-only` for read-only endpoints. Omit `protocol` only for non-HTTP protocols (WebSocket, gRPC streaming), endpoints that do not need HTTP inspection, or documented compatibility exceptions that require a client-managed CONNECT tunnel. |
 
 ### Operator Approval Flow
 
@@ -201,7 +201,7 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for
 | `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `gh` and `git`. |
 | `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. |
 | `jira` | Atlassian Jira API. | Gives agent read/write access to project issues and comments. |
-| `npm` | npm and Yarn registries (GET-only). | Allows installing arbitrary npm packages, which may contain malicious code. Publishing is blocked. |
+| `npm` | npm and Yarn registries via L4 pass-through. | Allows installing arbitrary npm packages, which may contain malicious code. OpenShell still gates by host, port, and binary, but does not inspect HTTP method, path, or body for this preset. |
 | `outlook` | Microsoft 365, Outlook. | Gives agent access to email. |
 | `pypi` | Python Package Index (GET and HEAD only). | Allows installing arbitrary Python packages, which may contain malicious code. Publishing is blocked. |
 | `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. |
@@ -533,7 +533,7 @@ The following patterns weaken security without providing meaningful benefit.
 
 | Mistake | Why it matters | What to do instead |
 |---------|---------------|-------------------|
-| Omitting `protocol: rest` on REST API endpoints | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. |
+| Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. |
 | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. |
 | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. |
 | Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Run `nemoclaw <name> shields up` to lock config for always-on assistants handling sensitive data. |

nemoclaw-blueprint/policies/presets/npm.yaml

@@ -9,18 +9,18 @@ network_policies:
   npm_yarn:
     name: npm_yarn
     endpoints:
+      # L4 CONNECT tunnel. Node 22 undici issues HTTP CONNECT through
+      # HTTPS_PROXY for TLS tunneling; L7 REST-mode method inspection
+      # rejects CONNECT and causes ECONNRESET on tarball downloads
+      # (see #2767). L4 pass-through restores undici compatibility.
       - host: registry.npmjs.org
         port: 443
-        protocol: rest
-        enforcement: enforce
-        rules:
-          - allow: { method: GET, path: "/**" }
+        access: full
+        tls: skip
       - host: registry.yarnpkg.com
         port: 443
-        protocol: rest
-        enforcement: enforce
-        rules:
-          - allow: { method: GET, path: "/**" }
+        access: full
+        tls: skip
     binaries:
       - { path: /usr/local/bin/npm* }
       - { path: /usr/local/bin/npx* }

test/policies.test.ts

@@ -679,22 +679,34 @@ describe("policies", () => {
       }
     });
 
-    it("package-manager presets use protocol: rest with read-only rules", () => {
-      // Package managers only need read access to install packages.
-      // Using access: full opens a raw CONNECT tunnel that allows
-      // PUT/POST (publish, exfiltrate). Restrict via rest rules.
-      const packagePresets = ["pypi", "npm"];
-      for (const name of packagePresets) {
-        const content = requirePresetContent(policies.loadPreset(name));
-        expect(content).toBeTruthy();
-        expect(content.includes("access: full")).toBe(false);
-        expect(content.includes("protocol: rest")).toBe(true);
-        expect(content.includes("method: GET")).toBe(true);
-        // No write methods allowed
-        expect(content.includes("method: PUT")).toBe(false);
-        expect(content.includes("method: POST")).toBe(false);
-        expect(content.includes("method: DELETE")).toBe(false);
-      }
+    it("pypi preset uses protocol: rest with read-only rules", () => {
+      // PyPI only needs read access to install packages.
+      // PyPI's pip uses http.request() (not undici), so it goes through
+      // http-proxy-fix.js which rewrites FORWARD-mode to https.request,
+      // avoiding CONNECT entirely. protocol: rest is therefore safe and
+      // preferred for tighter L7 method enforcement.
+      const content = requirePresetContent(policies.loadPreset("pypi"));
+      expect(content).toBeTruthy();
+      expect(content.includes("access: full")).toBe(false);
+      expect(content.includes("protocol: rest")).toBe(true);
+      expect(content.includes("method: GET")).toBe(true);
+      // No write methods allowed
+      expect(content.includes("method: PUT")).toBe(false);
+      expect(content.includes("method: POST")).toBe(false);
+      expect(content.includes("method: DELETE")).toBe(false);
+    });
+
+    it("npm preset uses L4 tunnel for CONNECT compatibility (#2767)", () => {
+      // npm on Node 22 uses undici's built-in fetch which bypasses
+      // http.request() and issues CONNECT directly through HTTPS_PROXY.
+      // protocol: rest triggers L7 method inspection that rejects
+      // CONNECT, causing ECONNRESET on tarball downloads. access: full
+      // with tls: skip uses L4 tunneling that supports CONNECT.
+      const content = requirePresetContent(policies.loadPreset("npm"));
+      expect(content).toBeTruthy();
+      expect(content.includes("access: full")).toBe(true);
+      expect(content.includes("tls: skip")).toBe(true);
+      expect(content.includes("protocol: rest")).toBe(false);
     });
 
     it("outlook preset allows PATCH on graph.microsoft.com", () => {

test/validate-blueprint.test.ts

@@ -45,6 +45,7 @@ type Endpoint = {
   protocol?: string;
   enforcement?: string;
   access?: string;
+  tls?: string;
   rules?: Rule[];
   binaries?: Array<{ path: string }>;
 };
@@ -395,3 +396,40 @@ describe("huggingface preset", () => {
     }
   });
 });
+
+describe("npm preset", () => {
+  // Regression #2767: npm/Yarn registry endpoints used `protocol: rest`
+  // with only GET allowed. Node 22 undici issues HTTP CONNECT through
+  // HTTPS_PROXY for TLS tunneling; the L7 proxy rejects parallel CONNECT
+  // tunnels, causing NET:FAIL and ECONNRESET on tarball downloads.
+  // The fix switches to L4 tunnel mode.
+  const NPM_PRESET_PATH = new URL(
+    "../nemoclaw-blueprint/policies/presets/npm.yaml",
+    import.meta.url,
+  );
+  const npmPreset = loadYaml<PolicyPreset>(NPM_PRESET_PATH);
+
+  function npmEndpoints(): Endpoint[] {
+    const np = npmPreset.network_policies;
+    if (!np) return [];
+    const entry = np.npm_yarn;
+    return Array.isArray(entry?.endpoints) ? entry.endpoints : [];
+  }
+
+  const REGISTRY_HOSTS = ["registry.npmjs.org", "registry.yarnpkg.com"];
+
+  for (const host of REGISTRY_HOSTS) {
+    it(`regression #2767: ${host} uses L4 tunnel (access: full, tls: skip) for CONNECT compatibility`, () => {
+      const endpoints = npmEndpoints().filter((ep) => ep.host === host);
+      expect(endpoints.length).toBeGreaterThan(0);
+      for (const ep of endpoints) {
+        expect(ep.access).toBe("full");
+        expect(ep).toHaveProperty("tls", "skip");
+        // Must NOT use protocol: rest — that triggers L7 method inspection
+        // which rejects CONNECT tunnels from Node 22 undici.
+        expect(ep).not.toHaveProperty("protocol");
+        expect(ep).not.toHaveProperty("rules");
+      }
+    });
+  }
+});