feat(ocap-kernel): bound relay hints in OCAP URLs and relay pool size

Cap relay hints embedded in OCAP URLs to 3 (MAX_URL_RELAY_HINTS) with
priority selection (bootstrap first, then most recently seen). Bound the
relay pool to 20 entries (MAX_KNOWN_RELAYS) with eviction of oldest
non-bootstrap entries. This prevents unbounded URL growth as kernels
exchange relay hints across the network.

Closes #889

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/ocap-kernel/src/remotes/kernel/remote-comms.test.ts

@@ -8,15 +8,31 @@ import {
   initRemoteIdentity,
   initRemoteComms,
   parseOcapURL,
+  MAX_URL_RELAY_HINTS,
+  MAX_KNOWN_RELAYS,
 } from './remote-comms.ts';
 import { createMockRemotesFactory } from '../../../test/remotes-mocks.ts';
 import { makeMapKernelDatabase } from '../../../test/storage.ts';
-import type { KernelStore } from '../../store/index.ts';
+import type { KernelStore, RelayEntry } from '../../store/index.ts';
 import { makeKernelStore } from '../../store/index.ts';
 import type { KRef, PlatformServices } from '../../types.ts';
 import { mnemonicToSeed } from '../../utils/bip39.ts';
 import type { RemoteMessageHandler } from '../types.ts';
 
+/**
+ * Build learned (non-bootstrap) relay entries from address strings.
+ *
+ * @param addrs - Relay multiaddr strings.
+ * @param lastSeen - Epoch ms for lastSeen (default 100).
+ * @returns Relay entries with isBootstrap: false.
+ */
+function makeLearnedRelayEntries(
+  addrs: string[],
+  lastSeen = 100,
+): RelayEntry[] {
+  return addrs.map((addr) => ({ addr, lastSeen, isBootstrap: false }));
+}
+
 describe('remote-comms', () => {
   let mockKernelStore: KernelStore;
   let mockPlatformServices: PlatformServices;
@@ -80,11 +96,11 @@ describe('remote-comms', () => {
       expect(remoteComms.getPeerId()).toBe(peerId);
 
       const ocapURL = await remoteComms.issueOcapURL('ko1' as KRef);
-      const { oid } = parseOcapURL(ocapURL);
-      const knownRelays = mockKernelStore.getKnownRelays();
-      expect(Array.isArray(knownRelays)).toBe(true);
-      expect(knownRelays.length).toBeGreaterThan(0);
-      expect(knownRelays).toStrictEqual(testRelays);
+      const { oid, hints } = parseOcapURL(ocapURL);
+      const knownRelayAddresses = mockKernelStore.getKnownRelayAddresses();
+      expect(knownRelayAddresses).toStrictEqual(testRelays);
+      // URL should embed the relays (within MAX_URL_RELAY_HINTS cap)
+      expect(hints).toStrictEqual(testRelays);
       const referenceURL = `ocap:${oid}@${peerId},${testRelays.join(',')}`;
       expect(ocapURL).toBe(referenceURL);
 
@@ -157,12 +173,12 @@ describe('remote-comms', () => {
       );
     });
 
-    it('uses getKnownRelays when options.relays is empty', async () => {
+    it('uses stored relays when options.relays is empty', async () => {
       const storedRelays = [
         '/dns4/stored-relay1.example/tcp/443/wss/p2p/relay1',
         '/dns4/stored-relay2.example/tcp/443/wss/p2p/relay2',
       ];
-      mockKernelStore.setKnownRelays(storedRelays);
+      mockKernelStore.setRelayEntries(makeLearnedRelayEntries(storedRelays));
       await initRemoteComms(
         mockKernelStore,
         mockPlatformServices,
@@ -339,20 +355,24 @@ describe('remote-comms', () => {
         mockRemoteMessageHandler,
         { relays: testRelays },
       );
-      expect(mockKernelStore.getKnownRelays()).toStrictEqual(testRelays);
+      expect(mockKernelStore.getKnownRelayAddresses()).toStrictEqual(
+        testRelays,
+      );
     });
 
     it('does not save relays to KV store when empty', async () => {
       const storedRelays = ['/dns4/stored-relay.example/tcp/443/wss/p2p/relay'];
-      mockKernelStore.setKnownRelays(storedRelays);
+      mockKernelStore.setRelayEntries(makeLearnedRelayEntries(storedRelays));
       await initRemoteComms(
         mockKernelStore,
         mockPlatformServices,
         mockRemoteMessageHandler,
         {}, // empty relays
       );
       // Should not overwrite existing relays
-      expect(mockKernelStore.getKnownRelays()).toStrictEqual(storedRelays);
+      expect(mockKernelStore.getKnownRelayAddresses()).toStrictEqual(
+        storedRelays,
+      );
     });
   });
 
@@ -444,7 +464,7 @@ describe('remote-comms', () => {
         '/dns4/relay1.example/tcp/443/wss/p2p-circuit', // duplicate
       ]);
 
-      const stored = mockKernelStore.getKnownRelays();
+      const stored = mockKernelStore.getKnownRelayAddresses();
       expect(stored).toStrictEqual([
         '/dns4/relay1.example/tcp/443/wss/p2p-circuit',
         '/dns4/relay2.example/tcp/443/wss/p2p-circuit',
@@ -475,10 +495,132 @@ describe('remote-comms', () => {
 
       identity.addKnownRelays([]);
 
-      const stored = mockKernelStore.getKnownRelays();
+      const stored = mockKernelStore.getKnownRelayAddresses();
       expect(stored).toStrictEqual(initialRelays);
     });
 
+    it('issueOcapURL caps relay hints to MAX_URL_RELAY_HINTS', async () => {
+      const relays = Array.from(
+        { length: MAX_URL_RELAY_HINTS + 3 },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      const { identity } = await initRemoteIdentity(mockKernelStore, {
+        relays,
+      });
+
+      const ocapURL = await identity.issueOcapURL('ko1' as KRef);
+      const { hints } = parseOcapURL(ocapURL);
+      expect(hints).toHaveLength(MAX_URL_RELAY_HINTS);
+    });
+
+    it('issueOcapURL prefers bootstrap relays over learned relays', async () => {
+      const bootstrapRelays = [
+        '/dns4/bootstrap1.example/tcp/443/wss/p2p-circuit',
+        '/dns4/bootstrap2.example/tcp/443/wss/p2p-circuit',
+      ];
+      const { identity } = await initRemoteIdentity(mockKernelStore, {
+        relays: bootstrapRelays,
+      });
+
+      // Add many learned relays (more recent lastSeen)
+      const learnedRelays = Array.from(
+        { length: 5 },
+        (_, i) => `/dns4/learned${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      identity.addKnownRelays(learnedRelays);
+
+      const ocapURL = await identity.issueOcapURL('ko1' as KRef);
+      const { hints } = parseOcapURL(ocapURL);
+      expect(hints).toHaveLength(MAX_URL_RELAY_HINTS);
+      // Bootstrap relays should be included ahead of learned relays
+      for (const bootstrap of bootstrapRelays) {
+        expect(hints).toContain(bootstrap);
+      }
+    });
+
+    it('addKnownRelays enforces MAX_KNOWN_RELAYS pool cap', async () => {
+      const { identity } = await initRemoteIdentity(mockKernelStore);
+
+      // Add more relays than the cap
+      const relays = Array.from(
+        { length: MAX_KNOWN_RELAYS + 5 },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      identity.addKnownRelays(relays);
+
+      const entries = mockKernelStore.getRelayEntries();
+      expect(entries).toHaveLength(MAX_KNOWN_RELAYS);
+    });
+
+    it('addKnownRelays evicts oldest non-bootstrap relays when pool is full', async () => {
+      const bootstrapRelays = [
+        '/dns4/bootstrap.example/tcp/443/wss/p2p-circuit',
+      ];
+      const { identity } = await initRemoteIdentity(mockKernelStore, {
+        relays: bootstrapRelays,
+      });
+
+      // Fill pool to the cap
+      const fillerRelays = Array.from(
+        { length: MAX_KNOWN_RELAYS },
+        (_, i) => `/dns4/relay${i}.example/tcp/443/wss/p2p-circuit`,
+      );
+      identity.addKnownRelays(fillerRelays);
+
+      const entries = mockKernelStore.getRelayEntries();
+      expect(entries).toHaveLength(MAX_KNOWN_RELAYS);
+      // Bootstrap relay must survive eviction
+      expect(entries.some((entry) => entry.addr === bootstrapRelays[0])).toBe(
+        true,
+      );
+    });
+
+    it('addKnownRelays updates lastSeen on re-observed relays', async () => {
+      const { identity } = await initRemoteIdentity(mockKernelStore);
+
+      identity.addKnownRelays(['/dns4/relay.example/tcp/443/wss/p2p-circuit']);
+      const firstSeen = mockKernelStore.getRelayEntries()[0]?.lastSeen ?? 0;
+
+      // SES lockdown prevents mocking Date.now; use a real delay instead
+      await new Promise((resolve) => {
+        setTimeout(resolve, 50);
+      });
+      identity.addKnownRelays(['/dns4/relay.example/tcp/443/wss/p2p-circuit']);
+      const secondSeen = mockKernelStore.getRelayEntries()[0]?.lastSeen ?? 0;
+
+      expect(secondSeen).toBeGreaterThan(firstSeen);
+    });
+
+    it('init marks bootstrap relays and preserves learned relays', async () => {
+      // Pre-seed a learned relay
+      mockKernelStore.setRelayEntries([
+        {
+          addr: '/dns4/learned.example/tcp/443/wss/p2p-circuit',
+          lastSeen: 100,
+          isBootstrap: false,
+        },
+      ]);
+
+      const bootstrapRelays = [
+        '/dns4/bootstrap.example/tcp/443/wss/p2p-circuit',
+      ];
+      await initRemoteIdentity(mockKernelStore, {
+        relays: bootstrapRelays,
+      });
+
+      const entries = mockKernelStore.getRelayEntries();
+      expect(entries).toHaveLength(2);
+      expect(
+        entries.find((entry) => entry.addr === bootstrapRelays[0])?.isBootstrap,
+      ).toBe(true);
+      expect(
+        entries.find(
+          (entry) =>
+            entry.addr === '/dns4/learned.example/tcp/443/wss/p2p-circuit',
+        )?.isBootstrap,
+      ).toBe(false);
+    });
+
     it('throws with mnemonic when identity already exists', async () => {
       mockKernelStore.setRemoteIdentityValue('peerId', 'existing-peer-id');
       mockKernelStore.setRemoteIdentityValue(
@@ -690,7 +832,7 @@ describe('remote-comms', () => {
         '/dns4/stored-relay1.example/tcp/443/wss/p2p/relay1',
         '/dns4/stored-relay2.example/tcp/443/wss/p2p/relay2',
       ];
-      mockKernelStore.setKnownRelays(storedRelays);
+      mockKernelStore.setRelayEntries(makeLearnedRelayEntries(storedRelays));
       const remoteComms = await initRemoteComms(
         mockKernelStore,
         mockPlatformServices,

packages/ocap-kernel/src/remotes/kernel/remote-comms.ts

@@ -24,6 +24,12 @@ export type OcapURLParts = {
   hints: string[];
 };
 
+/** Maximum number of relay hints embedded in a single OCAP URL. */
+export const MAX_URL_RELAY_HINTS = 3;
+
+/** Maximum number of relay entries stored in the kernel's relay pool. */
+export const MAX_KNOWN_RELAYS = 20;
+
 /**
  * Break down an ocap URL string into its constituent parts.
  *
@@ -109,7 +115,30 @@ export async function initRemoteIdentity(
   const relays = options?.relays ?? [];
   const mnemonic = options?.mnemonic;
   if (relays.length > 0) {
-    kernelStore.setKnownRelays(relays);
+    const now = Date.now();
+    const bootstrapSet = new Set(relays);
+    // Merge with existing entries: mark bootstrap relays, preserve learned ones
+    const existing = kernelStore.getRelayEntries();
+    const byAddr = new Map(existing.map((entry) => [entry.addr, entry]));
+    for (const addr of relays) {
+      byAddr.set(addr, { addr, lastSeen: now, isBootstrap: true });
+    }
+    // Clear bootstrap flag on entries no longer in the current bootstrap set
+    for (const entry of byAddr.values()) {
+      if (entry.isBootstrap && !bootstrapSet.has(entry.addr)) {
+        entry.isBootstrap = false;
+      }
+    }
+    let merged = [...byAddr.values()];
+    // Enforce pool cap: keep all bootstrap, then newest non-bootstrap
+    if (merged.length > MAX_KNOWN_RELAYS) {
+      const bootstrap = merged.filter((entry) => entry.isBootstrap);
+      const nonBootstrap = merged
+        .filter((entry) => !entry.isBootstrap)
+        .sort((a, b) => b.lastSeen - a.lastSeen);
+      merged = [...bootstrap, ...nonBootstrap].slice(0, MAX_KNOWN_RELAYS);
+    }
+    kernelStore.setRelayEntries(merged);
   }
 
   /* eslint-disable no-param-reassign */
@@ -171,34 +200,69 @@ export async function initRemoteIdentity(
     const encodedKref = encoder.encode(paddedKref);
     const rawOid = await cipher.encrypt(encodedKref, ocapURLKey);
     const oid = base58btc.encode(rawOid);
-    const currentRelays = kernelStore.getKnownRelays();
-    const relaySuffix =
-      currentRelays.length > 0 ? `,${currentRelays.join(',')}` : '';
+    const entries = kernelStore.getRelayEntries();
+    // Select top relays: bootstrap first, then most recently seen
+    const sorted = [...entries].sort((a, b) => {
+      if (a.isBootstrap !== b.isBootstrap) {
+        return a.isBootstrap ? -1 : 1;
+      }
+      return b.lastSeen - a.lastSeen;
+    });
+    const selected = sorted
+      .slice(0, MAX_URL_RELAY_HINTS)
+      .map((entry) => entry.addr);
+    const relaySuffix = selected.length > 0 ? `,${selected.join(',')}` : '';
     const ocapURL = `ocap:${oid}@${peerId}${relaySuffix}`;
     return ocapURL;
   }
 
   /**
-   * Add relay addresses to the kernel's known relay pool, deduplicating.
+   * Add relay addresses to the kernel's known relay pool.
+   * Deduplicates, updates lastSeen on re-observation, and enforces
+   * {@link MAX_KNOWN_RELAYS} by evicting the oldest non-bootstrap entries.
    *
    * @param newRelays - Relay multiaddrs to add.
    */
   function addKnownRelays(newRelays: string[]): void {
     if (newRelays.length === 0) {
       return;
     }
-    const existing = kernelStore.getKnownRelays();
-    const merged = new Set(existing);
+    const now = Date.now();
+    const existing = kernelStore.getRelayEntries();
+    const byAddr = new Map(existing.map((entry) => [entry.addr, entry]));
     let changed = false;
-    for (const relay of newRelays) {
-      if (!merged.has(relay)) {
-        merged.add(relay);
+
+    for (const addr of newRelays) {
+      const entry = byAddr.get(addr);
+      if (entry) {
+        // Update lastSeen on re-observation (create new object to avoid
+        // mutating potentially-hardened deserialized entries)
+        if (entry.lastSeen !== now) {
+          byAddr.set(addr, { ...entry, lastSeen: now });
+          changed = true;
+        }
+      } else {
+        byAddr.set(addr, { addr, lastSeen: now, isBootstrap: false });
         changed = true;
       }
     }
-    if (changed) {
-      kernelStore.setKnownRelays([...merged]);
+
+    if (!changed) {
+      return;
     }
+
+    let entries = [...byAddr.values()];
+
+    // Enforce pool cap by evicting oldest non-bootstrap entries
+    if (entries.length > MAX_KNOWN_RELAYS) {
+      const bootstrap = entries.filter((entry) => entry.isBootstrap);
+      const nonBootstrap = entries
+        .filter((entry) => !entry.isBootstrap)
+        .sort((a, b) => b.lastSeen - a.lastSeen);
+      entries = [...bootstrap, ...nonBootstrap].slice(0, MAX_KNOWN_RELAYS);
+    }
+
+    kernelStore.setRelayEntries(entries);
   }
 
   /**
@@ -231,7 +295,7 @@ export async function initRemoteIdentity(
   return {
     identity: { getPeerId, issueOcapURL, redeemLocalOcapURL, addKnownRelays },
     keySeed,
-    knownRelays: kernelStore.getKnownRelays(),
+    knownRelays: kernelStore.getKnownRelayAddresses(),
   };
 }