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

package/lib/backends/encryption.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Encrypting what goes to a storage service, and decrypting what
+ * comes back.
+ *
+ * A backup leaves the browser as two opaque blobs — a CAR and a small metadata
+ * JSON — and the services that hold them neither need nor should have their
+ * contents. This wraps a backend so `putBlob` encrypts and `getBlob` decrypts,
+ * and **nothing above it changes**: `dehydrate`, `restoreFromCID`, the mirror,
+ * the gateway path and the peer path all move opaque bytes either way.
+ *
+ * ## The keys are the caller's
+ *
+ * This package knows nothing about passkeys, and should not: it takes two
+ * functions, exactly as `createBackendFromChoice` takes `normaliseAddress`
+ * rather than importing viem. A browser consumer derives them from the
+ * security key's PRF output — `@le-space/orbitdb-identity-provider-webauthn-did`
+ * ships `getPrfOutput`, `encryptWithAESGCM` and `decryptWithAESGCM` — and
+ * should derive a **separate** key for this, from the same secret with a
+ * different info string, so that a compromised backup key is not a signing key.
+ *
+ * ## The envelope, and why it is not just ciphertext
+ *
+ * Bytes on the way back can be one of three things: this envelope, a plaintext
+ * CAR from before backups were encrypted, or a plaintext CAR written with
+ * `dontEncrypt`. A restore has to tell them apart without being told, because
+ * a pointer does not carry that knowledge. So every ciphertext starts with a
+ * magic number and a version:
+ *
+ * ```
+ * "OSBE" | version | ivLength | iv | ciphertext
+ *   4        1          1       ~12     …
+ * ```
+ *
+ * A CAR begins with a varint length and a dag-cbor header, and JSON with `{`,
+ * so neither collides with the magic. The version is there for the day the
+ * algorithm changes: a backup from before it can then be refused with a
+ * reason rather than decrypted into noise.
+ *
+ * @module backends/encryption
+ */
+
+import { defineBackend, BackendError } from "./types.js";
+
+/** `OSBE` — orbitdb-storage-bridge, encrypted. */
+// Not frozen: freezing a typed array throws, because its elements live in a
+// buffer the engine will not seal.
+export const ENVELOPE_MAGIC = new Uint8Array([0x4f, 0x53, 0x42, 0x45]);
+
+/** Bumped when the envelope or the algorithm changes in a way readers must notice. */
+export const ENVELOPE_VERSION = 1;
+
+const HEADER_LENGTH = ENVELOPE_MAGIC.length + 2;
+
+/** Do these bytes start with an envelope this module wrote? */
+export function isEncrypted(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.length < HEADER_LENGTH) return false;
+  return ENVELOPE_MAGIC.every((byte, index) => bytes[index] === byte);
+}
+
+/**
+ * Wrap ciphertext and its IV so a reader can recognise both without being told.
+ *
+ * @param {Uint8Array} ciphertext
+ * @param {Uint8Array} iv
+ * @returns {Uint8Array}
+ */
+export function wrapEnvelope(ciphertext, iv) {
+  if (!(ciphertext instanceof Uint8Array) || !(iv instanceof Uint8Array)) {
+    throw new BackendError("INVALID_BACKEND", "encrypt must return Uint8Array ciphertext and iv");
+  }
+  if (iv.length > 255) {
+    throw new BackendError("INVALID_BACKEND", `An IV of ${iv.length} bytes does not fit the envelope`);
+  }
+  const out = new Uint8Array(HEADER_LENGTH + iv.length + ciphertext.length);
+  out.set(ENVELOPE_MAGIC, 0);
+  out[ENVELOPE_MAGIC.length] = ENVELOPE_VERSION;
+  out[ENVELOPE_MAGIC.length + 1] = iv.length;
+  out.set(iv, HEADER_LENGTH);
+  out.set(ciphertext, HEADER_LENGTH + iv.length);
+  return out;
+}
+
+/**
+ * Read an envelope back, refusing a version this build does not know.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{ ciphertext: Uint8Array, iv: Uint8Array, version: number }}
+ */
+export function readEnvelope(bytes) {
+  if (!isEncrypted(bytes)) {
+    throw new BackendError("INVALID_BACKEND", "These bytes are not an encrypted backup");
+  }
+  const version = bytes[ENVELOPE_MAGIC.length];
+  if (version !== ENVELOPE_VERSION) {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      `This backup was written with envelope version ${version}, and this build reads ${ENVELOPE_VERSION}. ` +
+        "Upgrade @le-space/orbitdb-storage-bridge to restore it.",
+    );
+  }
+  const ivLength = bytes[ENVELOPE_MAGIC.length + 1];
+  const iv = bytes.subarray(HEADER_LENGTH, HEADER_LENGTH + ivLength);
+  const ciphertext = bytes.subarray(HEADER_LENGTH + ivLength);
+  return { ciphertext, iv, version };
+}
+
+/**
+ * Encrypt on the way out, decrypt on the way back.
+ *
+ * @param {import("./types.js").StorageBackend} backend - the one that stores bytes
+ * @param {object} options
+ * @param {(plaintext: Uint8Array) => Promise<{ciphertext: Uint8Array, iv: Uint8Array}>} options.encrypt
+ * @param {(ciphertext: Uint8Array, iv: Uint8Array) => Promise<Uint8Array>} options.decrypt
+ * @param {boolean} [options.allowPlaintextReads=true] - restore a backup written
+ *   before backups were encrypted, or written with `dontEncrypt`. On by
+ *   default: a pointer does not say which kind it names, and refusing would
+ *   make yesterday's backups unreadable for no gain in secrecy.
+ * @returns {import("./types.js").StorageBackend}
+ */
+export function withEncryption(backend, { encrypt, decrypt, allowPlaintextReads = true } = {}) {
+  if (!backend || typeof backend.putBlob !== "function") {
+    throw new BackendError("INVALID_BACKEND", "withEncryption needs a backend to wrap");
+  }
+  if (typeof encrypt !== "function" || typeof decrypt !== "function") {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      "withEncryption needs encrypt and decrypt functions — this package holds no keys of its own",
+    );
+  }
+
+  const inner = backend;
+
+  return defineBackend({
+    ...inner,
+    name: `encrypted(${inner.name})`,
+    capabilities: {
+      ...inner.capabilities,
+      // The stored bytes are an envelope, not a CAR: nothing downstream may
+      // treat them as one, and there are no inner CIDs to preserve.
+      carImport: false,
+      preservesInnerCids: false,
+    },
+
+    async putBlob(bytes, meta) {
+      const { ciphertext, iv } = (await encrypt(bytes)) ?? {};
+      return inner.putBlob(wrapEnvelope(ciphertext, iv), meta);
+    },
+
+    async getBlob(handle) {
+      const bytes = await inner.getBlob(handle);
+      if (!isEncrypted(bytes)) {
+        if (allowPlaintextReads) return bytes;
+        throw new BackendError(
+          "INVALID_BACKEND",
+          "This backup is not encrypted, and allowPlaintextReads is off",
+        );
+      }
+      const { ciphertext, iv } = readEnvelope(bytes);
+      try {
+        return await decrypt(ciphertext, iv);
+      } catch (error) {
+        // The common cause by far is the wrong key — a different security key,
+        // or a key derived with a different info string. Say that, rather than
+        // letting an unreadable CAR surface three layers down.
+        throw new BackendError(
+          "INVALID_BACKEND",
+          `Could not decrypt this backup: ${error.message}. ` +
+            "It was written with a different key, or by a different derivation.",
+          { cause: error },
+        );
+      }
+    },
+  });
+}
+
+/**
+ * Decrypt on the way back, for the path a restore actually takes.
+ *
+ * `restoreFromCID` does not read through a backend: it takes `fetchBytes(cid)`
+ * and gets the bytes from a gateway or from peers, so `withEncryption`'s
+ * `getBlob` never runs during a restore. This is the other half — wrap the
+ * fetcher, and a backup written through an encrypting backend comes back
+ * readable however it was fetched.
+ *
+ * @param {(cid: string, options?: object) => Promise<Uint8Array>} fetchBytes
+ * @param {object} options
+ * @param {(ciphertext: Uint8Array, iv: Uint8Array) => Promise<Uint8Array>} options.decrypt
+ * @param {boolean} [options.allowPlaintextReads=true]
+ * @returns {(cid: string, options?: object) => Promise<Uint8Array>}
+ */
+export function decryptingFetch(fetchBytes, { decrypt, allowPlaintextReads = true } = {}) {
+  if (typeof fetchBytes !== "function") {
+    throw new BackendError("INVALID_BACKEND", "decryptingFetch needs a fetcher to wrap");
+  }
+  if (typeof decrypt !== "function") {
+    throw new BackendError("INVALID_BACKEND", "decryptingFetch needs a decrypt function");
+  }
+
+  return async function fetchAndDecrypt(cid, options) {
+    const bytes = await fetchBytes(cid, options);
+    if (!isEncrypted(bytes)) {
+      if (allowPlaintextReads) return bytes;
+      throw new BackendError(
+        "INVALID_BACKEND",
+        `The backup at ${cid} is not encrypted, and allowPlaintextReads is off`,
+      );
+    }
+    const { ciphertext, iv } = readEnvelope(bytes);
+    try {
+      return await decrypt(ciphertext, iv);
+    } catch (error) {
+      throw new BackendError(
+        "INVALID_BACKEND",
+        `Could not decrypt the backup at ${cid}: ${error.message}. ` +
+          "It was written with a different key, or by a different derivation.",
+        { cause: error },
+      );
+    }
+  };
+}
+
+/**
+ * Recognise an encrypted backup when there is no key to open it.
+ *
+ * Without this, a restore of an encrypted backup without `decrypt` fails deep
+ * inside the CAR reader — "unexpected end of data", or a block that will not
+ * verify — and the reason has nothing to do with what actually happened.
+ *
+ * @param {(cid: string, options?: object) => Promise<Uint8Array>} fetchBytes
+ * @returns {(cid: string, options?: object) => Promise<Uint8Array>}
+ */
+export function explainIfEncrypted(fetchBytes) {
+  return async function fetchAndCheck(cid, options) {
+    const bytes = await fetchBytes(cid, options);
+    if (isEncrypted(bytes)) {
+      throw new BackendError(
+        "INVALID_BACKEND",
+        `The backup at ${cid} is encrypted, and no way to decrypt it was given. ` +
+          "Pass `decrypt` to hydrate() — a browser derives it from the security key.",
+      );
+    }
+    return bytes;
+  };
+}
+
+export default withEncryption;

package/lib/dehydrate.js

@@ -61,15 +61,33 @@ export async function dehydrate({
   seed,
   label,
   backend,
+  encrypt,
+  decrypt,
+  dontEncrypt = false,
   endpoints = DEFAULT_ENDPOINTS,
   sequence,
   backup = {},
 }) {
   if (!address) throw new Error("dehydrate needs the database address");
+
+  // Encrypted by default. A caller who wants the backup readable by anyone
+  // holding the CID has to write that down, because it is a decision rather
+  // than an oversight — and an oversight is what this refusal exists to catch.
+  if (!encrypt && !dontEncrypt) {
+    throw new Error(
+      "Backups are encrypted by default. Pass `encrypt` and `decrypt` — a browser " +
+        "derives them from the security key — or `dontEncrypt: true` if this backup " +
+        "is meant to be readable by anyone holding the CID.",
+    );
+  }
+
   const { backupDatabaseCAR } = await import("./backup-car.js");
+  const storeIn = encrypt
+    ? (await import("./backends/encryption.js")).withEncryption(backend, { encrypt, decrypt })
+    : backend;
 
   const result = await backupDatabaseCAR(orbitdb, address, {
-    backend,
+    backend: storeIn,
     ...backup,
   });
   if (!result?.success) {
@@ -118,6 +136,7 @@ export async function hydrate({
   orbitdb,
   seed,
   label,
+  decrypt,
   endpoints = DEFAULT_ENDPOINTS,
   open = {},
   restore = {},
@@ -126,10 +145,22 @@ export async function hydrate({
   const pointer = await resolvePointer({ privateKey, endpoints });
 
   const { restoreFromCID } = await import("./restore-cid.js");
+  const { decryptingFetch, explainIfEncrypted } = await import("./backends/encryption.js");
+  const { fetchFromGateways } = await import("./gateway-fetch.js");
+
+  // A restore does not read through a backend — it fetches from a gateway or
+  // from peers — so decryption belongs here, around the fetcher. Without a
+  // key, an encrypted backup is still recognised, and says so.
+  const fetchBytes = restore.fetchBytes ?? fetchFromGateways;
+  const reader = decrypt
+    ? decryptingFetch(fetchBytes, { decrypt })
+    : explainIfEncrypted(fetchBytes);
+
   const result = await restoreFromCID(orbitdb, {
     metadataCID: pointer.cid,
     open,
     ...restore,
+    fetchBytes: reader,
   });
 
   logger.info(

package/lib/peer-fetch.js

@@ -33,11 +33,30 @@
  *
  * ## 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: [] }`.
+ * A Helia with bitswap **and identify**. 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.
+ *
+ * Two things about that node are easy to get wrong, and both were:
+ *
+ * - **`identify` is not optional.** `withLibp2pLight` does not include it, and
+ *   without it bitswap never learns that the peer it just dialled speaks
+ *   bitswap: no want is sent, and the fetch fails with "Failed to load block"
+ *   after the full timeout. Measured against Aleph: 60 s of nothing without
+ *   identify, 1.6 s for 400 kB with it, over the same dialled connection.
+ * - **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: [] }`.
+ *
+ * ```js
+ * const helia = await withBitswap(withLibp2pLight(createHeliaLight({ … }), {
+ *   addresses: { listen: [] },
+ *   transports: [webSockets(), webRTCDirect()],
+ *   connectionEncrypters: [noise()],
+ *   streamMuxers: [yamux()],
+ *   services: { identify: identify() },   // ← without this, nothing arrives
+ * })).start()
+ * ```
  *
  * @module peer-fetch
  */
@@ -90,25 +109,25 @@ export const ALEPH_PEER_ID = "12D3KooWACE5dRw5V9WXuDTcngjE3ZaDSZ4qYJGfuhXZbENnL5
 /**
  * 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.
+ * Both send `access-control-allow-origin: *` for provider lookups. An earlier
+ * version of this file said `delegated-ipfs.dev` did not, from one request that
+ * came back without the header; repeated from a deployed page it answers with
+ * it, so the restriction was wrong and this list is both.
  *
- * They also know different things, which matters more than the CORS header:
+ * What is true, and matters more, is that they know **different things**:
  * `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.
+ * CIDs and Lighthouse's were there — while a CID that Aleph holds appeared only
+ * at `delegated-ipfs.dev`, because Aleph announces over the DHT. Asking one
+ * router is asking half the network.
  */
-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([
+export const DEFAULT_ROUTERS = Object.freeze([
   "https://cid.contact",
   "https://delegated-ipfs.dev",
 ]);
 
+/** @deprecated Same as {@link DEFAULT_ROUTERS}; kept so an import still works. */
+export const ALL_ROUTERS = DEFAULT_ROUTERS;
+
 /**
  * Transports a browser can dial.
  *
@@ -266,16 +285,23 @@ export function createPeerFetch({
       return helia.libp2p.dial(multiaddr(addr), { signal });
     });
 
-    let dialed = 0;
+    // One connection per peer, not one per address. A provider usually
+    // advertises the same peer several times — Aleph offers webrtc-direct and
+    // webtransport — and dialling both gets two connections to one node, which
+    // buys nothing and makes a peer count read double.
+    const reached = new Set();
     for (const addr of addrs) {
+      const peer = addr.match(/\/p2p\/([^/]+)/)?.[1] ?? addr;
+      if (reached.has(peer)) continue;
       try {
         await dialOne(addr);
-        dialed += 1;
+        reached.add(peer);
         log.debug(`   ✅ dialled ${addr}`);
       } catch (error) {
         log.debug(`   ⚠️ could not dial ${addr}: ${error.message}`);
       }
     }
+    const dialed = reached.size;
     if (dialed === 0) {
       throw new Error(`Could not dial any provider for ${cid} (tried ${addrs.length})`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-storage-bridge",
-  "version": "0.12.0",
+  "version": "0.13.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/",
@@ -25,6 +25,7 @@
     "./backends/pinata": "./lib/backends/pinata.js",
     "./backends/lighthouse": "./lib/backends/lighthouse.js",
     "./backends/mirror": "./lib/backends/mirror.js",
+    "./backends/encryption": "./lib/backends/encryption.js",
     "./backends/choose": "./lib/backends/choose.js",
     "./backends/resolve": "./lib/backends/resolve.js",
     "./memory-courier": "./lib/memory-courier.js",