buildwithnexus Security

buildwithnexus implements comprehensive security controls to protect your development workflows. The CLI and backend use industry-standard encryption, authentication, and secure key management practices.

Security Architecture Overview

Defense in Depth Strategy

buildwithnexus employs multiple security layers:

Data Protection

Database Encryption at Rest

All buildwithnexus databases use SQLCipher with industry-standard encryption:

Key Features:

• AES-256-CBC: Industry-standard symmetric encryption
• PBKDF2: 256,000 iterations for strong key derivation
• Salted Keys: Unique salt per database prevents rainbow table attacks
• Per-Database Keys: Each database has its own encryption key

Database Coverage (7 encrypted SQLite databases):

All databases live under ~/.buildwithnexus/.

Key Management

Master Secret:

• Generated on first run using cryptographically secure random
• Stored in ~/.buildwithnexus/.env.keys
• Never transmitted to any service
• Unique per user/machine

Per-Database Keys:

• Derived from master secret using PBKDF2
• 256,000 iterations ensure strong key derivation
• Unique salt per database
• Automatically rotated on schema changes

Authentication & Authorization

JWT Token Security

buildwithnexus uses JWT tokens with advanced security features for API authentication:

Token Structure:

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user_id",
    "exp": 1640995200,
    "iat": 1638316800,
    "fingerprint": "sha256_hash_of_user_agent_and_ip"
  }
}

Security Features:

• Fingerprint binding: Tokens tied to client characteristics (user agent, IP)
• Expiry enforcement: Tokens automatically expire
• HMAC-256 signing: Prevents token tampering
• No refresh: New token generated on each CLI invocation

Client Fingerprinting

Fingerprints are computed from:

• User agent (CLI version, OS)
• Client IP address
• System hostname
• Timestamp

Security Benefits:

• Prevents token theft and reuse
• Detects session anomalies
• Invalidated if client characteristics change
• Regenerates on new CLI invocation

API Key Security

Storage:

• API keys stored in ~/.buildwithnexus/.env.keys
• File permissions set to 0600 (owner read/write only)
• Never logged or displayed in output
• Encrypted before storage in databases

Rotation:

• Run buildwithnexus da-init to rotate keys
• Old keys invalidated immediately
• No downtime during rotation

Network Security

TLS Encryption

All communication uses TLS 1.3:

• Perfect forward secrecy: Ephemeral key exchange
• HSTS enforcement: HTTP Strict Transport Security headers
• Certificate validation: Verifies server certificate on connection

Rate Limiting with Progressive Backoff

Failed authentication attempts trigger progressive delays:

Persistent tracking:

• Failed attempts logged with timestamp
• Survives CLI restarts
• Automatic cleanup after successful authentication
• IP-based tracking with subnet consideration

Server-Sent Events (SSE)

Real-time streaming for live event updates:

• Persistent connection: Maintains connection to backend
• Automatic reconnection: Recovers from network drops
• Event ordering: Guarantees event sequence
• Timeout handling: 30-second idle timeout with reconnect

Input Validation & Prevention

SQL Injection Prevention

• All database queries use parameterized statements
• User input validated before database operations
• Character encoding enforced

Process Isolation

• CLI runs in user's security context
• No privilege escalation
• No background processes
• Clean shutdown on exit

Security Best Practices

Secure Setup

1. Run buildwithnexus da-init on first launch
2. Store API keys in a password manager if sharing devices
3. Use separate CLI sessions for different projects
4. Rotate API keys periodically (monthly recommended)

During Use

• Never commit .env.keys to version control
• Don't share CLI sessions with untrusted users
• Clear history on shared machines: rm ~/.bash_history ~/.zsh_history
• Monitor ~/.buildwithnexus/logs/ for unusual activity

Maintenance

• Keep buildwithnexus updated: npm update -g buildwithnexus
• Review stored tasks and directives periodically
• Clear old data: buildwithnexus clean (if available)
• Use different API keys for different projects

Security Considerations

What buildwithnexus Protects

• API keys: Encrypted storage and transmission
• Conversation history: Stored encrypted locally
• Cost data: Tracks API usage securely
• Session state: Protects against hijacking

What You Must Protect

• Master secret (~/.buildwithnexus/.env.keys): Never share, back up securely
• GitHub tokens: If used for repo access, store in separate file
• SSH keys: If used for SSH tasks, keep passphrase-protected
• Sensitive data: Don't put secrets in task descriptions

Environment Setup

Recommended Configuration

# Set secure file permissions
chmod 700 ~/.buildwithnexus
chmod 600 ~/.buildwithnexus/.env.keys

# Optional: Use environment variables instead of file storage
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Run CLI
buildwithnexus

Integration with Secret Managers

For team environments, use your password manager:

1Password integration:

eval $(op signin)
export ANTHROPIC_API_KEY=$(op read op://vault/nexus/api-key)
buildwithnexus

Manual rotation:

# Update keys
buildwithnexus da-init

# Test connectivity
buildwithnexus da-status

Incident Response

If You Suspect Compromise

1. Run buildwithnexus da-init to rotate API keys
2. Review ~/.buildwithnexus/logs/ for suspicious activity
3. Check API provider (Anthropic, OpenAI) for unusual usage
4. Update to latest buildwithnexus version

If You Lose Your Master Secret

Encrypted databases cannot be recovered without the master secret. We recommend:

1. Back up ~/.buildwithnexus/ directory periodically
2. Store master secret securely (password manager)
3. On loss, delete ~/.buildwithnexus/ and reinitialize with buildwithnexus da-init

Compliance & Security Updates

Security Patches

• Critical vulnerabilities patched within 48 hours
• Security advisories posted on GitHub releases
• Automatic update notifications in CLI

Responsible Disclosure

If you discover a security vulnerability:

1. Do NOT open a public GitHub issue
2. Email security details to: [contact method TBD]
3. Allow 90 days for patch before disclosure
4. You will be credited in release notes if desired

Technical Architecture

CLI Security (TypeScript / Node.js)

• Runs in user's process context (no elevated privileges)
• No background daemons or services
• Clean shutdown with automatic resource cleanup
• Node.js built-in crypto for all encryption

Backend Security (Python FastAPI)

• Self-contained HTTP server on localhost:4200
• TLS 1.3 on all connections
• JWT middleware for route protection
• SQLite database with SQLCipher encryption

Data Flow

All data stays local on your machine. No data is transmitted to external services except:

• API requests to Anthropic Claude, OpenAI, or Google Gemini (your configured LLM provider)
• Git operations to your configured repository

Contact & Support

For security questions or responsible disclosure:

• GitHub Issues: Non-sensitive questions only
• Email: [contact method TBD]
• Security Policy: See SECURITY.md in repository