@le-space/orbitdb-storage-bridge 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,8 +25,8 @@ Where "somewhere else" is, is a choice:
25
25
 
26
26
  | Backend | Needs | |
27
27
  | --- | --- | --- |
28
- | `aleph` | nothing | the only backend a browser can write to with no key; ingest only |
29
- | `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 |
28
+ | `aleph` | nothing | the only backend a browser can write to with no key; ingest only — nothing is kept, listed or deleted here, see `aleph-pin` |
29
+ | `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 — and the FORGET that releases it |
30
30
  | `pinata` | a scoped JWT | pin-by-CID as well as CAR upload |
31
31
  | `lighthouse` | an API key | pay once, stored in perpetuity |
32
32
  | `memory` | nothing | in-process, for tests and demos |
@@ -39,12 +39,54 @@ points do not involve a storage service at all — `courier-sync` replicates ove
39
39
  (a LoRa mesh, a QR relay, a file), and `dehydrate`/`hydrate` put a database where a second device
40
40
  can find it from a passkey alone.
41
41
 
42
+ How the pieces fit, as sequence diagrams: a full backup with a delegate's STORE and the restore on
43
+ an empty device in [docs/APP-BACKUP.md](docs/APP-BACKUP.md), the increments between two backups in
44
+ [docs/LIVE-BACKUP.md](docs/LIVE-BACKUP.md), the FORGET in
45
+ [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md#forgetting).
46
+
47
+ ## Entry points
48
+
49
+ Every import path the package exports, and what it is for. New code uses the sub-paths; the main
50
+ entry is the Storacha-era class and the helpers it grew.
51
+
52
+ | Import (`@le-space/orbitdb-storage-bridge` + …) | What it is |
53
+ | --- | --- |
54
+ | `.` | `OrbitDBStorachaBridge` and the older helpers (`backupDatabase`, `restoreDatabase`, `analyzeBlocks`, `extractManifestCID`); Storacha itself loads only when a Storacha path is called |
55
+ | `/backup-car` | `createCARFromBlocks`, `readBlocksFromCAR`, `backupDatabaseCAR` — the CAR every backup is ([docs/CAR-BACKUP.md](docs/CAR-BACKUP.md)) |
56
+ | `/restore-cid` | `restoreFromCID`, `restoreFromBlocks`: a database back from a CID, or from blocks verified one by one |
57
+ | `/extract-blocks` | `extractDatabaseBlocks`, `bundleDatabases`: one database's blocks, or several databases' in one bundle |
58
+ | `/app-backup` | one sealed file for an application: `buildAppBackup`, `openAppBackup`, `restoreAppBackup`, `readAppBackupHeader`, `isAppBackup` |
59
+ | `/live-backup` | increments: `createLiveBackup`, `collectIncrement`, `readIncrement`, `mergeIncrements`, `restoreFromIncrements`, `joinIncrements` |
60
+ | `/dehydrate` | `dehydrate`, `hydrate`: a database where a second device finds it from a secret alone |
61
+ | `/pointer-ipns` | `publishPointer`, `resolvePointer`: the IPNS pointer `dehydrate` publishes, under a name derived from a seed |
62
+ | `/gateway-fetch` | `fetchFromGateways`: bytes by CID over HTTP, verified against the CID |
63
+ | `/peer-fetch` | `createPeerFetch`, `createGatewayFirstFetch`: bytes by CID from the peers that hold them, over libp2p |
64
+ | `/courier-sync` | `createCourierSync`: replication over any byte courier — a LoRa mesh, a QR relay, a file |
65
+ | `/memory-courier` | `createMemoryCourierPair`: the in-process courier for tests and demos |
66
+ | `/backends/types` | the contract: `defineBackend`, `BackendError`, the capability flags |
67
+ | `/backends/memory` | the in-process driver |
68
+ | `/backends/aleph` | `createAlephBackend`: ingest to Aleph's IPFS with no key; nothing kept, listed or deleted here |
69
+ | `/backends/aleph-pin` | `createAlephPin`, `createAlephAuthorizer`, `listAlephStores`, `waitForMessage`, `createAlephForget`, `forgetAlephStores`: what makes Aleph keep a file, and lets it go |
70
+ | `/backends/pinata` | Pinata: pin by CID or upload, with a scoped JWT; `remove()` by file id |
71
+ | `/backends/lighthouse` | Lighthouse: upload with an API key; `list()` and `remove()` |
72
+ | `/backends/storacha` | the Storacha driver; needs the optional peer `@storacha/client`, and a service that no longer answers |
73
+ | `/backends/mirror` | one backup to several backends |
74
+ | `/backends/encryption` | `withEncryption`: the service holds ciphertext |
75
+ | `/backends/choose` | `createBackendFromChoice`: a backend from a name and a key, for a page's form |
76
+ | `/backends/resolve` | `resolveBackend`: the options-to-backend step the older functions share |
77
+ | `/StorachaAuth.svelte`, `/StorachaIntegration.svelte`, `/storacha-backup`, `/components/*` | point into a `dist/` that no build produces; not importable ([docs/STORACHA-UI-HISTORY.md](docs/STORACHA-UI-HISTORY.md)) |
78
+
42
79
  ## Install
43
80
 
44
81
  ```bash
45
82
  npm install @le-space/orbitdb-storage-bridge
46
83
  ```
47
84
 
85
+ That brings Aleph, Pinata, Lighthouse and the in-memory driver. The Storacha driver
86
+ (`backends/storacha`, the `OrbitDBStorachaBridge` class) needs `@storacha/client`, an optional
87
+ peer dependency since 0.22.0 — the service shut down on 2026-05-15, and 28 packages for a backend
88
+ nobody can reach were not worth every install. `npm install @storacha/client` puts them back.
89
+
48
90
  ## Quick start
49
91
 
50
92
  The demos back up to Aleph, which accepts an upload without an account, so they run straight after
@@ -82,7 +124,7 @@ Galaxy A57 with the same key brought the database back and wrote to it. Source:
82
124
  | [docs/DESIGN.md](docs/DESIGN.md) | the problem this solves, and how a backup and a restore actually work |
83
125
  | [docs/STORAGE-BACKENDS.md](docs/STORAGE-BACKENDS.md) | every backend evaluated — prices, limits, and what has been verified against a live account |
84
126
  | [docs/RECOVERY-ON-A-SECOND-DEVICE.md](docs/RECOVERY-ON-A-SECOND-DEVICE.md) | the passkey recovery procedure, step by step |
85
- | [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | CAR-based timestamped backups |
127
+ | [docs/CAR-BACKUP.md](docs/CAR-BACKUP.md) | the CAR as the unit of every backup, and the Storacha-era timestamped listing |
86
128
  | [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 |
87
129
  | [docs/LIVE-BACKUP.md](docs/LIVE-BACKUP.md) | increments between two full backups: what was written since the last one, shipped as one small CAR, with nobody clicking and no peer online |
88
130
  | [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 |
@@ -1,5 +1,7 @@
1
1
  /**
2
- * @fileoverview Making Aleph keep something: the STORE message, and nothing else.
2
+ * @fileoverview Making Aleph keep something, and letting it go: the STORE
3
+ * message, the owner's `security` authorizations, listing by owner, waiting
4
+ * for a decision, and FORGET.
3
5
  *
4
6
  * `createAlephBackend` stores without a key and says plainly that it does not
5
7
  * retain. This is the other half — and it is deliberately a separate module,
@@ -94,6 +96,11 @@ async function sha256Hex(payload) {
94
96
  * by default
95
97
  * @param {string} args.cid - what to keep
96
98
  * @param {string} [args.channel]
99
+ * @param {string} [args.ref] - Aleph's free-text `ref` on the STORE: a label the
100
+ * messages API filters by (`refs=`), so an application can keep several
101
+ * chains on one account and channel and list one of them — the increments of
102
+ * one database, say — without downloading anything. Opaque to Aleph; what it
103
+ * discloses is the caller's choice (a derived fingerprint, not an address)
97
104
  * @param {"credit" | "hold" | null} [args.payment] - `credit` by default; `null`
98
105
  * sends no `payment`, as every version up to 0.16.1 did, which Aleph books as
99
106
  * `hold`
@@ -105,10 +112,17 @@ export async function buildStoreMessage({
105
112
  owner,
106
113
  cid,
107
114
  channel = DEFAULT_ALEPH_CHANNEL,
115
+ ref,
108
116
  payment = "credit",
109
117
  now,
110
118
  hasher = sha256Hex,
111
119
  }) {
120
+ if (ref != null && (typeof ref !== "string" || !ref)) {
121
+ throw new BackendError(
122
+ "INVALID_BACKEND",
123
+ "a STORE's ref is a non-empty string, or absent",
124
+ );
125
+ }
112
126
  if (payment !== null && !STORE_PAYMENTS.includes(payment)) {
113
127
  throw new BackendError(
114
128
  "INVALID_BACKEND",
@@ -123,6 +137,7 @@ export async function buildStoreMessage({
123
137
  // "the thing to keep is an IPFS CID" — not the envelope's item_type
124
138
  item_type: "ipfs",
125
139
  item_hash: cid,
140
+ ...(ref ? { ref } : {}),
126
141
  // How that account pays. Without it Aleph books the STORE as `hold`, and an
127
142
  // account funded with credits covers nothing (see the file's header).
128
143
  ...(payment ? { payment: { type: payment } } : {}),
@@ -157,11 +172,13 @@ export const signaturePayload = (message) =>
157
172
  * `personal_sign`, or anything shaped like it. The library never sees a key.
158
173
  * @param {string} [options.apiHost]
159
174
  * @param {string} [options.channel]
175
+ * @param {string} [options.ref] - the `ref` every STORE from this pin carries
176
+ * (see {@link buildStoreMessage}); a `meta.ref` on one call wins over it
160
177
  * @param {"credit" | "hold" | null} [options.payment] - see {@link buildStoreMessage}
161
178
  * @param {(payload: string) => Promise<string>} [options.hasher]
162
179
  * @param {typeof fetch} [options.fetch]
163
180
  * @param {() => number} [options.now] - seconds
164
- * @returns {(cid: string, meta?: object) => Promise<{ itemHash: string, status: string }>}
181
+ * @returns {(cid: string, meta?: { name?: string, ref?: string }) => Promise<{ itemHash: string, status: string }>}
165
182
  * `status` is what Aleph answered: `processed`, or `pending` until it has
166
183
  * checked the signature, the authorization and the credit — follow a pending
167
184
  * one with {@link waitForMessage}.
@@ -188,12 +205,13 @@ export function createAlephPin(options = {}) {
188
205
  if (typeof doFetch !== "function")
189
206
  throw new BackendError("INVALID_BACKEND", "createAlephPin needs fetch");
190
207
 
191
- return async function pin(cid) {
208
+ return async function pin(cid, meta = {}) {
192
209
  const unsigned = await buildStoreMessage({
193
210
  sender,
194
211
  owner,
195
212
  cid,
196
213
  channel,
214
+ ref: meta?.ref ?? options.ref,
197
215
  payment,
198
216
  hasher,
199
217
  now: now?.(),
@@ -317,6 +335,7 @@ export async function waitForMessage(itemHash, options = {}) {
317
335
  * @param {string} options.owner - the paying account, EIP-55 checksummed (Aleph
318
336
  * keys accounts by that form)
319
337
  * @param {string} [options.channel] - one channel; every channel when absent
338
+ * @param {string} [options.ref] - only STOREs carrying this `ref` (`refs=`); every STORE when absent
320
339
  * @param {string} [options.apiHost]
321
340
  * @param {typeof fetch} [options.fetch]
322
341
  * @param {number} [options.pagination] - per page; default 50
@@ -326,7 +345,7 @@ export async function waitForMessage(itemHash, options = {}) {
326
345
  * the handle's `id`
327
346
  */
328
347
  export async function listAlephStores(options = {}) {
329
- const { owner, channel } = options;
348
+ const { owner, channel, ref } = options;
330
349
  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
331
350
  const doFetch = options.fetch || globalThis.fetch;
332
351
  if (!owner)
@@ -334,6 +353,11 @@ export async function listAlephStores(options = {}) {
334
353
  "INVALID_BACKEND",
335
354
  "listAlephStores needs the paying account's address as `owner`",
336
355
  );
356
+ if (ref != null && (typeof ref !== "string" || !ref))
357
+ throw new BackendError(
358
+ "INVALID_BACKEND",
359
+ "listAlephStores takes `ref` as a non-empty string, or not at all",
360
+ );
337
361
  if (typeof doFetch !== "function")
338
362
  throw new BackendError("INVALID_BACKEND", "listAlephStores needs fetch");
339
363
 
@@ -341,6 +365,7 @@ export async function listAlephStores(options = {}) {
341
365
  url.searchParams.set("owners", owner);
342
366
  url.searchParams.set("msgTypes", "STORE");
343
367
  if (channel) url.searchParams.set("channels", channel);
368
+ if (ref) url.searchParams.set("refs", ref);
344
369
  url.searchParams.set("pagination", String(options.pagination ?? 50));
345
370
  url.searchParams.set("page", String(options.page ?? 1));
346
371
 
@@ -362,11 +387,16 @@ export async function listAlephStores(options = {}) {
362
387
  owner: String(m?.content?.address ?? ""),
363
388
  time: Number(m?.content?.time ?? m?.time ?? 0),
364
389
  ...(m?.channel ? { channel: m.channel } : {}),
390
+ ...(typeof m?.content?.ref === "string" && m.content.ref
391
+ ? { ref: m.content.ref }
392
+ : {}),
365
393
  ...(m?.content?.payment?.type ? { payment: m.content.payment.type } : {}),
366
394
  }))
367
395
  // Aleph answers what it was asked; keeping only this owner's costs nothing
368
396
  // and keeps a misread filter from handing back someone else's files.
369
397
  .filter((store) => store.cid && store.itemHash && same(store.owner, owner))
398
+ // A host that ignored `refs=` must not hand back the other chains.
399
+ .filter((store) => !ref || store.ref === ref)
370
400
  .sort((a, b) => b.time - a.time);
371
401
  return {
372
402
  stores,
@@ -532,6 +562,7 @@ export function createAlephForget(options = {}) {
532
562
  * @param {object} options
533
563
  * @param {string} options.owner - the account the STOREs are for
534
564
  * @param {string} options.channel - one channel; a FORGET across channels is not what anyone means
565
+ * @param {string} [options.ref] - only the STOREs carrying this `ref` (one chain of several on the account); all of the channel when absent
535
566
  * @param {ReturnType<typeof createAlephForget>} options.forget - from {@link createAlephForget}, signing for that account
536
567
  * @param {(store: { cid: string, itemHash: string, time: number }) => boolean} [options.keep]
537
568
  * @param {string} [options.reason]
@@ -549,6 +580,7 @@ export async function forgetAlephStores(options = {}) {
549
580
  const {
550
581
  owner,
551
582
  channel,
583
+ ref,
552
584
  forget,
553
585
  keep,
554
586
  reason,
@@ -580,6 +612,7 @@ export async function forgetAlephStores(options = {}) {
580
612
  const { stores, total } = await listAlephStores({
581
613
  owner,
582
614
  channel,
615
+ ...(ref ? { ref } : {}),
583
616
  apiHost,
584
617
  fetch: doFetch,
585
618
  pagination: 100,
@@ -35,8 +35,8 @@
35
35
  * STORE message with the `ipfs` engine, posted to `api2.aleph.im`. That needs a
36
36
  * wallet and an SDK, so it is **injected rather than imported**: pass `pin` and
37
37
  * the driver declares `pinByCid`; leave it out and the driver is honest about
38
- * being ingest-only. `relay-button`'s `@le-space/browser` already speaks that
39
- * API, which is the implementation this hook is shaped for.
38
+ * being ingest-only. `./aleph-pin.js` is that implementation: `createAlephPin`
39
+ * builds and signs the STORE, and is what a caller passes as `pin`.
40
40
  *
41
41
  * @author @NiKrause
42
42
  * @requires ./types.js - the backend contract
@@ -53,8 +53,9 @@ import { fetchFromGateways } from "../gateway-fetch.js";
53
53
  * `dweb.link` and `ipfs.io` were the two fallbacks behind it until Protocol
54
54
  * Labs retired them on 2026-09-21; they answer 429 with a `Sunset` header now.
55
55
  * Nothing free was found to replace them that will serve an arbitrary CID, so
56
- * this driver's retrieval depends on one host until the peer path in #112
57
- * lands. A caller with its own gateway passes `gateways`.
56
+ * this driver's retrieval over HTTP depends on one host; `peer-fetch` (since
57
+ * 0.12.0) is the other path, over libp2p. A caller with its own gateway passes
58
+ * `gateways`.
58
59
  */
59
60
  export const ALEPH_GATEWAYS = Object.freeze(["https://ipfs.aleph.cloud/ipfs"]);
60
61
 
@@ -103,14 +104,19 @@ export function createAlephBackend(options = {}) {
103
104
  preservesInnerCids: true,
104
105
  // No key exists to leak.
105
106
  browserSafeAuth: true,
107
+ // Aleph's `security` aggregate (`createAlephAuthorizer` in ./aleph-pin.js)
108
+ // lets a paying account authorise another key for STORE on a channel, and
109
+ // revoke it — but never for a time, and the contract's `delegation` means
110
+ // scoped *and* time-bounded. So: no, with the grant documented there.
106
111
  delegation: false,
107
112
  // The IPFS host offers no listing, and the messages API needs the paying
108
113
  // account's address, which this driver deliberately does not hold:
109
114
  // `listAlephStores` in ./aleph-pin.js takes it.
110
115
  listing: false,
111
- // Unpinning is a FORGET message, so it belongs with `pin` rather than
112
- // here. Claiming deletion the driver cannot perform would be worse than
113
- // saying no.
116
+ // Unpinning is a FORGET message signed by the paying account:
117
+ // `createAlephForget` / `forgetAlephStores` in ./aleph-pin.js. `remove()`
118
+ // would need a key this driver does not hold, and claiming a deletion it
119
+ // cannot perform would be worse than saying no.
114
120
  deletion: false,
115
121
  minBlobSize: 0,
116
122
  },
@@ -30,7 +30,9 @@
30
30
  * @property {boolean} browserSafeAuth - no shared secret has to reach the browser
31
31
  * @property {boolean} delegation - access can be handed on, scoped and time-bounded
32
32
  * @property {boolean} listing - `list()` is implemented
33
- * @property {boolean} deletion - `remove()` is implemented
33
+ * @property {boolean} deletion - `remove()` by handle is implemented. A service whose
34
+ * release is a signed message (Aleph's FORGET) says false here and documents the message
35
+ * elsewhere
34
36
  * @property {number} minBlobSize - smallest accepted upload in bytes; 0 when there is no minimum
35
37
  */
36
38
 
package/lib/backup-car.js CHANGED
@@ -1,14 +1,12 @@
1
1
  /**
2
- * CAR-based OrbitDB Backup with Timestamps
2
+ * CAR backup and restore through any backend.
3
3
  *
4
- * Alternative implementation using CAR (Content Addressable Archive) files
5
- * for efficient timestamped backups. Works in both Node.js and browser environments.
6
- *
7
- * This is backward compatible with the existing individual block upload approach.
8
- * Use this when you want:
9
- * - Timestamped backups (multiple backup points)
10
- * - More efficient upload (fewer files)
11
- * - Better organization (grouped by timestamp)
4
+ * `createCARFromBlocks` and `readBlocksFromCAR` are the pair every other
5
+ * module builds on. `backupDatabaseCAR` packs one database into a CAR and
6
+ * uploads it with a metadata file through the backend `resolveBackend` picks
7
+ * from the options. `listAvailableBackups` and `restoreFromSpaceCAR` are
8
+ * Storacha-era: they need a backend that lists, and find a backup by reading
9
+ * every file in the listing. Works in Node.js and in a browser.
12
10
  */
13
11
 
14
12
  import { CarWriter, CarReader } from "@ipld/car";
@@ -6,7 +6,7 @@ import { logger } from "./logger.js";
6
6
  /**
7
7
  * Generate backup prefix with timestamp
8
8
  *
9
- * @param {string} spaceName - Name of the Storacha space
9
+ * @param {string} spaceName - a label kept in the metadata (a Storacha space, once)
10
10
  * @returns {string} - Backup prefix including timestamp
11
11
  */
12
12
  export function generateBackupPrefix(spaceName) {
@@ -27,8 +27,8 @@
27
27
  * ## One upload, one STORE
28
28
  *
29
29
  * An increment is one CAR whose root is a dag-cbor manifest
30
- * (`{ kind: "increment", v: 1, sequence, base, previous, metadata }`), so a
31
- * single blob is self-describing. Every increment carries each database's
30
+ * (`{ kind: "increment", v: 1, sequence, base, previous, createdAt, metadata }`),
31
+ * so a single blob is self-describing. Every increment carries each database's
32
32
  * manifest and access controller (a few hundred bytes) and the identity of
33
33
  * every writer it has entries from, so a chain of increments restores on its
34
34
  * own, with no base, if it is complete from the beginning; and so
@@ -430,7 +430,9 @@ function assertContiguous({ gaps, duplicates }, allowGaps) {
430
430
  * @param {Function} [params.onProgress]
431
431
  * @param {boolean} [params.allowGaps=false] - join a chain with missing or
432
432
  * duplicate sequence numbers instead of refusing it
433
- * @returns {Promise<{ blocks: number, databases: object[], sequences: number[] }>}
433
+ * @returns {Promise<{ blocks: number, databases: object[], sequences: number[], gaps: number[], duplicates: number[] }>}
434
+ * `gaps` and `duplicates`: the sequence numbers `mergeIncrements` found missing
435
+ * or twice — both empty unless `allowGaps` let such a chain through.
434
436
  */
435
437
  export async function restoreFromIncrements(
436
438
  orbitdb,
@@ -444,7 +446,12 @@ export async function restoreFromIncrements(
444
446
  log,
445
447
  onProgress,
446
448
  });
447
- return { ...restored, sequences };
449
+ return {
450
+ ...restored,
451
+ sequences,
452
+ gaps: merged.gaps,
453
+ duplicates: merged.duplicates,
454
+ };
448
455
  }
449
456
 
450
457
  /**
@@ -465,7 +472,10 @@ export async function restoreFromIncrements(
465
472
  * where the application's own (non-dag-cbor) blocks go, e.g. `orbitdb.ipfs.blockstore`;
466
473
  * without it they are counted in `skippedRaw` and left out
467
474
  * @param {boolean} [params.allowGaps=false]
468
- * @returns {Promise<{ joined: number, heads: number, blocks: number, skippedRaw?: number }>}
475
+ * @returns {Promise<{ joined: number, heads: number, blocks: number, gaps: number[], duplicates: number[], skippedRaw?: number }>}
476
+ * `gaps`: sequence numbers missing from the chain; `duplicates`: sequence
477
+ * numbers carried by more than one increment (two devices numbering on
478
+ * their own) — both empty unless the join was told `allowGaps`
469
479
  */
470
480
  export async function joinIncrements(
471
481
  database,
@@ -508,6 +518,9 @@ export async function joinIncrements(
508
518
  joined,
509
519
  heads: (described.heads ?? []).length,
510
520
  blocks: blocks.size,
521
+ // What the chain looked like, for a caller that joined it with allowGaps.
522
+ gaps: merged.gaps,
523
+ duplicates: merged.duplicates,
511
524
  ...(skippedRaw ? { skippedRaw } : {}),
512
525
  };
513
526
  }
@@ -1,14 +1,17 @@
1
1
  /**
2
- * OrbitDB Storacha Bridge - Main Library
2
+ * Main entry: the Storacha-era bridge class and the block, CID and restore
3
+ * helpers it grew. New code imports the sub-paths (`./backup-car`,
4
+ * `./restore-cid`, `./app-backup`, `./live-backup`, the drivers under
5
+ * `./backends/`); this file stays for the class and for the helpers the
6
+ * sub-paths still share.
3
7
  *
4
- * Provides complete OrbitDB database backup and restoration via Storacha/Filecoin
5
- * with 100% hash preservation and identity recovery.
8
+ * `@storacha/client` is an optional peer dependency since 0.22.0: the service
9
+ * shut down on 2026-05-15, and a consumer that only ever reaches Aleph, Pinata
10
+ * or Lighthouse should not carry 28 packages for it. Nothing here imports it
11
+ * at load time; `initializeStorachaClient` loads it on first use and says
12
+ * what is missing when it is not installed.
6
13
  */
7
14
 
8
- import * as Client from "@storacha/client";
9
- import { StoreMemory } from "@storacha/client/stores/memory";
10
- import { Signer } from "@storacha/client/principal/ed25519";
11
- import * as Proof from "@storacha/client/proof";
12
15
  import { BackendError } from "./backends/types.js";
13
16
  import { CID } from "multiformats/cid";
14
17
  import * as Block from "multiformats/block";
@@ -97,6 +100,34 @@ export function extractManifestCID(databaseAddress) {
97
100
  }
98
101
 
99
102
 
103
+ /**
104
+ * The Storacha client, loaded when first needed and never at import time.
105
+ * `@storacha/client` is an optional peer dependency: without it the main
106
+ * entry still loads, and only the Storacha paths fail, here, with a message
107
+ * that names the package.
108
+ *
109
+ * @returns {Promise<{Client: object, StoreMemory: Function, Signer: {parse: Function}, Proof: {parse: Function}}>}
110
+ */
111
+ async function loadStorachaClient() {
112
+ try {
113
+ const [Client, { StoreMemory }, { Signer }, Proof] = await Promise.all([
114
+ import("@storacha/client"),
115
+ import("@storacha/client/stores/memory"),
116
+ import("@storacha/client/principal/ed25519"),
117
+ import("@storacha/client/proof"),
118
+ ]);
119
+ return { Client, StoreMemory, Signer, Proof };
120
+ } catch (error) {
121
+ if (error?.code === "ERR_MODULE_NOT_FOUND" || error?.code === "MODULE_NOT_FOUND") {
122
+ throw new Error(
123
+ "The Storacha backend needs @storacha/client, an optional peer dependency since 0.22.0: npm install @storacha/client",
124
+ { cause: error },
125
+ );
126
+ }
127
+ throw error;
128
+ }
129
+ }
130
+
100
131
  /**
101
132
  * Initialize Storacha client with credentials
102
133
  *
@@ -112,6 +143,7 @@ async function initializeStorachaClient(
112
143
  serviceConf,
113
144
  receiptsEndpoint,
114
145
  ) {
146
+ const { Client, StoreMemory, Signer, Proof } = await loadStorachaClient();
115
147
  const principal = Signer.parse(storachaKey);
116
148
  const store = new StoreMemory();
117
149
  const clientOptions = { principal, store };
package/package.json CHANGED
@@ -1,15 +1,12 @@
1
1
  {
2
2
  "name": "@le-space/orbitdb-storage-bridge",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "description": "Back up, restore and replicate OrbitDB databases through pluggable storage backends, with hash and identity preservation",
5
5
  "main": "lib/orbitdb-storacha-bridge.js",
6
6
  "svelte": "dist/components/",
7
7
  "type": "module",
8
8
  "exports": {
9
- ".": {
10
- "types": "./lib/orbitdb-storacha-bridge.d.ts",
11
- "default": "./lib/orbitdb-storacha-bridge.js"
12
- },
9
+ ".": "./lib/orbitdb-storacha-bridge.js",
13
10
  "./backup-car": "./lib/backup-car.js",
14
11
  "./courier-sync": "./lib/courier-sync.js",
15
12
  "./pointer-ipns": "./lib/pointer-ipns.js",
@@ -58,7 +55,6 @@
58
55
  },
59
56
  "keywords": [
60
57
  "orbitdb",
61
- "storacha",
62
58
  "filecoin",
63
59
  "ipfs",
64
60
  "backup",
@@ -73,6 +69,7 @@
73
69
  "car",
74
70
  "aleph",
75
71
  "pinata",
72
+ "storacha",
76
73
  "local-first"
77
74
  ],
78
75
  "files": [
@@ -96,7 +93,6 @@
96
93
  "@helia/unixfs": "^8.0.7",
97
94
  "@ipld/car": "^5.4.1",
98
95
  "@ipld/dag-cbor": "^9.0.6",
99
- "@ipld/dag-ucan": "^3.4.5",
100
96
  "@libp2p/bootstrap": "^12.0.27",
101
97
  "@libp2p/crypto": "^5.1.21",
102
98
  "@libp2p/gossipsub": "^16.1.0",
@@ -107,12 +103,9 @@
107
103
  "@libp2p/tcp": "^11.0.28",
108
104
  "@orbitdb/core": "^4.0.0",
109
105
  "@scure/bip39": "^1.3.0",
110
- "@storacha/capabilities": "^2.0.0",
111
- "@storacha/client": "^2.0.0",
112
106
  "blockstore-level": "^4.0.1",
113
107
  "cbor-web": "^10.0.11",
114
108
  "datastore-level": "^13.0.1",
115
- "dotenv": "^17.2.1",
116
109
  "helia": "^7.1.15",
117
110
  "libp2p": "^3.3.6",
118
111
  "multiformats": "^14.0.5"
@@ -120,10 +113,13 @@
120
113
  "devDependencies": {
121
114
  "@eslint/js": "^10.0.1",
122
115
  "@ibm/plex": "^6.4.1",
116
+ "@ipld/dag-ucan": "^3.4.5",
123
117
  "@jest/globals": "^30.5.1",
124
118
  "@le-space/ucanto-principal": "^9.1.1",
125
119
  "@libp2p/websockets": "^10.1.17",
126
120
  "@orbitdb/identity-provider-did": "^1.0.2",
121
+ "@storacha/capabilities": "^2.0.0",
122
+ "@storacha/client": "^2.0.0",
127
123
  "@storacha/did-mailto": "^1.0.1",
128
124
  "@storacha/upload-api": "^3.0.0",
129
125
  "@types/jest": "^30.0.0",
@@ -135,6 +131,7 @@
135
131
  "@web3-storage/sigv4": "^1.0.2",
136
132
  "carbon-components-svelte": "^0.89.7",
137
133
  "carbon-icons-svelte": "^12.17.0",
134
+ "dotenv": "^17.2.1",
138
135
  "eslint": "^10.10.0",
139
136
  "jest": "^30.5.1",
140
137
  "key-did-provider-ed25519": "^4.0.2",
@@ -145,7 +142,8 @@
145
142
  },
146
143
  "peerDependencies": {
147
144
  "lucide-svelte": ">=0.400.0 <1.0.0",
148
- "svelte": "^3.0.0 || ^4.0.0 || ^5.0.0"
145
+ "svelte": "^3.0.0 || ^4.0.0 || ^5.0.0",
146
+ "@storacha/client": "^2.0.0"
149
147
  },
150
148
  "engines": {
151
149
  "node": ">=22.0.0"
@@ -176,5 +174,10 @@
176
174
  },
177
175
  "overrides": {
178
176
  "test-exclude": "^8.0.0"
177
+ },
178
+ "peerDependenciesMeta": {
179
+ "@storacha/client": {
180
+ "optional": true
181
+ }
179
182
  }
180
183
  }
package/lib/backup.js DELETED
@@ -1,249 +0,0 @@
1
- /**
2
- * OrbitDB database backup with timestamps and error handling
3
- * NOTE: This file is a placeholder/example and is incomplete
4
- */
5
-
6
- /* eslint-disable no-undef, no-unused-vars */
7
- import { Readable } from "stream";
8
- import { CarReader } from "@ipld/car";
9
- import * as Signer from "@storacha/client/principal/ed25519";
10
- import { createWritableCarReader } from "@storacha/client/utils";
11
- import { logger } from "./logger.js";
12
- import {
13
- generateBackupPrefix,
14
- getBackupFilenames,
15
- isValidMetadata,
16
- findLatestBackup,
17
- } from "./backup-helpers.js";
18
-
19
- const DEFAULT_OPTIONS = {
20
- verbose: false,
21
- };
22
-
23
- /**
24
- * Backup an OrbitDB database with timestamps and error handling
25
- *
26
- * @param {Object} orbitdb - OrbitDB instance
27
- * @param {string} databaseAddress - Database address or name
28
- * @param {Object} options - Backup options
29
- * @returns {Promise<Object>} - Backup result
30
- */
31
- export async function backupDatabase(orbitdb, databaseAddress, options = {}) {
32
- const config = { ...DEFAULT_OPTIONS, ...options };
33
- const { verbose } = config;
34
- const { spaceName } = config;
35
- const eventEmitter = options.eventEmitter;
36
- const logDebug = (message) => {
37
- if (verbose) {
38
- logger.debug(message);
39
- }
40
- };
41
-
42
- logDebug("🚀 Starting OrbitDB Database Backup");
43
- logDebug(`📍 Database: ${databaseAddress}`);
44
-
45
- try {
46
- // Open database and extract blocks
47
- const database = await orbitdb.open(databaseAddress, options.dbConfig);
48
- const { blocks, blockSources, manifestCID } = await extractDatabaseBlocks(
49
- database,
50
- { logEntriesOnly: false },
51
- );
52
-
53
- // Generate timestamped backup paths
54
- const backupPrefix = generateBackupPrefix(spaceName);
55
- const backupFiles = getBackupFilenames(backupPrefix);
56
-
57
- // Create metadata
58
- const metadata = {
59
- version: "1.0",
60
- timestamp: Date.now(),
61
- databaseCount: 1,
62
- totalEntries: blocks.size,
63
- databases: [
64
- {
65
- root: database.address.root,
66
- path: database.address.path,
67
- },
68
- ],
69
- };
70
-
71
- // Validate metadata structure
72
- if (!isValidMetadata(metadata)) {
73
- throw new Error("Invalid metadata structure");
74
- }
75
-
76
- // Write metadata with error handling
77
- try {
78
- await Signer.writeFile(
79
- backupFiles.metadata,
80
- JSON.stringify(metadata, null, 2),
81
- );
82
- } catch (error) {
83
- throw new Error(`Failed to write backup metadata: ${error.message}`, { cause: error });
84
- }
85
-
86
- // Write blocks with error handling
87
- try {
88
- // Create CAR storage and add blocks
89
- const storage = await CARStorage({
90
- path: ".",
91
- name: "backup-temp",
92
- autoFlush: false,
93
- });
94
-
95
- for (const [key, value] of blocks) {
96
- await storage.put(key, value);
97
- }
98
-
99
- await storage.persist();
100
- const reader = await CarReader.fromIterable(storage.iterator());
101
- const stream = Readable.from(reader.blocks());
102
-
103
- await stream.pipe(
104
- await createWritableCarReader({
105
- name: backupFiles.blocks,
106
- comment: `OrbitDB backup blocks (created at ${new Date().toISOString()})`,
107
- space: spaceName,
108
- }),
109
- );
110
-
111
- // Clean up temp storage
112
- await storage.close();
113
- await storage.clear();
114
- } catch (error) {
115
- // Try to clean up failed metadata
116
- try {
117
- await Signer.rm(backupFiles.metadata);
118
- } catch (cleanupError) {
119
- logDebug(
120
- `Failed to clean up metadata after error: ${cleanupError.message}`,
121
- );
122
- }
123
- throw new Error(`Failed to write backup blocks: ${error.message}`, { cause: error });
124
- }
125
-
126
- // Return success with file info
127
- return {
128
- success: true,
129
- manifestCID,
130
- databaseAddress: database.address,
131
- databaseName: database.name,
132
- blocksTotal: blocks.size,
133
- blocksUploaded: blocks.size,
134
- blockSummary: blockSources,
135
- backupFiles,
136
- };
137
- } catch (error) {
138
- return {
139
- success: false,
140
- error: error.message,
141
- };
142
- }
143
- }
144
-
145
- /**
146
- * Restore from the latest valid backup in a space
147
- *
148
- * @param {Object} orbitdb - OrbitDB instance
149
- * @param {Object} options - Restore options
150
- * @returns {Promise<Object>} - Restore result
151
- */
152
- export async function restoreFromSpace(orbitdb, options = {}) {
153
- const config = { ...DEFAULT_OPTIONS, ...options };
154
- const { verbose } = config;
155
- const { spaceName } = config;
156
- const logDebug = (message) => {
157
- if (verbose) {
158
- logger.debug(message);
159
- }
160
- };
161
-
162
- logDebug("🔄 Starting OrbitDB Restore");
163
-
164
- try {
165
- // Find latest valid backup
166
- const spaceFiles = await listStorachaSpaceFiles(config);
167
- const latestBackup = findLatestBackup(spaceFiles, {
168
- verbose,
169
- });
170
-
171
- if (!latestBackup) {
172
- throw new Error("No valid backup found in space");
173
- }
174
-
175
- // Read and validate metadata
176
- let metadata;
177
- try {
178
- const metadataJson = await Signer.readFile(
179
- `${spaceName}/${latestBackup.metadata}`,
180
- );
181
- metadata = JSON.parse(metadataJson);
182
- if (!isValidMetadata(metadata)) {
183
- throw new Error("Invalid backup metadata structure");
184
- }
185
- } catch (error) {
186
- throw new Error(`Failed to read/validate metadata: ${error.message}`, { cause: error });
187
- }
188
-
189
- // Create storage and load blocks
190
- const storage = await CARStorage({
191
- path: ".",
192
- name: "restore-temp",
193
- autoFlush: false,
194
- });
195
-
196
- try {
197
- // Get blocks stream
198
- const carStream = await Signer.readStream(
199
- `${spaceName}/${latestBackup.blocks}`,
200
- );
201
- const reader = await fromReadableStream(carStream);
202
-
203
- // Load blocks with validation
204
- let validBlocks = 0;
205
- for await (const block of reader.blocks()) {
206
- try {
207
- await storage.put(block.cid.toString(), block.bytes);
208
- validBlocks++;
209
- } catch (blockError) {
210
- logDebug(`⚠️ Failed to restore block: ${blockError.message}`);
211
- }
212
- }
213
-
214
- if (validBlocks === 0) {
215
- throw new Error("No valid blocks found in backup");
216
- }
217
-
218
- // Open database using metadata
219
- const databaseAddress = `/orbitdb/${metadata.databases[0].root}`;
220
- const database = await orbitdb.open(databaseAddress);
221
-
222
- // Replace storage and load entries
223
- await database._index.replaceStorage(storage);
224
- await database.load();
225
-
226
- const entries = await database.all();
227
-
228
- return {
229
- success: true,
230
- database,
231
- databaseAddress,
232
- entriesRecovered: entries.length,
233
- blocksRestored: validBlocks,
234
- backupUsed: latestBackup,
235
- };
236
- } catch (error) {
237
- throw new Error(`Failed to restore blocks: ${error.message}`, { cause: error });
238
- } finally {
239
- // Clean up temp storage
240
- await storage.close();
241
- await storage.clear();
242
- }
243
- } catch (error) {
244
- return {
245
- success: false,
246
- error: error.message,
247
- };
248
- }
249
- }