@aztec/wallet-sdk 0.0.1-commit.96bb3f7 → 0.0.1-commit.993d240

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.md +218 -355
  2. package/dest/base-wallet/base_wallet.d.ts +109 -40
  3. package/dest/base-wallet/base_wallet.d.ts.map +1 -1
  4. package/dest/base-wallet/base_wallet.js +286 -71
  5. package/dest/base-wallet/index.d.ts +3 -2
  6. package/dest/base-wallet/index.d.ts.map +1 -1
  7. package/dest/base-wallet/index.js +1 -0
  8. package/dest/base-wallet/utils.d.ts +52 -0
  9. package/dest/base-wallet/utils.d.ts.map +1 -0
  10. package/dest/base-wallet/utils.js +137 -0
  11. package/dest/crypto.d.ts +111 -27
  12. package/dest/crypto.d.ts.map +1 -1
  13. package/dest/crypto.js +307 -41
  14. package/dest/emoji_alphabet.d.ts +35 -0
  15. package/dest/emoji_alphabet.d.ts.map +1 -0
  16. package/dest/emoji_alphabet.js +299 -0
  17. package/dest/extension/handlers/background_connection_handler.d.ts +168 -0
  18. package/dest/extension/handlers/background_connection_handler.d.ts.map +1 -0
  19. package/dest/extension/handlers/background_connection_handler.js +294 -0
  20. package/dest/extension/handlers/content_script_connection_handler.d.ts +57 -0
  21. package/dest/extension/handlers/content_script_connection_handler.d.ts.map +1 -0
  22. package/dest/extension/handlers/content_script_connection_handler.js +193 -0
  23. package/dest/extension/handlers/index.d.ts +12 -0
  24. package/dest/extension/handlers/index.d.ts.map +1 -0
  25. package/dest/extension/handlers/index.js +10 -0
  26. package/dest/extension/handlers/internal_message_types.d.ts +65 -0
  27. package/dest/extension/handlers/internal_message_types.d.ts.map +1 -0
  28. package/dest/extension/handlers/internal_message_types.js +24 -0
  29. package/dest/extension/provider/extension_provider.d.ts +107 -0
  30. package/dest/extension/provider/extension_provider.d.ts.map +1 -0
  31. package/dest/extension/provider/extension_provider.js +160 -0
  32. package/dest/extension/provider/extension_wallet.d.ts +152 -0
  33. package/dest/extension/provider/extension_wallet.d.ts.map +1 -0
  34. package/dest/extension/provider/extension_wallet.js +349 -0
  35. package/dest/extension/provider/index.d.ts +3 -0
  36. package/dest/extension/provider/index.d.ts.map +1 -0
  37. package/dest/{providers/extension → extension/provider}/index.js +0 -1
  38. package/dest/iframe/handlers/iframe_connection_handler.d.ts +122 -0
  39. package/dest/iframe/handlers/iframe_connection_handler.d.ts.map +1 -0
  40. package/dest/iframe/handlers/iframe_connection_handler.js +239 -0
  41. package/dest/iframe/handlers/index.d.ts +2 -0
  42. package/dest/iframe/handlers/index.d.ts.map +1 -0
  43. package/dest/iframe/handlers/index.js +1 -0
  44. package/dest/iframe/provider/iframe_discovery.d.ts +25 -0
  45. package/dest/iframe/provider/iframe_discovery.d.ts.map +1 -0
  46. package/dest/iframe/provider/iframe_discovery.js +167 -0
  47. package/dest/iframe/provider/iframe_provider.d.ts +65 -0
  48. package/dest/iframe/provider/iframe_provider.d.ts.map +1 -0
  49. package/dest/iframe/provider/iframe_provider.js +257 -0
  50. package/dest/iframe/provider/iframe_wallet.d.ts +85 -0
  51. package/dest/iframe/provider/iframe_wallet.d.ts.map +1 -0
  52. package/dest/iframe/provider/iframe_wallet.js +269 -0
  53. package/dest/iframe/provider/index.d.ts +4 -0
  54. package/dest/iframe/provider/index.d.ts.map +1 -0
  55. package/dest/iframe/provider/index.js +3 -0
  56. package/dest/manager/index.d.ts +2 -7
  57. package/dest/manager/index.d.ts.map +1 -1
  58. package/dest/manager/index.js +0 -4
  59. package/dest/manager/types.d.ts +109 -5
  60. package/dest/manager/types.d.ts.map +1 -1
  61. package/dest/manager/types.js +17 -1
  62. package/dest/manager/wallet_manager.d.ts +50 -7
  63. package/dest/manager/wallet_manager.d.ts.map +1 -1
  64. package/dest/manager/wallet_manager.js +208 -29
  65. package/dest/types.d.ts +117 -15
  66. package/dest/types.d.ts.map +1 -1
  67. package/dest/types.js +39 -2
  68. package/package.json +22 -11
  69. package/src/base-wallet/base_wallet.ts +395 -128
  70. package/src/base-wallet/index.ts +7 -1
  71. package/src/base-wallet/utils.ts +248 -0
  72. package/src/crypto.ts +367 -47
  73. package/src/emoji_alphabet.ts +317 -0
  74. package/src/extension/handlers/background_connection_handler.ts +456 -0
  75. package/src/extension/handlers/content_script_connection_handler.ts +264 -0
  76. package/src/extension/handlers/index.ts +25 -0
  77. package/src/extension/handlers/internal_message_types.ts +71 -0
  78. package/src/extension/provider/extension_provider.ts +233 -0
  79. package/src/extension/provider/extension_wallet.ts +410 -0
  80. package/src/extension/provider/index.ts +7 -0
  81. package/src/iframe/handlers/iframe_connection_handler.ts +341 -0
  82. package/src/iframe/handlers/index.ts +7 -0
  83. package/src/iframe/provider/iframe_discovery.ts +185 -0
  84. package/src/iframe/provider/iframe_provider.ts +331 -0
  85. package/src/iframe/provider/iframe_wallet.ts +323 -0
  86. package/src/iframe/provider/index.ts +3 -0
  87. package/src/manager/index.ts +3 -9
  88. package/src/manager/types.ts +113 -4
  89. package/src/manager/wallet_manager.ts +235 -30
  90. package/src/types.ts +129 -14
  91. package/dest/providers/extension/extension_provider.d.ts +0 -17
  92. package/dest/providers/extension/extension_provider.d.ts.map +0 -1
  93. package/dest/providers/extension/extension_provider.js +0 -56
  94. package/dest/providers/extension/extension_wallet.d.ts +0 -95
  95. package/dest/providers/extension/extension_wallet.d.ts.map +0 -1
  96. package/dest/providers/extension/extension_wallet.js +0 -225
  97. package/dest/providers/extension/index.d.ts +0 -5
  98. package/dest/providers/extension/index.d.ts.map +0 -1
  99. package/src/providers/extension/extension_provider.ts +0 -72
  100. package/src/providers/extension/extension_wallet.ts +0 -275
  101. package/src/providers/extension/index.ts +0 -11
@@ -0,0 +1,107 @@
1
+ import type { ChainInfo } from '@aztec/aztec.js/account';
2
+ import { type ConnectedWalletInfo, type WalletInfo } from '../../types.js';
3
+ /**
4
+ * A discovered wallet before key exchange.
5
+ * Has basic info and MessagePort, but no shared key yet.
6
+ *
7
+ * Call {@link establishSecureChannel} to perform key exchange and get a connected wallet.
8
+ */
9
+ export declare class DiscoveredWallet {
10
+ /** Basic wallet information (id, name, icon, version) */
11
+ readonly info: WalletInfo;
12
+ /** The MessagePort for private communication with the wallet */
13
+ readonly port: MessagePort;
14
+ /** Request ID for correlation */
15
+ readonly requestId: string;
16
+ constructor(
17
+ /** Basic wallet information (id, name, icon, version) */
18
+ info: WalletInfo,
19
+ /** The MessagePort for private communication with the wallet */
20
+ port: MessagePort,
21
+ /** Request ID for correlation */
22
+ requestId: string);
23
+ /**
24
+ * Establishes a secure connection with this wallet.
25
+ *
26
+ * This method:
27
+ * 1. Generates an ECDH key pair
28
+ * 2. Sends public key to wallet over the MessagePort
29
+ * 3. Receives wallet's public key
30
+ * 4. Derives shared secret and computes verification hash locally
31
+ *
32
+ * **IMPORTANT**: Has a 2 second timeout for MITM defense.
33
+ * Both parties must exchange keys relatively quickly.
34
+ *
35
+ * The verification hash is computed independently by both parties
36
+ * and should be displayed to the user for visual comparison.
37
+ *
38
+ * @returns Connected wallet with shared key and verification hash
39
+ * @throws Error if key exchange fails or times out
40
+ */
41
+ establishSecureChannel(): Promise<ConnectedWallet>;
42
+ }
43
+ /**
44
+ * A fully connected wallet with secure channel established.
45
+ * Available after key exchange completes.
46
+ */
47
+ export interface ConnectedWallet {
48
+ /** Full wallet info including public key and verification hash */
49
+ info: ConnectedWalletInfo;
50
+ /** The MessagePort for encrypted communication */
51
+ port: MessagePort;
52
+ /** The derived AES-256-GCM shared key for encryption */
53
+ sharedKey: CryptoKey;
54
+ }
55
+ /**
56
+ * Options for wallet discovery.
57
+ */
58
+ export interface DiscoveryOptions {
59
+ /** Application ID making the request */
60
+ appId: string;
61
+ /** How long to wait for user approval (ms). Default: 60000 (60s) */
62
+ timeout?: number;
63
+ /**
64
+ * Callback invoked when a wallet is discovered.
65
+ * Wallets are streamed as users approve them.
66
+ */
67
+ onWalletDiscovered?: (wallet: DiscoveredWallet) => void;
68
+ /**
69
+ * AbortSignal for cancelling discovery early.
70
+ * When aborted, cleanup happens immediately instead of waiting for timeout.
71
+ */
72
+ signal?: AbortSignal;
73
+ }
74
+ /**
75
+ * Provider for discovering Aztec wallet extensions.
76
+ *
77
+ * NOTE: Most users should use WalletManager instead of this class directly.
78
+ * WalletManager provides a higher-level API with streaming support.
79
+ *
80
+ * The connection flow is split into two phases for security:
81
+ *
82
+ * 1. **Discovery Phase** ({@link discoverWallets}):
83
+ * - Broadcasts a discovery request (NO public keys)
84
+ * - Wallet shows pending request to user
85
+ * - User must approve before wallet reveals itself
86
+ * - Wallets are streamed via callback as they're approved
87
+ *
88
+ * 2. **Secure Channel Phase** ({@link DiscoveredWallet.establishSecureChannel}):
89
+ * - Performs ECDH key exchange over private MessageChannel
90
+ * - Both parties compute verification hash locally
91
+ * - Has a 2s timeout for MITM defense
92
+ * - Returns connected wallet with shared key and verification hash
93
+ */
94
+ export declare class ExtensionProvider {
95
+ /**
96
+ * Discovers wallet extensions that user has approved.
97
+ *
98
+ * Wallets are streamed via the `onWalletDiscovered` callback as users approve them.
99
+ * The promise resolves when the timeout expires or signal is aborted.
100
+ *
101
+ * @param chainInfo - Chain information to check if extensions support this network
102
+ * @param options - Discovery options including appId, appName, timeout, and callback
103
+ * @returns Promise that resolves when discovery completes
104
+ */
105
+ static discoverWallets(chainInfo: ChainInfo, options: DiscoveryOptions): Promise<void>;
106
+ }
107
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3Byb3ZpZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvZXh0ZW5zaW9uL3Byb3ZpZGVyL2V4dGVuc2lvbl9wcm92aWRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUt6RCxPQUFPLEVBQ0wsS0FBSyxtQkFBbUIsRUFLeEIsS0FBSyxVQUFVLEVBRWhCLE1BQU0sZ0JBQWdCLENBQUM7QUFReEI7Ozs7O0dBS0c7QUFDSCxxQkFBYSxnQkFBZ0I7SUFFekIseURBQXlEO2FBQ3pDLElBQUksRUFBRSxVQUFVO0lBQ2hDLGdFQUFnRTthQUNoRCxJQUFJLEVBQUUsV0FBVztJQUNqQyxpQ0FBaUM7YUFDakIsU0FBUyxFQUFFLE1BQU07SUFObkM7SUFDRSx5REFBeUQ7SUFDekMsSUFBSSxFQUFFLFVBQVU7SUFDaEMsZ0VBQWdFO0lBQ2hELElBQUksRUFBRSxXQUFXO0lBQ2pDLGlDQUFpQztJQUNqQixTQUFTLEVBQUUsTUFBTSxFQUMvQjtJQUVKOzs7Ozs7Ozs7Ozs7Ozs7OztPQWlCRztJQUNHLHNCQUFzQixJQUFJLE9BQU8sQ0FBQyxlQUFlLENBQUMsQ0ErQ3ZEO0NBQ0Y7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFdBQVcsZUFBZTtJQUM5QixrRUFBa0U7SUFDbEUsSUFBSSxFQUFFLG1CQUFtQixDQUFDO0lBQzFCLGtEQUFrRDtJQUNsRCxJQUFJLEVBQUUsV0FBVyxDQUFDO0lBQ2xCLHdEQUF3RDtJQUN4RCxTQUFTLEVBQUUsU0FBUyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsZ0JBQWdCO0lBQy9CLHdDQUF3QztJQUN4QyxLQUFLLEVBQUUsTUFBTSxDQUFDO0lBQ2Qsb0VBQW9FO0lBQ3BFLE9BQU8sQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNqQjs7O09BR0c7SUFDSCxrQkFBa0IsQ0FBQyxFQUFFLENBQUMsTUFBTSxFQUFFLGdCQUFnQixLQUFLLElBQUksQ0FBQztJQUN4RDs7O09BR0c7SUFDSCxNQUFNLENBQUMsRUFBRSxXQUFXLENBQUM7Q0FDdEI7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW1CRztBQUNILHFCQUFhLGlCQUFpQjtJQUM1Qjs7Ozs7Ozs7O09BU0c7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLFNBQVMsRUFBRSxTQUFTLEVBQUUsT0FBTyxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E4RHJGO0NBQ0YifQ==
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extension_provider.d.ts","sourceRoot":"","sources":["../../../src/extension/provider/extension_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAKzD,OAAO,EACL,KAAK,mBAAmB,EAKxB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAQxB;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEzB,yDAAyD;aACzC,IAAI,EAAE,UAAU;IAChC,gEAAgE;aAChD,IAAI,EAAE,WAAW;IACjC,iCAAiC;aACjB,SAAS,EAAE,MAAM;IANnC;IACE,yDAAyD;IACzC,IAAI,EAAE,UAAU;IAChC,gEAAgE;IAChD,IAAI,EAAE,WAAW;IACjC,iCAAiC;IACjB,SAAS,EAAE,MAAM,EAC/B;IAEJ;;;;;;;;;;;;;;;;;OAiBG;IACG,sBAAsB,IAAI,OAAO,CAAC,eAAe,CAAC,CA+CvD;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,WAAW,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxD;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8DrF;CACF"}
@@ -0,0 +1,160 @@
1
+ import { jsonStringify } from '@aztec/foundation/json-rpc';
2
+ import { promiseWithResolvers } from '@aztec/foundation/promise';
3
+ import { deriveSessionKeys, exportPublicKey, generateKeyPair, importPublicKey } from '../../crypto.js';
4
+ import { WalletMessageType } from '../../types.js';
5
+ /** Default discovery timeout - long to give users time to approve */ const DEFAULT_DISCOVERY_TIMEOUT_MS = 60000; // 60 seconds
6
+ /** Key exchange timeout - short, wallet should respond quickly after discovery approval */ const KEY_EXCHANGE_TIMEOUT_MS = 2000; // 2 seconds
7
+ /**
8
+ * A discovered wallet before key exchange.
9
+ * Has basic info and MessagePort, but no shared key yet.
10
+ *
11
+ * Call {@link establishSecureChannel} to perform key exchange and get a connected wallet.
12
+ */ export class DiscoveredWallet {
13
+ info;
14
+ port;
15
+ requestId;
16
+ constructor(/** Basic wallet information (id, name, icon, version) */ info, /** The MessagePort for private communication with the wallet */ port, /** Request ID for correlation */ requestId){
17
+ this.info = info;
18
+ this.port = port;
19
+ this.requestId = requestId;
20
+ }
21
+ /**
22
+ * Establishes a secure connection with this wallet.
23
+ *
24
+ * This method:
25
+ * 1. Generates an ECDH key pair
26
+ * 2. Sends public key to wallet over the MessagePort
27
+ * 3. Receives wallet's public key
28
+ * 4. Derives shared secret and computes verification hash locally
29
+ *
30
+ * **IMPORTANT**: Has a 2 second timeout for MITM defense.
31
+ * Both parties must exchange keys relatively quickly.
32
+ *
33
+ * The verification hash is computed independently by both parties
34
+ * and should be displayed to the user for visual comparison.
35
+ *
36
+ * @returns Connected wallet with shared key and verification hash
37
+ * @throws Error if key exchange fails or times out
38
+ */ async establishSecureChannel() {
39
+ const keyPair = await generateKeyPair();
40
+ const exportedPublicKey = await exportPublicKey(keyPair.publicKey);
41
+ const { promise, resolve, reject } = promiseWithResolvers();
42
+ const timeoutId = setTimeout(()=>{
43
+ reject(new Error('Key exchange timeout'));
44
+ }, KEY_EXCHANGE_TIMEOUT_MS);
45
+ this.port.onmessage = async (event)=>{
46
+ const data = event.data;
47
+ if (data.type === WalletMessageType.KEY_EXCHANGE_RESPONSE && data.requestId === this.requestId) {
48
+ clearTimeout(timeoutId);
49
+ try {
50
+ const walletPublicKey = await importPublicKey(data.publicKey);
51
+ const session = await deriveSessionKeys(keyPair, walletPublicKey, true);
52
+ const connectedInfo = {
53
+ ...this.info,
54
+ publicKey: data.publicKey,
55
+ verificationHash: session.verificationHash
56
+ };
57
+ resolve({
58
+ info: connectedInfo,
59
+ port: this.port,
60
+ sharedKey: session.encryptionKey
61
+ });
62
+ } catch (err) {
63
+ reject(new Error(`Key exchange failed: ${err}`));
64
+ }
65
+ }
66
+ };
67
+ this.port.start();
68
+ const keyExchangeRequest = {
69
+ type: WalletMessageType.KEY_EXCHANGE_REQUEST,
70
+ requestId: this.requestId,
71
+ publicKey: exportedPublicKey
72
+ };
73
+ this.port.postMessage(keyExchangeRequest);
74
+ return promise;
75
+ }
76
+ }
77
+ /**
78
+ * Provider for discovering Aztec wallet extensions.
79
+ *
80
+ * NOTE: Most users should use WalletManager instead of this class directly.
81
+ * WalletManager provides a higher-level API with streaming support.
82
+ *
83
+ * The connection flow is split into two phases for security:
84
+ *
85
+ * 1. **Discovery Phase** ({@link discoverWallets}):
86
+ * - Broadcasts a discovery request (NO public keys)
87
+ * - Wallet shows pending request to user
88
+ * - User must approve before wallet reveals itself
89
+ * - Wallets are streamed via callback as they're approved
90
+ *
91
+ * 2. **Secure Channel Phase** ({@link DiscoveredWallet.establishSecureChannel}):
92
+ * - Performs ECDH key exchange over private MessageChannel
93
+ * - Both parties compute verification hash locally
94
+ * - Has a 2s timeout for MITM defense
95
+ * - Returns connected wallet with shared key and verification hash
96
+ */ export class ExtensionProvider {
97
+ /**
98
+ * Discovers wallet extensions that user has approved.
99
+ *
100
+ * Wallets are streamed via the `onWalletDiscovered` callback as users approve them.
101
+ * The promise resolves when the timeout expires or signal is aborted.
102
+ *
103
+ * @param chainInfo - Chain information to check if extensions support this network
104
+ * @param options - Discovery options including appId, appName, timeout, and callback
105
+ * @returns Promise that resolves when discovery completes
106
+ */ static discoverWallets(chainInfo, options) {
107
+ if (options.signal?.aborted) {
108
+ return Promise.resolve();
109
+ }
110
+ const timeout = options.timeout ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
111
+ return new Promise((resolve)=>{
112
+ const requestId = globalThis.crypto.randomUUID();
113
+ let timeoutId = null;
114
+ let completed = false;
115
+ const finish = ()=>{
116
+ if (completed) {
117
+ return;
118
+ }
119
+ completed = true;
120
+ if (timeoutId !== null) {
121
+ clearTimeout(timeoutId);
122
+ }
123
+ window.removeEventListener('message', onMessage);
124
+ options.signal?.removeEventListener('abort', onAbort);
125
+ resolve();
126
+ };
127
+ const onAbort = ()=>finish();
128
+ const onMessage = (event)=>{
129
+ if (completed || event.source !== window) {
130
+ return;
131
+ }
132
+ let data;
133
+ try {
134
+ data = JSON.parse(event.data);
135
+ } catch {
136
+ return;
137
+ }
138
+ if (data.type !== WalletMessageType.DISCOVERY_RESPONSE || data.requestId !== requestId) {
139
+ return;
140
+ }
141
+ const port = event.ports?.[0];
142
+ if (port) {
143
+ options.onWalletDiscovered?.(new DiscoveredWallet(data.walletInfo, port, requestId));
144
+ }
145
+ };
146
+ options.signal?.addEventListener('abort', onAbort, {
147
+ once: true
148
+ });
149
+ window.addEventListener('message', onMessage);
150
+ const discoveryMessage = {
151
+ type: WalletMessageType.DISCOVERY,
152
+ requestId,
153
+ appId: options.appId,
154
+ chainInfo
155
+ };
156
+ window.postMessage(jsonStringify(discoveryMessage), '*');
157
+ timeoutId = setTimeout(finish, timeout);
158
+ });
159
+ }
160
+ }
@@ -0,0 +1,152 @@
1
+ import type { ChainInfo } from '@aztec/aztec.js/account';
2
+ import { type Wallet } from '@aztec/aztec.js/wallet';
3
+ import { type DisconnectCallback, type HeartbeatOptions, type WalletSdkLogger } from '../../types.js';
4
+ /**
5
+ * A wallet implementation that communicates with browser extension wallets
6
+ * using an encrypted MessageChannel.
7
+ *
8
+ * This class uses a secure channel established after discovery:
9
+ *
10
+ * 1. **MessageChannel**: Created during discovery and transferred via window.postMessage.
11
+ * Note: The port transfer is visible to page scripts, but security comes from encryption.
12
+ *
13
+ * 2. **ECDH Key Exchange**: The shared secret was derived after discovery using
14
+ * Elliptic Curve Diffie-Hellman key exchange over the MessagePort.
15
+ *
16
+ * 3. **AES-GCM Encryption**: All messages are encrypted using AES-256-GCM,
17
+ * providing both confidentiality and authenticity. This is what secures the channel.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * // Discover and establish secure channel to a wallet
22
+ * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-dapp' });
23
+ * const connection = await discoveredWallets[0].establishSecureChannel();
24
+ *
25
+ * // User can verify emoji if desired
26
+ * console.log('Verify:', hashToEmoji(connection.info.verificationHash!));
27
+ *
28
+ * // Create wallet using the connection
29
+ * const wallet = ExtensionWallet.create(connection.info.id, connection.port, connection.sharedKey, chainInfo, 'my-dapp');
30
+ *
31
+ * // All subsequent calls are encrypted
32
+ * const accounts = await wallet.getAccounts();
33
+ * ```
34
+ */
35
+ export declare class ExtensionWallet {
36
+ private chainInfo;
37
+ private appId;
38
+ private extensionId;
39
+ private port;
40
+ private sharedKey;
41
+ /** Map of pending requests awaiting responses, keyed by message ID */
42
+ private inFlight;
43
+ private disconnected;
44
+ private disconnectCallbacks;
45
+ private heartbeatTimer;
46
+ private lastInboundAt;
47
+ private log;
48
+ private heartbeatIntervalMs;
49
+ private heartbeatDeadAfterMs;
50
+ /**
51
+ * Private constructor - use {@link ExtensionWallet.create} to instantiate.
52
+ * @param chainInfo - The chain information (chainId and version)
53
+ * @param appId - Application identifier for the requesting dApp
54
+ * @param extensionId - The unique identifier of the target wallet extension
55
+ * @param port - The MessagePort for private communication with the wallet
56
+ * @param sharedKey - The derived AES-256-GCM shared key for encryption
57
+ * @param logger - Optional logger; defaults to a no-op logger
58
+ * @param heartbeatOptions - Optional heartbeat tuning (mostly useful for tests)
59
+ */
60
+ private constructor();
61
+ /**
62
+ * Creates a Wallet that communicates with a browser extension
63
+ * over a secure encrypted MessageChannel.
64
+ *
65
+ * @param extensionId - The unique identifier of the wallet extension
66
+ * @param port - The MessagePort for encrypted communication with the wallet
67
+ * @param sharedKey - The derived AES-256-GCM shared key for encryption
68
+ * @param chainInfo - The chain information (chainId and version) for request context
69
+ * @param appId - Application identifier used to identify the requesting dApp to the wallet
70
+ * @param logger - Optional logger; defaults to a no-op logger to keep extension/page bundles small
71
+ * @param heartbeatOptions - Optional override for heartbeat tuning (mostly useful for tests)
72
+ * @returns A Wallet interface where all method calls are encrypted
73
+ *
74
+ * @example
75
+ * ```typescript
76
+ * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-defi-app' });
77
+ * const connection = await discoveredWallets[0].establishSecureChannel();
78
+ * const wallet = ExtensionWallet.create(
79
+ * connection.info.id,
80
+ * connection.port,
81
+ * connection.sharedKey,
82
+ * chainInfo,
83
+ * 'my-defi-app'
84
+ * );
85
+ *
86
+ * const accounts = await wallet.getAccounts();
87
+ * ```
88
+ */
89
+ static create(extensionId: string, port: MessagePort, sharedKey: CryptoKey, chainInfo: ChainInfo, appId: string, logger?: WalletSdkLogger, heartbeatOptions?: HeartbeatOptions): ExtensionWallet;
90
+ asWallet(): Wallet;
91
+ private handleEncryptedResponse;
92
+ private postMessage;
93
+ /**
94
+ * Start the heartbeat probe loop while at least one request is in flight.
95
+ * Idempotent — calling while already running is a no-op.
96
+ *
97
+ * Heartbeat is opt-in via wire protocol: PINGs are unencrypted control messages
98
+ * (like DISCONNECT). Older wallets that do not understand PING simply drop it,
99
+ * which is safe — we only declare disconnect when **no** inbound traffic of any
100
+ * kind (PONG, encrypted response, DISCONNECT) arrives within the dead window.
101
+ * A wallet that is processing a slow request will reset the timer when it
102
+ * eventually responds, so this never causes false disconnects on legacy peers.
103
+ */
104
+ private startHeartbeat;
105
+ private maybeStopHeartbeat;
106
+ private heartbeatTick;
107
+ /**
108
+ * Handles wallet disconnection.
109
+ * Rejects all pending requests and notifies registered callbacks.
110
+ * @internal
111
+ */
112
+ private handleDisconnect;
113
+ /**
114
+ * Registers a callback to be invoked when the wallet disconnects.
115
+ *
116
+ * @param callback - Function to call when wallet disconnects
117
+ * @returns A function to unregister the callback
118
+ *
119
+ * @example
120
+ * ```typescript
121
+ * const wallet = await ExtensionWallet.create(...);
122
+ * const unsubscribe = wallet.onDisconnect(() => {
123
+ * console.log('Wallet disconnected! Please reconnect.');
124
+ * // Clean up UI, prompt user to reconnect, etc.
125
+ * });
126
+ * // Later: unsubscribe(); to stop receiving notifications
127
+ * ```
128
+ */
129
+ onDisconnect(callback: DisconnectCallback): () => void;
130
+ /**
131
+ * Returns whether the wallet has been disconnected.
132
+ *
133
+ * @returns true if the wallet is no longer connected
134
+ */
135
+ isDisconnected(): boolean;
136
+ /**
137
+ * Disconnects from the wallet and cleans up resources.
138
+ *
139
+ * This method notifies the wallet extension that the session is ending,
140
+ * allowing it to clean up its state. After calling this method, the wallet
141
+ * instance can no longer be used and any pending requests will be rejected.
142
+ *
143
+ * @example
144
+ * ```typescript
145
+ * const extensionWallet = ExtensionWallet.create(extensionId, port, sharedKey, chainInfo, 'my-app');
146
+ * // ... use wallet ...
147
+ * await extensionWallet.disconnect(); // Clean disconnect when done
148
+ * ```
149
+ */
150
+ disconnect(): Promise<void>;
151
+ }
152
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3dhbGxldC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2V4dGVuc2lvbi9wcm92aWRlci9leHRlbnNpb25fd2FsbGV0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx3QkFBd0IsQ0FBQztBQU9uRSxPQUFPLEVBR0wsS0FBSyxrQkFBa0IsRUFDdkIsS0FBSyxnQkFBZ0IsRUFLckIsS0FBSyxlQUFlLEVBQ3JCLE1BQU0sZ0JBQWdCLENBQUM7QUFheEI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQThCRztBQUNILHFCQUFhLGVBQWU7SUFzQnhCLE9BQU8sQ0FBQyxTQUFTO0lBQ2pCLE9BQU8sQ0FBQyxLQUFLO0lBQ2IsT0FBTyxDQUFDLFdBQVc7SUFDbkIsT0FBTyxDQUFDLElBQUk7SUFDWixPQUFPLENBQUMsU0FBUztJQXpCbkIsc0VBQXNFO0lBQ3RFLE9BQU8sQ0FBQyxRQUFRLENBQW9EO0lBQ3BFLE9BQU8sQ0FBQyxZQUFZLENBQVM7SUFDN0IsT0FBTyxDQUFDLG1CQUFtQixDQUE0QjtJQUN2RCxPQUFPLENBQUMsY0FBYyxDQUErQztJQUNyRSxPQUFPLENBQUMsYUFBYSxDQUFLO0lBQzFCLE9BQU8sQ0FBQyxHQUFHLENBQWtCO0lBQzdCLE9BQU8sQ0FBQyxtQkFBbUIsQ0FBUztJQUNwQyxPQUFPLENBQUMsb0JBQW9CLENBQVM7SUFFckM7Ozs7Ozs7OztPQVNHO0lBQ0gsT0FBTyxlQVlOO0lBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztPQTJCRztJQUNILE1BQU0sQ0FBQyxNQUFNLENBQ1gsV0FBVyxFQUFFLE1BQU0sRUFDbkIsSUFBSSxFQUFFLFdBQVcsRUFDakIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsS0FBSyxFQUFFLE1BQU0sRUFDYixNQUFNLENBQUMsRUFBRSxlQUFlLEVBQ3hCLGdCQUFnQixDQUFDLEVBQUUsZ0JBQWdCLEdBQ2xDLGVBQWUsQ0FvQ2pCO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FJakI7WUFVYSx1QkFBdUI7WUFnRHZCLFdBQVc7SUEyQnpCOzs7Ozs7Ozs7O09BVUc7SUFDSCxPQUFPLENBQUMsY0FBYztJQVF0QixPQUFPLENBQUMsa0JBQWtCO0lBTzFCLE9BQU8sQ0FBQyxhQUFhO0lBdUJyQjs7OztPQUlHO0lBQ0gsT0FBTyxDQUFDLGdCQUFnQjtJQStCeEI7Ozs7Ozs7Ozs7Ozs7OztPQWVHO0lBQ0gsWUFBWSxDQUFDLFFBQVEsRUFBRSxrQkFBa0IsR0FBRyxNQUFNLElBQUksQ0FRckQ7SUFFRDs7OztPQUlHO0lBQ0gsY0FBYyxJQUFJLE9BQU8sQ0FFeEI7SUFFRDs7Ozs7Ozs7Ozs7OztPQWFHO0lBRUcsVUFBVSxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FhaEM7Q0FDRiJ9
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extension_wallet.d.ts","sourceRoot":"","sources":["../../../src/extension/provider/extension_wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,wBAAwB,CAAC;AAOnE,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAKrB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAaxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAe;IAsBxB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,SAAS;IAzBnB,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,oBAAoB,CAAS;IAErC;;;;;;;;;OASG;IACH,OAAO,eAYN;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,MAAM,CACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,eAAe,EACxB,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,eAAe,CAoCjB;IAED,QAAQ,IAAI,MAAM,CAIjB;YAUa,uBAAuB;YAgDvB,WAAW;IA2BzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAuBrB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAQrD;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;;;OAaG;IAEG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAahC;CACF"}