holosphere 2.0.0-alpha21 → 2.0.0-alpha23

package/src/storage/global-tables.js

@@ -8,7 +8,7 @@
  * @module storage/global-tables
  */
 
-import { write, read, readAll, update, deleteData, deleteAll, subscribe } from './unified-storage.js';
+import { write, read, readAll, update, deleteData, deleteAll, subscribe } from './nostr-wrapper.js';
 
 /**
  * Write data to global table

package/src/storage/nostr-wrapper.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Nostr Storage Wrapper.
  *
- * Drop-in replacement for gun-wrapper.js providing the same API.
+ * High-level CRUD API for Nostr-based distributed P2P storage.
  * Handles path construction and CRUD operations using Nostr relays
  * for distributed P2P storage.
  *
@@ -62,6 +62,7 @@ export async function write(client, path, data, options = {}) {
     const putOptions = {
       ...(options.signingKey && { signingKey: options.signingKey }),
       ...(options.waitForRelays && { waitForRelays: options.waitForRelays }),
+      ...(options.lensKey && { lensKey: options.lensKey }),
     };
     const result = await nostrPut(client, path, data, putOptions);
     // Check if at least one relay accepted the event
@@ -126,9 +127,9 @@ export async function readAll(client, path, options = {}) {
  * @param {Object} updates - Fields to update
  * @returns {Promise<boolean>} Success indicator
  */
-export async function update(client, path, updates) {
+export async function update(client, path, updates, options = {}) {
   try {
-    const existing = await nostrGet(client, path);
+    const existing = await nostrGet(client, path, 30000, options);
 
     if (!existing || !existing.id || existing._deleted) {
       return false; // Not found or deleted
@@ -141,8 +142,11 @@ export async function update(client, path, updates) {
     if (!merged._meta) merged._meta = {};
     merged._meta.timestamp = Date.now();
 
-    // Write merged data
-    const result = await nostrPut(client, path, merged);
+    // Write merged data (pass lensKey for re-encryption)
+    const putOptions = {
+      ...(options.lensKey && { lensKey: options.lensKey }),
+    };
+    const result = await nostrPut(client, path, merged, putOptions);
     // If no relays (testing mode), consider it successful if event was created
     const success = result.results.length === 0 ? true : result.results.some(r => r.status === 'fulfilled');
     return success;

package/src/subscriptions/manager.js

@@ -4,7 +4,7 @@
  * @module subscriptions/manager
  */
 
-import { subscribe } from '../storage/unified-storage.js';
+import { subscribe } from '../storage/nostr-wrapper.js';
 import { resolveHologram } from '../federation/hologram.js';
 
 /**

package/types/index.d.ts

@@ -1,56 +1,91 @@
 // Type declarations for holosphere
-// This file tells TypeScript to skip type checking the bundled JS files
 
 declare module 'holosphere' {
   export class HoloSphere {
     constructor(config?: any);
     init(): Promise<void>;
+    ready(): Promise<void>;
 
     // Core CRUD operations
-    get(holonId: string, lens: string, key?: string): Promise<any>;
-    getAll(holonId: string, lens: string): Promise<Record<string, any>>;
-    put(holonId: string, lens: string, value: any): Promise<void>;
-    put(holonId: string, lens: string, key: string, value: any): Promise<void>;
-    delete(holonId: string, lens: string, key?: string): Promise<void>;
-    read(holonId: string, lens: string, key?: string): Promise<any>;
+    write(holonId: string, lens: string, data: any, options?: any): Promise<boolean>;
+    read(holonId: string, lens: string, key?: string, options?: any): Promise<any>;
+    update(holonId: string, lens: string, dataId: string, updates: any, options?: any): Promise<boolean>;
+    delete(holonId: string, lens: string, key?: string, options?: any): Promise<boolean>;
+    deleteAll(holonId: string, lens: string, options?: any): Promise<boolean>;
+
+    // CRUD aliases (same as above)
+    put(holonId: string, lens: string, data: any, options?: any): Promise<boolean>;
+    get(holonId: string, lens: string, key?: string, options?: any): Promise<any>;
+    getAll(holonId: string, lens: string, options?: any): Promise<any[]>;
+    remove(holonId: string, lens: string, key?: string, options?: any): Promise<boolean>;
 
     // Subscription
-    subscribe(holonId: string, lens: string, callback: (data: any, key: string) => void): Promise<{ unsubscribe: () => void }>;
+    subscribe(holonId: string, lens: string, callback: (data: any, key: string) => void, options?: any): { unsubscribe: () => void };
 
     // Profile operations
     getHolonProfile(holonId: string): Promise<any>;
     setHolonProfile(holonId: string, profile: any): Promise<void>;
 
     // Federation operations
-    federate(sourceHolonId: string, targetHolonId: string, sourceKey?: string | null, targetKey?: string | null, bidirectional?: boolean, permissions?: any): Promise<void>;
-    federateHolon(holonId: string, targetHolonId: string, options?: any): Promise<void>;
+    federate(source: string, target: string, lensName: string, options?: any): Promise<any>;
+    unfederate(source: string, target: string, lensName: string): Promise<boolean>;
+    federateHolon(holonId: string, targetHolonId: string, options?: any): Promise<boolean>;
+    unfederateHolon(holonId: string, targetHolonId: string): Promise<boolean>;
     getFederation(holonId: string): Promise<any>;
+    addFederatedHolosphere(pubKey: string, options?: any): Promise<boolean>;
+    removeFederatedHolosphere(pubKey: string): Promise<boolean>;
+    getFederatedHolospheres(): Promise<string[]>;
+    getFederationRegistry(): Promise<any>;
+    isFederated(pubKey: string): Promise<boolean>;
+
+    // Share protocol (Hologram DM as Federation)
+    share(target: string, lens: string, item?: string | null, opts?: {
+      keys?: Array<{ path: string; key: string }>;
+      msg?: string;
+      sourceHolon?: string;
+    }): Promise<{ success: boolean; error?: string }>;
+    accept(sharePayload: SharePayload, senderPubKey: string, opts?: {
+      holonId?: string;
+      msg?: string;
+    }): Promise<{ success: boolean; error?: string }>;
+    reject(sharePayload: SharePayload, senderPubKey: string, opts?: {
+      msg?: string;
+    }): Promise<{ success: boolean; error?: string }>;
+
+    // Propagation
     propagate(holonId: string, lens: string, key: string, value: any): Promise<void>;
-    propagateData(holonId: string, lens: string, data: any): Promise<void>;
+    propagateData(data: any, sourceHolon: string, targetHolon: string, lensName: string, options?: any): Promise<any>;
 
     // Global operations
-    getGlobal(lens: string, key?: string): Promise<any>;
-    getAllGlobal(lens: string): Promise<Record<string, any>>;
-    writeGlobal(lens: string, key: string, value: any): Promise<void>;
-
-    // Internal properties (exposed for advanced use)
-    gun?: any;
-    client?: any;
+    writeGlobal(table: string, data: any): Promise<void>;
+    readGlobal(table: string, key?: string): Promise<any>;
+    updateGlobal(table: string, key: string, updates: any): Promise<void>;
+    deleteGlobal(table: string, key: string): Promise<void>;
+    getAllGlobal(table: string): Promise<Record<string, any>>;
+
+    // Encryption
+    handleReceivedKeyShare(keyShare: any, senderPubKey: string): boolean;
+    hasLensKey(holonId: string, lensName: string): boolean;
+    isOwnLensKey(holonId: string, lensName: string): boolean;
+    getEncryptionStats(): { ownKeyCount: number; receivedKeyCount: number; totalPartnerGrants: number };
+
+    // Configuration and internal properties
+    config?: { appName: string; [key: string]: any };
+    client?: { publicKey: string; privateKey?: Uint8Array; [key: string]: any };
+    keyStore?: any;
   }
 
-  export class PersistentStorage {
-    init(namespace: string): Promise<void>;
-    put(key: string, event: any): Promise<void>;
-    get(key: string): Promise<any | null>;
-    getAll(prefix: string): Promise<any[]>;
-    delete(key: string): Promise<void>;
-    clear(): Promise<void>;
-    close(): Promise<void>;
+  export class LensKeyStore {
+    getOrCreateKey(lensPath: string, privateKey: string, publicKey: string): { key: Uint8Array; isNew: boolean; wrappedForSelf?: string };
+    getKey(lensPath: string): Uint8Array | null;
+    hasKey(lensPath: string): boolean;
+    isOwnKey(lensPath: string): boolean;
+    storeOwnKey(lensPath: string, key: Uint8Array, wrappedForSelf: string): void;
+    receiveKey(lensPath: string, wrappedKey: string, recipientPrivKey: string, senderPubKey: string): Uint8Array;
+    getStats(): { ownKeyCount: number; receivedKeyCount: number; totalPartnerGrants: number };
   }
 
-  export class IndexedDBStorage extends PersistentStorage {}
-  export class MemoryStorage extends PersistentStorage {}
-  export class FileSystemStorage extends PersistentStorage {}
+  export function buildLensPath(appName: string, holonId: string, lensName: string): string;
 
   export class ChainManager {
     constructor(config?: any);
@@ -79,27 +114,100 @@ declare module 'holosphere' {
   export const ContractABIs: any;
   export const NETWORKS: any;
 
+  export interface SharePayload {
+    id: string;
+    type: 'share';
+    source: string;
+    lens: string;
+    item: string | null;
+    author: string;
+    keys?: Array<{ path: string; key: string }>;
+    msg?: string;
+    timestamp?: number;
+  }
+
+  export interface ShareAckPayload {
+    id: string;
+    type: 'share_ack';
+    source: string;
+    lens: string;
+    item: string | null;
+    author: string;
+    status: 'accepted' | 'rejected';
+    msg?: string;
+    timestamp?: number;
+  }
+
   export class AuthorizationError extends Error {}
   export class ValidationError extends Error {}
 
   export const crypto: any;
   export const federation: any;
   export const handshake: {
-    initiateFederationHandshake(holosphere: HoloSphere, privateKey: string, params: any): Promise<any>;
-    acceptFederationRequest(holosphere: HoloSphere, privateKey: string, params: any): Promise<any>;
-    rejectFederationRequest(holosphere: HoloSphere, privateKey: string, params: any): Promise<any>;
-    subscribeToFederationDMs(client: any, privateKey: string, publicKey: string, handlers: any): () => void;
+    // Request/Response lifecycle
+    initiateFederationHandshake(holosphere: HoloSphere, privateKey: string, params: any): Promise<{ success: boolean; requestId?: string; error?: string }>;
+    acceptFederationRequest(holosphere: HoloSphere, privateKey: string, params: any): Promise<{ success: boolean; requestId?: string; receivedHolograms?: any; error?: string }>;
+    rejectFederationRequest(holosphere: HoloSphere, privateKey: string, params: any): Promise<{ success: boolean; error?: string }>;
+    processFederationResponse(holosphere: HoloSphere, response: any, responderPubKey: string, options?: any): Promise<{ success: boolean; receivedHolograms?: any; error?: string }>;
+
+    // DM operations
+    subscribeToFederationDMs(client: any, privateKey: string, publicKey: string, handlers: any, options?: any): () => void;
+    createFederationResponse(params: any): any;
+    sendFederationResponse(client: any, privateKey: string, recipientPubKey: string, response: any): Promise<boolean>;
+
+    // Validation helpers
+    isFederationRequest(payload: any): boolean;
+    isFederationResponse(payload: any): boolean;
+    normalizeLensConfig(lensConfig: any): any;
+  };
+  export const registry: {
+    addFederatedPartner(client: any, appname: string, partnerPubKey: string, options?: any): Promise<boolean>;
+    removeFederatedPartner(client: any, appname: string, partnerPubKey: string): Promise<boolean>;
+    getFederatedAuthors(client: any, appname: string): Promise<string[]>;
+    getFederationRegistry(client: any, appname: string, options?: any): Promise<any>;
+    isFederated(client: any, appname: string, pubKey: string): Promise<boolean>;
+    getFederatedPartner(client: any, appname: string, partnerPubKey: string): Promise<any>;
+    addCapabilityWriter(client: any, appname: string, writerPubKey: string): Promise<boolean>;
+    getCapabilityWriters(client: any, appname: string): Promise<string[]>;
+    removeCapabilityWriter(client: any, appname: string, writerPubKey: string): Promise<boolean>;
+  };
+  export const nostrUtils: {
+    // npub utilities
+    parseNpubOrHex(input: string): { valid: boolean; hexPubKey?: string; error?: string };
+    hexToNpub(hexPubKey: string): string;
+    npubToHex(npub: string): string | null;
+    isValidNpub(str: string): boolean;
+    shortenNpub(npub: string): string;
+    shortenPubKey(pubKey: string): string;
+    // nsec utilities
+    parseNsecOrHex(input: string): { valid: boolean; hexPrivKey?: string; error?: string };
+    hexToNsec(hexPrivKey: string): string;
+    nsecToHex(nsec: string): string | null;
+    isValidNsec(str: string): boolean;
+    // Key operations
+    generatePrivateKey(): string;
+    getPublicKey(privateKey: string): string;
+    isValidHexPubKey(str: string): boolean;
+    // Byte conversion
+    hexToBytes(hex: string): Uint8Array;
+    bytesToHex(bytes: Uint8Array): string;
+    [key: string]: any;
   };
-  export const hierarchical: any;
-  export const nostrUtils: any;
   export const schema: any;
   export const social: any;
   export const spatial: any;
   export const storage: any;
-  export const subscriptions: any;
+  export const subscriptions: {
+    createSubscription(client: any, path: string, callback: (data: any, key?: string) => void, options?: any): Promise<{ path: string; unsubscribe: () => void }>;
+  };
   export const networks: any;
+  export const hierarchical: any;
 
   export function createHologram(config?: any): any;
+  export function createLensHologram(sourceHolon: string, lensName: string, appname: string, options: { author: string }): any;
+  export function isLensHologram(data: any): boolean;
+  export function sendShare(client: any, privateKey: string, targetPubKey: string, payload: any): Promise<boolean>;
+  export function sendAck(client: any, privateKey: string, targetPubKey: string, payload: any): Promise<boolean>;
   export function createAIServices(config?: any): any;
   export function getNetwork(name: string): any;
   export function getNetworksByType(type: string): any[];
@@ -107,7 +215,7 @@ declare module 'holosphere' {
   export function isNetworkSupported(name: string): boolean;
   export function getAddressUrl(network: string, address: string): string;
   export function getTxUrl(network: string, txHash: string): string;
-  export function matchScope(scope: string, pattern: string): boolean;
+  export function dismissRequest(client: any, appname: string, requestId: string): Promise<void>;
 
   // AI-related exports
   export class Classifier {}

package/bin/holosphere-activitypub.js

@@ -1,158 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * HoloSphere ActivityPub Server CLI
- *
- * Starts a self-hosted ActivityPub server for HoloSphere federation.
- *
- * Usage:
- *   holosphere-activitypub [options]
- *
- * Options:
- *   -p, --port <port>       Port to listen on (default: 3000)
- *   -d, --domain <domain>   Domain name for federation (default: localhost)
- *   --data-dir <dir>        Data directory for storage
- *   --protocol <protocol>   Protocol: http or https (default: http)
- *   -h, --help              Show this help message
- *
- * Environment Variables:
- *   HOLOSPHERE_AP_PORT      Port to listen on
- *   HOLOSPHERE_AP_DOMAIN    Domain name
- *   HOLOSPHERE_AP_DATADIR   Data directory
- *   HOLOSPHERE_AP_PROTOCOL  Protocol (http/https)
- */
-
-import { ActivityPubServer } from '../src/storage/backends/activitypub/server.js';
-
-function parseArgs(args) {
-  const config = {
-    port: parseInt(process.env.HOLOSPHERE_AP_PORT) || 3000,
-    domain: process.env.HOLOSPHERE_AP_DOMAIN || 'localhost',
-    dataDir: process.env.HOLOSPHERE_AP_DATADIR,
-    protocol: process.env.HOLOSPHERE_AP_PROTOCOL || 'http',
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    const next = args[i + 1];
-
-    switch (arg) {
-      case '-p':
-      case '--port':
-        config.port = parseInt(next);
-        i++;
-        break;
-      case '-d':
-      case '--domain':
-        config.domain = next;
-        i++;
-        break;
-      case '--data-dir':
-        config.dataDir = next;
-        i++;
-        break;
-      case '--protocol':
-        config.protocol = next;
-        i++;
-        break;
-      case '-h':
-      case '--help':
-        showHelp();
-        process.exit(0);
-      default:
-        if (arg.startsWith('-')) {
-          console.error(`Unknown option: ${arg}`);
-          showHelp();
-          process.exit(1);
-        }
-    }
-  }
-
-  return config;
-}
-
-function showHelp() {
-  console.log(`
-HoloSphere ActivityPub Server
-
-Starts a self-hosted ActivityPub server for HoloSphere federation.
-This server can federate with Mastodon, Pleroma, and other ActivityPub servers.
-
-Usage:
-  holosphere-activitypub [options]
-
-Options:
-  -p, --port <port>       Port to listen on (default: 3000)
-  -d, --domain <domain>   Domain name for federation (default: localhost)
-  --data-dir <dir>        Data directory for persistent storage
-  --protocol <protocol>   Protocol: http or https (default: http)
-  -h, --help              Show this help message
-
-Environment Variables:
-  HOLOSPHERE_AP_PORT      Port to listen on
-  HOLOSPHERE_AP_DOMAIN    Domain name
-  HOLOSPHERE_AP_DATADIR   Data directory
-  HOLOSPHERE_AP_PROTOCOL  Protocol (http/https)
-
-Examples:
-  # Start server on default port
-  holosphere-activitypub
-
-  # Start server on port 8080 with custom domain
-  holosphere-activitypub -p 8080 -d myholosphere.example.com
-
-  # Start with persistent data directory
-  holosphere-activitypub --data-dir ./data --domain myserver.local
-
-Federation Notes:
-  For federation with other ActivityPub servers (Mastodon, etc.):
-  1. Your server must be accessible via the domain you specify
-  2. HTTPS is recommended for production federation
-  3. Set up proper DNS records pointing to your server
-  4. WebFinger discovery is available at /.well-known/webfinger
-`);
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const config = parseArgs(args);
-
-  console.log('\n========================================');
-  console.log('  HoloSphere ActivityPub Server');
-  console.log('========================================');
-  console.log(`  Port:     ${config.port}`);
-  console.log(`  Domain:   ${config.domain}`);
-  console.log(`  Protocol: ${config.protocol}`);
-  console.log(`  Data Dir: ${config.dataDir || '(default)'}`);
-  console.log('========================================\n');
-
-  const server = new ActivityPubServer(config);
-
-  // Handle shutdown gracefully
-  process.on('SIGINT', () => {
-    console.log('\nShutting down...');
-    server.stop();
-    process.exit(0);
-  });
-
-  process.on('SIGTERM', () => {
-    console.log('\nShutting down...');
-    server.stop();
-    process.exit(0);
-  });
-
-  try {
-    await server.start();
-    console.log('\nServer endpoints:');
-    console.log(`  WebFinger:  ${config.protocol}://${config.domain}:${config.port}/.well-known/webfinger`);
-    console.log(`  Actors:     ${config.protocol}://${config.domain}:${config.port}/actor/{name}`);
-    console.log(`  API:        ${config.protocol}://${config.domain}:${config.port}/api/data`);
-    console.log(`  Health:     ${config.protocol}://${config.domain}:${config.port}/health`);
-    console.log('\nPress Ctrl+C to stop the server\n');
-  } catch (error) {
-    console.error('Failed to start server:', error);
-    process.exit(1);
-  }
-}
-
-main();