@usequeek/app-sdk 0.4.0

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAQ5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,OAAO;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,kBAAkB,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,CAAC,KAAK,GAAG,OAAO,IAAI,CAC9C,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACrC,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,iBAAiB,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,uDAAuD;IACvD,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,oBAAoB,GAAG,IAAI,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,KAChE,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAyCD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAiFzE"}

package/dist/webhooks.js

@@ -0,0 +1,125 @@
+import { Hono } from "hono";
+import { MAX_TIMESTAMP_SKEW_SECONDS, verifyQueekSignature, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.js";
+/**
+ * Receiver for Queek topic deliveries (`DeliverWebhookJob` in
+ * queek_backend, one signed POST per installation endpoint).
+ *
+ * Delivery envelope: `{ id, topic, api_version: "v1", created_at, data }`
+ * with `X-Queek-Topic` echoing `topic`. Verification uses the
+ * PER-INSTALLATION endpoint secret handed over once inside the install
+ * payload (`data.webhook_secret`) — never the app signing secret.
+ *
+ * Secret lookup: topic payloads are resource renders with no guaranteed
+ * installation/vendor id, so the default resolver identifies the
+ * installation by trying each stored installation secret against the
+ * signature (the signature itself names the sender; HMACs are microseconds,
+ * installations per app are few). Apps that carry their own routing hint
+ * may pass `resolveSecret` instead.
+ *
+ * Dedupe: Queek retries a delivery for ~4h until it sees 2xx, so every
+ * `webhook-id` is processed AT MOST once — the header id is claimed
+ * atomically up front (exactly one concurrent same-id delivery runs the
+ * handler) and a repeat answers 200 WITHOUT re-running it. A throwing
+ * handler releases the claim and answers 500 so the retry can land.
+ * Unknown topics answer 200 too (a topic the app no longer handles must
+ * not wedge Queek's retry queue); only auth and malformed bodies are
+ * non-2xx.
+ */
+export const QUEEK_TOPIC_HEADER = "X-Queek-Topic";
+async function defaultResolveSecret(store, rawBody, headers, envelope) {
+    // Fast path: handoff-shaped payloads that name their installation.
+    const data = envelope?.data;
+    const named = data !== null && typeof data === "object"
+        ? data.installation?.id
+        : undefined;
+    if (typeof named === "string" && named !== "") {
+        const found = await store.getInstallation(named);
+        const secret = found?.webhookSecret;
+        if (found &&
+            secret &&
+            verifyQueekSignature({ ...headers, body: rawBody, secret }, { skipFreshnessCheck: true })) {
+            return { installationId: found.installationId, secret };
+        }
+        return null;
+    }
+    // General path: the signature identifies the sender.
+    const candidates = await store.listWebhookSecrets();
+    for (const candidate of candidates) {
+        if (verifyQueekSignature({ ...headers, body: rawBody, secret: candidate.secret }, { skipFreshnessCheck: true })) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function createWebhookHandler(options) {
+    const app = new Hono();
+    const maxSkew = options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS;
+    app.post("/", async (c) => {
+        const rawBody = await c.req.text();
+        const id = c.req.header(WEBHOOK_ID_HEADER);
+        const timestamp = c.req.header(WEBHOOK_TIMESTAMP_HEADER);
+        const signatureHeader = c.req.header(WEBHOOK_SIGNATURE_HEADER);
+        if (!id || !timestamp || !signatureHeader) {
+            return c.json({ ok: false, error: "missing signature headers" }, 401);
+        }
+        let envelope = null;
+        try {
+            const parsed = JSON.parse(rawBody);
+            if (typeof parsed === "object" && parsed !== null)
+                envelope = parsed;
+        }
+        catch {
+            return c.json({ ok: false, error: "invalid_json" }, 400);
+        }
+        if (!envelope || typeof envelope.topic !== "string") {
+            return c.json({ ok: false, error: "invalid_envelope" }, 400);
+        }
+        const headers = { id, timestamp, signatureHeader };
+        const resolution = options.resolveSecret
+            ? await options.resolveSecret(envelope, rawBody, headers)
+            : await defaultResolveSecret(options.store, rawBody, headers, envelope);
+        if (!resolution) {
+            return c.json({ ok: false, error: "unknown_installation" }, 401);
+        }
+        // Freshness is enforced HERE, once, against the resolved secret — the
+        // lookup above deliberately skips it so a stale delivery cannot be
+        // misattributed before it is rejected.
+        const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+        const ts = Number(timestamp);
+        if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkew) {
+            return c.json({ ok: false, error: "stale timestamp" }, 401);
+        }
+        // Freshness was enforced above; this re-checks the MAC only, so a
+        // custom resolver cannot claim an installation without its secret.
+        if (!verifyQueekSignature({ ...headers, body: rawBody, secret: resolution.secret }, { skipFreshnessCheck: true })) {
+            return c.json({ ok: false, error: "signature mismatch" }, 401);
+        }
+        const installation = await options.store.getInstallation(resolution.installationId);
+        if (!installation) {
+            return c.json({ ok: false, error: "unknown_installation" }, 401);
+        }
+        // Atomic claim on the HEADER id: exactly one concurrent same-id
+        // delivery runs the handler; the rest answer deduped.
+        if (!(await options.store.claimWebhookId(id))) {
+            return c.json({ ok: true, deduped: true });
+        }
+        const topic = c.req.header(QUEEK_TOPIC_HEADER) ?? envelope.topic;
+        const handler = options.handlers[topic];
+        if (!handler) {
+            // No handler for this topic is NOT a failure: answering non-2xx would
+            // retry for hours something the app will never handle. The claim
+            // stands as the seen-record.
+            return c.json({ ok: true, unhandled: true });
+        }
+        try {
+            await handler(envelope, { installation, topic, eventId: id });
+        }
+        catch {
+            await options.store.releaseWebhookId(id);
+            return c.json({ ok: false, error: "handler_failed" }, 500);
+        }
+        return c.json({ ok: true });
+    });
+    return app;
+}
+//# 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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"}