Webhook integration & verification

package webhook // rename to suit your service

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"strconv"
	"strings"
	"time"

	"github.com/decred/dcrd/dcrec/secp256k1/v4"
	"github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa"
)

// ErrTestDelivery means the delivery is authentic but came from a test action.
// Log it, never act on it.
var ErrTestDelivery = errors.New("test delivery: verified, not actioned")

type payload struct {
	Test             bool   `json:"test"`
	CanonicalString  string `json:"canonical_string"`
	CanonicalMessage struct {
		RequestID  string `json:"request_id"`
		ActionName string `json:"action_name"`
		Threshold  int    `json:"threshold"`
		ExpiresAt  int64  `json:"expires_at"`
	} `json:"canonical_message"`
	Signatures []struct {
		Pubkey    string `json:"pubkey"`
		Signature string `json:"signature"`
	} `json:"signatures"`
}

// Verify returns nil if the webhook is authentic, fresh, and carries enough
// valid approvals to act on.
//
//	rawBody    the request body exactly as received, unparsed
//	xSig/xTs   the X-Signature and X-Timestamp headers
//	secret     the action's HMAC secret, from its page in TeamSigner
//	whitelist  your team's current member public keys, lowercase 0x-hex
func Verify(rawBody []byte, xSig, xTs, secret string, whitelist map[string]bool) error {
	// 1. Envelope: HMAC-SHA256(secret, timestamp + "." + rawBody), over the raw
	//    bytes and before parsing — never act on a body you haven't authenticated.
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(xTs + "." + string(rawBody)))
	want := hex.EncodeToString(mac.Sum(nil))
	if !hmac.Equal([]byte(want), []byte(xSig)) {
		return errors.New("bad HMAC signature")
	}

	// 2. Freshness: a captured delivery must not be replayable tomorrow.
	ts, err := strconv.ParseInt(xTs, 10, 64)
	if err != nil {
		return errors.New("malformed X-Timestamp")
	}
	if skew := time.Since(time.Unix(ts, 0)); skew > 5*time.Minute || skew < -5*time.Minute {
		return fmt.Errorf("stale X-Timestamp (off by %s)", skew.Round(time.Second))
	}

	var p payload
	if err := json.Unmarshal(rawBody, &p); err != nil {
		return err
	}

	// 3. A test action's delivery is real, but must never trigger the real thing.
	if p.Test {
		return ErrTestDelivery
	}
	if time.Now().Unix() > p.CanonicalMessage.ExpiresAt {
		return errors.New("request expired")
	}

	// 4. The signed digest is SHA-256 of canonical_string exactly as delivered.
	//    Do not rebuild it from canonical_message: any serialization difference
	//    turns every signature into a false rejection.
	digest := sha256.Sum256([]byte(p.CanonicalString))

	// 5. Count DISTINCT whitelisted keys with a valid signature. Two copies of
	//    one member's approval is still one approval.
	seen := map[string]bool{}
	for _, s := range p.Signatures {
		k := strings.ToLower(s.Pubkey)
		if !whitelist[k] || seen[k] {
			continue
		}
		if verifySig(k, s.Signature, digest[:]) {
			seen[k] = true
		}
	}

	// 6. Threshold comes from the signed message, not from your own config:
	//    it is the number the members actually approved under.
	if len(seen) < p.CanonicalMessage.Threshold {
		return fmt.Errorf("only %d of %d required approvals", len(seen), p.CanonicalMessage.Threshold)
	}
	return nil // authentic, fresh, approved — now dedupe on X-Idempotency-Key and act.
}

func verifySig(pubHex, sigHex string, digest []byte) bool {
	pb, err := hex.DecodeString(strings.TrimPrefix(pubHex, "0x"))
	if err != nil {
		return false
	}
	sb, err := hex.DecodeString(strings.TrimPrefix(strings.ToLower(sigHex), "0x"))
	if err != nil || len(sb) != 64 {
		return false
	}
	pk, err := secp256k1.ParsePubKey(pb)
	if err != nil {
		return false
	}
	var r, s secp256k1.ModNScalar
	if r.SetByteSlice(sb[:32]) || s.SetByteSlice(sb[32:]) {
		return false // overflows the curve order
	}
	return ecdsa.NewSignature(&r, &s).Verify(digest, pk)
}

import { createHash, createHmac, timingSafeEqual } from "node:crypto";
import { secp256k1 } from "@noble/curves/secp256k1";

const bytes = (h: string) => Buffer.from(h.replace(/^0x/, ""), "hex");

export const TEST_DELIVERY = "test delivery: verified, not actioned";

/**
 * Returns null if the webhook is authentic, fresh, and carries enough valid
 * approvals to act on — otherwise a reason string.
 *
 *   rawBody    the request body exactly as received, unparsed
 *   xSig/xTs   the X-Signature and X-Timestamp headers
 *   secret     the action's HMAC secret, from its page in TeamSigner
 *   whitelist  your team's current member public keys, lowercase 0x-hex
 */
export function verify(
  rawBody: string, xSig: string, xTs: string,
  secret: string, whitelist: Set<string>,
): string | null {
  // 1. Envelope: HMAC-SHA256(secret, timestamp + "." + rawBody), over the raw
  //    bytes and before parsing — never act on a body you haven't authenticated.
  const want = createHmac("sha256", secret).update(xTs + "." + rawBody).digest("hex");
  if (want.length !== xSig.length ||
      !timingSafeEqual(Buffer.from(want), Buffer.from(xSig))) {
    return "bad HMAC signature";
  }

  // 2. Freshness: a captured delivery must not be replayable tomorrow.
  if (!/^\d+$/.test(xTs)) return "malformed X-Timestamp";
  const skew = Math.abs(Math.floor(Date.now() / 1000) - Number(xTs));
  if (skew > 300) return "stale X-Timestamp (off by " + skew + "s)";

  let p: any;
  try { p = JSON.parse(rawBody); } catch { return "body is not valid JSON"; }

  // 3. A test action's delivery is real, but must never trigger the real thing.
  if (p.test === true) return TEST_DELIVERY;
  if (Math.floor(Date.now() / 1000) > p.canonical_message.expires_at) {
    return "request expired";
  }

  // 4. The signed digest is SHA-256 of canonical_string exactly as delivered.
  //    Do not rebuild it from canonical_message: any serialization difference
  //    turns every signature into a false rejection.
  const digest = createHash("sha256").update(p.canonical_string).digest();

  // 5. Count DISTINCT whitelisted keys with a valid signature. Two copies of
  //    one member's approval is still one approval.
  const seen = new Set<string>();
  for (const s of p.signatures ?? []) {
    const k = String(s.pubkey).toLowerCase();
    if (!whitelist.has(k) || seen.has(k)) continue;
    try {
      if (secp256k1.verify(bytes(s.signature), digest, bytes(k))) seen.add(k);
    } catch { /* malformed hex is not an approval */ }
  }

  // 6. Threshold comes from the signed message, not from your own config:
  //    it is the number the members actually approved under.
  const threshold = p.canonical_message.threshold;
  if (seen.size < threshold) {
    return "only " + seen.size + " of " + threshold + " required approvals";
  }
  return null; // authentic, fresh, approved — dedupe on X-Idempotency-Key and act.
}

import hashlib, hmac, json, re, time
from ecdsa import VerifyingKey, SECP256k1, BadSignatureError
from ecdsa.util import sigdecode_string

TEST_DELIVERY = "test delivery: verified, not actioned"


def verify(raw_body: bytes, x_sig: str, x_ts: str, secret: str, whitelist: set):
    """Return None if the webhook is authentic, fresh, and carries enough valid
    approvals to act on — otherwise a reason string.

    raw_body   the request body exactly as received, unparsed
    x_sig/x_ts the X-Signature and X-Timestamp headers
    secret     the action's HMAC secret, from its page in TeamSigner
    whitelist  your team's current member public keys, lowercase 0x-hex
    """
    # 1. Envelope: HMAC-SHA256(secret, timestamp + "." + raw_body), over the raw
    #    bytes and before parsing — never act on a body you haven't authenticated.
    want = hmac.new(secret.encode(), (x_ts + ".").encode() + raw_body,
                    hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, x_sig):
        return "bad HMAC signature"

    # 2. Freshness: a captured delivery must not be replayable tomorrow.
    if not re.fullmatch(r"\d+", x_ts or ""):
        return "malformed X-Timestamp"
    skew = abs(int(time.time()) - int(x_ts))
    if skew > 300:
        return f"stale X-Timestamp (off by {skew}s)"

    try:
        p = json.loads(raw_body)
    except ValueError:
        return "body is not valid JSON"

    # 3. A test action's delivery is real, but must never trigger the real thing.
    if p.get("test") is True:
        return TEST_DELIVERY
    if time.time() > p["canonical_message"]["expires_at"]:
        return "request expired"

    # 4. The signed digest is SHA-256 of canonical_string exactly as delivered.
    #    Do not rebuild it from canonical_message: any serialization difference
    #    turns every signature into a false rejection.
    digest = hashlib.sha256(p["canonical_string"].encode()).digest()

    # 5. Count DISTINCT whitelisted keys with a valid signature. Two copies of
    #    one member's approval is still one approval.
    seen = set()
    for s in p.get("signatures", []):
        k = s["pubkey"].lower()
        if k not in whitelist or k in seen:
            continue
        try:
            vk = VerifyingKey.from_string(bytes.fromhex(k[2:]), curve=SECP256k1)
            vk.verify_digest(bytes.fromhex(s["signature"][2:]), digest,
                             sigdecode=sigdecode_string)
            seen.add(k)
        except (BadSignatureError, ValueError):
            pass  # malformed hex or a bad signature is not an approval

    # 6. Threshold comes from the signed message, not from your own config:
    #    it is the number the members actually approved under.
    threshold = p["canonical_message"]["threshold"]
    if len(seen) < threshold:
        return f"only {len(seen)} of {threshold} required approvals"

    # authentic, fresh, approved — dedupe on X-Idempotency-Key and act.
    return None

use hmac::{Hmac, Mac};
use k256::ecdsa::{signature::hazmat::PrehashVerifier, Signature, VerifyingKey};
use sha2::{Digest, Sha256};
use std::collections::HashSet;
use std::time::{SystemTime, UNIX_EPOCH};
use subtle::ConstantTimeEq;

pub const TEST_DELIVERY: &str = "test delivery: verified, not actioned";

/// Returns Ok(()) if the webhook is authentic, fresh, and carries enough valid
/// approvals to act on — otherwise a reason.
///
///   raw_body    the request body exactly as received, unparsed
///   x_sig/x_ts  the X-Signature and X-Timestamp headers
///   secret      the action's HMAC secret, from its page in TeamSigner
///   whitelist   your team's current member public keys, lowercase 0x-hex
pub fn verify(raw_body: &[u8], x_sig: &str, x_ts: &str,
              secret: &str, whitelist: &HashSet<String>) -> Result<(), String> {
    // 1. Envelope: HMAC-SHA256(secret, timestamp + "." + raw_body), over the raw
    //    bytes and before parsing — never act on a body you haven't authenticated.
    let mut mac = <Hmac<Sha256>>::new_from_slice(secret.as_bytes())
        .map_err(|e| e.to_string())?;
    mac.update(x_ts.as_bytes());
    mac.update(b".");
    mac.update(raw_body);
    let want = hex::encode(mac.finalize().into_bytes());
    if want.as_bytes().ct_eq(x_sig.as_bytes()).unwrap_u8() != 1 {
        return Err("bad HMAC signature".into());
    }

    // 2. Freshness: a captured delivery must not be replayable tomorrow.
    let ts: i64 = x_ts.parse().map_err(|_| "malformed X-Timestamp".to_string())?;
    let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs() as i64;
    let skew = (now - ts).abs();
    if skew > 300 {
        return Err(format!("stale X-Timestamp (off by {skew}s)"));
    }

    let p: serde_json::Value =
        serde_json::from_slice(raw_body).map_err(|_| "body is not valid JSON".to_string())?;

    // 3. A test action's delivery is real, but must never trigger the real thing.
    if p["test"] == serde_json::Value::Bool(true) {
        return Err(TEST_DELIVERY.into());
    }
    let expires_at = p["canonical_message"]["expires_at"].as_i64().unwrap_or(0);
    if now > expires_at {
        return Err("request expired".into());
    }

    // 4. The signed digest is SHA-256 of canonical_string exactly as delivered.
    //    Do not rebuild it from canonical_message: any serialization difference
    //    turns every signature into a false rejection.
    let cs = p["canonical_string"].as_str().ok_or("missing canonical_string")?;
    let digest = Sha256::digest(cs.as_bytes());

    // 5. Count DISTINCT whitelisted keys with a valid signature. Two copies of
    //    one member's approval is still one approval.
    let empty = vec![];
    let mut seen: HashSet<String> = HashSet::new();
    for s in p["signatures"].as_array().unwrap_or(&empty) {
        let (pk, sg) = match (s["pubkey"].as_str(), s["signature"].as_str()) {
            (Some(a), Some(b)) => (a.to_lowercase(), b.to_lowercase()),
            _ => continue,
        };
        if !whitelist.contains(&pk) || seen.contains(&pk) {
            continue;
        }
        let (pk_raw, sg_raw) = (pk.trim_start_matches("0x"), sg.trim_start_matches("0x"));
        if let (Ok(pb), Ok(sb)) = (hex::decode(pk_raw), hex::decode(sg_raw)) {
            if let (Ok(vk), Ok(sig)) =
                (VerifyingKey::from_sec1_bytes(&pb), Signature::from_slice(&sb))
            {
                if vk.verify_prehash(&digest, &sig).is_ok() {
                    seen.insert(pk);
                }
            }
        }
    }

    // 6. Threshold comes from the signed message, not from your own config:
    //    it is the number the members actually approved under.
    let threshold = p["canonical_message"]["threshold"].as_u64().unwrap_or(u64::MAX) as usize;
    if seen.len() < threshold {
        return Err(format!("only {} of {} required approvals", seen.len(), threshold));
    }

    // authentic, fresh, approved — dedupe on X-Idempotency-Key and act.
    Ok(())
}