@vivero/stoma 0.1.0-rc.10

package/dist/utils/cidr.d.ts

@@ -0,0 +1,58 @@
+/**
+ * IPv4/IPv6 CIDR parsing and range matching utilities.
+ *
+ * Used by the {@link ipFilter} policy to check client IPs against
+ * allowlists and denylists. Supports both individual IPs and CIDR notation
+ * for IPv4 (`10.0.0.0/8`) and IPv6 (`2001:db8::/32`).
+ *
+ * IPv4 uses 32-bit unsigned integers for fast bitwise matching.
+ * IPv6 uses BigInt for 128-bit address arithmetic.
+ *
+ * @module cidr
+ */
+/**
+ * Parsed IPv4 CIDR range represented as 32-bit network address and mask.
+ */
+interface ParsedCIDRv4 {
+    readonly version: 4;
+    /** Network address as a 32-bit unsigned integer. */
+    readonly network: number;
+    /** Subnet mask as a 32-bit unsigned integer. */
+    readonly mask: number;
+}
+/**
+ * Parsed IPv6 CIDR range represented as 128-bit BigInt network address and mask.
+ */
+interface ParsedCIDRv6 {
+    readonly version: 6;
+    /** Network address as a 128-bit unsigned BigInt. */
+    readonly network: bigint;
+    /** Subnet mask as a 128-bit unsigned BigInt. */
+    readonly mask: bigint;
+}
+/**
+ * Discriminated union of parsed IPv4 and IPv6 CIDR ranges.
+ * Use the `version` field to narrow the type.
+ */
+type ParsedCIDR = ParsedCIDRv4 | ParsedCIDRv6;
+/**
+ * Parse a CIDR string (IPv4 or IPv6) into a network address and mask.
+ * Bare IPs without a prefix length are treated as `/32` (IPv4) or `/128` (IPv6).
+ *
+ * @param cidr - IP address or CIDR notation string (IPv4 or IPv6).
+ * @returns Parsed range, or `null` if the input is invalid.
+ */
+declare function parseCIDR(cidr: string): ParsedCIDR | null;
+/**
+ * Check if an IP address (IPv4 or IPv6) falls within any of the parsed CIDR ranges.
+ *
+ * IPv4 addresses only match IPv4 ranges and vice versa - there is no
+ * cross-family matching.
+ *
+ * @param ip - IP address string.
+ * @param ranges - Pre-parsed CIDR ranges from {@link parseCIDR}.
+ * @returns `true` if the IP matches any range.
+ */
+declare function isInRange(ip: string, ranges: ParsedCIDR[]): boolean;
+
+export { type ParsedCIDR, type ParsedCIDRv4, type ParsedCIDRv6, isInRange, parseCIDR };

package/dist/utils/cidr.js

@@ -0,0 +1,107 @@
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return -1;
+  let result = 0;
+  for (const part of parts) {
+    const n = Number(part);
+    if (Number.isNaN(n) || n < 0 || n > 255) return -1;
+    result = result << 8 | n;
+  }
+  return result >>> 0;
+}
+function parseIPv4CIDR(ip, prefix) {
+  const addr = ipv4ToInt(ip);
+  if (addr === -1) return null;
+  if (prefix < 0 || prefix > 32) return null;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return { version: 4, network: (addr & mask) >>> 0, mask };
+}
+const IPV6_FULL_MASK = (1n << 128n) - 1n;
+function ipv6ToBigInt(raw) {
+  let addr = raw;
+  const zoneIdx = addr.indexOf("%");
+  if (zoneIdx !== -1) {
+    addr = addr.slice(0, zoneIdx);
+  }
+  addr = addr.toLowerCase();
+  const doubleColonIdx = addr.indexOf("::");
+  let left;
+  let right;
+  if (doubleColonIdx !== -1) {
+    if (addr.indexOf("::", doubleColonIdx + 2) !== -1) return null;
+    const leftPart = addr.slice(0, doubleColonIdx);
+    const rightPart = addr.slice(doubleColonIdx + 2);
+    left = leftPart === "" ? [] : leftPart.split(":");
+    right = rightPart === "" ? [] : rightPart.split(":");
+    const totalGroups = left.length + right.length;
+    if (totalGroups > 8) return null;
+    const fillCount = 8 - totalGroups;
+    const groups2 = [...left, ...Array(fillCount).fill("0"), ...right];
+    return groupsToBI(groups2);
+  }
+  const groups = addr.split(":");
+  if (groups.length !== 8) return null;
+  return groupsToBI(groups);
+}
+function groupsToBI(groups) {
+  if (groups.length !== 8) return null;
+  let result = 0n;
+  for (const group of groups) {
+    if (group.length === 0 || group.length > 4) return null;
+    const val = Number.parseInt(group, 16);
+    if (Number.isNaN(val) || val < 0 || val > 65535) return null;
+    result = result << 16n | BigInt(val);
+  }
+  return result;
+}
+function parseIPv6CIDR(ip, prefix) {
+  const addr = ipv6ToBigInt(ip);
+  if (addr === null) return null;
+  if (prefix < 0 || prefix > 128) return null;
+  const mask = prefix === 0 ? 0n : IPV6_FULL_MASK << BigInt(128 - prefix) & IPV6_FULL_MASK;
+  return { version: 6, network: addr & mask, mask };
+}
+function isIPv6(input) {
+  return input.includes(":");
+}
+function parseCIDR(cidr) {
+  const slash = cidr.indexOf("/");
+  if (slash === -1) {
+    if (isIPv6(cidr)) {
+      return parseIPv6CIDR(cidr, 128);
+    }
+    const addr = ipv4ToInt(cidr);
+    if (addr === -1) return null;
+    return { version: 4, network: addr, mask: 4294967295 >>> 0 };
+  }
+  const ipPart = cidr.slice(0, slash);
+  const bits = Number(cidr.slice(slash + 1));
+  if (Number.isNaN(bits)) return null;
+  if (isIPv6(ipPart)) {
+    return parseIPv6CIDR(ipPart, bits);
+  }
+  return parseIPv4CIDR(ipPart, bits);
+}
+function isInRange(ip, ranges) {
+  if (isIPv6(ip)) {
+    const addr2 = ipv6ToBigInt(ip);
+    if (addr2 === null) return false;
+    for (const range of ranges) {
+      if (range.version !== 6) continue;
+      if ((addr2 & range.mask) === range.network) return true;
+    }
+    return false;
+  }
+  const addr = ipv4ToInt(ip);
+  if (addr === -1) return false;
+  for (const range of ranges) {
+    if (range.version !== 4) continue;
+    if ((addr & range.mask) >>> 0 === range.network) return true;
+  }
+  return false;
+}
+export {
+  isInRange,
+  parseCIDR
+};
+//# sourceMappingURL=cidr.js.map

package/dist/utils/cidr.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/cidr.ts"],"sourcesContent":["/**\n * IPv4/IPv6 CIDR parsing and range matching utilities.\n *\n * Used by the {@link ipFilter} policy to check client IPs against\n * allowlists and denylists. Supports both individual IPs and CIDR notation\n * for IPv4 (`10.0.0.0/8`) and IPv6 (`2001:db8::/32`).\n *\n * IPv4 uses 32-bit unsigned integers for fast bitwise matching.\n * IPv6 uses BigInt for 128-bit address arithmetic.\n *\n * @module cidr\n */\n\n// ── Discriminated union types ────────────────────────────────────────\n\n/**\n * Parsed IPv4 CIDR range represented as 32-bit network address and mask.\n */\nexport interface ParsedCIDRv4 {\n  readonly version: 4;\n  /** Network address as a 32-bit unsigned integer. */\n  readonly network: number;\n  /** Subnet mask as a 32-bit unsigned integer. */\n  readonly mask: number;\n}\n\n/**\n * Parsed IPv6 CIDR range represented as 128-bit BigInt network address and mask.\n */\nexport interface ParsedCIDRv6 {\n  readonly version: 6;\n  /** Network address as a 128-bit unsigned BigInt. */\n  readonly network: bigint;\n  /** Subnet mask as a 128-bit unsigned BigInt. */\n  readonly mask: bigint;\n}\n\n/**\n * Discriminated union of parsed IPv4 and IPv6 CIDR ranges.\n * Use the `version` field to narrow the type.\n */\nexport type ParsedCIDR = ParsedCIDRv4 | ParsedCIDRv6;\n\n// ── IPv4 internals ───────────────────────────────────────────────────\n\n/**\n * Parse an IPv4 address to a 32-bit unsigned integer.\n * Returns `-1` for anything that isn't a valid dotted-quad.\n */\nfunction ipv4ToInt(ip: string): number {\n  const parts = ip.split(\".\");\n  if (parts.length !== 4) return -1;\n  let result = 0;\n  for (const part of parts) {\n    const n = Number(part);\n    if (Number.isNaN(n) || n < 0 || n > 255) return -1;\n    result = (result << 8) | n;\n  }\n  return result >>> 0; // unsigned\n}\n\n/**\n * Parse an IPv4 CIDR string into a `ParsedCIDRv4`.\n * Bare IPs without a prefix length are treated as `/32`.\n */\nfunction parseIPv4CIDR(ip: string, prefix: number): ParsedCIDRv4 | null {\n  const addr = ipv4ToInt(ip);\n  if (addr === -1) return null;\n  if (prefix < 0 || prefix > 32) return null;\n\n  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;\n  return { version: 4, network: (addr & mask) >>> 0, mask };\n}\n\n// ── IPv6 internals ───────────────────────────────────────────────────\n\n/** Full 128-bit mask for IPv6. */\nconst IPV6_FULL_MASK = (1n << 128n) - 1n;\n\n/**\n * Parse an IPv6 address string into a 128-bit BigInt.\n * Handles `::` zero compression, zone IDs (`%eth0`), and uppercase hex.\n * Returns `null` for invalid addresses.\n */\nfunction ipv6ToBigInt(raw: string): bigint | null {\n  // Strip zone ID (e.g. \"fe80::1%eth0\" → \"fe80::1\")\n  let addr = raw;\n  const zoneIdx = addr.indexOf(\"%\");\n  if (zoneIdx !== -1) {\n    addr = addr.slice(0, zoneIdx);\n  }\n\n  addr = addr.toLowerCase();\n\n  // Handle :: compression\n  const doubleColonIdx = addr.indexOf(\"::\");\n  let left: string[];\n  let right: string[];\n\n  if (doubleColonIdx !== -1) {\n    // Reject multiple ::\n    if (addr.indexOf(\"::\", doubleColonIdx + 2) !== -1) return null;\n\n    const leftPart = addr.slice(0, doubleColonIdx);\n    const rightPart = addr.slice(doubleColonIdx + 2);\n\n    left = leftPart === \"\" ? [] : leftPart.split(\":\");\n    right = rightPart === \"\" ? [] : rightPart.split(\":\");\n\n    const totalGroups = left.length + right.length;\n    if (totalGroups > 8) return null;\n\n    // Fill middle with zeros\n    const fillCount = 8 - totalGroups;\n    const groups = [...left, ...Array(fillCount).fill(\"0\"), ...right];\n    return groupsToBI(groups);\n  }\n\n  // No :: - must have exactly 8 groups\n  const groups = addr.split(\":\");\n  if (groups.length !== 8) return null;\n  return groupsToBI(groups);\n}\n\n/**\n * Convert an array of exactly 8 hex group strings into a 128-bit BigInt.\n */\nfunction groupsToBI(groups: string[]): bigint | null {\n  if (groups.length !== 8) return null;\n  let result = 0n;\n  for (const group of groups) {\n    if (group.length === 0 || group.length > 4) return null;\n    const val = Number.parseInt(group, 16);\n    if (Number.isNaN(val) || val < 0 || val > 0xffff) return null;\n    result = (result << 16n) | BigInt(val);\n  }\n  return result;\n}\n\n/**\n * Parse an IPv6 CIDR string into a `ParsedCIDRv6`.\n * Bare addresses without a prefix length are treated as `/128`.\n */\nfunction parseIPv6CIDR(ip: string, prefix: number): ParsedCIDRv6 | null {\n  const addr = ipv6ToBigInt(ip);\n  if (addr === null) return null;\n  if (prefix < 0 || prefix > 128) return null;\n\n  const mask =\n    prefix === 0\n      ? 0n\n      : (IPV6_FULL_MASK << BigInt(128 - prefix)) & IPV6_FULL_MASK;\n  return { version: 6, network: addr & mask, mask };\n}\n\n// ── Public API ───────────────────────────────────────────────────────\n\n/**\n * Detect whether a CIDR or IP string is IPv6.\n * Presence of `:` indicates IPv6 (IPv4 dotted-quad never contains colons).\n */\nfunction isIPv6(input: string): boolean {\n  return input.includes(\":\");\n}\n\n/**\n * Parse a CIDR string (IPv4 or IPv6) into a network address and mask.\n * Bare IPs without a prefix length are treated as `/32` (IPv4) or `/128` (IPv6).\n *\n * @param cidr - IP address or CIDR notation string (IPv4 or IPv6).\n * @returns Parsed range, or `null` if the input is invalid.\n */\nexport function parseCIDR(cidr: string): ParsedCIDR | null {\n  const slash = cidr.indexOf(\"/\");\n\n  if (slash === -1) {\n    // Bare IP - no prefix length\n    if (isIPv6(cidr)) {\n      return parseIPv6CIDR(cidr, 128);\n    }\n    const addr = ipv4ToInt(cidr);\n    if (addr === -1) return null;\n    return { version: 4, network: addr, mask: 0xffffffff >>> 0 };\n  }\n\n  const ipPart = cidr.slice(0, slash);\n  const bits = Number(cidr.slice(slash + 1));\n  if (Number.isNaN(bits)) return null;\n\n  if (isIPv6(ipPart)) {\n    return parseIPv6CIDR(ipPart, bits);\n  }\n  return parseIPv4CIDR(ipPart, bits);\n}\n\n/**\n * Check if an IP address (IPv4 or IPv6) falls within any of the parsed CIDR ranges.\n *\n * IPv4 addresses only match IPv4 ranges and vice versa - there is no\n * cross-family matching.\n *\n * @param ip - IP address string.\n * @param ranges - Pre-parsed CIDR ranges from {@link parseCIDR}.\n * @returns `true` if the IP matches any range.\n */\nexport function isInRange(ip: string, ranges: ParsedCIDR[]): boolean {\n  if (isIPv6(ip)) {\n    const addr = ipv6ToBigInt(ip);\n    if (addr === null) return false;\n    for (const range of ranges) {\n      if (range.version !== 6) continue;\n      if ((addr & range.mask) === range.network) return true;\n    }\n    return false;\n  }\n\n  // IPv4 path\n  const addr = ipv4ToInt(ip);\n  if (addr === -1) return false;\n  for (const range of ranges) {\n    if (range.version !== 4) continue;\n    if ((addr & range.mask) >>> 0 === range.network) return true;\n  }\n  return false;\n}\n"],"mappings":"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","names":["groups","addr"]}

package/dist/utils/debug.d.ts

@@ -0,0 +1 @@
+export { DebugLogger, createDebugFactory, createDebugger, matchNamespace, noopDebugLogger } from '@vivero/stoma-core';

package/dist/utils/debug.js

@@ -0,0 +1,13 @@
+import {
+  createDebugFactory,
+  createDebugger,
+  matchNamespace,
+  noopDebugLogger
+} from "@vivero/stoma-core";
+export {
+  createDebugFactory,
+  createDebugger,
+  matchNamespace,
+  noopDebugLogger
+};
+//# sourceMappingURL=debug.js.map

package/dist/utils/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/debug.ts"],"sourcesContent":["/**\n * Re-exports from `@vivero/stoma-core`.\n *\n * The debug module lives in `packages/core` and is shared across all Stoma\n * packages. This file exists so that gateway-internal imports\n * (`../utils/debug`) continue to resolve without a 12-file refactor.\n *\n * @module debug\n */\nexport {\n  createDebugFactory,\n  createDebugger,\n  type DebugLogger,\n  matchNamespace,\n  noopDebugLogger,\n} from \"@vivero/stoma-core\";\n"],"mappings":"AASA;AAAA,EACE;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/utils/headers.d.ts

@@ -0,0 +1,68 @@
+import { Context } from 'hono';
+
+/**
+ * HTTP header utilities for Stoma policies.
+ *
+ * Consolidates common header manipulation patterns to avoid duplication
+ * across policies (auth, proxy, transform, etc.).
+ *
+ * @module utils/headers
+ */
+
+/**
+ * Sanitize a header value to prevent header injection attacks.
+ *
+ * Strips control characters (CR, LF, NUL) that could allow attackers
+ * to inject or manipulate HTTP headers.
+ *
+ * @param value - The header value to sanitize
+ * @returns The sanitized value
+ */
+declare function sanitizeHeaderValue(value: string): string;
+/**
+ * Escape a string for safe inclusion in an HTTP header value.
+ *
+ * Adds backslash escaping for double quotes to prevent header injection.
+ *
+ * @param value - The value to escape
+ * @returns The escaped value
+ */
+declare function escapeHeaderValue(value: string): string;
+/**
+ * Create a mutable clone of the request headers from a Hono context.
+ *
+ * The Workers runtime has immutable Request.headers. This function creates
+ * a mutable Headers object that can be modified and then applied back
+ * to the request.
+ *
+ * @param c - The Hono context
+ * @returns A new mutable Headers object cloned from the request
+ */
+declare function cloneRequestHeaders(c: Context): Headers;
+/**
+ * Apply modified headers back to the request in a Hono context.
+ *
+ * @param c - The Hono context
+ * @param headers - The modified headers to apply
+ */
+declare function applyRequestHeaders(c: Context, headers: Headers): void;
+/**
+ * Modify request headers with a callback function.
+ *
+ * This is a convenience wrapper that combines cloneRequestHeaders and
+ * applyRequestHeaders into a single operation.
+ *
+ * @example
+ * ```ts
+ * withModifiedHeaders(c, (headers) => {
+ *   headers.set("X-Custom", "value");
+ *   headers.delete("X-Removed");
+ * });
+ * ```
+ *
+ * @param c - The Hono context
+ * @param mutator - Function to modify the headers
+ */
+declare function withModifiedHeaders(c: Context, mutator: (headers: Headers) => void): void;
+
+export { applyRequestHeaders, cloneRequestHeaders, escapeHeaderValue, sanitizeHeaderValue, withModifiedHeaders };

package/dist/utils/headers.js

@@ -0,0 +1,25 @@
+function sanitizeHeaderValue(value) {
+  return value.replace(/[\r\n\0]/g, "");
+}
+function escapeHeaderValue(value) {
+  return value.replace(/"/g, '\\"');
+}
+function cloneRequestHeaders(c) {
+  return new Headers(c.req.raw.headers);
+}
+function applyRequestHeaders(c, headers) {
+  c.req.raw = new Request(c.req.raw, { headers });
+}
+function withModifiedHeaders(c, mutator) {
+  const headers = cloneRequestHeaders(c);
+  mutator(headers);
+  applyRequestHeaders(c, headers);
+}
+export {
+  applyRequestHeaders,
+  cloneRequestHeaders,
+  escapeHeaderValue,
+  sanitizeHeaderValue,
+  withModifiedHeaders
+};
+//# sourceMappingURL=headers.js.map

package/dist/utils/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/headers.ts"],"sourcesContent":["/**\n * HTTP header utilities for Stoma policies.\n *\n * Consolidates common header manipulation patterns to avoid duplication\n * across policies (auth, proxy, transform, etc.).\n *\n * @module utils/headers\n */\nimport type { Context } from \"hono\";\n\n/**\n * Sanitize a header value to prevent header injection attacks.\n *\n * Strips control characters (CR, LF, NUL) that could allow attackers\n * to inject or manipulate HTTP headers.\n *\n * @param value - The header value to sanitize\n * @returns The sanitized value\n */\nexport function sanitizeHeaderValue(value: string): string {\n  return value.replace(/[\\r\\n\\0]/g, \"\");\n}\n\n/**\n * Escape a string for safe inclusion in an HTTP header value.\n *\n * Adds backslash escaping for double quotes to prevent header injection.\n *\n * @param value - The value to escape\n * @returns The escaped value\n */\nexport function escapeHeaderValue(value: string): string {\n  return value.replace(/\"/g, '\\\\\"');\n}\n\n/**\n * Create a mutable clone of the request headers from a Hono context.\n *\n * The Workers runtime has immutable Request.headers. This function creates\n * a mutable Headers object that can be modified and then applied back\n * to the request.\n *\n * @param c - The Hono context\n * @returns A new mutable Headers object cloned from the request\n */\nexport function cloneRequestHeaders(c: Context): Headers {\n  return new Headers(c.req.raw.headers);\n}\n\n/**\n * Apply modified headers back to the request in a Hono context.\n *\n * @param c - The Hono context\n * @param headers - The modified headers to apply\n */\nexport function applyRequestHeaders(c: Context, headers: Headers): void {\n  c.req.raw = new Request(c.req.raw, { headers });\n}\n\n/**\n * Modify request headers with a callback function.\n *\n * This is a convenience wrapper that combines cloneRequestHeaders and\n * applyRequestHeaders into a single operation.\n *\n * @example\n * ```ts\n * withModifiedHeaders(c, (headers) => {\n *   headers.set(\"X-Custom\", \"value\");\n *   headers.delete(\"X-Removed\");\n * });\n * ```\n *\n * @param c - The Hono context\n * @param mutator - Function to modify the headers\n */\nexport function withModifiedHeaders(\n  c: Context,\n  mutator: (headers: Headers) => void\n): void {\n  const headers = cloneRequestHeaders(c);\n  mutator(headers);\n  applyRequestHeaders(c, headers);\n}\n"],"mappings":"AAmBO,SAAS,oBAAoB,OAAuB;AACzD,SAAO,MAAM,QAAQ,aAAa,EAAE;AACtC;AAUO,SAAS,kBAAkB,OAAuB;AACvD,SAAO,MAAM,QAAQ,MAAM,KAAK;AAClC;AAYO,SAAS,oBAAoB,GAAqB;AACvD,SAAO,IAAI,QAAQ,EAAE,IAAI,IAAI,OAAO;AACtC;AAQO,SAAS,oBAAoB,GAAY,SAAwB;AACtE,IAAE,IAAI,MAAM,IAAI,QAAQ,EAAE,IAAI,KAAK,EAAE,QAAQ,CAAC;AAChD;AAmBO,SAAS,oBACd,GACA,SACM;AACN,QAAM,UAAU,oBAAoB,CAAC;AACrC,UAAQ,OAAO;AACf,sBAAoB,GAAG,OAAO;AAChC;","names":[]}

package/dist/utils/ip.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared client IP extraction utility.
+ *
+ * Centralises the IP header lookup logic used by rate limiting, IP filtering,
+ * and request logging. The header priority order is configurable - the first
+ * header that contains a value wins.
+ *
+ * @module ip
+ */
+/** Default ordered list of headers to inspect for the client IP. */
+declare const DEFAULT_IP_HEADERS: string[];
+interface ExtractClientIpOptions {
+    /** Ordered list of headers to inspect. Default: ["cf-connecting-ip", "x-forwarded-for"]. */
+    ipHeaders?: readonly string[];
+    /**
+     * List of trusted proxy IP ranges (CIDR notation).
+     * When specified, X-Forwarded-For will only be trusted if the client IP
+     * (leftmost) is within one of these ranges.
+     *
+     * @example
+     * // Only trust X-Forwarded-For from Cloudflare IPs
+     * { ipHeaders: ["cf-connecting-ip", "x-forwarded-for"], trustedProxies: ["173.245.48.0/20"] }
+     */
+    trustedProxies?: readonly string[];
+    /**
+     * When true, use the rightmost IP from X-Forwarded-For instead of leftmost.
+     * The rightmost IP is the one added by the most recent trusted proxy.
+     * Default: false.
+     */
+    useRightmostForwardedIp?: boolean;
+    /**
+     * Fallback IP address used when no headers match (e.g., the socket remote
+     * address from the Node.js HTTP server). This is checked after all
+     * configured headers have been exhausted.
+     */
+    fallbackAddress?: string;
+}
+/**
+ * Extract the client IP address from request headers.
+ *
+ * Iterates through `ipHeaders` in order. For comma-separated headers like
+ * `X-Forwarded-For`, the behavior depends on options:
+ * - By default, returns the first (leftmost) value
+ * - With `useRightmostForwardedIp: true`, returns the last (rightmost) value
+ * - With `trustedProxies`, validates the leftmost IP against trusted ranges
+ *
+ * @security The `X-Forwarded-For` header is trivially spoofable by clients
+ * outside of trusted proxy infrastructure. An attacker can set arbitrary IP
+ * values to bypass IP-based allowlists, rate limits, or geo-restrictions.
+ *
+ * To mitigate:
+ * 1. Use `cf-connecting-ip` when behind Cloudflare (not spoofable by clients)
+ * 2. Configure `trustedProxies` to validate X-Forwarded-For IPs
+ * 3. Use `useRightmostForwardedIp: true` when behind a trusted proxy
+ *
+ * @param headers - An object with a `.get(name)` method (e.g. `Headers`, Hono `c.req`).
+ * @param options - Configuration options for IP extraction.
+ * @returns The extracted IP address, or `"unknown"` if none found.
+ */
+declare function extractClientIp(headers: {
+    get(name: string): string | null | undefined;
+}, options?: ExtractClientIpOptions): string;
+
+export { DEFAULT_IP_HEADERS, type ExtractClientIpOptions, extractClientIp };

package/dist/utils/ip.js

@@ -0,0 +1,29 @@
+import { isInRange, parseCIDR } from "./cidr";
+const DEFAULT_IP_HEADERS = ["cf-connecting-ip", "x-forwarded-for"];
+function extractClientIp(headers, options = {}) {
+  const {
+    ipHeaders = DEFAULT_IP_HEADERS,
+    trustedProxies,
+    useRightmostForwardedIp = false,
+    fallbackAddress
+  } = options;
+  const parsedTrustedProxies = trustedProxies ? trustedProxies.map((cidr) => parseCIDR(cidr)).filter((r) => r !== null) : null;
+  for (const header of ipHeaders) {
+    const value = headers.get(header);
+    if (!value) continue;
+    const ips = value.split(",").map((ip) => ip.trim());
+    const clientIp = useRightmostForwardedIp ? ips[ips.length - 1] : ips[0];
+    if (parsedTrustedProxies && header.toLowerCase() === "x-forwarded-for") {
+      if (!isInRange(clientIp, parsedTrustedProxies)) {
+        continue;
+      }
+    }
+    return clientIp;
+  }
+  return fallbackAddress ?? "unknown";
+}
+export {
+  DEFAULT_IP_HEADERS,
+  extractClientIp
+};
+//# sourceMappingURL=ip.js.map

package/dist/utils/ip.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/ip.ts"],"sourcesContent":["/**\n * Shared client IP extraction utility.\n *\n * Centralises the IP header lookup logic used by rate limiting, IP filtering,\n * and request logging. The header priority order is configurable - the first\n * header that contains a value wins.\n *\n * @module ip\n */\n\nimport { isInRange, type ParsedCIDR, parseCIDR } from \"./cidr\";\n\n/** Default ordered list of headers to inspect for the client IP. */\nexport const DEFAULT_IP_HEADERS = [\"cf-connecting-ip\", \"x-forwarded-for\"];\n\nexport interface ExtractClientIpOptions {\n  /** Ordered list of headers to inspect. Default: [\"cf-connecting-ip\", \"x-forwarded-for\"]. */\n  ipHeaders?: readonly string[];\n  /**\n   * List of trusted proxy IP ranges (CIDR notation).\n   * When specified, X-Forwarded-For will only be trusted if the client IP\n   * (leftmost) is within one of these ranges.\n   *\n   * @example\n   * // Only trust X-Forwarded-For from Cloudflare IPs\n   * { ipHeaders: [\"cf-connecting-ip\", \"x-forwarded-for\"], trustedProxies: [\"173.245.48.0/20\"] }\n   */\n  trustedProxies?: readonly string[];\n  /**\n   * When true, use the rightmost IP from X-Forwarded-For instead of leftmost.\n   * The rightmost IP is the one added by the most recent trusted proxy.\n   * Default: false.\n   */\n  useRightmostForwardedIp?: boolean;\n  /**\n   * Fallback IP address used when no headers match (e.g., the socket remote\n   * address from the Node.js HTTP server). This is checked after all\n   * configured headers have been exhausted.\n   */\n  fallbackAddress?: string;\n}\n\n/**\n * Extract the client IP address from request headers.\n *\n * Iterates through `ipHeaders` in order. For comma-separated headers like\n * `X-Forwarded-For`, the behavior depends on options:\n * - By default, returns the first (leftmost) value\n * - With `useRightmostForwardedIp: true`, returns the last (rightmost) value\n * - With `trustedProxies`, validates the leftmost IP against trusted ranges\n *\n * @security The `X-Forwarded-For` header is trivially spoofable by clients\n * outside of trusted proxy infrastructure. An attacker can set arbitrary IP\n * values to bypass IP-based allowlists, rate limits, or geo-restrictions.\n *\n * To mitigate:\n * 1. Use `cf-connecting-ip` when behind Cloudflare (not spoofable by clients)\n * 2. Configure `trustedProxies` to validate X-Forwarded-For IPs\n * 3. Use `useRightmostForwardedIp: true` when behind a trusted proxy\n *\n * @param headers - An object with a `.get(name)` method (e.g. `Headers`, Hono `c.req`).\n * @param options - Configuration options for IP extraction.\n * @returns The extracted IP address, or `\"unknown\"` if none found.\n */\nexport function extractClientIp(\n  headers: { get(name: string): string | null | undefined },\n  options: ExtractClientIpOptions = {}\n): string {\n  const {\n    ipHeaders = DEFAULT_IP_HEADERS,\n    trustedProxies,\n    useRightmostForwardedIp = false,\n    fallbackAddress,\n  } = options;\n\n  const parsedTrustedProxies: ParsedCIDR[] | null = trustedProxies\n    ? trustedProxies\n        .map((cidr) => parseCIDR(cidr))\n        .filter((r): r is ParsedCIDR => r !== null)\n    : null;\n\n  for (const header of ipHeaders) {\n    const value = headers.get(header);\n    if (!value) continue;\n\n    const ips = value.split(\",\").map((ip) => ip.trim());\n    const clientIp = useRightmostForwardedIp ? ips[ips.length - 1] : ips[0];\n\n    // If trustedProxies is configured, validate against it\n    if (parsedTrustedProxies && header.toLowerCase() === \"x-forwarded-for\") {\n      if (!isInRange(clientIp, parsedTrustedProxies)) {\n        // Client IP is not from trusted proxy - don't trust this header\n        continue;\n      }\n    }\n\n    return clientIp;\n  }\n  return fallbackAddress ?? \"unknown\";\n}\n"],"mappings":"AAUA,SAAS,WAA4B,iBAAiB;AAG/C,MAAM,qBAAqB,CAAC,oBAAoB,iBAAiB;AAmDjE,SAAS,gBACd,SACA,UAAkC,CAAC,GAC3B;AACR,QAAM;AAAA,IACJ,YAAY;AAAA,IACZ;AAAA,IACA,0BAA0B;AAAA,IAC1B;AAAA,EACF,IAAI;AAEJ,QAAM,uBAA4C,iBAC9C,eACG,IAAI,CAAC,SAAS,UAAU,IAAI,CAAC,EAC7B,OAAO,CAAC,MAAuB,MAAM,IAAI,IAC5C;AAEJ,aAAW,UAAU,WAAW;AAC9B,UAAM,QAAQ,QAAQ,IAAI,MAAM;AAChC,QAAI,CAAC,MAAO;AAEZ,UAAM,MAAM,MAAM,MAAM,GAAG,EAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;AAClD,UAAM,WAAW,0BAA0B,IAAI,IAAI,SAAS,CAAC,IAAI,IAAI,CAAC;AAGtE,QAAI,wBAAwB,OAAO,YAAY,MAAM,mBAAmB;AACtE,UAAI,CAAC,UAAU,UAAU,oBAAoB,GAAG;AAE9C;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACA,SAAO,mBAAmB;AAC5B;","names":[]}

package/dist/utils/redact.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Field redaction utility for safe logging of request/response bodies.
+ *
+ * Supports dot-notation paths (`auth.token`) and single-level wildcards
+ * (`*.password`) to match fields at any nesting level. Always deep-clones
+ * before mutating - the original object is never modified.
+ *
+ * @module redact
+ */
+/** Configuration for field redaction. */
+interface RedactConfig {
+    /** JSON field paths to redact (e.g., `"password"`, `"*.secret"`, `"auth.token"`). */
+    paths: string[];
+    /** Replacement text. Default: `"[REDACTED]"`. */
+    replacement?: string;
+}
+/**
+ * Redact sensitive fields from an object for safe logging.
+ *
+ * Deep-clones the input, then replaces values at the specified paths
+ * with the replacement string. Non-object/non-array input passes
+ * through unchanged.
+ *
+ * @param obj - The value to redact (typically a parsed JSON body).
+ * @param config - Paths to redact and optional replacement text.
+ * @returns A deep-cloned copy with specified fields redacted.
+ */
+declare function redactFields(obj: unknown, config: RedactConfig): unknown;
+
+export { type RedactConfig, redactFields };

package/dist/utils/redact.js

@@ -0,0 +1,52 @@
+function redactFields(obj, config) {
+  if (!isPlainObject(obj) && !Array.isArray(obj)) {
+    return obj;
+  }
+  const replacement = config.replacement ?? "[REDACTED]";
+  const cloned = structuredClone(obj);
+  for (const path of config.paths) {
+    applyRedaction(cloned, path.split("."), 0, replacement);
+  }
+  return cloned;
+}
+function applyRedaction(obj, segments, depth, replacement) {
+  if (depth >= segments.length || obj == null) return;
+  const segment = segments[depth];
+  const isLast = depth === segments.length - 1;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      applyRedaction(item, segments, depth, replacement);
+    }
+    return;
+  }
+  if (!isPlainObject(obj)) return;
+  if (segment === "*") {
+    for (const key of Object.keys(obj)) {
+      if (isLast) {
+        obj[key] = replacement;
+      } else {
+        applyRedaction(
+          obj[key],
+          segments,
+          depth + 1,
+          replacement
+        );
+      }
+    }
+  } else {
+    const record = obj;
+    if (!(segment in record)) return;
+    if (isLast) {
+      record[segment] = replacement;
+    } else {
+      applyRedaction(record[segment], segments, depth + 1, replacement);
+    }
+  }
+}
+function isPlainObject(val) {
+  return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+export {
+  redactFields
+};
+//# sourceMappingURL=redact.js.map

package/dist/utils/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/redact.ts"],"sourcesContent":["/**\n * Field redaction utility for safe logging of request/response bodies.\n *\n * Supports dot-notation paths (`auth.token`) and single-level wildcards\n * (`*.password`) to match fields at any nesting level. Always deep-clones\n * before mutating - the original object is never modified.\n *\n * @module redact\n */\n\n/** Configuration for field redaction. */\nexport interface RedactConfig {\n  /** JSON field paths to redact (e.g., `\"password\"`, `\"*.secret\"`, `\"auth.token\"`). */\n  paths: string[];\n  /** Replacement text. Default: `\"[REDACTED]\"`. */\n  replacement?: string;\n}\n\n/**\n * Redact sensitive fields from an object for safe logging.\n *\n * Deep-clones the input, then replaces values at the specified paths\n * with the replacement string. Non-object/non-array input passes\n * through unchanged.\n *\n * @param obj - The value to redact (typically a parsed JSON body).\n * @param config - Paths to redact and optional replacement text.\n * @returns A deep-cloned copy with specified fields redacted.\n */\nexport function redactFields(obj: unknown, config: RedactConfig): unknown {\n  if (!isPlainObject(obj) && !Array.isArray(obj)) {\n    return obj;\n  }\n\n  const replacement = config.replacement ?? \"[REDACTED]\";\n  const cloned = structuredClone(obj);\n\n  for (const path of config.paths) {\n    applyRedaction(cloned, path.split(\".\"), 0, replacement);\n  }\n\n  return cloned;\n}\n\nfunction applyRedaction(\n  obj: unknown,\n  segments: string[],\n  depth: number,\n  replacement: string\n): void {\n  if (depth >= segments.length || obj == null) return;\n\n  const segment = segments[depth];\n  const isLast = depth === segments.length - 1;\n\n  if (Array.isArray(obj)) {\n    for (const item of obj) {\n      applyRedaction(item, segments, depth, replacement);\n    }\n    return;\n  }\n\n  if (!isPlainObject(obj)) return;\n\n  if (segment === \"*\") {\n    // Wildcard: apply to all keys at this level\n    for (const key of Object.keys(obj)) {\n      if (isLast) {\n        (obj as Record<string, unknown>)[key] = replacement;\n      } else {\n        applyRedaction(\n          (obj as Record<string, unknown>)[key],\n          segments,\n          depth + 1,\n          replacement\n        );\n      }\n    }\n  } else {\n    const record = obj as Record<string, unknown>;\n    if (!(segment in record)) return;\n\n    if (isLast) {\n      record[segment] = replacement;\n    } else {\n      applyRedaction(record[segment], segments, depth + 1, replacement);\n    }\n  }\n}\n\nfunction isPlainObject(val: unknown): val is Record<string, unknown> {\n  return typeof val === \"object\" && val !== null && !Array.isArray(val);\n}\n"],"mappings":"AA6BO,SAAS,aAAa,KAAc,QAA+B;AACxE,MAAI,CAAC,cAAc,GAAG,KAAK,CAAC,MAAM,QAAQ,GAAG,GAAG;AAC9C,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,OAAO,eAAe;AAC1C,QAAM,SAAS,gBAAgB,GAAG;AAElC,aAAW,QAAQ,OAAO,OAAO;AAC/B,mBAAe,QAAQ,KAAK,MAAM,GAAG,GAAG,GAAG,WAAW;AAAA,EACxD;AAEA,SAAO;AACT;AAEA,SAAS,eACP,KACA,UACA,OACA,aACM;AACN,MAAI,SAAS,SAAS,UAAU,OAAO,KAAM;AAE7C,QAAM,UAAU,SAAS,KAAK;AAC9B,QAAM,SAAS,UAAU,SAAS,SAAS;AAE3C,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,eAAW,QAAQ,KAAK;AACtB,qBAAe,MAAM,UAAU,OAAO,WAAW;AAAA,IACnD;AACA;AAAA,EACF;AAEA,MAAI,CAAC,cAAc,GAAG,EAAG;AAEzB,MAAI,YAAY,KAAK;AAEnB,eAAW,OAAO,OAAO,KAAK,GAAG,GAAG;AAClC,UAAI,QAAQ;AACV,QAAC,IAAgC,GAAG,IAAI;AAAA,MAC1C,OAAO;AACL;AAAA,UACG,IAAgC,GAAG;AAAA,UACpC;AAAA,UACA,QAAQ;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF,OAAO;AACL,UAAM,SAAS;AACf,QAAI,EAAE,WAAW,QAAS;AAE1B,QAAI,QAAQ;AACV,aAAO,OAAO,IAAI;AAAA,IACpB,OAAO;AACL,qBAAe,OAAO,OAAO,GAAG,UAAU,QAAQ,GAAG,WAAW;AAAA,IAClE;AAAA,EACF;AACF;AAEA,SAAS,cAAc,KAA8C;AACnE,SAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,CAAC,MAAM,QAAQ,GAAG;AACtE;","names":[]}

package/dist/utils/request-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate a unique request ID using the Web Crypto API.
+ *
+ * Returns a v4 UUID. Available in Cloudflare Workers, Deno, Node 19+,
+ * and modern browsers.
+ *
+ * @returns A v4 UUID string (e.g. `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`).
+ */
+declare function generateRequestId(): string;
+
+export { generateRequestId };

package/dist/utils/request-id.js

@@ -0,0 +1,7 @@
+function generateRequestId() {
+  return crypto.randomUUID();
+}
+export {
+  generateRequestId
+};
+//# sourceMappingURL=request-id.js.map

package/dist/utils/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/request-id.ts"],"sourcesContent":["/**\n * Generate a unique request ID using the Web Crypto API.\n *\n * Returns a v4 UUID. Available in Cloudflare Workers, Deno, Node 19+,\n * and modern browsers.\n *\n * @returns A v4 UUID string (e.g. `\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"`).\n */\nexport function generateRequestId(): string {\n  return crypto.randomUUID();\n}\n"],"mappings":"AAQO,SAAS,oBAA4B;AAC1C,SAAO,OAAO,WAAW;AAC3B;","names":[]}

package/dist/utils/timing-safe.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Constant-time string comparison to prevent timing side-channel attacks.
+ *
+ * Use this when comparing secrets (API keys, tokens, HMAC digests) to
+ * prevent an attacker from inferring the correct value by measuring
+ * response time differences.
+ *
+ * @module timing-safe
+ */
+/**
+ * Compare two strings in constant time.
+ *
+ * Returns `true` if `a` and `b` are identical, `false` otherwise.
+ * The comparison always examines every byte of the longer string,
+ * preventing timing side-channels that leak prefix information.
+ *
+ * @param a - First string to compare.
+ * @param b - Second string to compare.
+ * @returns `true` if the strings are identical.
+ *
+ * @example
+ * ```ts
+ * import { timingSafeEqual } from "@vivero/stoma";
+ *
+ * // Use in API key validators to prevent timing attacks
+ * const isValid = timingSafeEqual(providedKey, storedKey);
+ * ```
+ */
+declare function timingSafeEqual(a: string, b: string): boolean;
+
+export { timingSafeEqual };

package/dist/utils/timing-safe.js

@@ -0,0 +1,17 @@
+function timingSafeEqual(a, b) {
+  const encoder = new TextEncoder();
+  const bufA = encoder.encode(a);
+  const bufB = encoder.encode(b);
+  const maxLen = Math.max(bufA.length, bufB.length);
+  let mismatch = bufA.length !== bufB.length ? 1 : 0;
+  for (let i = 0; i < maxLen; i++) {
+    const byteA = i < bufA.length ? bufA[i] : 0;
+    const byteB = i < bufB.length ? bufB[i] : 0;
+    mismatch |= byteA ^ byteB;
+  }
+  return mismatch === 0;
+}
+export {
+  timingSafeEqual
+};
+//# sourceMappingURL=timing-safe.js.map

package/dist/utils/timing-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/timing-safe.ts"],"sourcesContent":["/**\n * Constant-time string comparison to prevent timing side-channel attacks.\n *\n * Use this when comparing secrets (API keys, tokens, HMAC digests) to\n * prevent an attacker from inferring the correct value by measuring\n * response time differences.\n *\n * @module timing-safe\n */\n\n/**\n * Compare two strings in constant time.\n *\n * Returns `true` if `a` and `b` are identical, `false` otherwise.\n * The comparison always examines every byte of the longer string,\n * preventing timing side-channels that leak prefix information.\n *\n * @param a - First string to compare.\n * @param b - Second string to compare.\n * @returns `true` if the strings are identical.\n *\n * @example\n * ```ts\n * import { timingSafeEqual } from \"@vivero/stoma\";\n *\n * // Use in API key validators to prevent timing attacks\n * const isValid = timingSafeEqual(providedKey, storedKey);\n * ```\n */\nexport function timingSafeEqual(a: string, b: string): boolean {\n  const encoder = new TextEncoder();\n  const bufA = encoder.encode(a);\n  const bufB = encoder.encode(b);\n\n  // Length mismatch - still compare to avoid early exit timing leak\n  const maxLen = Math.max(bufA.length, bufB.length);\n  let mismatch = bufA.length !== bufB.length ? 1 : 0;\n\n  for (let i = 0; i < maxLen; i++) {\n    // Use 0 as fallback for shorter buffer - still accumulates XOR\n    const byteA = i < bufA.length ? bufA[i] : 0;\n    const byteB = i < bufB.length ? bufB[i] : 0;\n    mismatch |= byteA ^ byteB;\n  }\n\n  return mismatch === 0;\n}\n"],"mappings":"AA6BO,SAAS,gBAAgB,GAAW,GAAoB;AAC7D,QAAM,UAAU,IAAI,YAAY;AAChC,QAAM,OAAO,QAAQ,OAAO,CAAC;AAC7B,QAAM,OAAO,QAAQ,OAAO,CAAC;AAG7B,QAAM,SAAS,KAAK,IAAI,KAAK,QAAQ,KAAK,MAAM;AAChD,MAAI,WAAW,KAAK,WAAW,KAAK,SAAS,IAAI;AAEjD,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK;AAE/B,UAAM,QAAQ,IAAI,KAAK,SAAS,KAAK,CAAC,IAAI;AAC1C,UAAM,QAAQ,IAAI,KAAK,SAAS,KAAK,CAAC,IAAI;AAC1C,gBAAY,QAAQ;AAAA,EACtB;AAEA,SAAO,aAAa;AACtB;","names":[]}

package/dist/utils/timing.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared timing utilities.
+ *
+ * @module timing
+ */
+/**
+ * Convert inclusive (onion-model) timings to self-time and reverse to
+ * execution order.
+ *
+ * `policiesToMiddleware()` records inclusive wall-clock time for each
+ * policy - meaning an outer policy's duration includes all inner
+ * policies plus the upstream. The timings array is ordered
+ * innermost-first (the innermost middleware finishes first and pushes
+ * its timing before outer ones).
+ *
+ * Self-time is computed as:
+ *   self[0] = inclusive[0]               (innermost, includes upstream)
+ *   self[i] = inclusive[i] - inclusive[i-1]   for i > 0
+ *
+ * The result is reversed so entries are in execution order (outermost
+ * policy first), which is the natural reading order for a waterfall.
+ */
+declare function toSelfTimes<T extends {
+    durationMs: number;
+}>(timings: T[]): T[];
+
+export { toSelfTimes };

package/dist/utils/timing.js

@@ -0,0 +1,12 @@
+function toSelfTimes(timings) {
+  const selfTimes = timings.map((entry, i) => ({
+    ...entry,
+    durationMs: i === 0 ? entry.durationMs : Math.max(0, entry.durationMs - timings[i - 1].durationMs)
+  }));
+  selfTimes.reverse();
+  return selfTimes;
+}
+export {
+  toSelfTimes
+};
+//# sourceMappingURL=timing.js.map

package/dist/utils/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/timing.ts"],"sourcesContent":["/**\n * Shared timing utilities.\n *\n * @module timing\n */\n\n/**\n * Convert inclusive (onion-model) timings to self-time and reverse to\n * execution order.\n *\n * `policiesToMiddleware()` records inclusive wall-clock time for each\n * policy - meaning an outer policy's duration includes all inner\n * policies plus the upstream. The timings array is ordered\n * innermost-first (the innermost middleware finishes first and pushes\n * its timing before outer ones).\n *\n * Self-time is computed as:\n *   self[0] = inclusive[0]               (innermost, includes upstream)\n *   self[i] = inclusive[i] - inclusive[i-1]   for i > 0\n *\n * The result is reversed so entries are in execution order (outermost\n * policy first), which is the natural reading order for a waterfall.\n */\nexport function toSelfTimes<T extends { durationMs: number }>(\n  timings: T[]\n): T[] {\n  const selfTimes = timings.map((entry, i) => ({\n    ...entry,\n    durationMs:\n      i === 0\n        ? entry.durationMs\n        : Math.max(0, entry.durationMs - timings[i - 1].durationMs),\n  }));\n\n  // Reverse: innermost-first → outermost-first (execution order)\n  selfTimes.reverse();\n  return selfTimes;\n}\n"],"mappings":"AAuBO,SAAS,YACd,SACK;AACL,QAAM,YAAY,QAAQ,IAAI,CAAC,OAAO,OAAO;AAAA,IAC3C,GAAG;AAAA,IACH,YACE,MAAM,IACF,MAAM,aACN,KAAK,IAAI,GAAG,MAAM,aAAa,QAAQ,IAAI,CAAC,EAAE,UAAU;AAAA,EAChE,EAAE;AAGF,YAAU,QAAQ;AAClB,SAAO;AACT;","names":[]}