ADR-0026: Configurable Data Directory for SPIKE Components

Status: accepted
Date: 2025-09-13
Tags: Configuration, Operations, Deployment

Context and Problem Statement

SPIKE currently hardcodes the data directory to ~/.spike for storing encrypted databases and recovery data. The comment in internal/config/config.go:40 states this is “for security reasons,” but analysis reveals this constraint provides limited security benefits while restricting legitimate operational use cases.

Given SPIKE’s security model:

The backing store is always encrypted with AES-256
SPIKE treats the backing store as untrusted
Directory permissions are set to 0700 regardless of location

The hardcoded path primarily provides operational simplicity rather than fundamental security guarantees.

Decision Drivers

Deployment flexibility for containerized environments
Support for multi-instance deployments
Compliance requirements for data residency
Testing and CI/CD pipeline needs
Maintaining the security posture

Considered Options

Keep current hardcoded approach - Maintain ~/.spike as the only option
Environment variable configuration - Allow override via environment variables
Configuration file approach - Use a configuration file for data paths
Hybrid approach - Environment variables with sensible defaults and validation

Decision

Implement Option 4: Hybrid approach using environment variables with sensible defaults and comprehensive validation.

Detailed Design

New Environment Variables

# SPIKE Nexus data directory (default: ~/.spike/data)
SPIKE_NEXUS_DATA_DIR=/custom/path/to/data

# SPIKE Pilot recovery directory (default: ~/.spike/recovery)
SPIKE_PILOT_RECOVERY_DIR=/custom/path/to/recovery

Fallback Chain

Use environment variable if set and valid
Fall back to ~/.spike (current default)
Fall back to /tmp/.spike-$USER if home directory unavailable

Validation Rules

The system will validate custom paths to ensure:

Path exists or can be created - Parent directory must exist
Proper permissions - Directory must have 0700 permissions
Write access - Process must be able to write to the directory
Restricted locations - Reject problematic paths:
- System directories: /, /etc, /sys, /proc, /dev
- Shared temp without user isolation: /tmp (without user suffix)
Warning for risky locations - Warn but allow:
- World-writable directories
- Network mounts (when detectable)

Implementation Example

func NexusDataFolder() string {
    // Check environment variable first
    if customDir := os.Getenv("SPIKE_NEXUS_DATA_DIR"); customDir != "" {
        if err := validateDataDirectory(customDir); err == nil {
            return filepath.Join(customDir, "data")
        }
        log.Warn("Invalid custom data directory, falling back to default",
            "dir", customDir, "err", err)
    }

    // Fall back to home directory
    homeDir, err := os.UserHomeDir()
    if err != nil {
        // Fall back to temp with user isolation
        return fmt.Sprintf("/tmp/.spike-%s/data", os.Getenv("USER"))
    }

    spikeDir := filepath.Join(homeDir, ".spike")
    os.MkdirAll(filepath.Join(spikeDir, "data"), 0700)
    return filepath.Join(spikeDir, "data")
}

Consequences

Positive

Container deployments - Mount persistent volumes at custom paths
Multi-instance support - Run multiple SPIKE instances with isolation
Compliance flexibility - Store data in specific locations for compliance
Testing isolation - Use temporary directories without affecting user data
Backward compatible - Existing deployments continue working unchanged
Security maintained - Validation ensures security properties are preserved

Negative

Configuration complexity - Additional environment variables to manage
Validation overhead - Path validation adds startup complexity
Support burden - More configurations to troubleshoot
Misconfiguration risk - Users might specify inappropriate paths

Neutral

Documentation updates - Need to document new configuration options

Migration Path

For Existing Users

No action required. The system continues to use ~/.spike by default.

For Users Wanting Custom Paths

Stop SPIKE components
Move existing data to new location:
```
mv ~/.spike/data /new/path/data
```
Set environment variable:
```
export SPIKE_NEXUS_DATA_DIR=/new/path
```
Restart SPIKE components

Security Considerations

Maintained Security Properties

Encryption - Data remains encrypted regardless of location
Permissions - Directory permissions enforced (0700)
Untrusted storage - Security model unchanged

Additional Safeguards

Path validation - Prevents use of system directories
Permission checks - Verifies proper access controls
Audit logging - Log custom directory usage for security monitoring

Implementation Notes

Update internal/config/config.go to implement path resolution logic
Add validation functions for directory security checks
Update CLAUDE.md and configuration.md with new environment variables
Add tests for path validation and fallback logic
Update necessary user-facing documentation