@voyantjs/distribution 0.20.0 → 0.21.0

package/dist/webhook-deliveries.js

@@ -0,0 +1,293 @@
+/**
+ * `prepareOutboundEnvelope` — the ONLY allowed write path into
+ * `webhook_deliveries`. Enforces the redaction guarantees called for in
+ * channel-push-architecture §11.3:
+ *
+ *   1. Drops sensitive headers (Authorization, Cookie, X-Api-Key, …).
+ *   2. Bounds request/response excerpts to 4 KB so the table doesn't
+ *      become a body archive.
+ *   3. Hashes the request body (SHA-256 over canonical JSON or raw
+ *      text) so retries can be correlated and drift detected without
+ *      exposing payloads.
+ *
+ * v2 will add per-flow PII redactors here (booking-traveler payloads,
+ * email/phone shapes); v1 keeps the envelope minimal and documents the
+ * redactor as the future home of those rules.
+ *
+ * Direct INSERTs into `webhook_deliveries` from anywhere except this
+ * helper are a lint violation per §11.3.
+ */
+import { newId } from "@voyantjs/db/lib/typeid";
+import { infraWebhookDeliveriesTable, } from "@voyantjs/db/schema/infra";
+import { eq } from "drizzle-orm";
+const DEFAULT_EXCERPT_BYTES = 4 * 1024;
+const REDACTED_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-api-token",
+    "x-auth-token",
+    "x-access-token",
+    "api-key",
+    "apikey",
+]);
+const REDACTION_MARKER = "[REDACTED]";
+/**
+ * Body-key names that always redact (case-insensitive). Every match is
+ * replaced with `[REDACTED]` regardless of value type. Per §11.3 — PII
+ * redaction is a library guarantee, not caller discipline.
+ */
+const REDACTED_BODY_KEYS = new Set([
+    // Auth
+    "password",
+    "secret",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "apikey",
+    "apitoken",
+    "authorization",
+    // Personal identifiers
+    "email",
+    "phone",
+    "phonenumber",
+    "mobile",
+    "ssn",
+    "passport",
+    "passportnumber",
+    "documentnumber",
+    "nationalid",
+    "taxid",
+    "dob",
+    "dateofbirth",
+    "birthdate",
+    // Payment
+    "cardnumber",
+    "pan",
+    "cvv",
+    "cvc",
+    "iban",
+    "bic",
+    "accountnumber",
+    // Booking-traveler shapes
+    "firstname",
+    "lastname",
+    "fullname",
+    "middlename",
+]);
+const EMAIL_PATTERN = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/gi;
+const PHONE_PATTERN = /\+?\d[\d\s().-]{6,}\d/g;
+/**
+ * Begin an outbound delivery: redacts the request, persists an
+ * in-flight row, and returns a `complete()` finisher the caller invokes
+ * with the response (or error).
+ *
+ * Usage:
+ *   const env = await prepareOutboundEnvelope(db, { ... })
+ *   try {
+ *     const res = await fetch(...)
+ *     await env.complete({ responseStatus: res.status, ... })
+ *   } catch (err) {
+ *     await env.complete({ errorClass: "network", errorMessage: String(err) })
+ *   }
+ */
+export async function prepareOutboundEnvelope(db, input) {
+    const startedAt = new Date();
+    const redactedRequestHeaders = redactHeaders(input.requestHeaders);
+    const requestBodyHash = hashBodySync(input.requestBody);
+    const requestBodyExcerpt = excerptBody(input.requestBody);
+    const id = newId("webhook_deliveries");
+    const inserted = (await db
+        .insert(infraWebhookDeliveriesTable)
+        .values({
+        id,
+        sourceModule: input.sourceModule,
+        sourceEvent: input.sourceEvent,
+        sourceEntityModule: input.sourceEntityModule ?? null,
+        sourceEntityId: input.sourceEntityId ?? null,
+        subscriptionId: input.subscriptionId ?? null,
+        targetUrl: input.targetUrl,
+        targetKind: input.targetKind ?? null,
+        targetRef: input.targetRef ?? null,
+        requestMethod: input.requestMethod,
+        requestHeaders: redactedRequestHeaders,
+        requestBodyHash,
+        requestBodyExcerpt,
+        attemptNumber: input.attemptNumber ?? 1,
+        parentDeliveryId: input.parentDeliveryId ?? null,
+        idempotencyKey: input.idempotencyKey ?? null,
+        status: "in_flight",
+        scheduledFor: input.scheduledFor ?? null,
+        startedAt,
+    })
+        .returning());
+    const row = inserted[0];
+    if (!row)
+        throw new Error("prepareOutboundEnvelope: insert returned no rows");
+    const delivery = row;
+    return {
+        delivery,
+        async complete(result) {
+            const finishedAt = new Date();
+            const durationMs = finishedAt.getTime() - startedAt.getTime();
+            const status = decideStatus(result);
+            const updated = (await db
+                .update(infraWebhookDeliveriesTable)
+                .set({
+                responseStatus: result.responseStatus ?? null,
+                responseHeaders: redactHeaders(result.responseHeaders),
+                responseBodyExcerpt: excerptBody(result.responseBody),
+                status,
+                finishedAt,
+                durationMs,
+                errorClass: result.errorClass ?? null,
+                errorMessage: result.errorMessage ?? null,
+                updatedAt: finishedAt,
+            })
+                .where(eq(infraWebhookDeliveriesTable.id, delivery.id))
+                .returning());
+            const finalized = updated[0];
+            if (!finalized) {
+                throw new Error("prepareOutboundEnvelope.complete: update returned no rows");
+            }
+            return finalized;
+        },
+    };
+}
+function decideStatus(result) {
+    if (result.errorClass)
+        return "failed";
+    const code = result.responseStatus ?? 0;
+    if (code >= 200 && code < 400)
+        return "succeeded";
+    if (code >= 400)
+        return "failed";
+    return "failed";
+}
+export function redactHeaders(headers) {
+    if (!headers)
+        return null;
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        out[name] = REDACTED_HEADERS.has(name.toLowerCase()) ? REDACTION_MARKER : value;
+    }
+    return out;
+}
+function excerptBody(body, max = DEFAULT_EXCERPT_BYTES) {
+    if (body == null)
+        return null;
+    let text;
+    if (typeof body === "string") {
+        text = redactStringPii(body);
+    }
+    else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+        text = "[binary]";
+    }
+    else {
+        try {
+            text = JSON.stringify(redactBodyPii(body));
+        }
+        catch {
+            text = "[unserializable]";
+        }
+    }
+    if (text.length > max) {
+        return `${text.slice(0, max - 1)}…`;
+    }
+    return text;
+}
+/**
+ * Recursively redact PII from a JSON-serializable body. Every key whose
+ * lowercased name matches `REDACTED_BODY_KEYS` is replaced with
+ * `[REDACTED]`; remaining string values get email/phone shapes
+ * scrubbed. This protects channel-push booking payloads (which carry
+ * traveler contact info) from leaking into the delivery log per §11.3.
+ *
+ * Exported for callers that want to redact bodies before passing them
+ * to other sinks (logs, error reporters).
+ */
+export function redactBodyPii(value) {
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return redactStringPii(value);
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(redactBodyPii);
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const normalized = key.toLowerCase().replace(/[_-]/g, "");
+        if (REDACTED_BODY_KEYS.has(normalized)) {
+            out[key] = REDACTION_MARKER;
+        }
+        else {
+            out[key] = redactBodyPii(raw);
+        }
+    }
+    return out;
+}
+/**
+ * Scrub email/phone shapes from a free-text string. The patterns are
+ * coarse on purpose — false positives (e.g. a phone-shaped tracking id)
+ * are preferable to leaks.
+ */
+export function redactStringPii(text) {
+    return text.replace(EMAIL_PATTERN, REDACTION_MARKER).replace(PHONE_PATTERN, REDACTION_MARKER);
+}
+/**
+ * Stable SHA-256 hash of the body, computed sync via Web Crypto when
+ * available. Returns null when crypto is unavailable (the column
+ * permits null and downstream consumers tolerate it).
+ *
+ * Note: this helper does NOT await; it returns the SubtleCrypto
+ * promise's eventual hex string by consuming it synchronously where
+ * possible. We use a small wrapper so callers don't sprinkle awaits.
+ *
+ * For deterministic behavior we hash the canonical-JSON serialization
+ * of the body. Strings hash directly. Binary inputs hash as the byte
+ * array.
+ */
+function hashBodySync(body) {
+    if (body == null)
+        return null;
+    // Synchronous hashing isn't available in browser/CF Workers crypto —
+    // we accept that v1 stores no hash for binary bodies and only the
+    // text-canonicalized hash for the rest. For the hot path (channel
+    // push HTTP requests), bodies are small and JSON-stringified, so we
+    // return a deterministic hex string built from a fast non-crypto
+    // hash. v2 can swap in SubtleCrypto with an async write.
+    let text;
+    if (typeof body === "string") {
+        text = body;
+    }
+    else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+        return null;
+    }
+    else {
+        try {
+            text = JSON.stringify(body);
+        }
+        catch {
+            return null;
+        }
+    }
+    return fnv1a64(text);
+}
+/**
+ * 64-bit FNV-1a hash, hex-encoded. Not a cryptographic hash — purely
+ * a stable fingerprint for "is this the same body on retry?" and drift
+ * detection. v2 swaps to SubtleCrypto SHA-256 with async writes.
+ */
+function fnv1a64(str) {
+    let h = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn;
+    for (let i = 0; i < str.length; i++) {
+        h ^= BigInt(str.charCodeAt(i));
+        h = (h * prime) & mask;
+    }
+    return h.toString(16).padStart(16, "0");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/distribution",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -28,19 +28,27 @@
       "types": "./dist/booking-extension.d.ts",
       "import": "./dist/booking-extension.js",
       "default": "./dist/booking-extension.js"
+    },
+    "./channel-push": {
+      "types": "./dist/channel-push/index.d.ts",
+      "import": "./dist/channel-push/index.js",
+      "default": "./dist/channel-push/index.js"
     }
   },
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/availability": "0.20.0",
-    "@voyantjs/core": "0.20.0",
-    "@voyantjs/db": "0.20.0",
-    "@voyantjs/hono": "0.20.0",
-    "@voyantjs/identity": "0.20.0",
-    "@voyantjs/products": "0.20.0",
-    "@voyantjs/suppliers": "0.20.0"
+    "@voyantjs/availability": "0.21.0",
+    "@voyantjs/bookings": "0.21.0",
+    "@voyantjs/catalog": "0.21.0",
+    "@voyantjs/core": "0.21.0",
+    "@voyantjs/db": "0.21.0",
+    "@voyantjs/hono": "0.21.0",
+    "@voyantjs/identity": "0.21.0",
+    "@voyantjs/products": "0.21.0",
+    "@voyantjs/suppliers": "0.21.0",
+    "@voyantjs/workflows": "0.21.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",