theokit 0.5.4 → 0.6.1

package/dist/server/http/index.js

@@ -22,7 +22,7 @@ import {
   runMiddlewareAndContext,
   sendError,
   sendJson
-} from "../../chunk-KJLECZWQ.js";
+} from "../../chunk-3FYJ7R7N.js";
 import "../../chunk-GY5Q27BJ.js";
 import "../../chunk-Z5IGLBWE.js";
 import "../../chunk-ZEGYW52B.js";
@@ -38,7 +38,6 @@ import {
   serializeCookie,
   setCookie
 } from "../../chunk-ZJQ4O76G.js";
-import "../../chunk-4HBI7DHP.js";
 import "../../chunk-DGUM43GV.js";
 export {
   BATCH_PATH,

package/dist/server/index.d.ts

@@ -1,9 +1,9 @@
 import { RouteConfig } from './define/index.js';
 export { ActionAccept, ActionConfig, AgentEndpointConfig, AgentEndpointHandlerArgs, ChannelHandler, CustomTool, DefineAgentToolSpec, MiddlewareHandler, WebChannelHandler, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel } from './define/index.js';
 export { W as WebSocketHandler, a as WebSocketHandlerWeb, b as WebSocketLike, d as defineWebSocket, c as defineWebSocketWeb } from '../define-websocket-CdK94O-D.js';
-export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoTransformer, _ as _resetMiddlewareCacheForTests, r as appendCookieToHeaders, s as appendDeleteCookieToHeaders, t as createCorsHandler, u as createCorsWebHandler, v as deleteCookie, w as executeAction, x as executeRoute, y as extractTraceId, z as extractTraceIdFromRequest, A as getCookie, D as getCookieFromRequest, F as handleBatchRequest, G as jsonTransformer, I as loadCustomErrorPages, J as matchesOrigin, K as parseCookieHeader, L as parseTraceparent, N as resolveTransformer, O as runMiddlewareAndContext, P as sendError, Q as sendJson, R as serializeCookie, U as serveStaticFile, V as setCookie, W as superjsonTransformer } from '../index-CuHICqb9.js';
+export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoTransformer, _ as _resetMiddlewareCacheForTests, r as appendCookieToHeaders, s as appendDeleteCookieToHeaders, t as createCorsHandler, u as createCorsWebHandler, v as deleteCookie, w as executeAction, x as executeRoute, y as extractTraceId, z as extractTraceIdFromRequest, A as getCookie, D as getCookieFromRequest, F as handleBatchRequest, G as jsonTransformer, I as loadCustomErrorPages, J as matchesOrigin, K as parseCookieHeader, L as parseTraceparent, N as resolveTransformer, O as runMiddlewareAndContext, P as sendError, Q as sendJson, R as serializeCookie, U as serveStaticFile, V as setCookie, W as superjsonTransformer } from '../index-DWZF8uQD.js';
 export { ActionNode, ActionScanError, LoadedManifest, ManifestAction, ManifestRoute, ManifestWebSocket, TheoManifest, WebSocketRouteNode, generateManifest, loadManifest, scanMiddlewares, scanServerActions, scanServerActionsEnriched, scanServerRoutes, scanWebSocketRoutes, writeManifest } from './scan/index.js';
-export { L as LoadModule, S as ServerRouteNode, c as compilePattern, a as createProductionLoader, b as createViteLoader, m as matchRoute } from '../module-loader-Cfz7dgCP.js';
+export { L as LoadModule, S as ServerRouteNode, c as compilePattern, a as createProductionLoader, b as createViteLoader, m as matchRoute } from '../match-CfbEFRG4.js';
 import { T as TheoErrorEnvelope, a as TheoErrorCode, V as ValidationFieldsExt } from '../error-envelope-BsNzzAV5.js';
 export { AgentRunLike, AgentRunResult, AgentRunStreamMessage, ConversationHistoryArgs, ConversationHistoryResult, ConversationStorageLike, SdkAgent, SdkAgentOptions, SdkRunLike, createConversationHistory, errorToEvent, streamAgentRun } from './agent/index.js';
 export { a as AgentErrorEvent, A as AgentEvent, b as AgentMessageEvent, e as AgentRunErrorCode, c as AgentToolCallEvent, d as AgentToolResultEvent } from '../agent-events-B3KNV9ER.js';
@@ -31,7 +31,7 @@ import { z } from 'zod';
 import { IncomingMessage } from 'node:http';
 import { W as WebOnRequestHook, b as WebPreHandlerHook, c as WebOnResponseHook, d as WebOnErrorHook } from '../plugin-types-DNJGxr4Z.js';
 export { e as HookName, H as HookResult, O as OnErrorHook, f as OnRequestHook, g as OnResponseHook, P as PluginContext, h as PluginErrorContext, i as PreHandlerHook, R as RunHookOptions, a as TheoApp, T as TheoPlugin, j as definePlugin } from '../plugin-types-DNJGxr4Z.js';
-export { a as ServiceDefinition, S as ServicesConfig, b as ServicesConfigInput, c as ServicesConfigOutput } from '../schema-D3v8VB7o.js';
+export { a as ServiceDefinition, S as ServicesConfig, b as ServicesConfigInput, c as ServicesConfigOutput } from '../schema-BpH6ivDY.js';
 import 'vite';
 
 /**
@@ -687,6 +687,25 @@ declare function serializeResponse(data: unknown): SerializedResponse;
  */
 declare function deserializeResponse(serialized: SerializedResponse): unknown;
 
+/**
+ * T3.2 — Web-Standards middleware runner for the `executeWebRequest` path.
+ *
+ * The Node request path (`http/execute.ts`) runs middleware via
+ * `runMiddlewareAndContext`, which is coupled to Node `req`/`res`. Per G8
+ * (Web Standards over Node APIs) the Web path needs a `Request`-shaped runner;
+ * this is it. Extracted to a sibling so `web-handler.ts` stays under its LoC
+ * budget (G6).
+ *
+ * Ordering invariant (EC-3): the caller runs the CSRF gate BEFORE invoking this
+ * runner, mirroring the Node path (CSRF stage precedes user middleware).
+ *
+ * NOTE (D4 / EC-12): this is its own middleware contract — `(request, context)`.
+ * Full semantic parity with the Node `defineMiddleware` contract is part of the
+ * deferred Node→Web pipeline convergence, not this slice.
+ */
+/** A Web-path middleware: mutate `context`, or return a `Response` to short-circuit. */
+type WebMiddleware = (request: Request, context: Record<string, unknown>) => Promise<Response | undefined> | Response | undefined | void;
+
 /**
  * The route module exported by a `server/routes/*.ts` file (after T2.6 G6
  * router lockdown). Method-named exports map to `defineRoute` results.
@@ -710,6 +729,20 @@ type WebRouteModule = Partial<Record<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  */
 interface ExecuteWebRequestOptions {
     csrfMode?: 'off' | 'strict';
+    /**
+     * T3.1 — route params resolved upstream by `matchRoute` (e.g. `{ id: '42' }`
+     * for `/users/:id`). Threaded to the handler's `params` input and validated
+     * against `config.params` (Zod) when declared. Defaults to `{}` — callers
+     * that don't supply params keep the prior behavior (additive, backward-compat).
+     */
+    params?: Record<string, string>;
+    /**
+     * T3.2 — Web-Standards middleware chain. Runs in order AFTER the CSRF gate
+     * (EC-3) and BEFORE the handler. A middleware returning a `Response`
+     * short-circuits (handler not reached); mutating `context` passes data to
+     * the handler. Omitted → zero overhead (handler runs directly).
+     */
+    middleware?: readonly WebMiddleware[];
     /**
      * T5a.2 Phase E — body parser strategy.
      *

package/dist/server/index.js

@@ -44,11 +44,6 @@ import {
   ChannelManager
 } from "../chunk-NM4WF3XD.js";
 import "../chunk-E3JH6YUM.js";
-import {
-  generateManifest,
-  loadManifest,
-  writeManifest
-} from "../chunk-GPF64ENM.js";
 import "../chunk-JHEAWR3L.js";
 import {
   StorageManager,
@@ -84,16 +79,17 @@ import {
   createViteLoader
 } from "../chunk-JQSKBMXP.js";
 import {
+  ActionScanError,
   compilePattern,
+  generateManifest,
+  loadManifest,
   matchRoute,
-  scanServerRoutes,
-  scanWebSocketRoutes
-} from "../chunk-OLPB36O2.js";
-import {
-  ActionScanError,
   scanServerActions,
-  scanServerActionsEnriched
-} from "../chunk-P3SGM4NR.js";
+  scanServerActionsEnriched,
+  scanServerRoutes,
+  scanWebSocketRoutes,
+  writeManifest
+} from "../chunk-223EFY5X.js";
 import "../chunk-WSJKACWB.js";
 import {
   CSP_REPORT_PATH,
@@ -110,7 +106,7 @@ import {
   handleCsrfReadinessRequest,
   normalizeLegacy,
   normalizeNew
-} from "../chunk-B3L3TJVF.js";
+} from "../chunk-JBCHWRKF.js";
 import {
   __resetSdkForTests,
   __setSdkForTests,
@@ -119,6 +115,7 @@ import {
   streamAgentRun
 } from "../chunk-RESN62GB.js";
 import {
+  AuthRequiredError,
   _resetKeyCacheForTests,
   assertProductionSecret,
   checkThrottle,
@@ -135,13 +132,14 @@ import {
   generateTotpSecret,
   pkceChallengeFromVerifier,
   recordAttempt,
+  requireAuth,
   rotateIfNeeded,
   rotateIfNeededWeb,
   totpUri,
   verifyBackupCode,
   verifyOAuthState,
   verifyTotp
-} from "../chunk-NZXH2LQQ.js";
+} from "../chunk-SJIRP73B.js";
 import {
   generateNonce
 } from "../chunk-C3ZZ56YZ.js";
@@ -181,7 +179,7 @@ import {
   defineWebChannel,
   defineWebSocket,
   defineWebSocketWeb
-} from "../chunk-H4J2LECY.js";
+} from "../chunk-6BUUZ2PK.js";
 import {
   MAX_ERROR_HTML_BYTES,
   loadCustomErrorPages,
@@ -198,6 +196,7 @@ import {
   _resetMiddlewareCacheForTests,
   createCorsHandler,
   createCorsWebHandler,
+  envelopeCodeToStatus,
   executeAction,
   executeRoute,
   extractTraceId,
@@ -211,7 +210,7 @@ import {
   runMiddlewareAndContext,
   sendError,
   sendJson
-} from "../chunk-KJLECZWQ.js";
+} from "../chunk-3FYJ7R7N.js";
 import {
   DuplicateContextKeyError,
   createOutbox,
@@ -252,10 +251,6 @@ import {
   serializeCookie,
   setCookie
 } from "../chunk-ZJQ4O76G.js";
-import {
-  AuthRequiredError,
-  requireAuth
-} from "../chunk-4HBI7DHP.js";
 import "../chunk-DGUM43GV.js";
 
 // src/server/openapi/serve-docs.ts
@@ -266,12 +261,13 @@ var DEFAULT_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
 function createOpenApiHandler(opts = {}) {
   const docsPath = opts.docsPath ?? "/api/docs";
   const jsonPath = opts.openapiJsonPath ?? "/api/docs/openapi.json";
-  const specFile = resolve(opts.specFilePath ?? ".theokit/openapi.json");
+  const rawSpecFile = opts.specFilePath ?? ".theokit/openapi.json";
   const title = opts.pageTitle ?? "API Reference";
   const cdn = opts.cdnUrl ?? DEFAULT_CDN;
-  if (specFile.includes("..")) {
-    throw new Error(`[theokit:openapi] specFilePath must not contain ".." segments: ${specFile}`);
+  if (hasDotDotSegment(rawSpecFile)) {
+    throw new Error(`[theokit:openapi] specFilePath must not contain ".." segments: ${rawSpecFile}`);
   }
+  const specFile = resolve(rawSpecFile);
   return (request) => {
     if (request.method !== "GET") return null;
     const url = new URL(request.url);
@@ -291,6 +287,9 @@ function createOpenApiHandler(opts = {}) {
     return null;
   };
 }
+function hasDotDotSegment(p) {
+  return p.split(/[/\\]/).includes("..");
+}
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -1095,6 +1094,15 @@ function deserializeResponse(serialized) {
   return superjson.deserialize(serialized);
 }
 
+// src/server/http/web-middleware-runner.ts
+async function runWebMiddleware(request, middleware, context) {
+  for (const mw of middleware) {
+    const result = await mw(request, context);
+    if (result instanceof Response) return result;
+  }
+  return void 0;
+}
+
 // src/server/web-handler.ts
 function searchParamsToObject(params) {
   const out = {};
@@ -1159,11 +1167,11 @@ function validationErrorResponse(zodError, field) {
     headers: { "content-type": "application/json" }
   });
 }
-async function runHandler(config, request, bodyParser = "inline") {
+async function runHandler(config, request, bodyParser = "inline", paramsInput = {}, context = {}) {
   const url = new URL(request.url);
   const queryRaw = searchParamsToObject(url.searchParams);
   const bodyRaw = bodyParser === "full" ? await parseBodyFull(request) : await parseBodyInline(request);
-  const paramsRaw = {};
+  const paramsRaw = paramsInput;
   let query = queryRaw;
   if (config.query !== void 0) {
     const parsed = config.query.safeParse(queryRaw);
@@ -1185,7 +1193,7 @@ async function runHandler(config, request, bodyParser = "inline") {
       return { ok: false, response: validationErrorResponse(parsed.error, "params") };
     params = parsed.data;
   }
-  const result = await config.handler({ query, body, params, request });
+  const result = await config.handler({ query, body, params, request, context });
   return { ok: true, result };
 }
 function toResponse(result) {
@@ -1208,36 +1216,6 @@ function handlerErrorResponse(err) {
     headers: { "content-type": "application/json" }
   });
 }
-function envelopeCodeToStatus(code) {
-  switch (code) {
-    case "BAD_REQUEST":
-      return 400;
-    case "UNAUTHORIZED":
-      return 401;
-    case "FORBIDDEN":
-      return 403;
-    case "NOT_FOUND":
-      return 404;
-    case "METHOD_NOT_ALLOWED":
-      return 405;
-    case "PAYLOAD_TOO_LARGE":
-      return 413;
-    case "UNPROCESSABLE_ENTITY":
-      return 422;
-    case "TOO_MANY_REQUESTS":
-    case "RATE_LIMITED":
-      return 429;
-    case "BAD_GATEWAY":
-      return 502;
-    case "SERVICE_UNAVAILABLE":
-      return 503;
-    case "GATEWAY_TIMEOUT":
-      return 504;
-    case "INTERNAL_SERVER_ERROR":
-    default:
-      return 500;
-  }
-}
 var CSRF_PROTECTED_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function mergeHookHeaders(response, hookHeaders) {
   if ([...hookHeaders].length === 0) return response;
@@ -1287,7 +1265,18 @@ async function executeWebRequest(request, routeModule, opts = {}) {
       if (!csrfCheck.valid) return csrfFailedResponse(csrfCheck.reason);
     }
     try {
-      const outcome = await runHandler(config, request, opts.bodyParser ?? "inline");
+      const context = {};
+      if (opts.middleware?.length) {
+        const shortCircuit = await runWebMiddleware(request, opts.middleware, context);
+        if (shortCircuit) return shortCircuit;
+      }
+      const outcome = await runHandler(
+        config,
+        request,
+        opts.bodyParser ?? "inline",
+        opts.params ?? {},
+        context
+      );
       if (!outcome.ok) return outcome.response;
       return toResponse(outcome.result);
     } catch (err) {
@@ -1313,13 +1302,29 @@ async function runPreHandlerPipeline(hookCtx, request, config, opts, hooks) {
     await runList(hooks.preHandler);
   }
   if (hookCtx.response === void 0) {
-    if (config === void 0 || typeof config.handler !== "function") {
-      hookCtx.response = methodNotAllowedResponse(method);
+    await runHandlerStage(hookCtx, request, config, opts, method);
+  }
+}
+async function runHandlerStage(hookCtx, request, config, opts, method) {
+  if (config === void 0 || typeof config.handler !== "function") {
+    hookCtx.response = methodNotAllowedResponse(method);
+    return;
+  }
+  if (opts.middleware?.length) {
+    const shortCircuit = await runWebMiddleware(request, opts.middleware, hookCtx.ctx);
+    if (shortCircuit) {
+      hookCtx.response = shortCircuit;
       return;
     }
-    const outcome = await runHandler(config, request, opts.bodyParser ?? "inline");
-    hookCtx.response = outcome.ok ? toResponse(outcome.result) : outcome.response;
   }
+  const outcome = await runHandler(
+    config,
+    request,
+    opts.bodyParser ?? "inline",
+    opts.params ?? {},
+    hookCtx.ctx
+  );
+  hookCtx.response = outcome.ok ? toResponse(outcome.result) : outcome.response;
 }
 async function runWithHooks(request, config, opts, hooks) {
   const hookCtx = {