Corteq Framework

Enterprise-Grade Multi-Tenant SaaS Framework for Rust

Corteq is a security-first, production-ready framework for building multi-tenant SaaS applications in Rust. Built on Actix Web, it provides comprehensive tenant isolation, authentication, encryption, and compliance features out of the box.

🚀 Features

🔒 Security First

• Row-Level Security (RLS): Automatic tenant data isolation at the PostgreSQL level
• AES-256-GCM Encryption: Data at rest encryption with tenant-specific keys
• JWT Authentication: Bearer token & HTTP cookie support
• Defense in Depth: Multiple layers of security (middleware + database)

🏢 Multi-Tenant Architecture

• Zero Cross-Tenant Leakage: Database-level isolation with compile-time safety
• Per-Tenant Encryption: Each tenant has unique encryption keys
• Tenant Context: Automatic tenant identification from JWT claims
• Efficient Caching: In-memory tenant data caching

🛡️ Compliance Ready

• GDPR: Data isolation, encryption, audit trails
• HIPAA: PHI protection with encryption at rest
• SOC 2: Security controls and audit logging patterns

⚡ Production Ready

• 64+ Tests: Comprehensive test coverage including security tests
• Type Safety: Compile-time guarantees prevent common mistakes
• Performance: Efficient connection pooling and caching
• Observability: Built-in tracing and logging support

📦 Quick Start

[dependencies]
corteq = "0.1"
actix-web = "4.9"
tokio = { version = "1", features = ["full"] }

use actix_web::{web, App, HttpServer};
use corteq::CorteqApp;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let app_config = CorteqApp::builder()
        .with_database("postgres://user:pass@localhost/db")
        .with_jwt_secret("your-secret-key-min-32-chars!!")
        .build()
        .await?;

    HttpServer::new(move || {
        App::new()
            .app_data(web::Data::new(app_config.clone()))
            .service(
                web::scope("/api")
                    .wrap(corteq::TenantContextMiddleware)
                    .route("/data", web::get().to(get_tenant_data))
            )
    })
    .bind("0.0.0.0:8080")?
    .run()
    .await
}

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     HTTP Request                        │
│         Authorization: Bearer <jwt_token>               │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│           TenantContextMiddleware                        │
│  • Extracts JWT from Bearer token or Cookie             │
│  • Validates signature and expiration                   │
│  • Loads tenant context from cache/database             │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  Handler Function                        │
│              (tenant: TenantExtractor)                   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  TenantDatabase                          │
│  • Begins transaction                                    │
│  • Sets app.current_tenant_id session variable          │
│  • RLS policies automatically filter queries            │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│            PostgreSQL with RLS Enabled                   │
│  • Row-Level Security enforces tenant isolation         │
│  • Only returns rows matching current_tenant_id         │
│  • Blocks INSERT/UPDATE/DELETE for other tenants        │
└─────────────────────────────────────────────────────────┘

🔐 Security Features

Tenant Isolation (RLS)

// Automatically filtered by tenant_id
let mut db = TenantDatabase::begin(&pool, &tenant_ctx).await?;
let docs = sqlx::query!("SELECT * FROM documents")
    .fetch_all(db.connection())
    .await?;
// ✅ Only returns documents for current tenant

JWT Authentication

// Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// HTTP Cookie (automatically handled)
Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Data Encryption

let encryption = EncryptionService::new();

// Encrypt with tenant-specific key
let encrypted = encryption.encrypt(plaintext, &tenant_ctx)?;
let bytes = encrypted.to_bytes(); // Store in database

// Decrypt
let decrypted = encryption.decrypt(&encrypted, &tenant_ctx)?;

📁 Project Structure

.
corteq/                    # Framework library crate
├── src/
│   ├── lib.rs            # Main library exports
│   ├── auth.rs           # JWT authentication
│   ├── cache.rs          # Tenant caching layer
│   ├── database/         # RLS database wrapper
│   ├── domain.rs         # Tenant, TenantContext models
│   ├── encryption.rs     # AES-256-GCM encryption
│   ├── error.rs          # Framework error types
│   ├── middleware.rs     # Tenant context middleware
│   └── repository/       # Tenant repository
└── tests/                # Integration & security tests

📚 Documentation

• API Documentation - Rust API docs (run cargo doc --open)

🧪 Running Tests

# All tests
cargo test

# Specific test suite
cargo test --test test_encryption
cargo test --test test_security_critical
cargo test --test test_rls_isolation

# With output
cargo test -- --nocapture

# Integration tests only
cargo test --test '*'

🔨 Development Setup

# 1. Clone repository
git clone https://github.com/Trendium-Labs/corteq
cd corteq

# 2. Start PostgreSQL
docker-compose up -d postgres

# 3. Run migrations (automatic on first run)
# Migrations run automatically when CorteqApp::builder().build() is called

# 4. Run demo app
cargo run --bin server

# 5. Test the API
curl http://localhost:3000/health

# Generate demo token
curl -X POST http://localhost:3000/auth/demo-token \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "11111111-1111-1111-1111-111111111111"}'

# Use token
curl -H "Authorization: Bearer <token>" \
  http://localhost:3000/api/me

🎯 Use Cases

Perfect for building:

• 🏢 B2B SaaS platforms
• 💼 Enterprise applications
• 🏥 Healthcare systems (HIPAA compliant)
• 💰 Financial services (SOC 2 ready)
• 📊 Analytics platforms
• 🎓 EdTech applications

🚦 Development Status

✅ Completed Phases (1-5)

Phase 1: Foundation

• Cargo workspace setup (corteq + demo-app)
• Core dependencies configured
• Module structure created
• PostgreSQL Docker Compose setup
• Test infrastructure configured
• Switched to Actix Web

Phase 2: Authentication & Middleware

• JWT token encoding/decoding with tenant claims
• Bearer token authentication
• HTTP cookie authentication
• Tenant context middleware
• Tenant caching layer (in-memory)
• Tenant repository for database access
• Demo app with protected routes

Phase 3: Row-Level Security

• PostgreSQL RLS migrations
• TenantDatabase wrapper with automatic context setting
• Comprehensive RLS isolation tests (9 tests)
• Non-superuser role for proper RLS testing
• Cross-tenant access blocking verified

Phase 4: Security Testing

• SQL injection prevention tests
• Malformed UUID handling tests
• JWT token manipulation tests
• Cache poisoning prevention tests
• Concurrent transaction isolation tests
• Session variable isolation tests
• Tampering detection tests

Phase 5: Encryption

• AES-256-GCM encryption service
• Tenant-specific key derivation
• EncryptedData serialization for database storage
• Nonce uniqueness verification
• 11 comprehensive encryption tests
• Cross-tenant encryption isolation

📋 Upcoming Phases

• Phase 6: RBAC authorization system
• Phase 7: Audit logging framework
• Phase 8: Rate limiting & throttling
• Phase 9: Performance optimization
• Phase 10: Documentation & examples

🏢 Production Deployment

Docker

FROM rust:1.75 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/app /usr/local/bin/
EXPOSE 8080
CMD ["app"]

Environment Variables

DATABASE_URL=postgres://user:pass@host:5432/db
JWT_SECRET=your-production-secret-key-min-32-chars!!
RUST_LOG=info
SERVER_PORT=8080

🤝 Contributing

This project is currently in active development. Contributions, issues, and feature requests are welcome!

📄 License

Licensed under MIT License (LICENSE-MIT)

🙏 Acknowledgments

Built with these amazing technologies:

• Actix Web - Fast, pragmatic web framework
• SQLx - Async SQL toolkit
• PostgreSQL - Advanced open source database
• jsonwebtoken - JWT implementation
• aes-gcm - Authenticated encryption

Built with ❤️ by Trendium Labs

⭐ Star this repo if you find it useful!