From 7d8c9c9d8d8de64d3ca08079ba79bb9a47de7b01 Mon Sep 17 00:00:00 2001 From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:32:40 +0200 Subject: [PATCH] feat(federation): peer_reset_pending guard during limbo window --- docs/systems/federation.md | 9 + docs/systems/social.md | 1 + .../src/routes/dm.peerResetPending.test.ts | 165 ++++++++++++++++++ packages/server/src/routes/dm.ts | 35 ++++ .../src/routes/social.federated.test.ts | 97 ++++++++++ packages/server/src/routes/social.ts | 28 ++- 6 files changed, 334 insertions(+), 1 deletion(-) create mode 100644 packages/server/src/routes/dm.peerResetPending.test.ts diff --git a/docs/systems/federation.md b/docs/systems/federation.md index 69f8f1c2..eb87d518 100644 --- a/docs/systems/federation.md +++ b/docs/systems/federation.md @@ -333,6 +333,15 @@ In a single transaction, `markPeerReset`: Legacy peers advertise no epoch (`instanceId` null), so detection requires a non-null observed epoch differing from a non-null stored baseline — legacy peers never trigger it, and the existing `auth_failures → needs_attention → manual Reset` path continues unchanged for them. +### Limbo-window user error (`peer_reset_pending`) + +Between reset detection (`markPeerReset`) and the admin's one-click Re-peer, the stale identity graph still exists and no heal has run (design §5.3). During this window a user re-adding a same-name friend, or creating a DM to that origin, would otherwise hit a confusing `already_friends` (stale friendship bound to the dead incarnation) or `peer_rejected` (the peer now sits in `needs_attention`, tripping `ensurePeered`). Both user-facing hot paths short-circuit with a clearer **409 `{ error: 'peer_reset_pending' }`**: + +- **Friend-add** (`social.ts` `POST /api/social/requests`, federated branch): after `resolveOriginFromHostname` yields `peerOrigin` and **before** the peering/lookup/`already_friends` checks. +- **DM-create** (`dm.ts` `POST /api/dm`, `homeUserId + homeInstance` branch): before stub creation, so no un-flagged stub is left behind. The target origin is resolved with `resolveOriginFromHostname(new URL(canonicalizeHomeInstance(homeInstance)).host)`. + +Both perform an **O(1) point lookup** on the `federation_reset_events` origin PRIMARY KEY (`origin = peerOrigin AND resolved_at IS NULL`). `peerOrigin` (from `resolveOriginFromHostname`, which returns the stored `federation_peers.origin` verbatim) is exactly the string `markPeerReset` journals, so the query is a single indexed hit/miss. The guard **only** short-circuits when an unresolved row exists; the common case — no reset in progress — is one indexed miss and the normal path proceeds byte-for-byte unchanged. Once the admin re-peers and `healResetIncarnation` resolves the journal (`resolved_at` set), the guard stops firing and the freshly-clean graph accepts the re-add. + ### Data Self-Heal (`healResetIncarnation` — `utils/federationReset.ts`) Detection (`markPeerReset`) only snapshots + journals + notifies; it destroys nothing. The actual heal is `healResetIncarnation(origin, newEpoch, reason)`, fired from `onPeerActivated` (`utils/federationPeerActivation.ts`) **after an admin-authenticated re-peer**, keyed to the confirmed epoch change (design §6). It runs **before** the mutation-log re-sync in `onPeerActivated` so re-sync repopulates onto a clean slate, and it runs **outside any transaction** (`tombstoneUser` opens its own; better-sqlite3 throws on a nested `BEGIN`). diff --git a/docs/systems/social.md b/docs/systems/social.md index c934869b..d2ca8ad0 100644 --- a/docs/systems/social.md +++ b/docs/systems/social.md @@ -293,6 +293,7 @@ As of 2026-04-25, the sender's home server owns the entire federated friend-add 1. **Parse target.** If `body.username` contains no `@`, or the domain after `@` normalizes to this server's own host, fall through to the local-only path (unchanged). 2. **resolveOriginFromHostname(targetDomain)** — resolves the target peer's full origin URL. Prefers a stored `federation_peers` row matching the typed host; falls back to mirroring `getOurOrigin()`'s scheme. Returns null → 400 `invalid_target_domain`. +2a. **Limbo-window guard → 409 `peer_reset_pending`.** O(1) point lookup on the `federation_reset_events` origin PRIMARY KEY: if an **unresolved** row exists for `peerOrigin` (`origin = peerOrigin AND resolved_at IS NULL`), the peer was reset-detected (wipe-and-reinstall) but the admin has not yet re-peered — the local friendship/stub graph is still bound to the dead incarnation. Return 409 `peer_reset_pending` instead of the confusing `already_friends` (stale friendship) or `peer_rejected` (the `needs_attention` peer would otherwise trip `ensurePeered`). `peerOrigin` is the exact string `markPeerReset` journals (the peer's `federation_peers.origin`), so the match is a single indexed lookup; no reset in progress → one indexed miss → the normal path proceeds unchanged. See `docs/systems/federation.md` (instance-epoch self-healing) and the design spec §5.3. The equivalent guard runs on federated DM-create (`POST /api/dm`, `dm.ts`). 3. **Authority defense.** If the calling user's `homeInstance` is set and does not normalize to this server's own host (checked via `normalizeOriginForCompare`), return 403 `not_authoritative_for_sender`. Prevents replicated/federated users from queueing relay events the home server isn't authoritative for. Runs before peering to fail fast. 4. **ensurePeered(peerOrigin)** — blocks on the result. Status → HTTP mapping: - `'active'` → continue diff --git a/packages/server/src/routes/dm.peerResetPending.test.ts b/packages/server/src/routes/dm.peerResetPending.test.ts new file mode 100644 index 00000000..40563c65 --- /dev/null +++ b/packages/server/src/routes/dm.peerResetPending.test.ts @@ -0,0 +1,165 @@ +import { describe, it, expect, beforeEach, 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>; +let sqlite: Database.Database; +let testDb: TestDb; +const currentUserId = 'user-A'; + +vi.mock('../db/index.js', () => ({ + getDb: () => testDb, + schema, +})); + +vi.mock('../utils/auth.js', () => ({ + authenticate: async (req: { userId?: string }) => { + req.userId = currentUserId; + }, +})); + +vi.mock('../ws/handler.js', () => ({ + connectionManager: { + sendToUser: vi.fn(), + sendToDmMembers: vi.fn(), + sendToAdmins: vi.fn(), + getAllOnlineUserIds: () => [], + }, +})); + +vi.mock('../utils/federationOutbox.js', async () => { + const actual = await vi.importActual('../utils/federationOutbox.js'); + return { + ...actual, + isFederationRelayEnabled: () => true, + queueDmCloseRelay: vi.fn(), + sendTypingRelay: vi.fn(), + queueDmRelay: vi.fn(), + queueOutboxEvent: vi.fn(), + appendMutationLog: vi.fn(), + }; +}); + +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 seedCaller(): void { + testDb.insert(schema.users).values({ + id: 'user-A', + username: 'alice', + displayName: 'Alice', + passwordHash: 'x', + homeUserId: 'user-A', + homeInstance: null, + createdAt: Date.now(), + }).run(); +} + +/** The reset peer's persistent row (still present during the limbo window — only + * deleted on admin Re-peer). Its `origin` is the exact string markPeerReset journals. */ +function seedPeer(): void { + testDb.insert(schema.federationPeers).values({ + id: 'peer-remote', + origin: 'https://remote.example', + hmacSecret: 'secret', + status: 'needs_attention', + needsAttentionReason: 'peer_reset_detected', + peerInstanceId: 'dead-epoch', + observedPeerInstanceId: 'new-epoch', + createdAt: Date.now(), + }).run(); +} + +function seedResetEvent(resolvedAt: number | null): void { + testDb.insert(schema.federationResetEvents).values({ + origin: 'https://remote.example', + deadEpoch: 'dead-epoch', + newEpoch: resolvedAt === null ? null : 'new-epoch', + detectedAt: Date.now(), + resolvedAt, + stubCount: 1, + orphanedAccountCount: 0, + }).run(); +} + +async function buildApp(): Promise { + const app = Fastify({ logger: false }); + const { dmRoutes } = await import('./dm.js'); + await app.register(dmRoutes); + await app.ready(); + return app; +} + +describe('POST /api/dm — limbo-window peer_reset_pending guard', () => { + beforeEach(() => { + sqlite = new Database(':memory:'); + testDb = drizzle(sqlite, { schema }); + applyMigrations(sqlite); + seedCaller(); + seedPeer(); + }); + + it('returns 409 peer_reset_pending when creating a federated DM to a reset-pending origin', async () => { + seedResetEvent(null); + + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/dm', + payload: { homeUserId: 'remote-bob', homeInstance: 'https://remote.example' }, + }); + + expect(res.statusCode).toBe(409); + expect(res.json().error).toBe('peer_reset_pending'); + // No stub created and no DM channel created for the reset-pending peer. + expect(testDb.select().from(schema.dmChannels).all()).toHaveLength(0); + expect(testDb.select().from(schema.users).where(eq(schema.users.homeUserId, 'remote-bob')).all()).toHaveLength(0); + }); + + it('proceeds normally when the reset event is RESOLVED', async () => { + seedResetEvent(Date.now()); + + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/dm', + payload: { homeUserId: 'remote-bob', homeInstance: 'https://remote.example' }, + }); + + expect(res.statusCode).toBe(201); + expect(res.json().federatedId).toMatch(/^[a-f0-9]{32}$/); + }); + + it('proceeds normally when NO reset event exists for the origin', async () => { + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/dm', + payload: { homeUserId: 'remote-bob', homeInstance: 'https://remote.example' }, + }); + + expect(res.statusCode).toBe(201); + expect(res.json().federatedId).toMatch(/^[a-f0-9]{32}$/); + }); +}); diff --git a/packages/server/src/routes/dm.ts b/packages/server/src/routes/dm.ts index c800f8bf..5d925999 100644 --- a/packages/server/src/routes/dm.ts +++ b/packages/server/src/routes/dm.ts @@ -47,6 +47,7 @@ import { normalizeIconForWire, } from '../utils/federationOutbox.js'; import { getOurOrigin, canonicalizeHomeInstance } from '../utils/federationAuth.js'; +import { resolveOriginFromHostname } from '../utils/federationOriginResolve.js'; import type { FederationRelayEvent } from '@backspace/shared'; import { resolveLocalUser, resolveOrCreateReplicatedUser } from './federation.js'; @@ -928,6 +929,40 @@ export async function dmRoutes(app: FastifyInstance): Promise { let targetUser: typeof schema.users.$inferSelect | undefined; if (homeUserId && homeInstance) { + // Limbo-window guard (federation instance-epoch self-healing §5.3). + // If the target's home instance was reset-detected but the admin has not yet + // re-peered, an UNRESOLVED `federation_reset_events` row exists for its origin. + // Creating a DM now would bind to stale, dead-incarnation identity state, so + // surface a clear `peer_reset_pending` instead of silently forming a doomed + // channel. Checked BEFORE stub creation so no un-flagged stub is left behind. + // + // The journal is keyed by the peer's `federation_peers.origin` (the exact string + // `markPeerReset` stores). `resolveOriginFromHostname` returns that stored origin + // verbatim, giving an O(1) point lookup on the origin PRIMARY KEY; the common case + // (no reset) is a single indexed miss and the normal path proceeds unchanged. + const canon = canonicalizeHomeInstance(homeInstance); + let peerOrigin: string | null = null; + if (canon) { + try { + peerOrigin = resolveOriginFromHostname(new URL(canon).host); + } catch { + peerOrigin = null; + } + } + if (peerOrigin) { + const pendingReset = db + .select({ origin: schema.federationResetEvents.origin }) + .from(schema.federationResetEvents) + .where(and( + eq(schema.federationResetEvents.origin, peerOrigin), + isNull(schema.federationResetEvents.resolvedAt), + )) + .get(); + if (pendingReset) { + return reply.code(409).send({ error: 'peer_reset_pending', statusCode: 409 }); + } + } + // Federated identity: resolve or create a replicated user stub targetUser = resolveOrCreateReplicatedUser(homeUserId, homeInstance, db) ?? undefined; } else if (userId && typeof userId === 'string') { diff --git a/packages/server/src/routes/social.federated.test.ts b/packages/server/src/routes/social.federated.test.ts index 2318fa0f..f26dccea 100644 --- a/packages/server/src/routes/social.federated.test.ts +++ b/packages/server/src/routes/social.federated.test.ts @@ -457,3 +457,100 @@ describe('POST /api/social/requests — federated branch (authority + self-frien expect(body.requestId).toBe('incoming-req'); }); }); + +describe('POST /api/social/requests — federated branch (limbo-window peer_reset_pending)', () => { + beforeEach(() => { + seedSelf(); + resolveOriginFromHostnameMock.mockReturnValue('https://orbit.test'); + }); + + function seedResetEvent(resolvedAt: number | null): void { + testDb.insert(schema.federationResetEvents).values({ + origin: 'https://orbit.test', + deadEpoch: 'dead-epoch', + newEpoch: resolvedAt === null ? null : 'new-epoch', + detectedAt: Date.now(), + resolvedAt, + stubCount: 1, + orphanedAccountCount: 0, + }).run(); + } + + it('returns 409 peer_reset_pending when an UNRESOLVED reset event exists for the target origin', async () => { + seedResetEvent(null); + // Even a stale friendship must NOT surface as `already_friends` during the limbo window. + testDb.insert(schema.users).values({ + id: 'stub-alice', + username: 'remote-alice@orbit.test', + displayName: 'Alice', + passwordHash: '!federation-replicated', + status: 'offline', + isAdmin: 0, + homeInstance: 'orbit.test', + homeUserId: 'remote-alice-old', + createdAt: Date.now(), + }).run(); + testDb.insert(schema.friends).values({ + userId: CALLER_ID, + friendId: 'stub-alice', + createdAt: Date.now(), + }).run(); + + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/social/requests', + payload: { username: 'alice@orbit.test' }, + }); + + expect(res.statusCode).toBe(409); + expect(JSON.parse(res.body).error).toBe('peer_reset_pending'); + // Short-circuits before peering/lookup — neither is consulted. + expect(ensurePeeredMock).not.toHaveBeenCalled(); + expect(lookupRemoteUserMock).not.toHaveBeenCalled(); + // No new request row created. + expect(testDb.select().from(schema.friendRequests).all()).toHaveLength(0); + }); + + it('proceeds normally when the reset event is RESOLVED (resolved_at set)', async () => { + seedResetEvent(Date.now()); + ensurePeeredMock.mockResolvedValue({ status: 'active', peerId: 'peer-1' }); + lookupRemoteUserMock.mockResolvedValue({ + ok: true, + homeUserId: 'remote-alice', + username: 'alice', + profile: { displayName: 'Alice', avatar: null, avatarColor: 'mint', banner: null, bio: null }, + }); + + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/social/requests', + payload: { username: 'alice@orbit.test' }, + }); + + expect(res.statusCode).toBe(201); + expect(ensurePeeredMock).toHaveBeenCalled(); + expect(JSON.parse(res.body).success).toBe(true); + }); + + it('proceeds normally when NO reset event exists for the origin', async () => { + ensurePeeredMock.mockResolvedValue({ status: 'active', peerId: 'peer-1' }); + lookupRemoteUserMock.mockResolvedValue({ + ok: true, + homeUserId: 'remote-alice', + username: 'alice', + profile: { displayName: 'Alice', avatar: null, avatarColor: 'mint', banner: null, bio: null }, + }); + + const app = await buildApp(); + const res = await app.inject({ + method: 'POST', + url: '/api/social/requests', + payload: { username: 'alice@orbit.test' }, + }); + + expect(res.statusCode).toBe(201); + expect(ensurePeeredMock).toHaveBeenCalled(); + }); +}); diff --git a/packages/server/src/routes/social.ts b/packages/server/src/routes/social.ts index 39b07331..c89b0ccd 100644 --- a/packages/server/src/routes/social.ts +++ b/packages/server/src/routes/social.ts @@ -1,5 +1,5 @@ import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify'; -import { eq, and, or, ne, like, sql, inArray } from 'drizzle-orm'; +import { eq, and, or, ne, like, sql, inArray, isNull } from 'drizzle-orm'; import { getDb, getRawDb, schema } from '../db/index.js'; import { authenticate } from '../utils/auth.js'; import { generateSnowflake } from '../utils/snowflake.js'; @@ -183,6 +183,32 @@ async function handleFederatedFriendRequest( return reply.code(400).send({ error: 'invalid_target_domain', statusCode: 400, domain: targetDomain }); } + // 1a. Limbo-window guard (federation instance-epoch self-healing §5.3). + // If this peer's home instance was reset-detected but the admin has not yet + // re-peered, an UNRESOLVED `federation_reset_events` row exists for its origin + // (the peer sits in `needs_attention`, its local friendship/stub graph still + // bound to the dead incarnation). Without this guard the re-add would surface + // a confusing `already_friends` (stale friendship) or `peer_rejected` (the + // needs_attention peer) — neither of which tells the user what to do. Return a + // clear `peer_reset_pending` instead. + // + // `resolveOriginFromHostname` returns the peer's stored `federation_peers.origin` + // verbatim, which is exactly the string `markPeerReset` journals as + // `federation_reset_events.origin` (its PRIMARY KEY), so this is an O(1) indexed + // point lookup. The common case — no reset in progress — is a single indexed miss + // and the normal path proceeds unchanged. + const pendingReset = db + .select({ origin: schema.federationResetEvents.origin }) + .from(schema.federationResetEvents) + .where(and( + eq(schema.federationResetEvents.origin, peerOrigin), + isNull(schema.federationResetEvents.resolvedAt), + )) + .get(); + if (pendingReset) { + return reply.code(409).send({ error: 'peer_reset_pending', statusCode: 409 }); + } + // 2. ensurePeered — block until 'active', or surface peer status as error const peering = await ensurePeered(peerOrigin, { kind: 'user_action',