holosphere 2.0.0-alpha13 → 2.0.0-alpha15

package/src/lib/federation-methods.js

@@ -80,13 +80,17 @@ export function withFederationMethods(Base) {
       } = options;
 
       // Normalize source and target to { holonId, authorPubKey } format
+      // Helper function to detect if a string is a pubkey (64-char hex)
+      const isPubkey = (str) => typeof str === 'string' && /^[0-9a-f]{64}$/i.test(str);
+
+      // When the holon ID is a pubkey, use it as the authorPubKey for cross-holosphere federation
       const normalizedSource = typeof source === 'string'
-        ? { holonId: source, authorPubKey: this.client.publicKey }
-        : { holonId: source.holonId, authorPubKey: source.authorPubKey || this.client.publicKey };
+        ? { holonId: source, authorPubKey: isPubkey(source) ? source : this.client.publicKey }
+        : { holonId: source.holonId, authorPubKey: source.authorPubKey || (isPubkey(source.holonId) ? source.holonId : this.client.publicKey) };
 
       const normalizedTarget = typeof target === 'string'
-        ? { holonId: target, authorPubKey: this.client.publicKey }
-        : { holonId: target.holonId, authorPubKey: target.authorPubKey || this.client.publicKey };
+        ? { holonId: target, authorPubKey: isPubkey(target) ? target : this.client.publicKey }
+        : { holonId: target.holonId, authorPubKey: target.authorPubKey || (isPubkey(target.holonId) ? target.holonId : this.client.publicKey) };
 
       // Validation
       if (normalizedSource.holonId === normalizedTarget.holonId &&
@@ -861,6 +865,306 @@ export function withFederationMethods(Base) {
 
       return results;
     }
+
+    // === UNIFIED ACCESS CONTROL ===
+
+    /**
+     * 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
+     * });
+     */
+    async canAccess(targetHolonId, lensName, actorPubKey, permission, options = {}) {
+      const { actingAsHolon = null, capabilityToken = null } = options;
+
+      // 1. Owner check - actor owns the target holon
+      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);
+        }
+      }
+
+      // 3. Membership in target holon
+      try {
+        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
+          );
+          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,
+            };
+          }
+        }
+      }
+
+      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);
+     * }
+     */
+    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 }
+     */
+    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' });
+
+      // 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
+                );
+                if (isMember) {
+                  results.push({ id: partner.pubKey, name: partner.alias || partner.pubKey });
+                }
+              }
+            } catch (err) {
+              // Skip holons we can't read
+            }
+          }
+        }
+      } catch (err) {
+        console.warn('[getHolonsForPubKey] Error reading federation registry:', err.message);
+      }
+
+      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');
+     */
+    async grantWriteAccess(holonId, lensName, options = {}) {
+      return registry.grantWriteAccessToHolon(
+        this.client,
+        this.config.appName,
+        holonId,
+        lensName,
+        options
+      );
+    }
+
+    /**
+     * Revoke write access from a federated holon for a specific lens.
+     *
+     * @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
+     */
+    async revokeWriteAccess(holonId, lensName) {
+      return registry.revokeWriteAccess(
+        this.client,
+        this.config.appName,
+        holonId,
+        lensName
+      );
+    }
+
+    /**
+     * Get write grants for a specific holon.
+     *
+     * @param {string} holonId - The holon to get write grants for
+     * @returns {Promise<Array>} Array of write grants { lensName, grantedAt, expiresAt }
+     */
+    async getWriteGrantsForHolon(holonId) {
+      return registry.getWriteGrantsForHolon(
+        this.client,
+        this.config.appName,
+        holonId
+      );
+    }
+
+    /**
+     * Get all write grants issued to federated holons.
+     *
+     * @returns {Promise<Array>} Array of { holonId, alias, writeGrants }
+     */
+    async getAllWriteGrants() {
+      return registry.getAllWriteGrants(
+        this.client,
+        this.config.appName
+      );
+    }
   };
 }