@metamask-previews/phishing-controller 18.0.0-preview-cfb927be0 → 18.0.0-preview-e8a256c39

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `extractSignatureAddresses` utility, plus `ExtractedSignatureAddresses` and `ExtractSignatureAddressesOptions` types, to collect the `address`-typed values from an EIP-712 typed-data message for real-time address scanning ([#10170](https://github.com/MetaMask/core/pull/10170))
+  - Walks the `types` schema from `primaryType`, matching fields by declared type (`address`/`address[]`, including nested structs and arrays) rather than by field name, so custom and unknown message shapes are covered without per-protocol handling.
+  - Normalizes non-canonical `address` encodings (variable-length hex and decimal strings) into canonical lower-case 20-byte hex by taking the leading 20 bytes of the signer-compatible big-endian encoding, and de-duplicates case-insensitively.
+  - Excludes the zero address, a caller-provided `exclude` list (e.g. the signer), and caller-provided top-level `excludeFields`.
+  - Bounds work with a distinct-address cap (default 10, caller-overridable via `maxAddresses`, hard ceiling 50), a traversal depth limit, and a node budget, reporting `overflow` when the message could not be fully walked. Exports `DEFAULT_MAX_SIGNATURE_ADDRESSES` and `MAX_SIGNATURE_ADDRESSES_CEILING`.
+  - Returns the field name each address was found under so callers can attribute alerts.
+
 ## [18.0.0]
 
 ### Changed

package/dist/index.d.ts

@@ -8,5 +8,7 @@ export { TokenScanResultType } from './types.js';
 export { PhishingDetectorResultType, RecommendedAction, AddressScanResultType, ApprovalResultType, ApprovalFeatureType, } from './types.js';
 export type { CacheEntry } from './CacheManager.js';
 export { PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS, getPhishingDetectionScanUrlParam, isAddressScanSupportedChainId, isPhishingDetectionPathBasedHostname, } from './utils.js';
+export { extractSignatureAddresses, DEFAULT_MAX_SIGNATURE_ADDRESSES, MAX_SIGNATURE_ADDRESSES_CEILING, } from './signature-address-extraction.js';
+export type { ExtractedSignatureAddresses, ExtractSignatureAddressesOptions, } from './signature-address-extraction.js';
 export type { PhishingControllerMaybeUpdateStateAction, PhishingControllerTestOriginAction, PhishingControllerIsBlockedRequestAction, PhishingControllerBypassAction, PhishingControllerScanUrlAction, PhishingControllerBulkScanUrlsAction, PhishingControllerBulkScanTokensAction, PhishingControllerScanAddressAction, PhishingControllerGetApprovalsAction, PhishingControllerCheckAddressPoisoningAction, } from './PhishingController-method-action-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,EACd,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,aAAa,EACb,QAAQ,EACR,OAAO,EACP,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,wCAAwC,EACxC,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,EAC9B,+BAA+B,EAC/B,oCAAoC,EACpC,sCAAsC,EACtC,mCAAmC,EACnC,oCAAoC,EACpC,6CAA6C,GAC9C,MAAM,6CAA6C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,EACd,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,aAAa,EACb,QAAQ,EACR,OAAO,EACP,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EACV,wCAAwC,EACxC,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,EAC9B,+BAA+B,EAC/B,oCAAoC,EACpC,sCAAsC,EACtC,mCAAmC,EACnC,oCAAoC,EACpC,6CAA6C,GAC9C,MAAM,6CAA6C,CAAC"}

package/dist/index.js

@@ -4,4 +4,5 @@ export { PhishingDetector } from './PhishingDetector.js';
 export { TokenScanResultType } from './types.js';
 export { PhishingDetectorResultType, RecommendedAction, AddressScanResultType, ApprovalResultType, ApprovalFeatureType, } from './types.js';
 export { PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS, getPhishingDetectionScanUrlParam, isAddressScanSupportedChainId, isPhishingDetectionPathBasedHostname, } from './utils.js';
+export { extractSignatureAddresses, DEFAULT_MAX_SIGNATURE_ADDRESSES, MAX_SIGNATURE_ADDRESSES_CEILING, } from './signature-address-extraction.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAQ9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAgBzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,YAAY,CAAC","sourcesContent":["export * from './PhishingController.js';\nexport { findSimilarAddresses } from './address-poisoning.js';\nexport type {\n  LegacyPhishingDetectorList,\n  PhishingDetectorList,\n  FuzzyTolerance,\n  PhishingDetectorOptions,\n  PhishingDetectorConfiguration,\n} from './PhishingDetector.js';\nexport { PhishingDetector } from './PhishingDetector.js';\nexport type {\n  PhishingDetectionScanResult,\n  AddressScanResult,\n  BulkTokenScanResponse,\n  SimilarAddressMatch,\n  SimilarityOptions,\n  ApprovalsResponse,\n  Approval,\n  Allowance,\n  ApprovalAsset,\n  Exposure,\n  Spender,\n  ApprovalFeature,\n} from './types.js';\nexport type { TokenScanCacheData } from './types.js';\nexport { TokenScanResultType } from './types.js';\nexport {\n  PhishingDetectorResultType,\n  RecommendedAction,\n  AddressScanResultType,\n  ApprovalResultType,\n  ApprovalFeatureType,\n} from './types.js';\nexport type { CacheEntry } from './CacheManager.js';\nexport {\n  PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS,\n  getPhishingDetectionScanUrlParam,\n  isAddressScanSupportedChainId,\n  isPhishingDetectionPathBasedHostname,\n} from './utils.js';\n\nexport type {\n  PhishingControllerMaybeUpdateStateAction,\n  PhishingControllerTestOriginAction,\n  PhishingControllerIsBlockedRequestAction,\n  PhishingControllerBypassAction,\n  PhishingControllerScanUrlAction,\n  PhishingControllerBulkScanUrlsAction,\n  PhishingControllerBulkScanTokensAction,\n  PhishingControllerScanAddressAction,\n  PhishingControllerGetApprovalsAction,\n  PhishingControllerCheckAddressPoisoningAction,\n} from './PhishingController-method-action-types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAQ9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAgBzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,mCAAmC,CAAC","sourcesContent":["export * from './PhishingController.js';\nexport { findSimilarAddresses } from './address-poisoning.js';\nexport type {\n  LegacyPhishingDetectorList,\n  PhishingDetectorList,\n  FuzzyTolerance,\n  PhishingDetectorOptions,\n  PhishingDetectorConfiguration,\n} from './PhishingDetector.js';\nexport { PhishingDetector } from './PhishingDetector.js';\nexport type {\n  PhishingDetectionScanResult,\n  AddressScanResult,\n  BulkTokenScanResponse,\n  SimilarAddressMatch,\n  SimilarityOptions,\n  ApprovalsResponse,\n  Approval,\n  Allowance,\n  ApprovalAsset,\n  Exposure,\n  Spender,\n  ApprovalFeature,\n} from './types.js';\nexport type { TokenScanCacheData } from './types.js';\nexport { TokenScanResultType } from './types.js';\nexport {\n  PhishingDetectorResultType,\n  RecommendedAction,\n  AddressScanResultType,\n  ApprovalResultType,\n  ApprovalFeatureType,\n} from './types.js';\nexport type { CacheEntry } from './CacheManager.js';\nexport {\n  PHISHING_DETECTION_PATH_BASED_ROOT_DOMAINS,\n  getPhishingDetectionScanUrlParam,\n  isAddressScanSupportedChainId,\n  isPhishingDetectionPathBasedHostname,\n} from './utils.js';\nexport {\n  extractSignatureAddresses,\n  DEFAULT_MAX_SIGNATURE_ADDRESSES,\n  MAX_SIGNATURE_ADDRESSES_CEILING,\n} from './signature-address-extraction.js';\nexport type {\n  ExtractedSignatureAddresses,\n  ExtractSignatureAddressesOptions,\n} from './signature-address-extraction.js';\n\nexport type {\n  PhishingControllerMaybeUpdateStateAction,\n  PhishingControllerTestOriginAction,\n  PhishingControllerIsBlockedRequestAction,\n  PhishingControllerBypassAction,\n  PhishingControllerScanUrlAction,\n  PhishingControllerBulkScanUrlsAction,\n  PhishingControllerBulkScanTokensAction,\n  PhishingControllerScanAddressAction,\n  PhishingControllerGetApprovalsAction,\n  PhishingControllerCheckAddressPoisoningAction,\n} from './PhishingController-method-action-types.js';\n"]}

package/dist/signature-address-extraction.d.ts

@@ -0,0 +1,86 @@
+export declare const DEFAULT_MAX_SIGNATURE_ADDRESSES = 10;
+export declare const MAX_SIGNATURE_ADDRESSES_CEILING = 50;
+/**
+ * The result of walking an EIP-712 typed-data message for `address`-typed
+ * values.
+ */
+export type ExtractedSignatureAddresses = {
+    /**
+     * Distinct canonical addresses to scan, capped at the effective `maxAddresses`.
+     */
+    addresses: string[];
+    /**
+     * Canonical address -> the field name it was first found under, so a caller
+     * can name the specific field in an alert.
+     */
+    fields: Record<string, string>;
+    /**
+     * True when the message could not be fully walked: more distinct addresses
+     * than the cap, traversal stopped by the depth or work budget, or an
+     * address-bearing type could not be walked (array type with a non-array
+     * value, or struct type with a non-object value). Some addresses may be
+     * unscanned, so the caller should surface a caution.
+     */
+    overflow: boolean;
+    /**
+     * Effective address cap after applying the default and ceiling.
+     */
+    maxAddresses: number;
+};
+/**
+ * Options for {@link extractSignatureAddresses}.
+ */
+export type ExtractSignatureAddressesOptions = {
+    /**
+     * Addresses to skip (e.g. the signer). The zero address is always excluded.
+     */
+    exclude?: string[];
+    /**
+     * Top-level field names to skip, used to avoid a duplicate scan/alert for a
+     * field already handled elsewhere (e.g. permit `spender`). Names must match
+     * the declared EIP-712 field exactly. Only applied to the primary type
+     * (depth 0), not nested structs.
+     */
+    excludeFields?: string[];
+    /**
+     * Distinct-address cap for this call. Defaults to
+     * {@link DEFAULT_MAX_SIGNATURE_ADDRESSES}. Clamped to
+     * {@link MAX_SIGNATURE_ADDRESSES_CEILING}. Invalid values use the default.
+     */
+    maxAddresses?: number;
+};
+/**
+ * Collect every `address`-typed value in an EIP-712 message.
+ *
+ * Walks the `types` schema from `primaryType` and returns the value of each
+ * field declared as `address` or `address[]`, recursing into nested structs and
+ * arrays. Matching on the declared type rather than the field name means custom
+ * and unknown message shapes are covered without per-protocol handling.
+ *
+ * Type dispatch matches the signer: a custom struct in `types` is walked first
+ * (even if its name looks like `address` or `address[]`), then `address`, then
+ * types whose name ends in `]` as arrays.
+ *
+ * `domain` is not traversed; its `verifyingContract` is expected to be scanned
+ * separately by the caller.
+ *
+ * @param typedData - Parsed EIP-712 payload (`types`, `primaryType`, `message`).
+ * @param options - Optional configuration.
+ * @param options.exclude - Addresses to skip (e.g. the signer). The zero
+ * address is always excluded.
+ * @param options.excludeFields - Top-level field names to skip. Names must
+ * match the declared EIP-712 field exactly. Only applied to the primary type
+ * (depth 0), not nested structs.
+ * @param options.maxAddresses - Distinct-address cap. Defaults to
+ * {@link DEFAULT_MAX_SIGNATURE_ADDRESSES} and is clamped to
+ * {@link MAX_SIGNATURE_ADDRESSES_CEILING}.
+ * @returns Up to `maxAddresses` distinct canonical addresses, the field each
+ * was found under, whether the message could not be fully walked, and the
+ * effective cap.
+ */
+export declare function extractSignatureAddresses(typedData: {
+    types?: unknown;
+    primaryType?: unknown;
+    message?: unknown;
+} | null | undefined, options?: ExtractSignatureAddressesOptions): ExtractedSignatureAddresses;
+//# sourceMappingURL=signature-address-extraction.d.ts.map

package/dist/signature-address-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-address-extraction.d.ts","sourceRoot":"","sources":["../src/signature-address-extraction.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAYlD;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC;;OAEG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC7C;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA+DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EACL;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,IAAI,GACJ,SAAS,EACb,OAAO,GAAE,gCAAqC,GAC7C,2BAA2B,CAoN7B"}

package/dist/signature-address-extraction.js

@@ -0,0 +1,267 @@
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+// Same as `@metamask/utils` `isStrictHexString` (`/^0x[0-9a-f]+$/iu`): the
+// signer accepts a `0X` prefix, so we must too.
+const HEX_STRING_REGEX = /^0x[0-9a-f]+$/iu;
+const DECIMAL_STRING_REGEX = /^[0-9]+$/u;
+export const DEFAULT_MAX_SIGNATURE_ADDRESSES = 10;
+export const MAX_SIGNATURE_ADDRESSES_CEILING = 50;
+// Limit recursion depth when walking nested types.
+const MAX_TRAVERSAL_DEPTH = 12;
+// Limit total nodes walked so a large or highly-repetitive payload cannot stall
+// traversal, independent of how many distinct addresses are found.
+const MAX_TRAVERSAL_NODES = 5000;
+function resolveMaxAddresses(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return DEFAULT_MAX_SIGNATURE_ADDRESSES;
+    }
+    const floored = Math.floor(value);
+    if (floored < 1) {
+        return DEFAULT_MAX_SIGNATURE_ADDRESSES;
+    }
+    return Math.min(floored, MAX_SIGNATURE_ADDRESSES_CEILING);
+}
+/**
+ * Encode a non-negative integer as big-endian hex (even length) and take the
+ * leading 20 bytes.
+ *
+ * @param numeric - A non-negative integer.
+ * @returns Canonical lower-case 20-byte address.
+ */
+function leadingTwentyBytesFromInteger(numeric) {
+    let digits = numeric.toString(16);
+    if (digits.length % 2 === 1) {
+        digits = `0${digits}`;
+    }
+    return `0x${digits.slice(0, 40).padStart(40, '0')}`;
+}
+/**
+ * Reduce an `address`-typed value to canonical 20-byte hex.
+ *
+ * The signer accepts more than canonical hex for an `address` field (hex of any
+ * length, or a decimal string) and takes the high / leading 20 bytes of the
+ * big-endian encoding (`reallyStrangeAddressToBytes(value).subarray(0, 20)` /
+ * `hexToBytes(value).subarray(0, 20)` in `@metamask/eth-sig-util`), so matching
+ * only `0x` + 40 hex would miss an address encoded in another form.
+ *
+ * @param value - The raw field value from the message.
+ * @returns Canonical lower-case address, or undefined if not address-like.
+ */
+function normalizeAddress(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (HEX_STRING_REGEX.test(trimmed)) {
+            let digits = trimmed.slice(2);
+            if (digits.length % 2 === 1) {
+                digits = `0${digits}`;
+            }
+            return `0x${digits.slice(0, 40).padStart(40, '0').toLowerCase()}`;
+        }
+        if (DECIMAL_STRING_REGEX.test(trimmed)) {
+            return leadingTwentyBytesFromInteger(BigInt(trimmed));
+        }
+        return undefined;
+    }
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+        return leadingTwentyBytesFromInteger(BigInt(value));
+    }
+    return undefined;
+}
+/**
+ * Collect every `address`-typed value in an EIP-712 message.
+ *
+ * Walks the `types` schema from `primaryType` and returns the value of each
+ * field declared as `address` or `address[]`, recursing into nested structs and
+ * arrays. Matching on the declared type rather than the field name means custom
+ * and unknown message shapes are covered without per-protocol handling.
+ *
+ * Type dispatch matches the signer: a custom struct in `types` is walked first
+ * (even if its name looks like `address` or `address[]`), then `address`, then
+ * types whose name ends in `]` as arrays.
+ *
+ * `domain` is not traversed; its `verifyingContract` is expected to be scanned
+ * separately by the caller.
+ *
+ * @param typedData - Parsed EIP-712 payload (`types`, `primaryType`, `message`).
+ * @param options - Optional configuration.
+ * @param options.exclude - Addresses to skip (e.g. the signer). The zero
+ * address is always excluded.
+ * @param options.excludeFields - Top-level field names to skip. Names must
+ * match the declared EIP-712 field exactly. Only applied to the primary type
+ * (depth 0), not nested structs.
+ * @param options.maxAddresses - Distinct-address cap. Defaults to
+ * {@link DEFAULT_MAX_SIGNATURE_ADDRESSES} and is clamped to
+ * {@link MAX_SIGNATURE_ADDRESSES_CEILING}.
+ * @returns Up to `maxAddresses` distinct canonical addresses, the field each
+ * was found under, whether the message could not be fully walked, and the
+ * effective cap.
+ */
+export function extractSignatureAddresses(typedData, options = {}) {
+    const maxAddresses = resolveMaxAddresses(options.maxAddresses);
+    const types = typedData?.types;
+    const primaryType = typedData?.primaryType;
+    const { message } = typedData ?? {};
+    if (!types ||
+        typeof types !== 'object' ||
+        !primaryType ||
+        !Array.isArray(types[primaryType]) ||
+        !message ||
+        typeof message !== 'object') {
+        return { addresses: [], fields: {}, overflow: false, maxAddresses };
+    }
+    // Narrowed alias so the hoisted helpers below see a defined `types`.
+    const schema = types;
+    // ZERO_ADDRESS is already canonical (lower-case, 20 bytes), so it is added
+    // directly rather than round-tripped through `normalizeAddress`.
+    const excluded = new Set([ZERO_ADDRESS]);
+    for (const address of options.exclude ?? []) {
+        const normalized = normalizeAddress(address);
+        if (normalized) {
+            excluded.add(normalized);
+        }
+    }
+    const excludedFields = new Set(options.excludeFields ?? []);
+    // Canonical address -> the field name it was first found under.
+    const found = new Map();
+    // Set when the message could not be fully walked, so some addresses may be
+    // unscanned: the address cap, the depth limit, the work budget, or an
+    // address-bearing type whose value could not be walked.
+    let overflow = false;
+    // Total nodes walked, bounded by MAX_TRAVERSAL_NODES.
+    let visited = 0;
+    // Stopping the walk (depth or work budget) leaves later fields unscanned, so
+    // it is treated as overflow the same way the distinct-address cap is.
+    const truncated = (depth) => {
+        if (depth > MAX_TRAVERSAL_DEPTH || visited >= MAX_TRAVERSAL_NODES) {
+            overflow = true;
+            return true;
+        }
+        return false;
+    };
+    /**
+     * Whether `type` can contain `address` values: the `address` primitive, an
+     * array of an address-bearing type, or a custom struct that contains one.
+     *
+     * @param type - The declared EIP-712 type.
+     * @param seen - Types already inspected, to break recursive structs.
+     * @returns True when walking this type can yield addresses.
+     */
+    function isAddressBearing(type, seen = new Set()) {
+        if (seen.has(type)) {
+            return false;
+        }
+        seen.add(type);
+        const structFields = schema[type];
+        if (Array.isArray(structFields)) {
+            return structFields.some((field) => Boolean(field) &&
+                typeof field.type === 'string' &&
+                isAddressBearing(field.type, seen));
+        }
+        if (type === 'address') {
+            return true;
+        }
+        if (type.endsWith(']')) {
+            return isAddressBearing(type.slice(0, type.lastIndexOf('[')), seen);
+        }
+        return false;
+    }
+    /**
+     * Record a candidate address value under a field name, applying exclusions,
+     * de-duplication, and the distinct-address cap.
+     *
+     * @param field - The field name the value was found under.
+     * @param value - The raw field value to normalize and collect.
+     */
+    function collect(field, value) {
+        const address = normalizeAddress(value);
+        if (!address || excluded.has(address) || found.has(address)) {
+            return;
+        }
+        if (found.size >= maxAddresses) {
+            overflow = true;
+            return;
+        }
+        found.set(address, field);
+    }
+    /**
+     * Walk the fields of a struct type, recursing per field.
+     *
+     * @param structName - The name of the struct type in the schema.
+     * @param value - The message object corresponding to the struct.
+     * @param depth - The current traversal depth.
+     */
+    function visitStruct(structName, value, depth) {
+        if (truncated(depth)) {
+            return;
+        }
+        const structFields = schema[structName];
+        if (!Array.isArray(structFields) || !value || typeof value !== 'object') {
+            if (Array.isArray(structFields) && isAddressBearing(structName)) {
+                overflow = true;
+            }
+            return;
+        }
+        for (const field of structFields) {
+            if (truncated(depth)) {
+                return;
+            }
+            if (!field ||
+                typeof field.name !== 'string' ||
+                typeof field.type !== 'string' ||
+                // Field exclusions only apply to the primary type (depth 0), matching
+                // the top-level field a dedicated caller already covers. Names must
+                // match the declared EIP-712 field exactly.
+                (depth === 0 && excludedFields.has(field.name))) {
+                continue;
+            }
+            visitField(field.name, field.type, value[field.name], depth);
+        }
+    }
+    /**
+     * Walk a single field value, handling custom structs, `address`, and arrays.
+     *
+     * Precedence matches `@metamask/eth-sig-util` `encodeField`: a type present
+     * in the schema is a struct first; otherwise `address`; otherwise a name
+     * ending in `]` is treated as an array (`type.slice(0, lastIndexOf('['))`).
+     *
+     * @param field - The field name.
+     * @param type - The declared EIP-712 type of the field.
+     * @param value - The field value from the message.
+     * @param depth - The current traversal depth.
+     */
+    function visitField(field, type, value, depth) {
+        visited += 1;
+        if (truncated(depth)) {
+            return;
+        }
+        if (Array.isArray(schema[type])) {
+            visitStruct(type, value, depth + 1);
+            return;
+        }
+        if (type === 'address') {
+            collect(field, value);
+            return;
+        }
+        if (type.endsWith(']')) {
+            if (Array.isArray(value)) {
+                const innerType = type.slice(0, type.lastIndexOf('['));
+                for (const item of value) {
+                    if (truncated(depth)) {
+                        return;
+                    }
+                    visitField(field, innerType, item, depth + 1);
+                }
+            }
+            else if (isAddressBearing(type)) {
+                overflow = true;
+            }
+        }
+    }
+    visitStruct(primaryType, message, 0);
+    return {
+        addresses: Array.from(found.keys()),
+        fields: Object.fromEntries(found),
+        overflow,
+        maxAddresses,
+    };
+}
+//# sourceMappingURL=signature-address-extraction.js.map

package/dist/signature-address-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-address-extraction.js","sourceRoot":"","sources":["../src/signature-address-extraction.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,4CAA4C,CAAC;AAElE,2EAA2E;AAC3E,gDAAgD;AAChD,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAC3C,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAEzC,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAElD,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAElD,mDAAmD;AACnD,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B,gFAAgF;AAChF,mEAAmE;AACnE,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAwDjC,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,+BAA+B,CAAC;IACzC,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,+BAA+B,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,+BAA+B,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,6BAA6B,CAAC,OAAe;IACpD,IAAI,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnC,IAAI,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACxB,CAAC;YACD,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACpE,CAAC;QACD,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,OAAO,6BAA6B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACvE,OAAO,6BAA6B,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAGa,EACb,OAAO,GAAqC,EAAE;IAE9C,MAAM,YAAY,GAAG,mBAAmB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,SAAS,EAAE,KAAgC,CAAC;IAC1D,MAAM,WAAW,GAAG,SAAS,EAAE,WAAiC,CAAC;IACjE,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,IAAI,EAAE,CAAC;IAEpC,IACE,CAAC,KAAK;QACN,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,WAAW;QACZ,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC,OAAO;QACR,OAAO,OAAO,KAAK,QAAQ,EAC3B,CAAC;QACD,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtE,CAAC;IAED,qEAAqE;IACrE,MAAM,MAAM,GAAG,KAAK,CAAC;IAErB,2EAA2E;IAC3E,iEAAiE;IACjE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IACjD,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,UAAU,EAAE,CAAC;YACf,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IAE5D,gEAAgE;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAExC,2EAA2E;IAC3E,sEAAsE;IACtE,wDAAwD;IACxD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,sDAAsD;IACtD,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,SAAS,GAAG,CAAC,KAAa,EAAW,EAAE;QAC3C,IAAI,KAAK,GAAG,mBAAmB,IAAI,OAAO,IAAI,mBAAmB,EAAE,CAAC;YAClE,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF;;;;;;;OAOG;IACH,SAAS,gBAAgB,CACvB,IAAY,EACZ,IAAI,GAAgB,IAAI,GAAG,EAAE;QAE7B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEf,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAChC,OAAO,YAAY,CAAC,IAAI,CACtB,CAAC,KAAK,EAAE,EAAE,CACR,OAAO,CAAC,KAAK,CAAC;gBACd,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,gBAAgB,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CACrC,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACtE,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACH,SAAS,OAAO,CAAC,KAAa,EAAE,KAAc;QAC5C,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5D,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;YAC/B,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO;QACT,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,SAAS,WAAW,CAClB,UAAkB,EAClB,KAAc,EACd,KAAa;QAEb,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxE,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChE,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;YACD,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO;YACT,CAAC;YACD,IACE,CAAC,KAAK;gBACN,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,sEAAsE;gBACtE,oEAAoE;gBACpE,4CAA4C;gBAC5C,CAAC,KAAK,KAAK,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAC/C,CAAC;gBACD,SAAS;YACX,CAAC;YACD,UAAU,CACR,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,IAAI,EACT,KAAiC,CAAC,KAAK,CAAC,IAAI,CAAC,EAC9C,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,UAAU,CACjB,KAAa,EACb,IAAY,EACZ,KAAc,EACd,KAAa;QAEb,OAAO,IAAI,CAAC,CAAC;QACb,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAChC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;wBACrB,OAAO;oBACT,CAAC;oBACD,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;iBAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClC,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAErC,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;QACjC,QAAQ;QACR,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';\n\n// Same as `@metamask/utils` `isStrictHexString` (`/^0x[0-9a-f]+$/iu`): the\n// signer accepts a `0X` prefix, so we must too.\nconst HEX_STRING_REGEX = /^0x[0-9a-f]+$/iu;\nconst DECIMAL_STRING_REGEX = /^[0-9]+$/u;\n\nexport const DEFAULT_MAX_SIGNATURE_ADDRESSES = 10;\n\nexport const MAX_SIGNATURE_ADDRESSES_CEILING = 50;\n\n// Limit recursion depth when walking nested types.\nconst MAX_TRAVERSAL_DEPTH = 12;\n\n// Limit total nodes walked so a large or highly-repetitive payload cannot stall\n// traversal, independent of how many distinct addresses are found.\nconst MAX_TRAVERSAL_NODES = 5000;\n\ntype Eip712Field = { name: string; type: string };\ntype Eip712Types = Record<string, Eip712Field[]>;\n\n/**\n * The result of walking an EIP-712 typed-data message for `address`-typed\n * values.\n */\nexport type ExtractedSignatureAddresses = {\n  /**\n   * Distinct canonical addresses to scan, capped at the effective `maxAddresses`.\n   */\n  addresses: string[];\n  /**\n   * Canonical address -> the field name it was first found under, so a caller\n   * can name the specific field in an alert.\n   */\n  fields: Record<string, string>;\n  /**\n   * True when the message could not be fully walked: more distinct addresses\n   * than the cap, traversal stopped by the depth or work budget, or an\n   * address-bearing type could not be walked (array type with a non-array\n   * value, or struct type with a non-object value). Some addresses may be\n   * unscanned, so the caller should surface a caution.\n   */\n  overflow: boolean;\n  /**\n   * Effective address cap after applying the default and ceiling.\n   */\n  maxAddresses: number;\n};\n\n/**\n * Options for {@link extractSignatureAddresses}.\n */\nexport type ExtractSignatureAddressesOptions = {\n  /**\n   * Addresses to skip (e.g. the signer). The zero address is always excluded.\n   */\n  exclude?: string[];\n  /**\n   * Top-level field names to skip, used to avoid a duplicate scan/alert for a\n   * field already handled elsewhere (e.g. permit `spender`). Names must match\n   * the declared EIP-712 field exactly. Only applied to the primary type\n   * (depth 0), not nested structs.\n   */\n  excludeFields?: string[];\n  /**\n   * Distinct-address cap for this call. Defaults to\n   * {@link DEFAULT_MAX_SIGNATURE_ADDRESSES}. Clamped to\n   * {@link MAX_SIGNATURE_ADDRESSES_CEILING}. Invalid values use the default.\n   */\n  maxAddresses?: number;\n};\n\nfunction resolveMaxAddresses(value: unknown): number {\n  if (typeof value !== 'number' || !Number.isFinite(value)) {\n    return DEFAULT_MAX_SIGNATURE_ADDRESSES;\n  }\n  const floored = Math.floor(value);\n  if (floored < 1) {\n    return DEFAULT_MAX_SIGNATURE_ADDRESSES;\n  }\n  return Math.min(floored, MAX_SIGNATURE_ADDRESSES_CEILING);\n}\n\n/**\n * Encode a non-negative integer as big-endian hex (even length) and take the\n * leading 20 bytes.\n *\n * @param numeric - A non-negative integer.\n * @returns Canonical lower-case 20-byte address.\n */\nfunction leadingTwentyBytesFromInteger(numeric: bigint): string {\n  let digits = numeric.toString(16);\n  if (digits.length % 2 === 1) {\n    digits = `0${digits}`;\n  }\n  return `0x${digits.slice(0, 40).padStart(40, '0')}`;\n}\n\n/**\n * Reduce an `address`-typed value to canonical 20-byte hex.\n *\n * The signer accepts more than canonical hex for an `address` field (hex of any\n * length, or a decimal string) and takes the high / leading 20 bytes of the\n * big-endian encoding (`reallyStrangeAddressToBytes(value).subarray(0, 20)` /\n * `hexToBytes(value).subarray(0, 20)` in `@metamask/eth-sig-util`), so matching\n * only `0x` + 40 hex would miss an address encoded in another form.\n *\n * @param value - The raw field value from the message.\n * @returns Canonical lower-case address, or undefined if not address-like.\n */\nfunction normalizeAddress(value: unknown): string | undefined {\n  if (typeof value === 'string') {\n    const trimmed = value.trim();\n    if (HEX_STRING_REGEX.test(trimmed)) {\n      let digits = trimmed.slice(2);\n      if (digits.length % 2 === 1) {\n        digits = `0${digits}`;\n      }\n      return `0x${digits.slice(0, 40).padStart(40, '0').toLowerCase()}`;\n    }\n    if (DECIMAL_STRING_REGEX.test(trimmed)) {\n      return leadingTwentyBytesFromInteger(BigInt(trimmed));\n    }\n    return undefined;\n  }\n\n  if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {\n    return leadingTwentyBytesFromInteger(BigInt(value));\n  }\n\n  return undefined;\n}\n\n/**\n * Collect every `address`-typed value in an EIP-712 message.\n *\n * Walks the `types` schema from `primaryType` and returns the value of each\n * field declared as `address` or `address[]`, recursing into nested structs and\n * arrays. Matching on the declared type rather than the field name means custom\n * and unknown message shapes are covered without per-protocol handling.\n *\n * Type dispatch matches the signer: a custom struct in `types` is walked first\n * (even if its name looks like `address` or `address[]`), then `address`, then\n * types whose name ends in `]` as arrays.\n *\n * `domain` is not traversed; its `verifyingContract` is expected to be scanned\n * separately by the caller.\n *\n * @param typedData - Parsed EIP-712 payload (`types`, `primaryType`, `message`).\n * @param options - Optional configuration.\n * @param options.exclude - Addresses to skip (e.g. the signer). The zero\n * address is always excluded.\n * @param options.excludeFields - Top-level field names to skip. Names must\n * match the declared EIP-712 field exactly. Only applied to the primary type\n * (depth 0), not nested structs.\n * @param options.maxAddresses - Distinct-address cap. Defaults to\n * {@link DEFAULT_MAX_SIGNATURE_ADDRESSES} and is clamped to\n * {@link MAX_SIGNATURE_ADDRESSES_CEILING}.\n * @returns Up to `maxAddresses` distinct canonical addresses, the field each\n * was found under, whether the message could not be fully walked, and the\n * effective cap.\n */\nexport function extractSignatureAddresses(\n  typedData:\n    | { types?: unknown; primaryType?: unknown; message?: unknown }\n    | null\n    | undefined,\n  options: ExtractSignatureAddressesOptions = {},\n): ExtractedSignatureAddresses {\n  const maxAddresses = resolveMaxAddresses(options.maxAddresses);\n  const types = typedData?.types as Eip712Types | undefined;\n  const primaryType = typedData?.primaryType as string | undefined;\n  const { message } = typedData ?? {};\n\n  if (\n    !types ||\n    typeof types !== 'object' ||\n    !primaryType ||\n    !Array.isArray(types[primaryType]) ||\n    !message ||\n    typeof message !== 'object'\n  ) {\n    return { addresses: [], fields: {}, overflow: false, maxAddresses };\n  }\n\n  // Narrowed alias so the hoisted helpers below see a defined `types`.\n  const schema = types;\n\n  // ZERO_ADDRESS is already canonical (lower-case, 20 bytes), so it is added\n  // directly rather than round-tripped through `normalizeAddress`.\n  const excluded = new Set<string>([ZERO_ADDRESS]);\n  for (const address of options.exclude ?? []) {\n    const normalized = normalizeAddress(address);\n    if (normalized) {\n      excluded.add(normalized);\n    }\n  }\n\n  const excludedFields = new Set(options.excludeFields ?? []);\n\n  // Canonical address -> the field name it was first found under.\n  const found = new Map<string, string>();\n\n  // Set when the message could not be fully walked, so some addresses may be\n  // unscanned: the address cap, the depth limit, the work budget, or an\n  // address-bearing type whose value could not be walked.\n  let overflow = false;\n\n  // Total nodes walked, bounded by MAX_TRAVERSAL_NODES.\n  let visited = 0;\n\n  // Stopping the walk (depth or work budget) leaves later fields unscanned, so\n  // it is treated as overflow the same way the distinct-address cap is.\n  const truncated = (depth: number): boolean => {\n    if (depth > MAX_TRAVERSAL_DEPTH || visited >= MAX_TRAVERSAL_NODES) {\n      overflow = true;\n      return true;\n    }\n    return false;\n  };\n\n  /**\n   * Whether `type` can contain `address` values: the `address` primitive, an\n   * array of an address-bearing type, or a custom struct that contains one.\n   *\n   * @param type - The declared EIP-712 type.\n   * @param seen - Types already inspected, to break recursive structs.\n   * @returns True when walking this type can yield addresses.\n   */\n  function isAddressBearing(\n    type: string,\n    seen: Set<string> = new Set(),\n  ): boolean {\n    if (seen.has(type)) {\n      return false;\n    }\n    seen.add(type);\n\n    const structFields = schema[type];\n    if (Array.isArray(structFields)) {\n      return structFields.some(\n        (field) =>\n          Boolean(field) &&\n          typeof field.type === 'string' &&\n          isAddressBearing(field.type, seen),\n      );\n    }\n\n    if (type === 'address') {\n      return true;\n    }\n\n    if (type.endsWith(']')) {\n      return isAddressBearing(type.slice(0, type.lastIndexOf('[')), seen);\n    }\n\n    return false;\n  }\n\n  /**\n   * Record a candidate address value under a field name, applying exclusions,\n   * de-duplication, and the distinct-address cap.\n   *\n   * @param field - The field name the value was found under.\n   * @param value - The raw field value to normalize and collect.\n   */\n  function collect(field: string, value: unknown): void {\n    const address = normalizeAddress(value);\n    if (!address || excluded.has(address) || found.has(address)) {\n      return;\n    }\n    if (found.size >= maxAddresses) {\n      overflow = true;\n      return;\n    }\n    found.set(address, field);\n  }\n\n  /**\n   * Walk the fields of a struct type, recursing per field.\n   *\n   * @param structName - The name of the struct type in the schema.\n   * @param value - The message object corresponding to the struct.\n   * @param depth - The current traversal depth.\n   */\n  function visitStruct(\n    structName: string,\n    value: unknown,\n    depth: number,\n  ): void {\n    if (truncated(depth)) {\n      return;\n    }\n    const structFields = schema[structName];\n    if (!Array.isArray(structFields) || !value || typeof value !== 'object') {\n      if (Array.isArray(structFields) && isAddressBearing(structName)) {\n        overflow = true;\n      }\n      return;\n    }\n    for (const field of structFields) {\n      if (truncated(depth)) {\n        return;\n      }\n      if (\n        !field ||\n        typeof field.name !== 'string' ||\n        typeof field.type !== 'string' ||\n        // Field exclusions only apply to the primary type (depth 0), matching\n        // the top-level field a dedicated caller already covers. Names must\n        // match the declared EIP-712 field exactly.\n        (depth === 0 && excludedFields.has(field.name))\n      ) {\n        continue;\n      }\n      visitField(\n        field.name,\n        field.type,\n        (value as Record<string, unknown>)[field.name],\n        depth,\n      );\n    }\n  }\n\n  /**\n   * Walk a single field value, handling custom structs, `address`, and arrays.\n   *\n   * Precedence matches `@metamask/eth-sig-util` `encodeField`: a type present\n   * in the schema is a struct first; otherwise `address`; otherwise a name\n   * ending in `]` is treated as an array (`type.slice(0, lastIndexOf('['))`).\n   *\n   * @param field - The field name.\n   * @param type - The declared EIP-712 type of the field.\n   * @param value - The field value from the message.\n   * @param depth - The current traversal depth.\n   */\n  function visitField(\n    field: string,\n    type: string,\n    value: unknown,\n    depth: number,\n  ): void {\n    visited += 1;\n    if (truncated(depth)) {\n      return;\n    }\n\n    if (Array.isArray(schema[type])) {\n      visitStruct(type, value, depth + 1);\n      return;\n    }\n\n    if (type === 'address') {\n      collect(field, value);\n      return;\n    }\n\n    if (type.endsWith(']')) {\n      if (Array.isArray(value)) {\n        const innerType = type.slice(0, type.lastIndexOf('['));\n        for (const item of value) {\n          if (truncated(depth)) {\n            return;\n          }\n          visitField(field, innerType, item, depth + 1);\n        }\n      } else if (isAddressBearing(type)) {\n        overflow = true;\n      }\n    }\n  }\n\n  visitStruct(primaryType, message, 0);\n\n  return {\n    addresses: Array.from(found.keys()),\n    fields: Object.fromEntries(found),\n    overflow,\n    maxAddresses,\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/phishing-controller",
-  "version": "18.0.0-preview-cfb927be0",
+  "version": "18.0.0-preview-e8a256c39",
   "description": "Maintains a periodically updated list of approved and unapproved website origins",
   "keywords": [
     "Ethereum",
@@ -63,6 +63,7 @@
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
+    "@metamask/eth-sig-util": "^9.0.0",
     "@types/jest": "^30.0.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "deepmerge": "^4.2.2",