@forklaunch/core 3.2.1 → 3.3.0

package/lib/http/index.js

@@ -66,6 +66,7 @@ __export(http_exports, {
   auditComplianceAccess: () => auditComplianceAccess,
   auditEnabled: () => auditEnabled,
   auditEventType: () => auditEventType,
+  bindRuntimeAuth: () => bindRuntimeAuth,
   createContext: () => createContext,
   createEmailClient: () => createEmailClient,
   createHmacToken: () => createHmacToken,
@@ -119,6 +120,7 @@ __export(http_exports, {
   put: () => put,
   recordMetric: () => recordMetric,
   recordRequestAudit: () => recordRequestAudit,
+  registerDelegatedSurface: () => registerDelegatedSurface,
   resetProcessHandlersForTesting: () => resetProcessHandlersForTesting,
   signPlatformEvent: () => signPlatformEvent,
   smsSegments: () => smsSegments,
@@ -134,6 +136,68 @@ __export(http_exports, {
 });
 module.exports = __toCommonJS(http_exports);
 
+// src/http/bindRuntimeAuth.ts
+function bindRuntimeAuth(details, binding) {
+  const policy = { ...details.auth };
+  const keys = Object.keys(binding);
+  const credentials = { ...binding };
+  const invalid = () => {
+    throw new Error("Invalid runtime authentication binding");
+  };
+  const allowedPolicy = policy.scheme === "jwt" ? [
+    "scheme",
+    "headerName",
+    "tokenPrefix",
+    "sessionSchema",
+    "allowedRoles",
+    "allowedPermissions"
+  ] : ["scheme", "headerName", "tokenPrefix"];
+  if (Object.keys(policy).some((key) => !allowedPolicy.includes(key)))
+    invalid();
+  for (const key of ["headerName", "tokenPrefix"]) {
+    if (policy[key] !== void 0 && (typeof policy[key] !== "string" || !policy[key]))
+      invalid();
+  }
+  if (policy.scheme === "jwt" && policy.allowedRoles === void 0 && policy.allowedPermissions === void 0)
+    invalid();
+  let authentication;
+  if (policy.scheme === "jwt") {
+    if (keys.some(
+      (key) => !["jwksPublicKeyUrl", "signatureKey", "decodeResource"].includes(key)
+    ))
+      invalid();
+    const keyFields = keys.filter((key) => key !== "decodeResource");
+    if (keyFields.length !== 1 || typeof credentials[keyFields[0]] !== "string" || !credentials[keyFields[0]])
+      invalid();
+    const decodeResource = credentials.decodeResource;
+    if (decodeResource !== void 0 && typeof decodeResource !== "function")
+      invalid();
+    delete credentials.decodeResource;
+    authentication = {
+      jwt: credentials,
+      ...decodeResource === void 0 ? {} : { decodeResource }
+    };
+  } else if (policy.scheme === "hmac") {
+    if (keys.length !== 1 || keys[0] !== "secretKeys" || !credentials.secretKeys || typeof credentials.secretKeys !== "object" || Array.isArray(credentials.secretKeys) || Object.keys(credentials.secretKeys).length === 0 || Object.values(credentials.secretKeys).some(
+      (key) => typeof key !== "string" || !key
+    ))
+      invalid();
+    authentication = { hmac: credentials };
+  } else {
+    return invalid();
+  }
+  delete policy.scheme;
+  for (const key of ["allowedRoles", "allowedPermissions"]) {
+    if (policy[key] !== void 0) {
+      const values = policy[key];
+      if (!Array.isArray(values) || values.some((value) => typeof value !== "string"))
+        invalid();
+      policy[key] = new Set(values);
+    }
+  }
+  return { ...details, auth: { ...policy, ...authentication } };
+}
+
 // src/http/middleware/request/cors.middleware.ts
 var import_cors = __toESM(require("cors"));
 function cors(corsOptions) {
@@ -594,7 +658,7 @@ function createContext(schemaValidator) {
 }
 
 // src/http/router/discriminateBody.ts
-function discriminateBody(schemaValidator, body) {
+function discriminateBody(schemaValidator, body, inputProjection) {
   if (body == null) {
     return void 0;
   }
@@ -644,7 +708,7 @@ function discriminateBody(schemaValidator, body) {
       parserType: "text",
       schema: maybeTypedBody
     };
-  } else if (schemaValidator.openapi(maybeTypedBody).format === "binary") {
+  } else if ((inputProjection ?? schemaValidator.openapi(maybeTypedBody)).format === "binary") {
     return {
       contentType: "application/octet-stream",
       parserType: "file",
@@ -1074,15 +1138,23 @@ async function checkAuthorizationToken(req, authorizationMethod, authorizationTo
       if (!parsedKeyId || !parsedTimestamp || !parsedNonce || !parsedSignature) {
         return invalidAuthorizationTokenFormat;
       }
-      const verificationResult = await auth.verificationFunction({
-        method: req?.method ?? "",
-        path: req?.path ?? "",
-        body: req?._rawBody ?? req?.body,
-        timestamp: new Date(parsedTimestamp),
-        nonce: parsedNonce,
-        signature: parsedSignature,
-        secretKey: collapsedAuthorizationMethod.hmac.secretKeys[parsedKeyId]
-      });
+      let verificationResult = false;
+      const signedPaths = hmacSignedPaths(req);
+      for (const path of signedPaths) {
+        verificationResult = Boolean(await auth.verificationFunction({
+          method: req?.method ?? "",
+          path,
+          body: req?._rawBody ?? req?.body,
+          timestamp: new Date(parsedTimestamp),
+          nonce: parsedNonce,
+          signature: parsedSignature,
+          secretKey: collapsedAuthorizationMethod.hmac.secretKeys[parsedKeyId]
+        }));
+        if (verificationResult) {
+          if (path !== signedPaths[0]) warnMountRelativeHmacPath();
+          break;
+        }
+      }
       if (!verificationResult) {
         return invalidAuthorizationSignature;
       }
@@ -1249,6 +1321,25 @@ async function checkAuthorizationToken(req, authorizationMethod, authorizationTo
     }
   }
 }
+function acceptMountRelativeHmacPaths() {
+  const value = typeof process === "undefined" ? void 0 : process.env?.HMAC_ACCEPT_MOUNT_RELATIVE_PATHS;
+  return value == null || !["false", "0"].includes(value.trim().toLowerCase());
+}
+var warnedMountRelativeHmacPath = false;
+function warnMountRelativeHmacPath() {
+  if (warnedMountRelativeHmacPath) return;
+  warnedMountRelativeHmacPath = true;
+  console.warn(
+    "Accepted an HMAC signature over the router-relative path. Sign the full request path instead; set HMAC_ACCEPT_MOUNT_RELATIVE_PATHS=false to reject the deprecated form."
+  );
+}
+function hmacSignedPaths(req) {
+  const relative = req?.path ?? "";
+  const wire = (req?.originalUrl ?? req?.url ?? relative).split("?")[0] || relative;
+  const paths = [wire];
+  if (relative !== wire && acceptMountRelativeHmacPaths()) paths.push(relative);
+  return paths;
+}
 async function parseRequestAuth(req, res, next) {
   const access = req.contractDetails.access;
   if (access === "public") {
@@ -1482,6 +1573,21 @@ function isRequestShape(maybeResponseShape) {
   return maybeResponseShape != null && ("body" in maybeResponseShape || "query" in maybeResponseShape || "params" in maybeResponseShape || "headers" in maybeResponseShape);
 }
 
+// src/http/middleware/internal/validationDiagnostic.ts
+var sendingDiagnostics = /* @__PURE__ */ new WeakSet();
+function isValidationDiagnostic(response) {
+  return sendingDiagnostics.has(response);
+}
+function sendValidationDiagnostic(response, send) {
+  const alreadySending = sendingDiagnostics.has(response);
+  sendingDiagnostics.add(response);
+  try {
+    return send();
+  } finally {
+    if (!alreadySending) sendingDiagnostics.delete(response);
+  }
+}
+
 // src/http/middleware/request/parse.middleware.ts
 function parse(req, res, next) {
   const globalOptions = req._globalOptions?.();
@@ -1563,14 +1669,13 @@ function parse(req, res, next) {
       default:
       case void 0:
       case "error":
-        res.type("application/json");
+        res.type("text/plain");
         res.status(400);
         if (hasSend(res)) {
-          res.send(
-            `${collectedParseErrors ?? (0, import_validator2.prettyPrintParseErrors)(parsedRequest.errors, "Request")}
+          const diagnostic = `${collectedParseErrors ?? (0, import_validator2.prettyPrintParseErrors)(parsedRequest.errors, "Request")}
 
-Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
-          );
+Correlation id: ${req.context.correlationId ?? "No correlation ID"}`;
+          sendValidationDiagnostic(res, () => res.send(diagnostic));
         } else {
           next?.(new Error("Request is not sendable."));
         }
@@ -1979,13 +2084,25 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
           span: void 0
         },
         _rawBody: void 0,
-        _parsedVersions: void 0
+        _parsedVersions: void 0,
+        // hyper-express's content parser reads the body through its Request's
+        // body readers; serve the body the call was given.
+        buffer: async () => Buffer.from(
+          typeof req.body === "string" ? req.body : JSON.stringify(req.body)
+        ),
+        json: async () => req.body,
+        text: async () => typeof req.body === "string" ? req.body : JSON.stringify(req.body)
       };
       const res = {
         statusCode: 200,
+        // hyper-express's response enrichment reads the status and headers
+        // from these fields, which its own Response keeps.
+        _status_code: 200,
+        _headers: responseHeaders,
         status: (code) => {
           statusCode = code;
           res.statusCode = code;
+          res._status_code = code;
           return res;
         },
         send: (message) => {
@@ -2005,6 +2122,8 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
           return res;
         },
         getHeader: (key) => responseHeaders[key],
+        getHeaders: () => ({ ...responseHeaders }),
+        locals: {},
         type: (contentType) => {
           responseHeaders["content-type"] = contentType;
           return res;
@@ -2023,31 +2142,59 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
         version
       };
       const executeMiddlewares = request?.executeMiddlewares ?? false;
+      const cHandler = controllerHandler;
       if (executeMiddlewares && middlewares.length > 0) {
-        const allHandlers = [...middlewares];
-        let cursor = allHandlers.shift();
-        if (cursor) {
-          for (const fn of allHandlers) {
-            await cursor(req, res, (err) => {
-              if (err) {
-                throw err;
+        const chain = middlewares;
+        await new Promise((resolve, reject) => {
+          let settled = false;
+          let responded = false;
+          let controllerStarted = false;
+          const finish = (error) => {
+            if (settled) return;
+            settled = true;
+            if (error) reject(error);
+            else resolve();
+          };
+          res.on("finish", () => {
+            responded = true;
+            if (!controllerStarted) finish();
+          });
+          const run = async (index) => {
+            try {
+              if (index === chain.length) {
+                controllerStarted = true;
+                await cHandler(req, res, (err) => {
+                  if (err) {
+                    throw err;
+                  }
+                });
+                finish();
+                return;
               }
-              cursor = fn;
-            });
-          }
-          await cursor(req, res, async (err) => {
-            if (err) {
-              throw err;
+              let calledNext = false;
+              await chain[index](req, res, (err) => {
+                calledNext = true;
+                if (err) {
+                  throw err;
+                }
+                return run(index + 1);
+              });
+              if (!calledNext && chain[index].length < 3 && !responded) {
+                await run(index + 1);
+              }
+            } catch (error) {
+              finish(error);
             }
-          });
-        }
+          };
+          void run(0);
+        });
+      } else {
+        await cHandler(req, res, (err) => {
+          if (err) {
+            throw err;
+          }
+        });
       }
-      const cHandler = controllerHandler;
-      await cHandler(req, res, (err) => {
-        if (err) {
-          throw err;
-        }
-      });
       return {
         code: Number(statusCode),
         response: responseMessage,
@@ -3536,7 +3683,7 @@ function loadStripe() {
 function stripeGatewayFetch(settings, fetchImpl = fetch) {
   const base = new URL(settings.gatewayUrl);
   const basePath = base.pathname.replace(/\/+$/, "");
-  return async (input, init = {}) => {
+  const signedFetch = async (input, init = {}) => {
     const original = new URL(
       typeof input === "string" || input instanceof URL ? input : input.url
     );
@@ -3576,6 +3723,13 @@ function stripeGatewayFetch(settings, fetchImpl = fetch) {
       }
     );
   };
+  const preconnect = Reflect.get(fetchImpl, "preconnect");
+  if (typeof preconnect === "function") {
+    Object.defineProperty(signedFetch, "preconnect", {
+      value: (_input, options2) => Reflect.apply(preconnect, fetchImpl, [base.origin, options2])
+    });
+  }
+  return signedFetch;
 }
 function createStripeClient(options2 = {}) {
   const StripeClass = options2.Stripe ?? loadStripe();
@@ -4808,10 +4962,10 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
             let bodySchema;
             let responsesSchemas;
             if (route.contractDetails.versions) {
-              const version2 = route.contractDetails.versions[index];
+              const version2 = Object.values(route.contractDetails.versions)[index];
+              responsesSchemas = version2.responses;
               if (version2.body && schemaValidator.parse(inputSchema, args).ok) {
                 bodySchema = version2.body;
-                responsesSchemas = version2.responses;
               }
             } else {
               bodySchema = route.contractDetails.body;
@@ -4822,7 +4976,7 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
             if (discriminatedBody) {
               switch (discriminatedBody.parserType) {
                 case "json": {
-                  parsedBody = (0, import_common13.safeStringify)(body);
+                  parsedBody = body === void 0 ? void 0 : JSON.stringify(body);
                   break;
                 }
                 case "text": {
@@ -4888,11 +5042,11 @@ function generateMcpServer(schemaValidator, protocol, host, port, version, appli
               ).toString();
               url += queryString ? `?${queryString}` : "";
             }
-            const response = await fetch(encodeURI(url), {
+            const response = await fetch(url, {
               method: route.method.toUpperCase(),
               headers: {
                 ...headers,
-                ...discriminatedBody?.contentType != "multipart/form-data" ? {
+                ...discriminatedBody?.contentType != "multipart/form-data" && (contentType ?? discriminatedBody?.contentType) !== void 0 ? {
                   "Content-Type": contentType ?? discriminatedBody?.contentType
                 } : {}
               },
@@ -4970,7 +5124,12 @@ function isResponseCompiledSchema(schema) {
 }
 
 // src/http/middleware/response/parse.middleware.ts
+var sendingValidationError = /* @__PURE__ */ new WeakSet();
 function parse2(req, res, next) {
+  if (sendingValidationError.has(res)) {
+    next?.();
+    return;
+  }
   let headers;
   let responses;
   const globalOptions = req._globalOptions?.();
@@ -5013,15 +5172,35 @@ function parse2(req, res, next) {
     responses = responseSchemas.responses;
   }
   const statusCode = Number(res.statusCode);
-  const parsedResponse = schemaValidator.parse(
-    [400, 401, 404, 403, 500].includes(statusCode) ? schemaValidator.union([schemaValidator.string, responses?.[statusCode]]) : responses?.[statusCode],
-    res.bodyData
-  );
+  const defaultErrorStatus = [400, 401, 404, 403, 500].includes(statusCode);
+  const missingResponseSchema = !defaultErrorStatus && !Object.prototype.hasOwnProperty.call(responses, statusCode);
+  if (missingResponseSchema && collapsedOptions !== "warning") {
+    throw new Error(`Undocumented response status ${statusCode}`);
+  }
+  const declaredResponse = responses?.[statusCode];
+  const defaultErrorResponse = () => {
+    try {
+      return schemaValidator.parse(
+        schemaValidator.union([schemaValidator.string, declaredResponse]),
+        res.bodyData
+      );
+    } catch (error) {
+      if (declaredResponse === void 0) throw error;
+      const declared = schemaValidator.parse(declaredResponse, res.bodyData);
+      if (declared.ok) return declared;
+      const message = schemaValidator.parse(
+        schemaValidator.string,
+        res.bodyData
+      );
+      return message.ok ? message : declared;
+    }
+  };
+  const parsedResponse = missingResponseSchema ? { ok: true } : defaultErrorStatus ? defaultErrorResponse() : schemaValidator.parse(declaredResponse, res.bodyData);
   const parsedHeaders = schemaValidator.parse(
     headers ?? schemaValidator.unknown,
     res.getHeaders()
   );
-  const parseErrors = [];
+  const parseErrors = missingResponseSchema ? [`Response: Undocumented response status ${statusCode}`] : [];
   if (!parsedHeaders.ok) {
     const headerErrors = (0, import_validator3.prettyPrintParseErrors)(parsedHeaders.errors, "Header");
     if (headerErrors) {
@@ -5038,21 +5217,26 @@ function parse2(req, res, next) {
     }
   }
   if (parseErrors.length > 0) {
-    switch (req.contractDetails.options?.responseValidation) {
+    switch (collapsedOptions) {
       default:
       case void 0:
       case "error":
         res.type("text/plain");
         res.status(500);
         if (hasSend(res)) {
-          res.send(
-            `Invalid response:
+          sendingValidationError.add(res);
+          try {
+            res.send(
+              `Invalid response:
 ${parseErrors.join(
-              "\n\n"
-            )}
+                "\n\n"
+              )}
 
 Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
-          );
+            );
+          } finally {
+            sendingValidationError.delete(res);
+          }
         } else {
           next?.(new Error("Response is not sendable."));
         }
@@ -5063,8 +5247,6 @@ Correlation id: ${req.context.correlationId ?? "No correlation ID"}`
 ${parseErrors.join("\n\n")}`
         );
         break;
-      case "none":
-        break;
     }
   }
   next?.();
@@ -5106,6 +5288,10 @@ function enrichExpressLikeSend(instance, req, res, originalOperation, originalSe
     originalSend.call(instance, data);
     return;
   }
+  if (typeof data === "string" && isValidationDiagnostic(res)) {
+    originalSend.call(instance, data);
+    return;
+  }
   let responses;
   if (req.contractDetails.responses == null && (req.contractDetails.versions == null || Object.values(req.contractDetails.versions).some(
     (version) => version?.responses == null
@@ -5115,7 +5301,7 @@ function enrichExpressLikeSend(instance, req, res, originalOperation, originalSe
     if (req.contractDetails.responses != null) {
       responses = req.contractDetails.responses;
     } else {
-      responses = req.contractDetails.versions[req.version].responses;
+      responses = req.contractDetails.versions[req.version]?.responses ?? {};
     }
   }
   const responseBodies = discriminateResponseBodies(
@@ -5337,7 +5523,16 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
   for (const key in discriminatedResponseBodiesResult) {
     coercedResponses[key] = {
       description: httpStatusCodes_default[key],
-      content: contentResolver(
+      // Undefined/void represent no response body, not a JSON null payload.
+      // Check the schema kind rather than its OpenAPI projection: null and
+      // nullish also project to null but still admit an actual JSON body.
+      content: schemaValidator.undefined !== void 0 && typedSchemaValidator.isInstanceOf(
+        discriminatedResponseBodiesResult[key].schema,
+        schemaValidator.undefined
+      ) || schemaValidator.void !== void 0 && typedSchemaValidator.isInstanceOf(
+        discriminatedResponseBodiesResult[key].schema,
+        schemaValidator.void
+      ) ? void 0 : contentResolver(
         schemaValidator,
         discriminatedResponseBodiesResult[key].schema,
         discriminatedResponseBodiesResult[key].contentType
@@ -5373,15 +5568,21 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       operationObject.parameters?.push({
         name: key,
         in: "path",
+        required: true,
         schema: typedSchemaValidator.openapi(params[key])
       });
     }
   }
-  const discriminatedBodyResult = body ? discriminateBody(schemaValidator, body) : null;
+  const adapter = schemaValidator;
+  const bareProjection = body && adapter.isSchema(body) ? adapter.openapiRequestBody?.(body) : void 0;
+  const discriminatedBodyResult = body ? discriminateBody(schemaValidator, body, bareProjection?.schema) : null;
   if (discriminatedBodyResult) {
+    const projection = bareProjection ?? adapter.openapiRequestBody?.(discriminatedBodyResult.schema);
     operationObject.requestBody = {
-      required: true,
-      content: contentResolver(
+      required: projection?.required ?? true,
+      content: projection ? {
+        [discriminatedBodyResult.contentType]: { schema: projection.schema }
+      } : contentResolver(
         schemaValidator,
         discriminatedBodyResult.schema,
         discriminatedBodyResult.contentType
@@ -5416,25 +5617,14 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       content: contentResolver(schemaValidator, schemaValidator.string)
     };
     if ("basic" in auth) {
-      operationObject.security = [
-        {
-          basic: Array.from(
-            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
-          )
-        }
-      ];
+      operationObject.security = [{ basic: [] }];
       securitySchemes["basic"] = {
         type: "http",
         scheme: "basic"
       };
     } else if (auth) {
-      operationObject.security = [
-        {
-          [auth.headerName !== "Authorization" ? "bearer" : "apiKey"]: Array.from(
-            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
-          )
-        }
-      ];
+      const schemeName = auth.headerName || "Authorization";
+      operationObject.security = [{ [schemeName]: [] }];
       if (auth.headerName && auth.headerName !== "Authorization") {
         securitySchemes[auth.headerName] = {
           type: "apiKey",
@@ -5665,6 +5855,22 @@ var RateLimiter = class {
     return READ_METHODS.has(method.toUpperCase()) ? "read" : "write";
   }
 };
+
+// src/http/registerDelegatedSurface.ts
+function registerDelegatedSurface(surface, mount, register) {
+  if (!surface.id || !surface.provider || surface.coverage !== "provider-owned" || !surface.client.package || !surface.client.export || surface.runtime.basePath !== "runtime-resolved" || typeof surface.runtime.openApi !== "boolean" || !Array.isArray(surface.callbacks) || surface.callbacks.some(
+    (callback) => typeof callback !== "string" || !callback.startsWith("/")
+  )) {
+    throw new Error("Invalid delegated HTTP surface descriptor");
+  }
+  const paths = Array.isArray(mount.paths) ? mount.paths : [mount.paths];
+  if (mount.basePath !== "" && !mount.basePath.startsWith("/") || paths.length === 0 || paths.some(
+    (path) => !path.startsWith("/") || mount.basePath !== "" && !path.startsWith(mount.basePath + "/")
+  )) {
+    throw new Error("Invalid delegated HTTP surface mount");
+  }
+  return register(mount);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ATTR_API_NAME,
@@ -5703,6 +5909,7 @@ var RateLimiter = class {
   auditComplianceAccess,
   auditEnabled,
   auditEventType,
+  bindRuntimeAuth,
   createContext,
   createEmailClient,
   createHmacToken,
@@ -5756,6 +5963,7 @@ var RateLimiter = class {
   put,
   recordMetric,
   recordRequestAudit,
+  registerDelegatedSurface,
   resetProcessHandlersForTesting,
   signPlatformEvent,
   smsSegments,