@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,349 @@
1
+ import { WalletSchema } from '@aztec/aztec.js/wallet';
2
+ import { jsonStringify } from '@aztec/foundation/json-rpc';
3
+ import { promiseWithResolvers } from '@aztec/foundation/promise';
4
+ import { getSchemaReturnType, schemaHasMethod } from '@aztec/foundation/schemas';
5
+ import { decrypt, encrypt } from '../../crypto.js';
6
+ import { DEFAULT_HEARTBEAT_DEAD_AFTER_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, NOOP_LOGGER, WalletMessageType } from '../../types.js';
7
+ /**
8
+ * A wallet implementation that communicates with browser extension wallets
9
+ * using an encrypted MessageChannel.
10
+ *
11
+ * This class uses a secure channel established after discovery:
12
+ *
13
+ * 1. **MessageChannel**: Created during discovery and transferred via window.postMessage.
14
+ * Note: The port transfer is visible to page scripts, but security comes from encryption.
15
+ *
16
+ * 2. **ECDH Key Exchange**: The shared secret was derived after discovery using
17
+ * Elliptic Curve Diffie-Hellman key exchange over the MessagePort.
18
+ *
19
+ * 3. **AES-GCM Encryption**: All messages are encrypted using AES-256-GCM,
20
+ * providing both confidentiality and authenticity. This is what secures the channel.
21
+ *
22
+ * @example
23
+ * ```typescript
24
+ * // Discover and establish secure channel to a wallet
25
+ * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-dapp' });
26
+ * const connection = await discoveredWallets[0].establishSecureChannel();
27
+ *
28
+ * // User can verify emoji if desired
29
+ * console.log('Verify:', hashToEmoji(connection.info.verificationHash!));
30
+ *
31
+ * // Create wallet using the connection
32
+ * const wallet = ExtensionWallet.create(connection.info.id, connection.port, connection.sharedKey, chainInfo, 'my-dapp');
33
+ *
34
+ * // All subsequent calls are encrypted
35
+ * const accounts = await wallet.getAccounts();
36
+ * ```
37
+ */ export class ExtensionWallet {
38
+ chainInfo;
39
+ appId;
40
+ extensionId;
41
+ port;
42
+ sharedKey;
43
+ /** Map of pending requests awaiting responses, keyed by message ID */ inFlight;
44
+ disconnected;
45
+ disconnectCallbacks;
46
+ heartbeatTimer;
47
+ lastInboundAt;
48
+ log;
49
+ heartbeatIntervalMs;
50
+ heartbeatDeadAfterMs;
51
+ /**
52
+ * Private constructor - use {@link ExtensionWallet.create} to instantiate.
53
+ * @param chainInfo - The chain information (chainId and version)
54
+ * @param appId - Application identifier for the requesting dApp
55
+ * @param extensionId - The unique identifier of the target wallet extension
56
+ * @param port - The MessagePort for private communication with the wallet
57
+ * @param sharedKey - The derived AES-256-GCM shared key for encryption
58
+ * @param logger - Optional logger; defaults to a no-op logger
59
+ * @param heartbeatOptions - Optional heartbeat tuning (mostly useful for tests)
60
+ */ constructor(chainInfo, appId, extensionId, port, sharedKey, logger, heartbeatOptions){
61
+ this.chainInfo = chainInfo;
62
+ this.appId = appId;
63
+ this.extensionId = extensionId;
64
+ this.port = port;
65
+ this.sharedKey = sharedKey;
66
+ this.inFlight = new Map();
67
+ this.disconnected = false;
68
+ this.disconnectCallbacks = [];
69
+ this.heartbeatTimer = null;
70
+ this.lastInboundAt = 0;
71
+ this.log = logger ?? NOOP_LOGGER;
72
+ this.heartbeatIntervalMs = heartbeatOptions?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
73
+ this.heartbeatDeadAfterMs = heartbeatOptions?.deadAfterMs ?? DEFAULT_HEARTBEAT_DEAD_AFTER_MS;
74
+ }
75
+ /**
76
+ * Creates a Wallet that communicates with a browser extension
77
+ * over a secure encrypted MessageChannel.
78
+ *
79
+ * @param extensionId - The unique identifier of the wallet extension
80
+ * @param port - The MessagePort for encrypted communication with the wallet
81
+ * @param sharedKey - The derived AES-256-GCM shared key for encryption
82
+ * @param chainInfo - The chain information (chainId and version) for request context
83
+ * @param appId - Application identifier used to identify the requesting dApp to the wallet
84
+ * @param logger - Optional logger; defaults to a no-op logger to keep extension/page bundles small
85
+ * @param heartbeatOptions - Optional override for heartbeat tuning (mostly useful for tests)
86
+ * @returns A Wallet interface where all method calls are encrypted
87
+ *
88
+ * @example
89
+ * ```typescript
90
+ * const discoveredWallets = await ExtensionProvider.discoverWallets(chainInfo, { appId: 'my-defi-app' });
91
+ * const connection = await discoveredWallets[0].establishSecureChannel();
92
+ * const wallet = ExtensionWallet.create(
93
+ * connection.info.id,
94
+ * connection.port,
95
+ * connection.sharedKey,
96
+ * chainInfo,
97
+ * 'my-defi-app'
98
+ * );
99
+ *
100
+ * const accounts = await wallet.getAccounts();
101
+ * ```
102
+ */ static create(extensionId, port, sharedKey, chainInfo, appId, logger, heartbeatOptions) {
103
+ const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey, logger, heartbeatOptions);
104
+ // Set up message handler for encrypted responses and unencrypted control messages
105
+ wallet.port.onmessage = (event)=>{
106
+ const data = event.data;
107
+ // Any inbound traffic counts as proof of liveness.
108
+ wallet.lastInboundAt = Date.now();
109
+ if (data && typeof data === 'object' && 'type' in data && data.type === WalletMessageType.DISCONNECT) {
110
+ wallet.handleDisconnect();
111
+ return;
112
+ }
113
+ // Otherwise treat as encrypted payload
114
+ void wallet.handleEncryptedResponse(data);
115
+ };
116
+ wallet.port.start();
117
+ return new Proxy(wallet, {
118
+ get: (target, prop, receiver)=>{
119
+ if (prop === 'asWallet') {
120
+ return ()=>receiver;
121
+ } else if (schemaHasMethod(WalletSchema, prop.toString())) {
122
+ return async (...args)=>{
123
+ const result = await target.postMessage({
124
+ type: prop.toString(),
125
+ args
126
+ });
127
+ return getSchemaReturnType(WalletSchema[prop.toString()]).parseAsync(result);
128
+ };
129
+ } else {
130
+ return target[prop];
131
+ }
132
+ }
133
+ });
134
+ }
135
+ asWallet() {
136
+ // Overridden by the proxy in create() to return the proxy itself.
137
+ // This body is never reached when accessed through create().
138
+ return this;
139
+ }
140
+ /**
141
+ * Handles an encrypted response received from the wallet extension.
142
+ *
143
+ * Decrypts the response using the shared AES key and resolves or rejects
144
+ * the corresponding pending promise based on the response content.
145
+ *
146
+ * @param encrypted - The encrypted response from the wallet
147
+ */ async handleEncryptedResponse(encrypted) {
148
+ if (!this.sharedKey) {
149
+ return;
150
+ }
151
+ try {
152
+ const response = await decrypt(this.sharedKey, encrypted);
153
+ const { messageId, result, error, walletId: responseWalletId } = response;
154
+ if (!messageId || !responseWalletId) {
155
+ return;
156
+ }
157
+ if (this.extensionId !== responseWalletId) {
158
+ return;
159
+ }
160
+ if (!this.inFlight.has(messageId)) {
161
+ return;
162
+ }
163
+ const { resolve, reject } = this.inFlight.get(messageId);
164
+ if (error) {
165
+ reject(new Error(jsonStringify(error)));
166
+ } else {
167
+ resolve(result);
168
+ }
169
+ this.inFlight.delete(messageId);
170
+ this.maybeStopHeartbeat();
171
+ } catch (err) {
172
+ this.log.warn('Failed to decrypt wallet response', {
173
+ err
174
+ });
175
+ }
176
+ }
177
+ /**
178
+ * Sends an encrypted wallet method call over the secure MessageChannel.
179
+ *
180
+ * The message is encrypted using AES-256-GCM with the shared key derived
181
+ * during discovery. A unique message ID is generated to correlate
182
+ * the response.
183
+ *
184
+ * @param call - The wallet method call containing method name and arguments
185
+ * @returns A Promise that resolves with the decrypted result from the wallet
186
+ *
187
+ * @throws Error if the secure channel has not been established or wallet is disconnected
188
+ */ async postMessage(call) {
189
+ if (this.disconnected) {
190
+ throw new Error('Wallet has been disconnected');
191
+ }
192
+ if (!this.port || !this.sharedKey) {
193
+ throw new Error('Secure channel not established');
194
+ }
195
+ const messageId = globalThis.crypto.randomUUID();
196
+ const message = {
197
+ type: call.type,
198
+ args: call.args,
199
+ messageId,
200
+ chainInfo: this.chainInfo,
201
+ appId: this.appId,
202
+ walletId: this.extensionId
203
+ };
204
+ const encrypted = await encrypt(this.sharedKey, jsonStringify(message));
205
+ this.port.postMessage(encrypted);
206
+ const { promise, resolve, reject } = promiseWithResolvers();
207
+ this.inFlight.set(messageId, {
208
+ promise,
209
+ resolve,
210
+ reject
211
+ });
212
+ this.startHeartbeat();
213
+ return promise;
214
+ }
215
+ /**
216
+ * Start the heartbeat probe loop while at least one request is in flight.
217
+ * Idempotent — calling while already running is a no-op.
218
+ *
219
+ * Heartbeat is opt-in via wire protocol: PINGs are unencrypted control messages
220
+ * (like DISCONNECT). Older wallets that do not understand PING simply drop it,
221
+ * which is safe — we only declare disconnect when **no** inbound traffic of any
222
+ * kind (PONG, encrypted response, DISCONNECT) arrives within the dead window.
223
+ * A wallet that is processing a slow request will reset the timer when it
224
+ * eventually responds, so this never causes false disconnects on legacy peers.
225
+ */ startHeartbeat() {
226
+ if (this.heartbeatTimer !== null || this.disconnected) {
227
+ return;
228
+ }
229
+ this.lastInboundAt = Date.now();
230
+ this.heartbeatTimer = setInterval(()=>this.heartbeatTick(), this.heartbeatIntervalMs);
231
+ }
232
+ maybeStopHeartbeat() {
233
+ if (this.inFlight.size === 0 && this.heartbeatTimer !== null) {
234
+ clearInterval(this.heartbeatTimer);
235
+ this.heartbeatTimer = null;
236
+ }
237
+ }
238
+ heartbeatTick() {
239
+ if (this.disconnected || this.inFlight.size === 0) {
240
+ this.maybeStopHeartbeat();
241
+ return;
242
+ }
243
+ const idleMs = Date.now() - this.lastInboundAt;
244
+ if (idleMs >= this.heartbeatDeadAfterMs) {
245
+ this.log.warn('Wallet channel unresponsive — declaring disconnect', {
246
+ idleMs,
247
+ inFlight: this.inFlight.size
248
+ });
249
+ this.handleDisconnect();
250
+ return;
251
+ }
252
+ try {
253
+ this.port.postMessage({
254
+ type: WalletMessageType.PING
255
+ });
256
+ } catch (err) {
257
+ this.log.warn('Failed to send heartbeat PING', {
258
+ err
259
+ });
260
+ }
261
+ }
262
+ /**
263
+ * Handles wallet disconnection.
264
+ * Rejects all pending requests and notifies registered callbacks.
265
+ * @internal
266
+ */ handleDisconnect() {
267
+ if (this.disconnected) {
268
+ return;
269
+ }
270
+ this.disconnected = true;
271
+ if (this.heartbeatTimer !== null) {
272
+ clearInterval(this.heartbeatTimer);
273
+ this.heartbeatTimer = null;
274
+ }
275
+ if (this.port) {
276
+ this.port.onmessage = null;
277
+ this.port.close();
278
+ }
279
+ const error = new Error('Wallet disconnected');
280
+ for (const { reject } of this.inFlight.values()){
281
+ reject(error);
282
+ }
283
+ this.inFlight.clear();
284
+ for (const callback of this.disconnectCallbacks){
285
+ try {
286
+ callback();
287
+ } catch {
288
+ // Ignore errors on disconnect callbacks
289
+ }
290
+ }
291
+ }
292
+ /**
293
+ * Registers a callback to be invoked when the wallet disconnects.
294
+ *
295
+ * @param callback - Function to call when wallet disconnects
296
+ * @returns A function to unregister the callback
297
+ *
298
+ * @example
299
+ * ```typescript
300
+ * const wallet = await ExtensionWallet.create(...);
301
+ * const unsubscribe = wallet.onDisconnect(() => {
302
+ * console.log('Wallet disconnected! Please reconnect.');
303
+ * // Clean up UI, prompt user to reconnect, etc.
304
+ * });
305
+ * // Later: unsubscribe(); to stop receiving notifications
306
+ * ```
307
+ */ onDisconnect(callback) {
308
+ this.disconnectCallbacks.push(callback);
309
+ return ()=>{
310
+ const index = this.disconnectCallbacks.indexOf(callback);
311
+ if (index !== -1) {
312
+ this.disconnectCallbacks.splice(index, 1);
313
+ }
314
+ };
315
+ }
316
+ /**
317
+ * Returns whether the wallet has been disconnected.
318
+ *
319
+ * @returns true if the wallet is no longer connected
320
+ */ isDisconnected() {
321
+ return this.disconnected;
322
+ }
323
+ /**
324
+ * Disconnects from the wallet and cleans up resources.
325
+ *
326
+ * This method notifies the wallet extension that the session is ending,
327
+ * allowing it to clean up its state. After calling this method, the wallet
328
+ * instance can no longer be used and any pending requests will be rejected.
329
+ *
330
+ * @example
331
+ * ```typescript
332
+ * const extensionWallet = ExtensionWallet.create(extensionId, port, sharedKey, chainInfo, 'my-app');
333
+ * // ... use wallet ...
334
+ * await extensionWallet.disconnect(); // Clean disconnect when done
335
+ * ```
336
+ */ // eslint-disable-next-line require-await -- async for interface compatibility
337
+ async disconnect() {
338
+ if (this.disconnected) {
339
+ return;
340
+ }
341
+ if (this.port) {
342
+ // Send unencrypted disconnect - control messages don't need encryption
343
+ this.port.postMessage({
344
+ type: WalletMessageType.DISCONNECT
345
+ });
346
+ }
347
+ this.handleDisconnect();
348
+ }
349
+ }
@@ -0,0 +1,3 @@
1
+ export { ExtensionWallet } from './extension_wallet.js';
2
+ export { ExtensionProvider, type DiscoveredWallet, type ConnectedWallet, type DiscoveryOptions, } from './extension_provider.js';
3
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9leHRlbnNpb24vcHJvdmlkZXIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ3hELE9BQU8sRUFDTCxpQkFBaUIsRUFDakIsS0FBSyxnQkFBZ0IsRUFDckIsS0FBSyxlQUFlLEVBQ3BCLEtBQUssZ0JBQWdCLEdBQ3RCLE1BQU0seUJBQXlCLENBQUMifQ==
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extension/provider/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC"}
@@ -1,3 +1,2 @@
1
1
  export { ExtensionWallet } from './extension_wallet.js';
2
2
  export { ExtensionProvider } from './extension_provider.js';
3
- export * from '../../crypto.js';
@@ -0,0 +1,122 @@
1
+ /**
2
+ * IframeConnectionHandler — wallet-side of the cross-origin iframe protocol.
3
+ *
4
+ * This mirrors {@link BackgroundConnectionHandler} from `@aztec/wallet-sdk/extension/handlers`
5
+ * but uses `window.postMessage` instead of browser.runtime messaging.
6
+ *
7
+ * Message flow (wallet receives):
8
+ * parent → DISCOVERY → show approval UI → send DISCOVERY_RESPONSE
9
+ * parent → KEY_EXCHANGE_REQUEST → ECDH → send KEY_EXCHANGE_RESPONSE
10
+ * parent → SECURE_MESSAGE → decrypt → Wallet → encrypt → SECURE_RESPONSE
11
+ * parent → DISCONNECT → terminate session
12
+ *
13
+ * The wallet announces itself by posting WALLET_READY as soon as the handler starts,
14
+ * so the dApp knows it can send a discovery request.
15
+ */
16
+ import type { ChainInfo } from '@aztec/aztec.js/account';
17
+ import type { Wallet } from '@aztec/aztec.js/wallet';
18
+ import { type WalletSdkLogger } from '../../types.js';
19
+ /**
20
+ * A pending discovery request from a dApp (before user approval).
21
+ */
22
+ export interface PendingSession {
23
+ /** Unique request identifier */
24
+ requestId: string;
25
+ /** Application identifier */
26
+ appId: string;
27
+ /** Origin URL of the requesting page */
28
+ origin: string;
29
+ /** Approval status */
30
+ status: 'pending' | 'approved';
31
+ }
32
+ /**
33
+ * An active session (after key exchange).
34
+ */
35
+ export interface ActiveSession {
36
+ /** Session identifier (same as the discovery requestId) */
37
+ sessionId: string;
38
+ /** AES-256-GCM shared key for this session */
39
+ sharedKey: CryptoKey;
40
+ /** Verification hash for emoji display */
41
+ verificationHash: string;
42
+ /** Origin URL of the connected dApp */
43
+ origin: string;
44
+ /** Application identifier */
45
+ appId: string;
46
+ }
47
+ /**
48
+ * Configuration for the iframe connection handler.
49
+ */
50
+ export interface IframeConnectionConfig {
51
+ /** Unique wallet identifier */
52
+ walletId: string;
53
+ /** Display name for the wallet */
54
+ walletName: string;
55
+ /** Wallet version string */
56
+ walletVersion: string;
57
+ /** Optional wallet icon URL */
58
+ walletIcon?: string;
59
+ /** Origins allowed to connect. If empty or undefined, all origins are allowed (dev mode). */
60
+ allowedOrigins?: string[];
61
+ /** Logger used for diagnostics. */
62
+ logger: WalletSdkLogger;
63
+ }
64
+ /**
65
+ * Event callbacks for the iframe connection handler.
66
+ */
67
+ export interface IframeConnectionCallbacks {
68
+ /** Called when a new discovery request arrives — wallet can show approval UI */
69
+ onPendingDiscovery?: (session: PendingSession) => void;
70
+ /** Called when a session is established (key exchange complete) */
71
+ onSessionEstablished?: (session: ActiveSession) => void;
72
+ /** Called when a session is terminated */
73
+ onSessionTerminated?: (sessionId: string) => void;
74
+ /** Called when a key exchange completes — show verificationHash as emojis to the user */
75
+ onVerificationHash?: (verificationHash: string) => void;
76
+ /**
77
+ * Resolves the Wallet instance to use for a given dApp and chain.
78
+ * Called when an encrypted message arrives and needs to be dispatched.
79
+ */
80
+ getWallet: (appId: string, chainInfo: ChainInfo) => Promise<Wallet>;
81
+ }
82
+ /**
83
+ * Handles the wallet side of the cross-origin iframe protocol.
84
+ *
85
+ * Manages the full lifecycle: discovery, ECDH key exchange, encrypted message
86
+ * dispatch to a {@link Wallet} instance, and session termination.
87
+ *
88
+ * @example
89
+ * ```typescript
90
+ * const handler = new IframeConnectionHandler(
91
+ * { walletId: 'my-wallet', walletName: 'My Wallet', walletVersion: '1.0.0', logger: console },
92
+ * {
93
+ * onPendingDiscovery: (session) => showApprovalUI(session),
94
+ * getWallet: (appId, chainInfo) => createWalletForApp(appId, chainInfo),
95
+ * },
96
+ * );
97
+ * handler.start();
98
+ * ```
99
+ */
100
+ export declare class IframeConnectionHandler {
101
+ private config;
102
+ private callbacks;
103
+ private pendingSessions;
104
+ private activeSessions;
105
+ private log;
106
+ constructor(config: IframeConnectionConfig, callbacks: IframeConnectionCallbacks);
107
+ start(): void;
108
+ stop(): void;
109
+ approveDiscovery(requestId: string): void;
110
+ rejectDiscovery(requestId: string): void;
111
+ terminateSession(sessionId: string): void;
112
+ getPendingSessions(): PendingSession[];
113
+ private handleMessage;
114
+ private handleMessageAsync;
115
+ private handlePing;
116
+ private handleDiscoveryRequest;
117
+ private handleKeyExchangeRequest;
118
+ private handleSecureMessage;
119
+ private postToParent;
120
+ private postToOrigin;
121
+ }
122
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaWZyYW1lX2Nvbm5lY3Rpb25faGFuZGxlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2lmcmFtZS9oYW5kbGVycy9pZnJhbWVfY29ubmVjdGlvbl9oYW5kbGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7OztHQWNHO0FBQ0gsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDekQsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFjckQsT0FBTyxFQUE4RCxLQUFLLGVBQWUsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBRWxIOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGNBQWM7SUFDN0IsZ0NBQWdDO0lBQ2hDLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsNkJBQTZCO0lBQzdCLEtBQUssRUFBRSxNQUFNLENBQUM7SUFDZCx3Q0FBd0M7SUFDeEMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmLHNCQUFzQjtJQUN0QixNQUFNLEVBQUUsU0FBUyxHQUFHLFVBQVUsQ0FBQztDQUNoQztBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGFBQWE7SUFDNUIsMkRBQTJEO0lBQzNELFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsOENBQThDO0lBQzlDLFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIsMENBQTBDO0lBQzFDLGdCQUFnQixFQUFFLE1BQU0sQ0FBQztJQUN6Qix1Q0FBdUM7SUFDdkMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmLDZCQUE2QjtJQUM3QixLQUFLLEVBQUUsTUFBTSxDQUFDO0NBQ2Y7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxzQkFBc0I7SUFDckMsK0JBQStCO0lBQy9CLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFDakIsa0NBQWtDO0lBQ2xDLFVBQVUsRUFBRSxNQUFNLENBQUM7SUFDbkIsNEJBQTRCO0lBQzVCLGFBQWEsRUFBRSxNQUFNLENBQUM7SUFDdEIsK0JBQStCO0lBQy9CLFVBQVUsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNwQiw2RkFBNkY7SUFDN0YsY0FBYyxDQUFDLEVBQUUsTUFBTSxFQUFFLENBQUM7SUFDMUIsbUNBQW1DO0lBQ25DLE1BQU0sRUFBRSxlQUFlLENBQUM7Q0FDekI7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyx5QkFBeUI7SUFDeEMsa0ZBQWdGO0lBQ2hGLGtCQUFrQixDQUFDLEVBQUUsQ0FBQyxPQUFPLEVBQUUsY0FBYyxLQUFLLElBQUksQ0FBQztJQUN2RCxtRUFBbUU7SUFDbkUsb0JBQW9CLENBQUMsRUFBRSxDQUFDLE9BQU8sRUFBRSxhQUFhLEtBQUssSUFBSSxDQUFDO0lBQ3hELDBDQUEwQztJQUMxQyxtQkFBbUIsQ0FBQyxFQUFFLENBQUMsU0FBUyxFQUFFLE1BQU0sS0FBSyxJQUFJLENBQUM7SUFDbEQsMkZBQXlGO0lBQ3pGLGtCQUFrQixDQUFDLEVBQUUsQ0FBQyxnQkFBZ0IsRUFBRSxNQUFNLEtBQUssSUFBSSxDQUFDO0lBQ3hEOzs7T0FHRztJQUNILFNBQVMsRUFBRSxDQUFDLEtBQUssRUFBRSxNQUFNLEVBQUUsU0FBUyxFQUFFLFNBQVMsS0FBSyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUM7Q0FDckU7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FpQkc7QUFDSCxxQkFBYSx1QkFBdUI7SUFNaEMsT0FBTyxDQUFDLE1BQU07SUFDZCxPQUFPLENBQUMsU0FBUztJQU5uQixPQUFPLENBQUMsZUFBZSxDQUFxQztJQUM1RCxPQUFPLENBQUMsY0FBYyxDQUFvQztJQUMxRCxPQUFPLENBQUMsR0FBRyxDQUFrQjtJQUU3QixZQUNVLE1BQU0sRUFBRSxzQkFBc0IsRUFDOUIsU0FBUyxFQUFFLHlCQUF5QixFQUc3QztJQUVELEtBQUssSUFBSSxJQUFJLENBSVo7SUFFRCxJQUFJLElBQUksSUFBSSxDQUVYO0lBRUQsZ0JBQWdCLENBQUMsU0FBUyxFQUFFLE1BQU0sR0FBRyxJQUFJLENBa0J4QztJQUVELGVBQWUsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLElBQUksQ0FFdkM7SUFFRCxnQkFBZ0IsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLElBQUksQ0FVeEM7SUFFRCxrQkFBa0IsSUFBSSxjQUFjLEVBQUUsQ0FFckM7SUFFRCxPQUFPLENBQUMsYUFBYSxDQUVuQjtZQUVZLGtCQUFrQjtJQStCaEMsT0FBTyxDQUFDLFVBQVU7SUFRbEIsT0FBTyxDQUFDLHNCQUFzQjtZQVNoQix3QkFBd0I7WUE2Q3hCLG1CQUFtQjtJQXFEakMsT0FBTyxDQUFDLFlBQVk7SUFNcEIsT0FBTyxDQUFDLFlBQVk7Q0FLckIifQ==
@@ -0,0 +1 @@
1
+ {"version":3,"file":"iframe_connection_handler.d.ts","sourceRoot":"","sources":["../../../src/iframe/handlers/iframe_connection_handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAcrD,OAAO,EAA8D,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAElH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,SAAS,CAAC;IACrB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,kFAAgF;IAChF,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IACvD,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IACxD,0CAA0C;IAC1C,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,2FAAyF;IACzF,kBAAkB,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD;;;OAGG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACrE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAuB;IAMhC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS;IANnB,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,GAAG,CAAkB;IAE7B,YACU,MAAM,EAAE,sBAAsB,EAC9B,SAAS,EAAE,yBAAyB,EAG7C;IAED,KAAK,IAAI,IAAI,CAIZ;IAED,IAAI,IAAI,IAAI,CAEX;IAED,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBxC;IAED,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvC;IAED,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAUxC;IAED,kBAAkB,IAAI,cAAc,EAAE,CAErC;IAED,OAAO,CAAC,aAAa,CAEnB;YAEY,kBAAkB;IA+BhC,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,sBAAsB;YAShB,wBAAwB;YA6CxB,mBAAmB;IAqDjC,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;CAKrB"}