feat(federation): /approve forwards token + /approve & /peer/initiate capture on 202 + 200 clear

Three changes to keep the outbound /peer/accept call sites consistent
with the new approval-token mechanism:

1. /approve outbound body now forwards approvalToken from the queued
   peer_approval_requests row when present. Receiver's awaiting_approval
   branch verifies it and promotes mutual approval. Legacy null-token
   rows omit the field; receiver falls through autoAccept gate. Spec §3.7.

2. /approve and /peer/initiate 202 paths now capture the approvalToken
   returned by the remote and store it on the local federation_peers row.
   Without this, the symmetric autoAccept=0 mutual-approval flow could
   not verify on the eventual return /peer/accept. Spec §3.7.

3. /approve and /peer/initiate 200 paths now include approvalToken=null
   in the activation UPDATE — single-use lifecycle hygiene per §3.2.

Test coverage: +6 tests (4 in approveOutbound, 2 in peerInitiateOutbound).
Total: 301 → 307. Web tsc clean.

packages/server/src/routes/federation.approveOutbound.test.ts

@@ -0,0 +1,239 @@
+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 { eq } from 'drizzle-orm';
+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 '../utils/snowflake.js';
+
+setWorkerId(1);
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+type TestDb = ReturnType<typeof drizzle<typeof schema>>;
+let sqlite: Database.Database;
+let testDb: TestDb;
+
+vi.mock('../db/index.js', () => ({
+  getDb: () => testDb,
+  getRawDb: () => sqlite,
+  schema,
+}));
+
+vi.mock('../config.js', () => ({
+  config: {
+    domain: 'local.example',
+    port: 3000,
+    host: '0.0.0.0',
+    jwtSecret: 'test-secret-12345678901234567890123456789012',
+    maxUploadSize: 100 * 1024 * 1024,
+    registrationOpen: true,
+  },
+}));
+
+vi.mock('../utils/auth.js', () => ({
+  authenticate: async (req: { userId?: string }) => {
+    req.userId = 'admin-user';
+  },
+  requireAdmin: async () => {},
+}));
+
+vi.mock('../utils/federationAuth.js', async () => {
+  const actual = await vi.importActual<typeof import('../utils/federationAuth.js')>('../utils/federationAuth.js');
+  return {
+    ...actual,
+    getOurOrigin: () => 'https://local.example',
+    generateHmacSecret: () => 'mock-generated-secret',
+  };
+});
+
+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),
+}));
+
+function applyMigrations(db: Database.Database): void {
+  const migrationsDir = path.resolve(__dirname, '../../drizzle');
+  const files = fs.readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+  for (const f of files) {
+    const sqlText = fs.readFileSync(path.join(migrationsDir, f), 'utf8');
+    const statements = sqlText.split(/-->\s*statement-breakpoint/);
+    for (const stmt of statements) {
+      const clean = stmt.trim();
+      if (clean) db.exec(clean);
+    }
+  }
+}
+
+function seedInstanceSettings(): void {
+  testDb.insert(schema.instanceSettings).values({
+    id: 1,
+    instanceName: 'Local Backspace',
+    autoAcceptPeering: 0,
+    registrationOpen: 1,
+    updatedAt: Date.now(),
+  }).run();
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  const { federationRoutes } = await import('./federation.js');
+  await app.register(federationRoutes);
+  await app.ready();
+  return app;
+}
+
+describe('POST /api/federation/approval-requests/:id/approve — outbound token forwarding & 202 capture', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    sqlite = new Database(':memory:');
+    testDb = drizzle(sqlite, { schema });
+    applyMigrations(sqlite);
+    seedInstanceSettings();
+    app = await buildApp();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    sqlite.close();
+  });
+
+  it('forwards approvalToken from peer_approval_requests in the outbound body', async () => {
+    const now = Date.now();
+    const token = 'a'.repeat(64);
+    testDb.insert(schema.peerApprovalRequests).values({
+      id: 'req-1',
+      origin: 'https://remote.example',
+      instanceName: 'Remote',
+      hmacSecret: 'remote-secret',
+      requestedAt: now,
+      expiresAt: now + 30 * 24 * 60 * 60 * 1000,
+      approvalToken: token,
+    }).run();
+
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ accepted: true, instanceName: 'Remote' }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/approval-requests/req-1/approve',
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const init = fetchSpy.mock.calls[0]?.[1];
+    const body = JSON.parse(init?.body as string) as { approvalToken?: string };
+    expect(body.approvalToken).toBe(token);
+  });
+
+  it('omits approvalToken from outbound body when approval-request has null token (legacy)', async () => {
+    const now = Date.now();
+    testDb.insert(schema.peerApprovalRequests).values({
+      id: 'req-2',
+      origin: 'https://remote.example',
+      instanceName: 'Remote',
+      hmacSecret: 'remote-secret',
+      requestedAt: now,
+      expiresAt: now + 30 * 24 * 60 * 60 * 1000,
+      approvalToken: null,
+    }).run();
+
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ accepted: true, instanceName: 'Remote' }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/approval-requests/req-2/approve',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const init = fetchSpy.mock.calls[0]?.[1];
+    const body = JSON.parse(init?.body as string) as { approvalToken?: string };
+    expect(body.approvalToken).toBeUndefined();
+  });
+
+  it('on 200 success, clears approvalToken on the new federation_peers row', async () => {
+    const now = Date.now();
+    testDb.insert(schema.peerApprovalRequests).values({
+      id: 'req-200',
+      origin: 'https://remote.example',
+      instanceName: 'Remote',
+      hmacSecret: 'remote-secret',
+      requestedAt: now,
+      expiresAt: now + 30 * 24 * 60 * 60 * 1000,
+      approvalToken: 'a'.repeat(64),
+    }).run();
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ accepted: true, instanceName: 'Remote' }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/approval-requests/req-200/approve',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const peer = testDb.select().from(schema.federationPeers)
+      .where(eq(schema.federationPeers.origin, 'https://remote.example')).get();
+    expect(peer?.status).toBe('active');
+    expect(peer?.approvalToken).toBeNull();
+  });
+
+  it('on 202 from remote, transitions local peer to awaiting_approval and stores returned approvalToken', async () => {
+    const now = Date.now();
+    const inboundToken = 'a'.repeat(64);
+    testDb.insert(schema.peerApprovalRequests).values({
+      id: 'req-3',
+      origin: 'https://remote.example',
+      instanceName: 'Remote',
+      hmacSecret: 'remote-secret',
+      requestedAt: now,
+      expiresAt: now + 30 * 24 * 60 * 60 * 1000,
+      approvalToken: inboundToken,
+    }).run();
+
+    const remoteToken = 'b'.repeat(64);
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ queued: true, message: 'queued', approvalToken: remoteToken }),
+        { status: 202, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/approval-requests/req-3/approve',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const peer = testDb.select().from(schema.federationPeers)
+      .where(eq(schema.federationPeers.origin, 'https://remote.example')).get();
+    expect(peer?.status).toBe('awaiting_approval');
+    expect(peer?.approvalToken).toBe(remoteToken);
+  });
+});

packages/server/src/routes/federation.peerInitiateOutbound.test.ts

@@ -0,0 +1,156 @@
+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 { eq } from 'drizzle-orm';
+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 '../utils/snowflake.js';
+
+setWorkerId(1);
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+type TestDb = ReturnType<typeof drizzle<typeof schema>>;
+let sqlite: Database.Database;
+let testDb: TestDb;
+
+vi.mock('../db/index.js', () => ({
+  getDb: () => testDb,
+  getRawDb: () => sqlite,
+  schema,
+}));
+
+vi.mock('../config.js', () => ({
+  config: {
+    domain: 'local.example',
+    port: 3000,
+    host: '0.0.0.0',
+    jwtSecret: 'test-secret-12345678901234567890123456789012',
+    maxUploadSize: 100 * 1024 * 1024,
+    registrationOpen: true,
+  },
+}));
+
+vi.mock('../utils/auth.js', () => ({
+  authenticate: async (req: { userId?: string }) => {
+    req.userId = 'admin-user';
+  },
+  requireAdmin: async () => {},
+}));
+
+vi.mock('../utils/federationAuth.js', async () => {
+  const actual = await vi.importActual<typeof import('../utils/federationAuth.js')>('../utils/federationAuth.js');
+  return {
+    ...actual,
+    getOurOrigin: () => 'https://local.example',
+    generateHmacSecret: () => 'mock-generated-secret',
+  };
+});
+
+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),
+}));
+
+function applyMigrations(db: Database.Database): void {
+  const migrationsDir = path.resolve(__dirname, '../../drizzle');
+  const files = fs.readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+  for (const f of files) {
+    const sqlText = fs.readFileSync(path.join(migrationsDir, f), 'utf8');
+    const statements = sqlText.split(/-->\s*statement-breakpoint/);
+    for (const stmt of statements) {
+      const clean = stmt.trim();
+      if (clean) db.exec(clean);
+    }
+  }
+}
+
+function seedInstanceSettings(): void {
+  testDb.insert(schema.instanceSettings).values({
+    id: 1,
+    instanceName: 'Local Backspace',
+    autoAcceptPeering: 0,
+    registrationOpen: 1,
+    updatedAt: Date.now(),
+  }).run();
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  const { federationRoutes } = await import('./federation.js');
+  await app.register(federationRoutes);
+  await app.ready();
+  return app;
+}
+
+describe('POST /api/federation/peer/initiate — 202 token capture & 200 clear', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    sqlite = new Database(':memory:');
+    testDb = drizzle(sqlite, { schema });
+    applyMigrations(sqlite);
+    seedInstanceSettings();
+    app = await buildApp();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    sqlite.close();
+  });
+
+  it('on 202 from remote, transitions local peer to awaiting_approval and stores returned approvalToken', async () => {
+    const remoteToken = 'c'.repeat(64);
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ queued: true, message: 'queued', approvalToken: remoteToken }),
+        { status: 202, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/peer/initiate',
+      payload: { remoteOrigin: 'https://remote.example' },
+    });
+
+    expect(response.statusCode).toBe(202);
+    const peer = testDb.select().from(schema.federationPeers)
+      .where(eq(schema.federationPeers.origin, 'https://remote.example')).get();
+    expect(peer?.status).toBe('awaiting_approval');
+    expect(peer?.approvalToken).toBe(remoteToken);
+  });
+
+  it('on 200 from remote, activates and clears approvalToken', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({ accepted: true, instanceName: 'Remote' }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/federation/peer/initiate',
+      payload: { remoteOrigin: 'https://remote.example' },
+    });
+
+    expect(response.statusCode).toBe(200);
+    const peer = testDb.select().from(schema.federationPeers)
+      .where(eq(schema.federationPeers.origin, 'https://remote.example')).get();
+    expect(peer?.status).toBe('active');
+    expect(peer?.approvalToken).toBeNull();
+  });
+});

packages/server/src/routes/federation.ts

@@ -409,12 +409,20 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
           // (autoAcceptPeering is off on their side). Do NOT activate the
           // local peer — mirror the auto-peer flow in federationPeering.ts
           // by transitioning the pending record to awaiting_approval.
-          // Without this branch the local peer would flip to `active`
+          // Capture the approval token they returned so the next inbound
-          // (because response.ok is true for 202) while the remote had us
+          // /peer/accept (when their admin approves) can be verified. §3.7.
-          // pending, producing a local-active / remote-pending split that
+          let returnedToken: string | null = null;
-          // only self-heals when the remote admin approves.
+          try {
+            const body = (await response.json()) as { approvalToken?: string };
+            if (typeof body?.approvalToken === 'string' && body.approvalToken.length > 0) {
+              returnedToken = body.approvalToken;
+            }
+          } catch {
+            // Non-JSON / empty body — legacy peer.
+          }
+
           db.update(schema.federationPeers)
-            .set({ status: 'awaiting_approval' })
+            .set({ status: 'awaiting_approval', approvalToken: returnedToken })
             .where(eq(schema.federationPeers.id, peerId))
             .run();
           connectionManager.sendToAdmins({ type: 'federation_peers_changed' as const });
@@ -462,7 +470,7 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
         }
 
         db.update(schema.federationPeers)
-          .set({ status: 'active', lastSeenAt: Date.now(), instanceName: remoteInstanceName })
+          .set({ status: 'active', lastSeenAt: Date.now(), instanceName: remoteInstanceName, approvalToken: null })
           .where(eq(schema.federationPeers.id, peerId))
           .run();
         connectionManager.sendToAdmins({ type: 'federation_peers_changed' as const });
@@ -1239,6 +1247,10 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
             sourceOrigin: localOrigin,
             hmacSecret,
             instanceName,
+            // Forward the stored token (issued in our 202 response when the
+            // remote first sent /peer/accept). Lets the remote verify mutual
+            // admin approval. Spec §3.7.
+            ...(approvalReq.approvalToken ? { approvalToken: approvalReq.approvalToken } : {}),
           }),
           signal: AbortSignal.timeout(10_000),
         });
@@ -1246,8 +1258,20 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
         if (response.status === 202) {
           // Remote instance also has autoAcceptPeering off — they queued our request.
           // Don't activate our peer. Set to awaiting_approval until their admin also approves.
+          // Capture the approval token they returned so the next inbound
+          // /peer/accept (when their admin approves) can be verified. §3.7.
+          let returnedToken: string | null = null;
+          try {
+            const body = (await response.json()) as { approvalToken?: string };
+            if (typeof body?.approvalToken === 'string' && body.approvalToken.length > 0) {
+              returnedToken = body.approvalToken;
+            }
+          } catch {
+            // Non-JSON / empty body — legacy peer.
+          }
+
           db.update(schema.federationPeers)
-            .set({ status: 'awaiting_approval' })
+            .set({ status: 'awaiting_approval', approvalToken: returnedToken })
             .where(eq(schema.federationPeers.id, peerId))
             .run();
           // Delete the approval request since we already acted on it
@@ -1288,7 +1312,7 @@ export async function federationRoutes(app: FastifyInstance): Promise<void> {
         }
 
         db.update(schema.federationPeers)
-          .set({ status: 'active', lastSeenAt: now, instanceName: remoteInstanceName })
+          .set({ status: 'active', lastSeenAt: now, instanceName: remoteInstanceName, approvalToken: null })
           .where(eq(schema.federationPeers.id, peerId))
           .run();