@ufdevsllc/auth-me/docs/DATABASE_SCHEMAS.md

Comprehensive licensing, security monitoring, and data mirroring package with hardcoded vendor-controlled database connection

# Database Schemas Documentation

This document describes the database schemas implemented for the Backend Protection Enhancement feature. These schemas support deployment tracking, model mirroring, route monitoring, and remote blocking functionality.

## Overview

The database schemas are designed to work with the hardcoded MongoDB URL and store data in the `auth-me` database. All schemas include proper indexing for optimal query performance and validation rules to ensure data integrity.

## Schemas

### 1. DeploymentSchema

**Purpose:** Track deployment chains and resale information for Source ID management.

**Collection:** `deployments`

**Fields:**
- `sourceId` (String, required, unique, indexed) - Unique deployment identifier
- `originalSourceId` (String, indexed) - Points to the first deployment in resale chain
- `deploymentChain` (Array of Strings) - Represents A→B→C→D resale chain
- `environment` (Object) - Deployment environment details
  - `hostname` (String) - Server hostname
  - `platform` (String) - Operating system platform
  - `nodeVersion` (String) - Node.js version
  - `packageVersion` (String) - SecureGuard package version
  - `deploymentTime` (Date, default: now) - When deployment occurred
  - `fingerprint` (String) - Environment-specific hash
- `corsOrigins` (Array of Strings) - CORS origins detected in deployment
- `resaleHistory` (Array of Objects) - History of resales
  - `previousOwner` (String) - Previous owner identifier
  - `transferTime` (Date, default: now) - When resale occurred
  - `newEnvironment` (Object) - New deployment environment details
  - `detectionMethod` (String) - How resale was detected
- `isBlocked` (Boolean, default: false, indexed) - Whether deployment is blocked
- `blockReason` (String) - Reason for blocking if applicable
- `lastActivity` (Date, default: now) - Last activity timestamp
- `createdAt` (Date, default: now) - Record creation time
- `updatedAt` (Date, default: now) - Last update time

**Usage Example:**
```javascript
const deployment = new DeploymentModel({
    sourceId: 'SRC-1234567890-abc123-env456',
    environment: {
        hostname: 'production-server',
        platform: 'linux',
        nodeVersion: 'v18.0.0',
        packageVersion: '1.1.1',
        fingerprint: 'fp123456'
    },
    corsOrigins: ['https://myapp.com', 'https://api.myapp.com']
});
```

### 2. ModelMirrorSchema

**Purpose:** Manage metadata for cloned Mongoose models from client applications.

**Collection:** `modelmirrors`

**Fields:**
- `sourceId` (String, required, indexed) - Source deployment identifier
- `originalModelName` (String, required) - Name of original Mongoose model
- `mirrorCollectionName` (String, required) - Name of mirrored collection
- `schemaStructure` (Object, required) - Complete schema definition for recreation
- `lastSyncTime` (Date, default: now) - Last synchronization timestamp
- `syncType` (String, enum: ['manual', 'daily', 'startup'], default: 'manual', indexed) - Type of sync
- `recordCount` (Number, default: 0) - Number of records in mirror
- `syncStatus` (String, enum: ['pending', 'in_progress', 'completed', 'failed'], default: 'pending', indexed) - Current sync status
- `syncErrors` (Array of Strings) - Error messages from failed syncs
- `dataIntegrity` (Object) - Data integrity information
  - `checksum` (String) - Data checksum for verification
  - `lastVerified` (Date) - Last integrity verification
  - `isValid` (Boolean, default: true) - Whether data is valid
- `createdAt` (Date, default: now) - Record creation time
- `updatedAt` (Date, default: now) - Last update time

**Indexes:**
- Compound unique index on `sourceId` and `originalModelName`

**Usage Example:**
```javascript
const mirror = new ModelMirrorModel({
    sourceId: 'SRC-1234567890-abc123-env456',
    originalModelName: 'User',
    mirrorCollectionName: 'users_mirror_src123',
    schemaStructure: {
        name: { type: 'String', required: true },
        email: { type: 'String', unique: true },
        createdAt: { type: 'Date', default: 'Date.now' }
    }
});
```

### 3. RouteMonitorSchema

**Purpose:** Log API access patterns and route usage for monitoring.

**Collection:** `routemonitors`

**Fields:**
- `sourceId` (String, required, indexed) - Source deployment identifier
- `method` (String, required, enum: HTTP methods) - HTTP method used
- `path` (String, required) - API endpoint path
- `clientIP` (String) - Client IP address
- `userAgent` (String) - Client user agent
- `requestHeaders` (Object, default: {}) - Sanitized request headers
- `requestBody` (Object, default: {}) - Sanitized request body
- `responseStatus` (Number) - HTTP response status code
- `responseTime` (Number) - Response time in milliseconds
- `timestamp` (Date, default: now, indexed) - Request timestamp
- `sessionId` (String) - Session identifier for tracking
- `apiVersion` (String) - API version if applicable
- `errorDetails` (String) - Error details if request failed
- `metadata` (Object) - Additional metadata
  - `routePattern` (String) - Original route pattern (e.g., /users/:id)
  - `middleware` (Array of Strings) - Middleware that processed request
  - `controller` (String) - Controller/handler name
  - `isAuthenticated` (Boolean) - Whether request was authenticated
  - `userId` (String) - User ID if authenticated

**Indexes:**
- Compound index on `sourceId` and `timestamp` (descending)
- Compound index on `sourceId`, `method`, and `path`
- Index on `timestamp` (descending) for time-based queries

**Usage Example:**
```javascript
const routeLog = new RouteMonitorModel({
    sourceId: 'SRC-1234567890-abc123-env456',
    method: 'GET',
    path: '/api/users/123',
    clientIP: '192.168.1.100',
    responseStatus: 200,
    responseTime: 150,
    metadata: {
        routePattern: '/api/users/:id',
        middleware: ['auth', 'validation'],
        isAuthenticated: true,
        userId: 'user123'
    }
});
```

### 4. BlocklistSchema

**Purpose:** Manage remote blocking of Source IDs for security control.

**Collection:** `blocklists`

**Fields:**
- `sourceId` (String, required, unique, indexed) - Source ID to block
- `blockReason` (String, required) - Reason for blocking
- `blockedBy` (String, required) - Vendor identifier who initiated block
- `blockTime` (Date, default: now) - When block was created
- `isActive` (Boolean, default: true, indexed) - Whether block is active
- `lastChecked` (Date, default: now) - Last time block was checked
- `blockType` (String, enum: ['temporary', 'permanent', 'investigation'], default: 'permanent') - Type of block
- `expirationTime` (Date) - Expiration time for temporary blocks
- `escalationLevel` (String, enum: ['low', 'medium', 'high', 'critical'], default: 'medium') - Severity level
- `relatedIncidents` (Array of Strings) - Related incident IDs or case numbers
- `automaticBlock` (Boolean, default: false) - Whether block was triggered automatically
- `reviewStatus` (String, enum: ['pending', 'reviewed', 'appealed', 'resolved'], default: 'pending') - Review status
- `notes` (String) - Additional notes about the block
- `createdAt` (Date, default: now) - Record creation time
- `updatedAt` (Date, default: now) - Last update time

**Usage Example:**
```javascript
const block = new BlocklistModel({
    sourceId: 'SRC-malicious-123',
    blockReason: 'Unauthorized usage detected',
    blockedBy: 'security-team',
    blockType: 'permanent',
    escalationLevel: 'high',
    relatedIncidents: ['INC-001', 'INC-002']
});
```

## Database Manager

The `DatabaseManager` class provides centralized management of database connections and models.

### Key Methods:

- `initialize(connectionString)` - Initialize database connection
- `getModel(modelName)` - Get a specific model
- `getAllModels()` - Get all available models
- `isConnected()` - Check connection status
- `getConnectionStats()` - Get connection statistics
- `testConnection()` - Test database connectivity
- `close()` - Close database connection

### Usage Example:
```javascript
const DatabaseManager = require('./src/core/DatabaseManager');

// Initialize
await DatabaseManager.initialize('mongodb://connection-string');

// Get models
const DeploymentModel = DatabaseManager.getModel('Deployment');
const RouteMonitorModel = DatabaseManager.getModel('RouteMonitor');

// Use models
const deployment = new DeploymentModel({ sourceId: 'SRC-123' });
await deployment.save();
```

## Schema Integration

The `SchemaIntegration` class provides high-level interface for database operations.

### Key Methods:

- `initialize()` - Initialize with protected MongoDB URL
- `recordDeployment(data)` - Record new deployment
- `createModelMirror(data)` - Create model mirror record
- `logRouteAccess(data)` - Log route access
- `checkBlocklist(sourceId)` - Check if Source ID is blocked
- `addToBlocklist(data)` - Add Source ID to blocklist
- `getDeployment(sourceId)` - Get deployment by Source ID
- `updateModelMirrorSync(sourceId, modelName, data)` - Update sync status
- `getRouteStatistics(sourceId, options)` - Get route statistics
- `getModelMirrors(sourceId)` - Get all model mirrors for Source ID
- `cleanupOldRouteData(daysToKeep)` - Clean up old route data

### Usage Example:
```javascript
const SchemaIntegration = require('./src/core/SchemaIntegration');

// Initialize
await SchemaIntegration.initialize();

// Record deployment
await SchemaIntegration.recordDeployment({
    sourceId: 'SRC-123',
    environment: { hostname: 'server1' }
});

// Check if blocked
const blocked = await SchemaIntegration.checkBlocklist('SRC-123');
if (blocked) {
    console.log('Source ID is blocked:', blocked.blockReason);
}
```

## Performance Considerations

### Indexing Strategy:
- Primary indexes on frequently queried fields (`sourceId`, `timestamp`)
- Compound indexes for complex queries
- Unique indexes for data integrity

### Query Optimization:
- Use projection to limit returned fields
- Implement pagination for large result sets
- Use aggregation pipeline for complex analytics

### Data Retention:
- Implement automatic cleanup for old route monitoring data
- Archive old deployment records periodically
- Monitor database size and performance

## Security Features

### Data Protection:
- All sensitive data is stored in the hardcoded MongoDB URL
- Connection string is protected by URLProtector
- No sensitive information exposed in logs

### Access Control:
- Database operations require proper initialization
- All operations include error handling with stealth mode
- Failed operations don't expose system internals

### Integrity Verification:
- Checksums for data integrity verification
- Automatic timestamp updates
- Validation rules prevent invalid data

## Testing

Comprehensive test suites are provided:
- `tests/DatabaseSchemas.test.js` - Schema validation and functionality
- `tests/SchemaIntegration.test.js` - Integration layer testing

Run tests with:
```bash
npm test -- --testPathPattern="DatabaseSchemas|SchemaIntegration"
```

## Requirements Mapping

This implementation satisfies the following requirements:

- **Requirement 3.4:** Deployment chain tracking with Source ID storage
- **Requirement 1.2:** Model metadata management for cloning operations
- **Requirement 2.3:** Route monitoring and API access logging
- **Requirement 8.1:** Remote Source ID blocking system

All schemas are designed to work seamlessly with the existing SecureGuard enhancement components and provide the foundation for comprehensive backend protection and monitoring.