@peers-app/peers-ui 0.20.6 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-ui",
-  "version": "0.20.6",
+  "version": "0.21.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-ui.git"
@@ -28,7 +28,7 @@
     "lint:fix": "biome check --write ."
   },
   "peerDependencies": {
-    "@peers-app/peers-sdk": "^0.20.6",
+    "@peers-app/peers-sdk": "^0.21.0",
     "bootstrap": "^5.3.3",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
@@ -39,7 +39,7 @@
     "@babel/preset-react": "^7.24.1",
     "@babel/preset-typescript": "^7.27.1",
     "@biomejs/biome": "2.3.11",
-    "@peers-app/peers-sdk": "0.20.6",
+    "@peers-app/peers-sdk": "0.21.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",

package/src/root-layout/root-layout-host.tsx

@@ -25,6 +25,7 @@ import {
   captureUserConnectInviteFromLocation,
   readUserConnectPendingIntent,
 } from "../screens/contacts/user-connect-invite";
+import { captureDevicePairingInviteFromLocation } from "../screens/device-pairing";
 import { colorMode } from "../screens/settings/color-mode-dropdown";
 import { SetupUser } from "../screens/setup-user";
 import { WelcomeModal } from "../screens/welcome-modal";
@@ -41,6 +42,7 @@ import { selectedRootLayoutId } from "./root-layout-state";
  */
 export function RootLayoutHost() {
   useState(() => {
+    captureDevicePairingInviteFromLocation();
     captureUserConnectInviteFromLocation();
     return true;
   });
@@ -55,6 +57,7 @@ export function RootLayoutHost() {
   useEffect(() => {
     const captureInviteFromHashChange = () => {
       const previousHash = window.location.hash;
+      captureDevicePairingInviteFromLocation();
       captureUserConnectInviteFromLocation();
       if (window.location.hash === previousHash) {
         return;

package/src/screens/device-pairing/device-pairing-invite.test.ts

@@ -0,0 +1,50 @@
+import {
+  createDevicePairingInvitation,
+  createDevicePairingInvitationUrl,
+  parseDevicePairingInvitation,
+} from "@peers-app/peers-sdk";
+import {
+  captureDevicePairingInviteFromLocation,
+  clearPendingDevicePairingInvite,
+  consumePendingDevicePairingInvite,
+  readPendingDevicePairingInvite,
+} from "./device-pairing-invite";
+
+describe("device pairing invitation capture", () => {
+  beforeEach(() => {
+    clearPendingDevicePairingInvite();
+    window.history.replaceState({}, "", "/?app");
+  });
+
+  it("captures the fragment only in memory and removes it from browser history", () => {
+    const invitation = createDevicePairingInvitation({
+      serviceOrigin: "https://peers.app",
+    });
+    const inviteUrl = createDevicePairingInvitationUrl(
+      `${window.location.origin}/?app`,
+      invitation,
+    );
+    window.history.replaceState(
+      {},
+      "",
+      new URL(inviteUrl).pathname + new URL(inviteUrl).search + new URL(inviteUrl).hash,
+    );
+
+    const token = captureDevicePairingInviteFromLocation();
+
+    expect(token).toBeDefined();
+    expect(parseDevicePairingInvitation(token ?? "")).toEqual(invitation);
+    expect(window.location.hash).toBe("");
+    expect(readPendingDevicePairingInvite()).toBe(token);
+    expect(consumePendingDevicePairingInvite()).toBe(token);
+    expect(readPendingDevicePairingInvite()).toBeUndefined();
+  });
+
+  it("ignores invalid fragments without retaining them", () => {
+    window.history.replaceState({}, "", "/?app#pair=invalid");
+
+    expect(captureDevicePairingInviteFromLocation()).toBeUndefined();
+    expect(readPendingDevicePairingInvite()).toBeUndefined();
+    expect(window.location.hash).toBe("");
+  });
+});

package/src/screens/device-pairing/device-pairing-invite.ts

@@ -0,0 +1,55 @@
+import { encodeDevicePairingInvitation, parseDevicePairingInvitation } from "@peers-app/peers-sdk";
+
+let pendingInvitation: string | undefined;
+
+/** Browser event emitted after a pairing invitation is captured and removed from the URL. */
+export const DEVICE_PAIRING_INVITE_CAPTURED_EVENT = "device-pairing:invite-captured";
+
+/** Captures a pairing fragment in memory and immediately removes it from browser history. */
+export function captureDevicePairingInviteFromLocation(
+  location: Location = window.location,
+): string | undefined {
+  if (!location.hash.startsWith("#pair=") && !location.hash.startsWith("#pair?")) {
+    return undefined;
+  }
+  let capturedInvitation: string | undefined;
+  try {
+    capturedInvitation = encodeDevicePairingInvitation(parseDevicePairingInvitation(location.href));
+    pendingInvitation = capturedInvitation;
+    return capturedInvitation;
+  } catch {
+    return undefined;
+  } finally {
+    if (typeof window !== "undefined" && location === window.location) {
+      window.history.replaceState(
+        window.history.state,
+        document.title,
+        `${location.pathname}${location.search}`,
+      );
+      if (capturedInvitation) {
+        window.dispatchEvent(
+          new CustomEvent(DEVICE_PAIRING_INVITE_CAPTURED_EVENT, {
+            detail: capturedInvitation,
+          }),
+        );
+      }
+    }
+  }
+}
+
+/** Returns the in-memory invitation without consuming it. */
+export function readPendingDevicePairingInvite(): string | undefined {
+  return pendingInvitation;
+}
+
+/** Returns and erases the in-memory invitation. */
+export function consumePendingDevicePairingInvite(): string | undefined {
+  const invitation = pendingInvitation;
+  pendingInvitation = undefined;
+  return invitation;
+}
+
+/** Erases any unconsumed invitation. */
+export function clearPendingDevicePairingInvite(): void {
+  pendingInvitation = undefined;
+}

package/src/screens/device-pairing/device-pairing.test.tsx

@@ -0,0 +1,100 @@
+import { type DevicePairingState, rpcServerCalls } from "@peers-app/peers-sdk";
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { DestinationDevicePairing, SourceDevicePairing } from "./device-pairing";
+
+const mockRpc = {
+  startSource: jest.fn(),
+  startDestination: jest.fn(),
+  approve: jest.fn(),
+  reject: jest.fn(),
+  cancel: jest.fn(),
+};
+let mockPairingState: DevicePairingState = { phase: "idle" };
+
+rpcServerCalls.devicePairingStartSource =
+  mockRpc.startSource as typeof rpcServerCalls.devicePairingStartSource;
+rpcServerCalls.devicePairingStartDestination =
+  mockRpc.startDestination as typeof rpcServerCalls.devicePairingStartDestination;
+rpcServerCalls.devicePairingApprove = mockRpc.approve as typeof rpcServerCalls.devicePairingApprove;
+rpcServerCalls.devicePairingReject = mockRpc.reject as typeof rpcServerCalls.devicePairingReject;
+rpcServerCalls.devicePairingCancel = mockRpc.cancel as typeof rpcServerCalls.devicePairingCancel;
+
+jest.mock("./use-device-pairing-state", () => ({
+  useDevicePairingState: () => mockPairingState,
+}));
+
+describe("device pairing UI lifecycle", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockPairingState = { phase: "idle" };
+    mockRpc.cancel.mockResolvedValue({ phase: "idle" });
+  });
+
+  it("uses the host-owned invitation URL and cancels a source that resolves after unmount", async () => {
+    let resolveStart!: (value: { state: DevicePairingState; invitationUrl: string }) => void;
+    mockRpc.startSource.mockReturnValue(
+      new Promise((resolve) => {
+        resolveStart = resolve;
+      }),
+    );
+    const view = render(<SourceDevicePairing onClose={jest.fn()} />);
+
+    expect(mockRpc.startSource).toHaveBeenCalledWith();
+    view.unmount();
+    resolveStart({
+      state: { sessionId: "00mh0wlipkdbeaw8tests0001", role: "source", phase: "inviting" },
+      invitationUrl: "https://peers.app/?app#pair=token",
+    });
+
+    await waitFor(() => {
+      expect(mockRpc.cancel).toHaveBeenCalledWith({
+        sessionId: "00mh0wlipkdbeaw8tests0001",
+      });
+    });
+  });
+
+  it("keeps source cancellation available while waiting for remote approval", async () => {
+    const onClose = jest.fn();
+    mockPairingState = {
+      sessionId: "00mh0wlipkdbeaw8tests0002",
+      role: "source",
+      phase: "waiting-for-approval",
+    };
+    mockRpc.startSource.mockResolvedValue({
+      state: mockPairingState,
+      invitationUrl: "https://peers.app/?app#pair=token",
+    });
+    const view = render(<SourceDevicePairing onClose={onClose} />);
+    await waitFor(() => expect(mockRpc.startSource).toHaveBeenCalled());
+
+    fireEvent.click(view.getByRole("button", { name: "Cancel" }));
+
+    await waitFor(() => {
+      expect(mockRpc.cancel).toHaveBeenCalledWith({
+        sessionId: "00mh0wlipkdbeaw8tests0002",
+      });
+      expect(onClose).toHaveBeenCalled();
+    });
+  });
+
+  it("does not clear the destination success reload when Done unmounts the flow", () => {
+    jest.useFakeTimers();
+    mockPairingState = {
+      sessionId: "00mh0wlipkdbeaw8tests0003",
+      role: "destination",
+      phase: "complete",
+    };
+    const setTimeoutSpy = jest.spyOn(window, "setTimeout");
+    const clearTimeoutSpy = jest.spyOn(window, "clearTimeout");
+    const view = render(<DestinationDevicePairing onBack={jest.fn()} />);
+    const reloadTimer = setTimeoutSpy.mock.calls.find(([, delay]) => delay === 750);
+
+    expect(reloadTimer).toBeDefined();
+    view.unmount();
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+
+    setTimeoutSpy.mockRestore();
+    clearTimeoutSpy.mockRestore();
+    jest.useRealTimers();
+  });
+});

package/src/screens/device-pairing/device-pairing.tsx

@@ -0,0 +1,390 @@
+import { copyToClipboard, type DevicePairingState, rpcServerCalls } from "@peers-app/peers-sdk";
+import { useEffect, useRef, useState } from "react";
+import QRCode from "react-qr-code";
+import { useDevicePairingState } from "./use-device-pairing-state";
+
+function formatCountdown(expiresAt?: number): string {
+  if (!expiresAt) {
+    return "";
+  }
+  const seconds = Math.max(0, Math.ceil((expiresAt - Date.now()) / 1000));
+  return `${Math.floor(seconds / 60)}:${(seconds % 60).toString().padStart(2, "0")}`;
+}
+
+function PairingProgress({ state }: { state: DevicePairingState }) {
+  const messages: Partial<Record<DevicePairingState["phase"], string>> = {
+    inviting: "Waiting for the new device…",
+    connecting: "Establishing a secure connection…",
+    "waiting-for-approval": "Waiting for approval on the other device…",
+    transferring: "Installing encrypted account credentials…",
+  };
+  return (
+    <output className="text-center py-4 d-block">
+      <div className="spinner-border text-primary mb-3" aria-hidden="true" />
+      <p className="text-muted mb-0">{messages[state.phase] ?? "Working…"}</p>
+    </output>
+  );
+}
+
+function PairingComparison(props: {
+  state: DevicePairingState;
+  approving: boolean;
+  onApprove: () => void;
+  onReject: () => void;
+  onCancel: () => void;
+}) {
+  return (
+    <div className="text-center" style={{ maxWidth: 440, margin: "0 auto" }}>
+      <h4>Compare these numbers</h4>
+      <p className="text-muted">
+        Confirm that both devices show the same number and the expected device before approving.
+      </p>
+      <div
+        className="display-4 font-monospace text-primary mb-3"
+        style={{ letterSpacing: "0.12em" }}
+      >
+        {props.state.sas}
+      </div>
+      <p className="mb-4">
+        {props.state.remoteDevice?.deviceName || "Unnamed device"}
+        {props.state.remoteDevice?.deviceType ? ` (${props.state.remoteDevice.deviceType})` : ""}
+      </p>
+      <div className="d-flex gap-2 justify-content-center">
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={props.approving}
+          onClick={props.onApprove}
+        >
+          {props.approving ? "Approving…" : "Numbers match — approve"}
+        </button>
+        <button
+          type="button"
+          className="btn btn-outline-danger"
+          disabled={props.approving}
+          onClick={props.onReject}
+        >
+          Reject
+        </button>
+        <button
+          type="button"
+          className="btn btn-outline-secondary"
+          disabled={props.approving}
+          onClick={props.onCancel}
+        >
+          Cancel
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function TerminalPanel(props: { state: DevicePairingState; onClose: () => void }) {
+  const complete = props.state.phase === "complete";
+  return (
+    <div className="text-center" style={{ maxWidth: 440, margin: "0 auto" }}>
+      <output className={`alert d-block ${complete ? "alert-success" : "alert-warning"}`}>
+        {complete
+          ? "Device added successfully."
+          : props.state.phase === "rejected"
+            ? "Pairing was rejected. No credentials were installed."
+            : props.state.error || "Pairing could not be completed. No credentials were installed."}
+      </output>
+      <button type="button" className="btn btn-outline-secondary" onClick={props.onClose}>
+        {complete ? "Done" : "Back"}
+      </button>
+    </div>
+  );
+}
+
+function ProgressWithCancel(props: { state: DevicePairingState; onCancel: () => void }) {
+  return (
+    <>
+      <PairingProgress state={props.state} />
+      <div className="text-center">
+        <button type="button" className="btn btn-outline-secondary" onClick={props.onCancel}>
+          Cancel
+        </button>
+      </div>
+    </>
+  );
+}
+
+function usePairingSessionLifecycle(state: DevicePairingState) {
+  const sessionId = useRef<string | undefined>(undefined);
+  const phase = useRef<DevicePairingState["phase"]>("idle");
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    if (state.sessionId && state.sessionId === sessionId.current) {
+      phase.current = state.phase;
+    }
+  }, [state.phase, state.sessionId]);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      const activeSessionId = sessionId.current;
+      if (activeSessionId && !["idle", "complete", "rejected", "error"].includes(phase.current)) {
+        void rpcServerCalls
+          .devicePairingCancel({ sessionId: activeSessionId })
+          .catch(() => undefined);
+      }
+    };
+  }, []);
+
+  return { sessionId, phase, mounted };
+}
+
+/** Signed-in source flow opened from Settings. */
+export function SourceDevicePairing(props: { onClose: () => void }) {
+  const state = useDevicePairingState();
+  const lifecycle = usePairingSessionLifecycle(state);
+  const started = useRef(false);
+  const [invitationUrl, setInvitationUrl] = useState("");
+  const [localError, setLocalError] = useState("");
+  const [approving, setApproving] = useState(false);
+  const [, setClock] = useState(0);
+
+  useEffect(() => {
+    if (started.current) {
+      return;
+    }
+    started.current = true;
+    void rpcServerCalls
+      .devicePairingStartSource()
+      .then(async (result) => {
+        lifecycle.sessionId.current = result.state.sessionId;
+        lifecycle.phase.current = result.state.phase;
+        if (!lifecycle.mounted.current && result.state.sessionId) {
+          await rpcServerCalls
+            .devicePairingCancel({ sessionId: result.state.sessionId })
+            .catch(() => undefined);
+          return;
+        }
+        setInvitationUrl(result.invitationUrl);
+      })
+      .catch(() => setLocalError("Could not create a pairing invitation."));
+  }, []);
+
+  useEffect(() => {
+    if (!state.expiresAt) {
+      return;
+    }
+    const timer = window.setInterval(() => setClock((value) => value + 1), 1000);
+    return () => window.clearInterval(timer);
+  }, [state.expiresAt]);
+
+  useEffect(() => {
+    if (state.phase !== "inviting") {
+      setInvitationUrl("");
+    }
+  }, [state.phase]);
+
+  const act = async (action: "approve" | "reject") => {
+    const sessionId = lifecycle.sessionId.current;
+    if (!sessionId) {
+      return;
+    }
+    setApproving(true);
+    try {
+      if (action === "approve") {
+        await rpcServerCalls.devicePairingApprove({ sessionId });
+      } else {
+        await rpcServerCalls.devicePairingReject({ sessionId });
+      }
+    } catch {
+      setLocalError("Could not update the pairing ceremony.");
+    } finally {
+      setApproving(false);
+    }
+  };
+
+  const cancel = async () => {
+    const sessionId = lifecycle.sessionId.current;
+    lifecycle.phase.current = "idle";
+    if (sessionId) {
+      await rpcServerCalls.devicePairingCancel({ sessionId }).catch(() => undefined);
+    }
+    props.onClose();
+  };
+
+  if (localError) {
+    return <div className="alert alert-danger">{localError}</div>;
+  }
+  if (["complete", "rejected", "error"].includes(state.phase)) {
+    return <TerminalPanel state={state} onClose={props.onClose} />;
+  }
+  if (state.phase === "comparing" && state.sas) {
+    return (
+      <PairingComparison
+        state={state}
+        approving={approving}
+        onApprove={() => void act("approve")}
+        onReject={() => void act("reject")}
+        onCancel={() => void cancel()}
+      />
+    );
+  }
+  if (state.phase === "waiting-for-approval" || state.phase === "transferring") {
+    return <ProgressWithCancel state={state} onCancel={() => void cancel()} />;
+  }
+  if (invitationUrl) {
+    return (
+      <div className="text-center" style={{ maxWidth: 440, margin: "0 auto" }}>
+        <p className="text-muted">Scan this on the signed-out device you want to add.</p>
+        <div className="d-inline-block bg-white rounded p-3 mb-3">
+          <QRCode value={invitationUrl} size={220} aria-label="Device pairing QR code" />
+        </div>
+        <p className="small text-muted">Expires in {formatCountdown(state.expiresAt)}</p>
+        <div className="d-flex gap-2 justify-content-center">
+          <button
+            type="button"
+            className="btn btn-outline-primary"
+            onClick={() => void copyToClipboard(invitationUrl)}
+          >
+            Copy pairing link
+          </button>
+          <button type="button" className="btn btn-outline-secondary" onClick={() => void cancel()}>
+            Cancel
+          </button>
+        </div>
+      </div>
+    );
+  }
+  return <PairingProgress state={state} />;
+}
+
+/** Signed-out destination flow opened by a QR link or manual invitation paste. */
+export function DestinationDevicePairing(props: {
+  initialInvitation?: string;
+  onInvitationConsumed?: () => void;
+  onBack: () => void;
+}) {
+  const state = useDevicePairingState();
+  const lifecycle = usePairingSessionLifecycle(state);
+  const [invitation, setInvitation] = useState(props.initialInvitation ?? "");
+  const [localError, setLocalError] = useState("");
+  const [approving, setApproving] = useState(false);
+  const autoStarted = useRef(false);
+
+  const start = async (value = invitation) => {
+    setLocalError("");
+    try {
+      const result = await rpcServerCalls.devicePairingStartDestination({
+        invitation: value.trim(),
+        deviceType: /Mobi|Android/i.test(navigator.userAgent) ? "mobile" : "browser",
+      });
+      lifecycle.sessionId.current = result.sessionId;
+      lifecycle.phase.current = result.phase;
+      if (!lifecycle.mounted.current && result.sessionId) {
+        await rpcServerCalls
+          .devicePairingCancel({ sessionId: result.sessionId })
+          .catch(() => undefined);
+        return;
+      }
+      setInvitation("");
+      props.onInvitationConsumed?.();
+    } catch {
+      setLocalError("That pairing invitation is invalid, expired, or unavailable.");
+    }
+  };
+
+  useEffect(() => {
+    if (!props.initialInvitation || autoStarted.current) {
+      return;
+    }
+    autoStarted.current = true;
+    void start(props.initialInvitation);
+  }, [props.initialInvitation]);
+
+  useEffect(() => {
+    if (state.phase !== "complete") {
+      return;
+    }
+    window.setTimeout(() => window.location.reload(), 750);
+  }, [state.phase]);
+
+  const act = async (action: "approve" | "reject") => {
+    const sessionId = lifecycle.sessionId.current;
+    if (!sessionId) {
+      return;
+    }
+    setApproving(true);
+    try {
+      if (action === "approve") {
+        await rpcServerCalls.devicePairingApprove({ sessionId });
+      } else {
+        await rpcServerCalls.devicePairingReject({ sessionId });
+      }
+    } catch {
+      setLocalError("Could not update the pairing ceremony.");
+    } finally {
+      setApproving(false);
+    }
+  };
+
+  const cancel = async () => {
+    const sessionId = lifecycle.sessionId.current;
+    lifecycle.phase.current = "idle";
+    if (sessionId) {
+      await rpcServerCalls.devicePairingCancel({ sessionId }).catch(() => undefined);
+    }
+    props.onBack();
+  };
+
+  if (["complete", "rejected", "error"].includes(state.phase)) {
+    return <TerminalPanel state={state} onClose={props.onBack} />;
+  }
+  if (state.phase === "comparing" && state.sas) {
+    return (
+      <PairingComparison
+        state={state}
+        approving={approving}
+        onApprove={() => void act("approve")}
+        onReject={() => void act("reject")}
+        onCancel={() => void cancel()}
+      />
+    );
+  }
+  if (
+    state.phase === "connecting" ||
+    state.phase === "waiting-for-approval" ||
+    state.phase === "transferring"
+  ) {
+    return <ProgressWithCancel state={state} onCancel={() => void cancel()} />;
+  }
+  return (
+    <div className="text-center" style={{ maxWidth: 500, margin: "0 auto" }}>
+      <h3>Sign in using another device</h3>
+      <p className="text-muted">
+        On a device already signed in to Peers, choose Add another device. Scan its QR code, or
+        paste the complete pairing link or token below.
+      </p>
+      <textarea
+        className="form-control font-monospace mb-3"
+        rows={4}
+        placeholder="Paste pairing link or token"
+        value={invitation}
+        onChange={(event) => setInvitation(event.target.value)}
+        autoComplete="off"
+        aria-label="Device pairing invitation"
+      />
+      {localError ? <div className="alert alert-danger">{localError}</div> : null}
+      <div className="d-grid gap-2">
+        <button
+          type="button"
+          className="btn btn-primary btn-lg"
+          disabled={!invitation.trim()}
+          onClick={() => void start()}
+        >
+          Connect securely
+        </button>
+        <button type="button" className="btn btn-outline-secondary" onClick={props.onBack}>
+          Back
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/screens/device-pairing/index.ts

@@ -0,0 +1,3 @@
+export * from "./device-pairing";
+export * from "./device-pairing-invite";
+export * from "./use-device-pairing-state";

package/src/screens/device-pairing/use-device-pairing-state.ts

@@ -0,0 +1,38 @@
+import {
+  DEVICE_PAIRING_STATE_EVENT,
+  type DevicePairingState,
+  devicePairingStateSchema,
+  rpcServerCalls,
+  subscribe,
+} from "@peers-app/peers-sdk";
+import { useEffect, useState } from "react";
+
+const IDLE_PAIRING_STATE: DevicePairingState = { phase: "idle" };
+
+/** Subscribes to renderer-safe host pairing state and loads its current snapshot. */
+export function useDevicePairingState(): DevicePairingState {
+  const [state, setState] = useState<DevicePairingState>(IDLE_PAIRING_STATE);
+
+  useEffect(() => {
+    let active = true;
+    const subscription = subscribe<DevicePairingState>(DEVICE_PAIRING_STATE_EVENT, (event) => {
+      if (active) {
+        setState(devicePairingStateSchema.parse(event.data));
+      }
+    });
+    void rpcServerCalls
+      .devicePairingGetState()
+      .then((value) => {
+        if (active) {
+          setState(devicePairingStateSchema.parse(value));
+        }
+      })
+      .catch(() => undefined);
+    return () => {
+      active = false;
+      subscription.unsubscribe();
+    };
+  }, []);
+
+  return state;
+}