@peers-app/peers-sdk 0.27.4 → 0.28.0

package/dist/device/connection.d.ts

@@ -8,12 +8,10 @@ export type GetTrustLevel = (deviceInfo: IDeviceInfo, registerNew?: boolean) =>
  * Authenticated RPC connection between two Peers devices.
  *
  * The handshake (`doHandshake` on the client, `completeHandshake` on the
- * server) authenticates both identities with signed, boxed messages. When both
- * sockets support it, the handshake also agrees on per-connection frame-cipher
- * keys (`frame-cipher.ts`) and arms the socket, after which every frame on the
- * wire is sealed and the legacy per-message sign+box envelope is skipped.
- * Against a peer that does not advertise `frameCrypto` the connection falls
- * back to the legacy behaviour and logs a warning.
+ * server) authenticates both identities with signed, boxed messages and agrees
+ * on per-connection frame-cipher keys (`frame-cipher.ts`), then arms the
+ * socket: every frame after the handshake is sealed. A peer that does not
+ * offer frame encryption (a build before 0.25.7) is refused.
  */
 export declare class Connection {
     readonly localDevice: Device;
@@ -21,23 +19,9 @@ export declare class Connection {
     protected readonly getTrustLevel: GetTrustLevel;
     private _verified;
     private _remoteDeviceInfo;
-    /**
-     * @deprecated Legacy transport classification, only consulted when the frame
-     * cipher is not armed. Removed once legacy peers are no longer supported.
-     */
-    secureLocal: boolean;
-    /** @deprecated See {@link Connection.secureLocal}. */
-    secureRemote: boolean;
-    /**
-     * Legacy per-message encryption override. Ignored once the frame cipher is
-     * armed. `"dont-encrypt-traffic-after-handshake"` is honoured only under
-     * `NODE_ENV=test`.
-     * @deprecated Removed with the legacy path.
-     */
-    overrideEncryption?: "encrypt-traffic-regardless-of-protocol" | "dont-encrypt-traffic-after-handshake";
     /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel: TrustLevel;
-    /** Server-side hook fired shortly after a successful handshake. */
+    /** Server-side hook fired shortly after the successful handshake reply has been sent. */
     onHandshakeComplete: ((deviceInfo: IDeviceInfo) => void) | undefined;
     /** RPC timeout for {@link Connection.emit}. */
     timeoutMs: number;
@@ -53,34 +37,26 @@ export declare class Connection {
     private pendingClientHandshake;
     /** Server side: keys to arm for sending right after the handshake response frame. */
     private pendingSendArm;
+    /** Bumped by every {@link Connection.reset}, so a handshake can tell it was cut short. */
+    private handshakeGeneration;
     constructor(socket: ISocket, localDevice: Device, localDeviceServerAddresses?: string[] | undefined, getTrustLevel?: GetTrustLevel);
     /** True once the remote identity has been authenticated by the handshake. */
     get verified(): boolean;
     /** True when every frame on this connection is sealed by the frame cipher. */
     get frameCipherArmed(): boolean;
-    /**
-     * Whether to apply the legacy per-message envelope (sign + box) to RPC payloads.
-     *
-     * Always false once the frame cipher is armed: the frame layer already gives
-     * confidentiality, integrity, and sender binding for every frame. Otherwise
-     * (legacy peer) the transport classification below applies:
-     * - skipped when both sides agreed the transport is secure (`secureLocal && secureRemote`)
-     * - applied on plain `ws` / `http`
-     */
-    get encryptTraffic(): boolean;
     /** Copy of the authenticated remote device identity (empty before the handshake). */
     get remoteDeviceInfo(): {
         publicKey: string;
         userId: string;
-        deviceId: string;
         publicBoxKey: string;
+        deviceId: string;
         userName?: string | undefined;
         deviceName?: string | undefined;
     };
     /** Socket ID shared by both ends; also the frame-cipher AAD and HKDF salt. */
     get connectionId(): string;
-    private get supportsFrameCrypto();
-    private warnLegacyPeer;
+    /** The socket's frame-cipher arming; throws when the transport can't encrypt frames. */
+    private requireFrameCipher;
     private readonly handleCompleteHandshakeRPC;
     /**
      * Get connection throughput stats with calculated rates.
@@ -105,10 +81,15 @@ export declare class Connection {
     exposeRPC<T extends Function>(fn: T): void;
     /** Calls a remote RPC handler and resolves with its result (rejects on error or timeout). */
     emit<T = any>(eventName: string, ...args: any): Promise<T>;
+    /**
+     * Sends one RPC. `onReply`, when given, runs synchronously while the reply frame is
+     * processed, before any later frame from the peer; its return value (or throw) settles
+     * the call.
+     */
+    private request;
     /**
      * Registers an RPC handler. Events other than the handshake set are rejected
-     * until the connection is verified; payloads use the legacy envelope only
-     * when {@link Connection.encryptTraffic} is true.
+     * until the connection is verified.
      */
     on(eventName: string, handler: Function): void;
     /** Removes RPC handlers for `eventName`, or all handlers when omitted. */
@@ -120,26 +101,36 @@ export declare class Connection {
      */
     reset(): void;
     /**
-     * Client side: builds the signed handshake (advertising frame-cipher support
-     * with a fresh ephemeral key when the socket can arm one) and boxes it to the
-     * remote device.
+     * Client side: builds the signed handshake (offering frame encryption with a
+     * fresh ephemeral key) and boxes it to the remote device.
      */
     initiateHandshake(serverAddress: string, remoteDeviceInfo?: IDeviceInfo): IDataBox;
     /**
      * Server side: verifies the client's handshake, resolves trust, and returns
-     * the (unsigned) response for the caller to sign and box. When the client
-     * offered `frameCrypto` and this socket can arm a cipher, derives the frame
+     * the (unsigned) response for the caller to sign and box. Derives the frame
      * keys, arms the receive direction immediately, and schedules the send
      * direction to arm right after the response frame (see
-     * {@link Connection.handleCompleteHandshakeRPC}).
+     * {@link Connection.handleCompleteHandshakeRPC}). A client that does not
+     * offer frame encryption is refused.
      */
     completeHandshake(boxedHandshake: IDataBox): Promise<IDeviceHandshake>;
     /**
      * Client side: runs the full handshake against `remoteAddress`. On success
-     * the remote identity is verified and, if both sockets support it, the
-     * frame cipher is armed in both directions before this resolves.
+     * the remote identity is verified and the frame cipher is armed in both
+     * directions before this resolves.
      */
     doHandshake(remoteAddress: string): Promise<IDeviceHandshake>;
+    /**
+     * Client side: checks the server's handshake reply, arms the frame cipher, and records the
+     * verified identity. Runs synchronously while the reply frame is processed, so a sealed
+     * frame read right after it finds the cipher armed and the connection verified.
+     */
+    private acceptHandshakeReply;
+    /**
+     * Throws when the connection was reset or closed after the handshake started: a handshake
+     * cut short must fail, not finish on a dead or reused connection.
+     */
+    private assertHandshakeCurrent;
     /**
      * Resets this side and asks the remote to do the same. The remote call is a courtesy: a
      * peer that is not a server has no `reset` handler, and a peer we just refused may already