@ts-cloud/core 0.7.108 → 0.7.109

package/dist/index.js

@@ -45382,8 +45382,9 @@ import { cpSync, mkdtempSync, rmSync, writeFileSync as writeFileSync3 } from "no
 import { tmpdir } from "node:os";
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join7, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-function adapterSourcePath() {
-  return join7(dirname2(fileURLToPath(import.meta.url)), "runtime", "adapter.ts");
+var RUNTIME_SOURCES = ["adapter.ts", "recursion.ts", "auto-recursion.ts"];
+function runtimeSourceDir() {
+  return join7(dirname2(fileURLToPath(import.meta.url)), "runtime");
 }
 function runBuildHooks(hooks, cwd, onStep) {
   for (const hook of hooks ?? []) {
@@ -45408,7 +45409,8 @@ async function packageServerlessApp(opts) {
   const entryPath = isAbsolute2(entry) ? entry : join7(projectRoot, entry);
   const stage = mkdtempSync(join7(tmpdir(), "tscloud-pkg-"));
   try {
-    cpSync(adapterSourcePath(), join7(stage, "adapter.ts"));
+    for (const source of RUNTIME_SOURCES)
+      cpSync(join7(runtimeSourceDir(), source), join7(stage, source));
     const bootstrapPath = join7(stage, "bootstrap.ts");
     writeFileSync3(bootstrapPath, generateBootstrap({ entryImport: entryPath, adapterImport: "./adapter" }));
     opts.onStep?.("bundling application");
@@ -46475,6 +46477,239 @@ function resolveLatestNode(major) {
     throw new Error(`No Node release found for major version ${major}`);
   return match.version.replace(/^v/, "");
 }
+// src/serverless/runtime/auto-recursion.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// src/serverless/runtime/recursion.ts
+import { createHash as createHash5 } from "node:crypto";
+var DEPTH_HEADER = "x-ts-cloud-invoke-depth";
+var CHAIN_HEADER = "x-ts-cloud-invoke-chain";
+var TRACE_HEADER = "x-ts-cloud-trace-id";
+function functionFingerprint(functionId) {
+  return createHash5("sha256").update(functionId).digest("hex").slice(0, 8);
+}
+var DEFAULT_RECURSION_LIMITS = {
+  maxDepth: 10,
+  maxRepeats: 3,
+  maxInvocationsPerTrace: 100,
+  traceWindowMs: 60000,
+  breakerThreshold: 5,
+  breakerCooldownMs: 60000
+};
+function readHeader(headers, name) {
+  if (typeof headers.get === "function")
+    return headers.get(name) ?? undefined;
+  const record = headers;
+  return record[name] ?? record[name.toLowerCase()] ?? record[name.toUpperCase()];
+}
+function parseChain(value, maxEntries = 64) {
+  if (!value)
+    return [];
+  return value.split(".").map((entry) => entry.trim()).filter((entry) => /^[0-9a-f]{8}$/.test(entry)).slice(-maxEntries);
+}
+function inspectInvocation(context, limits = DEFAULT_RECURSION_LIMITS) {
+  const fingerprint = functionFingerprint(context.functionId);
+  const incoming = parseChain(readHeader(context.headers, CHAIN_HEADER));
+  const traceId = context.traceId ?? readHeader(context.headers, TRACE_HEADER) ?? crypto.randomUUID();
+  const chain = [...incoming, fingerprint];
+  const repeats = incoming.filter((entry) => entry === fingerprint).length;
+  const selfInvocation = incoming[incoming.length - 1] === fingerprint;
+  const headerDepth = Number.parseInt(readHeader(context.headers, DEPTH_HEADER) ?? "", 10);
+  const depth = Math.max(chain.length, Number.isFinite(headerDepth) ? headerDepth + 1 : 0);
+  let reason = "ok";
+  if (depth > limits.maxDepth)
+    reason = "depth_exceeded";
+  else if (repeats >= limits.maxRepeats)
+    reason = "cycle_detected";
+  else if (selfInvocation && limits.maxRepeats <= 1)
+    reason = "self_invocation";
+  return {
+    reason,
+    depth,
+    chain,
+    traceId,
+    selfInvocation,
+    repeats,
+    propagate: {
+      [DEPTH_HEADER]: String(depth),
+      [CHAIN_HEADER]: chain.join("."),
+      [TRACE_HEADER]: traceId
+    }
+  };
+}
+var MESSAGES = {
+  ok: "",
+  depth_exceeded: "Invocation chain is deeper than the configured limit; the call was refused to stop a runaway loop.",
+  cycle_detected: "This function already appears in the invocation chain; the call was refused as a recursion loop.",
+  self_invocation: "This function invoked itself directly; the call was refused.",
+  trace_budget_exceeded: "This request has already made more invocations than its budget allows.",
+  breaker_open: "Recursion protection is open for this function after repeated loop detections."
+};
+
+class RecursionGuard {
+  limits;
+  clock;
+  traces = new Map;
+  breakers = new Map;
+  constructor(limits = DEFAULT_RECURSION_LIMITS, clock = () => Date.now()) {
+    this.limits = limits;
+    this.clock = clock;
+  }
+  check(context) {
+    const now = this.clock();
+    this.expireTraces(now);
+    const inspected = inspectInvocation(context, this.limits);
+    const breaker = this.breakers.get(context.functionId);
+    if (breaker?.openUntil != null && breaker.openUntil > now)
+      return this.deny(context.functionId, inspected, "breaker_open", now, false);
+    if (inspected.reason !== "ok")
+      return this.deny(context.functionId, inspected, inspected.reason, now, true);
+    const tally = this.traces.get(inspected.traceId) ?? { count: 0, firstAt: now };
+    if (tally.count >= this.limits.maxInvocationsPerTrace) {
+      this.traces.set(inspected.traceId, tally);
+      return this.deny(context.functionId, inspected, "trace_budget_exceeded", now, true);
+    }
+    this.traces.set(inspected.traceId, { count: tally.count + 1, firstAt: tally.firstAt });
+    if (breaker)
+      this.breakers.set(context.functionId, { consecutiveBlocks: 0 });
+    return { ...inspected, allowed: true, reason: "ok", propagate: inspected.propagate };
+  }
+  deny(functionId, inspected, reason, now, countTowardBreaker) {
+    if (countTowardBreaker) {
+      const state = this.breakers.get(functionId) ?? { consecutiveBlocks: 0 };
+      const consecutiveBlocks = state.consecutiveBlocks + 1;
+      this.breakers.set(functionId, {
+        consecutiveBlocks,
+        openUntil: consecutiveBlocks >= this.limits.breakerThreshold ? now + this.limits.breakerCooldownMs : state.openUntil
+      });
+    }
+    return { ...inspected, allowed: false, reason, message: MESSAGES[reason] };
+  }
+  breakerOpen(functionId) {
+    const state = this.breakers.get(functionId);
+    return state?.openUntil != null && state.openUntil > this.clock();
+  }
+  reset(functionId) {
+    if (functionId) {
+      this.breakers.delete(functionId);
+      return;
+    }
+    this.breakers.clear();
+    this.traces.clear();
+  }
+  expireTraces(now) {
+    if (this.traces.size === 0)
+      return;
+    for (const [traceId, tally] of this.traces)
+      if (now - tally.firstAt > this.limits.traceWindowMs)
+        this.traces.delete(traceId);
+  }
+  get trackedTraces() {
+    return this.traces.size;
+  }
+}
+function propagationHeaders(verdict) {
+  return { ...verdict.propagate };
+}
+function recursionBlockedResponse(verdict) {
+  return {
+    status: 508,
+    headers: { "content-type": "application/json", "x-ts-cloud-recursion-blocked": verdict.reason },
+    body: {
+      error: "recursion_blocked",
+      reason: verdict.reason,
+      message: verdict.message ?? MESSAGES[verdict.reason],
+      depth: verdict.depth,
+      traceId: verdict.traceId
+    }
+  };
+}
+
+// src/serverless/runtime/auto-recursion.ts
+var invocationContext = new AsyncLocalStorage;
+function envFlag(name) {
+  const raw = globalThis.process?.env?.[name];
+  if (raw == null || raw === "")
+    return;
+  return raw !== "0" && raw.toLowerCase() !== "false";
+}
+function defaultFunctionId() {
+  const env = globalThis.process?.env ?? {};
+  return env.TS_CLOUD_FUNCTION_ID || env.AWS_LAMBDA_FUNCTION_NAME || env.FUNCTION_NAME || "function";
+}
+function resolveRecursionConfig(config2) {
+  const explicit = config2 === false ? { enabled: false } : config2 ?? {};
+  const envEnabled = envFlag("TS_CLOUD_RECURSION_PROTECTION");
+  const envDetectionOnly = envFlag("TS_CLOUD_RECURSION_DETECTION_ONLY");
+  return {
+    enabled: envEnabled ?? explicit.enabled ?? true,
+    detectionOnly: envDetectionOnly ?? explicit.detectionOnly ?? false,
+    limits: { ...DEFAULT_RECURSION_LIMITS, ...explicit.limits },
+    functionId: explicit.functionId ?? defaultFunctionId()
+  };
+}
+var installedFetch;
+var originalFetch;
+function installRecursionFetch() {
+  const current = globalThis.fetch;
+  if (!current || installedFetch === current)
+    return () => {};
+  originalFetch = current;
+  const wrapped = async (input, init) => {
+    const verdict = invocationContext.getStore();
+    if (!verdict)
+      return originalFetch(input, init);
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    for (const [key, value] of Object.entries(propagationHeaders(verdict)))
+      headers.set(key, value);
+    if (input instanceof Request)
+      return originalFetch(new Request(input, { headers }), init);
+    return originalFetch(input, { ...init, headers });
+  };
+  Object.assign(wrapped, current);
+  globalThis.fetch = wrapped;
+  installedFetch = wrapped;
+  return () => {
+    if (globalThis.fetch === installedFetch && originalFetch)
+      globalThis.fetch = originalFetch;
+    installedFetch = undefined;
+  };
+}
+var sharedGuard;
+var sharedLimits;
+function sharedRecursionGuard(limits) {
+  if (!sharedGuard || JSON.stringify(sharedLimits) !== JSON.stringify(limits)) {
+    sharedGuard = new RecursionGuard(limits);
+    sharedLimits = limits;
+  }
+  return sharedGuard;
+}
+function resetRecursionRuntime() {
+  sharedGuard = undefined;
+  sharedLimits = undefined;
+  if (installedFetch && originalFetch && globalThis.fetch === installedFetch)
+    globalThis.fetch = originalFetch;
+  installedFetch = undefined;
+  originalFetch = undefined;
+}
+function checkInvocation(headers, config2) {
+  const resolved = resolveRecursionConfig(config2);
+  if (!resolved.enabled)
+    return;
+  const guard = sharedRecursionGuard(resolved.limits);
+  const context = { functionId: resolved.functionId, headers };
+  const verdict = guard.check(context);
+  return {
+    verdict,
+    blocked: !verdict.allowed && !resolved.detectionOnly,
+    observed: !verdict.allowed && resolved.detectionOnly
+  };
+}
+function withInvocation(verdict, work) {
+  installRecursionFetch();
+  return invocationContext.run(verdict, work);
+}
+
 // src/serverless/runtime/adapter.ts
 function resolveApp(mod) {
   const m = mod;
@@ -46566,9 +46801,25 @@ function createHttpHandler(handler8, opts) {
         };
       }
     }
+    const recursion = checkInvocation(event.headers ?? {}, opts?.recursionProtection);
+    if (recursion?.blocked) {
+      const blocked = recursionBlockedResponse(recursion.verdict);
+      return {
+        statusCode: blocked.status,
+        headers: { ...blocked.headers, "retry-after": "60" },
+        body: JSON.stringify(blocked.body),
+        isBase64Encoded: false
+      };
+    }
     const request = eventToRequest(event);
-    const response = await handler8(request);
-    return responseToResult(response);
+    if (!recursion) {
+      const response = await handler8(request);
+      return responseToResult(response);
+    }
+    if (recursion.observed) {
+      console.warn(`[ts-cloud] recursion detected (${recursion.verdict.reason}) at depth ${recursion.verdict.depth}; detection-only mode let it run`);
+    }
+    return withInvocation(recursion.verdict, async () => responseToResult(await handler8(request)));
   };
 }
 function parseRecordBody(body) {
@@ -46735,7 +46986,7 @@ function buildPhpRuntimeLayerZip(options = {}) {
 }
 // src/serverless-php/package-php.ts
 import { execSync as execSync2 } from "node:child_process";
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 import { readdirSync as readdirSync6, readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
 import { join as join11, relative as relative4, resolve as resolve2 } from "node:path";
 var PHP_DEFAULT_EXCLUDES = [
@@ -46800,7 +47051,7 @@ function packagePhpApp(opts) {
   const handler8 = opts.app.handlers?.http ?? "public/index.php";
   return {
     zip: zip2,
-    sha256: createHash5("sha256").update(zip2).digest("hex"),
+    sha256: createHash6("sha256").update(zip2).digest("hex"),
     handlers: {
       http: handler8,
       queue: opts.app.handlers?.queue ?? handler8,
@@ -47253,6 +47504,7 @@ export {
   withSecurity,
   withQueue,
   withMonitoring,
+  withInvocation,
   withDatabase,
   withCache,
   withCDN,
@@ -47280,6 +47532,7 @@ export {
   signRequestAsync,
   signRequest,
   sharedRuntimeLoop,
+  sharedRecursionGuard,
   sha256,
   setStateDir,
   serviceMeshManager,
@@ -47307,6 +47560,7 @@ export {
   resolveServerlessArtifactBucketName,
   resolveServerlessAppStackName,
   resolveRegion,
+  resolveRecursionConfig,
   resolveQueues,
   resolveQueueNames,
   resolveProjectStackName,
@@ -47320,11 +47574,14 @@ export {
   resolveCloudProvider,
   resolveAppDatabase,
   resolveApp,
+  resetRecursionRuntime,
   requiresReplacement,
   replicaManager,
   regionPairManager,
+  recursionBlockedResponse,
   quickHash,
   queueManagementManager,
+  propagationHeaders,
   progressiveDeploymentManager,
   processInChunks,
   previewNotifications,
@@ -47335,6 +47592,7 @@ export {
   performanceManager,
   parseXMLResponse,
   parseJSONResponse,
+  parseChain,
   parallelWithRetry,
   parallelMap,
   parallel,
@@ -47366,6 +47624,9 @@ export {
   isManagementDashboardSiteName,
   isLocalDevelopment,
   isLikelyTypo,
+  invocationContext,
+  installRecursionFetch,
+  inspectInvocation,
   imageScanningManager,
   healthCheckManager,
   hashString,
@@ -47425,6 +47686,7 @@ export {
   generateBootstrap,
   generateApprovalConfig,
   generateAppImageDockerfile,
+  functionFingerprint,
   fromWebIdentity,
   fromSharedCredentials,
   fromEnvironment,
@@ -47501,6 +47763,7 @@ export {
   clearSigningKeyCache,
   chunk,
   checkServiceQuotas,
+  checkInvocation,
   checkIAMPermissions,
   certificateManager,
   categorizeChanges,
@@ -47526,6 +47789,7 @@ export {
   TemplateCache,
   TemplateBuilder,
   TaskList,
+  TRACE_HEADER,
   SyntheticsManager,
   StorageAdvancedManager,
   Storage,
@@ -47556,6 +47820,7 @@ export {
   Registry,
   RegionPairManager,
   Redirects,
+  RecursionGuard,
   RealtimePresets,
   RateLimiter,
   REPLContext,
@@ -47628,8 +47893,10 @@ export {
   DNSSECManager,
   DNS,
   DLQMonitoringManager,
+  DEPTH_HEADER,
   DEFAULT_STATE_DIR,
   DEFAULT_SERVICE_LIMITS,
+  DEFAULT_RECURSION_LIMITS,
   DASHBOARD_STATE_DIR,
   DASHBOARD_PORT_SPAN,
   DASHBOARD_PORT_BASE,
@@ -47650,6 +47917,7 @@ export {
   CanaryManager,
   Cache,
   COMMON_CROSS_ACCOUNT_ROLES,
+  CHAIN_HEADER,
   CDN,
   BuildOptimizationManager,
   BounceComplaintHandler,

package/dist/runtime/adapter.ts

@@ -1,3 +1,6 @@
+import type { RecursionProtectionConfig } from './auto-recursion'
+import { checkInvocation, withInvocation } from './auto-recursion'
+import { recursionBlockedResponse } from './recursion'
 /**
  * Serverless runtime adapter (Node/Bun).
  *
@@ -120,6 +123,12 @@ function isTextContentType(contentType: string | null): boolean {
 // ── HTTP ────────────────────────────────────────────────────────────────────
 
 export interface HttpAdapterOptions {
+  /**
+   * Recursion protection. On by default; pass `false` or set
+   * `TS_CLOUD_RECURSION_PROTECTION=0` to disable, or `{ detectionOnly: true }`
+   * to watch what it would block before it blocks anything.
+   */
+  recursionProtection?: RecursionProtectionConfig | false
   /**
    * Read maintenance state from the environment. When `MAINTENANCE_MODE` is
    * truthy, requests get a 503 unless they carry the bypass secret in the
@@ -228,9 +237,33 @@ export function createHttpHandler(handler: FetchHandler | undefined, opts?: Http
       }
     }
 
+    // Recursion protection runs after maintenance (a parked app should answer
+    // 503 either way) and before the handler, so a loop costs one rejected
+    // invocation rather than a full execution plus everything it calls.
+    const recursion = checkInvocation(event.headers ?? {}, opts?.recursionProtection)
+    if (recursion?.blocked) {
+      const blocked = recursionBlockedResponse(recursion.verdict)
+      return {
+        statusCode: blocked.status,
+        headers: { ...blocked.headers, 'retry-after': '60' },
+        body: JSON.stringify(blocked.body),
+        isBase64Encoded: false,
+      }
+    }
+
     const request = eventToRequest(event)
-    const response = await handler(request)
-    return responseToResult(response)
+    if (!recursion) {
+      const response = await handler(request)
+      return responseToResult(response)
+    }
+    if (recursion.observed) {
+      console.warn(
+        `[ts-cloud] recursion detected (${recursion.verdict.reason}) at depth ${recursion.verdict.depth}; detection-only mode let it run`,
+      )
+    }
+    // Run inside the invocation context so outbound fetch carries the chain.
+    // Without this the next hop starts a fresh chain and the loop is invisible.
+    return withInvocation(recursion.verdict, async () => responseToResult(await handler(request)))
   }
 }
 

package/dist/serverless/index.d.ts

@@ -10,3 +10,5 @@ export * from './app-image';
 export * from './runtime-resolve';
 export * from './runtimes';
 export * from './runtime/adapter';
+export * from './runtime/recursion';
+export * from './runtime/auto-recursion';

package/dist/serverless/runtime/adapter.d.ts

@@ -1,3 +1,4 @@
+import type { RecursionProtectionConfig } from './auto-recursion';
 /**
  * Serverless runtime adapter (Node/Bun).
  *
@@ -83,6 +84,12 @@ export interface ServerlessApp {
  */
 export declare function resolveApp(mod: unknown): ServerlessApp;
 export interface HttpAdapterOptions {
+    /**
+     * Recursion protection. On by default; pass `false` or set
+     * `TS_CLOUD_RECURSION_PROTECTION=0` to disable, or `{ detectionOnly: true }`
+     * to watch what it would block before it blocks anything.
+     */
+    recursionProtection?: RecursionProtectionConfig | false;
     /**
      * Read maintenance state from the environment. When `MAINTENANCE_MODE` is
      * truthy, requests get a 503 unless they carry the bypass secret in the

package/dist/serverless/runtime/auto-recursion.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Making recursion protection automatic.
+ *
+ * `recursion.ts` can detect a loop given an invocation's headers, but detection
+ * only helps if something calls it on every invocation and propagates the chain
+ * on every outbound request. Asking application authors to do that by hand
+ * means it protects the code that already thought about the problem, which is
+ * never the code that loops.
+ *
+ * So the runtime does both:
+ *
+ *   - Every inbound invocation is inspected before the handler runs.
+ *   - `fetch` is wrapped once, per process, to attach the current invocation's
+ *     chain to outbound requests.
+ *
+ * The chain rides in headers, so protection survives the hop between two
+ * separate functions and even between two separate deployments. A request that
+ * leaves the platform carries the headers too - they are namespaced and inert
+ * to anyone who does not read them.
+ *
+ * **Coverage, stated plainly.** This covers `fetch`, which is what the platform
+ * and modern application code use. A handler that reaches for `node:http`
+ * directly, or opens a raw socket, is not covered; the depth header still
+ * catches those when the receiving side is one of ours, but the chain does not.
+ */
+import type { RecursionLimits, RecursionVerdict } from './recursion';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { RecursionGuard } from './recursion';
+/**
+ * The invocation currently on the stack.
+ *
+ * `AsyncLocalStorage` rather than a module-level variable: a runtime handling
+ * concurrent invocations in one process would otherwise attribute one
+ * invocation's outbound calls to another's chain, which is both wrong and
+ * exactly the case where a loop is hardest to see.
+ */
+export declare const invocationContext: AsyncLocalStorage<RecursionVerdict>;
+export interface RecursionProtectionConfig {
+    /** Off entirely. The escape hatch for a workload that genuinely re-enters. */
+    enabled?: boolean;
+    limits?: Partial<RecursionLimits>;
+    /**
+     * Detect and report, but let the invocation run.
+     *
+     * The way to roll this out over an existing workload: watch what it would
+     * have blocked for a week before it blocks anything.
+     */
+    detectionOnly?: boolean;
+    /** Identifies this function in the chain. Defaults to the Lambda name. */
+    functionId?: string;
+}
+/**
+ * Resolve configuration from options and the environment.
+ *
+ * The environment wins, because turning protection off is an operational
+ * decision made under pressure - during an incident, from the console, without
+ * a redeploy. A config value that could not be overridden that way would be a
+ * config value someone works around by deleting the function.
+ */
+export declare function resolveRecursionConfig(config?: RecursionProtectionConfig | false): {
+    enabled: boolean;
+    detectionOnly: boolean;
+    limits: RecursionLimits;
+    functionId: string;
+};
+/**
+ * Wrap `fetch` so outbound calls carry the current chain.
+ *
+ * Idempotent: a runtime that creates handlers more than once must not stack
+ * wrappers, or a chain entry would be appended once per wrapper and a
+ * three-hop request would look like a nine-hop loop.
+ */
+export declare function installRecursionFetch(): () => void;
+/**
+ * One guard per process.
+ *
+ * The trace budget and the circuit breaker only mean anything if successive
+ * invocations in the same container share them - a fresh guard per invocation
+ * would reset the counters the loop is being counted with.
+ */
+export declare function sharedRecursionGuard(limits: RecursionLimits): RecursionGuard;
+/** Reset process state. Tests need it; nothing in production should call it. */
+export declare function resetRecursionRuntime(): void;
+export interface RecursionCheck {
+    verdict: RecursionVerdict;
+    /** True when the invocation should be refused. */
+    blocked: boolean;
+    /** True when a loop was detected but detection-only let it through. */
+    observed: boolean;
+}
+/**
+ * Inspect an invocation and prepare its context.
+ *
+ * Returns rather than throws, so the caller decides the response shape - a
+ * Lambda HTTP handler answers with a 508 payload while a queue handler needs to
+ * fail the record instead.
+ */
+export declare function checkInvocation(headers: Record<string, string | undefined> | Headers, config?: RecursionProtectionConfig | false): RecursionCheck | undefined;
+/** Run `work` with the invocation's chain attached to any outbound fetch. */
+export declare function withInvocation<T>(verdict: RecursionVerdict, work: () => Promise<T>): Promise<T>;

package/dist/serverless/runtime/auto-recursion.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/serverless/runtime/recursion.d.ts

@@ -0,0 +1,98 @@
+/** Depth of the current invocation, as an integer string. */
+export declare const DEPTH_HEADER = "x-ts-cloud-invoke-depth";
+/** Dot-separated short hashes of every function in the chain, oldest first. */
+export declare const CHAIN_HEADER = "x-ts-cloud-invoke-chain";
+/** Correlates every hop of one logical request. */
+export declare const TRACE_HEADER = "x-ts-cloud-trace-id";
+/** Chain entries are 8 hex chars: collision-safe enough for a bounded chain, cheap in a header. */
+export declare function functionFingerprint(functionId: string): string;
+export interface RecursionLimits {
+    /** Hard ceiling on chain length. Beyond this, block regardless of cycles. */
+    maxDepth: number;
+    /**
+     * How many times one function may appear in a single chain.
+     *
+     * Not 1: legitimate fan-out patterns re-enter the same handler (a recursive
+     * directory walk, a paginated crawl). Two repeats is a pattern; five is a loop.
+     */
+    maxRepeats: number;
+    /** Ceiling on invocations sharing one trace id, across all functions. */
+    maxInvocationsPerTrace: number;
+    /** How long a trace's tally is remembered. */
+    traceWindowMs: number;
+    /** Consecutive blocks before the breaker opens for a function. */
+    breakerThreshold: number;
+    /** How long the breaker stays open. */
+    breakerCooldownMs: number;
+}
+export declare const DEFAULT_RECURSION_LIMITS: RecursionLimits;
+export type RecursionReason = 'ok' | 'depth_exceeded' | 'cycle_detected' | 'self_invocation' | 'trace_budget_exceeded' | 'breaker_open';
+export interface InvocationContext {
+    functionId: string;
+    headers: Record<string, string | undefined> | Headers;
+    /** Overrides the header value. Useful when the caller already has a trace. */
+    traceId?: string;
+}
+export interface RecursionVerdict {
+    allowed: boolean;
+    reason: RecursionReason;
+    depth: number;
+    /** The chain including this invocation. */
+    chain: string[];
+    traceId: string;
+    /** True when the immediate caller was this same function. */
+    selfInvocation: boolean;
+    /** Times this function already appears in the incoming chain. */
+    repeats: number;
+    message?: string;
+    /** Headers to attach to any call this invocation makes. */
+    propagate: Record<string, string>;
+}
+/** Parse the chain header. Bounded and sanitized: a header is attacker-controllable. */
+export declare function parseChain(value: string | undefined, maxEntries?: number): string[];
+/**
+ * Inspect an invocation without recording anything.
+ *
+ * Pure, so a caller can reason about a chain in a test or a dry-run without a
+ * guard instance. {@link RecursionGuard.check} adds the stateful backstops.
+ */
+export declare function inspectInvocation(context: InvocationContext, limits?: RecursionLimits): Omit<RecursionVerdict, 'allowed' | 'reason' | 'message'> & {
+    reason: RecursionReason;
+};
+/**
+ * Stateful recursion guard.
+ *
+ * In-memory on purpose. A loop runs in seconds, so the state that matters is
+ * seconds old; paying a database round trip per invocation to protect against
+ * a cost problem would be its own cost problem. Each instance protects the
+ * process it runs in, and the header chain carries protection across processes.
+ */
+export declare class RecursionGuard {
+    private readonly limits;
+    private readonly clock;
+    private readonly traces;
+    private readonly breakers;
+    constructor(limits?: RecursionLimits, clock?: () => number);
+    /** Decide whether an invocation may proceed, and record it if so. */
+    check(context: InvocationContext): RecursionVerdict;
+    private deny;
+    /** Whether the breaker is currently open for a function. */
+    breakerOpen(functionId: string): boolean;
+    /** Close a breaker manually, e.g. after an operator fixes the loop. */
+    reset(functionId?: string): void;
+    private expireTraces;
+    get trackedTraces(): number;
+}
+/**
+ * Headers for an outbound call made from inside a function.
+ *
+ * Every HTTP client used by platform code should merge these in. Without
+ * propagation the chain resets at each hop and the loop becomes invisible.
+ */
+export declare function propagationHeaders(verdict: RecursionVerdict): Record<string, string>;
+/** The response a blocked invocation should return: a 508, as the RFC intends. */
+export declare function recursionBlockedResponse(verdict: RecursionVerdict): {
+    status: number;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};

package/dist/serverless/runtime/recursion.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -2543,6 +2543,17 @@ export interface ComputeConfig {
      * primary firewall. @default { enabled: true } for PHP boxes
      */
     firewall?: ComputeFirewallConfig;
+    /**
+     * Kernel-level flood mitigation (nftables + sysctl). On by default; `false`
+     * disables it. UFW decides which ports are open, this decides what happens to
+     * the traffic arriving on them.
+     */
+    ddos?: boolean | ComputeDdosConfig;
+    /**
+     * Web application firewall (zig-waf). On by default in detection-only mode,
+     * so it scores and logs without refusing anything until you promote it.
+     */
+    waf?: boolean | ComputeWafConfig;
     /**
      * Automatic unattended security/system updates (Forge's "maintenance"). When
      * enabled, installs `unattended-upgrades` and enables daily auto-updates.
@@ -2666,6 +2677,49 @@ export interface ComputeFirewallConfig {
     /** TCP ports to allow in addition to SSH/80/443 (always allowed). */
     allowedPorts?: number[];
 }
+/**
+ * Kernel-level flood mitigation (nftables + sysctl).
+ *
+ * On by default. UFW decides which ports are open; this decides what happens to
+ * the traffic arriving on them - SYN floods, connection exhaustion, slow-loris,
+ * and single-source hammering. Set `false` to skip it entirely.
+ */
+export interface ComputeDdosConfig {
+    enabled?: boolean;
+    /** Ports the ruleset protects. @default [80, 443] */
+    ports?: number[];
+    /** CIDRs that bypass every limit: monitoring, office IPs, a load balancer. */
+    allowlist?: string[];
+    /** CIDRs dropped outright. */
+    blocklist?: string[];
+    /** Count what would be dropped without dropping it. */
+    monitorOnly?: boolean;
+    thresholds?: {
+        newConnectionsPerSecond?: number;
+        concurrentPerSource?: number;
+        synPerSecond?: number;
+        burst?: number;
+        icmpPerSecond?: number;
+        banSeconds?: number;
+    };
+}
+/**
+ * Web application firewall (zig-waf), configured at provision time.
+ *
+ * Defaults to `detection`: rules evaluate and matches are logged and scored,
+ * nothing is blocked. Promote to `blocking` once you have read your own
+ * detection log - a ruleset nobody has checked against real traffic will refuse
+ * some of it.
+ */
+export interface ComputeWafConfig {
+    mode?: 'off' | 'detection' | 'blocking';
+    /** OWASP CRS paranoia level. 1 is the only level safe unattended. */
+    paranoiaLevel?: 1 | 2 | 3 | 4;
+    /** Inbound anomaly score at which a request is blocked in `blocking` mode. */
+    inboundThreshold?: number;
+    /** Paths never inspected. Each one is an unguarded route. */
+    bypassPaths?: string[];
+}
 /** Scheduled database backup configuration. See {@link ComputeConfig.backups}. */
 export interface ComputeBackupConfig {
     /** Enable scheduled backups. @default false */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ts-cloud/core",
   "type": "module",
-  "version": "0.7.108",
+  "version": "0.7.109",
   "description": "Core CloudFormation generation library for ts-cloud",
   "author": "Chris Breuer <chris@stacksjs.com>",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.7.108"
+    "@ts-cloud/aws-types": "0.7.109"
   },
   "devDependencies": {
     "typescript": "^7.0.2"