@zaisma/game-server 0.0.1 → 1.0.0

package/src/webhooks.js

@@ -0,0 +1,102 @@
+/**
+ * Webhooks to the game server: a webhook can send Zaisma's events about a game to that game's own
+ * game server, whose onWebhook(event, server) turns them into whatever it likes, like a Discord post
+ * or a GitHub issue made with the developer's own tokens from server.secrets (docs/DECISIONS.md,
+ * "Webhooks to the game server"). Zaisma runs it in the game's own object (apps/rooms/src/game-server.ts)
+ * for a webhook whose destination_kind is game_server. On the developer's own server the Node runner
+ * (@zaisma/game-server/node) takes the same event as a signed POST at /v1/webhooks, checks it here with the
+ * webhook's whsec_ signing secret (Standard Webhooks, standardwebhooks.com) and runs the same
+ * onWebhook, so the code moves unchanged.
+ */
+export const WEBHOOK_LIMITS = {
+    /** How long onWebhook may take, awaiting the database and outside calls included, before the try fails and waits for the next. */
+    answerTimeoutSec: 10,
+    /** The most of a webhook's POST verifyWebhook and the Node runner take, in bytes: well above any event Zaisma sends. */
+    maximumEventSizeBytes: 16 * 1024 * 1024,
+    /** How far a POST's webhook-timestamp may be from the server's clock, so an old one can't be sent again. */
+    timestampToleranceDurationSec: 300,
+};
+const webhookError = (code, message, fix) => ({ error: { code, message, fix } });
+/**
+ * Run a game server's onWebhook for one event, with a time limit. An error says why the try failed,
+ * for the game server's errors: it has no onWebhook, it threw, or it took longer than
+ * WEBHOOK_LIMITS.answerTimeoutSec.
+ */
+export async function runWebhook(handler, event, server) {
+    if (typeof handler.onWebhook !== "function")
+        return webhookError("no_webhook_handler", "This game server has no onWebhook.", "Add onWebhook(event, server) to the game server.");
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(() => handler.onWebhook(event, server)),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`onWebhook didn't finish within ${WEBHOOK_LIMITS.answerTimeoutSec} seconds`)), WEBHOOK_LIMITS.answerTimeoutSec * 1000);
+            }),
+        ]);
+        return { isDone: true };
+    }
+    catch (error) {
+        return webhookError("game_server_error", String((error instanceof Error && error.stack) || error), "Fix onWebhook: Zaisma tries the event again later.");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const bytesOfBase64 = (text) => Uint8Array.from(atob(text), (character) => character.charCodeAt(0));
+/**
+ * Check a webhook POST the Standard Webhooks way: its webhook-signature holds a "v1,<base64>" HMAC-SHA256
+ * of "<webhook-id>.<webhook-timestamp>.<body>" keyed by the signing secret's bytes, and its timestamp is
+ * within WEBHOOK_LIMITS.timestampToleranceDurationSec of now. Answers the event, or an error saying why
+ * it isn't one to trust.
+ */
+export async function verifyWebhook(signingSecret, headers, body, nowMs = Date.now()) {
+    const { webhookId, webhookTimestamp, webhookSignature } = headers;
+    if (!webhookId || !webhookTimestamp || !webhookSignature)
+        return webhookError("missing_headers", "It has no webhook-id, webhook-timestamp or webhook-signature header.", "Only take POSTs Zaisma's webhooks send, with their headers as they came.");
+    if (new TextEncoder().encode(body).length > WEBHOOK_LIMITS.maximumEventSizeBytes) {
+        return webhookError("too_large", `Its body is over ${WEBHOOK_LIMITS.maximumEventSizeBytes} bytes, more than any event Zaisma sends.`, "Only take POSTs Zaisma's webhooks send.");
+    }
+    const timestampSec = Number(webhookTimestamp);
+    if (!Number.isInteger(timestampSec) || Math.abs(nowMs / 1000 - timestampSec) > WEBHOOK_LIMITS.timestampToleranceDurationSec) {
+        return webhookError("old_timestamp", `Its webhook-timestamp isn't within ${WEBHOOK_LIMITS.timestampToleranceDurationSec} seconds of this server's clock.`, "Check this server's clock; an old event sent again is refused on purpose.");
+    }
+    let key;
+    try {
+        key = await crypto.subtle.importKey("raw", bytesOfBase64(signingSecret.replace(/^whsec_/, "")), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    }
+    catch {
+        return webhookError("bad_signing_secret", "The signing secret isn't a whsec_ secret from create_webhook.", "Use the webhook's signing_secret, as create_webhook or replace_signing_secret answered it.");
+    }
+    const signed = new TextEncoder().encode(`${webhookId}.${webhookTimestamp}.${body}`);
+    let isSigned = false;
+    // Several signatures, space-separated, while a secret is replaced; any one that matches will do.
+    for (const part of webhookSignature.split(" ")) {
+        const [version, signature] = part.split(",");
+        if (version !== "v1" || !signature)
+            continue;
+        let signatureBytes;
+        try {
+            signatureBytes = bytesOfBase64(signature);
+        }
+        catch {
+            continue;
+        }
+        // crypto.subtle.verify compares in constant time.
+        if (await crypto.subtle.verify("HMAC", key, signatureBytes, signed)) {
+            isSigned = true;
+            break;
+        }
+    }
+    if (!isSigned)
+        return webhookError("bad_signature", "Its webhook-signature doesn't match the signing secret.", "Check the body as it came, byte for byte, with the webhook's current signing_secret.");
+    let event;
+    try {
+        event = JSON.parse(body);
+    }
+    catch {
+        return webhookError("not_an_event", "Its body isn't JSON.", "Only take POSTs Zaisma's webhooks send.");
+    }
+    if (!event || typeof event !== "object" || Array.isArray(event) || event.id !== webhookId)
+        return webhookError("not_an_event", "Its body isn't a webhook event with the webhook-id's id.", "Only take POSTs Zaisma's webhooks send.");
+    return { event: event };
+}