@qrlwallet/connect 0.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,16 +1,121 @@
 import EventEmitter from 'eventemitter3';
 
+/**
+ * Post-quantum handshake (v2).
+ *
+ * Flow:
+ *    dApp                                  relay                 wallet
+ *    ────────────────────────────────────────────────────────────────────
+ *    initiate() → (pk, sk)
+ *    QR(cid, pk) rendered                                        scan QR
+ *                                                                receiveQR(cid, pk)
+ *                                                                → SYNACK{ct, c0}
+ *                                            ◄── SYNACK ─────── send
+ *    onSynAck(cid, SYNACK)
+ *    → ACK{c1}
+ *    send ACK ──►                            ──► ack            onAck(ACK)
+ *
+ * Data phase: encryptMessage / decryptMessage use direction-tagged counter
+ * nonces and AAD = H_tx || seq to bind every ciphertext to the transcript.
+ */
+
+interface Session {
+    cid: Uint8Array;
+    key: CryptoKey;
+    htx: Uint8Array;
+    sendDir: Uint8Array;
+    recvDir: Uint8Array;
+    sendSeq: number;
+    recvSeq: number;
+}
+/** Wire-safe persisted form for localStorage. */
+interface PersistedSession {
+    cid: string;
+    kAeadRaw: string;
+    htx: string;
+    sendDir: string;
+    recvDir: string;
+    sendSeq: number;
+    recvSeq: number;
+}
+interface SynAckMessage {
+    type: KeyExchangeMessageType.SYNACK;
+    ct: string;
+    c0: string;
+    v: number;
+}
+interface AckMessage {
+    type: KeyExchangeMessageType.ACK;
+    c1: string;
+    v: number;
+}
+interface KeyExchangeEvents {
+    keys_exchanged: () => void;
+    step_change: (step: KeyExchangeMessageType) => void;
+}
+declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
+    private isOriginator;
+    private keypair;
+    private session;
+    private step;
+    private awaitingSynAck;
+    private awaitingAck;
+    private keysExchanged;
+    constructor(isOriginator: boolean, restored?: Session);
+    /**
+     * Originator (dApp) side: begin a fresh handshake by generating an
+     * ephemeral ML-KEM-768 keypair. Returns pk to embed in the QR URI.
+     */
+    initiate(): Uint8Array;
+    /**
+     * Originator: handle a SYNACK received over the relay.
+     * Returns an ACK wire message to send, or null if the SYNACK was a
+     * duplicate (handshake already complete).
+     */
+    onSynAck(cid: Uint8Array, msg: SynAckMessage): Promise<AckMessage | null>;
+    /**
+     * Responder (wallet) side: begin handshake from a scanned QR.
+     * Returns the SYNACK wire message to emit on the relay.
+     */
+    receiveQR(cid: Uint8Array, pk: Uint8Array): Promise<SynAckMessage>;
+    /**
+     * Responder: verify an incoming ACK and finalize the session.
+     * Duplicates are silently ignored (handshake is idempotent).
+     */
+    onAck(msg: AckMessage): Promise<void>;
+    /** Encrypt a string for the counterparty. Returns base64. */
+    encryptMessage(data: string): Promise<string>;
+    /** Decrypt a base64 ciphertext from the counterparty. */
+    decryptMessage(b64: string): Promise<string>;
+    /** Reset all state for a fresh handshake. Zeroes any live secret-key buffer. */
+    reset(): void;
+    private resetInternal;
+    areKeysExchanged(): boolean;
+    getSession(): Session | null;
+    getCurrentStep(): KeyExchangeMessageType;
+    /** Export the current session as a JSON-safe persisted record. */
+    exportPersisted(): Promise<PersistedSession | null>;
+    /** Rehydrate a Session from its persisted form. */
+    static sessionFromPersisted(p: PersistedSession): Promise<Session>;
+}
+
 /** dApp metadata shown to user in approval UI */
 interface DAppMetadata {
     name: string;
     url: string;
     icon?: string;
 }
-/** Stored session for reconnection */
+/**
+ * Stored session for reconnection.
+ *
+ * v2 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.
+ */
 interface DAppSession {
+    version: 2;
     channelId: string;
-    privateKey: string;
-    otherPublicKey: string | null;
+    keyExchange: PersistedSession;
     dappMetadata: DAppMetadata;
     connectedAccounts: string[];
     chainId: string;
@@ -26,7 +131,13 @@ interface PendingRequest {
     reject: (error: Error) => void;
     timestamp: number;
 }
-/** Key exchange message types */
+/**
+ * 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
+ * ML-KEM-768 encapsulation key is embedded in the URI, not sent on the wire.
+ */
 declare enum KeyExchangeMessageType {
     SYN = "key_handshake_SYN",
     SYNACK = "key_handshake_SYNACK",
@@ -164,14 +275,18 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
      */
     newConnection(): Promise<string>;
     /**
-     * Disconnect from wallet and clean up.
+     * 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
+     * its stale-session grace period.
      */
-    disconnect(): void;
+    disconnect(): Promise<void>;
 }
 
 /**
- * Connection Manager - Orchestrates socket connection, key exchange,
- * and encrypted message routing. Manages session persistence and reconnection.
+ * Connection Manager — orchestrates socket lifecycle, the post-quantum
+ * handshake, encrypted message routing, and session persistence for the
+ * dApp side of QRL Connect v2.
  */
 
 interface ConnectionManagerEvents {
@@ -188,7 +303,6 @@ interface ConnectionManagerEvents {
 }
 declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private socketClient;
-    private ecies;
     private keyExchange;
     private status;
     private channelId;
@@ -198,14 +312,11 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private connectedAccounts;
     private storageKey;
     private unresponsiveTimer;
-    private synRetryTimer;
     private failedReconnects;
-    private synSent;
-    private synAttempts;
     private walletPresent;
+    private pendingRestore;
+    private messageQueue;
     private static MAX_RECONNECT_FAILURES;
-    private static SYN_RETRY_MS;
-    private static MAX_SYN_ATTEMPTS;
     constructor(options: {
         dappMetadata: DAppMetadata;
         relayUrl?: string;
@@ -215,110 +326,56 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private setupSocketListeners;
     private setupKeyExchangeListeners;
     /**
-     * Generate the connection URI and start listening for wallet connection.
+     * Generate a new v2 connection URI. Rotates channel id and keypair.
+     * Returns a `qrlconnect://?q=…` URI safe for QR-rendering or deep-link.
      */
     getConnectionURI(retryOnConflict?: boolean): Promise<string>;
     /**
      * Reconnect to an existing session.
+     * Returns false if there is nothing to restore.
      */
     reconnect(): Promise<boolean>;
     /**
-     * Send a JSON-RPC request to the wallet.
+     * Send a JSON-RPC request to the wallet (async, fire-and-forget).
      */
     sendJsonRpc(request: JsonRpcRequest): void;
+    getStatus(): ConnectionStatus;
+    getAccounts(): string[];
+    getChainId(): string;
+    getChannelId(): string;
+    /** Check (sync) if a persisted session exists and has not expired. */
+    hasStoredSession(): boolean;
+    /**
+     * Best-effort TERMINATE delivery before we tear the socket down. Without
+     * awaiting, the socket.disconnect() below would win the race against the
+     * outbound emit, the wallet would only see `participants_changed:
+     * disconnect` and enter its stale-session grace period instead of an
+     * instant disconnect. Mirrors the wallet side's pattern.
+     */
+    private flushTerminate;
     /**
-     * Handle an incoming relay message.
+     * Reset to a fresh channel + keypair. Sends TERMINATE to any live peer,
+     * drops the persisted session, and prepares a clean state for
+     * getConnectionURI() to be called again.
      */
+    resetForNewChannel(): Promise<void>;
+    disconnect(): Promise<void>;
+    private enqueueRelayMessage;
     private handleRelayMessage;
-    private handleKeyExchangeMessage;
+    private handleSynAck;
     private handleDecryptedMessage;
-    /** Send a plaintext (unencrypted) message through the relay. */
     private sendPlaintext;
-    /** Send an encrypted message through the relay. */
     private sendEncrypted;
     private startUnresponsiveTimer;
     private clearUnresponsiveTimer;
-    private sendSYN;
-    private scheduleSynRetry;
-    private clearSynRetryTimer;
     private setStatus;
     private isDappParticipantConflictError;
     private areArraysEqual;
-    getStatus(): ConnectionStatus;
-    getAccounts(): string[];
-    getChainId(): string;
-    getChannelId(): string;
-    /** Check if a stored session exists (without loading/restoring it). */
-    hasStoredSession(): boolean;
-    /**
-     * Reset the connection and create a new channel for a fresh pairing.
-     * Disconnects any existing session, generates a new channel ID and keys.
-     */
-    resetForNewChannel(): void;
-    /** Disconnect and clean up. */
-    disconnect(): void;
-    private saveSession;
-    private loadSession;
+    private persistSession;
+    private readStoredSession;
     private clearSession;
 }
 
-/**
- * ECIES encryption/decryption client.
- * Adapted from MetaMask SDK's ECIES.ts pattern.
- */
-declare class ECIESClient {
-    private privateKey;
-    constructor(existingPrivateKey?: string);
-    /** Get public key as hex string */
-    getPublicKey(): string;
-    /** Get private key as hex string (for session persistence) */
-    getPrivateKeyHex(): string;
-    /** Encrypt a string message for the given public key. Returns base64. */
-    encrypt(data: string, otherPublicKey: string): string;
-    /** Decrypt a base64-encoded message using our private key. */
-    decrypt(encryptedBase64: string): string;
-}
-
-/**
- * Key Exchange - 3-step SYN/SYNACK/ACK handshake protocol.
- * Adapted from MetaMask SDK's KeyExchange.ts.
- */
-
-interface KeyExchangeEvents {
-    keys_exchanged: () => void;
-    step_change: (step: KeyExchangeMessageType) => void;
-}
-declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
-    private ecies;
-    private otherPublicKey;
-    private keysExchanged;
-    private awaitingSynAck;
-    private awaitingAck;
-    private step;
-    private isOriginator;
-    constructor(ecies: ECIESClient, isOriginator: boolean, otherPublicKey?: string);
-    /** Get the SYN message to start the handshake (originator/dApp side). */
-    createSYN(): object;
-    /**
-     * Process an incoming key exchange message.
-     * Returns a response message to send back, or null if handshake is complete.
-     */
-    onMessage(message: {
-        type: KeyExchangeMessageType;
-        pubkey?: string;
-        v?: number;
-    }): object | null;
-    /** Encrypt a message for the counterparty. */
-    encryptMessage(data: string): string;
-    /** Decrypt a message from the counterparty. */
-    decryptMessage(encryptedBase64: string): string;
-    /** Reset key exchange state for a fresh handshake (e.g. new QR code). */
-    reset(): void;
-    areKeysExchanged(): boolean;
-    getOtherPublicKey(): string | null;
-    getCurrentStep(): KeyExchangeMessageType;
-}
-
 /**
  * Socket.IO client wrapper for relay communication.
  */
@@ -334,24 +391,44 @@ interface SocketClientEvents {
     }) => void;
     error: (err: Error) => void;
 }
+interface JoinResult {
+    bufferedMessages: unknown[];
+    /**
+     * 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.
+     */
+    channelPublicKey: string | null;
+}
 declare class SocketClient extends EventEmitter<SocketClientEvents> {
     private socket;
     private relayUrl;
     private channelId;
     private clientType;
+    private publicKeyBase64;
     private seq;
     private pendingJoin;
     constructor(relayUrl: string, clientType: 'dapp' | 'wallet');
+    /**
+     * dApp-only: stash the PK so it gets uploaded on every join_channel
+     * attempt (including auto-rejoins after reconnect).
+     */
+    setPublicKey(publicKeyBase64: string): void;
     /**
      * Connect to the relay server.
      */
     connect(): void;
     /**
-     * Join a relay channel.
+     * Resolve or reject the currently-pending `joinChannel` promise, if it
+     * matches the given channelId. Clears the watchdog timer on settle so
+     * it doesn't fire after the fact.
      */
-    joinChannel(channelId: string): Promise<{
-        bufferedMessages: unknown[];
-    }>;
+    private settlePendingJoin;
+    /**
+     * Join a relay channel. Resolves with any buffered messages plus the
+     * dApp's public key bound to the channel (for wallet joins).
+     */
+    joinChannel(channelId: string): Promise<JoinResult>;
     private joinChannelNow;
     /**
      * Send a message through the relay.
@@ -372,23 +449,67 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
     getChannelId(): string | null;
 }
 
-interface QRConnectParams {
-    channelId: string;
-    pubKey: string;
-    name: string;
-    url: string;
-    icon?: string;
-    chainId: string;
-    relayUrl: string;
-}
 /**
- * Generate a qrlconnect:// URI for QR code or deep link.
+ * v2 QR URI codec (PQP2).
+ *
+ * Format: qrlconnect://?q=<base45(PQP2 || cid || fp)>[&r=<relayUrl>]
+ *
+ *   PQP2 = "PQP2" magic                                 (4 B)
+ *   cid  = 16 bytes (UUIDv4 raw)                        (16 B)
+ *   fp   = SHA-256("pq-fp/v2" || cid || pk) (full 32B)  (32 B)
+ *   total                                               (52 B)
+ *
+ * 52 bytes → ~78 alphanumeric chars after base45 → URI under 150 chars →
+ * fits a version-5 QR at ECC-M. Scannable from any 2015-vintage camera.
+ *
+ * Security: the public key is NOT carried in the QR. It's uploaded by the
+ * dApp to the relay at channel creation, the relay binds it to the cid, and
+ * the wallet fetches it via the join_channel ack. The 32-byte fp acts as
+ * the out-of-band commitment: the wallet rejects the PK served by the relay
+ * unless SHA-256("pq-fp/v2" || cid || pk) matches the fp from the QR.
+ * Full-width SHA-256 (2^128 collision resistance) rules out brute-force
+ * 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
+ * break before 2.0.0 ships, no backcompat.
  */
-declare function generateConnectionURI(params: QRConnectParams): string;
+declare const CID_LEN = 16;
+declare const FP_LEN = 32;
+declare const BLOB_LEN: number;
 /**
- * Parse a qrlconnect:// URI back into its components.
+ * Compute the full 32-byte fingerprint binding (label || cid || pk).
+ * Exported so the wallet side can re-derive and verify.
  */
-declare function parseConnectionURI(uri: string): QRConnectParams | null;
+declare function computeFingerprint(cid: Uint8Array, pk: Uint8Array): Promise<Uint8Array>;
+/**
+ * Constant-time comparison of two byte arrays. Both must be the same length.
+ * The verifier MUST use this rather than `===` or `indexOf` so timing signals
+ * don't leak which byte of `fp` diverged first.
+ */
+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
+ * 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.
+ */
+declare function generateConnectionURI(cid: Uint8Array, pk: Uint8Array, relayUrl?: string): Promise<string>;
+interface ParsedURI {
+    cid: Uint8Array;
+    fp: Uint8Array;
+    relayUrl?: string;
+}
+declare function parseConnectionURI(uri: string): Promise<ParsedURI>;
+/** Convert 16 raw cid bytes to RFC 4122 UUID hex string. */
+declare function cidToString(cid: Uint8Array): string;
+/** Convert RFC 4122 UUID string to 16 raw cid bytes. */
+declare function cidFromString(s: string): Uint8Array;
+/** Generate 16 random bytes for a fresh channel ID. */
+declare function cidRandom(): Uint8Array;
 
 /**
  * Detect if the current browser is on a mobile device.
@@ -401,9 +522,10 @@ declare function isMobileBrowser(): boolean;
 declare function getAppStoreUrl(): string;
 
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
+declare const PROTOCOL_VERSION = 2;
 /** RPC methods that require user approval in the wallet */
 declare const RESTRICTED_METHODS: Set<string>;
 /** RPC methods that can be auto-proxied without approval */
 declare const UNRESTRICTED_METHODS: Set<string>;
 
-export { ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, ECIESClient, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MessageType, type PendingRequest, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, RESTRICTED_METHODS, type RelayMessage, SocketClient, UNRESTRICTED_METHODS, generateConnectionURI, getAppStoreUrl, isMobileBrowser, parseConnectionURI };
+export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, RESTRICTED_METHODS, type RelayMessage, type Session, SocketClient, type SynAckMessage, UNRESTRICTED_METHODS, cidFromString, cidRandom, cidToString, computeFingerprint, fingerprintEquals, generateConnectionURI, getAppStoreUrl, isMobileBrowser, parseConnectionURI };