feat(phishing-controller): export extractSignatureAddresses for EIP-712 typed-data scanning

[wzrdk3lly]

Explanation

Ticket: PSAFE-441

Supersedes #9875 (same change, opened from a core branch so changelog CI can resolve the head). Review comments on that PR were addressed there.

MetaMask validates eth_signTypedData_v3 and eth_signTypedData_v4 requests with PPOM, which inspects the address fields of a signature. PPOM's threat data is refreshed on a delay, so an address that has been flagged recently can still be reported as benign, and it does not cover every chain or protocol.

Separately, the real-time per-address scan (/address/evm/scan) is only applied to a few fields today: the token verifyingContract, permit spender, and delegation delegate. Addresses carried in any other field — recipients, makers, tokens, custom protocol fields — receive no real-time scan at all.

This change adds a schema-driven extractor that returns up to 10 distinct address-typed values found in a typed-data message (including nested structs and arrays, matched by declared type rather than field name), and reports when the message could not be fully walked because the address cap, depth limit, or work budget was reached. When PPOM has not already flagged the request, the extracted addresses are passed to the real-time address scan. Results reuse the existing address cache, so fields already scanned elsewhere are not requested again.

What this exports

• extractSignatureAddresses(typedData, options) — walks types/primaryType/message, returns { addresses, fields, overflow, maxAddresses }
• ExtractedSignatureAddresses — return type
• ExtractSignatureAddressesOptions — options: exclude (addresses to skip, e.g. the signer), excludeFields (top-level field names to skip, e.g. spender when already covered by an existing scan), maxAddresses (optional cap override; default 10, hard ceiling 50)
• DEFAULT_MAX_SIGNATURE_ADDRESSES and MAX_SIGNATURE_ADDRESSES_CEILING — exported so clients can word overflow copy and stay aligned with the default/ceiling

Safeguards

• Cap of 10 distinct addresses per message by default, overridable via maxAddresses up to 50
• Max traversal depth of 12
• Max 5000 nodes visited
• overflow: true is returned whenever the walk is incomplete so callers can surface a caution

References

• Prior fork PR (same change): feat(phishing-controller): export extractSignatureAddresses for EIP-712 typed-data scanning #9875
• MetaMask Extension (client wiring): feat(confirmations): scan EIP-712 address fields via phishing controller metamask-extension#45521
• MetaMask Mobile (client wiring): feat(confirmations): scan EIP-712 address fields via phishing controller metamask-mobile#34786
• Prior implementation with local extractor copy (Extension): feat: scan address fields in typed-data signature requests metamask-extension#45058
• Prior implementation with local extractor copy (Mobile): feat(confirmations): scan address fields in signature requests metamask-mobile#34428

Changelog

See packages/phishing-controller/CHANGELOG.md.

Checklist

• Tests written and passing
• Changelog updated
• Exports added to index.ts
• Version bump (pending release cut)

---

Note

Medium Risk
Security-adjacent signing flow support: incorrect normalization or missed addresses could weaken typed-data scanning when clients adopt the export, though behavior is heavily tested and bounded with overflow signaling.

Overview
Adds extractSignatureAddresses, a schema-driven helper that walks EIP-712 types/primaryType/message and collects distinct address-typed values (including nested structs and arrays) for downstream real-time address scanning—not hard-coded field names like spender or to.

The function normalizes values the same way signing does (hex/decimal, leading 20 bytes, lowercase dedupe), supports exclude, top-level excludeFields, and a configurable distinct-address cap (default 10, ceiling 50). It returns addresses, per-address fields for alert copy, and overflow when traversal hits caps, depth (12), or a 5000-node budget so clients can warn when not every address was collected. DEFAULT_MAX_SIGNATURE_ADDRESSES and MAX_SIGNATURE_ADDRESSES_CEILING are exported from index.ts alongside the new types.

Ships signature-address-extraction.ts, a large Jest suite (including @metamask/eth-sig-util parity checks), changelog entry, and eth-sig-util as a devDependency only—no PhishingController wiring in this PR.

^{Reviewed by Cursor Bugbot for commit 732e1c3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fd1bfce. Configure here.}

[adonesky1]

LGTM but we should first address #10170 (comment)