Webhook signatures

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.MAAT_WEBHOOK_SECRET;

// express.raw, not express.json — verification needs the raw bytes.
app.post('/maat', express.raw({ type: 'application/json' }), (req, res) => {
    const timestamp = req.header('X-Signature-Timestamp') ?? '';

    // 1. Reject a missing, unreadable or stale timestamp before comparing
    //    anything. Number('abc') is NaN and every comparison against NaN is
    //    false, so the window check has to be written as a test that NaN FAILS.
    const sentAt = Number(timestamp);
    if (!Number.isFinite(sentAt) || !(Math.abs(Date.now() / 1000 - sentAt) <= 300)) {
        return res.status(401).end();
    }

    // 2. HMAC over "v1:" + timestamp + ":" + the raw body.
    const expected = createHmac('sha256', secret)
        .update(`v1:${timestamp}:`)
        .update(req.body) // a Buffer — the bytes as delivered
        .digest('hex');

    // 3. Constant-time compare — against either signature during a rotation.
    const matches = (candidate) =>
        typeof candidate === 'string' &&
        candidate.length === expected.length &&
        timingSafeEqual(Buffer.from(candidate), Buffer.from(expected));

    const verified =
        matches(req.header('X-Signature')) || matches(req.header('X-Signature-Previous'));
    if (!verified) return res.status(401).end();

    // 4. Only now parse.
    const event = JSON.parse(req.body.toString('utf8'));

    // 5. event_id is stable across our retries — use it as your idempotency key.
    //    A duplicate you have already processed should be answered 200 and ignored.

    if (event.event_type === 'endpoint.challenge') {
        return res.status(200).json({ challenge: event.data.challenge });
    }

    res.status(200).end();
});

app.listen(8443);

import hashlib
import hmac
import os
import time

from flask import Flask, jsonify, request

app = Flask(__name__)
SECRET = os.environ["MAAT_WEBHOOK_SECRET"].encode()


@app.post("/maat")
def maat_webhook():
    raw_body = request.get_data()  # the raw bytes, before any JSON parsing
    timestamp = request.headers.get("X-Signature-Timestamp", "")

    # 1. Reject a missing, unreadable or stale timestamp before comparing
    #    anything. int("abc") RAISES, which would answer 500 — a malformed
    #    header is a refusal, not a fault of yours.
    try:
        sent_at = int(timestamp)
    except ValueError:
        return "", 401
    if abs(time.time() - sent_at) > 300:
        return "", 401

    # 2. HMAC over b"v1:" + timestamp + b":" + the raw body.
    expected = hmac.new(
        SECRET, b"v1:" + timestamp.encode() + b":" + raw_body, hashlib.sha256
    ).hexdigest()

    # 3. Constant-time compare — against either signature during a rotation.
    #    compare_digest RAISES on a str with a non-ASCII character, and a header
    #    value can carry one (WSGI decodes headers as latin-1), so a forged
    #    signature must not be able to answer 500. Ours is always lowercase hex.
    candidates = [
        request.headers.get("X-Signature", ""),
        request.headers.get("X-Signature-Previous", ""),
    ]
    if not any(
        sig and sig.isascii() and hmac.compare_digest(sig, expected)
        for sig in candidates
    ):
        return "", 401

    # 4. Only now parse.
    event = request.get_json(force=True)

    # 5. event_id is stable across retries — use it as your idempotency key.

    if event["event_type"] == "endpoint.challenge":
        return jsonify(challenge=event["data"]["challenge"])

    return "", 200

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io"
    "log"
    "math"
    "net/http"
    "os"
    "strconv"
    "time"
)

var secret = []byte(os.Getenv("MAAT_WEBHOOK_SECRET"))

func expectedSignature(timestamp string, rawBody []byte) string {
    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte("v1:" + timestamp + ":"))
    mac.Write(rawBody)
    return hex.EncodeToString(mac.Sum(nil))
}

func matches(candidate, expected string) bool {
    // ConstantTimeCompare is length-safe here because both are hex of the same
    // digest; hmac.Equal is constant time for equal lengths and returns false
    // otherwise, which is what we want.
    return hmac.Equal([]byte(candidate), []byte(expected))
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 1. The raw bytes, before any JSON decoding.
    rawBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
    if err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    // 2. A missing, unreadable or stale timestamp is a 401, never a panic.
    timestamp := r.Header.Get("X-Signature-Timestamp")
    sentAt, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil || math.Abs(float64(time.Now().Unix()-sentAt)) > 300 {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    // 3. Constant-time compare — against either signature during a rotation.
    expected := expectedSignature(timestamp, rawBody)
    if !matches(r.Header.Get("X-Signature"), expected) &&
        !matches(r.Header.Get("X-Signature-Previous"), expected) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    // 4. Only now parse.
    var event struct {
        EventID   string          `json:"event_id"`
        EventType string          `json:"event_type"`
        Data      json.RawMessage `json:"data"`
    }
    if err := json.Unmarshal(rawBody, &event); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    // 5. event_id is stable across retries — use it as your idempotency key.

    if event.EventType == "endpoint.challenge" {
        var challenge struct {
            Challenge string `json:"challenge"`
        }
        _ = json.Unmarshal(event.Data, &challenge)
        w.Header().Set("Content-Type", "application/json")
        _ = json.NewEncoder(w).Encode(challenge)
        return
    }

    w.WriteHeader(http.StatusOK)
}

func main() {
    http.HandleFunc("/maat", handler)
    log.Fatal(http.ListenAndServe(":8443", nil))
}