@forklaunch/core 0.19.5 → 1.0.1

package/lib/http/index.mjs

@@ -242,11 +242,36 @@ function discriminateResponseBodies(schemaValidator, responses) {
 // src/http/router/routerSharedLogic.ts
 import { isRecord as isRecord2 } from "@forklaunch/common";
 
+// src/http/guards/hasPermissionChecks.ts
+function hasPermissionChecks(maybePermissionedAuth) {
+  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && ("allowedPermissions" in maybePermissionedAuth || "forbiddenPermissions" in maybePermissionedAuth);
+}
+
+// src/http/guards/hasRoleChecks.ts
+function hasRoleChecks(maybeRoledAuth) {
+  if (typeof maybeRoledAuth !== "object" || maybeRoledAuth === null) {
+    return false;
+  }
+  const hasAllowedRoles = "allowedRoles" in maybeRoledAuth && maybeRoledAuth.allowedRoles instanceof Set && maybeRoledAuth.allowedRoles.size > 0;
+  const hasForbiddenRoles = "forbiddenRoles" in maybeRoledAuth && maybeRoledAuth.forbiddenRoles instanceof Set && maybeRoledAuth.forbiddenRoles.size > 0;
+  return hasAllowedRoles || hasForbiddenRoles;
+}
+
+// src/http/guards/hasScopeChecks.ts
+function hasScopeChecks(maybePermissionedAuth) {
+  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && "requiredScope" in maybePermissionedAuth && maybePermissionedAuth.requiredScope != null;
+}
+
 // src/http/guards/hasVersionedSchema.ts
 function hasVersionedSchema(contractDetails) {
   return typeof contractDetails === "object" && contractDetails !== null && "versions" in contractDetails && contractDetails.versions !== null;
 }
 
+// src/http/guards/isHmacMethod.ts
+function isHmacMethod(maybeHmacMethod) {
+  return typeof maybeHmacMethod === "object" && maybeHmacMethod !== null && "hmac" in maybeHmacMethod && maybeHmacMethod.hmac != null;
+}
+
 // src/http/guards/isPathParamContractDetails.ts
 function isPathParamHttpContractDetails(maybePathParamHttpContractDetails) {
   return maybePathParamHttpContractDetails != null && typeof maybePathParamHttpContractDetails === "object" && "name" in maybePathParamHttpContractDetails && "summary" in maybePathParamHttpContractDetails && maybePathParamHttpContractDetails.name != null && maybePathParamHttpContractDetails.summary != null && ("responses" in maybePathParamHttpContractDetails && maybePathParamHttpContractDetails.responses != null || "versions" in maybePathParamHttpContractDetails && typeof maybePathParamHttpContractDetails.versions === "object" && maybePathParamHttpContractDetails.versions != null && Object.values(maybePathParamHttpContractDetails.versions).every(
@@ -299,11 +324,6 @@ function isBasicAuthMethod(maybeBasicAuthMethod) {
   return typeof maybeBasicAuthMethod === "object" && maybeBasicAuthMethod !== null && "basic" in maybeBasicAuthMethod && maybeBasicAuthMethod.basic != null;
 }
 
-// src/http/guards/isHmacMethod.ts
-function isHmacMethod(maybeHmacMethod) {
-  return typeof maybeHmacMethod === "object" && maybeHmacMethod !== null && "hmac" in maybeHmacMethod && maybeHmacMethod.hmac != null;
-}
-
 // src/http/guards/isJwtAuthMethod.ts
 function isJwtAuthMethod(maybeJwtAuthMethod) {
   return typeof maybeJwtAuthMethod === "object" && maybeJwtAuthMethod !== null && "jwt" in maybeJwtAuthMethod && maybeJwtAuthMethod.jwt != null;
@@ -433,26 +453,6 @@ function hasFeatureChecks(maybeFeatureAuth) {
   return typeof maybeFeatureAuth === "object" && maybeFeatureAuth !== null && "requiredFeatures" in maybeFeatureAuth && Array.isArray(maybeFeatureAuth.requiredFeatures) && maybeFeatureAuth.requiredFeatures.length > 0;
 }
 
-// src/http/guards/hasPermissionChecks.ts
-function hasPermissionChecks(maybePermissionedAuth) {
-  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && ("allowedPermissions" in maybePermissionedAuth || "forbiddenPermissions" in maybePermissionedAuth);
-}
-
-// src/http/guards/hasRoleChecks.ts
-function hasRoleChecks(maybeRoledAuth) {
-  if (typeof maybeRoledAuth !== "object" || maybeRoledAuth === null) {
-    return false;
-  }
-  const hasAllowedRoles = "allowedRoles" in maybeRoledAuth && maybeRoledAuth.allowedRoles instanceof Set && maybeRoledAuth.allowedRoles.size > 0;
-  const hasForbiddenRoles = "forbiddenRoles" in maybeRoledAuth && maybeRoledAuth.forbiddenRoles instanceof Set && maybeRoledAuth.forbiddenRoles.size > 0;
-  return hasAllowedRoles || hasForbiddenRoles;
-}
-
-// src/http/guards/hasScopeChecks.ts
-function hasScopeChecks(maybePermissionedAuth) {
-  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && "requiredScope" in maybePermissionedAuth && maybePermissionedAuth.requiredScope != null;
-}
-
 // src/http/guards/hasSubscriptionChecks.ts
 function hasSubscriptionChecks(maybeSubscriptionAuth) {
   return typeof maybeSubscriptionAuth === "object" && maybeSubscriptionAuth !== null && "requireActiveSubscription" in maybeSubscriptionAuth && maybeSubscriptionAuth.requireActiveSubscription === true;
@@ -1247,6 +1247,40 @@ function validateContractDetails(contractDetails, schemaValidator) {
   if (!isHttpContractDetails(contractDetails) && !isPathParamHttpContractDetails(contractDetails)) {
     throw new Error("Contract details are malformed for route definition");
   }
+  const access = contractDetails["access"];
+  const auth = contractDetails["auth"];
+  if (access != null) {
+    const validAccess = ["public", "authenticated", "protected", "internal"];
+    if (!validAccess.includes(access)) {
+      throw new Error(
+        `Route '${contractDetails.name}': invalid access level '${access}'. Must be one of: ${validAccess.join(", ")}`
+      );
+    }
+    if (access === "public" && auth != null) {
+      throw new Error(
+        `Route '${contractDetails.name}': access 'public' cannot have auth configured`
+      );
+    }
+    if (access === "protected") {
+      if (!auth) {
+        throw new Error(
+          `Route '${contractDetails.name}': access 'protected' requires auth with roles, permissions, or scope`
+        );
+      }
+      if (!hasPermissionChecks(auth) && !hasRoleChecks(auth) && !hasScopeChecks(auth)) {
+        throw new Error(
+          `Route '${contractDetails.name}': access 'protected' requires at least one of allowedRoles, forbiddenRoles, allowedPermissions, forbiddenPermissions, or requiredScope`
+        );
+      }
+    }
+    if (access === "internal") {
+      if (!auth || !isHmacMethod(auth)) {
+        throw new Error(
+          `Route '${contractDetails.name}': access 'internal' requires HMAC auth`
+        );
+      }
+    }
+  }
   if (contractDetails.versions) {
     const parserTypes = Object.values(contractDetails.versions).map(
       (version) => discriminateBody(schemaValidator, version.body)?.parserType
@@ -4168,6 +4202,44 @@ function generateOpenApiSpecs(schemaValidator, serverUrls, serverDescriptions, a
   );
 }
 
+// src/http/telemetry/auditLogger.ts
+import { createHash } from "crypto";
+var AuditLogger = class {
+  #otel;
+  constructor(otel) {
+    this.#otel = otel;
+  }
+  append(entry) {
+    try {
+      this.#otel.info(
+        {
+          "log.type": "audit",
+          "audit.timestamp": entry.timestamp,
+          "audit.userId": entry.userId ?? "",
+          "audit.tenantId": entry.tenantId ?? "",
+          "audit.route": entry.route,
+          "audit.method": entry.method,
+          "audit.bodyHash": entry.bodyHash,
+          "audit.status": entry.status,
+          "audit.duration": entry.duration,
+          "audit.redactedFields": entry.redactedFields.join(","),
+          "audit.eventType": entry.eventType,
+          _meta: true
+        },
+        `audit:${entry.eventType} ${entry.method} ${entry.route} ${entry.status}`
+      );
+    } catch (error) {
+      console.error("Failed to emit audit log via OTEL:", error);
+    }
+  }
+  static hashBody(body) {
+    if (body === void 0 || body === null || body === "") {
+      return "";
+    }
+    return createHash("sha256").update(body).digest("hex");
+  }
+};
+
 // src/http/telemetry/evaluateTelemetryOptions.ts
 function evaluateTelemetryOptions(telemetryOptions) {
   return {
@@ -4188,6 +4260,73 @@ function evaluateTelemetryOptions(telemetryOptions) {
 function metricsDefinitions(metrics2) {
   return metrics2;
 }
+
+// src/http/rateLimit/rateLimiter.ts
+var READ_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var RateLimiter = class {
+  constructor(cache) {
+    this.cache = cache;
+  }
+  /**
+   * Check whether the given key is within its rate limit.
+   *
+   * The counter is read from the cache, incremented, and written back.
+   * If the cache is unreachable the limiter **fails open** (allows the
+   * request) so that a cache outage does not take down the service.
+   *
+   * @param key - The rate limit key (see {@link RateLimiter.buildKey}).
+   * @param limit - Maximum number of requests allowed in the window.
+   * @param windowMs - Window duration in milliseconds.
+   */
+  async check(key, limit, windowMs) {
+    try {
+      const now = Date.now();
+      let counter;
+      try {
+        const record = await this.cache.readRecord(key);
+        counter = record.value;
+        if (now >= counter.resetAt) {
+          counter = { count: 0, resetAt: now + windowMs };
+        }
+      } catch {
+        counter = { count: 0, resetAt: now + windowMs };
+      }
+      counter.count += 1;
+      const ttl = Math.max(counter.resetAt - now, 1);
+      await this.cache.putRecord({
+        key,
+        value: counter,
+        ttlMilliseconds: ttl
+      });
+      const allowed = counter.count <= limit;
+      const remaining = Math.max(limit - counter.count, 0);
+      return { allowed, remaining, resetAt: counter.resetAt };
+    } catch {
+      console.warn(`[RateLimiter] Cache error for key "${key}". Failing open.`);
+      return { allowed: true, remaining: limit, resetAt: 0 };
+    }
+  }
+  /**
+   * Build a rate limit key from request context parts.
+   *
+   * Format: `ratelimit:{tenantId}:{route}:{userId}:{operationType}`
+   *
+   * When `tenantId` or `userId` is `null`, the placeholder `"anon"` is used.
+   */
+  static buildKey(parts) {
+    const tenant = parts.tenantId ?? "anon";
+    const user = parts.userId ?? "anon";
+    return `ratelimit:${tenant}:${parts.route}:${user}:${parts.operationType}`;
+  }
+  /**
+   * Determine whether an HTTP method is a read or write operation.
+   *
+   * GET, HEAD, and OPTIONS are reads; everything else is a write.
+   */
+  static operationType(method) {
+    return READ_METHODS.has(method.toUpperCase()) ? "read" : "write";
+  }
+};
 export {
   ATTR_API_NAME,
   ATTR_APPLICATION_ID,
@@ -4196,12 +4335,14 @@ export {
   ATTR_HTTP_RESPONSE_STATUS_CODE,
   ATTR_HTTP_ROUTE,
   ATTR_SERVICE_NAME,
+  AuditLogger,
   ForklaunchExpressLikeApplication,
   ForklaunchExpressLikeRouter,
   HTTPStatuses,
   OPENAPI_DEFAULT_VERSION,
   OpenTelemetryCollector,
   PinoLogger,
+  RateLimiter,
   createContext,
   createHmacToken,
   delete_,