chainlesschain 0.163.7 → 0.164.0

package/src/harness/remote-session-crypto.js

@@ -12,6 +12,15 @@ import {
 
 const PROTOCOL = "chainlesschain.remote-session.e2ee.v1";
 const PAIRING_SCHEME = "chainlesschain://remote-session/pair#";
+const RELAY_POSSESSION_SCHEMA =
+  "chainlesschain.remote-session.relay-possession-capability/v1";
+const relayPossessionCapabilities = new WeakMap();
+const RELAY_AUTHORITY_SCOPES = new Set([
+  "observe",
+  "prompt",
+  "approve",
+  "interrupt",
+]);
 
 function b64(value) {
   return Buffer.from(value).toString("base64url");
@@ -34,6 +43,91 @@ function importPublicKey(value) {
   return createPublicKey({ key: der, type: "spki", format: "der" });
 }
 
+function canonicalPublicKey(value) {
+  const key = importPublicKey(value);
+  if (key.asymmetricKeyType !== "x25519") {
+    throw new Error("Remote Session peer key must be X25519");
+  }
+  return exportPublicKey(key);
+}
+
+function digest(domain, value) {
+  return createHash("sha256")
+    .update(domain, "utf8")
+    .update("\0", "utf8")
+    .update(value)
+    .digest("hex");
+}
+
+export function remoteSessionPairingTokenDigest(pairingToken) {
+  if (typeof pairingToken !== "string" || pairingToken.length === 0) {
+    throw new Error("Remote Session pairing token is required");
+  }
+  return digest("chainlesschain.remote-session.pairing-token.v1", pairingToken);
+}
+
+function relayEnvelopeTranscriptHash(envelope) {
+  const normalized = {
+    v: envelope.v,
+    sessionId: envelope.sessionId,
+    senderId: envelope.senderId,
+    sequence: envelope.sequence,
+    nonce: envelope.nonce,
+    ciphertext: envelope.ciphertext,
+    tag: envelope.tag,
+  };
+  return digest(
+    "chainlesschain.remote-session.relay-envelope.v1",
+    JSON.stringify(normalized),
+  );
+}
+
+export function consumeRemoteRelayPossessionCapability(
+  capability,
+  {
+    sessionId,
+    mobilePeerId,
+    mobilePublicKey,
+    pairingTokenDigest,
+    coordinatorId,
+    serverInstanceId,
+    authorityVersion,
+  } = {},
+) {
+  const proof = relayPossessionCapabilities.get(capability);
+  // Consume before checking the caller's expectation. A confused-deputy or
+  // stale binding attempt cannot probe and then reuse the capability.
+  relayPossessionCapabilities.delete(capability);
+  const expectedPublicKey = canonicalPublicKey(mobilePublicKey);
+  if (
+    !proof ||
+    proof.sessionId !== sessionId ||
+    proof.mobilePeerId !== mobilePeerId ||
+    proof.mobilePublicKey !== expectedPublicKey ||
+    proof.pairingTokenDigest !== pairingTokenDigest ||
+    proof.coordinatorId !== coordinatorId ||
+    proof.serverInstanceId !== serverInstanceId ||
+    proof.authorityVersion !== authorityVersion
+  ) {
+    throw new Error("Remote relay possession capability is invalid or stale");
+  }
+  return Object.freeze({
+    ...proof,
+    authorizedScopes: Object.freeze([...proof.authorizedScopes]),
+  });
+}
+
+function normalizeRelayAuthorityScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new Error("Durable Remote relay scopes are required");
+  }
+  const normalized = [...new Set(scopes.map(String))].sort();
+  if (normalized.some((scope) => !RELAY_AUTHORITY_SCOPES.has(scope))) {
+    throw new Error("Durable Remote relay scopes are invalid");
+  }
+  return Object.freeze(normalized);
+}
+
 function aad(sessionId, senderId, sequence) {
   return Buffer.from(
     `${PROTOCOL}\n${sessionId}\n${senderId}\n${sequence}`,
@@ -121,7 +215,13 @@ export function parseRemotePairingUri(uri, now = Date.now()) {
 }
 
 export class RemoteSessionCryptoContext {
-  constructor({ sessionId, localPeerId, privateKey, publicKey } = {}) {
+  constructor({
+    sessionId,
+    localPeerId,
+    privateKey,
+    publicKey,
+    now = () => Date.now(),
+  } = {}) {
     if (!sessionId || !localPeerId)
       throw new Error("sessionId and localPeerId are required");
     let keyPair;
@@ -134,23 +234,88 @@ export class RemoteSessionCryptoContext {
       format: "der",
     });
     this.publicKey = publicKey || keyPair.publicKey;
+    this._now = now;
     this.keys = new Map();
+    this.pairingMaterial = new Map();
+    this.pendingRelayCapabilities = new Map();
+    this.outstandingRelayCapabilities = new Map();
     this.sendSequence = 0;
     this.receivedSequences = new Map();
   }
 
   pair(peerId, peerPublicKey, pairingToken) {
+    return this._pair(peerId, peerPublicKey, pairingToken, null);
+  }
+
+  pairForDurableMembership(
+    peerId,
+    peerPublicKey,
+    pairingToken,
+    {
+      authorizedScopes,
+      expiresAtMs,
+      coordinatorId,
+      serverInstanceId,
+      authorityVersion,
+    } = {},
+  ) {
+    const normalizedExpiry = Number(expiresAtMs);
+    if (
+      !Number.isSafeInteger(normalizedExpiry) ||
+      normalizedExpiry <= this._now()
+    ) {
+      throw new Error("Durable Remote relay pairing authority is expired");
+    }
+    if (
+      typeof coordinatorId !== "string" ||
+      coordinatorId.length === 0 ||
+      typeof serverInstanceId !== "string" ||
+      serverInstanceId.length === 0 ||
+      typeof authorityVersion !== "string" ||
+      authorityVersion.length === 0
+    ) {
+      throw new Error("Durable Remote relay authority domain is required");
+    }
+    return this._pair(peerId, peerPublicKey, pairingToken, {
+      authorizedScopes: normalizeRelayAuthorityScopes(authorizedScopes),
+      expiresAtMs: normalizedExpiry,
+      coordinatorId,
+      serverInstanceId,
+      authorityVersion,
+    });
+  }
+
+  _pair(peerId, peerPublicKey, pairingToken, durableAuthority) {
     if (!peerId || !peerPublicKey || !pairingToken)
       throw new Error("Incomplete peer key material");
+    // Preserve the legacy re-pair/rotated-token behavior. Re-pairing replaces
+    // the transport key, but first invalidates any not-yet-consumed authority
+    // capability minted under the old key/token tuple.
+    const outstandingCapability = this.outstandingRelayCapabilities.get(peerId);
+    if (outstandingCapability) {
+      relayPossessionCapabilities.delete(outstandingCapability);
+    }
+    this.pendingRelayCapabilities.delete(peerId);
+    this.outstandingRelayCapabilities.delete(peerId);
+    const normalizedPublicKey = canonicalPublicKey(peerPublicKey);
     this.keys.set(
       peerId,
       deriveKey(
         this.privateKey,
-        importPublicKey(peerPublicKey),
+        importPublicKey(normalizedPublicKey),
         this.sessionId,
         pairingToken,
       ),
     );
+    this.pairingMaterial.set(peerId, {
+      mobilePublicKey: normalizedPublicKey,
+      pairingTokenDigest: remoteSessionPairingTokenDigest(pairingToken),
+      authorizedScopes: durableAuthority?.authorizedScopes || null,
+      expiresAtMs: durableAuthority?.expiresAtMs || null,
+      coordinatorId: durableAuthority?.coordinatorId || null,
+      serverInstanceId: durableAuthority?.serverInstanceId || null,
+      authorityVersion: durableAuthority?.authorityVersion || null,
+    });
   }
 
   encrypt(peerId, message) {
@@ -207,6 +372,38 @@ export class RemoteSessionCryptoContext {
       ]);
       const message = JSON.parse(plaintext.toString("utf8"));
       this.receivedSequences.set(envelope.senderId, envelope.sequence);
+      const pairing = this.pairingMaterial.get(envelope.senderId);
+      if (
+        pairing &&
+        pairing.authorizedScopes !== null &&
+        pairing.coordinatorId !== null &&
+        pairing.serverInstanceId !== null &&
+        pairing.authorityVersion !== null &&
+        pairing.expiresAtMs > this._now() &&
+        message?.type === "pair.join" &&
+        typeof message.token === "string" &&
+        remoteSessionPairingTokenDigest(message.token) ===
+          pairing.pairingTokenDigest
+      ) {
+        const proof = Object.freeze({
+          schema: RELAY_POSSESSION_SCHEMA,
+          sessionId: this.sessionId,
+          mobilePeerId: envelope.senderId,
+          mobilePublicKey: pairing.mobilePublicKey,
+          pairingTokenDigest: pairing.pairingTokenDigest,
+          coordinatorId: pairing.coordinatorId,
+          serverInstanceId: pairing.serverInstanceId,
+          authorityVersion: pairing.authorityVersion,
+          authorizedScopes: pairing.authorizedScopes,
+          pairingExpiresAtMs: pairing.expiresAtMs,
+          envelopeSequence: envelope.sequence,
+          envelopeTranscriptHash: relayEnvelopeTranscriptHash(envelope),
+        });
+        relayPossessionCapabilities.set(proof, { ...proof });
+        this.pendingRelayCapabilities.set(envelope.senderId, proof);
+        this.outstandingRelayCapabilities.set(envelope.senderId, proof);
+        this.pairingMaterial.delete(envelope.senderId);
+      }
       return message;
     } catch (error) {
       throw new Error(
@@ -214,4 +411,15 @@ export class RemoteSessionCryptoContext {
       );
     }
   }
+
+  takeRelayPossessionCapability(peerId) {
+    const capability = this.pendingRelayCapabilities.get(peerId);
+    this.pendingRelayCapabilities.delete(peerId);
+    if (!capability) {
+      throw new Error(
+        "No authenticated Remote relay pairing transcript is available",
+      );
+    }
+    return capability;
+  }
 }

package/src/harness/remote-session-registry.js

@@ -167,6 +167,12 @@ function publicSession(session) {
     createdAt: session.createdAt,
     expiresAt: session.expiresAt,
     memberCount: session.members.size,
+    ...(session.membershipAuthority
+      ? {
+          membershipAuthority: session.membershipAuthority,
+          sessionEpoch: session.sessionEpoch,
+        }
+      : {}),
   };
 }
 
@@ -177,21 +183,54 @@ export class RemoteSessionRegistry {
     this.tokenTtlMs = options.tokenTtlMs || DEFAULT_TOKEN_TTL_MS;
     this.sessionTtlMs = options.sessionTtlMs || DEFAULT_SESSION_TTL_MS;
     this.policy = options.policy || new RemoteSessionPolicy();
+    // A factory keeps ordinary/in-memory Remote Session tests and deployments
+    // from touching the machine security store. Client-hosted approval bridges
+    // explicitly require this authority and trigger its lazy construction.
+    this._membershipAuthority = options.membershipAuthority ?? null;
     this.sessions = new Map();
     this.tokens = new Map();
   }
 
-  create({ hostClientId, agentSessionId, name, scopes } = {}) {
+  _requireMembershipAuthority() {
+    if (typeof this._membershipAuthority === "function") {
+      this._membershipAuthority = this._membershipAuthority();
+    }
+    if (!this._membershipAuthority) {
+      throw new Error(
+        "Durable Remote membership authority is required for client-hosted approvals",
+      );
+    }
+    return this._membershipAuthority;
+  }
+
+  create({
+    hostClientId,
+    agentSessionId,
+    name,
+    scopes,
+    durableMembership = false,
+  } = {}) {
     if (!hostClientId) throw new Error("hostClientId is required");
     if (!agentSessionId) throw new Error("agentSessionId is required");
     const now = this.now();
+    const expiresAt = now + this.policy.capSessionTtl(this.sessionTtlMs);
+    const sessionId = randomUUID();
+    const durable = durableMembership
+      ? this._requireMembershipAuthority().createSession({
+          sessionId,
+          agentSessionId,
+          hostPrincipalId: hostClientId,
+          scopes: REMOTE_SESSION_SCOPES,
+          expiresAt,
+        })
+      : null;
     const session = {
-      sessionId: randomUUID(),
+      sessionId,
       agentSessionId,
       name: name || agentSessionId,
       hostClientId,
       createdAt: now,
-      expiresAt: now + this.policy.capSessionTtl(this.sessionTtlMs),
+      expiresAt,
       members: new Map([
         [
           hostClientId,
@@ -199,9 +238,16 @@ export class RemoteSessionRegistry {
             clientId: hostClientId,
             scopes: REMOTE_SESSION_SCOPES,
             joinedAt: now,
+            ...(durable ? { membershipEpoch: durable.membershipEpoch } : {}),
           },
         ],
       ]),
+      ...(durable
+        ? {
+            membershipAuthority: durable.authorityVersion,
+            sessionEpoch: durable.sessionEpoch,
+          }
+        : {}),
     };
     this.sessions.set(session.sessionId, session);
     return {
@@ -251,6 +297,9 @@ export class RemoteSessionRegistry {
     if (!tokensMatch(token, pairing.digest)) {
       throw new Error("Invalid pairing token");
     }
+    if (clientId === session.hostClientId) {
+      throw new Error("Cannot replace the host membership through pairing");
+    }
     // Org policy is enforced only after the token proves the caller is invited,
     // so a device-limit / relay-disabled message never leaks to unauthenticated
     // probes. Existing (non-host) devices count against the limit.
@@ -258,8 +307,17 @@ export class RemoteSessionRegistry {
       (member) => member.clientId !== session.hostClientId,
     ).length;
     this.policy.enforceJoin({ deviceCount, via });
+    const durable = session.membershipAuthority
+      ? this._requireMembershipAuthority().joinMember({
+          sessionId,
+          principalId: clientId,
+          scopes: pairing.scopes,
+          expectedSessionEpoch: session.sessionEpoch,
+        })
+      : null;
     // Pairing credentials are deliberately one-time. The host must explicitly
-    // issue another token for each additional device.
+    // issue another token for each additional device. For durable sessions the
+    // authority commit happens first, so a persistence failure stays retryable.
     this.tokens.delete(sessionId);
     const member = {
       clientId,
@@ -267,6 +325,7 @@ export class RemoteSessionRegistry {
       joinedAt: this.now(),
       pushToken: pushToken || null,
       pushProvider: pushToken ? pushProvider || null : null,
+      ...(durable ? { membershipEpoch: durable.membershipEpoch } : {}),
     };
     session.members.set(clientId, member);
     return { session: publicSession(session), member: { ...member } };
@@ -311,13 +370,41 @@ export class RemoteSessionRegistry {
 
   authorize(sessionId, clientId, scope) {
     const session = this.requireSession(sessionId);
+    if (session.membershipQuarantined) {
+      throw new Error(
+        "Remote membership session is quarantined after an unknown durable transition",
+      );
+    }
     const member = session.members.get(clientId);
     if (!member)
       throw new Error("Client is not paired with this remote session");
+    if (member.membershipQuarantined) {
+      throw new Error(
+        "Remote membership is quarantined after an unknown durable transition",
+      );
+    }
     if (!member.scopes.includes(scope)) {
       throw new Error(`Remote session scope required: ${scope}`);
     }
-    return { session, member };
+    let membership = null;
+    if (session.membershipAuthority) {
+      const verdict = this._requireMembershipAuthority().readMembership(
+        {
+          sessionId,
+          principalId: clientId,
+          sessionEpoch: session.sessionEpoch,
+          membershipEpoch: member.membershipEpoch,
+        },
+        scope,
+      );
+      if (!verdict.ok) {
+        throw new Error(
+          `Remote membership authority denied: ${verdict.reason}`,
+        );
+      }
+      membership = verdict.binding;
+    }
+    return { session, member, membership };
   }
 
   members(sessionId) {
@@ -364,6 +451,21 @@ export class RemoteSessionRegistry {
     const member = session.members.get(clientId);
     if (!member)
       throw new Error("Device is not paired with this remote session");
+    if (session.membershipAuthority) {
+      try {
+        this._requireMembershipAuthority().revokeMember({
+          sessionId,
+          principalId: clientId,
+          expectedSessionEpoch: session.sessionEpoch,
+          expectedMembershipEpoch: member.membershipEpoch,
+        });
+      } catch (error) {
+        // The durable outcome may be unknown. Keep the record for diagnostics,
+        // but locally quarantine it so no later frame can authorize.
+        member.membershipQuarantined = true;
+        throw error;
+      }
+    }
     session.members.delete(clientId);
     return { session: publicSession(session), member: { ...member } };
   }
@@ -385,12 +487,39 @@ export class RemoteSessionRegistry {
   removeClient(clientId) {
     const affected = [];
     for (const [sessionId, session] of this.sessions) {
-      if (!session.members.delete(clientId)) continue;
+      const member = session.members.get(clientId);
+      if (!member) continue;
       if (session.hostClientId === clientId) {
+        if (session.membershipAuthority) {
+          try {
+            this._requireMembershipAuthority().closeSession({
+              sessionId,
+              hostPrincipalId: clientId,
+              expectedSessionEpoch: session.sessionEpoch,
+            });
+          } catch (error) {
+            session.membershipQuarantined = true;
+            throw error;
+          }
+        }
         this.sessions.delete(sessionId);
         this.tokens.delete(sessionId);
         affected.push({ sessionId, closed: true });
       } else {
+        if (session.membershipAuthority) {
+          try {
+            this._requireMembershipAuthority().revokeMember({
+              sessionId,
+              principalId: clientId,
+              expectedSessionEpoch: session.sessionEpoch,
+              expectedMembershipEpoch: member.membershipEpoch,
+            });
+          } catch (error) {
+            member.membershipQuarantined = true;
+            throw error;
+          }
+        }
+        session.members.delete(clientId);
         affected.push({ sessionId, closed: false });
       }
     }
@@ -402,6 +531,18 @@ export class RemoteSessionRegistry {
     if (session.hostClientId !== clientId) {
       throw new Error("Only the host can close a Remote Session");
     }
+    if (session.membershipAuthority) {
+      try {
+        this._requireMembershipAuthority().closeSession({
+          sessionId,
+          hostPrincipalId: clientId,
+          expectedSessionEpoch: session.sessionEpoch,
+        });
+      } catch (error) {
+        session.membershipQuarantined = true;
+        throw error;
+      }
+    }
     this.sessions.delete(sessionId);
     this.tokens.delete(sessionId);
     return publicSession(session);
@@ -411,6 +552,18 @@ export class RemoteSessionRegistry {
     const session = this.sessions.get(sessionId);
     if (!session) throw new Error("Remote session not found");
     if (session.expiresAt <= this.now()) {
+      if (session.membershipAuthority) {
+        try {
+          this._requireMembershipAuthority().closeSession({
+            sessionId,
+            hostPrincipalId: session.hostClientId,
+            expectedSessionEpoch: session.sessionEpoch,
+          });
+        } catch (error) {
+          session.membershipQuarantined = true;
+          throw error;
+        }
+      }
       this.sessions.delete(sessionId);
       this.tokens.delete(sessionId);
       throw new Error("Remote session expired");