Skip to content

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

Merged
TristanSpeakEasy merged 4 commits into
mainfrom
fix/typescript-reject-dot-segment-path-params
Nov 16, 2026
Merged

TristanSpeakEasy merged 4 commits into
mainfrom
fix/typescript-reject-dot-segment-path-params

Conversation

@TristanSpeakEasy

@TristanSpeakEasy TristanSpeakEasy commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

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.

Written for commit 0c7aca9. Summary will update on new commits.

View guided diff Turn on auto-fix

@TristanSpeakEasy
TristanSpeakEasy requested a review from a team as a code owner November 12, 2026 05:49
@TristanSpeakEasy TristanSpeakEasy added bug Something isn't working mcp-typescript Trigger (16) snapshot tests for mcp-typescript typescript Trigger (168) snapshot tests for typescript labels Nov 12, 2026

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 8 files

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

@speakeasy-generator-bot

speakeasy-generator-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Generator Snapshot Testing

Selector(s) Result Summary
snapshot-mcp-typescript, snapshot-typescript ❌ Snapshot run failed

Snapshot results: https://github.com/speakeasy-api/openapi-generation-snapshots/issues/165#issuecomment-6841576637

Snapshot results are summarized above. Additional run context is linked for maintainers with access.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 7 files (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Shadow auto-approve: would auto-approve. Bounded security fix: pathToFunc in the TypeScript and MCP templates now rejects path-parameter values that form '.', '..' (including encoded and separator tricks), preventing URL resolution from redirecting credentialed requests; comprehensive tests pin the corrected behavior.

View guided diff | Turn on auto-fix | Re-trigger cubic

@ThomasRooney ThomasRooney left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving with nits: the check holds for every parameter style in the generated SDK and MCP server, and output is otherwise identical to main.

(-Thomas + Fable 5.2)

Comment thread .changesets/1794462313-1f3dc8f5.yaml Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 31 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 12 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

@TristanSpeakEasy
TristanSpeakEasy added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 39488b5 Nov 16, 2026
174 of 175 checks passed
@TristanSpeakEasy
TristanSpeakEasy deleted the fix/typescript-reject-dot-segment-path-params branch November 16, 2026 01:09
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 16, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

bug Something isn't working mcp-typescript Trigger (16) snapshot tests for mcp-typescript typescript Trigger (168) snapshot tests for typescript

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants