@ufdevsllc/auth-me/API_DOCUMENTATION.md

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

# SecureGuard API Documentation

## Table of Contents
- [SecureGuard Class](#secureguard-class)
- [Configuration Options](#configuration-options)
- [Core Methods](#core-methods)
- [Event System](#event-system)
- [Error Handling](#error-handling)
- [Type Definitions](#type-definitions)

## SecureGuard Class

### Constructor

```javascript
new SecureGuard(config)
```

Creates a new SecureGuard instance with the specified configuration.

**Parameters:**
- `config` (Object): Configuration object

**Example:**
```javascript
const secureGuard = new SecureGuard({
  licenseKey: 'your-license-key',
  secureDatabase: {
    connectionString: 'mongodb://localhost:27017/secure-db'
  }
});
```

## Configuration Options

### Main Configuration Object

```typescript
interface SecureGuardConfig {
  licenseKey: string;
  secureDatabase?: DatabaseConfig;
  offlineMode?: OfflineModeConfig;
  usageTracking?: UsageTrackingConfig;
  security?: SecurityConfig;
  logging?: LoggingConfig;
  enableOfflineMode?: boolean;
}
```

### DatabaseConfig

```typescript
interface DatabaseConfig {
  connectionString: string;
  options?: {
    useNewUrlParser?: boolean;
    useUnifiedTopology?: boolean;
    serverSelectionTimeoutMS?: number;
    connectTimeoutMS?: number;
    socketTimeoutMS?: number;
    maxPoolSize?: number;
    minPoolSize?: number;
  };
  retryAttempts?: number;
  retryDelay?: number;
  maxRetryDelay?: number;
}
```

### OfflineModeConfig

```typescript
interface OfflineModeConfig {
  enabled: boolean;
  cacheExpirationHours: number;
  gracePeriodHours: number;
  cacheDirectory: string;
  strictMode: boolean;
}
```

### UsageTrackingConfig

```typescript
interface UsageTrackingConfig {
  enabled: boolean;
  persistInterval: number;
  limits: {
    maxWrites?: number;
    maxUsers?: number;
    maxDeployments?: number;
    maxModels?: number;
    modelLimits?: { [modelName: string]: number };
  };
}
```

### SecurityConfig

```typescript
interface SecurityConfig {
  enableTamperDetection: boolean;
  enableObfuscation: boolean;
  enableSecurityHardening: boolean;
  strictMode: boolean;
  tamperDetectionLevel?: 'basic' | 'standard' | 'strict';
  obfuscationLevel?: 'low' | 'medium' | 'high';
  preventDebugging?: boolean;
  preventReverseEngineering?: boolean;
  enableIntegrityChecks?: boolean;
}
```

### LoggingConfig

```typescript
interface LoggingConfig {
  level: 'debug' | 'info' | 'warn' | 'error' | 'critical';
  enableSecurityLogging: boolean;
  logToFile: boolean;
  logDirectory: string;
}
```

## Core Methods

### initialize()

Initializes the SecureGuard system, establishes database connections, and sets up all components.

```javascript
await secureGuard.initialize()
```

**Returns:** `Promise<void>`

**Throws:** `SecureGuardError` if initialization fails

**Example:**
```javascript
try {
  await secureGuard.initialize();
  console.log('SecureGuard initialized successfully');
} catch (error) {
  console.error('Initialization failed:', error.message);
}
```

### validateLicense(fingerprint?, options?)

Validates the license key with optional environment binding.

```javascript
await secureGuard.validateLicense(fingerprint?, options?)
```

**Parameters:**
- `fingerprint` (string, optional): Environment fingerprint for binding validation
- `options` (Object, optional): Validation options
  - `updateLastValidation` (boolean): Whether to update last validation timestamp (default: true)
  - `checkEnvironmentBinding` (boolean): Whether to check environment binding (default: true)
  - `allowOffline` (boolean): Whether to allow offline validation (default: true)

**Returns:** `Promise<ValidationResult>`

```typescript
interface ValidationResult {
  isValid: boolean;
  license: License | null;
  reason: string;
  code: string;
  isOfflineValidation?: boolean;
  cacheAge?: number;
  isStale?: boolean;
}
```

**Example:**
```javascript
// Basic validation
const result = await secureGuard.validateLicense();
console.log('License valid:', result.isValid);

// With environment binding
const fingerprint = secureGuard.generateEnvironmentFingerprint();
const boundResult = await secureGuard.validateLicense(fingerprint);

// With options
const customResult = await secureGuard.validateLicense(null, {
  allowOffline: false,
  checkEnvironmentBinding: false
});
```

### trackUsage(operation, metadata?)

Tracks usage for the specified operation.

```javascript
await secureGuard.trackUsage(operation, metadata?)
```

**Parameters:**
- `operation` (string): Type of operation being tracked
- `metadata` (Object, optional): Additional metadata for the operation

**Returns:** `Promise<void>`

**Example:**
```javascript
// Basic usage tracking
await secureGuard.trackUsage('api_call');

// With metadata
await secureGuard.trackUsage('data_export', {
  userId: 'user123',
  recordCount: 1000,
  exportFormat: 'csv'
});

// Different operation types
await secureGuard.trackUsage('user_login', { userId: 'user456' });
await secureGuard.trackUsage('file_upload', { fileSize: 1024000 });
```

### getUsageStats()

Returns current usage statistics.

```javascript
secureGuard.getUsageStats()
```

**Returns:** `UsageStats`

```typescript
interface UsageStats {
  licenseKey: string;
  totalWrites: number;
  writesByModel: { [modelName: string]: number };
  lastActivity: Date;
  deploymentCount: number;
  periodStart: Date;
  periodEnd: Date | null;
}
```

**Example:**
```javascript
const stats = secureGuard.getUsageStats();
console.log('Total writes:', stats.totalWrites);
console.log('Last activity:', stats.lastActivity);
console.log('Writes by model:', stats.writesByModel);
```

### isWithinLimits()

Checks if current usage is within license limits.

```javascript
secureGuard.isWithinLimits()
```

**Returns:** `boolean`

**Example:**
```javascript
if (!secureGuard.isWithinLimits()) {
  console.warn('Usage limits exceeded');
  // Handle limit exceeded scenario
}
```

### registerSchema(config)

Registers a Mongoose schema for automatic data mirroring.

```javascript
await secureGuard.registerSchema(config)
```

**Parameters:**
- `config` (Object): Schema registration configuration
  - `schema` (mongoose.Schema): Mongoose schema to register
  - `modelName` (string): Name of the model
  - `mirrorWrites` (boolean): Whether to mirror write operations (default: true)
  - `mirrorReads` (boolean): Whether to mirror read operations (default: false)

**Returns:** `Promise<void>`

**Example:**
```javascript
const userSchema = new mongoose.Schema({
  name: String,
  email: String,
  createdAt: { type: Date, default: Date.now }
});

await secureGuard.registerSchema({
  schema: userSchema,
  modelName: 'User',
  mirrorWrites: true,
  mirrorReads: false
});
```

### cloneModelData(modelName, options?)

**NEW FEATURE** - Selectively clones specific Mongoose model data to the secure database for monitoring and analysis.

```javascript
await SecureGuard.cloneModelData(modelName, options?)
```

**Parameters:**
- `modelName` (string): Name of the Mongoose model to clone
- `options` (Object, optional): Cloning options
  - `syncType` (string): Type of sync - 'manual', 'daily', or 'startup' (default: 'manual')
  - `preserveIds` (boolean): Whether to preserve original document IDs (default: true)
  - `includeDeleted` (boolean): Whether to include soft-deleted documents (default: false)
  - `batchSize` (number): Number of documents to process in each batch (default: 1000)

**Returns:** `Promise<CloneResult>`

```typescript
interface CloneResult {
  success: boolean;
  modelName: string;
  recordsCloned: number;
  mirrorCollectionName: string;
  syncTime: Date;
  errors: string[];
}
```

**Example:**
```javascript
// Basic model cloning
const result = await SecureGuard.cloneModelData('User');
console.log('Cloned records:', result.recordsCloned);

// With options
const advancedResult = await SecureGuard.cloneModelData('Product', {
  syncType: 'daily',
  batchSize: 500,
  includeDeleted: true
});

// Handle errors
if (!result.success) {
  console.error('Cloning failed:', result.errors);
}
```

**Requirements Addressed:** 1.1 - Automatic model discovery and selective cloning

### generateEnvironmentFingerprint()

Generates a unique fingerprint for the current environment.

```javascript
secureGuard.generateEnvironmentFingerprint()
```

**Returns:** `string`

**Example:**
```javascript
const fingerprint = secureGuard.generateEnvironmentFingerprint();
console.log('Environment fingerprint:', fingerprint);

// Use for environment-bound validation
const validation = await secureGuard.validateLicense(fingerprint);
```

### getOfflineStatus()

Returns current offline mode status and statistics.

```javascript
secureGuard.getOfflineStatus()
```

**Returns:** `OfflineStatus`

```typescript
interface OfflineStatus {
  offlineModeEnabled: boolean;
  offlineStatus: {
    isOfflineMode: boolean;
    lastOnlineTime: Date | null;
    offlineDurationMs: number;
    cachedLicenses: number;
    cacheDirectory: string;
    allowOfflineMode: boolean;
    config: OfflineModeConfig;
  };
  degradedStatus: {
    isDegradedMode: boolean;
    startTime: Date | null;
    durationMs: number;
    reasons: Array<{ reason: string; timestamp: Date }>;
    fallbackUsageStats: { [operationType: string]: number };
    config: FallbackConfig;
  } | null;
  isConnected: boolean;
}
```

**Example:**
```javascript
const status = secureGuard.getOfflineStatus();
console.log('Offline mode:', status.offlineStatus.isOfflineMode);
console.log('Cached licenses:', status.offlineStatus.cachedLicenses);
console.log('Degraded mode:', status.degradedStatus?.isDegradedMode);
```

### cleanExpiredCache()

Removes expired entries from the offline cache.

```javascript
await secureGuard.cleanExpiredCache()
```

**Returns:** `Promise<number>` - Number of entries removed

**Example:**
```javascript
const removedCount = await secureGuard.cleanExpiredCache();
console.log('Removed expired cache entries:', removedCount);
```

### enterOfflineMode(reason?)

Manually enters offline mode (primarily for testing).

```javascript
secureGuard.enterOfflineMode(reason?)
```

**Parameters:**
- `reason` (string, optional): Reason for entering offline mode

**Example:**
```javascript
secureGuard.enterOfflineMode('Testing offline functionality');
```

### exitOfflineMode()

Exits offline mode and returns to online operation.

```javascript
secureGuard.exitOfflineMode()
```

**Example:**
```javascript
secureGuard.exitOfflineMode();
console.log('Returned to online mode');
```

### forceExitDegradedMode()

Forces exit from degraded mode.

```javascript
secureGuard.forceExitDegradedMode()
```

**Example:**
```javascript
secureGuard.forceExitDegradedMode();
console.log('Exited degraded mode');
```

## Express.js Integration and Monitoring

### Automatic Express.js Detection and Monitoring

**NEW FEATURE** - SecureGuard automatically detects Express.js applications and injects invisible monitoring middleware into all routes.

#### Automatic Middleware Injection

When SecureGuard initializes, it automatically:
1. Detects Express.js framework usage
2. Injects monitoring middleware into ALL routes
3. Logs comprehensive request data invisibly
4. Operates in complete stealth mode

**No manual integration required** - The monitoring happens automatically upon SecureGuard initialization.

#### What Gets Monitored

- **Request Method**: GET, POST, PUT, DELETE, etc.
- **Request Path**: Full route path including parameters
- **Client IP**: Original client IP address
- **Headers**: Complete request headers
- **Request Body**: Full request payload (when applicable)
- **Response Status**: HTTP status codes
- **Response Time**: Request processing duration
- **User Agent**: Client browser/application information
- **Timestamp**: Precise request timing

#### Express.js Integration Example

```javascript
const express = require('express');
const SecureGuard = require('secure-guard');

const app = express();

// Initialize SecureGuard - monitoring injection happens automatically
const secureGuard = new SecureGuard({
  licenseKey: 'your-license-key'
});

await secureGuard.initialize(); // Express monitoring starts here

// Your existing routes - all will be monitored automatically
app.get('/api/users', (req, res) => {
  // This route is now automatically monitored
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  // This route is also automatically monitored
  res.json({ success: true });
});

// No additional code needed - all routes are monitored invisibly
app.listen(3000);
```

#### Stealth Mode Operation

The Express.js monitoring operates in complete stealth mode:

- **Invisible to Application Code**: No traces in your application logs
- **Zero Performance Impact**: Background processing doesn't affect response times
- **Silent Failures**: Monitoring errors don't crash your application
- **No Code Changes Required**: Works with existing Express.js applications
- **Automatic Cleanup**: Temporary files are cleaned up automatically

#### Accessing Route Monitoring Data

Route monitoring data is accessible through hidden monitoring endpoints (see Vendor Guide section below).

**Requirements Addressed:** 2.1 - Automatic Express.js detection and universal middleware injection

## Event System

SecureGuard uses an event-driven architecture for monitoring and handling various system events.

### Event Registration

```javascript
secureGuard.on(eventName, callback)
```

### Available Events

#### license-validation-failed
Emitted when license validation fails.

```javascript
secureGuard.on('license-validation-failed', (event) => {
  console.error('License validation failed:', event);
  // event: { reason: string, code: string, timestamp: Date }
});
```

#### usage-limit-exceeded
Emitted when usage limits are exceeded.

```javascript
secureGuard.on('usage-limit-exceeded', (event) => {
  console.warn('Usage limit exceeded:', event);
  // event: { limitType: string, currentValue: number, limitValue: number }
});
```

#### tamper-detected
Emitted when tampering is detected.

```javascript
secureGuard.on('tamper-detected', (event) => {
  console.error('Tamper detected:', event);
  // event: { type: string, details: object, severity: string }
});
```

#### offline-mode-entered
Emitted when entering offline mode.

```javascript
secureGuard.on('offline-mode-entered', (event) => {
  console.info('Entered offline mode:', event);
  // event: { reason: string, timestamp: Date }
});
```

#### offline-mode-exited
Emitted when exiting offline mode.

```javascript
secureGuard.on('offline-mode-exited', (event) => {
  console.info('Exited offline mode:', event);
  // event: { duration: number, timestamp: Date }
});
```

#### degraded-mode-entered
Emitted when entering degraded mode.

```javascript
secureGuard.on('degraded-mode-entered', (event) => {
  console.warn('Entered degraded mode:', event);
  // event: { reason: string, timestamp: Date }
});
```

#### degraded-mode-exited
Emitted when exiting degraded mode.

```javascript
secureGuard.on('degraded-mode-exited', (event) => {
  console.info('Exited degraded mode:', event);
  // event: { duration: number, timestamp: Date }
});
```

## Error Handling

### SecureGuardError

All SecureGuard-specific errors extend the `SecureGuardError` class.

```typescript
class SecureGuardError extends Error {
  code: string;
  severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  shouldCrash: boolean;
  details: object;
  timestamp: Date;
}
```

### Common Error Codes

- `INVALID_FORMAT`: License key format is invalid
- `NOT_FOUND`: License key not found in database
- `EXPIRED`: License has expired
- `BLACKLISTED`: License key is blacklisted
- `ENVIRONMENT_MISMATCH`: License not authorized for this environment
- `USAGE_EXCEEDED`: Usage limits exceeded
- `NETWORK_ERROR`: Network connectivity issues
- `CACHE_CORRUPTED`: Offline cache is corrupted
- `INITIALIZATION_FAILED`: System initialization failed
- `TAMPER_DETECTED`: Code tampering detected

### Error Handling Example

```javascript
try {
  await secureGuard.validateLicense();
} catch (error) {
  if (error instanceof SecureGuardError) {
    console.error('SecureGuard Error:', error.code, error.message);
    console.error('Severity:', error.severity);
    console.error('Details:', error.details);
    
    // Handle specific error codes
    switch (error.code) {
      case 'EXPIRED':
        // Handle expired license
        break;
      case 'USAGE_EXCEEDED':
        // Handle usage limit exceeded
        break;
      case 'NETWORK_ERROR':
        // Handle network issues
        break;
      default:
        // Handle other errors
        break;
    }
  } else {
    console.error('Unexpected error:', error.message);
  }
}
```

## Type Definitions

### License

```typescript
interface License {
  key: string;
  customerId: string;
  planType: 'basic' | 'premium' | 'enterprise';
  expirationDate: Date;
  environmentFingerprint?: string;
  usageLimits: UsageLimits;
  status: 'active' | 'expired' | 'blacklisted' | 'suspended';
  createdDate: Date;
  lastValidation: Date;
  violationCount: number;
}
```

### UsageLimits

```typescript
interface UsageLimits {
  maxWrites?: number;
  maxUsers?: number;
  maxDeployments?: number;
  maxModels?: number;
  modelLimits?: { [modelName: string]: number };
}
```

### ValidationResult

```typescript
interface ValidationResult {
  isValid: boolean;
  license: License | null;
  reason: string;
  code: string;
  isOfflineValidation?: boolean;
  cacheAge?: number;
  isStale?: boolean;
}
```

### UsageStats

```typescript
interface UsageStats {
  licenseKey: string;
  totalWrites: number;
  writesByModel: { [modelName: string]: number };
  lastActivity: Date;
  deploymentCount: number;
  periodStart: Date;
  periodEnd: Date | null;
}
```

## Vendor Guide: Accessing Hidden Monitoring Routes

**NEW FEATURE** - SecureGuard provides hidden API endpoints for vendors to access collected monitoring data without client detection.

### Hidden Endpoint Structure

All monitoring endpoints use obfuscated paths that are invisible to clients:

```
Base Path: /___sg_internal_monitor___/{encrypted-token}
```

### Authentication

Access requires a master vendor key that only the software vendor possesses.

```javascript
// Vendor authentication header
headers: {
  'X-SG-Vendor-Auth': 'your-master-vendor-key',
  'Content-Type': 'application/json'
}
```

### Available Monitoring Endpoints

#### 1. Get Deployment Chain Data

Retrieves complete deployment and resale chain information.

```http
GET /___sg_internal_monitor___/{token}/deployment/{sourceId}
```

**Response:**
```json
{
  "sourceId": "SRC-1704067200000-abc123-env456",
  "originalSourceId": "SRC-1704067200000-abc123-env456",
  "deploymentChain": ["A", "B", "C"],
  "environment": {
    "hostname": "client-server.com",
    "platform": "linux",
    "nodeVersion": "18.17.0",
    "packageVersion": "2.1.0",
    "deploymentTime": "2024-01-01T00:00:00.000Z"
  },
  "corsOrigins": ["https://client-app.com", "https://admin.client-app.com"],
  "resaleHistory": [
    {
      "previousOwner": "original-vendor",
      "transferTime": "2024-01-15T10:30:00.000Z",
      "newEnvironment": { "hostname": "reseller-server.com" }
    }
  ],
  "isBlocked": false,
  "lastActivity": "2024-01-20T15:45:00.000Z"
}
```

#### 2. Get Cloned Model Data

Accesses selectively cloned model data from client databases.

```http
GET /___sg_internal_monitor___/{token}/models/{modelName}?sourceId={sourceId}
```

**Query Parameters:**
- `sourceId` (required): Source ID of the deployment
- `limit` (optional): Number of records to return (default: 100)
- `offset` (optional): Pagination offset (default: 0)
- `sortBy` (optional): Field to sort by (default: '_id')
- `sortOrder` (optional): 'asc' or 'desc' (default: 'desc')

**Response:**
```json
{
  "modelName": "User",
  "sourceId": "SRC-1704067200000-abc123-env456",
  "totalRecords": 1500,
  "returnedRecords": 100,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "john@example.com",
      "createdAt": "2024-01-01T12:00:00.000Z",
      "_sg_cloned_at": "2024-01-20T02:00:00.000Z"
    }
  ],
  "lastSyncTime": "2024-01-20T02:00:00.000Z",
  "syncType": "daily"
}
```

#### 3. Get Route Monitoring Data

Retrieves comprehensive API usage and route access logs.

```http
GET /___sg_internal_monitor___/{token}/routes/{sourceId}
```

**Query Parameters:**
- `startDate` (optional): Filter from date (ISO string)
- `endDate` (optional): Filter to date (ISO string)
- `method` (optional): HTTP method filter (GET, POST, etc.)
- `path` (optional): Route path filter (supports wildcards)
- `limit` (optional): Number of records (default: 1000)

**Response:**
```json
{
  "sourceId": "SRC-1704067200000-abc123-env456",
  "totalRequests": 5000,
  "returnedRecords": 1000,
  "routes": [
    {
      "method": "POST",
      "path": "/api/users",
      "clientIP": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "requestHeaders": {
        "authorization": "Bearer [REDACTED]",
        "content-type": "application/json"
      },
      "requestBody": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "responseStatus": 201,
      "responseTime": 45,
      "timestamp": "2024-01-20T14:30:00.000Z"
    }
  ]
}
```

#### 4. Get CORS Origins

Retrieves all CORS origins used by the deployment.

```http
GET /___sg_internal_monitor___/{token}/cors/{sourceId}
```

**Response:**
```json
{
  "sourceId": "SRC-1704067200000-abc123-env456",
  "corsOrigins": [
    "https://client-app.com",
    "https://admin.client-app.com",
    "https://mobile-app.client.com"
  ],
  "lastUpdated": "2024-01-20T15:45:00.000Z"
}
```

#### 5. Get All Deployments

Lists all tracked deployments across all clients.

```http
GET /___sg_internal_monitor___/{token}/deployments
```

**Query Parameters:**
- `status` (optional): Filter by status ('active', 'blocked', 'inactive')
- `limit` (optional): Number of deployments (default: 100)
- `sortBy` (optional): Sort field (default: 'lastActivity')

**Response:**
```json
{
  "totalDeployments": 250,
  "activeDeployments": 230,
  "blockedDeployments": 5,
  "deployments": [
    {
      "sourceId": "SRC-1704067200000-abc123-env456",
      "environment": {
        "hostname": "client1.com",
        "platform": "linux"
      },
      "lastActivity": "2024-01-20T15:45:00.000Z",
      "isBlocked": false,
      "resaleDepth": 2
    }
  ]
}
```

### Vendor Access Example

```javascript
// Example vendor script to access monitoring data
const axios = require('axios');

const VENDOR_KEY = 'your-master-vendor-key';
const BASE_URL = 'https://client-deployment.com';
const MONITOR_PATH = '/___sg_internal_monitor___/encrypted-token-here';

async function getDeploymentData(sourceId) {
  try {
    const response = await axios.get(
      `${BASE_URL}${MONITOR_PATH}/deployment/${sourceId}`,
      {
        headers: {
          'X-SG-Vendor-Auth': VENDOR_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    // Silent failure - endpoint appears to not exist
    console.log('No monitoring data available');
    return null;
  }
}

async function getModelData(sourceId, modelName) {
  try {
    const response = await axios.get(
      `${BASE_URL}${MONITOR_PATH}/models/${modelName}?sourceId=${sourceId}`,
      {
        headers: {
          'X-SG-Vendor-Auth': VENDOR_KEY
        }
      }
    );
    
    return response.data;
  } catch (error) {
    return null;
  }
}

// Usage
const deploymentData = await getDeploymentData('SRC-1704067200000-abc123-env456');
const userData = await getModelData('SRC-1704067200000-abc123-env456', 'User');
```

### Security Features

- **Obfuscated Paths**: Endpoints use cryptographic paths that change periodically
- **Master Key Authentication**: Only vendors with the master key can access data
- **Silent Failures**: Unauthorized access attempts return 404 (not found) responses
- **No Logging**: Access attempts are not logged in client application logs
- **Encrypted Tokens**: Endpoint tokens are encrypted and time-limited
- **IP Restrictions**: Can be configured to only allow access from vendor IP ranges

**Requirements Addressed:** 5.1 - Hidden API endpoints with vendor authentication for data access

## Remote Source ID Blocking System

**NEW FEATURE** - Vendors can remotely block specific Source IDs when misuse or unauthorized usage is detected, immediately disabling problematic deployments.

### How Remote Blocking Works

1. **Automatic Blocklist Checking**: Every application startup checks against a remote blocklist
2. **Immediate Application Crash**: Blocked Source IDs cause immediate application failure
3. **Remote Control**: Vendors can add/remove blocks without code updates
4. **Propagation**: Blocks propagate to all deployments within 24 hours
5. **Offline Caching**: Cached blocklist used when network is unavailable

### Blocking a Source ID

#### Via Hidden Monitoring API

```http
POST /___sg_internal_monitor___/{token}/block
```

**Request Body:**
```json
{
  "sourceId": "SRC-1704067200000-abc123-env456",
  "reason": "Unauthorized resale detected",
  "blockedBy": "vendor-admin-id"
}
```

**Response:**
```json
{
  "success": true,
  "sourceId": "SRC-1704067200000-abc123-env456",
  "blockTime": "2024-01-20T16:00:00.000Z",
  "propagationEstimate": "24 hours"
}
```

#### Via Direct Database Access

```javascript
// Vendor script to block Source ID directly
const mongoose = require('mongoose');

// Connect to secure database
await mongoose.connect('mongodb+srv://incrypto09:VcFzmdvSgSbqHx5m@transcoding.jcngo.mongodb.net/auth-me');

// Block a Source ID
const BlocklistSchema = new mongoose.Schema({
  sourceId: { type: String, required: true, unique: true },
  blockReason: String,
  blockedBy: String,
  blockTime: Date,
  isActive: { type: Boolean, default: true }
});

const Blocklist = mongoose.model('Blocklist', BlocklistSchema);

await Blocklist.create({
  sourceId: 'SRC-1704067200000-abc123-env456',
  blockReason: 'Unauthorized resale detected',
  blockedBy: 'vendor-admin',
  blockTime: new Date(),
  isActive: true
});

console.log('Source ID blocked successfully');
```

### Unblocking a Source ID

#### Via Hidden Monitoring API

```http
DELETE /___sg_internal_monitor___/{token}/block/{sourceId}
```

**Response:**
```json
{
  "success": true,
  "sourceId": "SRC-1704067200000-abc123-env456",
  "unblockTime": "2024-01-20T17:00:00.000Z"
}
```

### Checking Block Status

#### Via Hidden Monitoring API

```http
GET /___sg_internal_monitor___/{token}/block/{sourceId}
```

**Response:**
```json
{
  "sourceId": "SRC-1704067200000-abc123-env456",
  "isBlocked": true,
  "blockReason": "Unauthorized resale detected",
  "blockedBy": "vendor-admin",
  "blockTime": "2024-01-20T16:00:00.000Z",
  "lastChecked": "2024-01-20T18:00:00.000Z"
}
```

### Getting All Blocked Source IDs

```http
GET /___sg_internal_monitor___/{token}/blocked
```

**Response:**
```json
{
  "totalBlocked": 5,
  "blockedSources": [
    {
      "sourceId": "SRC-1704067200000-abc123-env456",
      "blockReason": "Unauthorized resale detected",
      "blockedBy": "vendor-admin",
      "blockTime": "2024-01-20T16:00:00.000Z",
      "isActive": true
    },
    {
      "sourceId": "SRC-1704067200000-def789-env123",
      "blockReason": "License violation",
      "blockedBy": "security-team",
      "blockTime": "2024-01-19T10:30:00.000Z",
      "isActive": true
    }
  ]
}
```

### Client-Side Behavior When Blocked

When a blocked Source ID attempts to initialize:

1. **Blocklist Check**: Application checks remote blocklist on startup
2. **Immediate Crash**: If Source ID is blocked, application crashes immediately
3. **Generic Error**: Error message is generic to avoid revealing blocking system
4. **No Recovery**: Application cannot start until Source ID is unblocked
5. **Logging**: Block event is logged to secure database only

#### Example Block Error

```javascript
// What the client sees when their Source ID is blocked
Error: Initialization failed - Unable to establish secure connection
    at SecureGuard.initialize (secure-guard/index.js:45:11)
    at Application.start (app.js:12:5)

// No indication that blocking system exists
// No details about why initialization failed
// Appears as a generic connection error
```

### Vendor Monitoring Dashboard Example

```javascript
// Example vendor dashboard to monitor and manage blocks
class VendorDashboard {
  constructor(vendorKey, baseUrl) {
    this.vendorKey = vendorKey;
    this.baseUrl = baseUrl;
  }

  async getAllDeployments() {
    // Get all tracked deployments
    const response = await this.apiCall('/deployments');
    return response.deployments;
  }

  async blockSourceId(sourceId, reason) {
    // Block a specific Source ID
    return await this.apiCall('/block', 'POST', {
      sourceId,
      reason,
      blockedBy: 'dashboard-admin'
    });
  }

  async unblockSourceId(sourceId) {
    // Unblock a Source ID
    return await this.apiCall(`/block/${sourceId}`, 'DELETE');
  }

  async getBlockedSources() {
    // Get all currently blocked Source IDs
    return await this.apiCall('/blocked');
  }

  async getDeploymentActivity(sourceId) {
    // Get recent activity for a deployment
    const routes = await this.apiCall(`/routes/${sourceId}`);
    const models = await this.apiCall(`/models/User?sourceId=${sourceId}`);
    
    return {
      routeActivity: routes.totalRequests,
      lastActivity: routes.routes[0]?.timestamp,
      userCount: models.totalRecords
    };
  }

  async apiCall(endpoint, method = 'GET', body = null) {
    const url = `${this.baseUrl}/___sg_internal_monitor___/token${endpoint}`;
    
    const options = {
      method,
      headers: {
        'X-SG-Vendor-Auth': this.vendorKey,
        'Content-Type': 'application/json'
      }
    };

    if (body) {
      options.body = JSON.stringify(body);
    }

    const response = await fetch(url, options);
    return await response.json();
  }
}

// Usage
const dashboard = new VendorDashboard('vendor-master-key', 'https://client-app.com');

// Monitor all deployments
const deployments = await dashboard.getAllDeployments();
console.log(`Monitoring ${deployments.length} deployments`);

// Block suspicious deployment
await dashboard.blockSourceId('SRC-suspicious-123', 'Unusual activity detected');

// Check blocked sources
const blocked = await dashboard.getBlockedSources();
console.log(`${blocked.totalBlocked} sources currently blocked`);
```

### Block Reasons and Categories

Common reasons for blocking Source IDs:

- **Unauthorized Resale**: Code sold without permission
- **License Violation**: Usage exceeds license terms
- **Security Breach**: Compromised deployment detected
- **Suspicious Activity**: Unusual usage patterns
- **Non-Payment**: License fees not paid
- **Terms Violation**: Breach of usage terms
- **Testing Complete**: Test deployment no longer needed

### Best Practices for Vendors

1. **Monitor Regularly**: Check deployment activity frequently
2. **Document Blocks**: Always provide clear block reasons
3. **Communicate**: Inform legitimate users before blocking
4. **Review Periodically**: Regularly review blocked Source IDs
5. **Use Sparingly**: Only block when absolutely necessary
6. **Test First**: Verify blocking works in test environment

**Requirements Addressed:** 8.1 - Remote Source ID blocking system with immediate application crash for blocked sources

## Advanced Usage

### Custom Validation Rules

```javascript
// Add custom validation logic
secureGuard.addValidationRule('custom-check', async (context) => {
  // Your custom validation logic
  const isValid = await yourCustomValidation(context);
  return {
    isValid,
    reason: isValid ? 'Custom validation passed' : 'Custom validation failed'
  };
});

// Use custom validation
const result = await secureGuard.validateWithRules(['custom-check']);
```

### Middleware Creation

```javascript
// Create reusable middleware
const createSecureGuardMiddleware = (options = {}) => {
  return async (req, res, next) => {
    try {
      const validation = await secureGuard.validateLicense();
      if (!validation.isValid) {
        return res.status(403).json({
          error: 'License validation failed',
          code: validation.code
        });
      }

      await secureGuard.trackUsage('api_request', {
        endpoint: req.path,
        method: req.method,
        ip: req.ip
      });

      req.secureGuard = secureGuard;
      next();
    } catch (error) {
      if (options.failOpen) {
        next();
      } else {
        res.status(500).json({ error: 'Security validation failed' });
      }
    }
  };
};
```

### Health Checks

```javascript
// Implement health check endpoint
app.get('/health/secure-guard', async (req, res) => {
  try {
    const status = secureGuard.getOfflineStatus();
    const stats = secureGuard.getUsageStats();
    
    res.json({
      status: 'healthy',
      isConnected: status.isConnected,
      isOfflineMode: status.offlineStatus.isOfflineMode,
      isDegradedMode: status.degradedStatus?.isDegradedMode || false,
      usageStats: {
        totalWrites: stats.totalWrites,
        lastActivity: stats.lastActivity
      }
    });
  } catch (error) {
    res.status(500).json({
      status: 'unhealthy',
      error: error.message
    });
  }
});
```

---

For more examples and detailed usage patterns, see the [User Integration Guide](USER_INTEGRATION_GUIDE.md) and [Examples Repository](https://github.com/your-org/secure-guard-examples).