@qrlwallet/connect 3.0.0 → 3.1.0

package/dist/index.d.mts

@@ -61,6 +61,7 @@ declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
     private awaitingSynAck;
     private awaitingAck;
     private keysExchanged;
+    private lastAck;
     constructor(isOriginator: boolean, restored?: Session);
     /**
      * Originator (dApp) side: begin a fresh handshake by generating an
@@ -91,6 +92,8 @@ declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
     reset(): void;
     private resetInternal;
     areKeysExchanged(): boolean;
+    /** The ACK produced for the current handshake, for duplicate-SYNACK replies. */
+    getLastAck(): AckMessage | null;
     getSession(): Session | null;
     getCurrentStep(): KeyExchangeMessageType;
     /** Export the current session as a JSON-safe persisted record. */
@@ -115,12 +118,15 @@ interface DAppMetadata {
 /**
  * Stored session for reconnection.
  *
- * v2 persists the derived AES-256 session key (not the ML-KEM secret key) —
+ * Persists the derived AES-256 session key (not the ML-KEM secret key);
  * the ML-KEM keypair is ephemeral and zeroized after the handshake.
  * Re-pair (generate a new QR) to rotate the session key.
+ *
+ * v3 checkpoints the AEAD counters on every seal/open. v2 records (sparse
+ * checkpoints, stale-counter nonce-reuse risk on restore) are dropped.
  */
 interface DAppSession {
-    version: 2;
+    version: 3;
     channelId: string;
     keyExchange: PersistedSession;
     dappMetadata: DAppMetadata;
@@ -133,7 +139,7 @@ interface DAppSession {
 interface PendingRequest {
     id: string | number;
     method: string;
-    params?: unknown[];
+    params?: unknown[] | undefined;
     resolve: (result: unknown) => void;
     reject: (error: Error) => void;
     timestamp: number;
@@ -142,7 +148,7 @@ interface PendingRequest {
  * Key-exchange wire-message types.
  *
  * v2 note: only SYNACK (wallet→dApp) and ACK (dApp→wallet) are transmitted
- * over the relay. The SYN step is carried by the QR code itself — the dApp's
+ * over the relay. The SYN step is carried by the QR code itself - the dApp's
  * ML-KEM-768 encapsulation key is embedded in the URI, not sent on the wire.
  */
 declare enum KeyExchangeMessageType {
@@ -198,7 +204,7 @@ interface JsonRpcRequest {
     jsonrpc?: string;
     id?: string | number;
     method: string;
-    params?: unknown[];
+    params?: unknown[] | undefined;
 }
 /** JSON-RPC response */
 interface JsonRpcResponse {
@@ -215,7 +221,7 @@ interface JsonRpcResponse {
  * EIP-6963 wallet identity advertised to dApps.
  *
  * `rdns` MUST be unique to this wallet and SHOULD be a reverse-DNS string
- * (per EIP-6963). Defaults work for most consumers — override only when
+ * (per EIP-6963). Defaults work for most consumers - override only when
  * embedding the SDK inside a different branded wallet.
  */
 interface EIP6963ProviderInfoOverride {
@@ -262,10 +268,10 @@ type QrlSignMessageParams = [string, string];
  * for the full encoder.
  */
 interface QrlTypedDataPayload {
-    types: Record<string, ReadonlyArray<{
+    types: Record<string, readonly {
         name: string;
         type: string;
-    }>>;
+    }[]>;
     primaryType: string;
     domain: Record<string, unknown>;
     message: Record<string, unknown>;
@@ -316,6 +322,8 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private eip6963RequestListener;
     private resumeListener;
     private resumeDebounce;
+    private readonly requestIdPrefix;
+    private requestCounter;
     readonly isQRLConnect = true;
     constructor(options: QRLConnectOptions);
     private startEip6963Announce;
@@ -385,14 +393,14 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     /**
      * Disconnect from wallet and clean up. Returns once the TERMINATE has
      * either been flushed to the relay or the 800ms best-effort window has
-     * elapsed — the wallet gets an instant disconnect instead of landing in
+     * elapsed - the wallet gets an instant disconnect instead of landing in
      * its stale-session grace period.
      */
     disconnect(): Promise<void>;
 }
 
 /**
- * Connection Manager — orchestrates socket lifecycle, the post-quantum
+ * Connection Manager - orchestrates socket lifecycle, the post-quantum
  * handshake, encrypted message routing, and session persistence for the
  * dApp side of QRL Connect v2.
  */
@@ -425,12 +433,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private walletPresent;
     private pendingRestore;
     private messageQueue;
+    private outboundQueue;
     private static MAX_RECONNECT_FAILURES;
     constructor(options: {
         dappMetadata: DAppMetadata;
-        relayUrl?: string;
-        chainId?: string;
-        storageKey?: string;
+        relayUrl?: string | undefined;
+        chainId?: string | undefined;
+        storageKey?: string | undefined;
     });
     private setupSocketListeners;
     private setupKeyExchangeListeners;
@@ -498,7 +507,16 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
+    /**
+     * Serialize every encrypt+persist+send on a single outbound queue.
+     * Callers like sendJsonRpc() are fire-and-forget, so without the queue two
+     * rapid provider.request() calls would interleave inside encryptMessage()
+     * across its await and could complete out of order; the receiver's
+     * contiguous-seq check would then drop the late one. (Nonce reuse itself is
+     * already prevented by the synchronous seq reservation in KeyExchange.)
+     */
     private sendEncrypted;
+    private sendEncryptedNow;
     private startUnresponsiveTimer;
     private clearUnresponsiveTimer;
     private setStatus;
@@ -529,7 +547,7 @@ interface JoinResult {
     /**
      * Base64-encoded KEM public key the relay has bound to this channel.
      * Populated for wallet joins (v2 protocol). `null` if the dApp hasn't
-     * registered a PK yet — wallet callers must treat this as a retry signal.
+     * registered a PK yet - wallet callers must treat this as a retry signal.
      */
     channelPublicKey: string | null;
     /**
@@ -632,7 +650,8 @@ declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
  * EIP-712-shaped typed-data encoding for `qrl_signTypedData` v1.
  *
  * Byte-identical algorithm with the wallet's signing/typedData.ts; this
- * file is the SDK port (only the relative-import extensions differ). See
+ * file is the SDK port (only the import block differs: the SDK routes
+ * SHAKE256 through src/crypto/primitives.ts, its crypto boundary). See
  * the wallet copy for the spec-level comments; behavior must stay in
  * lock-step or the cross-repo parity test fails on next CI.
  */
@@ -709,7 +728,7 @@ declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
  * substitution of a maliciously-crafted PK with the same fingerprint.
  *
  * Legacy v2.0 URIs (magic=PQP1, 1208-byte blob with embedded PK) are
- * rejected with a clear error by parseConnectionURI — this is a hard
+ * rejected with a clear error by parseConnectionURI - this is a hard
  * break before 2.0.0 ships, no backcompat.
  */
 declare const CID_LEN = 16;
@@ -728,18 +747,18 @@ declare function computeFingerprint(cid: Uint8Array, pk: Uint8Array): Promise<Ui
 declare function fingerprintEquals(a: Uint8Array, b: Uint8Array): boolean;
 /**
  * Encode (cid, pk) as a qrlconnect:// URI. Note the PK is not stored in the
- * URI — we compute its fingerprint and embed only that. The caller must
+ * URI - we compute its fingerprint and embed only that. The caller must
  * upload the PK to the relay separately before publishing this URI.
  *
  * The optional `relayUrl` rides as a sibling query param (not inside the
  * fp-bound blob) so a tampered relay can cause the pairing to fail but
- * cannot substitute the PK — the fp still pins that.
+ * cannot substitute the PK - the fp still pins that.
  */
 declare function generateConnectionURI(cid: Uint8Array, pk: Uint8Array, relayUrl?: string): Promise<string>;
 interface ParsedURI {
     cid: Uint8Array;
     fp: Uint8Array;
-    relayUrl?: string;
+    relayUrl?: string | undefined;
 }
 declare function parseConnectionURI(uri: string): Promise<ParsedURI>;
 /** Convert 16 raw cid bytes to RFC 4122 UUID hex string. */

package/dist/index.d.ts

@@ -61,6 +61,7 @@ declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
     private awaitingSynAck;
     private awaitingAck;
     private keysExchanged;
+    private lastAck;
     constructor(isOriginator: boolean, restored?: Session);
     /**
      * Originator (dApp) side: begin a fresh handshake by generating an
@@ -91,6 +92,8 @@ declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
     reset(): void;
     private resetInternal;
     areKeysExchanged(): boolean;
+    /** The ACK produced for the current handshake, for duplicate-SYNACK replies. */
+    getLastAck(): AckMessage | null;
     getSession(): Session | null;
     getCurrentStep(): KeyExchangeMessageType;
     /** Export the current session as a JSON-safe persisted record. */
@@ -115,12 +118,15 @@ interface DAppMetadata {
 /**
  * Stored session for reconnection.
  *
- * v2 persists the derived AES-256 session key (not the ML-KEM secret key) —
+ * Persists the derived AES-256 session key (not the ML-KEM secret key);
  * the ML-KEM keypair is ephemeral and zeroized after the handshake.
  * Re-pair (generate a new QR) to rotate the session key.
+ *
+ * v3 checkpoints the AEAD counters on every seal/open. v2 records (sparse
+ * checkpoints, stale-counter nonce-reuse risk on restore) are dropped.
  */
 interface DAppSession {
-    version: 2;
+    version: 3;
     channelId: string;
     keyExchange: PersistedSession;
     dappMetadata: DAppMetadata;
@@ -133,7 +139,7 @@ interface DAppSession {
 interface PendingRequest {
     id: string | number;
     method: string;
-    params?: unknown[];
+    params?: unknown[] | undefined;
     resolve: (result: unknown) => void;
     reject: (error: Error) => void;
     timestamp: number;
@@ -142,7 +148,7 @@ interface PendingRequest {
  * Key-exchange wire-message types.
  *
  * v2 note: only SYNACK (wallet→dApp) and ACK (dApp→wallet) are transmitted
- * over the relay. The SYN step is carried by the QR code itself — the dApp's
+ * over the relay. The SYN step is carried by the QR code itself - the dApp's
  * ML-KEM-768 encapsulation key is embedded in the URI, not sent on the wire.
  */
 declare enum KeyExchangeMessageType {
@@ -198,7 +204,7 @@ interface JsonRpcRequest {
     jsonrpc?: string;
     id?: string | number;
     method: string;
-    params?: unknown[];
+    params?: unknown[] | undefined;
 }
 /** JSON-RPC response */
 interface JsonRpcResponse {
@@ -215,7 +221,7 @@ interface JsonRpcResponse {
  * EIP-6963 wallet identity advertised to dApps.
  *
  * `rdns` MUST be unique to this wallet and SHOULD be a reverse-DNS string
- * (per EIP-6963). Defaults work for most consumers — override only when
+ * (per EIP-6963). Defaults work for most consumers - override only when
  * embedding the SDK inside a different branded wallet.
  */
 interface EIP6963ProviderInfoOverride {
@@ -262,10 +268,10 @@ type QrlSignMessageParams = [string, string];
  * for the full encoder.
  */
 interface QrlTypedDataPayload {
-    types: Record<string, ReadonlyArray<{
+    types: Record<string, readonly {
         name: string;
         type: string;
-    }>>;
+    }[]>;
     primaryType: string;
     domain: Record<string, unknown>;
     message: Record<string, unknown>;
@@ -316,6 +322,8 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private eip6963RequestListener;
     private resumeListener;
     private resumeDebounce;
+    private readonly requestIdPrefix;
+    private requestCounter;
     readonly isQRLConnect = true;
     constructor(options: QRLConnectOptions);
     private startEip6963Announce;
@@ -385,14 +393,14 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     /**
      * Disconnect from wallet and clean up. Returns once the TERMINATE has
      * either been flushed to the relay or the 800ms best-effort window has
-     * elapsed — the wallet gets an instant disconnect instead of landing in
+     * elapsed - the wallet gets an instant disconnect instead of landing in
      * its stale-session grace period.
      */
     disconnect(): Promise<void>;
 }
 
 /**
- * Connection Manager — orchestrates socket lifecycle, the post-quantum
+ * Connection Manager - orchestrates socket lifecycle, the post-quantum
  * handshake, encrypted message routing, and session persistence for the
  * dApp side of QRL Connect v2.
  */
@@ -425,12 +433,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private walletPresent;
     private pendingRestore;
     private messageQueue;
+    private outboundQueue;
     private static MAX_RECONNECT_FAILURES;
     constructor(options: {
         dappMetadata: DAppMetadata;
-        relayUrl?: string;
-        chainId?: string;
-        storageKey?: string;
+        relayUrl?: string | undefined;
+        chainId?: string | undefined;
+        storageKey?: string | undefined;
     });
     private setupSocketListeners;
     private setupKeyExchangeListeners;
@@ -498,7 +507,16 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
+    /**
+     * Serialize every encrypt+persist+send on a single outbound queue.
+     * Callers like sendJsonRpc() are fire-and-forget, so without the queue two
+     * rapid provider.request() calls would interleave inside encryptMessage()
+     * across its await and could complete out of order; the receiver's
+     * contiguous-seq check would then drop the late one. (Nonce reuse itself is
+     * already prevented by the synchronous seq reservation in KeyExchange.)
+     */
     private sendEncrypted;
+    private sendEncryptedNow;
     private startUnresponsiveTimer;
     private clearUnresponsiveTimer;
     private setStatus;
@@ -529,7 +547,7 @@ interface JoinResult {
     /**
      * Base64-encoded KEM public key the relay has bound to this channel.
      * Populated for wallet joins (v2 protocol). `null` if the dApp hasn't
-     * registered a PK yet — wallet callers must treat this as a retry signal.
+     * registered a PK yet - wallet callers must treat this as a retry signal.
      */
     channelPublicKey: string | null;
     /**
@@ -632,7 +650,8 @@ declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
  * EIP-712-shaped typed-data encoding for `qrl_signTypedData` v1.
  *
  * Byte-identical algorithm with the wallet's signing/typedData.ts; this
- * file is the SDK port (only the relative-import extensions differ). See
+ * file is the SDK port (only the import block differs: the SDK routes
+ * SHAKE256 through src/crypto/primitives.ts, its crypto boundary). See
  * the wallet copy for the spec-level comments; behavior must stay in
  * lock-step or the cross-repo parity test fails on next CI.
  */
@@ -709,7 +728,7 @@ declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
  * substitution of a maliciously-crafted PK with the same fingerprint.
  *
  * Legacy v2.0 URIs (magic=PQP1, 1208-byte blob with embedded PK) are
- * rejected with a clear error by parseConnectionURI — this is a hard
+ * rejected with a clear error by parseConnectionURI - this is a hard
  * break before 2.0.0 ships, no backcompat.
  */
 declare const CID_LEN = 16;
@@ -728,18 +747,18 @@ declare function computeFingerprint(cid: Uint8Array, pk: Uint8Array): Promise<Ui
 declare function fingerprintEquals(a: Uint8Array, b: Uint8Array): boolean;
 /**
  * Encode (cid, pk) as a qrlconnect:// URI. Note the PK is not stored in the
- * URI — we compute its fingerprint and embed only that. The caller must
+ * URI - we compute its fingerprint and embed only that. The caller must
  * upload the PK to the relay separately before publishing this URI.
  *
  * The optional `relayUrl` rides as a sibling query param (not inside the
  * fp-bound blob) so a tampered relay can cause the pairing to fail but
- * cannot substitute the PK — the fp still pins that.
+ * cannot substitute the PK - the fp still pins that.
  */
 declare function generateConnectionURI(cid: Uint8Array, pk: Uint8Array, relayUrl?: string): Promise<string>;
 interface ParsedURI {
     cid: Uint8Array;
     fp: Uint8Array;
-    relayUrl?: string;
+    relayUrl?: string | undefined;
 }
 declare function parseConnectionURI(uri: string): Promise<ParsedURI>;
 /** Convert 16 raw cid bytes to RFC 4122 UUID hex string. */