chainlesschain 0.163.8 → 0.165.1

package/src/gateways/ws/ws-server.js

@@ -11,7 +11,7 @@
  */
 
 import { EventEmitter } from "node:events";
-import { createHash, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { WebSocketServer } from "ws";
@@ -29,6 +29,7 @@ import { createWsMessageDispatcher } from "./message-dispatcher.js";
 import {
   RemoteSessionRegistry,
   RemoteSessionPolicy,
+  REMOTE_APPROVAL_BINDING_CAPABILITY,
 } from "../../harness/remote-session-registry.js";
 import { RemoteSessionAuditLog } from "../../harness/remote-session-audit.js";
 import { RemoteSessionAuditFileSink } from "../../harness/remote-session-audit-sink.js";
@@ -37,6 +38,9 @@ import {
   isApprovalRequestEvent,
 } from "../../harness/remote-session-push.js";
 import { createRemoteSessionPushSender } from "../../harness/remote-session-push-senders.js";
+import { DurableRemoteMembershipAuthority } from "../../lib/remote-membership-authority.js";
+import { DurableRemoteMembershipCoordinator } from "../../lib/remote-membership-coordinator.js";
+import { remoteSessionPairingTokenDigest } from "../../harness/remote-session-crypto.js";
 import { RemoteSessionRelay } from "../remote-session-relay.js";
 import { handleRemoteSessionPublish } from "./remote-session-protocol.js";
 import { handleTaskDetail, handleTaskHistory } from "./task-protocol.js";
@@ -270,10 +274,37 @@ export class ChainlessChainWSServer extends EventEmitter {
     /** Org-policy constraints for Remote Sessions (scopes, device cap, TTL). */
     this.remoteSessionPolicy =
       options.remoteSessionPolicy || RemoteSessionPolicy.fromEnv(process.env);
+    /**
+     * Server-authoritative durable membership/lease coordinator. Constructed
+     * lazily so ordinary WS deployments that never enable Remote Approval do
+     * not create a machine-security root as a constructor side effect.
+     */
+    this._remoteMembershipCoordinatorOption =
+      options.remoteMembershipCoordinator === null
+        ? null
+        : options.remoteMembershipCoordinator || undefined;
+    this._remoteMembershipCoordinatorOptions =
+      options.remoteMembershipCoordinatorOptions || {};
     /** Local authorization state for multi-device Remote Sessions. */
     this.remoteSessions =
       options.remoteSessionRegistry ||
-      new RemoteSessionRegistry({ policy: this.remoteSessionPolicy });
+      new RemoteSessionRegistry({
+        policy: this.remoteSessionPolicy,
+        membershipCoordinator:
+          options.remoteMembershipCoordinator === null
+            ? null
+            : () => this._requireRemoteMembershipCoordinator(),
+        membershipAuthority:
+          options.remoteMembershipAuthority === null
+            ? null
+            : () =>
+                options.remoteMembershipAuthority ||
+                new DurableRemoteMembershipAuthority(
+                  options.remoteMembershipStateFile
+                    ? { filePath: options.remoteMembershipStateFile }
+                    : {},
+                ),
+      });
     /**
      * Optional durable sink (JSONL) for the audit trail. Enabled only when a
      * sink is injected or CHAINLESSCHAIN_REMOTE_SESSION_AUDIT_FILE is set; the
@@ -330,6 +361,20 @@ export class ChainlessChainWSServer extends EventEmitter {
     this._clientCounter = 0;
   }
 
+  _requireRemoteMembershipCoordinator() {
+    if (typeof this._remoteMembershipCoordinatorOption === "function") {
+      this._remoteMembershipCoordinatorOption =
+        this._remoteMembershipCoordinatorOption();
+    }
+    if (!this._remoteMembershipCoordinatorOption) {
+      this._remoteMembershipCoordinatorOption =
+        new DurableRemoteMembershipCoordinator(
+          this._remoteMembershipCoordinatorOptions,
+        );
+    }
+    return this._remoteMembershipCoordinatorOption;
+  }
+
   /** Start the WebSocket server */
   start() {
     return new Promise((resolve, reject) => {
@@ -452,6 +497,7 @@ export class ChainlessChainWSServer extends EventEmitter {
       ip: clientIp,
       alive: true,
       authTimer: null,
+      membershipConnectionNonce: randomBytes(32).toString("base64url"),
     };
     this.clients.set(clientId, client);
 
@@ -502,16 +548,36 @@ export class ChainlessChainWSServer extends EventEmitter {
       // remaining clients finalizes itself).
       cleanupBgAttachments(client);
       this.clients.delete(clientId);
-      for (const affected of this.remoteSessions.removeClient(clientId)) {
-        if (affected.closed)
-          this.remoteSessionCrypto.delete(affected.sessionId);
-        if (affected.closed)
-          this.remoteSessionPairingSecrets.delete(affected.sessionId);
+      try {
+        for (const affected of this.remoteSessions.removeClient(clientId)) {
+          if (affected.closed)
+            this.remoteSessionCrypto.delete(affected.sessionId);
+          if (affected.closed)
+            this.remoteSessionPairingSecrets.delete(affected.sessionId);
+          this.remoteSessionAudit?.record({
+            sessionId: affected.sessionId,
+            actor: clientId,
+            action: affected.closed ? "session.closed" : "device.disconnected",
+            detail: { reason: "disconnect" },
+          });
+        }
+      } catch (error) {
+        // A durable membership transition that cannot be committed must never
+        // be represented as a successful revoke/close. The socket is already
+        // gone (so this principal cannot send another frame), and every future
+        // durable authorization still re-checks the authority store.
         this.remoteSessionAudit?.record({
-          sessionId: affected.sessionId,
+          sessionId: null,
           actor: clientId,
-          action: affected.closed ? "session.closed" : "device.disconnected",
-          detail: { reason: "disconnect" },
+          action: "membership.state-error",
+          detail: {
+            reason: "disconnect-transition-failed",
+            errorCode: error?.code || null,
+          },
+        });
+        this.emit("client-error", {
+          clientId,
+          error: error?.message || String(error),
         });
       }
       this.emit("disconnection", { clientId });
@@ -539,11 +605,12 @@ export class ChainlessChainWSServer extends EventEmitter {
     return this._dispatcher.dispatch(clientId, ws, message);
   }
 
-  /** Read the same .claude settings rules used by the Agent Core. */
+  /** Read the same static + scoped authority used by the Agent Core. */
   async _handlePermissionRulesGet(id, ws) {
     try {
-      const { loadSettings } = await import("../../lib/settings-loader.cjs");
-      const loaded = loadSettings({ cwd: this.projectRoot });
+      const { loadPermissionAuthority } =
+        await import("../../lib/permission-authority.js");
+      const loaded = loadPermissionAuthority({ cwd: this.projectRoot });
       this._send(ws, {
         id,
         type: "permission-rules",
@@ -551,6 +618,8 @@ export class ChainlessChainWSServer extends EventEmitter {
         sources: loaded.sources,
         files: loaded.files,
         managed: loaded.managed || null,
+        managedFile: loaded.managedFile || null,
+        scoped: loaded.scoped || null,
       });
     } catch (error) {
       this._send(ws, {
@@ -1293,10 +1362,17 @@ export class ChainlessChainWSServer extends EventEmitter {
       data.sessionId,
       hostClientId,
     )) {
-      for (const member of remoteSession.members.values()) {
+      for (const memberView of this.remoteSessions.members(
+        remoteSession.sessionId,
+      )) {
+        const memberTransportId =
+          memberView.transportClientId || memberView.clientId;
+        if (remoteSession.hostPrincipalId && !memberView.transportClientId) {
+          continue;
+        }
         if (
-          member.clientId === hostClientId ||
-          !member.scopes.includes("observe")
+          memberTransportId === hostClientId ||
+          !memberView.scopes.includes("observe")
         ) {
           continue;
         }
@@ -1304,27 +1380,47 @@ export class ChainlessChainWSServer extends EventEmitter {
         // Independent of the WS mirror below — a relay-paired mobile app may
         // report a live socket while its process is suspended and will never
         // read the mirrored event until the user taps the push.
-        if (member.pushToken && isApprovalRequestEvent(data.type)) {
-          this._dispatchApprovalPush(remoteSession, member, data);
+        if (memberView.pushToken && isApprovalRequestEvent(data.type)) {
+          this._dispatchApprovalPush(remoteSession, memberView, data);
         }
-        const target = this.clients.get(member.clientId);
+        const target = this.clients.get(memberTransportId);
         if (!target && this.remoteSessionRelay) {
           const crypto = this.remoteSessionCrypto.get(remoteSession.sessionId);
           if (crypto) {
-            this.remoteSessionRelay.sendEncrypted(
-              member.clientId,
-              crypto.encrypt(member.clientId, data),
-            );
+            try {
+              this.remoteSessions.authorize(
+                remoteSession.sessionId,
+                memberTransportId,
+                "observe",
+              );
+              this.remoteSessionRelay.sendEncrypted(
+                memberTransportId,
+                crypto.encrypt(memberTransportId, data),
+              );
+            } catch {
+              // Revoked/closed between enumeration and the physical send.
+            }
           }
           continue;
         }
         if (!target) continue;
-        this._send(target.ws, {
-          type: "remote-session-event",
-          remoteSessionId: remoteSession.sessionId,
-          agentSessionId: remoteSession.agentSessionId,
-          event: data,
-        });
+        try {
+          this.remoteSessions.authorize(
+            remoteSession.sessionId,
+            memberTransportId,
+            "observe",
+          );
+          const currentTarget = this.clients.get(memberTransportId);
+          if (!currentTarget || currentTarget.ws !== target.ws) continue;
+          this._send(currentTarget.ws, {
+            type: "remote-session-event",
+            remoteSessionId: remoteSession.sessionId,
+            agentSessionId: remoteSession.agentSessionId,
+            event: data,
+          });
+        } catch {
+          // Current durable membership is the send-time authority.
+        }
       }
     }
   }
@@ -1337,14 +1433,26 @@ export class ChainlessChainWSServer extends EventEmitter {
   _dispatchApprovalPush(remoteSession, member, data) {
     const dispatcher = this.remoteSessionPush;
     if (!dispatcher || !dispatcher.enabled) return;
+    let authorized;
+    try {
+      authorized = this.remoteSessions.authorize(
+        remoteSession.sessionId,
+        member.transportClientId || member.clientId,
+        "observe",
+      );
+    } catch {
+      return;
+    }
+    const currentMember = authorized.member;
+    if (!currentMember.pushToken) return;
     const requestId =
       data.requestId || data.approvalId || data.id || `approval:${data.type}`;
     dispatcher
       .dispatch({
-        token: member.pushToken,
-        provider: member.pushProvider,
+        token: currentMember.pushToken,
+        provider: currentMember.pushProvider,
         sessionId: remoteSession.sessionId,
-        clientId: member.clientId,
+        clientId: currentMember.principalId || currentMember.clientId,
         dedupeKey: requestId,
         notification: {
           title: "Approval requested",
@@ -1358,7 +1466,7 @@ export class ChainlessChainWSServer extends EventEmitter {
           try {
             this.remoteSessions.registerPush(
               remoteSession.sessionId,
-              member.clientId,
+              currentMember.principalId || currentMember.clientId,
               { token: null },
             );
           } catch {
@@ -1366,15 +1474,15 @@ export class ChainlessChainWSServer extends EventEmitter {
           }
           this.remoteSessionAudit?.record({
             sessionId: remoteSession.sessionId,
-            actor: member.clientId,
+            actor: currentMember.principalId || currentMember.clientId,
             action: "push.unregistered",
-            detail: { provider: member.pushProvider || null },
+            detail: { provider: currentMember.pushProvider || null },
           });
           return;
         }
         this.remoteSessionAudit?.record({
           sessionId: remoteSession.sessionId,
-          actor: member.clientId,
+          actor: currentMember.principalId || currentMember.clientId,
           action:
             outcome.status === "sent"
               ? "push.sent"
@@ -1382,7 +1490,7 @@ export class ChainlessChainWSServer extends EventEmitter {
                 ? "push.failed"
                 : "push.skipped",
           detail: {
-            provider: member.pushProvider || null,
+            provider: currentMember.pushProvider || null,
             reason: outcome.reason || null,
             error: outcome.error || null,
           },
@@ -1411,6 +1519,52 @@ export class ChainlessChainWSServer extends EventEmitter {
     });
   }
 
+  _assertExactRemoteRelayMembership(sessionId, peerId, receipt) {
+    if (
+      receipt?.sessionId !== sessionId ||
+      receipt.mobilePeerId !== peerId ||
+      !Array.isArray(receipt.scopes) ||
+      receipt.scopes.length === 0
+    ) {
+      throw new Error("Remote relay membership reconciliation changed");
+    }
+    const authorized = this.remoteSessions.authorize(
+      sessionId,
+      peerId,
+      receipt.scopes[0],
+    );
+    const expectedScopes = JSON.stringify([...receipt.scopes].sort());
+    if (
+      authorized.session.sessionId !== receipt.sessionId ||
+      authorized.session.sessionEpoch !== receipt.sessionEpoch ||
+      authorized.member.principalId !== receipt.principalId ||
+      authorized.member.membershipEpoch !== receipt.membershipEpoch ||
+      authorized.member.transportClientId !== peerId ||
+      JSON.stringify([...authorized.member.scopes].sort()) !== expectedScopes ||
+      authorized.membership?.sessionId !== receipt.sessionId ||
+      authorized.membership?.sessionEpoch !== receipt.sessionEpoch ||
+      authorized.membership?.principalId !== receipt.principalId ||
+      authorized.membership?.membershipEpoch !== receipt.membershipEpoch ||
+      JSON.stringify([...(authorized.membership?.scopes || [])].sort()) !==
+        expectedScopes
+    ) {
+      throw new Error("Remote relay membership reconciliation changed");
+    }
+    return authorized;
+  }
+
+  _deleteRemoteSessionPairingSecretIfMatches(sessionId, tokenDigest) {
+    const current = this.remoteSessionPairingSecrets.get(sessionId);
+    if (
+      typeof current === "string" &&
+      remoteSessionPairingTokenDigest(current) === tokenDigest
+    ) {
+      this.remoteSessionPairingSecrets.delete(sessionId);
+      return true;
+    }
+    return false;
+  }
+
   async _handleRemoteRelayMessage(message) {
     if (
       message?.type !== "message" ||
@@ -1421,21 +1575,312 @@ export class ChainlessChainWSServer extends EventEmitter {
     const sessionId = payload.envelope?.sessionId;
     const crypto = this.remoteSessionCrypto.get(sessionId);
     const token = this.remoteSessionPairingSecrets.get(sessionId);
-    if (!crypto || !token)
+    if (!crypto)
+      throw new Error("Remote Session pairing is unavailable or expired");
+    if (
+      typeof payload.mobilePeerId !== "string" ||
+      payload.mobilePeerId !== message.from ||
+      payload.envelope?.senderId !== payload.mobilePeerId
+    ) {
+      throw new Error("Remote Session relay peer binding is invalid");
+    }
+
+    // An already-authenticated receipt wins even if the host has meanwhile
+    // issued a fresh token for another device. Trying the committed key first
+    // lets an ACK-lost peer reconcile without letting the new invitation erase
+    // its key/receipt. Authentication failure is side-effect free; only then
+    // may this frame be considered as a prospective current-token pairing.
+    let acceptedRetry = null;
+    const hasPendingCommittedAcceptance =
+      crypto.hasPendingCommittedRelayAcceptance(payload.mobilePeerId);
+    if (crypto.hasRelayMembershipAcceptance(payload.mobilePeerId)) {
+      try {
+        acceptedRetry = crypto.decrypt(payload.envelope);
+      } catch (error) {
+        if (!token && !hasPendingCommittedAcceptance) throw error;
+      }
+    }
+    if (acceptedRetry) {
+      const join = acceptedRetry;
+      if (
+        join.type !== "pair.join" ||
+        join.remoteSessionId !== sessionId ||
+        typeof join.token !== "string"
+      ) {
+        throw new Error("Invalid encrypted Remote Session pairing retry");
+      }
+      const receipt = crypto.readRelayMembershipAcceptance(
+        payload.mobilePeerId,
+        {
+          mobilePublicKey: payload.mobilePublicKey,
+          pairingTokenDigest: remoteSessionPairingTokenDigest(join.token),
+          capabilities: join.capabilities,
+        },
+      );
+      this._assertExactRemoteRelayMembership(
+        sessionId,
+        payload.mobilePeerId,
+        receipt,
+      );
+      this._deleteRemoteSessionPairingSecretIfMatches(
+        sessionId,
+        receipt.pairingTokenDigest,
+      );
+      this.remoteSessionAudit?.record({
+        sessionId,
+        actor: payload.mobilePeerId,
+        action: "device.join-reconciled",
+        detail: {
+          via: "relay",
+          principalId: receipt.principalId,
+          sessionEpoch: receipt.sessionEpoch,
+          membershipEpoch: receipt.membershipEpoch,
+        },
+      });
+      this.remoteSessionRelay.sendEncrypted(
+        payload.mobilePeerId,
+        crypto.encrypt(payload.mobilePeerId, {
+          type: "pair.accepted",
+          remoteSessionId: sessionId,
+          principalId: receipt.principalId,
+          sessionEpoch: receipt.sessionEpoch,
+          membershipEpoch: receipt.membershipEpoch,
+          scopes: [...receipt.scopes],
+          capabilities: [...receipt.capabilities],
+          reconciled: true,
+        }),
+      );
+      return;
+    }
+
+    let pendingRetry = null;
+    if (hasPendingCommittedAcceptance) {
+      try {
+        pendingRetry = crypto.decryptPendingCommittedRelayAcceptance(
+          payload.mobilePeerId,
+          payload.envelope,
+        );
+      } catch (error) {
+        if (!token) throw error;
+      }
+    }
+    if (pendingRetry) {
+      const join = pendingRetry;
+      if (
+        join.type !== "pair.join" ||
+        join.remoteSessionId !== sessionId ||
+        typeof join.token !== "string"
+      ) {
+        throw new Error("Invalid encrypted Remote Session pairing retry");
+      }
+      crypto.readPendingRelayMembershipRequest(payload.mobilePeerId, {
+        mobilePublicKey: payload.mobilePublicKey,
+        pairingTokenDigest: remoteSessionPairingTokenDigest(join.token),
+        capabilities: join.capabilities,
+      });
+      const membershipCoordinator = this._requireRemoteMembershipCoordinator();
+      const authorityRead = membershipCoordinator.getSessionSnapshot(sessionId);
+      const resolution = crypto.resolvePendingRelayMembershipCommit(
+        payload.mobilePeerId,
+        authorityRead,
+        membershipCoordinator.relayAuthorityDescriptor(),
+      );
+      if (resolution.status === "not-committed") {
+        crypto.discardPendingRelayMembershipCommit(payload.mobilePeerId);
+      } else if (resolution.status !== "committed") {
+        crypto.clearRelayPeer(payload.mobilePeerId);
+        throw new Error(
+          "Remote relay committed membership is no longer active",
+        );
+      } else {
+        const receipt = crypto.readPendingCommittedRelayAcceptance(
+          payload.mobilePeerId,
+          {
+            mobilePublicKey: payload.mobilePublicKey,
+            pairingTokenDigest: remoteSessionPairingTokenDigest(join.token),
+            capabilities: join.capabilities,
+          },
+        );
+        this._assertExactRemoteRelayMembership(
+          sessionId,
+          payload.mobilePeerId,
+          receipt,
+        );
+        crypto.finalizeCommittedRelayAcceptance(payload.mobilePeerId);
+        this._deleteRemoteSessionPairingSecretIfMatches(
+          sessionId,
+          receipt.pairingTokenDigest,
+        );
+        this.remoteSessionAudit?.record({
+          sessionId,
+          actor: payload.mobilePeerId,
+          action: "device.join-reconciled",
+          detail: {
+            via: "relay",
+            principalId: receipt.principalId,
+            sessionEpoch: receipt.sessionEpoch,
+            membershipEpoch: receipt.membershipEpoch,
+          },
+        });
+        this.remoteSessionRelay.sendEncrypted(
+          payload.mobilePeerId,
+          crypto.encrypt(payload.mobilePeerId, {
+            type: "pair.accepted",
+            remoteSessionId: sessionId,
+            principalId: receipt.principalId,
+            sessionEpoch: receipt.sessionEpoch,
+            membershipEpoch: receipt.membershipEpoch,
+            scopes: [...receipt.scopes],
+            capabilities: [...receipt.capabilities],
+            reconciled: true,
+          }),
+        );
+        return;
+      }
+    }
+    if (!token) {
       throw new Error("Remote Session pairing is unavailable or expired");
-    crypto.pair(payload.mobilePeerId, payload.mobilePublicKey, token);
-    const join = crypto.decrypt(payload.envelope);
-    if (join.type !== "pair.join" || join.token !== token) {
+    }
+    const invitation = this.remoteSessions.pairingInvitation(sessionId, token);
+    const durableMembership = Boolean(invitation.session.hostPrincipalId);
+    // A relay peer id is the transport identity for the life of its active
+    // membership. If an existing receipt could not authenticate this frame,
+    // do not let possession of a newer invitation replace that transport with
+    // a different key/principal. In particular, joinRelayMember() commits the
+    // durable coordinator transition before attaching the transport; detecting
+    // the collision there would consume the token and leave an orphan member.
+    // members() refreshes durable state and returns only active memberships, so
+    // a revoked/inactive member whose binding was cleared does not block a
+    // legitimate fresh join.
+    const activeTransportMember = this.remoteSessions
+      .members(sessionId)
+      .find((member) => member.transportClientId === payload.mobilePeerId);
+    if (activeTransportMember) {
+      throw new Error(
+        "Remote relay transport is already bound to an active membership",
+      );
+    }
+    // Derive and authenticate against a candidate key without touching the
+    // live key, replay high-water, or accepted receipt.
+    const membershipCoordinator = durableMembership
+      ? this._requireRemoteMembershipCoordinator()
+      : null;
+    const relayAuthority = membershipCoordinator
+      ? membershipCoordinator.relayAuthorityDescriptor()
+      : null;
+    const stagedPairing = crypto.stageRelayPairing(
+      payload.mobilePeerId,
+      payload.mobilePublicKey,
+      token,
+      payload.envelope,
+      durableMembership
+        ? {
+            authorizedScopes: invitation.scopes,
+            expiresAtMs: invitation.expiresAt,
+            ...relayAuthority,
+          }
+        : null,
+    );
+    const join = stagedPairing.message;
+    if (
+      join.type !== "pair.join" ||
+      join.remoteSessionId !== sessionId ||
+      join.token !== token
+    ) {
       throw new Error("Invalid encrypted Remote Session pairing request");
     }
-    const relayMember = this.remoteSessions.join({
-      sessionId,
-      clientId: payload.mobilePeerId,
-      token: join.token,
-      via: "relay",
-      pushToken: join.pushToken,
-      pushProvider: join.pushProvider,
-    });
+    const relayPossessionCapability = durableMembership
+      ? stagedPairing.possessionCapability
+      : null;
+    let relayMember;
+    let committedReceipt = null;
+    if (durableMembership) {
+      const expectedScopes = invitation.scopes.filter(
+        (scope) =>
+          scope !== "approve" ||
+          (Array.isArray(join.capabilities) &&
+            join.capabilities.includes(REMOTE_APPROVAL_BINDING_CAPABILITY)),
+      );
+      const authorityBefore =
+        membershipCoordinator.getSessionSnapshot(sessionId);
+      if (!authorityBefore) {
+        throw new Error("Remote relay membership authority is unavailable");
+      }
+      // The prepared record exists before the durable call. If the coordinator
+      // commits but the registry return path or the very next instruction
+      // fails, a later authenticated retry can adjudicate against a fresh
+      // authority snapshot without replaying the one-time join.
+      crypto.armPendingRelayMembershipCommit(stagedPairing.stage, {
+        authoritySnapshot: authorityBefore.session,
+        scopes: expectedScopes,
+        capabilities: join.capabilities,
+      });
+      try {
+        relayMember = this.remoteSessions.joinRelayMember({
+          sessionId,
+          transportClientId: payload.mobilePeerId,
+          token: join.token,
+          // Mobile/web clients send a raw 32-byte X25519 key. The authenticated
+          // relay transcript canonicalizes that key to SPKI; use the bound proof
+          // value rather than reparsing the untrusted transport representation.
+          mobilePublicKey: relayPossessionCapability.mobilePublicKey,
+          pairingTokenDigest: remoteSessionPairingTokenDigest(join.token),
+          possessionCapability: relayPossessionCapability,
+          capabilities: join.capabilities,
+          pushToken: join.pushToken,
+          pushProvider: join.pushProvider,
+        });
+        committedReceipt = crypto.completePendingCommittedRelayAcceptance(
+          payload.mobilePeerId,
+          {
+            mobilePublicKey: relayPossessionCapability.mobilePublicKey,
+            pairingTokenDigest: remoteSessionPairingTokenDigest(join.token),
+            principalId: relayMember.member.principalId,
+            sessionEpoch: relayMember.session.sessionEpoch,
+            membershipEpoch: relayMember.member.membershipEpoch,
+            scopes: relayMember.member.scopes,
+            capabilities: relayMember.capabilities,
+            statement: relayMember.statement,
+          },
+        );
+      } catch (error) {
+        try {
+          const freshAuthority =
+            membershipCoordinator.getSessionSnapshot(sessionId);
+          const resolution = crypto.resolvePendingRelayMembershipCommit(
+            payload.mobilePeerId,
+            freshAuthority,
+            relayAuthority,
+          );
+          if (resolution.status === "not-committed") {
+            crypto.discardPendingRelayMembershipCommit(payload.mobilePeerId);
+          } else if (resolution.status === "fenced") {
+            crypto.clearRelayPeer(payload.mobilePeerId);
+          }
+        } catch {
+          // Keep the prepared record if the fresh authority read itself is
+          // unavailable. Guessing non-commit here could erase the only
+          // in-process evidence for an already-durable membership.
+        }
+        throw error;
+      }
+      this._assertExactRemoteRelayMembership(
+        sessionId,
+        payload.mobilePeerId,
+        committedReceipt,
+      );
+      crypto.finalizeCommittedRelayAcceptance(payload.mobilePeerId);
+    } else {
+      relayMember = this.remoteSessions.join({
+        sessionId,
+        clientId: payload.mobilePeerId,
+        token: join.token,
+        via: "relay",
+        pushToken: join.pushToken,
+        pushProvider: join.pushProvider,
+      });
+      crypto.commitStagedRelayPairing(stagedPairing.stage);
+    }
     this.remoteSessionAudit?.record({
       sessionId,
       actor: payload.mobilePeerId,
@@ -1443,14 +1888,24 @@ export class ChainlessChainWSServer extends EventEmitter {
       detail: {
         via: "relay",
         hasPush: relayMember?.member?.pushToken ? true : false,
+        scopes: relayMember?.member?.scopes || null,
+        capabilities: relayMember?.capabilities || [],
       },
     });
-    this.remoteSessionPairingSecrets.delete(sessionId);
+    this._deleteRemoteSessionPairingSecretIfMatches(
+      sessionId,
+      remoteSessionPairingTokenDigest(join.token),
+    );
     this.remoteSessionRelay.sendEncrypted(
       payload.mobilePeerId,
       crypto.encrypt(payload.mobilePeerId, {
         type: "pair.accepted",
         remoteSessionId: sessionId,
+        principalId: relayMember?.member?.principalId || null,
+        sessionEpoch: relayMember?.session?.sessionEpoch || null,
+        membershipEpoch: relayMember?.member?.membershipEpoch || null,
+        scopes: relayMember?.member?.scopes || null,
+        capabilities: relayMember?.capabilities || [],
       }),
     );
   }
@@ -1464,6 +1919,11 @@ export class ChainlessChainWSServer extends EventEmitter {
       readyState: 1,
       send: (raw) => {
         const response = JSON.parse(raw);
+        try {
+          this.remoteSessions.authorize(envelope.sessionId, from, "observe");
+        } catch {
+          return;
+        }
         this.remoteSessionRelay.sendEncrypted(
           from,
           crypto.encrypt(from, response),