IPFS ID-RS Sandbox

A comprehensive IPFS (InterPlanetary File System) Identity-based Ring Signatures sandbox environment with private network support, featuring a secure gateway architecture and cross-platform mobile application with dual-mode operation.

🏗️ System Architecture

This project implements a complete IPFS private network with the following components:

Backend Infrastructure

Express.js Gateway: Secure API gateway with exclusive IPFS access
Private IPFS Network: 3-node storage network with shared swarm key
Database: Prisma ORM with SQLite for users, files, and signatures
Cryptography: Ring signatures implementation using node-forge
Docker Orchestration: Containerized infrastructure with health monitoring

Mobile Application

React Native: Cross-platform mobile app (iOS/Android)
Dual-Mode Operation: Online (gateway integration) and Offline (mock layer)
File Management: Document picker, image picker, and comprehensive file operations
IPFS Integration: Complete CRUD operations with private IPFS network
Modern UI: TypeScript-based with theme support and real-time status monitoring

🚀 Quick Start

Prerequisites

Docker Desktop installed and running
Node.js 20+ (for development)
Git
React Native Environment (for mobile development)
- iOS: Xcode, CocoaPods
- Android: Android Studio, Android SDK

1. Clone and Start Backend System

git clone <repository-url>
cd ipfs-sandbox

# Start entire IPFS system (backend + storage nodes)
./start-system.sh

2. Setup Mobile Development

📱 For Android Development

Step 1: Get Your Machine's IP Address

# macOS/Linux
ifconfig | grep "inet " | grep -v "127.0.0.1"
# Output example: inet 192.168.1.69 netmask 0xffffff00

# Windows  
ipconfig
# Look for IPv4 Address under your active network adapter

Step 2: Update Mobile App Configuration

cd mobile/src/config/api.ts

Edit line 17 and replace with your IP:

const HOST_MACHINE_IP = '192.168.1.69'; // 👈 CHANGE THIS TO YOUR IP

Step 3: Install Dependencies

cd mobile/
npm install

# For iOS (macOS only)
cd ios && pod install && cd ..

Step 4: Run Mobile App

# Start Metro bundler (keep running)
npm start

# In another terminal - Run Android app
npm run android

# Or run iOS app (macOS only)
npm run ios

3. Verify System Status

# Check backend services
docker compose ps

# Test backend health
curl http://localhost:3000/health

# Test from your IP (replace with your IP)
curl http://192.168.1.69:3000/health

4. Test CRUD Operations

# Test file upload
curl -X POST -F "file=@your-file.txt" http://localhost:3000/api/files/upload

# Test file download (replace HASH with returned hash)
curl http://localhost:3000/api/files/YOUR_HASH

📊 Services & Endpoints

Backend API (Port 3000)

GET /health - System health check ✅ WORKING
GET /api/users - User management endpoint ✅ WORKING
POST /api/files/upload - Upload files to IPFS ✅ WORKING
GET /api/files/:hash - Download files from IPFS ✅ WORKING
GET /api/files/test-ipfs - Test IPFS connectivity ✅ WORKING
GET /api/signatures - Ring signature operations ✅ WORKING

IPFS Services

IPFS API: http://localhost:5001 ✅ WORKING (Gateway exclusive access)
IPFS Gateway: http://localhost:8080 ✅ WORKING (Public gateway interface)
Storage Nodes: Internal-only (no external ports) ✅ HEALTHY

Mobile App Modes

🌐 Online Mode: Direct gateway integration with real IPFS operations
📱 Offline Mode: Full-featured mock layer for development and testing
🔄 Mode Switching: Real-time switching between online and offline modes

🔒 Security Architecture

Private Network Design

Gateway Exclusivity: Only the gateway container can access IPFS API
Storage Node Isolation: Storage nodes operate without external API exposure
Swarm Key Protection: All nodes use shared private network key (c1df9ee7cb3c82fb83c6935ec7009ad7)
Network Segmentation: Docker internal network for inter-node communication

Authentication & Authorization

Ring signature-based identity verification
Private network access controls
API endpoint protection
File encryption at rest

📱 Mobile Application Features

Dual-Mode Operation

🌐 Online Mode (Gateway Integration)

Real IPFS Operations: Direct connection to gateway at localhost:3000
Network Configurations:
- iOS Simulator: localhost:3000
- Android Emulator: 10.0.2.2:3000
- Physical Device: Actual IP address (e.g., 192.168.1.100:3000)
Health Monitoring: Real-time connection status and error handling
Progress Tracking: Live upload/download progress indicators

📱 Offline Mode (Mock Layer)

Complete UI Testing: All features work without gateway connectivity
Mock IPFS Operations: Realistic simulation with generated hashes
Configurable Delays: Simulate network latency for testing
Error Simulation: Test error handling scenarios
Development Benefits: No dependency on backend services

File Operations (CRUD)

📤 Upload: Single and multiple files with progress tracking
📥 Download: Retrieve files by IPFS hash with blob handling
📋 List: Display all uploaded files with metadata
🗑️ Delete: Remove files from IPFS storage
🔍 Metadata: File size, type, upload time, and IPFS hash management

Ring Signature Operations

Create Signatures: Generate ring signatures for files
Verify Signatures: Validate signature authenticity
List Signatures: Display all signatures with verification status

🛠️ Development

Backend Development

cd backend/

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev

# Database operations
npm run prisma:generate    # Generate Prisma client
npm run prisma:migrate     # Run migrations
npm run prisma:studio      # Database GUI

Mobile Development

Quick Setup

cd mobile/

# Install dependencies
npm install
cd ios && pod install && cd ..  # iOS only

# Start in mock mode (default)
npm run ios

Online Mode Setup

Start Gateway: docker compose up -d (from root directory)
Launch App: App starts in mock mode
Switch to Online: Tap "Switch to Online" in the connection status panel
Configure Network: Ensure proper IP configuration for your platform

Development Workflow

Mock Mode: Develop UI and test functionality offline
Online Mode: Test real gateway integration and network handling
Error Testing: Use both modes to test various error scenarios
Fast Iteration: Mock mode provides immediate feedback

Docker Operations

# Rebuild containers
docker compose build --no-cache

# View container status
docker compose ps

# View logs
docker compose logs -f

# Clean system
docker compose down
docker system prune -a

🧪 Testing

Complete CRUD Operations Test

# Create test file
echo "Hello IPFS Private Network!" > test.txt

# Upload to IPFS
curl -X POST -F "file=@test.txt" http://localhost:3000/api/files/upload

# Expected response:
{
  "success": true,
  "hash": "Qmek5MHc59XAf8JjCXiDwKNBx81QGnzxJ9k6jsTVEAC4te",
  "name": "test.txt",
  "size": 28,
  "ipfsUrl": "http://localhost:8080/ipfs/Qmek5MHc59XAf8JjCXiDwKNBx81QGnzxJ9k6jsTVEAC4te",
  "apiUrl": "http://localhost:5001/api/v0/cat?arg=Qmek5MHc59XAf8JjCXiDwKNBx81QGnzxJ9k6jsTVEAC4te"
}

# Download file
curl http://localhost:3000/api/files/Qmek5MHc59XAf8JjCXiDwKNBx81QGnzxJ9k6jsTVEAC4te
# Output: Hello IPFS Private Network!

Mobile App Testing

Mock Mode Testing (Default)

Launch App: Starts automatically in mock mode
Upload Files: Generates mock IPFS hashes instantly
List Files: Shows uploaded files with metadata
Delete Files: Removes from mock storage
Test Errors: Simulate network failures

Online Mode Testing

Start Gateway: docker compose up -d
Switch Mode: Tap "Switch to Online" in app
Upload Real Files: Get actual IPFS hashes
Download Files: Retrieve from IPFS network
Test Connection: Monitor health status and error recovery

System Health Check

# Check all containers
docker compose ps
# Expected: 4 containers running (gateway + 3 storage nodes)

# Test IPFS connectivity
curl http://localhost:3000/api/files/test-ipfs
# Expected: {"success":true,"ipfsVersion":{"Version":"0.24.0",...}}

# Check IPFS peers
docker exec ipfs-sandbox-gateway-1 ipfs swarm peers
# Expected: 0 (private network, no external peers)

# Verify private network
docker exec ipfs-sandbox-gateway-1 ipfs id
# Expected: Node ID and addresses listed

📁 Project Structure

ipfs-sandbox/
├── backend/                 # Express.js gateway
│   ├── src/
│   │   ├── routes/         # API endpoints
│   │   ├── services/       # IPFS service
│   │   └── config/         # Database config
│   ├── prisma/             # Database schema
│   └── start.sh           # IPFS initialization
├── mobile/                 # React Native app
│   ├── src/
│   │   ├── components/
│   │   │   ├── common/     # Reusable UI components
│   │   │   ├── file-manager/ # File management
│   │   │   └── ipfs/       # IPFS-specific components
│   │   ├── services/
│   │   │   ├── GatewayApiService.ts    # Real API communication
│   │   │   ├── MockApiService.ts       # Mock layer
│   │   │   └── IPFSService.ts         # Unified wrapper
│   │   ├── hooks/
│   │   │   └── useIPFS.ts             # Main IPFS hook
│   │   └── types/         # TypeScript definitions
│   ├── AppWithIPFS.tsx    # Main IPFS demo app
│   ├── ios/               # iOS configuration
│   ├── android/           # Android configuration
│   └── TEST_IPFS_CONNECTIVITY.md  # Testing guide
├── docker-compose.yml     # Container orchestration
├── swarm.key            # Private network key
├── CLAUDE.md            # Development instructions
└── README.md            # This file

🔧 Configuration

Environment Variables

# Backend (.env or docker-compose.yml)
NODE_ENV=development
DATABASE_URL=file:/app/data/database.db
IPFS_PATH=/data/ipfs
LIBP2P_FORCE_PNET=1

IPFS Configuration

Private Network: Enabled with swarm key fingerprint c1df9ee7cb3c82fb83c6935ec7009ad7
API Access: Gateway exclusive (localhost:5001)
Storage Nodes: 3 internal nodes for redundancy
Bootstrap: Disabled (private network only)

Mobile App Configuration

// Online mode configuration
const onlineConfig = {
  useMockApi: false,
  gatewayUrl: 'http://localhost:3000',
  timeout: 30000
};

// Mock mode configuration
const mockConfig = {
  useMockApi: true,
  mockDelay: 1000
};

🚨 Troubleshooting

Mobile App Connection Issues

"IPFS Gateway: Disconnected" in Android App:

Get Your Machine's IP Address:

# macOS/Linux
ifconfig | grep "inet " | grep -v "127.0.0.1"
# Example output: inet 192.168.1.69 netmask 0xffffff00

# Windows
ipconfig
# Look for IPv4 Address under your active WiFi/Ethernet adapter

Update Mobile App Configuration:

# Edit this file:
mobile/src/config/api.ts

# Update line 17 with your IP:
const HOST_MACHINE_IP = '192.168.1.69'; // 👈 CHANGE THIS

Reload Mobile App:
- Android: Press R twice in Metro console, or Ctrl+M -> Reload
- iOS: Cmd+R in simulator

Verify Backend is Accessible:

# Test from your IP (replace with your actual IP)
curl http://192.168.1.69:3000/health
# Should return: {"status":"OK",...}

Common IP Configuration Issues:

WiFi Changes: Your IP changes when switching networks
VPN Active: VPN may change your network configuration
Firewall: Ensure port 3000 is not blocked
Network Type: Ensure both host and emulator are on same network

Quick Reference Commands

Get Your IP for Mobile Setup:

# macOS/Linux - Copy the IP from this command
ifconfig | grep "inet " | grep -v "127.0.0.1" | awk '{print $2}'

# Windows - Look for IPv4 Address
ipconfig | findstr "IPv4"

Development Workflow:

# 1. Start backend
./start-system.sh

# 2. Get your IP and update mobile/src/config/api.ts
ifconfig | grep "inet " | grep -v "127.0.0.1"

# 3. Start mobile app
cd mobile && npm start
cd mobile && npm run android  # In another terminal

Backend Issues

IPFS API not responding:

# Check container logs
docker logs ipfs-sandbox-gateway-1

# Restart gateway
docker compose restart gateway

File upload fails:

# Verify IPFS connectivity
curl http://localhost:3000/api/files/test-ipfs
# Should return: {"success":true,"ipfsVersion":{"Version":"0.24.0",...}}

Storage nodes disconnected:

# Check swarm peers (should be 0 for private network)
docker exec ipfs-sandbox-gateway-1 ipfs swarm peers

# Restart entire system
docker compose down && docker compose up -d

Mobile Issues

Connection failures (Online Mode):

# iOS Simulator
curl http://localhost:3000/health

# Android Emulator
curl http://10.0.2.2:3000/health

# Physical Device (replace with actual IP)
curl http://192.168.1.100:3000/health

React Native build issues:

# Reset Metro cache
npx react-native start --reset-cache

# Clean builds
cd ios && pod deintegrate && pod install && cd ..  # iOS
cd android && ./gradlew clean && cd ..             # Android

# Verify environment
npx react-native doctor

Mock mode not working:

Verify app entry point uses AppWithIPFS
Check useIPFS hook configuration
Ensure mock service initialization

Logs and Monitoring

# All containers
docker compose logs -f

# Specific service
docker logs ipfs-sandbox-gateway-1 -f

# Mobile app debugging
# Use React Native Debugger or browser dev tools

📊 Success Metrics

✅ Backend System

✅ 4/4 Docker containers running healthy
✅ IPFS gateway operational (Kubo v0.24.0)
✅ Private network established with swarm key
✅ API endpoints responding correctly
✅ File upload/download working
✅ Database operations functional

✅ Mobile Application

✅ Dual-mode operation (Online/Offline)
✅ Complete CRUD functionality
✅ Real-time connection monitoring
✅ File upload with progress tracking
✅ Error handling and recovery
✅ Mock layer for offline development
✅ TypeScript type safety
✅ Modern UI with theme support

✅ Integration Testing

✅ Mobile-to-Gateway communication
✅ File operations across platforms
✅ Network error handling
✅ Mode switching functionality
✅ Progress indicators and status updates

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Test in both online and offline modes
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Documentation

CLAUDE.md - Claude Code development instructions
Mobile README - Comprehensive mobile app documentation
Mobile Testing Guide - Mobile connectivity testing
IPFS Documentation - Official IPFS docs
React Native Docs - React Native development
Docker Compose - Container orchestration

Status: ✅ Fully Functional - Complete system with CRUD operations, private IPFS network, and dual-mode mobile application ready for production use.

Recent Updates

✅ Complete mobile app integration with gateway
✅ Dual-mode operation (Online/Offline) implemented
✅ Mock layer for offline development
✅ Real-time connection monitoring
✅ Comprehensive error handling
✅ Progress tracking and status indicators
✅ Full CRUD operations tested and verified

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.idea		.idea
backend		backend
mobile		mobile
.dockerignore		.dockerignore
.env		.env
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
HUONG_DAN_PHAT_TRIEN.md		HUONG_DAN_PHAT_TRIEN.md
Makefile		Makefile
PROJECT_STATUS_REPORT.md		PROJECT_STATUS_REPORT.md
README.md		README.md
SCRIPTS.md		SCRIPTS.md
STATUS.md		STATUS.md
check-status.sh		check-status.sh
clean-docker.sh		clean-docker.sh
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
start-system.sh		start-system.sh
swarm.key		swarm.key
test-ipfs-functionality.sh		test-ipfs-functionality.sh
test-mobile.txt		test-mobile.txt
test.txt		test.txt

nguyenphuc22/ipfs-sandbox

Folders and files

Latest commit

History

Repository files navigation