@nomyx/gunfs NPM

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:

Clone the repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
This will create separate builds for Node.js and web environments.
Run tests:
```
npm test
```
Start the project:
```
npm start
```
Lint the code:
```
npm run lint
```