@hoox-sh/hoox-shared 1.2.0

package/dist/middleware/logger.js

@@ -0,0 +1,202 @@
+// @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/errors.ts
+function toError(err, fallback = "Unknown error") {
+  if (err instanceof 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 === null || err === undefined)
+    return fallback;
+  try {
+    return JSON.stringify(err) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+var SENSITIVE_FIELDS = new Set([
+  "password",
+  "token",
+  "secret",
+  "api_key",
+  "apiKey",
+  "authorization"
+]);
+function hasSensitiveFields(obj) {
+  for (const key of Object.keys(obj)) {
+    if (SENSITIVE_FIELDS.has(key))
+      return true;
+  }
+  return false;
+}
+function hasErrorValues(obj) {
+  for (const v of Object.values(obj)) {
+    if (v instanceof Error)
+      return true;
+  }
+  return false;
+}
+function sanitizeOutput(data) {
+  if (data === null || data === undefined)
+    return data;
+  const t = typeof data;
+  if (t === "string" || t === "number" || t === "boolean")
+    return data;
+  if (data instanceof Error) {
+    return { name: data.name, message: data.message };
+  }
+  if (Array.isArray(data)) {
+    return data.map(sanitizeOutput);
+  }
+  if (t === "object") {
+    const obj = data;
+    const keys = Object.keys(obj);
+    if (keys.length < 10) {
+      const sanitized2 = {};
+      for (const k of keys) {
+        if (k === "stack" || k === "cause")
+          continue;
+        const v = obj[k];
+        sanitized2[k] = v instanceof Error ? { name: v.name, message: v.message } : sanitizeOutput(v);
+      }
+      return sanitized2;
+    }
+    if (!hasSensitiveFields(obj) && !hasErrorValues(obj)) {
+      return obj;
+    }
+    const sanitized = {};
+    for (const k of keys) {
+      if (k === "stack" || k === "cause")
+        continue;
+      const v = obj[k];
+      sanitized[k] = v instanceof Error ? { name: v.name, message: v.message } : sanitizeOutput(v);
+    }
+    return sanitized;
+  }
+  return data;
+}
+function createJsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(sanitizeOutput(data)), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function createSuccessResponse(result) {
+  return createJsonResponse({ success: true, result }, 200);
+}
+function createErrorResponse(error, status) {
+  const message = typeof error === "string" ? error : error.message;
+  const statusCode = typeof error === "string" ? status ?? 500 : error.status ?? 500;
+  const body = { success: false, error: message };
+  if (typeof error !== "string" && error.code)
+    body.code = error.code;
+  if (typeof error !== "string" && error.details !== undefined)
+    body.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: statusCode,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var Errors = {
+  badRequest: (message) => createErrorResponse({ message, status: 400, code: "BAD_REQUEST" }),
+  unauthorized: (message = "Unauthorized") => createErrorResponse({ message, status: 401, code: "UNAUTHORIZED" }),
+  forbidden: (message = "Forbidden") => createErrorResponse({ message, status: 403, code: "FORBIDDEN" }),
+  notFound: (message = "Not found") => createErrorResponse({ message, status: 404, code: "NOT_FOUND" }),
+  methodNotAllowed: (message = "Method not allowed") => createErrorResponse({ message, status: 405, code: "METHOD_NOT_ALLOWED" }),
+  rateLimited: (retryAfter) => {
+    const res = createErrorResponse({
+      message: "Rate limit exceeded",
+      status: 429,
+      code: "RATE_LIMITED"
+    });
+    if (retryAfter)
+      res.headers.set("Retry-After", String(retryAfter));
+    return res;
+  },
+  internal: (err) => {
+    const message = err ? toError(err, "Internal server error") : "Internal server error";
+    return createErrorResponse({
+      message,
+      status: 500,
+      code: "INTERNAL_ERROR"
+    });
+  }
+};
+
+// src/middleware/logger.ts
+function createLogger(ctx) {
+  const base = { service: ctx.service, module: ctx.module };
+  function emit(level, message, context) {
+    const entry = {
+      level,
+      timestamp: new Date().toISOString(),
+      ...base,
+      message,
+      ...context && { context }
+    };
+    const line = JSON.stringify(entry);
+    if (level === "error")
+      console.error(line);
+    else if (level === "warn")
+      console.warn(line);
+    else if (level === "debug")
+      console.debug(line);
+    else
+      console.info(line);
+  }
+  return {
+    debug: (msg, ctx2) => emit("debug", msg, ctx2),
+    info: (msg, ctx2) => emit("info", msg, ctx2),
+    warn: (msg, ctx2) => emit("warn", msg, ctx2),
+    error: (msg, ctx2) => emit("error", msg, ctx2)
+  };
+}
+function withRequestLog(handler, logCtx) {
+  return async (request, env, ctx) => {
+    const start = Date.now();
+    const logger = createLogger(logCtx);
+    try {
+      const response = await handler(request, env, ctx);
+      const duration = Date.now() - start;
+      const url = new URL(request.url);
+      logger.info(`${request.method} ${url.pathname}`, {
+        method: request.method,
+        path: url.pathname,
+        status: response.status,
+        durationMs: duration
+      });
+      return response;
+    } catch (error) {
+      const duration = Date.now() - start;
+      logger.error("Request failed", {
+        method: request.method,
+        path: new URL(request.url).pathname,
+        durationMs: duration,
+        error: toError(error)
+      });
+      throw error;
+    }
+  };
+}
+export {
+  withRequestLog,
+  createLogger
+};

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Rate limiting middleware for Cloudflare Workers
+ * Adapted from workers/agent-worker/src/middleware/rate-limit.ts
+ *
+ * @available — Available for consumer use. Import from "@hoox-sh/hoox-shared/middleware".
+ */
+import type { Env } from "../types";
+export interface RateLimitConfig {
+    maxRequests: number;
+    windowSeconds: number;
+    keyPrefix?: string;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfter?: number;
+}
+export interface RateLimiter {
+    check(request: Request): Promise<RateLimitResult>;
+    enforce(request: Request): Promise<Response | null>;
+    checkKey(key: string): Promise<RateLimitResult>;
+    enforceKey(key: string): Promise<Response | null>;
+}
+export declare function createRateLimiter(kv: Env["CONFIG_KV"] | undefined, config: RateLimitConfig): RateLimiter;
+export {};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAClD,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACnD;AAuHD,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,SAAS,EAChC,MAAM,EAAE,eAAe,GACtB,WAAW,CAiHb"}

package/dist/middleware/rate-limit.js

@@ -0,0 +1,181 @@
+// @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/rate-limit.ts
+function createStorage(kv) {
+  if (!kv) {
+    const memory = new Map;
+    return {
+      async get(key) {
+        const entry = memory.get(key);
+        if (!entry)
+          return null;
+        if (Date.now() > entry.expiresAt) {
+          memory.delete(key);
+          return null;
+        }
+        return entry.value;
+      },
+      async put(key, value, opts) {
+        const ttl = opts?.expirationTtl ?? 0;
+        const expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : Infinity;
+        memory.set(key, { value, expiresAt });
+      },
+      async incr(key, opts) {
+        let entry = memory.get(key);
+        let newValue;
+        let attempts = 0;
+        const maxAttempts = 100;
+        while (true) {
+          const count = entry ? parseInt(entry.value, 10) : 0;
+          newValue = count + 1;
+          if (!entry) {
+            const ttl = opts?.expirationTtl ?? 0;
+            const expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : Infinity;
+            if (memory.get(key) === undefined) {
+              memory.set(key, { value: String(newValue), expiresAt });
+              return newValue;
+            }
+            entry = memory.get(key);
+          } else {
+            if (Date.now() > entry.expiresAt) {
+              memory.delete(key);
+              entry = undefined;
+              continue;
+            }
+            const currentEntry = memory.get(key);
+            if (currentEntry === entry) {
+              const ttl = opts?.expirationTtl ?? 0;
+              const expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : Infinity;
+              memory.set(key, { value: String(newValue), expiresAt });
+              return newValue;
+            }
+            entry = currentEntry;
+          }
+          attempts++;
+          if (attempts >= maxAttempts) {
+            const current = await this.get(key);
+            const count2 = current ? parseInt(current, 10) : 0;
+            newValue = count2 + 1;
+            const ttl = opts?.expirationTtl ?? 0;
+            const expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : Infinity;
+            memory.set(key, { value: String(newValue), expiresAt });
+            return newValue;
+          }
+        }
+      }
+    };
+  }
+  return {
+    async get(key) {
+      return kv.get(key);
+    },
+    async put(key, value, opts) {
+      await kv.put(key, value, opts);
+    },
+    async incr(key, opts) {
+      const current = await kv.get(key);
+      const count = current ? parseInt(current, 10) : 0;
+      const next = count + 1;
+      await kv.put(key, String(next), opts);
+      return next;
+    }
+  };
+}
+function createRateLimiter(kv, config) {
+  const prefix = config.keyPrefix ?? "rate-limit";
+  const storage = createStorage(kv);
+  function getClientIp(request) {
+    return request.headers.get("CF-Connecting-IP") ?? "unknown";
+  }
+  function getWindowKey(ip) {
+    const windowStart = Math.floor(Date.now() / (config.windowSeconds * 1000));
+    return `${prefix}:${ip}:${windowStart}`;
+  }
+  async function checkWithKey(fullKey) {
+    const current = await storage.get(fullKey);
+    const count = current ? parseInt(current, 10) : 0;
+    if (count >= config.maxRequests) {
+      const retryAfter = Math.ceil(config.windowSeconds - Date.now() % (config.windowSeconds * 1000) / 1000);
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfter
+      };
+    }
+    const newCount = await storage.incr(fullKey, {
+      expirationTtl: config.windowSeconds
+    });
+    if (newCount > config.maxRequests) {
+      const retryAfter = Math.ceil(config.windowSeconds - Date.now() % (config.windowSeconds * 1000) / 1000);
+      return {
+        allowed: false,
+        remaining: 0,
+        retryAfter
+      };
+    }
+    return {
+      allowed: true,
+      remaining: config.maxRequests - newCount
+    };
+  }
+  async function check(request) {
+    const ip = getClientIp(request);
+    const key = getWindowKey(ip);
+    return checkWithKey(key);
+  }
+  async function enforce(request) {
+    const result = await check(request);
+    if (!result.allowed) {
+      return new Response(JSON.stringify({
+        error: "Rate limit exceeded",
+        retryAfter: result.retryAfter
+      }), {
+        status: 429,
+        headers: {
+          "Content-Type": "application/json",
+          "Retry-After": String(result.retryAfter ?? config.windowSeconds)
+        }
+      });
+    }
+    return null;
+  }
+  async function checkKey(key) {
+    const fullKey = `${prefix}:${key}`;
+    return checkWithKey(fullKey);
+  }
+  async function enforceKey(key) {
+    const result = await checkKey(key);
+    if (!result.allowed) {
+      return new Response(JSON.stringify({
+        error: "Rate limit exceeded",
+        retryAfter: result.retryAfter
+      }), {
+        status: 429,
+        headers: {
+          "Content-Type": "application/json",
+          "Retry-After": String(result.retryAfter ?? config.windowSeconds)
+        }
+      });
+    }
+    return null;
+  }
+  return { check, enforce, checkKey, enforceKey };
+}
+export {
+  createRateLimiter
+};

package/dist/middleware/security-headers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Security Headers middleware for Cloudflare Workers
+ * Provides standardized security headers for all worker responses
+ *
+ * @available — Available for consumer use. Import from "@hoox-sh/hoox-shared/middleware".
+ */
+export interface SecurityHeadersOptions {
+    /** X-Content-Type-Options (default: "nosniff") */
+    xContentTypeOptions?: string;
+    /** X-Frame-Options (default: "DENY") */
+    xFrameOptions?: string;
+    /** X-XSS-Protection (default: "1; mode=block") */
+    xXssProtection?: string;
+    /** Referrer-Policy (default: "strict-origin-when-cross-origin") */
+    referrerPolicy?: string;
+    /** Permissions-Policy (default: restrictive — all disabled) */
+    permissionsPolicy?: string;
+    /** Strict-Transport-Security (default: "max-age=31536000; includeSubDomains") */
+    strictTransportSecurity?: string;
+    /** Content-Security-Policy (default: "default-src 'self'") */
+    contentSecurityPolicy?: string;
+}
+export declare const SECURITY_HEADERS_DEFAULTS: Required<SecurityHeadersOptions>;
+/**
+ * Create security headers object for use in responses.
+ * Merges provided options over defaults.
+ */
+export declare function secureHeaders(options?: SecurityHeadersOptions): Record<string, string>;
+/**
+ * Wrap an existing Response with security headers.
+ * Preserves existing response headers (security headers take precedence).
+ *
+ * @example
+ *   return wrapWithSecurityHeaders(
+ *     createJsonResponse({ success: true }, 200)
+ *   );
+ */
+export declare function wrapWithSecurityHeaders(response: Response, options?: SecurityHeadersOptions): Response;
+//# sourceMappingURL=security-headers.d.ts.map

package/dist/middleware/security-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/middleware/security-headers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,sBAAsB,CAStE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,QAAQ,CAUV"}

package/dist/middleware/security-headers.js

@@ -0,0 +1,58 @@
+// @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/security-headers.ts
+var SECURITY_HEADERS_DEFAULTS = {
+  xContentTypeOptions: "nosniff",
+  xFrameOptions: "DENY",
+  xXssProtection: "1; mode=block",
+  referrerPolicy: "strict-origin-when-cross-origin",
+  permissionsPolicy: "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
+  strictTransportSecurity: "max-age=31536000; includeSubDomains",
+  contentSecurityPolicy: "default-src 'self'"
+};
+function secureHeaders(options) {
+  const opts = { ...SECURITY_HEADERS_DEFAULTS, ...options };
+  const headers = {
+    "X-Content-Type-Options": opts.xContentTypeOptions,
+    "X-Frame-Options": opts.xFrameOptions,
+    "X-XSS-Protection": opts.xXssProtection,
+    "Referrer-Policy": opts.referrerPolicy,
+    "Permissions-Policy": opts.permissionsPolicy,
+    "Strict-Transport-Security": opts.strictTransportSecurity
+  };
+  if (opts.contentSecurityPolicy) {
+    headers["Content-Security-Policy"] = opts.contentSecurityPolicy;
+  }
+  return headers;
+}
+function wrapWithSecurityHeaders(response, options) {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(secureHeaders(options))) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+export {
+  wrapWithSecurityHeaders,
+  secureHeaders,
+  SECURITY_HEADERS_DEFAULTS
+};

package/dist/middleware/validate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Validation middleware for Cloudflare Workers
+ * Uses Zod for runtime schema validation.
+ *
+ * @available — Available for consumer use. Import from "@hoox-sh/hoox-shared/middleware".
+ */
+import { z } from "zod";
+import type { Result } from "../types";
+/**
+ * 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>>;
+/**
+ * Legacy signature: parse request body as JSON object.
+ * Kept for backward compatibility with existing workers.
+ */
+export declare function validateJsonLegacy(request: Request): Promise<Result<Record<string, unknown>>>;
+export declare function requireField<T>(body: Record<string, unknown>, field: string): Result<T>;
+export declare function optionalField<T>(body: Record<string, unknown>, field: string, defaultValue: T): T;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +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"}

package/dist/middleware/validate.js

@@ -0,0 +1,56 @@
+// @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/validate.ts
+function validateJson(schema, data) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    };
+  }
+  return { ok: true, value: result.data };
+}
+async function validateJsonLegacy(request) {
+  try {
+    const body = await request.json();
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      return { ok: false, error: "Request body must be a JSON object" };
+    }
+    return { ok: true, value: body };
+  } catch {
+    return { ok: false, error: "Invalid JSON in request body" };
+  }
+}
+function requireField(body, field) {
+  if (!(field in body)) {
+    return { ok: false, error: `Missing required field: ${field}` };
+  }
+  return { ok: true, value: body[field] };
+}
+function optionalField(body, field, defaultValue) {
+  if (!(field in body))
+    return defaultValue;
+  return body[field];
+}
+export {
+  validateJsonLegacy,
+  validateJson,
+  requireField,
+  optionalField
+};

package/dist/operator-transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Operator transport profile — how CLI/TUI clients reach the management plane.
+ *
+ * Transports:
+ *   public  — HTTPS + optional Bearer (default)
+ *   access  — Cloudflare Access service-token headers (+ optional Bearer)
+ *   mtls    — reserved (Enterprise); headers same as public until TLS certs land
+ *   tunnel  — reserved (private hostname); headers same as public
+ *
+ * Client maps HOOX_API_TOKEN → Authorization: Bearer …
+ * Server maps OPERATOR_API_KEY (preferred) or INTERNAL_API_KEY → requireOperatorAuth
+ */
+export type OperatorTransport = "public" | "access" | "mtls" | "tunnel";
+export interface OperatorTransportProfile {
+    transport: OperatorTransport;
+    /** API base URL without trailing slash */
+    apiBase: string;
+    /** Bearer token (HOOX_API_TOKEN); empty if unset */
+    bearerToken: string;
+    /** CF Access service token client id */
+    accessClientId: string;
+    /** CF Access service token client secret */
+    accessClientSecret: string;
+}
+export interface OperatorTransportEnv {
+    HOOX_API_URL?: string;
+    HOOX_API_TOKEN?: string;
+    HOOX_TRANSPORT?: string;
+    CF_ACCESS_CLIENT_ID?: string;
+    CF_ACCESS_CLIENT_SECRET?: string;
+    [key: string]: string | undefined;
+}
+export interface ResolveOperatorTransportOptions {
+    /**
+     * Fallback transport when HOOX_TRANSPORT is unset
+     * (e.g. from ~/.hoox/config.json).
+     */
+    configTransport?: string;
+    /** Fallback API base when HOOX_API_URL is unset. */
+    configApiUrl?: string;
+    /** Fallback bearer when HOOX_API_TOKEN is unset. */
+    configApiToken?: string;
+}
+/**
+ * Resolve operator transport from env (process.env by default).
+ * Pure + injectable for tests. Optional config fallbacks for file-backed prefs.
+ */
+export declare function resolveOperatorTransportProfile(env?: OperatorTransportEnv, options?: ResolveOperatorTransportOptions): OperatorTransportProfile;
+/**
+ * Build HTTP headers for operator management requests.
+ * Never logs secrets; callers must not print the result in debug without redaction.
+ */
+export declare function buildOperatorAuthHeaders(profile: OperatorTransportProfile): Record<string, string>;
+/** True when the profile has any client-side operator credential. */
+export declare function hasOperatorClientCredentials(profile: OperatorTransportProfile): boolean;
+/**
+ * Join base URL and path without double slashes.
+ * Paths should start with `/`.
+ */
+export declare function operatorUrl(profile: OperatorTransportProfile, path: string): string;
+//# sourceMappingURL=operator-transport.d.ts.map

package/dist/operator-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-transport.d.ts","sourceRoot":"","sources":["../src/operator-transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAwBD,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,GAAE,oBAA0D,EAC/D,OAAO,GAAE,+BAAoC,GAC5C,wBAAwB,CAyB1B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBxB;AAED,qEAAqE;AACrE,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,wBAAwB,EACjC,IAAI,EAAE,MAAM,GACX,MAAM,CAIR"}