@le-space/orbitdb-storage-bridge 0.10.0

package/lib/pointer-ipns.js

@@ -0,0 +1,234 @@
+/**
+ * A pointer a second device can find with nothing but a key.
+ *
+ * The problem this solves is not storage — a backup's CID is enough to fetch
+ * it from anywhere — but *naming*: a device that has lost everything cannot be
+ * told a CID, because there is nobody left to tell it. So the name has to be
+ * computable from the one thing that survived. Derive a key from a seed, and
+ * the IPNS name follows from the key; two devices holding the same seed
+ * compute the same name without ever exchanging anything.
+ *
+ * The seed is the caller's business. A passkey's PRF output is the case this
+ * was written for (funkpost#93), and it never passes through here as anything
+ * but bytes to stretch.
+ *
+ * Publication goes over **delegated routing** — `PUT /routing/v1/ipns/{name}`
+ * — because a browser cannot join the DHT, and `w3name`, which used to stand
+ * in for this, was Storacha's and Storacha is gone. Measured against
+ * `delegated-ipfs.dev` on 2026-09-19, from Node and from a page on a foreign
+ * origin: the preflight allows `PUT` from anywhere, the PUT is accepted, and
+ * the GET returns the record byte for byte
+ * (`test/helpers/probe-ipns-routing.js`).
+ *
+ * Two things that probe could not establish, and this module therefore does
+ * not promise: that a record travels beyond the endpoint that accepted it, and
+ * how long it is kept. Publish to more than one endpoint where that matters,
+ * and treat a pointer as a shortcut for a device that comes back soon rather
+ * than as an archive.
+ */
+
+import {
+  createIPNSRecord,
+  marshalIPNSRecord,
+  unmarshalIPNSRecord,
+  multihashToIPNSRoutingKey,
+} from "ipns";
+import { ipnsValidator } from "ipns/validator";
+import { generateKeyPairFromSeed } from "@libp2p/crypto/keys";
+import { peerIdFromPrivateKey, peerIdFromString } from "@libp2p/peer-id";
+import { CID } from "multiformats/cid";
+import { base36 } from "multiformats/bases/base36";
+import logger from "./logger.js";
+
+const log = logger.child ? logger.child({ module: "pointer-ipns" }) : logger;
+
+/** libp2p-key, the codec an IPNS name is a CID of. */
+const LIBP2P_KEY_CODEC = 0x72;
+
+/**
+ * Bumping this changes every name a seed produces, so treat it as a breaking
+ * change: pointers published under the old one become unfindable.
+ */
+export const POINTER_INFO = "orbitdb-storage-bridge:pointer-ipns:v1";
+
+/** Public endpoints that speak delegated routing v1. */
+export const DEFAULT_ENDPOINTS = ["https://delegated-ipfs.dev"];
+
+const DEFAULT_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000; // what a record claims for itself
+const DEFAULT_TIMEOUT_MS = 30_000;
+const RECORD_CONTENT_TYPE = "application/vnd.ipfs.ipns-record";
+
+/**
+ * Stretch a seed into the key whose name the pointer lives under.
+ *
+ * HKDF-SHA256, with `label` mixed into the info string so one seed can name
+ * several pointers without their keys being related in any usable way.
+ *
+ * @param {Uint8Array} seed Secret bytes — a PRF output, say. Never published.
+ * @param {Object} [options]
+ * @param {string} [options.label=""] Distinguishes pointers of one seed.
+ * @param {string} [options.info=POINTER_INFO] Domain separation.
+ * @returns {Promise<Object>} A libp2p Ed25519 private key.
+ */
+export async function derivePointerKey(
+  seed,
+  { label = "", info = POINTER_INFO } = {},
+) {
+  if (!(seed instanceof Uint8Array) || seed.length === 0) {
+    throw new Error("derivePointerKey needs seed bytes");
+  }
+  const base = await globalThis.crypto.subtle.importKey(
+    "raw",
+    seed,
+    "HKDF",
+    false,
+    ["deriveBits"],
+  );
+  const bits = await globalThis.crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(0),
+      info: new TextEncoder().encode(label ? `${info}:${label}` : info),
+    },
+    base,
+    256,
+  );
+  return generateKeyPairFromSeed("Ed25519", new Uint8Array(bits));
+}
+
+/**
+ * The IPNS name of a key, as routing endpoints and gateways spell it.
+ *
+ * @param {Object} key A libp2p private or public key.
+ * @returns {string} base36 `k51…`
+ */
+export function pointerName(key) {
+  const publicKey = key.publicKey ?? key;
+  const peerId = key.publicKey
+    ? peerIdFromPrivateKey(key)
+    : (publicKey.toPeerId?.() ?? publicKey);
+  return CID.createV1(LIBP2P_KEY_CODEC, peerId.toMultihash()).toString(base36);
+}
+
+const multihashOfName = (name) => peerIdFromString(name).toMultihash();
+
+/**
+ * Put a CID under the name this key derives, at every endpoint given.
+ *
+ * Resolves as soon as one endpoint has taken it; the rest are still tried, and
+ * what each of them said comes back in `results` — a pointer that reached one
+ * endpoint is published, and a pointer that reached three is more likely to be
+ * found later.
+ *
+ * @param {Object} params
+ * @param {Object} params.privateKey From `derivePointerKey`.
+ * @param {string|Object} params.cid What the pointer points at.
+ * @param {string[]} [params.endpoints]
+ * @param {bigint|number} [params.sequence] Must only ever grow for a name.
+ *   Seconds since the epoch by default, which is monotonic enough for a
+ *   pointer written by hand and readable in a log.
+ * @param {number} [params.lifetimeMs]
+ * @param {AbortSignal} [params.signal]
+ * @returns {Promise<{name: string, sequence: bigint, results: Array<{endpoint: string, ok: boolean, status?: number, error?: string}>}>}
+ */
+export async function publishPointer({
+  privateKey,
+  cid,
+  endpoints = DEFAULT_ENDPOINTS,
+  sequence = BigInt(Math.floor(Date.now() / 1000)),
+  lifetimeMs = DEFAULT_LIFETIME_MS,
+  signal,
+}) {
+  const value = typeof cid === "string" ? CID.parse(cid) : cid;
+  const record = await createIPNSRecord(
+    privateKey,
+    value,
+    BigInt(sequence),
+    lifetimeMs,
+  );
+  const body = marshalIPNSRecord(record);
+  const name = pointerName(privateKey);
+
+  const results = await Promise.all(
+    endpoints.map(async (endpoint) => {
+      try {
+        const response = await fetch(pointerUrl(endpoint, name), {
+          method: "PUT",
+          headers: { "Content-Type": RECORD_CONTENT_TYPE },
+          body,
+          signal: signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        });
+        return { endpoint, ok: response.ok, status: response.status };
+      } catch (error) {
+        return { endpoint, ok: false, error: error.message };
+      }
+    }),
+  );
+
+  if (!results.some((result) => result.ok)) {
+    const reasons = results
+      .map((result) => `${result.endpoint}: ${result.error ?? result.status}`)
+      .join("; ");
+    throw new Error(`no endpoint took the pointer (${reasons})`);
+  }
+  log.info?.("📍 pointer %s → %s", name, value.toString());
+  return { name, sequence: BigInt(sequence), results };
+}
+
+/**
+ * Read a pointer back, from whichever endpoint answers with a valid record.
+ *
+ * Every record is checked against the name it was asked for before it is
+ * believed: the name is the hash of the key that signs, so an endpoint cannot
+ * hand back somebody else's pointer, or an altered one, without being caught.
+ *
+ * @param {Object} params
+ * @param {string} [params.name] The name, if the caller has it.
+ * @param {Object} [params.privateKey] Or the key, and the name follows.
+ * @param {string[]} [params.endpoints]
+ * @param {AbortSignal} [params.signal]
+ * @returns {Promise<{name: string, cid: string, sequence: bigint, validity: string|undefined}>}
+ */
+export async function resolvePointer({
+  name,
+  privateKey,
+  endpoints = DEFAULT_ENDPOINTS,
+  signal,
+}) {
+  const pointer = name ?? (privateKey ? pointerName(privateKey) : null);
+  if (!pointer) throw new Error("resolvePointer needs a name or a key");
+  const routingKey = multihashToIPNSRoutingKey(multihashOfName(pointer));
+
+  const failures = [];
+  for (const endpoint of endpoints) {
+    try {
+      const response = await fetch(pointerUrl(endpoint, pointer), {
+        headers: { Accept: RECORD_CONTENT_TYPE },
+        signal: signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        failures.push(`${endpoint}: ${response.status}`);
+        continue;
+      }
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      await ipnsValidator(routingKey, bytes); // signed by this name, or nothing
+      const record = unmarshalIPNSRecord(bytes);
+      return {
+        name: pointer,
+        cid: String(record.value).replace(/^\/ipfs\//, ""),
+        sequence: record.sequence,
+        validity: record.validity,
+      };
+    } catch (error) {
+      failures.push(`${endpoint}: ${error.message}`);
+    }
+  }
+  throw new Error(
+    `no endpoint had a valid pointer for ${pointer} (${failures.join("; ")})`,
+  );
+}
+
+function pointerUrl(endpoint, name) {
+  return `${endpoint.replace(/\/$/, "")}/routing/v1/ipns/${name}`;
+}

package/lib/restore-cid.js

@@ -0,0 +1,302 @@
+/**
+ * Restore an OrbitDB database from a single CID — no Storacha client.
+ *
+ * `restoreFromSpaceCAR` can already do this: hand it a `metadataCID` and it
+ * resolves the blocks CAR out of the metadata and fetches both from public
+ * gateways, with no credentials on the restoring side. The problem was never
+ * the capability, it was the import — `backup-car.js` reaches into
+ * `orbitdb-storacha-bridge.js`, which pulls in `@storacha/client` at module
+ * level, so a peer that only ever *reads* paid for the whole backup SDK.
+ *
+ * Measured against a real consumer (funkpost's `mesh-todo`, 561 kB gzipped):
+ * importing `restoreFromSpaceCAR` added **617 kB gzipped**; what the steps
+ * below actually need adds about **11 kB**, because a consumer of this package
+ * already ships `multiformats` and `@ipld/dag-cbor`, leaving `@ipld/car`.
+ *
+ * So this module imports no client, no space, no proof, no Helia — and no
+ * logger, which is not a detail: the package's logger reaches `@libp2p/logger`,
+ * and pulling a logging framework in behind a progress line would undo most of
+ * the saving. Both the fetching and the logging are **injectable** instead: the
+ * default fetch is `fetch` against public gateways, the default log is silence,
+ * and a caller that wants either of the package's own versions passes it.
+ *
+ * ## Why a peer that only restores is a real shape
+ *
+ * Backing up needs an account. Reading a backup does not — a CID is a name that
+ * anyone can resolve. Alice keeps the space; Bob has a link. Over a courier
+ * where a byte is rationed this is the difference between announcing a whole
+ * database and announcing where one is: a CID fits in a single LoRa frame.
+ *
+ * @module restore-cid
+ */
+
+import { CarReader } from "@ipld/car";
+import { CID } from "multiformats/cid";
+import { base58btc } from "multiformats/bases/base58";
+import * as Block from "multiformats/block";
+import * as dagCbor from "@ipld/dag-cbor";
+import { sha256, sha512 } from "multiformats/hashes/sha2";
+import { isValidMetadata } from "./backup-metadata.js";
+// Re-exported below, so `restore-cid`'s surface is unchanged by the move.
+import { DEFAULT_GATEWAYS, SILENT, fetchFromGateways } from "./gateway-fetch.js";
+
+export { DEFAULT_GATEWAYS, SILENT, fetchFromGateways };
+
+const sameBytes = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+
+/**
+ * One spelling of a CID, so two of them can be compared.
+ *
+ * The same block is called `zdpuAw…` by OrbitDB, which addresses in base58btc,
+ * and `bafyrei…` inside a CAR, which uses the CID's own base32. Both are the
+ * same 32 bytes wearing different clothes, and comparing the strings says they
+ * are different — a mistake that reads as "the block is missing" and is
+ * therefore very easy to believe.
+ */
+const canonical = (value) => {
+  try {
+    return CID.parse(String(value)).toV1().toString();
+  } catch {
+    return null;
+  }
+};
+
+/** dag-cbor. Only these blocks can be OrbitDB log entries. */
+const DAG_CBOR = 0x71;
+
+/** By multihash code, so a block can be checked against the CID that names it. */
+const HASHERS = new Map([
+  [sha256.code, sha256],
+  [sha512.code, sha512],
+]);
+
+/**
+ * Every block in a CAR, by CID string — each one checked against its own name.
+ *
+ * **`CarReader` does not do this**, and the omission is easy to miss because it
+ * looks like it must: it hands back whatever CID the file claims for whatever
+ * bytes sit next to it, unverified. A CAR can therefore carry a block labelled
+ * with one CID and containing something else entirely, and a restore would put
+ * the attacker's bytes into the blockstore under a name the application trusts.
+ *
+ * That risk used to be bounded by where the bytes came from — your own space,
+ * on a service you had an account with. This module deliberately removed that
+ * boundary: it fetches from public gateways and takes an injected fetch, so the
+ * bytes can come from anywhere. Verification is what makes that safe, and it is
+ * the property worth having rather than a mitigation: **once every block is
+ * checked against its CID, where it came from stops mattering.** A hostile
+ * mirror, a stale gateway, a file on a USB stick — none of them can forge a
+ * block, only fail to provide one.
+ *
+ * @param {Uint8Array} carBytes
+ * @param {Object} [options]
+ * @param {boolean} [options.verify=true] Only turn this off for bytes you
+ *   produced yourself and have not let out of your sight.
+ * @returns {Promise<Map<string, { bytes: Uint8Array }>>}
+ */
+export async function readBlocksFromCAR(carBytes, { verify = true } = {}) {
+  const reader = await CarReader.fromBytes(carBytes);
+  const blocks = new Map();
+
+  for await (const block of reader.blocks()) {
+    const name = block.cid.toString();
+
+    if (verify) {
+      const hasher = HASHERS.get(block.cid.multihash.code);
+      // Refused rather than waved through: a hash we cannot compute is a block
+      // we cannot vouch for, and silently accepting it would defeat the point.
+      if (!hasher) {
+        throw new Error(
+          `Block ${name} uses multihash 0x${block.cid.multihash.code.toString(16)}, which this reader cannot verify`,
+        );
+      }
+      const digest = await hasher.digest(block.bytes);
+      if (!sameBytes(digest.digest, block.cid.multihash.digest)) {
+        throw new Error(`Block ${name} does not hash to its own CID — the CAR has been tampered with`);
+      }
+    }
+
+    blocks.set(name, { bytes: block.bytes });
+  }
+
+  return blocks;
+}
+
+/**
+ * The heads of a hash-linked log: entries nothing else points back to.
+ *
+ * Derived from the blocks rather than carried in the metadata, because the
+ * blocks are the truth and a stated head can be stale. A block counts as a log
+ * entry only if it is dag-cbor *and* carries a signature, key and identity —
+ * the manifest and the access controller are dag-cbor too.
+ */
+async function headsIn(blocks) {
+  const entries = [];
+  const pointedAt = new Set();
+
+  for (const [cidString, { bytes }] of blocks) {
+    let cid;
+    try {
+      cid = CID.parse(cidString);
+    } catch {
+      continue;
+    }
+    if (cid.code !== DAG_CBOR) continue;
+
+    try {
+      const { value } = await Block.decode({ cid, bytes, codec: dagCbor, hasher: sha256 });
+      if (!value?.sig || !value?.key || !value?.identity) continue;
+      entries.push({ hash: cid.toV1().toString(base58btc), value });
+      if (Array.isArray(value.next)) for (const next of value.next) pointedAt.add(next);
+    } catch {
+      /* not a block we can read; the CAR may hold more than this log */
+    }
+  }
+
+  return entries.filter((entry) => !pointedAt.has(entry.hash));
+}
+
+/**
+ * Restore a database from the CID of a CAR backup's metadata.
+ *
+ * Everything hangs off that one CID: the metadata names the CAR, the CAR holds
+ * the blocks, and the blocks carry their own addresses. Nothing here talks to
+ * Storacha, so the caller needs no space, key or proof — only a way to fetch
+ * bytes, which by default is `fetch` against public gateways.
+ *
+ * **The returned `database` replaces any handle the caller already held on this
+ * address.** The log has to be reopened to read the blocks put underneath it,
+ * and `orbitdb.open` hands out one instance per address — so the instance that
+ * gets closed here is the caller's own, and writing through it afterwards fails
+ * on an aborted signal.
+ *
+ * @param {Object} orbitdb an OrbitDB instance to restore into
+ * @param {Object} options
+ * @param {string} options.metadataCID the pointer — what `backupDatabaseCAR`
+ *   returns as `backupFiles.metadataCID`
+ * @param {string[]} [options.gateways]
+ * @param {number} [options.timeout] per request, in ms
+ * @param {AbortSignal} [options.signal]
+ * @param {boolean} [options.verify=true] Check every block against its own
+ *   CID, and that the CAR really holds the manifest this backup names. Leaving
+ *   it on is what makes an untrusted source acceptable.
+ * @param {{ info: Function, warn: Function, debug: Function }} [options.log]
+ *   where to report progress; silent unless given. Pass the package's own
+ *   `logger` for the verbose behaviour `restoreFromSpaceCAR` has.
+ * @param {(cid: string, options: Object) => Promise<Uint8Array>} [options.fetchBytes]
+ *   how to resolve a CID. Injected rather than imported so that a caller with
+ *   its own IPFS node can use it without every caller bundling one.
+ * @param {Object} [options.open] options for `orbitdb.open`, merged over the
+ *   type the backup names. A node without pubsub needs `{ sync: false }` here:
+ *   OrbitDB's Sync subscribes on open, and on a libp2p built without a pubsub
+ *   service that throws before the database is ever handed back.
+ * @returns {Promise<{ address: string, database: Object, blocks: number,
+ *   entries: number, heads: number, joined: number }>}
+ */
+export async function restoreFromCID(orbitdb, options = {}) {
+  const { metadataCID, fetchBytes = fetchFromGateways, log = SILENT, verify = true, open = {}, ...rest } = options;
+
+  if (!orbitdb?.ipfs?.blockstore) throw new Error("An OrbitDB instance is required");
+  if (!metadataCID) throw new Error("A metadataCID is required");
+
+  log.info(`🔄 Restoring from ${metadataCID}`);
+
+  // 1 · the metadata names everything else
+  const metadataBytes = await fetchBytes(metadataCID, { ...rest, log });
+  let metadata;
+  try {
+    metadata = JSON.parse(new TextDecoder().decode(metadataBytes));
+  } catch (error) {
+    throw new Error(`Backup metadata at ${metadataCID} is not JSON: ${error.message}`, { cause: error });
+  }
+  if (!isValidMetadata(metadata)) throw new Error("Invalid backup metadata");
+
+  // Everything the metadata must name, checked before anything is downloaded —
+  // a CAR is the large fetch here, and finding out afterwards that there is no
+  // address to open it into wastes the whole transfer.
+  const carCID = metadata.carCID;
+  if (!carCID) throw new Error("Backup metadata names no CAR file");
+
+  const dbInfo = metadata.databases?.[0];
+  if (!dbInfo?.address) {
+    // `isValidMetadata` also accepts the older `{ root, path }` shape, which
+    // predates CAR backups and has no address to open. Say which it is.
+    throw new Error(
+      dbInfo ? "This is a pre-CAR backup; restoreFromCID needs a CAR backup" : "Backup metadata names no database",
+    );
+  }
+
+  // 2 · the CAR holds the blocks, and each one is checked against its own CID
+  const blocks = await readBlocksFromCAR(await fetchBytes(carCID, { ...rest, log }), { verify });
+  log.info(`   ✅ ${blocks.size} blocks`);
+
+  // The blocks verify individually; this is what ties them to *this* backup.
+  // Without it a CAR full of perfectly valid blocks from some other database
+  // would restore happily, because every block would be honest about itself.
+  const manifestCID = dbInfo.manifestCID ?? metadata.manifestCID;
+  if (verify && manifestCID) {
+    const wanted = canonical(manifestCID);
+    const present = new Set([...blocks.keys()].map(canonical));
+    if (!wanted || !present.has(wanted)) {
+      throw new Error(
+        `The CAR does not contain the manifest ${manifestCID} that this backup names`,
+      );
+    }
+  }
+
+  // 3 · into the blockstore, and into the log's own storage
+  //
+  // Both, and not by accident: the blockstore is where Helia looks, while
+  // OrbitDB's log reads from its own store and addresses blocks in base58btc
+  // rather than the CAR's base32. A restore that fills only one of them opens
+  // a database that is empty in a way nothing reports.
+  let stored = 0;
+  for (const [cidString, { bytes }] of blocks) {
+    try {
+      await orbitdb.ipfs.blockstore.put(CID.parse(cidString), bytes);
+      stored++;
+    } catch (error) {
+      log.warn(`   ⚠️ could not store ${cidString.slice(0, 12)}…: ${error.message}`);
+    }
+  }
+
+  const opened = await orbitdb.open(dbInfo.address, { type: dbInfo.type, ...open });
+  for (const [cidString, { bytes }] of blocks) {
+    try {
+      await opened.log.storage.put(CID.parse(cidString).toV1().toString(base58btc), bytes);
+    } catch (error) {
+      log.warn(`   ⚠️ could not copy ${cidString.slice(0, 12)}… to log storage: ${error.message}`);
+    }
+  }
+
+  // Reopened so the log reads what we just put underneath it.
+  await opened.close();
+  const database = await orbitdb.open(dbInfo.address, { type: dbInfo.type, ...open });
+
+  // 4 · tell the log where its history ends
+  const heads = await headsIn(blocks);
+  let joined = 0;
+  for (const head of heads) {
+    try {
+      const { v, id, key, sig, next, refs, clock, payload, identity } = head.value;
+      if (await database.log.joinEntry({ hash: head.hash, v, id, key, sig, next, refs, clock, payload, identity })) {
+        joined++;
+      }
+    } catch (error) {
+      log.warn(`   ⚠️ could not join head ${head.hash.slice(0, 12)}…: ${error.message}`);
+    }
+  }
+
+  log.info(`✅ Restored ${dbInfo.address} — ${stored} blocks, ${joined}/${heads.length} heads`);
+
+  return {
+    address: dbInfo.address,
+    database,
+    blocks: stored,
+    entries: metadata.totalEntries ?? dbInfo.entryCount ?? null,
+    heads: heads.length,
+    joined,
+  };
+}
+
+export default { restoreFromCID, fetchFromGateways, readBlocksFromCAR, DEFAULT_GATEWAYS, SILENT };