@metamask-previews/phishing-controller 12.0.2-preview-367cb1da → 12.0.2-preview-cf09c0a

package/dist/PhishingController.d.mts

@@ -0,0 +1,304 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent, RestrictedControllerMessenger } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import { type PhishingDetectorResult } from "./types.mjs";
+export declare const PHISHING_CONFIG_BASE_URL = "https://phishing-detection.api.cx.metamask.io";
+export declare const METAMASK_STALELIST_FILE = "/v1/stalelist";
+export declare const METAMASK_HOTLIST_DIFF_FILE = "/v1/diffsSince";
+export declare const CLIENT_SIDE_DETECION_BASE_URL = "https://client-side-detection.api.cx.metamask.io";
+export declare const C2_DOMAIN_BLOCKLIST_ENDPOINT = "/v1/request-blocklist";
+export declare const C2_DOMAIN_BLOCKLIST_REFRESH_INTERVAL: number;
+export declare const HOTLIST_REFRESH_INTERVAL: number;
+export declare const STALELIST_REFRESH_INTERVAL: number;
+export declare const METAMASK_STALELIST_URL = "https://phishing-detection.api.cx.metamask.io/v1/stalelist";
+export declare const METAMASK_HOTLIST_DIFF_URL = "https://phishing-detection.api.cx.metamask.io/v1/diffsSince";
+export declare const C2_DOMAIN_BLOCKLIST_URL = "https://client-side-detection.api.cx.metamask.io/v1/request-blocklist";
+/**
+ * @type ListTypes
+ *
+ * Type outlining the types of lists provided by aggregating different source lists
+ */
+export type ListTypes = 'fuzzylist' | 'blocklist' | 'allowlist' | 'c2DomainBlocklist';
+/**
+ * @type EthPhishingResponse
+ *
+ * Configuration response from the eth-phishing-detect package
+ * consisting of approved and unapproved website origins
+ * @property blacklist - List of unapproved origins
+ * @property fuzzylist - List of fuzzy-matched unapproved origins
+ * @property tolerance - Fuzzy match tolerance level
+ * @property version - Version number of this configuration
+ * @property whitelist - List of approved origins
+ */
+export type EthPhishingResponse = {
+    blacklist: string[];
+    fuzzylist: string[];
+    tolerance: number;
+    version: number;
+    whitelist: string[];
+};
+/**
+ * @type C2DomainBlocklistResponse
+ *
+ * Response for blocklist update requests
+ * @property recentlyAdded - List of c2 domains recently added to the blocklist
+ * @property recentlyRemoved - List of c2 domains recently removed from the blocklist
+ * @property lastFetchedAt - Timestamp of the last fetch request
+ */
+export type C2DomainBlocklistResponse = {
+    recentlyAdded: string[];
+    recentlyRemoved: string[];
+    lastFetchedAt: string;
+};
+/**
+ * @type PhishingStalelist
+ *
+ * type defining expected type of the stalelist.json file.
+ * @property eth_phishing_detect_config - Stale list sourced from eth-phishing-detect's config.json.
+ * @property tolerance - Fuzzy match tolerance level
+ * @property lastUpdated - Timestamp of last update.
+ * @property version - Stalelist data structure iteration.
+ */
+export type PhishingStalelist = {
+    eth_phishing_detect_config: Record<ListTypes, string[]>;
+    tolerance: number;
+    version: number;
+    lastUpdated: number;
+};
+/**
+ * @type PhishingListState
+ *
+ * type defining the persisted list state. This is the persisted state that is updated frequently with `this.maybeUpdateState()`.
+ * @property allowlist - List of approved origins (legacy naming "whitelist")
+ * @property blocklist - List of unapproved origins (legacy naming "blacklist")
+ * @property c2DomainBlocklist - List of hashed hostnames that C2 requests are blocked against.
+ * @property fuzzylist - List of fuzzy-matched unapproved origins
+ * @property tolerance - Fuzzy match tolerance level
+ * @property lastUpdated - Timestamp of last update.
+ * @property version - Version of the phishing list state.
+ * @property name - Name of the list. Used for attribution.
+ */
+export type PhishingListState = {
+    allowlist: string[];
+    blocklist: string[];
+    c2DomainBlocklist: string[];
+    fuzzylist: string[];
+    tolerance: number;
+    version: number;
+    lastUpdated: number;
+    name: ListNames;
+};
+/**
+ * @type HotlistDiff
+ *
+ * type defining the expected type of the diffs in hotlist.json file.
+ * @property url - Url of the diff entry.
+ * @property timestamp - Timestamp at which the diff was identified.
+ * @property targetList - The list name where the diff was identified.
+ * @property isRemoval - Was the diff identified a removal type.
+ */
+export type HotlistDiff = {
+    url: string;
+    timestamp: number;
+    targetList: `${ListKeys}.${ListTypes}`;
+    isRemoval?: boolean;
+};
+export type DataResultWrapper<T> = {
+    data: T;
+};
+/**
+ * @type Hotlist
+ *
+ * Type defining expected hotlist.json file.
+ * @property url - Url of the diff entry.
+ * @property timestamp - Timestamp at which the diff was identified.
+ * @property targetList - The list name where the diff was identified.
+ * @property isRemoval - Was the diff identified a removal type.
+ */
+export type Hotlist = HotlistDiff[];
+/**
+ * Enum containing upstream data provider source list keys.
+ * These are the keys denoting lists consumed by the upstream data provider.
+ */
+export declare enum ListKeys {
+    EthPhishingDetectConfig = "eth_phishing_detect_config"
+}
+/**
+ * Enum containing downstream client attribution names.
+ */
+export declare enum ListNames {
+    MetaMask = "MetaMask"
+}
+/**
+ * Maps from list key sourced from upstream data
+ * provider to downstream client attribution name.
+ */
+export declare const phishingListKeyNameMap: {
+    eth_phishing_detect_config: ListNames;
+};
+declare const controllerName = "PhishingController";
+/**
+ * @type PhishingControllerState
+ *
+ * Phishing controller state
+ * @property phishing - eth-phishing-detect configuration
+ * @property whitelist - array of temporarily-approved origins
+ */
+export type PhishingControllerState = {
+    phishingLists: PhishingListState[];
+    whitelist: string[];
+    hotlistLastFetched: number;
+    stalelistLastFetched: number;
+    c2DomainBlocklistLastFetched: number;
+};
+/**
+ * @type PhishingControllerOptions
+ *
+ * Phishing controller options
+ * @property stalelistRefreshInterval - Polling interval used to fetch stale list.
+ * @property hotlistRefreshInterval - Polling interval used to fetch hotlist diff list.
+ * @property c2DomainBlocklistRefreshInterval - Polling interval used to fetch c2 domain blocklist.
+ */
+export type PhishingControllerOptions = {
+    stalelistRefreshInterval?: number;
+    hotlistRefreshInterval?: number;
+    c2DomainBlocklistRefreshInterval?: number;
+    messenger: PhishingControllerMessenger;
+    state?: Partial<PhishingControllerState>;
+};
+export type MaybeUpdateState = {
+    type: `${typeof controllerName}:maybeUpdateState`;
+    handler: PhishingController['maybeUpdateState'];
+};
+export type TestOrigin = {
+    type: `${typeof controllerName}:testOrigin`;
+    handler: PhishingController['test'];
+};
+export type PhishingControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PhishingControllerState>;
+export type PhishingControllerActions = PhishingControllerGetStateAction | MaybeUpdateState | TestOrigin;
+export type PhishingControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PhishingControllerState>;
+export type PhishingControllerEvents = PhishingControllerStateChangeEvent;
+export type PhishingControllerMessenger = RestrictedControllerMessenger<typeof controllerName, PhishingControllerActions, PhishingControllerEvents, never, never>;
+/**
+ * Controller that manages community-maintained lists of approved and unapproved website origins.
+ */
+export declare class PhishingController extends BaseController<typeof controllerName, PhishingControllerState, PhishingControllerMessenger> {
+    #private;
+    /**
+     * Construct a Phishing Controller.
+     *
+     * @param config - Initial options used to configure this controller.
+     * @param config.stalelistRefreshInterval - Polling interval used to fetch stale list.
+     * @param config.hotlistRefreshInterval - Polling interval used to fetch hotlist diff list.
+     * @param config.c2DomainBlocklistRefreshInterval - Polling interval used to fetch c2 domain blocklist.
+     * @param config.messenger - The controller restricted messenger.
+     * @param config.state - Initial state to set on this controller.
+     */
+    constructor({ stalelistRefreshInterval, hotlistRefreshInterval, c2DomainBlocklistRefreshInterval, messenger, state, }: PhishingControllerOptions);
+    /**
+     * Updates this.detector with an instance of PhishingDetector using the current state.
+     */
+    updatePhishingDetector(): void;
+    /**
+     * Set the interval at which the stale phishing list will be refetched.
+     * Fetching will only occur on the next call to test/bypass.
+     * For immediate update to the phishing list, call {@link updateStalelist} directly.
+     *
+     * @param interval - the new interval, in ms.
+     */
+    setStalelistRefreshInterval(interval: number): void;
+    /**
+     * Set the interval at which the hot list will be refetched.
+     * Fetching will only occur on the next call to test/bypass.
+     * For immediate update to the phishing list, call {@link updateHotlist} directly.
+     *
+     * @param interval - the new interval, in ms.
+     */
+    setHotlistRefreshInterval(interval: number): void;
+    /**
+     * Set the interval at which the C2 domain blocklist will be refetched.
+     * Fetching will only occur on the next call to test/bypass.
+     * For immediate update to the phishing list, call {@link updateHotlist} directly.
+     *
+     * @param interval - the new interval, in ms.
+     */
+    setC2DomainBlocklistRefreshInterval(interval: number): void;
+    /**
+     * Determine if an update to the stalelist configuration is needed.
+     *
+     * @returns Whether an update is needed
+     */
+    isStalelistOutOfDate(): boolean;
+    /**
+     * Determine if an update to the hotlist configuration is needed.
+     *
+     * @returns Whether an update is needed
+     */
+    isHotlistOutOfDate(): boolean;
+    /**
+     * Determine if an update to the C2 domain blocklist is needed.
+     *
+     * @returns Whether an update is needed
+     */
+    isC2DomainBlocklistOutOfDate(): boolean;
+    /**
+     * Conditionally update the phishing configuration.
+     *
+     * If the stalelist configuration is out of date, this function will call `updateStalelist`
+     * to update the configuration. This will automatically grab the hotlist,
+     * so it isn't necessary to continue on to download the hotlist and the c2 domain blocklist.
+     *
+     */
+    maybeUpdateState(): Promise<void>;
+    /**
+     * Determines if a given origin is unapproved.
+     *
+     * It is strongly recommended that you call {@link maybeUpdateState} before calling this,
+     * to check whether the phishing configuration is up-to-date. It will be updated if necessary
+     * by calling {@link updateStalelist} or {@link updateHotlist}.
+     *
+     * @param origin - Domain origin of a website.
+     * @returns Whether the origin is an unapproved origin.
+     */
+    test(origin: string): PhishingDetectorResult;
+    /**
+     * Checks if a request URL's domain is blocked against the request blocklist.
+     *
+     * This method is used to determine if a specific request URL is associated with a malicious
+     * command and control (C2) domain. The URL's hostname is hashed and checked against a configured
+     * blocklist of known malicious domains.
+     *
+     * @param origin - The full request URL to be checked.
+     * @returns An object indicating whether the URL's domain is blocked and relevant metadata.
+     */
+    isBlockedRequest(origin: string): PhishingDetectorResult;
+    /**
+     * Temporarily marks a given origin as approved.
+     *
+     * @param origin - The origin to mark as approved.
+     */
+    bypass(origin: string): void;
+    /**
+     * Update the C2 domain blocklist.
+     *
+     * If an update is in progress, no additional update will be made. Instead this will wait until
+     * the in-progress update has finished.
+     */
+    updateC2DomainBlocklist(): Promise<void>;
+    /**
+     * Update the hotlist.
+     *
+     * If an update is in progress, no additional update will be made. Instead this will wait until
+     * the in-progress update has finished.
+     */
+    updateHotlist(): Promise<void>;
+    /**
+     * Update the stalelist.
+     *
+     * If an update is in progress, no additional update will be made. Instead this will wait until
+     * the in-progress update has finished.
+     */
+    updateStalelist(): Promise<void>;
+}
+export default PhishingController;
+export type { PhishingDetectorResult };
+//# sourceMappingURL=PhishingController.d.mts.map

package/dist/PhishingController.d.mts.map

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