@stacknet/stacks 0.1.1 → 0.2.0

package/src/proxy/route-handlers.ts

@@ -1,7 +1,16 @@
 /**
  * Next.js API Route Handler Factories
  *
- * Create pre-configured route handlers for common patterns
+ * Create pre-configured route handlers for common patterns.
+ *
+ * SECURITY NOTES
+ * - Every path-position parameter is run through `validateId` before being
+ *   interpolated into the upstream path. Without this, characters like `?`,
+ *   `&`, `#`, or `/` in an id would smuggle extra query params or escape
+ *   the intended namespace.
+ * - Every factory supports `extractAuth`; the forwarder receives an
+ *   `Authorization` header so the upstream can attribute the request to
+ *   the real caller instead of treating it as anonymous.
  */
 
 import { forwardRequest, forwardJSON, type ForwarderConfig } from './forwarder';
@@ -9,6 +18,11 @@ import { forwardRequest, forwardJSON, type ForwarderConfig } from './forwarder';
 export interface RouteHandlerConfig extends ForwarderConfig {
   requireAuth?: boolean;
   enrichResponse?: (data: unknown) => Promise<unknown>;
+  /** Extract the caller's bearer token from the incoming Request and
+   *  forward it upstream as `Authorization: Bearer <token>`. If unset,
+   *  the handler passes through any inbound `Authorization` header
+   *  verbatim. Without one of these the upstream sees no auth at all. */
+  extractAuth?: (request: Request) => string | null;
 }
 
 export type RouteHandler = (request: Request, context?: { params?: Record<string, string> }) => Promise<Response>;
@@ -20,6 +34,65 @@ export interface CRUDRouteHandlers {
   DELETE?: RouteHandler;
 }
 
+/** Back-compat: `StackRouteHandlerConfig` used to be distinct; now every
+ *  factory accepts `extractAuth`, so the two configs are identical. */
+export type StackRouteHandlerConfig = RouteHandlerConfig;
+
+// ----------------------------------------------------------------------------
+// Shared helpers
+// ----------------------------------------------------------------------------
+
+/** Validate that an id/param is a safe alphanumeric/dash/underscore/dot string.
+ *  Blocks path traversal (`..`, `/`), query smuggling (`?`, `&`, `#`), and
+ *  header injection (`\r`, `\n`) in one shot. */
+function validateId(id: string | null | undefined, name: string): string {
+  if (!id || typeof id !== 'string') {
+    throw new Error(`Missing required parameter: ${name}`);
+  }
+  if (!/^[\w.\-]+$/.test(id)) {
+    throw new Error(`Invalid ${name}: contains disallowed characters`);
+  }
+  return id;
+}
+
+/** Convert a thrown validation error into a 400 response so handlers don't
+ *  have to pepper try/catch everywhere. */
+function badRequest(err: unknown): Response {
+  const message = err instanceof Error ? err.message : 'Bad request';
+  return Response.json({ error: message }, { status: 400 });
+}
+
+function authHeaders(config: RouteHandlerConfig, request: Request): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (config.extractAuth) {
+    const token = config.extractAuth(request);
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+  } else {
+    const auth = request.headers.get('Authorization');
+    if (auth) headers['Authorization'] = auth;
+  }
+  return headers;
+}
+
+/** Pull an id from the Next-style context first, then fall back to the
+ *  last path segment. Runs through validateId either way. */
+function idFromContext(
+  request: Request,
+  context: { params?: Record<string, string | undefined> } | undefined,
+  key: string,
+  segmentFromEnd = 1,
+): string {
+  const fromCtx = context?.params?.[key];
+  if (fromCtx) return validateId(fromCtx, key);
+  const segs = new URL(request.url).pathname.split('/').filter(Boolean);
+  const candidate = segs[segs.length - segmentFromEnd];
+  return validateId(candidate, key);
+}
+
+// ============================================================================
+// Agent Route Handlers
+// ============================================================================
+
 /**
  * Create agent route handlers
  */
@@ -35,12 +108,15 @@ export function createAgentRoutes(config: RouteHandlerConfig = {}): CRUDRouteHan
       const path = userMid
         ? `/agents?creator_mid=${encodeURIComponent(userMid)}`
         : visibility
-          ? `/agents?visibility=${visibility}`
+          ? `/agents?visibility=${encodeURIComponent(visibility)}`
           : '/agents';
 
-      const { data, status } = await forwardJSON(path, {}, { baseUrl });
+      const { data, status } = await forwardJSON(
+        path,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
 
-      // Optional response enrichment
       let responseData = data;
       if (config.enrichResponse) {
         responseData = await config.enrichResponse(data);
@@ -53,7 +129,7 @@ export function createAgentRoutes(config: RouteHandlerConfig = {}): CRUDRouteHan
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/agents',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -69,8 +145,13 @@ export function createAgentDetailRoutes(config: RouteHandlerConfig = {}): CRUDRo
 
   return {
     GET: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
-      const { data, status } = await forwardJSON(`/agents/${id}`, {}, { baseUrl });
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
+      const { data, status } = await forwardJSON(
+        `/agents/${id}`,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
 
       let responseData = data;
       if (config.enrichResponse) {
@@ -81,32 +162,35 @@ export function createAgentDetailRoutes(config: RouteHandlerConfig = {}): CRUDRo
     },
 
     POST: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/agents/${id}`,
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     PUT: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/agents/${id}`,
-        { method: 'PUT', body },
+        { method: 'PUT', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     DELETE: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/agents/${id}`,
-        { method: 'DELETE' },
+        { method: 'DELETE', headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -122,12 +206,13 @@ export function createAgentExecuteRoute(config: RouteHandlerConfig = {}): { POST
 
   return {
     POST: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').slice(-2)[0];
+      let id: string;
+      try { id = idFromContext(request, context, 'id', 2); } catch (e) { return badRequest(e); }
       const body = await request.json();
 
       const response = await forwardRequest(
         `/agents/${id}/execute`,
-        { method: 'POST', body, stream: true },
+        { method: 'POST', body, stream: true, headers: authHeaders(config, request) },
         { baseUrl }
       );
 
@@ -162,10 +247,11 @@ export function createAgentToggleRoutes(config: RouteHandlerConfig = {}): {
   return {
     enable: {
       POST: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').slice(-2)[0];
+        let id: string;
+        try { id = idFromContext(request, context, 'id', 2); } catch (e) { return badRequest(e); }
         const { data, status } = await forwardJSON(
           `/agents/${id}/enable`,
-          { method: 'POST' },
+          { method: 'POST', headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -173,10 +259,11 @@ export function createAgentToggleRoutes(config: RouteHandlerConfig = {}): {
     },
     disable: {
       POST: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').slice(-2)[0];
+        let id: string;
+        try { id = idFromContext(request, context, 'id', 2); } catch (e) { return badRequest(e); }
         const { data, status } = await forwardJSON(
           `/agents/${id}/disable`,
-          { method: 'POST' },
+          { method: 'POST', headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -185,6 +272,10 @@ export function createAgentToggleRoutes(config: RouteHandlerConfig = {}): {
   };
 }
 
+// ============================================================================
+// Skill Route Handlers
+// ============================================================================
+
 /**
  * Create skill route handlers
  */
@@ -201,7 +292,11 @@ export function createSkillRoutes(config: RouteHandlerConfig = {}): CRUDRouteHan
       if (scope) path += `?scope=${encodeURIComponent(scope)}`;
       else if (creatorMid) path += `?creator_mid=${encodeURIComponent(creatorMid)}`;
 
-      const { data, status } = await forwardJSON(path, {}, { baseUrl });
+      const { data, status } = await forwardJSON(
+        path,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
@@ -209,7 +304,7 @@ export function createSkillRoutes(config: RouteHandlerConfig = {}): CRUDRouteHan
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/skills',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -225,38 +320,46 @@ export function createSkillDetailRoutes(config: RouteHandlerConfig = {}): CRUDRo
 
   return {
     GET: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
-      const { data, status } = await forwardJSON(`/skills/${id}`, {}, { baseUrl });
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
+      const { data, status } = await forwardJSON(
+        `/skills/${id}`,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
     POST: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/skills/${id}`,
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     PUT: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/skills/${id}`,
-        { method: 'PUT', body },
+        { method: 'PUT', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     DELETE: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/skills/${id}`,
-        { method: 'DELETE' },
+        { method: 'DELETE', headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -264,6 +367,10 @@ export function createSkillDetailRoutes(config: RouteHandlerConfig = {}): CRUDRo
   };
 }
 
+// ============================================================================
+// Widget Route Handlers
+// ============================================================================
+
 /**
  * Create widget route handlers (same pattern as skills)
  */
@@ -280,7 +387,11 @@ export function createWidgetRoutes(config: RouteHandlerConfig = {}): CRUDRouteHa
       if (scope) path += `?scope=${encodeURIComponent(scope)}`;
       else if (creatorMid) path += `?creator_mid=${encodeURIComponent(creatorMid)}`;
 
-      const { data, status } = await forwardJSON(path, {}, { baseUrl });
+      const { data, status } = await forwardJSON(
+        path,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
@@ -288,7 +399,7 @@ export function createWidgetRoutes(config: RouteHandlerConfig = {}): CRUDRouteHa
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/widgets',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -304,38 +415,46 @@ export function createWidgetDetailRoutes(config: RouteHandlerConfig = {}): CRUDR
 
   return {
     GET: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
-      const { data, status } = await forwardJSON(`/widgets/${id}`, {}, { baseUrl });
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
+      const { data, status } = await forwardJSON(
+        `/widgets/${id}`,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
     POST: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/widgets/${id}`,
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     PUT: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/widgets/${id}`,
-        { method: 'PUT', body },
+        { method: 'PUT', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     DELETE: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/widgets/${id}`,
-        { method: 'DELETE' },
+        { method: 'DELETE', headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -343,6 +462,10 @@ export function createWidgetDetailRoutes(config: RouteHandlerConfig = {}): CRUDR
   };
 }
 
+// ============================================================================
+// Imagination Route Handlers
+// ============================================================================
+
 /**
  * Create imagination route handlers
  */
@@ -352,14 +475,26 @@ export function createImaginationRoutes(config: RouteHandlerConfig = {}): CRUDRo
   return {
     GET: async (request: Request) => {
       const url = new URL(request.url);
-      const id = url.searchParams.get('id');
+      const idParam = url.searchParams.get('id');
       const creatorMid = url.searchParams.get('creator_mid');
 
       let path = '/imaginations';
-      if (id) path = `/imaginations/${id}`;
-      else if (creatorMid) path += `?creator_mid=${encodeURIComponent(creatorMid)}`;
+      if (idParam) {
+        try {
+          const id = validateId(idParam, 'id');
+          path = `/imaginations/${id}`;
+        } catch (e) {
+          return badRequest(e);
+        }
+      } else if (creatorMid) {
+        path += `?creator_mid=${encodeURIComponent(creatorMid)}`;
+      }
 
-      const { data, status } = await forwardJSON(path, {}, { baseUrl });
+      const { data, status } = await forwardJSON(
+        path,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
@@ -367,7 +502,7 @@ export function createImaginationRoutes(config: RouteHandlerConfig = {}): CRUDRo
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/imaginations',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -397,7 +532,11 @@ export function createCoderSessionRoutes(config: RouteHandlerConfig = {}): CRUDR
       if (limit) params.push(`limit=${encodeURIComponent(limit)}`);
       if (params.length) path += `?${params.join('&')}`;
 
-      const { data, status: resStatus } = await forwardJSON(path, {}, { baseUrl });
+      const { data, status: resStatus } = await forwardJSON(
+        path,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status: resStatus });
     },
 
@@ -405,7 +544,7 @@ export function createCoderSessionRoutes(config: RouteHandlerConfig = {}): CRUDR
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/coder/sessions',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -423,27 +562,34 @@ export function createCoderSessionDetailRoutes(config: RouteHandlerConfig = {}):
 
   return {
     GET: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
-      const { data, status } = await forwardJSON(`/coder/sessions/${id}`, {}, { baseUrl });
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
+      const { data, status } = await forwardJSON(
+        `/coder/sessions/${id}`,
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
     POST: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/coder/sessions/${id}`,
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
     },
 
     DELETE: async (request: Request, context?: { params?: { id?: string } }) => {
-      const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+      let id: string;
+      try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/coder/sessions/${id}`,
-        { method: 'DELETE' },
+        { method: 'DELETE', headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -451,10 +597,11 @@ export function createCoderSessionDetailRoutes(config: RouteHandlerConfig = {}):
 
     abort: {
       POST: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').slice(-2)[0];
+        let id: string;
+        try { id = idFromContext(request, context, 'id', 2); } catch (e) { return badRequest(e); }
         const { data, status } = await forwardJSON(
           `/coder/sessions/${id}/abort`,
-          { method: 'POST' },
+          { method: 'POST', headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -475,7 +622,7 @@ export function createCoderExecuteRoute(config: RouteHandlerConfig = {}): { POST
 
       const response = await forwardRequest(
         '/coder/execute',
-        { method: 'POST', body, stream: body.stream },
+        { method: 'POST', body, stream: body.stream, headers: authHeaders(config, request) },
         { baseUrl }
       );
 
@@ -508,18 +655,23 @@ export function createCoderToolsRoutes(config: RouteHandlerConfig = {}): {
   const baseUrl = config.baseUrl;
 
   return {
-    GET: async () => {
-      const { data, status } = await forwardJSON('/coder/tools', {}, { baseUrl });
+    GET: async (request: Request) => {
+      const { data, status } = await forwardJSON(
+        '/coder/tools',
+        { headers: authHeaders(config, request) },
+        { baseUrl },
+      );
       return Response.json(data, { status });
     },
 
     call: {
       POST: async (request: Request, context?: { params?: { tool?: string } }) => {
-        const tool = context?.params?.tool || new URL(request.url).pathname.split('/').pop();
+        let tool: string;
+        try { tool = idFromContext(request, context, 'tool'); } catch (e) { return badRequest(e); }
         const body = await request.json();
         const { data, status } = await forwardJSON(
           `/coder/tools/${tool}`,
-          { method: 'POST', body },
+          { method: 'POST', body, headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -552,7 +704,11 @@ export function createCoderFilesRoutes(config: RouteHandlerConfig = {}): {
         if (sessionId) apiPath += `&sessionId=${encodeURIComponent(sessionId)}`;
         if (sandboxId) apiPath += `&sandboxId=${encodeURIComponent(sandboxId)}`;
 
-        const { data, status } = await forwardJSON(apiPath, {}, { baseUrl });
+        const { data, status } = await forwardJSON(
+          apiPath,
+          { headers: authHeaders(config, request) },
+          { baseUrl },
+        );
         return Response.json(data, { status });
       },
     },
@@ -562,7 +718,7 @@ export function createCoderFilesRoutes(config: RouteHandlerConfig = {}): {
         const body = await request.json();
         const { data, status } = await forwardJSON(
           '/coder/files/write',
-          { method: 'POST', body },
+          { method: 'POST', body, headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -579,12 +735,16 @@ export function createCoderFilesRoutes(config: RouteHandlerConfig = {}): {
         const sandboxId = url.searchParams.get('sandboxId');
 
         let apiPath = `/coder/files/list?path=${encodeURIComponent(path)}`;
-        if (recursive) apiPath += `&recursive=${recursive}`;
-        if (maxDepth) apiPath += `&maxDepth=${maxDepth}`;
+        if (recursive) apiPath += `&recursive=${encodeURIComponent(recursive)}`;
+        if (maxDepth) apiPath += `&maxDepth=${encodeURIComponent(maxDepth)}`;
         if (sessionId) apiPath += `&sessionId=${encodeURIComponent(sessionId)}`;
         if (sandboxId) apiPath += `&sandboxId=${encodeURIComponent(sandboxId)}`;
 
-        const { data, status } = await forwardJSON(apiPath, {}, { baseUrl });
+        const { data, status } = await forwardJSON(
+          apiPath,
+          { headers: authHeaders(config, request) },
+          { baseUrl },
+        );
         return Response.json(data, { status });
       },
     },
@@ -604,7 +764,11 @@ export function createCoderFilesRoutes(config: RouteHandlerConfig = {}): {
         if (sessionId) apiPath += `&sessionId=${encodeURIComponent(sessionId)}`;
         if (sandboxId) apiPath += `&sandboxId=${encodeURIComponent(sandboxId)}`;
 
-        const { data, status } = await forwardJSON(apiPath, {}, { baseUrl });
+        const { data, status } = await forwardJSON(
+          apiPath,
+          { headers: authHeaders(config, request) },
+          { baseUrl },
+        );
         return Response.json(data, { status });
       },
     },
@@ -614,7 +778,7 @@ export function createCoderFilesRoutes(config: RouteHandlerConfig = {}): {
         const body = await request.json();
         const { data, status } = await forwardJSON(
           '/coder/files/diff',
-          { method: 'POST', body },
+          { method: 'POST', body, headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -640,7 +804,7 @@ export function createCoderSandboxRoutes(config: RouteHandlerConfig = {}): {
         const body = await request.json();
         const { data, status } = await forwardJSON(
           '/coder/sandbox',
-          { method: 'POST', body },
+          { method: 'POST', body, headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -649,20 +813,26 @@ export function createCoderSandboxRoutes(config: RouteHandlerConfig = {}): {
 
     get: {
       GET: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
-        const { data, status } = await forwardJSON(`/coder/sandbox/${id}`, {}, { baseUrl });
+        let id: string;
+        try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
+        const { data, status } = await forwardJSON(
+          `/coder/sandbox/${id}`,
+          { headers: authHeaders(config, request) },
+          { baseUrl },
+        );
         return Response.json(data, { status });
       },
     },
 
     exec: {
       POST: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').slice(-2)[0];
+        let id: string;
+        try { id = idFromContext(request, context, 'id', 2); } catch (e) { return badRequest(e); }
         const body = await request.json();
 
         const response = await forwardRequest(
           `/coder/sandbox/${id}/exec`,
-          { method: 'POST', body, stream: body.stream },
+          { method: 'POST', body, stream: body.stream, headers: authHeaders(config, request) },
           { baseUrl }
         );
 
@@ -686,10 +856,11 @@ export function createCoderSandboxRoutes(config: RouteHandlerConfig = {}): {
 
     destroy: {
       DELETE: async (request: Request, context?: { params?: { id?: string } }) => {
-        const id = context?.params?.id || new URL(request.url).pathname.split('/').pop();
+        let id: string;
+        try { id = idFromContext(request, context, 'id'); } catch (e) { return badRequest(e); }
         const { data, status } = await forwardJSON(
           `/coder/sandbox/${id}`,
-          { method: 'DELETE' },
+          { method: 'DELETE', headers: authHeaders(config, request) },
           { baseUrl }
         );
         return Response.json(data, { status });
@@ -712,7 +883,7 @@ export function createCoderExecRoutes(config: RouteHandlerConfig = {}): {
       const body = await request.json();
       const { data, status } = await forwardJSON(
         '/coder/exec',
-        { method: 'POST', body },
+        { method: 'POST', body, headers: authHeaders(config, request) },
         { baseUrl }
       );
       return Response.json(data, { status });
@@ -724,7 +895,7 @@ export function createCoderExecRoutes(config: RouteHandlerConfig = {}): {
 
         const response = await forwardRequest(
           '/coder/exec/stream',
-          { method: 'POST', body, stream: true },
+          { method: 'POST', body, stream: true, headers: authHeaders(config, request) },
           { baseUrl }
         );
 
@@ -750,35 +921,6 @@ export function createCoderExecRoutes(config: RouteHandlerConfig = {}): {
 // Stack Management Route Handlers
 // ============================================================================
 
-export interface StackRouteHandlerConfig extends RouteHandlerConfig {
-  /** Extract JWT from incoming request and forward as Authorization header */
-  extractAuth?: (request: Request) => string | null;
-}
-
-/** Validate that an ID parameter is a safe alphanumeric/dash/underscore string */
-function validateId(id: string | null | undefined, name: string): string {
-  if (!id || typeof id !== 'string') {
-    throw new Error(`Missing required parameter: ${name}`);
-  }
-  // Allow alphanumeric, dashes, underscores, dots — block path traversal
-  if (!/^[\w.\-]+$/.test(id)) {
-    throw new Error(`Invalid ${name}: contains disallowed characters`);
-  }
-  return id;
-}
-
-function authHeaders(config: StackRouteHandlerConfig, request: Request): Record<string, string> {
-  const headers: Record<string, string> = {};
-  if (config.extractAuth) {
-    const token = config.extractAuth(request);
-    if (token) headers['Authorization'] = `Bearer ${token}`;
-  } else {
-    const auth = request.headers.get('Authorization');
-    if (auth) headers['Authorization'] = auth;
-  }
-  return headers;
-}
-
 /**
  * Create stack CRUD route handlers (list + create)
  */
@@ -815,7 +957,8 @@ export function createStackDetailRoutes(config: StackRouteHandlerConfig = {}): C
 
   return {
     GET: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}`,
         { headers: authHeaders(config, request) },
@@ -827,7 +970,8 @@ export function createStackDetailRoutes(config: StackRouteHandlerConfig = {}): C
     POST: async () => Response.json({ error: 'Method not allowed' }, { status: 405 }),
 
     PUT: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}`,
@@ -838,7 +982,8 @@ export function createStackDetailRoutes(config: StackRouteHandlerConfig = {}): C
     },
 
     DELETE: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}`,
         { method: 'DELETE', headers: authHeaders(config, request) },
@@ -857,7 +1002,8 @@ export function createStackKeysRoutes(config: StackRouteHandlerConfig = {}): CRU
 
   return {
     GET: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}/keys`,
         { headers: authHeaders(config, request) },
@@ -867,7 +1013,8 @@ export function createStackKeysRoutes(config: StackRouteHandlerConfig = {}): CRU
     },
 
     POST: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const body = await request.json();
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}/keys`,
@@ -878,8 +1025,12 @@ export function createStackKeysRoutes(config: StackRouteHandlerConfig = {}): CRU
     },
 
     DELETE: async (request: Request, context?: { params?: { stackId?: string; keyId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
-      const keyId = validateId(context?.params?.keyId, 'keyId');
+      let stackId: string;
+      let keyId: string;
+      try {
+        stackId = validateId(context?.params?.stackId, 'stackId');
+        keyId = validateId(context?.params?.keyId, 'keyId');
+      } catch (e) { return badRequest(e); }
       const { data, status } = await forwardJSON(
         `/api/v2/stacks/${stackId}/keys/${keyId}`,
         { method: 'DELETE', headers: authHeaders(config, request) },
@@ -902,7 +1053,8 @@ export function createStackMembersRoutes(config: StackRouteHandlerConfig = {}):
 
   return {
     GET: async (request: Request, context?: { params?: { stackId?: string } }) => {
-      const stackId = validateId(context?.params?.stackId, 'stackId');
+      let stackId: string;
+      try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
       const url = new URL(request.url);
       const params = new URLSearchParams();
       const limit = url.searchParams.get('limit');
@@ -923,7 +1075,8 @@ export function createStackMembersRoutes(config: StackRouteHandlerConfig = {}):
 
     stats: {
       GET: async (request: Request, context?: { params?: { stackId?: string } }) => {
-        const stackId = validateId(context?.params?.stackId, 'stackId');
+        let stackId: string;
+        try { stackId = validateId(context?.params?.stackId, 'stackId'); } catch (e) { return badRequest(e); }
         const { data, status } = await forwardJSON(
           `/api/v2/stacks/${stackId}/members/stats`,
           { headers: authHeaders(config, request) },
@@ -935,11 +1088,15 @@ export function createStackMembersRoutes(config: StackRouteHandlerConfig = {}):
 
     updateRole: {
       PATCH: async (request: Request, context?: { params?: { stackId?: string; userId?: string } }) => {
-        const stackId = validateId(context?.params?.stackId, 'stackId');
-        const userId = validateId(context?.params?.userId, 'userId');
+        let stackId: string;
+        let userId: string;
+        try {
+          stackId = validateId(context?.params?.stackId, 'stackId');
+          userId = validateId(context?.params?.userId, 'userId');
+        } catch (e) { return badRequest(e); }
         const body = await request.json();
         const { data, status } = await forwardJSON(
-          `/api/v2/stacks/${stackId}/members/${encodeURIComponent(userId)}/role`,
+          `/api/v2/stacks/${stackId}/members/${userId}/role`,
           { method: 'PATCH', body, headers: authHeaders(config, request) },
           { baseUrl }
         );