fix: encode caller-supplied path parameters in legacy modules

[gjtorikian]

Description

Resolves VULN-1216

The hand-written legacy modules (user-management, authorization, organizations, feature-flags, multi-factor-auth, audit-logs, directory-sync, organization-domains, sso, passwordless) interpolated caller-supplied identifiers straight into URL path templates. HttpClient.getResourceURL then resolves the path with the WHATWG URL parser, which collapses ../ and honors ?/#, so workos.mfa.deleteFactor('../../user_management/users/user_01VICTIM') sent DELETE /user_management/users/user_01VICTIM with the integrator's API key. Any method of a non-encoding module could be retargeted to any same-verb endpoint.

• Add src/common/utils/encode-path-parameter.ts and wrap every interpolated path parameter in the ten legacy modules with it (about 110 call sites, including the newer waitlist, IT contact, user API key, session, group and role-assignment paths added since July). This re-lands the approach from Encode caller-supplied path parameters in legacy modules #1662/Encode the userId path parameter in user API key methods #1664, which were closed unmerged.
• Preserve : so RBAC slugs such as users:read keep their exact wire format. A colon is a valid path-segment character and can never be read as a URL scheme after a /-delimited prefix. Existing slug tests are unchanged and an explicit test pins the /permissions/users:read path.
• Reject a bare . or .. with a TypeError before any request is made. encodeURIComponent leaves them unchanged and the URL parser strips them as relative segments even in %2e form, so a slug of .. in a non-terminal template like /feature-flags/${slug}/enable would still climb. Neither is a valid WorkOS identifier, so the helper fails closed.
• Encode the four raw sites in the generated src/api-keys/api-keys.ts (deleteApiKey, listOrganizationApiKeys, createOrganizationApiKey). This file carries the oagen header, so the fix is hand-applied with the exact bare encodeURIComponent(...) form the current node emitter emits (see src/pipes/pipes.ts), meaning the next regeneration produces the same output with no drift. No import or other change to the file.
• Guard HttpClient.getResourceURL against dot segments. Generated modules use bare encodeURIComponent, which leaves a bare . or .. unchanged, so deleteApiKey('..') would still have resolved /api_keys/.. to / and an organization ID of .. would have turned /organizations/../api_keys into /api_keys. The one hand-maintained place that calls new URL() now rejects any path segment equal to . or .. (including the %2e forms the WHATWG parser also collapses) with a TypeError before a request is built (the WorkOS request wrapper surfaces it as its usual "Unexpected error" with the TypeError as cause). This closes the gap for every generated module without editing them beyond the emitter-exact form, and is a second line of defense behind encodePathParameter for the legacy modules.
• Tests: unit specs for the helper and for getResourceURL, plus each touched module spec (api-keys included) asserts that a traversal payload stays a single encoded path segment and that .. rejects before fetch is called.

Not changed

• Other oagen-generated modules (pipes, vault, webhooks, groups, agents, radar, connect, widgets) already wrap path parameters in encodeURIComponent from the emitter and are untouched.
• Other oagen-generated modules keep their bare encodeURIComponent call sites; the getResourceURL guard covers their dot-segment case, so a matching emitter change is a parity follow-up rather than a safety requirement.
• The open oagen migration PRs (feat(authorization)!: own the Authorization service via oagen #1636, feat: Generate feature flags from OpenAPI spec #1635, feat!: Generate SSO from OpenAPI spec #1633, feat!: Generate organizations APIs using oagen #1628, feat!: Port AuditLogs to oagen #1627, feat!: Port DirectorySync to oagen #1626, feat!: generate OrganizationDomains off the OpenAPI spec #1620) will need a rebase after this merges, but they regenerate these modules with encodeURIComponent anyway, so the change is compatible in direction.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

[linear-code]

VULN-1216

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the centralized guard fully addresses the previously reported API-key dot-segment retargeting issue, and no new actionable failures were identified.

Findings

1.   Dot segments retarget requests ▶

Fix with agent prompt

### Issue 1
src/api-keys/api-keys.ts:undefined-63
These API key paths use `encodeURIComponent`, which leaves bare `.` and `..` values unchanged. Since the HTTP client then passes the path through the WHATWG `URL` parser, `deleteApiKey('..')` normalizes `/api_keys/..` to `/`, while an organization ID of `..` normalizes `/organizations/../api_keys` to `/api_keys`. Caller-controlled identifiers can therefore retarget DELETE, GET, or POST requests instead of remaining in their intended path segment. The same issue occurs at lines 87, 94, and 123; these values need the dot-only rejection provided by the new shared helper.

**How this was verified:** The public methods accept unrestricted strings, and every resulting path passes through `new URL(...)`, which normalizes the unchanged dot segments before issuing the request.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR prevents caller-supplied identifiers from changing SDK request paths in legacy and API-key modules.

• Encodes interpolated path parameters while preserving colons used in RBAC slugs.
• Rejects standalone dot segments before URL normalization can retarget a request.
• Adds module-level and HTTP-client tests covering traversal payloads and pre-request rejection.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Caller-supplied identifier] --> B[Encode path parameter]
    B --> C{Standalone dot segment?}
    C -- Yes --> D[Throw before request]
    C -- No --> E[Build request path]
    E --> F[HttpClient dot-segment guard]
    F --> G[WHATWG URL construction]
    G --> H[Send request to intended endpoint]

Loading

_{Reviews (3) · Last reviewed commit: "fix(http-client): reject dot segments in..."}