walletpair-sdk 1.0.0

package/dist/wallet-session.js

@@ -0,0 +1,794 @@
+/**
+ * Wallet-side WalletPair session.
+ *
+ * Manages: parse URI → join → connected → handle requests → push events.
+ */
+import { b64urlDecode, b64urlEncode, bytesToHex, canonicalJson, computeSessionFingerprint, computeSharedSecret, constantTimeEqual, deriveDirectionalSessionKeys, deriveJoinEncryptionKey, deriveSessionKey, generateX25519KeyPair, hexToBytes, parsePairingUri, sealJoin, sealPayload, sha256Hex, signSnapshot, unsealPayload, verifySnapshot, } from './crypto.js';
+import { Emitter } from './emitter.js';
+const BACKOFF = [1000, 2000, 5000, 10000, 30000];
+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)
+const IDEMPOTENCY_CACHE_LIMIT = 1024;
+const IDEMPOTENCY_RESPONSE_LIMIT_BYTES = 16 * 1024;
+const BROADCAST_CACHE_LIMIT = 256;
+function isPromiseLike(value) {
+    return !!value && typeof value.then === 'function';
+}
+export class WalletSession extends Emitter {
+    phase = 'idle';
+    /** Channel ID (hex). Available after join. */
+    channelId = '';
+    /** 4-digit session fingerprint. Available after prepareJoin(). */
+    sessionFingerprint = '';
+    transport;
+    capabilities;
+    meta;
+    privKey;
+    pubKeyB64 = '';
+    remotePubKey = null;
+    sessionKey = null;
+    sendKey = null;
+    recvKey = null;
+    sendSeq = 0;
+    recvSeq = -1;
+    relayUrl = '';
+    dappName;
+    intentionalClose = false;
+    evtCounter = 0;
+    /** dApp-declared method scope from pairing URI (§9.1 / §8.1). */
+    dappDeclaredMethods;
+    /** dApp-declared chain scope from pairing URI (§9.1 / §8.1). */
+    dappDeclaredChains;
+    /** Effective capabilities after scope intersection (§8.1). */
+    effectiveCapabilities;
+    /** Session TTL in ms (§16 rule 16). */
+    sessionTtl;
+    sessionTtlTimer = null;
+    sessionStartTime = null;
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+    pendingRequestRecords = new Map();
+    idempotencyCache = new Map();
+    broadcastResponseCache = new Map();
+    persistence;
+    constructor(options) {
+        super();
+        this.transport = options.transport;
+        this.capabilities = options.capabilities;
+        this.meta = options.meta;
+        this.sessionTtl = options.sessionTtl ?? DEFAULT_SESSION_TTL;
+        this.effectiveCapabilities = { ...options.capabilities };
+        this.persistence = options.persistence;
+        this.transport.onMessage((msg) => this.handleMessage(msg));
+        this.transport.onClose(() => this.handleTransportClose());
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Prepare to join a channel by parsing a pairing URI.
+     * Computes local keys and the session fingerprint without connecting.
+     * Returns the 4-digit session fingerprint for user verification.
+     */
+    prepareJoin(uri) {
+        const parsed = parsePairingUri(uri);
+        this.intentionalClose = false;
+        this.channelId = parsed.ch;
+        this.remotePubKey = b64urlDecode(parsed.pubkey);
+        this.relayUrl = parsed.relay ?? '';
+        this.dappName = parsed.name;
+        this.dappDeclaredMethods = parsed.methods;
+        this.dappDeclaredChains = parsed.chains;
+        this.sendSeq = 0;
+        this.recvSeq = -1;
+        this.sendKey = null;
+        this.recvKey = null;
+        this.pendingRequestRecords.clear();
+        this.idempotencyCache.clear();
+        this.broadcastResponseCache.clear();
+        // Compute effective capabilities via scope intersection (§8.1)
+        this.effectiveCapabilities = this.computeScopeIntersection();
+        const kp = generateX25519KeyPair();
+        this.privKey = kp.privateKey;
+        this.pubKeyB64 = kp.publicKeyB64;
+        // Derive root and directional traffic keys immediately.
+        const shared = computeSharedSecret(this.privKey, this.remotePubKey);
+        const rootKey = deriveSessionKey(shared, this.channelId);
+        // §20.7: erase shared_secret immediately after root_key derivation
+        shared.fill(0);
+        const context = this.sessionContext();
+        const keys = deriveDirectionalSessionKeys(rootKey, this.channelId, context);
+        this.sendKey = keys.walletToDappKey;
+        this.recvKey = keys.dappToWalletKey;
+        this.sessionFingerprint = computeSessionFingerprint(this.channelId, b64urlEncode(this.remotePubKey));
+        this.emit('sessionFingerprint', this.sessionFingerprint);
+        // Always derive join encryption key for sealed_join before erasing rootKey
+        this.sessionKey = deriveJoinEncryptionKey(rootKey, this.channelId);
+        // §20.7: erase root_key after all derivations complete
+        rootKey.fill(0);
+        keys.rootKey.fill(0);
+        keys.transcriptHash.fill(0);
+        return this.sessionFingerprint;
+    }
+    /**
+     * Send the join message after the user has verified the session fingerprint.
+     */
+    async confirmJoin() {
+        if (!this.channelId || !this.sendKey || !this.recvKey) {
+            throw new Error('Must call prepareJoin() first');
+        }
+        // Update transport URL if WebSocket, add ?ch= for CF Worker relay routing
+        const transportWithUrl = this.transport;
+        if (typeof transportWithUrl.setUrl === 'function') {
+            let url = this.relayUrl;
+            if (this.channelId && !url.includes('?ch=')) {
+                const sep = url.includes('?') ? '&' : '?';
+                url = `${url}${sep}ch=${this.channelId}`;
+            }
+            transportWithUrl.setUrl(url);
+        }
+        await this.transport.connect();
+        this.setPhase('waiting_accept');
+        await this.sendJoin();
+    }
+    /**
+     * Join a channel in one step (convenience method).
+     * Equivalent to prepareJoin() + confirmJoin().
+     */
+    async joinFromUri(uri) {
+        const code = this.prepareJoin(uri);
+        await this.confirmJoin();
+        return code;
+    }
+    /** Respond to a request with success. */
+    approve(requestId, result) {
+        const sent = this.sendResponse(requestId, true, result);
+        const afterSend = (ok) => {
+            if (ok)
+                this.cacheProcessedResponse(requestId, true, result);
+            return ok;
+        };
+        return isPromiseLike(sent) ? sent.then(afterSend) : afterSend(sent);
+    }
+    /** Respond to a request with rejection. */
+    reject(requestId, code = 'user_rejected', message = 'User rejected the request') {
+        const error = { code, message };
+        const sent = this.sendResponse(requestId, false, error);
+        const afterSend = (ok) => {
+            if (ok)
+                this.cacheProcessedResponse(requestId, false, error);
+            return ok;
+        };
+        return isPromiseLike(sent) ? sent.then(afterSend) : afterSend(sent);
+    }
+    /** Push an event to the dApp. */
+    pushEvent(event, data) {
+        if (this.phase !== 'connected' || !this.sendKey)
+            return false;
+        const seq = this.nextSendSeq();
+        const evtId = `evt-${++this.evtCounter}`;
+        const send = (reservedSeq) => {
+            if (reservedSeq == null || !this.sendKey)
+                return false;
+            // Privacy mode (§7.4): encrypt event name inside sealed payload
+            const sealedData = {
+                _event: event,
+                ...(data && typeof data === 'object' ? data : { _data: data }),
+            };
+            const hdr = { type: 'evt', from: this.pubKeyB64, id: evtId };
+            const sealed = sealPayload(this.sendKey, this.channelId, reservedSeq, sealedData, hdr);
+            this.sendRaw({
+                v: 1,
+                t: 'evt',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { id: evtId, sealed },
+            });
+            return true;
+        };
+        return isPromiseLike(seq) ? seq.then(send) : send(seq);
+    }
+    /** 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. */
+    close(reason = 'normal') {
+        this.intentionalClose = true;
+        this.stopReconnect();
+        this.clearSessionTtl();
+        this.pendingRequestRecords.clear();
+        this.idempotencyCache.clear();
+        this.broadcastResponseCache.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 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.pendingRequestRecords.clear();
+        this.idempotencyCache.clear();
+        this.broadcastResponseCache.clear();
+        this.sessionKey = null;
+        this.sendKey = null;
+        this.recvKey = null;
+    }
+    // -------------------------------------------------------------------------
+    // State serialization
+    // -------------------------------------------------------------------------
+    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,
+            relayUrl: this.relayUrl,
+            capabilities: this.capabilities,
+            meta: this.meta ?? null,
+            dappName: this.dappName ?? null,
+            sessionStartTime: this.sessionStartTime,
+        });
+        return this.sendKey ? signSnapshot(this.sendKey, json) : json;
+    }
+    restore(signed) {
+        try {
+            let json;
+            if (signed.length > 65 && signed[64] === '.') {
+                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;
+                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.relayUrl = d.relayUrl;
+            if ('capabilities' in d &&
+                canonicalJson(d.capabilities ?? null) !== canonicalJson(this.capabilities ?? null)) {
+                return false;
+            }
+            if ('meta' in d && canonicalJson(d.meta ?? null) !== canonicalJson(this.meta ?? null)) {
+                return false;
+            }
+            this.dappName = d.dappName ?? undefined;
+            this.sessionStartTime = d.sessionStartTime ?? null;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async restoreFromPersistence() {
+        if (!this.persistence?.load)
+            return false;
+        const json = await this.persistence.load();
+        return json ? this.restore(json) : false;
+    }
+    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 dApp'));
+                        this.close();
+                        break;
+                    }
+                }
+                if (readyBody.state === 'waiting') {
+                    this.setPhase('waiting_accept');
+                }
+                else if (readyBody.state === 'connected') {
+                    this.setPhase('connected');
+                    this.startSessionTtl();
+                    this.persistSnapshotAsync();
+                }
+                break;
+            }
+            case 'req': {
+                const reqBody = msg.body;
+                if (this.remotePubKey && msg.from !== b64urlEncode(this.remotePubKey))
+                    break;
+                // All requests MUST be sealed — reject unsealed requests to prevent
+                // method injection by a malicious relay.
+                if (!reqBody.sealed || !reqBody.id || !this.recvKey) {
+                    if (reqBody.id) {
+                        this.observeSend(this.reject(reqBody.id, 'protocol_error', 'Request must be encrypted'));
+                    }
+                    break;
+                }
+                const requestId = reqBody.id;
+                try {
+                    // AAD: no method field — real method is inside sealed payload
+                    const reqHdr = { type: 'req', from: msg.from, id: requestId };
+                    const { seq, data, plaintext } = unsealPayload(this.recvKey, this.channelId, reqBody.sealed, reqHdr);
+                    if (seq <= this.recvSeq)
+                        break; // replay — silently drop
+                    const prevRecvSeq = this.recvSeq;
+                    this.recvSeq = seq;
+                    const afterPersist = () => this.processRequest(requestId, data, plaintext);
+                    const persisted = this.persistSnapshot();
+                    if (isPromiseLike(persisted)) {
+                        void persisted
+                            .then(afterPersist)
+                            .catch((e) => {
+                            this.recvSeq = prevRecvSeq; // rollback on persist failure
+                            this.emit('error', this.persistenceError(e));
+                        });
+                    }
+                    else {
+                        afterPersist();
+                    }
+                }
+                catch {
+                    this.observeSend(this.reject(requestId, 'decryption_failed', 'Failed to decrypt request'));
+                }
+                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.pendingRequestRecords.clear();
+                    this.idempotencyCache.clear();
+                    this.broadcastResponseCache.clear();
+                    this.clearPersistence();
+                    this.setPhase('closed');
+                    this.intentionalClose = true;
+                }
+                break;
+            }
+            case 'terminate': {
+                const termBody = msg.body;
+                // Race condition: relay sends channel_not_found when we join during reconnect
+                if (termBody.reason === 'channel_not_found' &&
+                    (this.phase === 'disconnected' || this.phase === 'waiting_accept')) {
+                    this.transport.disconnect();
+                    this.startReconnect();
+                    break;
+                }
+                // Adapter-sent termination — treat like close
+                if (this.phase !== 'disconnected') {
+                    this.pendingRequestRecords.clear();
+                    this.idempotencyCache.clear();
+                    this.broadcastResponseCache.clear();
+                    this.clearPersistence();
+                    this.setPhase('closed');
+                    this.intentionalClose = true;
+                }
+                break;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal: responses and request idempotency
+    // -------------------------------------------------------------------------
+    processRequest(requestId, data, plaintext) {
+        // Extract _method from decrypted payload
+        if (!data || typeof data !== 'object') {
+            this.observeSend(this.reject(requestId, 'invalid_params', 'Request payload missing _method'));
+            return;
+        }
+        const payload = data;
+        if (typeof payload._method !== 'string' || payload._method.length === 0) {
+            this.observeSend(this.reject(requestId, 'invalid_params', 'Request payload missing _method'));
+            return;
+        }
+        const method = payload._method;
+        // §7.1 runtime enforcement: reject methods not in capabilities
+        if (!this.effectiveCapabilities.methods.includes(method)) {
+            this.observeSend(this.reject(requestId, 'unsupported_method', `Method "${method}" not in granted capabilities`));
+            return;
+        }
+        const { _method: _, ...rest } = payload;
+        const params = rest;
+        const paramsHash = sha256Hex(plaintext);
+        const cachedBroadcast = this.broadcastResponseCache.get(requestId);
+        if (cachedBroadcast) {
+            if (!constantTimeEqual(cachedBroadcast.paramsHash, paramsHash)) {
+                this.observeSend(this.reject(requestId, 'invalid_params', 'Duplicate request ID with different params'));
+                return;
+            }
+            this.observeSend(this.sendResponse(requestId, cachedBroadcast.ok, cachedBroadcast.data));
+            return;
+        }
+        const cached = this.idempotencyCache.get(requestId);
+        if (cached) {
+            if (!constantTimeEqual(cached.paramsHash, paramsHash)) {
+                this.observeSend(this.reject(requestId, 'invalid_params', 'Duplicate request ID with different params'));
+                return;
+            }
+            this.touchIdempotencyEntry(requestId, cached);
+            if (!cached.tooLarge) {
+                this.observeSend(this.sendResponse(requestId, cached.ok, cached.data));
+                return;
+            }
+        }
+        const pending = this.pendingRequestRecords.get(requestId);
+        if (pending) {
+            if (!constantTimeEqual(pending.paramsHash, paramsHash)) {
+                this.observeSend(this.reject(requestId, 'invalid_params', 'Duplicate request ID with different params'));
+            }
+            return;
+        }
+        // §15 rule 11: max 32 pending requests
+        if (this.pendingRequestRecords.size >= MAX_PENDING_REQUESTS) {
+            this.observeSend(this.reject(requestId, 'rate_limited', 'Too many pending requests'));
+            return;
+        }
+        this.pendingRequestRecords.set(requestId, { paramsHash, method });
+        this.emit('request', { id: requestId, method, params });
+    }
+    sendResponse(requestId, ok, data) {
+        if (!this.sendKey)
+            return false;
+        const seq = this.nextSendSeq();
+        const send = (reservedSeq) => {
+            if (reservedSeq == null || !this.sendKey)
+                return false;
+            // Per protocol §5.3: success = { _ok: true, _result: <result> }
+            //                     error   = { _ok: false, code: "...", message: "..." }
+            const sealedPayload = ok
+                ? { _ok: true, _result: data }
+                : { _ok: false, ...data };
+            const hdr = { type: 'res', from: this.pubKeyB64, id: requestId };
+            const sealed = sealPayload(this.sendKey, this.channelId, reservedSeq, sealedPayload, hdr);
+            this.sendRaw({
+                v: 1,
+                t: 'res',
+                ch: this.channelId,
+                ts: Date.now(),
+                from: this.pubKeyB64,
+                body: { id: requestId, sealed },
+            });
+            return true;
+        };
+        return isPromiseLike(seq) ? seq.then(send) : send(seq);
+    }
+    cacheProcessedResponse(requestId, ok, data) {
+        const pending = this.pendingRequestRecords.get(requestId);
+        if (!pending)
+            return;
+        this.pendingRequestRecords.delete(requestId);
+        const serialized = JSON.stringify(data ?? null);
+        const tooLarge = new TextEncoder().encode(serialized).length > IDEMPOTENCY_RESPONSE_LIMIT_BYTES;
+        const entry = {
+            ...pending,
+            ok,
+            data: tooLarge ? null : data,
+            tooLarge,
+        };
+        this.idempotencyCache.set(requestId, entry);
+        this.evictIdempotencyCache();
+        if (pending.method === 'wallet_sendTransaction' && ok) {
+            this.broadcastResponseCache.set(requestId, {
+                ...pending,
+                ok,
+                data,
+                tooLarge: false,
+            });
+            this.evictBroadcastCache();
+        }
+    }
+    touchIdempotencyEntry(requestId, entry) {
+        this.idempotencyCache.delete(requestId);
+        this.idempotencyCache.set(requestId, entry);
+    }
+    evictIdempotencyCache() {
+        while (this.idempotencyCache.size > IDEMPOTENCY_CACHE_LIMIT) {
+            const oldest = this.idempotencyCache.keys().next().value;
+            if (!oldest)
+                return;
+            this.idempotencyCache.delete(oldest);
+        }
+    }
+    evictBroadcastCache() {
+        while (this.broadcastResponseCache.size > BROADCAST_CACHE_LIMIT) {
+            const oldest = this.broadcastResponseCache.keys().next().value;
+            if (!oldest)
+                return;
+            this.broadcastResponseCache.delete(oldest);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal: transport
+    // -------------------------------------------------------------------------
+    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);
+    }
+    sendJoin() {
+        const body = {
+            sealed_join: null,
+        };
+        if (this.sessionKey) {
+            // Initial join: encrypt capabilities/meta in sealed_join
+            body.sealed_join = sealJoin(this.sessionKey, this.channelId, this.effectiveCapabilities, this.meta);
+            // §20.7: erase join_encryption_key after one-shot use
+            this.sessionKey.fill(0);
+            this.sessionKey = null;
+        }
+        // else: reconnect — sealed_join stays null (capabilities already negotiated)
+        const msg = {
+            v: 1,
+            t: 'join',
+            ch: this.channelId,
+            ts: Date.now(),
+            from: this.pubKeyB64,
+            body,
+        };
+        const send = () => this.sendRaw(msg);
+        const persisted = this.persistSnapshot();
+        if (isPromiseLike(persisted)) {
+            return persisted.then(send).catch((e) => {
+                throw this.persistenceError(e);
+            });
+        }
+        send();
+    }
+    sessionContext() {
+        return {
+            dappPubKeyB64: this.remotePubKey ? b64urlEncode(this.remotePubKey) : '',
+            walletPubKeyB64: this.pubKeyB64,
+            capabilities: this.effectiveCapabilities,
+            walletMeta: this.meta ?? null,
+            dappName: this.dappName,
+        };
+    }
+    /**
+     * Compute the intersection of wallet capabilities with dApp-declared
+     * scope from the pairing URI (§8.1).
+     */
+    computeScopeIntersection() {
+        const base = this.capabilities;
+        // §7.1: Wallet MUST check it can satisfy dApp's minimum requirements.
+        // Wallet MAY grant additional methods/chains beyond what was requested.
+        // We grant all wallet capabilities (not just the intersection).
+        if (this.dappDeclaredMethods?.length) {
+            const granted = new Set(base.methods);
+            const unsatisfied = this.dappDeclaredMethods.filter((m) => !granted.has(m));
+            if (unsatisfied.length > 0) {
+                // Wallet cannot satisfy dApp's requirements — emit warning but proceed
+                // (the dApp will check and close if needed)
+            }
+        }
+        if (this.dappDeclaredChains?.length) {
+            const granted = new Set(base.chains);
+            const unsatisfied = this.dappDeclaredChains.filter((c) => !granted.has(c));
+            if (unsatisfied.length > 0) {
+                // Same as above
+            }
+        }
+        const result = { methods: base.methods, events: base.events, chains: base.chains };
+        if (base.version != null)
+            result.version = base.version;
+        return result;
+    }
+    nextSendSeq() {
+        if (this.sendSeq >= MAX_SEND_SEQ) {
+            const error = new Error('Send sequence overflow/limit reached — session invalidated');
+            this.emit('error', error);
+            this.close();
+            return null;
+        }
+        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);
+            });
+        }
+    }
+    observeSend(result) {
+        if (isPromiseLike(result)) {
+            void result.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;
+    }
+    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 {
+            // Re-set URL with ?ch= for CF Worker relay routing
+            const t = this.transport;
+            if (typeof t.setUrl === 'function' && this.channelId) {
+                let url = this.relayUrl;
+                if (!url.includes('?ch=')) {
+                    const sep = url.includes('?') ? '&' : '?';
+                    url = `${url}${sep}ch=${this.channelId}`;
+                }
+                t.setUrl(url);
+            }
+            await this.transport.connect();
+            this.setPhase('waiting_accept');
+            await this.sendJoin();
+        }
+        catch {
+            this.scheduleReconnect();
+        }
+    }
+    stopReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = 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=wallet-session.js.map