@le-space/orbitdb-storage-bridge 0.10.0 → 0.11.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]
@@ -157,7 +157,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 +169,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 +224,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/choose.js

@@ -0,0 +1,145 @@
+/**
+ * @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.
+ *
+ * ## 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";
+
+/** 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[]} [choice.gateways] - retrieval gateways, where the driver takes them
+ * @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) {
+    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 gateways = choice.gateways ? { gateways: choice.gateways } : {};
+  const extra = choice.options ?? {};
+
+  if (kind === "aleph") {
+    const { createAlephBackend } = await import("./aleph.js");
+    return createAlephBackend({ ...gateways, ...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 } : {}),
+      ...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",
+      ...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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-storage-bridge",
-  "version": "0.10.0",
+  "version": "0.11.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/",
@@ -23,6 +23,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",