sentinelayer-cli 0.1.2 → 0.4.4

package/src/audit/replay.js

@@ -1,103 +1,103 @@
-import fsp from "node:fs/promises";
-import path from "node:path";
-
-function normalizeString(value) {
-  return String(value || "").trim();
-}
-
-function toPosixPath(value) {
-  return String(value || "").replace(/\\/g, "/");
-}
-
-function fingerprintFinding(finding = {}) {
-  return [
-    normalizeString(finding.severity).toUpperCase(),
-    toPosixPath(finding.file),
-    String(Number(finding.line || 0)),
-    normalizeString(finding.message).toLowerCase(),
-  ].join("|");
-}
-
-function collectFindings(report = {}) {
-  const flattened = [];
-  for (const agent of report.agentResults || []) {
-    for (const finding of agent.findings || []) {
-      flattened.push({
-        severity: normalizeString(finding.severity).toUpperCase(),
-        file: toPosixPath(finding.file),
-        line: Number(finding.line || 0),
-        message: normalizeString(finding.message),
-        ruleId: normalizeString(finding.ruleId),
-        ownerAgentId: agent.agentId,
-      });
-    }
-  }
-  return flattened;
-}
-
-function summaryDelta(base = {}, candidate = {}) {
-  const keys = ["P0", "P1", "P2", "P3"];
-  const delta = {};
-  for (const key of keys) {
-    delta[key] = Number(candidate[key] || 0) - Number(base[key] || 0);
-  }
-  delta.blockingChanged = Boolean(base.blocking) !== Boolean(candidate.blocking);
-  return delta;
-}
-
-export function compareAuditReports(baseReport = {}, candidateReport = {}) {
-  const baseFindings = collectFindings(baseReport);
-  const candidateFindings = collectFindings(candidateReport);
-  const baseByFingerprint = new Map(baseFindings.map((finding) => [fingerprintFinding(finding), finding]));
-  const candidateByFingerprint = new Map(
-    candidateFindings.map((finding) => [fingerprintFinding(finding), finding])
-  );
-
-  const added = [];
-  const removed = [];
-
-  for (const [fingerprint, finding] of candidateByFingerprint.entries()) {
-    if (!baseByFingerprint.has(fingerprint)) {
-      added.push(finding);
-    }
-  }
-  for (const [fingerprint, finding] of baseByFingerprint.entries()) {
-    if (!candidateByFingerprint.has(fingerprint)) {
-      removed.push(finding);
-    }
-  }
-
-  const deterministicEquivalent = added.length === 0 && removed.length === 0;
-  return {
-    schemaVersion: "1.0.0",
-    generatedAt: new Date().toISOString(),
-    baseRunId: normalizeString(baseReport.runId),
-    candidateRunId: normalizeString(candidateReport.runId),
-    baseSummary: baseReport.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
-    candidateSummary: candidateReport.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
-    summaryDelta: summaryDelta(baseReport.summary || {}, candidateReport.summary || {}),
-    baseFindingCount: baseFindings.length,
-    candidateFindingCount: candidateFindings.length,
-    addedCount: added.length,
-    removedCount: removed.length,
-    deterministicEquivalent,
-    added: added.slice(0, 500),
-    removed: removed.slice(0, 500),
-  };
-}
-
-export async function writeAuditComparisonArtifact({
-  baseReport = {},
-  candidateReport = {},
-  outputDirectory = "",
-} = {}) {
-  const resolvedOutputDirectory = path.resolve(String(outputDirectory || "."));
-  const comparison = compareAuditReports(baseReport, candidateReport);
-  const fileName = `AUDIT_COMPARISON_${comparison.baseRunId}_vs_${comparison.candidateRunId}.json`;
-  const outputPath = path.join(resolvedOutputDirectory, fileName);
-  await fsp.writeFile(outputPath, `${JSON.stringify(comparison, null, 2)}\n`, "utf-8");
-  return {
-    comparison,
-    outputPath,
-  };
-}
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function toPosixPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function fingerprintFinding(finding = {}) {
+  return [
+    normalizeString(finding.severity).toUpperCase(),
+    toPosixPath(finding.file),
+    String(Number(finding.line || 0)),
+    normalizeString(finding.message).toLowerCase(),
+  ].join("|");
+}
+
+function collectFindings(report = {}) {
+  const flattened = [];
+  for (const agent of report.agentResults || []) {
+    for (const finding of agent.findings || []) {
+      flattened.push({
+        severity: normalizeString(finding.severity).toUpperCase(),
+        file: toPosixPath(finding.file),
+        line: Number(finding.line || 0),
+        message: normalizeString(finding.message),
+        ruleId: normalizeString(finding.ruleId),
+        ownerAgentId: agent.agentId,
+      });
+    }
+  }
+  return flattened;
+}
+
+function summaryDelta(base = {}, candidate = {}) {
+  const keys = ["P0", "P1", "P2", "P3"];
+  const delta = {};
+  for (const key of keys) {
+    delta[key] = Number(candidate[key] || 0) - Number(base[key] || 0);
+  }
+  delta.blockingChanged = Boolean(base.blocking) !== Boolean(candidate.blocking);
+  return delta;
+}
+
+export function compareAuditReports(baseReport = {}, candidateReport = {}) {
+  const baseFindings = collectFindings(baseReport);
+  const candidateFindings = collectFindings(candidateReport);
+  const baseByFingerprint = new Map(baseFindings.map((finding) => [fingerprintFinding(finding), finding]));
+  const candidateByFingerprint = new Map(
+    candidateFindings.map((finding) => [fingerprintFinding(finding), finding])
+  );
+
+  const added = [];
+  const removed = [];
+
+  for (const [fingerprint, finding] of candidateByFingerprint.entries()) {
+    if (!baseByFingerprint.has(fingerprint)) {
+      added.push(finding);
+    }
+  }
+  for (const [fingerprint, finding] of baseByFingerprint.entries()) {
+    if (!candidateByFingerprint.has(fingerprint)) {
+      removed.push(finding);
+    }
+  }
+
+  const deterministicEquivalent = added.length === 0 && removed.length === 0;
+  return {
+    schemaVersion: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    baseRunId: normalizeString(baseReport.runId),
+    candidateRunId: normalizeString(candidateReport.runId),
+    baseSummary: baseReport.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
+    candidateSummary: candidateReport.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
+    summaryDelta: summaryDelta(baseReport.summary || {}, candidateReport.summary || {}),
+    baseFindingCount: baseFindings.length,
+    candidateFindingCount: candidateFindings.length,
+    addedCount: added.length,
+    removedCount: removed.length,
+    deterministicEquivalent,
+    added: added.slice(0, 500),
+    removed: removed.slice(0, 500),
+  };
+}
+
+export async function writeAuditComparisonArtifact({
+  baseReport = {},
+  candidateReport = {},
+  outputDirectory = "",
+} = {}) {
+  const resolvedOutputDirectory = path.resolve(String(outputDirectory || "."));
+  const comparison = compareAuditReports(baseReport, candidateReport);
+  const fileName = `AUDIT_COMPARISON_${comparison.baseRunId}_vs_${comparison.candidateRunId}.json`;
+  const outputPath = path.join(resolvedOutputDirectory, fileName);
+  await fsp.writeFile(outputPath, `${JSON.stringify(comparison, null, 2)}\n`, "utf-8");
+  return {
+    comparison,
+    outputPath,
+  };
+}

package/src/auth/gate.js

@@ -16,6 +16,7 @@ import { readStoredSession } from "./session-store.js";
 
 const AUTH_BYPASS_COMMANDS = new Set([
   "auth",      // auth subcommands handle their own auth
+  "help",      // help must work without login so agents can discover commands
   "--help",
   "-h",
   "--version",
@@ -27,6 +28,46 @@ const NO_AUTH_REQUIRED = new Set([
   "config",    // local config inspection
 ]);
 
+function hasTrustedBypassContext() {
+  const nonce = String(process.env.SENTINELAYER_CLI_TEST_BYPASS_NONCE || "").trim();
+  return (
+    process.env.NODE_ENV === "test" &&
+    process.env.SENTINELAYER_CLI_TEST_MODE === "1" &&
+    nonce.length >= 12
+  );
+}
+
+function isValidSessionToken(session) {
+  const token = String(session?.token || "");
+  if (!token || token !== token.trim()) {
+    return false;
+  }
+  if (/\s/.test(token)) {
+    return false;
+  }
+  // Require printable ASCII only for bearer token material in local metadata.
+  if (/[^\x21-\x7E]/.test(token)) {
+    return false;
+  }
+  const tokenPrefix = String(session?.tokenPrefix || "").trim();
+  if (tokenPrefix && !token.startsWith(tokenPrefix)) {
+    return false;
+  }
+  return true;
+}
+
+function isSessionUnexpired(tokenExpiresAt) {
+  const normalized = String(tokenExpiresAt || "").trim();
+  if (!normalized) {
+    return false;
+  }
+  const expiresAt = new Date(normalized).getTime();
+  if (!Number.isFinite(expiresAt)) {
+    return false;
+  }
+  return expiresAt >= Date.now();
+}
+
 /**
  * Check if the current command requires authentication.
  * Returns true if auth is required but user is not logged in.
@@ -46,22 +87,15 @@ export async function checkAuthGate(args) {
     return { authenticated: true, session: null, bypassReason: "no_auth_required" };
   }
 
-  // CI/test bypass — allows automated testing without auth
-  if (process.env.SENTINELAYER_CLI_SKIP_AUTH === "1" || process.env.CI === "true") {
-    return { authenticated: true, session: null, bypassReason: "env_bypass" };
+  // Explicit bypass is gated to trusted test contexts only.
+  if (process.env.SENTINELAYER_CLI_SKIP_AUTH === "1" && hasTrustedBypassContext()) {
+    return { authenticated: true, session: null, bypassReason: "env_bypass_guarded" };
   }
 
   // Check for stored session
   try {
     const session = await readStoredSession();
-    if (session && session.token) {
-      // Check if token is expired
-      if (session.tokenExpiresAt) {
-        const expiresAt = new Date(session.tokenExpiresAt).getTime();
-        if (expiresAt < Date.now()) {
-          return { authenticated: false, session: null, bypassReason: null };
-        }
-      }
+    if (session && isValidSessionToken(session) && isSessionUnexpired(session.tokenExpiresAt)) {
       return { authenticated: true, session, bypassReason: null };
     }
   } catch {

package/src/auth/http.js

@@ -1,113 +1,270 @@
-import { setTimeout as sleep } from "node:timers/promises";
-
-/**
- * Default timeout applied to Sentinelayer API requests when no override is provided.
- * @type {number}
- */
-export const DEFAULT_REQUEST_TIMEOUT_MS = 20_000;
-
-function normalizeApiError(errorPayload = {}) {
-  if (!errorPayload || typeof errorPayload !== "object" || Array.isArray(errorPayload)) {
-    return {
-      code: "UNKNOWN",
-      message: "Unknown API error",
-      requestId: null,
-    };
-  }
-  return {
-    code: String(errorPayload.code || "UNKNOWN"),
-    message: String(errorPayload.message || "Unknown API error"),
-    requestId: errorPayload.request_id ? String(errorPayload.request_id) : null,
-  };
-}
-
-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"));
-    this.name = "SentinelayerApiError";
-    this.status = Number(status || 500);
-    this.code = String(code || "UNKNOWN");
-    this.requestId = requestId ? String(requestId) : null;
-  }
-}
-
-/**
- * Execute an HTTP request against the Sentinelayer API and parse a JSON response.
- * Throws `SentinelayerApiError` for transport errors, timeouts, API failures, and invalid JSON.
- *
- * @param {string} url
- * @param {{
- *   method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
- *   headers?: Record<string, string>,
- *   body?: unknown,
- *   timeoutMs?: number
- * }} [options]
- * @returns {Promise<any>}
- */
-export async function requestJson(
-  url,
-  { method = "GET", headers = {}, body, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}
-) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), Number(timeoutMs || DEFAULT_REQUEST_TIMEOUT_MS));
-
-  try {
-    const response = await fetch(String(url), {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        ...headers,
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
-      signal: controller.signal,
-    });
-
-    const rawBody = await response.text();
-    let json = {};
-    if (rawBody.trim()) {
-      try {
-        json = JSON.parse(rawBody);
-      } catch {
-        throw new SentinelayerApiError("Invalid JSON returned by API.", {
-          status: response.status,
-          code: "INVALID_JSON",
-        });
-      }
-    }
-
-    if (!response.ok) {
-      const apiError = normalizeApiError(json && typeof json === "object" ? json.error : {});
-      throw new SentinelayerApiError(apiError.message, {
-        status: response.status,
-        code: apiError.code,
-        requestId: apiError.requestId,
-      });
-    }
-
-    return json;
-  } catch (error) {
-    if (error instanceof SentinelayerApiError) {
-      throw error;
-    }
-    if (error && typeof error === "object" && error.name === "AbortError") {
-      throw new SentinelayerApiError("Request timed out.", {
-        status: 408,
-        code: "TIMEOUT",
-      });
-    }
-    throw new SentinelayerApiError(
-      error instanceof Error ? error.message : String(error || "Request failed"),
-      {
-        status: 503,
-        code: "NETWORK_ERROR",
-      }
-    );
-  } finally {
-    clearTimeout(timeout);
-    await sleep(0);
-  }
-}
+import { setTimeout as sleep } from "node:timers/promises";
+
+/**
+ * Default timeout applied to Sentinelayer API requests when no override is provided.
+ * @type {number}
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 20_000;
+export const DEFAULT_MAX_RETRIES = 2;
+export const DEFAULT_RETRY_DELAY_MS = 250;
+export const MAX_RETRY_DELAY_MS = 2_000;
+export const CIRCUIT_BREAKER_THRESHOLD = 5;
+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,
+};
+
+function normalizeApiError(errorPayload = {}) {
+  if (!errorPayload || typeof errorPayload !== "object" || Array.isArray(errorPayload)) {
+    return {
+      code: "UNKNOWN",
+      message: "Unknown API error",
+      requestId: null,
+    };
+  }
+  return {
+    code: String(errorPayload.code || "UNKNOWN"),
+    message: String(errorPayload.message || "Unknown API error"),
+    requestId: errorPayload.request_id ? String(errorPayload.request_id) : null,
+  };
+}
+
+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"));
+    this.name = "SentinelayerApiError";
+    this.status = Number(status || 500);
+    this.code = String(code || "UNKNOWN");
+    this.requestId = requestId ? String(requestId) : null;
+  }
+}
+
+function normalizePositiveNumber(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeNonNegativeInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return Math.floor(parsed);
+}
+
+function parseRetryAfterMs(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return null;
+  }
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1000);
+  }
+  const parsedDate = Date.parse(raw);
+  if (Number.isFinite(parsedDate)) {
+    const delta = parsedDate - Date.now();
+    if (delta > 0) {
+      return delta;
+    }
+  }
+  return null;
+}
+
+function computeBackoffMs({ attempt, retryDelayMs, retryAfterHeader }) {
+  const retryAfterMs = parseRetryAfterMs(retryAfterHeader);
+  if (retryAfterMs !== null) {
+    return Math.min(retryAfterMs, MAX_RETRY_DELAY_MS);
+  }
+  const exponent = Math.max(0, Number(attempt) - 1);
+  const computed = Math.round(retryDelayMs * Math.pow(2, exponent));
+  return Math.min(Math.max(1, computed), MAX_RETRY_DELAY_MS);
+}
+
+function isCircuitOpen() {
+  if (circuitState.openedAtMs <= 0) {
+    return false;
+  }
+  if (Date.now() - circuitState.openedAtMs >= CIRCUIT_BREAKER_COOLDOWN_MS) {
+    circuitState.openedAtMs = 0;
+    circuitState.consecutiveFailures = 0;
+    return false;
+  }
+  return true;
+}
+
+function recordFailureForCircuit() {
+  circuitState.consecutiveFailures += 1;
+  if (circuitState.consecutiveFailures >= CIRCUIT_BREAKER_THRESHOLD) {
+    circuitState.openedAtMs = Date.now();
+  }
+}
+
+function recordSuccessForCircuit() {
+  circuitState.consecutiveFailures = 0;
+  circuitState.openedAtMs = 0;
+}
+
+function shouldRetryStatus(statusCode) {
+  return RETRYABLE_STATUS_CODES.has(Number(statusCode || 0));
+}
+
+function shouldRecordFailureForStatus(statusCode) {
+  return CIRCUIT_TRACK_STATUS_CODES.has(Number(statusCode || 0));
+}
+
+export function __resetRequestCircuitForTests() {
+  circuitState.consecutiveFailures = 0;
+  circuitState.openedAtMs = 0;
+}
+
+/**
+ * Execute an HTTP request against the Sentinelayer API and parse a JSON response.
+ * Throws `SentinelayerApiError` for transport errors, timeouts, API failures, and invalid JSON.
+ *
+ * @param {string} url
+ * @param {{
+ *   method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+ *   headers?: Record<string, string>,
+ *   body?: unknown,
+ *   timeoutMs?: number
+ *   maxRetries?: number,
+ *   retryDelayMs?: number
+ * }} [options]
+ * @returns {Promise<any>}
+ */
+export async function requestJson(
+  url,
+  {
+    method = "GET",
+    headers = {},
+    body,
+    timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    retryDelayMs = DEFAULT_RETRY_DELAY_MS,
+  } = {}
+) {
+  if (isCircuitOpen()) {
+    throw new SentinelayerApiError("Request circuit breaker is open after consecutive API failures.", {
+      status: 503,
+      code: "CIRCUIT_OPEN",
+    });
+  }
+
+  const normalizedTimeoutMs = normalizePositiveNumber(timeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+  const normalizedMaxRetries = normalizeNonNegativeInteger(maxRetries, DEFAULT_MAX_RETRIES);
+  const normalizedRetryDelayMs = normalizePositiveNumber(retryDelayMs, DEFAULT_RETRY_DELAY_MS);
+
+  let lastRetryableError = null;
+  for (let attempt = 0; attempt <= normalizedMaxRetries; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), normalizedTimeoutMs);
+
+    try {
+      const response = await fetch(String(url), {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...headers,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      const rawBody = await response.text();
+      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 (response.ok) {
+        recordSuccessForCircuit();
+        return json;
+      }
+
+      const apiError = normalizeApiError(json && typeof json === "object" ? json.error : {});
+      const statusCode = Number(response.status || 500);
+      const retryable = shouldRetryStatus(statusCode);
+      const shouldRecordCircuitFailure = shouldRecordFailureForStatus(statusCode);
+      const error = new SentinelayerApiError(apiError.message, {
+        status: statusCode,
+        code: apiError.code,
+        requestId: apiError.requestId,
+      });
+
+      if (!retryable || attempt >= normalizedMaxRetries) {
+        if (shouldRecordCircuitFailure) {
+          recordFailureForCircuit();
+        }
+        throw error;
+      }
+
+      lastRetryableError = error;
+      const delayMs = computeBackoffMs({
+        attempt: attempt + 1,
+        retryDelayMs: normalizedRetryDelayMs,
+        retryAfterHeader: response.headers.get("retry-after"),
+      });
+      await sleep(delayMs);
+      continue;
+    } catch (error) {
+      if (error instanceof SentinelayerApiError) {
+        throw error;
+      }
+
+      const isAbortError = Boolean(error && typeof error === "object" && error.name === "AbortError");
+      const normalizedError = new SentinelayerApiError(
+        isAbortError ? "Request timed out." : (error instanceof Error ? error.message : String(error || "Request failed")),
+        {
+          status: isAbortError ? 408 : 503,
+          code: isAbortError ? "TIMEOUT" : "NETWORK_ERROR",
+        }
+      );
+
+      if (attempt >= normalizedMaxRetries) {
+        recordFailureForCircuit();
+        throw normalizedError;
+      }
+
+      lastRetryableError = normalizedError;
+      const delayMs = computeBackoffMs({
+        attempt: attempt + 1,
+        retryDelayMs: normalizedRetryDelayMs,
+        retryAfterHeader: null,
+      });
+      await sleep(delayMs);
+      continue;
+    } finally {
+      clearTimeout(timeout);
+      await sleep(0);
+    }
+  }
+
+  if (lastRetryableError instanceof SentinelayerApiError) {
+    throw lastRetryableError;
+  }
+  throw new SentinelayerApiError("Request failed without a terminal response.", {
+    status: 503,
+    code: "NETWORK_ERROR",
+  });
+}