ClusterKit is a coordination library designed for trusted network environments. It does not include built-in security features like TLS encryption or authentication. This document outlines security considerations and best practices for production deployments.

Current State: ClusterKit does not provide built-in TLS encryption for inter-node communication.

Recommendations:

1. Deploy in Trusted Networks

   • Use private networks (VPC, private subnets)
   • Isolate cluster nodes from public internet
   • Use cloud provider security groups/firewall rules

2. TLS Termination via Reverse Proxy

   Client → TLS → Nginx/Envoy → ClusterKit Node
   

   • Use nginx, Envoy, or HAProxy for TLS termination
   • Terminate TLS at the edge, plain HTTP internally
   • Example nginx config:

     server {
         listen 443 ssl;
         ssl_certificate /path/to/cert.pem;
         ssl_certificate_key /path/to/key.pem;
         
         location / {
             proxy_pass http://localhost:8080;
         }
     }

3. VPN/WireGuard for Inter-Node Communication

   • Use WireGuard or IPsec for encrypted tunnels between nodes
   • Transparent to ClusterKit
   • Provides network-level encryption

Current State: ClusterKit does not provide built-in authentication or authorization.

Recommendations:

Implement authentication in your application layer:

// Your application wrapper
func (app *App) Set(key, value string, authToken string) error {
    // Verify auth token
    if !app.auth.Verify(authToken) {
        return errors.New("unauthorized")
    }
    
    // Use ClusterKit
    return app.ck.SetCustomData(key, []byte(value))
}

Use client certificates for node authentication:

// Configure HTTP client with client cert
tlsConfig := &tls.Config{
    Certificates: []tls.Certificate{clientCert},
    RootCAs:      caCertPool,
}
client := &http.Client{
    Transport: &http.Transport{
        TLSClientConfig: tlsConfig,
    },
}

Place an API gateway (Kong, Tyk) in front of ClusterKit:

• Handles authentication (JWT, OAuth, API keys)
• Rate limiting
• Request validation

Important: Custom data is stored unencrypted in Raft logs and snapshots.

Recommendations:

1. Encrypt Sensitive Data Before Storing

   // Encrypt before storing
   encrypted := encrypt(sensitiveData, encryptionKey)
   ck.SetCustomData("user:123", encrypted)
   
   // Decrypt after retrieving
   encrypted, _ := ck.GetCustomData("user:123")
   decrypted := decrypt(encrypted, encryptionKey)

2. Use Key Management Service (KMS)

   • AWS KMS, Google Cloud KMS, HashiCorp Vault
   • Rotate encryption keys regularly
   • Never hardcode encryption keys

3. Avoid Storing Secrets

   • Don't store passwords, API keys, or tokens in custom data
   • Use dedicated secret management systems

• Raft logs contain all cluster state changes
• Logs are stored on disk unencrypted
• Recommendation: Use encrypted filesystems (LUKS, dm-crypt)

1. Firewall Rules

   # Only allow cluster nodes to communicate
   iptables -A INPUT -p tcp --dport 8080 -s 10.0.1.0/24 -j ACCEPT
   iptables -A INPUT -p tcp --dport 8080 -j DROP

2. Security Groups (AWS/GCP/Azure)

   • Restrict inbound traffic to cluster CIDR
   • Only allow necessary ports (HTTP, Raft)

3. Network Policies (Kubernetes)

   apiVersion: networking.k8s.io/v1
   kind: NetworkPolicy
   metadata:
     name: clusterkit-policy
   spec:
     podSelector:
       matchLabels:
         app: clusterkit
     ingress:
     - from:
       - podSelector:
           matchLabels:
             app: clusterkit

• Run ClusterKit processes with minimal permissions
• Use dedicated service accounts
• Avoid running as root

// Log all custom data operations
ck.OnCustomDataChange(func(key string, operation string) {
    auditLog.Info("custom data operation",
        "key", key,
        "operation", operation,
        "user", getCurrentUser(),
        "timestamp", time.Now())
})

• Keep Go runtime updated
• Update dependencies regularly:

  go get -u ./...
  go mod tidy

• Monitor for security advisories

// Validate all inputs
func validateKey(key string) error {
    if len(key) > 256 {
        return errors.New("key too long")
    }
    if !isAlphanumeric(key) {
        return errors.New("key contains invalid characters")
    }
    return nil
}

Implement rate limiting to prevent abuse:

// Use golang.org/x/time/rate
limiter := rate.NewLimiter(rate.Limit(100), 200) // 100 req/s, burst 200

func (app *App) Set(key, value string) error {
    if !limiter.Allow() {
        return errors.New("rate limit exceeded")
    }
    return app.ck.SetCustomData(key, []byte(value))
}

• Deploy in private network/VPC
• Configure firewall rules
• Set up TLS termination (if needed)
• Implement authentication layer
• Encrypt sensitive data before storing
• Set up monitoring and alerting
• Review and minimize permissions

• Enable audit logging
• Set up automated backups
• Configure rate limiting
• Implement health checks
• Set up incident response procedures
• Document security architecture
• Conduct security review

✅ Split-brain scenarios - Raft consensus prevents
✅ Data inconsistency - Raft log replication ensures consistency
✅ Node failures - Automatic health checking and rebalancing

❌ Network eavesdropping - Use TLS/VPN
❌ Unauthorized access - Implement authentication
❌ Data at rest - Encrypt filesystems
❌ DDoS attacks - Use rate limiting and firewalls
❌ Insider threats - Use audit logging and access controls

• Encrypt personal data before storing
• Implement data retention policies
• Provide data deletion capabilities
• Log all data access for audit trails

• Document security controls
• Implement access logging
• Regular security assessments
• Incident response procedures

For security-related questions or to report vulnerabilities:

1. Do not open public GitHub issues for security vulnerabilities
2. Email security concerns to: [your-security-email]
3. Use encrypted communication when possible

ClusterKit is designed for trusted network environments. For production deployments:

1. ✅ Use private networks
2. ✅ Implement TLS via reverse proxy
3. ✅ Add authentication at application layer
4. ✅ Encrypt sensitive data before storing
5. ✅ Use firewall rules and security groups
6. ✅ Enable monitoring and audit logging
7. ✅ Follow principle of least privilege

Remember: Security is a shared responsibility. ClusterKit provides the coordination layer; you provide the security layer.