@le-space/orbitdb-storage-bridge 0.14.1 → 0.16.0

package/README.md

@@ -1,348 +1,109 @@
 # OrbitDB Storage Bridge
 
-> **OrbitDB database backup, restoration and replication through pluggable storage backends, with hash and identity preservation**
-
+> Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
 [![CI/CD Pipeline](https://github.com/NiKrause/orbitdb-storage-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/NiKrause/orbitdb-storage-bridge/actions/workflows/ci.yml)
-[![ESLint](https://img.shields.io/badge/ESLint-passing-brightgreen.svg)](https://github.com/NiKrause/orbitdb-storage-bridge/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@le-space/orbitdb-storage-bridge.svg)](https://www.npmjs.com/package/@le-space/orbitdb-storage-bridge)
 
 > [!NOTE]
-> **Renamed from `orbitdb-storacha-bridge`.** Up to 0.6.0 this package was published as
-> `orbitdb-storacha-bridge`. From 0.7.0 it is `@le-space/orbitdb-storage-bridge`, because Storacha is no
-> longer the only backend it bridges to. The rename changes no API — swap the dependency and the
-> import specifiers:
->
-> ```bash
-> npm uninstall orbitdb-storacha-bridge
-> npm install @le-space/orbitdb-storage-bridge
-> ```
->
-> `orbitdb-storacha-bridge/courier-sync` becomes `@le-space/orbitdb-storage-bridge/courier-sync`, and so on
-> for every entry point. Names that refer to Storacha itself stay as they are:
-> `OrbitDBStorachaBridge`, `StorachaIntegration.svelte`, `backends/storacha`, the `storacha_*`
-> localStorage keys that hold saved logins — and so does the debug namespace
-> `libp2p:orbitdb-storacha:*`.
-
-
-> [!IMPORTANT]
-> **The Storacha upload service is gone.** Writes were switched off in May 2026 and the
-> service has since been decommissioned. Backup no longer works, and restore only reaches
-> blocks that something other than Storacha still holds. See
-> [Status: Storacha sunset](#status-storacha-sunset-may-2026) and
-> [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) for where to go instead.
-
-
-## Table of Contents
-
-- [OrbitDB Storage Bridge](#@le-space/orbitdb-storage-bridge)
-  - [Table of Contents](#table-of-contents)
-  - [Status: Storacha sunset (May 2026)](#status-storacha-sunset-may-2026)
-  - [What we want to accomplish](#what-we-want-to-accomplish)
-    - [The Challenge of Distributed Data Persistence](#the-challenge-of-distributed-data-persistence)
-    - [Architectural Considerations for Local-First Applications](#architectural-considerations-for-local-first-applications)
-    - [Use Cases](#use-cases)
-    - [Architecture Notes](#architecture-notes)
-  - [What This Does](#what-this-does)
-  - [Roadmap](#roadmap)
-  - [Installation](#installation)
-  - [Environment Setup](#environment-setup)
-  - [Demo](#demo)
-    - [NodeJS Demo Scripts (full backup with Manifest, Identity and AccessController and entries blocks)](#nodejs-demo-scripts-full-backup-with-manifest-identity-and-accesscontroller-and-entries-blocks)
-    - [Svelte Components](#svelte-components)
-  - [How It Works](#how-it-works)
-  - [Restore Mechanism](#restore-mechanism)
-  - [Logging](#logging)
-  - [Testing](#testing)
-  - [Contributing](#contributing)
-  - [License](#license)
-
-
-## Does this work from a browser? Measure it
-
-`examples/browser/storage-probe/` is a static page that asks the services this package talks to,
-from a real browser, with no server: do Aleph, Pinata and Lighthouse answer a page at all, does
-their CORS survive a refusal as well as a success, and does anybody on IPFS hold a given CID at an
-address a browser can dial. With your own key it does a real upload and reads it back. The key is
-kept in that browser and sent only to the service it belongs to.
-
-It is published from this repository's Pages, and it opens from a checkout just as well — there is
-no build step, which is the point: what it measures is a browser talking to a service, with
-nothing in between.
-
-## Status: Storacha sunset (May 2026)
-
-Storacha switched off user writes in **May 2026** and has since decommissioned the service.
-Verified on 2026-09-05:
-
-| Check | Result |
-| --- | --- |
-| `up.storacha.network`, `console.storacha.network`, `indexer.storacha.network`, `forge.storacha.network` | no DNS record — upload, console and indexing endpoints are gone |
-| `storacha.network`, `docs.storacha.network` | `301` → `fil.one`, the team's new S3-compatible product |
-| `storacha.link`, `w3s.link` | `301` → `dweb.link`; the gateways only forward to the public IPFS gateway now |
-| the widget demo CID linked in the roadmap below | `504` on `w3s.link`, `dweb.link`, `ipfs.io` and `trustless-gateway.link` |
-| `@storacha/client` on npm | last release `2.1.4`, 2026-05-15, not marked deprecated |
-
-The gateway those redirects pointed at is gone too. On **2026-09-21** Protocol Labs retired
-`ipfs.io` and `dweb.link`: both answer `429` with an RFC 8594 `Sunset` header and a link to
-[gatewaychanges.ipfs.io](https://gatewaychanges.ipfs.io/), so `storacha.link` and `w3s.link`
-now redirect to a closed door. Retrieval defaults here are `ipfs.aleph.cloud` — the one free
-path gateway measured still serving arbitrary CIDs on 2026-09-23 — with
-`trustless-gateway.link` available for verifiable single-block requests
-(`Accept: application/vnd.ipld.raw`). One host is not a fallback chain, which is why `peer-fetch.js` fetches from the providers that
-hold the blocks instead — bitswap over libp2p, measured from a real page at 0.73 s to dial and
-0.26 s for the block, with no credential in the path. See
-[docs/RECOVERY-ON-A-SECOND-DEVICE.md](docs/RECOVERY-ON-A-SECOND-DEVICE.md).
-
-The shutdown is traceable in the open:
-[`upload-service#708`](https://github.com/storacha/upload-service/pull/708) added a `writesDisabled`
-kill switch that makes the eight user-initiated write capabilities
-(`space/blob/{add,remove,replicate}`, `space/index/add`, `upload/{add,remove}`, `store/{add,remove}`)
-return `ServiceUnavailable`, and [`w3infra#636`](https://github.com/storacha/w3infra/pull/636) wired
-`WRITES_DISABLED=true` into the production stack — both merged 2026-05-15. Five days later Storacha
-shipped `storacha space migrate`
-([`@storacha/filecoin-pin-migration`](https://www.npmjs.com/package/@storacha/filecoin-pin-migration)),
-a migration path from Storacha spaces to Filecoin Onchain Cloud. That tool reads spaces through
-endpoints that no longer resolve, so the official migration window has closed.
-
-We found no announcement page: the Storacha blog now redirects to `fil.one/blog`, which carries a
-single post ("Introducing Fil One", 2026-08-12). The dates above come from the code and the DNS,
-not from a press release.
-
-**What this means for this library**
-
-- **Backup does not work.** Every write path ends in `client.uploadFile()` against `up.storacha.network`.
-- **Restore only reaches what someone else still holds.** The p2p-first path still finds blocks that a
-  peer or another pinning service pins; the gateway fallback and the `capability.upload.list`
-  discovery step cannot reach Storacha any more.
-- **The OrbitDB half is unaffected.** Block extraction, CID bridging, CAR packing, identity
-  preservation, UCAN signing and courier-sync are backend-agnostic — only the handful of Storacha
-  client methods mapped in [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) need a new home.
-
-If you still have an OrbitDB instance with the blocks in it, re-pin them somewhere else now: the data
-is only as alive as the peers that hold it.
-
-
-## What we want to accomplish
-
-### The Challenge of Distributed Data Persistence
-
-In local-first, peer-to-peer applications built on OrbitDB, data naturally replicates across participating peers through libp2p network connections. Under ideal conditions, this distributed architecture provides inherent redundancy—if one peer loses data, they can resynchronize from other active peers in the network. This peer-to-peer replication model represents the current state of OrbitDB technology.
-
-While relay nodes and pinning services (running Helia and OrbitDB instances) can provide additional decentralized persistence for database entries and IPFS-referenced content, the ecosystem still lacks comprehensive infrastructure for long-term archival of large-scale OrbitDB deployments.
-
-### Architectural Considerations for Local-First Applications
-
-OrbitDB's data model differs fundamentally from traditional centralized databases. In local-first architectures, users typically host their own data locally and selectively replicate with specific peers based on collaboration requirements—not with the entire network. This selective replication is essential for scalability and user experience.
-
-However, as OrbitDB instances grow (consider a blog database accumulating years of posts), replication times increase proportionally. At scale, databases require archival strategies and potential sharding to maintain performant synchronization and optimal user experience.
-
-### Use Cases
-
-This bridge addresses several critical scenarios:
-
-**1. Long-term Archival**
-Archive large OrbitDB instances to Storacha/Filecoin storage, enabling efficient cold storage for historical data while maintaining fast replication of active datasets.
-
-**2. Disaster Recovery**
-Provides recovery options when all active peers lose data simultaneously. Users can restore databases from Storacha using either their original identity or a new identity, ensuring business continuity beyond the peer-to-peer network's availability.
-
-**3. Network Resilience**
-Historically, various network environments (corporate networks, ISPs, regional restrictions) have blocked critical protocols including WebRTC and WebSocket/WebTransport. While libp2p's multi-transport architecture provides numerous fallback options, having an additional restoration pathway through IPFS/Storacha offers defense-in-depth for network-hostile environments. Users can restore databases directly from IPFS and maintain incremental backups after each database mutation.
-
-**4. Access Control & Delegation**
-The bridge supports UCAN (User Controlled Authorization Networks) authentication with planned delegation capabilities between OrbitDB instances. This enables fine-grained, time-bound access control for Storacha backup spaces, allowing users to securely share access with collaborators or recovery agents.
-
-### Architecture Notes
-
-Currently, Storacha backup and restore operations utilize Storacha's gateway infrastructure to interface with Filecoin's decentralized storage network. This hybrid approach balances accessibility with decentralization during the current phase of the Filecoin ecosystem's evolution.
-
-That description is now historical: the gateway infrastructure it relies on was decommissioned in 2026 (see [Status: Storacha sunset](#status-storacha-sunset-may-2026)). The hybrid shape of the design still holds — a backend that stores bytes, an IPFS network that serves them — but the backend slot is open. [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) compares the candidates.
-
-## What This Does
-
-Backup and restore between **OrbitDB databases** and **Storacha/Filecoin** with full hash and identity preservation. Works in both Node.js and browser environments.
-
-The project includes **Svelte components** for browser-based demos and integration (see [SVELTE-COMPONENTS.md](SVELTE-COMPONENTS.md) for detailed documentation).
-
-**Features:**
-
-- backup/restore between OrbitDB and Storacha in browsers and NodeJS via Storacha key and proof credential
-  - full backup per space
-  - timestamped backups (multiple backups per space - restore last backup by default)
-- Storacha Svelte components for integration into Svelte projects
-- UCAN authentication 
-- Backup/restore functionality with hash and identity preservation
-- OrbitDB CAR file storage [OrbitDB CustomStorage](https://github.com/orbitdb/orbitdb/blob/main/docs/STORAGE.md)
-
-## Roadmap
-
-> Being re-based on a backend interface instead of a single vendor — the plan is
-> [issue 54](https://github.com/NiKrause/orbitdb-storage-bridge/issues/54), not here. The WebAuthn/varsig items below survive
-> unchanged; the Storacha-named ones become backend-agnostic.
-
-- [ ] Live parallel persistence: hand an open database a backend-backed OrbitDB `ComposedStorage`, so every block is written to a backend **as it is created** — during sync and after each update — rather than only when a backup runs.
-  - [ ] Today a block becomes durable somewhere else only if bitswap reaches a peer that keeps it, gossipsub reaches a subscriber, or somebody runs a backup. All three depend on another party being reachable at that moment; a write-through storage does not.
-  - [ ] The seam already exists: [`lib/car-storage.js`](lib/car-storage.js) implements OrbitDB's storage shape (`put`/`get`/`del`/`iterator`/`merge`) against a CAR file, and `ComposedStorage` is designed to fan a write out to more than one place. This points the same seam at a network backend instead.
-  - [ ] Aleph Cloud is the first candidate, because it is the only evaluated backend a browser can write to with no key at all — `POST /api/v0/add` answers unauthenticated with an open CORS header. See [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md); persistence there needs the wallet-signed STORE message, not the ingest alone.
-  - [ ] Open question worth settling first: what a write-through storage does when the backend is unreachable. Blocking a local write on a network round trip would make the database only as available as the backend, which is the opposite of the point — so it queues, and the queue is the design.
-
-- [ ] v0.4.4 (Feb 2026): Latest-backup pointer (single CID) to avoid listing via the Storacha SDK and restore from the IPFS network for initial OrbitDB syncs.
-  - [ ] After each backup, write a small pointer record (JSON) that stores the latest metadata CID, CAR CID, and last heads (block CID).
-  - [ ] Store that pointer in a user-controlled place (local storage, QR/share link, WebAuthN largetBlog extension or file download).
-- [ ] v0.5.0 (Feb 2026): OrbitDB CustomStorage (StorachaStorage) ([issue 23](https://github.com/NiKrause/orbitdb-storage-bridge/issues/23)).
-- [ ] v0.6.0 (Mar 2026): WebAuthN + varsig signing/verification (Ed25519 and P-256) for OrbitDB oplog. https://github.com/ChainAgnostic/varsig/blob/main/README.md
-- [ ] v0.6.1 (Mar 2026): WebAuthN + SimpleEncryption example that uses WebAuthN+PRF key material for encrypted backups and restore.
-- [ ] v0.7.0 (Apr 2026): WebAuthN + OrbitDB AccessController (store a UCAN instead of only a DID for admin/write access).
-  - [ ] Alice (authenticated via UCAN or Storacha credentials) can delegate/revoke access for Bob with custom/default capabilities ([issue 16](https://github.com/NiKrause/orbitdb-storage-bridge/issues/16)). See [WebAuthN Upload Wall](https://github.com/NiKrause/ucan-upload-wall/tree/browser-only/web) and the [live demo](https://bafybeibdcnp7pr26okzr6kbygcounsz3klyg3vydxwwovmz2ljyzfmprre.ipfs.w3s.link/).
-- [ ] v0.7.1 (May 2026): Storacha Backup & Restore Svelte widget with WebAuthN-varsig UCAN signing/verification (Ed25519/P-256).
-- [ ] v0.7.2 (May 2026): Storacha Backup & Restore React widget with WebAuthN-varsig UCAN signing/verification (Ed25519/P-256).
-- [ ] v0.7.3 (May 2026): Storacha Backup & Restore React widget with WebAuthN-varsig UCAN delegation (Ed25519/P-256).
-- [ ] v0.7.4 (May 2026): UI enhancement for the Storacha Backup & Restore widget (timestamped backup restore and management).
-- [ ] v0.8.0 (Jun 2026): Upgrade to UCAN 1.0 support.
-- [ ] v0.9.0 (Jul 2026): Social backup between devices with DKG (decentralized key generation).
-- [ ] v0.10.0 (Aug 2027): WebAuthN + Roaming Credentials: Have a browser and a mobile with one Yubikey creating one and the same DID and replicating the same OrbitDB
-
-Read more on Medium: [Bridging OrbitDB with Storacha: Decentralized Database Backups](https://medium.com/@akashjana663/bridging-orbitdb-with-storacha-decentralized-database-backups-44c7bee5c395)
-
-## Installation
-
-Install the package via npm:
+> Published as `orbitdb-storacha-bridge` up to 0.6.0 and as `@le-space/orbitdb-storage-bridge`
+> from 0.7.0, because Storacha is no longer the only backend it bridges to. The rename changed no
+> API — only the dependency and the import specifiers. Names that refer to Storacha itself stay as
+> they are: `OrbitDBStorachaBridge`, `backends/storacha`, and the `libp2p:orbitdb-storacha:*` debug
+> namespace.
+
+## What it does
+
+An OrbitDB database is a set of content-addressed blocks and a log whose heads tie them together.
+This package moves those blocks somewhere else and brings them back with their CIDs and the
+writer's identity intact — so a restored database is the same database, and its original author can
+still write to it.
+
+Where "somewhere else" is, is a choice:
+
+| Backend | Needs | |
+| --- | --- | --- |
+| `aleph` | nothing | the only backend a browser can write to with no key; ingest only |
+| `aleph-pin` | a wallet | the signed STORE message that makes Aleph keep it |
+| `pinata` | a scoped JWT | pin-by-CID as well as CAR upload |
+| `lighthouse` | an API key | pay once, stored in perpetuity |
+| `memory` | nothing | in-process, for tests and demos |
+| `mirror` | — | wraps others: one backup, several services |
+| `encryption` | — | wraps one: the service holds ciphertext |
+
+Reading back needs no account, because a CID is a name anyone can resolve: `peer-fetch` asks the
+peers that hold the blocks over libp2p, `gateway-fetch` asks an HTTP gateway. Two more entry
+points do not involve a storage service at all — `courier-sync` replicates over any byte courier
+(a LoRa mesh, a QR relay, a file), and `dehydrate`/`hydrate` put a database where a second device
+can find it from a passkey alone.
+
+## Install
 
 ```bash
 npm install @le-space/orbitdb-storage-bridge
 ```
 
-## Environment Setup
-
-`STORACHA_KEY` and `STORACHA_PROOF` in `.env` are still what the code reads, and existing credentials still parse — but there is no longer a service to present them to, and no way to mint new ones: the console and the quickstart docs are gone (see [Status: Storacha sunset](#status-storacha-sunset-may-2026)). The test suite's in-memory modes run without credentials; see `test/README.md`.
-
-## Demo
-
-### NodeJS Demo Scripts (full backup with Manifest, Identity and AccessController and entries blocks)
+## Quick start
 
-They back up to Aleph by default, which takes an upload without an account, so
-they run straight after cloning. `STORAGE=pinata` and `STORAGE=lighthouse`
-switch to the paid services and read their keys from the environment — see
-[`examples/storage.js`](examples/storage.js).
+The demos back up to Aleph, which accepts an upload without an account, so they run straight after
+cloning:
 
 ```sh
-node examples/backup-demo.js                          # prints the backup's CID
-BACKUP_CID=<cid> node examples/restore-demo.js        # restores it on a fresh node
+node examples/backup-demo.js                     # prints the backup's CID
+BACKUP_CID=<cid> node examples/restore-demo.js   # restores it on a node that has never seen it
 ```
 
-- `node` [`examples/demo.js`](examples/demo.js) - Complete backup/restore cycle, including what stops the second node from writing
-- `node` [`examples/backup-demo.js`](examples/backup-demo.js) - Backup only; prints the CID the restore needs
-- `node` [`examples/restore-demo.js`](examples/restore-demo.js) - Restore from that CID onto a node that has never seen the database
-- `node` [`examples/demo-different-identity.js`](examples/demo-different-identity.js) - Different identities with access control enforcement
-- `node` [`examples/demo-shared-identities.js`](examples/demo-shared-identities.js) - Shared identity backup/restore scenarios
-
-An Aleph upload is not kept: staying stored takes a wallet-signed STORE message
-this library does not send, so restore what you back up while the demo is still
-running.
-
-The scripts written against Storacha's space and UCAN model are in
-[`examples/storacha/`](examples/storacha/README.md). None of them runs end to
-end since the uploads stopped, and the README there says what replaced each.
-
-### In a browser: a database back on a device that has nothing
-
-[**funkpost's recovery page**](https://nikrause.github.io/funkpost/recovery/) runs the whole
-[recovery procedure](docs/RECOVERY-ON-A-SECOND-DEVICE.md) in a phone's browser, with a
-security key and nothing else ([source](https://github.com/NiKrause/funkpost/tree/main/examples/recovery)):
+`STORAGE=pinata` and `STORAGE=lighthouse` switch backends and read their keys from the environment
+— see [`examples/storage.js`](examples/storage.js). An Aleph upload is not retained without the
+signed STORE message, so restore what you back up while the demo is still running.
 
-1. **the key gives the identity** — the DID, and a signing key derived from its PRF output,
-   the same on every device;
-2. **a list** is made and written to;
-3. **`dehydrate`** backs it up to Aleph as a CAR, and publishes an IPNS pointer under a name
-   the key derives;
-4. **on another device** — or the same one, wiped — the same key finds the pointer, **`hydrate`**
-   brings the list back, and the list takes new entries, because the writer is the same.
+Further scripts: identity and access-control scenarios in [`examples/`](examples/), and the
+Storacha-era scripts in [`examples/storacha/`](examples/storacha/README.md), none of which runs end
+to end any more.
 
-On 21 September 2026 it ran that way on two phones: a Galaxy Fold 5 backed up and was reset,
-and a Galaxy A57 with the same key brought the list back and wrote to it. The page says at
-every step which service it contacts; the technical details sit behind one button.
+## Recovery on a second device
 
-### Svelte Components
+[The recovery page](https://nikrause.github.io/orbitdb-storage-bridge/recovery/) runs the whole
+procedure in a phone's browser with a security key and nothing else: the passkey gives the
+identity, `dehydrate` backs the database up and publishes an IPNS pointer under a name derived from
+the key, and on another device the same key finds that pointer — so `hydrate` needs no CID, no
+address and no file. The restored database takes new entries, because the writer is the same.
 
-For browser-based integration, this project includes Svelte components for authentication, backup/restore, P2P replication, and WebAuthn biometric authentication. See [**SVELTE-COMPONENTS.md**](SVELTE-COMPONENTS.md) for complete documentation of all available components and demonstrations.
+On 21 September 2026 it ran that way on two phones: a Galaxy Fold 5 backed up and was reset, and a
+Galaxy A57 with the same key brought the database back and wrote to it. Source:
+[`examples/svelte/recovery/`](examples/svelte/recovery).
 
-That browser side is older than this repository's copy of it, and the UCAN delegation work now sits on a branch. [docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md) records what existed, what it could do, and where each piece is today.
+## Documentation
 
-## How It Works
-
-1. **Extract Blocks** - Separates OrbitDB database into individual components (log entries, manifest, identities, access controls)
-2. **Upload to Storacha** - Each block is uploaded separately to IPFS/Filecoin via Storacha
-3. **Block Discovery** - Lists all files in Storacha space using Storacha SDK APIs
-4. **CID Bridging** - Converts between Storacha CIDs (`bafkre*`) and OrbitDB CIDs (`zdpu*`)
-5. **Reconstruct Database** - Reassembles blocks and opens database with original identity
-
-## Restore Mechanism
-
-The restore process uses a **ipfs-p2p-first approach with ipfs-http-gateway fallback** for downloading backups for restore. File listing and metadata discovery are currently performed via the Storacha SDK (using Storacha gateway API). We are working on an **IPNS-based mechanism** to find the latest heads blocks and OrbitDB address directly from the IPFS network via IPNS, eliminating the need to list all files via the centralized Storacha gateway API.
-
-## Logging
-
-The library uses **@libp2p/logger** for consistent logging across the libp2p ecosystem. Control logging with the `DEBUG` environment variable:
-
-**Node.js:**
-```bash
-# Enable all logs from this library (the namespace kept its old name)
-DEBUG=libp2p:orbitdb-storacha:* node your-script.js
-
-# Enable specific components
-DEBUG=libp2p:orbitdb-storacha:bridge node your-script.js
-
-# Enable all libp2p logs (includes this library + libp2p internals)
-DEBUG=libp2p:* node your-script.js
-```
-
-**Browser:**
-```javascript
-// In browser console or before loading the application
-localStorage.setItem('debug', 'libp2p:orbitdb-storacha:*')
-// Then refresh the page
-```
-
-The logger supports printf-style formatting:
-- `%s` - string
-- `%d` - number
-- `%o` - object
-- `%p` - peer ID
-- `%b` - base58btc encoded data
-- `%t` - base32 encoded data
-
-## Testing
-
-See `test/README.md` for detailed test documentation, modes (in-memory vs production),
-and how to run each suite.
+| | |
+| --- | --- |
+| [docs/DESIGN.md](docs/DESIGN.md) | the problem this solves, and how a backup and a restore actually work |
+| [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) | every backend evaluated — prices, limits, and what has been verified against a live account |
+| [docs/RECOVERY-ON-A-SECOND-DEVICE.md](docs/RECOVERY-ON-A-SECOND-DEVICE.md) | the passkey recovery procedure, step by step |
+| [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | CAR-based timestamped backups |
+| [SVELTE-COMPONENTS.md](SVELTE-COMPONENTS.md) | the browser components — older than this repository's copy of them; [docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md) records what each piece could do and where it went |
+| [docs/LOGGING.md](docs/LOGGING.md) | debug namespaces, in Node and in a browser |
+| [ROADMAP.md](ROADMAP.md) | what is planned |
+| [docs/STORACHA-SUNSET.md](docs/STORACHA-SUNSET.md) | why Storacha stopped being the default, with dates and evidence |
+| [test/README.md](test/README.md) | the suites, and which of them need credentials |
+
+`examples/browser/storage-probe/` is a static page that asks these services from a real browser
+with no build step: whether they answer a page at all, whether their CORS survives a refusal as
+well as a success, and whether anyone on IPFS holds a given CID at an address a browser can dial.
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Submit a pull request
+Fork, branch, add tests for new behaviour, open a pull request.
 
 ## License
 
-MIT License
-
-## Trademarks
-
-LoRa® is a trademark of Semtech Corporation. Meshtastic® is a registered
-trademark of Meshtastic LLC. Other names used here — OrbitDB, IPFS, Filecoin,
-Storacha, Pinata, Lighthouse, Aleph — belong to their respective owners and
-appear only to say what this package interoperates with. This project is not
-affiliated with or endorsed by any of them.
+MIT.
 
-The first two appear in this repository only in prose about what the courier
-seam is *for*: `courier-sync` is transport-neutral and this package contains no
-code from either project and depends on neither. That is deliberate rather than
-incidental. The Meshtastic client libraries (`@meshtastic/core`,
-`@meshtastic/transport-web-bluetooth`) are **GPL-3.0-only**, and the courier
-that drives them lives in [funkpost](https://github.com/NiKrause/funkpost), on
-the GPL side of that line. This package is MIT and stays that way; the door
-only opens one way.
+LoRa® is a trademark of Semtech Corporation and Meshtastic® a registered trademark of Meshtastic
+LLC; OrbitDB, IPFS, Filecoin, Storacha, Pinata, Lighthouse and Aleph belong to their respective
+owners and appear here only to say what this package interoperates with. This project is
+affiliated with none of them and contains no code from the Meshtastic libraries, which are
+GPL-3.0-only — see [docs/TRADEMARKS.md](docs/TRADEMARKS.md) for why that line matters and which
+side of it this package is on.

package/lib/backends/aleph-pin.js

@@ -65,16 +65,21 @@ async function sha256Hex(payload) {
  * Exported so it can be tested without a wallet, and read without running one.
  *
  * @param {object} args
- * @param {string} args.sender - the wallet address
+ * @param {string} args.sender - the wallet address that signs
+ * @param {string} [args.owner] - the account the STORE is for, when the sender
+ *   signs on its behalf (see {@link createAlephAuthorizer}); the sender itself
+ *   by default
  * @param {string} args.cid - what to keep
  * @param {string} [args.channel]
  * @param {number} [args.now] - seconds; injected so a test is not a clock
  * @param {(payload: string) => Promise<string>} [args.hasher]
  */
-export async function buildStoreMessage({ sender, cid, channel = DEFAULT_ALEPH_CHANNEL, now, hasher = sha256Hex }) {
+export async function buildStoreMessage({ sender, owner, cid, channel = DEFAULT_ALEPH_CHANNEL, now, hasher = sha256Hex }) {
   const time = now ?? Date.now() / 1000;
   const content = {
-    address: sender,
+    // Whose STORE this is. Equal to the sender unless the owner's `security`
+    // aggregate authorizes the sender to send it on the owner's behalf.
+    address: owner || sender,
     // "the thing to keep is an IPFS CID" — not the envelope's item_type
     item_type: "ipfs",
     item_hash: cid,
@@ -102,7 +107,9 @@ export const signaturePayload = (message) =>
  * A `pin` function for {@link createAlephBackend}.
  *
  * @param {object} options
- * @param {string} options.sender - the wallet address doing the keeping
+ * @param {string} options.sender - the wallet address that signs
+ * @param {string} [options.owner] - the account the STORE is for, when it has
+ *   authorized `sender` (a delegate) to send STORE messages on its behalf
  * @param {(address: string, message: string) => Promise<string>} options.sign -
  *   `personal_sign`, or anything shaped like it. The library never sees a key.
  * @param {string} [options.apiHost]
@@ -113,7 +120,7 @@ export const signaturePayload = (message) =>
  * @returns {(cid: string, meta?: object) => Promise<{ itemHash: string, status: string }>}
  */
 export function createAlephPin(options = {}) {
-  const { sender, sign } = options;
+  const { sender, sign, owner } = options;
   const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
   const channel = options.channel || DEFAULT_ALEPH_CHANNEL;
   const hasher = options.hasher || sha256Hex;
@@ -125,7 +132,7 @@ export function createAlephPin(options = {}) {
   if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "createAlephPin needs fetch");
 
   return async function pin(cid) {
-    const unsigned = await buildStoreMessage({ sender, cid, channel, hasher, now: now?.() });
+    const unsigned = await buildStoreMessage({ sender, owner, cid, channel, hasher, now: now?.() });
     const signature = await sign(sender, signaturePayload(unsigned));
     const message = {
       ...unsigned,
@@ -158,4 +165,138 @@ export function createAlephPin(options = {}) {
   };
 }
 
+/** The reserved channel and aggregate key Aleph keeps permissions in. */
+export const SECURITY = "security";
+
+/**
+ * @typedef {object} AlephAuthorization one entry of an owner's `security.authorizations`
+ * @property {string} address - the delegate, which may then send on the owner's behalf
+ * @property {string[]} [types] - e.g. `["STORE"]`; every type when absent
+ * @property {string[]} [channels] - e.g. `["BELEGE-BACKUP"]`; every channel when absent
+ * @property {string} [chain] - only the delegate's address on this chain, e.g. `"ETH"`
+ * @property {string[]} [post_types]
+ * @property {string[]} [aggregate_keys]
+ */
+
+/**
+ * Build the unsigned AGGREGATE that sets an owner's authorizations.
+ *
+ * Aleph keeps permissions in the owner's `security` aggregate, written only by
+ * the owner itself (`sender == content.address`) on the `security` channel. An
+ * aggregate key is replaced as a whole, so `authorizations` is the **complete**
+ * list after the change, not an addition: {@link createAlephAuthorizer} reads
+ * the current list first.
+ *
+ * @param {object} args
+ * @param {string} args.owner - the account granting, and signing
+ * @param {AlephAuthorization[]} args.authorizations
+ * @param {number} [args.now] - seconds
+ * @param {(payload: string) => Promise<string>} [args.hasher]
+ */
+export async function buildAuthorizationMessage({ owner, authorizations, now, hasher = sha256Hex }) {
+  if (!owner) throw new BackendError("INVALID_BACKEND", "an authorization needs the owner's address");
+  if (!Array.isArray(authorizations) || authorizations.some((a) => typeof a?.address !== "string" || !a.address)) {
+    throw new BackendError("INVALID_BACKEND", "every authorization needs the delegate's address");
+  }
+  const time = now ?? Date.now() / 1000;
+  const item_content = JSON.stringify({
+    address: owner,
+    key: SECURITY,
+    content: { authorizations },
+    time,
+  });
+  return {
+    sender: owner,
+    chain: "ETH",
+    type: "AGGREGATE",
+    item_hash: await hasher(item_content),
+    item_type: "inline",
+    item_content,
+    time,
+    channel: SECURITY,
+  };
+}
+
+/**
+ * Let other keys send STORE messages for an account: read, grant and revoke its
+ * authorizations.
+ *
+ * The use it was built for: one funded account pays for keeping backups, and
+ * the keys that actually sign them are others — a key derived from a passkey in
+ * the browser, one per person or device. Each is granted only what it needs
+ * (`types: ["STORE"]`, one channel), and revoked on its own. The owner signs
+ * these grants; the delegates then pass `owner` to {@link createAlephPin}.
+ *
+ * Which balance Aleph charges for a STORE sent by a delegate is not stated in
+ * its documentation; measure it before relying on it.
+ *
+ * Aleph keys accounts by their EIP-55 checksummed address; pass `owner` in that
+ * form, or `read()` finds nothing.
+ *
+ * @param {object} options
+ * @param {string} options.owner - the account granting
+ * @param {(address: string, message: string) => Promise<string>} options.sign - the owner's `personal_sign`
+ * @param {string} [options.apiHost]
+ * @param {typeof fetch} [options.fetch]
+ * @param {() => number} [options.now] - seconds
+ * @param {(payload: string) => Promise<string>} [options.hasher]
+ */
+export function createAlephAuthorizer(options = {}) {
+  const { owner, sign } = options;
+  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
+  const hasher = options.hasher || sha256Hex;
+  const doFetch = options.fetch || globalThis.fetch;
+  if (!owner) throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs the owner's address");
+  if (typeof sign !== "function") throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs a `sign` function");
+  if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs fetch");
+
+  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+
+  /** @returns {Promise<AlephAuthorization[]>} */
+  async function read() {
+    const response = await doFetch(`${apiHost}/api/v0/aggregates/${owner}.json?keys=${SECURITY}`);
+    if (response.status === 404) return [];
+    if (!response.ok) {
+      throw new BackendError("UNSUPPORTED", `Aleph did not answer the owner's permissions: ${response.status}`);
+    }
+    const body = await response.json().catch(() => ({}));
+    const list = body?.data?.[SECURITY]?.authorizations;
+    return Array.isArray(list) ? list : [];
+  }
+
+  /** @param {AlephAuthorization[]} authorizations */
+  async function write(authorizations) {
+    const unsigned = await buildAuthorizationMessage({ owner, authorizations, hasher, now: options.now?.() });
+    const signature = await sign(owner, signaturePayload(unsigned));
+    const response = await doFetch(`${apiHost}/api/v0/messages`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        message: { ...unsigned, signature: signature.startsWith("0x") ? signature : `0x${signature}` },
+        sync: true,
+      }),
+    });
+    if (!response.ok && response.status !== 202) {
+      const detail = await response.text().catch(() => "");
+      throw new BackendError("UNSUPPORTED", `Aleph refused the authorization: ${response.status} ${detail.slice(0, 200)}`);
+    }
+    const body = await response.json().catch(() => ({}));
+    return { itemHash: unsigned.item_hash, status: body?.message_status ?? "pending", authorizations };
+  }
+
+  return {
+    read,
+    write,
+    /** Grant, or replace the grant of the same address. @param {AlephAuthorization} authorization */
+    async authorize(authorization) {
+      const others = (await read()).filter((a) => !same(a.address, authorization?.address));
+      return write([...others, authorization]);
+    },
+    /** Take one address's grant away; the others stay. @param {string} address */
+    async revoke(address) {
+      return write((await read()).filter((a) => !same(a.address, address)));
+    },
+  };
+}
+
 export default createAlephPin;