feat: input hardening against agent hallucinations (#370)

Add client-side validation that rejects malformed inputs from AI agents
before they reach the Sentry API. Agents hallucinate differently than
humans — they embed query params in IDs, double-encode URLs, and inject
path traversals.

## Changes

New module `src/lib/input-validation.ts` with four reusable validators:

| Validator | Purpose | Rejects |
|-----------|---------|---------|
| `rejectControlChars` | Block invisible characters | ASCII < 0x20 |
| `rejectPreEncoded` | Block double-encoding | `%XX` hex patterns |
| `validateResourceId` | Validate slugs and IDs | `?`, `#`, `%`,
whitespace, control chars |
| `validateEndpoint` | Block path traversal | `..` path segments |

Applied at three integration points:
- `parseOrgProjectArg` / `parseIssueArg` in `arg-parsing.ts` — validates
org slugs, project slugs, and issue identifiers
- `normalizeEndpoint` in `api.ts` — rejects `..` path traversal in
`sentry api` endpoints

## Attacks prevented

```bash
sentry issue list "my-org?query=foo"        # query injection → rejected
sentry project view "my-project#anchor"     # fragment injection → rejected
sentry issue view "CLI-G%20extra"           # double encoding → rejected
sentry api "../../admin/settings/"          # path traversal → rejected
```

## Tests

- 19 property-based tests for all validators
- 14 unit tests for arg-parsing injection hardening
- 7 unit tests for endpoint path traversal hardening
- All 3021 existing tests pass with zero regressions

Fixes #350

Author: BYK

AGENTS.md

@@ -9,6 +9,7 @@ import type { SentryContext } from "../context.js";
 import { rawApiRequest } from "../lib/api-client.js";
 import { buildCommand } from "../lib/command.js";
 import { ValidationError } from "../lib/errors.js";
+import { validateEndpoint } from "../lib/input-validation.js";
 import type { Writer } from "../types/index.js";
 
 type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
@@ -74,6 +75,9 @@ export function parseMethod(value: string): HttpMethod {
  * @internal Exported for testing
  */
 export function normalizeEndpoint(endpoint: string): string {
+  // Reject path traversal and control characters before processing
+  validateEndpoint(endpoint);
+
   // Remove leading slash if present (rawApiRequest handles the base URL)
   const trimmed = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
 

src/commands/api.ts

@@ -7,6 +7,7 @@
  */
 
 import { ContextError, ValidationError } from "./errors.js";
+import { validateResourceId } from "./input-validation.js";
 import type { ParsedSentryUrl } from "./sentry-url-parser.js";
 import { applySentryUrlContext, parseSentryUrl } from "./sentry-url-parser.js";
 import { isAllDigits } from "./utils.js";
@@ -294,7 +295,8 @@ function issueArgFromUrl(parsed: ParsedSentryUrl): ParsedIssueArg | null {
 
 /**
  * Parse a slash-delimited `org/project` string into a {@link ParsedOrgProject}.
- * Applies {@link normalizeSlug} to both components.
+ * Applies {@link normalizeSlug} to both components and validates against
+ * URL injection characters.
  */
 function parseSlashOrgProject(input: string): ParsedOrgProject {
   const slashIndex = input.indexOf("/");
@@ -308,6 +310,7 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
         'Invalid format: "/" requires a project slug (e.g., "/cli")'
       );
     }
+    validateResourceId(rawProject, "project slug");
     const np = normalizeSlug(rawProject);
     return {
       type: "project-search",
@@ -316,6 +319,7 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
     };
   }
 
+  validateResourceId(rawOrg, "organization slug");
   const no = normalizeSlug(rawOrg);
 
   if (!rawProject) {
@@ -328,6 +332,7 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
   }
 
   // "sentry/cli" → explicit org and project
+  validateResourceId(rawProject, "project slug");
   const np = normalizeSlug(rawProject);
   const normalized = no.normalized || np.normalized;
   return {
@@ -378,6 +383,7 @@ export function parseOrgProjectArg(arg: string | undefined): ParsedOrgProject {
   }
 
   // No slash → search for project across all orgs
+  validateResourceId(trimmed, "project slug");
   const np = normalizeSlug(trimmed);
   return {
     type: "project-search",
@@ -587,7 +593,10 @@ export function parseSlashSeparatedArg(
   const slashIdx = arg.indexOf("/");
 
   if (slashIdx === -1) {
-    // No slashes — plain ID
+    // No slashes — plain ID. Skip validation here because callers may
+    // do further processing (e.g., splitting newline-separated IDs).
+    // Downstream validators like validateHexId or validateTraceId provide
+    // format-specific validation.
     return { id: arg, targetArg: undefined };
   }
 
@@ -608,6 +617,10 @@ export function parseSlashSeparatedArg(
     throw new ContextError(idLabel, usageHint);
   }
 
+  // Validate the extracted ID against injection characters.
+  // The targetArg flows through parseOrgProjectArg which has its own validation.
+  validateResourceId(id, idLabel);
+
   return { id, targetArg };
 }
 
@@ -627,6 +640,11 @@ export function parseIssueArg(arg: string): ParsedIssueArg {
     );
   }
 
+  // Validate raw input against injection characters before parsing.
+  // Slashes are allowed (they're structural separators), but ?, #, %, whitespace,
+  // and control characters are never valid in issue identifiers.
+  validateResourceId(arg.replace(/\//g, ""), "issue identifier");
+
   // 1. Pure numeric → direct fetch by ID
   if (isAllDigits(arg)) {
     return { type: "numeric", id: arg };

src/lib/arg-parsing.ts

@@ -0,0 +1,189 @@
+/**
+ * Input Validation for Agent Hallucination Hardening
+ *
+ * Reusable validators that defend against malformed inputs from AI agents.
+ * Agents hallucinate differently than humans typo — they embed query params
+ * in resource IDs, double-encode URLs, and inject path traversals.
+ *
+ * These validators are applied at the CLI argument parsing layer so all
+ * commands benefit automatically. The Sentry API handles most of these
+ * server-side (404, 400), but client-side validation provides:
+ * - Better error messages with actionable suggestions
+ * - Faster failure without a network round-trip
+ * - Defense-in-depth against unexpected URL manipulation
+ *
+ * @see https://github.com/getsentry/cli/issues/350
+ */
+
+import { ValidationError } from "./errors.js";
+
+/**
+ * Characters that are never valid in Sentry resource identifiers (slugs, IDs).
+ * These would cause URL injection if interpolated into API paths.
+ *
+ * - `?` — query string injection
+ * - `#` — fragment injection
+ * - `%` — pre-URL-encoded values (double-encoding risk)
+ * - whitespace — breaks URL structure
+ */
+const RESOURCE_ID_FORBIDDEN = /[?#%\s]/;
+
+/**
+ * Matches `%XX` hex-encoded sequences (e.g., `%2F`, `%20`, `%3A`).
+ * Used to detect pre-encoded strings that would get double-encoded.
+ */
+const PRE_ENCODED_PATTERN = /%[0-9a-fA-F]{2}/;
+
+/**
+ * Matches ASCII control characters (code points 0x00–0x1F).
+ * These are invisible and have no valid use in CLI string inputs.
+ *
+ * Built via RegExp constructor to avoid lint warnings about literal
+ * control characters in regex patterns.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally matching control chars for input validation
+const CONTROL_CHAR_PATTERN = /[\x00-\x1f]/;
+
+/**
+ * Matches `..` path segments that could be used for path traversal.
+ * Anchored to segment boundaries (start/end of string or `/`).
+ */
+const PATH_TRAVERSAL_PATTERN = /(^|\/)\.\.(\/|$)/;
+
+/**
+ * Human-readable descriptions for the first forbidden character found.
+ * Provides clear context in error messages.
+ */
+function describeForbiddenChar(char: string): string {
+  const code = char.charCodeAt(0);
+
+  if (char === "?") {
+    return '"?" (query string)';
+  }
+  if (char === "#") {
+    return '"#" (URL fragment)';
+  }
+  if (char === "%") {
+    return '"%" (URL encoding)';
+  }
+  if (char === " ") {
+    return "a space";
+  }
+  if (char === "\t") {
+    return "a tab character";
+  }
+  if (char === "\n") {
+    return "a newline";
+  }
+  if (char === "\r") {
+    return "a carriage return";
+  }
+  if (char === "\0") {
+    return "a null byte";
+  }
+  // Generic control character
+  if (code < 0x20) {
+    return `control character (0x${code.toString(16).padStart(2, "0")})`;
+  }
+  // Other whitespace
+  return `whitespace character (U+${code.toString(16).padStart(4, "0")})`;
+}
+
+/**
+ * Reject ASCII control characters (below 0x20) in any string input.
+ *
+ * Control characters are invisible and have no valid use in CLI arguments.
+ * An agent could embed them to manipulate downstream processing.
+ *
+ * @param input - String to validate
+ * @param label - Human-readable name for error messages (e.g., "organization slug")
+ * @throws {ValidationError} When input contains control characters
+ */
+export function rejectControlChars(input: string, label: string): void {
+  const match = CONTROL_CHAR_PATTERN.exec(input);
+  if (match) {
+    const capitalizedLabel = label.charAt(0).toUpperCase() + label.slice(1);
+    throw new ValidationError(
+      `Invalid ${label}: contains ${describeForbiddenChar(match[0])}.\n` +
+        `  ${capitalizedLabel} must not contain control characters.`
+    );
+  }
+}
+
+/**
+ * Reject pre-URL-encoded sequences (`%XX`) in resource identifiers.
+ *
+ * Resource IDs (slugs, issue IDs) should always be plain strings. If they
+ * contain `%XX` patterns, they were likely pre-encoded by an agent and
+ * would get double-encoded when interpolated into API URLs.
+ *
+ * @param input - String to validate
+ * @param label - Human-readable name for error messages (e.g., "project slug")
+ * @throws {ValidationError} When input contains percent-encoded sequences
+ */
+export function rejectPreEncoded(input: string, label: string): void {
+  const match = PRE_ENCODED_PATTERN.exec(input);
+  if (match) {
+    throw new ValidationError(
+      `Invalid ${label}: contains URL-encoded sequence "${match[0]}".\n` +
+        `  Use plain text instead of percent-encoding (e.g., "my project" not "my%20project").`
+    );
+  }
+}
+
+/**
+ * Validate a resource identifier (org slug, project slug, or issue ID component).
+ *
+ * Rejects characters that would cause URL injection when the identifier
+ * is interpolated into API endpoint paths. This is the primary defense
+ * against agent-hallucinated inputs like:
+ * - `my-org?query=foo` (query injection)
+ * - `my-project#anchor` (fragment injection)
+ * - `CLI-G%20extra` (pre-encoded space → double encoding)
+ * - `my-org\tother` (control character injection)
+ *
+ * @param input - Resource identifier to validate
+ * @param label - Human-readable name for error messages (e.g., "organization slug")
+ * @throws {ValidationError} When input contains forbidden characters
+ */
+export function validateResourceId(input: string, label: string): void {
+  // Check control characters first (subset of the broader check)
+  rejectControlChars(input, label);
+
+  // Check for URL-significant characters and whitespace
+  const match = RESOURCE_ID_FORBIDDEN.exec(input);
+  if (match) {
+    throw new ValidationError(
+      `Invalid ${label}: contains ${describeForbiddenChar(match[0])}.\n` +
+        "  Slugs and IDs must contain only letters, numbers, hyphens, and underscores."
+    );
+  }
+}
+
+/**
+ * Validate an API endpoint path for path traversal attacks.
+ *
+ * Rejects `..` path segments that could be used to escape the API prefix:
+ * ```
+ * sentry api "../../admin/settings/"  →  rejected
+ * sentry api "organizations/../admin" →  rejected
+ * ```
+ *
+ * While the Sentry API server handles this safely (404), rejecting on the
+ * client provides better error messages and defense-in-depth.
+ *
+ * Also validates that the endpoint doesn't contain control characters.
+ *
+ * @param endpoint - API endpoint path to validate
+ * @throws {ValidationError} When endpoint contains path traversal or control characters
+ */
+export function validateEndpoint(endpoint: string): void {
+  rejectControlChars(endpoint, "API endpoint");
+
+  if (PATH_TRAVERSAL_PATTERN.test(endpoint)) {
+    throw new ValidationError(
+      'Invalid API endpoint: contains ".." path traversal.\n' +
+        "  Use absolute API paths (e.g., /api/0/organizations/my-org/issues/)."
+    );
+  }
+}

src/lib/input-validation.ts

@@ -71,6 +71,46 @@ describe("normalizeEndpoint edge cases", () => {
   });
 });
 
+describe("normalizeEndpoint: path traversal hardening (#350)", () => {
+  test("rejects bare .. traversal", () => {
+    expect(() => normalizeEndpoint("..")).toThrow(/path traversal/);
+  });
+
+  test("rejects leading ../ traversal", () => {
+    expect(() => normalizeEndpoint("../../admin/settings/")).toThrow(
+      /path traversal/
+    );
+  });
+
+  test("rejects mid-path traversal", () => {
+    expect(() => normalizeEndpoint("organizations/my-org/../admin/")).toThrow(
+      /path traversal/
+    );
+  });
+
+  test("rejects traversal with leading slash", () => {
+    expect(() => normalizeEndpoint("/../../admin/")).toThrow(/path traversal/);
+  });
+
+  test("allows single dots in paths", () => {
+    expect(normalizeEndpoint("organizations/.well-known/")).toBe(
+      "organizations/.well-known/"
+    );
+  });
+
+  test("allows double dots inside segment names", () => {
+    expect(normalizeEndpoint("organizations/my..org/")).toBe(
+      "organizations/my..org/"
+    );
+  });
+
+  test("rejects control characters in endpoint", () => {
+    expect(() => normalizeEndpoint("organizations/\x00admin/")).toThrow(
+      /Invalid/
+    );
+  });
+});
+
 describe("parseFieldKey error cases", () => {
   test("throws for invalid format with unmatched brackets", () => {
     expect(() => parseFieldKey("user[name")).toThrow(