@palai/sdk 0.4.0 → 0.6.0

package/dist/webhooks.js

@@ -0,0 +1,77 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+// Receiving the plane's webhooks (spec §21.5, §23.10): the receiver-side half of what every delivery carries. It mirrors
+// the server's signer (adapters/integrations/webhook) byte for byte, as the Go and Python SDKs do: the signed input is
+// "v1." + delivery id + "." + unix seconds + "." followed by the EXACT raw body, HMAC-SHA-256, hex. A rotation header
+// carries several space-separated v1= values, so a receiver on either the old or the new secret verifies during the
+// overlap.
+//
+// ‼️ VERIFY THE RAW BODY, NOT A RE-SERIALISED ONE. The MAC is over the bytes the plane sent; parsing and stringifying
+// the JSON before checking changes key order and whitespace and turns every delivery into a forgery.
+const VERSION = "v1";
+/** The default replay window around now, in seconds (spec §21.5). */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+/** The hex HMAC-SHA-256 the plane puts after `v1=` for one delivery. */
+export function signWebhook(secret, deliveryId, timestamp, body) {
+    return createHmac("sha256", secret).update(`${VERSION}.${deliveryId}.${timestamp}.`).update(body).digest("hex");
+}
+/** Whether a delivery was signed with `secret` and sent within the replay window. Constant-time. */
+export function verifyWebhook(params) {
+    const now = params.now ?? Math.floor(Date.now() / 1000);
+    const tolerance = params.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    const skew = now - params.timestamp;
+    if (!Number.isFinite(skew) || skew > tolerance || skew < -tolerance)
+        return false;
+    const want = Buffer.from(signWebhook(params.secret, params.id, params.timestamp, params.body));
+    for (const field of params.signature.split(/\s+/)) {
+        if (!field.startsWith(`${VERSION}=`))
+            continue;
+        const given = Buffer.from(field.slice(VERSION.length + 1));
+        // Equal lengths first: timingSafeEqual throws on a length mismatch, and the header is the sender's to write.
+        if (given.length === want.length && timingSafeEqual(given, want))
+            return true;
+    }
+    return false;
+}
+/** A delivery that did not verify: a missing header, a bad signature, or a timestamp outside the window. */
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+/**
+ * Verifies a delivery from its headers and raw body and returns its event. Throws WebhookVerificationError for
+ * anything that does not verify — answer those 400 and the plane stops retrying them only when its window closes.
+ */
+export function parseWebhook(params) {
+    const header = (name) => {
+        if (params.headers instanceof Headers)
+            return params.headers.get(name) ?? undefined;
+        const found = Object.entries(params.headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+        return Array.isArray(found) ? found[0] : found;
+    };
+    const id = header("webhook-id"), stamp = header("webhook-timestamp"), signature = header("webhook-signature");
+    if (!id || !stamp || !signature)
+        throw new WebhookVerificationError("the delivery is missing its Webhook-Id, Webhook-Timestamp or Webhook-Signature header");
+    const timestamp = Number(stamp);
+    if (!Number.isSafeInteger(timestamp))
+        throw new WebhookVerificationError("the Webhook-Timestamp header is not unix seconds");
+    const secrets = Array.isArray(params.secret) ? params.secret : [params.secret];
+    const verified = secrets.some((secret) => verifyWebhook({
+        secret, id, timestamp, body: params.body, signature,
+        ...(params.now !== undefined ? { now: params.now } : {}),
+        ...(params.toleranceSeconds !== undefined ? { toleranceSeconds: params.toleranceSeconds } : {}),
+    }));
+    if (!verified)
+        throw new WebhookVerificationError("the delivery's signature does not verify, or it was sent outside the replay window");
+    const text = typeof params.body === "string" ? params.body : new TextDecoder().decode(params.body);
+    let envelope;
+    try {
+        envelope = JSON.parse(text);
+    }
+    catch {
+        throw new WebhookVerificationError("the delivery's body is not JSON");
+    }
+    return { ...envelope, deliveryId: id };
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palai/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeScript client for the Palai API: responses, sessions, agents, approvals, artifacts and streaming.",
   "license": "Apache-2.0",
   "type": "module",