Merge pull request #88 from jobbykings/feature/implement-backend-features

feat: Implement comprehensive backend features for SubStream Protocol

Author: elizabetheonoja-art

.env.example

@@ -0,0 +1,28 @@
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# JWT Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+
+# Pinata Configuration
+PINATA_API_KEY=your-pinata-api-key
+PINATA_SECRET_KEY=your-pinata-secret-key
+
+# Web3.Storage Configuration
+WEB3STORAGE_API_KEY=your-web3-storage-api-key
+
+# Infura IPFS Configuration
+INFURA_API_KEY=your-infura-api-key
+
+# Database Configuration (for production)
+# DATABASE_URL=postgresql://username:password@localhost:5432/substream
+
+# Redis Configuration (for production caching)
+# REDIS_URL=redis://localhost:6379
+
+# Analytics Database (for production)
+# INFLUXDB_URL=http://localhost:8086
+# INFLUXDB_TOKEN=your-influxdb-token
+# INFLUXDB_ORG=your-org
+# INFLUXDB_BUCKET=substream-analytics

README.md

@@ -0,0 +1,215 @@
+# SubStream Protocol Backend
+
+A comprehensive backend API for the SubStream Protocol, supporting wallet-based authentication, tier-based content access, real-time analytics, and multi-region storage replication.
+
+## Features
+
+### 🔐 Authentication (SIWE)
+- Wallet-based authentication using Sign In With Ethereum
+- JWT token generation and validation
+- Nonce-based security
+- Multi-tier user support (Bronze, Silver, Gold)
+
+### 📊 Real-time Analytics
+- View-time event aggregation
+- On-chain withdrawal event tracking
+- Heatmap generation for content engagement
+- Server-sent events for real-time updates
+- Creator analytics dashboard
+
+### 🌍 Multi-Region Storage
+- IPFS content replication across multiple services
+- Automatic failover between regions
+- Health monitoring and service recovery
+- Support for Pinata, Web3.Storage, and Infura
+
+### 🛡️ Tier-Based Access Control
+- Content filtering based on user subscription tier
+- Censored previews for unauthorized content
+- Database-level access control
+- Upgrade suggestions and tier management
+
+## Quick Start
+
+### Prerequisites
+- Node.js 16+
+- npm or yarn
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/jobbykings/SubStream-Protocol-Backend.git
+cd SubStream-Protocol-Backend
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Copy environment variables:
+```bash
+cp .env.example .env
+```
+
+4. Configure your environment variables in `.env`:
+- Set your JWT secret
+- Add IPFS service API keys
+- Configure database connections (optional for development)
+
+5. Start the server:
+```bash
+# Development
+npm run dev
+
+# Production
+npm start
+```
+
+The API will be available at `http://localhost:3000`
+
+## API Endpoints
+
+### Authentication
+- `GET /auth/nonce?address={address}` - Get nonce for SIWE
+- `POST /auth/login` - Authenticate with wallet signature
+
+### Content
+- `GET /content` - List content (filtered by user tier)
+- `GET /content/{id}` - Get specific content
+- `POST /content` - Create new content (requires authentication)
+- `PUT /content/{id}` - Update content (creator only)
+- `DELETE /content/{id}` - Delete content (creator only)
+- `GET /content/{id}/access` - Check access permissions
+- `GET /content/upgrade/suggestions` - Get upgrade suggestions
+
+### Analytics
+- `POST /analytics/view-event` - Record view-time event
+- `POST /analytics/withdrawal-event` - Record withdrawal event
+- `GET /analytics/heatmap/{videoId}` - Get content heatmap
+- `GET /analytics/creator/{address}` - Get creator analytics
+- `GET /analytics/stream/{videoId}` - Real-time analytics stream
+
+### Storage
+- `POST /storage/pin` - Pin content to multiple regions
+- `GET /storage/content/{id}` - Get content with failover
+- `GET /storage/metadata/{id}` - Get content metadata
+- `GET /storage/health` - Check storage service health
+- `GET /storage/url/{id}` - Get content URLs
+
+### System
+- `GET /` - API information
+- `GET /health` - Health check
+
+## Usage Examples
+
+### Authentication
+```javascript
+// 1. Get nonce
+const nonceResponse = await fetch('/auth/nonce?address=0x742d35Cc6634C0532925a3b8D4C9db96C4b4Db45');
+const { nonce } = await nonceResponse.json();
+
+// 2. Sign message with wallet
+const message = `Sign in to SubStream Protocol at ${new Date().toISOString()}\n\nNonce: ${nonce}\nAddress: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4Db45`;
+const signature = await signer.signMessage(message);
+
+// 3. Login
+const loginResponse = await fetch('/auth/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ address, signature, message, nonce })
+});
+const { token } = await loginResponse.json();
+```
+
+### Content Access
+```javascript
+// Get content list (automatically filtered by tier)
+const response = await fetch('/content', {
+  headers: { 'Authorization': `Bearer ${token}` }
+});
+const { content } = await response.json();
+
+// Content will be full or censored based on user tier
+```
+
+### Analytics
+```javascript
+// Record view event
+await fetch('/analytics/view-event', {
+  method: 'POST',
+  headers: { 
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    videoId: 'video_001',
+    watchTime: 120,
+    totalDuration: 300
+  })
+});
+
+// Get heatmap
+const heatmapResponse = await fetch('/analytics/heatmap/video_001', {
+  headers: { 'Authorization': `Bearer ${token}` }
+});
+```
+
+## Architecture
+
+### Services
+- **AuthService**: Handles SIWE authentication and JWT management
+- **ContentService**: Manages content with tier-based filtering
+- **AnalyticsService**: Processes real-time analytics and generates heatmaps
+- **StorageService**: Manages multi-region IPFS replication
+
+### Middleware
+- **Authentication**: JWT token validation
+- **Tier Access**: Role-based access control
+- **Error Handling**: Centralized error management
+
+### Data Flow
+1. User authenticates via wallet signature
+2. JWT token issued with tier information
+3. All subsequent requests include token
+4. Content filtered based on user tier
+5. Analytics events tracked in real-time
+6. Content replicated across multiple regions
+
+## Environment Variables
+
+See `.env.example` for all available configuration options.
+
+## Development
+
+### Running Tests
+```bash
+npm test
+```
+
+### Project Structure
+```
+├── routes/          # API route handlers
+├── middleware/      # Express middleware
+├── services/        # Business logic services
+├── docs/           # API documentation
+├── tests/          # Test files
+└── index.js        # Main application entry
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.

docs/API_AUTHENTICATION.md

@@ -0,0 +1,122 @@
+# API Authentication Documentation
+
+## Overview
+
+The SubStream Protocol backend uses wallet-based authentication following the SIWE (Sign In With Ethereum) pattern. Users authenticate by signing a message with their wallet, which is then verified on the backend to issue a JWT token.
+
+## Authentication Flow
+
+### 1. POST /auth/login
+
+Authenticate with the backend using a wallet signature.
+
+#### Request Body
+```json
+{
+  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4Db45",
+  "signature": "0x4355c47d63924e8a72e509b65029052eb6c50d03db4e6b1b3b9f1c2d3a4e5f6b",
+  "message": "Sign in to SubStream Protocol at 2024-03-23T16:14:00.000Z",
+  "nonce": "random_nonce_string"
+}
+```
+
+#### Response
+```json
+{
+  "success": true,
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4Db45",
+    "tier": "bronze"
+  },
+  "expiresIn": 86400
+}
+```
+
+#### Error Response
+```json
+{
+  "success": false,
+  "error": "Invalid signature"
+}
+```
+
+### 2. JWT Token Usage
+
+Once authenticated, include the JWT token in the Authorization header for all protected endpoints:
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+#### Token Structure
+The JWT token contains the following claims:
+- `address`: User's wallet address
+- `tier`: User's subscription tier (bronze, silver, gold)
+- `iat`: Issued at timestamp
+- `exp`: Expiration timestamp (24 hours)
+
+#### Protected Endpoints
+All endpoints except `/` and `/auth/login` require a valid JWT token.
+
+## Implementation Details
+
+### SIWE Message Format
+The message to sign should follow this format:
+```
+Sign in to SubStream Protocol at {timestamp}
+
+Nonce: {nonce}
+Address: {wallet_address}
+```
+
+### Signature Verification
+The backend verifies:
+1. The signature matches the address
+2. The nonce is valid and hasn't been used
+3. The timestamp is within acceptable range (5 minutes)
+
+### Security Considerations
+- Nonces are single-use and expire after 5 minutes
+- JWT tokens expire after 24 hours
+- Rate limiting is applied to login attempts
+- All sensitive operations require valid JWT authentication
+
+## Example Usage
+
+### JavaScript/Node.js
+```javascript
+const response = await fetch('/auth/login', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4Db45',
+    signature: '0x4355c47d63924e8a72e509b65029052eb6c50d03db4e6b1b3b9f1c2d3a4e5f6b',
+    message: 'Sign in to SubStream Protocol at 2024-03-23T16:14:00.000Z',
+    nonce: 'random_nonce_string'
+  })
+});
+
+const { token } = await response.json();
+
+// Use token for authenticated requests
+const protectedResponse = await fetch('/content', {
+  headers: {
+    'Authorization': `Bearer ${token}`
+  }
+});
+```
+
+## Troubleshooting
+
+### Common Errors
+
+1. **Invalid signature**: Check that the signature was created with the correct message and address
+2. **Expired nonce**: Request a new nonce and try again
+3. **Token expired**: Re-authenticate to get a new token
+4. **Invalid token format**: Ensure the token is included in the Authorization header with "Bearer " prefix
+
+### Support
+For authentication issues, check the browser console for detailed error messages or contact support with your wallet address.