Complete real browser-side wiring of the master plane (parent-control web app)

[hanwencheng]

Problem

The parent-control web app (apps/parent-control) renders the master-side flows but does not perform the real backend calls. Audited in PR #162 (docs/plan/web-flow/wire-real-paths.md §2):

• Onboarding ceremony — only the K11 WebAuthn step is real (and only in daemon backend mode); email-verify, wallet/SIWE→J1, and register_master_device are progress-bar narration with a mock tx hash. "Logged in" is a localStorage flag, not a session JWT.
• Memory plant/list — hits the daemon ui-bridge but stores in an in-memory map; no cap-mint → STS → memory worker → S3.
• Pairing / scope / revoke mutations — in-memory stubs; no broker pairing calls, no on-chain registerAgentDevice / setScopeWithWebauthn.
• Under the default empty backend (what a fresh user runs), nothing is real.

Root issue: the orchestration logic lives behind a localhost daemon (desktop-only). For the phone-first product (most operators have only a phone, no desktop), the browser/client itself must carry the master-plane logic and talk to the always-on broker.

Target

Complete the real browser-side wiring of the master plane so the web app drives the master onboarding, memory, pairing, and mutations through the real broker + chain + memory worker — the same calls harness/phase1-wire-demo.sh already makes — with no fabricated/in-memory data.

Per the plan (#162, docs/plan/web-flow/wire-real-paths.md §0.5 + §11 + §12): factor the master-plane orchestration into a portable agentkeys-core, compile it to WASM, and expose it as a CoreBackend behind the existing lib/client AgentKeysClient interface — so the browser calls the broker directly (the same core later binds to the mobile native app via UniFFI).

Scope (master plane, browser/client side only)

• X0 — carve the master-plane logic into agentkeys-core with a host-agnostic API (no axum/daemon deps); extend the existing init_flow with pairing + cap + onboarding-state.
• X1 — wasm-bindgen exports for: email auth (start/verify/status), wallet SIWE (start/verify), pairing (claim/pending/ack), cap-mint, onboarding-state aggregation. wasm-pack build.
• X2 — CoreBackend implementing AgentKeysClient (alongside empty/daemon); NEXT_PUBLIC_AGENTKEYS_BACKEND=core. UI unchanged (same interface).
• X3 — WebAuthn interop: the core asks the JS host to run navigator.credentials.{create,get}; the K11 enroll + assert flow back into the core.
• Onboarding §9 — real email magic-link → broker binding_nonce; real wallet/SIWE → J1 (replaces the localStorage.ak_onboarded flag with a real session); real register_master_device.
• Memory — plant/list through real cap-mint → OIDC-mint → STS → memory worker → S3 (replace the in-memory map).
• Pairing §10.2 — proxy the broker pairing endpoints (/v1/agent/pairing/*, /v1/agent/pending-bindings) + bind/grant chain writes.
• X4 — chain-write delegation per the §11 gating decision (see below).

Gating constraint (verified — wire-real-paths.md §11)

Every master chain write is msg.sender-bound to the operator's secp256k1 key (SidecarRegistry / AgentKeysScope); K11 is an additional gate, not a substitute. A browser/WASM host cannot safely custody the secp256k1 key, so it must delegate the on-chain broadcast to a key-holding host (phone Keychain / desktop daemon) — unless the contracts move to assertion-only auth. The exact secure delegation/relayer mechanism is the open design question (under adversarial security review; see #162 §11 fork A vs B).

Acceptance criteria

• With NEXT_PUBLIC_AGENTKEYS_BACKEND=core, a fresh operator completes onboarding (email → Touch ID → wallet/SIWE → master registered on chain) entirely from the browser, producing the same on-disk + on-chain artifacts the harness produces.
• Memory planted from the UI is readable via the real memory worker / S3 (cross-checked by the agent-side hook memory-inject).
• A pairing claim + scope grant from the UI lands real registerAgentDevice + setScopeWithWebauthn txs; isServiceInScope(...) == true.
• No narrated/in-memory data paths remain on the master plane; disconnected/empty states are honest.

References

• Plan: PR #162 — docs/plan/web-flow/wire-real-paths.md (§0.5 host model, §11 gating, §12 WASM scope), data-model.md (phone-first amendment), arch.md §22c.3.
• Reference implementation of the real calls: harness/phase1-wire-demo.sh.
• Canonical ceremonies: docs/arch.md §9 (master bootstrap), §10.1, §10.2.

Out of scope

• Agent-side wire/hook flow (separate concern).
• Audit calldata/CBOR decode (Audit decode: surface CBOR AuditEnvelope + EVM calldata decoding to the web UI #153).
• Second-master pairing, recovery quorum, isolation health-check (Phase 3+, already specced in data-model.md).
• A native Rust chain client (future hardening).

[hanwencheng]

Security prerequisites surfaced by the codex review of #162 (docs/plan/web-flow/wire-real-paths-security-review.md). These gate the chain-write half of the master-plane wiring:

• [CRITICAL] Authenticate first-master bootstrap (registerFirstMasterDevice is front-runnable today).
• [HIGH] K11-gate agent bind/revoke (currently msg.sender-only, no biometric).
• [HIGH] Full-intent K11 challenge binding on add-master + (for fork B) every master path.
• [HIGH] Precise multi-device sender-key model + recovery (single global operatorMasterWallet today).
• [HIGH] Directly part of this issue's X4: the browser→key-host delegation must use a native confirmation that independently decodes calldata + re-derives the K11 challenge before signing.

The contract-level items (bootstrap auth, agent-bind K11, full-intent challenges, multi-device model) are arguably a separate contract-hardening workstream that blocks this issue's real chain writes.

[hanwencheng]

Confirmed chain-write model: ERC-4337 P-256 smart-account — tracked in #164. That issue is the blocker for this issue's X4 (the browser signs UserOps with its passkey; depends on the account + EntryPoint existing on Heima). The contract-prerequisites from the codex review (bootstrap auth, full-intent binding, agent-bind gating) are folded into #164.

[Kailai-Wang]

Edited 2026-06-01 (see #168): corrected point 1 — the evm_version = "london" pin must stay (it's a forge script header-validation workaround, not an EVM-opcode ceiling); my original "relax the pin" was wrong. The Cancun finding and the P-256/passkey results below are unchanged. Doc fixes landed in #168.

Heima chain-side feasibility for passkey/assertion auth (re: §11 gating + the K11-gate comment above)

The §11 gating constraint and @hanwencheng's [HIGH] K11-gate agent bind/revoke item both point at the same chain-side question: master writes are msg.sender-bound to secp256k1, which a phone/browser can't safely custody — so one fork is moving the contracts to assertion-only auth (verify a passkey/P-256 WebAuthn assertion on-chain instead of relying on msg.sender). I dug into whether Heima can actually support that today and verified it end-to-end on a local Heima dev chain. TL;DR: yes, no chain changes needed — and I found that our documented "London EVM" assumption is wrong.

Experiment setup

• Built + ran the node: heima-node --dev (chainId 2013, 18-dec, token HEI), block production via -- --dev-block-time.
• Funded an EVM account by transferring from //Alice to the HashedAddressMapping(BlakeTwo256) of the EVM address (Frontier dev genesis pre-funds only the Substrate Alice/Bob accounts; evm: Default::default()).
• Foundry (forge 1.3.5), deployed real contracts, sent real txs/calls.

Findings

1. Heima's EVM is actually Cancun, not London. Our CLAUDE.md note ("Heima is London-level, pin foundry.toml to london") is based on block-header introspection, which conflates header format with opcode capability. Empirically:

• A Shanghai-compiled contract using PUSH0 (0x5f) deployed AND executed (set(42) → x()=42). London would reject PUSH0.
• A Cancun-compiled contract using TSTORE/TLOAD (EIP-1153, Cancun-only) ran: roundtrip(99) → 99.
• Source confirms it: Frontier stable2412 frame/evm/src/lib.rs fn config() returns &CANCUN_CONFIG (the // London doc comment one line up is stale).
• Action: correct CLAUDE.md (done in docs: Heima EVM level is Cancun, not London (correct the rationale; keep the foundry pin) #168). Keep the evm_version = "london" pin — relax it [correction]: it must stay, but for a different reason than the docs claimed. It is a forge script simulator header-validation workaround, not an EVM-opcode ceiling: forge script ... --broadcast validates Heima's prevrandao-less Substrate/Aura block header against the target revision and rejects paris+ with header validation error: prevrandao not set. Verified — DeployAgentKeysV1.s.sol with FOUNDRY_EVM_VERSION=cancun reproduces the error; london deploys. (forge create --broadcast with cancun does not hit this, which is what misled the original note — but our deploy path is forge script.) No SDK upgrade is needed to "raise" the EVM version — it's already Cancun.

2. On-chain P-256 (passkey/WebAuthn) verification works today — no precompile, no chain change. Heima has no RIP-7212 (0x100) precompile (confirmed: not in runtime/*/src/precompiles.rs). But the pure-Solidity Daimo P256Verifier (EIP-7212-compatible interface) deploys and verifies correctly:

• Canonical Wycheproof valid vector → returns 0x..01 (VALID).
• Tampered pubkey/sig → returns 0x..00 (INVALID).
• Cost: ~421k gas/verify. Fine for low-frequency master ops (scope set, agent bind/revoke); not a hot path.
• Compile note: needs via_ir = true (stack-too-deep), independent of EVM version.

3. The agentKeys "K11 on chain" / assertion-only path runs end-to-end. Deployed a minimal ERC-4337-style PasskeyAccount(verifier, pubKeyX, pubKeyY) whose isValidSignature(userOpHash, r, s) staticcalls the P256Verifier — i.e. a smart account gated by a passkey instead of msg.sender:

• Valid passkey assertion → true; tampered s → false. Both on-chain on Heima dev.

Conclusion for the X4 / chain-write-delegation fork

• ERC-4337 deploys on Heima with zero chain changes (it's app-layer; "AA without protocol changes"). The EVM is Cancun, so no PUSH0/opcode workaround is needed at runtime — but if you deploy via forge script, still keep evm_version = "london" for that tool's header validation (see corrected point 1).
• A Substrate P-256 precompile is not required (the p256 crate is already a Heima dep, so registering one at 0x100 is feasible later as a gas optimization — ~3450 vs ~421k gas — but it needs a runtime upgrade and isn't a blocker).
• The "assertion-only auth" fork is chain-feasible now: SidecarRegistry / AgentKeysScope could verify a K11 P-256 WebAuthn assertion via a deployed verifier instead of (or in addition to) msg.sender, which removes the browser/phone secp256k1-custody problem for master writes. Worth splitting into its own contract-hardening issue (ties into @hanwencheng's K11-gate items).

Reproduce

# 1. node
heima-node --dev --base-path /tmp/heima-devdata --rpc-port 9944 --rpc-methods=unsafe -- --dev-block-time 1000
# 2. fund an EVM acct: transfer from //Alice to blake2_256("evm:"++H160) via polkadot.js
# 3. P256Verifier (foundry: via_ir=true, solc 0.8.21; for `forge script` deploys keep evm_version=london — header workaround)
forge create src/P256Verifier.sol:P256Verifier --rpc-url http://127.0.0.1:9944 --private-key <pk> --broadcast --legacy
cast call <verifier> 0x<hash||r||s||x||y>   # valid Wycheproof vector -> 0x..01
# 4. Cancun proof: deploy a TSTORE/TLOAD contract, call it -> succeeds

Test vector: Daimo test/P256Verifier.t.sol first valid Wycheproof case.

(Note: #163's own scope is the web-app wiring; this comment only addresses the chain-side feasibility behind the §11/X4 gating question, so the "assertion-only" fork can be evaluated with real numbers.)