fix(http): percent-encode path segments in resolveUrl

Centralize RFC 3986 path-segment encoding in HttpClient::resolveUrl so
an untrusted ID interpolated into a path template (e.g. om_xyz?/foo)
stays inside a single segment instead of opening a new path or query.
Existing services that already call rawurlencode are preserved
(percent-encoded triplets are not double-encoded).

Author: gjtorikian

lib/HttpClient.php

@@ -238,7 +238,50 @@ private function resolveUrl(string $path, ?RequestOptions $options): string
 
         $baseUrl = $options !== null && $options->baseUrl !== null ? $options->baseUrl : $this->baseUrl;
         $baseUrl = rtrim($baseUrl, '/');
-        return $baseUrl . '/' . ltrim($path, '/');
+        return $baseUrl . '/' . self::encodePathSegments(ltrim($path, '/'));
+    }
+
+    /**
+     * RFC 3986 path-segment encoding for an entire path string.
+     *
+     * Splits `$path` on `/`, percent-encodes any unsafe characters in each
+     * segment, and reassembles with `/` separators. Existing valid
+     * percent-encoded triplets (`%XX`) are preserved verbatim, so generated
+     * services that already call `rawurlencode($id)` are not double-encoded.
+     *
+     * Defense-in-depth: when a service forgets to encode an interpolated ID
+     * like `om_xyz?/foo`, the `?` and `/` inside the ID become percent-encoded
+     * inside a single segment instead of opening a new path or query.
+     */
+    private static function encodePathSegments(string $path): string
+    {
+        if ($path === '') {
+            return '';
+        }
+        $segments = explode('/', $path);
+        return implode('/', array_map([self::class, 'encodePathSegment'], $segments));
+    }
+
+    private static function encodePathSegment(string $segment): string
+    {
+        if ($segment === '') {
+            return '';
+        }
+        // Re-encode each character except RFC 3986 pchar safe characters and
+        // already-formed `%XX` triplets. Keeps idempotency for callers that
+        // already rawurlencoded their input.
+        return preg_replace_callback(
+            '/%[0-9A-Fa-f]{2}|[^A-Za-z0-9\-._~!$&\'()*+,;=:@]/',
+            static function (array $match): string {
+                $value = $match[0];
+                // Preserve existing percent-encoded triplets.
+                if (strlen($value) === 3 && $value[0] === '%') {
+                    return $value;
+                }
+                return rawurlencode($value);
+            },
+            $segment,
+        ) ?? $segment;
     }
 
     private function resolveTimeout(?RequestOptions $options): int

tests/HttpClientTest.php

@@ -252,6 +252,58 @@ public function testEmptyErrorBodySetsNullCodeAndError(): void
         }
     }
 
+    public function testResolveUrlPreservesEncodedIdAsSingleSegment(): void
+    {
+        // security-fix-plan.md finding #61: an untrusted ID like `om_xyz?/foo`
+        // must remain a single percent-encoded path segment instead of
+        // opening a new path/query when interpolated into a path template.
+        // Generated services already call `rawurlencode($id)`; the centralized
+        // fix must preserve that encoding (no double-encoding) and not re-split
+        // the encoded slash.
+        $mock = new MockHandler([
+            new Response(200, ['Content-Type' => 'application/json'], '{}'),
+        ]);
+        $history = [];
+        $handler = HandlerStack::create($mock);
+        $handler->push(\GuzzleHttp\Middleware::history($history));
+
+        $client = new HttpClient(
+            apiKey: 'test_key',
+            clientId: null,
+            baseUrl: 'https://api.workos.com',
+            timeout: 10,
+            maxRetries: 0,
+            handler: $handler,
+        );
+
+        $id = 'om_xyz?/foo';
+        $client->request('GET', 'organizations/' . rawurlencode($id));
+
+        $request = $history[array_key_last($history)]['request'];
+        $uri = $request->getUri();
+
+        // No query string — `?` inside the ID stayed percent-encoded.
+        $this->assertSame('', $uri->getQuery());
+        // The whole ID (including its `/`) stayed inside a single segment.
+        $this->assertSame('/organizations/om_xyz%3F%2Ffoo', $uri->getPath());
+
+        // Defense-in-depth: a path with the raw ID also has its `?` encoded
+        // and does not produce a stray query string.
+        $client2 = new HttpClient(
+            apiKey: 'test_key',
+            clientId: null,
+            baseUrl: 'https://api.workos.com',
+            timeout: 10,
+            maxRetries: 0,
+            handler: $handler,
+        );
+        $mock->append(new Response(200, ['Content-Type' => 'application/json'], '{}'));
+        $client2->request('GET', 'organizations/om_xyz?/foo');
+        $rawRequest = $history[array_key_last($history)]['request'];
+        $this->assertSame('', $rawRequest->getUri()->getQuery());
+        $this->assertStringContainsString('om_xyz%3F', $rawRequest->getUri()->getPath());
+    }
+
     public function testNonStringCodeFieldIsIgnored(): void
     {
         $body = json_encode([