feat(federation): signed /api/federation/epoch endpoint + caller

packages/server/src/routes/federation.ts

@@ -2317,6 +2317,55 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
     },
   );
 
+  // ─── POST /api/federation/epoch ────────────────────────────────────────────
+  // Server-to-server: return this instance's persistent epoch (instance_id).
+  // Authenticated via HMAC-SHA256 signature on the REQUEST (only a peer holding
+  // the shared secret may call it), and the RESPONSE body is HMAC-SIGNED with
+  // the same secret so the caller can verify the epoch it newly trusts before
+  // writing it as the peer's baseline (design §3.2 / §9). The value itself
+  // (instanceId) is already public via /instance/info; signing is for
+  // baseline-integrity, not confidentiality.
+  app.post(
+    '/api/federation/epoch',
+    { bodyLimit: 4 * 1024 },
+    async (request, reply) => {
+      const db = getDb();
+
+      // 1. Parse and require federation headers (mirror relay/users-lookup).
+      const fedHeaders = parseFederationHeaders(request.headers as Record<string, string | string[] | undefined>);
+      if (!fedHeaders) {
+        return reply.code(400).send({ error: 'Missing or malformed federation headers', statusCode: 400 });
+      }
+
+      // 2. Resolve the peer by origin. Reject unknown or revoked peers.
+      const peer = db
+        .select()
+        .from(schema.federationPeers)
+        .where(eq(schema.federationPeers.origin, fedHeaders.origin))
+        .get();
+      if (!peer || peer.status === 'revoked') {
+        return reply.code(403).send({ error: 'Not peered', statusCode: 403 });
+      }
+
+      // 3. Verify the inbound request signature (honours rotation grace).
+      const bodyString = JSON.stringify(request.body ?? {});
+      if (!verifyPeerSignature(bodyString, fedHeaders.signature, fedHeaders.timestamp, fedHeaders.nonce, peer)) {
+        return reply.code(401).send({ error: 'Invalid signature', statusCode: 401 });
+      }
+
+      // 4. Sign the response body with the peer's shared secret and return it.
+      const responseBody = JSON.stringify({ instanceId: getInstanceId() });
+      const sigHeaders = buildFederationHeaders(responseBody, peer.hmacSecret, getOurOrigin());
+      reply.headers({
+        'X-Federation-Signature': sigHeaders['X-Federation-Signature'],
+        'X-Federation-Timestamp': sigHeaders['X-Federation-Timestamp'],
+        'X-Federation-Nonce': sigHeaders['X-Federation-Nonce'],
+        'Content-Type': 'application/json',
+      });
+      return reply.code(200).send(responseBody);
+    },
+  );
+
   // ─── POST /api/federation/users/lookup ─────────────────────────────────────
   // Server-to-server: resolve a username on this instance to its canonical
   // (homeUserId, profile snapshot). Used by another instance to construct a

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

@@ -1,10 +1,15 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
 import Database from 'better-sqlite3';
 import { drizzle } from 'drizzle-orm/better-sqlite3';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as schema from '../db/schema.js';
+import { setWorkerId } from './snowflake.js';
+import { buildFederationHeaders, verifySignature } from './federationAuth.js';
+
+setWorkerId(1);
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 let sqlite: Database.Database;
@@ -16,6 +21,33 @@ vi.mock('../db/index.js', () => ({
   schema,
 }));
 
+vi.mock('../utils/auth.js', () => ({
+  authenticate: async (req: { userId?: string }) => {
+    req.userId = 'admin-user';
+  },
+  requireAdmin: async () => {
+    // epoch endpoint is HMAC-authenticated, not JWT
+  },
+}));
+
+vi.mock('../ws/handler.js', () => ({
+  connectionManager: {
+    sendToAdmins: vi.fn(),
+    getAllOnlineUserIds: () => [],
+    sendToUser: vi.fn(),
+    sendToDmMembers: vi.fn(),
+  },
+}));
+
+vi.mock('../utils/federationPeerActivation.js', () => ({
+  onPeerActivated: vi.fn(async () => undefined),
+  onPeerDeactivated: vi.fn(async () => undefined),
+}));
+
+const LOCAL_EPOCH = 'local-epoch-abcd';
+const PEER_ORIGIN = 'https://remote.example';
+const PEER_SECRET = 'peer-shared-secret-0123456789abcdef';
+
 function applyMigrations(db: Database.Database): void {
   const dir = path.resolve(__dirname, '../../drizzle');
   for (const f of fs.readdirSync(dir).filter(f => f.endsWith('.sql')).sort()) {
@@ -82,3 +114,209 @@ describe('getInstanceId', () => {
     expect(() => getInstanceId()).toThrow(/instance_id is not set/);
   });
 });
+
+function seedInstanceSettings(instanceId: string): void {
+  testDb.insert(schema.instanceSettings).values({
+    id: 1,
+    instanceName: 'Local Backspace',
+    instanceId,
+    autoAcceptPeering: 1,
+    registrationOpen: 1,
+    updatedAt: Date.now(),
+  } as typeof schema.instanceSettings.$inferInsert).run();
+}
+
+function seedActivePeer(): void {
+  testDb.insert(schema.federationPeers).values({
+    id: 'peer-remote',
+    origin: PEER_ORIGIN,
+    hmacSecret: PEER_SECRET,
+    status: 'active',
+    createdAt: Date.now(),
+  }).run();
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  const { federationRoutes } = await import('../routes/federation.js');
+  await app.register(federationRoutes);
+  await app.ready();
+  return app;
+}
+
+describe('POST /api/federation/epoch — signed request + signed response', () => {
+  // The module-level beforeEach already created a fresh in-memory DB and reset
+  // the instance-id cache; here we only seed rows and build the app.
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    seedInstanceSettings(LOCAL_EPOCH);
+    seedActivePeer();
+    app = await buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    vi.restoreAllMocks();
+  });
+
+  it('returns 200 with a signed { instanceId } for a validly-signed request', async () => {
+    const body = JSON.stringify({});
+    const headers = buildFederationHeaders(body, PEER_SECRET, PEER_ORIGIN);
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/epoch',
+      headers,
+      payload: body,
+    });
+
+    expect(response.statusCode).toBe(200);
+    const parsed = response.json() as { instanceId?: string };
+    expect(parsed.instanceId).toBe(LOCAL_EPOCH);
+
+    // The response body must be HMAC-signed with the peer's shared secret.
+    const sigHeader = response.headers['x-federation-signature'] as string | undefined;
+    const tsHeader = response.headers['x-federation-timestamp'] as string | undefined;
+    const nonceHeader = response.headers['x-federation-nonce'] as string | undefined;
+    expect(sigHeader).toMatch(/^sha256=/);
+    expect(tsHeader).toBeTruthy();
+    expect(nonceHeader).toBeTruthy();
+
+    const sig = (sigHeader ?? '').replace(/^sha256=/, '');
+    const ts = Number(tsHeader);
+    const ok = verifySignature(response.body, sig, PEER_SECRET, ts, nonceHeader ?? null);
+    expect(ok).toBe(true);
+  });
+
+  it('returns 400 when federation headers are missing', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/epoch',
+      payload: JSON.stringify({}),
+      headers: { 'content-type': 'application/json' },
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+
+  it('returns 401 when the request is signed with the wrong secret', async () => {
+    const body = JSON.stringify({});
+    const headers = buildFederationHeaders(body, 'the-wrong-secret', PEER_ORIGIN);
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/epoch',
+      headers,
+      payload: body,
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  it('returns 403 for an origin that is not a known peer', async () => {
+    const body = JSON.stringify({});
+    const headers = buildFederationHeaders(body, PEER_SECRET, 'https://stranger.example');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/epoch',
+      headers,
+      payload: body,
+    });
+
+    expect(response.statusCode).toBe(403);
+  });
+
+  it('returns 403 for a revoked peer', async () => {
+    testDb.insert(schema.federationPeers).values({
+      id: 'peer-revoked',
+      origin: 'https://revoked.example',
+      hmacSecret: 'revoked-secret',
+      status: 'revoked',
+      createdAt: Date.now(),
+    }).run();
+
+    const body = JSON.stringify({});
+    const headers = buildFederationHeaders(body, 'revoked-secret', 'https://revoked.example');
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/epoch',
+      headers,
+      payload: body,
+    });
+
+    expect(response.statusCode).toBe(403);
+  });
+});
+
+describe('fetchPeerEpoch — signs request, verifies signed response, fails safe', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  function signedEpochResponse(instanceId: string, secret: string): Response {
+    const responseBody = JSON.stringify({ instanceId });
+    // buildFederationHeaders returns a complete Record<string,string> (signature,
+    // timestamp, nonce, origin, content-type) — exactly what the real handler sets.
+    const sigHeaders = buildFederationHeaders(responseBody, secret, PEER_ORIGIN);
+    return new Response(responseBody, { status: 200, headers: sigHeaders });
+  }
+
+  it('returns the instanceId when the response signature is valid', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => signedEpochResponse('remote-epoch-1', PEER_SECRET)));
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    const result = await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+    expect(result).toBe('remote-epoch-1');
+  });
+
+  it('signs the outbound request with the peer secret', async () => {
+    const fetchMock = vi.fn(async () => signedEpochResponse('remote-epoch-1', PEER_SECRET));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+
+    const call = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    expect(call[0]).toBe(`${PEER_ORIGIN}/api/federation/epoch`);
+    const sentHeaders = call[1].headers as Record<string, string>;
+    const sig = (sentHeaders['X-Federation-Signature'] ?? '').replace(/^sha256=/, '');
+    const ts = Number(sentHeaders['X-Federation-Timestamp']);
+    const nonce = sentHeaders['X-Federation-Nonce'] ?? null;
+    expect(verifySignature(call[1].body as string, sig, PEER_SECRET, ts, nonce)).toBe(true);
+  });
+
+  it('returns null when the response signature is invalid (wrong secret)', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => signedEpochResponse('remote-epoch-1', 'a-different-secret')));
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    const result = await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+    expect(result).toBeNull();
+  });
+
+  it('returns null on 404 (peer not yet upgraded)', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('Not found', { status: 404 })));
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    const result = await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+    expect(result).toBeNull();
+  });
+
+  it('returns null on a network error (no throw escapes)', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => { throw new Error('ECONNREFUSED'); }));
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    const result = await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when the response omits the signature header', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () =>
+      new Response(JSON.stringify({ instanceId: 'remote-epoch-1' }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ));
+    const { fetchPeerEpoch } = await import('./federationEpoch.js');
+    const result = await fetchPeerEpoch({ origin: PEER_ORIGIN, hmacSecret: PEER_SECRET });
+    expect(result).toBeNull();
+  });
+});

packages/server/src/utils/federationEpoch.ts

@@ -1,5 +1,6 @@
 import { eq } from 'drizzle-orm';
 import { getDb, schema } from '../db/index.js';
+import { buildFederationHeaders, verifySignature, getOurOrigin } from './federationAuth.js';
 
 let cached: string | null = null;
 
@@ -22,3 +23,66 @@ export function getInstanceId(): string {
 export function __resetInstanceIdCacheForTest(): void {
   cached = null;
 }
+
+/** The minimal peer shape `fetchPeerEpoch` needs: its origin and our shared secret with it. */
+export interface PeerForEpoch {
+  origin: string;
+  hmacSecret: string;
+}
+
+/**
+ * Fetch a peer's authenticated instance epoch via `POST /api/federation/epoch`.
+ *
+ * The request is HMAC-signed with the shared secret (so only an established
+ * peer can make the call), and the peer's response body is HMAC-verified with
+ * the same secret before its value is trusted — a poisoned baseline can drive a
+ * spurious heal on a live peer (design §9), so the epoch we newly trust is
+ * signed, not TLS-only.
+ *
+ * Fails safe: any failure — a 404 from a not-yet-upgraded peer, a bad/absent
+ * response signature, or a network/timeout error — returns `null`. Callers
+ * treat `null` as "retry on the next tick," never as an error to surface. No
+ * exception escapes this function.
+ */
+export async function fetchPeerEpoch(peer: PeerForEpoch): Promise<string | null> {
+  const body = JSON.stringify({});
+  const headers = buildFederationHeaders(body, peer.hmacSecret, getOurOrigin());
+
+  let res: Response;
+  try {
+    res = await fetch(`${peer.origin}/api/federation/epoch`, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch {
+    // Network error / timeout — benign no-op, retry later.
+    return null;
+  }
+
+  // 404 = peer not yet upgraded (endpoint absent); any other non-2xx = error.
+  if (res.status === 404 || !res.ok) return null;
+
+  let text: string;
+  try {
+    text = await res.text();
+  } catch {
+    return null;
+  }
+
+  // Verify the response signature with the SAME secret and arg order the peer's
+  // handler signed it with. A mismatch means we must not trust the value.
+  const sig = (res.headers.get('x-federation-signature') ?? '').replace(/^sha256=/, '');
+  const ts = Number(res.headers.get('x-federation-timestamp'));
+  const nonce = res.headers.get('x-federation-nonce');
+  if (!sig || !Number.isFinite(ts) || !verifySignature(text, sig, peer.hmacSecret, ts, nonce)) {
+    return null;
+  }
+
+  try {
+    return (JSON.parse(text) as { instanceId?: string }).instanceId ?? null;
+  } catch {
+    return null;
+  }
+}