feat: freenet-updates crate (decentralized version-pointer for tooling)

[sanity]

Idea

Build a reusable freenet-updates crate that holds a small Freenet contract whose state is the canonical "current published version + release-key signature" pointer for a given tool. Tools (riverctl first; eventually fdev, river-publish, etc.) consume the crate to check for updates via the local Freenet node — no external HTTP, no crates.io polling, no GitHub API rate limits, no privacy footprint to a centralised registry.

Why now

We just discussed adding an HTTP-based crates.io version check to riverctl. That's the obvious-but-undecentralised approach — and adding a "phone home to a central registry" check to a tool whose purpose is decentralisation feels off. We should eat our own dogfood.

Shape

• New crate freenet-updates in the freenet/ org (or under river/ workspace if scoped first to River — TBD).
• Contract: VersionPointerV1 { tool_name: String, latest_version: SemVer, released_at: SystemTime, release_signature: Signature } signed by a known release key.
• One contract instance per tool (e.g., riverctl, fdev, river contract). Tools know their own contract key.
• Helper API: freenet_updates::check_for_update(tool_name, current_version) -> Result<UpdateStatus> — GETs the pointer contract via the local Freenet node, validates the release signature, returns UpToDate | Outdated { latest, released_at } | NetworkError.
• Tools opt in by calling the helper on startup (or via a self-update-check subcommand). Warn-and-continue on outdated. Opt-out env var.

Design questions

• Release key management: the simplest answer is one Ed25519 release key per tool, held by the release-cutter (today: Ian). Compromise of the release key = false-version attack. Mitigate via signature being verified locally against the bundled public key.
• Contract update mechanism: each tool publish bumps its version-pointer contract via a delegate or a release-script riverctl-style invocation.
• Bootstrap: tools need to be able to read the contract via the local Freenet node. If the local node isn't reachable, fall back to a no-op (don't block).
• Cache: stale-while-revalidate — tools can use the most recent successful check (cached to local disk) for offline scenarios.

Use cases

1. riverctl: warn on startup if outdated, with a hint to cargo install riverctl --force.
2. fdev: same shape.
3. freenet itself: long-term, could underpin auto-update for the daemon.
4. River UI: the UI could surface a "new River build available" toast once the UI bundles the freenet-updates crate.

Acceptance criteria

• Crate published to crates.io (or available as a git dep within the freenet org).
• riverctl uses it for its startup check.
• Public README documenting the release-key setup.
• Issue closed after the second tool starts using it (proves the API is genuinely reusable).

Related

• The "crates.io HTTP check" alternative was considered and rejected on dogfood grounds.
• Connection to the existing legacy_delegates.toml migration story: not directly, but the release-signature key is the same kind of "centralised trust root we need to manage" problem.

[AI-assisted - Claude]

[sanity]

Issue Priority Assessment

Generated: 2026-05-26T16:03:02.750715881+00:00
Issue hash: 71bad7c9

Value Assessment

This issue is still open and unimplemented. The feature doesn't exist anywhere in the codebase.

Relevance Check: The issue remains fully relevant — no update-checking mechanism exists in riverctl or anywhere else in the River codebase. The cli/src/main.rs has a bare #[command(version)] attribute that surfaces a static version string, and nothing more. The freenet-updates crate described in the issue has not been started.

User Impact: The impact is modest but real for the current riverctl user base. Without any update notification, users running an outdated riverctl against a newer gateway or room contract will encounter confusing wire-format errors rather than a clear "you need to upgrade" message. Given the project's active protocol evolution (the AGENTS.md documents multiple breaking wire-format incidents), users are routinely exposed to silent incompatibility failures. The audience is small today — early adopters and developers — but the pain is disproportionately high for them because they're the ones most likely to be running a stale binary after a release.

Strategic Alignment: The issue is well-aligned with Freenet's core identity: a decentralised system that routes its own update mechanism through itself rather than phoning home to crates.io or GitHub. The issue author frames this correctly as dogfooding. However, it requires a non-trivial amount of new infrastructure — a new contract, a release-key management process, a new crate — and the contract/delegate complexity means it touches the higher-risk surfaces of the codebase. The alternative (an HTTP crates.io check) would be far faster to implement and would solve the immediate user-facing problem, even if it feels philosophically inconsistent. The strategic value of the decentralised approach is real but somewhat speculative until the network has more nodes and users.

Blocking Factor and Urgency: This doesn't block any current work. There's no time pressure, and the absence of update notifications hasn't been reported as a recurring user complaint in the issue tracker. The most urgent related work — fixing wire-format incompatibilities — is already handled by the legacy_delegates.toml migration system. This issue is a quality-of-life improvement that becomes more valuable as the user base grows, but it isn't blocking anything today and can sit in the backlog without harm. The implementation scope is also genuinely larger than it appears: the contract, release-key management, bootstrap/fallback logic, and multi-tool generalization are each non-trivial, making this a medium-sized project rather than a quick addition.

Cost Assessment

This is a new feature issue — building a freenet-updates crate from scratch — so the relevant question isn't whether existing code was changed, but what the implementation would touch. The issue is still fully actionable; nothing in the existing codebase makes the described approach obsolete.

The scope is substantial but bounded. It requires creating an entirely new crate (freenet-updates) with its own Freenet contract (analogous to the existing room-contract), a signing/verification layer, a node-communication layer (reusing the WebSocket/stdlib patterns already in cli/src/api.rs), a local disk cache, and then wiring the helper into riverctl's startup path in cli/src/main.rs. The contract itself is simpler than the room contract — a single VersionPointerV1 struct with no CRDT merge needed, just signature validation — but it still needs the full Freenet contract boilerplate (WASM build, contract key derivation, publication tooling). The crate also needs to live somewhere (the issue is undecided on whether this belongs in the river workspace or a separate freenet-org repo), which adds a non-trivial design/organization decision up front.

Technically the implementation is moderate difficulty. The WebSocket GET pattern is already well-understood in cli/src/api.rs, and Ed25519 signature verification is already used throughout common/. The tricky edges are: (a) graceful no-op when the local Freenet node isn't running (the CLI currently assumes the node is reachable and would need a timeout/fallback path specifically for this check), (b) the stale-while-revalidate disk cache (requires its own file format and invalidation logic), and (c) bootstrapping — the version-pointer contract must itself be published somewhere before any tool can GET it, meaning Ian needs to run a one-time publish step against a live node, and that state must persist across node restarts. If the Freenet network doesn't reliably cache this contract, the check silently fails for everyone.

The external/non-code costs are the real bottleneck here. The release signing key needs to be generated, secured, and its public key bundled into the crate at compile time. The version-pointer contract needs to be initially published to the Freenet network, and there's an implicit dependency on the network being stable enough that a GET of this contract is reliably resolvable — a meaningful assumption given Freenet is still pre-production. If the check silently fails too often (node not running, network unreachable, contract not cached), the feature provides no value; if it blocks startup, it's a regression. Testing this meaningfully requires either a live Freenet node or mocking the WebSocket layer. The acceptance criteria also require a second tool (fdev) to adopt the crate before the issue closes, which means coordinating with the freenet-core repo — cross-repo work that adds timeline risk.

Overall this is a medium-to-high cost feature: probably 2–3 weeks of focused work to do it right (contract + crate + riverctl integration + cache + tests + initial publish + docs), with meaningful external risk around network reliability and the cross-repo coordination for fdev adoption. The value is real but not urgent — riverctl works fine without an update check — so the cost/benefit ratio depends on how much the team cares about the decentralized-by-default principle vs. shipping a simpler HTTP check in a day.

---

Generated by issue-prioritizer