holosphere 2.0.0-alpha21 → 2.0.0-alpha23

package/src/lib/federation-methods.js

@@ -1,12 +1,18 @@
 /**
- * @fileoverview Unified Federation Methods - UNIFIED MODEL
+ * @fileoverview Federation Methods — Simplified.
  *
- * Provides a single, consistent API for all federation operations:
- * - Same-author federation (previously "in-federation")
- * - Cross-author federation (previously "cross-federation")
+ * Federation = exchanging pubkeys.
+ * No capability tokens, no complex handshake.
  *
- * All federation uses capabilities, providing consistent security semantics.
- * The unified `federate()` method handles both cases based on parameters.
+ * The hologram is the core infrastructure:
+ * - federate() adds a partner to the registry + stores config (no auto-hologram creation)
+ * - Reads are filtered by federation membership
+ * - Everyone can write everywhere; non-federated data is invisible
+ * - Holograms are only created explicitly via propagateData()
+ *
+ * For cryptographic privacy: encrypted lenses + key sharing via NIP-44 DMs.
+ * - shareLensKeys() shares symmetric keys with a federation partner
+ * - Only holders of the key can decrypt the data on the relay
  *
  * @module lib/federation-methods
  */
@@ -14,18 +20,16 @@
 import * as registry from '../federation/registry.js';
 import * as discovery from '../federation/discovery.js';
 import * as federation from '../federation/hologram.js';
-import * as storage from '../storage/unified-storage.js';
+import * as storage from '../storage/nostr-wrapper.js';
 import * as nostrAsync from '../storage/nostr-async.js';
-import * as crypto from '../crypto/secp256k1.js';
-import { hashToken, isPubkey } from '../crypto/secp256k1.js';
+import { isPubkey } from '../crypto/secp256k1.js';
+import { sendLensKeyShare } from '../federation/handshake.js';
+import { buildLensPath } from '../crypto/key-store.js';
+import { registerHolon } from '../federation/holon-registry.js';
 import { ValidationError, AuthorizationError } from './errors.js';
 
 /**
  * Normalize a holon target (string or object) to { holonId, authorPubKey }.
- * If the holonId is a 64-char hex pubkey, uses it as the authorPubKey.
- * @param {string|Object} input - Holon ID string or { holonId, authorPubKey }
- * @param {string} defaultPubKey - Default author public key (typically client.publicKey)
- * @returns {{ holonId: string, authorPubKey: string }}
  */
 function normalizeHolonTarget(input, defaultPubKey) {
   if (typeof input === 'string') {
@@ -39,229 +43,86 @@ function normalizeHolonTarget(input, defaultPubKey) {
 
 /**
  * Mixin that adds federation methods to a HoloSphere class.
- * Enables unified federation with capability-based access control,
- * hologram creation, and Nostr-based discovery protocols.
  *
- * UNIFIED MODEL: All federation uses capabilities for consistent security.
+ * SIMPLIFIED MODEL: Federation = pubkey list + holograms.
+ * No capability tokens. No complex access control.
  *
  * @param {Class} Base - Base class to extend
  * @returns {Class} Extended class with federation methods
  */
 export function withFederationMethods(Base) {
   return class extends Base {
-    // === UNIFIED FEDERATION API ===
 
     /**
-     * Federation method - UNIFIED MODEL
+     * Federate two holons — the core operation.
+     *
+     * This does two things:
+     * 1. Adds the partner to the federation registry (pubkey list)
+     * 2. Stores federation config
      *
-     * Single entry point for all federation operations.
-     * Handles both same-author and cross-author federation consistently.
+     * Holograms are NOT automatically created. Use propagateData() explicitly
+     * to create holograms when needed.
      *
-     * @param {string|Object} source - Source holon. Can be:
-     *   - string: holonId (implies same author as client)
-     *   - { holonId, authorPubKey }: explicit author specification
-     * @param {string|Object} target - Target holon. Same format as source.
-     * @param {string} lensName - Name of the lens to federate
+     * @param {string|Object} source - Source holon
+     * @param {string|Object} target - Target holon
+     * @param {string} lensName - Lens name to federate
      * @param {Object} [options={}] - Federation options
      * @param {string} [options.direction='outbound'] - 'inbound', 'outbound', or 'bidirectional'
      * @param {string} [options.mode='reference'] - 'reference' (hologram) or 'copy'
-     * @param {boolean} [options.propagate=true] - Whether to propagate existing data (false = capability only)
-     * @param {string} [options.capability] - Pre-issued capability (auto-generated if not provided)
-     * @param {string[]} [options.permissions=['read']] - Permissions for auto-issued capability
-     * @param {Function} [options.filter] - Filter function to select which data to federate
-     * @returns {Promise<Object>} Federation result with capability info
-     * @throws {ValidationError} If trying to federate a holon with itself
-     *
-     * @example
-     * // Same-author federation (simplified)
-     * await hs.federate('holon-a', 'holon-b', 'events');
-     *
-     * @example
-     * // Cross-author federation (explicit)
-     * await hs.federate(
-     *   { holonId: 'holon-a', authorPubKey: 'abc123...' },
-     *   { holonId: 'holon-b', authorPubKey: 'def456...' },
-     *   'events',
-     *   { capability: preIssuedToken }
-     * );
+     * @param {boolean} [options.shareKeys=false] - Share encrypted lens keys with partner via NIP-44 DM
+     * @returns {Promise<Object>} Federation result
      */
     async federate(source, target, lensName, options = {}) {
       const {
         direction = 'outbound',
         mode = 'reference',
-        propagate = true,
-        capability: providedCapability = null,
-        permissions = ['read'],
-        filter = null,
+        shareKeys = false,  // Share encrypted lens keys with partner
       } = options;
 
-      // Normalize source and target to { holonId, authorPubKey } format
       const normalizedSource = normalizeHolonTarget(source, this.client.publicKey);
       const normalizedTarget = normalizeHolonTarget(target, this.client.publicKey);
 
-      // Validation
       if (normalizedSource.holonId === normalizedTarget.holonId &&
           normalizedSource.authorPubKey === normalizedTarget.authorPubKey) {
         throw new ValidationError('Cannot federate a holon with itself');
       }
 
       if (!['inbound', 'outbound', 'bidirectional'].includes(direction)) {
-        throw new ValidationError(`Invalid direction: ${direction}. Must be 'inbound', 'outbound', or 'bidirectional'`);
+        throw new ValidationError(`Invalid direction: ${direction}`);
       }
 
-      // Determine if this is self-federation or cross-federation
       const isSelfFederation = normalizedSource.authorPubKey === normalizedTarget.authorPubKey;
 
-      // Issue capabilities per direction.
-      // Outbound: capability scoped to source holon (data lives in source, hologram points to source)
-      // Inbound: capability scoped to target holon (data lives in target, hologram points to target)
-      const expiresIn = isSelfFederation
-        ? 365 * 24 * 60 * 60 * 1000  // 1 year for self
-        : 24 * 60 * 60 * 1000;       // 24 hours for cross
-
-      const needsOutbound = direction === 'outbound' || direction === 'bidirectional';
-      const needsInbound = direction === 'inbound' || direction === 'bidirectional';
-
-      // Outbound capability: scoped to source holon
-      let outboundCapability = providedCapability;
-      if (!outboundCapability && needsOutbound) {
-        outboundCapability = await crypto.issueCapability(
-          permissions,
-          { holonId: normalizedSource.holonId, lensName, dataId: '*' },
-          normalizedTarget.authorPubKey,
-          {
-            expiresIn,
-            issuer: normalizedSource.authorPubKey,
-            issuerKey: this.client.privateKey,
-            isSelfCapability: isSelfFederation,
-          }
-        );
+      // Add partner to federation list (if cross-author)
+      if (!isSelfFederation) {
+        const needsOutbound = direction === 'outbound' || direction === 'bidirectional';
+        const needsInbound = direction === 'inbound' || direction === 'bidirectional';
 
-        if (isSelfFederation) {
-          await registry.storeSelfCapability(this.client, this.config.appName, {
-            token: outboundCapability,
-            scope: { holonId: normalizedSource.holonId, lensName },
-            permissions,
-          });
-        } else {
-          await registry.storeInboundCapability(
-            this.client,
-            this.config.appName,
-            normalizedSource.authorPubKey,
-            {
-              token: outboundCapability,
-              scope: { holonId: normalizedSource.holonId, lensName },
-              permissions,
-            }
+        if (needsOutbound) {
+          await registry.addFederatedPartner(
+            this.client, this.config.appName,
+            normalizedTarget.authorPubKey,
+            { addedVia: 'federate' }
           );
         }
-      }
-
-      // Inbound capability: scoped to target holon
-      let inboundCapability = providedCapability;
-      if (!inboundCapability && needsInbound) {
-        inboundCapability = await crypto.issueCapability(
-          permissions,
-          { holonId: normalizedTarget.holonId, lensName, dataId: '*' },
-          normalizedSource.authorPubKey,
-          {
-            expiresIn,
-            issuer: normalizedTarget.authorPubKey,
-            issuerKey: this.client.privateKey,
-            isSelfCapability: isSelfFederation,
-          }
-        );
-
-        if (isSelfFederation) {
-          await registry.storeSelfCapability(this.client, this.config.appName, {
-            token: inboundCapability,
-            scope: { holonId: normalizedTarget.holonId, lensName },
-            permissions,
-          });
-        } else {
-          await registry.storeInboundCapability(
-            this.client,
-            this.config.appName,
-            normalizedTarget.authorPubKey,
-            {
-              token: inboundCapability,
-              scope: { holonId: normalizedTarget.holonId, lensName },
-              permissions,
-            }
+        if (needsInbound) {
+          await registry.addFederatedPartner(
+            this.client, this.config.appName,
+            normalizedSource.authorPubKey,
+            { addedVia: 'federate' }
           );
         }
       }
 
-      // Setup federation based on direction
       const results = {
         source: normalizedSource,
         target: normalizedTarget,
         lensName,
         direction,
         mode,
-        propagate,
-        capability: outboundCapability || inboundCapability,
         isSelfFederation,
-        propagated: { outbound: 0, inbound: 0 },
       };
 
-      // Handle data propagation (skip if propagate: false)
-      if (propagate && needsOutbound) {
-        // Propagate existing data from source to target
-        const sourceData = await this.read(normalizedSource.holonId, lensName, null, {
-          resolveHolograms: false,
-        });
-
-        if (sourceData && Array.isArray(sourceData)) {
-          for (const item of sourceData) {
-            if (filter && !filter(item)) continue;
-
-            await federation.propagateData(
-              this.client,
-              this.config.appName,
-              item,
-              normalizedSource.holonId,
-              normalizedTarget.holonId,
-              lensName,
-              mode,
-              {
-                sourceAuthorPubKey: normalizedSource.authorPubKey,
-                capability: outboundCapability,
-              }
-            );
-            results.propagated.outbound++;
-          }
-        }
-      }
-
-      if (propagate && needsInbound) {
-        // Propagate from target to source
-        const targetData = await this.read(normalizedTarget.holonId, lensName, null, {
-          resolveHolograms: false,
-        });
-
-        if (targetData && Array.isArray(targetData)) {
-          for (const item of targetData) {
-            if (filter && !filter(item)) continue;
-
-            await federation.propagateData(
-              this.client,
-              this.config.appName,
-              item,
-              normalizedTarget.holonId,
-              normalizedSource.holonId,
-              lensName,
-              mode,
-              {
-                sourceAuthorPubKey: normalizedTarget.authorPubKey,
-                capability: inboundCapability,
-              }
-            );
-            results.propagated.inbound++;
-          }
-        }
-      }
-
       // Store federation config
       await federation.setupFederation(
         this.client,
@@ -272,135 +133,79 @@ export function withFederationMethods(Base) {
         { direction, mode }
       );
 
+      // Share encrypted lens keys with partner (if requested and cross-author)
+      if (shareKeys && !isSelfFederation && this.client?.privateKey && this.keyStore) {
+        try {
+          const keyResult = await this.shareLensKeys(
+            normalizedTarget.authorPubKey,
+            [lensName],
+            { holonId: normalizedSource.holonId }
+          );
+          results.keysShared = keyResult.shared;
+        } catch (err) {
+          results.keysShared = 0;
+          results.keyShareError = err.message;
+        }
+      }
+
       return results;
     }
 
     /**
-     * Unfederate method - UNIFIED MODEL
-     *
-     * Removes federation between source and target holons.
-     *
-     * @param {string|Object} source - Source holon (string or { holonId, authorPubKey })
-     * @param {string|Object} target - Target holon (string or { holonId, authorPubKey })
-     * @param {string} lensName - Lens name to unfederate
-     * @returns {Promise<boolean>} True if unfederation succeeded
+     * Unfederate — remove federation between source and target holons.
      */
     async unfederate(source, target, lensName) {
       const normalizedSource = normalizeHolonTarget(source, this.client.publicKey);
       const normalizedTarget = normalizeHolonTarget(target, this.client.publicKey);
 
-      // Remove federation config
       const configPath = storage.buildPath(this.config.appName, normalizedSource.holonId, lensName, '_federation');
       try {
         await storage.deleteData(this.client, configPath);
       } catch (e) {
-        // Ignore errors - already unfederated or doesn't exist
+        // Ignore — already unfederated
       }
 
       return true;
     }
 
-    // === Legacy Methods (kept for backward compatibility) ===
+    // === Federation Registry Methods ===
 
-    /**
-     * Add a federated HoloSphere partner by public key.
-     * @deprecated Use federate() with explicit authorPubKey instead
-     * @param {string} pubKey - Public key (hex) of the federated HoloSphere
-     * @param {Object} [options={}] - Federation options (metadata, capabilities, etc.)
-     * @returns {Promise<Object>} Federation registration result
-     * @throws {ValidationError} If pubKey is invalid
-     */
     async addFederatedHolosphere(pubKey, options = {}) {
       if (!pubKey || typeof pubKey !== 'string') {
         throw new ValidationError('pubKey must be a valid public key string');
       }
-      return registry.addFederatedPartner(
-        this.client,
-        this.config.appName,
-        pubKey,
-        options
-      );
+      return registry.addFederatedPartner(this.client, this.config.appName, pubKey, options);
     }
 
-    /**
-     * Remove a federated HoloSphere partner.
-     * @param {string} pubKey - Public key of the partner to remove
-     * @returns {Promise<void>}
-     */
     async removeFederatedHolosphere(pubKey) {
-      return registry.removeFederatedPartner(
-        this.client,
-        this.config.appName,
-        pubKey
-      );
+      return registry.removeFederatedPartner(this.client, this.config.appName, pubKey);
     }
 
-    /**
-     * Get all federated HoloSphere public keys.
-     * @returns {Promise<string[]>} Array of federated public keys
-     */
     async getFederatedHolospheres() {
-      return registry.getFederatedAuthors(
-        this.client,
-        this.config.appName
-      );
+      return registry.getFederatedAuthors(this.client, this.config.appName);
     }
 
-    /**
-     * Get the complete federation registry.
-     * @returns {Promise<Object>} Federation registry with all partners and capabilities
-     */
     async getFederationRegistry() {
-      return registry.getFederationRegistry(
-        this.client,
-        this.config.appName
-      );
+      return registry.getFederationRegistry(this.client, this.config.appName);
     }
 
     /**
-     * Store an inbound capability token from a federated partner.
-     * @param {string} partnerPubKey - Partner's public key
-     * @param {Object} capabilityInfo - Capability token and metadata
-     * @returns {Promise<void>}
+     * Check if a pubkey is in this holosphere's federation.
+     * @param {string} pubKey - Public key to check
+     * @returns {Promise<boolean>}
      */
-    async storeInboundCapability(partnerPubKey, capabilityInfo) {
-      return registry.storeInboundCapability(
-        this.client,
-        this.config.appName,
-        partnerPubKey,
-        capabilityInfo
-      );
+    async isFederated(pubKey) {
+      return registry.isFederated(this.client, this.config.appName, pubKey);
     }
 
     /**
-     * Read data from a federated source with capability verification.
-     * @param {string} sourcePubKey - Source HoloSphere public key
-     * @param {string} holonId - Holon ID to read from
-     * @param {string} lensName - Lens name to read from
-     * @param {string|null} [dataId=null] - Optional specific data ID (null for all)
-     * @returns {Promise<Object|Object[]>} Data from federated source
-     * @throws {AuthorizationError} If capability verification fails
+     * Read data from a federated source.
+     * Simplified: just checks federation membership, then reads with author filter.
      */
     async readFromFederatedSource(sourcePubKey, holonId, lensName, dataId = null) {
-      const capabilityEntry = await registry.getCapabilityForAuthor(
-        this.client,
-        this.config.appName,
-        sourcePubKey,
-        { holonId, lensName, dataId }
-      );
-
-      if (!capabilityEntry) {
-        throw new AuthorizationError('No valid capability for federated source', 'read');
-      }
-
-      const isValid = await this.verifyCapability(
-        capabilityEntry.token,
-        'read',
-        { holonId, lensName, dataId }
-      );
-
-      if (!isValid) {
-        throw new AuthorizationError('Capability verification failed', 'read');
+      const federated = await this.isFederated(sourcePubKey);
+      if (!federated) {
+        throw new AuthorizationError('Source is not in the federation', 'read');
       }
 
       if (dataId) {
@@ -419,544 +224,137 @@ export function withFederationMethods(Base) {
     }
 
     /**
-     * Create a cross-HoloSphere hologram reference.
-     * Links data from another HoloSphere into this one using capability-based access.
-     * @param {string} sourcePubKey - Source HoloSphere public key
-     * @param {string} sourceHolon - Source holon ID
-     * @param {string} lensName - Lens name
-     * @param {string} dataId - Data ID
-     * @param {string} targetHolon - Target holon in this HoloSphere
-     * @param {Object} [options={}] - Hologram options
-     * @param {boolean} [options.embedCapability=true] - Embed capability in hologram
-     * @returns {Promise<Object>} Created hologram
-     * @throws {AuthorizationError} If no valid capability exists
+     * Create a cross-holosphere hologram reference.
      */
-    async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, options = {}) {
-      const { embedCapability = true } = options;
-
-      const capabilityEntry = await registry.getCapabilityForAuthor(
-        this.client,
-        this.config.appName,
-        sourcePubKey,
-        { holonId: sourceHolon, lensName, dataId }
-      );
-
-      if (!capabilityEntry) {
-        throw new AuthorizationError('No valid capability for cross-holosphere hologram', 'read');
-      }
-
+    async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, _options = {}) {
       const hologram = federation.createHologram(
-        sourceHolon,
-        targetHolon,
-        lensName,
-        dataId,
+        sourceHolon, targetHolon, lensName, dataId,
         this.config.appName,
-        {
-          authorPubKey: sourcePubKey,
-          capability: embedCapability ? capabilityEntry.token : null,
-        }
+        { authorPubKey: sourcePubKey }
       );
 
       const targetPath = storage.buildPath(this.config.appName, targetHolon, lensName, dataId);
       await storage.write(this.client, targetPath, hologram);
-
       return hologram;
     }
 
-    /**
-     * Issue a capability token for federated access.
-     * Grants another HoloSphere permission to access data with specified scope.
-     * @param {string} targetPubKey - Target HoloSphere public key to grant access to
-     * @param {Object} scope - Access scope (holonId, lensName, dataId patterns)
-     * @param {string[]} permissions - Array of permissions ('read', 'write', etc.)
-     * @param {Object} [options={}] - Capability options
-     * @param {number} [options.expiresIn=3600000] - Expiration time in milliseconds
-     * @param {boolean} [options.trackInRegistry=true] - Store in federation registry
-     * @returns {Promise<string>} Capability token
-     */
-    async issueCapabilityForFederation(targetPubKey, scope, permissions, options = {}) {
-      const { expiresIn = 3600000, trackInRegistry = true } = options;
-
-      const token = await crypto.issueCapability(
-        permissions,
-        scope,
-        targetPubKey,
-        {
-          expiresIn,
-          issuerKey: this.client.privateKey,
-        }
-      );
-
-      if (trackInRegistry) {
-        const partner = await registry.getFederatedPartner(
-          this.client,
-          this.config.appName,
-          targetPubKey
-        );
-
-        if (!partner) {
-          await registry.addFederatedPartner(
-            this.client,
-            this.config.appName,
-            targetPubKey,
-            { addedVia: 'capability_issued' }
-          );
-        }
-
-        await registry.storeOutboundCapability(
-          this.client,
-          this.config.appName,
-          targetPubKey,
-          {
-            tokenHash: await this._hashToken(token),
-            scope,
-            permissions,
-            expires: Date.now() + expiresIn,
-          }
-        );
-      }
-
-      return token;
-    }
-
-    /**
-     * Hash a capability token for storage.
-     * @private
-     * @param {string} token - Capability token to hash
-     * @returns {string} SHA256 hash of token
-     */
-    _hashToken(token) {
-      return hashToken(token);
-    }
-
     // === Nostr Discovery Protocol ===
 
-    /**
-     * Send a federation request to another HoloSphere via Nostr.
-     * @param {string} targetPubKey - Target HoloSphere public key
-     * @param {Object} [options={}] - Request options (message, metadata, etc.)
-     * @returns {Promise<Object>} Request event
-     */
     async sendFederationRequest(targetPubKey, options = {}) {
-      return discovery.sendFederationRequest(
-        this.client,
-        this.config.appName,
-        targetPubKey,
-        options
-      );
+      return discovery.sendFederationRequest(this.client, this.config.appName, targetPubKey, options);
     }
 
-    /**
-     * Subscribe to incoming federation requests.
-     * @param {Function} callback - Callback function (request) => void
-     * @returns {Promise<Object>} Subscription object with unsubscribe method
-     */
     async subscribeFederationRequests(callback) {
       return discovery.subscribeFederationRequests(this.client, callback);
     }
 
-    /**
-     * Accept a federation request and establish partnership.
-     * @param {Object} request - Federation request object
-     * @param {Object} [options={}] - Acceptance options (capabilities to grant, etc.)
-     * @returns {Promise<Object>} Acceptance event
-     */
     async acceptFederationRequest(request, options = {}) {
-      return discovery.acceptFederationRequest(
-        this.client,
-        this.config.appName,
-        request,
-        options
-      );
+      return discovery.acceptFederationRequest(this.client, this.config.appName, request, options);
     }
 
-    /**
-     * Decline a federation request.
-     * @param {Object} request - Federation request object
-     * @param {string} [reason=''] - Optional reason for declining
-     * @returns {Promise<Object>} Decline event
-     */
     async declineFederationRequest(request, reason = '') {
-      return discovery.declineFederationRequest(
-        this.client,
-        this.config.appName,
-        request,
-        reason
-      );
+      return discovery.declineFederationRequest(this.client, this.config.appName, request, reason);
     }
 
-    /**
-     * Subscribe to federation request acceptances.
-     * @param {Function} callback - Callback function (acceptance) => void
-     * @returns {Promise<Object>} Subscription object with unsubscribe method
-     */
     async subscribeFederationAcceptances(callback) {
-      return discovery.subscribeFederationAcceptances(
-        this.client,
-        this.config.appName,
-        callback
-      );
+      return discovery.subscribeFederationAcceptances(this.client, this.config.appName, callback);
     }
 
-    /**
-     * Subscribe to federation request declines.
-     * @param {Function} callback - Callback function (decline) => void
-     * @returns {Promise<Object>} Subscription object with unsubscribe method
-     */
     async subscribeFederationDeclines(callback) {
       return discovery.subscribeFederationDeclines(this.client, callback);
     }
 
-    /**
-     * Get all pending federation requests.
-     * @param {Object} [options={}] - Query options (limit, since, etc.)
-     * @returns {Promise<Object[]>} Array of pending requests
-     */
     async getPendingFederationRequests(options = {}) {
       return discovery.getPendingFederationRequests(this.client, options);
     }
 
-    // === Federated Lens Reception (Hologram-based) ===
+    // === Encrypted Federation (Key Sharing via NIP-44 DMs) ===
 
     /**
-     * Receive data from a federated partner's lens as holograms in your own holon.
-     * This creates holograms pointing to the partner's data, allowing you to see
-     * their data in your holon while the source of truth remains with the partner.
+     * Share lens encryption keys with a federation partner.
      *
-     * @param {string} partnerPubKey - Partner's public key
-     * @param {string} sourceHolonId - Partner's holon ID to receive data from
-     * @param {string} lensName - Lens name to receive
-     * @param {string} targetHolonId - Your holon ID where holograms will be created
-     * @param {Object} [options={}] - Reception options
-     * @param {Function} [options.filter] - Optional filter function to select which items to receive
-     * @param {boolean} [options.overwrite=false] - Whether to overwrite existing holograms
-     * @returns {Promise<Object>} Result with count of received holograms and any errors
-     * @throws {AuthorizationError} If no valid capability exists for the source
+     * This is how you make your data readable ONLY by your federation:
+     * 1. Your lenses are encrypted with symmetric keys (AES-256-GCM)
+     * 2. This method wraps each key for the partner using NIP-44
+     * 3. Sends the wrapped key via encrypted DM (kind 4)
+     * 4. Partner unwraps with their private key → can now decrypt your data
      *
-     * @example
-     * // Receive events from a federated partner into your holon
-     * const result = await hs.receiveFederatedLens(
-     *   'partner-pubkey',
-     *   'partner-holon-id',
-     *   'events',
-     *   'my-holon-id'
-     * );
-     * console.log(`Received ${result.received} holograms`);
+     * Non-federation members see encrypted blobs they can't decrypt.
+     *
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {string[]} [lensNames] - Specific lenses to share (default: all encrypted lenses)
+     * @param {Object} [options={}] - Options
+     * @param {string} [options.holonId] - Specific holon (default: client.publicKey)
+     * @returns {Promise<Object>} { shared: number, failed: number, lenses: string[] }
      */
-    async receiveFederatedLens(partnerPubKey, sourceHolonId, lensName, targetHolonId, options = {}) {
-      const { filter = null, overwrite = false } = options;
-
-      // Get capability for accessing partner's data
-      const capabilityEntry = await registry.getCapabilityForAuthor(
-        this.client,
-        this.config.appName,
-        partnerPubKey,
-        { holonId: sourceHolonId, lensName, dataId: '*' }
-      );
-
-      if (!capabilityEntry) {
-        throw new AuthorizationError(
-          `No valid capability to access ${sourceHolonId}/${lensName} from ${partnerPubKey}`,
-          'read'
-        );
+    async shareLensKeys(partnerPubKey, lensNames = null, options = {}) {
+      if (!this.client?.privateKey) {
+        throw new ValidationError('Private key required to share lens keys');
       }
 
-      // Read all data from partner's lens
-      const sourcePath = storage.buildPath(this.config.appName, sourceHolonId, lensName);
-      const partnerData = await nostrAsync.nostrGetAll(this.client, sourcePath, 30000, {
-        authors: [partnerPubKey],
-        includeAuthor: true,
-      });
+      const holonId = options.holonId || this.client.publicKey;
+      const result = { shared: 0, failed: 0, lenses: [] };
 
-      if (!partnerData || !Array.isArray(partnerData)) {
-        return { received: 0, skipped: 0, errors: [] };
-      }
+      // Get all own keys from the key store
+      const ownKeys = this.keyStore.ownKeys;
 
-      const result = { received: 0, skipped: 0, errors: [] };
-
-      for (const item of partnerData) {
-        if (!item || !item.id) continue;
-
-        // Apply filter if provided
-        if (filter && !filter(item)) {
-          result.skipped++;
-          continue;
+      for (const [lensPath, keyData] of ownKeys) {
+        // If specific lenses requested, filter
+        if (lensNames) {
+          const matchesLens = lensNames.some(name => lensPath.includes(`/${name}`));
+          if (!matchesLens) continue;
         }
 
-        // Skip if hologram already exists and overwrite is false
-        if (!overwrite) {
-          const existingPath = storage.buildPath(this.config.appName, targetHolonId, lensName, item.id);
-          const existing = await storage.read(this.client, existingPath);
-          if (existing && existing.hologram) {
-            result.skipped++;
-            continue;
-          }
+        // If specific holonId, filter
+        if (holonId && !lensPath.includes(`/${holonId}/`) && !lensPath.startsWith(`${this.config.appName}/${holonId}/`)) {
+          continue;
         }
 
         try {
-          // Create hologram in target holon pointing to partner's data
-          const hologram = await federation.createHologramWithCapability(
-            this.client,
-            sourceHolonId,
-            targetHolonId,
-            lensName,
-            item.id,
-            this.config.appName,
-            {
-              sourceAuthorPubKey: partnerPubKey,
-              targetAuthorPubKey: this.client.publicKey,
-              capability: capabilityEntry.token,
-              permissions: ['read'],
-            }
+          // Wrap the key for this partner
+          const wrappedKey = this.keyStore.wrapKeyForPartner(
+            lensPath,
+            this.client.privateKey,
+            partnerPubKey
           );
 
-          const targetPath = storage.buildPath(this.config.appName, targetHolonId, lensName, item.id);
-          await storage.write(this.client, targetPath, hologram);
-          result.received++;
-        } catch (error) {
-          result.errors.push({ id: item.id, error: error.message });
-        }
-      }
-
-      return result;
-    }
-
-    /**
-     * Subscribe to a federated partner's lens for real-time hologram updates.
-     * When the partner writes new data, holograms are automatically created in your holon.
-     *
-     * @param {string} partnerPubKey - Partner's public key
-     * @param {string} sourceHolonId - Partner's holon ID to subscribe to
-     * @param {string} lensName - Lens name to subscribe to
-     * @param {string} targetHolonId - Your holon ID where holograms will be created
-     * @param {Object} [options={}] - Subscription options
-     * @param {Function} [options.onHologram] - Callback when a new hologram is created (hologram, sourceData) => void
-     * @param {Function} [options.onError] - Callback for errors (error) => void
-     * @param {Function} [options.filter] - Optional filter function to select which items to receive
-     * @returns {Promise<Object>} Subscription object with unsubscribe() method
-     *
-     * @example
-     * // Subscribe to partner's events lens
-     * const sub = await hs.subscribeFederatedLens(
-     *   'partner-pubkey',
-     *   'partner-holon-id',
-     *   'events',
-     *   'my-holon-id',
-     *   {
-     *     onHologram: (hologram, data) => {
-     *       console.log(`New hologram received: ${data.id}`);
-     *     }
-     *   }
-     * );
-     *
-     * // Later, unsubscribe
-     * sub.unsubscribe();
-     */
-    async subscribeFederatedLens(partnerPubKey, sourceHolonId, lensName, targetHolonId, options = {}) {
-      const { onHologram, onError, filter = null } = options;
-
-      // Get capability for accessing partner's data
-      const capabilityEntry = await registry.getCapabilityForAuthor(
-        this.client,
-        this.config.appName,
-        partnerPubKey,
-        { holonId: sourceHolonId, lensName, dataId: '*' }
-      );
-
-      if (!capabilityEntry) {
-        throw new AuthorizationError(
-          `No valid capability to subscribe to ${sourceHolonId}/${lensName} from ${partnerPubKey}`,
-          'read'
-        );
-      }
-
-      // Track processed items to avoid duplicates
-      const processedIds = new Set();
-
-      // Subscribe to partner's lens path
-      const sourcePath = storage.buildPath(this.config.appName, sourceHolonId, lensName);
-
-      const handleEvent = async (data) => {
-        if (!data || !data.id) return;
-
-        // Skip if already processed
-        if (processedIds.has(data.id)) return;
-        processedIds.add(data.id);
-
-        // Apply filter if provided
-        if (filter && !filter(data)) return;
+          if (!wrappedKey) continue;
 
-        try {
-          // Check if hologram already exists
-          const existingPath = storage.buildPath(this.config.appName, targetHolonId, lensName, data.id);
-          const existing = await storage.read(this.client, existingPath);
-
-          if (existing && existing.hologram) {
-            // Hologram already exists, skip
-            return;
-          }
-
-          // Create hologram in target holon
-          const hologram = await federation.createHologramWithCapability(
+          // Send via NIP-44 encrypted DM
+          await sendLensKeyShare(
             this.client,
-            sourceHolonId,
-            targetHolonId,
-            lensName,
-            data.id,
-            this.config.appName,
-            {
-              sourceAuthorPubKey: partnerPubKey,
-              targetAuthorPubKey: this.client.publicKey,
-              capability: capabilityEntry.token,
-              permissions: ['read'],
-            }
+            this.client.privateKey,
+            partnerPubKey,
+            { lensPath, wrappedKey }
           );
 
-          const targetPath = storage.buildPath(this.config.appName, targetHolonId, lensName, data.id);
-          await storage.write(this.client, targetPath, hologram);
-
-          if (onHologram) {
-            onHologram(hologram, data);
-          }
+          result.shared++;
+          result.lenses.push(lensPath);
         } catch (error) {
-          if (onError) {
-            onError(error);
-          }
+          result.failed++;
         }
-      };
-
-      // Subscribe using nostr-async subscription with author filter
-      const subscription = await nostrAsync.nostrSubscribe(
-        this.client,
-        sourcePath,
-        handleEvent,
-        30000,
-        { authors: [partnerPubKey] }
-      );
-
-      return {
-        unsubscribe: () => {
-          if (subscription && subscription.unsubscribe) {
-            subscription.unsubscribe();
-          }
-          processedIds.clear();
-        },
-        processedCount: () => processedIds.size,
-      };
-    }
-
-    /**
-     * Sync all federated lenses for a holon.
-     * Receives holograms from all federated partners for their configured inbound lenses.
-     *
-     * @param {string} holonId - Your holon ID
-     * @param {Object} [options={}] - Sync options
-     * @param {boolean} [options.overwrite=false] - Whether to overwrite existing holograms
-     * @returns {Promise<Object>} Sync results per partner
-     *
-     * @example
-     * // Sync all federated data for a holon
-     * const results = await hs.syncFederatedLenses('my-holon-id');
-     * console.log(results);
-     */
-    async syncFederatedLenses(holonId, options = {}) {
-      const { overwrite = false } = options;
-
-      // Get federation configuration for this holon
-      const federationData = await this.readGlobal('federation', holonId);
-      if (!federationData) {
-        return { error: 'No federation configuration found for this holon' };
       }
 
-      const results = {};
-
-      // Get all federated partners
-      const partners = await this.getFederatedHolospheres();
-
-      for (const partnerPubKey of partners) {
-        results[partnerPubKey] = { lenses: {}, errors: [] };
-
-        // Get partner's lens configuration
-        const partnerLensConfig = federationData.lensConfig?.[partnerPubKey];
-        const inboundLenses = partnerLensConfig?.inbound || [];
-
-        for (const lensName of inboundLenses) {
-          try {
-            // For cross-holosphere federation, the sourceHolonId would be the partner's holon
-            // We need to determine the partner's holon ID - this might be stored in the federation config
-            const partnerHolonId = partnerLensConfig?.holonId || holonId;
-
-            const result = await this.receiveFederatedLens(
-              partnerPubKey,
-              partnerHolonId,
-              lensName,
-              holonId,
-              { overwrite }
-            );
-
-            results[partnerPubKey].lenses[lensName] = result;
-          } catch (error) {
-            results[partnerPubKey].errors.push({
-              lens: lensName,
-              error: error.message,
-            });
-          }
-        }
-      }
-
-      return results;
+      return result;
     }
 
-    // === UNIFIED ACCESS CONTROL ===
+    // === Access Control (Simplified) ===
 
     /**
-     * Unified access verification method.
-     * Single entry point for checking all access permissions (read, write, etc.).
-     * Replaces and unifies the previous separate access checking methods.
-     *
-     * @param {string} targetHolonId - The holon being accessed
-     * @param {string} lensName - The lens being accessed
-     * @param {string} actorPubKey - The actor's public key
-     * @param {string} permission - Permission to check ('read' or 'write')
-     * @param {Object} [options={}] - Options
-     * @param {string} [options.actingAsHolon] - The holon the actor is acting on behalf of
-     * @param {string} [options.capabilityToken] - Explicit capability token to verify
-     * @returns {Promise<Object>} { allowed: boolean, via: string, reason?: string, grant?: Object }
-     *
-     * @example
-     * // Check if current user can read from a holon
-     * const result = await hs.canAccess(targetHolonId, 'quests', myPubKey, 'read');
-     * if (result.allowed) {
-     *   console.log('Access granted via:', result.via);
-     * }
-     *
-     * @example
-     * // Check write access with explicit capability
-     * const result = await hs.canAccess(targetHolonId, 'quests', myPubKey, 'write', {
-     *   capabilityToken: myCapToken
-     * });
+     * Unified access check.
+     * Simplified: owner always has access; federated partners always have access.
+     * No capability tokens needed.
      */
     async canAccess(targetHolonId, lensName, actorPubKey, permission, options = {}) {
-      const { actingAsHolon = null, capabilityToken = null } = options;
-
-      // 1. Owner check - actor owns the target holon
+      // 1. Owner check
       if (actorPubKey === targetHolonId) {
         return { allowed: true, via: 'owner' };
       }
 
-      // 2. Explicit capability token verification
-      if (capabilityToken) {
-        try {
-          const valid = await this.verifyCapability(capabilityToken, permission, {
-            holonId: targetHolonId,
-            lensName,
-          });
-          if (valid) {
-            return { allowed: true, via: 'capability' };
-          }
-        } catch (err) {
-          console.log('[canAccess] Capability verification failed:', err.message);
-        }
+      // 2. Federation check
+      const federated = await this.isFederated(actorPubKey);
+      if (federated) {
+        return { allowed: true, via: 'federation' };
       }
 
       // 3. Membership in target holon
@@ -964,248 +362,311 @@ export function withFederationMethods(Base) {
         const members = await this.get(targetHolonId, 'users');
         if (members && Array.isArray(members)) {
           const isMember = members.some(m =>
-            m.pubKey === actorPubKey ||
-            m.id === actorPubKey ||
-            m.nostrPubKey === actorPubKey
+            m.pubKey === actorPubKey || m.id === actorPubKey || m.nostrPubKey === actorPubKey
           );
           if (isMember) {
             return { allowed: true, via: 'membership' };
           }
         }
-      } catch (err) {
-        // Users lens might not exist or be empty - continue to check grants
-        console.log('[canAccess] Could not read users lens:', err.message);
-      }
-
-      // 4. Access grant via federation (unified check)
-      // First check using the new unified findAccessGrant
-      const scope = { holonId: targetHolonId, lensName };
-
-      // Check if actingAsHolon is specified
-      if (actingAsHolon) {
-        // Verify the actor is a member of the acting holon
-        const actorHolons = await this.getHolonsForPubKey(actorPubKey);
-        const isMemberOfActingHolon = actorHolons.some(h => h.id === actingAsHolon);
-
-        if (!isMemberOfActingHolon) {
-          return { allowed: false, via: 'none', reason: 'Not a member of the acting holon' };
-        }
-
-        // Check if actingAsHolon has an access grant
-        const grant = await registry.findAccessGrant(
-          this.client,
-          this.config.appName,
-          actingAsHolon,
-          scope,
-          permission,
-          { direction: 'inbound' }
-        );
-
-        if (grant) {
-          return {
-            allowed: true,
-            via: 'federation',
-            grant,
-            reason: `Acting as ${actingAsHolon} with ${permission} grant`,
-          };
-        }
-      } else {
-        // Check all holons the actor is a member of
-        const actorHolons = await this.getHolonsForPubKey(actorPubKey);
-
-        for (const holon of actorHolons) {
-          const grant = await registry.findAccessGrant(
-            this.client,
-            this.config.appName,
-            holon.id,
-            scope,
-            permission,
-            { direction: 'inbound' }
-          );
-
-          if (grant) {
-            return {
-              allowed: true,
-              via: 'federation',
-              grant,
-              reason: `Member of ${holon.name || holon.id} which has ${permission} grant`,
-              viaHolon: holon.id,
-            };
-          }
-        }
+      } catch (_err) {
+        // Users lens might not exist
       }
 
       return { allowed: false, via: 'none', reason: 'No access' };
     }
 
-    // === CROSS-HOLON WRITE ACCESS ===
-
     /**
-     * Check if a writer can write to a target holon's lens.
-     * This is a backward-compatible wrapper that delegates to canAccess().
-     *
-     * @param {string} targetHolonId - The holon being written to
-     * @param {string} lensName - The lens being written to
-     * @param {string} writerPubKey - The writer's public key
-     * @param {Object} [options={}] - Options
-     * @param {string} [options.actingAsHolon] - The holon the writer is acting on behalf of
-     * @param {string} [options.capabilityToken] - Explicit capability token to verify
-     * @returns {Promise<Object>} { canWrite: boolean, reason: string, accessType: string }
-     *
-     * @example
-     * // Check if current user can write to another holon
-     * const result = await hs.canWrite(targetHolonId, 'quests', myPubKey);
-     * if (result.canWrite) {
-     *   console.log('Access granted:', result.accessType);
-     * }
+     * Check write access (delegates to canAccess).
      */
     async canWrite(targetHolonId, lensName, writerPubKey, options = {}) {
-      // Delegate to unified canAccess method
       const result = await this.canAccess(targetHolonId, lensName, writerPubKey, 'write', options);
-
-      // Convert to legacy format for backward compatibility
       return {
         canWrite: result.allowed,
         reason: result.reason || result.via,
         accessType: result.via,
-        viaHolon: result.viaHolon,
-        grant: result.grant,
       };
     }
 
     /**
-     * Check if an actor can read from a target holon's lens.
-     * Convenience wrapper around canAccess() for read operations.
-     *
-     * @param {string} targetHolonId - The holon being read from
-     * @param {string} lensName - The lens being read from
-     * @param {string} readerPubKey - The reader's public key
-     * @param {Object} [options={}] - Options
-     * @param {string} [options.actingAsHolon] - The holon the reader is acting on behalf of
-     * @param {string} [options.capabilityToken] - Explicit capability token to verify
-     * @returns {Promise<Object>} { canRead: boolean, reason: string, accessType: string }
+     * Check read access (delegates to canAccess).
      */
     async canRead(targetHolonId, lensName, readerPubKey, options = {}) {
-      // Delegate to unified canAccess method
       const result = await this.canAccess(targetHolonId, lensName, readerPubKey, 'read', options);
-
       return {
         canRead: result.allowed,
         reason: result.reason || result.via,
         accessType: result.via,
-        viaHolon: result.viaHolon,
-        grant: result.grant,
       };
     }
 
     /**
      * Get all holons that a public key is a member of.
-     * Searches federation registry and users lenses.
-     *
-     * @param {string} pubKey - The public key to look up
-     * @returns {Promise<Array>} Array of { id, name } for each holon
      */
     async getHolonsForPubKey(pubKey) {
-      const results = [];
-
-      // The user's own holon (their pubkey is also a holon)
-      results.push({ id: pubKey, name: 'Personal Holon' });
+      const results = [{ id: pubKey, name: 'Personal Holon' }];
 
-      // Check federation registry for holons where user has membership
       try {
         const reg = await registry.getFederationRegistry(this.client, this.config.appName);
         if (reg && reg.federatedWith) {
           for (const partner of reg.federatedWith) {
-            // Check if this partner's holon has the user as a member
             try {
               const members = await this.get(partner.pubKey, 'users');
               if (members && Array.isArray(members)) {
                 const isMember = members.some(m =>
-                  m.pubKey === pubKey ||
-                  m.id === pubKey ||
-                  m.nostrPubKey === pubKey
+                  m.pubKey === pubKey || m.id === pubKey || m.nostrPubKey === pubKey
                 );
                 if (isMember) {
                   results.push({ id: partner.pubKey, name: partner.alias || partner.pubKey });
                 }
               }
-            } catch (err) {
-              // Skip holons we can't read
-            }
+            } catch (_err) { /* skip */ }
           }
         }
-      } catch (err) {
-        console.warn('[getHolonsForPubKey] Error reading federation registry:', err.message);
-      }
+      } catch (_err) { /* skip */ }
 
       return results;
     }
 
-    /**
-     * Grant write access to a federated holon for a specific lens.
-     * Members of the granted holon will be able to write to this lens.
-     *
-     * @param {string} holonId - The holon to grant write access to
-     * @param {string} lensName - The lens to grant write access for (or '*' for all)
-     * @param {Object} [options={}] - Grant options
-     * @param {number} [options.expiresAt] - Optional expiration timestamp
-     * @returns {Promise<boolean>} Success indicator
-     *
-     * @example
-     * // Grant holon B write access to quests lens
-     * await hs.grantWriteAccess('holon-b-pubkey', 'quests');
-     */
+    // === Write Grant Backward Compat ===
+
     async grantWriteAccess(holonId, lensName, options = {}) {
-      return registry.grantWriteAccessToHolon(
-        this.client,
-        this.config.appName,
-        holonId,
-        lensName,
-        options
-      );
+      return registry.addFederatedPartner(this.client, this.config.appName, holonId, {
+        addedVia: 'write_grant',
+      });
     }
 
+    // === Share Protocol (Hologram DM as Federation) ===
+
     /**
-     * Revoke write access from a federated holon for a specific lens.
+     * Share data with another user via NIP-44 DM.
+     *
+     * - If `item` is provided → share one item (creates an item hologram on accept)
+     * - If `item` is omitted  → share an entire lens (creates a lens hologram on accept)
      *
-     * @param {string} holonId - The holon to revoke write access from
-     * @param {string} lensName - The lens to revoke write access for
-     * @returns {Promise<boolean>} Success indicator
+     * This replaces `federate()` + `propagateData()` + `initiateFederationHandshake()`
+     * for cross-author cases. Same-author (H3 hierarchical) still uses propagateData().
+     *
+     * @param {string} target - Recipient's hex public key
+     * @param {string} lens - Lens name to share
+     * @param {string|null} [item=null] - Specific data ID, or null for lens-level share
+     * @param {Object} [opts={}] - Options
+     * @param {Array} [opts.keys] - Bundled lens encryption keys [{ path, key }]
+     * @param {string} [opts.msg] - Optional message
+     * @param {string} [opts.sourceHolon] - Source holon ID (defaults to client.publicKey)
+     * @returns {Promise<Object>} { success, shareId?, error? }
      */
-    async revokeWriteAccess(holonId, lensName) {
-      return registry.revokeWriteAccess(
+    async share(target, lens, item = null, opts = {}) {
+      if (!target || typeof target !== 'string') {
+        throw new ValidationError('target must be a valid public key string');
+      }
+      if (!lens || typeof lens !== 'string') {
+        throw new ValidationError('lens must be a non-empty string');
+      }
+      if (!this.client?.privateKey) {
+        throw new ValidationError('Private key required to send share');
+      }
+
+      const sourceHolon = opts.sourceHolon || this.client.publicKey;
+      const author = this.client.publicKey;
+
+      // Bundle lens encryption keys if requested or if we have them
+      let keys = opts.keys || [];
+      if (keys.length === 0 && this.keyStore) {
+        const lensPath = buildLensPath(this.config.appName, sourceHolon, lens);
+        const lensKey = this.keyStore.getKey(lensPath);
+        if (lensKey && this.client.privateKey) {
+          try {
+            const wrappedKey = this.keyStore.wrapKeyForPartner(
+              lensPath,
+              this.client.privateKey,
+              target
+            );
+            if (wrappedKey) {
+              keys = [{ path: lensPath, key: wrappedKey }];
+            }
+          } catch (_err) {
+            // Key wrapping failed — share without keys
+          }
+        }
+      }
+
+      const sent = await federation.sendShare(
         this.client,
-        this.config.appName,
-        holonId,
-        lensName
+        this.client.privateKey,
+        target,
+        {
+          source: sourceHolon,
+          lens,
+          item,
+          author,
+          keys,
+          msg: opts.msg,
+        }
       );
+
+      if (sent) {
+        // Add target to federation registry proactively
+        await registry.addFederatedPartner(
+          this.client, this.config.appName, target,
+          { addedVia: 'share_sent' }
+        );
+        return { success: true };
+      }
+      return { success: false, error: 'Failed to send share DM' };
     }
 
     /**
-     * Get write grants for a specific holon.
+     * Accept an incoming share.
      *
-     * @param {string} holonId - The holon to get write grants for
-     * @returns {Promise<Array>} Array of write grants { lensName, grantedAt, expiresAt }
+     * Stores the hologram locally, adds the sender to the federation registry,
+     * unwraps any bundled keys, and sends a share_ack DM.
+     *
+     * @param {Object} sharePayload - The share DM payload
+     * @param {string} sharePayload.id - Share nonce
+     * @param {string} sharePayload.source - Source holon ID
+     * @param {string} sharePayload.lens - Lens name
+     * @param {string|null} sharePayload.item - Data ID (null for lens-level)
+     * @param {string} sharePayload.author - Author's public key
+     * @param {Array} [sharePayload.keys] - Bundled encryption keys
+     * @param {string} senderPubKey - The pubkey of who sent the share
+     * @param {Object} [opts={}] - Options
+     * @param {string} [opts.holonId] - Local holon to store hologram in (defaults to client.publicKey)
+     * @param {string} [opts.msg] - Optional message in ack
+     * @returns {Promise<Object>} { success, error? }
      */
-    async getWriteGrantsForHolon(holonId) {
-      return registry.getWriteGrantsForHolon(
-        this.client,
-        this.config.appName,
-        holonId
-      );
+    async accept(sharePayload, senderPubKey, opts = {}) {
+      if (!sharePayload || !sharePayload.lens || !sharePayload.author) {
+        throw new ValidationError('Invalid share payload');
+      }
+      if (!this.client?.privateKey) {
+        throw new ValidationError('Private key required to accept share');
+      }
+
+      const localHolon = opts.holonId || this.client.publicKey;
+      const { source, lens, item, author, keys = [] } = sharePayload;
+
+      try {
+        // 1. Create and store the hologram locally
+        let hologram;
+        if (item) {
+          // Item-level hologram
+          hologram = federation.createHologram(
+            source, localHolon, lens, item, this.config.appName,
+            { authorPubKey: author }
+          );
+        } else {
+          // Lens-level hologram
+          hologram = federation.createLensHologram(
+            source, lens, this.config.appName,
+            { author }
+          );
+        }
+
+        const hologramPath = storage.buildPath(
+          this.config.appName, localHolon, lens, hologram.id
+        );
+        await storage.write(this.client, hologramPath, hologram);
+
+        // 2. Add sender to federation registry
+        await registry.addFederatedPartner(
+          this.client, this.config.appName, senderPubKey,
+          { addedVia: 'share_accepted' }
+        );
+
+        // Also add the author if different from sender
+        if (author !== senderPubKey) {
+          await registry.addFederatedPartner(
+            this.client, this.config.appName, author,
+            { addedVia: 'share_accepted_author' }
+          );
+        }
+
+        // Register the source holon -> author pubkey mapping
+        if (source) {
+          await registerHolon(this.client, this.config.appName, source, author, {
+            alias: null,
+          });
+        }
+
+        // 3. Unwrap bundled encryption keys
+        if (keys.length > 0 && this.keyStore && this.client.privateKey) {
+          for (const { path: kPath, key: wrappedKey } of keys) {
+            try {
+              this.keyStore.receiveKey(
+                kPath,
+                wrappedKey,
+                this.client.privateKey,
+                senderPubKey
+              );
+            } catch (_err) {
+              // Key unwrap failed for this entry — continue
+            }
+          }
+        }
+
+        // 4. Send ack DM
+        await federation.sendAck(
+          this.client,
+          this.client.privateKey,
+          senderPubKey,
+          {
+            id: sharePayload.id,
+            source,
+            lens,
+            item,
+            author,
+            status: 'accepted',
+            msg: opts.msg,
+          }
+        );
+
+        return { success: true };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
     }
 
     /**
-     * Get all write grants issued to federated holons.
+     * Reject an incoming share.
+     *
+     * Sends a share_ack DM with status 'rejected'. No local state is changed.
      *
-     * @returns {Promise<Array>} Array of { holonId, alias, writeGrants }
+     * @param {Object} sharePayload - The share DM payload
+     * @param {string} senderPubKey - The pubkey of who sent the share
+     * @param {Object} [opts={}] - Options
+     * @param {string} [opts.msg] - Optional rejection message
+     * @returns {Promise<Object>} { success, error? }
      */
-    async getAllWriteGrants() {
-      return registry.getAllWriteGrants(
-        this.client,
-        this.config.appName
-      );
+    async reject(sharePayload, senderPubKey, opts = {}) {
+      if (!sharePayload || !sharePayload.id) {
+        throw new ValidationError('Invalid share payload');
+      }
+      if (!this.client?.privateKey) {
+        throw new ValidationError('Private key required to reject share');
+      }
+
+      try {
+        await federation.sendAck(
+          this.client,
+          this.client.privateKey,
+          senderPubKey,
+          {
+            id: sharePayload.id,
+            source: sharePayload.source,
+            lens: sharePayload.lens,
+            item: sharePayload.item,
+            author: sharePayload.author,
+            status: 'rejected',
+            msg: opts.msg,
+          }
+        );
+
+        return { success: true };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
     }
+
   };
 }