walletpair-sdk 1.0.0

package/dist/dapp-session.js

@@ -0,0 +1,918 @@
+/**
+ * DApp-side WalletPair session.
+ *
+ * Manages the full lifecycle: create channel → QR → wallet joins → accept →
+ * encrypted request/response + events.
+ */
+import { b64urlDecode, b64urlEncode, buildPairingUri, bytesToHex, canonicalJson, computeSessionFingerprint, computeSharedSecret, deriveDirectionalSessionKeys, deriveJoinEncryptionKey, deriveSessionKey, generateChannelId, generateX25519KeyPair, hexToBytes, sealPayload, signSnapshot, unsealJoin, unsealPayload, verifySnapshot, } from './crypto.js';
+import { Emitter } from './emitter.js';
+const BACKOFF = [1000, 2000, 5000, 10000, 30000];
+const DEFAULT_REQUEST_TIMEOUT = 120_000;
+const PENDING_ACCEPT_TIMEOUT = 60_000;
+const MAX_SEND_SEQ = 2 ** 31;
+const MAX_PENDING_REQUESTS = 32; // §15 rule 11
+const MAX_MESSAGE_BYTES = 65536; // §15 rule 10: 64 KB
+const DEFAULT_SESSION_TTL = 24 * 60 * 60 * 1000; // 24 hours (§16 rule 16)
+function isPromiseLike(value) {
+    return !!value && typeof value.then === 'function';
+}
+function validateCapabilities(cap) {
+    if (cap == null || typeof cap !== 'object')
+        return false;
+    const c = cap;
+    return Array.isArray(c.methods) && Array.isArray(c.events) && Array.isArray(c.chains);
+}
+export class DAppSession extends Emitter {
+    phase = 'idle';
+    /** Channel ID (hex). Available after createPairing(). */
+    channelId = '';
+    /** Pairing URI. Available after createPairing(). */
+    pairingUri = '';
+    /** 4-digit session fingerprint. Available after createPairing(). */
+    sessionFingerprint = '';
+    /** Remote wallet capabilities. Available after wallet joins. */
+    walletCapabilities = undefined;
+    /** Remote wallet metadata. Available after wallet joins. */
+    walletMeta = undefined;
+    approvedCapabilities = undefined;
+    approvedWalletMeta = undefined;
+    approvedWalletPubKeyB64 = undefined;
+    approvedScopeRecorded = false;
+    transport;
+    meta;
+    declaredMethods;
+    declaredChains;
+    requestTimeout;
+    autoAccept;
+    /** Session lifetime in ms (§16 rule 16). */
+    sessionTtl;
+    sessionTtlTimer = null;
+    sessionStartTime = null;
+    privKey;
+    pubKeyB64 = '';
+    remotePubKey = null;
+    sessionKey = null;
+    sendKey = null;
+    recvKey = null;
+    sendSeq = 0;
+    recvSeq = -1;
+    paired = false;
+    intentionalClose = false;
+    reqCounter = 0;
+    pendingRequests = new Map();
+    persistence;
+    pendingAcceptTimer = null;
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+    constructor(options) {
+        super();
+        this.transport = options.transport;
+        this.meta = options.meta;
+        this.declaredMethods = options.methods;
+        this.declaredChains = options.chains;
+        this.requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+        this.autoAccept = options.autoAccept ?? true;
+        this.sessionTtl = options.sessionTtl ?? DEFAULT_SESSION_TTL;
+        this.persistence = options.persistence;
+        this.transport.onMessage((msg) => this.handleMessage(msg));
+        this.transport.onClose(() => this.handleTransportClose());
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Create a new pairing channel and return the pairing URI for QR display.
+     *
+     * @param options.deferTransport - If true, don't connect the transport yet.
+     *   Call `connectTransport()` later (e.g. after user scans QR in BLE mode).
+     */
+    async createPairing(options) {
+        this.intentionalClose = false;
+        const kp = generateX25519KeyPair();
+        this.privKey = kp.privateKey;
+        this.pubKeyB64 = kp.publicKeyB64;
+        this.channelId = generateChannelId();
+        this.sendSeq = 0;
+        this.recvSeq = -1;
+        this.remotePubKey = null;
+        this.sessionKey = null;
+        this.sendKey = null;
+        this.recvKey = null;
+        this.sessionStartTime = null;
+        this.clearSessionTtl();
+        this.approvedCapabilities = undefined;
+        this.approvedWalletMeta = undefined;
+        this.approvedWalletPubKeyB64 = undefined;
+        this.approvedScopeRecorded = false;
+        this.reqCounter = 0;
+        this.paired = false;
+        // Build pairing URI first (before transport connect, so BLE can show QR first)
+        let relayUrl;
+        const transportWithUrl = this.transport;
+        if (typeof transportWithUrl.url === 'string') {
+            relayUrl = transportWithUrl.url;
+        }
+        this.pairingUri = buildPairingUri({
+            channelId: this.channelId,
+            pubkeyB64: this.pubKeyB64,
+            relayUrl,
+            name: this.meta.name,
+            url: this.meta.url,
+            icon: this.meta.icon,
+            methods: this.declaredMethods,
+            chains: this.declaredChains,
+        });
+        this.sessionFingerprint = computeSessionFingerprint(this.channelId, this.pubKeyB64);
+        this.emit('pairingUri', this.pairingUri);
+        this.emit('sessionFingerprint', this.sessionFingerprint);
+        if (!options?.deferTransport) {
+            await this.connectTransport();
+        }
+        else {
+            this.setPhase('waiting');
+        }
+        return this.pairingUri;
+    }
+    /**
+     * Connect the transport and send the `create` message.
+     * Call this after `createPairing({ deferTransport: true })` when the user
+     * is ready (e.g. after showing QR and before BLE scan).
+     */
+    async connectTransport() {
+        this.setTransportChannelHint();
+        await this.transport.connect();
+        this.setPhase('waiting');
+        this.sendRaw({
+            v: 1,
+            t: 'create',
+            ch: this.channelId,
+            ts: Date.now(),
+            from: this.pubKeyB64,
+            body: { meta: this.meta },
+        });
+    }
+    /** Accept the wallet after sealed_join verification. */
+    acceptWallet() {
+        if (this.phase !== 'pending_accept' || !this.remotePubKey)
+            return;
+        this.clearPendingAcceptTimer();
+        this.doAccept();
+    }
+    /** Reject the wallet. */
+    rejectWallet() {
+        if (!this.remotePubKey)
+            return;
+        this.sendRaw({
+            v: 1,
+            t: 'close',
+            ch: this.channelId,
+            ts: Date.now(),
+            from: this.pubKeyB64,
+            body: { reason: 'user_rejected' },
+        });
+        this.close();
+    }
+    /** Send an encrypted request to the wallet. Returns the decrypted response. */
+    request(method, params) {
+        if (this.phase !== 'connected' || !this.sendKey) {
+            return Promise.reject(new Error('Not connected'));
+        }
+        // §15 rule 11: max 32 pending requests
+        if (this.pendingRequests.size >= MAX_PENDING_REQUESTS) {
+            return Promise.reject(new Error('Too many pending requests'));
+        }
+        const id = `req-${++this.reqCounter}`;
+        // Always seal: even parameterless requests must be authenticated via AEAD
+        // to prevent method injection by a malicious relay.
+        const send = (seq) => {
+            // AAD: no method field — real method goes inside sealed payload
+            const hdr = { type: 'req', from: this.pubKeyB64, id };
+            const sealedParams = {
+                _method: method,
+                ...(params && typeof params === 'object'
+                    ? params
+                    : { _params: params ?? {} }),
+            };
+            const sealed = sealPayload(this.sendKey, this.channelId, seq, sealedParams, hdr);
+            const msg = {
+                v: 1,
+                t: 'req',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { id, sealed },
+            };
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`Request ${method} timed out`));
+                }, this.requestTimeout);
+                this.pendingRequests.set(id, { id, method, resolve: resolve, reject, timer });
+                this.sendRaw(msg);
+            });
+        };
+        try {
+            const seqOrPromise = this.nextSendSeq();
+            return isPromiseLike(seqOrPromise) ? seqOrPromise.then(send) : send(seqOrPromise);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /** Send ping. */
+    ping() {
+        if (this.phase !== 'connected')
+            return;
+        this.sendRaw({
+            v: 1,
+            t: 'ping',
+            ch: this.channelId,
+            ts: Date.now(),
+            from: this.pubKeyB64,
+            body: {},
+        });
+    }
+    /** Gracefully close the session. */
+    close(reason = 'normal') {
+        this.intentionalClose = true;
+        this.clearPendingAcceptTimer();
+        this.clearSessionTtl();
+        this.stopReconnect();
+        for (const [, req] of this.pendingRequests) {
+            if (req.timer)
+                clearTimeout(req.timer);
+            req.reject(new Error('Session closed'));
+        }
+        this.pendingRequests.clear();
+        if (this.channelId) {
+            this.sendRaw({
+                v: 1,
+                t: 'close',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { reason },
+            });
+        }
+        this.clearPersistence();
+        this.transport.disconnect();
+        this.setPhase('closed');
+    }
+    /** Destroy the session and release all resources. */
+    destroy() {
+        this.close();
+        this.removeAll();
+        // Wipe sensitive key material (§20.7)
+        if (this.privKey)
+            this.privKey.fill(0);
+        if (this.sessionKey)
+            this.sessionKey.fill(0);
+        if (this.sendKey)
+            this.sendKey.fill(0);
+        if (this.recvKey)
+            this.recvKey.fill(0);
+        this.sessionKey = null;
+        this.sendKey = null;
+        this.recvKey = null;
+    }
+    // -------------------------------------------------------------------------
+    // State serialization (for persistence across page reloads)
+    // -------------------------------------------------------------------------
+    serialize() {
+        const json = JSON.stringify({
+            channelId: this.channelId,
+            privKey: bytesToHex(this.privKey),
+            pubKeyB64: this.pubKeyB64,
+            remotePubKeyB64: this.remotePubKey ? b64urlEncode(this.remotePubKey) : null,
+            sendKey: this.sendKey ? bytesToHex(this.sendKey) : null,
+            recvKey: this.recvKey ? bytesToHex(this.recvKey) : null,
+            sendSeq: this.sendSeq,
+            recvSeq: this.recvSeq,
+            reqCounter: this.reqCounter,
+            paired: this.paired,
+            dappMeta: this.meta,
+            approvedScopeRecorded: this.approvedScopeRecorded,
+            approvedCapabilities: this.approvedCapabilities ?? null,
+            approvedWalletMeta: this.approvedWalletMeta ?? null,
+            approvedWalletPubKeyB64: this.approvedWalletPubKeyB64 ?? null,
+            sessionStartTime: this.sessionStartTime,
+        });
+        // HMAC-sign the snapshot so tampered storage (e.g. via XSS) is detected on restore
+        return this.sendKey ? signSnapshot(this.sendKey, json) : json;
+    }
+    async restoreFromPersistence() {
+        if (!this.persistence?.load)
+            return false;
+        const json = await this.persistence.load();
+        return json ? this.restore(json) : false;
+    }
+    restore(signed) {
+        try {
+            // Try HMAC-verified format first: "<hex-mac>.<json>"
+            // Fall back to plain JSON for backward compatibility with unsigned snapshots
+            let json;
+            if (signed.length > 65 && signed[64] === '.') {
+                // Extract sendKey from the JSON to verify HMAC
+                const candidateJson = signed.slice(65);
+                const d0 = JSON.parse(candidateJson);
+                if (!d0.sendKey)
+                    return false;
+                const sendKey = hexToBytes(d0.sendKey);
+                const verified = verifySnapshot(sendKey, signed);
+                if (!verified)
+                    return false; // tampered
+                json = verified;
+            }
+            else {
+                json = signed;
+            }
+            const d = JSON.parse(json);
+            if (!d.channelId || !d.privKey)
+                return false;
+            this.channelId = d.channelId;
+            this.privKey = hexToBytes(d.privKey);
+            this.pubKeyB64 = d.pubKeyB64;
+            this.remotePubKey = d.remotePubKeyB64 ? b64urlDecode(d.remotePubKeyB64) : null;
+            this.sendKey = d.sendKey ? hexToBytes(d.sendKey) : null;
+            this.recvKey = d.recvKey ? hexToBytes(d.recvKey) : null;
+            if (!this.sendKey || !this.recvKey)
+                return false;
+            this.sendSeq = d.sendSeq ?? 0;
+            this.recvSeq = d.recvSeq ?? -1;
+            this.reqCounter = d.reqCounter || 0;
+            this.paired = d.paired || false;
+            this.approvedScopeRecorded = d.approvedScopeRecorded === true;
+            this.approvedCapabilities = d.approvedCapabilities ?? undefined;
+            this.approvedWalletMeta = d.approvedWalletMeta ?? undefined;
+            this.approvedWalletPubKeyB64 = d.approvedWalletPubKeyB64 ?? d.remotePubKeyB64 ?? undefined;
+            this.walletCapabilities = this.approvedCapabilities;
+            this.walletMeta = this.approvedWalletMeta;
+            this.meta =
+                d.dappMeta ??
+                    (d.dappName ? { name: d.dappName, description: '', url: '', icon: '' } : this.meta);
+            this.sessionStartTime = d.sessionStartTime ?? null;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Reconnect after restoring state. */
+    async reconnect() {
+        this.intentionalClose = false;
+        this.stopReconnect();
+        this.setPhase('disconnected');
+        this.reconnectAttempt = 0;
+        await this.doReconnectAttempt();
+    }
+    // -------------------------------------------------------------------------
+    // Internal: message handling
+    // -------------------------------------------------------------------------
+    handleMessage(msg) {
+        // §2: Peers MUST reject any peer-sent message where from equals "_adapter"
+        if (msg.t !== 'ready' && msg.t !== 'terminate' && msg.from === '_adapter') {
+            this.emit('error', new Error('Rejected message with spoofed _adapter from'));
+            return;
+        }
+        // §15 rule 12: reject unsupported protocol version
+        if (msg.v !== 1) {
+            this.close('unsupported_version');
+            return;
+        }
+        switch (msg.t) {
+            case 'ready': {
+                const readyBody = msg.body;
+                this.stopReconnect();
+                if (readyBody.state === 'connected') {
+                    const expectedRemote = this.remotePubKey ? b64urlEncode(this.remotePubKey) : null;
+                    if (!expectedRemote || readyBody.remote !== expectedRemote) {
+                        this.emit('error', new Error('Connected remote does not match paired wallet'));
+                        this.close();
+                        break;
+                    }
+                }
+                if (readyBody.state === 'waiting') {
+                    this.setPhase('waiting');
+                }
+                else if (readyBody.state === 'connected') {
+                    this.setPhase('connected');
+                    this.startSessionTtl();
+                    this.persistSnapshotAsync();
+                }
+                break;
+            }
+            case 'join': {
+                const joinBody = msg.body;
+                const joinPubKey = msg.from;
+                if (!joinPubKey) {
+                    this.emit('error', new Error('Malformed wallet join: missing from'));
+                    break;
+                }
+                let remoteBytes;
+                try {
+                    remoteBytes = b64urlDecode(joinPubKey);
+                    if (remoteBytes.length !== 32)
+                        throw new Error('Invalid wallet public key length');
+                }
+                catch {
+                    this.sendRaw({
+                        v: 1,
+                        t: 'close',
+                        ch: this.channelId,
+                        ts: Date.now(),
+                        from: this.pubKeyB64,
+                        body: { reason: 'protocol_error' },
+                    });
+                    this.emit('error', new Error('Malformed wallet public key'));
+                    break;
+                }
+                this.remotePubKey = remoteBytes;
+                const shared = computeSharedSecret(this.privKey, this.remotePubKey);
+                const rootKey = deriveSessionKey(shared, this.channelId);
+                // §20.7: erase shared_secret immediately
+                shared.fill(0);
+                // For reconnect (sealed_join is null), skip sealed_join decryption
+                let joinCapabilities;
+                let joinMeta;
+                if (joinBody.sealed_join === null && this.paired) {
+                    // Reconnect — capabilities/meta come from previously approved scope
+                    joinCapabilities = this.approvedCapabilities;
+                    joinMeta = this.approvedWalletMeta;
+                }
+                else if (joinBody.sealed_join && typeof joinBody.sealed_join === 'string') {
+                    // Decrypt sealed_join (private handshake §7.5)
+                    let joinKey = null;
+                    try {
+                        joinKey = deriveJoinEncryptionKey(rootKey, this.channelId);
+                        const decrypted = unsealJoin(joinKey, this.channelId, joinBody.sealed_join);
+                        joinCapabilities = decrypted.capabilities;
+                        joinMeta = decrypted.meta;
+                    }
+                    catch {
+                        this.sendRaw({
+                            v: 1,
+                            t: 'close',
+                            ch: this.channelId,
+                            ts: Date.now(),
+                            from: this.pubKeyB64,
+                            body: { reason: 'decryption_failed' },
+                        });
+                        this.emit('error', new Error('Failed to decrypt sealed_join'));
+                        rootKey.fill(0);
+                        break;
+                    }
+                    finally {
+                        // §20.7: erase join_encryption_key after one-shot use.
+                        if (joinKey)
+                            joinKey.fill(0);
+                    }
+                }
+                else {
+                    this.sendRaw({
+                        v: 1,
+                        t: 'close',
+                        ch: this.channelId,
+                        ts: Date.now(),
+                        from: this.pubKeyB64,
+                        body: { reason: 'protocol_error' },
+                    });
+                    this.emit('error', new Error('Initial wallet join missing sealed_join'));
+                    rootKey.fill(0);
+                    break;
+                }
+                // Validate capabilities shape
+                if (joinCapabilities != null && !validateCapabilities(joinCapabilities)) {
+                    this.sendRaw({
+                        v: 1,
+                        t: 'close',
+                        ch: this.channelId,
+                        ts: Date.now(),
+                        from: this.pubKeyB64,
+                        body: { reason: 'protocol_error' },
+                    });
+                    this.emit('error', new Error('Malformed wallet capabilities'));
+                    rootKey.fill(0);
+                    break;
+                }
+                // Warn if wallet omits any of the 5 MUST-support methods (backwards-compatible)
+                if (joinCapabilities) {
+                    const requiredMethods = [
+                        'wallet_getAccounts',
+                        'wallet_signTransaction',
+                        'wallet_signMessage',
+                        'wallet_signTypedData',
+                        'wallet_switchChain',
+                    ];
+                    const declared = new Set(joinCapabilities.methods);
+                    const absent = requiredMethods.filter((m) => !declared.has(m));
+                    if (absent.length > 0) {
+                        console.warn(`[WalletPair] Wallet missing MUST-support methods: ${absent.join(', ')}`);
+                    }
+                }
+                const knownWallet = this.isSameApprovedWallet(joinPubKey, joinCapabilities, joinMeta);
+                this.walletCapabilities = joinCapabilities;
+                this.walletMeta = joinMeta;
+                const context = this.sessionContext(joinPubKey, joinCapabilities, joinMeta);
+                const keys = deriveDirectionalSessionKeys(rootKey, this.channelId, context);
+                this.sendKey = keys.dappToWalletKey;
+                this.recvKey = keys.walletToDappKey;
+                // §20.7: erase root_key and transcript_hash after all derivations
+                rootKey.fill(0);
+                keys.rootKey.fill(0);
+                keys.transcriptHash.fill(0);
+                // §7.1 DApp-side scope enforcement: check granted capabilities
+                if (joinCapabilities && this.declaredMethods?.length) {
+                    const granted = new Set(joinCapabilities.methods);
+                    const missing = this.declaredMethods.filter((m) => !granted.has(m));
+                    if (missing.length > 0) {
+                        this.sendRaw({
+                            v: 1,
+                            t: 'close',
+                            ch: this.channelId,
+                            ts: Date.now(),
+                            from: this.pubKeyB64,
+                            body: { reason: 'unsupported_capability' },
+                        });
+                        this.emit('error', new Error(`Wallet missing required methods: ${missing.join(', ')}`));
+                        break;
+                    }
+                }
+                if (joinCapabilities && this.declaredChains?.length) {
+                    const granted = new Set(joinCapabilities.chains);
+                    const missing = this.declaredChains.filter((c) => !granted.has(c));
+                    if (missing.length > 0) {
+                        this.sendRaw({
+                            v: 1,
+                            t: 'close',
+                            ch: this.channelId,
+                            ts: Date.now(),
+                            from: this.pubKeyB64,
+                            body: { reason: 'unsupported_capability' },
+                        });
+                        this.emit('error', new Error(`Wallet missing required chains: ${missing.join(', ')}`));
+                        break;
+                    }
+                }
+                this.emit('walletJoined', {
+                    capabilities: joinCapabilities,
+                    meta: joinMeta,
+                });
+                this.setPhase('pending_accept');
+                // Auto-accept for known wallets on reconnect, or when autoAccept is enabled
+                if (this.autoAccept || knownWallet) {
+                    this.doAccept();
+                }
+                else {
+                    // Application must call acceptWallet() or rejectWallet()
+                    this.pendingAcceptTimer = setTimeout(() => {
+                        this.emit('error', new Error('Pending accept timed out'));
+                        this.close('timeout');
+                    }, PENDING_ACCEPT_TIMEOUT);
+                }
+                break;
+            }
+            case 'res': {
+                const resBody = msg.body;
+                if (this.remotePubKey && msg.from !== b64urlEncode(this.remotePubKey))
+                    break;
+                if (!resBody.id)
+                    break;
+                const responseId = resBody.id;
+                const pending = this.pendingRequests.get(responseId);
+                if (!pending)
+                    break;
+                this.pendingRequests.delete(responseId);
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                // All responses MUST be sealed — reject unsealed to prevent forgery.
+                if (!resBody.sealed || !this.recvKey) {
+                    pending.reject(new Error('Response must be encrypted'));
+                    break;
+                }
+                try {
+                    const resHdr = { type: 'res', from: msg.from, id: responseId };
+                    const { seq, data } = unsealPayload(this.recvKey, this.channelId, resBody.sealed, resHdr);
+                    if (seq <= this.recvSeq) {
+                        pending.reject(new Error('Replay detected'));
+                        break;
+                    }
+                    const prevRecvSeq = this.recvSeq;
+                    this.recvSeq = seq;
+                    const afterPersist = () => {
+                        // Per protocol §5.3: _ok is inside the decrypted sealed payload
+                        const envelope = data;
+                        if (typeof envelope._ok !== 'boolean') {
+                            pending.reject(new Error('Response missing _ok field'));
+                            return;
+                        }
+                        if (envelope._ok) {
+                            pending.resolve(envelope._result);
+                            this.emit('response', { id: responseId, ok: true, result: envelope._result });
+                        }
+                        else {
+                            const error = new Error(envelope.message ?? 'Request rejected');
+                            error.code = envelope.code;
+                            pending.reject(error);
+                            this.emit('response', {
+                                id: responseId,
+                                ok: false,
+                                result: { code: envelope.code, message: envelope.message },
+                            });
+                        }
+                    };
+                    const persisted = this.persistSnapshot();
+                    if (isPromiseLike(persisted)) {
+                        void persisted.then(afterPersist).catch((e) => {
+                            this.recvSeq = prevRecvSeq; // rollback on persist failure
+                            pending.reject(this.persistenceError(e));
+                        });
+                    }
+                    else {
+                        afterPersist();
+                    }
+                }
+                catch {
+                    pending.reject(new Error('Decryption failed'));
+                }
+                break;
+            }
+            case 'evt': {
+                const evtBody = msg.body;
+                if (this.remotePubKey && msg.from !== b64urlEncode(this.remotePubKey))
+                    break;
+                // Events MUST be sealed — drop unsealed events to prevent forgery.
+                if (!evtBody.sealed || !evtBody.id || !this.recvKey)
+                    break;
+                try {
+                    const evtHdr = { type: 'evt', from: msg.from, id: evtBody.id };
+                    const { seq, data } = unsealPayload(this.recvKey, this.channelId, evtBody.sealed, evtHdr);
+                    if (seq <= this.recvSeq)
+                        break; // replay — silently drop
+                    const prevRecvSeqEvt = this.recvSeq;
+                    this.recvSeq = seq;
+                    const afterPersist = () => {
+                        // Privacy mode (§7.4): real event name is inside the encrypted payload
+                        let event;
+                        let eventData = data;
+                        if (data && typeof data === 'object' && '_event' in data) {
+                            event = data._event;
+                            const { _event: _, ...rest } = data;
+                            eventData = Object.keys(rest).length === 1 && '_data' in rest ? rest._data : rest;
+                        }
+                        if (event) {
+                            this.emit('event', { event, data: eventData });
+                        }
+                        else {
+                            this.emit('error', new Error('Event payload missing _event'));
+                        }
+                    };
+                    const persisted = this.persistSnapshot();
+                    if (isPromiseLike(persisted)) {
+                        void persisted
+                            .then(afterPersist)
+                            .catch((e) => {
+                            this.recvSeq = prevRecvSeqEvt; // rollback on persist failure
+                            this.emit('error', this.persistenceError(e));
+                        });
+                    }
+                    else {
+                        afterPersist();
+                    }
+                }
+                catch {
+                    /* drop events that fail decryption */
+                }
+                break;
+            }
+            case 'ping':
+                this.sendRaw({
+                    v: 1,
+                    t: 'pong',
+                    ch: this.channelId,
+                    ts: Date.now(),
+                    from: this.pubKeyB64,
+                    body: {},
+                });
+                break;
+            case 'pong':
+                break;
+            case 'close': {
+                if (this.phase !== 'disconnected') {
+                    this.clearPersistence();
+                    this.setPhase('closed');
+                    this.intentionalClose = true;
+                }
+                break;
+            }
+            case 'terminate': {
+                const termBody = msg.body;
+                // Race condition: relay sends channel_exists when we re-create during reconnect
+                if (termBody.reason === 'channel_exists' && this.phase === 'disconnected') {
+                    this.startReconnect();
+                    break;
+                }
+                // Adapter-sent termination — treat like close
+                if (this.phase !== 'disconnected') {
+                    this.clearPersistence();
+                    this.setPhase('closed');
+                    this.intentionalClose = true;
+                }
+                break;
+            }
+        }
+    }
+    doAccept() {
+        this.paired = true;
+        this.approvedCapabilities = this.walletCapabilities;
+        this.approvedWalletMeta = this.walletMeta;
+        this.approvedWalletPubKeyB64 = b64urlEncode(this.remotePubKey);
+        this.approvedScopeRecorded = true;
+        const walletPubB64 = b64urlEncode(this.remotePubKey);
+        const sendAccept = () => {
+            this.sendRaw({
+                v: 1,
+                t: 'accept',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { target: walletPubB64 },
+            });
+        };
+        const persisted = this.persistSnapshot();
+        if (isPromiseLike(persisted)) {
+            void persisted.then(sendAccept).catch((e) => this.persistenceError(e));
+        }
+        else {
+            sendAccept();
+        }
+    }
+    sessionContext(walletPubKeyB64, capabilities, walletMeta) {
+        return {
+            dappPubKeyB64: this.pubKeyB64,
+            walletPubKeyB64,
+            capabilities: capabilities ?? null,
+            walletMeta: walletMeta ?? null,
+            dappName: this.meta.name,
+        };
+    }
+    isSameApprovedWallet(walletPubKeyB64, capabilities, walletMeta) {
+        return (this.paired &&
+            this.approvedWalletPubKeyB64 === walletPubKeyB64 &&
+            this.approvedScopeRecorded &&
+            canonicalJson(this.approvedCapabilities) === canonicalJson(capabilities ?? null) &&
+            canonicalJson(this.approvedWalletMeta ?? null) === canonicalJson(walletMeta ?? null));
+    }
+    nextSendSeq() {
+        if (this.sendSeq >= MAX_SEND_SEQ) {
+            const error = new Error('Send sequence overflow/limit reached — session invalidated');
+            this.emit('error', error);
+            this.close();
+            throw error;
+        }
+        const seq = this.sendSeq;
+        this.sendSeq += 1;
+        const persisted = this.persistSnapshot();
+        if (isPromiseLike(persisted)) {
+            return persisted
+                .then(() => seq)
+                .catch((e) => {
+                throw this.persistenceError(e);
+            });
+        }
+        return seq;
+    }
+    persistSnapshot() {
+        if (!this.persistence)
+            return;
+        return this.persistence.save(this.serialize());
+    }
+    persistSnapshotAsync() {
+        const persisted = this.persistSnapshot();
+        if (isPromiseLike(persisted)) {
+            void persisted.catch((e) => this.persistenceError(e));
+        }
+    }
+    clearPersistence() {
+        if (!this.persistence?.clear)
+            return;
+        const cleared = this.persistence.clear();
+        if (isPromiseLike(cleared)) {
+            void cleared.catch((e) => {
+                const err = e instanceof Error ? e : new Error(String(e));
+                this.emit('error', err);
+            });
+        }
+    }
+    persistenceError(error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const wrapped = new Error(`Session persistence failed: ${err.message}`);
+        this.emit('error', wrapped);
+        this.close('protocol_error');
+        return wrapped;
+    }
+    // -------------------------------------------------------------------------
+    // Internal: transport
+    // -------------------------------------------------------------------------
+    /** Append ?ch= to transport URL for CF Worker relay routing. Rust relay ignores it. */
+    setTransportChannelHint() {
+        const t = this.transport;
+        if (typeof t.setUrl === 'function') {
+            const base = t.url ?? '';
+            if (base && !base.includes('?ch=')) {
+                const sep = base.includes('?') ? '&' : '?';
+                t.setUrl(`${base}${sep}ch=${this.channelId}`);
+            }
+        }
+    }
+    sendRaw(msg) {
+        // §15 rule 10: max 64 KB on the wire
+        const json = JSON.stringify(msg);
+        if (new TextEncoder().encode(json).length > MAX_MESSAGE_BYTES) {
+            this.emit('error', new Error('Message exceeds 64 KB limit'));
+            return;
+        }
+        this.transport.send(msg);
+    }
+    handleTransportClose() {
+        if (this.intentionalClose || this.phase === 'closed')
+            return;
+        this.startReconnect();
+    }
+    // -------------------------------------------------------------------------
+    // Internal: reconnect
+    // -------------------------------------------------------------------------
+    startReconnect() {
+        this.setPhase('disconnected');
+        this.reconnectAttempt = 0;
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.intentionalClose || this.phase === 'closed')
+            return;
+        const base = BACKOFF[Math.min(this.reconnectAttempt, BACKOFF.length - 1)] ?? 1000;
+        const delay = base + Math.floor(Math.random() * base * 0.3); // ±30% jitter
+        this.reconnectTimer = setTimeout(() => {
+            this.doReconnectAttempt();
+            this.reconnectAttempt++;
+        }, delay);
+    }
+    async doReconnectAttempt() {
+        if (this.intentionalClose || this.phase === 'closed')
+            return;
+        try {
+            this.setTransportChannelHint();
+            await this.transport.connect();
+            this.sendRaw({
+                v: 1,
+                t: 'create',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { meta: this.meta },
+            });
+        }
+        catch {
+            this.scheduleReconnect();
+        }
+    }
+    stopReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    clearPendingAcceptTimer() {
+        if (this.pendingAcceptTimer) {
+            clearTimeout(this.pendingAcceptTimer);
+            this.pendingAcceptTimer = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal: session TTL (§16 rule 16)
+    // -------------------------------------------------------------------------
+    startSessionTtl() {
+        this.clearSessionTtl();
+        if (this.sessionStartTime == null) {
+            this.sessionStartTime = Date.now();
+        }
+        const elapsed = Date.now() - this.sessionStartTime;
+        const remaining = Math.max(0, this.sessionTtl - elapsed);
+        this.sessionTtlTimer = setTimeout(() => {
+            this.emit('error', new Error('Session lifetime expired'));
+            this.close('timeout');
+        }, remaining);
+    }
+    clearSessionTtl() {
+        if (this.sessionTtlTimer) {
+            clearTimeout(this.sessionTtlTimer);
+            this.sessionTtlTimer = null;
+        }
+    }
+    setPhase(phase) {
+        if (this.phase === phase)
+            return;
+        this.phase = phase;
+        this.emit('phase', phase);
+    }
+}
+//# sourceMappingURL=dapp-session.js.map