nip/docs/platform-detection.md

# Platform Detection and Isolation Strategy Selection

## Overview

The platform detection module (`src/nip/platform.nim`) provides runtime detection of OS capabilities and automatic selection of appropriate isolation strategies for multi-platform support.

**Core Philosophy:**
- **Detect, don't assume** - Query OS capabilities at runtime
- **Graceful degradation** - Fall back to simpler strategies when advanced features unavailable
- **Platform-native solutions** - Use each OS's native isolation tools
- **No false security** - Be honest about what each strategy provides

## Supported Platforms

| Platform | Isolation Strategy | Requirements | Security Level |
|----------|-------------------|--------------|-----------------|
| **Linux** | User Namespaces | Linux 4.19+ with CONFIG_USER_NS | ⭐⭐⭐⭐⭐ |
| **Linux** | POSIX Fallback | Any Linux | ⭐ (Merkle primary) |
| **FreeBSD** | Jails + nullfs | FreeBSD 11.0+ | ⭐⭐⭐⭐⭐ |
| **FreeBSD** | POSIX Fallback | Any FreeBSD | ⭐ (Merkle primary) |
| **OpenBSD** | Unveil + Pledge | OpenBSD 6.4+ | ⭐⭐⭐⭐ |
| **OpenBSD** | POSIX Fallback | Any OpenBSD | ⭐ (Merkle primary) |
| **macOS** | POSIX Fallback | Any macOS | ⭐ (Merkle primary) |
| **Embedded/IoT** | POSIX Fallback | Any system | ⭐ (Merkle primary) |

## Isolation Strategies

### 1. Linux User Namespaces (Preferred on Linux 4.19+)

**Mechanism:** `unshare -r -m` with read-only bind mount

**What it provides:**
- User-level isolation without root privilege
- Kernel-enforced read-only CAS mount
- Process cannot write even if it owns files
- True architectural isolation

**Security Level:** ⭐⭐⭐⭐⭐ (Kernel-enforced)

**When to use:**
- Linux systems with user namespace support
- Default for Linux 4.19+
- Provides strongest isolation

**Example:**
```bash
# Automatically selected on Linux with namespace support
nip install nginx
# Uses: unshare -r -m with read-only bind mount
```

### 2. FreeBSD Jails + nullfs (Elegant BSD Solution)

**Mechanism:** `jail` with read-only `nullfs` mount

**What it provides:**
- Lightweight container isolation
- Read-only nullfs mounts (BSD equivalent of bind mounts)
- Process confined to jail cannot escape
- Mature, battle-tested technology

**Security Level:** ⭐⭐⭐⭐⭐ (Kernel-enforced, mature)

**When to use:**
- FreeBSD systems (requires root)
- Provides excellent isolation
- More mature than Linux namespaces

**Example:**
```bash
# Automatically selected on FreeBSD with jail support
nip install nginx
# Uses: jail + nullfs read-only mount
```

### 3. OpenBSD Unveil + Pledge (Crypto-Anarchist's Dream)

**Mechanism:** `unveil()` for path-based access control + `pledge()` for capability restrictions

**What it provides:**
- Fine-grained path-based access control
- Capability-based security model
- Prevents privilege escalation
- Excellent for build wrappers

**Limitations:**
- `unveil` is reset on `exec()`
- Best for wrapper processes, not direct execution
- Requires explicit pledge() calls

**Security Level:** ⭐⭐⭐⭐ (Capability-based, but reset on exec)

**When to use:**
- OpenBSD systems
- Build wrappers and orchestration
- Not for direct package execution

**Example:**
```bash
# Automatically selected on OpenBSD with unveil support
nip install nginx
# Uses: unveil + pledge for capability restrictions
```

### 4. POSIX Fallback (chmod + Merkle Verification)

**Mechanism:** `chmod 555` for read-only + Merkle verification

**What it provides:**
- Prevents accidental deletion (UX convenience)
- Merkle verification detects tampering immediately
- Works everywhere
- Simple and reliable

**Limitations:**
- **NOT security against malicious actors**
- Users own their files and can change permissions
- Root can always write
- Relies on user discipline

**Security Level:** ⭐ (UX convenience only, Merkle is primary security)

**When to use:**
- Embedded/IoT systems without advanced features
- Fallback when better strategies unavailable
- Non-root users on systems without namespaces
- Always paired with Merkle verification

**Example:**
```bash
# Automatically selected on systems without advanced isolation
nip install nginx
# Uses: chmod 555 + Merkle verification
# ⚠️  WARNING: Running in user mode without kernel isolation
#    CAS is protected by chmod 555 (UX convenience only)
#    Real security comes from Merkle verification
```

## Platform Detection

### Automatic Detection

The platform detection happens automatically when nip starts:

```nim
let caps = detectPlatform()
let strategy = selectStrategy(caps)
```

This detects:
- **OS Type:** Linux, FreeBSD, OpenBSD, NetBSD, macOS, Embedded
- **Kernel Version:** For version-specific feature detection
- **Capabilities:** User namespaces, jails, unveil support
- **System Resources:** Memory, CPU count
- **Embedded Devices:** OpenWrt, Raspberry Pi, etc.

### Manual Override

You can override automatic detection via configuration:

```kdl
# nip-config.kdl
nip {
  platform {
    // Auto-detect platform and select strategy
    auto_detect true

    // Override auto-detection if needed
    // force_strategy "posix"  // "linux", "freebsd", "openbsd", "posix"

    // Embedded device settings
    embedded {
      auto_detect true
      max_concurrent_downloads 2
      max_concurrent_builds 1
      max_cache_size "100MB"
    }

    // Isolation settings
    isolation {
      // Prefer user mode on Linux (if available)
      prefer_user_mode true

      // Require root for system mode
      require_root_for_system true

      // Merkle verification (always enabled)
      verify_chunks true
      verify_signatures true
    }
  }
}
```

## Installation Modes

### User Mode (Linux with Namespaces Only)

**Requirements:**
- Linux 4.19+ with user namespace support
- No root privilege required

**Behavior:**
- Installs to `~/.nexus/envs/<env>/Programs/`
- Creates isolated namespace for each operation
- Kernel enforces read-only CAS mount
- Perfect for development and testing

**Example:**
```bash
nip install --user nginx
# Installs to ~/.nexus/envs/home/Programs/Nginx/
# Uses user namespace isolation
```

### System Mode (Root Required)

**Requirements:**
- Root privilege
- Any platform

**Behavior:**
- Installs to `/Programs/`
- System-wide installation
- Creates new system generation
- Requires root access

**Example:**
```bash
sudo nip install nginx
# Installs to /Programs/Nginx/
# Creates new system generation
```

## Embedded Device Support

### Automatic Detection

Embedded devices are detected via multiple indicators:
- OpenWrt release file
- Device tree (ARM devices)
- Memory < 512MB
- CPU count <= 2
- Raspberry Pi detection

### Resource Constraints

When embedded device is detected, nip automatically applies constraints:

```
📱 Embedded device detected
   Memory: 256MB
   CPUs: 1
   Max concurrent downloads: 1
   Max concurrent builds: 1
   Max cache size: 50MB
   Compression enabled: true
   Deduplication enabled: true
   Parallelization enabled: false
```

### Optimization

For embedded devices:
- Single-threaded builds
- Reduced cache size
- Aggressive compression
- Disabled parallelization on single-core
- Optimized for low memory

## Security Guarantees

### Linux with User Namespaces

```
⭐⭐⭐⭐⭐ Kernel-enforced read-only mount
⭐⭐⭐⭐⭐ Merkle verification (xxh3)
⭐⭐⭐⭐⭐ Signature verification (Ed25519)
```

**Guarantee:** Process cannot modify CAS even if compromised

### FreeBSD with Jails

```
⭐⭐⭐⭐⭐ Kernel-enforced jail isolation
⭐⭐⭐⭐⭐ Read-only nullfs mount
⭐⭐⭐⭐⭐ Merkle verification (xxh3)
⭐⭐⭐⭐⭐ Signature verification (Ed25519)
```

**Guarantee:** Process cannot escape jail or modify CAS

### OpenBSD with Unveil

```
⭐⭐⭐⭐ Capability-based security
⭐⭐⭐⭐⭐ Merkle verification (xxh3)
⭐⭐⭐⭐⭐ Signature verification (Ed25519)
```

**Guarantee:** Process capabilities restricted, tampering detected

### POSIX Fallback

```
⭐ chmod 555 (UX convenience)
⭐⭐⭐⭐⭐ Merkle verification (xxh3) - PRIMARY SECURITY
⭐⭐⭐⭐⭐ Signature verification (Ed25519)
⭐⭐⭐ Audit logging
```

**Guarantee:** Tampering detected immediately via Merkle verification

## Troubleshooting

### "User mode not available on this platform"

**Cause:** You requested user mode on a platform that doesn't support it

**Solution:**
- Use system mode (requires root): `sudo nip install nginx`
- Or use a Linux system with user namespace support (4.19+)

**Check namespace support:**
```bash
cat /proc/sys/user/max_user_namespaces
# Should output a number > 0
```

### "Running in user mode without kernel isolation"

**Cause:** Running on Linux without user namespace support

**Solution:**
- Upgrade kernel to 4.19+
- Or enable CONFIG_USER_NS in kernel config
- Or use system mode with root

**Check kernel version:**
```bash
uname -r
# Should be 4.19 or later
```

### "Embedded device detected"

**Cause:** System detected as embedded/IoT device

**Solution:**
- This is automatic and optimizes for low resources
- No action needed - nip will adjust constraints
- To override: set `embedded.auto_detect false` in config

**Check detection:**
```bash
nip doctor
# Shows platform information and detected constraints
```

## API Reference

### Main Functions

```nim
# Detect platform capabilities
proc detectPlatform*(): PlatformCapabilities

# Select isolation strategy
proc selectStrategy*(caps: PlatformCapabilities): IsolationStrategy

# Select installation mode
proc selectMode*(strategy: IsolationStrategy,
                 userRequest: Option[InstallMode]): InstallMode

# Check if running as root
proc isRoot*(): bool

# Get embedded device constraints
proc getEmbeddedConstraints*(): EmbeddedConstraints
```

### Information Functions

```nim
# Get human-readable OS type name
proc getOSTypeString*(osType: OSType): string

# Get strategy description
proc getStrategyDescription*(strategy: IsolationStrategy): string

# Get security level (1-5 stars)
proc getSecurityLevel*(strategy: IsolationStrategy): int

# Get detailed strategy information
proc getStrategyInfo*(strategy: IsolationStrategy): string

# Format bytes as human-readable string
proc formatBytes*(bytes: int64): string

# Print platform information
proc printPlatformInfo*(caps: PlatformCapabilities)

# Print embedded device constraints
proc printEmbeddedConstraints*(constraints: EmbeddedConstraints)
```

## Testing

Run platform detection tests:

```bash
nim c -r nip/tests/test_platform.nim
```

Tests cover:
- OS type detection
- Kernel version parsing
- Capability detection
- Strategy selection
- Mode selection
- Embedded device detection
- Byte formatting

## Future Enhancements

### Phase 8A: Linux Namespace Isolation (Post-MVP)

- Implement kernel-enforced read-only CAS mount
- Add namespace lifecycle management
- Integrate with package launchers

### Phase 8B: FreeBSD Jail Support (Post-MVP)

- Implement jail creation and lifecycle
- Add nullfs mount management
- Integrate with package launchers

### Phase 8C: OpenBSD Unveil Support (Post-MVP)

- Implement unveil/pledge integration
- Add build wrapper support
- Integrate with build system

### Phase 8D: Embedded/IoT Support (Post-MVP)

- Optimize for resource-constrained devices
- Add OpenWrt-specific support
- Implement low-memory operation modes

## References

- **Linux Namespaces:** https://man7.org/linux/man-pages/man7/namespaces.7.html
- **FreeBSD Jails:** https://docs.freebsd.org/en/books/handbook/jails/
- **OpenBSD Unveil:** https://man.openbsd.org/unveil.2
- **OpenBSD Pledge:** https://man.openbsd.org/pledge.2
- **Platform Isolation Strategy:** `.kiro/steering/shared/platform-isolation-strategy.md`

---

**Document Version:** 1.0
**Last Updated:** November 20, 2025
**Status:** Implementation Complete (MVP)
**Next Steps:** Phase 8 - Advanced isolation strategies (post-MVP)