swarmwire-lib 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tibotibotibotibotibotibotibotibotibotibotibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# swarmwire
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Content-addressed file transfer over Hyperswarm.**
+
+> Transfers directly from one's filesystem to another, no need to duplicate the data in a hyperblob
+
+Give someone a link, they get the bytes — from you, or from anyone else who already has them.
+Files are served in place, from wherever they already live on disk. Nothing is copied into a
+store, a core, or a cache first.
+
+```
+npm i swarmwire-lib hyperswarm
+```
+
+One side serves a file and prints a link. The other side hands the link to `download`:
+
+```js
+import process from 'process'
+import Hyperswarm from 'hyperswarm'
+import { Swarmwire } from 'swarmwire-lib'
+
+const [mode, target, out] = process.argv.slice(2)
+
+const swarm = new Hyperswarm()
+const node = new Swarmwire({ swarm })
+
+if (mode === 'send') {
+  const { link } = await node.serve(target)
+  console.log(link) // hand this to the other side; keep running while they fetch
+  await new Promise((resolve) => process.once('SIGINT', resolve))
+} else if (mode === 'get') {
+  await node.download(target, out)
+  console.log(out)
+}
+
+await node.destroy()
+await swarm.destroy()
+```
+
+This is `examples/send-get.js` without its `--bootstrap` option, which points both sides at a
+private DHT so the test suite needs no internet. It is an ES module, so your project needs
+`"type": "module"` or a `.mjs` file.
+
+```
+$ node examples/send-get.js send ./holidays.mp4
+swarmwire://10db6398a68dff502d002912f54502fdde9ab55fb30bec32861a2f004d874fc8?s=734003200&n=holidays.mp4
+
+$ node examples/send-get.js get 'swarmwire://10db63…' ./holidays.mp4
+./holidays.mp4
+```
+
+A folder goes the same way, as one link: `serveCollection` and `downloadCollection`.
+The command-line tool built on this library is moving to its own package,
+[`swarmwire-cli`](https://github.com/tibocub/swarmwire-cli) ([npm](https://www.npmjs.com/package/swarmwire-cli)).
+
+> Status: **pre-alpha.** Transfers work end to end, over a real swarm, with resume,
+> verification, request timeouts, partial seeding, rarest-first selection and an adaptive
+> request window. Behaviour with very many peers is not measured yet. See
+> [docs/roadmap.md](docs/roadmap.md) for what is built and what is next.
+
+## What it is
+
+A library that moves bytes between peers:
+
+- **Content-addressed.** A file's address is its BLAKE3 hash — the same value `b3sum` prints.
+  You ask for content, never for a peer, so any peer holding it can answer.
+- **Verified in transit.** Every received range is checked against the root hash before it
+  touches the destination file, using [bao](https://github.com/oconnor663/bao) verified
+  streaming. A lying peer is caught on its first bad range, not at the end of the download.
+- **Served in place.** A shared file is read from its existing path. There is no import step,
+  no second copy, no storage layer that owns your data.
+- **Swarm-shaped.** Many peers per transfer, partial seeders included, like BitTorrent —
+  but with Hyperswarm's DHT and holepunching instead of trackers.
+
+## What it is not
+
+- **Not a filesystem.** Names, directories, mutation, sharing and permissions live one layer
+  up, in SwarmFS. swarmwire only knows roots and bytes.
+- **Not a hypercore.** It never writes your content into a core, a blob store or a database.
+  (Hypercore/hypergraph are excellent at distributing the *references* — that is SwarmFS's job,
+  not this one.)
+- **Not BitTorrent-compatible.** It borrows BitTorrent's swarm algorithms, not its wire format.
+- **Not a live-stream transport.** Addresses name fixed content. Open-ended streams need an
+  append-only log; that is what hypercore is for.
+
+## Runtimes
+
+Node and Bare, with the same test suite passing on both — Bare because that is what mobile
+builds run on. See [AGENTS.md](AGENTS.md) for what that costs in practice.
+
+## Layering
+
+```
+  SwarmFS            virtual filesystem: names, directories, multi-writer, permissions
+     │               (hypergraph/hypercore hold the references)
+     ▼
+  swarmwire          roots → bytes: discovery, verified transfer, in-place serving
+     │
+     ▼
+  Hyperswarm         DHT discovery, holepunching, encrypted streams
+```
+
+The dependency runs one way. swarmwire must never import SwarmFS, hypergraph or hypercore.
+Anything that needs a name, a directory or a user belongs upstairs. See
+[`ECOSYSTEM.md`](../hypergraph/ECOSYSTEM.md) for how the wider family fits together.
+
+## Documentation
+
+| Document                           | What's in it                                                                                  |
+|------------------------------------|-----------------------------------------------------------------------------------------------|
+| [docs/format.md](docs/format.md)   | Addressing, verification, links, topic derivation — the parts that must never change casually |
+| [docs/contract.md](docs/contract.md) | What applications can rely on, supply and must not expect                                  |
+| [docs/roadmap.md](docs/roadmap.md) | Vision and milestones                                                                         |
+| [AGENTS.md](AGENTS.md)             | How to work in this repo                                                                      |
+
+## License
+
+MIT

package/docs/contract.md

@@ -0,0 +1,145 @@
+# swarmwire contract
+
+What an application built on `swarmwire-lib` (SwarmFS, `swarmwire-cli`, anything else) can rely on,
+what it can supply, and what swarmwire will never do. Only what is listed here is stable.
+Version 0.x: a minor release may change anything marked *exists* if this document and the
+changelog say so; anything marked *planned* is a direction, not a promise.
+
+## 1. Summary
+
+swarmwire takes a content root (a plain BLAKE3 hash) and returns verified bytes on disk, from
+whichever connected peers hold them. The application owns the network connection, keys, names,
+directories, users and permissions. A "folder" in this document is called a *collection* in the
+code (`serveCollection`, `downloadCollection`). See `AGENTS.md` for the invariants this contract rests on.
+
+## 2. Capabilities
+
+| Capability | Status | Delivered by | Proof |
+|---|---|---|---|
+| Serve a file in place, download by link, resume, verify every range | exists | - | `test/swarm/transfer.test.js` |
+| Serve and download a folder as one link | exists | - | `test/swarm/collection.test.js` |
+| Partial seeding: a download in progress serves what it holds | exists | - | `test/swarm/partial.test.js` |
+| Application supplies the network connection (any object with `join(topic, opts)` returning a session with `destroy()`, and a `connection` event; Hyperswarm is one) | exists | - | `test/helpers/network.js`, `test/net/real-swarm.test.js` |
+| Peer identity: the remote public key of the connection | exists | - | `test/swarm/transfer.test.js` |
+| Peer activity events, peer count, seeder and leecher counts | exists | - | `test/swarm/peers.test.js` |
+| Folder file-list reader (look-only, in memory), and downloading one listed file | exists | - | `test/swarm/list.test.js` |
+| Peer hints (preferred peers, priorities) | planned | 003 | - |
+| Admission decisions | planned | 003 | - |
+
+## 3. Rules the application can rely on
+
+### 3.1 Hints add options, never correctness
+
+A transfer completes correctly when every hint is wrong or stale. A hint cannot stall a transfer.
+A **peer hint** only changes which already-connected peers are asked first; swarmwire never dials
+a peer because of a hint. The application dials through the connection it owns.
+
+### 3.2 Admission
+
+The application can decide, per peer and per content, whether content is served.
+
+- Decided **per content root**. Each file of a folder is its own root and is decided separately;
+  the decision is told which folder root the file was requested through, if any. The folder's own
+  file list is content too, with its own root, and is decided like any other root.
+- **Deny on failure**: a decision that throws, times out or never answers is a deny. How long a
+  decision may take is an option of the admission mechanism, set by the application (its
+  default is chosen when the mechanism is built); the contract promises only that running out
+  of time is a deny.
+- A deny is answered **exactly as content swarmwire does not hold**. A refused peer learns nothing
+  about what is held, its size or its name.
+- With no decision installed, content is served as it is today.
+- A folder where some files are allowed and some denied transfers the allowed ones; the denied
+  ones read as absent, and the folder download reports which were unavailable.
+
+### 3.3 Peer activity
+
+`Swarmwire` is an event emitter.
+
+- `peer-connected` and `peer-disconnected`, each with `{ id }` (the remote public key, hex). Each
+  fires **once per distinct peer**, and only for a peer that completed the swarmwire handshake: a
+  connection that never speaks the protocol is neither announced nor counted. Two connections
+  from one key are one peer. A peer that vanishes without closing is reported when its connection
+  closes; `peerCount` is already correct when the event fires.
+- `peerCount`: connected peers, never negative.
+- `counts(link)` returns `{ peers, seeders, leechers }` for a file or folder link, synchronously.
+  A **seeder** holds all of it, a **leecher** holds part, and a peer that has said nothing about
+  that content is in `peers` only. For a folder, a seeder holds the file list and every listed
+  file; a peer holding the list alone is a leecher. Content the node knows nothing about, and a
+  folder whose list is not yet known, give zeros, never an error.
+- A node that only serves still learns what its peers hold: it asks each connected peer about
+  the content it serves, with the ordinary `want` message. No message was added. A peer that does
+  not answer is simply uncounted.
+
+**Direct connections only**: a snapshot that may lag, not a count of the swarm. Global counts and
+chunk rarity across the network are a tracker's job, not swarmwire's.
+
+### 3.4 Identity
+
+swarmwire knows the remote public key of each connection and nothing else about a peer. Tying a
+key to a user or device is the application's job (Principle II).
+
+### 3.5 Choosing files of a folder
+
+`readList(link)` reads a folder's file list without fetching any content: it resolves to
+`{ files: [{ path, root, size }], size }`, and `stop()` gives up waiting, like a download. It
+writes nothing to disk and only **looks** for peers: it never announces this node as a provider.
+A link that is not a folder is refused, and so is a list with an unsafe path (the same paths a
+whole-folder download refuses; nothing is repaired). `downloadFile(link, file, outPath)` then
+downloads one listed file, using only the folder's link and the list entry, and does not announce
+it separately. Which files, and any interface for choosing, belong to the application.
+
+### 3.6 The shared connection
+
+The application creates and destroys the swarm, owns its keypair, and may use the same connections
+for other protocols. swarmwire attaches to the `connection` event and leaves the connection alone
+when it is destroyed.
+
+## 4. What swarmwire will not do
+
+| Not in swarmwire | Where it lives |
+|---|---|
+| Names, directories, mutable references | SwarmFS |
+| Users, devices, permissions (it only asks, via admission) | Hypergraph, SwarmFS |
+| A tracker, global peer counts, global chunk rarity | SwarmFS (coarse, per file), not per chunk |
+| Choosing which files of a folder to download | SwarmFS or the CLI |
+| Storing content in a core, blob store or database | never |
+
+## 5. Exports
+
+The importable surface of `swarmwire-lib`. A test checks every name below exists.
+
+```exports
+Swarmwire
+Download
+rootOf
+formatLink
+parseLink
+discoveryTopic
+swarmTopic
+SCHEME
+ContentSource
+MemorySource
+encodeManifest
+decodeManifest
+isSafePath
+MANIFEST_TYPE
+Destination
+verifyGroup
+groupCount
+groupRange
+groupLength
+DEFAULT_GROUP_LOG
+```
+
+**Stable** (changes bump the version and are in the changelog): `Swarmwire`
+(`serve`, `serveCollection`, `download`, `downloadCollection`, `readList`, `downloadFile`,
+`unserve`, `destroy`, `peerCount`, `counts`; events `peer-connected`, `peer-disconnected`),
+`Download` (awaitable; events `progress`, `rejected`, `timeout`, `stalled`), `rootOf`,
+`formatLink`, `parseLink`, `SCHEME`.
+
+**Exported for tests and advanced use, may change in any 0.x**: everything else.
+
+## 6. Wire format
+
+Described in `docs/format.md`. Changes only deliberately; unknown messages are ignored so old
+peers survive new ones.

package/docs/format.md

@@ -0,0 +1,185 @@
+# The swarmwire format — v0
+
+Everything here ends up inside links that people share and store. Links must keep working after
+the engine has been rewritten three times, so this document changes slowly and deliberately,
+and everything in it is pinned by tests in `test/unit/`.
+
+## 1. Addressing
+
+**A content address is the 32-byte BLAKE3 hash of the content.** Nothing custom, nothing
+swarmwire-specific: it is the value `b3sum` prints, and the value any other BLAKE3 tool agrees
+on.
+
+Two consequences worth stating plainly:
+
+- **The same bytes always have the same address**, whoever hashed them, with whatever tool, at
+  whatever chunk size. Deduplication across peers and across apps is free.
+- **The address commits to the content's length.** BLAKE3's tree shape depends on the length, so
+  truncation and extension attacks are not possible. (SwarmFS's hand-rolled tree duplicated the
+  last node of an odd level, which made `[a,b,c]` and `[a,b,c,c]` collide. Dropping the custom
+  tree drops the bug.)
+
+Size and filename are **hints**, never part of the address. A peer may lie about either; the
+hash is what is enforced.
+
+## 2. Verification
+
+Ranges are verified with [bao](https://github.com/oconnor663/bao) verified streaming, as
+implemented by the pure-JavaScript `blake3-bao`.
+
+- A sender keeps an **outboard** tree for the content it serves — hashes only, no data copy.
+- For a requested byte range, the sender produces a **slice**: the range plus the minimal set of
+  tree nodes proving it belongs to the root.
+- The receiver verifies each slice against the root **before writing it to disk**. A peer that
+  sends one bad byte is caught immediately, not at the end of the transfer.
+
+**Chunk groups.** Standard bao verifies at 1 KiB granularity, which makes the outboard tree
+large. Grouping chunks shrinks it while keeping the same root hash:
+
+| Group size | Outboard for 1 GiB | Smallest verifiable unit |
+|---|---|---|
+| 1 KiB (plain bao) | ~64 MiB | 1 KiB |
+| **16 KiB (default)** | ~4 MiB | 16 KiB |
+| 256 KiB | ~256 KiB | 256 KiB |
+
+**Defaults: 16 KiB verification groups, 64 KiB request blocks.** 16 KiB is what the rest of the
+world converged on — BitTorrent v1's request block, BitTorrent v2's leaf block size, and
+bao-tree's default — so it is where we start, not where we must stay. Both numbers are
+negotiated per transfer and must be re-judged against real measurements once M2's benchmark
+exists; very large files may want bigger groups to keep outboards small.
+
+`blake3-bao` calls grouped encoding "Iroh chunk groups" because iroh popularised the technique.
+**swarmwire does not depend on iroh, Rust, or any native module.** Keeping the whole stack pure
+JavaScript is deliberate: it has to run on Bare for mobile.
+
+## 3. Links
+
+```
+swarmwire://<root-hex>[?s=<size>][&n=<name>][&k=<secret-hex>]
+```
+
+| Part | Meaning |
+|---|---|
+| `root-hex` | 64 lowercase hex characters: the BLAKE3 address |
+| `s` | Size hint in bytes. Lets the receiver preallocate and show progress before any peer answers. Unverified until the content is complete. |
+| `n` | Filename hint, percent-encoded. Display only — never used as a path without sanitising. |
+| `k` | 32-byte swarm key, hex. See §4. |
+| `t` | What the content is: `c` for a collection (§6). Absent means a plain file. |
+
+A link with no parameters is valid and sufficient: everything else is an optimisation or a
+privacy choice.
+
+**Why hex and not z32.** The Holepunch convention (`hypercore-id-encoding`) renders *Hypercore
+keys* as z-base-32 for users — 52 characters instead of 64, with visually ambiguous characters
+removed. A swarmwire root is not a key, it is a BLAKE3 hash, and the whole world prints those as
+hex: a link should be directly comparable to `b3sum <file>` output. Parsers may later accept
+z32 on input; swarmwire only ever emits hex.
+
+Unknown query parameters are ignored, so later versions can add hints without breaking today's
+parsers.
+
+## 4. Discovery
+
+Content is found through Hyperswarm topics derived by BLAKE3 with domain separation. There are
+two modes, and a peer may announce on both at once.
+
+### Content topics — "here is a link"
+
+```
+public:   topic = BLAKE3("swarmwire/v0/discovery" || root)
+private:  topic = BLAKE3("swarmwire/v0/discovery" || root || swarmKey)
+```
+
+Holding the link is enough to find peers: no topic to join, no tracker.
+
+**Public** behaves like a magnet link: every peer holding that content, anywhere, helps — and
+anyone who knows the address can discover that you have it. **Private** mixes in a 32-byte
+swarm key, so only people holding the link can derive the topic. The cost is that unrelated
+holders of the same content cannot help, so a private swarm is only as resilient as the people
+in it.
+
+`send` defaults to **private**. Sharing a file should not announce your holdings to anyone who
+can guess the hash; `--public` opts into the wider swarm.
+
+### Swarm topics — "here is a group of people"
+
+```
+topic = BLAKE3("swarmwire/v0/swarm" || swarmKey)
+```
+
+A swarm key identifies a *set of peers*, not a piece of content. Members announce on one topic,
+stay connected, and then ask each other for roots over the existing connection.
+
+This exists because the per-content topic does not scale to a shared workspace: a directory of
+a thousand files must not mean a thousand DHT announces. Dropping a file into a shared workspace
+should make it reachable by that workspace's members immediately, with no per-file setup and no
+authorisation step — which is exactly what SwarmFS needs for multi-writer virtual directories.
+
+swarmwire treats a swarm key as an opaque 32 bytes. Where it comes from — a link, a workspace,
+a hypergraph context — is SwarmFS's business, not this layer's.
+
+### Passphrases
+
+A swarm key is 32 bytes. When a link cannot be pasted — read aloud, typed from another screen —
+it may be *displayed* as a word sequence from a fixed wordlist, hyperbeam-style. That is a
+display encoding of the same bytes, never a second kind of secret: words in, bytes out, same
+topic. Not in v0.
+
+## 6. Collections
+
+A folder is shared as a **manifest**: a list of the files in it, each named by its address.
+The manifest is itself content, so it has an address like anything else — sharing a folder is
+sharing one link, and the receiver fetches the manifest first and then the files it names.
+
+```json
+{"swarmwire":"collection/v0","files":[{"path":"photos/one.jpg","root":"<hex>","size":70000}]}
+```
+
+The encoding is canonical, because the manifest's bytes are its identity and the same folder
+must produce the same address on every machine: entries sorted by path, no incidental
+whitespace, paths with forward slashes and no `.` segments. A folder packed on Windows and the
+same folder packed on Linux have the same address.
+
+**Paths are validated, never repaired.** A manifest arrives from a stranger, and a path is
+refused — rather than normalised — if it is absolute, contains `..`, is empty, carries a drive
+letter or control characters, or is simply not already canonical. Quietly turning
+`/etc/passwd` into `etc/passwd` would write somewhere the sender did not name. Two entries for
+the same path are refused too, since which one won would otherwise depend on arrival order.
+
+Collections are immutable, like everything else here: change a file and you have a different
+manifest with a different address. Folders that change are SwarmFS's problem, one layer up.
+
+**Discovery:** only the manifest's root is announced. The files are fetched over the
+connections that topic already produced, so a folder of a thousand files still costs one
+announce.
+
+## 5. Stability rules
+
+**Fixed for v0 — changing any of these invalidates existing links:**
+
+- The address is the plain BLAKE3 hash of the content
+- The link scheme, the hex encoding of the root, and the meaning of `s`, `n`, `k`, `t`
+- The collection manifest's encoding, including that entries are sorted by path
+- The domain-separation strings `swarmwire/v0/discovery` and `swarmwire/v0/swarm`
+
+**Free to change at any time** (negotiated per connection, never stored in a link): chunk group
+size, request block size, wire messages, scheduling, how outboard trees are cached, the sidecar
+format for partial downloads.
+
+The handshake carries a version and the group size (`groupLog`); it carries no capability set.
+Unknown message types are ignored rather than treated as errors, so new message types never
+break old peers.
+
+What a peer holds is learned by asking: `want` is answered with `have` (or `unavailable`) and
+followed by `holds` as the peer gains groups. A node that only serves sends `want` for what it
+serves, which is how it counts its seeders and leechers. No message exists for this.
+
+## Open questions
+
+1. **Which wordlist** for passphrases — BIP39 (2048 words, widely implemented, 24 words for 32
+   bytes) or a shorter custom list. Deferred until the feature is actually built.
+2. **Should a peer announce partial content on the content topic?** Announcing while still
+   downloading helps the swarm, but tells the topic you are interested before you have anything.
+   Measure in M2.
+3. **Per-size default group size.** A single 16 KiB default is one less rule to remember; a
+   size-dependent default keeps outboards small for very large files. Decide with the benchmark.

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * swarmwire - content-addressed file transfer between filesystems, over Hyperswarm.
+ *
+ * Runs on Node and on Bare. See docs/roadmap.md for what exists and what is next.
+ */
+
+export { Swarmwire, Download } from './lib/swarmwire.js'
+export { rootOf, formatLink, parseLink, discoveryTopic, swarmTopic, SCHEME } from './lib/address.js'
+export { ContentSource, MemorySource } from './lib/source.js'
+export { encodeManifest, decodeManifest, isSafePath, MANIFEST_TYPE } from './lib/collection.js'
+export { Destination } from './lib/destination.js'
+export { verifyGroup, groupCount, groupRange, groupLength, DEFAULT_GROUP_LOG } from './lib/tree.js'

package/lib/address.js

@@ -0,0 +1,166 @@
+/**
+ * Addressing: content roots, links, and the topics content is announced on.
+ *
+ * This is the part of swarmwire that ends up inside links other people keep, so it changes
+ * slowly and deliberately. See docs/format.md; every rule here is pinned by test/unit.
+ *
+ * Runs on Node and on Bare: no Buffer, no node builtins.
+ */
+
+import { blake3 } from './blake3.js'
+import b4a from 'b4a'
+
+export const SCHEME = 'swarmwire'
+
+/** Domain separation for topic derivation. Changing these strings splits the network. */
+const CONTENT_PREFIX = 'swarmwire/v0/discovery'
+const SWARM_PREFIX = 'swarmwire/v0/swarm'
+
+const HEX32 = /^[0-9a-f]{64}$/
+
+/**
+ * The content address of a buffer: the plain BLAKE3 hash, as `b3sum` prints it.
+ *
+ * @param {Uint8Array} content
+ * @returns {string} 64 lowercase hex characters
+ */
+export function rootOf (content) {
+  if (!(content instanceof Uint8Array)) throw new TypeError('content must be a Uint8Array')
+  return blake3.hashHex(content)
+}
+
+/**
+ * Build a link.
+ *
+ * @param {object} opts
+ * @param {string} opts.root - 64 hex characters
+ * @param {number} [opts.size] - size hint in bytes
+ * @param {string} [opts.name] - filename hint, for display only
+ * @param {string} [opts.secret] - 64 hex characters: the swarm key for a private swarm
+ * @param {'collection'|null} [opts.type] - what the content is, when it is not a plain file
+ * @returns {string}
+ */
+export function formatLink ({ root, size = null, name = null, secret = null, type = null } = {}) {
+  assertHex32(root, 'root')
+  if (secret !== null) assertHex32(secret, 'secret')
+  if (size !== null && !isSize(size)) throw new Error('size must be a non-negative integer')
+  if (type !== null && type !== 'collection') throw new Error('unknown link type')
+
+  const params = []
+  if (size !== null) params.push('s=' + size)
+  if (name !== null) params.push('n=' + encodeURIComponent(name))
+  if (secret !== null) params.push('k=' + secret)
+  if (type === 'collection') params.push('t=c')
+
+  return `${SCHEME}://${root}` + (params.length ? '?' + params.join('&') : '')
+}
+
+/**
+ * Parse a link. Hints are returned as given: validating a name against a destination path is
+ * the caller's job, and this must not silently "fix" a hostile one.
+ *
+ * @param {string} link
+ * @returns {{root: string, size: number|null, name: string|null, secret: string|null,
+ *   type: 'collection'|null}}
+ */
+export function parseLink (link) {
+  if (typeof link !== 'string') throw new TypeError('link must be a string')
+
+  const prefix = `${SCHEME}://`
+  if (!link.startsWith(prefix)) throw new Error(`link must use the ${SCHEME}:// scheme`)
+
+  const rest = link.slice(prefix.length)
+  const q = rest.indexOf('?')
+  const root = q === -1 ? rest : rest.slice(0, q)
+  assertHex32(root, 'root')
+
+  const out = { root, size: null, name: null, secret: null, type: null }
+  if (q === -1) return out
+
+  for (const pair of rest.slice(q + 1).split('&')) {
+    if (pair === '') continue
+    const eq = pair.indexOf('=')
+    const key = eq === -1 ? pair : pair.slice(0, eq)
+    const value = eq === -1 ? '' : pair.slice(eq + 1)
+
+    switch (key) {
+      case 's': {
+        const size = Number(value)
+        if (!isSize(size)) throw new Error('size hint must be a non-negative integer')
+        out.size = size
+        break
+      }
+      case 'n':
+        out.name = decodeURIComponent(value)
+        break
+      case 'k':
+        assertHex32(value, 'secret')
+        out.secret = value
+        break
+      case 't':
+        // A hint, like the others: the content is checked when it arrives, and a link that
+        // lies about this produces a manifest that does not parse, not a wrong folder.
+        out.type = value === 'c' ? 'collection' : null
+        break
+      default:
+        // Unknown parameters are ignored, so later versions can add hints without
+        // breaking today's parsers.
+        break
+    }
+  }
+
+  return out
+}
+
+/**
+ * The topic a single piece of content is announced on — what a link resolves through.
+ *
+ * With a swarm key, only holders of the link can derive it; without one, anyone who knows the
+ * content's address can.
+ *
+ * @param {string} root - 64 hex characters
+ * @param {string|null} [swarmKey] - 64 hex characters
+ * @returns {Uint8Array} 32 bytes
+ */
+export function discoveryTopic (root, swarmKey = null) {
+  assertHex32(root, 'root')
+  if (swarmKey !== null) assertHex32(swarmKey, 'swarmKey')
+
+  const parts = [b4a.from(CONTENT_PREFIX, 'ascii'), b4a.from(root, 'hex')]
+  if (swarmKey !== null) parts.push(b4a.from(swarmKey, 'hex'))
+
+  return hash(parts)
+}
+
+/**
+ * The topic a *group of peers* meets on, independent of what they hold.
+ *
+ * Members announce once and then ask each other for roots over the connection, so a shared
+ * workspace of a thousand files costs one announce rather than a thousand. Where the swarm key
+ * comes from — a link, a workspace, a hypergraph context — is the caller's business.
+ *
+ * @param {string} swarmKey - 64 hex characters
+ * @returns {Uint8Array} 32 bytes
+ */
+export function swarmTopic (swarmKey) {
+  assertHex32(swarmKey, 'swarmKey')
+  return hash([b4a.from(SWARM_PREFIX, 'ascii'), b4a.from(swarmKey, 'hex')])
+}
+
+function hash (parts) {
+  return b4a.from(blake3.hashHex(toU8(b4a.concat(parts))), 'hex')
+}
+
+function toU8 (buf) {
+  return buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+}
+
+function assertHex32 (value, what) {
+  if (typeof value !== 'string' || !HEX32.test(value)) {
+    throw new Error(`${what} must be 64 lowercase hex characters`)
+  }
+}
+
+function isSize (n) {
+  return Number.isInteger(n) && n >= 0
+}

package/lib/blake3.cjs

@@ -0,0 +1,15 @@
+/**
+ * BLAKE3 and bao, reached through CommonJS.
+ *
+ * `blake3-bao`'s ESM entry points are thin wrappers that call `createRequire` from Node's
+ * `module` builtin, which does not exist on Bare — so importing them directly makes the whole
+ * library Node-only. The CommonJS files underneath are plain JavaScript and load identically
+ * on both runtimes, so this is the one place that reaches for them.
+ *
+ * Verified: the same input hashes to the same value under Node and Bare.
+ */
+
+const blake3 = require('blake3-bao/blake3')
+const bao = require('blake3-bao/bao')
+
+module.exports = { blake3, bao }