fix(typescript,mcp): reject path parameters that form dot segments

Merged
TR
19h ago
+773-154

Why

Generated TypeScript SDKs build request paths with pathToFunc and then resolve them against the base URL with new URL(path, baseURL). Percent-encoding (encodeURIComponent) leaves . unchanged, so a path parameter whose value is exactly . or .. becomes a dot segment, and URL resolution removes it along with its parent:

// path template: /stores/{store_id}/items/{item_id}/details
sdk.stores.getItemDetails({ storeId: "..", itemId: "item-1" });
// before: GET {base}/items/item-1/details   (a different route)
// after:  rejected with InvalidRequestError before any request is sent

The request still carries the client's credentials. If an application passes untrusted input (end-user or model tool-call values) as a path parameter, the input can redirect the call to another endpoint under the same base URL and bypass the per-resource restrictions the application relies on. The flaw is in the shared runtime, so it affects every generated TypeScript SDK and MCP server.

What changed

Operation paths now reject a path parameter value that forms a . or .. segment, before any request is sent. This needs no spec changes.

  • TypeScript SDK: functions with path parameters build the path with a new encodePath helper in lib/sdks.ts. A rejected value comes back as ERR(InvalidRequestError) through the same invalid-request path as other request-building errors, so standalone functions keep returning a Result and SDK methods reject with InvalidRequestError:

    const pathResult = encodePath("/stores/{store_id}/items/{item_id}/details", pathParams);
    if (!pathResult.ok) {
      return [pathResult, { status: "invalid" }];
    }
    const path = pathResult.value;
    
  • MCP server: functions use the same encodePath helper, so the function returns InvalidRequestError as a Result, the tool call reports an error, and nothing is sent.

  • The check is opt-in on pathToFunc ({ rejectDotSegments: true }) and only operation paths opt in. Server URL templates and server variables are unchanged.

  • The error names the parameters that contributed to the segment: Parameter 'store_id' must not form a '.' or '..' path segment, or Parameters 'a', 'b' ... when several placeholders share it. Placeholders with empty values are not named.

  • The MCP runtime's pathToFunc now substitutes hyphenated placeholders such as {thing-blah}, matching the TypeScript runtime. Previously they were left in the path unsubstituted.

The check runs per template segment that contains a placeholder, after encoding, and matches what the WHATWG URL parser treats as a dot segment:

  • . and .., including the percent-encoded forms %2e, .%2E, %2e%2e, etc. (these reach pathToFunc unescaped when a caller pre-encodes or uses allowReserved)
  • separators the parser honours inside a value: / and \ (special schemes), so a/../b and ..\x are caught under allowReserved. Only the part before the first ? or # is checked, because the parser ends the path there: ..?x is rejected, safe?next=/.. is not
  • tab, LF and CR, which the parser strips (so .\t. would otherwise become ..)
  • label-style output such as encodeLabel("."), which renders as ..

Values that only contain dots remain valid: ..., .hidden, v1.2.3, a..b, and dots next to literal text in the same segment (user-{id} with .. gives user-..). Literal dot segments written into the path template are left untouched.

The zSDKs/sdk-typescriptv2 and zSDKs/mcp-typescript review SDKs are regenerated.

Review notes

  • Behaviour change for existing SDKs. The check is on for every regenerated SDK, with no feature flag (the Go target gates its equivalent behind fixFlags.encodePathParams for new SDKs only). These calls previously reached a different route from the one the caller asked for, so there is no working behaviour to preserve. The changeset calls this out.
  • A raw ? or # inside an allowReserved value still moves the rest of the URL into the query or fragment, as before. This PR only stops such values from changing the path.

Testing

  • TARGET=primary make test-typescriptv2: 53 files, 852 tests passing. tests/lib/url.test.ts covers rejected forms, encoder output from encodeSimple/encodeLabel, legitimate dotted values, error wording, and that templates are unchecked without rejectDotSegments. A new runtime test checks that a standalone function returns InvalidRequestError, that the SDK method rejects with it, and that nothing is sent.
  • TARGET=primary make test-mcp-typescript: 33 files, 362 tests passing, including a new tests/lib/url.test.ts for the MCP runtime (hyphenated placeholders, dot segments, server URL templates) and a runtime test that a function returns InvalidRequestError.
  • TARGET=review make test-typescriptv2 and TARGET=review make test-mcp-typescript pass.
  • make check-template-typescriptv2 and make check-template-mcp-typescript pass.
  • Prettier formatting is applied.
  • make lint: golangci-lint's gofmt check reports an alignment finding on an unrelated templates/perms.go entry; local gofmt makes no changes to the file.

Public-safety check

  • This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
  • Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
  • Generated fixtures and review SDK changes are public-safe.
  • I reviewed git diff --check.

Summary by cubic

Blocks path parameter values that form . or .. segments from redirecting SDK requests to a different endpoint under the same base URL. pathToFunc now rejects them before any request is sent, returning an InvalidRequestError in both typescriptv2 and mcp-typescript; previously the request went to a wrong route.

  • Rejects dot segments and their percent-encoded forms (%2e%2e), separators inside allowReserved values (a/../b, ..\x), and tab/newline tricks that the WHATWG URL parser strips.
  • Allows dots in longer labels (..., .hidden, v1.2.3), dots next to literal text, and literal dot segments written into the path template. Server URL templates are left unchecked.