@le-space/orbitdb-storage-bridge 0.18.0 → 0.19.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.
@@ -77,7 +77,9 @@ async function sha256Hex(payload) {
77
77
  "SHA-256",
78
78
  new TextEncoder().encode(payload),
79
79
  );
80
- return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
80
+ return [...new Uint8Array(digest)]
81
+ .map((b) => b.toString(16).padStart(2, "0"))
82
+ .join("");
81
83
  }
82
84
 
83
85
  /**
@@ -173,12 +175,29 @@ export function createAlephPin(options = {}) {
173
175
  const doFetch = options.fetch || globalThis.fetch;
174
176
  const now = options.now;
175
177
 
176
- if (!sender) throw new BackendError("INVALID_BACKEND", "createAlephPin needs the wallet address as `sender`");
177
- if (typeof sign !== "function") throw new BackendError("INVALID_BACKEND", "createAlephPin needs a `sign` function");
178
- if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "createAlephPin needs fetch");
178
+ if (!sender)
179
+ throw new BackendError(
180
+ "INVALID_BACKEND",
181
+ "createAlephPin needs the wallet address as `sender`",
182
+ );
183
+ if (typeof sign !== "function")
184
+ throw new BackendError(
185
+ "INVALID_BACKEND",
186
+ "createAlephPin needs a `sign` function",
187
+ );
188
+ if (typeof doFetch !== "function")
189
+ throw new BackendError("INVALID_BACKEND", "createAlephPin needs fetch");
179
190
 
180
191
  return async function pin(cid) {
181
- const unsigned = await buildStoreMessage({ sender, owner, cid, channel, payment, hasher, now: now?.() });
192
+ const unsigned = await buildStoreMessage({
193
+ sender,
194
+ owner,
195
+ cid,
196
+ channel,
197
+ payment,
198
+ hasher,
199
+ now: now?.(),
200
+ });
182
201
  const signature = await sign(sender, signaturePayload(unsigned));
183
202
  const message = {
184
203
  ...unsigned,
@@ -212,7 +231,13 @@ export function createAlephPin(options = {}) {
212
231
  }
213
232
 
214
233
  /** Statuses after which a message no longer changes by itself. */
215
- const SETTLED = new Set(["processed", "rejected", "removing", "removed", "forgotten"]);
234
+ const SETTLED = new Set([
235
+ "processed",
236
+ "rejected",
237
+ "removing",
238
+ "removed",
239
+ "forgotten",
240
+ ]);
216
241
 
217
242
  /**
218
243
  * Follow a message until Aleph has decided about it.
@@ -241,9 +266,16 @@ export async function waitForMessage(itemHash, options = {}) {
241
266
  const doFetch = options.fetch || globalThis.fetch;
242
267
  const timeout = options.timeout ?? 60_000;
243
268
  const interval = options.interval ?? 2_000;
244
- const sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
245
- if (!itemHash) throw new BackendError("INVALID_BACKEND", "waitForMessage needs the message's item hash");
246
- if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "waitForMessage needs fetch");
269
+ const sleep =
270
+ options.sleep ||
271
+ ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
272
+ if (!itemHash)
273
+ throw new BackendError(
274
+ "INVALID_BACKEND",
275
+ "waitForMessage needs the message's item hash",
276
+ );
277
+ if (typeof doFetch !== "function")
278
+ throw new BackendError("INVALID_BACKEND", "waitForMessage needs fetch");
247
279
 
248
280
  // Counted in asks rather than read off a clock, so an injected `sleep` is enough for a test.
249
281
  const asks = Math.max(1, Math.floor(timeout / interval) + 1);
@@ -297,8 +329,13 @@ export async function listAlephStores(options = {}) {
297
329
  const { owner, channel } = options;
298
330
  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
299
331
  const doFetch = options.fetch || globalThis.fetch;
300
- if (!owner) throw new BackendError("INVALID_BACKEND", "listAlephStores needs the paying account's address as `owner`");
301
- if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "listAlephStores needs fetch");
332
+ if (!owner)
333
+ throw new BackendError(
334
+ "INVALID_BACKEND",
335
+ "listAlephStores needs the paying account's address as `owner`",
336
+ );
337
+ if (typeof doFetch !== "function")
338
+ throw new BackendError("INVALID_BACKEND", "listAlephStores needs fetch");
302
339
 
303
340
  const url = new URL(`${apiHost}/api/v0/messages.json`);
304
341
  url.searchParams.set("owners", owner);
@@ -309,7 +346,10 @@ export async function listAlephStores(options = {}) {
309
346
 
310
347
  const response = await doFetch(url.toString());
311
348
  if (!response.ok) {
312
- throw new BackendError("UNSUPPORTED", `Aleph did not list the STORE messages: ${response.status}`);
349
+ throw new BackendError(
350
+ "UNSUPPORTED",
351
+ `Aleph did not list the STORE messages: ${response.status}`,
352
+ );
313
353
  }
314
354
  const body = await response.json().catch(() => ({}));
315
355
  const messages = Array.isArray(body?.messages) ? body.messages : [];
@@ -328,7 +368,246 @@ export async function listAlephStores(options = {}) {
328
368
  // and keeps a misread filter from handing back someone else's files.
329
369
  .filter((store) => store.cid && store.itemHash && same(store.owner, owner))
330
370
  .sort((a, b) => b.time - a.time);
331
- return { stores, total: Number.isFinite(body?.pagination_total) ? body.pagination_total : null };
371
+ return {
372
+ stores,
373
+ total: Number.isFinite(body?.pagination_total)
374
+ ? body.pagination_total
375
+ : null,
376
+ };
377
+ }
378
+
379
+ /**
380
+ * Build the unsigned FORGET that releases what STORE messages keep.
381
+ *
382
+ * Aleph keeps a file for as long as a STORE names it; a FORGET from the
383
+ * STORE's owner (or a delegate it authorized for `FORGET`) names those STOREs
384
+ * by their item hashes, and the files they kept are unpinned and stop
385
+ * costing credits. Only messages of the same account can be forgotten, and a
386
+ * forgotten message cannot be brought back — the file has to be stored again.
387
+ *
388
+ * @param {object} args
389
+ * @param {string} args.sender - the address that signs
390
+ * @param {string} [args.owner] - the account whose messages these are, when `sender` is its delegate
391
+ * @param {string[]} args.hashes - item hashes of the STORE messages to forget
392
+ * @param {string} [args.reason] - kept with the FORGET, for whoever reads the account's history
393
+ * @param {string} [args.channel]
394
+ * @param {number} [args.now] - seconds since the epoch; injected for tests
395
+ * @param {(payload: string) => Promise<string>} [args.hasher]
396
+ */
397
+ export async function buildForgetMessage({
398
+ sender,
399
+ owner,
400
+ hashes,
401
+ reason,
402
+ channel = DEFAULT_ALEPH_CHANNEL,
403
+ now,
404
+ hasher = sha256Hex,
405
+ }) {
406
+ if (
407
+ !Array.isArray(hashes) ||
408
+ hashes.length === 0 ||
409
+ !hashes.every((h) => typeof h === "string" && h)
410
+ ) {
411
+ throw new BackendError(
412
+ "INVALID_BACKEND",
413
+ "a FORGET names at least one item hash",
414
+ );
415
+ }
416
+ const time = now ?? Date.now() / 1000;
417
+ const content = {
418
+ address: owner || sender,
419
+ time,
420
+ hashes: [...hashes],
421
+ ...(reason ? { reason } : {}),
422
+ };
423
+ const item_content = JSON.stringify(content);
424
+ return {
425
+ sender,
426
+ chain: "ETH",
427
+ type: "FORGET",
428
+ item_hash: await hasher(item_content),
429
+ item_type: "inline",
430
+ item_content,
431
+ time,
432
+ channel,
433
+ };
434
+ }
435
+
436
+ /**
437
+ * Forget STORE messages: a signed FORGET, posted, and Aleph's first answer.
438
+ *
439
+ * The same shape as {@link createAlephPin}: the library never sees a key, and
440
+ * `pending` is what Aleph says before it has checked the signature and the
441
+ * ownership — follow it with {@link waitForMessage}. A FORGET that names a
442
+ * message of another account is `rejected` there.
443
+ *
444
+ * @param {object} options
445
+ * @param {string} options.sender
446
+ * @param {string} [options.owner]
447
+ * @param {(address: string, message: string) => Promise<string>} options.sign - `personal_sign`
448
+ * @param {string} [options.apiHost]
449
+ * @param {string} [options.channel]
450
+ * @param {(payload: string) => Promise<string>} [options.hasher]
451
+ * @param {typeof fetch} [options.fetch]
452
+ * @param {() => number} [options.now]
453
+ * @returns {(hashes: string[], reason?: string) => Promise<{ itemHash: string, status: string }>}
454
+ */
455
+ export function createAlephForget(options = {}) {
456
+ const { sender, sign, owner } = options;
457
+ const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
458
+ const channel = options.channel || DEFAULT_ALEPH_CHANNEL;
459
+ const hasher = options.hasher || sha256Hex;
460
+ const doFetch = options.fetch || globalThis.fetch;
461
+ const now = options.now;
462
+
463
+ if (!sender)
464
+ throw new BackendError(
465
+ "INVALID_BACKEND",
466
+ "createAlephForget needs the wallet address as `sender`",
467
+ );
468
+ if (typeof sign !== "function")
469
+ throw new BackendError(
470
+ "INVALID_BACKEND",
471
+ "createAlephForget needs a `sign` function",
472
+ );
473
+ if (typeof doFetch !== "function")
474
+ throw new BackendError("INVALID_BACKEND", "createAlephForget needs fetch");
475
+
476
+ return async function forget(hashes, reason) {
477
+ const unsigned = await buildForgetMessage({
478
+ sender,
479
+ owner,
480
+ hashes,
481
+ reason,
482
+ channel,
483
+ hasher,
484
+ now: now?.(),
485
+ });
486
+ const signature = await sign(sender, signaturePayload(unsigned));
487
+ const message = {
488
+ ...unsigned,
489
+ signature: signature.startsWith("0x") ? signature : `0x${signature}`,
490
+ };
491
+ const response = await doFetch(`${apiHost}/api/v0/messages`, {
492
+ method: "POST",
493
+ headers: { "content-type": "application/json" },
494
+ body: JSON.stringify({ message, sync: true }),
495
+ });
496
+ if (!response.ok && response.status !== 202) {
497
+ const detail = await response.text().catch(() => "");
498
+ throw new BackendError(
499
+ "UNSUPPORTED",
500
+ `Aleph refused the FORGET message: ${response.status} ${detail.slice(0, 200)}`,
501
+ );
502
+ }
503
+ const body = await response.json().catch(() => ({}));
504
+ return {
505
+ itemHash: unsigned.item_hash,
506
+ status: body?.message_status ?? "pending",
507
+ };
508
+ };
509
+ }
510
+
511
+ /**
512
+ * Forget every STORE an account keeps on a channel — an application's whole
513
+ * archive — in batches, each followed until Aleph has decided.
514
+ *
515
+ * `keep` spares some: a predicate over the listed stores, e.g. the newest full
516
+ * backup. What was forgotten, what was kept and what Aleph rejected come back
517
+ * by item hash, so the caller can say so.
518
+ *
519
+ * @param {object} options
520
+ * @param {string} options.owner - the account the STOREs are for
521
+ * @param {string} options.channel - one channel; a FORGET across channels is not what anyone means
522
+ * @param {ReturnType<typeof createAlephForget>} options.forget - from {@link createAlephForget}, signing for that account
523
+ * @param {(store: { cid: string, itemHash: string, time: number }) => boolean} [options.keep]
524
+ * @param {string} [options.reason]
525
+ * @param {number} [options.batch=50] - item hashes per FORGET message
526
+ * @param {string} [options.apiHost]
527
+ * @param {typeof fetch} [options.fetch]
528
+ * @param {{ timeout?: number, interval?: number }} [options.settle] - for {@link waitForMessage}
529
+ * @param {(progress: { done: number, total: number }) => void} [options.onProgress]
530
+ * @returns {Promise<{ forgotten: string[], kept: string[], rejected: { itemHash: string, errorCode?: string }[] }>}
531
+ */
532
+ export async function forgetAlephStores(options = {}) {
533
+ const {
534
+ owner,
535
+ channel,
536
+ forget,
537
+ keep,
538
+ reason,
539
+ batch = 50,
540
+ apiHost,
541
+ settle = {},
542
+ onProgress,
543
+ } = options;
544
+ if (!owner)
545
+ throw new BackendError(
546
+ "INVALID_BACKEND",
547
+ "forgetAlephStores needs the account's address as `owner`",
548
+ );
549
+ if (!channel)
550
+ throw new BackendError(
551
+ "INVALID_BACKEND",
552
+ "forgetAlephStores needs a `channel`",
553
+ );
554
+ if (typeof forget !== "function")
555
+ throw new BackendError(
556
+ "INVALID_BACKEND",
557
+ "forgetAlephStores needs `forget` from createAlephForget",
558
+ );
559
+ const doFetch = options.fetch;
560
+
561
+ /** @type {{ cid: string, itemHash: string, time: number }[]} */
562
+ const all = [];
563
+ for (let page = 1; ; page++) {
564
+ const { stores } = await listAlephStores({
565
+ owner,
566
+ channel,
567
+ apiHost,
568
+ fetch: doFetch,
569
+ pagination: 100,
570
+ page,
571
+ });
572
+ all.push(...stores);
573
+ if (stores.length < 100) break;
574
+ }
575
+ const kept = all
576
+ .filter((store) => keep?.(store))
577
+ .map((store) => store.itemHash);
578
+ const targets = all
579
+ .filter((store) => !kept.includes(store.itemHash))
580
+ .map((store) => store.itemHash);
581
+
582
+ const forgotten = [];
583
+ const rejected = [];
584
+ for (let i = 0; i < targets.length; i += batch) {
585
+ const hashes = targets.slice(i, i + batch);
586
+ const sent = await forget(hashes, reason);
587
+ const final =
588
+ sent.status === "pending"
589
+ ? await waitForMessage(sent.itemHash, {
590
+ apiHost,
591
+ fetch: doFetch,
592
+ ...settle,
593
+ })
594
+ : sent;
595
+ if (final.status === "rejected") {
596
+ rejected.push(
597
+ ...hashes.map((itemHash) => ({
598
+ itemHash,
599
+ ...(final.errorCode ? { errorCode: final.errorCode } : {}),
600
+ })),
601
+ );
602
+ } else {
603
+ forgotten.push(...hashes);
604
+ }
605
+ onProgress?.({
606
+ done: Math.min(i + batch, targets.length),
607
+ total: targets.length,
608
+ });
609
+ }
610
+ return { forgotten, kept, rejected };
332
611
  }
333
612
 
334
613
  /** The reserved channel and aggregate key Aleph keeps permissions in. */
@@ -359,10 +638,25 @@ export const SECURITY = "security";
359
638
  * @param {number} [args.now] - seconds
360
639
  * @param {(payload: string) => Promise<string>} [args.hasher]
361
640
  */
362
- export async function buildAuthorizationMessage({ owner, authorizations, now, hasher = sha256Hex }) {
363
- if (!owner) throw new BackendError("INVALID_BACKEND", "an authorization needs the owner's address");
364
- if (!Array.isArray(authorizations) || authorizations.some((a) => typeof a?.address !== "string" || !a.address)) {
365
- throw new BackendError("INVALID_BACKEND", "every authorization needs the delegate's address");
641
+ export async function buildAuthorizationMessage({
642
+ owner,
643
+ authorizations,
644
+ now,
645
+ hasher = sha256Hex,
646
+ }) {
647
+ if (!owner)
648
+ throw new BackendError(
649
+ "INVALID_BACKEND",
650
+ "an authorization needs the owner's address",
651
+ );
652
+ if (
653
+ !Array.isArray(authorizations) ||
654
+ authorizations.some((a) => typeof a?.address !== "string" || !a.address)
655
+ ) {
656
+ throw new BackendError(
657
+ "INVALID_BACKEND",
658
+ "every authorization needs the delegate's address",
659
+ );
366
660
  }
367
661
  const time = now ?? Date.now() / 1000;
368
662
  const item_content = JSON.stringify({
@@ -413,18 +707,35 @@ export function createAlephAuthorizer(options = {}) {
413
707
  const apiHost = options.apiHost || DEFAULT_ALEPH_API_HOST;
414
708
  const hasher = options.hasher || sha256Hex;
415
709
  const doFetch = options.fetch || globalThis.fetch;
416
- if (!owner) throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs the owner's address");
417
- if (typeof sign !== "function") throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs a `sign` function");
418
- if (typeof doFetch !== "function") throw new BackendError("INVALID_BACKEND", "createAlephAuthorizer needs fetch");
710
+ if (!owner)
711
+ throw new BackendError(
712
+ "INVALID_BACKEND",
713
+ "createAlephAuthorizer needs the owner's address",
714
+ );
715
+ if (typeof sign !== "function")
716
+ throw new BackendError(
717
+ "INVALID_BACKEND",
718
+ "createAlephAuthorizer needs a `sign` function",
719
+ );
720
+ if (typeof doFetch !== "function")
721
+ throw new BackendError(
722
+ "INVALID_BACKEND",
723
+ "createAlephAuthorizer needs fetch",
724
+ );
419
725
 
420
726
  const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
421
727
 
422
728
  /** @returns {Promise<AlephAuthorization[]>} */
423
729
  async function read() {
424
- const response = await doFetch(`${apiHost}/api/v0/aggregates/${owner}.json?keys=${SECURITY}`);
730
+ const response = await doFetch(
731
+ `${apiHost}/api/v0/aggregates/${owner}.json?keys=${SECURITY}`,
732
+ );
425
733
  if (response.status === 404) return [];
426
734
  if (!response.ok) {
427
- throw new BackendError("UNSUPPORTED", `Aleph did not answer the owner's permissions: ${response.status}`);
735
+ throw new BackendError(
736
+ "UNSUPPORTED",
737
+ `Aleph did not answer the owner's permissions: ${response.status}`,
738
+ );
428
739
  }
429
740
  const body = await response.json().catch(() => ({}));
430
741
  const list = body?.data?.[SECURITY]?.authorizations;
@@ -433,22 +744,37 @@ export function createAlephAuthorizer(options = {}) {
433
744
 
434
745
  /** @param {AlephAuthorization[]} authorizations */
435
746
  async function write(authorizations) {
436
- const unsigned = await buildAuthorizationMessage({ owner, authorizations, hasher, now: options.now?.() });
747
+ const unsigned = await buildAuthorizationMessage({
748
+ owner,
749
+ authorizations,
750
+ hasher,
751
+ now: options.now?.(),
752
+ });
437
753
  const signature = await sign(owner, signaturePayload(unsigned));
438
754
  const response = await doFetch(`${apiHost}/api/v0/messages`, {
439
755
  method: "POST",
440
756
  headers: { "content-type": "application/json" },
441
757
  body: JSON.stringify({
442
- message: { ...unsigned, signature: signature.startsWith("0x") ? signature : `0x${signature}` },
758
+ message: {
759
+ ...unsigned,
760
+ signature: signature.startsWith("0x") ? signature : `0x${signature}`,
761
+ },
443
762
  sync: true,
444
763
  }),
445
764
  });
446
765
  if (!response.ok && response.status !== 202) {
447
766
  const detail = await response.text().catch(() => "");
448
- throw new BackendError("UNSUPPORTED", `Aleph refused the authorization: ${response.status} ${detail.slice(0, 200)}`);
767
+ throw new BackendError(
768
+ "UNSUPPORTED",
769
+ `Aleph refused the authorization: ${response.status} ${detail.slice(0, 200)}`,
770
+ );
449
771
  }
450
772
  const body = await response.json().catch(() => ({}));
451
- return { itemHash: unsigned.item_hash, status: body?.message_status ?? "pending", authorizations };
773
+ return {
774
+ itemHash: unsigned.item_hash,
775
+ status: body?.message_status ?? "pending",
776
+ authorizations,
777
+ };
452
778
  }
453
779
 
454
780
  return {
@@ -456,7 +782,9 @@ export function createAlephAuthorizer(options = {}) {
456
782
  write,
457
783
  /** Grant, or replace the grant of the same address. @param {AlephAuthorization} authorization */
458
784
  async authorize(authorization) {
459
- const others = (await read()).filter((a) => !same(a.address, authorization?.address));
785
+ const others = (await read()).filter(
786
+ (a) => !same(a.address, authorization?.address),
787
+ );
460
788
  return write([...others, authorization]);
461
789
  },
462
790
  /** Take one address's grant away; the others stay. @param {string} address */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@le-space/orbitdb-storage-bridge",
3
- "version": "0.18.0",
3
+ "version": "0.19.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/",