gun-eth 2.0.1 → 3.0.1

package/dist/types/features/bubbles/providers/base-bubble-provider.d.ts

@@ -0,0 +1,303 @@
+/**
+ * @typedef {Object} BubbleProviderOptions
+ * @property {string} rpcUrl - RPC URL for the provider
+ * @property {string} chain - Chain name (e.g. 'localhost', 'optimismSepolia')
+ * @property {Object} gun - Gun instance
+ * @property {Object} keypair - Keypair for encryption
+ * @property {string} keypair.epub - Public encryption key
+ * @property {string} keypair.epriv - Private encryption key
+ * @property {string} [contractAddress] - Optional custom contract address
+ * @property {Object} [contractAbi] - Optional custom contract ABI
+ */
+/**
+ * @typedef {Object} BubbleDetails
+ * @property {string} id - Bubble ID
+ * @property {string} name - Bubble name
+ * @property {string} owner - Owner's Ethereum address
+ * @property {boolean} isPrivate - Whether the bubble is private
+ * @property {number} createdAt - Creation timestamp
+ */
+/**
+ * @typedef {Object} FileMetadata
+ * @property {string} name - File name
+ * @property {string} owner - File owner
+ * @property {string} filePath - File path
+ * @property {number} created - Creation timestamp
+ * @property {number} updated - Last update timestamp
+ * @property {number} size - File size in bytes
+ * @property {Object} encryptionInfo - Encryption info
+ * @property {string} encryptionInfo.ownerEpub - Owner's public key
+ * @property {string} encryptionInfo.ownerAddress - Owner's address
+ */
+/**
+ * @typedef {Object} DeleteResult
+ * @property {boolean} success - Whether deletion was successful
+ * @property {string} [message] - Optional status message
+ */
+/**
+ * @typedef {Object} DeleteBubbleResult
+ * @property {boolean} success - Whether deletion was successful
+ * @property {string} [message] - Optional status message
+ */
+/**
+ * Base class for bubble storage providers
+ */
+export class BaseBubbleProvider {
+    /**
+     * Creates a new bubble provider instance
+     * @param {BubbleProviderOptions} options - Provider configuration options
+     */
+    constructor(options: BubbleProviderOptions);
+    provider: ethers.JsonRpcProvider;
+    /** @type {BubbleRegistryContract} */
+    contract: BubbleRegistryContract;
+    gun: any;
+    keypair: {
+        /**
+         * - Public encryption key
+         */
+        epub: string;
+        /**
+         * - Private encryption key
+         */
+        epriv: string;
+    };
+    bubbleRoot: any;
+    keyPairs: Map<any, any>;
+    /**
+     * Verifies request signature
+     * @param {string} address - Ethereum address of the requester
+     * @param {string} message - Message that was signed
+     * @param {string} signature - Signature of the message
+     * @returns {Promise<boolean>} - Whether the signature is valid
+     */
+    verifyRequest(address: string, message: string, signature: string): Promise<boolean>;
+    /**
+     * Manages user keys
+     * @param {string} address - Ethereum address of the user
+     * @returns {Promise<Object>} - Key pair of the user
+     */
+    getUserKeyPair(address: string): Promise<any>;
+    /**
+     * Verifies bubble access
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} userAddress - Ethereum address of the user
+     * @returns {Promise<boolean>} - Whether the user has access to the bubble
+     */
+    verifyBubbleAccess(bubbleId: string, userAddress: string): Promise<boolean>;
+    /**
+     * Verifies bubble ownership
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} ownerAddress - Ethereum address of the owner
+     * @returns {Promise<boolean>} - Whether the user is the owner of the bubble
+     */
+    verifyBubbleOwnership(bubbleId: string, ownerAddress: string): Promise<boolean>;
+    /**
+     * Grants on-chain access to a target address
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} targetAddress - Ethereum address to grant access to
+     * @returns {Promise<void>}
+     */
+    grantOnChainAccess(bubbleId: string, targetAddress: string): Promise<void>;
+    /**
+     * Puts data into GunDB
+     * @param {string} path - Path in GunDB
+     * @param {Object} data - Data to put
+     * @param {number} [maxRetries=3] - Maximum number of retries
+     * @returns {Promise<void>}
+     */
+    putGunData(path: string, data: any, maxRetries?: number): Promise<void>;
+    /**
+     * Gets a node from GunDB
+     * @typedef {Object} GunNode
+     * @property {Object} data - Data of the node (if any)
+     * @property {string} err - Error message if any
+     * @property {any} content - Content of the node
+     * @param {string} path - Path in GunDB
+     * @param {number} [maxRetries=3] - Maximum number of retries
+     * @returns {Promise<GunNode>} - Node data
+     */
+    getGunNode(path: string, maxRetries?: number): Promise<{
+        /**
+         * - Data of the node (if any)
+         */
+        data: any;
+        /**
+         * - Error message if any
+         */
+        err: string;
+        /**
+         * - Content of the node
+         */
+        content: any;
+    }>;
+    /**
+     * Handles bubble creation
+     * @param {Object} params - Parameters for bubble creation
+     * @param {string} params.name - Name of the bubble
+     * @param {boolean} params.isPrivate - Whether the bubble is private
+     * @param {string} params.userAddress - Ethereum address of the user
+     * @returns {Promise<BubbleDetails>} - Metadata of the created bubble
+     */
+    handleCreateBubble(params: {
+        name: string;
+        isPrivate: boolean;
+        userAddress: string;
+    }): Promise<BubbleDetails>;
+    /**
+     * Handles granting permission to a bubble
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} targetAddress - Ethereum address of the target user
+     * @param {string} granterAddress - Ethereum address of the granter
+     * @param {Object} options - Additional options
+     * @param {string} options.granteeEpub - Public encryption key of the grantee
+     * @returns {Promise<Object>} - Result of the permission grant
+     */
+    handleGrantPermission(bubbleId: string, targetAddress: string, granterAddress: string, options: {
+        granteeEpub: string;
+    }): Promise<any>;
+    /**
+     * Handles file upload to a bubble
+     * @abstract
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} fileName - Name of the file
+     * @param {string} content - File content
+     * @param {string} userAddress - Ethereum address of the uploader
+     * @returns {Promise<FileMetadata>} - Metadata of the uploaded file
+     */
+    handleFileUpload(bubbleId: string, fileName: string, content: string, userAddress: string): Promise<FileMetadata>;
+    /**
+     * Handles file deletion from a bubble
+     * @abstract
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} fileName - Name of the file
+     * @param {string} userAddress - Ethereum address of the user
+     * @returns {Promise<DeleteResult>} - Result of the deletion
+     */
+    handleDeleteFile(bubbleId: string, fileName: string, userAddress: string): Promise<DeleteResult>;
+    /**
+     * Handles file download from a bubble
+     * @abstract
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} fileName - Name of the file
+     * @param {string} userAddress - Ethereum address of the user
+     * @returns {Promise<{content: any, metadata: Object}>} - File content and metadata
+     */
+    handleFileDownload(bubbleId: string, fileName: string, userAddress: string): Promise<{
+        content: any;
+        metadata: any;
+    }>;
+    /**
+     * Handles bubble deletion
+     * @abstract
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} userAddress - Ethereum address of the user
+     * @returns {Promise<DeleteBubbleResult>} - Result of the deletion
+     */
+    handleDeleteBubble(bubbleId: string, userAddress: string): Promise<DeleteBubbleResult>;
+}
+export type BubbleProviderOptions = {
+    /**
+     * - RPC URL for the provider
+     */
+    rpcUrl: string;
+    /**
+     * - Chain name (e.g. 'localhost', 'optimismSepolia')
+     */
+    chain: string;
+    /**
+     * - Gun instance
+     */
+    gun: any;
+    /**
+     * - Keypair for encryption
+     */
+    keypair: {
+        epub: string;
+        epriv: string;
+    };
+    /**
+     * - Optional custom contract address
+     */
+    contractAddress?: string;
+    /**
+     * - Optional custom contract ABI
+     */
+    contractAbi?: any;
+};
+export type BubbleDetails = {
+    /**
+     * - Bubble ID
+     */
+    id: string;
+    /**
+     * - Bubble name
+     */
+    name: string;
+    /**
+     * - Owner's Ethereum address
+     */
+    owner: string;
+    /**
+     * - Whether the bubble is private
+     */
+    isPrivate: boolean;
+    /**
+     * - Creation timestamp
+     */
+    createdAt: number;
+};
+export type FileMetadata = {
+    /**
+     * - File name
+     */
+    name: string;
+    /**
+     * - File owner
+     */
+    owner: string;
+    /**
+     * - File path
+     */
+    filePath: string;
+    /**
+     * - Creation timestamp
+     */
+    created: number;
+    /**
+     * - Last update timestamp
+     */
+    updated: number;
+    /**
+     * - File size in bytes
+     */
+    size: number;
+    /**
+     * - Encryption info
+     */
+    encryptionInfo: {
+        ownerEpub: string;
+        ownerAddress: string;
+    };
+};
+export type DeleteResult = {
+    /**
+     * - Whether deletion was successful
+     */
+    success: boolean;
+    /**
+     * - Optional status message
+     */
+    message?: string;
+};
+export type DeleteBubbleResult = {
+    /**
+     * - Whether deletion was successful
+     */
+    success: boolean;
+    /**
+     * - Optional status message
+     */
+    message?: string;
+};
+import { ethers } from 'ethers';

package/dist/types/features/bubbles/providers/gun-bubble-provider.d.ts

@@ -0,0 +1,173 @@
+export class GUNBubbleProvider extends BaseBubbleProvider {
+    constructor(options: any);
+    user: any;
+    /**
+     * @typedef {Object} FileDownloadParams
+     * @property {string} bubbleId - ID of the bubble
+     * @property {string} fileName - Name of the file to download
+     * @property {string} userAddress - Ethereum address of the user
+     */
+    /**
+     * Handles file download
+     * @param {string} bubbleId - ID of the bubble
+     * @param {string} fileName - Name of the file to download
+     * @param {string} userAddress - Ethereum address of the user
+     */
+    handleFileDownload(bubbleId: string, fileName: string, userAddress: string): Promise<{
+        content: any;
+        metadata: {
+            name: any;
+            owner: any;
+            filePath: any;
+            created: any;
+            updated: any;
+            size: any;
+            readOnly: any;
+            encryptionInfo: any;
+        };
+    }>;
+    /**
+     * @typedef {Object} FileUploadOptions
+     * @property {string} bubbleId - ID of the bubble
+     * @property {string} fileName - Name of the file
+     * @property {string} content - Content of the file
+     * @property {string} userAddress - Address of the user
+     */
+    handleFileUpload(bubbleId: any, fileName: any, content: any, userAddress: any): Promise<any>;
+    /**
+     * @typedef {Object} GrantPermissionOptions
+     * @property {string} granteeEpub - Public encryption key of grantee
+     */
+    handleGrantPermission(bubbleId: any, targetAddress: any, granterAddress: any, options?: {}): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * @typedef {Object} BubbleParams
+     * @property {string} name - The name of the bubble
+     * @property {boolean} isPrivate - Whether the bubble is private
+     * @property {string} userAddress - The address of the user creating the bubble
+     */
+    /**
+     * Handles the creation of a new bubble.
+     * @param {BubbleParams} params - The parameters for bubble creation
+     */
+    handleCreateBubble(params: {
+        /**
+         * - The name of the bubble
+         */
+        name: string;
+        /**
+         * - Whether the bubble is private
+         */
+        isPrivate: boolean;
+        /**
+         * - The address of the user creating the bubble
+         */
+        userAddress: string;
+    }): Promise<{
+        id: any;
+        name: string;
+        owner: string;
+        isPrivate: boolean;
+        createdAt: number;
+    }>;
+    /**
+     * @typedef {Object} DeleteFileOptions
+     * @property {string} bubbleId - The ID of the bubble
+     * @property {string} fileName - The name of the file to delete
+     * @property {string} userAddress - The address of the user requesting the deletion
+     */
+    handleDeleteFile(bubbleId: any, fileName: any, userAddress: any): Promise<any>;
+    /**
+     * @typedef {Object} DeleteBubbleResult
+     * @property {boolean} success - Indicates if the bubble was successfully deleted
+     */
+    /**
+     * Deletes a bubble and all its contents.
+     * @param {string} bubbleId - The ID of the bubble to delete.
+     * @param {string} userAddress - The address of the user requesting the deletion.
+     * @returns {Promise<DeleteBubbleResult>} - The result of the deletion operation.
+     */
+    handleDeleteBubble(bubbleId: string, userAddress: string): Promise<{
+        /**
+         * - Indicates if the bubble was successfully deleted
+         */
+        success: boolean;
+    }>;
+}
+export type FileMetadata = {
+    /**
+     * - Name of the file
+     */
+    name: string;
+    /**
+     * - Address of file owner
+     */
+    owner: string;
+    /**
+     * - Creation timestamp
+     */
+    created: number;
+    /**
+     * - Last update timestamp
+     */
+    updated: number;
+    /**
+     * - File path
+     */
+    filePath: string;
+    /**
+     * - File size
+     */
+    size: number;
+    /**
+     * - Encryption info
+     */
+    encryptionInfo: {
+        ownerEpub: string;
+        ownerAddress: string;
+    };
+    /**
+     * - Whether file is read-only
+     */
+    readOnly: boolean;
+};
+export type BubbleMetadata = {
+    /**
+     * - Unique bubble ID
+     */
+    id: string;
+    /**
+     * - Name of the bubble
+     */
+    name: string;
+    /**
+     * - Address of bubble owner
+     */
+    owner: string;
+    /**
+     * - Whether bubble is private
+     */
+    isPrivate: boolean;
+    /**
+     * - Creation timestamp
+     */
+    createdAt: number;
+};
+export type FileDownloadResult = {
+    /**
+     * - Decrypted file content
+     */
+    content: string;
+    /**
+     * - File metadata
+     */
+    metadata: FileMetadata;
+};
+export type GrantPermissionOptions = {
+    /**
+     * - Public encryption key of grantee
+     */
+    granteeEpub: string;
+};
+import { BaseBubbleProvider } from './base-bubble-provider.js';

package/dist/types/features/bubbles/providers/hybrid-bubble-provider.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Options for initializing a HybridBubbleProvider
+ * @typedef {Object} HybridBubbleProviderOptions
+ * @property {string} rpcUrl - RPC URL for the provider
+ * @property {string} contractAddress - Address of the bubble registry contract
+ * @property {Object} [contractAbi] - ABI of the bubble registry contract
+ * @property {Object} gun - Gun instance
+ * @property {Object} keypair - Key pair for encryption
+ */
+/**
+ * Extended Gun node with additional file metadata
+ * @typedef {Object} ExtendedGunNode
+ * @property {string} filePath - Path to the file on disk
+ * @property {string} owner - Address of file owner
+ * @property {string} content - Encrypted file content
+ * @property {string} [name] - File name
+ * @property {number} [created] - Creation timestamp
+ * @property {number} [updated] - Last update timestamp
+ * @property {number} [size] - File size in bytes
+ * @property {{ ownerEpub: string, ownerAddress: string }} [encryptionInfo] - Encryption metadata
+ */
+/** @typedef {import('./base-bubble-provider.js').BubbleProviderOptions} BubbleProviderOptions */
+/** @typedef {import('./base-bubble-provider.js').FileMetadata} FileMetadata */
+/** @typedef {import('./gun-bubble-provider.js').FileDownloadResult} FileDownloadResult */
+/** @typedef {import('./base-bubble-provider.js').DeleteResult} DeleteResult */
+/** @typedef {Object} GunNode */
+/** @typedef {GunNode & ExtendedGunNode} FileGunNode */
+export class HybridBubbleProvider extends BaseBubbleProvider {
+    /**
+     * @param {import("fs").PathLike} dir
+     */
+    ensureDirectory(dir: import("fs").PathLike): Promise<void>;
+    getFilePath(bubbleId: any, fileName: any): string;
+    /**
+     * Handles file download
+     * @param {string} bubbleId
+     * @param {string} fileName
+     * @param {string} userAddress
+     * @returns {Promise<FileDownloadResult>}
+     */
+    handleFileDownload(bubbleId: string, fileName: string, userAddress: string): Promise<FileDownloadResult>;
+    handleGrantPermission(bubbleId: any, targetAddress: any, granterAddress: any, options?: {}): Promise<{
+        success: boolean;
+    }>;
+    handleCreateBubble(params: any): Promise<{
+        id: any;
+        name: any;
+        owner: any;
+        isPrivate: boolean;
+        createdAt: number;
+    }>;
+}
+/**
+ * Options for initializing a HybridBubbleProvider
+ */
+export type HybridBubbleProviderOptions = {
+    /**
+     * - RPC URL for the provider
+     */
+    rpcUrl: string;
+    /**
+     * - Address of the bubble registry contract
+     */
+    contractAddress: string;
+    /**
+     * - ABI of the bubble registry contract
+     */
+    contractAbi?: any;
+    /**
+     * - Gun instance
+     */
+    gun: any;
+    /**
+     * - Key pair for encryption
+     */
+    keypair: any;
+};
+/**
+ * Extended Gun node with additional file metadata
+ */
+export type ExtendedGunNode = {
+    /**
+     * - Path to the file on disk
+     */
+    filePath: string;
+    /**
+     * - Address of file owner
+     */
+    owner: string;
+    /**
+     * - Encrypted file content
+     */
+    content: string;
+    /**
+     * - File name
+     */
+    name?: string;
+    /**
+     * - Creation timestamp
+     */
+    created?: number;
+    /**
+     * - Last update timestamp
+     */
+    updated?: number;
+    /**
+     * - File size in bytes
+     */
+    size?: number;
+    /**
+     * - Encryption metadata
+     */
+    encryptionInfo?: {
+        ownerEpub: string;
+        ownerAddress: string;
+    };
+};
+export type BubbleProviderOptions = import("./base-bubble-provider.js").BubbleProviderOptions;
+export type FileMetadata = import("./base-bubble-provider.js").FileMetadata;
+export type FileDownloadResult = import("./gun-bubble-provider.js").FileDownloadResult;
+export type DeleteResult = import("./base-bubble-provider.js").DeleteResult;
+export type GunNode = any;
+export type FileGunNode = GunNode & ExtendedGunNode;
+import { BaseBubbleProvider } from './base-bubble-provider.js';