sentinelayer-cli 0.4.5 → 0.8.0

package/src/auth/http.js

@@ -1,4 +1,8 @@
 import { setTimeout as sleep } from "node:timers/promises";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 /**
  * Default timeout applied to Sentinelayer API requests when no override is provided.
@@ -13,33 +17,232 @@ export const CIRCUIT_BREAKER_COOLDOWN_MS = 30_000;
 
 const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
 const CIRCUIT_TRACK_STATUS_CODES = new Set([401, 403, 408, 425, 429, 500, 502, 503, 504]);
-const circuitState = {
-  consecutiveFailures: 0,
-  openedAtMs: 0,
-};
+const circuitStateByScope = new Map();
+
+// File-backed cache. Lets cooldown + failure counts survive across CLI
+// invocations — without it, each new process hammers a degraded upstream
+// until it hits the threshold again. Best-effort: if file ops fail, we
+// silently fall back to in-memory behavior (no hard dependency).
+const CIRCUIT_STATE_FILE = (() => {
+  const base = process.env.SENTINELAYER_CIRCUIT_STATE_DIR ||
+    path.join(os.homedir() || os.tmpdir(), ".sentinelayer");
+  try {
+    fs.mkdirSync(base, { recursive: true });
+  } catch {
+    /* noop */
+  }
+  return path.join(base, "circuit-state.json");
+})();
+let circuitStateLoaded = false;
+
+function loadCircuitStateFromDisk() {
+  if (circuitStateLoaded) return;
+  circuitStateLoaded = true;
+  try {
+    const raw = fs.readFileSync(CIRCUIT_STATE_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return;
+    const now = Date.now();
+    for (const [key, value] of Object.entries(parsed)) {
+      if (!value || typeof value !== "object") continue;
+      const consecutiveFailures = Number(value.consecutiveFailures) || 0;
+      const openedAtMs = Number(value.openedAtMs) || 0;
+      // TTL: only carry over entries within the cooldown window — older
+      // entries are stale and should reset naturally on this process.
+      if (openedAtMs > 0 && now - openedAtMs < CIRCUIT_BREAKER_COOLDOWN_MS) {
+        circuitStateByScope.set(String(key), { consecutiveFailures, openedAtMs });
+      }
+    }
+  } catch {
+    /* noop: missing, corrupt, or unreadable — start fresh */
+  }
+}
+
+function persistCircuitState() {
+  try {
+    const snapshot = {};
+    for (const [key, value] of circuitStateByScope.entries()) {
+      snapshot[key] = {
+        consecutiveFailures: value.consecutiveFailures || 0,
+        openedAtMs: value.openedAtMs || 0,
+      };
+    }
+    const tmp = `${CIRCUIT_STATE_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(snapshot), "utf-8");
+    fs.renameSync(tmp, CIRCUIT_STATE_FILE);
+  } catch {
+    /* noop */
+  }
+}
+const REQUEST_ID_HEADERS = ["x-request-id", "request-id", "x-correlation-id"];
+const DEBUG_API_ERRORS_ENV = "SENTINELAYER_DEBUG_ERRORS";
+const MAX_API_ERROR_MESSAGE_LENGTH = 512;
+const IDEMPOTENCY_KEY_MIN_LENGTH = 32;
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PREFIXED_UUID_V4_PATTERN = /^[a-z0-9][a-z0-9_-]{1,48}-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function resolveCircuitScope(url) {
+  try {
+    const parsed = new URL(String(url));
+    return parsed.origin;
+  } catch {
+    return "unknown";
+  }
+}
+
+function getCircuitState(scope) {
+  loadCircuitStateFromDisk();
+  const key = String(scope || "unknown");
+  if (!circuitStateByScope.has(key)) {
+    circuitStateByScope.set(key, { consecutiveFailures: 0, openedAtMs: 0 });
+  }
+  return circuitStateByScope.get(key);
+}
 
 function normalizeApiError(errorPayload = {}) {
+  const fallbackMessage = "Unknown API error";
   if (!errorPayload || typeof errorPayload !== "object" || Array.isArray(errorPayload)) {
     return {
       code: "UNKNOWN",
-      message: "Unknown API error",
+      message: sanitizeApiErrorMessage(fallbackMessage, fallbackMessage),
       requestId: null,
     };
   }
+  const rawMessage = String(errorPayload.message || fallbackMessage);
+  const safeMessage = sanitizeApiErrorMessage(rawMessage, fallbackMessage);
+  const message = appendDebugContext(safeMessage, {
+    code: String(errorPayload.code || "UNKNOWN"),
+    requestId: errorPayload.request_id ? String(errorPayload.request_id) : null,
+  });
   return {
     code: String(errorPayload.code || "UNKNOWN"),
-    message: String(errorPayload.message || "Unknown API error"),
+    message,
     requestId: errorPayload.request_id ? String(errorPayload.request_id) : null,
   };
 }
 
+function resolveRequestId(headers) {
+  if (!headers || typeof headers.get !== "function") {
+    return null;
+  }
+  for (const headerName of REQUEST_ID_HEADERS) {
+    const value = headers.get(headerName);
+    if (value) {
+      return String(value);
+    }
+  }
+  return null;
+}
+
+function resolveIdempotencyKey(headers) {
+  if (!headers) {
+    return null;
+  }
+  if (typeof headers.get === "function") {
+    const value =
+      headers.get("idempotency-key") ||
+      headers.get("Idempotency-Key") ||
+      headers.get("IDEMPOTENCY-KEY");
+    return String(value || "").trim() || null;
+  }
+  if (typeof headers !== "object") {
+    return null;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (String(key || "").toLowerCase() === "idempotency-key") {
+      const normalized = String(value || "").trim();
+      return normalized || null;
+    }
+  }
+  return null;
+}
+
+function isValidIdempotencyKey(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    return false;
+  }
+  if (UUID_V4_PATTERN.test(normalized)) {
+    return true;
+  }
+  if (PREFIXED_UUID_V4_PATTERN.test(normalized)) {
+    return true;
+  }
+  if (normalized.length < IDEMPOTENCY_KEY_MIN_LENGTH) {
+    return false;
+  }
+  return /^[A-Za-z0-9_-]+$/.test(normalized);
+}
+
+function validateIdempotencyKey(value) {
+  if (!isValidIdempotencyKey(value)) {
+    throw new SentinelayerApiError("Idempotency-Key must be a UUIDv4 or a prefixed UUID.", {
+      status: 400,
+      code: "IDEMPOTENCY_KEY_INVALID",
+    });
+  }
+}
+
+function sanitizeOperationName(value) {
+  const normalized = String(value || "").toLowerCase();
+  const cleaned = normalized.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned.slice(0, 32) || "mutation";
+}
+
+function createIdempotencyKeyForOperation(operationName) {
+  const op = sanitizeOperationName(operationName);
+  let suffix;
+  try {
+    suffix = crypto.randomUUID();
+  } catch {
+    suffix = crypto.randomBytes(16).toString("hex");
+  }
+  return `sl-cli-${op}-${suffix}`;
+}
+
+function normalizeHeaderObject(headers) {
+  if (!headers) {
+    return {};
+  }
+  if (typeof headers.get === "function") {
+    const normalized = {};
+    for (const [key, value] of headers.entries()) {
+      normalized[key] = value;
+    }
+    return normalized;
+  }
+  if (typeof headers !== "object") {
+    return {};
+  }
+  return { ...headers };
+}
+
+function isMutationVerb(method) {
+  const normalized = String(method || "").trim().toUpperCase();
+  return (
+    normalized === "POST" ||
+    normalized === "PUT" ||
+    normalized === "PATCH" ||
+    normalized === "DELETE"
+  );
+}
+
+function applyIdempotencyKey(headers, idempotencyKey) {
+  const normalized = normalizeHeaderObject(headers);
+  if (idempotencyKey && !resolveIdempotencyKey(normalized)) {
+    normalized["Idempotency-Key"] = idempotencyKey;
+  }
+  return normalized;
+}
+
 export class SentinelayerApiError extends Error {
   /**
    * @param {string} message
    * @param {{ status?: number, code?: string, requestId?: string | null }} [options]
    */
   constructor(message, { status = 500, code = "UNKNOWN", requestId = null } = {}) {
-    super(String(message || "Sentinelayer API error"));
+    const safeMessage = sanitizeApiErrorMessage(message, "Sentinelayer API error");
+    super(appendDebugContext(safeMessage, { code, status, requestId }));
     this.name = "SentinelayerApiError";
     this.status = Number(status || 500);
     this.code = String(code || "UNKNOWN");
@@ -92,28 +295,87 @@ function computeBackoffMs({ attempt, retryDelayMs, retryAfterHeader }) {
   return Math.min(Math.max(1, computed), MAX_RETRY_DELAY_MS);
 }
 
-function isCircuitOpen() {
+function isCircuitOpen(scope) {
+  const circuitState = getCircuitState(scope);
   if (circuitState.openedAtMs <= 0) {
     return false;
   }
   if (Date.now() - circuitState.openedAtMs >= CIRCUIT_BREAKER_COOLDOWN_MS) {
     circuitState.openedAtMs = 0;
     circuitState.consecutiveFailures = 0;
+    persistCircuitState();
     return false;
   }
   return true;
 }
 
-function recordFailureForCircuit() {
+function recordFailureForCircuit(scope) {
+  const circuitState = getCircuitState(scope);
   circuitState.consecutiveFailures += 1;
   if (circuitState.consecutiveFailures >= CIRCUIT_BREAKER_THRESHOLD) {
     circuitState.openedAtMs = Date.now();
   }
+  persistCircuitState();
 }
 
-function recordSuccessForCircuit() {
+function shouldExposeApiErrorDetails() {
+  const normalized = String(process.env[DEBUG_API_ERRORS_ENV] || "").trim().toLowerCase();
+  return normalized === "true" || normalized === "1" || normalized === "yes";
+}
+
+function isTestNonIdempotentAllowed() {
+  return (
+    process.env.NODE_ENV === "test" &&
+    process.env.SENTINELAYER_ALLOW_NON_IDEMPOTENT === "1" &&
+    process.env.SENTINELAYER_CLI_TEST_MODE === "1" &&
+    !process.env.CI
+  );
+}
+
+function sanitizeApiErrorMessage(message, fallback = "Sentinelayer API error") {
+  const fallbackMessage = String(fallback || "Sentinelayer API error");
+  const normalized = String(message || "").trim();
+  const candidate = normalized || fallbackMessage;
+  const sanitized = candidate
+    .replace(/\bbearer\s+[a-z0-9._~+/=-]+\b/gi, "bearer [REDACTED]")
+    .replace(/\b(token|secret|password|api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token)\b\s*[:=]\s*["']?[^"'\s,;]+["']?/gi, "$1=[REDACTED]")
+    .replace(/\b[a-z0-9_-]+\.[a-z0-9_-]+\.[a-z0-9_-]+\b/gi, "[REDACTED_JWT]")
+    .replace(/\bhttps?:\/\/[^\s"'`]+/gi, () => "<redacted-url>")
+    .replace(/\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b/gi, "<redacted-email>");
+  if (sanitized.length <= MAX_API_ERROR_MESSAGE_LENGTH) {
+    return sanitized;
+  }
+  return `${sanitized.slice(0, MAX_API_ERROR_MESSAGE_LENGTH - 3)}...`;
+}
+
+function anonymizeRequestIdForDebug(requestId) {
+  const normalized = String(requestId || "").trim();
+  if (!normalized) {
+    return "";
+  }
+  return crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+}
+
+function appendDebugContext(safeMessage, { code, status, requestId } = {}) {
+  if (!shouldExposeApiErrorDetails()) {
+    return safeMessage;
+  }
+  const parts = [];
+  const normalizedCode = String(code || "").trim();
+  const normalizedStatus = Number.isFinite(Number(status)) ? Number(status) : null;
+  const requestIdHash = anonymizeRequestIdForDebug(requestId);
+  if (normalizedCode) parts.push(`code=${normalizedCode}`);
+  if (normalizedStatus) parts.push(`status=${normalizedStatus}`);
+  if (requestIdHash) parts.push(`request_id_hash=${requestIdHash}`);
+  if (parts.length === 0) return safeMessage;
+  return `${safeMessage} (${parts.join(", ")})`;
+}
+
+function recordSuccessForCircuit(scope) {
+  const circuitState = getCircuitState(scope);
   circuitState.consecutiveFailures = 0;
   circuitState.openedAtMs = 0;
+  persistCircuitState();
 }
 
 function shouldRetryStatus(statusCode) {
@@ -124,9 +386,21 @@ function shouldRecordFailureForStatus(statusCode) {
   return CIRCUIT_TRACK_STATUS_CODES.has(Number(statusCode || 0));
 }
 
-export function __resetRequestCircuitForTests() {
-  circuitState.consecutiveFailures = 0;
-  circuitState.openedAtMs = 0;
+export function __resetRequestCircuitForTests(scope) {
+  if (scope) {
+    const circuitState = getCircuitState(scope);
+    circuitState.consecutiveFailures = 0;
+    circuitState.openedAtMs = 0;
+    persistCircuitState();
+    return;
+  }
+  circuitStateByScope.clear();
+  circuitStateLoaded = true; // block disk reload after manual reset
+  try {
+    fs.rmSync(CIRCUIT_STATE_FILE, { force: true });
+  } catch {
+    /* noop */
+  }
 }
 
 /**
@@ -138,9 +412,12 @@ export function __resetRequestCircuitForTests() {
  *   method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
  *   headers?: Record<string, string>,
  *   body?: unknown,
+ *   idempotencyKey?: string | null,
+ *   allowNonIdempotent?: boolean,
  *   timeoutMs?: number
  *   maxRetries?: number,
  *   retryDelayMs?: number
+ *   allowEmptyBody?: boolean
  * }} [options]
  * @returns {Promise<any>}
  */
@@ -150,12 +427,46 @@ export async function requestJson(
     method = "GET",
     headers = {},
     body,
+    idempotencyKey = null,
+    allowNonIdempotent = false,
     timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     maxRetries = DEFAULT_MAX_RETRIES,
     retryDelayMs = DEFAULT_RETRY_DELAY_MS,
+    allowEmptyBody = false,
   } = {}
 ) {
-  if (isCircuitOpen()) {
+  const normalizedMethod = String(method || "GET").trim().toUpperCase();
+  const explicitIdempotencyKey = String(idempotencyKey || "").trim() || null;
+  const existingIdempotencyKey = explicitIdempotencyKey || resolveIdempotencyKey(headers);
+  const isMutationMethod = isMutationVerb(normalizedMethod);
+  const resolvedIdempotencyKey = existingIdempotencyKey;
+  const requestHeaders = applyIdempotencyKey(headers, resolvedIdempotencyKey);
+  const outgoingHeaders = { ...requestHeaders };
+  if (body !== undefined) {
+    outgoingHeaders["Content-Type"] = "application/json";
+  }
+  const isIdempotentMutation = Boolean(resolvedIdempotencyKey);
+  const allowUnsafeMutation = Boolean(allowNonIdempotent) && isTestNonIdempotentAllowed();
+  if (isMutationMethod && !isIdempotentMutation && !allowUnsafeMutation) {
+    throw new SentinelayerApiError("Idempotency-Key is required for mutation requests.", {
+      status: 400,
+      code: "IDEMPOTENCY_KEY_REQUIRED",
+    });
+  }
+  if (isMutationMethod && isIdempotentMutation) {
+    validateIdempotencyKey(resolvedIdempotencyKey);
+  }
+  const retryableMethod =
+    normalizedMethod === "GET" ||
+    normalizedMethod === "HEAD" ||
+    normalizedMethod === "OPTIONS" ||
+    (isIdempotentMutation &&
+      (normalizedMethod === "POST" ||
+        normalizedMethod === "PUT" ||
+        normalizedMethod === "PATCH" ||
+        normalizedMethod === "DELETE"));
+  const circuitScope = resolveCircuitScope(url);
+  if (isCircuitOpen(circuitScope)) {
     throw new SentinelayerApiError("Request circuit breaker is open after consecutive API failures.", {
       status: 503,
       code: "CIRCUIT_OPEN",
@@ -169,52 +480,84 @@ export async function requestJson(
   let lastRetryableError = null;
   for (let attempt = 0; attempt <= normalizedMaxRetries; attempt += 1) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), normalizedTimeoutMs);
+    let timeoutTriggered = false;
+    let timeoutHandle;
+    timeoutHandle = setTimeout(() => {
+      timeoutTriggered = true;
+      controller.abort();
+    }, normalizedTimeoutMs);
 
     try {
       const response = await fetch(String(url), {
-        method,
-        headers: {
-          "Content-Type": "application/json",
-          ...headers,
-        },
+        method: normalizedMethod,
+        headers: outgoingHeaders,
         body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "error",
         signal: controller.signal,
       });
 
       const rawBody = await response.text();
+      const trimmedBody = rawBody.trim();
+      const contentType = response.headers.get("content-type") || "";
+      const isJson = /application\/json/i.test(contentType);
       let json = {};
-      if (rawBody.trim()) {
-        try {
-          json = JSON.parse(rawBody);
-        } catch {
-          if (response.ok) {
-            throw new SentinelayerApiError("Invalid JSON returned by API.", {
-              status: response.status,
-              code: "INVALID_JSON",
-            });
+      if (!trimmedBody) {
+        const statusCode = Number(response.status || 0);
+        const allowEmpty = Boolean(allowEmptyBody) || statusCode === 204 || statusCode === 205;
+        if (response.ok && !allowEmpty) {
+          const requestId = resolveRequestId(response.headers);
+          throw new SentinelayerApiError("Empty response body returned by API.", {
+            status: response.status,
+            code: "EMPTY_BODY",
+            requestId,
+          });
+        }
+      } else {
+        if (response.ok && !isJson) {
+          const requestId = resolveRequestId(response.headers);
+          throw new SentinelayerApiError("Invalid content-type returned by API.", {
+            status: response.status,
+            code: "INVALID_CONTENT_TYPE",
+            requestId,
+          });
+        }
+        if (isJson) {
+          try {
+            json = JSON.parse(rawBody);
+          } catch {
+            const requestId = resolveRequestId(response.headers);
+            if (response.ok) {
+              throw new SentinelayerApiError("Invalid JSON returned by API.", {
+                status: response.status,
+                code: "INVALID_JSON",
+                requestId,
+              });
+            }
           }
         }
       }
 
       if (response.ok) {
-        recordSuccessForCircuit();
+        recordSuccessForCircuit(circuitScope);
         return json;
       }
 
       const apiError = normalizeApiError(json && typeof json === "object" ? json.error : {});
+      const requestId = apiError.requestId || resolveRequestId(response.headers);
       const statusCode = Number(response.status || 500);
-      const retryable = shouldRetryStatus(statusCode);
+      const retryable = retryableMethod && shouldRetryStatus(statusCode);
       const shouldRecordCircuitFailure = shouldRecordFailureForStatus(statusCode);
+      const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
       const error = new SentinelayerApiError(apiError.message, {
         status: statusCode,
         code: apiError.code,
-        requestId: apiError.requestId,
+        requestId,
       });
+      error.retryAfterMs = retryAfterMs;
 
       if (!retryable || attempt >= normalizedMaxRetries) {
         if (shouldRecordCircuitFailure) {
-          recordFailureForCircuit();
+          recordFailureForCircuit(circuitScope);
         }
         throw error;
       }
@@ -233,16 +576,23 @@ export async function requestJson(
       }
 
       const isAbortError = Boolean(error && typeof error === "object" && error.name === "AbortError");
+      const abortMessage = error instanceof Error ? error.message : String(error || "");
+      const abortReason =
+        isAbortError && !timeoutTriggered && /cancel/i.test(abortMessage) ? "CANCELLED" : "TIMEOUT";
+      const abortCode = isAbortError ? abortReason : "NETWORK_ERROR";
+      const abortStatus = isAbortError ? (abortReason === "CANCELLED" ? 499 : 408) : 503;
       const normalizedError = new SentinelayerApiError(
-        isAbortError ? "Request timed out." : (error instanceof Error ? error.message : String(error || "Request failed")),
+        isAbortError
+          ? (abortReason === "CANCELLED" ? "Request cancelled." : "Request timed out.")
+          : (error instanceof Error ? error.message : String(error || "Request failed")),
         {
-          status: isAbortError ? 408 : 503,
-          code: isAbortError ? "TIMEOUT" : "NETWORK_ERROR",
+          status: abortStatus,
+          code: abortCode,
         }
       );
 
-      if (attempt >= normalizedMaxRetries) {
-        recordFailureForCircuit();
+      if (!retryableMethod || attempt >= normalizedMaxRetries) {
+        recordFailureForCircuit(circuitScope);
         throw normalizedError;
       }
 
@@ -255,7 +605,9 @@ export async function requestJson(
       await sleep(delayMs);
       continue;
     } finally {
-      clearTimeout(timeout);
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
       await sleep(0);
     }
   }
@@ -268,3 +620,62 @@ export async function requestJson(
     code: "NETWORK_ERROR",
   });
 }
+
+/**
+ * Execute an HTTP mutation request and auto-derive an idempotency key when missing.
+ *
+ * @param {string} url
+ * @param {{
+ *   method?: "POST" | "PUT" | "PATCH" | "DELETE",
+ *   headers?: Record<string, string>,
+ *   body?: unknown,
+ *   idempotencyKey?: string | null,
+ *   operationName: string,
+ *   timeoutMs?: number
+ *   maxRetries?: number,
+ *   retryDelayMs?: number
+ *   allowEmptyBody?: boolean
+ * }} options
+ * @returns {Promise<any>}
+ */
+export async function requestJsonMutation(
+  url,
+  {
+    method = "POST",
+    headers = {},
+    body,
+    idempotencyKey = null,
+    operationName,
+    timeoutMs,
+    maxRetries,
+    retryDelayMs,
+    allowEmptyBody = false,
+  } = {}
+) {
+  const normalizedMethod = String(method || "POST").trim().toUpperCase();
+  if (!isMutationVerb(normalizedMethod)) {
+    throw new SentinelayerApiError("requestJsonMutation requires a mutation HTTP method.", {
+      status: 400,
+      code: "INVALID_MUTATION_METHOD",
+    });
+  }
+  const resolvedOperation = String(operationName || "").trim();
+  if (!resolvedOperation) {
+    throw new SentinelayerApiError("requestJsonMutation requires an operationName.", {
+      status: 400,
+      code: "OPERATION_NAME_REQUIRED",
+    });
+  }
+  const resolvedIdempotencyKey =
+    String(idempotencyKey || "").trim() || createIdempotencyKeyForOperation(resolvedOperation);
+  return requestJson(url, {
+    method: normalizedMethod,
+    headers,
+    body,
+    idempotencyKey: resolvedIdempotencyKey,
+    timeoutMs,
+    maxRetries,
+    retryDelayMs,
+    allowEmptyBody,
+  });
+}