Rotating a secret

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300; // 5 minutes

/**
 * @param rawBody the EXACT bytes we sent, as a string or Buffer — never a
 *                re-serialised object.
 */
export function verifySalafSignature(rawBody, header, secret) {
  if (!header) return false;

  let timestamp = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=");
    if (key?.trim() === "t") timestamp = Number(value?.trim());
    if (key?.trim() === "v1") signatures.push(value?.trim());
  }
  if (!Number.isFinite(timestamp) || signatures.length === 0) return false;

  // Reject anything captured and replayed later. The timestamp is INSIDE the
  // signed string, so an attacker cannot simply put a fresh one in the header.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  // During a secret rotation there are TWO v1= values; either may match.
  return signatures.some((candidate) => timingSafeEqual(expected, candidate));
}

// Never use === on a signature: the early exit leaks, through timing, how
// many leading characters an attacker guessed right.
function timingSafeEqual(a, b) {
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300  # 5 minutes


def verify_salaf_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """raw_body is the exact request body — bytes, not a parsed dict."""
    if not header:
        return False

    timestamp = None
    signatures = []
    for part in header.split(","):
        key, _, value = part.partition("=")
        if key.strip() == "t":
            timestamp = value.strip()
        elif key.strip() == "v1":
            signatures.append(value.strip())

    if timestamp is None or not signatures:
        return False

    # Replay window. The timestamp is signed, so it cannot be swapped.
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed_payload = timestamp.encode() + b"." + raw_body
    expected = hmac.new(
        secret.encode(), signed_payload, hashlib.sha256
    ).hexdigest()

    # compare_digest, never ==: a plain comparison leaks the match length.
    # Two v1= values appear during a rotation; either may match.
    return any(hmac.compare_digest(expected, s) for s in signatures)

<?php

const SALAF_TOLERANCE_SECONDS = 300; // 5 minutes

/** $rawBody must be the exact request body, not a re-encoded array. */
function verify_salaf_signature(string $rawBody, ?string $header, string $secret): bool
{
    if ($header === null || $header === '') {
        return false;
    }

    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', $part, 2), 2, null);
        $key = trim((string) $key);
        if ($key === 't') {
            $timestamp = trim((string) $value);
        } elseif ($key === 'v1') {
            $signatures[] = trim((string) $value);
        }
    }

    if ($timestamp === null || $signatures === []) {
        return false;
    }

    // Replay window — the timestamp is part of what was signed.
    if (abs(time() - (int) $timestamp) > SALAF_TOLERANCE_SECONDS) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    // hash_equals, never ===. Two signatures ride along during a rotation.
    foreach ($signatures as $candidate) {
        if (hash_equals($expected, $candidate)) {
            return true;
        }
    }

    return false;
}