@usequeek/app-sdk 0.8.0 → 0.8.1

package/dist/webhooks.d.ts

@@ -1,4 +1,4 @@
-import { type CoreDelivery, type DeliveryErrorHandler, type DeliveryResult } from "./delivery.js";
+import { type DeliveryErrorHandler, type DeliveryResult, type WebhookDelivery } from "./delivery.js";
 import type { InstallationRecord, InstallationStore } from "./store.js";
 /**
  * Framework-agnostic receiver for Queek topic deliveries (one signed POST
@@ -79,6 +79,11 @@ export interface WebhookHandlerOptions {
  * 200 for a handled, repeated or unhandled-topic delivery; 500 when your
  * handler throws (the claim is released so Queek's retry can land).
  *
+ * `method` `GET` or `HEAD` is the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no handler; with a signature (over the
+ * empty body) 200 when it verifies against an installation secret and 401
+ * when not.
+ *
  * @example
  * const result = await handleWebhookDelivery(
  *   { rawBody, headers },
@@ -93,10 +98,11 @@ export interface WebhookHandlerOptions {
  * );
  * // reply with result.status and result.body
  */
-export declare function handleWebhookDelivery(input: CoreDelivery, options: WebhookHandlerOptions): Promise<DeliveryResult>;
+export declare function handleWebhookDelivery(input: WebhookDelivery, options: WebhookHandlerOptions): Promise<DeliveryResult>;
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads
  * `await request.arrayBuffer()` + headers, calls the core, builds the
- * `Response`. Only `POST` is served; anything else answers 405.
+ * `Response`. `POST` is a delivery; `GET` and `HEAD` are the review probe
+ * (see `handleWebhookDelivery`); anything else answers 405.
  */
 export declare function handleWebhookRequest(request: Request, options: WebhookHandlerOptions): Promise<Response>;

package/dist/webhooks.js

@@ -1,4 +1,4 @@
-import { decodeBody, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
+import { decodeBody, isProbeMethod, isUnsignedProbe, probeResult, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
 import { isFreshTimestamp, MAX_TIMESTAMP_SKEW_SECONDS, verifyQueekSignature, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.js";
 /**
  * Framework-agnostic receiver for Queek topic deliveries (one signed POST
@@ -57,6 +57,50 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
     }
     return null;
 }
+/**
+ * Resolve the endpoint secret that signed a delivery and verify freshness
+ * and the MAC against it. The single verification path of a delivery AND of
+ * a signed review probe (empty body, no envelope).
+ */
+async function verifyAgainstResolvedSecret(options, rawBody, headers, envelope) {
+    const resolution = options.resolveSecret
+        ? await options.resolveSecret(envelope, rawBody, headers)
+        : await defaultResolveSecret(options.store, rawBody, headers, envelope);
+    if (!resolution) {
+        return { ok: false, error: "unknown_installation" };
+    }
+    // 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);
+    if (!isFreshTimestamp(headers.timestamp, now, options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS)) {
+        return { ok: false, error: "stale timestamp" };
+    }
+    // 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 { ok: false, error: "signature mismatch" };
+    }
+    return { ok: true, resolution };
+}
+/**
+ * The review probe (`GET` / `HEAD`): 200 without running a handler or
+ * touching the store. A probe that carries a signature is verified like a
+ * delivery, over the empty body and against the stored endpoint secrets:
+ * 200 when it verifies, 401 when not. A valid probe claims nothing.
+ */
+async function probeDelivery(input, options) {
+    if (isUnsignedProbe(input.headers))
+        return probeResult(200);
+    const id = readHeader(input.headers, WEBHOOK_ID_HEADER);
+    const timestamp = readHeader(input.headers, WEBHOOK_TIMESTAMP_HEADER);
+    const signatureHeader = readHeader(input.headers, WEBHOOK_SIGNATURE_HEADER);
+    if (!id || !timestamp || !signatureHeader) {
+        return probeResult(401, "missing signature headers");
+    }
+    const verified = await verifyAgainstResolvedSecret(options, "", { id, timestamp, signatureHeader }, null);
+    return verified.ok ? probeResult(200) : probeResult(401, verified.error);
+}
 /**
  * Layer 1: handle one signed Queek topic delivery from plain data — no
  * `Request`, no framework. Same options, same behaviour, same
@@ -67,6 +111,11 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
  * 200 for a handled, repeated or unhandled-topic delivery; 500 when your
  * handler throws (the claim is released so Queek's retry can land).
  *
+ * `method` `GET` or `HEAD` is the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no handler; with a signature (over the
+ * empty body) 200 when it verifies against an installation secret and 401
+ * when not.
+ *
  * @example
  * const result = await handleWebhookDelivery(
  *   { rawBody, headers },
@@ -82,7 +131,8 @@ async function defaultResolveSecret(store, rawBody, headers, envelope) {
  * // reply with result.status and result.body
  */
 export async function handleWebhookDelivery(input, options) {
-    const maxSkew = options.maxSkewSeconds ?? MAX_TIMESTAMP_SKEW_SECONDS;
+    if (isProbeMethod(input.method))
+        return probeDelivery(input, options);
     const rawBody = decodeBody(input.rawBody);
     const id = readHeader(input.headers, WEBHOOK_ID_HEADER);
     const timestamp = readHeader(input.headers, WEBHOOK_TIMESTAMP_HEADER);
@@ -103,24 +153,10 @@ export async function handleWebhookDelivery(input, options) {
         return { status: 400, body: { ok: false, error: "invalid_envelope" } };
     }
     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 { status: 401, body: { ok: false, error: "unknown_installation" } };
-    }
-    // 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);
-    if (!isFreshTimestamp(timestamp, now, maxSkew)) {
-        return { status: 401, body: { ok: false, error: "stale timestamp" } };
-    }
-    // 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 { status: 401, body: { ok: false, error: "signature mismatch" } };
-    }
+    const verified = await verifyAgainstResolvedSecret(options, rawBody, headers, envelope);
+    if (!verified.ok)
+        return { status: 401, body: { ok: false, error: verified.error } };
+    const resolution = verified.resolution;
     const installation = await options.store.getInstallation(resolution.installationId);
     if (!installation) {
         return { status: 401, body: { ok: false, error: "unknown_installation" } };
@@ -151,14 +187,17 @@ export async function handleWebhookDelivery(input, options) {
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads
  * `await request.arrayBuffer()` + headers, calls the core, builds the
- * `Response`. Only `POST` is served; anything else answers 405.
+ * `Response`. `POST` is a delivery; `GET` and `HEAD` are the review probe
+ * (see `handleWebhookDelivery`); anything else answers 405.
  */
 export async function handleWebhookRequest(request, options) {
-    if (request.method.toUpperCase() !== "POST") {
+    const method = request.method.toUpperCase();
+    if (method !== "POST" && !isProbeMethod(method)) {
         return toResponse({ status: 405, body: { ok: false, error: "method_not_allowed" } });
     }
     return toResponse(await handleWebhookDelivery({
         rawBody: new Uint8Array(await request.arrayBuffer()),
         headers: request.headers,
-    }, options));
+        method,
+    }, options), method);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/app-sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "license": "MIT",
   "author": "Queekx Technology LTD",