BizBox.WebApi.Template 1.2.0

🚀 BizBox WebAPI Template

Version 1.2.0 - Enterprise-grade .NET 8 Web API template with HIPAA-ready security features

📋 Table of Contents

• Overview
• Installation
• Quick Start
• Features
• Documentation
• Architecture
• Security
• Project Structure
• Development
• Deployment
• Version History
• Support & Contributing

---

🎯 Overview

BizBox is a production-ready .NET 8 Web API template built with Clean Architecture principles, featuring enterprise-grade security, HIPAA-compliant audit logging, and comprehensive authentication/authorization systems. Perfect for healthcare, finance, and high-security applications.

🌟 Key Highlights

• 🔐 Enterprise Security - Multi-layer defense with JWT, encrypted payloads, token blacklist
• 🏥 HIPAA-Ready Features - Comprehensive audit logging, encryption at transit, secure logout
• 🛡️ Advanced Protection - BOLA/IDOR prevention with ticket-based authorization
• 💬 Real-time Messaging - SignalR-powered WebSocket communication
• 🏗️ Clean Architecture - Maintainable, testable, scalable codebase
• 📊 Audit Trail - Automatic change tracking with old/new values, duration monitoring
• 🔄 Session Management - Configurable single/multi-device policies with proper logout
• 📧 Invitation System - Email-based user onboarding
• 🚀 Template Ready - Install from NuGet, customize, and deploy

📈 Current Status

Metric	Status	Notes
Overall Security	82% Complete	✅ 16/19 items implemented
HIPAA Compliance	50% Complete	🚧 Core features done, encryption pending
Production Ready	✅ Yes	Secure for non-PHI workloads
HIPAA PHI Ready	🚧 In Progress	Encryption at rest pending

---

📦 Installation (from NuGet)

Install the Template

dotnet new install BizBox.WebApi.Template

Create a New Project

# Create from template
dotnet new bizboxapi -n MyCompanyName.ProjectName

# Navigate to project
cd MyCompanyName.ProjectName

# Open in IDE
code .  # VS Code
# or
start MyCompanyName.ProjectName.sln  # Visual Studio

Verify Installation

dotnet new bizboxapi --help

---

🚀 Quick Start

1. Generate Secrets

# Windows
Generate-Secrets.bat

# Or PowerShell
.\Generate-Secrets.ps1

This will generate all required secrets and optionally save them to a .env file.

1. Database Setup

# Create PostgreSQL databases
createdb BizBox.Db           # Main database
createdb BizBox.AuditDb      # Audit database (HIPAA requirement)

2. Configure Secrets

cd MyProject.API

# Initialize User Secrets
dotnet user-secrets init

# Set required secrets
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;Port=5432;Username=postgres;Password=yourpassword;Database=BizBox.Db"
dotnet user-secrets set "ConnectionStrings:AuditDb" "Host=localhost;Port=5432;Username=postgres;Password=yourpassword;Database=BizBox.AuditDb"
dotnet user-secrets set "Jwt:Key" "your-super-secret-jwt-key-min-32-characters-long"
dotnet user-secrets set "Encryption:Key" "12345678901234567890123456789012"
dotnet user-secrets set "Encryption:IV" "1234567890123456"
dotnet user-secrets set "SuperAdmin:Email" "admin@yourdomain.com"
dotnet user-secrets set "SuperAdmin:Password" "SecurePassword123!"

2. Apply Migrations

# Main database
dotnet ef database update --context ApplicationDbContext

# Audit database
dotnet ef database update --context AuditDbContext

3. Run the Application

dotnet run --project BizBox.API

API: https://localhost:7264
Swagger: https://localhost:7264/swagger
SignalR Test: https://localhost:7264/signalr-test-client.html

📖 Need help? See docu/QUICK_START.md for detailed setup

---

✨ Features

🔐 Security Features (82% Complete)

✅ Implemented (16/19)

Authentication & Authorization:

• ✅ JWT Authentication with HS256/RS256 support
• ✅ Role-based authorization (Admin, SuperAdmin, Finance)
• ✅ Token versioning (concurrent session detection)
• ✅ Encrypted JWT payloads (AES-256)
• ✅ Ticket-based authorization (BOLA/IDOR protection)
• ✅ Password hashing (PBKDF2 with salt)
• ✅ Email confirmation
• ✅ Invitation-based registration
• ✅ Token Blacklist (NEW in v1.2.0 ✨)
  • Immediate token invalidation on logout
  • "Logout all devices" functionality
  • Database-backed with automatic cleanup
  • Background cleanup service (hourly)
  • Works across load-balanced servers
  • Proper logout that actually works!
• ✅ Account Lockout (v1.1)
  • Automatic lockout after 5 failed attempts
  • 15-minute lockout duration (configurable)
  • Admin unlock capability
  • Full audit trail integration

Audit & Monitoring:

• ✅ Comprehensive Audit Logging
  • Automatic change tracking for all entities
  • Old/new value capture
  • User and operation tracking
  • Duration and IP address logging
  • Separate audit database (HIPAA requirement)
• ✅ Structured logging with Serilog
• ✅ Security event tracking

API Protection:

• ✅ Rate limiting (AspNetCoreRateLimit)
  • Login: 5 attempts per 15 minutes
  • Registration: 3 per hour
  • General API: 100 per minute
• ✅ IP-based rate limiting
• ✅ Configurable per-endpoint limits
• ✅ IP whitelist support

Configuration Security:

• ✅ User Secrets (Development)
• ✅ Environment Variables (Production)
• ✅ Azure Key Vault ready
• ✅ Secrets generator tool
• ✅ Configurable Identity Settings
  • Lockout policy via appsettings.json
  • Password requirements configurable
  • Environment-specific overrides

Transport Security:

• ✅ HTTPS enforcement
• ✅ HSTS headers
• ✅ CORS configuration
• ✅ Secure WebSocket (SignalR)

Session Management:

• ✅ Single/Multiple/Limited session modes
• ✅ Multi-device tracking
• ✅ Logout current device (with blacklist)
• ✅ Logout all devices (with blacklist)
• ✅ Session info endpoint

🚧 In Progress (18%)

Priority 2 (P2):

• Two-Factor Authentication (2FA) - TOTP-based additional security layer
• Input Sanitization - Enhanced XSS protection with HtmlSanitizer
• Security Headers - CSP, X-Frame-Options, X-Content-Type-Options, HSTS

Priority 3 (P3):

• Encryption at Rest - Database field encryption (HIPAA critical)
• CSRF Protection - Anti-forgery tokens for state-changing operations

📊 Detailed Status: See docu/SECURITY_AUDIT.md

💬 Real-time Features (SignalR)

• ✅ Private messaging
• ✅ Group chat
• ✅ Online/offline status
• ✅ Multi-device support
• ✅ Typing indicators
• ✅ System notifications
• ✅ Auto-reconnection
• ✅ JWT authentication

🎯 Application Features

• ✅ User management (Identity framework)
• ✅ Email invitation system
• ✅ Global exception handling
• ✅ Input validation (FluentValidation)
• ✅ AutoMapper object mapping
• ✅ MediatR CQRS pattern
• ✅ Swagger/OpenAPI documentation
• ✅ API versioning
• ✅ Sample CRUD operations

---

📚 Documentation

🚀 Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Secrets Setup - Configure development secrets

🔐 Security

• Security Audit - Comprehensive security assessment
• Account Lockout Documentation - Account lockout feature guide
• Account Lockout Testing - Test procedures
• Identity Configuration Guide - Configure lockout & password policies

🗄️ Database & Audit

• Audit Database Setup - Configure separate audit database
• Audit Logging Guide - Use audit system

🎓 Learning

• Clean Architecture Guide - Deep dive into architecture patterns
• Security-First Development - Building secure code from the start

🐳 Deployment

• Docker Secrets Guide - Secure Docker deployment

---

🏗️ Architecture

BizBox follows Clean Architecture (Onion Architecture) with clear separation of concerns:

┌──────────────────────────────────────────────────┐
│           BizBox.API (Presentation)              │
│  ├─ Controllers (API Endpoints)                  │
│  ├─ Middleware (Authentication, rate limiting)   │
│  ├─ Hubs (SignalR)                              │
│  └─ Configurations (DI, services setup)         │
└───────────────────┬──────────────────────────────┘
                    │
┌───────────────────▼──────────────────────────────┐
│        BizBox.APPLICATION (Use Cases)            │
│  ├─ Commands (Write operations - CQRS)          │
│  ├─ Queries (Read operations - CQRS)            │
│  └─ Validators (FluentValidation)               │
└───────────────────┬──────────────────────────────┘
                    │
┌───────────────────▼──────────────────────────────┐
│           BizBox.DOMAIN (Entities)               │
│  ├─ Entities (Core business objects)            │
│  ├─ Value Objects                               │
│  └─ Domain Interfaces (Contracts)               │
└───────────────────┬──────────────────────────────┘
                    │
┌───────────────────▼──────────────────────────────┐
│      BizBox.PERSISTENCE (Data Access)            │
│  ├─ DbContext (EF Core contexts)                │
│  │   ├─ ApplicationDbContext (Main data)        │
│  │   └─ AuditDbContext (Audit logs)             │
│  ├─ Migrations (Database versions)              │
│  └─ Configurations (Entity configurations)      │
└───────────────────┬──────────────────────────────┘
                    │
┌───────────────────▼──────────────────────────────┐
│        BizBox.SERVICES (Infrastructure)          │
│  ├─ TokenBlacklistService (Token invalidation)  │
│  ├─ EmailService (SMTP integration)             │
│  ├─ EncryptionService (AES-256 crypto)          │
│  ├─ CurrentUserService (User context)           │
│  └─ AuditCaptureService (Audit logging)         │
└──────────────────────────────────────────────────┘

---

🔐 Security

Defense-in-Depth Architecture

Layer 1: Rate Limiting (DDoS protection)
         ↓
Layer 2: HTTPS/TLS (Transport encryption)
         ↓
Layer 3: JWT Authentication (Identity)
         ↓
Layer 4: Token Blacklist (Logout validation) ← NEW!
         ↓
Layer 5: Token Versioning (Session security)
         ↓
Layer 6: Role Authorization (Access control)
         ↓
Layer 7: Ticket Validation (BOLA protection)
         ↓
Layer 8: Input Validation (Data integrity)
         ↓
Layer 9: Audit Logging (Monitoring & compliance)

HIPAA Compliance Status

Requirement	Status	Implementation
Access Control	✅ Complete	Role-based, ticket validation, account lockout, token blacklist
Audit Controls	✅ Complete	Comprehensive audit logging (separate database)
Person/Entity Authentication	✅ Complete	JWT + email verification + lockout + proper logout
Transmission Security	✅ Complete	HTTPS/TLS, encrypted JWT payloads (AES-256)
Integrity Controls	🚧 Partial	Change tracking implemented, hash verification pending
Encryption at Rest	❌ Pending	Database field encryption (P3 - Critical for PHI)

Current Score: 50% HIPAA Compliant (16/32 requirements)

---

📁 Project Structure

BizBox.WebApi.Template/
│
├── BizBox.API/                          # 🌐 Presentation Layer
│   ├── Controllers/
│   │   ├── AuthController.cs            # Authentication (+ new logout endpoints)
│   │   ├── UserController.cs
│   │   └── AuditLogController.cs
│   └── Middleware/
│       ├── TokenBlacklistMiddleware.cs  # Token blacklist validation (NEW)
│       ├── TokenVersionValidationMiddleware.cs
│       └── TicketValidationMiddleware.cs
│
├── BizBox.APPLICATION/                  # 💼 Application Layer
│   └── Auth/
│       └── Commands/
│           ├── Logout.cs                # Logout command (NEW)
│           └── LogoutAllDevices.cs      # Logout all devices (NEW)
│
├── BizBox.DOMAIN/                       # 🎯 Domain Layer
│   ├── Entities/
│   │   ├── TokenBlacklist/
│   │   │   └── TokenBlacklist.cs        # Token blacklist entity (NEW)
│   │   └── User/
│   │       └── ApplicationUser.cs
│   └── Interfaces/
│       └── ITokenBlacklistService.cs    # Token blacklist contract (NEW)
│
├── BizBox.PERSISTENCE/                  # 🗄️ Persistence Layer
│   ├── Context/
│   │   ├── ApplicationDbContext.cs      # Main database (+ TokenBlacklist)
│   │   └── AuditDbContext.cs
│   ├── Migrations/
│   │   ├── *_TokenBlacklist.cs          # Token blacklist migration (NEW)
│   │   └── Audit/
│   └── Configurations/
│       └── TokenBlacklistConfiguration.cs # EF config (NEW)
│
└── BizBox.SERVICES/                     # ⚙️ Infrastructure Layer
    └── TokenBlacklistService/           # (NEW)
        ├── DatabaseTokenBlacklistService.cs
        └── TokenBlacklistCleanupService.cs

---

🛠️ Development

Running Locally

# Development mode with watch
dotnet watch --project BizBox.API

# Run without watch
dotnet run --project BizBox.API

Database Migrations

# Main Database
dotnet ef migrations add MigrationName \
  --project BizBox.PERSISTENCE \
  --startup-project BizBox.API \
  --context ApplicationDbContext

# Audit Database
dotnet ef migrations add MigrationName \
  --project BizBox.PERSISTENCE \
  --startup-project BizBox.API \
  --context AuditDbContext \
  --output-dir Migrations/Audit

# Apply Migrations
dotnet ef database update --context ApplicationDbContext
dotnet ef database update --context AuditDbContext

---

📊 Version History

🎉 Version 1.2.0 (Current - January 2025)

🚀 Major Feature: Token Blacklist

• ✅ Proper Logout Functionality
  • Immediate token invalidation on logout
  • "Logout all devices" with bulk token blacklisting
  • Database-backed blacklist (PostgreSQL)
  • Token blacklist middleware (validates on every request)
  • Background cleanup service (removes expired tokens hourly)
  • Configurable cleanup interval and batch size
  • Works across load-balanced servers
  • No more "JWT tokens can't be revoked" problem!

New Endpoints:

• POST /api/auth/logout-v2 - Logout from current device
• POST /api/auth/logout-all-devices - Logout from all devices

Database Changes:

• New TokenBlacklist table with performance indexes
• Automatic migration included
• Configurable via appsettings.json

Security & Compliance:

• ✅ Security Score: 78% → 82% (+4%)
• ✅ HIPAA Compliance: 45% → 50% (+5%)
• ✅ Items Complete: 15/19 → 16/19 security items

Documentation Added:

• Complete Token Blacklist architecture documentation
• Implementation guides and testing procedures
• Updated README with new features

📦 Version 1.1.0 (December 2024 - January 2025)

Major Features:

• ✅ Comprehensive Audit Logging System
• ✅ Account Lockout System (TESTED ✓)
• ✅ Configurable Identity Settings
• ✅ 12-Factor App Methodology (12/12 complete)

Security:

• Security Score: 60% → 78% (+18%)
• HIPAA Compliance: 30% → 45% (+15%)
• Items Complete: 13/19 → 15/19

📦 Version 1.0.0 (December 2024)

Initial Release:

• JWT authentication & authorization
• Rate limiting
• SignalR real-time messaging
• Session management
• Clean architecture foundation
• Published to NuGet

---

🗺️ Roadmap

✅ Version 1.2.0 (Current - January 2025)

• ✅ Token Blacklist implementation
• ✅ Proper logout functionality
• ✅ "Logout all devices" support
• ✅ Background cleanup service
• ✅ 82% security completion
• ✅ 50% HIPAA compliance

👉 Version 1.3.0 (Q1 2025) - Next Up

Priority 2 (P2) - High Security:

• Two-Factor Authentication (2FA) (1-2 weeks)
  • TOTP-based implementation
  • QR code generation
  • Backup codes
• Input Sanitization (1 week)
  • HtmlSanitizer integration
  • XSS protection
  • Content Security Policy headers
• Security Headers (2-3 days)
  • CSP, X-Frame-Options, X-Content-Type-Options
  • HSTS configuration

Expected Metrics:

• Security Score: 82% → 90%
• HIPAA Compliance: 50% → 70%
• Items Complete: 16/19 → 18/19

📋 Version 2.0 (Q2-Q3 2025)

• Encryption at rest (field-level)
• Full HIPAA compliance (95%+)
• OAuth/OIDC integration
• Advanced monitoring dashboard
• SOC 2 compliance ready

---

🤝 Support & Contributing

Getting Help

• 📖 Documentation: docu/ folder
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Follow our coding standards
4. Write/update tests
5. Update documentation
6. Submit a pull request

---

📄 License

This project is licensed under the MIT License.

---

<div align="center">

Made with ❤️ and 🔐 by the BizBox Team

⭐ Star us on GitHub if this template helps your project!

🛡️ Security First. HIPAA Ready. Production Proven.

v1.2.0 - Now with Proper Logout! 🎉

</div>