@qrlwallet/connect 3.3.0 → 5.0.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 import EventEmitter from 'eventemitter3';
 
 /**
- * Post-quantum handshake (v2).
+ * Post-quantum handshake (v3).
  *
  * Flow:
  *    dApp                                  relay                 wallet
  *    ────────────────────────────────────────────────────────────────────
- *    initiate() → (pk, sk)
- *    QR(cid, pk) rendered                                        scan QR
- *                                                                receiveQR(cid, pk)
+ *    initiate() → (pk, sk, cap)
+ *    QR(cid, fp, cap) rendered                                  scan QR
+ *                                                                receiveQR(cid, pk, cap)
  *                                                                → SYNACK{ct, c0}
  *                                            ◄── SYNACK ─────── send
  *    onSynAck(cid, SYNACK)
@@ -20,6 +20,7 @@ import EventEmitter from 'eventemitter3';
  */
 
 interface Session {
+    protocolVersion: 3;
     cid: Uint8Array;
     key: CryptoKey;
     htx: Uint8Array;
@@ -30,6 +31,7 @@ interface Session {
 }
 /** Wire-safe persisted form for localStorage. */
 interface PersistedSession {
+    protocolVersion: 3;
     cid: string;
     kAeadRaw: string;
     htx: string;
@@ -49,6 +51,10 @@ interface AckMessage {
     c1: string;
     v: number;
 }
+interface InitiatedKeyExchange {
+    publicKey: Uint8Array;
+    capability: Uint8Array;
+}
 interface KeyExchangeEvents {
     keys_exchanged: () => void;
     step_change: (step: KeyExchangeMessageType) => void;
@@ -56,29 +62,40 @@ interface KeyExchangeEvents {
 declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
     private isOriginator;
     private keypair;
+    private capability;
     private session;
     private step;
     private awaitingSynAck;
     private awaitingAck;
+    private awaitingAckDelivery;
     private keysExchanged;
+    private stateGeneration;
     private lastAck;
     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.
+     * ephemeral ML-KEM-768 keypair and a fresh 32-byte pairing capability.
+     * Both returned arrays are copies; the originator retains its own secret
+     * capability until the handshake succeeds or is retired.
      */
-    initiate(): Uint8Array;
+    initiate(): InitiatedKeyExchange;
     /**
      * 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>;
+    /**
+     * Originator: publish completion only after the relay acknowledged ACK.
+     * This is deliberately separate from onSynAck() so transport ambiguity
+     * cannot leave a live or persistable one-sided session.
+     */
+    confirmOriginatorAckDelivered(): void;
     /**
      * 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>;
+    receiveQR(cid: Uint8Array, pk: Uint8Array, capability: Uint8Array): Promise<SynAckMessage>;
     /**
      * Responder: verify an incoming ACK and finalize the session.
      * Duplicates are silently ignored (handshake is idempotent).
@@ -108,10 +125,11 @@ interface DAppMetadata {
     url: string;
     icon?: string;
     /**
-     * Optional "return to dApp" target (a URL or app deep-link scheme). Sent to
-     * the wallet in ORIGINATOR_INFO; after the wallet resolves a restricted
-     * request it bounces the user back here (WalletConnect-style peer redirect)
-     * so a same-device deep-link flow does not strand the user in the wallet.
+     * Optional credential-free HTTP(S) "return to dApp" target. HTTPS is
+     * required except for explicit loopback development URLs. Sent to the
+     * wallet in ORIGINATOR_INFO; after the wallet resolves a restricted request
+     * it bounces the user back here so a same-device flow does not strand the
+     * user in the wallet.
      */
     redirectUrl?: string;
 }
@@ -122,11 +140,12 @@ interface DAppMetadata {
  * 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.
+ * v5 checkpoints every seal/open, requires exclusive browser-tab ownership,
+ * and proves the AEAD key came from a PQP3 capability-bound handshake.
+ * Older records cannot prove all three invariants and are dropped.
  */
 interface DAppSession {
-    version: 3;
+    version: 5;
     channelId: string;
     keyExchange: PersistedSession;
     dappMetadata: DAppMetadata;
@@ -140,6 +159,8 @@ interface PendingRequest {
     id: string | number;
     method: string;
     params?: unknown[] | undefined;
+    /** Immutable postcondition captured before caller-owned params can change. */
+    expectedChainId?: string | undefined;
     resolve: (result: unknown) => void;
     reject: (error: Error) => void;
     timestamp: number;
@@ -147,9 +168,10 @@ 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
- * ML-KEM-768 encapsulation key is embedded in the URI, not sent on the wire.
+ * v3 note: only SYNACK (wallet to dApp) and ACK (dApp to wallet) are
+ * transmitted over the relay. The SYN step is represented by the pairing URI,
+ * while the relay carries only the dApp's ML-KEM public key. The URI contains
+ * the key fingerprint and a capability that is never uploaded to the relay.
  */
 declare enum KeyExchangeMessageType {
     SYN = "key_handshake_SYN",
@@ -247,31 +269,68 @@ interface EIP6963ProviderInfoOverride {
     rdns?: string;
 }
 /**
- * Rich response object returned by both `qrl_signMessage` and
- * `qrl_signTypedData`. The signature alone is not enough to verify since
- * ML-DSA-87 public keys cannot be recovered from a signature, so the
- * wallet always returns the public key explicitly. Stateless verifiers
- * (e.g. the SDK's `verifyMessage` / `verifyTypedData`) need every field.
+ * Rich response object returned by `qrl_signMessage` and retained for locked
+ * `qrl_signTypedData` v1 fixtures. The signature alone is not enough to
+ * verify since ML-DSA-87 public keys cannot be recovered from a signature,
+ * so the wallet returns the public key explicitly. Stateless verifiers need
+ * the original payload plus the signature fields below.
  */
 interface QrlSignedResult {
-    /** 0x-hex of the 4595-byte ML-DSA-87 signature. */
+    /** 0x-hex of the 4627-byte ML-DSA-87 signature. */
     signature: string;
     /** 0x-hex of the 2592-byte ML-DSA-87 public key. */
     publicKey: string;
-    /** 41-char checksummed Q-address derived from `publicKey`. */
+    /**
+     * 0x-hex of the 3-byte wallet descriptor used to derive `signer`.
+     * Optional while older wallet builds are upgraded; bound verification
+     * requires it.
+     */
+    descriptor?: string;
+    /** QIP-55 129-character checksummed Q-address derived from descriptor + key. */
     signer: string;
     /** 0x-hex of the 64-byte SHAKE256 digest that was signed. */
     digest: string;
     /** Scheme tag: 'QRL-SIGN-MSG-v1' or 'QRL-SIGN-TYPED-v1'. */
-    schemeVersion: string;
+    schemeVersion: QrlSigningSchemeVersion;
+}
+/** A current wallet response whose descriptor can be signer-bound. */
+interface QrlSignedResultWithDescriptor extends QrlSignedResult {
+    descriptor: string;
+}
+type QrlSigningSchemeVersion = 'QRL-SIGN-MSG-v1' | 'QRL-SIGN-TYPED-v1';
+/** Strict wire shape returned by `qrl_signMessage`. */
+interface QrlSignedMessageResult extends QrlSignedResult {
+    schemeVersion: 'QRL-SIGN-MSG-v1';
 }
 /**
- * Response from `qrl_signTypedData`. Echoes `domain` so a stateless
- * verifier doesn't need to be told the domain out-of-band.
+ * Historical v1 response from `qrl_signTypedData`. It echoes `domain` so a
+ * stateless verifier does not need to be told the domain out-of-band.
  */
 interface QrlSignedTypedDataResult extends QrlSignedResult {
+    schemeVersion: 'QRL-SIGN-TYPED-v1';
     domain: Record<string, unknown>;
 }
+/** Every strict signing-result wire shape understood by this SDK. */
+type QrlSigningResult = QrlSignedMessageResult | QrlSignedTypedDataResult;
+/**
+ * Validate an unknown value as the exact `qrl_signMessage` result wire shape.
+ * This checks structure and fixed widths only. Use `verifyMessageForSigner`
+ * with the original message to authenticate the signature and signer binding.
+ */
+declare function isQrlSignedMessageResult(value: unknown): value is QrlSignedMessageResult;
+/**
+ * Validate an unknown value as the exact `qrl_signTypedData` result wire shape.
+ * This checks structure and fixed widths only. Use `verifyTypedDataForSigner`
+ * with the original payload to authenticate the signature and signer binding.
+ */
+declare function isQrlSignedTypedDataResult(value: unknown): value is QrlSignedTypedDataResult;
+/** Validate either exact signing-result wire shape from an unknown value. */
+declare function isQrlSignedResult(value: unknown): value is QrlSigningResult;
+/**
+ * Strictly validate an unknown signing result and narrow it to one carrying
+ * the exact 3-byte ML-DSA descriptor required for signer-bound verification.
+ */
+declare function hasSigningDescriptor(result: unknown): result is QrlSigningResult & QrlSignedResultWithDescriptor;
 /**
  * `qrl_signMessage` params: `[signer, messageHex]`. `signer` must equal the
  * dApp's currently-connected account; the wallet rejects mismatches before
@@ -279,10 +338,10 @@ interface QrlSignedTypedDataResult extends QrlSignedResult {
  */
 type QrlSignMessageParams = [string, string];
 /**
- * `qrl_signTypedData` params: `[signer, payload]`. Payload mirrors EIP-712
- * shape: `{ types, primaryType, domain, message }`, but with `QRLDomain`
- * in place of `EIP712Domain` and SHAKE256-based hashing. See `signing/`
- * for the full encoder.
+ * Reserved `qrl_signTypedData` params: `[signer, payload]`. This interface
+ * describes the historical v1 payload retained by the verifier exports. The
+ * QIP-55 provider rejects requests until a versioned 64-byte encoding is
+ * defined.
  */
 interface QrlTypedDataPayload {
     types: Record<string, readonly {
@@ -353,6 +412,12 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private orphanedRequests;
     private readonly requestIdPrefix;
     private requestCounter;
+    private requestGeneration;
+    private requestCancellationMessage;
+    private lifecycleTransition;
+    private disconnectInFlight;
+    private restrictedRequestActive;
+    private restrictedRequestQueue;
     readonly isQRLConnect = true;
     constructor(options: QRLConnectOptions);
     private startEip6963Announce;
@@ -374,6 +439,10 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
      */
     stopEip6963Announce(): void;
     private setupConnectionListeners;
+    private handleJsonRpcResponse;
+    private cancelAllRequests;
+    private assertRequestGeneration;
+    private isCurrentChain;
     /**
      * Generate a connection URI for QR code display or deep link redirect.
      */
@@ -393,6 +462,15 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
         method: string;
         params?: unknown[];
     }): Promise<unknown>;
+    /**
+     * Keep at most one approval-bound request active. Wallet approval screens
+     * are a serial human interaction, and request-id ordering must remain
+     * stable even when a dApp fires several signing calls concurrently.
+     */
+    private enqueueRestrictedRequest;
+    private runRestrictedRequest;
+    private finishRestrictedRequest;
+    private performRequest;
     /**
      * Redirect only for calls the user must approve, on mobile, and only when
      * the wallet is actually absent from the channel: right after pairing its
@@ -470,7 +548,7 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
 /**
  * Connection Manager - orchestrates socket lifecycle, the post-quantum
  * handshake, encrypted message routing, and session persistence for the
- * dApp side of QRL Connect v2.
+ * dApp side of QRL Connect v3.
  */
 
 interface ConnectionManagerEvents {
@@ -510,6 +588,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private pendingRestore;
     private messageQueue;
     private outboundQueue;
+    private persistenceQueue;
+    private readonly storage;
+    private readonly persistenceEnabled;
+    private readonly sessionOwnership;
+    private persistenceBroken;
+    private sessionCreatedAt;
+    private sessionGeneration;
     private consecutiveDecryptFailures;
     private static MAX_RECONNECT_FAILURES;
     private static MAX_DECRYPT_FAILURES;
@@ -520,9 +605,11 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
         storageKey?: string | undefined;
     });
     private setupSocketListeners;
+    private handleAutoReconnected;
     private setupKeyExchangeListeners;
     /**
-     * Generate a new v2 connection URI. Rotates channel id and keypair.
+     * Generate a new v3 connection URI. Rotates channel id, keypair, and the
+     * QR-only pairing capability.
      * Returns a `qrlconnect://?q=…` URI safe for QR-rendering or deep-link.
      */
     getConnectionURI(retryOnConflict?: boolean): Promise<string>;
@@ -585,6 +672,11 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     sendJsonRpc(request: JsonRpcRequest): Promise<void>;
     getStatus(): ConnectionStatus;
     getAccounts(): string[];
+    /**
+     * Commit accounts returned by an approved qrl_requestAccounts response.
+     * WALLET_INFO alone cannot grant this authorization.
+     */
+    authorizeAccounts(value: unknown): Promise<string[]>;
     getChainId(): string;
     getChannelId(): string;
     /** Check (sync) if a persisted session exists and has not expired. */
@@ -597,6 +689,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * instant disconnect. Mirrors the wallet side's pattern.
      */
     private flushTerminate;
+    /**
+     * Ensure this socket is a relay participant before closing a restorable or
+     * temporarily disconnected channel. close_channel is intentionally
+     * participant-only on the relay, so a cold stored session cannot be retired
+     * by emitting the close event from an unjoined socket.
+     */
+    private prepareRelayChannelForRetirement;
     /**
      * Reset to a fresh channel + keypair. Sends TERMINATE to any live peer,
      * drops the persisted session, and prepares a clean state for
@@ -616,6 +715,7 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * clear local state and surface the standard terminated teardown.
      */
     private teardownDesyncedSession;
+    private teardownPersistenceFailedSession;
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
@@ -634,8 +734,17 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private setStatus;
     private isDappParticipantConflictError;
     private areArraysEqual;
+    private invalidateSessionWork;
+    private captureSessionWorkContext;
+    private isSessionWorkCurrent;
+    private assertSessionWorkCurrent;
+    private acquireSessionOwnership;
+    private releaseSessionOwnership;
     private persistSession;
+    private persistSessionNow;
     private readStoredSession;
+    private removeStoredSession;
+    private removeStoredSessionOrThrow;
     private clearSession;
 }
 
@@ -644,7 +753,7 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
  */
 
 interface SocketClientEvents {
-    message: (data: RelayMessage) => void;
+    message: (data: unknown) => void;
     connected: () => void;
     disconnected: (reason: string) => void;
     reconnected: (result: JoinResult) => void;
@@ -658,7 +767,7 @@ 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
+     * Populated for wallet joins (v3 protocol). `null` if the dApp hasn't
      * registered a PK yet - wallet callers must treat this as a retry signal.
      */
     channelPublicKey: string | null;
@@ -683,6 +792,9 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
     private publicKeyBase64;
     private seq;
     private pendingJoin;
+    private pendingSends;
+    private pendingJoinAttempts;
+    private get expectedPeerType();
     constructor(relayUrl: string, clientType: 'dapp' | 'wallet');
     /**
      * dApp-only: stash the PK so it gets uploaded on every join_channel
@@ -705,6 +817,7 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
      */
     joinChannel(channelId: string): Promise<JoinResult>;
     private joinChannelNow;
+    private rejectPendingJoinAttempts;
     /**
      * Send a message through the relay.
      */
@@ -712,6 +825,7 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
         success: boolean;
         buffered: boolean;
     }>;
+    private rejectPendingSends;
     /**
      * Emit an event and resolve once the relay acks it, or after a bounded
      * flush window. Lets a caller await transmission before tearing the
@@ -725,7 +839,7 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
      * peer could not open it). Resolves once the close is flushed or the
      * bounded window elapses, so the caller can safely disconnect afterwards.
      */
-    closeChannel(): Promise<void>;
+    closeChannel(): Promise<boolean>;
     /**
      * Leave the current channel.
      */
@@ -773,14 +887,30 @@ declare const DIGEST_LEN = 64;
 declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
 
 /**
- * EIP-712-shaped typed-data encoding for `qrl_signTypedData` v1.
+ * Historical 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 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.
+ *
+ * The v1 address slot is 32 bytes. QIP-55 address fields fail closed until a
+ * 64-byte encoding receives a new scheme tag and lockstep wallet fixtures.
+ * Address-free digests retain their existing encoding.
  */
+declare const TYPED_DATA_LIMITS: Readonly<{
+    maxTypes: 32;
+    maxFieldsPerType: 32;
+    maxTotalFields: 256;
+    maxTypeGraphDepth: 12;
+    maxArrayNesting: 12;
+    maxArrayLength: 256;
+    maxEncodedValues: 2048;
+    maxDynamicBytes: number;
+    maxIdentifierLength: 64;
+    maxFieldTypeLength: 128;
+}>;
 type FieldType = string;
 interface TypedField {
     name: string;
@@ -800,28 +930,70 @@ declare function encodeType(primary: string, types: TypeMap): string;
 declare function typeHash(primary: string, types: TypeMap): Uint8Array;
 declare function encodeField(type: FieldType, value: unknown, types: TypeMap): Uint8Array;
 declare function hashStruct(primary: string, data: Message, types: TypeMap): Uint8Array;
-declare function computeTypedDataDigest(payload: TypedDataPayload): Uint8Array;
+declare function computeTypedDataDigest(payload: unknown): Uint8Array;
 
 /**
  * Stateless verifiers for the two PQ signing schemes. The SDK exposes these
  * so a dApp can re-verify the rich response object returned by the wallet
- * without round-tripping back through the relay. They never touch a secret
- * key and never derive an address; that's the wallet's job.
+ * without round-tripping back through the relay. The lower-level
+ * verifyMessageSignature / verifyTypedDataSignature prove only that a
+ * supplied public key made the signature. Authorization decisions should use
+ * the ForSigner variants, which also bind that key to the expected
+ * current-format address.
  */
 
+declare const ML_DSA_DESCRIPTOR_BYTES = 3;
+declare const ML_DSA_87_PUBLIC_KEY_BYTES = 2592;
+declare const ML_DSA_87_SIGNATURE_BYTES = 4627;
 interface VerifyMessageParams {
     signature: Uint8Array | string;
     publicKey: Uint8Array | string;
     /** 0x-hex bytes that were originally signed. */
     messageBytes: Uint8Array | string;
 }
-declare function verifyMessage({ signature, publicKey, messageBytes, }: VerifyMessageParams): boolean;
+/**
+ * Verify against an explicitly supplied ML-DSA public key only. This does not
+ * prove that the key derives the signer claimed by a wallet response. Use
+ * verifyMessageForSigner for authentication or authorization decisions.
+ */
+declare function verifyMessageSignature({ signature, publicKey, messageBytes, }: VerifyMessageParams): boolean;
 interface VerifyTypedDataParams {
     signature: Uint8Array | string;
     publicKey: Uint8Array | string;
     payload: TypedDataPayload;
 }
-declare function verifyTypedData({ signature, publicKey, payload }: VerifyTypedDataParams): boolean;
+/**
+ * Verify against an explicitly supplied ML-DSA public key only. This does not
+ * bind that key to a Q-address. Use verifyTypedDataForSigner when signer
+ * identity matters.
+ */
+declare function verifyTypedDataSignature({ signature, publicKey, payload, }: VerifyTypedDataParams): boolean;
+interface VerifyMessageForSignerParams extends VerifyMessageParams {
+    /** QIP-55 Q + 128 hex address expected by the dApp. */
+    expectedSigner: string;
+    /** Exact 3-byte wallet descriptor. Missing legacy values fail closed. */
+    descriptor?: Uint8Array | string | undefined;
+}
+/** Verify both the message signature and public-key-to-signer binding. */
+declare function verifyMessageForSigner({ expectedSigner, descriptor, signature, publicKey, messageBytes, }: VerifyMessageForSignerParams): boolean;
+interface VerifyTypedDataForSignerParams extends VerifyTypedDataParams {
+    /** QIP-55 Q + 128 hex address expected by the dApp. */
+    expectedSigner: string;
+    /** Exact 3-byte wallet descriptor. Missing legacy values fail closed. */
+    descriptor?: Uint8Array | string | undefined;
+}
+/** Verify both the typed-data signature and public-key-to-signer binding. */
+declare function verifyTypedDataForSigner({ expectedSigner, descriptor, signature, publicKey, payload, }: VerifyTypedDataForSignerParams): boolean;
+/**
+ * @deprecated Use verifyMessageSignature for a key-only check, or
+ * verifyMessageForSigner when signer identity matters.
+ */
+declare function verifyMessage(params: VerifyMessageParams): boolean;
+/**
+ * @deprecated Use verifyTypedDataSignature for a key-only check, or
+ * verifyTypedDataForSigner when signer identity matters.
+ */
+declare function verifyTypedData(params: VerifyTypedDataParams): boolean;
 
 /**
  * Local hex/bytes utilities for the signing module.
@@ -833,38 +1005,40 @@ declare function bytesToHex(bytes: Uint8Array): string;
 declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
 
 /**
- * v2 QR URI codec (PQP2).
+ * v3 QR URI codec (PQP3).
  *
- * Format: qrlconnect://?q=<base45(PQP2 || cid || fp)>[&r=<relayUrl>]
+ * Format: qrlconnect://?q=<base45(PQP3 || cid || fp || cap)>[&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)
+ *   PQP3 = "PQP3" magic                                        (4 B)
+ *   cid  = 16 bytes (UUIDv4 raw)                               (16 B)
+ *   fp   = SHA-256("pq-fp/v3" || cid || pk || cap) (full 32B) (32 B)
+ *   cap  = fresh CSPRNG pairing capability                     (32 B)
+ *   total                                                       (84 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.
+ * The capability is a bearer secret. It is never uploaded to the relay and
+ * must not be logged or persisted before the handshake consumes it.
  *
  * 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.
+ * the wallet fetches it via the join_channel ack. The fingerprint commits
+ * the relay-served key to the exact out-of-band capability. The capability
+ * is also bound into the transcript and HKDF by the key-exchange layer, so a
+ * relay cannot fabricate an authenticated wallet hello.
  *
- * 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.
+ * Legacy PQP1 and PQP2 URIs are rejected with a clear migration error. This
+ * intentional v4.0 break prevents fallback to a pairing mode where the relay
+ * could impersonate a wallet.
  */
 declare const CID_LEN = 16;
 declare const FP_LEN = 32;
+declare const CAP_LEN = 32;
 declare const BLOB_LEN: number;
+declare const MAX_CONNECTION_URI_LENGTH = 4096;
 /**
- * Compute the full 32-byte fingerprint binding (label || cid || pk).
+ * Compute the full 32-byte fingerprint binding (label || cid || pk || cap).
  * Exported so the wallet side can re-derive and verify.
  */
-declare function computeFingerprint(cid: Uint8Array, pk: Uint8Array): Promise<Uint8Array>;
+declare function computeFingerprint(cid: Uint8Array, pk: Uint8Array, capability: 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
@@ -872,18 +1046,19 @@ 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
- * upload the PK to the relay separately before publishing this URI.
+ * Encode (cid, pk, capability) as a qrlconnect:// URI. The PK is not stored
+ * in the URI; only its capability-bound fingerprint is embedded. 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>;
+declare function generateConnectionURI(cid: Uint8Array, pk: Uint8Array, capability: Uint8Array, relayUrl?: string): Promise<string>;
 interface ParsedURI {
     cid: Uint8Array;
     fp: Uint8Array;
+    capability: Uint8Array;
     relayUrl?: string | undefined;
 }
 declare function parseConnectionURI(uri: string): Promise<ParsedURI>;
@@ -922,21 +1097,42 @@ declare function getAppStoreUrl(): string;
  */
 declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
+declare const QRL_ADDRESS_BYTES = 64;
+declare const QRL_ADDRESS_HEX_LENGTH: number;
+/**
+ * Validate the QRL 2.0 text form. The prefix is the network's uppercase Q.
+ * A case-uniform hex body is accepted for compatibility. Mixed-case input
+ * must carry the canonical SHAKE256 QIP-55 checksum.
+ */
+declare function isCurrentQrlAddress(value: unknown): value is string;
+/** Stable visual fingerprint for long QRL addresses. */
+declare function formatQrlAddressFingerprint(address: string): string;
+/** Format exactly 64 address bytes as the canonical mixed-case QIP-55 form. */
+declare function qip55AddressFromBytes(address: Uint8Array): string;
+
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
-declare const PROTOCOL_VERSION = 2;
+declare const PROTOCOL_VERSION = 3;
+declare const PAIRING_CAPABILITY_LEN = 32;
+declare const MAX_JSON_RPC_ID_LENGTH = 128;
+declare const MAX_JSON_RPC_METHOD_LENGTH = 128;
+declare const MAX_RELAY_URL_LENGTH = 2048;
 /**
- * RPC methods that require user approval in the wallet.
- *
- * v3.0.0 replaces the Ethereum-flavored signing surface with two
- * post-quantum-native methods: `qrl_signMessage` for opaque bytes and
- * `qrl_signTypedData` for structured payloads (EIP-712-shaped, but with
- * SHAKE256 + native Dilithium ctx). The legacy methods (`personal_sign`,
- * `qrl_sign`, `qrl_signTypedData_v3`, `qrl_signTypedData_v4`) are no
- * longer accepted; a dApp calling them via this SDK will get a
- * "method not supported" error before the relay round-trip.
- */
-declare const RESTRICTED_METHODS: Set<string>;
-/** RPC methods that can be auto-proxied without approval */
-declare const UNRESTRICTED_METHODS: Set<string>;
+ * Validate and canonicalize relay endpoints before they reach logging,
+ * Socket.IO, or a QR URI. Production relays require HTTPS; plain HTTP is
+ * limited to explicit loopback hostnames for local development.
+ */
+declare function normalizeRelayUrl(value: unknown): string;
+/** Public snapshots for discovery. Provider authorization uses private sets. */
+declare const RESTRICTED_METHODS: ReadonlySet<string>;
+declare const UNRESTRICTED_METHODS: ReadonlySet<string>;
+declare const EXPLICITLY_UNSUPPORTED_METHODS: ReadonlySet<string>;
+type RpcMethodPolicy = 'restricted' | 'unrestricted' | 'unsupported';
+declare function isValidJsonRpcId(value: unknown): value is string | number;
+declare function isValidJsonRpcMethod(value: unknown): value is string;
+/**
+ * Classify an RPC method with a closed allowlist. Any method absent from the
+ * two positive policy sets is unsupported, including future signing methods.
+ */
+declare function classifyRpcMethod(method: string): RpcMethodPolicy;
 
-export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };
+export { type AckMessage, BLOB_LEN, CAP_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, EXPLICITLY_UNSUPPORTED_METHODS, FP_LEN, type InitiatedKeyExchange, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MAX_CONNECTION_URI_LENGTH, MAX_JSON_RPC_ID_LENGTH, MAX_JSON_RPC_METHOD_LENGTH, MAX_RELAY_URL_LENGTH, ML_DSA_87_PUBLIC_KEY_BYTES, ML_DSA_87_SIGNATURE_BYTES, ML_DSA_DESCRIPTOR_BYTES, type Message, MessageType, PAIRING_CAPABILITY_LEN, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_ADDRESS_BYTES, QRL_ADDRESS_HEX_LENGTH, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedMessageResult, type QrlSignedResult, type QrlSignedResultWithDescriptor, type QrlSignedTypedDataResult, type QrlSigningResult, type QrlSigningSchemeVersion, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, type RpcMethodPolicy, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, TYPED_DATA_LIMITS, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageForSignerParams, type VerifyMessageParams, type VerifyTypedDataForSignerParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, classifyRpcMethod, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, formatQrlAddressFingerprint, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isCurrentQrlAddress, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, qip55AddressFromBytes, typeHash, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };