From bf74aa8bb2d8c5e74a7588a4d02d262ec6e49d8b Mon Sep 17 00:00:00 2001 From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com> Date: Wed, 1 Jul 2026 21:43:02 +0200 Subject: [PATCH] feat(federation): signed /api/federation/epoch endpoint + caller --- docs/systems/api.md | 3 + docs/systems/federation.md | 5 + packages/server/src/routes/federation.ts | 49 ++++ .../server/src/utils/federationEpoch.test.ts | 240 +++++++++++++++++- packages/server/src/utils/federationEpoch.ts | 64 +++++ 5 files changed, 360 insertions(+), 1 deletion(-) diff --git a/docs/systems/api.md b/docs/systems/api.md index a8091ef7..2485a2c6 100644 --- a/docs/systems/api.md +++ b/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). diff --git a/docs/systems/federation.md b/docs/systems/federation.md index ec9121d2..dd9d0236 100644 --- a/docs/systems/federation.md +++ b/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`) diff --git a/packages/server/src/routes/federation.ts b/packages/server/src/routes/federation.ts index 378537a1..7e7c6661 100644 --- a/packages/server/src/routes/federation.ts +++ b/packages/server/src/routes/federation.ts @@ -2317,6 +2317,55 @@ export async function federationRoutes(app: FastifyInstance): Promise { }, ); + // ─── 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); + 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 diff --git a/packages/server/src/utils/federationEpoch.test.ts b/packages/server/src/utils/federationEpoch.test.ts index 733a0187..a0079f6d 100644 --- a/packages/server/src/utils/federationEpoch.test.ts +++ b/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 { + 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 (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; + 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(); + }); +}); diff --git a/packages/server/src/utils/federationEpoch.ts b/packages/server/src/utils/federationEpoch.ts index daa18834..5f35d0b0 100644 --- a/packages/server/src/utils/federationEpoch.ts +++ b/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 { + 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; + } +}