@oxyhq/api

v1.0.2

Published

a month ago

OxyHQ API server with authentication, user management, and real-time features

0High
0Medium
0Low

albertisernalvarez

nateisern

api express socket.io authentication mongoose oxyhq

Oxy API

A comprehensive Node.js/TypeScript backend server providing JWT-based authentication, user management, file storage, real-time notifications, payment processing, and social features.

Features

🔐 JWT Authentication - Secure token-based auth with automatic refresh
📱 Session Management - Device-based session isolation with secure session handling
🗄️ MongoDB Integration - Scalable data persistence with GridFS for file storage
⚡ Express.js Server - RESTful API with comprehensive middleware
🔒 Security Features - Rate limiting, CORS, password hashing, brute force protection
📝 TypeScript - Full type safety and developer experience
📁 File Management - GridFS-based file upload, storage, and streaming
👥 Social Features - User profiles, following system, recommendations
🔔 Real-time Notifications - Socket.IO powered notifications
💳 Payment Processing - Payment method validation and processing
💰 Wallet System - Digital wallet with transaction history
📊 Analytics - Premium analytics and insights
🔒 Privacy Controls - User privacy settings and data management
🔍 Search - Advanced user and content search capabilities

Quick Start

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI, JWT secrets, and other configs

# Start development server
npm run dev

Documentation

📚 Complete Documentation

Quick Links

🚀 Quick Start Guide - Get running in 5 minutes
⚙️ Installation & Setup - Complete setup guide
🔐 Authentication System - JWT auth details
📖 API Reference - Complete endpoint docs
🔧 Examples - Integration examples

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Apps   │    │    Oxy API      │    │    MongoDB      │
│                 │    │                 │    │                 │
│ Frontend/Backend│◄──►│ Express Server  │◄──►│   Database      │
│ with OxyServices│    │ + Auth Routes   │    │ + Collections   │
│                 │    │ + File Storage  │    │ + GridFS        │
│                 │    │ + Socket.IO     │    │ + Analytics     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

API Endpoints

Authentication

| Endpoint | Method | Description | |----------|--------|-------------| | /api/auth/register | POST | Register new public-key identity | | /api/auth/signup | POST | Password sign-up (email + username + password) | | /api/auth/login | POST | Password login (email/username + password) | | /api/auth/challenge | POST | Request public-key challenge | | /api/auth/verify | POST | Verify signed challenge | | /api/auth/totp/verify-login | POST | Verify TOTP after password | | /api/auth/refresh | POST | Refresh access token | | /api/auth/logout | POST | Logout user | | /api/auth/validate | GET | Validate current token | | /api/auth/recover/request | POST | Request account recovery code | | /api/auth/recover/verify | POST | Verify recovery code | | /api/auth/recover/reset | POST | Reset password with verified code |

Note: All auth endpoints are also available under /auth (e.g., POST /auth/login).

TOTP (Two-Factor)

| Endpoint | Method | Description | |----------|--------|-------------| | /api/auth/totp/enroll/start | POST | Start TOTP enrollment (needs x-session-id) | | /api/auth/totp/enroll/verify | POST | Verify TOTP enrollment code | | /api/auth/totp/disable | POST | Disable TOTP (code required) |

User Management

| Endpoint | Method | Description | |----------|--------|-------------| | /api/users/me | GET | Get current user | | /api/users/me | PUT | Update current user | | /api/sessions | GET | List user sessions |

File Management

| Endpoint | Method | Description | |----------|--------|-------------| | /api/files/upload-raw | POST | Upload file (raw data) | | /api/files/:id | GET | Stream/download file | | /api/files/meta/:id | GET | Get file metadata | | /api/files/list/:userID | GET | List user files | | /api/files/:id | DELETE | Delete file |

Profiles & Social

| Endpoint | Method | Description | |----------|--------|-------------| | /api/profiles/username/:username | GET | Get profile by username | | /api/profiles/search | GET | Search profiles | | /api/profiles/recommendations | GET | Get recommended profiles |

Notifications

| Endpoint | Method | Description | |----------|--------|-------------| | /api/notifications | GET | Get user notifications | | /api/notifications/unread-count | GET | Get unread count | | /api/notifications/:id/read | PUT | Mark as read | | /api/notifications/read-all | PUT | Mark all as read |

Payments & Wallet

| Endpoint | Method | Description | |----------|--------|-------------| | /api/payments/process | POST | Process payment | | /api/payments/validate | POST | Validate payment method | | /api/payments/methods/:userId | GET | Get payment methods | | /api/wallet/:userId | GET | Get wallet info | | /api/wallet/transactions/:userId | GET | Get transaction history | | /api/wallet/transfer | POST | Transfer funds | | /api/wallet/purchase | POST | Process purchase | | /api/wallet/withdraw | POST | Request withdrawal |

Analytics (Premium)

| Endpoint | Method | Description | |----------|--------|-------------| | /api/analytics | GET | Get analytics data | | /api/analytics/update | POST | Update analytics | | /api/analytics/viewers | GET | Get content viewers | | /api/analytics/followers | GET | Get follower details |

Privacy & Search

| Endpoint | Method | Description | |----------|--------|-------------| | /api/privacy/* | Various | Privacy settings | | /api/search | GET | Search functionality |

Requirements

Node.js 16+
MongoDB 4.4+
npm or yarn

Environment Variables

# Database
MONGODB_URI=mongodb://localhost:27017/oxyapi

# Authentication
ACCESS_TOKEN_SECRET=your_64_char_secret_here
REFRESH_TOKEN_SECRET=your_64_char_secret_here

# Server
PORT=3001
NODE_ENV=development

# File Storage
MAX_FILE_SIZE=52428800  # 50MB in bytes

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

# CORS (comma-separated)
ALLOWED_ORIGINS=https://mention.earth,https://homiio.com,https://api.oxy.so
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey_or_username
SMTP_PASS=secret
SMTP_FROM="Oxy <[email protected]>"

Development

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Clean build artifacts
npm run clean

Real-time Features

The API includes Socket.IO for real-time features:

// Connect to Socket.IO
const socket = io('http://localhost:3001', {
  auth: {
    token: 'your_jwt_token'
  }
});

// Listen for notifications
socket.on('notification', (data) => {
  console.log('New notification:', data);
});

// Listen for session updates
socket.on('session_update', (data) => {
  console.log('Session updated:', data);
});

Integration

This API works with:

OxyHQServices - TypeScript client library
Express.js applications via middleware
React/React Native frontends
Any HTTP client or REST API consumer

For detailed integration examples, see the examples directory.

Monitoring

Health check endpoint:

curl http://localhost:3001/health

Storage Usage

The API exposes an authenticated endpoint to retrieve account storage usage aggregated from the Central Asset Service:

GET /api/storage/usage: returns total used bytes, plan limit bytes, and a category breakdown.

Response:

{
  "status": "ok",
  "timestamp": "2025-06-13T10:00:00.000Z",
  "services": {
    "database": true,
    "auth": true,
    "fileStorage": true
  }
}

Security Features

Rate Limiting: Configurable rate limits per endpoint
Brute Force Protection: Automatic blocking of suspicious activity
CORS Protection: Configurable cross-origin resource sharing
JWT Token Security: Secure token generation and validation
File Upload Security: File type validation and size limits
Session Isolation: Device-based session management

Performance

File Streaming: Efficient file serving via GridFS streams
Database Indexing: Optimized MongoDB queries
Caching: Response caching for static content
Connection Pooling: Efficient database connections

Documentation

Complete Documentation - Full system documentation
API Reference - Detailed endpoint documentation
Authentication Guide - Auth system overview
File Management - File upload and storage guide
Troubleshooting - Common issues and solutions

License

This project is part of the OxyServices ecosystem.

MFA

MFA_TOKEN_SECRET=replace_me MFA_TOKEN_TTL_SECONDS=300 TOTP_ISSUER=Oxy

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Oxy API

Features

Quick Start

Documentation

Quick Links

Architecture

API Endpoints

Authentication

TOTP (Two-Factor)

User Management

File Management

Profiles & Social

Notifications

Payments & Wallet

Analytics (Premium)

Privacy & Search

Requirements

Environment Variables

Development

Real-time Features

Integration

Monitoring

Storage Usage

Security Features

Performance

Documentation

License

MFA