GunFS

GunFS is a decentralized file system and communication platform built on top of Gun.js. It provides secure, encrypted storage and real-time synchronization for files, chat sessions, and terminal sessions. The core functionality is designed to be portable across web and Node.js environments.

Features

• Decentralized file system with directory and file management
• Secure, encrypted chat sessions
• Encrypted terminal sessions with a busybox-like shell (Node.js environment only)
• User authentication and management
• Fine-grained access control for files, chats, and terminal sessions
• Standalone mode for running a GunFS server (Node.js environment only)
• Client mode with the ability to connect to standalone servers
• JavaScript code execution in a sandboxed environment, including execution from files
• Built with TypeScript for improved developer experience and type safety
• Modular architecture with service providers for easy extensibility and environment-specific implementations
• Separate builds for Node.js and web environments

Installation

To install GunFS, use npm:

npm install @nomyx/gunfs

Usage

Web Environment

For web applications, import the library as follows:

import { initializeGunFS, GunFSConfig } from '@nomyx/gunfs';

Node.js Environment

For Node.js applications, import the library as follows:

const { initializeNodeGunFS, GunFSConfig } = require('@nomyx/gunfs/node');

Here's a basic example of how to use GunFS in client mode (works in both web and Node.js environments):

import Gun from 'gun';
import { initializeGunFS, UserCredentials, GunFSConfig } from '@nomyx/gunfs';

// Initialize Gun and GunFS in client mode
const config: GunFSConfig = {
  mode: 'client',
  peers: ['http://localhost:8765/gun'] // Connect to a standalone server
};
const gunInstance = Gun();
const { serviceProvider, userManager, filesystem, decentralizedShell, chatSession } = initializeGunFS(gunInstance, config);

async function main() {
  // User registration
  const credentials: UserCredentials = { alias: 'user1', password: 'password123' };
  await userManager.register(credentials);

  // User login
  await userManager.login(credentials);

  // Create a directory
  await filesystem.createDirectory('/', 'my_folder');

  // Create a file
  await filesystem.createFile('/my_folder', 'hello.txt', 'Hello, World!');

  // Read a file
  const content = await filesystem.readFile('/my_folder/hello.txt');
  console.log(content); // Outputs: Hello, World!

  // Use the decentralized shell
  const result = await decentralizedShell.executeCommand('ls /my_folder');
  console.log(result); // Outputs: hello.txt

  // Create a chat session
  await chatSession.createSession('my_chat', ['user2_public_key']);

  // Send a message
  await chatSession.sendMessage('my_chat', 'Hello, User2!');

  // Read messages
  const messages = await chatSession.readMessages('my_chat');
  console.log(messages);

  // Execute JavaScript code
  const codeResult = await decentralizedShell.executeCommand('execute console.log("Hello from sandboxed environment!")');
  console.log(codeResult);
}

main().catch(console.error);

Node.js-specific Features

Some features, such as terminal sessions and standalone mode, are only available in Node.js environments. To use these features, you need to use the Node.js-specific initialization:

const { initializeNodeGunFS, GunFSConfig } = require('@nomyx/gunfs/node');

const config: GunFSConfig = {
  mode: 'standalone',
  port: 8765
};
const gunInstance = Gun();
const { serviceProvider, userManager, filesystem, decentralizedShell, terminalSession, chatSession } = initializeNodeGunFS(gunInstance, config);

// Now you can use terminalSession and other Node.js-specific features

Standalone Mode

To run GunFS in standalone mode (Node.js environment only):

const { startStandaloneServer } = require('@nomyx/gunfs/node');

const port = 8765; // Optional, defaults to 8765
const standaloneServer = startStandaloneServer(port);
console.log(`GunFS standalone server is running on port ${port}`);

This will start a Gun.js server on the specified port and initialize the GunFS root node.

Code Execution

GunFS provides a sandboxed environment for executing JavaScript code. This feature is available in both client and standalone modes:

import { executeCode } from '@nomyx/gunfs';

// Execute code directly
const result = executeCode('console.log("Hello, World!"); return 42;', vmService);
console.log(result); // Outputs: { result: 42 }

In the DecentralizedShell, you can execute code using the execute command:

// Execute code directly
const result = await decentralizedShell.executeCommand('execute console.log("Hello, World!"); return 42;');

Architecture

GunFS uses a modular architecture based on service providers. This allows for easy extensibility and the ability to swap out implementations for different environments.

Service Interfaces

• TerminalSessionService: Handles execution of terminal commands (Node.js only)
• AIChatService: Provides AI-powered chat functionality
• FileWriteService: Manages file read and write operations
• VMService: Provides a sandboxed environment for code execution

ServiceProvider

The ServiceProvider interface defines methods to get instances of the above services. The core library provides default implementations that throw errors when used in unsupported environments. You can provide custom implementations for environment-specific features.

NodeServiceProvider

For Node.js environments, we provide a NodeServiceProvider that implements concrete versions of these services, including support for terminal sessions and file system operations.

API Documentation

(The rest of the API documentation remains the same)

Dependencies

• gun: ^0.2020.1240
• uuid: ^10.0.0

Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/nomyx/gunfs.git
   cd gunfs

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

   This will create separate builds for Node.js and web environments.

4. Run tests:

   npm test

5. Start the project:

   npm start

6. Lint the code:

   npm run lint

Building and Publishing

To build the project for production:

1. Update the version in package.json
2. Run npm run build
3. Test the build: npm test
4. Commit changes and push to the repository
5. Create a new release on GitHub
6. Publish to npm: npm publish --access public

This will create separate bundles for Node.js and web environments.

License

This project is licensed under the ISC License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you have any questions or need help with GunFS, please open an issue in the GitHub repository.