SWIP-XXXX: Swarm Provider API (window.swarm)#94

Open

flotob wants to merge 6 commits intoethersphere:masterfrom

flotob commented May 9, 2026

Summary

This PR proposes a new draft SWIP defining a standard JavaScript provider API — window.swarm — that lets web pages request access to a user's Swarm (Bee) node for publishing data, uploading files, managing mutable feeds, reading and writing indexed feed entries, and introspecting their own feed records. It follows the request/response pattern established by EIP-1193 for Ethereum providers, adapted for Swarm's publishing and feed primitives.

The draft lives at SWIPs/swip-draft_provider_api.md and will be renamed to swip-XXXX.md once a number is assigned.

Motivation

Today, publishing to Swarm from a web app requires either:

Direct HTTP calls to a locally running Bee node — exposing the full API surface (including administrative, debug and staking endpoints) to any page that can reach localhost, or
Server-side publishing infrastructure — defeating the point of decentralized hosting.

Neither is acceptable for a user-sovereign web. Users need a way to grant web apps controlled, permissioned access to Swarm publishing — the way window.ethereum lets pages interact with a wallet without exposing private keys. Without a standard, every Swarm-enabled browser or extension will invent its own API, fragmenting the ecosystem.

What the SWIP specifies

Provider object (window.swarm) injected before DOMContentLoaded, with request(), convenience wrappers, and an event interface.
Ten RPC methods covering: connection (swarm_requestAccess), capability discovery (swarm_getCapabilities), publishing (swarm_publishData, swarm_publishFiles, swarm_getUploadStatus), mutable feeds (swarm_createFeed, swarm_updateFeed), indexed feed entries (swarm_writeFeedEntry, swarm_readFeedEntry), and origin-scoped feed introspection (swarm_listFeeds).
Permission model with explicit user consent, origin normalization (so all dweb content served from 127.0.0.1 doesn't collapse into one permission scope), and app-scoped feed identities (each origin's feeds signed by a per-origin derived key, so dApps can't impersonate the user's main wallet).
Read-only methods on public Swarm data (feed entry reads, listing the calling origin's own feeds) require no permission grant, since the same data is fetchable via any Bee gateway and gating it would be friction without security benefit.
Exact-match requirements on indexed feed reads/writes (with implementation notes on Bee's GET /feeds/{owner}/{topic} at-or-before semantics and the SOC-address fallback) so overwrite protection and explicit-index reads are safe.
Capability-advertised limits (maxDataBytes, maxPathBytes) so future implementations supporting PAX tar can advertise larger paths without breaking the spec.
Security considerations covering origin trust, resource exhaustion, iframe behavior, key material isolation, and temp artifact cleanup.
Future extensions explicitly out of scope for 1.0 (capabilitiesChanged event, preferredIdentityMode, encoding parameter for reads, promotion path for specVersion).

Reference implementations

This is not a paper spec — both sides of the API are already implemented and exercise the full surface:

Provider: Freedom Browser (PR #19) injects window.swarm into webview contexts, with main-process IPC enforcement, origin normalization, app-scoped feed keys, and per-origin permissions.
Consumer dApp: Swarmit — a decentralized message board — uses swarm_requestAccess, swarm_publishData, swarm_createFeed, swarm_writeFeedEntry, swarm_readFeedEntry, and swarm_listFeeds for its full publishing and profile-discovery pipeline.

The implementation work surfaced several spec issues that have already been folded back into this draft (USTAR tar's 100-byte path limit, Bee's at-or-before feed lookup semantics, the SOC-address endianness trap, permission gating for public reads).

Status

Status: Draft — opening this PR to register the SWIP and begin discussion.
Developer Documentation: Swarm Provider JavaScript API
Discussion: Swarm Discord — SWIPs channel.
Happy to iterate on naming, scope, and any specifics before this is endorsed. Filename will be renamed from swip-draft_provider_api.md to swip-XXXX.md once a number is assigned.

flobot and others added 6 commits

April 3, 2026 20:12


          draft: Swarm Provider API (window.swarm) SWIP

c243a97


          refine SWIP draft: security, versioning, edge cases, and editorial im…

e2659eb

…provements

Add Security Considerations section (origin trust, resource exhaustion, iframe
behavior, feed key material, temp artifacts). Add Future Extensions section
(swarm_listFeeds, capabilitiesChanged, preferredIdentityMode, specVersion
promotion path). Promote convenience methods and re-prompting from SHOULD to
MUST. Add specVersion (SHOULD) to swarm_getCapabilities. Document UTF-8 string
encoding, session-scoped tag ownership, feed update failure semantics, and
bzz:// URI scheme status. Add edge-case test cases. Fix stale branch links.
Rename file to match repo conventions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>


          fix: correct Swarmit repo URL

b049ade

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>


          save current state

7bcfea2


          spec: add swarm_listFeeds and remove permission gate from swarm_readF…

0e8e211

…eedEntry

Two coordinated updates reflecting the implemented behavior in Freedom
Browser (PR ethersphere#19):

1. New method: swarm_listFeeds()
   - Origin-scoped introspection returning the calling origin's previously
     created feed records — name, topic, owner, manifestReference, bzzUrl,
     createdAt, lastUpdated, lastReference.
   - No permission required: feed coordinates are deterministic given
     (origin, name) and the metadata persists across permission revocation
     by design, so gating it would be friction without security benefit.
   - Returns [] for origins with no feeds (never an error).
   - Removed from the Future Extensions list since it now ships in 1.0.

2. Permission correction for swarm_readFeedEntry
   - The 1.0 draft previously required connection permission. That was
     wrong — feeds are public Swarm data readable from any Bee gateway
     without auth, and forcing requestAccess broke passive use cases like
     profile pages displaying on-chain-discovered activity feeds.
   - Method now requires NO permission grant. Updated description, errors
     (4100 removed), behavior bullets, permission lifecycle item 4, and
     the corresponding test case ("Without Feed Grant" → "Without Any
     Permission" with stronger assertions).
   - Permission lifecycle item 5 (disconnection) clarified that
     permission-free reads MUST continue to function after revocation.

Other touches:
- Method count in the abstract bumped from "nine" to "ten".
- Convenience method list extended with window.swarm.listFeeds().
- Implementation reference updated: removed the broken docs/swarm-provider-test
  link (the file moved to research/ and is no longer tracked); Swarmit's
  method usage list extended to include writeFeedEntry / readFeedEntry /
  listFeeds.

Net diff: +83 / -14 lines.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>


          spec: add maxPathBytes capability and require exact-match feed reads

82c55ec

Reflects implementation findings from the iOS Freedom Browser provider:

- USTAR tar's 100-byte name field caps file paths far below the prior
  256-char wording. Replace the hardcoded limit with a capability-advertised
  maxPathBytes (normative floor of 100, recommended default 100 UTF-8 bytes)
  so future PAX-supporting implementations can advertise more.
- Bee's GET /feeds/{owner}/{topic}?index=N is at-or-before, not exact-match,
  which silently breaks writeFeedEntry's overwrite protection on sparse
  writes and corrupts readFeedEntry's explicit-index contract. Add normative
  exact-match requirements on both methods plus an informative section
  documenting the SOC-address derivation (GET /chunks/{socAddress}) and the
  big-endian/little-endian endianness trap.
- Clarify that the 4 KB SOC body limit is internal to the storage envelope,
  not a writeFeedEntry payload cap; the dApp-visible cap is maxDataBytes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet