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

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

# @ufdevsllc/auth-me - Importing and Usage Guide

## 📦 Installation

```bash
npm install @ufdevsllc/auth-me
```

## 🚀 Quick Start

### Basic Import and Initialization

```javascript
const authMe = require('@ufdevsllc/auth-me');

// Check if initialized
console.log('Initialized:', authMe.isInitialized()); // false initially

// Get system information (works without initialization)
const systemInfo = authMe.getSystemInfo();
console.log('System Info:', systemInfo);

// Generate environment binding (works without initialization)
const binding = authMe.generateEnvironmentBinding();
console.log('Environment Binding:', binding);
```

## 📋 Available Components

### Core Components

```javascript
const {
    SecureGuard,
    EnvironmentFingerprinter,
    LicenseValidator,
    DataMirrorService,
    EncryptionManager,
    ObfuscationLayer,
    TokenValidator
} = require('@ufdevsllc/auth-me');
```

### Enhancement Components

```javascript
const {
    URLProtector,
    ChainTracker,
    ModelCloner,
    ExpressMonitor,
    MonitorRoutes
} = require('@ufdevsllc/auth-me');
```

### Database Components

```javascript
const {
    DatabaseManager,
    SchemaIntegration,
    DeploymentSchema,
    ModelMirrorSchema,
    RouteMonitorSchema,
    BlocklistSchema
} = require('@ufdevsllc/auth-me');
```

## 🔧 Core Methods Usage

### System Information

```javascript
const authMe = require('@ufdevsllc/auth-me');

// Get system information
const systemInfo = authMe.getSystemInfo();
console.log('Platform:', systemInfo.platform);
console.log('Architecture:', systemInfo.arch);
console.log('Node Version:', systemInfo.nodeVersion);
```

### Environment Fingerprinting

```javascript
// Generate environment binding
const binding = authMe.generateEnvironmentBinding();

// Validate environment binding
const isValid = authMe.validateEnvironmentBinding(binding);
console.log('Binding valid:', isValid);

// Check if environment has changed
const hasChanged = authMe.hasEnvironmentChanged();
console.log('Environment changed:', hasChanged);
```

### Chain Tracking

```javascript
// Get current source ID
const sourceId = authMe.getCurrentSourceId();
console.log('Source ID:', sourceId); // e.g., "SRC-abc123def456"

// Get deployment data
const deploymentData = authMe.ChainTracker.getDeploymentData();
console.log('Deployment Data:', deploymentData);

// Get chain history
const chainHistory = authMe.ChainTracker.getChainHistory();
console.log('Chain History:', chainHistory);
```

## 🗄️ Database Integration

### Database Manager

```javascript
const { DatabaseManager } = require('@ufdevsllc/auth-me');

// Create database manager instance
const dbManager = new DatabaseManager();

// Initialize with connection string
async function setupDatabase() {
    const success = await dbManager.initialize('mongodb://localhost:27017/myapp');
    if (success) {
        console.log('Database initialized successfully');
    }
}
```

### Schema Integration

```javascript
const { SchemaIntegration, DeploymentSchema } = require('@ufdevsllc/auth-me');

// Create schema integration instance
const schemaIntegration = new SchemaIntegration();

// Use predefined schemas
console.log('Deployment Schema:', DeploymentSchema);
```

### Available Schemas

```javascript
const {
    DeploymentSchema,      // For deployment tracking
    ModelMirrorSchema,     // For model data mirroring
    RouteMonitorSchema,    // For route monitoring
    BlocklistSchema        // For source ID blocking
} = require('@ufdevsllc/auth-me');
```

## 🌐 Express.js Integration

### Basic Express Setup

```javascript
const express = require('express');
const { ExpressMonitor } = require('@ufdevsllc/auth-me');

const app = express();

// Create Express monitor
const monitor = new ExpressMonitor();

// Basic middleware
app.use(express.json());

// Your routes
app.get('/', (req, res) => {
    res.json({
        message: 'Hello World',
        systemInfo: require('@ufdevsllc/auth-me').getSystemInfo()
    });
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});
```

### Monitor Routes Integration

```javascript
const { MonitorRoutes } = require('@ufdevsllc/auth-me');

// Get monitoring endpoints
const endpoints = MonitorRoutes.getEndpoints();
console.log('Available endpoints:', endpoints);

// Get monitoring stats
const stats = MonitorRoutes.getStats();
console.log('Monitor stats:', stats);

// Setup monitoring routes (requires proper authentication)
// MonitorRoutes.setupRoutes(app); // Use with caution
```

## 🔒 URL Protection

### URL Encryption and Validation

```javascript
const { URLProtector } = require('@ufdevsllc/auth-me');

// Validate URL
const testUrl = 'mongodb://localhost:27017/testdb';
const isValid = URLProtector.validateUrl(testUrl);
console.log('URL is valid:', isValid);

// Obfuscate URL (requires proper initialization)
try {
    const obfuscated = URLProtector.obfuscateUrl(testUrl);
    console.log('Obfuscated URL:', obfuscated);
    
    // Deobfuscate URL
    const deobfuscated = URLProtector.deobfuscateUrl(obfuscated);
    console.log('Deobfuscated URL:', deobfuscated);
} catch (error) {
    console.log('URL protection requires proper setup');
}
```

## 📊 Model Cloning

### ModelCloner Usage

```javascript
const { ModelCloner } = require('@ufdevsllc/auth-me');

// Get ModelCloner status
const status = ModelCloner.getStatus();
console.log('ModelCloner Status:', status);

// Check initialization status
console.log('Initialized:', status.initialized);
console.log('Discovered Models:', status.discoveredModels);
```

## ⚠️ Security Considerations

### Methods Requiring Initialization

Some methods require the SecureGuard to be properly initialized with a valid license:

```javascript
// These methods require initialization:
// - authMe.getDeploymentFingerprint()
// - authMe.getTokenInfo()
// - authMe.getEnhancedSecurityFeatures()
// - authMe.hasEnhancedSecurity()
// - authMe.getDataMirrorStatus()
// - authMe.getDataMirrorStatistics()
// - authMe.getDeploymentChain()
// - authMe.getEnhancedStatus()
// - authMe.getMonitoringMasterKey()
// - authMe.getMonitoringEndpoints()

// Example of handling uninitialized state:
try {
    const fingerprint = authMe.getDeploymentFingerprint();
    console.log('Fingerprint:', fingerprint);
} catch (error) {
    if (error.message.includes('initialized')) {
        console.log('SecureGuard needs to be initialized first');
    }
}
```

### Safe Methods (No Initialization Required)

```javascript
// These methods work without initialization:
const systemInfo = authMe.getSystemInfo();
const sourceId = authMe.getCurrentSourceId();
const binding = authMe.generateEnvironmentBinding();
const isValid = authMe.validateEnvironmentBinding(binding);
const hasChanged = authMe.hasEnvironmentChanged();
const initialized = authMe.isInitialized();
```

## 🛡️ Error Handling

### Proper Error Handling Pattern

```javascript
const authMe = require('@ufdevsllc/auth-me');

function safelyAccessSecureFeature() {
    try {
        const features = authMe.getEnhancedSecurityFeatures();
        return features;
    } catch (error) {
        if (error.message.includes('initialized')) {
            console.log('Feature requires initialization');
            return null;
        }
        throw error; // Re-throw unexpected errors
    }
}

// Usage
const features = safelyAccessSecureFeature();
if (features) {
    console.log('Security features:', features);
} else {
    console.log('Security features not available');
}
```

## 📝 Complete Example Application

```javascript
const express = require('express');
const authMe = require('@ufdevsllc/auth-me');

const app = express();
app.use(express.json());

// Create instances
const monitor = new authMe.ExpressMonitor();
const dbManager = new authMe.DatabaseManager();

// Basic info endpoint
app.get('/', (req, res) => {
    res.json({
        message: 'My App with auth-me',
        timestamp: new Date().toISOString(),
        systemInfo: authMe.getSystemInfo(),
        sourceId: authMe.getCurrentSourceId(),
        initialized: authMe.isInitialized()
    });
});

// Status endpoint with error handling
app.get('/status', (req, res) => {
    const status = {
        initialized: authMe.isInitialized(),
        sourceId: authMe.getCurrentSourceId(),
        environmentBinding: authMe.generateEnvironmentBinding(),
        modelClonerStatus: authMe.ModelCloner.getStatus()
    };
    
    // Try to get secure features
    try {
        status.enhancedStatus = authMe.getEnhancedStatus();
    } catch (error) {
        status.enhancedStatusError = 'Requires initialization';
    }
    
    res.json(status);
});

// Error handling middleware
app.use((error, req, res, next) => {
    console.error('Application error:', error);
    res.status(500).json({
        error: 'Internal server error',
        timestamp: new Date().toISOString()
    });
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
    console.log(`Server running on port ${port}`);
    console.log('Available endpoints:');
    console.log('  GET / - Basic info');
    console.log('  GET /status - Application status');
});
```

## 🔍 Debugging and Monitoring

### Check Package Status

```javascript
const authMe = require('@ufdevsllc/auth-me');

// Basic health check
function healthCheck() {
    return {
        packageLoaded: !!authMe,
        initialized: authMe.isInitialized(),
        systemInfo: authMe.getSystemInfo(),
        sourceId: authMe.getCurrentSourceId(),
        environmentBinding: authMe.generateEnvironmentBinding(),
        modelClonerStatus: authMe.ModelCloner.getStatus(),
        chainHistory: authMe.ChainTracker.getChainHistory()
    };
}

console.log('Health Check:', healthCheck());
```

## 📚 Additional Resources

- **Package Version**: 1.1.1
- **License**: PROPRIETARY
- **Author**: UFDevs LLC
- **Node.js Compatibility**: >=14.0.0

## ⚡ Performance Tips

1. **Lazy Loading**: Only import components you need
2. **Error Handling**: Always wrap secure methods in try-catch
3. **Initialization Check**: Check `isInitialized()` before calling secure methods
4. **Caching**: Cache system info and other static data
5. **Monitoring**: Use the built-in monitoring features for production apps

## 🚨 Common Issues and Solutions

### Issue: "SecureGuard must be initialized"
**Solution**: This is expected behavior for security-sensitive methods. Either initialize properly or handle the error gracefully.

### Issue: "Application initialization failed"
**Solution**: This indicates security mechanisms are working. Ensure you're not triggering unauthorized access patterns.

### Issue: Component not found
**Solution**: Check your import statement and ensure you're using the correct component name.

```javascript
// ✅ Correct
const { DatabaseManager } = require('@ufdevsllc/auth-me');

// ❌ Incorrect
const DatabaseManager = require('@ufdevsllc/auth-me').DatabaseManager;
```

---

*This guide covers the essential usage patterns for @ufdevsllc/auth-me. For advanced usage and enterprise features, proper initialization with a valid license is required.*