design(security): recipient-resolution seam — where the recipient invariant lives (substrate review, #711/#727/#741/#737/#757 class)

[angelazhy]

Design task (Role: ARCH) — substrate review, not a point fix

Five separately-root-caused issues share one failure class on one substrate (the pre-sign safety gate): #711 → #727 (ERC-20 transferFrom recipient) → #741 (ERC-777 operatorSend) → #737 (ERC-20 transfer) → #757 (recipient-bearing functions on RECOGNIZED destinations — INCIDENT). Per the repo CLAUDE.md "Pre-Sign Gate Surface Sweeps" rule and the global ≥3-same-failure-class trigger, the next step is an architecture review of the layer, not a fifth selector patch. SEC filed the substrate-review; this issue is the ARCH design home for it.

Structural cause (SEC's diagnosis, verified in #757)

The gate keys on selector identity while the asset moves via an argument. Block 5 is allowedSelectors.has(selector) where the sets are computeSelectorsFromAbi(<protocol ABI>) — a selector allowlist derived from a protocol's own ABI necessarily admits that protocol's own recipient-bearing functions (withdraw(asset,amount,to), collect(...,recipient), borrow(...,receiver)). Block 4 (the only argument-agnostic catch-all, which consults the ack flags) is skipped precisely when the destination is recognized. So every recipient-bearing function in a pinned protocol ABI is a signable drain path to an arbitrary address, and no ack flag is load-bearing on that path. Sharp instance in #757: an ack-stamped prepare_custom_call to the real Aave V3 Pool with withdraw(USDC, MAX, ATTACKER) passes every block as designed.

The design question

Where should the recipient invariant live, such that ONE invariant closes the whole class instead of a perpetually-growing selector list? SEC's direction (input, not a ruling): an argument-level recipient-resolution seam — any address-typed recipient/receiver/owner/to argument resolves, and refuses non-bypassably when it is neither the wallet nor a saved contact.

Questions the verified artifact must settle

1. Seam locus — pre-sign (argument decode inside assertTransactionSafe) vs prepare-time; and how it composes with blocks 4/5 for recognized vs unknown destinations.
2. Per-ABI enumeration — the canonical set of address-typed recipient params (recipient/receiver/owner/to/dst/beneficiary) per recognized ABI, and how it stays complete as ABIs are added.
3. Resolution + allow — contact-book resolution and the == wallet allow; behavior when the contact book is empty.
4. Ack non-bypassability — the recipient invariant MUST NOT be bypassable by any ack flag (that is the entire exfil-defense point).
5. Drain-target vs legitimate-protocol-target (the crux) — some recipient args legitimately point at a non-wallet contract (a router/vault/receiver). A naive wallet-or-contact-only rule would over-block real flows. The artifact must enumerate these exceptions and handle them explicitly, or the seam is unshippable.

Two shapes the design must cover (SEC inputs; reachability UNVERIFIED — recon confirming)

• Permit2 transferFrom(address,address,uint160,address) (0x36c78516) — with from == wallet, a second self-source drain route a transfer-selector-keyed gate would not catch. Direct evidence a selector-keyed gate is the wrong shape.
• ERC-4626 deposit(uint256,address) / mint(uint256,address) — self-source, so security: ERC-777 operatorSend untracked in custom-call classifier — exfil sibling of #711 (SEC/ARCH weigh in on send-family set) #741's current inclusion criterion (classify by source-of-funds) excludes them by construction, yet they take the caller's tokens and credit shares to an attacker-chosen receiver. Evidence the classifier frame should be is-the-recipient-attacker-choosable, not source-of-funds. This reframe of security: ERC-777 operatorSend untracked in custom-call classifier — exfil sibling of #711 (SEC/ARCH weigh in on send-family set) #741's criterion is part of this design.

Acceptance criterion

A VERIFIED design artifact (design doc, reviewed to fixpoint and approved by REVIEW and SEC — the pre-sign exception surface takes a SEC verdict beside REVIEW's) that:

• answers the questions above with one argument-level invariant,
• handles legitimate non-wallet recipients explicitly (no over-block),
• is non-bypassable by ack,
• carries INCIDENT: pre-sign block 5 checks selector but never arguments — recipient-bearing fns on RECOGNIZED destinations are signable drain paths (Aave/Morpho/Uniswap/Lido) #757's falsifier generalized per blast-radius row: an ack-stamped call to a real recognized destination with a recipient that is neither the wallet nor a saved contact is REFUSED at pre-sign; the same call with recipient == wallet passes.

DEV implements the fix (#757) from the approved artifact; DEV is holding implementation pending it.

Status / dependencies

• Read-only evidence-recon in progress (verify SEC's anchors, complete the recipient-bearing enumeration, map the drain-vs-protocol distinction + resolution infrastructure).
• Blocks: INCIDENT: pre-sign block 5 checks selector but never arguments — recipient-bearing fns on RECOGNIZED destinations are signable drain paths (Aave/Morpho/Uniswap/Lido) #757 implementation (DEV holding).
• Related: security: transfer(address,uint256) via prepare_custom_call may be ack-bypassable to arbitrary recipient (sibling of #711) #737, security: ERC-777 operatorSend untracked in custom-call classifier — exfil sibling of #711 (SEC/ARCH weigh in on send-family set) #741, fix(custom-call): gate transferFrom ack on recipient #727, security: transferFrom custom-call classifier ignores recipient — ack-bypass permits arbitrary attacker recipient #711; PR fix(security): recipient-gate the send-family selectors (#741) #753 (classifier hardening — does NOT close this class).
• ARCHITECTURE.md §3 doc amendment to follow (block 5 constrains WHICH function may be called, not WHERE value goes).
• A Fable-tier adversarial pass on the design is available on user request (fund-safety + recurring-class + security-boundary).

Role: ARCH

[angelazhy]

CLAIMED ARCH — design owner, host macbookpro, 2026-07-19T10:25:59Z. Read-only evidence-recon in progress; verified design artifact to follow (REVIEW+SEC-approved). No implementation from this issue — DEV implements #757 from the approved artifact.

[angelazhy]

Recon complete → provisional design direction (ARCH deliberative state)

Read-only recon (against origin/main @ 32e001b; #753 landed the #741 send-family gate mid-session) confirms SEC's diagnosis and sharpens it:

• No recipient check exists in pre-sign at all. The security: transferFrom custom-call classifier ignores recipient — ack-bypass permits arbitrary attacker recipient #711/security: ERC-777 operatorSend untracked in custom-call classifier — exfil sibling of #711 (SEC/ARCH weigh in on send-family set) #741 gates are prepare-time, on prepare_custom_call only, and resolve recipient against a caller-supplied args.wallet — not the device address, not saved contacts. Protocol-specific prepare paths bypass them.
• Core exposure = self-sourced drains on recognized destinations: Aave withdraw(…,to), Morpho withdraw/borrow(…,receiver), Lido requestWithdrawals(…,owner), and tuple-nested Uniswap mint/collect/exactInputSingle(…,recipient) — invisible to both existing gates. Permit2 transferFrom (0x36c78516) is fully ungated (dest not in CONTRACTS); ERC-4626 deposit/mint excluded by construction.
• Over-block landmines are real: swap-recipient-is-the-router in multicall native-out chains; repay(onBehalf); and multicall itself re-checks no inner selectors (a bypass surface).
• The contacts-aware resolver already exists (resolveRecipient, src/contacts/resolver.ts:193) but is unwired.

Provisional design: an argument-level recipient-resolution seam at PRE-SIGN (the universal chokepoint, unlike the custom-call-only prepare gate), using a curated per-ABI, tuple-path-aware recipient-arg map (name heuristics are unsafe: to=recipient in Aave withdraw, onBehalfOf=debtor in Aave borrow), resolving each recipient to device-wallet-or-saved-contact via resolveRecipient, non-bypassable by ack. Reframes #741's criterion from source-of-funds → is-recipient-attacker-choosable. Adds Permit2 to recognized CONTRACTS so the seam covers it.

Highest-risk open decisions going into adversarial review: (1) multicall handling (fail-closed recursion vs over-block of legit swap→unwrap chains); (2) recipient-arg-map completeness + anti-rot; (3) pre-sign has the device addr/contacts + decode-error MUST fail-closed; (4) residual C-list over-block.

Next: Opus-tier adversarial design review (bypass-completeness / over-block / locus-feasibility lenses) → fix to fixpoint → design-doc PR → REVIEW+SEC approve → DEV implements #757. A Fable-tier pass is offered to the user on top. Full working draft held by ARCH; will land as the design-doc PR.

[angelazhy]

Design CONVERGED — 2 adversarial review rounds complete

The recipient-authorization seam design went through two full adversarial-review rounds (3 independent lenses: bypass/completeness, over-block/false-refuse, locus/feasibility). Round 2 converged: all three round-1 BLOCKERs resolved, and all three reviewers independently landed on the same single remaining blocker — now fixed in v3.

Load-bearing outcomes:

• Locus: the check lives in runEvmPreSignGuards after a fail-closed device account-match, comparing the recipient to the device-verified tx.from (not agent-supplied args.wallet). Ack-non-bypassable because it reads no ack flag.
• Fail-closed authorization over every address arg (replacing the v1 inclusion-map that recreated INCIDENT: pre-sign block 5 checks selector but never arguments — recipient-bearing fns on RECOGNIZED destinations are signable drain paths (Aave/Morpho/Uniswap/Lido) #757), with a module-load enumeration that refuses to boot if any recognized-ABI mutating-fn address/bytes path is unclassified — the anti-rot machine falsifier. Fail-closed on opaque bytes/bytes[] containers (Universal Router execute, multicall).
• Scope: hard gate applies to protocol-embedded / attacker-anomaly recipients only; ordinary transfer/native user sends stay on the resolver + on-device display (no regression).
• Contact trust root: wallet or SIGNED contact — signed add_contact requires a physical Ledger personal_sign button press (verified non-forgeable by an unattended agent), so the predicate binds to a signed-verified reverseLookup match, never to a label an unsigned agent-mintable entry also carries.
• LiFi _receiver gated (was decoded-then-discarded); Permit2 scoped to exact transfer selectors + batch .to[]; ERC-4626 deposit/mint/withdraw/redeem; Morpho marketParams 4 addresses allowlisted; universal per-leg multicall.

Hard dependency: #751 (tx-store deep-freeze) is a co-merge prerequisite (the gate is bypassable at send if the preview→send binding can be mutated) — OR adopt the recommended send-time recipient re-check in sendTransaction (tamper-proof by construction, removes the freeze dependency for this gate).

Next: ARCH authors the design-doc PR (docs/design/759-*) → SEC + REVIEW verdict (a pre-sign exception-surface change takes a SEC verdict beside REVIEW's) → DEV implements #757 from the approved artifact. DEV remains correctly holding. Full working design + review captures held by ARCH; they land in the design-doc PR.

[angelazhy]

Design artifact opened: PR #765 (docs/design/759-recipient-authorization-seam.md, draft) — the ARCH-converged design after two adversarial review rounds. Routed to SEC (security verdict on the exception surface + the §6 open items) and REVIEW (structural/completeness) for the authoritative verdict; a pre-sign exception-surface change takes both. DEV implements #757/#760 from this artifact once verdicts land — remains correctly holding.

Note for reviewers/DEV: the design's evidence base predates PR #758 (execution/index.ts decomposition, #720), so execution/index.ts line-anchors are evidence-pointers, not normative — the doc preamble states this; re-resolve runEvmPreSignGuards/previewSend/sendTransaction symbols against current HEAD. #751 (tx-store freeze) is a hard co-merge prerequisite of this design as specified, or is removed by the recommended send-time recipient re-check (§5).

[angelazhy]

REVIEW structural verdict (PR #765): REQUEST_CHANGES — 6 design defects, all re-derived against post-#758 main, all ACCEPTED. Grounding-edge fixes (block-5 union selector construction, live tool surface, a missing fail-open falsifier, a #751 mis-attribution) — a revision round, not a redesign; REVIEW confirmed the static bucket coverage + struct-nested walk + #760 native-value deferral are sound.

Folding all 6 into a v4 revision alongside SEC's (still-pending) security half — ONE revision, then re-request BOTH verdicts.

Two to highlight:

• D-1 (critical): the fail-closed account-match had no falsifier in §4 and the current code fail-opens on empty getConnectedAccounts() — a correct impl and a INCIDENT: pre-sign block 5 checks selector but never arguments — recipient-bearing fns on RECOGNIZED destinations are signable drain paths (Aave/Morpho/Uniswap/Lido) #757-reopening one were indistinguishable under the test set. v4 adds the empty-accounts / falsy-tx.from REFUSE falsifiers.
• D-6 (dependency correction): design(security): recipient-resolution seam — where the recipient invariant lives (substrate review, #711/#727/#741/#737/#757 class) #759 does NOT co-merge-depend on security: safe-tx-store lookupSafeTx returns body by reference unfrozen — deepFreeze sibling of #742/#730 #751 — it rests on the LANDED EVM tx-store freeze (security: tx-store issueHandles has no Object.freeze — stored-tx immutability is assumed, not enforced #710/security: apply deepFreeze across tron/solana/btc/ltc tx-stores — TOCTOU sibling sweep of #710/#730 #742). Verified: grep lookupSafeTx = 0 in execution/index.ts; the EVM gate consumes the EVM tx-store (deep-frozen at tx-store.ts:178), never the Safe-tx-store. DEV: INCIDENT: pre-sign block 5 checks selector but never arguments — recipient-bearing fns on RECOGNIZED destinations are signable drain paths (Aave/Morpho/Uniswap/Lido) #757/INCIDENT: LiFi Diamond allowedAbi: null — block 5 does not run at all; arbitrary calldata + arbitrary native value to a recognized destination, blind-sign class (ARCHITECTURE.md §3.4) #760 are NOT blocked on security: safe-tx-store lookupSafeTx returns body by reference unfrozen — deepFreeze sibling of #742/#730 #751 (correction propagated to PM).

DEV continues holding pending the revised artifact + both verdicts.