holosphere 1.1.21 → 1.3.0-alpha3

package/global.js

@@ -65,11 +65,15 @@ export async function putGlobal(holoInstance, tableName, data, password = null)
 
         return new Promise((resolve, reject) => {
             try {
-                // Create a copy of data without the _meta field if it exists
+                // Create a copy of data, stripping read-side envelopes that
+                // must never be persisted (they're attached at resolution time).
                 let dataToStore = { ...data };
                 if (dataToStore._meta !== undefined) {
                     delete dataToStore._meta;
                 }
+                if (dataToStore._hologram !== undefined) {
+                    delete dataToStore._hologram;
+                }
                 const payload = JSON.stringify(dataToStore);
 
                 // Check if the data being stored is a hologram
@@ -327,8 +331,12 @@ export async function getAllGlobal(holoInstance, tableName, password = null) {
                 user.get('private').get(tableName) :
                 holoInstance.gun.get(holoInstance.appname).get(tableName);
 
-            // PASS 1: Get shallow node to determine expected item count
-            dataPath.once((data) => {
+            // PASS 1: Get shallow node to determine expected item count.
+            // Retry once if empty — Gun's .once() reads from local cache, which
+            // may be cold immediately after startup before peers have synced.
+            const shallowOnce = () => new Promise((res) => dataPath.once((d) => res(d)));
+
+            const processShallow = (data) => {
                 if (!data) {
                     resolve([]);
                     return;
@@ -350,60 +358,63 @@ export async function getAllGlobal(holoInstance, tableName, password = null) {
                     return;
                 }
 
-                // PASS 2: Use map().once() to iterate and get full item data
-                let receivedCount = 0;
-
-                dataPath.map().once(async (itemData, key) => {
-                    if (!itemData || key === '_') {
-                        receivedCount++;
-                        if (receivedCount >= expectedCount) {
-                            await Promise.all(pendingProcessing);
-                            resolve(output);
-                        }
-                        return;
-                    }
-
-                    const processingPromise = (async () => {
-                        try {
-                            const parsed = await holoInstance.parse(itemData);
-                            if (!parsed) return;
+                // PASS 2: iterate explicitly over the filtered keys.
+                // Avoid dataPath.map().once() — it fires for null tombstone
+                // siblings and can resolve before real items are processed.
+                const processItem = async (itemData, key) => {
+                    if (!itemData) return;
+                    try {
+                        const parsed = await holoInstance.parse(itemData);
+                        if (!parsed) return;
 
-                            if (holoInstance.isHologram(parsed)) {
-                                const resolved = await holoInstance.resolveHologram(parsed, {
-                                    followHolograms: true
-                                });
+                        if (holoInstance.isHologram(parsed)) {
+                            const resolved = await holoInstance.resolveHologram(parsed, {
+                                followHolograms: true
+                            });
 
-                                if (resolved === null) {
-                                    try {
-                                        await holoInstance.deleteGlobal(tableName, key, password);
-                                    } catch (deleteError) {
-                                        console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
-                                    }
-                                    return;
+                            if (resolved === null) {
+                                try {
+                                    await holoInstance.deleteGlobal(tableName, key, password);
+                                } catch (deleteError) {
+                                    console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
                                 }
+                                return;
+                            }
 
-                                if (resolved !== parsed) {
-                                    output.push(resolved);
-                                } else {
-                                    output.push(parsed);
-                                }
+                            if (resolved !== parsed) {
+                                output.push(resolved);
                             } else {
                                 output.push(parsed);
                             }
-                        } catch (error) {
-                            console.error('Error parsing data:', error);
+                        } else {
+                            output.push(parsed);
                         }
-                    })();
-
-                    pendingProcessing.push(processingPromise);
-                    receivedCount++;
+                    } catch (error) {
+                        console.error('Error parsing data:', error);
+                    }
+                };
 
-                    if (receivedCount >= expectedCount) {
-                        await Promise.all(pendingProcessing);
-                        resolve(output);
+                Promise.all(keys.map((key) => {
+                    const inline = data[key];
+                    if (typeof inline !== 'object' || inline === null) {
+                        return processItem(inline, key);
                     }
-                });
-            });
+                    return new Promise((resolveItem) => {
+                        dataPath.get(key).once((itemData) => {
+                            processItem(itemData, key).then(resolveItem, resolveItem);
+                        });
+                    });
+                })).then(() => resolve(output));
+            };
+
+            (async () => {
+                let data = await shallowOnce();
+                if (!data) {
+                    await new Promise(r => setTimeout(r, 1500));
+                    data = await shallowOnce();
+                }
+                processShallow(data);
+            })();
         });
     } catch (error) {
         console.error('Error in getAllGlobal:', error);
@@ -730,11 +741,70 @@ export async function deleteAllGlobal(holoInstance, tableName, password = null)
     }
 } 
 
+/**
+ * Subscribe to real-time changes in a global table.
+ * @param {HoloSphere} holoInstance - The HoloSphere instance.
+ * @param {string} tableName - The table name to subscribe to.
+ * @param {string|null} key - Specific key to subscribe to, or null for all keys.
+ * @param {function} callback - Callback for data changes.
+ * @param {object} [options] - Subscription options.
+ * @param {boolean} [options.realtimeOnly] - Only fire for new changes.
+ * @returns {Promise<{ unsubscribe: () => void }>}
+ */
+export async function subscribeGlobal(holoInstance, tableName, key, callback, options = {}) {
+    const dataPath = holoInstance.gun.get(holoInstance.appname).get(tableName);
+    let active = true;
+
+    if (key) {
+        // Subscribe to a specific key
+        dataPath.get(key).on(async (data) => {
+            if (!active || !data) return;
+            try {
+                const parsed = await holoInstance.parse(data);
+                if (parsed) callback(parsed, key);
+            } catch (e) {
+                console.warn('[subscribeGlobal] Error parsing data:', e);
+            }
+        });
+    } else {
+        // Subscribe to all keys in the table
+        dataPath.map().on(async (data, k) => {
+            if (!active || !data || k === '_') return;
+            try {
+                const parsed = await holoInstance.parse(data);
+                if (parsed) callback(parsed, k);
+            } catch (e) {
+                console.warn('[subscribeGlobal] Error parsing data:', e);
+            }
+        });
+    }
+
+    return {
+        unsubscribe: () => {
+            active = false;
+            if (key) {
+                dataPath.get(key).off();
+            } else {
+                dataPath.off();
+            }
+        },
+        stop: () => {
+            active = false;
+            if (key) {
+                dataPath.get(key).off();
+            } else {
+                dataPath.off();
+            }
+        }
+    };
+}
+
 // Export all global operations as default
 export default {
     putGlobal,
     getGlobal,
     getAllGlobal,
     deleteGlobal,
-    deleteAllGlobal
-}; 
+    deleteAllGlobal,
+    subscribeGlobal
+};

package/handshake-shim.js

@@ -0,0 +1,321 @@
+/**
+ * GunDB-based federation handshake protocol for HoloSphere v1.3
+ * Replaces Nostr NIP-44 encrypted DMs with GunDB DM channels.
+ * Same protocol payloads (JSON with type: federation_request/response/update),
+ * different transport layer.
+ */
+
+/**
+ * Generate a unique message ID
+ */
+function generateMessageId() {
+    return Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 10);
+}
+
+/**
+ * Get the DM path for a recipient in GunDB
+ */
+function getDMPath(holosphere, recipientPubKey) {
+    return holosphere.gun.get(holosphere.appname).get('_dm').get(recipientPubKey);
+}
+
+/**
+ * Write a DM to a recipient's channel
+ */
+async function sendDM(holosphere, recipientPubKey, message) {
+    const msgId = generateMessageId();
+    const payload = JSON.stringify({
+        ...message,
+        id: msgId,
+        timestamp: Date.now()
+    });
+
+    return new Promise((resolve) => {
+        getDMPath(holosphere, recipientPubKey).get(msgId).put(payload, (ack) => {
+            if (ack.err) {
+                console.warn('[handshake] Failed to send DM:', ack.err);
+                resolve({ success: false, error: ack.err });
+            } else {
+                resolve({ success: true, id: msgId });
+            }
+        });
+    });
+}
+
+/**
+ * Subscribe to federation DMs for a public key.
+ * Listens for incoming federation requests, responses, and updates.
+ *
+ * @param {object} holosphere - The HoloSphere instance
+ * @param {string|Uint8Array} privateKey - The user's private key (for identity)
+ * @param {string} publicKey - The user's public key
+ * @param {object} handlers - Event handlers
+ * @param {function} handlers.onRequest - Called when a federation request is received
+ * @param {function} handlers.onResponse - Called when a federation response is received
+ * @param {function} handlers.onUpdate - Called when a federation update is received
+ * @param {function} handlers.onUpdateResponse - Called when an update response is received
+ * @returns {function} Unsubscribe function
+ */
+export function subscribeToFederationDMs(holosphere, privateKey, publicKey, handlers) {
+    const dmPath = getDMPath(holosphere, publicKey);
+    let active = true;
+    const processedMessages = new Set();
+
+    dmPath.map().on((data, key) => {
+        if (!active || !data || key === '_') return;
+
+        // Avoid processing the same message twice
+        if (processedMessages.has(key)) return;
+        processedMessages.add(key);
+
+        try {
+            const message = typeof data === 'string' ? JSON.parse(data) : data;
+            const senderPubKey = message.senderPubKey || message.sender || '';
+
+            switch (message.type) {
+                case 'federation_request':
+                    if (handlers.onRequest) {
+                        handlers.onRequest(message, senderPubKey);
+                    }
+                    break;
+                case 'federation_response':
+                    if (handlers.onResponse) {
+                        handlers.onResponse(message, senderPubKey);
+                    }
+                    break;
+                case 'federation_update':
+                    if (handlers.onUpdate) {
+                        handlers.onUpdate(message, senderPubKey);
+                    }
+                    break;
+                case 'federation_update_response':
+                    if (handlers.onUpdateResponse) {
+                        handlers.onUpdateResponse(message, senderPubKey);
+                    }
+                    break;
+                default:
+                    console.log('[handshake] Unknown DM type:', message.type);
+            }
+        } catch (e) {
+            // Skip unparseable messages
+        }
+    });
+
+    // Return unsubscribe function
+    return () => {
+        active = false;
+        dmPath.off();
+    };
+}
+
+/**
+ * Initiate a federation handshake with a partner.
+ *
+ * @param {object} holosphere - The HoloSphere instance
+ * @param {string|Uint8Array} privateKey - The initiator's private key
+ * @param {object} params - Handshake parameters
+ * @param {string} params.partnerPubKey - The partner's public key
+ * @param {string} params.holonId - The initiator's holon ID
+ * @param {string} params.holonName - The initiator's holon name
+ * @param {object} [params.lensConfig] - Lens configuration to share
+ * @param {string} [params.message] - Optional message
+ * @returns {Promise<{ success: boolean, requestId?: string }>}
+ */
+export async function initiateFederationHandshake(holosphere, privateKey, params) {
+    const {
+        partnerPubKey,
+        holonId,
+        holonName,
+        lensConfig = {},
+        message = ''
+    } = params;
+
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const request = {
+        type: 'federation_request',
+        senderPubKey,
+        senderHolonId: holonId,
+        senderHolonName: holonName,
+        lensConfig,
+        message,
+        status: 'pending'
+    };
+
+    const result = await sendDM(holosphere, partnerPubKey, request);
+    if (result.success) {
+        console.log('[handshake] Federation request sent to:', partnerPubKey?.slice(0, 8));
+    }
+    return { success: result.success, requestId: result.id };
+}
+
+/**
+ * Accept a federation request.
+ *
+ * @param {object} holosphere - The HoloSphere instance
+ * @param {string|Uint8Array} privateKey - The responder's private key
+ * @param {object} params - Accept parameters
+ * @param {string} params.requesterPubKey - The requester's public key
+ * @param {string} params.holonId - The responder's holon ID
+ * @param {string} params.holonName - The responder's holon name
+ * @param {object} [params.lensConfig] - Lens configuration
+ * @param {string} [params.requestId] - Original request ID
+ * @returns {Promise<{ success: boolean }>}
+ */
+export async function acceptFederationRequest(holosphere, privateKey, params) {
+    const {
+        requesterPubKey,
+        holonId,
+        holonName,
+        lensConfig = {},
+        requestId
+    } = params;
+
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const response = {
+        type: 'federation_response',
+        senderPubKey,
+        responderHolonId: holonId,
+        responderHolonName: holonName,
+        lensConfig,
+        status: 'accepted',
+        requestId
+    };
+
+    // Add the requester as an allowed author
+    if (requesterPubKey) {
+        holosphere.addAllowedAuthor(requesterPubKey);
+    }
+
+    return sendDM(holosphere, requesterPubKey, response);
+}
+
+/**
+ * Reject a federation request.
+ */
+export async function rejectFederationRequest(holosphere, privateKey, params) {
+    const { requesterPubKey, holonId, reason = '', requestId } = params;
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const response = {
+        type: 'federation_response',
+        senderPubKey,
+        responderHolonId: holonId,
+        status: 'rejected',
+        reason,
+        requestId
+    };
+
+    return sendDM(holosphere, requesterPubKey, response);
+}
+
+/**
+ * Process a received federation response.
+ * Creates the federation relationship on the initiator's side.
+ *
+ * @param {object} holosphere - The HoloSphere instance
+ * @param {object} response - The response object
+ * @param {string} senderPubKey - The responder's public key
+ * @param {object} options - Processing options
+ * @param {string} options.holonId - The initiator's holon ID
+ * @param {string[]} [options.inboundLenses] - Lenses to accept inbound data for
+ * @returns {Promise<{ success: boolean }>}
+ */
+export async function processFederationResponse(holosphere, response, senderPubKey, options = {}) {
+    const { holonId, inboundLenses = [] } = options;
+
+    if (response.status !== 'accepted') {
+        return { success: false, reason: 'not_accepted' };
+    }
+
+    try {
+        // Add the responder as an allowed author
+        if (senderPubKey) {
+            holosphere.addAllowedAuthor(senderPubKey);
+        }
+
+        // Store the responder's holon ID for federation lookup
+        const responderHolonId = response.responderHolonId || senderPubKey;
+
+        console.log('[handshake] Processing accepted federation from:', responderHolonId?.slice(0, 8));
+        return { success: true, responderHolonId };
+    } catch (error) {
+        console.error('[handshake] Error processing federation response:', error);
+        return { success: false, error: error.message };
+    }
+}
+
+/**
+ * Request a federation update (e.g., change shared lenses).
+ *
+ * @param {object} holosphere - The HoloSphere instance
+ * @param {string|Uint8Array} privateKey - The requester's private key
+ * @param {object} params - Update parameters
+ * @param {string} params.partnerPubKey - The partner's public key
+ * @param {string} params.holonId - The requester's holon ID
+ * @param {string} params.holonName - The requester's holon name
+ * @param {object} params.newLensConfig - The new lens configuration
+ * @param {string} [params.message] - Optional message
+ * @returns {Promise<{ success: boolean }>}
+ */
+export async function requestFederationUpdate(holosphere, privateKey, params) {
+    const {
+        partnerPubKey,
+        holonId,
+        holonName,
+        newLensConfig = {},
+        message = ''
+    } = params;
+
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const update = {
+        type: 'federation_update',
+        senderPubKey,
+        senderHolonId: holonId,
+        senderHolonName: holonName,
+        newLensConfig,
+        message
+    };
+
+    return sendDM(holosphere, partnerPubKey, update);
+}
+
+/**
+ * Accept a federation update request.
+ */
+export async function acceptFederationUpdate(holosphere, privateKey, params) {
+    const { requesterPubKey, holonId, newLensConfig = {}, updateId } = params;
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const response = {
+        type: 'federation_update_response',
+        senderPubKey,
+        responderHolonId: holonId,
+        status: 'accepted',
+        newLensConfig,
+        updateId
+    };
+
+    return sendDM(holosphere, requesterPubKey, response);
+}
+
+/**
+ * Reject a federation update request.
+ */
+export async function rejectFederationUpdate(holosphere, privateKey, params) {
+    const { requesterPubKey, holonId, reason = '', updateId } = params;
+    const senderPubKey = holosphere.client?.publicKey || '';
+
+    const response = {
+        type: 'federation_update_response',
+        senderPubKey,
+        responderHolonId: holonId,
+        status: 'rejected',
+        reason,
+        updateId
+    };
+
+    return sendDM(holosphere, requesterPubKey, response);
+}

package/hologram.js

@@ -78,7 +78,37 @@ export function isHologram(data) {
 }
 
 /**
- * Resolves a hologram to its actual data
+ * Attaches the canonical `_hologram` envelope to data resolved from a soul reference.
+ *
+ * This is the SINGLE source of truth for resolved-hologram metadata in HoloSphere.
+ * Every code path that returns "data resolved from a hologram reference" must go
+ * through this helper so consumers can rely on one shape.
+ *
+ * @param {object} originalData - The data fetched from the source holon/lens/key.
+ * @param {string} hologramSoul - The soul path the hologram pointed at.
+ * @returns {object} - originalData merged with `_hologram: { isHologram, soul, sourceHolon, sourceLens, sourceKey, resolvedAt }`.
+ */
+export function attachHologramMeta(originalData, hologramSoul) {
+    const parts = parseSoulPath(hologramSoul);
+    return {
+        ...originalData,
+        _hologram: {
+            isHologram: true,
+            soul: hologramSoul,
+            sourceHolon: parts?.holon ?? null,
+            sourceLens: parts?.lens ?? null,
+            sourceKey: parts?.key ?? null,
+            resolvedAt: Date.now(),
+        },
+    };
+}
+
+/**
+ * Resolves a hologram to its actual data.
+ *
+ * On success, the returned object spreads `originalData` and attaches the
+ * canonical `_hologram` envelope (see {@link attachHologramMeta}).
+ *
  * @param {HoloSphere} holoInstance - The HoloSphere instance.
  * @param {object} hologram - The hologram to resolve
  * @param {object} [options] - Optional parameters
@@ -86,7 +116,7 @@ export function isHologram(data) {
  * @param {Set<string>} [options.visited] - Internal use: Tracks visited souls to prevent loops
  * @param {number} [options.maxDepth=10] - Maximum resolution depth to prevent infinite loops
  * @param {number} [options.currentDepth=0] - Current resolution depth
- * @returns {Promise<object|null>} - The resolved data, null if resolution failed due to target not found, or the original hologram for circular/invalid cases.
+ * @returns {Promise<object|null>} - The resolved data with `_hologram` attached, null if resolution failed due to target not found, or the original hologram for circular/invalid cases.
  */
 export async function resolveHologram(holoInstance, hologram, options = {}) {
     if (!isHologram(hologram)) {
@@ -143,16 +173,9 @@ export async function resolveHologram(holoInstance, hologram, options = {}) {
                 );
 
             if (originalData && !originalData._invalidHologram) {
-                    // Structure for the returned object - isHologram (top-level) is removed
-                    return {
-                        ...originalData,
-                        _meta: {
-                            ...(originalData._meta || {}), // Preserve original _meta
-                            resolvedFromHologram: true,    // This is now the primary indicator
-                        hologramSoul: hologram.soul,   // Clarified meta field
-                        resolutionDepth: currentDepth
-                        }
-                    };
+                    // Attach the canonical `_hologram` envelope. This is the only
+                    // resolved-hologram indicator HoloSphere emits.
+                    return attachHologramMeta(originalData, hologram.soul);
                 } else {
                 console.warn(`!!! Original data NOT FOUND for soul: ${hologram.soul}. Removing broken hologram.`);
                 
@@ -179,5 +202,6 @@ export default {
     createHologram,
     parseSoulPath,
     isHologram,
-    resolveHologram
-}; 
+    resolveHologram,
+    attachHologramMeta
+};