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

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

# @ufdevsllc/auth-me - API Reference

## 📚 Table of Contents

1. [Core Methods](#core-methods)
2. [Component Classes](#component-classes)
3. [Database Schemas](#database-schemas)
4. [Static Methods](#static-methods)
5. [Error Handling](#error-handling)
6. [Type Definitions](#type-definitions)

## 🔧 Core Methods

### Package Import

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

### Basic Methods (No Initialization Required)

#### `authMe.isInitialized()`
Returns the initialization status of SecureGuard.

**Returns:** `boolean`
```javascript
const initialized = authMe.isInitialized();
// Returns: false (initially)
```

#### `authMe.getSystemInfo()`
Returns comprehensive system information.

**Returns:** `Object`
```javascript
const systemInfo = authMe.getSystemInfo();
// Returns: {
//   platform: 'darwin',
//   arch: 'x64',
//   release: '24.5.0',
//   cpus: 12,
//   totalMemory: 17179869184,
//   freeMemory: 1223409664,
//   uptime: 2260,
//   nodeVersion: 'v18.20.7',
//   processId: 12345,
//   processUptime: 32.282
// }
```

#### `authMe.getCurrentSourceId()`
Returns the current deployment's unique source ID.

**Returns:** `string`
```javascript
const sourceId = authMe.getCurrentSourceId();
// Returns: "SRC-abc123def456"
```

#### `authMe.generateEnvironmentBinding()`
Generates an environment-specific binding string.

**Returns:** `string`
```javascript
const binding = authMe.generateEnvironmentBinding();
// Returns: "ENV-bind123456789abcdef..."
```

#### `authMe.validateEnvironmentBinding(binding)`
Validates an environment binding string.

**Parameters:**
- `binding` (string): The binding string to validate

**Returns:** `boolean`
```javascript
const binding = authMe.generateEnvironmentBinding();
const isValid = authMe.validateEnvironmentBinding(binding);
// Returns: true
```

#### `authMe.hasEnvironmentChanged()`
Checks if the environment has changed since last check.

**Returns:** `boolean`
```javascript
const hasChanged = authMe.hasEnvironmentChanged();
// Returns: false (typically)
```

### Secure Methods (Require Initialization)

#### `authMe.getDeploymentFingerprint()`
Returns the deployment fingerprint.

**Returns:** `string`
**Throws:** Error if not initialized
```javascript
try {
    const fingerprint = authMe.getDeploymentFingerprint();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing deployment fingerprint"
}
```

#### `authMe.getTokenInfo()`
Returns token information.

**Returns:** `Object`
**Throws:** Error if not initialized
```javascript
try {
    const tokenInfo = authMe.getTokenInfo();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing token info"
}
```

#### `authMe.getEnhancedSecurityFeatures()`
Returns enhanced security features information.

**Returns:** `Object`
**Throws:** Error if not initialized
```javascript
try {
    const features = authMe.getEnhancedSecurityFeatures();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing enhanced security features"
}
```

#### `authMe.hasEnhancedSecurity()`
Checks if enhanced security is available.

**Returns:** `boolean`
**Throws:** Error if not initialized
```javascript
try {
    const hasEnhanced = authMe.hasEnhancedSecurity();
} catch (error) {
    // Error: "SecureGuard must be initialized before checking enhanced security"
}
```

#### `authMe.getDataMirrorStatus()`
Returns data mirror status.

**Returns:** `Object`
**Throws:** Error if not initialized
```javascript
try {
    const status = authMe.getDataMirrorStatus();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing data mirror status"
}
```

#### `authMe.getDataMirrorStatistics()`
Returns data mirror statistics.

**Returns:** `Object`
**Throws:** Error if not initialized
```javascript
try {
    const stats = authMe.getDataMirrorStatistics();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing data mirror statistics"
}
```

#### `authMe.getDeploymentChain(sourceId?)`
Returns deployment chain information.

**Parameters:**
- `sourceId` (string, optional): Specific source ID to query

**Returns:** `Promise<Array>`
**Throws:** Error if not initialized
```javascript
try {
    const chain = await authMe.getDeploymentChain();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing deployment chain"
}
```

#### `authMe.getEnhancedStatus()`
Returns comprehensive enhanced status.

**Returns:** `Object`
**Throws:** Error if not initialized
```javascript
try {
    const status = authMe.getEnhancedStatus();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing enhanced status"
}
```

#### `authMe.getMonitoringMasterKey()`
Returns the monitoring master key.

**Returns:** `string`
**Throws:** Error if not initialized
```javascript
try {
    const masterKey = authMe.getMonitoringMasterKey();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing master key"
}
```

#### `authMe.getMonitoringEndpoints()`
Returns available monitoring endpoints.

**Returns:** `Array<string>`
**Throws:** Error if not initialized
```javascript
try {
    const endpoints = authMe.getMonitoringEndpoints();
} catch (error) {
    // Error: "SecureGuard must be initialized before accessing monitoring endpoints"
}
```

### Token Management Methods

#### `authMe.getTokenCacheStats()`
Returns token cache statistics.

**Returns:** `Object`
**Throws:** Error if not initialized

#### `authMe.clearTokenCache()`
Clears the token cache.

**Returns:** `void`
**Throws:** Error if not initialized

#### `authMe.validateTokens(tokens)`
Validates provided tokens.

**Parameters:**
- `tokens` (Array): Tokens to validate

**Returns:** `Object`
**Throws:** Error if not initialized

## 🏗️ Component Classes

### DatabaseManager

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

#### Methods

##### `initialize(connectionString)`
Initializes the database connection.

**Parameters:**
- `connectionString` (string): MongoDB connection string

**Returns:** `Promise<boolean>`
```javascript
const success = await dbManager.initialize('mongodb://localhost:27017/myapp');
```

##### `getConnection()`
Returns the current database connection.

**Returns:** `Object|null`

##### `isInitialized()`
Checks if the database manager is initialized.

**Returns:** `boolean`

### SchemaIntegration

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

#### Methods

##### `initialize(connection)`
Initializes schema integration with a database connection.

**Parameters:**
- `connection` (Object): Database connection object

**Returns:** `Promise<boolean>`

##### `getSchemas()`
Returns available schemas.

**Returns:** `Object`

### ExpressMonitor

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

#### Methods

##### `initialize(app, options?)`
Initializes monitoring for an Express app.

**Parameters:**
- `app` (Object): Express application instance
- `options` (Object, optional): Configuration options

**Returns:** `Promise<boolean>`

##### `getStats()`
Returns monitoring statistics.

**Returns:** `Object`

## 🔧 Static Methods

### ChainTracker

#### `ChainTracker.getCurrentSourceId()`
Returns the current source ID.

**Returns:** `string`
```javascript
const sourceId = authMe.ChainTracker.getCurrentSourceId();
```

#### `ChainTracker.getDeploymentData()`
Returns current deployment data.

**Returns:** `Object|null`
```javascript
const deploymentData = authMe.ChainTracker.getDeploymentData();
```

#### `ChainTracker.getChainHistory()`
Returns chain history.

**Returns:** `Array`
```javascript
const history = authMe.ChainTracker.getChainHistory();
```

#### `ChainTracker.isInitialized()`
Checks if ChainTracker is initialized.

**Returns:** `boolean`
```javascript
const initialized = authMe.ChainTracker.isInitialized();
```

### ModelCloner

#### `ModelCloner.getStatus()`
Returns ModelCloner status.

**Returns:** `Object`
```javascript
const status = authMe.ModelCloner.getStatus();
// Returns: {
//   initialized: false,
//   discoveredModels: 0,
//   connectionStatus: 'disconnected'
// }
```

#### `ModelCloner.initialize(connectionString)`
Initializes ModelCloner with database connection.

**Parameters:**
- `connectionString` (string): MongoDB connection string

**Returns:** `Promise<Object>`

#### `ModelCloner.closeConnection()`
Closes the ModelCloner connection.

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

### URLProtector

#### `URLProtector.validateUrl(url)`
Validates a URL format.

**Parameters:**
- `url` (string): URL to validate

**Returns:** `boolean`
```javascript
const isValid = authMe.URLProtector.validateUrl('mongodb://localhost:27017/test');
// Returns: true
```

#### `URLProtector.obfuscateUrl(url)`
Obfuscates a URL (requires initialization).

**Parameters:**
- `url` (string): URL to obfuscate

**Returns:** `string`
**Throws:** Error if not properly initialized

#### `URLProtector.deobfuscateUrl(obfuscatedUrl)`
Deobfuscates a URL (requires initialization).

**Parameters:**
- `obfuscatedUrl` (string): Obfuscated URL

**Returns:** `string`
**Throws:** Error if not properly initialized

### MonitorRoutes

#### `MonitorRoutes.getEndpoints()`
Returns available monitoring endpoints.

**Returns:** `Array<string>`
```javascript
const endpoints = authMe.MonitorRoutes.getEndpoints();
```

#### `MonitorRoutes.getStats()`
Returns monitoring statistics.

**Returns:** `Object`
```javascript
const stats = authMe.MonitorRoutes.getStats();
```

#### `MonitorRoutes.setupRoutes(app)`
Sets up monitoring routes on an Express app.

**Parameters:**
- `app` (Object): Express application instance

**Returns:** `Promise<Object>`

## 📊 Database Schemas

### DeploymentSchema

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

Schema for deployment tracking data.

### ModelMirrorSchema

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

Schema for model data mirroring.

### RouteMonitorSchema

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

Schema for route monitoring data.

### BlocklistSchema

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

Schema for source ID blocking.

## ⚠️ Error Handling

### Common Error Types

#### InitializationError
Thrown when accessing secure features without proper initialization.

```javascript
try {
    const features = authMe.getEnhancedSecurityFeatures();
} catch (error) {
    if (error.message.includes('initialized')) {
        // Handle initialization requirement
        console.log('Feature requires initialization');
    }
}
```

#### SecurityError
Thrown when security mechanisms are triggered.

```javascript
try {
    const endpoints = authMe.MonitorRoutes.getEndpoints();
} catch (error) {
    if (error.message.includes('contact support')) {
        // Security mechanism triggered
        console.log('Access denied by security system');
    }
}
```

### Error Handling Pattern

```javascript
function safeMethodCall(methodName, ...args) {
    try {
        return {
            success: true,
            result: authMe[methodName](...args)
        };
    } catch (error) {
        return {
            success: false,
            error: error.message,
            requiresInitialization: error.message.includes('initialized'),
            securityTriggered: error.message.includes('contact support')
        };
    }
}
```

## 📝 Type Definitions

### SystemInfo

```typescript
interface SystemInfo {
    platform: string;
    arch: string;
    release: string;
    cpus: number;
    totalMemory: number;
    freeMemory: number;
    uptime: number;
    nodeVersion: string;
    processId: number;
    processUptime: number;
}
```

### ModelClonerStatus

```typescript
interface ModelClonerStatus {
    initialized: boolean;
    discoveredModels: number;
    connectionStatus: string;
    lastSync?: Date;
    errors?: Array<string>;
}
```

### ChainTrackerData

```typescript
interface ChainTrackerData {
    sourceId: string;
    timestamp: Date;
    environment: Object;
    parentSourceId?: string;
    metadata: Object;
}
```

## 🔍 Usage Examples

### Basic Usage

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

// Always available
console.log('System:', authMe.getSystemInfo());
console.log('Source ID:', authMe.getCurrentSourceId());
console.log('Initialized:', authMe.isInitialized());

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

### Error Handling

```javascript
function getSecureFeatures() {
    try {
        return authMe.getEnhancedSecurityFeatures();
    } catch (error) {
        if (error.message.includes('initialized')) {
            return { error: 'Requires initialization' };
        }
        throw error;
    }
}
```

### Express Integration

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

const app = express();
const monitor = new authMe.ExpressMonitor();

app.get('/status', (req, res) => {
    res.json({
        initialized: authMe.isInitialized(),
        systemInfo: authMe.getSystemInfo(),
        sourceId: authMe.getCurrentSourceId()
    });
});
```

---

## 📋 Method Summary

| Method | Initialization Required | Returns | Description |
|--------|------------------------|---------|-------------|
| `isInitialized()` | ❌ | boolean | Check initialization status |
| `getSystemInfo()` | ❌ | Object | Get system information |
| `getCurrentSourceId()` | ❌ | string | Get source ID |
| `generateEnvironmentBinding()` | ❌ | string | Generate environment binding |
| `validateEnvironmentBinding()` | ❌ | boolean | Validate binding |
| `hasEnvironmentChanged()` | ❌ | boolean | Check environment changes |
| `getDeploymentFingerprint()` | ✅ | string | Get deployment fingerprint |
| `getTokenInfo()` | ✅ | Object | Get token information |
| `getEnhancedSecurityFeatures()` | ✅ | Object | Get security features |
| `getDataMirrorStatus()` | ✅ | Object | Get mirror status |
| `getEnhancedStatus()` | ✅ | Object | Get comprehensive status |

---

*This API reference covers all public methods and components available in @ufdevsllc/auth-me v1.1.1*