# Security Boundaries and Threat Model

This document covers repo-specific security boundaries. See the [BTCDecoded Security Policy](https://github.com/BTCDecoded/.github/blob/main/SECURITY.md) for organization-wide policy.

## Overview

This document defines the security boundaries, threat model, and limitations of the BTCDecoded blvm-node implementation. This is critical for understanding what this node can and cannot do safely.

**Operators:** deployment exposure classes (RPC / P2P / modules) and **required vs recommended vs unsupported** combinations are summarized in the BLVM book — **[Deployment posture](https://docs.thebitcoincommons.org/security/deployment-posture.html)** — and in **[RPC transport × authentication](https://docs.thebitcoincommons.org/security/rpc-transport-auth-matrix.html)**.

## Security Boundaries

### What blvm-node Handles

- Consensus validation (delegated to blvm-consensus via blvm-protocol)
- Network protocol (P2P message parsing, peer management)
- Storage layer (block storage, UTXO set, chain state)
- RPC interface (JSON-RPC 2.0 API)
- Module orchestration (loading, IPC, lifecycle management)
- Mempool management
- Mining coordination

### What blvm-node NEVER Handles

- Consensus rule validation (delegated to blvm-consensus)
- Protocol variant selection (delegated to blvm-protocol)
- Private key management (no wallet functionality)
- Cryptographic key generation (delegated to blvm-sdk or modules)
- Governance enforcement (delegated to blvm-commons)

## Security Boundaries (Detailed)

### ✅ IN SCOPE - What This Node Handles

1. **Consensus Validation**
   - Block validation using blvm-consensus
   - Transaction validation and script execution
   - Proof of work verification
   - Economic rule enforcement (supply limits, fees)

2. **Network Protocol**
   - Bitcoin P2P protocol message parsing
   - Peer connection management
   - Block and transaction relay
   - Network message validation

3. **Storage Layer**
   - Block storage and indexing
   - UTXO set management
   - Chain state tracking
   - Transaction indexing

4. **RPC Interface**
   - JSON-RPC 2.0 compliant API
   - Blockchain data queries
   - Network status reporting
   - Mining coordination

### ❌ OUT OF SCOPE - What This Node NEVER Handles

1. **Private Key Management**
   - NO private key storage
   - NO private key generation
   - NO wallet functionality
   - NO signing operations

2. **Wallet Operations**
   - NO address generation
   - NO transaction creation
   - NO UTXO selection
   - NO change calculation

3. **Mining Operations**
   - NO actual mining (proof of work)
   - NO block template generation
   - NO nonce searching
   - NO mining pool coordination

## Threat Model

### Current Deployment (Pre-Production Testing)

**Environment**: Trusted network only
**Timeline**: 6-12 months testing phase
**Threats**: Limited to development and testing scenarios

#### Threats NOT Applicable (Trusted Network)
- Eclipse attacks
- Sybil attacks
- Network partitioning attacks
- Malicious peer injection

#### Threats That Apply
- **Code vulnerabilities** in consensus validation
- **Memory corruption** in parsing
- **Integer overflow** in calculations
- **Resource exhaustion** (DoS)
- **Supply chain attacks** on dependencies

### Future Mainnet Deployment

**Environment**: Public Bitcoin network
**Timeline**: After security audit and hardening
**Threats**: Full Bitcoin network threat model

#### Additional Threats for Mainnet
- **Eclipse attacks** — malicious peers isolate node
- **Sybil attacks** — fake peer identities
- **Network partitioning** — routing attacks
- **Resource exhaustion** — memory/CPU DoS
- **Protocol manipulation** — malformed messages

## Security Limitations

### Current Implementation Limitations

1. **Storage Layer**
   - ✅ **RocksDB** is included in default features (performance path for mainnet-scale IBD)
   - ✅ **redb** available as `--features redb` (pure Rust; no default C++ `rocksdb`)
   - ⚠️ `sled` available behind `--features sled` (not recommended for production mainnet)
   - ✅ Database abstraction allows switching backends (`database_backend` config)
   - ⚠️ No advanced indexing (sufficient for current use case)

2. **Network Layer**
   - ✅ Peer management implemented
   - ✅ Rate limiting implemented (token bucket, per-IP connection limits)
   - ✅ DoS protection implemented (connection rate limiting, message queue limits, auto-ban, resource monitoring)

3. **RPC Interface**
   - ✅ Authentication implemented (token-based and certificate-based, configurable)
   - ✅ Rate limiting implemented (per-user, per-IP when auth disabled, batch-aware)
   - ✅ IP rate limiting when auth disabled (rate-limit-only mode)
   - ✅ Quinn RPC auth and rate limiting (same model as HTTP RPC)
   - ✅ Batch RPC rate limiting (consumes min(batch_len, 10) tokens)
   - ✅ Connection rate limiting (per-IP per minute for RPC and REST)
   - ✅ REST vault/pool/congestion: oversized body returns 413
   - ✅ Input validation and sanitization
   - ✅ Access control via authentication
   - ⚠️ **Certificate auth (S-001)**: When using certificate-based RPC auth, the RPC endpoint **must** be behind TLS termination (e.g. nginx, Caddy) that sets the `x-client-cert-fingerprint` header from the validated client certificate. Without this, the header is spoofable—any client can forge it. If RPC is not behind such TLS, use token-based auth only or disable cert auth.

4. **Consensus Layer**
   - Signature verification now uses real transaction hashes ✅
   - All consensus-critical dependencies pinned ✅
   - Proper Bitcoin hashing implemented ✅
   - Network protocol validation added ✅

### Security Hardening Roadmap

#### Phase 1: Pre-Production (Current)
- [x] Fix signature verification with real transaction hashes
- [x] Implement proper Bitcoin double SHA256 hashing
- [x] Pin all dependencies to exact versions
- [x] Add network protocol input validation
- [ ] Add storage bounds checking
- [ ] Add comprehensive test vectors

#### Phase 2: Production Readiness
- [x] Add redb as optional pure-Rust storage backend; RocksDB remains default feature set for performance
- [x] Add DoS protection mechanisms (connection rate limiting, auto-ban, resource monitoring)
- [x] Add RPC authentication (token-based and certificate-based)
- [x] Implement rate limiting (per-user RPC rate limiting, network message rate limiting)
- [x] Add comprehensive fuzzing (protocol parsing, compact blocks, enhanced edge cases)
- [x] Add eclipse attack prevention (IP diversity tracking, limits connections from same IP range)
- [x] Add storage bounds checking (prevents overflow, warns when approaching limits)

#### Phase 2.5: RPC Security Hardening (Complete)
- [x] Rate limiting when auth disabled
- [x] Quinn RPC auth and rate limiting
- [x] Batch RPC rate limiting
- [x] RPC connection rate limiting
- [x] REST vault/pool/congestion error handling (413 for oversized body)

#### Phase 3: Mainnet Hardening
- [ ] Professional security audit (external, requires security firm)
- [x] Formal verification of critical paths (property tests for node invariants added)
- [x] Advanced peer management (connection quality tracking, peer selection, reliability scoring)
- [x] Performance optimization (performance profiler infrastructure added)
- [x] Monitoring and alerting (metrics collection, health checks, RPC endpoints)

## Usage Guidelines

### Safe Usage Patterns

1. **Validation Only**
   - Use for block and transaction validation
   - Query blockchain state
   - Monitor network health
   - Educational purposes

2. **Development and Testing**
   - Integration testing
   - Consensus rule validation
   - Protocol development
   - Research and analysis

### Unsafe Usage Patterns

1. **Never Use For**
   - Storing private keys
   - Creating transactions
   - Mining operations
   - Production mainnet without hardening

2. **Security Warnings**
   - **Never expose RPC to untrusted/public networks** without authentication. The node warns at startup when bound to a non-loopback address without auth (`rpc_auth.required = false`); heed the warning.
   - Do not use for financial operations
   - Do not rely on for consensus without audit
   - Do not use sled storage for production

## Dependencies Security

### Consensus-Critical Dependencies (Exact Versions)
- `secp256k1 = "=0.28.2"` - ECDSA cryptography
- `sha2 = "=0.10.9"` - SHA256 hashing
- `ripemd = "=0.1.3"` - RIPEMD160 hashing
- `bitcoin_hashes = "=0.11.0"` - Bitcoin-specific hashing

### Non-Consensus Dependencies (Exact Versions)
- `serde = "=1.0.193"` - Serialization
- `anyhow = "=1.0.93"` - Error handling
- `thiserror = "=1.0.69"` - Error types

## Reporting Security Issues

### Responsible Disclosure

If you discover a security vulnerability:

1. **DO NOT** create public issues
2. **DO NOT** discuss publicly
3. **DO** report privately to: security@thebitcoincommons.org
4. **DO** provide detailed reproduction steps
5. **DO** allow reasonable time for fixes

### Security Response Process

1. **Acknowledgment** within 48 hours
2. **Assessment** within 7 days
3. **Fix development** within 30 days
4. **Public disclosure** after fix deployment

## Compliance and Standards

### Bitcoin Protocol Compliance
- Implements Bitcoin consensus rules
- Interoperates with common chain data and RPC conventions where implemented
- Follows BIP specifications
- Maintains protocol compatibility

### Security Standards
- Follows Rust security best practices
- Implements defense in depth
- Uses secure coding patterns
- Maintains audit trail

## Conclusion

This blvm-node implementation provides a solid foundation for Bitcoin consensus validation but is **NOT suitable for production mainnet use** without significant hardening. It is designed for:

- **Educational purposes**
- **Development and testing**
- **Consensus rule validation**
- **Research and analysis**

For production use, additional security hardening, professional audit, and mainnet-specific protections are required.

---

**Last Updated**: April 2026  
**Version**: 0.1.0  
**Status**: Pre-Production Testing
