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

package/README.md

@@ -26,7 +26,7 @@ Where "somewhere else" is, is a choice:
 | Backend | Needs | |
 | --- | --- | --- |
 | `aleph` | nothing | the only backend a browser can write to with no key; ingest only |
-| `aleph-pin` | a wallet | the signed STORE message that makes Aleph keep it |
+| `aleph-pin` | a signing key: the paying account's, or one it authorised | the signed STORE message that makes Aleph keep it, paid in credits |
 | `pinata` | a scoped JWT | pin-by-CID as well as CAR upload |
 | `lighthouse` | an API key | pay once, stored in perpetuity |
 | `memory` | nothing | in-process, for tests and demos |
@@ -83,6 +83,7 @@ Galaxy A57 with the same key brought the database back and wrote to it. Source:
 | [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) | every backend evaluated — prices, limits, and what has been verified against a live account |
 | [docs/RECOVERY-ON-A-SECOND-DEVICE.md](docs/RECOVERY-ON-A-SECOND-DEVICE.md) | the passkey recovery procedure, step by step |
 | [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | CAR-based timestamped backups |
+| [docs/APP-BACKUP.md](docs/APP-BACKUP.md) | an application's backup in one sealed file: several databases, a keyring header, kept on Aleph from the browser, restored by merging |
 | [SVELTE-COMPONENTS.md](SVELTE-COMPONENTS.md) | the browser components — older than this repository's copy of them; [docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md) records what each piece could do and where it went |
 | [docs/LOGGING.md](docs/LOGGING.md) | debug namespaces, in Node and in a browser |
 | [ROADMAP.md](ROADMAP.md) | what is planned |

package/lib/app-backup.js

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview An application's backup in one sealed file (#147).
+ *
+ * Two applications, Le-Space/belege and Le-Space/invoice, back up the same way:
+ * every OrbitDB database they keep, and blocks of their own (belege's receipt
+ * files), go into one CAR whose root is a manifest; the CAR is sealed with the
+ * application's key; one upload, one STORE. This module is that file,
+ * generalised from belege's `archive.js` (Le-Space/belege#77), so that the
+ * applications stop inventing their own.
+ *
+ * ## The file
+ *
+ *     "OSBA" | version | header length (4 bytes, big-endian) | header | envelope
+ *
+ * - **The header** is the caller's, and is read without a key
+ *   ({@link readAppBackupHeader}). It is room for a keyring: invoice puts its
+ *   vault there, one sealed slot per passkey, so that any registered passkey
+ *   finds the key to the rest. This module does not interpret it. Its SHA-256
+ *   is in the manifest, so a header swapped after the backup was made is
+ *   refused once the body is open.
+ * - **The envelope** is the package's own (`OSBE`, see ./backends/encryption.js)
+ *   around the CAR, encrypted by the caller's `encrypt`. The package holds no
+ *   keys, here as everywhere.
+ * - **The CAR's root** is a dag-cbor manifest: `kind` and `v` say what this is,
+ *   `app` whose it is, and `metadata` is `bundleDatabases`'s, naming every
+ *   database with its heads. `extra` is the application's own (belege lists its
+ *   receipt files there).
+ *
+ * Everything is built in memory, as the rest of the package does; a backup is
+ * as large as the books it holds.
+ *
+ * @requires ./extract-blocks.js - bundleDatabases
+ * @requires ./backup-car.js - createCARFromBlocks
+ * @requires ./restore-cid.js - the verifying CAR reader, restoreFromBlocks
+ */
+
+import * as dagCbor from "@ipld/dag-cbor";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import { bundleDatabases } from "./extract-blocks.js";
+import { createCARFromBlocks } from "./backup-car.js";
+import { readBlocksFromCAR, restoreFromBlocks } from "./restore-cid.js";
+import { wrapEnvelope, readEnvelope } from "./backends/encryption.js";
+
+/** `OSBA` — orbitdb-storage-bridge, application backup. */
+export const APP_BACKUP_MAGIC = new Uint8Array([0x4f, 0x53, 0x42, 0x41]);
+
+/** Bumped when the file changes in a way readers must notice. */
+export const APP_BACKUP_VERSION = 1;
+
+/** What the manifest at the CAR's root calls itself. */
+export const APP_BACKUP_KIND = "app-backup";
+
+const PREAMBLE = APP_BACKUP_MAGIC.length + 1 + 4;
+
+const hex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+
+async function sha256Hex(bytes) {
+  return hex(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes)));
+}
+
+/**
+ * @typedef {object} AppBackupManifest
+ * @property {"app-backup"} kind
+ * @property {number} v - {@link APP_BACKUP_VERSION}
+ * @property {string} app - whose backup this is, e.g. `"invoice"`
+ * @property {string} createdAt - ISO
+ * @property {string} [appVersion]
+ * @property {any} metadata - `bundleDatabases`'s: `databases` with each one's
+ *   `address`, `name`, `type`, `manifestCID`, `entryCount`, `heads`, and
+ *   `collection` when the databases were given by name
+ * @property {string} [header] - hex SHA-256 of the file's header, when it has one
+ * @property {any} [extra] - the application's own, as it passed it
+ */
+
+/**
+ * @typedef {{ stage: "database", index: number, total: number, name: string, entries: number }
+ *   | { stage: "sealing", bytes: number }} AppBackupProgress
+ */
+
+/**
+ * Build a backup file.
+ *
+ * @param {object} params
+ * @param {string} params.app - whose backup this is; {@link openAppBackup} can insist on it
+ * @param {Object[]|Object<string, Object>} params.databases - open OrbitDB
+ *   databases. Given by name, the names go into the metadata as `collection`.
+ * @param {(plaintext: Uint8Array) => Promise<{ ciphertext: Uint8Array, iv: Uint8Array }>} params.encrypt -
+ *   the caller's, with the caller's key
+ * @param {Map<string, { bytes: Uint8Array }>} [params.blocks] - blocks of the
+ *   application's own, by CID string: they travel in the CAR and come back into
+ *   the blockstore on restore
+ * @param {Uint8Array} [params.header] - read without a key, e.g. a keyring
+ * @param {string} [params.appVersion]
+ * @param {any} [params.extra] - anything dag-cbor can encode
+ * @param {() => Date} [params.now]
+ * @param {(progress: AppBackupProgress) => void} [params.onProgress]
+ * @returns {Promise<{ bytes: Uint8Array, manifest: AppBackupManifest, blocks: number, carBytes: number }>}
+ */
+export async function buildAppBackup({
+  app,
+  databases,
+  encrypt,
+  blocks: own,
+  header,
+  appVersion,
+  extra,
+  now = () => new Date(),
+  onProgress,
+}) {
+  if (typeof app !== "string" || !app) throw new Error("buildAppBackup needs the application's name as `app`");
+  if (typeof encrypt !== "function") throw new Error("buildAppBackup needs an `encrypt` function: the package holds no keys");
+  if (header !== undefined && !(header instanceof Uint8Array)) throw new Error("A backup's header is bytes");
+  if (own !== undefined && !(own instanceof Map)) throw new Error("An application's own blocks come as a Map, by CID string");
+
+  const at = now();
+  const names = Array.isArray(databases) ? null : Object.keys(databases ?? {});
+  const { blocks, metadata } = await bundleDatabases(databases, {
+    timestamp: at.getTime(),
+    onProgress: (p) =>
+      onProgress?.({
+        stage: "database",
+        index: p.index,
+        total: p.total,
+        name: names?.[p.index] ?? p.name,
+        entries: p.entries,
+      }),
+  });
+  if (names) metadata.databases.forEach((d, i) => (d.collection = names[i]));
+  for (const [name, block] of own ?? []) if (!blocks.has(name)) blocks.set(name, block);
+
+  /** @type {AppBackupManifest} */
+  const manifest = {
+    kind: APP_BACKUP_KIND,
+    v: APP_BACKUP_VERSION,
+    app,
+    createdAt: at.toISOString(),
+    ...(appVersion ? { appVersion } : {}),
+    metadata,
+    ...(header?.length ? { header: await sha256Hex(header) } : {}),
+    ...(extra !== undefined ? { extra } : {}),
+  };
+  const root = dagCbor.encode(manifest);
+  const rootCid = CID.createV1(dagCbor.code, await sha256.digest(root));
+  blocks.set(rootCid.toString(), { cid: rootCid, bytes: root });
+
+  const car = await createCARFromBlocks(blocks, rootCid.toString());
+  onProgress?.({ stage: "sealing", bytes: car.length });
+  const { ciphertext, iv } = await encrypt(car);
+  const envelope = wrapEnvelope(ciphertext, iv);
+
+  const head = header ?? new Uint8Array(0);
+  const bytes = new Uint8Array(PREAMBLE + head.length + envelope.length);
+  bytes.set(APP_BACKUP_MAGIC, 0);
+  bytes[APP_BACKUP_MAGIC.length] = APP_BACKUP_VERSION;
+  new DataView(bytes.buffer).setUint32(APP_BACKUP_MAGIC.length + 1, head.length);
+  bytes.set(head, PREAMBLE);
+  bytes.set(envelope, PREAMBLE + head.length);
+  return { bytes, manifest, blocks: blocks.size, carBytes: car.length };
+}
+
+/** Is this an application backup this module wrote, of any version? */
+export function isAppBackup(bytes) {
+  return (
+    bytes instanceof Uint8Array &&
+    bytes.length >= PREAMBLE &&
+    APP_BACKUP_MAGIC.every((byte, index) => bytes[index] === byte)
+  );
+}
+
+/**
+ * The header, without a key: what a keyring needs before anything can be opened.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{ version: number, header: Uint8Array, body: Uint8Array }}
+ */
+export function readAppBackupHeader(bytes) {
+  if (!isAppBackup(bytes)) throw new Error("This is not an application backup.");
+  const version = bytes[APP_BACKUP_MAGIC.length];
+  if (version !== APP_BACKUP_VERSION) {
+    throw new Error(
+      `This backup was written in format ${version}, and this build reads ${APP_BACKUP_VERSION}. ` +
+        "Upgrade @le-space/orbitdb-storage-bridge to open it.",
+    );
+  }
+  const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(APP_BACKUP_MAGIC.length + 1);
+  if (PREAMBLE + length > bytes.length) throw new Error("This backup is cut short.");
+  return {
+    version,
+    header: bytes.subarray(PREAMBLE, PREAMBLE + length),
+    body: bytes.subarray(PREAMBLE + length),
+  };
+}
+
+/**
+ * Open a backup file: the envelope decrypted, every block checked against its
+ * own CID, the manifest found among them, and the header checked against it.
+ *
+ * A wrong key fails in `decrypt` itself (AES-GCM refuses it), and its error
+ * comes through unchanged, for the caller to name.
+ *
+ * @param {Uint8Array} bytes
+ * @param {object} options
+ * @param {(ciphertext: Uint8Array, iv: Uint8Array) => Promise<Uint8Array>} options.decrypt
+ * @param {string} [options.app] - refuse a backup of another application
+ * @returns {Promise<{ header: Uint8Array, manifest: AppBackupManifest, blocks: Map<string, { cid: any, bytes: Uint8Array }> }>}
+ */
+export async function openAppBackup(bytes, { decrypt, app } = {}) {
+  if (typeof decrypt !== "function") throw new Error("openAppBackup needs a `decrypt` function");
+  const { header, body } = readAppBackupHeader(bytes);
+  const { ciphertext, iv } = readEnvelope(body);
+  const car = await decrypt(ciphertext, iv);
+  const blocks = await readBlocksFromCAR(car, { verify: true });
+
+  let manifest;
+  for (const [name, { bytes: block }] of blocks) {
+    if (CID.parse(name).code !== dagCbor.code) continue;
+    let value;
+    try {
+      value = dagCbor.decode(block);
+    } catch {
+      continue;
+    }
+    if (value?.kind === APP_BACKUP_KIND && value?.v === APP_BACKUP_VERSION) {
+      manifest = value;
+      break;
+    }
+  }
+  if (!manifest) throw new Error("This backup holds no manifest.");
+  if (app && manifest.app !== app) throw new Error(`This is a backup of ${manifest.app}, not of ${app}.`);
+  // The header is outside the seal; the manifest inside it says which header belongs.
+  const expected = manifest.header ?? null;
+  const actual = header.length ? await sha256Hex(header) : null;
+  if (expected !== actual) throw new Error("This backup's header is not the one it was made with.");
+  return { header, manifest, blocks };
+}
+
+/**
+ * @typedef {{ stage: "database", index: number, total: number, name: string, joined: number }} AppRestoreProgress
+ */
+
+/**
+ * Put an opened backup back into books that are open here.
+ *
+ * Every database the backup names must be one of these books, by address:
+ * restoring merges, and merging another's books into these is never wanted.
+ * The databases go back through {@link restoreFromBlocks}: every block into the
+ * blockstore (the application's own with them), each database reopened and its
+ * heads joined. Joining merges — what is here stays, what the backup holds is
+ * added, nothing is deleted. A head that cannot be joined fails the restore
+ * with the reason, where `restoreFromBlocks` alone only warns.
+ *
+ * The open databases are closed and reopened behind the caller's back; reload
+ * the application's handles afterwards.
+ *
+ * @param {object} params
+ * @param {any} params.orbitdb
+ * @param {{ manifest: AppBackupManifest, blocks: Map<string, any> }} params.opened - from {@link openAppBackup}
+ * @param {Record<string, string> | string[]} params.addresses - these books'
+ *   database addresses, by collection or as a list
+ * @param {Record<string, any>} [params.open] - what `orbitdb.open` needs for them (`encryption`, `AccessController`, …)
+ * @param {(progress: AppRestoreProgress) => void} [params.onProgress]
+ * @returns {Promise<{ databases: { address: string, collection?: string, joined: number, entries: number | null }[] }>}
+ */
+export async function restoreAppBackup({ orbitdb, opened, addresses, open, onProgress }) {
+  const metadata = opened?.manifest?.metadata;
+  if (!metadata?.databases?.length) throw new Error("This backup names no databases.");
+  const byAddress = Array.isArray(addresses)
+    ? Object.fromEntries(addresses.map((address) => [String(address), undefined]))
+    : Object.fromEntries(Object.entries(addresses ?? {}).map(([collection, address]) => [String(address), collection]));
+  for (const d of metadata.databases) {
+    if (!(String(d.address) in byAddress)) {
+      throw new Error("This backup holds databases these books do not have.");
+    }
+  }
+
+  const warnings = [];
+  const restored = await restoreFromBlocks(orbitdb, opened.blocks, metadata, {
+    open,
+    log: { info() {}, debug() {}, warn: (message) => warnings.push(String(message)) },
+    onProgress: (p) =>
+      onProgress?.({
+        stage: "database",
+        index: p.index,
+        total: p.total,
+        name: byAddress[p.address] ?? p.address,
+        joined: p.joined,
+      }),
+  });
+  const failed = warnings.find((w) => /could not join head/.test(w));
+  if (failed) throw new Error(`The backup could not be put back: ${failed.replace(/^\W+/, "")}`);
+  return {
+    databases: restored.databases.map((d) => ({
+      address: d.address,
+      ...(byAddress[d.address] ? { collection: byAddress[d.address] } : {}),
+      joined: d.joined,
+      entries: d.entries ?? null,
+    })),
+  };
+}

package/lib/backends/aleph-pin.js

@@ -9,11 +9,29 @@
  *
  * ## No tokens move
  *
- * The wallet **signs a string**. Aleph then checks that the signing address has
- * enough balance or credit to cover what it is being asked to keep. There is no
- * transaction, no gas and no transfer: the token is the evidence, not the
- * payment. Worth stating because "pay for storage with a wallet" reads as the
- * opposite.
+ * The wallet **signs a string**. Aleph then checks that the account the STORE
+ * is for has enough credit to cover what it is being asked to keep. There is no
+ * transaction, no gas and no transfer at that moment: credits are drawn from the
+ * account by the hour, afterwards. Worth stating because "pay for storage with a
+ * wallet" reads as the opposite.
+ *
+ * ## Paid in credits
+ *
+ * Measured against `api2.aleph.im` on 2026-10-03, with throwaway accounts and
+ * 2 MiB of random bytes:
+ *
+ * - A STORE whose content names no `payment` is booked as **`hold`**: ALEPH
+ *   tokens locked on the account, a model Aleph has deprecated. It was
+ *   processed at once for an account holding nothing, so "processed" says
+ *   nothing about cover there.
+ * - With `payment: { type: "credit" }` — what Aleph's own CLI sends by default —
+ *   Aleph wants credit for at least a day (`min_runtime_days: 1`) and rejects
+ *   the STORE otherwise: 107.8 credits for 2 MiB, about 54 per MiB and day.
+ * - It is the account in `content.address` whose credit is checked and to
+ *   which the cost is booked, not the sender: a delegate with no credit at all
+ *   stored for a funded owner, and the cost appeared on the owner.
+ *
+ * So {@link buildStoreMessage} pays in credits unless told otherwise.
  *
  * ## Injected, not imported
  *
@@ -50,6 +68,9 @@ import { BackendError } from "./types.js";
 export const DEFAULT_ALEPH_API_HOST = "https://api2.aleph.im";
 export const DEFAULT_ALEPH_CHANNEL = "ALEPH-CLOUDSOLUTIONS";
 
+/** How a STORE may be paid for; `null` leaves `payment` out, which Aleph books as `hold`. */
+export const STORE_PAYMENTS = Object.freeze(["credit", "hold"]);
+
 /** Hex sha-256 of a string, via WebCrypto — present in browsers and in Node 18+. */
 async function sha256Hex(payload) {
   const digest = await globalThis.crypto.subtle.digest(
@@ -71,10 +92,27 @@ async function sha256Hex(payload) {
  *   by default
  * @param {string} args.cid - what to keep
  * @param {string} [args.channel]
+ * @param {"credit" | "hold" | null} [args.payment] - `credit` by default; `null`
+ *   sends no `payment`, as every version up to 0.16.1 did, which Aleph books as
+ *   `hold`
  * @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, owner, cid, channel = DEFAULT_ALEPH_CHANNEL, now, hasher = sha256Hex }) {
+export async function buildStoreMessage({
+  sender,
+  owner,
+  cid,
+  channel = DEFAULT_ALEPH_CHANNEL,
+  payment = "credit",
+  now,
+  hasher = sha256Hex,
+}) {
+  if (payment !== null && !STORE_PAYMENTS.includes(payment)) {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      `a STORE is paid by "credit" or "hold", or names no payment (null), not ${JSON.stringify(payment)}`,
+    );
+  }
   const time = now ?? Date.now() / 1000;
   const content = {
     // Whose STORE this is. Equal to the sender unless the owner's `security`
@@ -83,6 +121,9 @@ export async function buildStoreMessage({ sender, owner, cid, channel = DEFAULT_
     // "the thing to keep is an IPFS CID" — not the envelope's item_type
     item_type: "ipfs",
     item_hash: cid,
+    // How that account pays. Without it Aleph books the STORE as `hold`, and an
+    // account funded with credits covers nothing (see the file's header).
+    ...(payment ? { payment: { type: payment } } : {}),
     time,
   };
   const item_content = JSON.stringify(content);
@@ -114,15 +155,20 @@ export const signaturePayload = (message) =>
  *   `personal_sign`, or anything shaped like it. The library never sees a key.
  * @param {string} [options.apiHost]
  * @param {string} [options.channel]
+ * @param {"credit" | "hold" | null} [options.payment] - see {@link buildStoreMessage}
  * @param {(payload: string) => Promise<string>} [options.hasher]
  * @param {typeof fetch} [options.fetch]
  * @param {() => number} [options.now] - seconds
  * @returns {(cid: string, meta?: object) => Promise<{ itemHash: string, status: string }>}
+ *   `status` is what Aleph answered: `processed`, or `pending` until it has
+ *   checked the signature, the authorization and the credit — follow a pending
+ *   one with {@link waitForMessage}.
  */
 export function createAlephPin(options = {}) {
   const { sender, sign, owner } = options;
   const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
   const channel = options.channel || DEFAULT_ALEPH_CHANNEL;
+  const payment = options.payment === undefined ? "credit" : options.payment;
   const hasher = options.hasher || sha256Hex;
   const doFetch = options.fetch || globalThis.fetch;
   const now = options.now;
@@ -132,7 +178,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, owner, cid, channel, hasher, now: now?.() });
+    const unsigned = await buildStoreMessage({ sender, owner, cid, channel, payment, hasher, now: now?.() });
     const signature = await sign(sender, signaturePayload(unsigned));
     const message = {
       ...unsigned,
@@ -165,6 +211,126 @@ export function createAlephPin(options = {}) {
   };
 }
 
+/** Statuses after which a message no longer changes by itself. */
+const SETTLED = new Set(["processed", "rejected", "removing", "removed", "forgotten"]);
+
+/**
+ * Follow a message until Aleph has decided about it.
+ *
+ * A STORE answered with 202 is `pending`: Aleph has taken it, and checks the
+ * signature, the authorization and the account's credit afterwards. A
+ * rejected one says why. For a credit STORE without enough credit,
+ * `details.errors[0]` names `account_credits`, `required_credits` and
+ * `min_runtime_days`, with `errorCode` 6 (measured 2026-10-03).
+ *
+ * Never throws for what Aleph answers: a message still pending when the time is
+ * up comes back as `{ status: "pending", timedOut: true }`, for the caller to
+ * report as exactly that.
+ *
+ * @param {string} itemHash
+ * @param {object} [options]
+ * @param {string} [options.apiHost]
+ * @param {typeof fetch} [options.fetch]
+ * @param {number} [options.timeout] - ms in all; default 60 000
+ * @param {number} [options.interval] - ms between asks; default 2 000
+ * @param {(ms: number) => Promise<void>} [options.sleep] - injected so a test is not a clock
+ * @returns {Promise<{ itemHash: string, status: string, errorCode?: number, details?: unknown, timedOut?: true }>}
+ */
+export async function waitForMessage(itemHash, options = {}) {
+  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
+  const doFetch = options.fetch || globalThis.fetch;
+  const timeout = options.timeout ?? 60_000;
+  const interval = options.interval ?? 2_000;
+  const sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  if (!itemHash) throw new BackendError("INVALID_BACKEND", "waitForMessage needs the message's item hash");
+  if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "waitForMessage needs fetch");
+
+  // Counted in asks rather than read off a clock, so an injected `sleep` is enough for a test.
+  const asks = Math.max(1, Math.floor(timeout / interval) + 1);
+  let status = "pending";
+  for (let ask = 0; ask < asks; ask++) {
+    if (ask > 0) await sleep(interval);
+    let response;
+    try {
+      response = await doFetch(`${apiHost}/api/v0/messages/${itemHash}`);
+    } catch {
+      continue; // the network, not Aleph's answer: ask again
+    }
+    // 404: not known on this node yet. Anything else not ok: ask again.
+    if (!response.ok) continue;
+    const body = await response.json().catch(() => ({}));
+    if (typeof body?.status === "string") status = body.status;
+    if (SETTLED.has(status)) {
+      return {
+        itemHash,
+        status,
+        ...(body.error_code != null ? { errorCode: body.error_code } : {}),
+        ...(body.details != null ? { details: body.details } : {}),
+      };
+    }
+  }
+  return { itemHash, status, timedOut: true };
+}
+
+/**
+ * The STORE messages kept for an account, newest first: its own, and those a
+ * delegate sent for it.
+ *
+ * This is how an empty device finds a backup with nothing but the paying
+ * account's public address. Aleph's `addresses` filter matches the *sender*,
+ * so it misses a delegate's STORE; `owners` matches `content.address`, the
+ * account the STORE is for (measured 2026-10-03).
+ *
+ * @param {object} options
+ * @param {string} options.owner - the paying account, EIP-55 checksummed (Aleph
+ *   keys accounts by that form)
+ * @param {string} [options.channel] - one channel; every channel when absent
+ * @param {string} [options.apiHost]
+ * @param {typeof fetch} [options.fetch]
+ * @param {number} [options.pagination] - per page; default 50
+ * @param {number} [options.page] - from 1
+ * @returns {Promise<{ stores: Array<{ cid: string, itemHash: string, sender: string, owner: string, time: number, channel?: string, payment?: string }>, total: number | null }>}
+ *   `cid` is what the STORE keeps — for an upload through `createAlephBackend`,
+ *   the handle's `id`
+ */
+export async function listAlephStores(options = {}) {
+  const { owner, channel } = options;
+  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
+  const doFetch = options.fetch || globalThis.fetch;
+  if (!owner) throw new BackendError("INVALID_BACKEND", "listAlephStores needs the paying account's address as `owner`");
+  if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "listAlephStores needs fetch");
+
+  const url = new URL(`${apiHost}/api/v0/messages.json`);
+  url.searchParams.set("owners", owner);
+  url.searchParams.set("msgTypes", "STORE");
+  if (channel) url.searchParams.set("channels", channel);
+  url.searchParams.set("pagination", String(options.pagination ?? 50));
+  url.searchParams.set("page", String(options.page ?? 1));
+
+  const response = await doFetch(url.toString());
+  if (!response.ok) {
+    throw new BackendError("UNSUPPORTED", `Aleph did not list the STORE messages: ${response.status}`);
+  }
+  const body = await response.json().catch(() => ({}));
+  const messages = Array.isArray(body?.messages) ? body.messages : [];
+  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+  const stores = messages
+    .map((m) => ({
+      cid: String(m?.content?.item_hash ?? ""),
+      itemHash: String(m?.item_hash ?? ""),
+      sender: String(m?.sender ?? ""),
+      owner: String(m?.content?.address ?? ""),
+      time: Number(m?.content?.time ?? m?.time ?? 0),
+      ...(m?.channel ? { channel: m.channel } : {}),
+      ...(m?.content?.payment?.type ? { payment: m.content.payment.type } : {}),
+    }))
+    // Aleph answers what it was asked; keeping only this owner's costs nothing
+    // and keeps a misread filter from handing back someone else's files.
+    .filter((store) => store.cid && store.itemHash && same(store.owner, owner))
+    .sort((a, b) => b.time - a.time);
+  return { stores, total: Number.isFinite(body?.pagination_total) ? body.pagination_total : null };
+}
+
 /** The reserved channel and aggregate key Aleph keeps permissions in. */
 export const SECURITY = "security";
 
@@ -227,8 +393,9 @@ export async function buildAuthorizationMessage({ owner, authorizations, now, ha
  * (`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's documentation does not say whose credit pays for a STORE a delegate
+ * sends. Measured on 2026-10-03: the owner's, the account in `content.address`
+ * (see the file's header).
  *
  * Aleph keys accounts by their EIP-55 checksummed address; pass `owner` in that
  * form, or `read()` finds nothing.

package/lib/backends/aleph.js

@@ -104,8 +104,9 @@ export function createAlephBackend(options = {}) {
       // No key exists to leak.
       browserSafeAuth: true,
       delegation: false,
-      // The IPFS host offers no listing, and the messages API would need the
-      // wallet address this driver deliberately does not hold.
+      // The IPFS host offers no listing, and the messages API needs the paying
+      // account's address, which this driver deliberately does not hold:
+      // `listAlephStores` in ./aleph-pin.js takes it.
       listing: false,
       // Unpinning is a FORGET message, so it belongs with `pin` rather than
       // here. Claiming deletion the driver cannot perform would be worse than
@@ -167,8 +168,11 @@ export function createAlephBackend(options = {}) {
         size: bytes.length,
         ...(meta.name ? { name: meta.name } : {}),
         // Said out loud in the handle, because "stored" and "kept" are not the
-        // same thing here and a caller should not have to read this file.
-        retained: Boolean(pin),
+        // same thing here and a caller should not have to read this file. An
+        // upload is never kept by itself, `pin` or not: keeping is a STORE,
+        // which `pinCid` sends. (Up to 0.16.1 this said `Boolean(pin)`, a
+        // promise no call had kept.)
+        retained: false,
       };
     },
 
@@ -190,8 +194,21 @@ export function createAlephBackend(options = {}) {
      * predicted, and the reason `pinCid` here does not upload anything.
      */
     backend.pinCid = async (cid, meta = {}) => {
-      await pin(cid, meta);
-      return { id: cid, cid, backend: "aleph", retained: true, ...(meta.name ? { name: meta.name } : {}) };
+      const kept = await pin(cid, meta);
+      // A pin that reports Aleph's answer (createAlephPin does) is believed:
+      // retained only once the STORE is processed, and a pending one says so,
+      // with the item hash to follow it by (waitForMessage). A pin that
+      // reports nothing keeps the old answer.
+      const status = typeof kept?.status === "string" ? kept.status : undefined;
+      return {
+        id: cid,
+        cid,
+        backend: "aleph",
+        retained: status === undefined || status === "processed",
+        ...(status ? { status } : {}),
+        ...(kept?.itemHash ? { itemHash: kept.itemHash } : {}),
+        ...(meta.name ? { name: meta.name } : {}),
+      };
     };
   }
 

package/lib/restore-cid.js

@@ -350,8 +350,13 @@ export async function restoreFromBlocks(orbitdb, blocks, metadata, options = {})
     let joined = 0;
     for (const head of heads) {
       try {
+        // The log decodes its own entry: an encrypted database's entry is not
+        // the raw dag-cbor fields, and joining those throws (an `undefined`
+        // the IPLD data model refuses). The raw fields stay as the fallback for
+        // a log storage that does not have the block.
+        const entry = await database.log.get(head.hash).catch(() => undefined);
         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 })) {
+        if (await database.log.joinEntry(entry ?? { hash: head.hash, v, id, key, sig, next, refs, clock, payload, identity })) {
           joined++;
         }
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-storage-bridge",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation",
   "main": "lib/orbitdb-storacha-bridge.js",
   "svelte": "dist/components/",
@@ -16,6 +16,7 @@
     "./dehydrate": "./lib/dehydrate.js",
     "./restore-cid": "./lib/restore-cid.js",
     "./extract-blocks": "./lib/extract-blocks.js",
+    "./app-backup": "./lib/app-backup.js",
     "./gateway-fetch": "./lib/gateway-fetch.js",
     "./peer-fetch": "./lib/peer-fetch.js",
     "./backends/types": "./lib/backends/types.js",