@hoox-sh/hoox-shared 1.3.0 → 1.4.0

package/dist/kvUtils.d.ts

@@ -4,7 +4,7 @@
  */
 /**
  * Utility functions for KV operations
- * Shared across workers that need KV timestamp logging
+ * Shared across workers that need KV timestamp logging and parallel I/O
  */
 import type { KVNamespace } from "@cloudflare/workers-types";
 /**
@@ -21,6 +21,39 @@ export interface EnvWithKV {
  * @returns Promise that resolves when the operation completes
  */
 export declare function logKvTimestamp(env: EnvWithKV, prefix?: string): Promise<void>;
+/**
+ * Max keys per Workers KV bulk read (platform limit).
+ * @see https://developers.cloudflare.com/kv/api/read-key-value-pairs/
+ */
+export declare const KV_BULK_GET_MAX_KEYS = 100;
+/**
+ * Parallel / bulk KV gets — prefer over sequential `await kv.get` loops.
+ * Order of returned values matches `keys`.
+ *
+ * Uses native `kv.get(string[])` bulk reads (up to 100 keys per call) when
+ * available. Bulk reads count as a single operation against the Workers
+ * subrequest limit and avoid simultaneous-connection pressure.
+ * Falls back to `Promise.all` of individual gets for mocks / older runtimes.
+ */
+export declare function kvGetMany(kv: KVNamespace, keys: readonly string[]): Promise<Array<string | null>>;
+/**
+ * Parallel KV gets as a record keyed by the original key names.
+ */
+export declare function kvGetManyAsRecord(kv: KVNamespace, keys: readonly string[]): Promise<Record<string, string | null>>;
+export interface KvPutEntry {
+    key: string;
+    value: string;
+    options?: {
+        expirationTtl?: number;
+        expiration?: number;
+        metadata?: Record<string, unknown>;
+    };
+}
+/**
+ * Parallel KV puts — prefer over sequential `await kv.put` loops
+ * when writes are independent (no read-modify-write races).
+ */
+export declare function kvPutMany(kv: KVNamespace, entries: readonly KvPutEntry[]): Promise<void>;
 /**
  * Helper function to convert Headers to a plain object
  * @param headers - The Headers object to convert

package/dist/kvUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kvUtils.d.ts","sourceRoot":"","sources":["../src/kvUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,WAAW,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,MAAM,GAAE,MAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB"}
+{"version":3,"file":"kvUtils.d.ts","sourceRoot":"","sources":["../src/kvUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,WAAW,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,MAAM,GAAE,MAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAyBxC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CA0B/B;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAOxC;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;CACH;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,SAAS,UAAU,EAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB"}

package/dist/kvUtils.js

@@ -21,8 +21,10 @@ function toError(err, fallback = "Unknown error") {
     return err.message;
   if (typeof err === "string")
     return err;
-  if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
-    return err.message;
+  if (err && typeof err === "object" && "message" in err) {
+    const message = err.message;
+    if (typeof message === "string")
+      return message;
   }
   if (err === null || err === undefined)
     return fallback;
@@ -151,6 +153,53 @@ async function logKvTimestamp(env, prefix = "timestamp") {
     console.error(`Failed to log timestamp to KV: ${toError(error, "Unknown error")}`);
   }
 }
+var KV_BULK_GET_MAX_KEYS = 100;
+async function tryBulkGetChunk(kv, chunk) {
+  try {
+    const result = await kv.get([...chunk]);
+    if (!(result instanceof Map)) {
+      return null;
+    }
+    return chunk.map((key) => result.get(key) ?? null);
+  } catch {
+    return null;
+  }
+}
+async function kvGetMany(kv, keys) {
+  if (keys.length === 0)
+    return [];
+  const out = new Array(keys.length);
+  let offset = 0;
+  while (offset < keys.length) {
+    const chunk = keys.slice(offset, offset + KV_BULK_GET_MAX_KEYS);
+    const bulk = await tryBulkGetChunk(kv, chunk);
+    if (bulk === null) {
+      const rest = await Promise.all(keys.slice(offset).map((key) => kv.get(key)));
+      for (let i = 0;i < rest.length; i++) {
+        out[offset + i] = rest[i] ?? null;
+      }
+      return out;
+    }
+    for (let i = 0;i < bulk.length; i++) {
+      out[offset + i] = bulk[i] ?? null;
+    }
+    offset += chunk.length;
+  }
+  return out;
+}
+async function kvGetManyAsRecord(kv, keys) {
+  const values = await kvGetMany(kv, keys);
+  const out = {};
+  for (let i = 0;i < keys.length; i++) {
+    out[keys[i]] = values[i] ?? null;
+  }
+  return out;
+}
+async function kvPutMany(kv, entries) {
+  if (entries.length === 0)
+    return;
+  await Promise.all(entries.map((entry) => kv.put(entry.key, entry.value, entry.options)));
+}
 function headersToObject(headers) {
   const result = {};
   if (!headers)
@@ -166,5 +215,9 @@ function headersToObject(headers) {
 }
 export {
   logKvTimestamp,
-  headersToObject
+  kvPutMany,
+  kvGetManyAsRecord,
+  kvGetMany,
+  headersToObject,
+  KV_BULK_GET_MAX_KEYS
 };

package/dist/middleware/auth.d.ts

@@ -11,14 +11,17 @@ import type { MiddlewareHandler } from "../types/router";
 /**
  * Constant-time string comparison to prevent timing attacks.
  *
- * Length is NOT short-circuited: both strings are hashed to fixed-size
- * digests via a simple XOR-fold into equal-length buffers so that
- * unequal lengths do not leak via early return (length oracle).
+ * Length is NOT short-circuited: both strings are padded to equal length
+ * and XOR-folded so unequal lengths do not leak via early return
+ * (length oracle). Prefer {@link timingSafeEqualAsync} when Web Crypto
+ * is available — it hashes both sides to fixed-size digests first
+ * (Cloudflare Workers best practice).
  *
  * Note: true crypto.subtle.timingSafeEqual needs equal-length ArrayBuffers;
  * we pad both encodings to the same max length before XOR comparison.
  */
 export declare function timingSafeEqual(a: string, b: string): boolean;
+export declare function timingSafeEqualAsync(a: string, b: string): Promise<boolean>;
 /**
  * Environment bindings accepted for operator Bearer auth.
  * Prefer OPERATOR_API_KEY; INTERNAL_API_KEY remains a legacy alias.

package/dist/middleware/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAe7D;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,eAAe,GAAG,GAAG,GACzB,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,GAAG,eAAe,GACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAE1B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,GAAG,GAAG,GACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAqB1B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,iBAAiB,CAAC,eAAe,CAAC,CAUjF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAS7D,6FAA6F;AAC7F,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,EAAE,CASV;AA2BD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,mBAA4C,GACpD,QAAQ,GAAG,IAAI,CAcjB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,mBAA4C,GACpD,iBAAiB,CAAC,eAAe,CAAC,CAoBpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,mBAA4C,GACpD;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAezC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAe7D;AAmBD,wBAAsB,oBAAoB,CACxC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,eAAe,GAAG,GAAG,GACzB,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,GAAG,eAAe,GACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAE1B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,GAAG,GAAG,GACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyB1B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,iBAAiB,CAAC,eAAe,CAAC,CAUjF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAS7D,6FAA6F;AAC7F,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,EAAE,CASV;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,mBAA4C,GACpD,QAAQ,GAAG,IAAI,CAcjB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,mBAA4C,GACpD,iBAAiB,CAAC,eAAe,CAAC,CAoBpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,mBAA4C,GACpD;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAezC"}

package/dist/middleware/auth.js

@@ -23,12 +23,24 @@ function timingSafeEqual(a, b) {
   const len = Math.max(aBuf.length, bBuf.length);
   let result = aBuf.length === bBuf.length ? 0 : 1;
   for (let i = 0;i < len; i++) {
-    const av = i < aBuf.length ? aBuf[i] : 0;
-    const bv = i < bBuf.length ? bBuf[i] : 0;
+    const av = aBuf[i] ?? 0;
+    const bv = bBuf[i] ?? 0;
     result |= av ^ bv;
   }
   return result === 0;
 }
+async function timingSafeEqualAsync(a, b) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle || typeof subtle.digest !== "function" || typeof subtle.timingSafeEqual !== "function") {
+    return timingSafeEqual(a, b);
+  }
+  const encoder = new TextEncoder;
+  const [providedHash, expectedHash] = await Promise.all([
+    subtle.digest("SHA-256", encoder.encode(a)),
+    subtle.digest("SHA-256", encoder.encode(b))
+  ]);
+  return subtle.timingSafeEqual(providedHash, expectedHash);
+}
 function resolveOperatorApiKey(env) {
   const preferred = env.OPERATOR_API_KEY;
   if (typeof preferred === "string" && preferred.length > 0) {
@@ -53,7 +65,7 @@ async function requireOperatorAuth(request, env) {
   }
   const authHeader = request.headers.get("Authorization");
   const expectedHeader = `Bearer ${apiKey}`;
-  if (!authHeader || !timingSafeEqual(authHeader, expectedHeader)) {
+  if (!authHeader || !await timingSafeEqualAsync(authHeader, expectedHeader)) {
     return new Response(JSON.stringify({ error: "Unauthorized" }), {
       status: 401,
       headers: { "Content-Type": "application/json" }
@@ -86,12 +98,13 @@ function collectInternalAuthKeys(env, keyNames) {
   return keys;
 }
 function matchesAnyInternalAuthKey(providedKey, expectedKeys) {
+  let matched = false;
   for (const expected of expectedKeys) {
     if (timingSafeEqual(providedKey, expected)) {
-      return true;
+      matched = true;
     }
   }
-  return false;
+  return matched;
 }
 function internalAuthNotConfiguredResponse(keyNames) {
   const label = normalizeKeyNames(keyNames).join(" | ");
@@ -139,6 +152,7 @@ function checkInternalAuth(request, env, keyName = "INTERNAL_KEY_BINDING") {
   return { authorized: true };
 }
 export {
+  timingSafeEqualAsync,
   timingSafeEqual,
   resolveOperatorApiKey,
   requireOperatorAuth,

package/dist/middleware/index.d.ts

@@ -6,9 +6,10 @@
  * Barrel exports for shared middleware
  */
 export { createLogger, withRequestLog, type Logger, type LogContext, } from "./logger";
-export { requireAuth, requireOperatorAuth, createOperatorAuthMiddleware, resolveOperatorApiKey, requireInternalAuth, createInternalAuthMiddleware, checkInternalAuth, timingSafeEqual, collectInternalAuthKeys, type InternalAuthEnv, type InternalAuthKeyName, type OperatorAuthEnv, } from "./auth";
+export { requireAuth, requireOperatorAuth, createOperatorAuthMiddleware, resolveOperatorApiKey, requireInternalAuth, createInternalAuthMiddleware, checkInternalAuth, timingSafeEqual, timingSafeEqualAsync, collectInternalAuthKeys, type InternalAuthEnv, type InternalAuthKeyName, type OperatorAuthEnv, } from "./auth";
 export { createRateLimiter, type RateLimiter, type RateLimitConfig, } from "./rate-limit";
-export { validateJson, validateJsonLegacy, requireField, optionalField, } from "./validate";
+export { validateJson, validateJsonLegacy, parseJsonBody, requireField, optionalField, DEFAULT_MAX_JSON_BODY_BYTES, type ParseJsonBodyOptions, } from "./validate";
+export { safeWaitUntil, waitUntilAll, type WaitUntilHost } from "./wait-until";
 export { corsHeaders, resolveCorsOptions, type CorsEnv, publicCorsHeaders, internalCorsHeaders, handleCorsPreflightRequest, type CorsOptions, } from "./cors";
 export { secureHeaders, wrapWithSecurityHeaders, type SecurityHeadersOptions, SECURITY_HEADERS_DEFAULTS, } from "./security-headers";
 //# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,KAAK,MAAM,EACX,KAAK,UAAU,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,OAAO,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,KAAK,WAAW,GACjB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,KAAK,MAAM,EACX,KAAK,UAAU,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,2BAA2B,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,OAAO,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,KAAK,WAAW,GACjB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC"}

package/dist/middleware/index.js

@@ -21,8 +21,10 @@ function toError(err, fallback = "Unknown error") {
     return err.message;
   if (typeof err === "string")
     return err;
-  if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
-    return err.message;
+  if (err && typeof err === "object" && "message" in err) {
+    const message = err.message;
+    if (typeof message === "string")
+      return message;
   }
   if (err === null || err === undefined)
     return fallback;
@@ -149,12 +151,24 @@ function timingSafeEqual(a, b) {
   const len = Math.max(aBuf.length, bBuf.length);
   let result = aBuf.length === bBuf.length ? 0 : 1;
   for (let i = 0;i < len; i++) {
-    const av = i < aBuf.length ? aBuf[i] : 0;
-    const bv = i < bBuf.length ? bBuf[i] : 0;
+    const av = aBuf[i] ?? 0;
+    const bv = bBuf[i] ?? 0;
     result |= av ^ bv;
   }
   return result === 0;
 }
+async function timingSafeEqualAsync(a, b) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle || typeof subtle.digest !== "function" || typeof subtle.timingSafeEqual !== "function") {
+    return timingSafeEqual(a, b);
+  }
+  const encoder = new TextEncoder;
+  const [providedHash, expectedHash] = await Promise.all([
+    subtle.digest("SHA-256", encoder.encode(a)),
+    subtle.digest("SHA-256", encoder.encode(b))
+  ]);
+  return subtle.timingSafeEqual(providedHash, expectedHash);
+}
 function resolveOperatorApiKey(env) {
   const preferred = env.OPERATOR_API_KEY;
   if (typeof preferred === "string" && preferred.length > 0) {
@@ -179,7 +193,7 @@ async function requireOperatorAuth(request, env) {
   }
   const authHeader = request.headers.get("Authorization");
   const expectedHeader = `Bearer ${apiKey}`;
-  if (!authHeader || !timingSafeEqual(authHeader, expectedHeader)) {
+  if (!authHeader || !await timingSafeEqualAsync(authHeader, expectedHeader)) {
     return new Response(JSON.stringify({ error: "Unauthorized" }), {
       status: 401,
       headers: { "Content-Type": "application/json" }
@@ -212,12 +226,13 @@ function collectInternalAuthKeys(env, keyNames) {
   return keys;
 }
 function matchesAnyInternalAuthKey(providedKey, expectedKeys) {
+  let matched = false;
   for (const expected of expectedKeys) {
     if (timingSafeEqual(providedKey, expected)) {
-      return true;
+      matched = true;
     }
   }
-  return false;
+  return matched;
 }
 function internalAuthNotConfiguredResponse(keyNames) {
   const label = normalizeKeyNames(keyNames).join(" | ");
@@ -538,6 +553,7 @@ function createRateLimiter(kv, config) {
 }
 
 // src/middleware/validate.ts
+var DEFAULT_MAX_JSON_BODY_BYTES = 1048576;
 function validateJson(schema, data) {
   const result = schema.safeParse(data);
   if (!result.success) {
@@ -548,6 +564,39 @@ function validateJson(schema, data) {
   }
   return { ok: true, value: result.data };
 }
+async function parseJsonBody(request, schema, options = {}) {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_JSON_BODY_BYTES;
+  const contentLength = request.headers.get("content-length");
+  if (contentLength !== null) {
+    const declared = Number(contentLength);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      return {
+        ok: false,
+        error: `Request body too large (max ${maxBytes} bytes)`
+      };
+    }
+  }
+  let text;
+  try {
+    text = await request.text();
+  } catch {
+    return { ok: false, error: "Failed to read request body" };
+  }
+  const byteLength = new TextEncoder().encode(text).byteLength;
+  if (byteLength > maxBytes) {
+    return {
+      ok: false,
+      error: `Request body too large (max ${maxBytes} bytes)`
+    };
+  }
+  let data;
+  try {
+    data = text.length === 0 ? null : JSON.parse(text);
+  } catch {
+    return { ok: false, error: "Invalid JSON in request body" };
+  }
+  return validateJson(schema, data);
+}
 async function validateJsonLegacy(request) {
   try {
     const body = await request.json();
@@ -571,6 +620,32 @@ function optionalField(body, field, defaultValue) {
   return body[field];
 }
 
+// src/middleware/wait-until.ts
+function safeWaitUntil(ctx, promise, onError) {
+  ctx.waitUntil(promise.catch((err) => {
+    onError?.(err);
+    console.error(JSON.stringify({
+      message: "waitUntil background task failed",
+      error: err instanceof Error ? err.message : String(err)
+    }));
+  }));
+}
+function waitUntilAll(ctx, promises, onError) {
+  if (promises.length === 0)
+    return;
+  safeWaitUntil(ctx, Promise.allSettled(promises).then((results) => {
+    for (const result of results) {
+      if (result.status === "rejected") {
+        onError?.(result.reason);
+        console.error(JSON.stringify({
+          message: "waitUntilAll background task failed",
+          error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+        }));
+      }
+    }
+  }), onError);
+}
+
 // src/middleware/security-headers.ts
 var SECURITY_HEADERS_DEFAULTS = {
   xContentTypeOptions: "nosniff",
@@ -610,10 +685,13 @@ function wrapWithSecurityHeaders(response, options) {
 export {
   wrapWithSecurityHeaders,
   withRequestLog,
+  waitUntilAll,
   validateJsonLegacy,
   validateJson,
+  timingSafeEqualAsync,
   timingSafeEqual,
   secureHeaders,
+  safeWaitUntil,
   resolveOperatorApiKey,
   resolveCorsOptions,
   requireOperatorAuth,
@@ -621,6 +699,7 @@ export {
   requireField,
   requireAuth,
   publicCorsHeaders,
+  parseJsonBody,
   optionalField,
   internalCorsHeaders,
   handleCorsPreflightRequest,
@@ -631,5 +710,6 @@ export {
   corsHeaders,
   collectInternalAuthKeys,
   checkInternalAuth,
-  SECURITY_HEADERS_DEFAULTS
+  SECURITY_HEADERS_DEFAULTS,
+  DEFAULT_MAX_JSON_BODY_BYTES
 };

package/dist/middleware/logger.js

@@ -21,8 +21,10 @@ function toError(err, fallback = "Unknown error") {
     return err.message;
   if (typeof err === "string")
     return err;
-  if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
-    return err.message;
+  if (err && typeof err === "object" && "message" in err) {
+    const message = err.message;
+    if (typeof message === "string")
+      return message;
   }
   if (err === null || err === undefined)
     return fallback;

package/dist/middleware/validate.d.ts

@@ -10,11 +10,27 @@
  */
 import { z } from "zod";
 import type { Result } from "../types";
+/** Default body size cap for JSON request parsing (1 MiB). */
+export declare const DEFAULT_MAX_JSON_BODY_BYTES = 1048576;
+export interface ParseJsonBodyOptions {
+    /** Reject bodies larger than this many bytes (Content-Length or measured). */
+    maxBytes?: number;
+}
 /**
  * Validate unknown data against a Zod schema, returning a Result type.
  * Provides structured error messages from Zod issue paths.
  */
 export declare function validateJson<T extends z.ZodTypeAny>(schema: T, data: unknown): Result<z.infer<T>>;
+/**
+ * Parse a Request body as JSON and validate against a Zod schema.
+ * Enforces an optional max body size to stay within Workers memory limits.
+ *
+ * @example
+ * const parsed = await parseJsonBody(request, WebhookPayloadSchema);
+ * if (!parsed.ok) return Errors.badRequest(parsed.error);
+ * const payload = parsed.value;
+ */
+export declare function parseJsonBody<T extends z.ZodTypeAny>(request: Request, schema: T, options?: ParseJsonBodyOptions): Promise<Result<z.infer<T>>>;
 /**
  * Legacy signature: parse request body as JSON object.
  * Kept for backward compatibility with existing workers.

package/dist/middleware/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/middleware/validate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACjD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAWpB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAU1C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,CAAC,CAAC,CAKX;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,CAAC,GACd,CAAC,CAGH"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/middleware/validate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACjD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAWpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACxD,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAsC7B;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAU1C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,CAAC,CAAC,CAKX;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,CAAC,GACd,CAAC,CAGH"}

package/dist/middleware/validate.js

@@ -16,6 +16,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/middleware/validate.ts
+var DEFAULT_MAX_JSON_BODY_BYTES = 1048576;
 function validateJson(schema, data) {
   const result = schema.safeParse(data);
   if (!result.success) {
@@ -26,6 +27,39 @@ function validateJson(schema, data) {
   }
   return { ok: true, value: result.data };
 }
+async function parseJsonBody(request, schema, options = {}) {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_JSON_BODY_BYTES;
+  const contentLength = request.headers.get("content-length");
+  if (contentLength !== null) {
+    const declared = Number(contentLength);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      return {
+        ok: false,
+        error: `Request body too large (max ${maxBytes} bytes)`
+      };
+    }
+  }
+  let text;
+  try {
+    text = await request.text();
+  } catch {
+    return { ok: false, error: "Failed to read request body" };
+  }
+  const byteLength = new TextEncoder().encode(text).byteLength;
+  if (byteLength > maxBytes) {
+    return {
+      ok: false,
+      error: `Request body too large (max ${maxBytes} bytes)`
+    };
+  }
+  let data;
+  try {
+    data = text.length === 0 ? null : JSON.parse(text);
+  } catch {
+    return { ok: false, error: "Invalid JSON in request body" };
+  }
+  return validateJson(schema, data);
+}
 async function validateJsonLegacy(request) {
   try {
     const body = await request.json();
@@ -52,5 +86,7 @@ export {
   validateJsonLegacy,
   validateJson,
   requireField,
-  optionalField
+  parseJsonBody,
+  optionalField,
+  DEFAULT_MAX_JSON_BODY_BYTES
 };

package/dist/middleware/wait-until.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Production helpers around ExecutionContext / DurableObjectState.waitUntil.
+ *
+ * Floating / rejected background promises are a common Workers footgun:
+ * the isolate may exit before work finishes, and rejections can go unhandled.
+ * Always pass promises through these helpers (or await them).
+ *
+ * Never destructure `waitUntil` off `ctx` — it loses `this` and throws
+ * "Illegal invocation" at runtime.
+ *
+ * Accepts any object with waitUntil so the same helper works for both
+ * fetch ExecutionContext and DurableObjectState (DO lifecycle).
+ */
+/** Minimal surface shared by ExecutionContext and DurableObjectState. */
+export type WaitUntilHost = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+/**
+ * Schedule background work that must not affect the HTTP response.
+ * Captures rejections so they never become unhandled promise rejections.
+ */
+export declare function safeWaitUntil(ctx: WaitUntilHost, promise: Promise<unknown>, onError?: (err: unknown) => void): void;
+/**
+ * Fan-out multiple independent background tasks via a single waitUntil.
+ * Uses allSettled so one failure does not cancel siblings.
+ */
+export declare function waitUntilAll(ctx: WaitUntilHost, promises: ReadonlyArray<Promise<unknown>>, onError?: (err: unknown) => void): void;
+//# sourceMappingURL=wait-until.d.ts.map

package/dist/middleware/wait-until.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-until.d.ts","sourceRoot":"","sources":["../../src/middleware/wait-until.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EACzB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC/B,IAAI,CAYN;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EACzC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC/B,IAAI,CAsBN"}

package/dist/middleware/wait-until.js

@@ -0,0 +1,46 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/middleware/wait-until.ts
+function safeWaitUntil(ctx, promise, onError) {
+  ctx.waitUntil(promise.catch((err) => {
+    onError?.(err);
+    console.error(JSON.stringify({
+      message: "waitUntil background task failed",
+      error: err instanceof Error ? err.message : String(err)
+    }));
+  }));
+}
+function waitUntilAll(ctx, promises, onError) {
+  if (promises.length === 0)
+    return;
+  safeWaitUntil(ctx, Promise.allSettled(promises).then((results) => {
+    for (const result of results) {
+      if (result.status === "rejected") {
+        onError?.(result.reason);
+        console.error(JSON.stringify({
+          message: "waitUntilAll background task failed",
+          error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+        }));
+      }
+    }
+  }), onError);
+}
+export {
+  waitUntilAll,
+  safeWaitUntil
+};

package/dist/queue-handler.d.ts

@@ -19,6 +19,11 @@ export interface QueueHandlerOptions<T> {
         info(msg: string, data?: unknown): void;
         error(msg: string, data?: unknown): void;
     };
+    /**
+     * Max number of messages to process concurrently within a batch.
+     * Defaults to 1 (serial) for back-compat. Values < 1 are treated as 1.
+     */
+    concurrency?: number;
 }
 /**
  * Creates a reusable queue handler with retry + exponential backoff logic.
@@ -28,6 +33,7 @@ export interface QueueHandlerOptions<T> {
  * const handler = createQueueHandler({
  *   maxRetries: 5,
  *   backoffDelays: [0, 30, 60, 300, 900],
+ *   concurrency: 4, // optional; default 1 (serial)
  *   onMessage: async (msg) => {
  *     await executeTask(msg);
  *   },

package/dist/queue-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-handler.d.ts","sourceRoot":"","sources":["../src/queue-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,+CAA+C;IAC/C,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,sDAAsD;IACtD,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,CAAC,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,KACjB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,iEAAiE;IACjE,KAAK,CAAC,EAAE,CACN,OAAO,EAAE,CAAC,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,KACV,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,oCAAoC;IACpC,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;KAC1C,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,IAIrD,OAAO,YAAY,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAmCrD"}
+{"version":3,"file":"queue-handler.d.ts","sourceRoot":"","sources":["../src/queue-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,+CAA+C;IAC/C,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,sDAAsD;IACtD,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,CAAC,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,KACjB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,iEAAiE;IACjE,KAAK,CAAC,EAAE,CACN,OAAO,EAAE,CAAC,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,KACV,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,oCAAoC;IACpC,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;KAC1C,CAAC;IACF;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAkCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,IAqDrD,OAAO,YAAY,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAGrD"}