feat(federation): add verifyPeerSignature with dual-secret grace period (FED-011)

packages/server/src/utils/federationAuth.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { verifyPeerSignature, signRequest, ROTATION_GRACE_PERIOD_MS } from './federationAuth.js';
+
+describe('verifyPeerSignature', () => {
+  const primarySecret = 'a'.repeat(64);
+  const pendingSecret = 'b'.repeat(64);
+  const body = '{"test":"data"}';
+  const nonce = 'test-nonce-uuid';
+
+  function makePeer(overrides: Partial<{
+    hmacSecret: string;
+    pendingHmacSecret: string | null;
+    secretRotationAt: number | null;
+  }> = {}) {
+    return {
+      hmacSecret: primarySecret,
+      pendingHmacSecret: null,
+      secretRotationAt: null,
+      ...overrides,
+    };
+  }
+
+  it('accepts signature signed with primary secret', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, primarySecret, timestamp, nonce);
+    expect(verifyPeerSignature(body, sig, timestamp, nonce, makePeer())).toBe(true);
+  });
+
+  it('rejects invalid signature with no pending secret', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, 'wrong-secret', timestamp, nonce);
+    expect(verifyPeerSignature(body, sig, timestamp, nonce, makePeer())).toBe(false);
+  });
+
+  it('accepts signature signed with pending secret during grace period', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, pendingSecret, timestamp, nonce);
+    const peer = makePeer({
+      pendingHmacSecret: pendingSecret,
+      secretRotationAt: Date.now() - 1000,
+    });
+    expect(verifyPeerSignature(body, sig, timestamp, nonce, peer)).toBe(true);
+  });
+
+  it('rejects pending secret after grace period expires', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, pendingSecret, timestamp, nonce);
+    const peer = makePeer({
+      pendingHmacSecret: pendingSecret,
+      secretRotationAt: Date.now() - ROTATION_GRACE_PERIOD_MS - 1000,
+    });
+    expect(verifyPeerSignature(body, sig, timestamp, nonce, peer)).toBe(false);
+  });
+
+  it('still accepts primary secret during grace period', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, primarySecret, timestamp, nonce);
+    const peer = makePeer({
+      pendingHmacSecret: pendingSecret,
+      secretRotationAt: Date.now() - 1000,
+    });
+    expect(verifyPeerSignature(body, sig, timestamp, nonce, peer)).toBe(true);
+  });
+
+  it('handles null nonce (legacy peers)', () => {
+    const timestamp = Date.now();
+    const sig = signRequest(body, primarySecret, timestamp, null);
+    expect(verifyPeerSignature(body, sig, timestamp, null, makePeer())).toBe(true);
+  });
+});

packages/server/src/utils/federationAuth.ts

@@ -60,6 +60,40 @@ export function verifySignature(
   return timingSafeEqual(expectedBuf, actualBuf);
 }
 
+/** Grace period during which both old and new secrets are accepted for verification. */
+export const ROTATION_GRACE_PERIOD_MS = 15 * 60 * 1000; // 15 minutes
+
+/**
+ * Verify a federation request signature against a peer's secrets.
+ *
+ * During secret rotation (when pendingHmacSecret is set and within the grace period),
+ * accepts signatures made with either the primary or pending secret.
+ */
+export function verifyPeerSignature(
+  body: string,
+  signature: string,
+  timestamp: number,
+  nonce: string | null,
+  peer: {
+    hmacSecret: string;
+    pendingHmacSecret: string | null;
+    secretRotationAt: number | null;
+  },
+): boolean {
+  // Try primary secret first
+  if (verifySignature(body, signature, peer.hmacSecret, timestamp, nonce)) return true;
+
+  // During grace period, try pending secret
+  if (peer.pendingHmacSecret && peer.secretRotationAt) {
+    const elapsed = Date.now() - peer.secretRotationAt;
+    if (elapsed <= ROTATION_GRACE_PERIOD_MS) {
+      return verifySignature(body, signature, peer.pendingHmacSecret, timestamp, nonce);
+    }
+  }
+
+  return false;
+}
+
 /**
  * Build the HTTP headers required for an outbound federation request.
  *