feat: Implement signed delegate chain migration

[sanity]

Summary

The current delegate migration system uses a LEGACY_DELEGATES array that manually tracks old delegate keys. This works but requires manual maintenance and bypasses the delegate encapsulation model.

Problem

When delegate WASM changes (due to dependency updates, bug fixes, etc.), the delegate key changes because key = BLAKE3(BLAKE3(WASM) || params). The current workaround:

1. Hard-code old delegate keys in LEGACY_DELEGATES array
2. Check if the current delegate matches any legacy key
3. If so, migrate data from old delegate to new one

This approach:

• Requires manual maintenance every time delegate WASM changes
• Creates a growing list of legacy keys to track
• Bypasses the delegate trust model (any code could claim to be a "legacy" delegate)
• Risk of forgetting to add old keys, breaking migration for users

Proposed Solution: Signed Delegate Chains

Implement a proper delegate migration system using cryptographic signatures:

1. Each delegate version is signed by the application's signing key
2. Delegates only reveal private keys (room secrets, signing keys) to another delegate that:
   • Has a valid signature from the same application key
   • Presents a proper migration request
3. Chain of trust: New delegate proves it's authorized by presenting its signed certificate
4. No manual key tracking: The delegate itself verifies the migration chain

Design Sketch

DelegateMigrationRequest {
    source_delegate_key: DelegateKey,      // Old delegate
    target_delegate_key: DelegateKey,      // New delegate
    target_code_signature: Signature,       // App key signs new WASM hash
    migration_token: MigrationToken,        // One-time use token
}

The old delegate validates:

• target_code_signature is valid for the target WASM hash
• The signing key matches the expected application key
• The migration token is fresh (prevent replay)

Then transfers its secrets to the new delegate.

Benefits

• Eliminates LEGACY_DELEGATES array entirely
• Preserves delegate encapsulation and trust model
• Automatic migration without manual key tracking
• Replay-protected via one-time tokens
• Works across arbitrary version jumps (not just N to N+1)

Current Workaround

The LEGACY_DELEGATES approach in chat_delegate.rs works for now but should be replaced with this proper solution.

Related

• Room contract migration is handled separately via OptionalUpgradeV1 upgrade pointers
• This issue specifically covers delegate-level migration (where secrets are stored)

[AI-assisted - Claude]

[sanity]

Issue Priority Assessment

Generated: 2026-03-05T15:26:26.835001909+00:00
Issue hash: 71a78cdc

Value Assessment

The current migration experience in ui/src/components/app/chat_delegate.rs still relies on a hard-coded LEGACY_DELEGATES array that fire_legacy_migration_request() iterates over to pull room secrets from previous delegate keys. Every delegate release that changes the WASM (and therefore the DelegateKey) requires someone to memorize the previous key, append it to this list, and then trust that the new binary is authorized to take over. When that happens in practice, any omission causes nodes that already have rooms on the older delegate to start failing to load those rooms, because the delegate with the new key can’t see the secrets anymore. That means potentially every production user who already has rooms in Freenet will suddenly lose access after a delegate update unless the list is manually patched, so the user impact is broad and severe whenever a release touches the delegate (which happens often after dependency bumps or bug fixes).

Strategically, River’s promise depends on Federnet’s delegate isolation model and the ability to ship updates without breaking existing rooms, which is exactly the scenario this issue targets. The LEGACY_DELEGATES shortcut not only subverts the delegate trust boundary (any code that lies about being legacy can pretend to migrate) but also forces the team to add yet another maintenance step to every delegate release, as noted by the check-delegate-migration CI guard in AGENTS.md. Implementing a signed migration chain keeps the delegation model intact, removes the need for manual key tracking described in the issue, and aligns with the stated goal of safe, upgrade-friendly smart contract and delegate deployments in the project’s architecture.

The manual approach also acts as a bottleneck for future work: any change to delegates/chat-delegate or shared common/ code that changes the WASM hash requires updating LEGACY_DELEGATES before any release can be published, or else users will be trapped on old binaries. That makes simple dependency updates or cleanups risky and effectively blocks deployments until the developer remembers to “bless” the legacy key. There isn’t a strict calendar urgency (the next delegate update could be planned weeks away), but every pending release carries the same risk, so the sooner a signed chain replaces the ad-hoc list, the less risk of data loss and deployment friction the project has to accept going forward.

Cost Assessment

Any replacement of the current LEGACY_DELEGATES fan-out has to touch several moving parts at once. The constant + migration helpers in ui/src/components/app/chat_delegate.rs (lines 78‑360) currently enumerate every previous delegate key, fire GetRequests against those delegates, and then, when the response handler at ui/src/components/app/freenet_api/response_handler.rs (around lines 240‑520) sees a legacy response it re‑stores the rooms in the new delegate and drops the migration flag. That whole workflow would disappear, so the UI will instead need to send a new DelegateMigrationRequest (and interpret a matching response) rather than hard‑coding old keys. The shared ChatDelegateRequestMsg/ResponseMsg definitions in common/src/chat_delegate.rs would need to grow the new variants and the helper code around send_delegate_request/complete_pending_request would need to account for them. Almost simultaneously, the delegate WASM (delegates/chat-delegate/src/lib.rs, handlers.rs) will have to understand the new migration message, validate the signature chain, refuse unsigned requests, and hand secrets safely over to the requesting delegate.

The cryptographic handshake itself is non‑trivial. The handler already extracts an attested origin and uses it to namespace storage (create_origin_key, create_index_key in delegates/chat-delegate/src/utils.rs), so the migration path must include a one‑time token store, verification that the migration request carries a signature created with the same application key that signs the web container (the key that contracts/web-container-contract/web-container-tool stores in ~/.config/river/web-container-keys.toml), and a fresh nonce per migration. Validating the target_code_signature means the delegate must hash the offered WASM and compare it to the signature, so the UI also has to compute and sign that hash before contacting the old delegate. The two delegates need a protocol for requesting secrets (source verifies the signature, checks the token, then packages secrets into a response) and the client needs to know when it can discard the legacy migration workflow (including removing the check-delegate-migration workflow’s assumption that LEGACY_DELEGATES must be updated).

Faults in that added logic are high risk—losing a migration token or failing to store the new target hash properly could block every legacy user from retrieving their room data, since the fallback previously relied solely on a growing list of hard‑coded keys (ui/src/components/app/chat_delegate.rs:83-550). The current response_handler already tries to save rooms to the new delegate when an old one replies (see the portion around lines 420‑510 where it calls save_rooms_to_delegate and marks the migration flag), so any incorrect sequencing or missing mark_legacy_migration_done() analogue could lead to repeated migration attempts or missed cleanups. The delegate itself must also carefully ensure it only discloses secrets once per token; adding that state means a regression in token handling could silently stop migrations and leave the node stuck on the legacy delegate.

Testing will be heavier than the current manual array updates. The new request/response enums in common/src/chat_delegate.rs can be unit‑tested for serialization, but the meat of the feature lives in the delegate WASM: you’ll need integration tests that spin up two DelegateCtx instances (old and new), inject a signed migration request, and assert the legacy storage is drained into the new delegate and that replayed tokens are rejected. Similarly, the UI layer must be exercised (probably via wasm tests or by mocking send_delegate_request) to ensure it signs the correct hash, stores/use tokens only once, and gracefully handles a failed migration. The existing check-delegate-migration CI job will also become obsolete or need a rewrite so it no longer insists on editing LEGACY_DELEGATES. All told, this is a cross‑module effort touching ui/, common/, delegates/, and the CI/workflow definitions, with non‑trivial crypto validation, so expect several days of work plus new tests to ensure regressions don’t cost users their rooms.

---

Generated by issue-prioritizer