feat(federation): add /users/by-home-id reverse lookup for stub backfill

HMAC-authenticated, rate-limited (60/min/peer) endpoint that resolves a homeUserId on this instance to its canonical username + profile snapshot. Native non-deleted users only. Mirrors /users/lookup's auth shape. Adds lookupRemoteUserByHomeId to federationLookup.ts as the client-side helper. Used by the upcoming stub-backfill worker on peers that hold legacy snowflake-named replicas of users now visible by their real handle.
2026-05-05 15:54:06 +02:00
parent 097eb9a2ef
commit b2faf5afaa
3 changed files with 224 additions and 0 deletions
@@ -75,3 +75,65 @@ export async function lookupRemoteUser(peerOrigin: string, username: string): Pr
    profile: json.user.profile,
  };
 }
+
+/**
+ * Reverse-lookup: ask the peer for a user by homeUserId. Used by the stub
+ * backfill worker to translate legacy snowflake-named stubs into realname-named
+ * stubs. Mirrors lookupRemoteUser's auth + error semantics.
+ *
+ * `not_found` here means "the peer does not host a native non-deleted user
+ * with that homeUserId" — including the tombstone case. Caller should leave
+ * the local stub untouched and retry on the next peer activation.
+ */
+export async function lookupRemoteUserByHomeId(peerOrigin: string, homeUserId: string): Promise<LookupResult> {
+  const db = getDb();
+  const peer = db
+    .select()
+    .from(schema.federationPeers)
+    .where(eq(schema.federationPeers.origin, peerOrigin))
+    .get();
+
+  if (!peer) {
+    throw new Error(`lookupRemoteUserByHomeId: no peer record for ${peerOrigin}`);
+  }
+
+  const body = JSON.stringify({ homeUserId });
+  const headers = buildFederationHeaders(body, peer.hmacSecret, getOurOrigin());
+
+  let response: Response;
+  try {
+    response = await fetch(`${peerOrigin}/api/federation/users/by-home-id`, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+    });
+  } catch {
+    return { ok: false, reason: 'unreachable' };
+  }
+
+  if (response.status === 429) {
+    const raw = Number(response.headers.get('Retry-After') ?? '60');
+    const retryAfter = Number.isFinite(raw) ? raw : 60;
+    return { ok: false, reason: 'rate_limited', retryAfter };
+  }
+
+  if (!response.ok) {
+    throw new Error(`lookupRemoteUserByHomeId: peer ${peerOrigin} returned HTTP ${response.status}`);
+  }
+
+  const json = (await response.json()) as FederationUserLookupResponse;
+  if (!json) {
+    throw new Error(`lookupRemoteUserByHomeId: peer ${peerOrigin} returned empty body`);
+  }
+  if (json.found !== true || !json.user || typeof json.user.homeUserId !== 'string') {
+    return { ok: false, reason: 'not_found' };
+  }
+
+  return {
+    ok: true,
+    homeUserId: json.user.homeUserId,
+    username: json.user.username,
+    profile: json.user.profile,
+  };
+}