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

package/lib/backends/aleph-pin.js

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

package/lib/courier-sync.js

@@ -127,6 +127,13 @@ const CHANGE_ID_LENGTH = 8;
 // How many change ids to remember. A duplicate arriving after this many others
 // is applied twice: one extra entry in the log, not a wrong value.
 const SEEN_OPS = 512;
+// How many operations may wait for a deliberate send before the batch goes as
+// a delta instead. Not a memory limit: the outbox holds `maxOutbox` (32) and
+// sheds the oldest when it overflows, and an operation is the one message here
+// that is *not* re-derivable — so a long batch of them would lose writes
+// quietly. A delta is one message and complete by construction, which is the
+// right shape once a batch is large enough to threaten that.
+const MAX_PENDING_OPS = 16;
 
 // Four bytes of sender id: enough that two peers in one conversation collide
 // with probability ~1 in 4 billion, small enough to ride on every message.
@@ -640,6 +647,10 @@ export async function createCourierSync({
   const peers = new Map(); // sender id (hex) -> when we last heard it
   let lastHeardAt = null; // any traffic for this database, identified or not
   const listeners = { synced: [], applied: [], message: [], error: [] };
+  // Written locally and not yet sent, oldest first. Only fills when the
+  // operation plane is on and the application has opted out of sending on
+  // every write — the batching case, where a button decides.
+  const pendingOps = [];
   // Change ids already applied, oldest first. Insertion-ordered, so the oldest
   // key is the first one Map iteration yields.
   const seenOps = new Map();
@@ -847,6 +858,31 @@ export async function createCourierSync({
     await send(message);
   };
 
+  /**
+   * Everything written since the last deliberate send, as operations.
+   *
+   * Answers how many went, so the caller can tell "I sent your changes" from
+   * "there was nothing to send, so I asked the peer to reconcile" — which is
+   * what an announce means when the queue is empty.
+   *
+   * Past `MAX_PENDING_OPS` the batch goes as a delta instead. Not arbitrary:
+   * the outbox holds `maxOutbox` messages and sheds the oldest, and an
+   * operation is the one message here that cannot be re-derived, so a long
+   * batch of them would lose writes without saying so. One delta is one
+   * message and carries all of it.
+   */
+  const flushOperations = async () => {
+    if (pendingOps.length === 0) return 0;
+    const going = pendingOps.splice(0, pendingOps.length);
+    if (going.length > MAX_PENDING_OPS) {
+      emit("message", { direction: "out", type: "batch-too-long", bytes: 0 });
+      await announce(true);
+      return going.length;
+    }
+    for (const entry of going) await shipOperation(entry);
+    return going.length;
+  };
+
   /**
    * Announce without waiting for delivery — for callers that sit on the
    * receive queue, where waiting for the radio is the head-of-line block this
@@ -878,13 +914,22 @@ export async function createCourierSync({
   };
 
   const watchLocalUpdates = () => {
-    // Opted out: the application announces when it decides to, not when a write
-    // happens. Incoming announces are still answered, so a peer asking for
-    // blocks is served — going quiet must not mean going deaf.
-    if (!announceOnLocalUpdate) return;
+    // On the delta plane, opting out means not watching at all: the application
+    // announces when it decides to. On the operation plane it means something
+    // else — the write still has to be *remembered*, or the deliberate send has
+    // nothing to send. So the hook goes on either way there, and only what it
+    // does with the entry changes.
+    //
+    // Incoming announces are still answered in both cases: going quiet must not
+    // mean going deaf.
+    if (!announceOnLocalUpdate && liveUpdates !== "operations") return;
     if (!database || offUpdate) return;
     const onUpdate = (entry) => {
       if (applying) return; // courier-applied entries already end in an announce
+      if (liveUpdates === "operations" && !announceOnLocalUpdate) {
+        pendingOps.push(entry);
+        return; // waits for the application to ask
+      }
       queue = queue
         .then(() =>
           liveUpdates === "operations" ? shipOperation(entry) : announceSoon(),
@@ -1183,7 +1228,18 @@ export async function createCourierSync({
       }
     },
     /** Re-announce — recovery poke after suspected loss. */
-    announce: () => announce(true),
+    /**
+     * What an application's "send" button means.
+     *
+     * With changes waiting, it sends those — that is what the press was about.
+     * With none, it is a request to reconcile, which is what it always was.
+     * Internal announces never flush: the acknowledgement that ends a blocks
+     * delivery must not spend somebody's queued writes on its own.
+     */
+    announce: async () => {
+      if ((await flushOperations()) > 0) return;
+      await announce(true);
+    },
     /** This instance's sender id, as it appears on the wire. */
     peerId: hex(peerId),
     /**

package/lib/extract-blocks.js

@@ -256,3 +256,76 @@ export async function extractDatabaseBlocks(database, options = {}) {
   logger.info(`   📊 Extracted ${blocks.size} total blocks`);
   return { blocks, blockSources, manifestCID };
 }
+
+/**
+ * Several databases in one backup: every block of each, in one Map, and the
+ * metadata that names them all.
+ *
+ * The metadata is the shape `backupDatabaseCAR` writes and `isValidMetadata`
+ * accepts — `databases` was always a list, and here it finally holds more than
+ * one. Each entry also names the database's **heads**: `restoreFromBlocks` can
+ * find them from the blocks alone, but a stated head says which entries the
+ * writer considered current when the backup ran, and costs a few bytes.
+ *
+ * Blocks two databases share — a writer's identity — are kept once: the Map is
+ * keyed by the CID string OrbitDB uses, and the same block has the same name.
+ *
+ * @param {Object[]|Object<string, Object>} databases opened OrbitDB databases,
+ *   as a list or by name
+ * @param {Object} [options]
+ * @param {(progress: { stage: "database", index: number, total: number,
+ *   name: string, address: string, entries: number, blocks: number }) => void}
+ *   [options.onProgress] called after each database, with what it added
+ * @param {number} [options.timestamp] ms since the epoch; injected for tests
+ * @returns {Promise<{ blocks: Map<string, { cid: CID, bytes: Uint8Array }>,
+ *   metadata: Object }>}
+ */
+export async function bundleDatabases(databases, options = {}) {
+  const list = Array.isArray(databases) ? databases : Object.values(databases ?? {});
+  if (list.length === 0) throw new Error("bundleDatabases needs at least one database");
+
+  const blocks = new Map();
+  const described = [];
+  let totalEntries = 0;
+
+  for (const [index, database] of list.entries()) {
+    const before = blocks.size;
+    const { blocks: own, manifestCID } = await extractDatabaseBlocks(database);
+    for (const [name, block] of own) if (!blocks.has(name)) blocks.set(name, block);
+
+    const entries = (await database.log.values()).length;
+    const heads = (await database.log.heads()).map((head) => head.hash);
+    totalEntries += entries;
+    described.push({
+      address: database.address,
+      name: database.name,
+      type: database.type,
+      manifestCID,
+      entryCount: entries,
+      heads,
+    });
+    options.onProgress?.({
+      stage: "database",
+      index,
+      total: list.length,
+      name: database.name,
+      address: database.address,
+      entries,
+      blocks: blocks.size - before,
+    });
+  }
+
+  return {
+    blocks,
+    metadata: {
+      version: "1.0",
+      timestamp: options.timestamp ?? Date.now(),
+      databaseCount: described.length,
+      totalBlocks: blocks.size,
+      totalEntries,
+      // The first database's, so a reader of the one-database shape still finds one.
+      manifestCID: described[0].manifestCID,
+      databases: described,
+    },
+  };
+}

package/lib/restore-cid.js

@@ -157,7 +157,8 @@ async function headsIn(blocks) {
 }
 
 /**
- * Restore a database from the CID of a CAR backup's metadata.
+ * Restore from the CID of a CAR backup's metadata: every database it names
+ * (`restoreFromBlocks` does the work once the blocks are fetched).
  *
  * 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
@@ -191,7 +192,9 @@ async function headsIn(blocks) {
  *   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 }>}
+ *   entries: number, heads: number, joined: number, databases: Object[] }>}
+ *   the first database's at the top, as a one-database backup always had it;
+ *   `databases` lists them all
  */
 export async function restoreFromCID(orbitdb, options = {}) {
   const { metadataCID, fetchBytes = fetchFromGateways, log = SILENT, verify = true, open = {}, ...rest } = options;
@@ -216,40 +219,97 @@ export async function restoreFromCID(orbitdb, options = {}) {
   // 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",
-    );
-  }
+  assertRestorable(metadata);
 
   // 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`);
 
+  // 3 · every database the metadata names
+  const restored = await restoreFromBlocks(orbitdb, blocks, metadata, { log, verify, open });
+  const [first] = restored.databases;
+
+  // The one-database answer this always gave, and the whole list beside it.
+  return {
+    address: first.address,
+    database: first.database,
+    blocks: restored.blocks,
+    entries: metadata.totalEntries ?? first.entries,
+    heads: first.heads,
+    joined: first.joined,
+    databases: restored.databases,
+  };
+}
+
+/**
+ * Refuse metadata that names nothing a restore could open, and say which kind
+ * it is. `isValidMetadata` also accepts the older `{ root, path }` shape, which
+ * predates CAR backups and has no address to open.
+ */
+function assertRestorable(metadata) {
+  const dbs = metadata.databases ?? [];
+  if (dbs.length === 0) throw new Error("Backup metadata names no database");
+  if (!dbs.every((db) => db?.address)) {
+    throw new Error("This is a pre-CAR backup; restoreFromCID needs a CAR backup");
+  }
+}
+
+/**
+ * Restore every database a backup names, from blocks already in hand.
+ *
+ * `restoreFromCID` fetches and then calls this. An application that holds the
+ * blocks some other way — a backup it sealed itself and has just opened, a file
+ * on a USB stick, several small CARs written as it went — calls it directly.
+ * The blocks are checked against the metadata, never trusted for it: each
+ * database's manifest must be among them.
+ *
+ * Per database: the blocks go into the blockstore (once, for all of them) and
+ * into that database's own log storage (its dag-cbor blocks only — a receipt
+ * file's raw chunks are no log's business); the database is reopened so the
+ * log reads what was put underneath it; and its heads are joined. The heads
+ * are the ones the metadata states, or — for metadata that states none — the
+ * entries of this log nothing else points back to.
+ *
+ * **Each returned `database` replaces any handle the caller held on that
+ * address**, for the reason `restoreFromCID` gives.
+ *
+ * @param {Object} orbitdb an OrbitDB instance to restore into
+ * @param {Map<string, { bytes: Uint8Array }>} blocks by CID string, in any base —
+ *   what `readBlocksFromCAR` returns
+ * @param {Object} metadata as `bundleDatabases` or `backupDatabaseCAR` write it
+ * @param {Object} [options]
+ * @param {boolean} [options.verify=true] each database's manifest must be among the blocks
+ * @param {{ info: Function, warn: Function, debug: Function }} [options.log]
+ * @param {Object} [options.open] options for `orbitdb.open`, merged over the type
+ *   the backup names (a node without pubsub needs `{ sync: false }`)
+ * @param {(progress: { stage: "database", index: number, total: number,
+ *   address: string, joined: number, heads: number }) => void} [options.onProgress]
+ * @returns {Promise<{ blocks: number, databases: { address: string, name?: string,
+ *   database: Object, entries: number|null, heads: number, joined: number }[] }>}
+ */
+export async function restoreFromBlocks(orbitdb, blocks, metadata, options = {}) {
+  const { log = SILENT, verify = true, open = {}, onProgress } = options;
+  if (!orbitdb?.ipfs?.blockstore) throw new Error("An OrbitDB instance is required");
+  if (!(blocks instanceof Map)) throw new Error("blocks must be a Map");
+  if (!isValidMetadata(metadata)) throw new Error("Invalid backup metadata");
+  assertRestorable(metadata);
+
   // 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`,
-      );
+  const present = new Set([...blocks.keys()].map(canonical));
+  if (verify) {
+    for (const db of metadata.databases) {
+      const manifestCID = db.manifestCID ?? metadata.manifestCID;
+      if (!manifestCID) continue;
+      const wanted = canonical(manifestCID);
+      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.
+  // Into the blockstore, where Helia looks — once, whatever the databases.
   let stored = 0;
   for (const [cidString, { bytes }] of blocks) {
     try {
@@ -260,43 +320,75 @@ export async function restoreFromCID(orbitdb, options = {}) {
     }
   }
 
-  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}`);
+  const found = metadata.databases.some((db) => !Array.isArray(db.heads)) ? await headsIn(blocks) : [];
+  const byCanonical = new Map([...blocks].map(([name, block]) => [canonical(name), block]));
+
+  const databases = [];
+  for (const [index, dbInfo] of metadata.databases.entries()) {
+    const opened = await orbitdb.open(dbInfo.address, { type: dbInfo.type, ...open });
+    // OrbitDB's log reads from its own store and addresses blocks in base58btc
+    // rather than the CAR's base32. A restore that fills only the blockstore
+    // opens a database that is empty in a way nothing reports.
+    for (const [cidString, { bytes }] of blocks) {
+      try {
+        const cid = CID.parse(cidString);
+        if (cid.code !== DAG_CBOR) continue;
+        await opened.log.storage.put(cid.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 });
+    // 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++;
+    // Tell the log where its history ends.
+    const heads = Array.isArray(dbInfo.heads)
+      ? (await Promise.all(dbInfo.heads.map((hash) => headFrom(byCanonical, hash)))).filter(Boolean)
+      : found.filter((head) => head.value.id === dbInfo.address || metadata.databases.length === 1);
+    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}`);
       }
-    } catch (error) {
-      log.warn(`   ⚠️ could not join head ${head.hash.slice(0, 12)}…: ${error.message}`);
     }
+
+    log.info(`✅ Restored ${dbInfo.address} — ${joined}/${heads.length} heads`);
+    onProgress?.({
+      stage: "database",
+      index,
+      total: metadata.databases.length,
+      address: dbInfo.address,
+      joined,
+      heads: heads.length,
+    });
+    databases.push({
+      address: dbInfo.address,
+      name: dbInfo.name,
+      database,
+      entries: dbInfo.entryCount ?? null,
+      heads: heads.length,
+      joined,
+    });
   }
 
-  log.info(`✅ Restored ${dbInfo.address} — ${stored} blocks, ${joined}/${heads.length} heads`);
+  return { blocks: stored, databases };
+}
 
-  return {
-    address: dbInfo.address,
-    database,
-    blocks: stored,
-    entries: metadata.totalEntries ?? dbInfo.entryCount ?? null,
-    heads: heads.length,
-    joined,
-  };
+/** A stated head, decoded from the blocks; null when the blocks lack it. */
+async function headFrom(byCanonical, hash) {
+  const name = canonical(hash);
+  const block = name ? byCanonical.get(name) : undefined;
+  if (!block) return null;
+  const cid = CID.parse(name);
+  const { value } = await Block.decode({ cid, bytes: block.bytes, codec: dagCbor, hasher: sha256 });
+  return { hash: cid.toV1().toString(base58btc), value };
 }
 
-export default { restoreFromCID, fetchFromGateways, readBlocksFromCAR, DEFAULT_GATEWAYS, SILENT };
+export default { restoreFromCID, restoreFromBlocks, fetchFromGateways, readBlocksFromCAR, DEFAULT_GATEWAYS, SILENT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-storage-bridge",
-  "version": "0.15.0",
+  "version": "0.16.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/",
@@ -15,6 +15,7 @@
     "./pointer-ipns": "./lib/pointer-ipns.js",
     "./dehydrate": "./lib/dehydrate.js",
     "./restore-cid": "./lib/restore-cid.js",
+    "./extract-blocks": "./lib/extract-blocks.js",
     "./gateway-fetch": "./lib/gateway-fetch.js",
     "./peer-fetch": "./lib/peer-fetch.js",
     "./backends/types": "./lib/backends/types.js",