@le-space/orbitdb-storage-bridge 0.10.0 → 0.12.0

package/README.md

@@ -5,8 +5,8 @@
 
 [![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/@le-space/orbitdb-storage-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/NiKrause/@le-space/orbitdb-storage-bridge/actions/workflows/ci.yml)
-[![ESLint](https://img.shields.io/badge/ESLint-passing-brightgreen.svg)](https://github.com/NiKrause/@le-space/orbitdb-storage-bridge/actions/workflows/ci.yml)
+[![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]
@@ -60,6 +60,18 @@
   - [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.
@@ -73,6 +85,17 @@ Verified on 2026-09-05:
 | 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
@@ -157,7 +180,7 @@ The project includes **Svelte components** for browser-based demos and integrati
 ## Roadmap
 
 > Being re-based on a backend interface instead of a single vendor — the plan is
-> [issue 54](https://github.com/NiKrause/@le-space/orbitdb-storage-bridge/issues/54), not here. The WebAuthn/varsig items below survive
+> [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.
@@ -169,11 +192,11 @@ The project includes **Svelte components** for browser-based demos and integrati
 - [ ] 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/@le-space/orbitdb-storage-bridge/issues/23)).
+- [ ] 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/@le-space/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/).
+  - [ ] 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).
@@ -224,6 +247,24 @@ 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)):
+
+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.
+
+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.
+
 ### Svelte Components
 
 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.

package/lib/backends/aleph.js

@@ -47,12 +47,16 @@
 import { defineBackend, handleId, BackendError } from "./types.js";
 import { fetchFromGateways } from "../gateway-fetch.js";
 
-/** Aleph's own first: it serves what Aleph ingested without waiting for propagation. */
-export const ALEPH_GATEWAYS = Object.freeze([
-  "https://ipfs.aleph.cloud/ipfs",
-  "https://dweb.link/ipfs",
-  "https://ipfs.io/ipfs",
-]);
+/**
+ * Aleph's own, and only Aleph's own.
+ *
+ * `dweb.link` and `ipfs.io` were the two fallbacks behind it until Protocol
+ * Labs retired them on 2026-09-21; they answer 429 with a `Sunset` header now.
+ * Nothing free was found to replace them that will serve an arbitrary CID, so
+ * this driver's retrieval depends on one host until the peer path in #112
+ * lands. A caller with its own gateway passes `gateways`.
+ */
+export const ALEPH_GATEWAYS = Object.freeze(["https://ipfs.aleph.cloud/ipfs"]);
 
 const ALEPH_INGEST = "https://ipfs.aleph.cloud/api/v0/add";
 const DEFAULT_TIMEOUT_MS = 120_000;

package/lib/backends/choose.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview One backend from a plain choice — a name and, where a service
+ * needs one, a key.
+ *
+ * `resolveBackend` understands a ready backend or Storacha credentials, which is
+ * what a Node caller has. A page has something smaller and less trusting: a
+ * reader ticked *Lighthouse* and pasted their own key, and nothing else is
+ * known. This turns that into a driver.
+ *
+ * ## Every vendor module is imported lazily, and that is the point
+ *
+ * A page that chose Aleph must not ship the Pinata and Lighthouse drivers, and
+ * a page that chose none of them must ship no vendor code at all. Each branch
+ * therefore `import()`s exactly what it builds — the same reason
+ * `resolveBackend` loads Storacha only when it builds one, where the module
+ * costs about 88 kB gzipped.
+ *
+ * ## Several choices are a mirror, not a loop in the caller
+ *
+ * `kind: ["aleph", "lighthouse"]` builds both and returns
+ * {@link ../backends/mirror.js createMirrorBackend} over them, so the caller's
+ * code is the same whether one service was ticked or three.
+ *
+ * ## A gateway belongs to the service it came from
+ *
+ * Since the public path gateways were retired (#111), the gateway a reader can
+ * actually use is usually their own account's — `<name>.mypinata.cloud`,
+ * `<name>.lighthouseweb3.xyz` — and those are not interchangeable: Pinata's
+ * answers 401 for a Lighthouse CID, Lighthouse's answers 402. So `gateway` is
+ * a string only while one service is chosen, and an object keyed by service
+ * once several are. Handing one string to three drivers is refused rather than
+ * half-working.
+ *
+ * ## What it refuses
+ *
+ * A key that is missing is refused here, with the name of the service in the
+ * message, rather than at the first upload — a page can then keep the button
+ * disabled and say why. Nothing in this module reads an environment variable on
+ * a page's behalf: in a browser there is no environment, and a driver that
+ * silently finds a key somewhere else is a driver nobody can reason about. The
+ * per-driver fallbacks to `process.env` stay where they are, for Node.
+ *
+ * @author @NiKrause
+ * @requires ./types.js - the contract every branch returns
+ */
+
+import { BackendError } from "./types.js";
+
+/**
+ * Aleph's driver tries a list of `…/ipfs` prefixes, while a reader types a
+ * host. Accept either, and a bare domain as https, like the other drivers do.
+ */
+const alephGateway = (value) => {
+  const withScheme = /^https?:\/\//i.test(value) ? value : `https://${value}`;
+  const trimmed = withScheme.replace(/\/+$/, "");
+  return trimmed.endsWith("/ipfs") ? trimmed : `${trimmed}/ipfs`;
+};
+
+/** The names a caller may ask for. */
+export const BACKEND_KINDS = Object.freeze([
+  "aleph",
+  "pinata",
+  "lighthouse",
+  "storacha",
+  "memory",
+]);
+
+/**
+ * Build a backend from a choice.
+ *
+ * @param {object} choice
+ * @param {string|string[]} choice.kind - one name, or several for a mirror
+ * @param {string} [choice.jwt] - Pinata
+ * @param {() => Promise<string>} [choice.getUploadUrl] - Pinata, without a secret in the page
+ * @param {string} [choice.apiKey] - Lighthouse
+ * @param {"shared"|"user"} [choice.keyOwnership] - Lighthouse: whose key it is,
+ *   which is what decides `browserSafeAuth`
+ * @param {string|Record<string, string>} [choice.gateway] - retrieval gateway:
+ *   a string for a single kind, or `{ pinata: "…", lighthouse: "…" }` for several.
+ *   A bare domain is read as https, as each driver already accepts
+ * @param {string[]} [choice.gateways] - retrieval gateways, tried in order; wins
+ *   over `gateway` where a driver takes a list
+ * @param {object} [choice.options] - passed through to the driver, for anything
+ *   this signature does not name
+ * @param {"one"|"all"} [choice.require] - for several kinds: how many must accept a write
+ * @returns {Promise<import("./types.js").StorageBackend>}
+ */
+export async function createBackendFromChoice(choice = {}) {
+  const kinds = Array.isArray(choice.kind) ? choice.kind : [choice.kind];
+  const wanted = kinds.filter(Boolean);
+
+  if (wanted.length === 0) {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      `Pick a backend: ${BACKEND_KINDS.join(", ")}`,
+    );
+  }
+  for (const kind of wanted) {
+    if (!BACKEND_KINDS.includes(kind)) {
+      throw new BackendError(
+        "INVALID_BACKEND",
+        `Unknown backend "${kind}" — pick one of ${BACKEND_KINDS.join(", ")}`,
+      );
+    }
+  }
+
+  if (wanted.length > 1 && typeof choice.gateway === "string") {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      `A gateway belongs to one service — with several kinds pass an object: ` +
+        `{ gateway: { ${wanted.map((k) => `${k}: "…"`).join(", ")} } }`,
+    );
+  }
+
+  if (wanted.length > 1) {
+    const backends = [];
+    for (const kind of wanted) {
+      backends.push(await createBackendFromChoice({ ...choice, kind }));
+    }
+    const { createMirrorBackend } = await import("./mirror.js");
+    return createMirrorBackend(backends, { require: choice.require ?? "one" });
+  }
+
+  const [kind] = wanted;
+  const extra = choice.options ?? {};
+  const gateway =
+    typeof choice.gateway === "string" ? choice.gateway : choice.gateway?.[kind];
+  const gateways = choice.gateways ? { gateways: choice.gateways } : {};
+  // Pinata and Lighthouse take one gateway; Aleph takes the list it tries in
+  // order, so a single choice becomes a list of one.
+  const oneGateway = gateway ? { gateway } : {};
+
+  if (kind === "aleph") {
+    const { createAlephBackend } = await import("./aleph.js");
+    const fromOne =
+      gateway && !choice.gateways ? { gateways: [alephGateway(gateway)] } : {};
+    return createAlephBackend({ ...gateways, ...fromOne, ...extra });
+  }
+
+  if (kind === "pinata") {
+    if (
+      !choice.jwt &&
+      !choice.getUploadUrl &&
+      !extra.jwt &&
+      !extra.getUploadUrl
+    ) {
+      throw new BackendError(
+        "INVALID_BACKEND",
+        "Pinata needs a JWT, or a getUploadUrl function that mints a presigned URL",
+      );
+    }
+    const { createPinataBackend } = await import("./pinata.js");
+    return createPinataBackend({
+      ...(choice.jwt ? { jwt: choice.jwt } : {}),
+      ...(choice.getUploadUrl ? { getUploadUrl: choice.getUploadUrl } : {}),
+      ...oneGateway,
+      ...gateways,
+      ...extra,
+    });
+  }
+
+  if (kind === "lighthouse") {
+    if (!choice.apiKey && !extra.apiKey) {
+      throw new BackendError("INVALID_BACKEND", "Lighthouse needs an apiKey");
+    }
+    const { createLighthouseBackend } = await import("./lighthouse.js");
+    return createLighthouseBackend({
+      ...(choice.apiKey ? { apiKey: choice.apiKey } : {}),
+      // Whose key it is decides browserSafeAuth, and a page should say which it got.
+      keyOwnership: choice.keyOwnership ?? "shared",
+      ...oneGateway,
+      ...gateways,
+      ...extra,
+    });
+  }
+
+  if (kind === "memory") {
+    const { createMemoryBackend } = await import("./memory.js");
+    return createMemoryBackend(extra);
+  }
+
+  const { resolveBackend } = await import("./resolve.js");
+  return resolveBackend({ ...choice, ...extra, kind: undefined });
+}
+
+export default createBackendFromChoice;

package/lib/backends/mirror.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview One backup, several services: the mirror backend.
+ *
+ * A page that wants its backup on Aleph *and* on Lighthouse had to call both
+ * and reconcile two handles itself. This does that once, behind the same
+ * contract every other driver keeps, so `dehydrate`, `backupDatabaseCAR` and
+ * `restoreFromCID` need to know nothing about it.
+ *
+ * ## What a mirror promises, and what it refuses to
+ *
+ * **A partial write is reported, never swallowed.** By default a write
+ * succeeds when at least one service took it — a backup that fails because the
+ * third service was down would be worse than useless — but the handle then
+ * names who holds it and who refused, and the caller decides what to say. Pass
+ * `require: "all"` when a copy everywhere is the point of the exercise.
+ *
+ * **A read asks in order and stops at the first answer.** Not a race: a race
+ * spends every service's bandwidth on every read, and on a gateway that bills
+ * by request that is somebody's money. The order is the order the backends
+ * were given, so "the fast one first" is the caller's decision to make.
+ *
+ * **Capabilities are the honest composition, not the flattering one.**
+ * `browserSafeAuth` is true only when *every* service is safe to hand a page,
+ * because the weakest one decides what a page leaks. `preservesInnerCids` and
+ * `carImport` likewise. `minBlobSize` is the largest of them, because a blob
+ * has to clear the strictest door. `pinByCid` is the exception: it is true when
+ * *any* service can pin, and `pinCid()` then asks exactly those.
+ *
+ * **It does not list and it does not delete.** Both questions have no single
+ * honest answer across services — a listing would be a union with duplicates,
+ * and a deletion that half succeeds leaves a copy behind while reporting
+ * success. A caller that wants either can ask the service it means.
+ *
+ * @author @NiKrause
+ * @requires ./types.js - the contract this keeps
+ */
+
+import {
+  defineBackend,
+  handleId,
+  BackendError,
+  DEFAULT_CAPABILITIES,
+} from "./types.js";
+import { logger } from "../logger.js";
+
+/** The strictest door decides; an unstated minimum is no minimum. */
+const largestMinimum = (backends) =>
+  backends.reduce(
+    (largest, backend) =>
+      Math.max(largest, backend.capabilities?.minBlobSize ?? 0),
+    0,
+  );
+
+const everyOne = (backends, flag) =>
+  backends.every((backend) => Boolean(backend.capabilities?.[flag]));
+const anyOne = (backends, flag) =>
+  backends.some((backend) => Boolean(backend.capabilities?.[flag]));
+
+/**
+ * Write one backup to several services and read it back from whichever answers.
+ *
+ * @param {import("./types.js").StorageBackend[]} backends - two or more drivers,
+ *   in the order reads should try them
+ * @param {object} [options]
+ * @param {"one"|"all"} [options.require="one"] - how many services must accept a
+ *   write for it to count as one
+ * @param {string} [options.name] - what the mirror calls itself; the default
+ *   names its members, because a log line saying "mirror" says nothing
+ * @returns {import("./types.js").StorageBackend}
+ */
+export function createMirrorBackend(backends = [], options = {}) {
+  const members = backends.filter(Boolean);
+  if (members.length < 2) {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      "createMirrorBackend needs at least two backends; one backend is not a mirror",
+    );
+  }
+
+  const require_ = options.require ?? "one";
+  if (require_ !== "one" && require_ !== "all") {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      `require must be "one" or "all", not ${require_}`,
+    );
+  }
+
+  const name =
+    options.name ||
+    `mirror(${members.map((backend) => backend.name).join("+")})`;
+  const pinners = members.filter(
+    (backend) => typeof backend.pinCid === "function",
+  );
+
+  /** Run one operation against every member, keeping which of them said what. */
+  const acrossAll = async (operation) => {
+    const settled = await Promise.allSettled(
+      members.map((backend) => operation(backend)),
+    );
+    const copies = [];
+    const failures = [];
+    settled.forEach((result, index) => {
+      const backend = members[index];
+      if (result.status === "fulfilled") {
+        copies.push({ backend: backend.name, ...result.value });
+      } else {
+        failures.push({
+          backend: backend.name,
+          code: result.reason?.code ?? "FAILED",
+          message: result.reason?.message ?? String(result.reason),
+        });
+      }
+    });
+    return { copies, failures };
+  };
+
+  /**
+   * One handle for the copies. The id is the CID when every service agreed on
+   * one — which is the normal case, since the bytes decide it — and the first
+   * success otherwise, so a handle is always usable somewhere.
+   */
+  const mergeHandles = ({ copies, failures }, what) => {
+    if (copies.length === 0) {
+      throw new BackendError(
+        failures[0]?.code === "TOO_SMALL" ? "TOO_SMALL" : "FAILED",
+        `${name}: no service accepted ${what} — ${failures
+          .map((failure) => `${failure.backend}: ${failure.message}`)
+          .join("; ")}`,
+      );
+    }
+    if (require_ === "all" && failures.length > 0) {
+      throw new BackendError(
+        "FAILED",
+        `${name}: ${failures.length} of ${members.length} services refused ${what} and require is "all" — ${failures
+          .map((failure) => `${failure.backend}: ${failure.message}`)
+          .join("; ")}`,
+      );
+    }
+    if (failures.length > 0) {
+      logger.warn(
+        `⚠️  ${name}: ${copies.length} of ${members.length} services hold ${what}; ` +
+          failures
+            .map((failure) => `${failure.backend} refused (${failure.code})`)
+            .join(", "),
+      );
+    }
+
+    const cids = new Set(copies.map((copy) => copy.cid).filter(Boolean));
+    const agreed = cids.size === 1 ? [...cids][0] : null;
+    return {
+      id: agreed ?? copies[0].id,
+      ...(agreed ? { cid: agreed } : {}),
+      backend: name,
+      ...(copies[0].size != null ? { size: copies[0].size } : {}),
+      ...(copies[0].name ? { name: copies[0].name } : {}),
+      copies,
+      ...(failures.length > 0 ? { failures } : {}),
+    };
+  };
+
+  /** A member's own id for this handle, since only the CID is shared. */
+  const idFor = (backend, handle) => {
+    const copy =
+      typeof handle === "object" && handle?.copies
+        ? handle.copies.find((entry) => entry.backend === backend.name)
+        : null;
+    return copy?.id ?? handleId(handle);
+  };
+
+  const mirror = {
+    name,
+    /** The members, in read order — a caller that wants one service can reach it. */
+    backends: members,
+    capabilities: {
+      ...DEFAULT_CAPABILITIES,
+      pinByCid: pinners.length > 0 && anyOne(members, "pinByCid"),
+      carImport: everyOne(members, "carImport"),
+      preservesInnerCids: everyOne(members, "preservesInnerCids"),
+      browserSafeAuth: everyOne(members, "browserSafeAuth"),
+      delegation: everyOne(members, "delegation"),
+      listing: false,
+      deletion: false,
+      minBlobSize: largestMinimum(members),
+    },
+
+    putBlob: async (bytes, meta = {}) =>
+      mergeHandles(
+        await acrossAll((backend) => backend.putBlob(bytes, meta)),
+        "the blob",
+      ),
+
+    getBlob: async (handle) => {
+      const reasons = [];
+      for (const backend of members) {
+        try {
+          return await backend.getBlob(idFor(backend, handle));
+        } catch (error) {
+          reasons.push(`${backend.name}: ${error?.message ?? error}`);
+        }
+      }
+      throw new BackendError(
+        "NOT_FOUND",
+        `${name}: no service returned ${handleId(handle)} — ${reasons.join("; ")}`,
+      );
+    },
+  };
+
+  if (mirror.capabilities.pinByCid) {
+    /** Only the services that can pin are asked; the others have nothing to say. */
+    mirror.pinCid = async (cid, meta = {}) => {
+      const settled = await Promise.allSettled(
+        pinners.map((backend) => backend.pinCid(cid, meta)),
+      );
+      const copies = [];
+      const failures = [];
+      settled.forEach((result, index) => {
+        const backend = pinners[index];
+        if (result.status === "fulfilled")
+          copies.push({ backend: backend.name, ...result.value });
+        else
+          failures.push({
+            backend: backend.name,
+            code: result.reason?.code ?? "FAILED",
+            message: result.reason?.message ?? String(result.reason),
+          });
+      });
+      return mergeHandles({ copies, failures }, `the pin for ${cid}`);
+    };
+  }
+
+  return defineBackend(mirror);
+}
+
+export default createMirrorBackend;

package/lib/backends/resolve.js

@@ -20,6 +20,9 @@ import { logger } from "../logger.js";
  *
  * @param {Object} [config] - call options
  * @param {Object} [config.backend] - any driver implementing the backend contract
+ * @param {string|string[]} [config.kind] - a backend by name, or several for a
+ *   mirror, with the credentials each needs. What a page has, since a reader
+ *   ticks a service and pastes a key rather than handing over a driver.
  * @param {Object} [config.ucanClient] - a Storacha client authorised over UCAN
  * @param {string} [config.spaceDID]
  * @param {string} [config.storachaKey] - falls back to STORACHA_KEY
@@ -35,6 +38,13 @@ export async function resolveBackend(config = {}) {
     return config.backend;
   }
 
+  // A name and a key: loaded here so that one decision stays one decision, and
+  // lazily so a caller that never names a vendor never bundles one.
+  if (config.kind) {
+    const { createBackendFromChoice } = await import("./choose.js");
+    return createBackendFromChoice(config);
+  }
+
   const gateways = config.gateways;
 
   if (config.ucanClient) {

package/lib/backends/storacha.js

@@ -7,9 +7,10 @@
  * credentials against a self-hosted w3up deployment can still use it, and it is the
  * reference for what a UCAN-delegated backend looked like when one existed.
  *
- * Retrieval no longer defaults to Storacha's own gateways: `storacha.link` and `w3s.link`
- * answer 301 to `dweb.link` as of 2026-09-05, so the driver goes there directly and lets
- * a caller pass its own list — which is what the in-memory service does.
+ * Retrieval defaults to a gateway belonging to nobody in this story: `storacha.link`
+ * and `w3s.link` answer 301 to `dweb.link`, which Protocol Labs retired on 2026-09-21
+ * along with `ipfs.io`. A caller passes its own list — which is what the in-memory
+ * service does.
  *
  * @author @NiKrause
  * @requires ./types.js - the backend contract
@@ -23,11 +24,15 @@ import * as Proof from "@storacha/client/proof";
 import { CID } from "multiformats/cid";
 import { defineBackend, handleId, BackendError } from "./types.js";
 
-/** Gateways tried in order by `getBlob()`, unless the caller supplies its own. */
-export const DEFAULT_GATEWAYS = Object.freeze([
-  "https://dweb.link",
-  "https://ipfs.io",
-]);
+/**
+ * Gateways tried in order by `getBlob()`, unless the caller supplies its own.
+ *
+ * Storacha's own hosts redirected here, and here was retired on 2026-09-21
+ * together with `ipfs.io`. What is left is a gateway belonging to a different
+ * service, which will serve a Storacha CID only while somebody still provides
+ * those blocks to the network.
+ */
+export const DEFAULT_GATEWAYS = Object.freeze(["https://ipfs.aleph.cloud"]);
 
 /**
  * Build a Storacha client from key and proof, or adopt one that already exists.

package/lib/backup-car.js

@@ -33,13 +33,14 @@ const spaceHelpers = () => import("./orbitdb-storacha-bridge.js");
 import { unixfs } from "@helia/unixfs";
 import logger from "./logger.js";
 import { readBlockBytes } from "./block-bytes.js";
+import { DEFAULT_GATEWAYS, MAX_BACKOFF_MS } from "./gateway-fetch.js";
 
 /**
  * Default configuration options
  */
 const DEFAULT_OPTIONS = {
   timeout: 30000,
-  gateway: "https://w3s.link",
+  gateway: "https://ipfs.aleph.cloud", // w3s.link redirects to a gateway retired on 2026-09-21
   verbose: false,
   // Network download options
   useIPFSNetwork: true, // Enable network downloads by default
@@ -812,12 +813,11 @@ export async function restoreFromSpaceCAR(orbitdb, options = {}) {
 
     // Fallback to gateway if network failed or disabled
     if (!carBytes) {
-      // Try multiple gateways in order
+      // The configured gateway, then whatever the package still trusts.
+      // `storacha.link`, `dweb.link` and `ipfs.io` were all retired on
+      // 2026-09-21 and stood here until then.
       const gateways = [
-        `${config.gateway}/ipfs`,
-        "https://storacha.link/ipfs",
-        "https://dweb.link/ipfs",
-        "https://ipfs.io/ipfs",
+        ...new Set([`${config.gateway}/ipfs`, ...DEFAULT_GATEWAYS]),
       ];
 
       let carResponse;
@@ -943,6 +943,13 @@ export async function restoreFromSpaceCAR(orbitdb, options = {}) {
                 }
               }
 
+              if (waitTime > MAX_BACKOFF_MS) {
+                logger.warn(
+                  `   ⚠️ ${gateway} wants ${Math.round(waitTime / 1000)}s — treating it as closed`,
+                );
+                break; // try the next gateway rather than wait out a retirement
+              }
+
               logger.warn(
                 `   Waiting ${Math.round(waitTime / 1000)}s before retry (attempt ${attempts + 1}/${maxAttempts})...`,
               );

package/lib/gateway-fetch.js

@@ -12,13 +12,39 @@
  * @module gateway-fetch
  */
 
-/** Tried in order. The first is Storacha's own, the rest are public. */
-export const DEFAULT_GATEWAYS = [
-  "https://w3s.link/ipfs",
-  "https://storacha.link/ipfs",
-  "https://dweb.link/ipfs",
-  "https://ipfs.io/ipfs",
-];
+/**
+ * Tried in order.
+ *
+ * This used to be four entries and is now one, because on 2026-09-21 Protocol
+ * Labs retired `ipfs.io` and `dweb.link` — they answer 429 with an RFC 8594
+ * `Sunset` header — and `w3s.link` and `storacha.link` redirect to `dweb.link`.
+ * All four were dead at once, which is what a list of gateways run by one
+ * organisation is worth.
+ *
+ * Measured 2026-09-23: `ipfs.aleph.cloud` answers in 0.2 s with CORS, and no
+ * other free path gateway found would serve an arbitrary CID —
+ * `gateway.pinata.cloud` answers 403 for content it does not hold,
+ * `4everland.io` redirects after 15 s, the rest do not answer at all.
+ *
+ * One entry is not a fallback chain, and pretending otherwise is how this
+ * rotted unnoticed. The replacement is not a longer list: it is fetching from
+ * the providers that hold the blocks, over libp2p — see issue #112.
+ */
+export const DEFAULT_GATEWAYS = ["https://ipfs.aleph.cloud/ipfs"];
+
+/**
+ * Gateways that serve **verifiable** responses only: a single block, or a CAR.
+ *
+ * `trustless-gateway.link` was still healthy when the path gateways were
+ * retired, and it answers with CORS — but it refuses an ordinary path request
+ * with a 406, so it is only usable with `accept` set, and only for a CID whose
+ * bytes are one block. A UnixFS file split into chunks needs its DAG walked,
+ * which this module deliberately cannot do.
+ */
+export const TRUSTLESS_GATEWAYS = ["https://trustless-gateway.link/ipfs"];
+
+/** `accept` for a single block from a trustless gateway. */
+export const RAW_BLOCK = "application/vnd.ipld.raw";
 
 /**
  * Quiet by default. A restore reports itself through its return value and its
@@ -30,6 +56,15 @@ export const SILENT = { info() {}, warn() {}, debug() {} };
 const DEFAULT_TIMEOUT_MS = 60_000;
 const MAX_ATTEMPTS_PER_GATEWAY = 3;
 
+/**
+ * Longest 429 wait worth honouring.
+ *
+ * A retired gateway asks for 900 s, and three attempts against four of them is
+ * most of an afternoon spent waiting for an answer that will not change. Past
+ * this, the gateway is not rate-limiting us, it is closed.
+ */
+export const MAX_BACKOFF_MS = 30_000;
+
 /**
  * A gateway that cannot serve a CID usually says so in HTML, with a 200.
  *
@@ -73,9 +108,14 @@ const backoffFor = (response, attempt) => {
  * @param {string[]} [options.gateways]
  * @param {number} [options.timeout] per request, in ms
  * @param {AbortSignal} [options.signal]
+ * @param {string} [options.accept] sent as `Accept`; `RAW_BLOCK` for a single
+ *   block from a trustless gateway
+ * @param {number} [options.maxBackoff] longest 429 wait to honour, in ms
+ * @param {(ms: number) => Promise<void>} [options.sleep] injectable for tests
+ * @param {typeof fetch} [options.fetchImpl] injectable for tests
  * @returns {Promise<Uint8Array>}
  */
-export async function fetchFromGateways(cid, { gateways = DEFAULT_GATEWAYS, timeout = DEFAULT_TIMEOUT_MS, signal = null, log = SILENT } = {}) {
+export async function fetchFromGateways(cid, { gateways = DEFAULT_GATEWAYS, timeout = DEFAULT_TIMEOUT_MS, signal = null, log = SILENT, accept = null, maxBackoff = MAX_BACKOFF_MS, sleep = waitFor, fetchImpl = fetch } = {}) {
   let lastError = null;
 
   for (const gateway of gateways) {
@@ -83,12 +123,27 @@ export async function fetchFromGateways(cid, { gateways = DEFAULT_GATEWAYS, time
     for (let attempt = 0; attempt < MAX_ATTEMPTS_PER_GATEWAY; attempt++) {
       const timer = AbortSignal.timeout ? AbortSignal.timeout(timeout) : null;
       try {
-        const response = await fetch(url, { signal: signal ?? timer ?? undefined });
+        const response = await fetchImpl(url, {
+          signal: signal ?? timer ?? undefined,
+          ...(accept ? { headers: { Accept: accept } } : {}),
+        });
+
+        // An RFC 8594 Sunset header means the gateway is going away or already
+        // has. Retrying is pointless, and so is coming back next time.
+        const sunset = response.headers?.get?.("Sunset");
+        if (sunset && !response.ok) {
+          log.warn(`   ⚠️ ${gateway} is retired (Sunset: ${sunset})`);
+          break;
+        }
 
         if (response.status === 429 && attempt < MAX_ATTEMPTS_PER_GATEWAY - 1) {
           const wait = backoffFor(response, attempt);
+          if (wait > maxBackoff) {
+            log.warn(`   ⚠️ ${gateway} wants ${Math.round(wait / 1000)}s — treating it as closed`);
+            break;
+          }
           log.warn(`   ⚠️ ${gateway} rate-limited; waiting ${Math.round(wait / 1000)}s`);
-          await waitFor(wait);
+          await sleep(wait);
           continue;
         }
         if (!response.ok) {

package/lib/orbitdb-storacha-bridge.js

@@ -17,6 +17,7 @@ import { sha256 } from "multiformats/hashes/sha2";
 import { bases } from "multiformats/basics";
 import { EventEmitter } from "events";
 import { createHeliaOrbitDB, cleanupOrbitDBDirectories } from "./utils.js";
+import { DEFAULT_GATEWAYS } from "./gateway-fetch.js";
 import {
   generateBackupPrefix,
   getBackupFilenames,
@@ -47,7 +48,7 @@ function logHeliaActivity(message) {
 const DEFAULT_OPTIONS = {
   // Core configuration
   timeout: 30000, // Timeout in milliseconds
-  gateway: "https://dweb.link", // IPFS gateway URL (w3s.link only redirects here now)
+  gateway: "https://ipfs.aleph.cloud", // dweb.link was retired on 2026-09-21
   verbose: false, // Enable verbose debug logging
 
   // Network download options
@@ -823,14 +824,12 @@ export async function downloadBlock(cid, options = {}) {
     }
   }
 
-  // Fallback to gateway download
-  // storacha.link and w3s.link answer 301 to dweb.link as of 2026-09-05, so going
-  // through them only buys a redirect. Ask the destination directly.
-  const gateways = [
-    `${config.gateway}/ipfs`,
-    "https://dweb.link/ipfs",
-    "https://ipfs.io/ipfs",
-  ];
+  // Fallback to gateway download.
+  // `dweb.link` and `ipfs.io` stood here until Protocol Labs retired them on
+  // 2026-09-21; `storacha.link` and `w3s.link` had already become redirects to
+  // the first of those. What is left is one host, which is not a fallback
+  // chain — see issue #112 for the path that does not depend on one.
+  const gateways = [...new Set([`${config.gateway}/ipfs`, ...DEFAULT_GATEWAYS])];
 
   for (const gateway of gateways) {
     try {

package/lib/peer-fetch.js

@@ -0,0 +1,365 @@
+/**
+ * @fileoverview Fetching bytes by CID from peers, when a gateway will not do.
+ *
+ * `gateway-fetch.js` is the HTTP half of this: ask a host, hope it answers.
+ * That stopped being a plan on 2026-09-21, when the public path gateways were
+ * retired (#111) and every fallback list in this package turned out to be one
+ * live entry and a dead tail. This is the other half — ask the peers that
+ * actually hold the blocks.
+ *
+ * ## Measured before it was written
+ *
+ * From a real page (Chrome, no build step, Helia loaded as ES modules), on
+ * 2026-09-23:
+ *
+ * ```
+ * Pinata      dial 729 ms over wss            bitswap 263 ms
+ * Lighthouse  dial 581 ms over webrtc-direct  bitswap 323 ms
+ * Aleph       dial 450 ms over webrtc-direct  bitswap 345 ms
+ * ```
+ *
+ * No credential in any of it, while both paid providers' HTTP gateways want
+ * that account's key and Lighthouse's shared gateway answers 402 for content
+ * it does not hold. Three services, two transports, about a second each.
+ *
+ * ## The peer list follows the backends, and nothing else
+ *
+ * There is no default provider here, and that is deliberate. Whoever stores
+ * with a service already shares their CIDs with it, so reading from it adds no
+ * new party — but a page that dials Pinata having never uploaded there would
+ * be telling Pinata what its reader is looking for, in exchange for nothing.
+ * The caller names the providers. {@link PINATA_BITSWAP} is a constant because
+ * Pinata publishes it in DNS; everyone else has to be looked up.
+ *
+ * ## What the caller has to bring
+ *
+ * A Helia with bitswap. This module has no libp2p of its own — the page that
+ * restores already has a node, and a second one would be a second identity on
+ * the network. Helia's browser defaults try to listen on `/webrtc` and
+ * `/p2p-circuit` and **throw on start** when no transport serves them, so a
+ * fetch-only node wants `addresses: { listen: [] }`.
+ *
+ * @module peer-fetch
+ */
+
+/**
+ * Pinata's bitswap endpoint, published in DNS:
+ *
+ * ```
+ * $ dig +short TXT _dnsaddr.bitswap-v3.pinata.cloud
+ * "dnsaddr=/dns4/bitswap-v3.pinata.cloud/tcp/443/wss/p2p/Qmdv6yNikmUWUWXufLJLRNkv6Y9sY5cmgeX5RVWA4WNMz4"
+ * ```
+ *
+ * A DNS name on 443 with a CA certificate is dialable from a page, which is
+ * what makes it worth naming here rather than looking up per CID.
+ */
+export const PINATA_BITSWAP =
+  "/dns4/bitswap-v3.pinata.cloud/tcp/443/wss/p2p/Qmdv6yNikmUWUWXufLJLRNkv6Y9sY5cmgeX5RVWA4WNMz4";
+
+/**
+ * Aleph's own node, which took some finding.
+ *
+ * It publishes no `_dnsaddr` and answers `404` to `/api/v0/id`, so looking for
+ * it the way Pinata is found says it has no peer — which is what an earlier
+ * version of this file claimed. It does: ask a router for the providers of a
+ * CID Aleph holds, and the record is `46.255.204.211`, the address
+ * `ipfs.aleph.cloud` resolves to, with `webrtc-direct` and `webtransport`
+ * among its addresses. A page dialled it in 450 ms and had the block 345 ms
+ * later.
+ *
+ * Two caveats make this a starting point rather than a guarantee:
+ *
+ * - **The certhash rotates.** A `webrtc-direct` address carries the
+ *   certificate's hash, and the node generates a new certificate when it
+ *   restarts. When this address stops working, look the CID up again — the
+ *   peer id is the stable part.
+ * - **Only one router will tell you.** Aleph announces over the DHT rather
+ *   than IPNI, so `cid.contact` — the one router that answers a browser with
+ *   CORS — does not know its CIDs, while `delegated-ipfs.dev` does and sends
+ *   no CORS header for provider lookups. From a page, this constant is the way
+ *   in; from Node, {@link providersFor} with `delegated-ipfs.dev` is better.
+ */
+export const ALEPH_BITSWAP = Object.freeze([
+  "/ip4/46.255.204.211/udp/4001/webrtc-direct/certhash/uEiCbM9yMfnP02vviIL26n8bI0-vU0DGUHx20POBLKGjEmg/p2p/12D3KooWACE5dRw5V9WXuDTcngjE3ZaDSZ4qYJGfuhXZbENnL54y",
+  "/ip4/46.255.204.211/udp/4001/quic-v1/webtransport/certhash/uEiDMxOK9kZFH5SW6zcmNpXU4EGgBgvZYqqlJhw1cci50KA/certhash/uEiCeRpuyQWojWx2cP8guNiY3EDfIF25D2k8CMTZd1qtSfw/p2p/12D3KooWACE5dRw5V9WXuDTcngjE3ZaDSZ4qYJGfuhXZbENnL54y",
+]);
+
+/** Aleph's peer id, which outlives the certificate hashes above. */
+export const ALEPH_PEER_ID = "12D3KooWACE5dRw5V9WXuDTcngjE3ZaDSZ4qYJGfuhXZbENnL54y";
+
+/**
+ * Routers that answer a page.
+ *
+ * `cid.contact` sends `access-control-allow-origin: *` for provider lookups;
+ * `delegated-ipfs.dev` did not, measured 2026-09-23 — it does for `/routing/v1/ipns`,
+ * which is why the pointer lookup can use it and this cannot.
+ *
+ * They also know different things, which matters more than the CORS header:
+ * `cid.contact` is an IPNI index and knows what is announced to it — Pinata's
+ * CIDs and Lighthouse's were there — while a CID that Aleph holds appeared
+ * only at `delegated-ipfs.dev`, because Aleph announces over the DHT. So from
+ * a page, a lookup finds the two paid services and not Aleph; that is what
+ * {@link ALEPH_BITSWAP} is for.
+ */
+export const DEFAULT_ROUTERS = Object.freeze(["https://cid.contact"]);
+
+/** Everything a Node caller can ask, where CORS does not apply. */
+export const ALL_ROUTERS = Object.freeze([
+  "https://cid.contact",
+  "https://delegated-ipfs.dev",
+]);
+
+/**
+ * Transports a browser can dial.
+ *
+ * `tcp` and plain `quic-v1` are not here: a page has no raw sockets. `tls/ws`
+ * needs a name rather than an IP, since the certificate has to match — an
+ * AutoTLS `libp2p.direct` address qualifies only while that name resolves,
+ * which for one provider it did not on the day this was written.
+ */
+export const BROWSER_TRANSPORTS = Object.freeze([
+  "/wss",
+  "/tls/ws",
+  "/webtransport",
+  "/webrtc-direct",
+]);
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Quiet by default, like `gateway-fetch.js`. */
+export const SILENT = { info() {}, warn() {}, debug() {} };
+
+/** Does this multiaddr use a transport a page can open? */
+export function isBrowserDialable(addr) {
+  if (typeof addr !== "string") return false;
+  if (!BROWSER_TRANSPORTS.some((transport) => addr.includes(transport))) return false;
+  // A certificate cannot be issued for a bare IP, so ws/wss on one is not
+  // dialable however well-formed it looks; webtransport and webrtc-direct
+  // carry a certhash instead and are fine.
+  const needsName = addr.includes("/wss") || addr.includes("/tls/ws");
+  return !needsName || addr.includes("/dns");
+}
+
+/**
+ * Who says they hold this CID, and at what address.
+ *
+ * @param {string} cid
+ * @param {Object} [options]
+ * @param {string[]} [options.routers] - delegated routing endpoints
+ * @param {boolean} [options.dialableOnly=true] - keep only what a page can open
+ * @param {AbortSignal} [options.signal]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<Array<{ id: string, addrs: string[] }>>}
+ */
+export async function providersFor(cid, {
+  routers = DEFAULT_ROUTERS,
+  dialableOnly = true,
+  signal = null,
+  fetchImpl = fetch,
+  log = SILENT,
+} = {}) {
+  const found = new Map();
+
+  for (const router of routers) {
+    try {
+      const response = await fetchImpl(`${router}/routing/v1/providers/${cid}`, {
+        headers: { Accept: "application/json" },
+        signal,
+      });
+      if (!response.ok) {
+        log.debug(`   ⚠️ ${router} answered ${response.status}`);
+        continue;
+      }
+      const body = await response.text();
+      for (const record of parseProviderRecords(body)) {
+        const id = record.ID ?? record.id;
+        if (!id) continue;
+        const addrs = (record.Addrs ?? record.addrs ?? []).filter(
+          (addr) => !dialableOnly || isBrowserDialable(addr),
+        );
+        if (addrs.length === 0) continue;
+        const already = found.get(id);
+        if (already) {
+          for (const addr of addrs) if (!already.addrs.includes(addr)) already.addrs.push(addr);
+        } else {
+          found.set(id, { id, addrs: [...addrs] });
+        }
+      }
+    } catch (error) {
+      log.debug(`   ⚠️ ${router} failed: ${error.message}`);
+    }
+  }
+
+  return [...found.values()];
+}
+
+/**
+ * A routing answer is JSON, or one JSON object per line when the router
+ * streams — both shapes are in the spec, and both are in the wild.
+ */
+function parseProviderRecords(body) {
+  const records = [];
+  const push = (value) => {
+    if (!value) return;
+    if (Array.isArray(value.Providers)) records.push(...value.Providers);
+    else if (Array.isArray(value.providers)) records.push(...value.providers);
+    else records.push(value);
+  };
+  try {
+    push(JSON.parse(body));
+    return records;
+  } catch {
+    // not one document — try it as a stream of them
+  }
+  for (const line of body.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      push(JSON.parse(trimmed));
+    } catch {
+      // a partial line at the end of a stream; nothing to do with it
+    }
+  }
+  return records;
+}
+
+/**
+ * Build a `fetchBytes(cid)` that goes over libp2p.
+ *
+ * Fits where `restoreFromCID`'s `fetchBytes` goes, so nothing downstream
+ * changes: the blocks are verified against their CIDs exactly as before, which
+ * is what makes a stranger's bytes as safe as a gateway's.
+ *
+ * @param {Object} options
+ * @param {Object} options.helia - a started Helia **with bitswap**
+ * @param {string[] | ((cid: string) => Promise<string[]>)} options.providers -
+ *   multiaddrs to dial, or a function that finds them for a CID
+ * @param {number} [options.timeout]
+ * @param {(addr: string) => Promise<unknown>} [options.dial] - defaults to the node's
+ * @param {(cid: any, options?: Object) => AsyncIterable<Uint8Array>} [options.cat] -
+ *   defaults to `@helia/unixfs`, which reads a chunked file as well as a single block
+ * @returns {(cid: string, options?: Object) => Promise<Uint8Array>}
+ */
+export function createPeerFetch({
+  helia,
+  providers = [],
+  timeout = DEFAULT_TIMEOUT_MS,
+  dial = null,
+  cat = null,
+  log = SILENT,
+} = {}) {
+  if (!helia && (!dial || !cat)) {
+    throw new Error("createPeerFetch needs a Helia node, or both dial and cat");
+  }
+
+  return async function fetchOverPeers(cid, options = {}) {
+    const signal = options.signal ?? AbortSignal.timeout(options.timeout ?? timeout);
+    const addrs =
+      typeof providers === "function" ? await providers(cid) : [...providers];
+
+    if (addrs.length === 0) {
+      throw new Error(`No provider to dial for ${cid}`);
+    }
+
+    const dialOne = dial ?? (async (addr) => {
+      const { multiaddr } = await import("@multiformats/multiaddr");
+      return helia.libp2p.dial(multiaddr(addr), { signal });
+    });
+
+    let dialed = 0;
+    for (const addr of addrs) {
+      try {
+        await dialOne(addr);
+        dialed += 1;
+        log.debug(`   ✅ dialled ${addr}`);
+      } catch (error) {
+        log.debug(`   ⚠️ could not dial ${addr}: ${error.message}`);
+      }
+    }
+    if (dialed === 0) {
+      throw new Error(`Could not dial any provider for ${cid} (tried ${addrs.length})`);
+    }
+
+    const read = cat ?? (await unixfsCat(helia));
+    const parts = [];
+    let total = 0;
+    for await (const chunk of read(cid, { signal })) {
+      parts.push(chunk);
+      total += chunk.length;
+    }
+    const bytes = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+      bytes.set(part, at);
+      at += part.length;
+    }
+    log.info(`   ✅ ${bytes.length} bytes over libp2p from ${dialed} peer(s)`);
+    return bytes;
+  };
+}
+
+/**
+ * `@helia/unixfs` rather than the blockstore: a backup large enough to be
+ * chunked is a DAG, and `blockstore.get` would return its root block and call
+ * that the file. Imported here so a caller that supplies `cat` never loads it.
+ */
+async function unixfsCat(helia) {
+  const [{ unixfs }, { CID }] = await Promise.all([
+    import("@helia/unixfs"),
+    import("multiformats/cid"),
+  ]);
+  const fs = unixfs(helia);
+  return (cid, options) => fs.cat(typeof cid === "string" ? CID.parse(cid) : cid, options);
+}
+
+/**
+ * Try HTTP first, then peers — and say which one delivered.
+ *
+ * The order is not a preference for HTTP: a warm gateway answered in 0.23 s
+ * against 0.86–1.9 s over libp2p, and a phone on a rationed connection should
+ * not open a swarm for a file one request would have fetched. But the timeout
+ * is short on purpose, because the other measurement from the same day is a
+ * gateway taking 29 s for a block a peer served in under one.
+ *
+ * @param {Object} options
+ * @param {(cid: string, options?: Object) => Promise<Uint8Array>} options.viaGateway
+ * @param {(cid: string, options?: Object) => Promise<Uint8Array>} options.viaPeers
+ * @param {number} [options.gatewayTimeout=3000] - before the peer path starts
+ * @param {(path: "gateway"|"peers", info: Object) => void} [options.onPath] -
+ *   told which path was taken and how long it took, so a page can show it
+ * @returns {(cid: string, options?: Object) => Promise<Uint8Array>}
+ */
+export function createGatewayFirstFetch({
+  viaGateway,
+  viaPeers,
+  gatewayTimeout = 3000,
+  onPath = () => {},
+  now = () => Date.now(),
+} = {}) {
+  return async function fetchBytes(cid, options = {}) {
+    const started = now();
+    try {
+      const bytes = await viaGateway(cid, { ...options, timeout: gatewayTimeout });
+      onPath("gateway", { cid, ms: now() - started, bytes: bytes.length });
+      return bytes;
+    } catch (error) {
+      const gatewayMs = now() - started;
+      const peersStarted = now();
+      try {
+        const bytes = await viaPeers(cid, options);
+        onPath("peers", {
+          cid,
+          ms: now() - peersStarted,
+          bytes: bytes.length,
+          after: { path: "gateway", ms: gatewayMs, error: error.message },
+        });
+        return bytes;
+      } catch (peerError) {
+        throw new Error(
+          `Could not fetch ${cid}: the gateway said "${error.message}" and the peers said "${peerError.message}"`,
+          { cause: peerError },
+        );
+      }
+    }
+  };
+}

package/lib/ucan-bridge.js

@@ -102,7 +102,7 @@ function findCorrectManifest(analysis) {
  */
 const DEFAULT_UCAN_OPTIONS = {
   timeout: 30000,
-  gateway: "https://w3s.link",
+  gateway: "https://ipfs.aleph.cloud", // w3s.link redirects to a gateway retired on 2026-09-21
   batchSize: 10,
   maxConcurrency: 3,
   // UCAN-specific options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-storage-bridge",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation",
   "main": "lib/orbitdb-storacha-bridge.js",
   "svelte": "dist/components/",
@@ -16,6 +16,7 @@
     "./dehydrate": "./lib/dehydrate.js",
     "./restore-cid": "./lib/restore-cid.js",
     "./gateway-fetch": "./lib/gateway-fetch.js",
+    "./peer-fetch": "./lib/peer-fetch.js",
     "./backends/types": "./lib/backends/types.js",
     "./backends/memory": "./lib/backends/memory.js",
     "./backends/storacha": "./lib/backends/storacha.js",
@@ -23,6 +24,9 @@
     "./backends/aleph-pin": "./lib/backends/aleph-pin.js",
     "./backends/pinata": "./lib/backends/pinata.js",
     "./backends/lighthouse": "./lib/backends/lighthouse.js",
+    "./backends/mirror": "./lib/backends/mirror.js",
+    "./backends/choose": "./lib/backends/choose.js",
+    "./backends/resolve": "./lib/backends/resolve.js",
     "./memory-courier": "./lib/memory-courier.js",
     "./StorachaIntegration.svelte": "./dist/components/StorachaIntegration.svelte",
     "./StorachaAuth.svelte": "./dist/components/StorachaAuth.svelte",
@@ -83,7 +87,6 @@
   "dependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
-    "@helia/block-brokers": "^5.2.4",
     "@helia/routers": "^5.1.1",
     "@helia/unixfs": "^8.0.7",
     "@ipld/car": "^5.4.1",
@@ -105,7 +108,7 @@
     "cbor-web": "^10.0.11",
     "datastore-level": "^13.0.1",
     "dotenv": "^17.2.1",
-    "helia": "^7.1.12",
+    "helia": "^7.1.15",
     "libp2p": "^3.3.6",
     "multiformats": "^14.0.5"
   },