@metamask-previews/phishing-controller 17.4.0-preview-4f4c98e → 17.4.0-preview-eb263b0ee

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 (103) hide show
  1. package/CHANGELOG.md +0 -2
  2. package/dist/CacheManager.cjs +177 -0
  3. package/dist/CacheManager.cjs.map +1 -0
  4. package/dist/{CacheManager.d.ts → CacheManager.d.cts} +1 -1
  5. package/dist/CacheManager.d.cts.map +1 -0
  6. package/dist/CacheManager.d.mts +104 -0
  7. package/dist/CacheManager.d.mts.map +1 -0
  8. package/dist/{CacheManager.js → CacheManager.mjs} +2 -2
  9. package/dist/CacheManager.mjs.map +1 -0
  10. package/dist/PathTrie.cjs +169 -0
  11. package/dist/PathTrie.cjs.map +1 -0
  12. package/dist/{PathTrie.d.ts → PathTrie.d.cts} +1 -1
  13. package/dist/PathTrie.d.cts.map +1 -0
  14. package/dist/PathTrie.d.mts +46 -0
  15. package/dist/PathTrie.d.mts.map +1 -0
  16. package/dist/{PathTrie.js → PathTrie.mjs} +2 -2
  17. package/dist/PathTrie.mjs.map +1 -0
  18. package/dist/PhishingController-method-action-types.cjs +7 -0
  19. package/dist/PhishingController-method-action-types.cjs.map +1 -0
  20. package/dist/{PhishingController-method-action-types.d.ts → PhishingController-method-action-types.d.cts} +2 -2
  21. package/dist/PhishingController-method-action-types.d.cts.map +1 -0
  22. package/dist/PhishingController-method-action-types.d.mts +123 -0
  23. package/dist/PhishingController-method-action-types.d.mts.map +1 -0
  24. package/dist/{PhishingController-method-action-types.js → PhishingController-method-action-types.mjs} +1 -1
  25. package/dist/PhishingController-method-action-types.mjs.map +1 -0
  26. package/dist/PhishingController.cjs +1222 -0
  27. package/dist/PhishingController.cjs.map +1 -0
  28. package/dist/{PhishingController.d.ts → PhishingController.d.cts} +10 -10
  29. package/dist/PhishingController.d.cts.map +1 -0
  30. package/dist/PhishingController.d.mts +425 -0
  31. package/dist/PhishingController.d.mts.map +1 -0
  32. package/dist/{PhishingController.js → PhishingController.mjs} +12 -11
  33. package/dist/PhishingController.mjs.map +1 -0
  34. package/dist/PhishingDetector.cjs +277 -0
  35. package/dist/PhishingDetector.cjs.map +1 -0
  36. package/dist/{PhishingDetector.d.ts → PhishingDetector.d.cts} +4 -4
  37. package/dist/PhishingDetector.d.cts.map +1 -0
  38. package/dist/PhishingDetector.d.mts +73 -0
  39. package/dist/PhishingDetector.d.mts.map +1 -0
  40. package/dist/{PhishingDetector.js → PhishingDetector.mjs} +15 -21
  41. package/dist/PhishingDetector.mjs.map +1 -0
  42. package/dist/address-poisoning.cjs +71 -0
  43. package/dist/address-poisoning.cjs.map +1 -0
  44. package/dist/{address-poisoning.d.ts → address-poisoning.d.cts} +2 -2
  45. package/dist/address-poisoning.d.cts.map +1 -0
  46. package/dist/address-poisoning.d.mts +3 -0
  47. package/dist/address-poisoning.d.mts.map +1 -0
  48. package/dist/{address-poisoning.js → address-poisoning.mjs} +2 -2
  49. package/dist/address-poisoning.mjs.map +1 -0
  50. package/dist/index.cjs +36 -0
  51. package/dist/index.cjs.map +1 -0
  52. package/dist/{index.d.ts → index.d.cts} +12 -12
  53. package/dist/index.d.cts.map +1 -0
  54. package/dist/index.d.mts +12 -0
  55. package/dist/index.d.mts.map +1 -0
  56. package/dist/index.mjs +7 -0
  57. package/dist/index.mjs.map +1 -0
  58. package/dist/tests/utils.cjs +102 -0
  59. package/dist/tests/utils.cjs.map +1 -0
  60. package/dist/tests/{utils.d.ts → utils.d.cts} +3 -3
  61. package/dist/tests/utils.d.cts.map +1 -0
  62. package/dist/tests/utils.d.mts +70 -0
  63. package/dist/tests/utils.d.mts.map +1 -0
  64. package/dist/tests/{utils.js → utils.mjs} +2 -2
  65. package/dist/tests/utils.mjs.map +1 -0
  66. package/dist/types.cjs +267 -0
  67. package/dist/types.cjs.map +1 -0
  68. package/dist/{types.d.ts → types.d.cts} +62 -62
  69. package/dist/types.d.cts.map +1 -0
  70. package/dist/types.d.mts +338 -0
  71. package/dist/types.d.mts.map +1 -0
  72. package/dist/{types.js → types.mjs} +1 -1
  73. package/dist/types.mjs.map +1 -0
  74. package/dist/utils.cjs +522 -0
  75. package/dist/utils.cjs.map +1 -0
  76. package/dist/{utils.d.ts → utils.d.cts} +72 -74
  77. package/dist/utils.d.cts.map +1 -0
  78. package/dist/utils.d.mts +302 -0
  79. package/dist/utils.d.mts.map +1 -0
  80. package/dist/{utils.js → utils.mjs} +16 -16
  81. package/dist/utils.mjs.map +1 -0
  82. package/package.json +16 -12
  83. package/dist/CacheManager.d.ts.map +0 -1
  84. package/dist/CacheManager.js.map +0 -1
  85. package/dist/PathTrie.d.ts.map +0 -1
  86. package/dist/PathTrie.js.map +0 -1
  87. package/dist/PhishingController-method-action-types.d.ts.map +0 -1
  88. package/dist/PhishingController-method-action-types.js.map +0 -1
  89. package/dist/PhishingController.d.ts.map +0 -1
  90. package/dist/PhishingController.js.map +0 -1
  91. package/dist/PhishingDetector.d.ts.map +0 -1
  92. package/dist/PhishingDetector.js.map +0 -1
  93. package/dist/address-poisoning.d.ts.map +0 -1
  94. package/dist/address-poisoning.js.map +0 -1
  95. package/dist/index.d.ts.map +0 -1
  96. package/dist/index.js +0 -7
  97. package/dist/index.js.map +0 -1
  98. package/dist/tests/utils.d.ts.map +0 -1
  99. package/dist/tests/utils.js.map +0 -1
  100. package/dist/types.d.ts.map +0 -1
  101. package/dist/types.js.map +0 -1
  102. package/dist/utils.d.ts.map +0 -1
  103. package/dist/utils.js.map +0 -1
@@ -0,0 +1,425 @@
1
+ import type { AddressBookControllerGetStateAction, AddressBookControllerStateChangeEvent } from "@metamask/address-book-controller";
2
+ import { BaseController } from "@metamask/base-controller";
3
+ import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
4
+ import type { Messenger } from "@metamask/messenger";
5
+ import type { TransactionControllerGetStateAction, TransactionControllerStateChangeEvent } from "@metamask/transaction-controller";
6
+ import type { CacheEntry } from "./CacheManager.mjs";
7
+ import type { PathTrie } from "./PathTrie.mjs";
8
+ import type { PhishingControllerMaybeUpdateStateAction, PhishingControllerMethodActions, PhishingControllerTestOriginAction } from "./PhishingController-method-action-types.mjs";
9
+ import type { PhishingDetectorResult, PhishingDetectionScanResult, TokenScanCacheData, BulkTokenScanResponse, BulkTokenScanRequest, AddressScanCacheData, AddressScanResult, SimilarAddressMatch, ApprovalsResponse } from "./types.mjs";
10
+ export declare const PHISHING_CONFIG_BASE_URL = "https://phishing-detection.api.cx.metamask.io";
11
+ export declare const METAMASK_STALELIST_FILE = "/v1/stalelist";
12
+ export declare const METAMASK_HOTLIST_DIFF_FILE = "/v2/diffsSince";
13
+ export declare const CLIENT_SIDE_DETECION_BASE_URL = "https://client-side-detection.api.cx.metamask.io";
14
+ export declare const C2_DOMAIN_BLOCKLIST_ENDPOINT = "/v1/request-blocklist";
15
+ export declare const PHISHING_DETECTION_BASE_URL = "https://dapp-scanning.api.cx.metamask.io";
16
+ export declare const PHISHING_DETECTION_SCAN_ENDPOINT = "v2/scan";
17
+ export declare const PHISHING_DETECTION_BULK_SCAN_ENDPOINT = "bulk-scan";
18
+ export declare const SECURITY_ALERTS_BASE_URL = "https://security-alerts.api.cx.metamask.io";
19
+ export declare const TOKEN_BULK_SCANNING_ENDPOINT = "/token/scan-bulk";
20
+ export declare const ADDRESS_SCAN_ENDPOINT = "/address/evm/scan";
21
+ export declare const APPROVALS_ENDPOINT = "/address/evm/approvals";
22
+ export declare const DEFAULT_URL_SCAN_CACHE_TTL: number;
23
+ export declare const DEFAULT_URL_SCAN_CACHE_MAX_SIZE = 250;
24
+ export declare const DEFAULT_TOKEN_SCAN_CACHE_TTL: number;
25
+ export declare const DEFAULT_TOKEN_SCAN_CACHE_MAX_SIZE = 1000;
26
+ export declare const DEFAULT_ADDRESS_SCAN_CACHE_TTL: number;
27
+ export declare const DEFAULT_ADDRESS_SCAN_CACHE_MAX_SIZE = 1000;
28
+ export declare const C2_DOMAIN_BLOCKLIST_REFRESH_INTERVAL: number;
29
+ export declare const HOTLIST_REFRESH_INTERVAL: number;
30
+ export declare const STALELIST_REFRESH_INTERVAL: number;
31
+ export declare const METAMASK_STALELIST_URL = "https://phishing-detection.api.cx.metamask.io/v1/stalelist";
32
+ export declare const METAMASK_HOTLIST_DIFF_URL = "https://phishing-detection.api.cx.metamask.io/v2/diffsSince";
33
+ export declare const C2_DOMAIN_BLOCKLIST_URL = "https://client-side-detection.api.cx.metamask.io/v1/request-blocklist";
34
+ /**
35
+ * @type ListTypes
36
+ *
37
+ * Type outlining the types of lists provided by aggregating different source lists
38
+ */
39
+ export type ListTypes = 'fuzzylist' | 'blocklist' | 'blocklistPaths' | 'allowlist' | 'c2DomainBlocklist';
40
+ /**
41
+ * @type EthPhishingResponse
42
+ *
43
+ * Configuration response from the eth-phishing-detect package
44
+ * consisting of approved and unapproved website origins
45
+ *
46
+ * @property blacklist - List of unapproved origins
47
+ * @property fuzzylist - List of fuzzy-matched unapproved origins
48
+ * @property tolerance - Fuzzy match tolerance level
49
+ * @property version - Version number of this configuration
50
+ * @property whitelist - List of approved origins
51
+ */
52
+ export type EthPhishingResponse = {
53
+ blacklist: string[];
54
+ fuzzylist: string[];
55
+ tolerance: number;
56
+ version: number;
57
+ whitelist: string[];
58
+ };
59
+ /**
60
+ * @type C2DomainBlocklistResponse
61
+ *
62
+ * Response for blocklist update requests
63
+ *
64
+ * @property recentlyAdded - List of c2 domains recently added to the blocklist
65
+ * @property recentlyRemoved - List of c2 domains recently removed from the blocklist
66
+ * @property lastFetchedAt - Timestamp of the last fetch request
67
+ */
68
+ export type C2DomainBlocklistResponse = {
69
+ recentlyAdded: string[];
70
+ recentlyRemoved: string[];
71
+ lastFetchedAt: string;
72
+ };
73
+ /**
74
+ * PhishingStalelist defines the expected type of the stalelist from the API.
75
+ *
76
+ * allowlist - List of approved origins.
77
+ * blocklist - List of unapproved origins (hostname-only entries).
78
+ * blocklistPaths - Trie of unapproved origins with paths (hostname + path entries).
79
+ * fuzzylist - List of fuzzy-matched unapproved origins.
80
+ * tolerance - Fuzzy match tolerance level
81
+ * lastUpdated - Timestamp of last update.
82
+ * version - Stalelist data structure iteration.
83
+ */
84
+ export type PhishingStalelist = {
85
+ allowlist: string[];
86
+ blocklist: string[];
87
+ blocklistPaths: string[];
88
+ fuzzylist: string[];
89
+ tolerance: number;
90
+ version: number;
91
+ lastUpdated: number;
92
+ };
93
+ /**
94
+ * @type PhishingListState
95
+ *
96
+ * type defining the persisted list state. This is the persisted state that is updated frequently with `this.maybeUpdateState()`.
97
+ *
98
+ * @property allowlist - List of approved origins (legacy naming "whitelist")
99
+ * @property blocklist - List of unapproved origins (legacy naming "blacklist")
100
+ * @property blocklistPaths - Trie of unapproved origins with paths (hostname + path, no query params).
101
+ * @property c2DomainBlocklist - List of hashed hostnames that C2 requests are blocked against.
102
+ * @property fuzzylist - List of fuzzy-matched unapproved origins
103
+ * @property tolerance - Fuzzy match tolerance level
104
+ * @property lastUpdated - Timestamp of last update.
105
+ * @property version - Version of the phishing list state.
106
+ * @property name - Name of the list. Used for attribution.
107
+ */
108
+ export type PhishingListState = {
109
+ allowlist: string[];
110
+ blocklist: string[];
111
+ blocklistPaths: PathTrie;
112
+ c2DomainBlocklist: string[];
113
+ fuzzylist: string[];
114
+ tolerance: number;
115
+ version: number;
116
+ lastUpdated: number;
117
+ name: ListNames;
118
+ };
119
+ /**
120
+ * @type HotlistDiff
121
+ *
122
+ * type defining the expected type of the diffs in hotlist.json file.
123
+ *
124
+ * @property url - Url of the diff entry.
125
+ * @property timestamp - Timestamp at which the diff was identified.
126
+ * @property targetList - The list name where the diff was identified.
127
+ * @property isRemoval - Was the diff identified a removal type.
128
+ */
129
+ export type HotlistDiff = {
130
+ url: string;
131
+ timestamp: number;
132
+ targetList: `${ListKeys}.${ListTypes}`;
133
+ isRemoval?: boolean;
134
+ };
135
+ export type DataResultWrapper<T> = {
136
+ data: T;
137
+ };
138
+ /**
139
+ * @type Hotlist
140
+ *
141
+ * Type defining expected hotlist.json file.
142
+ *
143
+ * @property url - Url of the diff entry.
144
+ * @property timestamp - Timestamp at which the diff was identified.
145
+ * @property targetList - The list name where the diff was identified.
146
+ * @property isRemoval - Was the diff identified a removal type.
147
+ */
148
+ export type Hotlist = HotlistDiff[];
149
+ /**
150
+ * Enum containing upstream data provider source list keys.
151
+ * These are the keys denoting lists consumed by the upstream data provider.
152
+ */
153
+ export declare enum ListKeys {
154
+ EthPhishingDetectConfig = "eth_phishing_detect_config"
155
+ }
156
+ /**
157
+ * Enum containing downstream client attribution names.
158
+ */
159
+ export declare enum ListNames {
160
+ MetaMask = "MetaMask"
161
+ }
162
+ /**
163
+ * Maps from list key sourced from upstream data
164
+ * provider to downstream client attribution name.
165
+ */
166
+ export declare const phishingListKeyNameMap: {
167
+ eth_phishing_detect_config: ListNames;
168
+ };
169
+ declare const controllerName = "PhishingController";
170
+ /**
171
+ * @type PhishingControllerState
172
+ *
173
+ * Phishing controller state
174
+ * phishingLists - array of phishing lists
175
+ * whitelist - origins that bypass the phishing detector
176
+ * whitelistPaths - origins with paths that bypass the phishing detector
177
+ * hotlistLastFetched - timestamp of the last hotlist fetch
178
+ * stalelistLastFetched - timestamp of the last stalelist fetch
179
+ * c2DomainBlocklistLastFetched - timestamp of the last c2 domain blocklist fetch
180
+ * urlScanCache - cache of URL scan results
181
+ * tokenScanCache - cache of token scan results
182
+ * addressScanCache - cache of address scan results
183
+ */
184
+ export type PhishingControllerState = {
185
+ phishingLists: PhishingListState[];
186
+ whitelist: string[];
187
+ whitelistPaths: PathTrie;
188
+ hotlistLastFetched: number;
189
+ stalelistLastFetched: number;
190
+ c2DomainBlocklistLastFetched: number;
191
+ urlScanCache: Record<string, CacheEntry<PhishingDetectionScanResult>>;
192
+ tokenScanCache: Record<string, CacheEntry<TokenScanCacheData>>;
193
+ addressScanCache: Record<string, CacheEntry<AddressScanCacheData>>;
194
+ };
195
+ /**
196
+ * PhishingControllerOptions
197
+ *
198
+ * Phishing controller options
199
+ * stalelistRefreshInterval - Polling interval used to fetch stale list.
200
+ * hotlistRefreshInterval - Polling interval used to fetch hotlist diff list.
201
+ * c2DomainBlocklistRefreshInterval - Polling interval used to fetch c2 domain blocklist.
202
+ * urlScanCacheTTL - Time to live in seconds for cached scan results.
203
+ * urlScanCacheMaxSize - Maximum number of entries in the scan cache.
204
+ * tokenScanCacheTTL - Time to live in seconds for cached token scan results.
205
+ * tokenScanCacheMaxSize - Maximum number of entries in the token scan cache.
206
+ * addressScanCacheTTL - Time to live in seconds for cached address scan results.
207
+ * addressScanCacheMaxSize - Maximum number of entries in the address scan cache.
208
+ */
209
+ export type PhishingControllerOptions = {
210
+ stalelistRefreshInterval?: number;
211
+ hotlistRefreshInterval?: number;
212
+ c2DomainBlocklistRefreshInterval?: number;
213
+ urlScanCacheTTL?: number;
214
+ urlScanCacheMaxSize?: number;
215
+ tokenScanCacheTTL?: number;
216
+ tokenScanCacheMaxSize?: number;
217
+ addressScanCacheTTL?: number;
218
+ addressScanCacheMaxSize?: number;
219
+ messenger: PhishingControllerMessenger;
220
+ state?: Partial<PhishingControllerState>;
221
+ };
222
+ /**
223
+ * @deprecated Use `PhishingControllerTestOriginAction` instead.
224
+ */
225
+ export type TestOrigin = PhishingControllerTestOriginAction;
226
+ /**
227
+ * @deprecated Use `PhishingControllerMaybeUpdateStateAction` instead.
228
+ */
229
+ export type MaybeUpdateState = PhishingControllerMaybeUpdateStateAction;
230
+ export type PhishingControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PhishingControllerState>;
231
+ export type PhishingControllerActions = PhishingControllerGetStateAction | PhishingControllerMethodActions;
232
+ export type PhishingControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PhishingControllerState>;
233
+ export type PhishingControllerEvents = PhishingControllerStateChangeEvent;
234
+ /**
235
+ * The external actions available to the PhishingController.
236
+ */
237
+ type AllowedActions = AddressBookControllerGetStateAction | TransactionControllerGetStateAction;
238
+ /**
239
+ * The external events available to the PhishingController.
240
+ */
241
+ export type AllowedEvents = AddressBookControllerStateChangeEvent | TransactionControllerStateChangeEvent;
242
+ export type PhishingControllerMessenger = Messenger<typeof controllerName, PhishingControllerActions | AllowedActions, PhishingControllerEvents | AllowedEvents>;
243
+ /**
244
+ * BulkPhishingDetectionScanResponse
245
+ *
246
+ * Response for bulk phishing detection scan requests
247
+ * results - Record of domain names and their corresponding phishing detection scan results
248
+ *
249
+ * errors - Record of domain names and their corresponding errors
250
+ */
251
+ export type BulkPhishingDetectionScanResponse = {
252
+ results: Record<string, PhishingDetectionScanResult>;
253
+ errors: Record<string, string[]>;
254
+ };
255
+ /**
256
+ * Controller that manages community-maintained lists of approved and unapproved website origins.
257
+ */
258
+ export declare class PhishingController extends BaseController<typeof controllerName, PhishingControllerState, PhishingControllerMessenger> {
259
+ #private;
260
+ /**
261
+ * Construct a Phishing Controller.
262
+ *
263
+ * @param config - Initial options used to configure this controller.
264
+ * @param config.stalelistRefreshInterval - Polling interval used to fetch stale list.
265
+ * @param config.hotlistRefreshInterval - Polling interval used to fetch hotlist diff list.
266
+ * @param config.c2DomainBlocklistRefreshInterval - Polling interval used to fetch c2 domain blocklist.
267
+ * @param config.urlScanCacheTTL - Time to live in seconds for cached scan results.
268
+ * @param config.urlScanCacheMaxSize - Maximum number of entries in the scan cache.
269
+ * @param config.tokenScanCacheTTL - Time to live in seconds for cached token scan results.
270
+ * @param config.tokenScanCacheMaxSize - Maximum number of entries in the token scan cache.
271
+ * @param config.addressScanCacheTTL - Time to live in seconds for cached address scan results.
272
+ * @param config.addressScanCacheMaxSize - Maximum number of entries in the address scan cache.
273
+ * @param config.messenger - The controller restricted messenger.
274
+ * @param config.state - Initial state to set on this controller.
275
+ */
276
+ constructor({ stalelistRefreshInterval, hotlistRefreshInterval, c2DomainBlocklistRefreshInterval, urlScanCacheTTL, urlScanCacheMaxSize, tokenScanCacheTTL, tokenScanCacheMaxSize, addressScanCacheTTL, addressScanCacheMaxSize, messenger, state, }: PhishingControllerOptions);
277
+ /**
278
+ * Updates this.detector with an instance of PhishingDetector using the current state.
279
+ */
280
+ updatePhishingDetector(): void;
281
+ /**
282
+ * Finds known recipient addresses that look like an address poisoning match.
283
+ *
284
+ * @param candidate - The recipient address being checked.
285
+ * @returns Similar known recipient matches sorted by score.
286
+ */
287
+ checkAddressPoisoning(candidate: string): SimilarAddressMatch[];
288
+ /**
289
+ * Determine if an update to the stalelist configuration is needed.
290
+ *
291
+ * @returns Whether an update is needed
292
+ */
293
+ isStalelistOutOfDate(): boolean;
294
+ /**
295
+ * Determine if an update to the hotlist configuration is needed.
296
+ *
297
+ * @returns Whether an update is needed
298
+ */
299
+ isHotlistOutOfDate(): boolean;
300
+ /**
301
+ * Determine if an update to the C2 domain blocklist is needed.
302
+ *
303
+ * @returns Whether an update is needed
304
+ */
305
+ isC2DomainBlocklistOutOfDate(): boolean;
306
+ /**
307
+ * Conditionally update the phishing configuration.
308
+ *
309
+ * If the stalelist configuration is out of date, this function will call `updateStalelist`
310
+ * to update the configuration. This will automatically grab the hotlist,
311
+ * so it isn't necessary to continue on to download the hotlist and the c2 domain blocklist.
312
+ *
313
+ */
314
+ maybeUpdateState(): Promise<void>;
315
+ /**
316
+ * Determines if a given origin is unapproved.
317
+ *
318
+ * It is strongly recommended that you call {@link maybeUpdateState} before calling this,
319
+ * to check whether the phishing configuration is up-to-date. It will be updated if necessary
320
+ * by calling {@link updateStalelist} or {@link updateHotlist}.
321
+ *
322
+ * @param origin - Domain origin of a website.
323
+ * @returns Whether the origin is an unapproved origin.
324
+ */
325
+ testOrigin(origin: string): PhishingDetectorResult;
326
+ /**
327
+ * Determines if a given origin is unapproved.
328
+ *
329
+ * It is strongly recommended that you call {@link maybeUpdateState} before calling this,
330
+ * to check whether the phishing configuration is up-to-date. It will be updated if necessary
331
+ * by calling {@link updateStalelist} or {@link updateHotlist}.
332
+ *
333
+ * @param origin - Domain origin of a website.
334
+ * @returns Whether the origin is an unapproved origin.
335
+ * @deprecated Use {@link testOrigin} instead. This method is exposed for backward compatibility and will be removed in a future release.
336
+ */
337
+ test: (origin: string) => PhishingDetectorResult;
338
+ /**
339
+ * Checks if a request URL's domain is blocked against the request blocklist.
340
+ *
341
+ * This method is used to determine if a specific request URL is associated with a malicious
342
+ * command and control (C2) domain. The URL's hostname is hashed and checked against a configured
343
+ * blocklist of known malicious domains.
344
+ *
345
+ * @param origin - The full request URL to be checked.
346
+ * @returns An object indicating whether the URL's domain is blocked and relevant metadata.
347
+ */
348
+ isBlockedRequest(origin: string): PhishingDetectorResult;
349
+ /**
350
+ * Temporarily marks a given origin as approved.
351
+ *
352
+ * @param origin - The origin to mark as approved.
353
+ */
354
+ bypass(origin: string): void;
355
+ /**
356
+ * Update the C2 domain blocklist.
357
+ *
358
+ * If an update is in progress, no additional update will be made. Instead this will wait until
359
+ * the in-progress update has finished.
360
+ */
361
+ updateC2DomainBlocklist(): Promise<void>;
362
+ /**
363
+ * Update the hotlist.
364
+ *
365
+ * If an update is in progress, no additional update will be made. Instead this will wait until
366
+ * the in-progress update has finished.
367
+ */
368
+ updateHotlist(): Promise<void>;
369
+ /**
370
+ * Update the stalelist.
371
+ *
372
+ * If an update is in progress, no additional update will be made. Instead this will wait until
373
+ * the in-progress update has finished.
374
+ */
375
+ updateStalelist(): Promise<void>;
376
+ /**
377
+ * Scan a URL for phishing. For most hosts only the hostname is sent to the API; for known
378
+ * shared gateways the pathname is included (see `PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS`).
379
+ * Only supports web URLs (`http:` / `https:`).
380
+ *
381
+ * @param url - The URL to scan.
382
+ * @returns The phishing detection scan result.
383
+ */
384
+ scanUrl(url: string): Promise<PhishingDetectionScanResult>;
385
+ /**
386
+ * Scan multiple URLs for phishing in bulk. It will only scan the hostnames of the URLs.
387
+ * It also only supports web URLs.
388
+ *
389
+ * @param urls - The URLs to scan.
390
+ * @returns A mapping of URLs to their phishing detection scan results and errors.
391
+ */
392
+ bulkScanUrls(urls: string[]): Promise<BulkPhishingDetectionScanResponse>;
393
+ /**
394
+ * Scan an address for security alerts.
395
+ *
396
+ * @param chainId - The chain ID in hex format (e.g., '0x1' for Ethereum).
397
+ * @param address - The address to scan.
398
+ * @returns The address scan result.
399
+ */
400
+ scanAddress(chainId: string, address: string): Promise<AddressScanResult>;
401
+ /**
402
+ * Get token approvals for an EVM address with security enrichments.
403
+ *
404
+ * @param chainId - The chain ID in hex format (e.g., '0x1' for Ethereum).
405
+ * @param address - The address to get approvals for.
406
+ * @returns The approvals response containing approval data, or empty approvals on error.
407
+ */
408
+ getApprovals: (chainId: string, address: string) => Promise<ApprovalsResponse>;
409
+ /**
410
+ * Scan multiple tokens for malicious activity in bulk.
411
+ *
412
+ * @param request - The bulk scan request containing chainId and tokens.
413
+ * @param request.chainId - The chain identifier. Accepts a hex chain ID for
414
+ * EVM chains (e.g. `'0x1'` for Ethereum) or a chain name for non-EVM chains
415
+ * (e.g. `'solana'`).
416
+ * @param request.tokens - Array of token addresses to scan.
417
+ * @returns A mapping of token addresses to their scan results. For EVM chains,
418
+ * addresses are lowercased; for non-EVM chains, original casing is preserved.
419
+ * Tokens that fail to scan are omitted.
420
+ */
421
+ bulkScanTokens(request: BulkTokenScanRequest): Promise<BulkTokenScanResponse>;
422
+ }
423
+ export default PhishingController;
424
+ export type { PhishingDetectorResult };
425
+ //# sourceMappingURL=PhishingController.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PhishingController.d.mts","sourceRoot":"","sources":["../src/PhishingController.ts"],"names":[],"mappings":"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"}
@@ -10,16 +10,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
12
  var _PhishingController_instances, _PhishingController_detector, _PhishingController_stalelistRefreshInterval, _PhishingController_hotlistRefreshInterval, _PhishingController_c2DomainBlocklistRefreshInterval, _PhishingController_urlScanCache, _PhishingController_tokenScanCache, _PhishingController_addressScanCache, _PhishingController_knownRecipients, _PhishingController_transactionRecipients, _PhishingController_transactionRecipientsByTransactionId, _PhishingController_transactionRecipientCounts, _PhishingController_addressBookRecipients, _PhishingController_inProgressHotlistUpdate, _PhishingController_inProgressStalelistUpdate, _PhishingController_isProgressC2DomainBlocklistUpdate, _PhishingController_transactionControllerStateChangeHandler, _PhishingController_addressBookControllerStateChangeHandler, _PhishingController_subscribeToAddressBookControllerStateChange, _PhishingController_subscribeToTransactionControllerStateChange, _PhishingController_isTransactionPatch, _PhishingController_isSimulationDataPatch, _PhishingController_onTransactionControllerStateChange, _PhishingController_onAddressBookControllerStateChange, _PhishingController_getTokensFromTransaction, _PhishingController_scanTokensByChain, _PhishingController_hydrateKnownRecipients, _PhishingController_hydrateKnownRecipientsFromTransactionState, _PhishingController_hydrateKnownRecipientsFromAddressBookState, _PhishingController_setKnownRecipientsFromTransactionState, _PhishingController_updateKnownRecipientsFromTransactionPatches, _PhishingController_getTransactionFromPatchValue, _PhishingController_updateTransactionRecipients, _PhishingController_addTransactionRecipients, _PhishingController_removeTransactionRecipients, _PhishingController_setKnownRecipientsFromAddressBookState, _PhishingController_rebuildKnownRecipients, _PhishingController_getAddressBookRecipients, _PhishingController_getRecipientAddressesFromTransaction, _PhishingController_normalizeAddress, _PhishingController_fetchTokenScanBulkResults, _PhishingController_processBatch, _PhishingController_updateStalelist, _PhishingController_updateHotlist, _PhishingController_updateC2DomainBlocklist, _PhishingController_queryConfig;
13
- import { BaseController } from '@metamask/base-controller';
14
- import { isValidHexAddress, safelyExecute, safelyExecuteWithTimeout, } from '@metamask/controller-utils';
15
- import { getEffectiveRecipient, TransactionStatus, } from '@metamask/transaction-controller';
16
- import { toASCII } from 'punycode/punycode.js';
17
- import { findSimilarAddresses } from './address-poisoning.js';
18
- import { CacheManager } from './CacheManager.js';
19
- import { convertListToTrie, insertToTrie, matchedPathPrefix, } from './PathTrie.js';
20
- import { PhishingDetector } from './PhishingDetector.js';
21
- import { PhishingDetectorResultType, RecommendedAction, AddressScanResultType, } from './types.js';
22
- import { applyDiffs, fetchTimeNow, getHostnameFromUrl, roundToNearestMinute, getHostnameFromWebUrl, getPhishingDetectionScanUrlParam, buildCacheKey, splitCacheHits, resolveChainName, getPathnameFromUrl, getAddressScanSupportedChain, isApprovalSupportedChain, isTokenScanSupportedChain, } from './utils.js';
13
+ import { BaseController } from "@metamask/base-controller";
14
+ import { isValidHexAddress, safelyExecute, safelyExecuteWithTimeout } from "@metamask/controller-utils";
15
+ import { getEffectiveRecipient, TransactionStatus } from "@metamask/transaction-controller";
16
+ import $punycodepunycodejs from "punycode/punycode.js";
17
+ const { toASCII } = $punycodepunycodejs;
18
+ import { findSimilarAddresses } from "./address-poisoning.mjs";
19
+ import { CacheManager } from "./CacheManager.mjs";
20
+ import { convertListToTrie, insertToTrie, matchedPathPrefix } from "./PathTrie.mjs";
21
+ import { PhishingDetector } from "./PhishingDetector.mjs";
22
+ import { PhishingDetectorResultType, RecommendedAction, AddressScanResultType } from "./types.mjs";
23
+ import { applyDiffs, fetchTimeNow, getHostnameFromUrl, roundToNearestMinute, getHostnameFromWebUrl, getPhishingDetectionScanUrlParam, buildCacheKey, splitCacheHits, resolveChainName, getPathnameFromUrl, getAddressScanSupportedChain, isApprovalSupportedChain, isTokenScanSupportedChain } from "./utils.mjs";
23
24
  export const PHISHING_CONFIG_BASE_URL = 'https://phishing-detection.api.cx.metamask.io';
24
25
  export const METAMASK_STALELIST_FILE = '/v1/stalelist';
25
26
  export const METAMASK_HOTLIST_DIFF_FILE = '/v2/diffsSince';
@@ -1215,4 +1216,4 @@ async function _PhishingController_updateC2DomainBlocklist() {
1215
1216
  }
1216
1217
  };
1217
1218
  export default PhishingController;
1218
- //# sourceMappingURL=PhishingController.js.map
1219
+ //# sourceMappingURL=PhishingController.mjs.map