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:

# 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:

# 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:

# 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:

# 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:

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:

# 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:

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:

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:

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:

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:

nip doctor
# Shows platform information and detected constraints

API Reference

Main Functions

# 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

# 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:

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)