feat: support multi-page website navigation in gateway iframe sandbox

[sanity]

Problem

The gateway serves web container content inside a sandboxed iframe with allow-scripts allow-forms allow-popups (no allow-top-navigation, no allow-same-origin). This works for single-page apps (like River) where all routing happens in JavaScript, but breaks multi-page static websites where links navigate between HTML pages.

When a user clicks a link like <a href="/v1/contract/web/KEY/news/">, the navigation is silently blocked by the sandbox. Neither regular link clicks nor window.location.href assignments work.

Impact

Static websites published with fdev website publish render correctly on the first page load, but internal navigation between pages doesn't work. This significantly limits the usefulness of the website hosting feature for multi-page sites (which is most static sites).

Current workaround

Users must navigate by editing the URL directly in the browser address bar. This is unusable for non-technical visitors.

Possible solutions

1. Add allow-same-origin to the sandbox -- simplest but may have security implications that need evaluation
2. Gateway-side navigation interception -- the freenetBridge script could listen for postMessage navigation requests from the iframe and update the iframe's src
3. Rewrite links at serve time -- the gateway could inject JavaScript into served pages that intercepts clicks and communicates with the bridge via postMessage

Option 2 seems most promising -- the iframe posts a {type: 'navigate', href: '/news/'} message, and the bridge updates the iframe src accordingly. This preserves the sandbox security model while enabling navigation.

[AI-assisted - Claude]

[sanity]

Issue Priority Assessment

Generated: 2026-05-26T16:07:52.254557907+00:00
Issue hash: 6f3cece0

Value Assessment

The issue appears to have been partially addressed already. The __sandbox=1 detection code in hugo-site/themes/freenet/assets/js/main.js handles navigation for the freenet.org website itself, and the documentation at publish-a-website.md explicitly states that "the gateway automatically intercepts link clicks within the iframe and navigates to the target page (as of v0.2.41)." This means the core navigation problem described in the issue was resolved at the freenet-core level.

Relevance Check: This issue is largely obsolete as written. The documentation in this very repository (hugo-site/content/build/manual/publish-a-website.md) explicitly describes that multi-page navigation now works — the gateway automatically intercepts link clicks within the sandbox iframe as of v0.2.41. The __sandbox=1 detection pattern in the site's own JavaScript (hugo-site/themes/freenet/assets/js/main.js:2-16) further confirms this infrastructure exists and is in use. The issue's proposed Option 2 (postMessage navigation interception) appears to have been implemented in freenet-core, not this repository. The issue may remain open simply because it was filed against the wrong repo, or because some edge cases remain, but the headline problem — "internal navigation between pages doesn't work" — is documented as fixed.

User Impact: When the issue was active, the impact was severe: every static multi-page site published via fdev website publish was effectively broken for non-technical users, limiting a core Freenet use case (censorship-resistant website hosting) to single-page apps only. This is not a niche scenario — most websites have multiple pages. That said, since v0.2.41 resolved it at the gateway level, this impact has been mitigated for users running a current gateway.

Strategic Alignment: Website hosting is a first-class feature for Freenet's goal of censorship-resistant publishing. A broken multi-page navigation story would be a significant gap in that value proposition, so fixing it is highly aligned with project goals. However, since the fix already landed in freenet-core, keeping this issue open in the web repo adds little value.

Blocking and Urgency: With the navigation feature documented as working in v0.2.41+, this issue no longer blocks other contributions. The appropriate next action is to close it as resolved (pointing to the freenet-core PR that fixed it), or move it to freenet-core if any edge cases remain. There is no urgency to address it further in this repository.

Cost Assessment

The issue is about gateway iframe sandbox behavior, but the gateway code lives in freenet-core, not this web repo. The web repo (freenet/web) is primarily the Freenet.org marketing/documentation website plus Ghost Key WebAssembly components — it doesn't contain the gateway server or its iframe sandbox logic.

Relevance Check: This issue is filed against the wrong repository. The gateway that serves web container content via sandboxed iframes, the freenetBridge script, and the iframe sandbox attribute (allow-scripts allow-forms allow-popups) all live in freenet-core (the Rust gateway implementation), not in freenet/web. The explore agent found a __sandbox=1 query parameter check in hugo-site/themes/freenet/assets/js/main.js that intercepts link clicks within the Freenet.org site itself, but that's unrelated to serving arbitrary published websites through the gateway iframe. No freenetBridge postMessage bridge was found in this repo at all. The implementation work described in the issue — modifying the gateway's iframe sandbox policy, injecting JavaScript into served pages, or handling postMessage navigation — would need to happen in freenet-core, not here.

Scope and Complexity: If the issue were re-filed against freenet-core, the implementation effort for Option 2 (postMessage-based navigation) is moderate. It would require: (1) modifying the gateway's HTML injection code to include a script that intercepts <a href> clicks and posts navigation messages to the parent frame, (2) modifying the gateway's iframe host page to listen for those messages and update iframe.src, and (3) handling edge cases like relative vs. absolute URLs, fragment links (#anchor), external links (which should open in a new tab, not be intercepted), and <base href> tags that alter relative URL resolution. The approach is well-understood and doesn't require novel cryptographic or distributed systems work.

External Dependencies and Risk: No external dependencies or approvals are needed. The main risk is the security evaluation of the sandbox model — adding postMessage-based navigation must be carefully scoped so that malicious content inside the iframe can only navigate to URLs within the same contract's path space (i.e., URLs under /v1/contract/web/KEY/), not to arbitrary URLs. Without that constraint, a sandboxed page could trick the bridge into navigating the parent frame to a phishing URL. This security constraint is the trickiest design decision and needs explicit validation. There's also a risk of breaking single-page apps (like River) that already handle their own routing via JavaScript, though those wouldn't be sending navigate postMessages so the bridge would simply ignore them.

Testing Effort: Testing would require an end-to-end setup with a running Freenet gateway node and a multi-page static site published via fdev website publish — not easily unit-testable. The existing integration test infrastructure in freenet-core uses browser automation, so a new Playwright or similar test navigating between pages in a served iframe is feasible but requires that full stack. This is non-trivial to set up in CI. Overall, if filed in the correct repo, this is a medium-cost issue: the code changes are modest (perhaps 50-100 lines across 2-3 files in freenet-core), but the security reasoning and end-to-end testing are where the real effort lies. As currently filed against freenet/web, it is not actionable without first moving it to the correct repository.

---

Generated by issue-prioritizer