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

[flotob]

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:

1. 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
2. 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.

[agazso]

It would be good if chunk level operations were supported in the API, because with those every higher level Swarm APIs can be implemented (feeds, manifest, ACT etc.), even ones that are not supported at the moment by Bee (e.g. epoch feeds).

The API could be window.swarm.publishChunk({ chunkPayload, span, options }) where chunkPayload is the chunk payload with type Uint8Array | string, and an optional span that can be omitted and it defaults to the payload length (in bytes). options would be also optional, and it can contain other fields controlling advanced functionality (pin, encryption, tag, deferred, redundancy).

Similarly there would be a window.swarm.readChunk({ reference, options }) which would return the chunk data. The reference could be either Uint8Array | string and it could contain a regular or an encrypted reference. The options would be optional and it can contain other fields controlling advanced functionality (redundancy, ACT).

There are also Single-Owner Chunks. Currently Swarm does not have a way to distinguish different chunk types, and it does it with heuristics, but there are documented issues and discrepancies about it.
See:

• add swip-26: strictly typed chunk system #67
  and
• fix: reverse SOC/CAC detection order in POST /chunks handler bee#5445

If this could be fixed at the Swarm level, then publishChunk would be enough for publishing and only a readSingleOwnerChunk would be needed additionally, otherwise also a publishSingleOwnerChunk would be necessary. But maybe that's out of the scope of this SWIP already.

[flotob]

Thanks @agazso — this ended up being very useful feedback. The latest push (d42af03) takes the chunk tier substantively on board.

Chunk methods added: swarm_publishChunk / swarm_readChunk for CACs, and swarm_writeSingleOwnerChunk / swarm_readSingleOwnerChunk for SOCs. The chunk type is declared by the method name rather than inferred, which avoids depending on the SOC/CAC heuristic ambiguity discussed in #67 and ethersphere/bee#5445.

Type validation on reads: providers must verify returned bytes against the requested chunk type: BMT/address validation for CACs, and SOC signature recovery plus keccak256(identifier || owner) derivation for SOCs. A mismatch returns chunk_type_mismatch.

Signing identity discovery: added swarm_getSigningIdentity, so dApps can pre-compute SOC addresses, e.g. for epoch-feed construction, before committing to a specific write. It also gives a clean bootstrap path for the feed/signing permission grant.

options exists, but is intentionally narrow in v1: chunk methods accept an options object, but no fields are standardized yet. Unknown fields must return unsupported_option. ACT, encryption, redundancy, progress tags, cache behavior, and deferred upload are listed as future-extension candidates pending a precise mapping to Bee’s endpoint semantics.

SOC mutability wording corrected: same (owner, identifier) rewrites are undefined/discouraged; mutable structures should use distinct identifiers, with swarm_writeFeedEntry retaining overwrite-rejection semantics for the journal/feed use case.

A few related changes fell out of this: permission-free reads now have mandatory per-origin rate/bandwidth limits with a rate_limited reason; span is now number | bigint for u64-safe custom BMT spans; and 4001 vs 4100 is now consistent across publish/feed permission prompts.

I also looked at SwarmID while shaping this. My current read is that window.swarm should provide the node-access, permission, origin, postage-selection, and signing boundary, while libraries such as SwarmID can build identity/encryption/ACT/higher-level structures on top of the chunk substrate. Happy to coordinate on what a SwarmID adapter would need from this interface.

Reference implementations for the new chunk tier and swarm_getSigningIdentity will follow in a subsequent Freedom Browser PR; the existing high-level methods are already implemented there. Feedback on the new surface before that work starts is very welcome.