peerpigeon 0.0.8 → 0.1.1

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.
@@ -1,4 +1,6 @@
1
1
  import { EventEmitter } from './EventEmitter.js';
2
+ import DebugLogger from './DebugLogger.js';
3
+ import { createLexicalInterface } from './LexicalStorageInterface.js';
2
4
 
3
5
  // Dynamic import for unsea to handle both Node.js and browser environments
4
6
  let unsea = null;
@@ -55,10 +57,12 @@ async function initializeUnsea() {
55
57
  * - Optional immutability with CRDT support for collaborative editing
56
58
  * - Mutable layer for data originators
57
59
  * - Integration with WebDHT for distributed storage
60
+ * - Space separation for preventing data overwrites (Private, Public, Frozen)
58
61
  */
59
62
  export class DistributedStorageManager extends EventEmitter {
60
63
  constructor(mesh) {
61
64
  super();
65
+ this.debug = DebugLogger.create('DistributedStorageManager');
62
66
  this.mesh = mesh;
63
67
  this.webDHT = mesh.webDHT;
64
68
  this.cryptoManager = mesh.cryptoManager;
@@ -74,7 +78,15 @@ export class DistributedStorageManager extends EventEmitter {
74
78
  defaultTTL: null, // No expiration by default
75
79
  maxValueSize: 1024 * 1024, // 1MB default max size
76
80
  enableCRDT: true,
77
- conflictResolution: 'last-write-wins' // or 'crdt-merge'
81
+ conflictResolution: 'last-write-wins', // or 'crdt-merge'
82
+ spaceEnforcement: true // Enable space-based access control
83
+ };
84
+
85
+ // Storage spaces for data separation
86
+ this.spaces = {
87
+ PRIVATE: 'private', // Only owner can read/write, encrypted
88
+ PUBLIC: 'public', // Anyone can read, only owner can write
89
+ FROZEN: 'frozen' // Immutable once set, anyone can read
78
90
  };
79
91
 
80
92
  // Local storage for metadata and permissions
@@ -82,13 +94,15 @@ export class DistributedStorageManager extends EventEmitter {
82
94
  this.accessControl = new Map(); // keyId -> access control info
83
95
  this.crdtStates = new Map(); // keyId -> CRDT state for collaborative data
84
96
 
85
- // Track data ownership
97
+ // Track data ownership by space
86
98
  this.ownedKeys = new Set(); // Keys owned by this peer
99
+ this.spaceOwnership = new Map(); // space:key -> owner mapping
100
+ this.keyToSpaceMapping = new Map(); // baseKey -> {space, fullKey} mapping for transparent access
87
101
 
88
102
  // Track enabled state
89
103
  this.enabled = true; // Enable by default
90
104
 
91
- console.log(`DistributedStorageManager initialized for peer ${this.mesh.peerId?.substring(0, 8)}...`);
105
+ this.debug.log(`DistributedStorageManager initialized for peer ${this.mesh.peerId?.substring(0, 8)}...`);
92
106
  }
93
107
 
94
108
  /**
@@ -107,9 +121,9 @@ export class DistributedStorageManager extends EventEmitter {
107
121
  this.storageKeypair = await this.unsea.generateRandomPair();
108
122
  }
109
123
 
110
- console.log('📦 Storage encryption initialized with unsea');
124
+ this.debug.log('📦 Storage encryption initialized with unsea');
111
125
  } catch (error) {
112
- console.warn('📦 Failed to initialize storage encryption:', error);
126
+ this.debug.warn('📦 Failed to initialize storage encryption:', error);
113
127
  // Disable encryption if unsea fails to load
114
128
  this.config.encryptionEnabled = false;
115
129
  }
@@ -128,29 +142,272 @@ export class DistributedStorageManager extends EventEmitter {
128
142
  const timeout = 5000;
129
143
  const start = Date.now();
130
144
 
131
- while (!this.unsea || !this.storageKeypair) {
132
- if (Date.now() - start > timeout) {
133
- console.warn('📦 Crypto initialization timeout - proceeding without encryption');
134
- this.config.encryptionEnabled = false;
135
- break;
136
- }
145
+ while ((!this.unsea || !this.storageKeypair) && (Date.now() - start) < timeout) {
137
146
  await new Promise(resolve => setTimeout(resolve, 100));
138
147
  }
139
148
  }
140
149
 
150
+ /**
151
+ * Resolve a key to its actual storage location across spaces
152
+ * @param {string} key - The storage key (can be plain or space-prefixed)
153
+ * @returns {Object} - {space, baseKey, fullKey, keyId}
154
+ */
155
+ async resolveKey(key) {
156
+ // If key already has space prefix, use it as-is
157
+ const keyInfo = this.parseStorageKey(key);
158
+
159
+ // If it's not a bare key (has space prefix), use it directly
160
+ if (key.includes(':')) {
161
+ const keyId = await this.webDHT.generateKeyId(keyInfo.fullKey);
162
+ return {
163
+ space: keyInfo.space,
164
+ baseKey: keyInfo.baseKey,
165
+ fullKey: keyInfo.fullKey,
166
+ keyId
167
+ };
168
+ }
169
+
170
+ // For bare keys, check if we have a mapping
171
+ const mapping = this.keyToSpaceMapping.get(keyInfo.baseKey);
172
+ if (mapping) {
173
+ const keyId = await this.webDHT.generateKeyId(mapping.fullKey);
174
+ return {
175
+ space: mapping.space,
176
+ baseKey: keyInfo.baseKey,
177
+ fullKey: mapping.fullKey,
178
+ keyId
179
+ };
180
+ }
181
+
182
+ // If no mapping exists, try to find it by checking each space
183
+ for (const space of Object.values(this.spaces)) {
184
+ const testFullKey = this.createSpacedKey(space, keyInfo.baseKey);
185
+ const testKeyId = await this.webDHT.generateKeyId(testFullKey);
186
+
187
+ // Check if we have metadata for this key in this space
188
+ if (this.storageMetadata.has(testKeyId) || this.spaceOwnership.has(testFullKey)) {
189
+ // Update the mapping for future use
190
+ this.keyToSpaceMapping.set(keyInfo.baseKey, { space, fullKey: testFullKey });
191
+ return {
192
+ space,
193
+ baseKey: keyInfo.baseKey,
194
+ fullKey: testFullKey,
195
+ keyId: testKeyId
196
+ };
197
+ }
198
+ }
199
+
200
+ // If still not found, default to the parsed key (likely private space)
201
+ const keyId = await this.webDHT.generateKeyId(keyInfo.fullKey);
202
+ return {
203
+ space: keyInfo.space,
204
+ baseKey: keyInfo.baseKey,
205
+ fullKey: keyInfo.fullKey,
206
+ keyId
207
+ };
208
+ }
209
+
210
+ /**
211
+ * Parse a storage key to extract space and base key
212
+ * @param {string} key - The storage key (can be plain or space-prefixed)
213
+ * @returns {Object} - {space, baseKey, fullKey}
214
+ */
215
+ parseStorageKey(key) {
216
+ // Check if key has space prefix (e.g., "private:user:123" or "public:config")
217
+ const spacePrefixes = Object.values(this.spaces);
218
+ for (const space of spacePrefixes) {
219
+ if (key.startsWith(`${space}:`)) {
220
+ return {
221
+ space,
222
+ baseKey: key.substring(space.length + 1),
223
+ fullKey: key
224
+ };
225
+ }
226
+ }
227
+
228
+ // Default to private space if no prefix specified
229
+ return {
230
+ space: this.spaces.PRIVATE,
231
+ baseKey: key,
232
+ fullKey: `${this.spaces.PRIVATE}:${key}`
233
+ };
234
+ }
235
+
236
+ /**
237
+ * Create a space-prefixed key
238
+ * @param {string} space - The storage space
239
+ * @param {string} baseKey - The base key
240
+ * @returns {string} - The full key with space prefix
241
+ */
242
+ createSpacedKey(space, baseKey) {
243
+ if (!Object.values(this.spaces).includes(space)) {
244
+ throw new Error(`Invalid storage space: ${space}. Must be one of: ${Object.values(this.spaces).join(', ')}`);
245
+ }
246
+ return `${space}:${baseKey}`;
247
+ }
248
+
249
+ /**
250
+ * Check if a peer can access a key in a specific space
251
+ * @param {string} space - The storage space
252
+ * @param {string} key - The storage key
253
+ * @param {string} peerId - The peer ID requesting access
254
+ * @param {string} operation - The operation (read, write)
255
+ * @returns {boolean} - Whether access is allowed
256
+ */
257
+ canAccessSpace(space, key, peerId, operation = 'read') {
258
+ if (!this.config.spaceEnforcement) {
259
+ return true; // Space enforcement disabled
260
+ }
261
+
262
+ const spaceKey = `${space}:${key}`;
263
+ const owner = this.spaceOwnership.get(spaceKey);
264
+
265
+ switch (space) {
266
+ case this.spaces.PRIVATE:
267
+ // Private: Only owner can read/write, or if no owner exists (initial write)
268
+ return !owner || owner === peerId;
269
+
270
+ case this.spaces.PUBLIC:
271
+ if (operation === 'read') {
272
+ return true; // Anyone can read public data
273
+ } else {
274
+ return !owner || owner === peerId; // Only owner can write, or initial write
275
+ }
276
+
277
+ case this.spaces.FROZEN:
278
+ if (operation === 'read') {
279
+ return true; // Anyone can read frozen data
280
+ } else {
281
+ // For frozen data, only the owner can write (both initial and updates)
282
+ return !owner || owner === peerId; // Only owner can write, or initial write
283
+ }
284
+
285
+ default:
286
+ return false;
287
+ }
288
+ }
289
+
290
+ /**
291
+ * Determine appropriate space and access control from options
292
+ * @param {Object} options - Storage options
293
+ * @returns {Object} - {space, isPublic, isImmutable}
294
+ */
295
+ determineSpaceFromOptions(options = {}) {
296
+ // Allow explicit space specification
297
+ if (options.space && Object.values(this.spaces).includes(options.space)) {
298
+ const space = options.space;
299
+ return {
300
+ space,
301
+ isPublic: space !== this.spaces.PRIVATE,
302
+ isImmutable: space === this.spaces.FROZEN
303
+ };
304
+ }
305
+
306
+ // Legacy compatibility - determine space from isPublic/isImmutable
307
+ if (options.isImmutable) {
308
+ return {
309
+ space: this.spaces.FROZEN,
310
+ isPublic: true,
311
+ isImmutable: true
312
+ };
313
+ } else if (options.isPublic) {
314
+ return {
315
+ space: this.spaces.PUBLIC,
316
+ isPublic: true,
317
+ isImmutable: false
318
+ };
319
+ } else {
320
+ return {
321
+ space: this.spaces.PRIVATE,
322
+ isPublic: false,
323
+ isImmutable: false
324
+ };
325
+ }
326
+ }
327
+
328
+ /**
329
+ * Find if a base key exists in a different space
330
+ * @param {string} baseKey - The base key to search for
331
+ * @param {string} excludeSpace - The space to exclude from search
332
+ * @returns {string|null} - The space where the key exists, or null if not found
333
+ */
334
+ findKeyInDifferentSpace(baseKey, excludeSpace) {
335
+ for (const space of Object.values(this.spaces)) {
336
+ if (space !== excludeSpace) {
337
+ const spacedKey = this.createSpacedKey(space, baseKey);
338
+ if (this.spaceOwnership.has(spacedKey)) {
339
+ return space;
340
+ }
341
+ }
342
+ }
343
+ return null;
344
+ }
345
+
346
+ /**
347
+ * Check if the current peer has read access to a key with space awareness
348
+ * @param {string} keyId - The key ID
349
+ * @param {Object} metadata - The metadata object
350
+ * @param {string} space - The storage space
351
+ * @returns {boolean} - Whether access is allowed
352
+ */
353
+ hasReadAccessWithSpace(keyId, metadata, space) {
354
+ const accessControl = this.accessControl.get(keyId);
355
+
356
+ if (!accessControl && metadata) {
357
+ // Create access control from metadata
358
+ this.accessControl.set(keyId, {
359
+ isPublic: metadata.isPublic,
360
+ owner: metadata.owner,
361
+ allowedPeers: new Set(metadata.allowedPeers || []),
362
+ isImmutable: metadata.isImmutable,
363
+ space: metadata.space || space
364
+ });
365
+ return this.hasReadAccessWithSpace(keyId, metadata, space);
366
+ }
367
+
368
+ if (!accessControl) {
369
+ return false;
370
+ }
371
+
372
+ // Owner always has access
373
+ if (accessControl.owner === this.mesh.peerId) {
374
+ return true;
375
+ }
376
+
377
+ // Space-based access control
378
+ switch (space) {
379
+ case this.spaces.PRIVATE:
380
+ // Private: only owner and specifically allowed peers
381
+ return accessControl.allowedPeers.has(this.mesh.peerId);
382
+
383
+ case this.spaces.PUBLIC:
384
+ case this.spaces.FROZEN:
385
+ // Public and frozen: anyone can read
386
+ return true;
387
+
388
+ default:
389
+ return false;
390
+ }
391
+ }
392
+
141
393
  /**
142
394
  * Store data with encryption and access control
143
395
  * @param {string} key - The storage key
144
396
  * @param {any} value - The value to store
145
397
  * @param {Object} options - Storage options
146
- * @param {boolean} options.isPublic - Whether data is publicly readable (default: false - private and encrypted)
147
- * @param {boolean} options.isImmutable - Whether data is immutable for other peers (default: false)
398
+ * @param {string} options.space - Storage space ('private', 'public', 'frozen')
399
+ * @param {boolean} options.isPublic - Whether data is publicly readable (legacy, use space instead)
400
+ * @param {boolean} options.isImmutable - Whether data is immutable (legacy, use frozen space instead)
148
401
  * @param {boolean} options.enableCRDT - Whether to enable CRDT for collaborative editing (default: false)
149
402
  * @param {number} options.ttl - Time to live in milliseconds
150
403
  * @param {Array<string>} options.allowedPeers - Specific peers allowed to read private data
151
404
  * @returns {Promise<boolean>} Success status
152
405
  */
153
406
  async store(key, value, options = {}) {
407
+ if (!this.enabled) {
408
+ return false;
409
+ }
410
+
154
411
  if (!this.webDHT) {
155
412
  throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
156
413
  }
@@ -160,9 +417,31 @@ export class DistributedStorageManager extends EventEmitter {
160
417
  await this.waitForCrypto();
161
418
  }
162
419
 
163
- const keyId = await this.webDHT.generateKeyId(key);
420
+ // Parse key and determine storage space
421
+ const keyInfo = this.parseStorageKey(key);
422
+ const spaceConfig = this.determineSpaceFromOptions(options);
423
+
424
+ // Use explicit space from options if provided, otherwise use parsed space
425
+ const space = options.space || spaceConfig.space;
426
+ const fullKey = keyInfo.space === space ? keyInfo.fullKey : this.createSpacedKey(space, keyInfo.baseKey);
427
+ const baseKey = keyInfo.baseKey;
428
+
429
+ // Check space access permissions
430
+ if (!this.canAccessSpace(space, baseKey, this.mesh.peerId, 'write')) {
431
+ throw new Error(`Write access denied for space "${space}" and key "${baseKey}"`);
432
+ }
433
+
434
+ // Check if key already exists in a different space
435
+ if (this.config.spaceEnforcement) {
436
+ const existingSpaceKey = this.findKeyInDifferentSpace(baseKey, space);
437
+ if (existingSpaceKey) {
438
+ throw new Error(`Key "${baseKey}" already exists in space "${existingSpaceKey}" - cannot store in "${space}" space`);
439
+ }
440
+ }
441
+
442
+ const keyId = await this.webDHT.generateKeyId(fullKey);
164
443
  const timestamp = Date.now();
165
- console.log(`📦 Storing key: ${key}, keyId: ${keyId.substring(0, 8)}...`);
444
+ this.debug.log(`📦 Storing key: ${fullKey}, keyId: ${keyId.substring(0, 8)}...`);
166
445
 
167
446
  // Validate value size
168
447
  const serializedValue = JSON.stringify(value);
@@ -170,13 +449,15 @@ export class DistributedStorageManager extends EventEmitter {
170
449
  throw new Error(`Value size exceeds maximum allowed size of ${this.config.maxValueSize} bytes`);
171
450
  }
172
451
 
173
- // Create storage metadata - default to private for security
452
+ // Create storage metadata with space information
174
453
  const metadata = {
175
- key,
454
+ key: fullKey,
455
+ baseKey,
456
+ space,
176
457
  keyId,
177
458
  owner: this.mesh.peerId,
178
- isPublic: options.isPublic !== undefined ? options.isPublic : false, // Default to private
179
- isImmutable: options.isImmutable || false,
459
+ isPublic: spaceConfig.isPublic,
460
+ isImmutable: spaceConfig.isImmutable,
180
461
  enableCRDT: options.enableCRDT || false,
181
462
  allowedPeers: options.allowedPeers || [],
182
463
  createdAt: timestamp,
@@ -189,12 +470,19 @@ export class DistributedStorageManager extends EventEmitter {
189
470
  this.storageMetadata.set(keyId, metadata);
190
471
  this.ownedKeys.add(keyId);
191
472
 
473
+ // Track space ownership
474
+ this.spaceOwnership.set(fullKey, this.mesh.peerId);
475
+
476
+ // Track base key to space mapping for transparent access
477
+ this.keyToSpaceMapping.set(baseKey, { space, fullKey });
478
+
192
479
  // Set up access control
193
480
  this.accessControl.set(keyId, {
194
481
  isPublic: metadata.isPublic,
195
482
  owner: metadata.owner,
196
483
  allowedPeers: new Set(metadata.allowedPeers),
197
- isImmutable: metadata.isImmutable
484
+ isImmutable: metadata.isImmutable,
485
+ space
198
486
  });
199
487
 
200
488
  // Initialize CRDT state if enabled
@@ -213,8 +501,8 @@ export class DistributedStorageManager extends EventEmitter {
213
501
  encrypted: false
214
502
  };
215
503
 
216
- // Only encrypt private data (isPublic: false) to ensure owner-only access
217
- if (!metadata.isPublic && this.config.encryptionEnabled && this.unsea && this.storageKeypair) {
504
+ // Only encrypt private space data
505
+ if (space === this.spaces.PRIVATE && this.config.encryptionEnabled && this.unsea && this.storageKeypair) {
218
506
  try {
219
507
  // For private data, encrypt with the owner's keypair so only the owner can decrypt
220
508
  const encryptedValue = await this.unsea.encryptMessageWithMeta(serializedValue, this.storageKeypair);
@@ -224,32 +512,35 @@ export class DistributedStorageManager extends EventEmitter {
224
512
  encrypted: true,
225
513
  encryptedBy: this.mesh.peerId // Track who encrypted it
226
514
  };
227
- console.log(`📦 Encrypted private storage data for key: ${key} (owner-only access)`);
515
+ this.debug.log(`📦 Encrypted private space storage data for key: ${fullKey} (owner-only access)`);
228
516
  } catch (error) {
229
- console.warn(`Failed to encrypt private storage data for key ${key}:`, error);
517
+ this.debug.warn(`Failed to encrypt private space storage data for key ${fullKey}:`, error);
230
518
  // Fall back to unencrypted storage if encryption fails
231
519
  }
232
520
  } else {
233
- console.log(`📦 Storing ${metadata.isPublic ? 'public' : 'unencrypted'} data for key: ${key}`);
521
+ this.debug.log(`📦 Storing ${space} space data for key: ${fullKey}`);
234
522
  }
235
523
 
236
- // Store in WebDHT
524
+ // Store in WebDHT with space prefix
237
525
  try {
238
- console.log(`📦 Storing payload for key ${key}:`, {
526
+ this.debug.log(`📦 Storing payload for key ${fullKey}:`, {
239
527
  hasValue: !!storagePayload.value,
240
528
  hasMetadata: !!storagePayload.metadata,
241
- encrypted: storagePayload.encrypted
529
+ encrypted: storagePayload.encrypted,
530
+ space
242
531
  });
243
532
 
244
- await this.webDHT.put(`storage:${key}`, storagePayload, {
533
+ await this.webDHT.put(`storage:${fullKey}`, storagePayload, {
245
534
  ttl: metadata.ttl
246
535
  });
247
536
 
248
- console.log(`📦 Stored ${metadata.isPublic ? 'public' : 'private'} data for key: ${key}`);
537
+ this.debug.log(`📦 Stored ${space} space data for key: ${fullKey}`);
249
538
 
250
539
  // Emit storage event
251
540
  this.emit('dataStored', {
252
- key,
541
+ key: fullKey,
542
+ baseKey,
543
+ space,
253
544
  keyId,
254
545
  isPublic: metadata.isPublic,
255
546
  isImmutable: metadata.isImmutable,
@@ -258,12 +549,14 @@ export class DistributedStorageManager extends EventEmitter {
258
549
 
259
550
  return true;
260
551
  } catch (error) {
261
- console.error(`Failed to store data for key ${key}:`, error);
552
+ this.debug.error(`Failed to store data for key ${fullKey}:`, error);
262
553
  // Clean up local metadata on failure
263
554
  this.storageMetadata.delete(keyId);
264
555
  this.ownedKeys.delete(keyId);
265
556
  this.accessControl.delete(keyId);
266
557
  this.crdtStates.delete(keyId);
558
+ this.spaceOwnership.delete(fullKey);
559
+ this.keyToSpaceMapping.delete(baseKey);
267
560
  throw error;
268
561
  }
269
562
  }
@@ -285,30 +578,39 @@ export class DistributedStorageManager extends EventEmitter {
285
578
  await this.waitForCrypto();
286
579
  }
287
580
 
288
- const keyId = await this.webDHT.generateKeyId(key);
289
- console.log(`📦 Retrieving key: ${key}, keyId: ${keyId.substring(0, 8)}...`);
581
+ // Resolve the key to its actual storage location
582
+ const resolved = await this.resolveKey(key);
583
+ const { space, baseKey, fullKey, keyId } = resolved;
584
+
585
+ // Check space access permissions
586
+ if (!this.canAccessSpace(space, baseKey, this.mesh.peerId, 'read')) {
587
+ this.debug.warn(`📦 Access denied for space "${space}" and key "${baseKey}"`);
588
+ return null;
589
+ }
590
+
591
+ this.debug.log(`📦 Retrieving key: ${fullKey}, keyId: ${keyId.substring(0, 8)}...`);
290
592
 
291
593
  try {
292
594
  // Get data from WebDHT
293
- console.log(`📦 Attempting to retrieve data for key: ${key}`);
294
- const storagePayload = await this.webDHT.get(`storage:${key}`, {
595
+ this.debug.log(`📦 Attempting to retrieve data for key: ${fullKey}`);
596
+ const storagePayload = await this.webDHT.get(`storage:${fullKey}`, {
295
597
  forceRefresh: options.forceRefresh
296
598
  });
297
599
 
298
- console.log(`📦 Retrieved payload for key ${key}:`, {
600
+ this.debug.log(`📦 Retrieved payload for key ${fullKey}:`, {
299
601
  payloadExists: !!storagePayload,
300
602
  payloadType: typeof storagePayload,
301
- payloadValue: storagePayload,
603
+ space,
302
604
  keys: storagePayload ? Object.keys(storagePayload) : 'none'
303
605
  });
304
606
 
305
607
  if (!storagePayload || typeof storagePayload !== 'object') {
306
- console.log(`📦 No data found for key: ${key}`);
608
+ this.debug.log(`📦 No data found for key: ${fullKey}`);
307
609
  return null;
308
610
  }
309
611
 
310
612
  // Debug: Log the raw payload structure
311
- console.log('📦 Raw payload structure:', JSON.stringify(storagePayload, null, 2));
613
+ this.debug.log('📦 Raw payload structure:', JSON.stringify(storagePayload, null, 2));
312
614
 
313
615
  // Safely destructure the payload with detailed logging
314
616
  const value = storagePayload.value;
@@ -316,23 +618,30 @@ export class DistributedStorageManager extends EventEmitter {
316
618
  const encrypted = storagePayload.encrypted || false;
317
619
  const encryptedBy = storagePayload.encryptedBy;
318
620
 
319
- console.log('📦 Payload components:', {
621
+ this.debug.log('📦 Payload components:', {
320
622
  hasValue: value !== undefined,
321
623
  valueType: typeof value,
322
624
  hasMetadata: metadata !== undefined,
323
625
  metadataType: typeof metadata,
324
626
  encrypted,
627
+ space: metadata?.space || 'unknown',
325
628
  encryptedBy: encryptedBy?.substring(0, 8) + '...' || 'unknown'
326
629
  });
327
630
 
328
631
  if (!metadata) {
329
- console.warn(`📦 Invalid storage payload for key ${key}: missing metadata`);
632
+ this.debug.warn(`📦 Invalid storage payload for key ${fullKey}: missing metadata`);
330
633
  return null;
331
634
  }
332
635
 
333
- // Check access permissions
334
- if (!this.hasReadAccess(keyId, metadata)) {
335
- console.warn(`Access denied for key: ${key}`);
636
+ // Verify space consistency
637
+ if (metadata.space && metadata.space !== space) {
638
+ this.debug.warn(`📦 Space mismatch for key ${fullKey}: expected ${space}, got ${metadata.space}`);
639
+ return null;
640
+ }
641
+
642
+ // Check access permissions using space-aware logic
643
+ if (!this.hasReadAccessWithSpace(keyId, metadata, space)) {
644
+ this.debug.warn(`📦 Access denied for key: ${fullKey} in space: ${space}`);
336
645
  return null;
337
646
  }
338
647
 
@@ -341,10 +650,10 @@ export class DistributedStorageManager extends EventEmitter {
341
650
  if (encrypted && this.unsea && this.storageKeypair) {
342
651
  // Only allow decryption if this peer is the owner (encrypted the data)
343
652
  if (encryptedBy && encryptedBy !== this.mesh.peerId) {
344
- console.warn(`📦 Cannot decrypt data for key ${key}: encrypted by different peer (${encryptedBy.substring(0, 8)}...), current peer: ${this.mesh.peerId.substring(0, 8)}...`);
653
+ 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)}...`);
345
654
  // For private data encrypted by another peer, deny access
346
655
  if (!metadata.isPublic) {
347
- console.warn(`Access denied for key: ${key} - private data encrypted by different peer`);
656
+ this.debug.warn(`Access denied for key: ${key} - private data encrypted by different peer`);
348
657
  return null;
349
658
  }
350
659
  }
@@ -352,15 +661,15 @@ export class DistributedStorageManager extends EventEmitter {
352
661
  try {
353
662
  const decryptedValue = await this.unsea.decryptMessageWithMeta(value, this.storageKeypair.epriv);
354
663
  finalValue = JSON.parse(decryptedValue);
355
- console.log(`🔓 Decrypted storage data for key: ${key}`);
664
+ this.debug.log(`🔓 Decrypted storage data for key: ${key}`);
356
665
  } catch (error) {
357
- console.error(`Failed to decrypt data for key ${key}:`, error);
666
+ this.debug.error(`Failed to decrypt data for key ${key}:`, error);
358
667
  // If this is private data and decryption fails, deny access
359
668
  if (!metadata.isPublic) {
360
669
  return null;
361
670
  }
362
671
  // For public data, if decryption fails, try to use the raw value
363
- console.warn(`📦 Using raw value for public key ${key} due to decryption failure`);
672
+ this.debug.warn(`📦 Using raw value for public key ${key} due to decryption failure`);
364
673
  finalValue = value;
365
674
  }
366
675
  }
@@ -372,15 +681,28 @@ export class DistributedStorageManager extends EventEmitter {
372
681
  isPublic: metadata.isPublic,
373
682
  owner: metadata.owner,
374
683
  allowedPeers: new Set(metadata.allowedPeers),
375
- isImmutable: metadata.isImmutable
684
+ isImmutable: metadata.isImmutable,
685
+ space: metadata.space || space
376
686
  });
687
+
688
+ // Track space ownership from retrieved metadata
689
+ if (metadata.owner && !this.spaceOwnership.has(fullKey)) {
690
+ this.spaceOwnership.set(fullKey, metadata.owner);
691
+ }
692
+
693
+ // Update key mapping for future transparent access
694
+ if (!key.includes(':')) {
695
+ this.keyToSpaceMapping.set(baseKey, { space, fullKey });
696
+ }
377
697
  }
378
698
 
379
- console.log(`📦 Retrieved ${metadata.isPublic ? 'public' : 'private'} data for key: ${key}`);
699
+ this.debug.log(`📦 Retrieved ${space} space data for key: ${fullKey}`);
380
700
 
381
701
  // Emit retrieval event
382
702
  this.emit('dataRetrieved', {
383
- key,
703
+ key: fullKey,
704
+ baseKey,
705
+ space,
384
706
  keyId,
385
707
  isPublic: metadata.isPublic,
386
708
  owner: metadata.owner
@@ -388,7 +710,7 @@ export class DistributedStorageManager extends EventEmitter {
388
710
 
389
711
  return finalValue;
390
712
  } catch (error) {
391
- console.error(`Failed to retrieve data for key ${key}:`, error);
713
+ this.debug.error(`Failed to retrieve data for key ${key}:`, error);
392
714
  return null;
393
715
  }
394
716
  }
@@ -406,21 +728,33 @@ export class DistributedStorageManager extends EventEmitter {
406
728
  throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
407
729
  }
408
730
 
409
- const keyId = await this.webDHT.generateKeyId(key);
731
+ // Resolve the key to its actual storage location
732
+ const resolved = await this.resolveKey(key);
733
+ const { fullKey, keyId } = resolved;
410
734
  const timestamp = Date.now();
411
735
 
412
736
  // Check if we have access to update
413
- const accessControl = this.accessControl.get(keyId);
414
- const metadata = this.storageMetadata.get(keyId);
737
+ let accessControl = this.accessControl.get(keyId);
738
+ let metadata = this.storageMetadata.get(keyId);
415
739
 
416
740
  if (!accessControl || !metadata) {
417
741
  // Try to retrieve metadata first
418
- const existingData = await this.retrieve(key);
742
+ const existingData = await this.retrieve(fullKey);
419
743
  if (!existingData) {
420
744
  throw new Error(`Key ${key} does not exist or is not accessible`);
421
745
  }
422
- // Retry after retrieving metadata
423
- return this.update(key, newValue, options);
746
+
747
+ // Check if metadata is now available after retrieve
748
+ const updatedAccessControl = this.accessControl.get(keyId);
749
+ const updatedMetadata = this.storageMetadata.get(keyId);
750
+
751
+ if (!updatedAccessControl || !updatedMetadata) {
752
+ throw new Error(`Key ${key} metadata could not be loaded - unable to update`);
753
+ }
754
+
755
+ // Update local references and continue with update logic
756
+ accessControl = updatedAccessControl;
757
+ metadata = updatedMetadata;
424
758
  }
425
759
 
426
760
  const isOwner = accessControl.owner === this.mesh.peerId;
@@ -457,26 +791,26 @@ export class DistributedStorageManager extends EventEmitter {
457
791
  encrypted: true,
458
792
  encryptedBy: this.mesh.peerId // Track who encrypted it
459
793
  };
460
- console.log(`📦 Encrypted updated storage data for key: ${key}`);
794
+ this.debug.log(`📦 Encrypted updated storage data for key: ${key}`);
461
795
  } catch (error) {
462
- console.warn(`Failed to encrypt updated storage data for key ${key}:`, error);
796
+ this.debug.warn(`Failed to encrypt updated storage data for key ${key}:`, error);
463
797
  }
464
798
  }
465
799
 
466
800
  try {
467
801
  // Use WebDHT update to notify all replicas and subscribers
468
- await this.webDHT.update(`storage:${key}`, storagePayload, {
802
+ await this.webDHT.update(`storage:${fullKey}`, storagePayload, {
469
803
  ttl: metadata.ttl
470
804
  });
471
805
 
472
806
  // Update local metadata
473
807
  this.storageMetadata.set(keyId, metadata);
474
808
 
475
- console.log(`📦 Updated ${metadata.isPublic ? 'public' : 'private'} data for key: ${key}`);
809
+ this.debug.log(`📦 Updated ${metadata.isPublic ? 'public' : 'private'} data for key: ${fullKey}`);
476
810
 
477
811
  // Emit update event
478
812
  this.emit('dataUpdated', {
479
- key,
813
+ key: fullKey,
480
814
  keyId,
481
815
  isPublic: metadata.isPublic,
482
816
  version: metadata.version,
@@ -485,7 +819,7 @@ export class DistributedStorageManager extends EventEmitter {
485
819
 
486
820
  return true;
487
821
  } catch (error) {
488
- console.error(`Failed to update data for key ${key}:`, error);
822
+ this.debug.error(`Failed to update data for key ${fullKey}:`, error);
489
823
  throw error;
490
824
  }
491
825
  }
@@ -564,7 +898,10 @@ export class DistributedStorageManager extends EventEmitter {
564
898
  throw new Error('WebDHT not available - ensure it is enabled in mesh configuration');
565
899
  }
566
900
 
567
- const keyId = await this.webDHT.generateKeyId(key);
901
+ // Resolve the key to its actual storage location
902
+ const resolved = await this.resolveKey(key);
903
+ const { baseKey, fullKey, keyId } = resolved;
904
+
568
905
  const accessControl = this.accessControl.get(keyId);
569
906
 
570
907
  if (!accessControl || accessControl.owner !== this.mesh.peerId) {
@@ -579,7 +916,7 @@ export class DistributedStorageManager extends EventEmitter {
579
916
  deletedBy: this.mesh.peerId
580
917
  };
581
918
 
582
- await this.webDHT.update(`storage:${key}`, tombstone);
919
+ await this.webDHT.update(`storage:${fullKey}`, tombstone);
583
920
 
584
921
  // Clean up local state
585
922
  this.storageMetadata.delete(keyId);
@@ -587,14 +924,18 @@ export class DistributedStorageManager extends EventEmitter {
587
924
  this.accessControl.delete(keyId);
588
925
  this.crdtStates.delete(keyId);
589
926
 
590
- console.log(`📦 Deleted data for key: ${key}`);
927
+ // Clean up space ownership tracking and key mapping
928
+ this.spaceOwnership.delete(fullKey);
929
+ this.keyToSpaceMapping.delete(baseKey);
930
+
931
+ this.debug.log(`📦 Deleted data for key: ${fullKey}`);
591
932
 
592
933
  // Emit deletion event
593
- this.emit('dataDeleted', { key, keyId });
934
+ this.emit('dataDeleted', { key: fullKey, keyId });
594
935
 
595
936
  return true;
596
937
  } catch (error) {
597
- console.error(`Failed to delete data for key ${key}:`, error);
938
+ this.debug.error(`Failed to delete data for key ${fullKey}:`, error);
598
939
  throw error;
599
940
  }
600
941
  }
@@ -612,7 +953,7 @@ export class DistributedStorageManager extends EventEmitter {
612
953
  // Subscribe to the WebDHT key
613
954
  const currentValue = await this.webDHT.subscribe(`storage:${key}`);
614
955
 
615
- console.log(`📦 Subscribed to storage key: ${key}`);
956
+ this.debug.log(`📦 Subscribed to storage key: ${key}`);
616
957
 
617
958
  return currentValue;
618
959
  }
@@ -627,7 +968,7 @@ export class DistributedStorageManager extends EventEmitter {
627
968
  }
628
969
 
629
970
  await this.webDHT.unsubscribe(`storage:${key}`);
630
- console.log(`📦 Unsubscribed from storage key: ${key}`);
971
+ this.debug.log(`📦 Unsubscribed from storage key: ${key}`);
631
972
  }
632
973
 
633
974
  /**
@@ -673,7 +1014,10 @@ export class DistributedStorageManager extends EventEmitter {
673
1014
  * @returns {Promise<boolean>} Success status
674
1015
  */
675
1016
  async grantAccess(key, peerId) {
676
- const keyId = await this.webDHT.generateKeyId(key);
1017
+ // Resolve the key to its actual storage location
1018
+ const resolved = await this.resolveKey(key);
1019
+ const { fullKey, keyId } = resolved;
1020
+
677
1021
  const accessControl = this.accessControl.get(keyId);
678
1022
  const metadata = this.storageMetadata.get(keyId);
679
1023
 
@@ -692,16 +1036,16 @@ export class DistributedStorageManager extends EventEmitter {
692
1036
 
693
1037
  // Update the stored metadata
694
1038
  try {
695
- const currentPayload = await this.webDHT.get(`storage:${key}`);
1039
+ const currentPayload = await this.webDHT.get(`storage:${fullKey}`);
696
1040
  if (currentPayload) {
697
1041
  currentPayload.metadata = metadata;
698
- await this.webDHT.update(`storage:${key}`, currentPayload);
1042
+ await this.webDHT.update(`storage:${fullKey}`, currentPayload);
699
1043
  }
700
1044
 
701
- console.log(`📦 Granted access to peer ${peerId.substring(0, 8)}... for key: ${key}`);
1045
+ this.debug.log(`📦 Granted access to peer ${peerId.substring(0, 8)}... for key: ${fullKey}`);
702
1046
 
703
1047
  // Emit access granted event
704
- this.emit('accessGranted', { key, keyId, peerId });
1048
+ this.emit('accessGranted', { key: fullKey, keyId, peerId });
705
1049
 
706
1050
  return true;
707
1051
  } catch (error) {
@@ -719,7 +1063,10 @@ export class DistributedStorageManager extends EventEmitter {
719
1063
  * @returns {Promise<boolean>} Success status
720
1064
  */
721
1065
  async revokeAccess(key, peerId) {
722
- const keyId = await this.webDHT.generateKeyId(key);
1066
+ // Resolve the key to its actual storage location
1067
+ const resolved = await this.resolveKey(key);
1068
+ const { fullKey, keyId } = resolved;
1069
+
723
1070
  const accessControl = this.accessControl.get(keyId);
724
1071
  const metadata = this.storageMetadata.get(keyId);
725
1072
 
@@ -734,16 +1081,16 @@ export class DistributedStorageManager extends EventEmitter {
734
1081
 
735
1082
  // Update the stored metadata
736
1083
  try {
737
- const currentPayload = await this.webDHT.get(`storage:${key}`);
1084
+ const currentPayload = await this.webDHT.get(`storage:${fullKey}`);
738
1085
  if (currentPayload) {
739
1086
  currentPayload.metadata = metadata;
740
- await this.webDHT.update(`storage:${key}`, currentPayload);
1087
+ await this.webDHT.update(`storage:${fullKey}`, currentPayload);
741
1088
  }
742
1089
 
743
- console.log(`📦 Revoked access from peer ${peerId.substring(0, 8)}... for key: ${key}`);
1090
+ this.debug.log(`📦 Revoked access from peer ${peerId.substring(0, 8)}... for key: ${fullKey}`);
744
1091
 
745
1092
  // Emit access revoked event
746
- this.emit('accessRevoked', { key, keyId, peerId });
1093
+ this.emit('accessRevoked', { key: fullKey, keyId, peerId });
747
1094
 
748
1095
  return true;
749
1096
  } catch (error) {
@@ -827,7 +1174,7 @@ export class DistributedStorageManager extends EventEmitter {
827
1174
  this.storageMetadata.delete(keyId);
828
1175
  this.accessControl.delete(keyId);
829
1176
  this.ownedKeys.delete(keyId);
830
- console.log(`📦 Cleaned up expired metadata for key: ${metadata.key}`);
1177
+ this.debug.log(`📦 Cleaned up expired metadata for key: ${metadata.key}`);
831
1178
  }
832
1179
  }
833
1180
 
@@ -835,7 +1182,7 @@ export class DistributedStorageManager extends EventEmitter {
835
1182
  for (const [keyId, crdtState] of this.crdtStates.entries()) {
836
1183
  if (crdtState.operations.length > 100) {
837
1184
  crdtState.operations = crdtState.operations.slice(-100);
838
- console.log(`📦 Cleaned up old CRDT operations for key: ${keyId.substring(0, 8)}...`);
1185
+ this.debug.log(`📦 Cleaned up old CRDT operations for key: ${keyId.substring(0, 8)}...`);
839
1186
  }
840
1187
  }
841
1188
  }
@@ -872,12 +1219,12 @@ export class DistributedStorageManager extends EventEmitter {
872
1219
  });
873
1220
  }
874
1221
  } catch (error) {
875
- console.warn(`Failed to backup key ${metadata.key}:`, error);
1222
+ this.debug.warn(`Failed to backup key ${metadata.key}:`, error);
876
1223
  }
877
1224
  }
878
1225
  }
879
1226
 
880
- console.log(`📦 Created backup with ${backupData.keys.length} keys`);
1227
+ this.debug.log(`📦 Created backup with ${backupData.keys.length} keys`);
881
1228
  return backupData;
882
1229
  }
883
1230
 
@@ -920,11 +1267,11 @@ export class DistributedStorageManager extends EventEmitter {
920
1267
  key: keyData.key,
921
1268
  error: error.message
922
1269
  });
923
- console.warn(`Failed to restore key ${keyData.key}:`, error);
1270
+ this.debug.warn(`Failed to restore key ${keyData.key}:`, error);
924
1271
  }
925
1272
  }
926
1273
 
927
- console.log(`📦 Restore complete: ${results.restored} restored, ${results.skipped} skipped, ${results.failed} failed`);
1274
+ this.debug.log(`📦 Restore complete: ${results.restored} restored, ${results.skipped} skipped, ${results.failed} failed`);
928
1275
  return results;
929
1276
  }
930
1277
 
@@ -1006,7 +1353,7 @@ export class DistributedStorageManager extends EventEmitter {
1006
1353
  });
1007
1354
 
1008
1355
  await Promise.allSettled(storePromises);
1009
- console.log(`📦 Bulk store complete: ${results.stored} stored, ${results.failed} failed`);
1356
+ this.debug.log(`📦 Bulk store complete: ${results.stored} stored, ${results.failed} failed`);
1010
1357
  return results;
1011
1358
  }
1012
1359
 
@@ -1024,7 +1371,7 @@ export class DistributedStorageManager extends EventEmitter {
1024
1371
  const value = await this.retrieve(key, options);
1025
1372
  results[key] = value;
1026
1373
  } catch (error) {
1027
- console.warn(`Failed to retrieve key ${key}:`, error);
1374
+ this.debug.warn(`Failed to retrieve key ${key}:`, error);
1028
1375
  results[key] = null;
1029
1376
  }
1030
1377
  });
@@ -1108,7 +1455,7 @@ export class DistributedStorageManager extends EventEmitter {
1108
1455
  await this.subscribe(key);
1109
1456
  subscriptions.add(key);
1110
1457
  } catch (error) {
1111
- console.warn(`Failed to subscribe to key ${key}:`, error);
1458
+ this.debug.warn(`Failed to subscribe to key ${key}:`, error);
1112
1459
  }
1113
1460
  }
1114
1461
 
@@ -1129,7 +1476,7 @@ export class DistributedStorageManager extends EventEmitter {
1129
1476
  try {
1130
1477
  await this.unsubscribe(key);
1131
1478
  } catch (error) {
1132
- console.warn(`Failed to unsubscribe from key ${key}:`, error);
1479
+ this.debug.warn(`Failed to unsubscribe from key ${key}:`, error);
1133
1480
  }
1134
1481
  }
1135
1482
 
@@ -1145,8 +1492,24 @@ export class DistributedStorageManager extends EventEmitter {
1145
1492
  * @returns {Promise<Object|null>} Key information or null if not found
1146
1493
  */
1147
1494
  async getKeyInfo(key) {
1148
- const keyId = await this.webDHT.generateKeyId(key);
1149
- const metadata = this.storageMetadata.get(keyId);
1495
+ // Resolve the key to its actual storage location
1496
+ const resolved = await this.resolveKey(key);
1497
+ const { fullKey, keyId } = resolved;
1498
+
1499
+ let metadata = this.storageMetadata.get(keyId);
1500
+
1501
+ // If metadata is not found locally, try to retrieve it from the network
1502
+ if (!metadata) {
1503
+ try {
1504
+ const existingData = await this.retrieve(fullKey);
1505
+ if (existingData !== null) {
1506
+ // Metadata should now be available after retrieve
1507
+ metadata = this.storageMetadata.get(keyId);
1508
+ }
1509
+ } catch (error) {
1510
+ this.debug.warn(`Failed to retrieve metadata for key ${key}:`, error);
1511
+ }
1512
+ }
1150
1513
 
1151
1514
  if (!metadata) {
1152
1515
  return null;
@@ -1180,7 +1543,7 @@ export class DistributedStorageManager extends EventEmitter {
1180
1543
  }
1181
1544
 
1182
1545
  this.enabled = true;
1183
- console.log('📦 Distributed storage enabled');
1546
+ this.debug.log('📦 Distributed storage enabled');
1184
1547
  this.emit('storageEnabled');
1185
1548
  }
1186
1549
 
@@ -1190,7 +1553,7 @@ export class DistributedStorageManager extends EventEmitter {
1190
1553
  */
1191
1554
  async disable() {
1192
1555
  this.enabled = false;
1193
- console.log('📦 Distributed storage disabled');
1556
+ this.debug.log('📦 Distributed storage disabled');
1194
1557
  this.emit('storageDisabled');
1195
1558
  }
1196
1559
 
@@ -1215,7 +1578,7 @@ export class DistributedStorageManager extends EventEmitter {
1215
1578
  try {
1216
1579
  await this.delete(metadata.key);
1217
1580
  } catch (error) {
1218
- console.warn(`Failed to delete key ${metadata.key} during clear:`, error);
1581
+ this.debug.warn(`Failed to delete key ${metadata.key} during clear:`, error);
1219
1582
  }
1220
1583
  }
1221
1584
  }
@@ -1225,8 +1588,10 @@ export class DistributedStorageManager extends EventEmitter {
1225
1588
  this.accessControl.clear();
1226
1589
  this.crdtStates.clear();
1227
1590
  this.ownedKeys.clear();
1591
+ this.spaceOwnership.clear();
1592
+ this.keyToSpaceMapping.clear();
1228
1593
 
1229
- console.log('📦 All stored data cleared');
1594
+ this.debug.log('📦 All stored data cleared');
1230
1595
  this.emit('storageCleared');
1231
1596
  }
1232
1597
 
@@ -1240,8 +1605,15 @@ export class DistributedStorageManager extends EventEmitter {
1240
1605
 
1241
1606
  for (const keyId of this.ownedKeys) {
1242
1607
  const metadata = this.storageMetadata.get(keyId);
1243
- if (metadata && metadata.key.startsWith(prefix)) {
1244
- keys.push(metadata.key);
1608
+ if (metadata) {
1609
+ // Check both the full key and the base key for prefix match
1610
+ const fullKey = metadata.key;
1611
+ const baseKey = metadata.baseKey;
1612
+
1613
+ if (fullKey.startsWith(prefix) || baseKey.startsWith(prefix)) {
1614
+ // Return the base key for user convenience (since they stored with base key)
1615
+ keys.push(baseKey);
1616
+ }
1245
1617
  }
1246
1618
  }
1247
1619
 
@@ -1262,7 +1634,7 @@ export class DistributedStorageManager extends EventEmitter {
1262
1634
  await this.delete(key);
1263
1635
  deletedCount++;
1264
1636
  } catch (error) {
1265
- console.warn(`Failed to delete key ${key} during bulk delete:`, error);
1637
+ this.debug.warn(`Failed to delete key ${key} during bulk delete:`, error);
1266
1638
  }
1267
1639
  }
1268
1640
 
@@ -1331,4 +1703,20 @@ export class DistributedStorageManager extends EventEmitter {
1331
1703
 
1332
1704
  return results;
1333
1705
  }
1706
+
1707
+ /**
1708
+ * Get a lexical interface for GUN-like chaining
1709
+ * @returns {Proxy} Lexical interface
1710
+ */
1711
+ lexical() {
1712
+ return createLexicalInterface(this);
1713
+ }
1714
+
1715
+ /**
1716
+ * Alias for lexical() - more GUN-like naming
1717
+ * @returns {Proxy} Lexical interface
1718
+ */
1719
+ gun() {
1720
+ return this.lexical();
1721
+ }
1334
1722
  }