# Majoor Assets Manager - Security Model & Environment Variables Guide

**Version**: 2.4.9
**Last Updated**: April 7, 2026

## Overview
The Majoor Assets Manager implements a comprehensive security model to protect your system while providing powerful asset management capabilities. This guide covers the security architecture, threat models, and security-related environment variables.

**Recent highlights**: Enhanced API token support, improved Safe Mode controls, better remote access configuration, and a configurable index database directory for network-drive setups.

## Security Architecture

### Defense Layers
The Assets Manager employs multiple layers of security:

#### Application Layer Security
- Input validation and sanitization
- Path containment and validation
- File type verification
- Access control mechanisms

#### Network Layer Security
- CSRF protection on state-changing endpoints
- Origin validation for sensitive requests
- Rate limiting on expensive operations
- Secure communication protocols

#### File System Security
- Root containment validation
- Path traversal prevention
- Permission checking
- Symlink handling controls

### Trust Model
- **User Input**: All user input is validated and sanitized
- **File System**: Only allowed directories are accessible
- **External Tools**: Tools run with limited privileges
- **Network**: Requests validated against origin policies

## Authentication & Authorization

### Write access guard (recommended)
ComfyUI is often used locally, but it can be exposed via `--listen`, reverse proxies, or tunnels.
To reduce risk, Majoor blocks destructive/write operations from non-local clients by default.

- **Default behavior (no token configured)**: allow write operations only from loopback clients (`127.0.0.1` / `::1` / `localhost`).
- **Token behavior**: if `MAJOOR_API_TOKEN` (or `MJR_API_TOKEN`) is set, remote write operations require it.
  - Loopback keeps the compatibility behavior by default.
  - Send the token via `X-MJR-Token: <token>` or `Authorization: Bearer <token>`.
- **Remote first-run bootstrap**: if no persistent API token is configured yet, an authenticated ComfyUI user can bootstrap the initial remote session token automatically over HTTPS without setting `MAJOOR_ALLOW_BOOTSTRAP=1`.
- **Loopback recovery bootstrap**: local browser sessions on loopback can recover a Majoor write session after restart/new tab without a separate ComfyUI sign-in step.
- **Legacy hash-only recovery**: if an older install only has a stored token hash, the first successful bootstrap rotates to a new persistent plaintext token automatically so future sessions can recover cleanly.
- **Strict local auth**: set `MAJOOR_REQUIRE_AUTH=1` if you want loopback writes to require the token too.

#### Overrides (use with care)
- `MAJOOR_REQUIRE_AUTH=1` forces token auth even for loopback (requires `MAJOOR_API_TOKEN`).
- `MAJOOR_ALLOW_REMOTE_WRITE=1` allows remote write operations without a token (**unsafe**).
- `MAJOOR_ALLOW_BOOTSTRAP=1` temporarily enables initial `/bootstrap-token` provisioning for remote clients even when no authenticated ComfyUI user context is available. Disable it after first successful bootstrap.

#### Where to set these variables
Set these on the machine that runs ComfyUI, in the same shell, batch file, service definition, or launcher script that starts `python main.py`.

Recent builds expose the main remote-access controls directly in Majoor Settings as well. For many home/LAN setups, a signed-in ComfyUI user can now complete the initial remote setup from the UI without manually editing startup scripts.

Recommended UI path for a trusted LAN setup:

1. Open Majoor Settings.
2. Enable `Recommended Remote LAN Setup`.
3. Confirm the browser session is authorized.

That preset generates a strong token if needed, forces token auth for writes, keeps anonymous remote writes disabled, automatically enables HTTP token transport only when the current session is a non-loopback HTTP LAN connection, and injects the token into the current browser session immediately.

Majoor also shows the current session state directly inside Assets Manager through the runtime widget, with a `Write auth:` line such as `Write auth: active ...ABCD`.

Windows batch example:
```batch
@echo off
set MAJOOR_API_TOKEN=change-this-to-a-long-random-secret
set MJR_AM_INDEX_DIRECTORY=C:\mjr_index
cd /d "C:\path\to\ComfyUI"
python main.py --listen 0.0.0.0 --port 8188
```

Linux/macOS shell example:
```bash
export MAJOOR_API_TOKEN="change-this-to-a-long-random-secret"
export MJR_AM_INDEX_DIRECTORY=/var/local/mjr_index
cd /path/to/ComfyUI
python main.py --listen 0.0.0.0 --port 8188
```

If you change the value after ComfyUI is already running, restart ComfyUI so the new environment is loaded.

### Client-side token handling
Set the same secret inside ComfyUI's Settings modal at **Security -> Majoor: API Token** if you want a fixed shared token across multiple browsers/devices.

Runtime behavior:

- the current browser session keeps its active write token in `sessionStorage` (tab/session scoped)
- bootstrap/rotate flows can also set the companion `httpOnly` cookie `mjr_write_token`
- the settings API does not expose the plaintext token after save; it only reports non-secret status fields such as `token_configured` and `token_hint`
- browser-local settings intentionally scrub the plaintext token after it has been pushed into the active session

### Safe Mode (default enabled)
Safe Mode adds an explicit opt-in layer for operations that modify files or user metadata.

- `MAJOOR_SAFE_MODE` (default: enabled)
  - Set `MAJOOR_SAFE_MODE=0` to disable Safe Mode.
- `MAJOOR_ALLOW_WRITE=1`
  - Allows rating/tags writes while Safe Mode is enabled.
- `MAJOOR_ALLOW_DELETE=1`
  - Enables asset deletion (disabled by default).
- `MAJOOR_ALLOW_RENAME=1`
  - Enables asset rename (disabled by default).
- `MAJOOR_ALLOW_OPEN_IN_FOLDER=1`
  - Enables `/mjr/am/open-in-folder` (disabled by default).
  - This route may reveal any existing local file path in the OS file manager. It does not read, write, delete, download, or index that file.

### Access Control
- File access limited to ComfyUI's allowed directories
- No direct read/write access to system files outside allowed paths
- Exception: `/mjr/am/open-in-folder` can reveal an existing path in the OS file manager when explicitly enabled, because it is an OS launch action rather than file content access.
- Permission inheritance from ComfyUI's file system access
- No elevation of privileges possible

## CSRF Protection

### Request Validation
All state-changing endpoints require additional validation:

#### XMLHttpRequest Header
- Requests must include `X-Requested-With: XMLHttpRequest`
- Prevents simple form submissions from external sites
- Standard technique for AJAX endpoint protection

#### CSRF Token Alternative
- Alternative validation using `X-CSRF-Token` header
- Provides fallback for different client implementations
- Tokens validated against session state

### Origin Validation
- When `Origin` header is present, it's validated against `Host`
- Prevents cross-origin requests from unauthorized domains
- Protects against certain types of cross-site attacks

## Rate Limiting

### Per-Client Limits
Rate limiting is implemented on expensive endpoints:

#### Affected Endpoints
- Search operations (`/mjr/am/search`)
- Index scanning (`/mjr/am/scan`)
- Metadata extraction (`/mjr/am/metadata`)
- Batch ZIP operations (`/mjr/am/batch-zip`)

#### Limit Configuration
- Implemented in-memory per-client
- Client identity based on IP address
- Configurable thresholds for different operations
- Resets after specified time intervals

#### Trusted Proxy Support
- `X-Forwarded-For` header honored only from trusted proxies
- Controlled by `MAJOOR_TRUSTED_PROXIES` environment variable
- Prevents IP spoofing in proxy environments

## Path Safety & Containment

### Root Validation
All file operations validate root containment:

#### Allowed Roots
- ComfyUI output directory
- ComfyUI input directory
- Custom roots defined by user
- Collections directory

#### Path Validation Process
1. Normalize the requested path
2. Resolve to absolute path
3. Verify path starts with allowed root
4. Reject if outside allowed boundaries

### Symlink Handling
- Symlinks are handled carefully to prevent directory traversal
- Optional symlink support via `MJR_ALLOW_SYMLINKS` environment variable
- Disabled by default for security
- When enabled, still validates final resolved path

### Path Traversal Prevention
- Input paths are normalized to prevent `../` attacks
- Absolute path resolution ensures final location is verified
- Multiple validation layers prevent bypass attempts

## File Operation Security

### Safe File Operations
- All file operations go through security validation
- Read operations limited to allowed directories
- Write operations limited to index and temporary directories
- Delete operations require additional confirmation

### Batch ZIP Security
- ZIP building streams directly from file handles
- Prevents TOCTOU (Time-of-Check-Time-of-Use) race conditions
- No temporary file copies created during ZIP building
- Automatic cleanup of temporary ZIP files

### File Type Validation
- File types validated before processing
- Dangerous file types blocked from certain operations
- MIME type checking where possible
- Extension validation for security-sensitive operations

## Network Security

### HTTP Security Headers
Applied to Majoor API endpoints only:

#### Content Security Policy
- `Content-Security-Policy: default-src 'none'`
- Prevents execution of injected content
- Applies only to API responses

#### Content Type Options
- `X-Content-Type-Options: nosniff`
- Prevents MIME-type confusion attacks
- Ensures content is treated as declared type

#### Frame Options
- `X-Frame-Options: DENY`
- Prevents embedding in iframes
- Protects against clickjacking

#### Referrer Policy
- `Referrer-Policy: strict-origin-when-cross-origin`
- Limits referrer information leakage
- Balances privacy with functionality

### API Versioning Security
- Versioned routes redirect to canonical endpoints
- `/mjr/am/v1/...` redirects to `/mjr/am/...` using 308
- Maintains security headers across versions
- Preserves method and query parameters

## External Tool Security

### Tool Execution Safety
- External tools (ExifTool, FFprobe) run with limited privileges
- Input validation before passing to external tools
- Timeout enforcement to prevent hanging operations
- Output validation after tool execution

### Path Validation for Tools
- File paths validated before passing to external tools
- No direct shell execution, only tool invocation
- Input sanitization for all tool parameters
- Tool output parsing with validation

### Tool Location Security
- Tools can be specified via environment variables
- Default to system PATH for security
- No arbitrary tool execution possible
- Tool paths validated at startup

## Environment Variable Security

### Secure Configuration
Environment variables provide secure configuration without code changes:

#### Configuration Validation
- Environment variables validated at startup
- Invalid values fall back to defaults safely
- No unsafe defaults used
- Clear error messages for invalid configurations

### Sensitive Information Handling
- No passwords or secrets stored in environment
- File paths validated for security
- No direct system command execution via environment
- Configuration changes logged appropriately

### Trusted Proxy Configuration
- `MAJOOR_TRUSTED_PROXIES` controls proxy trust
- Default: `127.0.0.1,::1` (localhost only)
- Prevents IP spoofing in proxy environments
- Critical for rate limiting effectiveness

## Threat Model

### Identified Threats

#### Information Disclosure
- Unauthorized access to file metadata
- Exposure of file system structure
- Leakage of generation parameters
- **Mitigation**: Path validation, access controls

#### Path Traversal
- Access to files outside allowed directories
- Reading system files or other users' data
- Writing to unauthorized locations
- **Mitigation**: Path containment, normalization

#### Resource Exhaustion
- Denial of service through expensive operations
- Memory exhaustion via large metadata
- Database locking through concurrent operations
- **Mitigation**: Rate limiting, timeouts, resource limits

#### Code Execution
- Arbitrary command execution through file operations
- Injection through file names or paths
- Malicious file content processing
- **Mitigation**: Input validation, sandboxing

#### Cross-Site Attacks
- CSRF attacks on API endpoints
- XSS through metadata injection
- Clickjacking of interface elements
- **Mitigation**: CSRF tokens, security headers

### Attack Vectors

#### Direct API Access
- Unauthorized access to HTTP endpoints
- Brute force attempts on protected endpoints
- **Protection**: Origin validation, rate limiting

#### File System Manipulation
- Creation of malicious file names
- Symlink attacks in custom roots
- **Protection**: Path validation, containment

#### Input Injection
- Malformed metadata in files
- Special characters in file names
- **Protection**: Input sanitization, validation

## Security Monitoring

### Request Logging
- Optional request logging via observability settings
- Logs include client IP, endpoint, and timestamp
- Sensitive data not logged (file contents, metadata)
- Helpful for detecting unusual access patterns

### Error Handling
- Secure error messages that don't leak system information
- Internal errors logged but not exposed to users
- Validation errors provide guidance without revealing internals
- Stack traces hidden from end users

### Audit Trail
- File operations logged with appropriate detail
- Configuration changes tracked where applicable
- Access patterns monitored for anomalies
- Retention policies for security logs

## Security Best Practices

### Deployment Security

#### Network Isolation
- Run ComfyUI behind appropriate firewalls
- Limit network access to trusted users
- Use VPN or other secure access methods
- Monitor network traffic for anomalies

#### File System Permissions
- Run ComfyUI with minimal required privileges
- Restrict file system permissions appropriately
- Regular permission audits
- Separate user accounts for different functions

#### Regular Updates
- Keep Assets Manager updated to latest version
- Update external tools (ExifTool, FFprobe) regularly
- Apply security patches promptly
- Test updates in non-production environments first

### Configuration Security

#### Principle of Least Privilege
- Grant only necessary file system access
- Disable unnecessary features
- Use restrictive default settings
- Regular security configuration reviews

#### Environment Hardening
- Secure environment variable storage
- Validate all configuration inputs
- Use secure defaults where possible
- Regular security configuration audits

### Operational Security

#### Access Control
- Limit access to authorized users
- Regular access reviews
- Session management best practices
- Audit user activities appropriately

#### Monitoring and Detection
- Monitor for unusual access patterns
- Alert on security-relevant events
- Regular security log reviews
- Incident response procedures

## Security-Related Environment Variables

### Trusted Proxy Configuration
- **MAJOOR_TRUSTED_PROXIES**
  - Purpose: IPs/CIDRs allowed to supply `X-Forwarded-For`/`X-Real-IP`
  - Default: `127.0.0.1,::1`
  - Format: Comma-separated IPs or CIDR blocks
  - Security Impact: Controls which proxies can affect rate limiting
  - Example: `MAJOOR_TRUSTED_PROXIES=127.0.0.1,192.168.1.0/24,10.0.0.0/8`

### Symlink Controls
- **MJR_ALLOW_SYMLINKS**
  - Purpose: Allow symlink/junction custom roots
  - Default: `off` (disabled)
  - Options: `on`, `off`, `true`, `false`
  - Security Impact: Controls directory traversal risk
  - Example: `MJR_ALLOW_SYMLINKS=on`

### Database Security
- **MAJOOR_DB_TIMEOUT**
  - Purpose: Database operation timeout
  - Default: 30.0 seconds
  - Security Impact: Prevents resource exhaustion
  - Example: `MAJOOR_DB_TIMEOUT=60.0`

- **MAJOOR_DB_QUERY_TIMEOUT**
  - Purpose: Maximum query execution time
  - Default: 60.0 seconds
  - Security Impact: Prevents long-running queries
  - Example: `MAJOOR_DB_QUERY_TIMEOUT=45.0`

### Resource Limits
- **MAJOOR_MAX_METADATA_JSON_BYTES**
  - Purpose: Maximum metadata JSON size stored in DB/cache
  - Default: 2097152 (2MB)
  - Security Impact: Prevents memory exhaustion
  - Example: `MAJOOR_MAX_METADATA_JSON_BYTES=4194304`

- **MJR_COLLECTION_MAX_ITEMS**
  - Purpose: Max items per collection JSON
  - Default: 50000
  - Security Impact: Prevents resource exhaustion
  - Example: `MJR_COLLECTION_MAX_ITEMS=100000`

### Dependency Management
- **MJR_AM_NO_AUTO_PIP**
  - Purpose: Disable best-effort dependency auto-install on startup
  - Default: Auto-install enabled
  - Security Impact: Controls external package installation
  - Options: `1`, `true`, `yes`, `on` to disable
  - Example: `MJR_AM_NO_AUTO_PIP=1`

## Security Testing

### Self-Assessment Checklist
Regularly verify security configuration:

#### Access Controls
- [ ] File system access limited to intended directories
- [ ] Custom roots validated and secure
- [ ] No unauthorized file access possible

#### Network Security
- [ ] CSRF protection active on state-changing endpoints
- [ ] Rate limiting functioning properly
- [ ] Security headers applied correctly

#### Input Validation
- [ ] Path traversal prevented
- [ ] File type validation working
- [ ] External tool inputs sanitized

### Penetration Testing Considerations
When performing security testing:

#### Authorized Testing Only
- Ensure proper authorization before testing
- Test in isolated environments when possible
- Document and report findings appropriately

#### Testing Areas
- Path traversal attempts
- Input validation bypasses
- Authentication bypasses
- Resource exhaustion attacks
- Cross-site scripting attempts

## Incident Response

### Security Event Classification
- **Low Risk**: Minor configuration issues
- **Medium Risk**: Potential information disclosure
- **High Risk**: System compromise or data breach
- **Critical Risk**: Active exploitation in progress

### Response Procedures
1. Isolate affected systems
2. Document the incident
3. Assess scope and impact
4. Apply immediate mitigations
5. Investigate root cause
6. Implement permanent fixes
7. Communicate appropriately
8. Review and improve procedures

---
*Security Model & Environment Variables Guide Version: 1.0*
*Last Updated: April 5, 2026*