reploid 0.0.0-stage → 0.1.0

package/packages/reploid/src/transport/introduction-bootstrap.js

@@ -0,0 +1,112 @@
+import defaults from './introduction-policy.json' with { type: 'json' };
+import { boundedSnapshot, verifyContact } from './introduction-records.js';
+import { abortable, untilAborted } from '../cancellation.js';
+
+/** Host-owned entry points, tried in retained-contact order, then configured order. */
+export async function bootstrapIntroductions({ introductions, routes, store, signal, isConnected,
+  policy = defaults, onState = () => {} }) {
+  if (!Array.isArray(routes) || routes.length > policy.maxBootstrapRoutes
+    || new Set(routes.map(route => route.id)).size !== routes.length
+    || routes.some(route => typeof route.id !== 'string' || !route.id || typeof route.open !== 'function')) {
+    throw new Error('Explicit bounded introduction routes required');
+  }
+  const local = introductions.exportContact(), roomId = local.body.roomId;
+  signal?.throwIfAborted();
+  const loadSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(policy.messageTtlMs)]) : AbortSignal.timeout(policy.messageTtlMs);
+  const loaded = store ? await abortable(() => store.load(), loadSignal) : [];
+  const saved = boundedSnapshot(loaded, policy.maxMessageBytes);
+  if (!Array.isArray(saved) || saved.length > policy.maxBootstrapRoutes) throw new Error('Invalid retained introduction routes');
+  const retained = new Map();
+  for (const entry of saved) {
+    if (!routes.some(route => route.id === entry.routeId)) continue;
+    try { retained.set(entry.routeId, await verifyContact(entry.contact, { roomId, policy })); }
+    catch { /* Expired/corrupt records grant no authority. Reopen only configured routes. */ }
+  }
+  const ordered = [...routes].sort((a, b) => Number(retained.has(b.id)) - Number(retained.has(a.id)));
+  const failures = [];
+  for (const route of ordered) {
+    signal?.throwIfAborted();
+    const timeout = AbortSignal.timeout(policy.messageTtlMs);
+    const lifetime = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    let session, remotePeerId, expired = false;
+    onState({ state: 'connecting', routeId: route.id });
+    // Each step stops waiting when this route attempt's lifetime ends.
+    const step = operation => untilAborted(operation, lifetime);
+    try {
+      session = await step(Promise.resolve(route.open({ contact: local, retainedContact: retained.get(route.id) || null,
+        signal: lifetime, receive: packet => introductions.receive(null, 'reploid:introduction-signal', packet,
+          answer => { if (!session || lifetime.aborted) throw new Error('Bootstrap route closed'); return session.publish(answer); })
+      })).then(opened => { if (expired || lifetime.aborted) { opened?.close(); throw new Error('Stale bootstrap opening'); } return opened; }));
+      if (!session || typeof session.publish !== 'function' || typeof session.close !== 'function') throw new Error('Invalid bootstrap session');
+      const remote = await step(verifyContact(session.contact, { roomId, policy }));
+      remotePeerId = remote.body.peerId;
+      if (retained.has(route.id) && retained.get(route.id).body.participantId !== remote.body.participantId) throw new Error('Bootstrap participant changed');
+      await step(introductions.connect(remote, packet => {
+        lifetime.throwIfAborted(); return session.publish(packet);
+      }, lifetime));
+      while (!isConnected(remote.body.peerId)) {
+        await step(new Promise(resolve => {
+          const finish = () => { clearTimeout(timer); lifetime.removeEventListener('abort', finish); resolve(); };
+          const timer = setTimeout(finish, 25);
+          lifetime.addEventListener('abort', finish, { once: true });
+        }));
+      }
+      lifetime.throwIfAborted();
+      // Store public verified contact records, never keys, prompts or credentials.
+      retained.set(route.id, remote);
+      if (store) await step(store.save([...retained].slice(-policy.maxBootstrapRoutes)
+        .map(([routeId, contact]) => ({ routeId, contact }))));
+      onState({ state: 'connected', routeId: route.id, peerId: remote.body.peerId });
+      return { routeId: route.id, peerId: remote.body.peerId, failures };
+    } catch (error) {
+      signal?.throwIfAborted();
+      failures.push({ routeId: route.id, message: error.message });
+      onState({ state: 'unavailable', routeId: route.id, message: error.message });
+    } finally { expired = true; if (remotePeerId && !isConnected(remotePeerId)) introductions.cancelPending?.(remotePeerId); session?.close(); }
+  }
+  const error = new Error('No introduction route connected; supply a current invitation or reachable participant');
+  error.failures = failures;
+  throw error;
+}
+
+/** A participant-operated endpoint speaks contact/signal JSON; admission stays at endpoints. */
+export function createWebSocketIntroductionRoute({ id, url, expectedParticipantId, maxMessageBytes = defaults.maxMessageBytes,
+  WebSocket: Socket = globalThis.WebSocket }) {
+  const parsed = new URL(url);
+  if (!['wss:', 'ws:'].includes(parsed.protocol) || parsed.username || parsed.password
+    || parsed.protocol === 'ws:' && !['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname)) {
+    throw new Error('Introduction endpoint requires WSS or loopback WS');
+  }
+  if (typeof expectedParticipantId !== 'string' || !expectedParticipantId.startsWith('peer:')) throw new Error('Pinned bootstrap participant required');
+  return Object.freeze({ id, open({ contact, receive, signal }) {
+    return new Promise((resolve, reject) => {
+      signal.throwIfAborted();
+      const socket = new Socket(url);
+      let admitted = false, closed = false;
+      const close = () => { if (closed) return; closed = true; signal.removeEventListener('abort', aborted); socket.close(); };
+      const failed = error => { close(); reject(error); };
+      const aborted = () => failed(signal.reason);
+      signal.addEventListener('abort', aborted, { once: true });
+      const publish = record => {
+        signal.throwIfAborted();
+        if (closed || socket.readyState !== Socket.OPEN || socket.bufferedAmount > maxMessageBytes) throw new Error('Bootstrap endpoint unavailable');
+        socket.send(JSON.stringify(boundedSnapshot(record, maxMessageBytes))); return true;
+      };
+      socket.onopen = () => { try { publish({ type: 'contact', contact }); } catch (error) { failed(error); } };
+      socket.onerror = () => failed(new Error('Bootstrap endpoint connection failed'));
+      socket.onclose = () => failed(new Error('Bootstrap endpoint closed'));
+      socket.onmessage = event => {
+        try {
+          if (closed || typeof event.data !== 'string' || new TextEncoder().encode(event.data).length > maxMessageBytes) throw new Error('Invalid bootstrap record size');
+          const message = JSON.parse(event.data);
+          if (!admitted) {
+            if (message.type !== 'contact' || message.contact?.body?.participantId !== expectedParticipantId) throw new Error('Bootstrap endpoint identity mismatch');
+            admitted = true;
+            resolve({ contact: message.contact, publish: record => publish({ type: 'signal', envelope: record }), close });
+          } else if (message.type === 'signal') Promise.resolve(receive(message.envelope)).catch(failed);
+          else throw new Error('Unexpected bootstrap record');
+        } catch (error) { failed(error); }
+      };
+    });
+  } });
+}

package/packages/reploid/src/transport/introduction-policy.json

@@ -0,0 +1,12 @@
+{
+  "schema": "reploid.introductions-policy/v1",
+  "contactTtlMs": 300000,
+  "messageTtlMs": 30000,
+  "maxContacts": 64,
+  "maxPending": 8,
+  "maxMessageBytes": 32768,
+  "maxMessagesPerWindow": 256,
+  "windowMs": 30000,
+  "maxBootstrapRoutes": 8,
+  "maxClockSkewMs": 5000
+}

package/packages/reploid/src/transport/introduction-records.js

@@ -0,0 +1,90 @@
+/** Signed endpoint contacts and end-to-end encrypted introduction records. */
+import { canonicalize } from '../artifacts/canonical-json.js';
+import { createPeerIdFromPublicJwk, importSigningKey, importVerificationKey,
+  getIdentitySignAlgorithm, toBase64Url, fromBase64Url } from '../artifacts/identity.js';
+
+const encode = value => new TextEncoder().encode(canonicalize(value));
+const assert = (value, message) => { if (!value) throw new Error(message); };
+export const CONTACT = 'reploid.contact/v1', SIGNAL = 'reploid.introduction/v1';
+
+export function boundedSnapshot(value, limit) {
+  const text = JSON.stringify(value);
+  assert(typeof text === 'string' && new TextEncoder().encode(text).length <= limit, 'Introduction record exceeds allocation');
+  return JSON.parse(text);
+}
+
+async function sign(body, identity) {
+  return { body, publicJwk: identity.publicJwk,
+    signature: toBase64Url(await crypto.subtle.sign(getIdentitySignAlgorithm(identity),
+      await importSigningKey(identity), encode(body))) };
+}
+async function verify(record, participantId) {
+  assert(record?.publicJwk && !record.publicJwk.d && typeof record.signature === 'string', 'Invalid introduction signature shape');
+  assert(await createPeerIdFromPublicJwk(record.publicJwk) === participantId, 'Introduction identity mismatch');
+  assert(await crypto.subtle.verify(getIdentitySignAlgorithm(record.publicJwk),
+    await importVerificationKey(record.publicJwk), fromBase64Url(record.signature), encode(record.body)), 'Invalid introduction signature');
+}
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 256;
+function lifetime(body, now, ttl, skew) {
+  assert(Number.isSafeInteger(body.createdAt) && Number.isSafeInteger(body.expiresAt)
+    && body.createdAt <= now + skew && body.expiresAt > now && body.expiresAt - body.createdAt <= ttl
+    && body.expiresAt > body.createdAt, 'Expired or invalid introduction lifetime');
+}
+export async function createContact({ identity, peerId, roomId, sequence, policy, createAdmission, now = Date.now() }) {
+  assert(await createPeerIdFromPublicJwk(identity.publicJwk) === identity.peerId, 'Local introduction identity mismatch');
+  const keys = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey']);
+  const body = { schema: CONTACT, participantId: identity.peerId, peerId, roomId, sequence,
+    createdAt: now, expiresAt: now + policy.contactTtlMs,
+    encryptionKey: await crypto.subtle.exportKey('jwk', keys.publicKey) };
+  if (createAdmission) body.admission = await createAdmission(structuredClone(body));
+  return { record: await sign(body, identity), privateKey: keys.privateKey };
+}
+export async function verifyContact(input, { roomId, policy, now = Date.now() }) {
+  const record = boundedSnapshot(input, policy.maxMessageBytes), body = record.body;
+  assert(body?.schema === CONTACT && body.roomId === roomId && identifier(body.peerId)
+    && identifier(body.participantId) && Number.isSafeInteger(body.sequence) && body.sequence >= 0,
+  'Invalid introduction contact');
+  lifetime(body, now, policy.contactTtlMs, policy.maxClockSkewMs);
+  assert(body.encryptionKey?.kty === 'EC' && body.encryptionKey.crv === 'P-256' && !body.encryptionKey.d,
+    'Invalid introduction encryption key');
+  await crypto.subtle.importKey('jwk', body.encryptionKey, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+  await verify(record, body.participantId);
+  return record;
+}
+async function sharedKey(privateKey, publicJwk) {
+  const publicKey = await crypto.subtle.importKey('jwk', publicJwk, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+  return crypto.subtle.deriveKey({ name: 'ECDH', public: publicKey }, privateKey,
+    { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+export async function sealIntroduction({ identity, contact, recipient, payload, policy, now = Date.now() }) {
+  const header = { schema: SIGNAL, roomId: contact.record.body.roomId, id: crypto.randomUUID(),
+    from: contact.record.body.peerId, to: recipient.body.peerId, participantId: identity.peerId,
+    recipientId: recipient.body.participantId, recipientSequence: recipient.body.sequence,
+    createdAt: now, expiresAt: Math.min(now + policy.messageTtlMs, contact.record.body.expiresAt, recipient.body.expiresAt) };
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await sharedKey(contact.privateKey, recipient.body.encryptionKey);
+  const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: encode(header) }, key, encode(payload));
+  const record = await sign({ ...header, iv: toBase64Url(iv), ciphertext: toBase64Url(ciphertext), contact: contact.record }, identity);
+  return boundedSnapshot(record, policy.maxMessageBytes);
+}
+export async function verifyIntroduction(input, { roomId, policy, now = Date.now() }) {
+  const record = boundedSnapshot(input, policy.maxMessageBytes), body = record.body;
+  assert(body?.schema === SIGNAL && body.roomId === roomId && identifier(body.id) && identifier(body.to)
+    && identifier(body.recipientId) && typeof body.ciphertext === 'string'
+    && typeof body.iv === 'string' && fromBase64Url(body.iv).length === 12, 'Invalid introduction envelope');
+  lifetime(body, now, policy.messageTtlMs, policy.maxClockSkewMs);
+  const contact = await verifyContact(body.contact, { roomId, policy, now });
+  assert(contact.body.peerId === body.from && contact.body.participantId === body.participantId,
+    'Introduction sender does not match contact');
+  await verify(record, body.participantId);
+  return record;
+}
+export async function openIntroduction(record, contact) {
+  const { iv, ciphertext, contact: sender, ...header } = record.body;
+  assert(header.to === contact.record.body.peerId && header.recipientId === contact.record.body.participantId
+    && header.recipientSequence === contact.record.body.sequence, 'Introduction recipient changed');
+  const key = await sharedKey(contact.privateKey, sender.body.encryptionKey);
+  const bytes = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromBase64Url(iv), additionalData: encode(header) },
+    key, fromBase64Url(ciphertext));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}

package/packages/reploid/src/transport/introductions.js

@@ -0,0 +1,209 @@
+import { fingerprint } from './sdp-fingerprint.js';
+import defaults from './introduction-policy.json' with { type: 'json' };
+import { freezeJson } from '../config/index.js';
+import { boundedSnapshot, createContact, verifyContact, sealIntroduction,
+  verifyIntroduction, openIntroduction } from './introduction-records.js';
+
+export const INTRODUCTION_CONTACT = 'reploid:introduction-contact';
+export const INTRODUCTION_SIGNAL = 'reploid:introduction-signal';
+const assert = (value, message) => { if (!value) throw new Error(message); };
+
+/** One-hop introductions. The host grants admission/forwarding independently of compute. */
+export async function createPeerIntroductions({ transport, identity, roomId, authorize, createAdmission, policy = defaults,
+  now = Date.now, onError = () => {} }) {
+  policy = freezeJson(structuredClone(policy));
+  assert(policy.schema === defaults.schema && Object.keys(defaults).every(key => key === 'schema'
+    || Number.isSafeInteger(policy[key]) && policy[key] > 0), 'Invalid introduction policy');
+  assert(typeof authorize === 'function', 'Introduction authorization is required');
+  identity = structuredClone(identity);
+  const peerId = transport._getPeerId();
+  const contacts = new Map(), attempts = new Map(), seen = new Map();
+  let closed = false, contact = await createContact({ identity, peerId, roomId, sequence: now(), policy, createAdmission, now: now() });
+  let inFlight = 0, windowStart = now(), windowCount = 0;
+  const alive = () => assert(!closed, 'Introductions are closed');
+  const permitted = async (action, details) => {
+    alive();
+    assert(await authorize(freezeJson({ action, roomId, ...structuredClone(details) })) === true,
+      `Introduction ${action} denied`);
+    alive();
+  };
+  const prune = () => {
+    for (const [key, value] of seen) if (value <= now()) seen.delete(key);
+    for (const [key, value] of contacts) if (value.record.body.expiresAt <= now()) contacts.delete(key);
+    for (const [key, value] of attempts) if (value.expiresAt <= now()) {
+      attempts.delete(key); if (!value.established) transport.cancelIntroduction?.(key, value.id);
+    }
+  };
+  async function bounded(operation) {
+    alive(); prune();
+    if (now() - windowStart >= policy.windowMs) { windowStart = now(); windowCount = 0; }
+    assert(inFlight < policy.maxPending && windowCount < policy.maxMessagesPerWindow, 'Introduction rate limit');
+    inFlight++; windowCount++;
+    try { return await operation(); } finally { inFlight--; }
+  }
+  async function retain(input, route) {
+    const record = await verifyContact(input, { roomId, policy, now: now() });
+    alive();
+    assert(record.body.peerId !== peerId, 'Self introduction');
+    await permitted('admit', { contact: record });
+    const previous = contacts.get(record.body.peerId);
+    if (previous) {
+      assert(previous.record.body.participantId === record.body.participantId, 'Contact identity collision');
+      assert(record.body.sequence >= previous.record.body.sequence, 'Stale contact sequence');
+      if (record.body.sequence === previous.record.body.sequence) {
+        assert(JSON.stringify(record.body) === JSON.stringify(previous.record.body), 'Contact sequence collision');
+      }
+    }
+    assert(previous || contacts.size < policy.maxContacts, 'Contact allocation exhausted');
+    contacts.set(record.body.peerId, { record, route });
+    return record;
+  }
+  const directRoute = via => envelope => transport.sendToPeer(via, INTRODUCTION_SIGNAL, envelope);
+  async function publish(remote, payload, route) {
+    alive();
+    const recipient = contacts.get(remote)?.record;
+    assert(recipient && recipient.body.expiresAt > now() && contact.record.body.expiresAt > now(), 'Contact expired');
+    await permitted('connect', { contact: recipient });
+    const record = await sealIntroduction({ identity, contact, recipient, payload, policy, now: now() });
+    await permitted('connect', { contact: recipient });
+    assert(await route({ record, forwarded: false }) !== false, 'Introduction route unavailable');
+    alive();
+  }
+  function exchange(remote, attempt) {
+    return { attemptId: attempt.id, isActive: () => !closed && attempts.get(remote) === attempt, publish(message) {
+      const payload = { ...boundedSnapshot(message, policy.maxMessageBytes), attemptId: attempt.id };
+      // Preserve offer/answer/candidate order even when signing completes asynchronously.
+      attempt.sending = attempt.sending.then(async () => {
+        alive(); assert(attempts.get(remote) === attempt, 'Introduction attempt superseded');
+        await publish(remote, payload, attempt.route);
+      });
+      attempt.sending.catch(error => { if (!closed) onError(error); });
+      return attempt.sending;
+    } };
+  }
+  function allocate(remote, id, route) {
+    assert(attempts.has(remote) || attempts.size < policy.maxPending, 'Introduction attempt allocation exhausted');
+    const attempt = { id, route, expiresAt: now() + policy.messageTtlMs, sending: Promise.resolve() };
+    attempts.set(remote, attempt);
+    return attempt;
+  }
+  async function connectRecord(record, route, signal) {
+    signal?.throwIfAborted();
+    if (transport.getConnectedPeers().some(peer => peer.id === record.body.peerId) || attempts.has(record.body.peerId)) return;
+    assert(transport.getConnectedPeers().length < policy.maxContacts, 'Connected peer allocation exhausted');
+    await permitted('connect', { contact: record });
+    signal?.throwIfAborted();
+    if (attempts.has(record.body.peerId)) return;
+    const remote = record.body.peerId, attempt = allocate(remote, crypto.randomUUID(), route);
+    const aborted = () => {
+      if (attempts.get(remote) !== attempt) return;
+      attempts.delete(remote); transport.cancelIntroduction?.(remote, attempt.id);
+    };
+    signal?.addEventListener('abort', aborted, { once: true });
+    try { await transport.connectIntroducedPeer(remote, exchange(remote, attempt)); signal?.throwIfAborted(); }
+    catch (error) { if (attempts.get(remote) === attempt) attempts.delete(remote); throw error; }
+    finally { signal?.removeEventListener('abort', aborted); }
+  }
+  async function receiveSignal(via, input, replyRoute) {
+    assert(input?.forwarded === false || input?.forwarded === true, 'Invalid introduction route');
+    const record = await verifyIntroduction(input.record, { roomId, policy, now: now() });
+    alive();
+    const { body } = record;
+    assert(!seen.has(body.id), 'Replayed introduction');
+    assert(seen.size < policy.maxMessagesPerWindow, 'Introduction replay allocation exhausted');
+    seen.set(body.id, body.expiresAt);
+    if (body.to !== peerId) {
+      assert(!input.forwarded && via === body.from && body.to !== via, 'Introduction forwarding limit');
+      assert(transport.getConnectedPeers().some(peer => peer.id === body.to), 'Introduction recipient unavailable');
+      await permitted('forward', { from: body.contact, to: body.to });
+      alive();
+      assert(transport.sendToPeer(body.to, INTRODUCTION_SIGNAL, { record, forwarded: true }), 'Introduction forwarding failed');
+      return;
+    }
+    const remote = body.from, route = replyRoute || directRoute(via);
+    await retain(body.contact, route);
+    const payload = await openIntroduction(record, contact);
+    alive();
+    assert(typeof payload.attemptId === 'string' && /^[a-f0-9-]{36}$/.test(payload.attemptId)
+      && ['offer', 'answer', 'ice-candidate'].includes(payload.type), 'Invalid introduction negotiation');
+    if (payload.type !== 'ice-candidate') assert(fingerprint(payload[payload.type]), 'Missing unique WebRTC certificate fingerprint');
+    // Admission of a contact does not preserve a revoked connection grant.
+    await permitted('connect', { contact: body.contact });
+    let attempt = attempts.get(remote);
+    if (attempt && attempt.id !== payload.attemptId) {
+      // One deterministic initiator survives simultaneous introductions.
+      assert(payload.type === 'offer' && peerId > remote, 'Introduction attempt collision');
+      transport.cancelIntroduction?.(remote, attempt.id); attempts.delete(remote); attempt = null;
+    }
+    if (!attempt) {
+      assert(payload.type === 'offer' || payload.type === 'ice-candidate', 'Unsolicited introduction answer');
+      assert(transport.getConnectedPeers().length < policy.maxContacts, 'Connected peer allocation exhausted');
+      attempt = allocate(remote, payload.attemptId, route);
+    }
+    assert(attempt.expiresAt > now(), 'Introduction attempt expired');
+    await transport.acceptIntroductionSignal(remote, payload, exchange(remote, attempt));
+  }
+  async function receiveContact(via, input) {
+    assert(typeof input?.forwarded === 'boolean', 'Invalid contact route');
+    assert(input.forwarded || input.contact?.body?.peerId === via, 'Contact source mismatch');
+    const record = await retain(input.contact, directRoute(via));
+    if (!input.forwarded) {
+      for (const peer of transport.getConnectedPeers()) {
+        if (peer.id === via) continue;
+        try {
+          await permitted('forward', { from: record, to: peer.id });
+          transport.sendToPeer(peer.id, INTRODUCTION_CONTACT, { contact: record, forwarded: true });
+          const other = contacts.get(peer.id)?.record;
+          if (other) {
+            await permitted('forward', { from: other, to: via });
+            transport.sendToPeer(via, INTRODUCTION_CONTACT, { contact: other, forwarded: true });
+          }
+        } catch (error) { onError(error); }
+      }
+    } else if (peerId < record.body.peerId) await connectRecord(record, directRoute(via));
+  }
+  const receive = (via, type, value, replyRoute) => {
+    // Snapshot before the first asynchronous authority check.
+    const input = boundedSnapshot(value, policy.maxMessageBytes);
+    return bounded(() => type === INTRODUCTION_CONTACT ? receiveContact(via, input)
+      : type === INTRODUCTION_SIGNAL ? receiveSignal(via, input, replyRoute) : Promise.reject(new Error('Unknown introduction message')));
+  };
+  transport.onMessage(INTRODUCTION_CONTACT, (via, value) => { receive(via, INTRODUCTION_CONTACT, value).catch(onError); });
+  transport.onMessage(INTRODUCTION_SIGNAL, (via, value) => { receive(via, INTRODUCTION_SIGNAL, value).catch(onError); });
+  return Object.freeze({
+    exportContact() { alive(); return structuredClone(contact.record); },
+    async announce(remote) {
+      alive(); prune();
+      await permitted('announce', { to: remote });
+      if (contact.record.body.expiresAt <= now() + policy.messageTtlMs) {
+        assert(attempts.size === 0, 'Cannot rotate contact during negotiation');
+        const next = await createContact({ identity, peerId, roomId, sequence: Math.max(now(), contact.record.body.sequence + 1), policy, createAdmission, now: now() });
+        alive(); contact = next;
+      }
+      transport.sendToPeer(remote, INTRODUCTION_CONTACT, { contact: contact.record, forwarded: false });
+    },
+    async connect(input, route, signal) {
+      signal?.throwIfAborted();
+      assert(typeof route === 'function', 'Reachable introduction route required');
+      return bounded(async () => { const record = await retain(input, route); await connectRecord(record, route, signal); });
+    },
+    receive,
+    cancelPending(remote) {
+      const attempt = attempts.get(remote);
+      if (attempt && !attempt.established) { transport.cancelIntroduction?.(remote, attempt.id); attempts.delete(remote); }
+    },
+    retirePeer(remote, attemptId) {
+      const attempt = attempts.get(remote);
+      if (!attempt || !attemptId || attempt.id === attemptId) { contacts.delete(remote); attempts.delete(remote); }
+    },
+    settled(remote) { const attempt = attempts.get(remote); if (attempt) attempt.established = true; },
+    getState: () => ({ contacts: contacts.size, pending: attempts.size, closed }),
+    close() {
+      closed = true;
+      for (const [remote, attempt] of attempts) {
+        if (!attempt.established) transport.cancelIntroduction?.(remote, attempt.id);
+      }
+      contacts.clear(); attempts.clear(); seen.clear();
+    }
+  });
+}