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:

┌─────────────────────────────────────────────────────────────────┐
│                    Network Security                              │
├─────────────────────────────────────────────────────────────────┤
│  • TLS 1.3 Encryption for All Communications                   │
│  • Rate Limiting with Progressive Exponential Backoff          │
│  • Server-Sent Events (SSE) for Real-Time Streaming            │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│                  Authentication & Authorization                  │
├─────────────────────────────────────────────────────────────────┤
│  • JWT Tokens with Client Fingerprint Binding                  │
│  • Secure API Key Storage in ~/.buildwithnexus/.env.keys       │
│  • Session Management with Automatic Expiry                    │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│                     Application Security                         │
├─────────────────────────────────────────────────────────────────┤
│  • Input Validation and Sanitization                          │
│  • SQL Injection Prevention                                   │
│  • Process Isolation (CLI runs in user context)               │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│                       Data Protection                            │
├─────────────────────────────────────────────────────────────────┤
│  • AES-256-CBC Encryption at Rest (SQLCipher)                 │
│  • PBKDF2 Key Derivation (256,000 iterations)                 │
│  • Per-Database Encryption Keys                               │
│  • Automatic Cleanup on Session End                           │
└─────────────────────────────────────────────────────────────────┘

Data Protection

Database Encryption at Rest

All buildwithnexus databases use SQLCipher with military-grade encryption:

Encryption Scheme: AES-256-CBC
KDF Algorithm: PBKDF2
KDF Iterations: 256,000
Key Derivation: Per-database salted HMAC
WAL Mode: Enabled for durability

Key Features:

  • AES-256-CBC: Military-grade encryption algorithm
  • 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:

~/.buildwithnexus/
├── state.db         (Encrypted: CLI state, directives, tasks)
├── cost.db          (Encrypted: API usage tracking)
├── knowledge.db     (Encrypted: RAG knowledge chunks)
└── sessions.db      (Encrypted: Session information)

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: Algorithm prevents token tampering
  • No Token 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:

Attempts 1-3:   30 seconds delay
Attempts 4-6:   2 minutes delay
Attempts 7-9:   15 minutes delay
Attempts 10+:   1 hour lockout

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 (if available):

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

Manual Rotation:

# Update keys via init
buildwithnexus da-init

# Test connectivity
buildwithnexus run "echo test"

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

Unfortunately, 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 (Node.js HTTP API)

  • 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

User Input (CLI)
    ↓
[TLS 1.3 Encrypted]
    ↓
Node.js Backend (localhost:4200)
    ↓
[Parameterized Queries]
    ↓
SQLite + SQLCipher (AES-256-CBC)
    ↓
Encrypted at Rest

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