chainlesschain 0.162.143 → 0.162.148

package/src/gateways/remote-session-relay.js

@@ -0,0 +1,160 @@
+import { EventEmitter } from "events";
+import WebSocket from "ws";
+
+export class RemoteSessionRelay extends EventEmitter {
+  constructor({
+    relayUrl,
+    peerId,
+    deviceType = "remote-session",
+    websocketFactory,
+    reconnectBaseMs = 500,
+    reconnectMaxMs = 30_000,
+    maxReconnectAttempts = Infinity,
+    queueLimit = 100,
+    setTimer = setTimeout,
+    clearTimer = clearTimeout,
+  } = {}) {
+    super();
+    if (!relayUrl || !peerId)
+      throw new Error("relayUrl and peerId are required");
+    this.relayUrl = relayUrl;
+    this.peerId = peerId;
+    this.deviceType = deviceType;
+    this.websocketFactory = websocketFactory || ((url) => new WebSocket(url));
+    this.ws = null;
+    this.reconnectBaseMs = reconnectBaseMs;
+    this.reconnectMaxMs = reconnectMaxMs;
+    this.maxReconnectAttempts = maxReconnectAttempts;
+    this.queueLimit = queueLimit;
+    this.setTimer = setTimer;
+    this.clearTimer = clearTimer;
+    this.reconnectAttempts = 0;
+    this.reconnectTimer = null;
+    this.outbox = [];
+    this.closedExplicitly = false;
+    this.connectPromise = null;
+  }
+
+  connect() {
+    if (this.ws && this.ws.readyState === this.ws.OPEN)
+      return Promise.resolve();
+    if (this.connectPromise) return this.connectPromise;
+    this.closedExplicitly = false;
+    this.connectPromise = new Promise((resolve, reject) => {
+      const ws = this.websocketFactory(this.relayUrl);
+      this.ws = ws;
+      const onOpen = () => {
+        this._send({
+          type: "register",
+          peerId: this.peerId,
+          deviceType: this.deviceType,
+          deviceInfo: { protocol: "remote-session.e2ee.v1" },
+        });
+        this.reconnectAttempts = 0;
+        this.connectPromise = null;
+        this._flushOutbox();
+        this.emit("connect");
+        resolve();
+      };
+      ws.once("open", onOpen);
+      ws.once("error", (error) => {
+        this.connectPromise = null;
+        reject(error);
+      });
+      ws.on("message", (raw) => this._handleMessage(raw));
+      ws.on("close", () => {
+        if (this.ws === ws) this.ws = null;
+        this.connectPromise = null;
+        this.emit("disconnect");
+        this._scheduleReconnect();
+      });
+    });
+    return this.connectPromise;
+  }
+
+  sendEncrypted(targetPeerId, envelope) {
+    const message = {
+      type: "message",
+      to: targetPeerId,
+      payload: { type: "remote-session.encrypted", envelope },
+    };
+    if (!this.ws || this.ws.readyState !== this.ws.OPEN) {
+      if (this.outbox.length >= this.queueLimit) this.outbox.shift();
+      this.outbox.push(message);
+      this.emit("queued", { size: this.outbox.length });
+      return false;
+    }
+    this._send(message);
+    return true;
+  }
+
+  close() {
+    this.closedExplicitly = true;
+    if (this.reconnectTimer) {
+      this.clearTimer(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+    this.ws = null;
+  }
+
+  _scheduleReconnect() {
+    if (
+      this.closedExplicitly ||
+      this.reconnectTimer ||
+      this.reconnectAttempts >= this.maxReconnectAttempts
+    ) {
+      return;
+    }
+    const delay = Math.min(
+      this.reconnectBaseMs * 2 ** this.reconnectAttempts,
+      this.reconnectMaxMs,
+    );
+    this.reconnectAttempts += 1;
+    this.emit("reconnecting", { attempt: this.reconnectAttempts, delay });
+    this.reconnectTimer = this.setTimer(() => {
+      this.reconnectTimer = null;
+      this.connect().catch((error) => {
+        this.emit("reconnect-error", error);
+        this._scheduleReconnect();
+      });
+    }, delay);
+    if (typeof this.reconnectTimer?.unref === "function")
+      this.reconnectTimer.unref();
+  }
+
+  _flushOutbox() {
+    const pending = this.outbox.splice(0);
+    for (const message of pending) this._send(message);
+    if (pending.length) this.emit("flushed", { count: pending.length });
+  }
+
+  _send(message) {
+    if (!this.ws || this.ws.readyState !== this.ws.OPEN) {
+      throw new Error("Remote Session relay is not connected");
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+
+  _handleMessage(raw) {
+    let message;
+    try {
+      message = JSON.parse(raw.toString("utf8"));
+    } catch {
+      this.emit("protocol-error", new Error("Invalid signaling relay JSON"));
+      return;
+    }
+    if (message.type === "offline-message") message = message.originalMessage;
+    if (
+      message?.type === "message" &&
+      message.payload?.type === "remote-session.encrypted"
+    ) {
+      this.emit("encrypted-message", {
+        from: message.from,
+        envelope: message.payload.envelope,
+      });
+      return;
+    }
+    this.emit("relay-message", message);
+  }
+}

package/src/gateways/ws/message-dispatcher.js

@@ -7,6 +7,18 @@ import {
   PERSONAL_DATA_HUB_HANDLERS,
   PERSONAL_DATA_HUB_STREAMING_HANDLERS,
 } from "./personal-data-hub-protocol.js";
+import {
+  handleRemoteSessionAudit,
+  handleRemoteSessionCreate,
+  handleRemoteSessionClose,
+  handleRemoteSessionDevices,
+  handleRemoteSessionJoin,
+  handleRemoteSessionPairingToken,
+  handleRemoteSessionPolicy,
+  handleRemoteSessionPublish,
+  handleRemoteSessionPushRegister,
+  handleRemoteSessionRevoke,
+} from "./remote-session-protocol.js";
 
 export function createWsMessageDispatcher(server) {
   return {
@@ -54,6 +66,26 @@ export function createWsMessageDispatcher(server) {
           server._handleSessionInterrupt(id, ws, message),
         "slash-command": () => server._handleSlashCommand(id, ws, message),
         "session-answer": () => server._handleSessionAnswer(id, ws, message),
+        "remote-session-create": () =>
+          handleRemoteSessionCreate(server, clientId, ws, message),
+        "remote-session-close": () =>
+          handleRemoteSessionClose(server, clientId, ws, message),
+        "remote-session-pairing-token": () =>
+          handleRemoteSessionPairingToken(server, clientId, ws, message),
+        "remote-session-join": () =>
+          handleRemoteSessionJoin(server, clientId, ws, message),
+        "remote-session-devices": () =>
+          handleRemoteSessionDevices(server, clientId, ws, message),
+        "remote-session-audit": () =>
+          handleRemoteSessionAudit(server, clientId, ws, message),
+        "remote-session-policy": () =>
+          handleRemoteSessionPolicy(server, clientId, ws, message),
+        "remote-session-push-register": () =>
+          handleRemoteSessionPushRegister(server, clientId, ws, message),
+        "remote-session-revoke": () =>
+          handleRemoteSessionRevoke(server, clientId, ws, message),
+        "remote-session-publish": () =>
+          handleRemoteSessionPublish(server, clientId, ws, message),
         "host-tool-result": () => server._handleHostToolResult(id, ws, message),
         orchestrate: () => server._handleOrchestrate(id, ws, message),
         "cowork-task": () => server._handleCoworkTask(id, ws, message),

package/src/gateways/ws/remote-session-protocol.js

@@ -0,0 +1,429 @@
+import {
+  handleSessionAnswer,
+  handleSessionInterrupt,
+  handleSessionMessage,
+} from "./session-protocol.js";
+import {
+  RemoteSessionCryptoContext,
+  createRemotePairingUri,
+} from "../../harness/remote-session-crypto.js";
+
+const CLIENT_EVENT_SCOPES = Object.freeze({
+  prompt: "prompt",
+  "approval.resolve": "approve",
+  interrupt: "interrupt",
+});
+
+function reply(server, ws, id, type, payload = {}) {
+  server._send(ws, { id, type, ...payload });
+}
+
+function audit(server, entry) {
+  server.remoteSessionAudit?.record(entry);
+}
+
+function attachPairingUri(server, result) {
+  const relayUrl = server.remoteSessionRelayUrl;
+  const hostPeerId = server.remoteSessionPeerId;
+  if (!relayUrl || !hostPeerId) return result;
+  server.remoteSessionPairingSecrets.set(
+    result.session.sessionId,
+    result.pairing.token,
+  );
+  let crypto = server.remoteSessionCrypto.get(result.session.sessionId);
+  if (!crypto) {
+    crypto = new RemoteSessionCryptoContext({
+      sessionId: result.session.sessionId,
+      localPeerId: hostPeerId,
+    });
+    server.remoteSessionCrypto.set(result.session.sessionId, crypto);
+  }
+  return {
+    ...result,
+    pairing: {
+      ...result.pairing,
+      hostPublicKey: crypto.publicKey,
+      uri: createRemotePairingUri({
+        relayUrl,
+        remoteSessionId: result.session.sessionId,
+        hostPeerId,
+        hostPublicKey: crypto.publicKey,
+        pairingToken: result.pairing.token,
+        expiresAt: result.pairing.expiresAt,
+      }),
+    },
+  };
+}
+
+export function handleRemoteSessionCreate(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.create({
+      hostClientId: clientId,
+      agentSessionId: message.sessionId,
+      name: message.name,
+      scopes: message.scopes,
+    });
+    audit(server, {
+      sessionId: result.session.sessionId,
+      actor: clientId,
+      action: "session.created",
+      detail: { agentSessionId: message.sessionId, name: message.name || null },
+    });
+    reply(
+      server,
+      ws,
+      message.id,
+      "remote-session-created",
+      attachPairingUri(server, result),
+    );
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_CREATE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPairingToken(server, clientId, ws, message) {
+  try {
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      "observe",
+    );
+    if (session.hostClientId !== clientId) {
+      throw new Error("Only the host can issue pairing tokens");
+    }
+    const pairing = server.remoteSessions.issuePairingToken(
+      message.remoteSessionId,
+      { scopes: message.scopes },
+    );
+    const result = attachPairingUri(server, {
+      session: {
+        sessionId: message.remoteSessionId,
+      },
+      pairing,
+    });
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "pairing-token.issued",
+      detail: { scopes: message.scopes || null, expiresAt: pairing.expiresAt },
+    });
+    reply(server, ws, message.id, "remote-session-pairing-token", {
+      pairing: result.pairing,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PAIRING_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionJoin(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.join({
+      sessionId: message.remoteSessionId,
+      clientId,
+      token: message.token,
+      pushToken: message.pushToken,
+      pushProvider: message.pushProvider,
+    });
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "device.joined",
+      detail: {
+        scopes: result.member.scopes,
+        via: "direct",
+        hasPush: result.member.pushToken ? true : false,
+      },
+    });
+    reply(server, ws, message.id, "remote-session-joined", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_JOIN_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPushRegister(server, clientId, ws, message) {
+  try {
+    // A device may only register its OWN token (clientId is the authenticated
+    // caller). Storing no push value clears it.
+    const result = server.remoteSessions.registerPush(
+      message.remoteSessionId,
+      clientId,
+      { token: message.pushToken, provider: message.pushProvider },
+    );
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "push.registered",
+      detail: { hasPush: result.hasPush, provider: result.provider },
+    });
+    reply(server, ws, message.id, "remote-session-push-registered", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PUSH_REGISTER_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionDevices(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.listDevices(
+      message.remoteSessionId,
+      clientId,
+    );
+    reply(server, ws, message.id, "remote-session-devices", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_DEVICES_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPolicy(server, clientId, ws, message) {
+  try {
+    // The active org policy is not sensitive — any authenticated client may
+    // read it (e.g. to pre-check allowed scopes before requesting a session).
+    const policy = server.remoteSessions?.policy;
+    reply(server, ws, message.id, "remote-session-policy", {
+      policy: policy ? policy.describe() : null,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_POLICY_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionAudit(server, clientId, ws, message) {
+  try {
+    // Host-only: authorize proves membership, the host check proves ownership.
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      "observe",
+    );
+    if (session.hostClientId !== clientId) {
+      throw new Error("Only the host can read the audit log");
+    }
+    const auditLog = server.remoteSessionAudit;
+    const entries = auditLog
+      ? auditLog.list({
+          sessionId: message.remoteSessionId,
+          limit: message.limit || 200,
+        })
+      : [];
+    const stats = auditLog
+      ? auditLog.stats(message.remoteSessionId)
+      : { total: 0, byAction: {} };
+    reply(server, ws, message.id, "remote-session-audit", {
+      remoteSessionId: message.remoteSessionId,
+      entries,
+      stats,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_AUDIT_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+/**
+ * Tell a revoked device it is no longer paired. Locally connected clients get a
+ * plaintext `remote-session-revoked` push; relay-paired mobile devices get an
+ * encrypted `session.revoked` control event so they stop auto-reconnecting.
+ */
+function notifyRevokedDevice(
+  server,
+  remoteSessionId,
+  agentSessionId,
+  clientId,
+) {
+  const target = server.clients.get(clientId);
+  if (target) {
+    server._send(target.ws, {
+      type: "remote-session-revoked",
+      remoteSessionId,
+      agentSessionId,
+    });
+    return;
+  }
+  if (!server.remoteSessionRelay) return;
+  const crypto = server.remoteSessionCrypto.get(remoteSessionId);
+  if (!crypto) return;
+  try {
+    server.remoteSessionRelay.sendEncrypted(
+      clientId,
+      crypto.encrypt(clientId, { type: "session.revoked", remoteSessionId }),
+    );
+  } catch {
+    // Peer key may already be gone; the registry removal is what actually
+    // enforces revocation, so a failed courtesy notice is non-fatal.
+  }
+}
+
+export function handleRemoteSessionRevoke(server, clientId, ws, message) {
+  try {
+    const targetClientId = message.clientId || message.deviceId;
+    const { session, member } = server.remoteSessions.revokeMember(
+      message.remoteSessionId,
+      clientId,
+      targetClientId,
+    );
+    notifyRevokedDevice(
+      server,
+      message.remoteSessionId,
+      session.agentSessionId,
+      member.clientId,
+    );
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "device.revoked",
+      detail: { revoked: member.clientId },
+    });
+    reply(server, ws, message.id, "remote-session-revoked", {
+      session,
+      revoked: member.clientId,
+      devices: server.remoteSessions.listDevices(
+        message.remoteSessionId,
+        clientId,
+      ).devices,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_REVOKE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionClose(server, clientId, ws, message) {
+  try {
+    const session = server.remoteSessions.close(
+      message.remoteSessionId,
+      clientId,
+    );
+    server.remoteSessionCrypto.delete(message.remoteSessionId);
+    server.remoteSessionPairingSecrets.delete(message.remoteSessionId);
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "session.closed",
+      detail: { reason: "host-closed" },
+    });
+    reply(server, ws, message.id, "remote-session-closed", { session });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_CLOSE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export async function handleRemoteSessionPublish(
+  server,
+  clientId,
+  ws,
+  message,
+) {
+  try {
+    if (!message.event || typeof message.event.type !== "string") {
+      throw new Error("event.type is required");
+    }
+    const requiredScope = CLIENT_EVENT_SCOPES[message.event.type];
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      requiredScope || "observe",
+    );
+    // Runtime/output events are host-only. Remote clients may publish only the
+    // three explicitly scoped control event types above.
+    if (!requiredScope && session.hostClientId !== clientId) {
+      throw new Error("Only the host can publish runtime events");
+    }
+
+    if (requiredScope && session.hostClientId !== clientId) {
+      const controlMessage = {
+        id: message.id,
+        sessionId: session.agentSessionId,
+      };
+      if (message.event.type === "prompt") {
+        if (
+          typeof message.event.content !== "string" ||
+          !message.event.content.trim()
+        ) {
+          throw new Error("prompt content is required");
+        }
+        // Record the shape, not the content — the audit trail must stay useful
+        // without hoarding potentially sensitive session prompts.
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.prompt",
+          detail: { chars: message.event.content.length },
+        });
+        handleSessionMessage(server, message.id, ws, {
+          ...controlMessage,
+          content: message.event.content,
+        });
+      } else if (message.event.type === "approval.resolve") {
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.approval",
+          detail: {
+            requestId: message.event.requestId || message.event.approvalId,
+            approved: message.event.answer ?? message.event.approved,
+          },
+        });
+        await handleSessionAnswer(server, message.id, ws, {
+          ...controlMessage,
+          requestId: message.event.requestId || message.event.approvalId,
+          answer: message.event.answer ?? message.event.approved,
+        });
+      } else if (message.event.type === "interrupt") {
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.interrupt",
+          detail: null,
+        });
+        await handleSessionInterrupt(server, message.id, ws, controlMessage);
+      }
+      return;
+    }
+
+    let delivered = 0;
+    for (const member of server.remoteSessions.members(
+      message.remoteSessionId,
+    )) {
+      if (member.clientId === clientId) continue;
+      const target = server.clients.get(member.clientId);
+      if (!target) continue;
+      server._send(target.ws, {
+        type: "remote-session-event",
+        remoteSessionId: message.remoteSessionId,
+        agentSessionId: session.agentSessionId,
+        event: message.event,
+      });
+      delivered += 1;
+    }
+    reply(server, ws, message.id, "remote-session-published", { delivered });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PUBLISH_ERROR",
+      message: error.message,
+    });
+  }
+}