@volidator/node 1.0.0 → 1.0.2

package/dist/middleware/next.cjs

@@ -25,8 +25,10 @@ __export(next_exports, {
 module.exports = __toCommonJS(next_exports);
 
 // src/index.ts
-var VolidatorClient = class _VolidatorClient {
+var import_node_async_hooks = require("async_hooks");
+var _VolidatorClient = class _VolidatorClient {
   constructor(config) {
+    this.fallbackLogicalClock = 0;
     this.apiKey = config.apiKey;
     this.endpoint = config.endpoint || "https://ingestion.volidator.com";
     this.projectId = config.projectId;
@@ -34,6 +36,8 @@ var VolidatorClient = class _VolidatorClient {
     this.redactKeys = config.redactKeys || [];
     this.referenceKeys = config.referenceKeys || [];
     this.maxMetadataSize = config.maxMetadataSize || 10240;
+    this.maxRetries = config.maxRetries !== void 0 ? config.maxRetries : 3;
+    this.onDeliveryFailure = config.onDeliveryFailure;
     if (config.keyring && config.activeEncryptionKeyId) {
       this.keyring = config.keyring;
       this.activeKeyId = config.activeEncryptionKeyId;
@@ -54,6 +58,22 @@ var VolidatorClient = class _VolidatorClient {
     this.compliance = new VolidatorCompliance(this);
     this.agent = new VolidatorAgent(this);
   }
+  /**
+   * Increments and returns the current Lamport Logical Clock counter.
+   * If a logicalClockStore context is active, it reads, syncs, and updates
+   * the thread-scoped clock; otherwise, it falls back to a global instance-scoped counter.
+   *
+   * @param incomingClock Optional logical clock sequence from incoming trace parent header
+   */
+  getAndIncrementClock(incomingClock) {
+    const store = _VolidatorClient.logicalClockStore.getStore();
+    if (store) {
+      store.clock = Math.max(store.clock, incomingClock || 0) + 1;
+      return store.clock;
+    }
+    this.fallbackLogicalClock = Math.max(this.fallbackLogicalClock, incomingClock || 0) + 1;
+    return this.fallbackLogicalClock;
+  }
   // ---------------------------------------------------------------------------
   // Telemetry Context Parser (Zero-latency header parsing)
   // ---------------------------------------------------------------------------
@@ -95,11 +115,23 @@ var VolidatorClient = class _VolidatorClient {
       }
       return "";
     };
+    const result = {};
+    const clockVal = getHeader("x-volidator-clock");
+    if (clockVal) {
+      const parsed = parseInt(clockVal, 10);
+      if (!isNaN(parsed)) {
+        result.logicalClock = parsed;
+      }
+    }
     const traceparent = getHeader("traceparent");
-    if (!traceparent) return {};
-    const parts = traceparent.split("-");
-    if (parts.length !== 4) return {};
-    return { traceId: parts[1], spanId: parts[2] };
+    if (traceparent) {
+      const parts = traceparent.split("-");
+      if (parts.length === 4) {
+        result.traceId = parts[1];
+        result.spanId = parts[2];
+      }
+    }
+    return result;
   }
   static resolveTelemetryConfig(config) {
     const preset = config.preset || "standard";
@@ -222,6 +254,12 @@ var VolidatorClient = class _VolidatorClient {
   // prepareLogEntry() — Prepares, redacts, and encrypts a single log entry payload
   // ---------------------------------------------------------------------------
   async prepareLogEntry(payload, maxMetaOverride) {
+    const PAYLOAD_5MB_LIMIT = 5 * 1024 * 1024;
+    const metadata = payload.metadata || {};
+    const payloadSize = new TextEncoder().encode(JSON.stringify(metadata)).length;
+    if (payloadSize > PAYLOAD_5MB_LIMIT) {
+      throw new Error(`Volidator SDK Error: Audit log payload exceeds the 5MB hard limit (${payloadSize} bytes).`);
+    }
     const actorRaw = payload.actor || payload.actorId || "unknown";
     const targetRaw = payload.target || payload.targetId || "unknown";
     const tenantRaw = payload.tenant || payload.tenantId || "";
@@ -303,13 +341,20 @@ var VolidatorClient = class _VolidatorClient {
         safeMetadata[k] = v;
       }
     }
+    let didTruncateDepth = false;
+    let didTruncateString = false;
     const limitDepth = (obj, currentDepth = 1) => {
       if (currentDepth > 5) {
+        didTruncateDepth = true;
         return "[Truncated - Depth Exceeded]";
       }
       if (typeof obj !== "object" || obj === null) {
         if (typeof obj === "string") {
-          return truncate(obj, 1e3);
+          const truncatedVal = truncate(obj, 1e3);
+          if (truncatedVal.length !== obj.length) {
+            didTruncateString = true;
+          }
+          return truncatedVal;
         }
         return obj;
       }
@@ -323,6 +368,14 @@ var VolidatorClient = class _VolidatorClient {
       return result;
     };
     const processedMetadata = limitDepth(safeMetadata);
+    if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      if (didTruncateDepth) {
+        console.warn("[Volidator] Warning: Log metadata exceeded maximum depth limit (5) and was truncated.");
+      }
+      if (didTruncateString) {
+        console.warn("[Volidator] Warning: One or more log metadata string values exceeded the 1000-character limit and were truncated.");
+      }
+    }
     const serializedMeta = JSON.stringify(processedMetadata);
     const maxMetaLimit = maxMetaOverride || this.maxMetadataSize;
     if (serializedMeta.length > maxMetaLimit) {
@@ -346,6 +399,7 @@ var VolidatorClient = class _VolidatorClient {
     let traceId = payload.traceId;
     let spanId = payload.spanId;
     let parentSpanId = payload.parentSpanId;
+    let logicalClock = payload.logicalClock;
     if (payload.req) {
       const extractedTrace = _VolidatorClient.extractTraceContext(payload.req);
       if (!traceId && extractedTrace.traceId) {
@@ -354,7 +408,11 @@ var VolidatorClient = class _VolidatorClient {
       if (!spanId && extractedTrace.spanId) {
         spanId = extractedTrace.spanId;
       }
+      if (logicalClock === void 0 && extractedTrace.logicalClock !== void 0) {
+        logicalClock = extractedTrace.logicalClock;
+      }
     }
+    const resolvedClock = this.getAndIncrementClock(logicalClock);
     if (spanId) {
       enrichedPayload.spanId = spanId;
     }
@@ -367,14 +425,39 @@ var VolidatorClient = class _VolidatorClient {
     const targetBlindIndex = await this.generateBlindIndex(target, activeKeyBuffer);
     const tenantBlindIndex = tenant ? await this.generateBlindIndex(tenant, activeKeyBuffer) : void 0;
     const traceBlindIndex = traceId ? await this.generateBlindIndex(traceId, activeKeyBuffer) : void 0;
-    const encryptedPayload = await this.encryptPayload(enrichedPayload);
+    let encryptedPayload = await this.encryptPayload(enrichedPayload);
+    let isClaimCheck = false;
+    if (encryptedPayload.length > 30720) {
+      const binaryBuffer = new TextEncoder().encode(encryptedPayload);
+      const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", binaryBuffer);
+      const hashHex = Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+      try {
+        const uploadRes = await fetch(`${this.endpoint}/v1/log/upload/${hashHex}`, {
+          method: "PUT",
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/octet-stream"
+          },
+          body: encryptedPayload
+        });
+        if (!uploadRes.ok) {
+          throw new Error(`Upload failed with status: ${uploadRes.status}`);
+        }
+        encryptedPayload = hashHex;
+        isClaimCheck = true;
+      } catch (err) {
+        console.error(`[Volidator] Claim check upload failed: ${err.message}`);
+      }
+    }
     return {
       actorBlindIndex,
       actionBlindIndex,
       targetBlindIndex,
       tenantBlindIndex,
       traceBlindIndex,
-      encryptedPayload
+      encryptedPayload,
+      logicalClock: resolvedClock,
+      isClaimCheck
     };
   }
   // ---------------------------------------------------------------------------
@@ -382,20 +465,44 @@ var VolidatorClient = class _VolidatorClient {
   // ---------------------------------------------------------------------------
   async log(payload, maxMetaOverride) {
     const entry = await this.prepareLogEntry(payload, maxMetaOverride);
-    try {
-      const res = await fetch(`${this.endpoint}/v1/log`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(entry)
-      });
-      return res.ok;
-    } catch (err) {
-      console.error(`[Volidator] Failed to send log: ${err.message}`);
-      return false;
+    let attempt = 0;
+    let delay = 500;
+    let lastError = new Error("Unknown error");
+    while (attempt <= this.maxRetries) {
+      try {
+        const res = await fetch(`${this.endpoint}/v1/log`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(entry)
+        });
+        if (res.ok) {
+          return true;
+        }
+        lastError = new Error(`Server returned status ${res.status}`);
+        if (res.status >= 400 && res.status < 500) {
+          break;
+        }
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+      attempt++;
+      if (attempt <= this.maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay *= 3;
+      }
+    }
+    console.error(`[Volidator] Failed to send log after ${attempt} attempts: ${lastError.message}`);
+    if (this.onDeliveryFailure) {
+      try {
+        this.onDeliveryFailure(payload, lastError);
+      } catch (cbErr) {
+        console.error(`[Volidator] Error in onDeliveryFailure callback: ${cbErr.message}`);
+      }
     }
+    return false;
   }
   // ---------------------------------------------------------------------------
   // logBatch() — Bulk encrypt and ingest a batch of up to 100 audit events
@@ -442,12 +549,79 @@ var VolidatorClient = class _VolidatorClient {
     }
   }
   // ---------------------------------------------------------------------------
+  // batcher() — Convenience batcher for buffered log ingestion
+  // ---------------------------------------------------------------------------
+  /**
+   * Creates a convenience batcher instance for buffering and ingestion.
+   * 
+   * ⚠️ SERVERLESS/EDGE CAVEAT:
+   * autoFlushInterval uses setInterval internally. In serverless/edge environments
+   * (e.g. Cloudflare Workers, Vercel Edge), the V8 isolate is frozen or destroyed
+   * once the response is sent. Background timers will silently fail to fire, leading
+   * to dropped logs. Only use autoFlushInterval in long-lived Node.js processes.
+   * In serverless/edge environments, always call await batcher.flush() explicitly
+   * before returning the response, or wrap it in ctx.waitUntil().
+   */
+  batcher(options) {
+    const client = this;
+    let buffer = [];
+    let intervalId = null;
+    const flush = async () => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      if (buffer.length === 0) {
+        if (options?.autoFlushInterval) {
+          startTimer();
+        }
+        return { accepted: 0, rejected: 0 };
+      }
+      const payloadsToFlush = [...buffer];
+      buffer = [];
+      if (options?.autoFlushInterval) {
+        startTimer();
+      }
+      return client.logBatch(payloadsToFlush);
+    };
+    const startTimer = () => {
+      if (options?.autoFlushInterval && !intervalId) {
+        intervalId = setInterval(() => {
+          flush().catch((err) => {
+            console.error(`[Volidator] Batcher auto-flush failed: ${err.message}`);
+          });
+        }, options.autoFlushInterval);
+        if (intervalId && typeof intervalId.unref === "function") {
+          intervalId.unref();
+        }
+      }
+    };
+    const push = (payload) => {
+      buffer.push(payload);
+      const maxCount = options?.autoFlushCount || 100;
+      if (buffer.length >= Math.min(maxCount, 100)) {
+        flush().catch((err) => {
+          console.error(`[Volidator] Batcher auto-flush on count failed: ${err.message}`);
+        });
+      }
+    };
+    const size = () => buffer.length;
+    startTimer();
+    return {
+      push,
+      flush,
+      size
+    };
+  }
+  // ---------------------------------------------------------------------------
   // generateEmbedToken() — Sign a HS256 JWT for the embeddable dashboard widget
   // ---------------------------------------------------------------------------
   async generateEmbedToken(config) {
-    if (!this.projectId || !this.clientSecret) {
+    const projectId = config.projectId || this.projectId;
+    const clientSecret = config.clientSecret || this.clientSecret;
+    if (!projectId || !clientSecret) {
       throw new Error(
-        "generateEmbedToken() requires projectId and clientSecret in the VolidatorClient constructor."
+        "generateEmbedToken() requires projectId and clientSecret to be provided in either the configuration or the VolidatorClient constructor."
       );
     }
     const {
@@ -474,7 +648,7 @@ var VolidatorClient = class _VolidatorClient {
     const expiresInSeconds = Math.min(parsedExpiry, maxExpiry);
     const now = Math.floor(Date.now() / 1e3);
     const payload = {
-      pid: this.projectId,
+      pid: projectId,
       scope: defaultScope,
       iat: now,
       exp: now + expiresInSeconds
@@ -507,7 +681,7 @@ var VolidatorClient = class _VolidatorClient {
       }
       payload.view = compressed;
     }
-    const token = await this.signHS256JWT(payload, this.clientSecret);
+    const token = await this.signHS256JWT(payload, clientSecret);
     const keyringString = Object.entries(this.keyring).map(([id, key]) => `${id}:${key}`).join(",");
     const hostParam = hostOrigin ? `?host=${encodeURIComponent(hostOrigin)}` : "";
     const embedUrl = `${dashboardUrl}/embed/${token}${hostParam}#${keyringString}`;
@@ -556,6 +730,13 @@ var VolidatorClient = class _VolidatorClient {
     }
   }
 };
+/**
+ * Thread-local asynchronous context storage used to maintain
+ * and increment Lamport logical clock sequences across execution boundaries
+ * (e.g. within API requests or serverless handler contexts).
+ */
+_VolidatorClient.logicalClockStore = new import_node_async_hooks.AsyncLocalStorage();
+var VolidatorClient = _VolidatorClient;
 var VolidatorCompliance = class {
   constructor(client) {
     this.client = client;
@@ -685,6 +866,8 @@ var VolidatorAgent = class {
 function withVolidator(client, handler) {
   return async (req, ctx = {}, ...args) => {
     const extractedContext = VolidatorClient.extractContext(req);
+    const extractedTrace = VolidatorClient.extractTraceContext(req);
+    const incomingClock = extractedTrace.logicalClock || 0;
     const scopedLog = async (payload) => {
       return client.log({
         ...payload,
@@ -725,7 +908,9 @@ function withVolidator(client, handler) {
         compliance: scopedCompliance
       }
     };
-    return handler(req, newCtx, ...args);
+    return VolidatorClient.logicalClockStore.run({ clock: incomingClock }, () => {
+      return handler(req, newCtx, ...args);
+    });
   };
 }
 // Annotate the CommonJS export names for ESM import in node: