peerpigeon 0.0.7 → 0.1.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.
@@ -0,0 +1,1701 @@
1
+ import { EventEmitter } from './EventEmitter.js';
2
+ import DebugLogger from './DebugLogger.js';
3
+
4
+ // Dynamic import for unsea to handle both Node.js and browser environments
5
+ let unsea = null;
6
+
7
+ async function initializeUnsea() {
8
+ if (unsea) return unsea;
9
+
10
+ try {
11
+ // Detect environment - prioritize Node.js detection for tests
12
+ const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
13
+ const isBrowser = !isNode && typeof window !== 'undefined' && typeof document !== 'undefined';
14
+
15
+ if (isNode) {
16
+ // For Node.js environments (including tests), use npm package
17
+ unsea = await import('unsea');
18
+ console.log('✅ Loaded unsea from npm package (Node.js) for storage');
19
+ } else if (isBrowser) {
20
+ // For browser environments, try CDN sources
21
+ try {
22
+ unsea = await import('https://cdn.jsdelivr.net/npm/unsea@latest/+esm');
23
+ console.log('✅ Loaded unsea from jsDelivr CDN for storage');
24
+ } catch (jsDelivrError) {
25
+ console.warn('Failed to load from jsDelivr, trying unpkg:', jsDelivrError);
26
+ try {
27
+ unsea = await import('https://unpkg.com/unsea@latest/dist/unsea.esm.js');
28
+ console.log('✅ Loaded unsea from unpkg CDN for storage');
29
+ } catch (unpkgError) {
30
+ console.warn('Failed to load from unpkg, trying Skypack:', unpkgError);
31
+ unsea = await import('https://cdn.skypack.dev/unsea');
32
+ console.log('✅ Loaded unsea from Skypack CDN for storage');
33
+ }
34
+ }
35
+ } else {
36
+ throw new Error('Unknown environment - cannot load unsea');
37
+ }
38
+
39
+ if (!unsea) {
40
+ throw new Error('Unsea not found after loading');
41
+ }
42
+
43
+ return unsea;
44
+ } catch (error) {
45
+ console.error('Failed to load unsea for storage:', error);
46
+ throw error;
47
+ }
48
+ }
49
+
50
+ /**
51
+ * DistributedStorageManager - Optional storage layer for PeerPigeon mesh
52
+ *
53
+ * Features:
54
+ * - Encrypted storage using unsea directly
55
+ * - Optional public/private data visibility
56
+ * - Optional immutability with CRDT support for collaborative editing
57
+ * - Mutable layer for data originators
58
+ * - Integration with WebDHT for distributed storage
59
+ * - Space separation for preventing data overwrites (Private, Public, Frozen)
60
+ */
61
+ export class DistributedStorageManager extends EventEmitter {
62
+ constructor(mesh) {
63
+ super();
64
+ this.debug = DebugLogger.create('DistributedStorageManager');
65
+ this.mesh = mesh;
66
+ this.webDHT = mesh.webDHT;
67
+ this.cryptoManager = mesh.cryptoManager;
68
+
69
+ // Initialize unsea for encryption
70
+ this.unsea = null;
71
+ this.storageKeypair = null;
72
+ this.initializeCrypto();
73
+
74
+ // Storage configuration
75
+ this.config = {
76
+ encryptionEnabled: true,
77
+ defaultTTL: null, // No expiration by default
78
+ maxValueSize: 1024 * 1024, // 1MB default max size
79
+ enableCRDT: true,
80
+ conflictResolution: 'last-write-wins', // or 'crdt-merge'
81
+ spaceEnforcement: true // Enable space-based access control
82
+ };
83
+
84
+ // Storage spaces for data separation
85
+ this.spaces = {
86
+ PRIVATE: 'private', // Only owner can read/write, encrypted
87
+ PUBLIC: 'public', // Anyone can read, only owner can write
88
+ FROZEN: 'frozen' // Immutable once set, anyone can read
89
+ };
90
+
91
+ // Local storage for metadata and permissions
92
+ this.storageMetadata = new Map(); // keyId -> metadata
93
+ this.accessControl = new Map(); // keyId -> access control info
94
+ this.crdtStates = new Map(); // keyId -> CRDT state for collaborative data
95
+
96
+ // Track data ownership by space
97
+ this.ownedKeys = new Set(); // Keys owned by this peer
98
+ this.spaceOwnership = new Map(); // space:key -> owner mapping
99
+ this.keyToSpaceMapping = new Map(); // baseKey -> {space, fullKey} mapping for transparent access
100
+
101
+ // Track enabled state
102
+ this.enabled = true; // Enable by default
103
+
104
+ this.debug.log(`DistributedStorageManager initialized for peer ${this.mesh.peerId?.substring(0, 8)}...`);
105
+ }
106
+
107
+ /**
108
+ * Initialize unsea encryption for storage
109
+ * @private
110
+ */
111
+ async initializeCrypto() {
112
+ try {
113
+ this.unsea = await initializeUnsea();
114
+
115
+ // Generate a keypair for storage encryption
116
+ // Use the mesh's keypair if available, otherwise generate one
117
+ if (this.cryptoManager && this.cryptoManager.keypair) {
118
+ this.storageKeypair = this.cryptoManager.keypair;
119
+ } else {
120
+ this.storageKeypair = await this.unsea.generateRandomPair();
121
+ }
122
+
123
+ this.debug.log('📦 Storage encryption initialized with unsea');
124
+ } catch (error) {
125
+ this.debug.warn('📦 Failed to initialize storage encryption:', error);
126
+ // Disable encryption if unsea fails to load
127
+ this.config.encryptionEnabled = false;
128
+ }
129
+ }
130
+
131
+ /**
132
+ * Wait for crypto initialization to complete
133
+ * @returns {Promise<void>}
134
+ */
135
+ async waitForCrypto() {
136
+ if (this.unsea && this.storageKeypair) {
137
+ return;
138
+ }
139
+
140
+ // Wait up to 5 seconds for crypto to initialize
141
+ const timeout = 5000;
142
+ const start = Date.now();
143
+
144
+ while ((!this.unsea || !this.storageKeypair) && (Date.now() - start) < timeout) {
145
+ await new Promise(resolve => setTimeout(resolve, 100));
146
+ }
147
+ }
148
+
149
+ /**
150
+ * Resolve a key to its actual storage location across spaces
151
+ * @param {string} key - The storage key (can be plain or space-prefixed)
152
+ * @returns {Object} - {space, baseKey, fullKey, keyId}
153
+ */
154
+ async resolveKey(key) {
155
+ // If key already has space prefix, use it as-is
156
+ const keyInfo = this.parseStorageKey(key);
157
+
158
+ // If it's not a bare key (has space prefix), use it directly
159
+ if (key.includes(':')) {
160
+ const keyId = await this.webDHT.generateKeyId(keyInfo.fullKey);
161
+ return {
162
+ space: keyInfo.space,
163
+ baseKey: keyInfo.baseKey,
164
+ fullKey: keyInfo.fullKey,
165
+ keyId
166
+ };
167
+ }
168
+
169
+ // For bare keys, check if we have a mapping
170
+ const mapping = this.keyToSpaceMapping.get(keyInfo.baseKey);
171
+ if (mapping) {
172
+ const keyId = await this.webDHT.generateKeyId(mapping.fullKey);
173
+ return {
174
+ space: mapping.space,
175
+ baseKey: keyInfo.baseKey,
176
+ fullKey: mapping.fullKey,
177
+ keyId
178
+ };
179
+ }
180
+
181
+ // If no mapping exists, try to find it by checking each space
182
+ for (const space of Object.values(this.spaces)) {
183
+ const testFullKey = this.createSpacedKey(space, keyInfo.baseKey);
184
+ const testKeyId = await this.webDHT.generateKeyId(testFullKey);
185
+
186
+ // Check if we have metadata for this key in this space
187
+ if (this.storageMetadata.has(testKeyId) || this.spaceOwnership.has(testFullKey)) {
188
+ // Update the mapping for future use
189
+ this.keyToSpaceMapping.set(keyInfo.baseKey, { space, fullKey: testFullKey });
190
+ return {
191
+ space,
192
+ baseKey: keyInfo.baseKey,
193
+ fullKey: testFullKey,
194
+ keyId: testKeyId
195
+ };
196
+ }
197
+ }
198
+
199
+ // If still not found, default to the parsed key (likely private space)
200
+ const keyId = await this.webDHT.generateKeyId(keyInfo.fullKey);
201
+ return {
202
+ space: keyInfo.space,
203
+ baseKey: keyInfo.baseKey,
204
+ fullKey: keyInfo.fullKey,
205
+ keyId
206
+ };
207
+ }
208
+
209
+ /**
210
+ * Parse a storage key to extract space and base key
211
+ * @param {string} key - The storage key (can be plain or space-prefixed)
212
+ * @returns {Object} - {space, baseKey, fullKey}
213
+ */
214
+ parseStorageKey(key) {
215
+ // Check if key has space prefix (e.g., "private:user:123" or "public:config")
216
+ const spacePrefixes = Object.values(this.spaces);
217
+ for (const space of spacePrefixes) {
218
+ if (key.startsWith(`${space}:`)) {
219
+ return {
220
+ space,
221
+ baseKey: key.substring(space.length + 1),
222
+ fullKey: key
223
+ };
224
+ }
225
+ }
226
+
227
+ // Default to private space if no prefix specified
228
+ return {
229
+ space: this.spaces.PRIVATE,
230
+ baseKey: key,
231
+ fullKey: `${this.spaces.PRIVATE}:${key}`
232
+ };
233
+ }
234
+
235
+ /**
236
+ * Create a space-prefixed key
237
+ * @param {string} space - The storage space
238
+ * @param {string} baseKey - The base key
239
+ * @returns {string} - The full key with space prefix
240
+ */
241
+ createSpacedKey(space, baseKey) {
242
+ if (!Object.values(this.spaces).includes(space)) {
243
+ throw new Error(`Invalid storage space: ${space}. Must be one of: ${Object.values(this.spaces).join(', ')}`);
244
+ }
245
+ return `${space}:${baseKey}`;
246
+ }
247
+
248
+ /**
249
+ * Check if a peer can access a key in a specific space
250
+ * @param {string} space - The storage space
251
+ * @param {string} key - The storage key
252
+ * @param {string} peerId - The peer ID requesting access
253
+ * @param {string} operation - The operation (read, write)
254
+ * @returns {boolean} - Whether access is allowed
255
+ */
256
+ canAccessSpace(space, key, peerId, operation = 'read') {
257
+ if (!this.config.spaceEnforcement) {
258
+ return true; // Space enforcement disabled
259
+ }
260
+
261
+ const spaceKey = `${space}:${key}`;
262
+ const owner = this.spaceOwnership.get(spaceKey);
263
+
264
+ switch (space) {
265
+ case this.spaces.PRIVATE:
266
+ // Private: Only owner can read/write, or if no owner exists (initial write)
267
+ return !owner || owner === peerId;
268
+
269
+ case this.spaces.PUBLIC:
270
+ if (operation === 'read') {
271
+ return true; // Anyone can read public data
272
+ } else {
273
+ return !owner || owner === peerId; // Only owner can write, or initial write
274
+ }
275
+
276
+ case this.spaces.FROZEN:
277
+ if (operation === 'read') {
278
+ return true; // Anyone can read frozen data
279
+ } else {
280
+ // For frozen data, only the owner can write (both initial and updates)
281
+ return !owner || owner === peerId; // Only owner can write, or initial write
282
+ }
283
+
284
+ default:
285
+ return false;
286
+ }
287
+ }
288
+
289
+ /**
290
+ * Determine appropriate space and access control from options
291
+ * @param {Object} options - Storage options
292
+ * @returns {Object} - {space, isPublic, isImmutable}
293
+ */
294
+ determineSpaceFromOptions(options = {}) {
295
+ // Allow explicit space specification
296
+ if (options.space && Object.values(this.spaces).includes(options.space)) {
297
+ const space = options.space;
298
+ return {
299
+ space,
300
+ isPublic: space !== this.spaces.PRIVATE,
301
+ isImmutable: space === this.spaces.FROZEN
302
+ };
303
+ }
304
+
305
+ // Legacy compatibility - determine space from isPublic/isImmutable
306
+ if (options.isImmutable) {
307
+ return {
308
+ space: this.spaces.FROZEN,
309
+ isPublic: true,
310
+ isImmutable: true
311
+ };
312
+ } else if (options.isPublic) {
313
+ return {
314
+ space: this.spaces.PUBLIC,
315
+ isPublic: true,
316
+ isImmutable: false
317
+ };
318
+ } else {
319
+ return {
320
+ space: this.spaces.PRIVATE,
321
+ isPublic: false,
322
+ isImmutable: false
323
+ };
324
+ }
325
+ }
326
+
327
+ /**
328
+ * Find if a base key exists in a different space
329
+ * @param {string} baseKey - The base key to search for
330
+ * @param {string} excludeSpace - The space to exclude from search
331
+ * @returns {string|null} - The space where the key exists, or null if not found
332
+ */
333
+ findKeyInDifferentSpace(baseKey, excludeSpace) {
334
+ for (const space of Object.values(this.spaces)) {
335
+ if (space !== excludeSpace) {
336
+ const spacedKey = this.createSpacedKey(space, baseKey);
337
+ if (this.spaceOwnership.has(spacedKey)) {
338
+ return space;
339
+ }
340
+ }
341
+ }
342
+ return null;
343
+ }
344
+
345
+ /**
346
+ * Check if the current peer has read access to a key with space awareness
347
+ * @param {string} keyId - The key ID
348
+ * @param {Object} metadata - The metadata object
349
+ * @param {string} space - The storage space
350
+ * @returns {boolean} - Whether access is allowed
351
+ */
352
+ hasReadAccessWithSpace(keyId, metadata, space) {
353
+ const accessControl = this.accessControl.get(keyId);
354
+
355
+ if (!accessControl && metadata) {
356
+ // Create access control from metadata
357
+ this.accessControl.set(keyId, {
358
+ isPublic: metadata.isPublic,
359
+ owner: metadata.owner,
360
+ allowedPeers: new Set(metadata.allowedPeers || []),
361
+ isImmutable: metadata.isImmutable,
362
+ space: metadata.space || space
363
+ });
364
+ return this.hasReadAccessWithSpace(keyId, metadata, space);
365
+ }
366
+
367
+ if (!accessControl) {
368
+ return false;
369
+ }
370
+
371
+ // Owner always has access
372
+ if (accessControl.owner === this.mesh.peerId) {
373
+ return true;
374
+ }
375
+
376
+ // Space-based access control
377
+ switch (space) {
378
+ case this.spaces.PRIVATE:
379
+ // Private: only owner and specifically allowed peers
380
+ return accessControl.allowedPeers.has(this.mesh.peerId);
381
+
382
+ case this.spaces.PUBLIC:
383
+ case this.spaces.FROZEN:
384
+ // Public and frozen: anyone can read
385
+ return true;
386
+
387
+ default:
388
+ return false;
389
+ }
390
+ }
391
+
392
+ /**
393
+ * Store data with encryption and access control
394
+ * @param {string} key - The storage key
395
+ * @param {any} value - The value to store
396
+ * @param {Object} options - Storage options
397
+ * @param {string} options.space - Storage space ('private', 'public', 'frozen')
398
+ * @param {boolean} options.isPublic - Whether data is publicly readable (legacy, use space instead)
399
+ * @param {boolean} options.isImmutable - Whether data is immutable (legacy, use frozen space instead)
400
+ * @param {boolean} options.enableCRDT - Whether to enable CRDT for collaborative editing (default: false)
401
+ * @param {number} options.ttl - Time to live in milliseconds
402
+ * @param {Array<string>} options.allowedPeers - Specific peers allowed to read private data
403
+ * @returns {Promise<boolean>} Success status
404
+ */
405
+ async store(key, value, options = {}) {
406
+ if (!this.webDHT) {
407
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
408
+ }
409
+
410
+ // Wait for crypto initialization if encryption is enabled
411
+ if (this.config.encryptionEnabled) {
412
+ await this.waitForCrypto();
413
+ }
414
+
415
+ // Parse key and determine storage space
416
+ const keyInfo = this.parseStorageKey(key);
417
+ const spaceConfig = this.determineSpaceFromOptions(options);
418
+
419
+ // Use explicit space from options if provided, otherwise use parsed space
420
+ const space = options.space || spaceConfig.space;
421
+ const fullKey = keyInfo.space === space ? keyInfo.fullKey : this.createSpacedKey(space, keyInfo.baseKey);
422
+ const baseKey = keyInfo.baseKey;
423
+
424
+ // Check space access permissions
425
+ if (!this.canAccessSpace(space, baseKey, this.mesh.peerId, 'write')) {
426
+ throw new Error(`Write access denied for space "${space}" and key "${baseKey}"`);
427
+ }
428
+
429
+ // Check if key already exists in a different space
430
+ if (this.config.spaceEnforcement) {
431
+ const existingSpaceKey = this.findKeyInDifferentSpace(baseKey, space);
432
+ if (existingSpaceKey) {
433
+ throw new Error(`Key "${baseKey}" already exists in space "${existingSpaceKey}" - cannot store in "${space}" space`);
434
+ }
435
+ }
436
+
437
+ const keyId = await this.webDHT.generateKeyId(fullKey);
438
+ const timestamp = Date.now();
439
+ this.debug.log(`📦 Storing key: ${fullKey}, keyId: ${keyId.substring(0, 8)}...`);
440
+
441
+ // Validate value size
442
+ const serializedValue = JSON.stringify(value);
443
+ if (serializedValue.length > this.config.maxValueSize) {
444
+ throw new Error(`Value size exceeds maximum allowed size of ${this.config.maxValueSize} bytes`);
445
+ }
446
+
447
+ // Create storage metadata with space information
448
+ const metadata = {
449
+ key: fullKey,
450
+ baseKey,
451
+ space,
452
+ keyId,
453
+ owner: this.mesh.peerId,
454
+ isPublic: spaceConfig.isPublic,
455
+ isImmutable: spaceConfig.isImmutable,
456
+ enableCRDT: options.enableCRDT || false,
457
+ allowedPeers: options.allowedPeers || [],
458
+ createdAt: timestamp,
459
+ updatedAt: timestamp,
460
+ version: 1,
461
+ ttl: options.ttl || this.config.defaultTTL
462
+ };
463
+
464
+ // Store metadata locally
465
+ this.storageMetadata.set(keyId, metadata);
466
+ this.ownedKeys.add(keyId);
467
+
468
+ // Track space ownership
469
+ this.spaceOwnership.set(fullKey, this.mesh.peerId);
470
+
471
+ // Track base key to space mapping for transparent access
472
+ this.keyToSpaceMapping.set(baseKey, { space, fullKey });
473
+
474
+ // Set up access control
475
+ this.accessControl.set(keyId, {
476
+ isPublic: metadata.isPublic,
477
+ owner: metadata.owner,
478
+ allowedPeers: new Set(metadata.allowedPeers),
479
+ isImmutable: metadata.isImmutable,
480
+ space
481
+ });
482
+
483
+ // Initialize CRDT state if enabled
484
+ if (metadata.enableCRDT) {
485
+ this.crdtStates.set(keyId, {
486
+ vectorClock: { [this.mesh.peerId]: 1 },
487
+ operations: [],
488
+ lastMerged: timestamp
489
+ });
490
+ }
491
+
492
+ // Prepare the storage payload
493
+ let storagePayload = {
494
+ value,
495
+ metadata,
496
+ encrypted: false
497
+ };
498
+
499
+ // Only encrypt private space data
500
+ if (space === this.spaces.PRIVATE && this.config.encryptionEnabled && this.unsea && this.storageKeypair) {
501
+ try {
502
+ // For private data, encrypt with the owner's keypair so only the owner can decrypt
503
+ const encryptedValue = await this.unsea.encryptMessageWithMeta(serializedValue, this.storageKeypair);
504
+ storagePayload = {
505
+ value: encryptedValue,
506
+ metadata,
507
+ encrypted: true,
508
+ encryptedBy: this.mesh.peerId // Track who encrypted it
509
+ };
510
+ this.debug.log(`📦 Encrypted private space storage data for key: ${fullKey} (owner-only access)`);
511
+ } catch (error) {
512
+ this.debug.warn(`Failed to encrypt private space storage data for key ${fullKey}:`, error);
513
+ // Fall back to unencrypted storage if encryption fails
514
+ }
515
+ } else {
516
+ this.debug.log(`📦 Storing ${space} space data for key: ${fullKey}`);
517
+ }
518
+
519
+ // Store in WebDHT with space prefix
520
+ try {
521
+ this.debug.log(`📦 Storing payload for key ${fullKey}:`, {
522
+ hasValue: !!storagePayload.value,
523
+ hasMetadata: !!storagePayload.metadata,
524
+ encrypted: storagePayload.encrypted,
525
+ space
526
+ });
527
+
528
+ await this.webDHT.put(`storage:${fullKey}`, storagePayload, {
529
+ ttl: metadata.ttl
530
+ });
531
+
532
+ this.debug.log(`📦 Stored ${space} space data for key: ${fullKey}`);
533
+
534
+ // Emit storage event
535
+ this.emit('dataStored', {
536
+ key: fullKey,
537
+ baseKey,
538
+ space,
539
+ keyId,
540
+ isPublic: metadata.isPublic,
541
+ isImmutable: metadata.isImmutable,
542
+ enableCRDT: metadata.enableCRDT
543
+ });
544
+
545
+ return true;
546
+ } catch (error) {
547
+ this.debug.error(`Failed to store data for key ${fullKey}:`, error);
548
+ // Clean up local metadata on failure
549
+ this.storageMetadata.delete(keyId);
550
+ this.ownedKeys.delete(keyId);
551
+ this.accessControl.delete(keyId);
552
+ this.crdtStates.delete(keyId);
553
+ this.spaceOwnership.delete(fullKey);
554
+ this.keyToSpaceMapping.delete(baseKey);
555
+ throw error;
556
+ }
557
+ }
558
+
559
+ /**
560
+ * Retrieve data with access control and decryption
561
+ * @param {string} key - The storage key
562
+ * @param {Object} options - Retrieval options
563
+ * @param {boolean} options.forceRefresh - Force refresh from network
564
+ * @returns {Promise<any>} The stored value or null if not accessible
565
+ */
566
+ async retrieve(key, options = {}) {
567
+ if (!this.webDHT) {
568
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
569
+ }
570
+
571
+ // Wait for crypto initialization if encryption is enabled
572
+ if (this.config.encryptionEnabled) {
573
+ await this.waitForCrypto();
574
+ }
575
+
576
+ // Resolve the key to its actual storage location
577
+ const resolved = await this.resolveKey(key);
578
+ const { space, baseKey, fullKey, keyId } = resolved;
579
+
580
+ // Check space access permissions
581
+ if (!this.canAccessSpace(space, baseKey, this.mesh.peerId, 'read')) {
582
+ this.debug.warn(`📦 Access denied for space "${space}" and key "${baseKey}"`);
583
+ return null;
584
+ }
585
+
586
+ this.debug.log(`📦 Retrieving key: ${fullKey}, keyId: ${keyId.substring(0, 8)}...`);
587
+
588
+ try {
589
+ // Get data from WebDHT
590
+ this.debug.log(`📦 Attempting to retrieve data for key: ${fullKey}`);
591
+ const storagePayload = await this.webDHT.get(`storage:${fullKey}`, {
592
+ forceRefresh: options.forceRefresh
593
+ });
594
+
595
+ this.debug.log(`📦 Retrieved payload for key ${fullKey}:`, {
596
+ payloadExists: !!storagePayload,
597
+ payloadType: typeof storagePayload,
598
+ space,
599
+ keys: storagePayload ? Object.keys(storagePayload) : 'none'
600
+ });
601
+
602
+ if (!storagePayload || typeof storagePayload !== 'object') {
603
+ this.debug.log(`📦 No data found for key: ${fullKey}`);
604
+ return null;
605
+ }
606
+
607
+ // Debug: Log the raw payload structure
608
+ this.debug.log('📦 Raw payload structure:', JSON.stringify(storagePayload, null, 2));
609
+
610
+ // Safely destructure the payload with detailed logging
611
+ const value = storagePayload.value;
612
+ const metadata = storagePayload.metadata;
613
+ const encrypted = storagePayload.encrypted || false;
614
+ const encryptedBy = storagePayload.encryptedBy;
615
+
616
+ this.debug.log('📦 Payload components:', {
617
+ hasValue: value !== undefined,
618
+ valueType: typeof value,
619
+ hasMetadata: metadata !== undefined,
620
+ metadataType: typeof metadata,
621
+ encrypted,
622
+ space: metadata?.space || 'unknown',
623
+ encryptedBy: encryptedBy?.substring(0, 8) + '...' || 'unknown'
624
+ });
625
+
626
+ if (!metadata) {
627
+ this.debug.warn(`📦 Invalid storage payload for key ${fullKey}: missing metadata`);
628
+ return null;
629
+ }
630
+
631
+ // Verify space consistency
632
+ if (metadata.space && metadata.space !== space) {
633
+ this.debug.warn(`📦 Space mismatch for key ${fullKey}: expected ${space}, got ${metadata.space}`);
634
+ return null;
635
+ }
636
+
637
+ // Check access permissions using space-aware logic
638
+ if (!this.hasReadAccessWithSpace(keyId, metadata, space)) {
639
+ this.debug.warn(`📦 Access denied for key: ${fullKey} in space: ${space}`);
640
+ return null;
641
+ }
642
+
643
+ // Decrypt if necessary
644
+ let finalValue = value;
645
+ if (encrypted && this.unsea && this.storageKeypair) {
646
+ // Only allow decryption if this peer is the owner (encrypted the data)
647
+ if (encryptedBy && encryptedBy !== this.mesh.peerId) {
648
+ this.debug.warn(`📦 Cannot decrypt data for key ${key}: encrypted by different peer (${encryptedBy.substring(0, 8)}...), current peer: ${this.mesh.peerId.substring(0, 8)}...`);
649
+ // For private data encrypted by another peer, deny access
650
+ if (!metadata.isPublic) {
651
+ this.debug.warn(`Access denied for key: ${key} - private data encrypted by different peer`);
652
+ return null;
653
+ }
654
+ }
655
+
656
+ try {
657
+ const decryptedValue = await this.unsea.decryptMessageWithMeta(value, this.storageKeypair.epriv);
658
+ finalValue = JSON.parse(decryptedValue);
659
+ this.debug.log(`🔓 Decrypted storage data for key: ${key}`);
660
+ } catch (error) {
661
+ this.debug.error(`Failed to decrypt data for key ${key}:`, error);
662
+ // If this is private data and decryption fails, deny access
663
+ if (!metadata.isPublic) {
664
+ return null;
665
+ }
666
+ // For public data, if decryption fails, try to use the raw value
667
+ this.debug.warn(`📦 Using raw value for public key ${key} due to decryption failure`);
668
+ finalValue = value;
669
+ }
670
+ }
671
+
672
+ // Update local metadata if we don't have it
673
+ if (!this.storageMetadata.has(keyId)) {
674
+ this.storageMetadata.set(keyId, metadata);
675
+ this.accessControl.set(keyId, {
676
+ isPublic: metadata.isPublic,
677
+ owner: metadata.owner,
678
+ allowedPeers: new Set(metadata.allowedPeers),
679
+ isImmutable: metadata.isImmutable,
680
+ space: metadata.space || space
681
+ });
682
+
683
+ // Track space ownership from retrieved metadata
684
+ if (metadata.owner && !this.spaceOwnership.has(fullKey)) {
685
+ this.spaceOwnership.set(fullKey, metadata.owner);
686
+ }
687
+
688
+ // Update key mapping for future transparent access
689
+ if (!key.includes(':')) {
690
+ this.keyToSpaceMapping.set(baseKey, { space, fullKey });
691
+ }
692
+ }
693
+
694
+ this.debug.log(`📦 Retrieved ${space} space data for key: ${fullKey}`);
695
+
696
+ // Emit retrieval event
697
+ this.emit('dataRetrieved', {
698
+ key: fullKey,
699
+ baseKey,
700
+ space,
701
+ keyId,
702
+ isPublic: metadata.isPublic,
703
+ owner: metadata.owner
704
+ });
705
+
706
+ return finalValue;
707
+ } catch (error) {
708
+ this.debug.error(`Failed to retrieve data for key ${key}:`, error);
709
+ return null;
710
+ }
711
+ }
712
+
713
+ /**
714
+ * Update existing data (only allowed for owners or if mutable)
715
+ * @param {string} key - The storage key
716
+ * @param {any} newValue - The new value
717
+ * @param {Object} options - Update options
718
+ * @param {boolean} options.forceCRDTMerge - Force CRDT merge even if not owner
719
+ * @returns {Promise<boolean>} Success status
720
+ */
721
+ async update(key, newValue, options = {}) {
722
+ if (!this.webDHT) {
723
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
724
+ }
725
+
726
+ // Resolve the key to its actual storage location
727
+ const resolved = await this.resolveKey(key);
728
+ const { fullKey, keyId } = resolved;
729
+ const timestamp = Date.now();
730
+
731
+ // Check if we have access to update
732
+ let accessControl = this.accessControl.get(keyId);
733
+ let metadata = this.storageMetadata.get(keyId);
734
+
735
+ if (!accessControl || !metadata) {
736
+ // Try to retrieve metadata first
737
+ const existingData = await this.retrieve(fullKey);
738
+ if (!existingData) {
739
+ throw new Error(`Key ${key} does not exist or is not accessible`);
740
+ }
741
+
742
+ // Check if metadata is now available after retrieve
743
+ const updatedAccessControl = this.accessControl.get(keyId);
744
+ const updatedMetadata = this.storageMetadata.get(keyId);
745
+
746
+ if (!updatedAccessControl || !updatedMetadata) {
747
+ throw new Error(`Key ${key} metadata could not be loaded - unable to update`);
748
+ }
749
+
750
+ // Update local references and continue with update logic
751
+ accessControl = updatedAccessControl;
752
+ metadata = updatedMetadata;
753
+ }
754
+
755
+ const isOwner = accessControl.owner === this.mesh.peerId;
756
+ const canUpdate = isOwner || (!accessControl.isImmutable) || (metadata.enableCRDT && options.forceCRDTMerge);
757
+
758
+ if (!canUpdate) {
759
+ throw new Error(`Update not allowed for key ${key}: immutable data and not owner`);
760
+ }
761
+
762
+ // Handle CRDT merge if enabled
763
+ if (metadata.enableCRDT && !isOwner) {
764
+ return this.applyCRDTUpdate(key, keyId, newValue, options);
765
+ }
766
+
767
+ // Update metadata
768
+ metadata.updatedAt = timestamp;
769
+ metadata.version += 1;
770
+
771
+ // Prepare storage payload
772
+ let storagePayload = {
773
+ value: newValue,
774
+ metadata,
775
+ encrypted: false
776
+ };
777
+
778
+ // Encrypt if not public and crypto is available
779
+ if (!metadata.isPublic && this.config.encryptionEnabled && this.unsea && this.storageKeypair) {
780
+ try {
781
+ const serializedValue = JSON.stringify(newValue);
782
+ const encryptedValue = await this.unsea.encryptMessageWithMeta(serializedValue, this.storageKeypair);
783
+ storagePayload = {
784
+ value: encryptedValue,
785
+ metadata,
786
+ encrypted: true,
787
+ encryptedBy: this.mesh.peerId // Track who encrypted it
788
+ };
789
+ this.debug.log(`📦 Encrypted updated storage data for key: ${key}`);
790
+ } catch (error) {
791
+ this.debug.warn(`Failed to encrypt updated storage data for key ${key}:`, error);
792
+ }
793
+ }
794
+
795
+ try {
796
+ // Use WebDHT update to notify all replicas and subscribers
797
+ await this.webDHT.update(`storage:${fullKey}`, storagePayload, {
798
+ ttl: metadata.ttl
799
+ });
800
+
801
+ // Update local metadata
802
+ this.storageMetadata.set(keyId, metadata);
803
+
804
+ this.debug.log(`📦 Updated ${metadata.isPublic ? 'public' : 'private'} data for key: ${fullKey}`);
805
+
806
+ // Emit update event
807
+ this.emit('dataUpdated', {
808
+ key: fullKey,
809
+ keyId,
810
+ isPublic: metadata.isPublic,
811
+ version: metadata.version,
812
+ isOwner
813
+ });
814
+
815
+ return true;
816
+ } catch (error) {
817
+ this.debug.error(`Failed to update data for key ${fullKey}:`, error);
818
+ throw error;
819
+ }
820
+ }
821
+
822
+ /**
823
+ * Apply CRDT-based update for collaborative editing
824
+ * @private
825
+ */
826
+ async applyCRDTUpdate(key, keyId, operation, options = {}) {
827
+ const crdtState = this.crdtStates.get(keyId);
828
+ const metadata = this.storageMetadata.get(keyId);
829
+
830
+ if (!crdtState || !metadata) {
831
+ throw new Error(`CRDT state not found for key ${key}`);
832
+ }
833
+
834
+ // Increment vector clock for this peer
835
+ const currentClock = crdtState.vectorClock[this.mesh.peerId] || 0;
836
+ crdtState.vectorClock[this.mesh.peerId] = currentClock + 1;
837
+
838
+ // Add operation to CRDT state
839
+ const crdtOperation = {
840
+ peerId: this.mesh.peerId,
841
+ timestamp: Date.now(),
842
+ vectorClock: { ...crdtState.vectorClock },
843
+ operation,
844
+ type: options.operationType || 'replace'
845
+ };
846
+
847
+ crdtState.operations.push(crdtOperation);
848
+ crdtState.lastMerged = Date.now();
849
+
850
+ // Apply CRDT merge logic (simplified last-write-wins for now)
851
+ const mergedValue = this.mergeCRDTOperations(crdtState.operations);
852
+
853
+ // Update the stored value
854
+ return this.update(key, mergedValue, { ...options, forceCRDTMerge: false });
855
+ }
856
+
857
+ /**
858
+ * Simple CRDT merge implementation (can be extended for more sophisticated CRDTs)
859
+ * @private
860
+ */
861
+ mergeCRDTOperations(operations) {
862
+ // Sort operations by timestamp and apply in order
863
+ const sortedOps = operations.sort((a, b) => a.timestamp - b.timestamp);
864
+
865
+ let result = null;
866
+ for (const op of sortedOps) {
867
+ switch (op.type) {
868
+ case 'replace':
869
+ result = op.operation;
870
+ break;
871
+ case 'merge':
872
+ if (result && typeof result === 'object' && typeof op.operation === 'object') {
873
+ result = { ...result, ...op.operation };
874
+ } else {
875
+ result = op.operation;
876
+ }
877
+ break;
878
+ default:
879
+ result = op.operation;
880
+ }
881
+ }
882
+
883
+ return result;
884
+ }
885
+
886
+ /**
887
+ * Delete data (only allowed for owners)
888
+ * @param {string} key - The storage key
889
+ * @returns {Promise<boolean>} Success status
890
+ */
891
+ async delete(key) {
892
+ if (!this.webDHT) {
893
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
894
+ }
895
+
896
+ // Resolve the key to its actual storage location
897
+ const resolved = await this.resolveKey(key);
898
+ const { baseKey, fullKey, keyId } = resolved;
899
+
900
+ const accessControl = this.accessControl.get(keyId);
901
+
902
+ if (!accessControl || accessControl.owner !== this.mesh.peerId) {
903
+ throw new Error(`Delete not allowed for key ${key}: not owner`);
904
+ }
905
+
906
+ try {
907
+ // Create a tombstone entry to mark as deleted
908
+ const tombstone = {
909
+ deleted: true,
910
+ deletedAt: Date.now(),
911
+ deletedBy: this.mesh.peerId
912
+ };
913
+
914
+ await this.webDHT.update(`storage:${fullKey}`, tombstone);
915
+
916
+ // Clean up local state
917
+ this.storageMetadata.delete(keyId);
918
+ this.ownedKeys.delete(keyId);
919
+ this.accessControl.delete(keyId);
920
+ this.crdtStates.delete(keyId);
921
+
922
+ // Clean up space ownership tracking and key mapping
923
+ this.spaceOwnership.delete(fullKey);
924
+ this.keyToSpaceMapping.delete(baseKey);
925
+
926
+ this.debug.log(`📦 Deleted data for key: ${fullKey}`);
927
+
928
+ // Emit deletion event
929
+ this.emit('dataDeleted', { key: fullKey, keyId });
930
+
931
+ return true;
932
+ } catch (error) {
933
+ this.debug.error(`Failed to delete data for key ${fullKey}:`, error);
934
+ throw error;
935
+ }
936
+ }
937
+
938
+ /**
939
+ * Subscribe to changes for a storage key
940
+ * @param {string} key - The storage key
941
+ * @returns {Promise<any>} Current value or null
942
+ */
943
+ async subscribe(key) {
944
+ if (!this.webDHT) {
945
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
946
+ }
947
+
948
+ // Subscribe to the WebDHT key
949
+ const currentValue = await this.webDHT.subscribe(`storage:${key}`);
950
+
951
+ this.debug.log(`📦 Subscribed to storage key: ${key}`);
952
+
953
+ return currentValue;
954
+ }
955
+
956
+ /**
957
+ * Unsubscribe from changes for a storage key
958
+ * @param {string} key - The storage key
959
+ */
960
+ async unsubscribe(key) {
961
+ if (!this.webDHT) {
962
+ return;
963
+ }
964
+
965
+ await this.webDHT.unsubscribe(`storage:${key}`);
966
+ this.debug.log(`📦 Unsubscribed from storage key: ${key}`);
967
+ }
968
+
969
+ /**
970
+ * Check if the current peer has read access to a key
971
+ * @private
972
+ */
973
+ hasReadAccess(keyId, metadata) {
974
+ const accessControl = this.accessControl.get(keyId);
975
+
976
+ if (!accessControl && metadata) {
977
+ // Create access control from metadata
978
+ this.accessControl.set(keyId, {
979
+ isPublic: metadata.isPublic,
980
+ owner: metadata.owner,
981
+ allowedPeers: new Set(metadata.allowedPeers || []),
982
+ isImmutable: metadata.isImmutable
983
+ });
984
+ return this.hasReadAccess(keyId, metadata);
985
+ }
986
+
987
+ if (!accessControl) {
988
+ return false;
989
+ }
990
+
991
+ // Owner always has access
992
+ if (accessControl.owner === this.mesh.peerId) {
993
+ return true;
994
+ }
995
+
996
+ // Public data is accessible to everyone
997
+ if (accessControl.isPublic) {
998
+ return true;
999
+ }
1000
+
1001
+ // Check if peer is in allowed list
1002
+ return accessControl.allowedPeers.has(this.mesh.peerId);
1003
+ }
1004
+
1005
+ /**
1006
+ * Grant access to a peer for a private key (only owner can do this)
1007
+ * @param {string} key - The storage key
1008
+ * @param {string} peerId - The peer to grant access to
1009
+ * @returns {Promise<boolean>} Success status
1010
+ */
1011
+ async grantAccess(key, peerId) {
1012
+ // Resolve the key to its actual storage location
1013
+ const resolved = await this.resolveKey(key);
1014
+ const { fullKey, keyId } = resolved;
1015
+
1016
+ const accessControl = this.accessControl.get(keyId);
1017
+ const metadata = this.storageMetadata.get(keyId);
1018
+
1019
+ if (!accessControl || !metadata || accessControl.owner !== this.mesh.peerId) {
1020
+ throw new Error(`Cannot grant access for key ${key}: not owner`);
1021
+ }
1022
+
1023
+ if (accessControl.isPublic) {
1024
+ throw new Error(`Cannot grant access for key ${key}: already public`);
1025
+ }
1026
+
1027
+ // Add peer to allowed list
1028
+ accessControl.allowedPeers.add(peerId);
1029
+ metadata.allowedPeers.push(peerId);
1030
+ metadata.updatedAt = Date.now();
1031
+
1032
+ // Update the stored metadata
1033
+ try {
1034
+ const currentPayload = await this.webDHT.get(`storage:${fullKey}`);
1035
+ if (currentPayload) {
1036
+ currentPayload.metadata = metadata;
1037
+ await this.webDHT.update(`storage:${fullKey}`, currentPayload);
1038
+ }
1039
+
1040
+ this.debug.log(`📦 Granted access to peer ${peerId.substring(0, 8)}... for key: ${fullKey}`);
1041
+
1042
+ // Emit access granted event
1043
+ this.emit('accessGranted', { key: fullKey, keyId, peerId });
1044
+
1045
+ return true;
1046
+ } catch (error) {
1047
+ // Rollback changes
1048
+ accessControl.allowedPeers.delete(peerId);
1049
+ metadata.allowedPeers = metadata.allowedPeers.filter(p => p !== peerId);
1050
+ throw error;
1051
+ }
1052
+ }
1053
+
1054
+ /**
1055
+ * Revoke access from a peer for a private key (only owner can do this)
1056
+ * @param {string} key - The storage key
1057
+ * @param {string} peerId - The peer to revoke access from
1058
+ * @returns {Promise<boolean>} Success status
1059
+ */
1060
+ async revokeAccess(key, peerId) {
1061
+ // Resolve the key to its actual storage location
1062
+ const resolved = await this.resolveKey(key);
1063
+ const { fullKey, keyId } = resolved;
1064
+
1065
+ const accessControl = this.accessControl.get(keyId);
1066
+ const metadata = this.storageMetadata.get(keyId);
1067
+
1068
+ if (!accessControl || !metadata || accessControl.owner !== this.mesh.peerId) {
1069
+ throw new Error(`Cannot revoke access for key ${key}: not owner`);
1070
+ }
1071
+
1072
+ // Remove peer from allowed list
1073
+ accessControl.allowedPeers.delete(peerId);
1074
+ metadata.allowedPeers = metadata.allowedPeers.filter(p => p !== peerId);
1075
+ metadata.updatedAt = Date.now();
1076
+
1077
+ // Update the stored metadata
1078
+ try {
1079
+ const currentPayload = await this.webDHT.get(`storage:${fullKey}`);
1080
+ if (currentPayload) {
1081
+ currentPayload.metadata = metadata;
1082
+ await this.webDHT.update(`storage:${fullKey}`, currentPayload);
1083
+ }
1084
+
1085
+ this.debug.log(`📦 Revoked access from peer ${peerId.substring(0, 8)}... for key: ${fullKey}`);
1086
+
1087
+ // Emit access revoked event
1088
+ this.emit('accessRevoked', { key: fullKey, keyId, peerId });
1089
+
1090
+ return true;
1091
+ } catch (error) {
1092
+ // Rollback changes
1093
+ accessControl.allowedPeers.add(peerId);
1094
+ metadata.allowedPeers.push(peerId);
1095
+ throw error;
1096
+ }
1097
+ }
1098
+
1099
+ /**
1100
+ * List all keys owned by this peer
1101
+ * @returns {Array<Object>} Array of owned key metadata
1102
+ */
1103
+ getOwnedKeys() {
1104
+ const ownedKeys = [];
1105
+ for (const keyId of this.ownedKeys) {
1106
+ const metadata = this.storageMetadata.get(keyId);
1107
+ if (metadata) {
1108
+ ownedKeys.push({
1109
+ key: metadata.key,
1110
+ keyId,
1111
+ isPublic: metadata.isPublic,
1112
+ isImmutable: metadata.isImmutable,
1113
+ enableCRDT: metadata.enableCRDT,
1114
+ createdAt: metadata.createdAt,
1115
+ updatedAt: metadata.updatedAt,
1116
+ version: metadata.version
1117
+ });
1118
+ }
1119
+ }
1120
+ return ownedKeys;
1121
+ }
1122
+
1123
+ /**
1124
+ * Get statistics about the storage manager
1125
+ * @returns {Promise<Object>} Storage statistics
1126
+ */
1127
+ async getStats() {
1128
+ let totalSize = 0;
1129
+ let itemCount = 0;
1130
+
1131
+ // Calculate sizes for owned keys
1132
+ for (const keyId of this.ownedKeys) {
1133
+ const metadata = this.storageMetadata.get(keyId);
1134
+ if (metadata) {
1135
+ try {
1136
+ const value = await this.retrieve(metadata.key);
1137
+ if (value !== null) {
1138
+ const serializedSize = JSON.stringify(value).length;
1139
+ totalSize += serializedSize;
1140
+ itemCount++;
1141
+ }
1142
+ } catch (error) {
1143
+ // Skip keys that can't be retrieved
1144
+ }
1145
+ }
1146
+ }
1147
+
1148
+ return {
1149
+ enabled: this.enabled,
1150
+ itemCount,
1151
+ totalSize,
1152
+ ownedKeys: this.ownedKeys.size,
1153
+ totalKeys: this.storageMetadata.size,
1154
+ crdtKeys: this.crdtStates.size,
1155
+ encryptionEnabled: this.config.encryptionEnabled && !!this.unsea && !!this.storageKeypair,
1156
+ maxValueSize: this.config.maxValueSize
1157
+ };
1158
+ }
1159
+
1160
+ /**
1161
+ * Clean up expired data and old CRDT operations
1162
+ */
1163
+ cleanup() {
1164
+ const now = Date.now();
1165
+
1166
+ // Clean up expired metadata
1167
+ for (const [keyId, metadata] of this.storageMetadata.entries()) {
1168
+ if (metadata.ttl && (metadata.createdAt + metadata.ttl) < now) {
1169
+ this.storageMetadata.delete(keyId);
1170
+ this.accessControl.delete(keyId);
1171
+ this.ownedKeys.delete(keyId);
1172
+ this.debug.log(`📦 Cleaned up expired metadata for key: ${metadata.key}`);
1173
+ }
1174
+ }
1175
+
1176
+ // Clean up old CRDT operations (keep last 100 operations per key)
1177
+ for (const [keyId, crdtState] of this.crdtStates.entries()) {
1178
+ if (crdtState.operations.length > 100) {
1179
+ crdtState.operations = crdtState.operations.slice(-100);
1180
+ this.debug.log(`📦 Cleaned up old CRDT operations for key: ${keyId.substring(0, 8)}...`);
1181
+ }
1182
+ }
1183
+ }
1184
+
1185
+ /**
1186
+ * Backup all owned data to a serializable format
1187
+ * @returns {Object} Backup data that can be restored later
1188
+ */
1189
+ async backup() {
1190
+ const backupData = {
1191
+ version: '1.0.0',
1192
+ timestamp: Date.now(),
1193
+ peerId: this.mesh.peerId,
1194
+ keys: []
1195
+ };
1196
+
1197
+ for (const keyId of this.ownedKeys) {
1198
+ const metadata = this.storageMetadata.get(keyId);
1199
+ if (metadata) {
1200
+ try {
1201
+ // Get the current value from storage
1202
+ const value = await this.retrieve(metadata.key);
1203
+ if (value !== null) {
1204
+ backupData.keys.push({
1205
+ key: metadata.key,
1206
+ value,
1207
+ metadata: {
1208
+ isPublic: metadata.isPublic,
1209
+ isImmutable: metadata.isImmutable,
1210
+ enableCRDT: metadata.enableCRDT,
1211
+ allowedPeers: metadata.allowedPeers,
1212
+ ttl: metadata.ttl
1213
+ }
1214
+ });
1215
+ }
1216
+ } catch (error) {
1217
+ this.debug.warn(`Failed to backup key ${metadata.key}:`, error);
1218
+ }
1219
+ }
1220
+ }
1221
+
1222
+ this.debug.log(`📦 Created backup with ${backupData.keys.length} keys`);
1223
+ return backupData;
1224
+ }
1225
+
1226
+ /**
1227
+ * Restore data from a backup
1228
+ * @param {Object} backupData - Backup data created by backup()
1229
+ * @param {Object} options - Restore options
1230
+ * @param {boolean} options.overwrite - Whether to overwrite existing keys (default: false)
1231
+ * @returns {Promise<Object>} Restore results
1232
+ */
1233
+ async restore(backupData, options = {}) {
1234
+ if (!backupData || !backupData.keys || !Array.isArray(backupData.keys)) {
1235
+ throw new Error('Invalid backup data format');
1236
+ }
1237
+
1238
+ const results = {
1239
+ restored: 0,
1240
+ skipped: 0,
1241
+ failed: 0,
1242
+ errors: []
1243
+ };
1244
+
1245
+ for (const keyData of backupData.keys) {
1246
+ try {
1247
+ const { key, value, metadata } = keyData;
1248
+
1249
+ // Check if key already exists
1250
+ const existing = await this.retrieve(key);
1251
+ if (existing !== null && !options.overwrite) {
1252
+ results.skipped++;
1253
+ continue;
1254
+ }
1255
+
1256
+ // Restore the key
1257
+ await this.store(key, value, metadata);
1258
+ results.restored++;
1259
+ } catch (error) {
1260
+ results.failed++;
1261
+ results.errors.push({
1262
+ key: keyData.key,
1263
+ error: error.message
1264
+ });
1265
+ this.debug.warn(`Failed to restore key ${keyData.key}:`, error);
1266
+ }
1267
+ }
1268
+
1269
+ this.debug.log(`📦 Restore complete: ${results.restored} restored, ${results.skipped} skipped, ${results.failed} failed`);
1270
+ return results;
1271
+ }
1272
+
1273
+ /**
1274
+ * List all accessible keys (owned + granted access)
1275
+ * @returns {Array<Object>} Array of accessible key metadata
1276
+ */
1277
+ async listAccessibleKeys() {
1278
+ const accessibleKeys = [];
1279
+
1280
+ // Add owned keys
1281
+ for (const keyId of this.ownedKeys) {
1282
+ const metadata = this.storageMetadata.get(keyId);
1283
+ if (metadata) {
1284
+ accessibleKeys.push({
1285
+ key: metadata.key,
1286
+ keyId,
1287
+ isPublic: metadata.isPublic,
1288
+ isImmutable: metadata.isImmutable,
1289
+ enableCRDT: metadata.enableCRDT,
1290
+ createdAt: metadata.createdAt,
1291
+ updatedAt: metadata.updatedAt,
1292
+ version: metadata.version,
1293
+ owned: true,
1294
+ accessible: true
1295
+ });
1296
+ }
1297
+ }
1298
+
1299
+ // Add keys we have access to but don't own
1300
+ for (const [keyId] of this.accessControl.entries()) {
1301
+ if (!this.ownedKeys.has(keyId) && this.hasReadAccess(keyId)) {
1302
+ const metadata = this.storageMetadata.get(keyId);
1303
+ if (metadata) {
1304
+ accessibleKeys.push({
1305
+ key: metadata.key,
1306
+ keyId,
1307
+ isPublic: metadata.isPublic,
1308
+ isImmutable: metadata.isImmutable,
1309
+ enableCRDT: metadata.enableCRDT,
1310
+ createdAt: metadata.createdAt,
1311
+ updatedAt: metadata.updatedAt,
1312
+ version: metadata.version,
1313
+ owned: false,
1314
+ accessible: true
1315
+ });
1316
+ }
1317
+ }
1318
+ }
1319
+
1320
+ return accessibleKeys;
1321
+ }
1322
+
1323
+ /**
1324
+ * Bulk store multiple key-value pairs
1325
+ * @param {Array<Object>} items - Array of {key, value, options} objects
1326
+ * @param {Object} globalOptions - Options to apply to all items
1327
+ * @returns {Promise<Object>} Results summary
1328
+ */
1329
+ async bulkStore(items, globalOptions = {}) {
1330
+ const results = {
1331
+ stored: 0,
1332
+ failed: 0,
1333
+ errors: []
1334
+ };
1335
+
1336
+ const storePromises = items.map(async (item) => {
1337
+ try {
1338
+ const options = { ...globalOptions, ...item.options };
1339
+ await this.store(item.key, item.value, options);
1340
+ results.stored++;
1341
+ } catch (error) {
1342
+ results.failed++;
1343
+ results.errors.push({
1344
+ key: item.key,
1345
+ error: error.message
1346
+ });
1347
+ }
1348
+ });
1349
+
1350
+ await Promise.allSettled(storePromises);
1351
+ this.debug.log(`📦 Bulk store complete: ${results.stored} stored, ${results.failed} failed`);
1352
+ return results;
1353
+ }
1354
+
1355
+ /**
1356
+ * Bulk retrieve multiple keys
1357
+ * @param {Array<string>} keys - Array of keys to retrieve
1358
+ * @param {Object} options - Retrieval options
1359
+ * @returns {Promise<Object>} Map of key -> value (null for inaccessible keys)
1360
+ */
1361
+ async bulkRetrieve(keys, options = {}) {
1362
+ const results = {};
1363
+
1364
+ const retrievePromises = keys.map(async (key) => {
1365
+ try {
1366
+ const value = await this.retrieve(key, options);
1367
+ results[key] = value;
1368
+ } catch (error) {
1369
+ this.debug.warn(`Failed to retrieve key ${key}:`, error);
1370
+ results[key] = null;
1371
+ }
1372
+ });
1373
+
1374
+ await Promise.allSettled(retrievePromises);
1375
+ return results;
1376
+ }
1377
+
1378
+ /**
1379
+ * Search for keys by pattern or metadata
1380
+ * @param {Object} criteria - Search criteria
1381
+ * @param {string} criteria.keyPattern - Regex pattern to match keys
1382
+ * @param {boolean} criteria.isPublic - Filter by public/private
1383
+ * @param {boolean} criteria.owned - Filter by ownership
1384
+ * @param {string} criteria.owner - Filter by specific owner
1385
+ * @returns {Array<Object>} Matching keys
1386
+ */
1387
+ searchKeys(criteria = {}) {
1388
+ const matches = [];
1389
+
1390
+ for (const [keyId, metadata] of this.storageMetadata.entries()) {
1391
+ let match = true;
1392
+
1393
+ // Check key pattern
1394
+ if (criteria.keyPattern) {
1395
+ const regex = new RegExp(criteria.keyPattern);
1396
+ if (!regex.test(metadata.key)) {
1397
+ match = false;
1398
+ }
1399
+ }
1400
+
1401
+ // Check public/private
1402
+ if (criteria.isPublic !== undefined && metadata.isPublic !== criteria.isPublic) {
1403
+ match = false;
1404
+ }
1405
+
1406
+ // Check ownership
1407
+ if (criteria.owned !== undefined) {
1408
+ const isOwned = this.ownedKeys.has(keyId);
1409
+ if (isOwned !== criteria.owned) {
1410
+ match = false;
1411
+ }
1412
+ }
1413
+
1414
+ // Check specific owner
1415
+ if (criteria.owner && metadata.owner !== criteria.owner) {
1416
+ match = false;
1417
+ }
1418
+
1419
+ if (match) {
1420
+ matches.push({
1421
+ key: metadata.key,
1422
+ keyId,
1423
+ isPublic: metadata.isPublic,
1424
+ isImmutable: metadata.isImmutable,
1425
+ enableCRDT: metadata.enableCRDT,
1426
+ owner: metadata.owner,
1427
+ createdAt: metadata.createdAt,
1428
+ updatedAt: metadata.updatedAt,
1429
+ version: metadata.version,
1430
+ owned: this.ownedKeys.has(keyId)
1431
+ });
1432
+ }
1433
+ }
1434
+
1435
+ return matches;
1436
+ }
1437
+
1438
+ /**
1439
+ * Watch for changes to multiple keys
1440
+ * @param {Array<string>} keys - Keys to watch
1441
+ * @param {Function} callback - Callback function for changes
1442
+ * @returns {Function} Unwatch function
1443
+ */
1444
+ async watchKeys(keys, callback) {
1445
+ const subscriptions = new Set();
1446
+
1447
+ // Subscribe to each key
1448
+ for (const key of keys) {
1449
+ try {
1450
+ await this.subscribe(key);
1451
+ subscriptions.add(key);
1452
+ } catch (error) {
1453
+ this.debug.warn(`Failed to subscribe to key ${key}:`, error);
1454
+ }
1455
+ }
1456
+
1457
+ // Set up event listener
1458
+ const eventHandler = (event) => {
1459
+ if (keys.includes(event.key)) {
1460
+ callback(event);
1461
+ }
1462
+ };
1463
+
1464
+ this.addEventListener('dataUpdated', eventHandler);
1465
+ this.addEventListener('dataDeleted', eventHandler);
1466
+
1467
+ // Return unwatch function
1468
+ return async () => {
1469
+ // Unsubscribe from keys
1470
+ for (const key of subscriptions) {
1471
+ try {
1472
+ await this.unsubscribe(key);
1473
+ } catch (error) {
1474
+ this.debug.warn(`Failed to unsubscribe from key ${key}:`, error);
1475
+ }
1476
+ }
1477
+
1478
+ // Remove event listeners
1479
+ this.removeEventListener('dataUpdated', eventHandler);
1480
+ this.removeEventListener('dataDeleted', eventHandler);
1481
+ };
1482
+ }
1483
+
1484
+ /**
1485
+ * Get detailed information about a key including access control
1486
+ * @param {string} key - The storage key
1487
+ * @returns {Promise<Object|null>} Key information or null if not found
1488
+ */
1489
+ async getKeyInfo(key) {
1490
+ // Resolve the key to its actual storage location
1491
+ const resolved = await this.resolveKey(key);
1492
+ const { fullKey, keyId } = resolved;
1493
+
1494
+ let metadata = this.storageMetadata.get(keyId);
1495
+
1496
+ // If metadata is not found locally, try to retrieve it from the network
1497
+ if (!metadata) {
1498
+ try {
1499
+ const existingData = await this.retrieve(fullKey);
1500
+ if (existingData !== null) {
1501
+ // Metadata should now be available after retrieve
1502
+ metadata = this.storageMetadata.get(keyId);
1503
+ }
1504
+ } catch (error) {
1505
+ this.debug.warn(`Failed to retrieve metadata for key ${key}:`, error);
1506
+ }
1507
+ }
1508
+
1509
+ if (!metadata) {
1510
+ return null;
1511
+ }
1512
+
1513
+ return {
1514
+ key: metadata.key,
1515
+ keyId,
1516
+ owner: metadata.owner,
1517
+ isPublic: metadata.isPublic,
1518
+ isImmutable: metadata.isImmutable,
1519
+ enableCRDT: metadata.enableCRDT,
1520
+ allowedPeers: metadata.allowedPeers,
1521
+ createdAt: metadata.createdAt,
1522
+ updatedAt: metadata.updatedAt,
1523
+ version: metadata.version,
1524
+ ttl: metadata.ttl,
1525
+ owned: this.ownedKeys.has(keyId),
1526
+ accessible: this.hasReadAccess(keyId, metadata),
1527
+ crdtEnabled: this.crdtStates.has(keyId)
1528
+ };
1529
+ }
1530
+
1531
+ /**
1532
+ * Enable the distributed storage layer
1533
+ * @returns {Promise<void>}
1534
+ */
1535
+ async enable() {
1536
+ if (!this.webDHT) {
1537
+ throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
1538
+ }
1539
+
1540
+ this.enabled = true;
1541
+ this.debug.log('📦 Distributed storage enabled');
1542
+ this.emit('storageEnabled');
1543
+ }
1544
+
1545
+ /**
1546
+ * Disable the distributed storage layer
1547
+ * @returns {Promise<void>}
1548
+ */
1549
+ async disable() {
1550
+ this.enabled = false;
1551
+ this.debug.log('📦 Distributed storage disabled');
1552
+ this.emit('storageDisabled');
1553
+ }
1554
+
1555
+ /**
1556
+ * Check if the distributed storage layer is enabled
1557
+ * @returns {boolean} Whether storage is enabled
1558
+ */
1559
+ isEnabled() {
1560
+ return this.enabled;
1561
+ }
1562
+
1563
+ /**
1564
+ * Clear all stored data owned by this peer
1565
+ * @returns {Promise<void>}
1566
+ */
1567
+ async clear() {
1568
+ const ownedKeys = Array.from(this.ownedKeys);
1569
+
1570
+ for (const keyId of ownedKeys) {
1571
+ const metadata = this.storageMetadata.get(keyId);
1572
+ if (metadata) {
1573
+ try {
1574
+ await this.delete(metadata.key);
1575
+ } catch (error) {
1576
+ this.debug.warn(`Failed to delete key ${metadata.key} during clear:`, error);
1577
+ }
1578
+ }
1579
+ }
1580
+
1581
+ // Clear local state
1582
+ this.storageMetadata.clear();
1583
+ this.accessControl.clear();
1584
+ this.crdtStates.clear();
1585
+ this.ownedKeys.clear();
1586
+ this.spaceOwnership.clear();
1587
+ this.keyToSpaceMapping.clear();
1588
+
1589
+ this.debug.log('📦 All stored data cleared');
1590
+ this.emit('storageCleared');
1591
+ }
1592
+
1593
+ /**
1594
+ * List keys with optional prefix filter
1595
+ * @param {string} prefix - Optional prefix to filter keys
1596
+ * @returns {Promise<Array<string>>} Array of matching keys
1597
+ */
1598
+ async listKeys(prefix = '') {
1599
+ const keys = [];
1600
+
1601
+ for (const keyId of this.ownedKeys) {
1602
+ const metadata = this.storageMetadata.get(keyId);
1603
+ if (metadata) {
1604
+ // Check both the full key and the base key for prefix match
1605
+ const fullKey = metadata.key;
1606
+ const baseKey = metadata.baseKey;
1607
+
1608
+ if (fullKey.startsWith(prefix) || baseKey.startsWith(prefix)) {
1609
+ // Return the base key for user convenience (since they stored with base key)
1610
+ keys.push(baseKey);
1611
+ }
1612
+ }
1613
+ }
1614
+
1615
+ return keys.sort();
1616
+ }
1617
+
1618
+ /**
1619
+ * Bulk delete keys with a given prefix
1620
+ * @param {string} prefix - Prefix of keys to delete
1621
+ * @returns {Promise<number>} Number of keys deleted
1622
+ */
1623
+ async bulkDelete(prefix) {
1624
+ const keysToDelete = await this.listKeys(prefix);
1625
+ let deletedCount = 0;
1626
+
1627
+ for (const key of keysToDelete) {
1628
+ try {
1629
+ await this.delete(key);
1630
+ deletedCount++;
1631
+ } catch (error) {
1632
+ this.debug.warn(`Failed to delete key ${key} during bulk delete:`, error);
1633
+ }
1634
+ }
1635
+
1636
+ return deletedCount;
1637
+ }
1638
+
1639
+ /**
1640
+ * Search for data by key, value, or metadata
1641
+ * @param {string} query - Search query
1642
+ * @param {string} type - Search type: 'key', 'value', or 'metadata'
1643
+ * @returns {Promise<Array<Object>>} Search results
1644
+ */
1645
+ async search(query, type = 'key') {
1646
+ const results = [];
1647
+ const searchRegex = new RegExp(query, 'i'); // Case-insensitive search
1648
+
1649
+ for (const keyId of this.ownedKeys) {
1650
+ const metadata = this.storageMetadata.get(keyId);
1651
+ if (!metadata) continue;
1652
+
1653
+ let match = false;
1654
+
1655
+ if (type === 'key' && searchRegex.test(metadata.key)) {
1656
+ match = true;
1657
+ } else if (type === 'value') {
1658
+ try {
1659
+ const value = await this.retrieve(metadata.key);
1660
+ if (value && searchRegex.test(JSON.stringify(value))) {
1661
+ match = true;
1662
+ }
1663
+ } catch (error) {
1664
+ // Skip values that can't be retrieved
1665
+ }
1666
+ } else if (type === 'metadata') {
1667
+ const metadataStr = JSON.stringify({
1668
+ owner: metadata.owner,
1669
+ isPublic: metadata.isPublic,
1670
+ isImmutable: metadata.isImmutable,
1671
+ enableCRDT: metadata.enableCRDT
1672
+ });
1673
+ if (searchRegex.test(metadataStr)) {
1674
+ match = true;
1675
+ }
1676
+ }
1677
+
1678
+ if (match) {
1679
+ try {
1680
+ const value = await this.retrieve(metadata.key);
1681
+ results.push({
1682
+ key: metadata.key,
1683
+ value,
1684
+ metadata: {
1685
+ owner: metadata.owner,
1686
+ isPublic: metadata.isPublic,
1687
+ isImmutable: metadata.isImmutable,
1688
+ enableCRDT: metadata.enableCRDT,
1689
+ createdAt: metadata.createdAt,
1690
+ updatedAt: metadata.updatedAt
1691
+ }
1692
+ });
1693
+ } catch (error) {
1694
+ // Skip keys that can't be retrieved
1695
+ }
1696
+ }
1697
+ }
1698
+
1699
+ return results;
1700
+ }
1701
+ }