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

docs/systems/api.md

@@ -324,12 +324,15 @@ DELETE /federation/peers/:id       (admin)
 POST   /federation/relay           (HMAC-signed S2S)  FederationRelayRequest        → { accepted[], rejected[] }
 POST   /federation/sync            (HMAC-signed S2S)  { sinceTimestamp, limit?, dmChannelId?, federatedId?, contextType? } → { events[], hasMore, checkpoint }
 POST   /federation/users/lookup    (HMAC-signed S2S, rate-limited 60/min/peer)  { username }  → { found, user? }
+POST   /federation/epoch           (HMAC-signed S2S, HMAC-signed response)  {}  → { instanceId }
 ```
 
 **`POST /api/federation/peer/accept`** — public, IP-rate-limited. Optional `approvalToken` (64-hex) on the request body proves mutual admin approval; required to promote an `awaiting_approval` row to `active` when the receiver has `autoAcceptPeering=0`. The receiver returns it in the 202 body when queueing the request for admin review (`{ queued: true, message, approvalToken }`); the initiator stores it and the receiver's `/approve` later forwards it back. See `federation.md` §1 "Approval Token Verification" for the full lifecycle and threat model.
 
 **`POST /api/federation/users/lookup`** — HMAC-authenticated S2S endpoint. Resolves a username on this instance to its canonical `(homeUserId, profile snapshot)`. Used by the cross-instance friend-add flow on the sender's home server before queuing a `friend_request_create` event. Responds to native, non-deleted users only; ignores `discoverable`. Returns `{ found: false, code: 'user_not_found' }` for stubs, tombstoned users, or unknown handles. See `federation.md` §1 "S2S User Lookup" for the full contract.
 
+**`POST /api/federation/epoch`** — HMAC-authenticated S2S endpoint returning this instance's persistent epoch (`{ instanceId }`). The **request** is HMAC-signed (only a peer holding the shared secret may call it; unknown/revoked peers → 403, bad signature → 401, missing headers → 400) **and the response body is HMAC-signed** with the same secret (`X-Federation-Signature/Timestamp/Nonce` response headers), so the caller can verify the epoch before writing it as the peer's trusted baseline (`federation_peers.peer_instance_id`). The value is already public via `/instance/info`; signing is for baseline-integrity, not confidentiality. Caller: `fetchPeerEpoch(peer)` (`utils/federationEpoch.ts`), which fails safe — 404 (not-yet-upgraded peer), bad/absent response signature, or network/timeout all return `null` (retry next tick). Populates the epoch baseline deterministically via the bounded periodic epoch-refresh. See `federation.md` "Instance Epoch" §3.2.
+
 ### Federation Peering Approval Queue
 
 Inbound + outbound peering approval queue (`autoAcceptPeering=0`). See [federation.md → Peer Approval Queue](federation.md#peer-approval-queue) and [federation.md → Outbound Peering Gate](federation.md#outbound-peering-gate).

docs/systems/federation.md

@@ -307,6 +307,11 @@ Admin-initiated paths (`/peer/initiate`, `/approve`) do NOT call `ensurePeered`.
 | `/api/federation/peer/denied` | POST | HMAC | Receive denial notification for awaiting_approval peer |
 | `/api/federation/identity` | DELETE | HMAC | Delete federated user identity (soft/full mode) |
 | `/api/federation/users/lookup` | POST | HMAC, rate-limited 60/min/peer | Resolve a username on this instance to (homeUserId, profile snapshot) for cross-instance friend-request originators |
+| `/api/federation/epoch` | POST | HMAC (signed request **and** signed response) | Return this instance's persistent epoch `{ instanceId }`; populates a peer's trusted epoch baseline (`peer_instance_id`) |
+
+### S2S Epoch Refresh (`POST /api/federation/epoch`)
+
+HMAC-authenticated in **both directions**: the request is signed (only a peer holding the shared secret may call it — unknown/revoked peers → 403, bad signature → 401, missing headers → 400) **and the response body `{ instanceId }` is HMAC-signed** with the same secret (`X-Federation-Signature/Timestamp/Nonce` response headers). The caller (`fetchPeerEpoch(peer)` in `utils/federationEpoch.ts`) verifies that response signature with the same secret before trusting the value, then writes it to `federation_peers.peer_instance_id`. Response-signing (not TLS-only) is deliberate: a poisoned baseline could drive a spurious data-heal on a live peer, so the newly-trusted epoch is authenticated (design §9). `fetchPeerEpoch` **fails safe** — a `404` from a not-yet-upgraded peer, an absent/invalid response signature, or a network/timeout error all return `null` (10s timeout via `AbortSignal.timeout`); the caller treats `null` as "retry on the next tick," never as an error to surface. This is the deterministic populator of the epoch baseline (the bounded periodic epoch-refresh, design §3.2), independent of organic relay traffic.
 
 ### S2S Identity Deletion (`DELETE /api/federation/identity`)
 

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;
+  }
+}