@aztec/wallet-sdk 0.0.1-commit.7d4e6cd → 0.0.1-commit.8afd444

package/dest/extension/handlers/background_connection_handler.d.ts

@@ -0,0 +1,158 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { type EncryptedPayload } from '../../crypto.js';
+import { type DiscoveryRequest, type KeyExchangeRequest, type WalletInfo, type WalletMessage, type WalletResponse } from '../../types.js';
+import { type BackgroundMessage, type MessageSender } from './internal_message_types.js';
+/**
+ * Status of a pending discovery request.
+ */
+export type DiscoveryStatus = 'pending' | 'approved' | 'rejected';
+/**
+ * A pending discovery request from a dApp.
+ */
+export interface PendingDiscovery {
+    /** Unique request identifier. */
+    requestId: string;
+    /** Application identifier. */
+    appId: string;
+    /** Optional application name. */
+    appName?: string;
+    /** Origin URL of the requesting page. */
+    origin: string;
+    /** Network information. */
+    chainInfo: ChainInfo;
+    /** Browser tab ID. */
+    tabId: number;
+    /** Request timestamp. */
+    timestamp: number;
+    /** Current status. */
+    status: DiscoveryStatus;
+}
+/**
+ * An active session with a connected dApp.
+ * Created after key exchange completes.
+ */
+export interface ActiveSession {
+    /** Unique session identifier. */
+    sessionId: string;
+    /** Derived AES-GCM encryption key. */
+    sharedKey: CryptoKey;
+    /** Hex-encoded verification hash for visual comparison. */
+    verificationHash: string;
+    /** Browser tab ID. */
+    tabId: number;
+    /** Origin URL of the connected app. */
+    origin: string;
+    /** Application identifier. */
+    appId: string;
+    /** Connection timestamp. */
+    connectedAt: number;
+    /** Network information. */
+    chainInfo: ChainInfo;
+}
+/**
+ * Transport interface for background script communication.
+ */
+export interface BackgroundTransport {
+    /**
+     * Send a message to a specific tab.
+     * Typically `(tabId, message) => browser.tabs.sendMessage(tabId, message)`.
+     */
+    sendToTab: (tabId: number, message: BackgroundMessage) => void;
+    /**
+     * Register a listener for messages from content scripts.
+     * Typically `browser.runtime.onMessage.addListener`.
+     */
+    addContentListener: (handler: (message: unknown, sender: MessageSender) => void) => void;
+}
+/**
+ * Event callbacks for the background connection handler.
+ * All callbacks are optional.
+ */
+export interface BackgroundConnectionCallbacks {
+    /**
+     * Called when a new discovery request is received and stored as pending.
+     */
+    onPendingDiscovery?: (discovery: PendingDiscovery) => void;
+    /**
+     * Called when a session is established (key exchange complete).
+     */
+    onSessionEstablished?: (session: ActiveSession) => void;
+    /**
+     * Called when a session is terminated.
+     */
+    onSessionTerminated?: (sessionId: string) => void;
+    /**
+     * Called when a decrypted wallet message is received.
+     */
+    onWalletMessage?: (session: ActiveSession, message: WalletMessage) => void;
+}
+/**
+ * Configuration for the background connection handler.
+ */
+export interface BackgroundConnectionConfig {
+    /** Unique wallet identifier. */
+    walletId: string;
+    /** Display name for the wallet. */
+    walletName: string;
+    /** Wallet version string. */
+    walletVersion: string;
+    /** Optional wallet icon URL. */
+    walletIcon?: string;
+}
+/**
+ * Handles wallet session flow in the extension background script.
+ *
+ * This class manages:
+ * - Pending discovery requests (before user approval)
+ * - Active sessions (after key exchange)
+ * - Per-session ECDH key exchange
+ * - Message encryption/decryption
+ *
+ * @example
+ * ```typescript
+ * const handler = new BackgroundConnectionHandler(
+ *   {
+ *     walletId: 'my-wallet',
+ *     walletName: 'My Wallet',
+ *     walletVersion: '1.0.0',
+ *   },
+ *   {
+ *     sendToTab: (tabId, message) => browser.tabs.sendMessage(tabId, message),
+ *     addContentListener: (handler) => browser.runtime.onMessage.addListener(handler),
+ *   },
+ *   {
+ *     onPendingDiscovery: (discovery) => updateBadge(),
+ *     onSessionEstablished: (session) => console.log('Connected:', session.sessionId),
+ *     onWalletMessage: (session, message) => nativePort.postMessage(message),
+ *   }
+ * );
+ *
+ * handler.initialize();
+ * ```
+ */
+export declare class BackgroundConnectionHandler {
+    private config;
+    private transport;
+    private callbacks;
+    private pendingDiscoveries;
+    private activeSessions;
+    constructor(config: BackgroundConnectionConfig, transport: BackgroundTransport, callbacks?: BackgroundConnectionCallbacks);
+    initialize(): void;
+    private handleMessage;
+    getWalletInfo(): WalletInfo;
+    handleDiscoveryRequest(request: DiscoveryRequest, tabId: number, origin: string): void;
+    approveDiscovery(requestId: string): boolean;
+    rejectDiscovery(requestId: string): boolean;
+    handleKeyExchangeRequest(sessionId: string, request: KeyExchangeRequest): Promise<void>;
+    handleEncryptedMessage(sessionId: string, encrypted: EncryptedPayload): Promise<void>;
+    sendResponse(sessionId: string, response: WalletResponse): Promise<void>;
+    terminateSession(sessionId: string): void;
+    terminateForTab(tabId: number): void;
+    clearAll(): void;
+    getPendingDiscoveries(): PendingDiscovery[];
+    getPendingDiscoveryCount(): number;
+    getActiveSessions(): ActiveSession[];
+    getSession(sessionId: string): ActiveSession | undefined;
+    getPendingDiscovery(requestId: string): PendingDiscovery | undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja2dyb3VuZF9jb25uZWN0aW9uX2hhbmRsZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9leHRlbnNpb24vaGFuZGxlcnMvYmFja2dyb3VuZF9jb25uZWN0aW9uX2hhbmRsZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFFekQsT0FBTyxFQUNMLEtBQUssZ0JBQWdCLEVBT3RCLE1BQU0saUJBQWlCLENBQUM7QUFDekIsT0FBTyxFQUNMLEtBQUssZ0JBQWdCLEVBQ3JCLEtBQUssa0JBQWtCLEVBRXZCLEtBQUssVUFBVSxFQUNmLEtBQUssYUFBYSxFQUVsQixLQUFLLGNBQWMsRUFDcEIsTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QixPQUFPLEVBQ0wsS0FBSyxpQkFBaUIsRUFJdEIsS0FBSyxhQUFhLEVBQ25CLE1BQU0sNkJBQTZCLENBQUM7QUFFckM7O0dBRUc7QUFDSCxNQUFNLE1BQU0sZUFBZSxHQUFHLFNBQVMsR0FBRyxVQUFVLEdBQUcsVUFBVSxDQUFDO0FBRWxFOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGdCQUFnQjtJQUMvQixpQ0FBaUM7SUFDakMsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQiw4QkFBOEI7SUFDOUIsS0FBSyxFQUFFLE1BQU0sQ0FBQztJQUNkLGlDQUFpQztJQUNqQyxPQUFPLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDakIseUNBQXlDO0lBQ3pDLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZiwyQkFBMkI7SUFDM0IsU0FBUyxFQUFFLFNBQVMsQ0FBQztJQUNyQixzQkFBc0I7SUFDdEIsS0FBSyxFQUFFLE1BQU0sQ0FBQztJQUNkLHlCQUF5QjtJQUN6QixTQUFTLEVBQUUsTUFBTSxDQUFDO0lBQ2xCLHNCQUFzQjtJQUN0QixNQUFNLEVBQUUsZUFBZSxDQUFDO0NBQ3pCO0FBRUQ7OztHQUdHO0FBQ0gsTUFBTSxXQUFXLGFBQWE7SUFDNUIsaUNBQWlDO0lBQ2pDLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsc0NBQXNDO0lBQ3RDLFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIsMkRBQTJEO0lBQzNELGdCQUFnQixFQUFFLE1BQU0sQ0FBQztJQUN6QixzQkFBc0I7SUFDdEIsS0FBSyxFQUFFLE1BQU0sQ0FBQztJQUNkLHVDQUF1QztJQUN2QyxNQUFNLEVBQUUsTUFBTSxDQUFDO0lBQ2YsOEJBQThCO0lBQzlCLEtBQUssRUFBRSxNQUFNLENBQUM7SUFDZCw0QkFBNEI7SUFDNUIsV0FBVyxFQUFFLE1BQU0sQ0FBQztJQUNwQiwyQkFBMkI7SUFDM0IsU0FBUyxFQUFFLFNBQVMsQ0FBQztDQUN0QjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLG1CQUFtQjtJQUNsQzs7O09BR0c7SUFDSCxTQUFTLEVBQUUsQ0FBQyxLQUFLLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRSxpQkFBaUIsS0FBSyxJQUFJLENBQUM7SUFFL0Q7OztPQUdHO0lBQ0gsa0JBQWtCLEVBQUUsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sRUFBRSxhQUFhLEtBQUssSUFBSSxLQUFLLElBQUksQ0FBQztDQUMxRjtBQUVEOzs7R0FHRztBQUNILE1BQU0sV0FBVyw2QkFBNkI7SUFDNUM7O09BRUc7SUFDSCxrQkFBa0IsQ0FBQyxFQUFFLENBQUMsU0FBUyxFQUFFLGdCQUFnQixLQUFLLElBQUksQ0FBQztJQUUzRDs7T0FFRztJQUNILG9CQUFvQixDQUFDLEVBQUUsQ0FBQyxPQUFPLEVBQUUsYUFBYSxLQUFLLElBQUksQ0FBQztJQUV4RDs7T0FFRztJQUNILG1CQUFtQixDQUFDLEVBQUUsQ0FBQyxTQUFTLEVBQUUsTUFBTSxLQUFLLElBQUksQ0FBQztJQUVsRDs7T0FFRztJQUNILGVBQWUsQ0FBQyxFQUFFLENBQUMsT0FBTyxFQUFFLGFBQWEsRUFBRSxPQUFPLEVBQUUsYUFBYSxLQUFLLElBQUksQ0FBQztDQUM1RTtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLDBCQUEwQjtJQUN6QyxnQ0FBZ0M7SUFDaEMsUUFBUSxFQUFFLE1BQU0sQ0FBQztJQUNqQixtQ0FBbUM7SUFDbkMsVUFBVSxFQUFFLE1BQU0sQ0FBQztJQUNuQiw2QkFBNkI7SUFDN0IsYUFBYSxFQUFFLE1BQU0sQ0FBQztJQUN0QixnQ0FBZ0M7SUFDaEMsVUFBVSxDQUFDLEVBQUUsTUFBTSxDQUFDO0NBQ3JCO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQThCRztBQUNILHFCQUFhLDJCQUEyQjtJQUtwQyxPQUFPLENBQUMsTUFBTTtJQUNkLE9BQU8sQ0FBQyxTQUFTO0lBQ2pCLE9BQU8sQ0FBQyxTQUFTO0lBTm5CLE9BQU8sQ0FBQyxrQkFBa0IsQ0FBdUM7SUFDakUsT0FBTyxDQUFDLGNBQWMsQ0FBb0M7SUFFMUQsWUFDVSxNQUFNLEVBQUUsMEJBQTBCLEVBQ2xDLFNBQVMsRUFBRSxtQkFBbUIsRUFDOUIsU0FBUyxHQUFFLDZCQUFrQyxFQUNuRDtJQUVKLFVBQVUsSUFBSSxJQUFJLENBRWpCO0lBRUQsT0FBTyxDQUFDLGFBQWEsQ0FvQ25CO0lBRUYsYUFBYSxJQUFJLFVBQVUsQ0FPMUI7SUFFRCxzQkFBc0IsQ0FBQyxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxHQUFHLElBQUksQ0FhckY7SUFFRCxnQkFBZ0IsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FvQjNDO0lBRUQsZUFBZSxDQUFDLFNBQVMsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQVUxQztJQUVLLHdCQUF3QixDQUFDLFNBQVMsRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLGtCQUFrQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E0QzVGO0lBRUssc0JBQXNCLENBQUMsU0FBUyxFQUFFLE1BQU0sRUFBRSxTQUFTLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVkxRjtJQUVLLFlBQVksQ0FBQyxTQUFTLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxjQUFjLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWlCN0U7SUFFRCxnQkFBZ0IsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLElBQUksQ0F5QnhDO0lBRUQsZUFBZSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsSUFBSSxDQVduQztJQUVELFFBQVEsSUFBSSxJQUFJLENBTWY7SUFFRCxxQkFBcUIsSUFBSSxnQkFBZ0IsRUFBRSxDQUUxQztJQUVELHdCQUF3QixJQUFJLE1BQU0sQ0FFakM7SUFFRCxpQkFBaUIsSUFBSSxhQUFhLEVBQUUsQ0FFbkM7SUFFRCxVQUFVLENBQUMsU0FBUyxFQUFFLE1BQU0sR0FBRyxhQUFhLEdBQUcsU0FBUyxDQUV2RDtJQUVELG1CQUFtQixDQUFDLFNBQVMsRUFBRSxNQUFNLEdBQUcsZ0JBQWdCLEdBQUcsU0FBUyxDQUVuRTtDQUNGIn0=

package/dest/extension/handlers/background_connection_handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background_connection_handler.d.ts","sourceRoot":"","sources":["../../../src/extension/handlers/background_connection_handler.ts"],"names":[],"mappings":"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"}

package/dest/extension/handlers/background_connection_handler.js

@@ -0,0 +1,258 @@
+import { decrypt, deriveSessionKeys, encrypt, exportPublicKey, generateKeyPair, importPublicKey } from '../../crypto.js';
+import { WalletMessageType } from '../../types.js';
+import { InternalMessageType, MessageOrigin } from './internal_message_types.js';
+/**
+ * Handles wallet session flow in the extension background script.
+ *
+ * This class manages:
+ * - Pending discovery requests (before user approval)
+ * - Active sessions (after key exchange)
+ * - Per-session ECDH key exchange
+ * - Message encryption/decryption
+ *
+ * @example
+ * ```typescript
+ * const handler = new BackgroundConnectionHandler(
+ *   {
+ *     walletId: 'my-wallet',
+ *     walletName: 'My Wallet',
+ *     walletVersion: '1.0.0',
+ *   },
+ *   {
+ *     sendToTab: (tabId, message) => browser.tabs.sendMessage(tabId, message),
+ *     addContentListener: (handler) => browser.runtime.onMessage.addListener(handler),
+ *   },
+ *   {
+ *     onPendingDiscovery: (discovery) => updateBadge(),
+ *     onSessionEstablished: (session) => console.log('Connected:', session.sessionId),
+ *     onWalletMessage: (session, message) => nativePort.postMessage(message),
+ *   }
+ * );
+ *
+ * handler.initialize();
+ * ```
+ */ export class BackgroundConnectionHandler {
+    config;
+    transport;
+    callbacks;
+    pendingDiscoveries;
+    activeSessions;
+    constructor(config, transport, callbacks = {}){
+        this.config = config;
+        this.transport = transport;
+        this.callbacks = callbacks;
+        this.pendingDiscoveries = new Map();
+        this.activeSessions = new Map();
+        this.handleMessage = (message, sender)=>{
+            const msg = message;
+            if (msg.origin !== MessageOrigin.CONTENT_SCRIPT) {
+                return;
+            }
+            const tabId = sender.tab?.id;
+            const tabOrigin = sender.tab?.url ? new URL(sender.tab.url).origin : 'unknown';
+            if (!tabId) {
+                return;
+            }
+            const { type, sessionId, content } = msg;
+            switch(type){
+                case InternalMessageType.DISCOVERY_REQUEST:
+                    this.handleDiscoveryRequest(content, tabId, tabOrigin);
+                    break;
+                case InternalMessageType.KEY_EXCHANGE_REQUEST:
+                    if (sessionId) {
+                        this.handleKeyExchangeRequest(sessionId, content).catch(()=>{
+                        // Key exchange failed - session won't be established
+                        });
+                    }
+                    break;
+                case InternalMessageType.DISCONNECT_REQUEST:
+                    if (sessionId) {
+                        this.terminateSession(sessionId);
+                    }
+                    break;
+                case InternalMessageType.SECURE_MESSAGE:
+                    if (sessionId) {
+                        void this.handleEncryptedMessage(sessionId, content);
+                    }
+                    break;
+            }
+        };
+    }
+    initialize() {
+        this.transport.addContentListener(this.handleMessage);
+    }
+    handleMessage;
+    getWalletInfo() {
+        return {
+            id: this.config.walletId,
+            name: this.config.walletName,
+            version: this.config.walletVersion,
+            icon: this.config.walletIcon
+        };
+    }
+    handleDiscoveryRequest(request, tabId, origin) {
+        const discovery = {
+            requestId: request.requestId,
+            appId: request.appId,
+            origin,
+            chainInfo: request.chainInfo,
+            tabId,
+            timestamp: Date.now(),
+            status: 'pending'
+        };
+        this.pendingDiscoveries.set(request.requestId, discovery);
+        this.callbacks.onPendingDiscovery?.(discovery);
+    }
+    approveDiscovery(requestId) {
+        const discovery = this.pendingDiscoveries.get(requestId);
+        if (!discovery || discovery.status !== 'pending') {
+            return false;
+        }
+        // The discovery requestId becomes our sessionId
+        // This is what will be used internally to correlate
+        // content<->background messages
+        const sessionId = requestId;
+        discovery.status = 'approved';
+        this.transport.sendToTab(discovery.tabId, {
+            origin: MessageOrigin.BACKGROUND,
+            type: InternalMessageType.DISCOVERY_APPROVED,
+            sessionId,
+            content: this.getWalletInfo()
+        });
+        return true;
+    }
+    rejectDiscovery(requestId) {
+        const discovery = this.pendingDiscoveries.get(requestId);
+        if (!discovery || discovery.status !== 'pending') {
+            return false;
+        }
+        discovery.status = 'rejected';
+        this.pendingDiscoveries.delete(requestId);
+        return true;
+    }
+    async handleKeyExchangeRequest(sessionId, request) {
+        const discovery = this.pendingDiscoveries.get(sessionId);
+        if (!discovery || discovery.status !== 'approved') {
+            return;
+        }
+        try {
+            const keyPair = await generateKeyPair();
+            const publicKey = await exportPublicKey(keyPair.publicKey);
+            const appPublicKey = await importPublicKey(request.publicKey);
+            const sessionKeys = await deriveSessionKeys(keyPair, appPublicKey, false);
+            const session = {
+                sessionId,
+                sharedKey: sessionKeys.encryptionKey,
+                verificationHash: sessionKeys.verificationHash,
+                tabId: discovery.tabId,
+                origin: discovery.origin,
+                appId: discovery.appId,
+                connectedAt: Date.now(),
+                chainInfo: discovery.chainInfo
+            };
+            this.activeSessions.set(sessionId, session);
+            this.pendingDiscoveries.delete(sessionId);
+            const response = {
+                type: WalletMessageType.KEY_EXCHANGE_RESPONSE,
+                requestId: sessionId,
+                publicKey
+            };
+            this.transport.sendToTab(discovery.tabId, {
+                origin: MessageOrigin.BACKGROUND,
+                type: InternalMessageType.KEY_EXCHANGE_RESPONSE,
+                sessionId,
+                content: response
+            });
+            this.callbacks.onSessionEstablished?.(session);
+        } catch  {
+        // Key exchange failed silently - session won't be established
+        }
+    }
+    async handleEncryptedMessage(sessionId, encrypted) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        try {
+            const message = await decrypt(session.sharedKey, encrypted);
+            this.callbacks.onWalletMessage?.(session, message);
+        } catch  {
+        // Decryption failed - ignore malformed message
+        }
+    }
+    async sendResponse(sessionId, response) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        try {
+            const encrypted = await encrypt(session.sharedKey, JSON.stringify(response));
+            this.transport.sendToTab(session.tabId, {
+                origin: MessageOrigin.BACKGROUND,
+                type: InternalMessageType.SECURE_RESPONSE,
+                sessionId,
+                content: encrypted
+            });
+        } catch  {
+        // Encryption failed - response won't be sent
+        }
+    }
+    terminateSession(sessionId) {
+        const session = this.activeSessions.get(sessionId);
+        if (session) {
+            // Notify the content script (and ultimately the dApp) that the session is disconnected
+            this.transport.sendToTab(session.tabId, {
+                origin: MessageOrigin.BACKGROUND,
+                type: InternalMessageType.SESSION_DISCONNECTED,
+                sessionId
+            });
+            this.activeSessions.delete(sessionId);
+            this.callbacks.onSessionTerminated?.(sessionId);
+            // Restore discovery to approved state so user can retry key exchange
+            const discovery = {
+                requestId: sessionId,
+                appId: session.appId,
+                origin: session.origin,
+                chainInfo: session.chainInfo,
+                tabId: session.tabId,
+                timestamp: Date.now(),
+                status: 'approved'
+            };
+            this.pendingDiscoveries.set(sessionId, discovery);
+        }
+    }
+    terminateForTab(tabId) {
+        for (const [sessionId, session] of this.activeSessions){
+            if (session.tabId === tabId) {
+                this.terminateSession(sessionId);
+            }
+        }
+        for (const [requestId, discovery] of this.pendingDiscoveries){
+            if (discovery.tabId === tabId) {
+                this.pendingDiscoveries.delete(requestId);
+            }
+        }
+    }
+    clearAll() {
+        for (const sessionId of this.activeSessions.keys()){
+            this.callbacks.onSessionTerminated?.(sessionId);
+        }
+        this.activeSessions.clear();
+        this.pendingDiscoveries.clear();
+    }
+    getPendingDiscoveries() {
+        return Array.from(this.pendingDiscoveries.values()).filter((d)=>d.status === 'pending');
+    }
+    getPendingDiscoveryCount() {
+        return this.getPendingDiscoveries().length;
+    }
+    getActiveSessions() {
+        return Array.from(this.activeSessions.values());
+    }
+    getSession(sessionId) {
+        return this.activeSessions.get(sessionId);
+    }
+    getPendingDiscovery(requestId) {
+        return this.pendingDiscoveries.get(requestId);
+    }
+}

package/dest/extension/handlers/content_script_connection_handler.d.ts

@@ -0,0 +1,56 @@
+import { type BackgroundMessage, type ContentScriptMessage } from './internal_message_types.js';
+/**
+ * Transport interface for content script communication.
+ */
+export interface ContentScriptTransport {
+    /**
+     * Send a message to the background script.
+     * Typically `browser.runtime.sendMessage`.
+     */
+    sendToBackground: (message: ContentScriptMessage) => void;
+    /**
+     * Register a listener for messages from the background script.
+     * Typically `browser.runtime.onMessage.addListener`.
+     */
+    addBackgroundListener: (handler: (message: BackgroundMessage) => void) => void;
+}
+/**
+ * Handles wallet connection flow in the extension content script.
+ *
+ * This class manages:
+ * - Listening for discovery requests from the page
+ * - Creating MessageChannels after discovery approval
+ * - Relaying key exchange messages between page and background
+ * - Relaying encrypted messages between page and background
+ *
+ * The content script acts as a pure relay - it never has access to
+ * private keys or shared secrets.
+ *
+ * @example
+ * ```typescript
+ * const handler = new ContentScriptConnectionHandler({
+ *   sendToBackground: (message) => browser.runtime.sendMessage(message),
+ *   addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+ * });
+ *
+ * handler.start();
+ * ```
+ */
+export declare class ContentScriptConnectionHandler {
+    private transport;
+    private ports;
+    private listening;
+    private pageMessageHandler;
+    constructor(transport: ContentScriptTransport);
+    start(): void;
+    private handleBackgroundMessage;
+    private handleDiscoveryRequest;
+    private handleDiscoveryApproved;
+    private handleKeyExchangeResponse;
+    private handleSecureResponse;
+    private handleSessionDisconnected;
+    closeConnection(sessionId: string): void;
+    closeAllConnections(): void;
+    getConnectionCount(): number;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udGVudF9zY3JpcHRfY29ubmVjdGlvbl9oYW5kbGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvZXh0ZW5zaW9uL2hhbmRsZXJzL2NvbnRlbnRfc2NyaXB0X2Nvbm5lY3Rpb25faGFuZGxlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFFQSxPQUFPLEVBQ0wsS0FBSyxpQkFBaUIsRUFDdEIsS0FBSyxvQkFBb0IsRUFHMUIsTUFBTSw2QkFBNkIsQ0FBQztBQW9DckM7O0dBRUc7QUFDSCxNQUFNLFdBQVcsc0JBQXNCO0lBQ3JDOzs7T0FHRztJQUNILGdCQUFnQixFQUFFLENBQUMsT0FBTyxFQUFFLG9CQUFvQixLQUFLLElBQUksQ0FBQztJQUUxRDs7O09BR0c7SUFDSCxxQkFBcUIsRUFBRSxDQUFDLE9BQU8sRUFBRSxDQUFDLE9BQU8sRUFBRSxpQkFBaUIsS0FBSyxJQUFJLEtBQUssSUFBSSxDQUFDO0NBQ2hGO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRztBQUNILHFCQUFhLDhCQUE4QjtJQUs3QixPQUFPLENBQUMsU0FBUztJQUo3QixPQUFPLENBQUMsS0FBSyxDQUFxQztJQUNsRCxPQUFPLENBQUMsU0FBUyxDQUFTO0lBQzFCLE9BQU8sQ0FBQyxrQkFBa0IsQ0FBZ0Q7SUFFMUUsWUFBb0IsU0FBUyxFQUFFLHNCQUFzQixFQUFJO0lBRXpELEtBQUssSUFBSSxJQUFJLENBOEJaO0lBRUQsT0FBTyxDQUFDLHVCQUF1QixDQXFCN0I7SUFFRixPQUFPLENBQUMsc0JBQXNCO0lBUTlCLE9BQU8sQ0FBQyx1QkFBdUI7SUFpRC9CLE9BQU8sQ0FBQyx5QkFBeUI7SUFRakMsT0FBTyxDQUFDLG9CQUFvQjtJQVE1QixPQUFPLENBQUMseUJBQXlCO0lBVWpDLGVBQWUsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLElBQUksQ0FNdkM7SUFFRCxtQkFBbUIsSUFBSSxJQUFJLENBSzFCO0lBRUQsa0JBQWtCLElBQUksTUFBTSxDQUUzQjtDQUNGIn0=

package/dest/extension/handlers/content_script_connection_handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content_script_connection_handler.d.ts","sourceRoot":"","sources":["../../../src/extension/handlers/content_script_connection_handler.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAG1B,MAAM,6BAA6B,CAAC;AAoCrC;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAE1D;;;OAGG;IACH,qBAAqB,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,KAAK,IAAI,CAAC;CAChF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,8BAA8B;IAK7B,OAAO,CAAC,SAAS;IAJ7B,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,kBAAkB,CAAgD;IAE1E,YAAoB,SAAS,EAAE,sBAAsB,EAAI;IAEzD,KAAK,IAAI,IAAI,CA8BZ;IAED,OAAO,CAAC,uBAAuB,CAqB7B;IAEF,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,uBAAuB;IAiD/B,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,yBAAyB;IAUjC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMvC;IAED,mBAAmB,IAAI,IAAI,CAK1B;IAED,kBAAkB,IAAI,MAAM,CAE3B;CACF"}

package/dest/extension/handlers/content_script_connection_handler.js

@@ -0,0 +1,174 @@
+import { WalletMessageType } from '../../types.js';
+import { InternalMessageType, MessageOrigin } from './internal_message_types.js';
+/**
+ * Handles wallet connection flow in the extension content script.
+ *
+ * This class manages:
+ * - Listening for discovery requests from the page
+ * - Creating MessageChannels after discovery approval
+ * - Relaying key exchange messages between page and background
+ * - Relaying encrypted messages between page and background
+ *
+ * The content script acts as a pure relay - it never has access to
+ * private keys or shared secrets.
+ *
+ * @example
+ * ```typescript
+ * const handler = new ContentScriptConnectionHandler({
+ *   sendToBackground: (message) => browser.runtime.sendMessage(message),
+ *   addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+ * });
+ *
+ * handler.start();
+ * ```
+ */ export class ContentScriptConnectionHandler {
+    transport;
+    ports;
+    listening;
+    pageMessageHandler;
+    constructor(transport){
+        this.transport = transport;
+        this.ports = new Map();
+        this.listening = false;
+        this.pageMessageHandler = null;
+        this.handleBackgroundMessage = (message)=>{
+            if (message.origin !== MessageOrigin.BACKGROUND) {
+                return;
+            }
+            const { type, sessionId, content } = message;
+            switch(type){
+                case InternalMessageType.DISCOVERY_APPROVED:
+                    this.handleDiscoveryApproved(sessionId, content);
+                    break;
+                case InternalMessageType.KEY_EXCHANGE_RESPONSE:
+                    this.handleKeyExchangeResponse(sessionId, content);
+                    break;
+                case InternalMessageType.SECURE_RESPONSE:
+                    this.handleSecureResponse(sessionId, content);
+                    break;
+                case InternalMessageType.SESSION_DISCONNECTED:
+                    this.handleSessionDisconnected(sessionId);
+                    break;
+            }
+        };
+    }
+    start() {
+        if (this.listening) {
+            return;
+        }
+        this.transport.addBackgroundListener(this.handleBackgroundMessage);
+        this.pageMessageHandler = (event)=>{
+            if (event.source !== window) {
+                return;
+            }
+            let data;
+            try {
+                data = JSON.parse(event.data);
+            } catch  {
+                return;
+            }
+            if (!data?.type) {
+                return;
+            }
+            if (data.type === WalletMessageType.DISCOVERY) {
+                this.handleDiscoveryRequest(data);
+            }
+        };
+        window.addEventListener('message', this.pageMessageHandler);
+        this.listening = true;
+    }
+    handleBackgroundMessage;
+    handleDiscoveryRequest(request) {
+        this.transport.sendToBackground({
+            origin: MessageOrigin.CONTENT_SCRIPT,
+            type: InternalMessageType.DISCOVERY_REQUEST,
+            content: request
+        });
+    }
+    handleDiscoveryApproved(sessionId, walletInfo) {
+        const channel = new MessageChannel();
+        this.ports.set(sessionId, {
+            port: channel.port1,
+            sessionId
+        });
+        channel.port1.onmessage = (event)=>{
+            const data = event.data;
+            switch(data?.type){
+                case WalletMessageType.KEY_EXCHANGE_REQUEST:
+                    this.transport.sendToBackground({
+                        origin: MessageOrigin.CONTENT_SCRIPT,
+                        type: InternalMessageType.KEY_EXCHANGE_REQUEST,
+                        sessionId,
+                        content: data
+                    });
+                    break;
+                case WalletMessageType.DISCONNECT:
+                    this.transport.sendToBackground({
+                        origin: MessageOrigin.CONTENT_SCRIPT,
+                        type: InternalMessageType.DISCONNECT_REQUEST,
+                        sessionId,
+                        content: data
+                    });
+                    break;
+                default:
+                    this.transport.sendToBackground({
+                        origin: MessageOrigin.CONTENT_SCRIPT,
+                        type: InternalMessageType.SECURE_MESSAGE,
+                        sessionId,
+                        content: data
+                    });
+                    break;
+            }
+        };
+        channel.port1.start();
+        const response = {
+            type: WalletMessageType.DISCOVERY_RESPONSE,
+            requestId: sessionId,
+            walletInfo
+        };
+        window.postMessage(JSON.stringify(response), '*', [
+            channel.port2
+        ]);
+    }
+    handleKeyExchangeResponse(sessionId, response) {
+        const connection = this.ports.get(sessionId);
+        if (!connection) {
+            return;
+        }
+        connection.port.postMessage(response);
+    }
+    handleSecureResponse(sessionId, content) {
+        const connection = this.ports.get(sessionId);
+        if (!connection) {
+            return;
+        }
+        connection.port.postMessage(content);
+    }
+    handleSessionDisconnected(sessionId) {
+        const connection = this.ports.get(sessionId);
+        if (!connection) {
+            return;
+        }
+        connection.port.postMessage({
+            type: WalletMessageType.DISCONNECT
+        });
+        connection.port.close();
+        this.ports.delete(sessionId);
+    }
+    closeConnection(sessionId) {
+        const connection = this.ports.get(sessionId);
+        if (connection) {
+            connection.port.close();
+            this.ports.delete(sessionId);
+        }
+    }
+    closeAllConnections() {
+        for (const [sessionId, connection] of this.ports){
+            connection.port.close();
+            this.ports.delete(sessionId);
+        }
+    }
+    getConnectionCount() {
+        return this.ports.size;
+    }
+}

package/dest/extension/handlers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser-safe exports for extension background and content scripts.
+ *
+ * This module contains ONLY handlers that work in service worker/content script
+ * environments without Node.js polyfills.
+ *
+ * @packageDocumentation
+ */
+export { BackgroundConnectionHandler, type PendingDiscovery, type ActiveSession, type DiscoveryStatus, type BackgroundConnectionCallbacks, type BackgroundConnectionConfig, type BackgroundTransport, } from './background_connection_handler.js';
+export { ContentScriptConnectionHandler, type ContentScriptTransport } from './content_script_connection_handler.js';
+export { type ContentScriptMessage, type BackgroundMessage, type MessageSender, type MessageOriginType, MessageOrigin, } from './internal_message_types.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9leHRlbnNpb24vaGFuZGxlcnMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7R0FPRztBQUNILE9BQU8sRUFDTCwyQkFBMkIsRUFDM0IsS0FBSyxnQkFBZ0IsRUFDckIsS0FBSyxhQUFhLEVBQ2xCLEtBQUssZUFBZSxFQUNwQixLQUFLLDZCQUE2QixFQUNsQyxLQUFLLDBCQUEwQixFQUMvQixLQUFLLG1CQUFtQixHQUN6QixNQUFNLG9DQUFvQyxDQUFDO0FBQzVDLE9BQU8sRUFBRSw4QkFBOEIsRUFBRSxLQUFLLHNCQUFzQixFQUFFLE1BQU0sd0NBQXdDLENBQUM7QUFDckgsT0FBTyxFQUNMLEtBQUssb0JBQW9CLEVBQ3pCLEtBQUssaUJBQWlCLEVBQ3RCLEtBQUssYUFBYSxFQUNsQixLQUFLLGlCQUFpQixFQUN0QixhQUFhLEdBQ2QsTUFBTSw2QkFBNkIsQ0FBQyJ9

package/dest/extension/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extension/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,2BAA2B,EAC3B,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,8BAA8B,EAAE,KAAK,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AACrH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,aAAa,GACd,MAAM,6BAA6B,CAAC"}