# Dependency Management

Isolated npm installations and module management for user projects with security controls.

## Files

### `dependency-manager.ts`
Handles isolated npm installations for user projects and creates secure require functions with module whitelisting.

## Core Components

### DependencyManager Class
Manages isolated npm installations and provides secure module loading for user applications.

**Purpose:** Ensures user applications have their dependencies installed in isolation while enforcing security controls through module whitelisting.

**Key Features:**
- Isolated `node_modules` per project
- Module whitelist validation
- Version constraint checking
- Secure require function creation
- Path traversal protection

**Usage:**
```typescript
import { DependencyManager } from '@chargebee/chargebee-apps-shared';

const dependencyManager = new DependencyManager();

// Install dependencies for a project
await dependencyManager.ensureDependencies('/app/path', manifest);

// Create secure require function
const allowedModules = [{ name: 'lodash', version: '^4.17.21' }];
const safeRequire = dependencyManager.createIsolatedRequire('/app/path', allowedModules);

// User code can now safely require modules
const _ = safeRequire('lodash'); // ✅ Allowed
// const fs = safeRequire('fs'); // ❌ Throws error - not allowed
```

## Security Features

### Module Whitelisting
Only modules in the allowed list can be required:
- Validates module names against whitelist
- Checks version constraints using semver
- Prevents access to Node.js core modules (fs, child_process, etc.)

### Path Traversal Protection
Prevents directory traversal attacks in relative imports:
- Blocks `../` patterns that escape project directory
- Validates resolved paths stay within project bounds
- Provides safe access to project files only

### Isolated Installation
Each project gets its own dependency environment:
- Separate `node_modules` directory per project
- No shared dependencies between projects
- Clean installation process with error handling

## Installation Process

The dependency manager handles npm installation automatically:
1. Creates `package.json` if missing
2. Runs `npm install` in project directory
3. Validates installation success
4. Provides detailed error reporting

## Error Handling

Comprehensive error handling for various scenarios:
- **Module not allowed** - Clear error when requesting non-whitelisted modules
- **Path traversal** - Security error for invalid relative paths
- **Installation failures** - Detailed npm error reporting
- **Version mismatches** - Warnings for version constraint violations

## Best Practices

1. **Use isolated environments** - Each project gets its own node_modules
2. **Validate all modules** - Only allow whitelisted modules
3. **Check versions** - Validate installed versions match constraints
4. **Handle errors gracefully** - Provide clear error messages
5. **Log security violations** - Track attempted access to restricted modules