fix(onboard): reject an unsafe custom endpoint URL before any mutation

Custom endpoint intake validated only userinfo, query, and fragment
components (#9106), so an endpoint URL containing shell metacharacters,
percent-encoded control characters, raw control characters, or a
non-HTTP(S) value passed intake and reached the SSRF preflight, the
endpoint probe, provider registration, session checkpoint writes, and
registry writes before any deep layer rejected it — and nothing
rejected percent-encoded control characters at all.

One composite classification, unsafeEndpointUrlViolation, now owns the
rejection rules, and every custom endpoint intake consumes it before
mutating state: onboarding intake (interactive and non-interactive),
inference set --endpoint-url before DNS resolution, and rebuild resume
preflight, which treats a violating recorded value as unknown metadata.
The character allowlist matches the container startup-command token set
plus "~", so an accepted URL stays inert across every downstream
consumer; the sets stay separate because command tokens and endpoint
URLs are distinct contracts. Rejection reasons are static and never
echo the input. The #9106 class keeps its established message and hint,
and the inference set shape check keeps its established message for the
classes it already owned.

The integration rows prove the QA contract directly: a subprocess
onboard with an unsafe URL exits 1 with no probe request and no
onboard-session.json or sandboxes.json write under the test HOME.

The url-utils fan-in budget moves 29 -> 30 for the one new
inference-set importer, the same adjustment #9119 made for this file.

Fixes #9301

Signed-off-by: Dongni Yang <dongniy@nvidia.com>

Author: Dongni-Yang

ci/source-architecture-budget.json

@@ -17,7 +17,7 @@
       "src/lib/core/json-types.ts": 36,
       "src/lib/core/ports.ts": 89,
       "src/lib/core/shell-quote.ts": 28,
-      "src/lib/core/url-utils.ts": 29,
+      "src/lib/core/url-utils.ts": 30,
       "src/lib/core/wait.ts": 36,
       "src/lib/credentials/store.ts": 46,
       "src/lib/inference/config.ts": 30,

docs/inference/custom-endpoint-security.mdx

@@ -36,6 +36,12 @@ Custom endpoint onboarding rejects endpoint URLs that contain userinfo, query, o
 NemoClaw does not forward those components to the endpoint.
 Configure the provider credential separately instead of putting it in the endpoint URL.
 
+Custom endpoint onboarding also rejects an endpoint URL that contains control characters, percent-encoded control characters, spaces, shell metacharacters, or other characters outside the URL-safe ASCII set.
+It also rejects an input that is not an absolute HTTP or HTTPS URL.
+This rejection happens before any network request, provider registration, registry write, or sandbox and image mutation, so a rejected input changes no NemoClaw state.
+The `inference set` command applies the same rejection classes to `--endpoint-url` before DNS resolution.
+Sandbox rebuild applies the same rejection classes to recorded custom endpoint metadata and treats a violating value as unknown.
+
 Managed provider defaults that do not provide an explicit custom endpoint through these paths are unaffected.
 
 Custom endpoint onboarding has one narrower operator-controlled exception for corporate inference gateways.

docs/reference/commands.mdx

@@ -4737,7 +4737,7 @@ Set them before running `$$nemoclaw onboard`.
 | `NEMOCLAW_LLAMACPP_RECIPE` | repository-owned managed-inference recipe ID | Selects the exact managed llama.cpp recipe when `NEMOCLAW_PROVIDER=install-llama-cpp`, including a compatible lower-priority profile. When unset, NemoClaw selects the unique highest-priority compatible automatic profile. An unknown recipe, an ambiguous selection, or a stale or incompatible readiness report fails before image, model, or runtime effects. |
 | `NEMOCLAW_MODEL` | model ID | Selects an explicit model for a non-interactive onboarding run. NemoClaw preserves it across a detected provider switch, even when it matches the recorded provider's default. When this variable is unset during such a switch, NemoClaw ignores the `NEMOCLAW_PROVIDER_MODEL` compatibility fallback and uses normal provider model selection. |
 | `NEMOCLAW_TOOL_DISCLOSURE` | `progressive` or `direct` | Selects progressive tool discovery or the prior direct-exposure behavior. Defaults to `progressive`; `--tool-disclosure` takes precedence when both are set. |
-| `NEMOCLAW_ENDPOINT_URL` | URL | Custom endpoint URL. Used together with `NEMOCLAW_PROVIDER=custom` for OpenAI-compatible endpoints or `NEMOCLAW_PROVIDER=anthropicCompatible` for Anthropic-compatible endpoints. Onboarding rejects a URL that contains userinfo, query, or fragment components. |
+| `NEMOCLAW_ENDPOINT_URL` | URL | Custom endpoint URL. Used together with `NEMOCLAW_PROVIDER=custom` for OpenAI-compatible endpoints or `NEMOCLAW_PROVIDER=anthropicCompatible` for Anthropic-compatible endpoints. Onboarding rejects a URL that contains userinfo, query, or fragment components. It also rejects a URL that contains control characters, percent-encoded control characters, spaces, shell metacharacters, or other characters outside the URL-safe ASCII set, and a value that is not an absolute HTTP or HTTPS URL. |
 | `NEMOCLAW_COMPATIBLE_AUTH_MODE` | `none` or unset | Explicitly selects no authentication for an HTTP OpenAI-compatible endpoint using `localhost`, `127.0.0.1`, or `[::1]` and port `8000`, `11434`, or `11435` during non-interactive onboarding. |
 | `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` | comma-separated exact hostnames or IP literals | Allows operator-owned RFC1918, CGNAT, or IPv6 unique local destinations through supported inference, managed MCP, and custom-policy registration paths. Link-local metadata and other reserved ranges remain blocked; DNS resolution and exact address pinning remain active; wildcards are not supported. |
 | `NEMOCLAW_TRUSTED_PRIVATE_INFERENCE_HOSTS` | comma-separated exact hostnames or IP literals | Inference-only compatibility alias. Inference onboarding combines entries from this variable and `NEMOCLAW_TRUSTED_PRIVATE_HOSTS`. |

src/lib/actions/inference-set-endpoint-security.test.ts

@@ -38,6 +38,29 @@ describe("custom inference endpoint DNS pinning", () => {
     ).rejects.toThrow(/endpoint-url is not allowed:.*private\/internal address/i);
   });
 
+  it.each([
+    [
+      "shell metacharacters",
+      "http://public.example/v1$(id)",
+      /endpoint-url must contain only URL-safe ASCII characters\./,
+    ],
+    [
+      "percent-encoded control characters",
+      "http://public.example/v1%0ainjected",
+      /endpoint-url must not contain percent-encoded control characters\./,
+    ],
+  ] as const)(
+    "rejects an endpoint URL with %s before DNS validation or any mutation (#9301)",
+    async (_label, endpointUrl, message) => {
+      const rewriteUrl = vi.fn(async () => {
+        throw new Error("unsafe endpoint unexpectedly reached DNS validation");
+      });
+
+      await expect(normalizeCustomEndpointUrl(endpointUrl, rewriteUrl)).rejects.toThrow(message);
+      expect(rewriteUrl).not.toHaveBeenCalled();
+    },
+  );
+
   it("pins validated public HTTP endpoints before they become durable metadata", async () => {
     const lookup = vi.fn(async () => [{ address: "93.184.216.34", family: 4 }]);
 

src/lib/actions/inference-set-route-containment.ts

@@ -11,6 +11,7 @@ import {
   type HttpsPinCredentialProviderType,
   isHttpsPinRuntimeEligible,
 } from "../inference/https-pin-runtime";
+import { unsafeEndpointUrlViolation } from "../core/url-utils";
 import { resolveSandboxGatewayName } from "../onboard/gateway-binding";
 import { isAllowedOpenShellSandboxBridgeUrl } from "../private-networks";
 import { ConfigUrlValidationError } from "../sandbox/config";
@@ -136,14 +137,25 @@ function normalizeCustomEndpointUrlWithoutDns(value: string | null | undefined):
   const raw = typeof value === "string" ? value.trim() : "";
   if (!raw)
     throw new InferenceSetError("endpoint-url is required for custom-compatible metadata.", 2);
+  let normalized: string;
   try {
-    return normalizeEndpointUrlShape(raw).normalized;
+    normalized = normalizeEndpointUrlShape(raw).normalized;
   } catch {
     throw new InferenceSetError(
       "endpoint-url must be a valid http(s) URL without userinfo, query, or fragment components.",
       2,
     );
   }
+  // #9301: reject control characters, percent-encoded control characters,
+  // spaces, and shell metacharacters before any provider, registry, or
+  // sandbox mutation, matching onboarding intake. The shape check above owns
+  // the userinfo, query, fragment, scheme, and parse classes and their
+  // established message.
+  const violation = unsafeEndpointUrlViolation(raw);
+  if (violation) {
+    throw new InferenceSetError(`endpoint-url ${violation.reason}`, 2);
+  }
+  return normalized;
 }
 
 export async function normalizeCustomEndpointUrl(

src/lib/actions/sandbox/rebuild-resume-config.test.ts

@@ -133,6 +133,12 @@ describe("getRebuildEndpointFromRegistry", () => {
     expect(
       getRebuildEndpointFromRegistry("compatible-endpoint", "https://example.test/v1?x=1"),
     ).toEqual({ known: false });
+    expect(
+      getRebuildEndpointFromRegistry("compatible-endpoint", "https://example.test/v1;id"),
+    ).toEqual({ known: false });
+    expect(
+      getRebuildEndpointFromRegistry("compatible-endpoint", "https://example.test/v1%0ax"),
+    ).toEqual({ known: false });
     expect(getRebuildEndpointFromRegistry("compatible-endpoint", "http://@example.test/v1")).toEqual(
       { known: false },
     );

src/lib/actions/sandbox/rebuild-resume-preflight.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { D, R } from "../../cli/terminal-style";
-import { endpointUrlHasUserinfoQueryOrFragment } from "../../core/url-utils";
+import { unsafeEndpointUrlViolation } from "../../core/url-utils";
 import type { InferenceSelection } from "../../inference/selection";
 import type { RegistryInferenceRoute } from "../../onboard/rebuild-route-handoff";
 import { isRecoveredProviderCredentialReuseSelectionKey } from "../../onboard/recovered-provider-reuse";
@@ -98,9 +98,9 @@ const SESSION_ONLY_ENDPOINT_PROVIDER_NAMES = new Set(
 
 export function canonicalCustomEndpointUrl(value: string | null | undefined): string | null {
   const raw = typeof value === "string" ? value.trim() : "";
-  // #9106: reject userinfo, query, and fragment components instead of
-  // stripping them, matching onboarding intake.
-  if (endpointUrlHasUserinfoQueryOrFragment(raw)) return null;
+  // #9106/#9301: reject unsafe endpoint metadata instead of stripping or
+  // forwarding it, matching onboarding intake.
+  if (unsafeEndpointUrlViolation(raw)) return null;
   try {
     const url = new URL(raw);
     const supportedProtocol = url.protocol === "http:" || url.protocol === "https:";

src/lib/core/url-utils.test.ts

@@ -12,6 +12,7 @@ import {
   normalizeProviderBaseUrl,
   parsePolicyPresetEnv,
   stripEndpointSuffix,
+  unsafeEndpointUrlViolation,
 } from "./url-utils";
 
 describe("compactText", () => {
@@ -145,6 +146,44 @@ describe("endpointUrlHasUserinfoQueryOrFragment", () => {
   });
 });
 
+describe("unsafeEndpointUrlViolation", () => {
+  it.each([
+    ["backtick command substitution", "http://127.0.0.1:8000/v1`whoami`", "unsupported-characters"],
+    ["dollar command substitution", "http://127.0.0.1:8000/v1$(id)", "unsupported-characters"],
+    ["semicolon in the path", "https://example.test/v1;id", "unsupported-characters"],
+    ["pipe in the path", "https://example.test/v1|cat", "unsupported-characters"],
+    ["ampersand in the path", "https://example.test/v1&x", "unsupported-characters"],
+    ["double quote", 'https://example.test/v1"q"', "unsupported-characters"],
+    ["single quote", "https://example.test/v1'q'", "unsupported-characters"],
+    ["interior space", "https://example.test/v 1", "unsupported-characters"],
+    ["encoded newline", "https://example.test/v1%0ainjected", "encoded-control-characters"],
+    ["encoded carriage return uppercase", "https://example.test/v1%0Dx", "encoded-control-characters"],
+    ["encoded NUL", "https://example.test/v1%00x", "encoded-control-characters"],
+    ["raw tab", "https://example.test/v\t1", "control-characters"],
+    ["raw newline", "https://example.test/v\n1", "control-characters"],
+    ["query string", "http://127.0.0.1:8000/v1?param=value", "userinfo-query-fragment"],
+    ["userinfo", "https://user:password@example.test/v1", "userinfo-query-fragment"],
+    ["non-HTTP scheme", "ftp://example.test/v1", "unsupported-protocol"],
+    ["scheme-less host and port", "localhost:8000/v1", "unsupported-protocol"],
+    ["scheme-less host path", "example.test/v1", "invalid-url"],
+    ["non-ASCII host", "https://exämple.test/v1", "unsupported-characters"],
+  ] as const)("rejects %s (#9301)", (_label, input, kind) => {
+    expect(unsafeEndpointUrlViolation(input)?.kind).toBe(kind);
+  });
+
+  it.each([
+    ["IPv6 loopback with port", "http://[::1]:8000/v1"],
+    ["host with port and deep path", "https://example.test:8443/deep/path-v1"],
+    ["path with URL-legal punctuation", "http://example.test/v1_x.y~z"],
+    ["percent-encoded space in the path", "https://example.test/v1/a%20b"],
+    ["clean origin", "https://proxy.example.com"],
+    ["empty input", ""],
+    ["whitespace input", "   "],
+  ] as const)("accepts %s (#9301)", (_label, input) => {
+    expect(unsafeEndpointUrlViolation(input)).toBeNull();
+  });
+});
+
 describe("isLoopbackHostname", () => {
   it.each([
     ["localhost", true],

src/lib/core/url-utils.ts

@@ -73,6 +73,71 @@ export function endpointUrlHasUserinfoQueryOrFragment(value: string | null | und
   }
 }
 
+// Endpoint URL inputs feed provider registration, registry writes, Dockerfile
+// ARGs, and container startup commands, so intake accepts only characters that
+// stay inert across every downstream consumer. The set matches the
+// startup-command token allowlist in onboard/docker-startup-command-env.ts
+// plus "~"; the two sets stay separate because command tokens and endpoint
+// URLs are distinct contracts.
+const ENDPOINT_URL_ALLOWED_CHARACTERS = /^[A-Za-z0-9_./:=,@%+\-[\]~]+$/u;
+const PERCENT_ENCODED_CONTROL_CHARACTER = /%(?:[01][0-9a-f]|7f)/i;
+
+export type EndpointUrlViolation = {
+  kind:
+    | "userinfo-query-fragment"
+    | "control-characters"
+    | "encoded-control-characters"
+    | "unsupported-characters"
+    | "invalid-url"
+    | "unsupported-protocol";
+  reason: string;
+};
+
+/**
+ * Classify an endpoint URL input that onboarding must reject before any
+ * network request, provider registration, registry write, or sandbox and
+ * image mutation (#9301). Returns null for an empty input (emptiness is a
+ * separate required-input error) and for a safe absolute HTTP(S) URL. The
+ * reason completes the sentence "Endpoint URL ..." and never echoes the
+ * input value.
+ */
+export function unsafeEndpointUrlViolation(
+  value: string | null | undefined,
+): EndpointUrlViolation | null {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  if (endpointUrlHasUserinfoQueryOrFragment(raw)) {
+    return {
+      kind: "userinfo-query-fragment",
+      reason: "must not contain userinfo, query, or fragment components.",
+    };
+  }
+  if (/[\p{Cc}\p{Cf}]/u.test(raw)) {
+    return { kind: "control-characters", reason: "must not contain control characters." };
+  }
+  if (PERCENT_ENCODED_CONTROL_CHARACTER.test(raw)) {
+    return {
+      kind: "encoded-control-characters",
+      reason: "must not contain percent-encoded control characters.",
+    };
+  }
+  if (!ENDPOINT_URL_ALLOWED_CHARACTERS.test(raw)) {
+    return {
+      kind: "unsupported-characters",
+      reason: "must contain only URL-safe ASCII characters.",
+    };
+  }
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return { kind: "unsupported-protocol", reason: "must use HTTP or HTTPS." };
+    }
+  } catch {
+    return { kind: "invalid-url", reason: "must be a valid HTTP or HTTPS URL." };
+  }
+  return null;
+}
+
 /** Return the bounded canonical form of a credential-free HTTP(S) provider endpoint. */
 export function canonicalEndpoint(
   value: string | null | undefined,

src/lib/onboard/setup-nim-selection.ts

@@ -3,8 +3,8 @@
 
 import {
   canonicalEndpoint,
-  endpointUrlHasUserinfoQueryOrFragment,
   normalizeProviderBaseUrl,
+  unsafeEndpointUrlViolation,
 } from "../core/url-utils";
 import { applyCompatibleEndpointContextWindow } from "../inference/compatible-endpoint-context";
 import type { TrustedPrivateEndpointCapability } from "../inference/endpoint-ssrf-preflight";
@@ -142,21 +142,24 @@ export async function resolveCompatibleEndpointSelection(args: {
   if (navigation === "exit") {
     exitOnboardFromPrompt();
   }
-  // #9106: reject instead of silently stripping components that NemoClaw
-  // cannot forward to the endpoint.
-  if (endpointUrlHasUserinfoQueryOrFragment(endpointInput)) {
-    console.error("  Endpoint URL must not contain userinfo, query, or fragment components.");
-    // canonicalEndpoint returns null unless the stripped base is a
-    // credential-free http(s) URL, so the hint never echoes userinfo or
-    // query values.
-    const strippedBaseUrl = canonicalEndpoint(
-      normalizeProviderBaseUrl(endpointInput, args.kind),
-      args.kind,
-    );
-    if (strippedBaseUrl) {
-      console.error(
-        `  NemoClaw does not forward these components to the endpoint. Use: ${strippedBaseUrl}`,
+  // #9106/#9301: reject unsafe endpoint input here, before any network
+  // request, provider registration, registry write, or sandbox mutation.
+  const endpointViolation = unsafeEndpointUrlViolation(endpointInput);
+  if (endpointViolation) {
+    console.error(`  Endpoint URL ${endpointViolation.reason}`);
+    if (endpointViolation.kind === "userinfo-query-fragment") {
+      // canonicalEndpoint returns null unless the stripped base is a
+      // credential-free http(s) URL, so the hint never echoes userinfo or
+      // query values.
+      const strippedBaseUrl = canonicalEndpoint(
+        normalizeProviderBaseUrl(endpointInput, args.kind),
+        args.kind,
       );
+      if (strippedBaseUrl) {
+        console.error(
+          `  NemoClaw does not forward these components to the endpoint. Use: ${strippedBaseUrl}`,
+        );
+      }
     }
     if (args.nonInteractive) {
       process.exit(1);