@qrlwallet/connect 3.2.0 → 4.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",
@@ -182,6 +204,22 @@ declare enum ConnectionStatus {
     CONNECTED = "connected",
     RECONNECTING = "reconnecting"
 }
+/**
+ * A response for a request issued by a PREVIOUS page load. Same-device
+ * approvals bounce back via a URL open, which reloads the dApp page and
+ * destroys the awaiting promise; the SDK persists in-flight restricted
+ * request ids and surfaces their eventual responses through this event.
+ */
+interface LateResponse {
+    id: string | number;
+    method: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
 /** EIP-1193 provider events */
 interface ProviderEvents {
     connect: (info: {
@@ -198,6 +236,7 @@ interface ProviderEvents {
         data: unknown;
     }) => void;
     statusChanged: (status: ConnectionStatus) => void;
+    late_response: (payload: LateResponse) => void;
 }
 /** JSON-RPC request */
 interface JsonRpcRequest {
@@ -233,28 +272,65 @@ interface EIP6963ProviderInfoOverride {
  * 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.
+ * wallet always 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;
+    /** Current 41-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.
  */
 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
@@ -297,6 +373,16 @@ interface QRLConnectOptions {
     announceProvider?: boolean;
     /** Override the EIP-6963 announce metadata (name / icon / rdns). */
     providerInfo?: EIP6963ProviderInfoOverride;
+    /**
+     * On mobile browsers, deep-link (`qrlconnect://resume`) to foreground the
+     * wallet app when a restricted request is made while the wallet is absent
+     * from the relay channel. A backgrounded wallet app loses its socket
+     * within seconds; the relay buffers the request, and without the redirect
+     * it would sit there until the user remembers to switch apps on their
+     * own. Defaults to true. Set false when the dApp runs its own
+     * "open wallet" UX.
+     */
+    walletRedirectOnRequest?: boolean;
 }
 
 /**
@@ -322,8 +408,16 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private eip6963RequestListener;
     private resumeListener;
     private resumeDebounce;
+    private inflightKey;
+    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;
@@ -345,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.
      */
@@ -364,6 +462,45 @@ 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
+     * socket lingers and a pointless app flash would be jarring.
+     *
+     * qrl_requestAccounts is excluded even though it is restricted: dApps call
+     * it on page load to restore a session, so it can run with no user gesture
+     * (an unsolicited "Open in MyQRLWallet?" sheet on load) and pairing UIs
+     * already own their own deep-link step.
+     */
+    private shouldRedirectToWallet;
+    private readInflight;
+    private writeInflight;
+    private persistInflight;
+    private settleInflight;
+    private clearAllInflight;
+    /**
+     * Wake URI for the wallet app. Carries no pairing payload: the app
+     * foregrounds on any `qrlconnect:` URL and re-joins its sessions (draining
+     * the buffered request); the cid lets a future wallet jump straight to the
+     * right approval.
+     *
+     * MUST stay query-only (no host/path). The mobile app routes deep links
+     * with expo-router, which maps anything after the scheme to an in-app
+     * route: `qrlconnect://resume?...` lands on the "+not-found" screen and
+     * unmounts the WebView, so the wake achieves nothing. The hostless form
+     * routes to the WebView tab exactly like the pairing URIs
+     * (`qrlconnect://?q=...`), which is the whole point of the wake.
+     */
+    private walletWakeUri;
     /**
      * Get the current connection status.
      */
@@ -384,6 +521,15 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
      * Check if a stored session exists that can be reconnected.
      */
     hasStoredSession(): boolean;
+    /**
+     * True while a pairing exists (keys exchanged), even when the wallet app
+     * is backgrounded and its socket is out of the channel. Combine with
+     * getStatus() to tell "wallet away, session intact" (paired + WAITING)
+     * apart from "waiting for a first scan" in pairing UIs.
+     */
+    isPaired(): boolean;
+    /** True while the wallet is actually present in the relay channel. */
+    isWalletPresent(): boolean;
     /**
      * Reset the connection and start a fresh pairing with a new channel.
      * Use this when the user wants to create a new connection instead of
@@ -402,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 {
@@ -415,6 +561,13 @@ interface ConnectionManagerEvents {
         chainId: string;
     }) => void;
     connection_lost: () => void;
+    /**
+     * The session is dead for good (wallet TERMINATE, relay 'close', or a
+     * tombstone observed on join). Distinct from a transient DISCONNECTED:
+     * in-flight requests can never be answered and must be failed promptly
+     * instead of running out the full request timeout.
+     */
+    session_terminated: () => void;
     error: (error: Error) => void;
 }
 declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
@@ -429,12 +582,22 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private storageKey;
     private unresponsiveTimer;
     private reconnectProbeTimer;
+    private restoreInFlight;
     private failedReconnects;
     private walletPresent;
     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;
     constructor(options: {
         dappMetadata: DAppMetadata;
         relayUrl?: string | undefined;
@@ -442,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>;
@@ -453,6 +618,7 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * Returns false if there is nothing to restore.
      */
     reconnect(): Promise<boolean>;
+    private reconnectNow;
     /**
      * (Re)open the socket, join the persisted channel, drain buffered relay
      * messages, and settle status. Shared by the cold-restore reconnect() and
@@ -469,6 +635,25 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * own connect handler re-joins the channel and drains the relay buffer.
      */
     resume(): void;
+    /**
+     * Make sure the socket is open and joined to the paired session's channel
+     * so an outbound request can be routed - or relay-buffered if the wallet is
+     * currently absent (its socket dies within seconds of the app
+     * backgrounding; the relay holds channel traffic for it). Revives the
+     * socket after a probe-timeout teardown and hydrates a cold stored
+     * session. Returns false when there is no session to revive (never paired,
+     * explicit disconnect, or the channel was tombstoned).
+     */
+    ensureChannelJoined(): Promise<boolean>;
+    /**
+     * True while a pairing exists (handshake complete, session keys in
+     * memory), even when the wallet's socket is momentarily out of the
+     * channel. Survives the reconnect-probe teardown; false after an explicit
+     * disconnect or a relay tombstone.
+     */
+    isPaired(): boolean;
+    /** True while the relay roster last showed the wallet in the channel. */
+    isWalletPresent(): boolean;
     /**
      * A session was terminated for good (wallet sent a relay 'close', or the
      * join ack reported a tombstone). Clear local state and surface
@@ -478,11 +663,20 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private armReconnectProbe;
     private clearReconnectProbe;
     /**
-     * Send a JSON-RPC request to the wallet (async, fire-and-forget).
+     * Send a JSON-RPC request to the wallet. Returns the outbound send promise
+     * (settled on the relay's ack) so callers that must sequence on delivery -
+     * e.g. the provider's wallet-wake redirect, which cannot navigate away
+     * before the ciphertext reaches the relay - can await it. Callers may also
+     * ignore it: failures are logged here either way.
      */
-    sendJsonRpc(request: JsonRpcRequest): void;
+    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. */
@@ -495,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
@@ -504,6 +705,17 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     disconnect(): Promise<void>;
     private enqueueRelayMessage;
     private handleRelayMessage;
+    /**
+     * The receive stream is cryptographically unrecoverable: the peer's send
+     * counter is ahead of our recv counter for good (relay buffer TTL/cap
+     * dropped a ciphertext), so every future message would fail its tag.
+     * An encrypted TERMINATE cannot communicate this (the desynced peer could
+     * not open it either); tombstone the channel on the relay instead so the
+     * wallet learns the pairing is dead even if it only re-joins later, then
+     * clear local state and surface the standard terminated teardown.
+     */
+    private teardownDesyncedSession;
+    private teardownPersistenceFailedSession;
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
@@ -522,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;
 }
 
@@ -532,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;
@@ -546,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;
@@ -571,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
@@ -593,6 +817,7 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
      */
     joinChannel(channelId: string): Promise<JoinResult>;
     private joinChannelNow;
+    private rejectPendingJoinAttempts;
     /**
      * Send a message through the relay.
      */
@@ -600,6 +825,21 @@ 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
+     * socket down.
+     */
+    private flushEmit;
+    /**
+     * Explicitly terminate the channel on the relay (durable tombstone), as
+     * opposed to the transient leaveChannel(). Used when the session is dead
+     * in a way an encrypted TERMINATE cannot communicate (AEAD desync: the
+     * 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<boolean>;
     /**
      * Leave the current channel.
      */
@@ -655,6 +895,18 @@ declare function computeMessageDigest(messageBytes: Uint8Array): Uint8Array;
  * the wallet copy for the spec-level comments; behavior must stay in
  * lock-step or the cross-repo parity test fails on next CI.
  */
+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;
@@ -674,28 +926,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 {
+    /** Current Q + 40 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 {
+    /** Current Q + 40 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.
@@ -707,38 +1001,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
@@ -746,18 +1042,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>;
@@ -797,20 +1094,28 @@ declare function getAppStoreUrl(): string;
 declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
 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_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, generateConnectionURI, getAppStoreUrl, hasSigningDescriptor, hashStruct, hexToBytes, isMobileBrowser, isQrlSignedMessageResult, isQrlSignedResult, isQrlSignedTypedDataResult, isValidJsonRpcId, isValidJsonRpcMethod, normalizeRelayUrl, parseConnectionURI, typeHash, verifyMessage, verifyMessageForSigner, verifyMessageSignature, verifyTypedData, verifyTypedDataForSigner, verifyTypedDataSignature };