Security Model

Last Updated: May 19, 2025

This document describes the security architecture of the Typus Development Framework, outlining the components, patterns, and practices that ensure the security of applications built with the framework.

Security Architecture Overview

The Typus Development Framework implements a multi-layered security architecture that protects applications at various levels:

Authentication System

The authentication system verifies the identity of users and services accessing the application.

Authentication Components

Authentication Flow

JWT Token Structure

The framework uses JWT (JSON Web Tokens) for authentication with the following structure:

Access Token Payload:

{
  "sub": "user_id",
  "name": "username",
  "email": "[email protected]",
  "roles": ["user", "admin"],
  "permissions": ["read:users", "write:users"],
  "iat": 1619712000,
  "exp": 1619715600,
  "iss": "typus-auth"
}

Refresh Token Payload:

{
  "sub": "user_id",
  "jti": "unique_token_id",
  "iat": 1619712000,
  "exp": 1620316800,
  "iss": "typus-auth"
}

Multi-factor Authentication

The framework supports multiple MFA methods:

1. Time-based One-Time Password (TOTP): Compatible with authenticator apps
2. Email Verification: One-time codes sent via email
3. SMS Verification: One-time codes sent via SMS (optional)

Authorization System

The authorization system controls access to resources and operations based on user roles and permissions.

Role-Based Access Control (RBAC)

Authorization Flow

Permission Enforcement

The framework enforces permissions at multiple levels:

1. Route Level: Using middleware to protect API endpoints
2. Controller Level: Using decorators to protect controller methods
3. Service Level: Using programmatic checks in service methods
4. UI Level: Conditionally rendering UI elements based on permissions

Data Protection

The framework implements multiple layers of data protection to secure sensitive information.

Data Encryption

Sensitive Data Handling

The framework provides utilities for handling sensitive data:

1. Password Hashing: Using bcrypt with appropriate work factors
2. PII Encryption: Encrypting personally identifiable information
3. Secure Configuration: Protecting secrets and credentials
4. Data Masking: Masking sensitive data in logs and responses

API Security

The framework implements multiple measures to secure API endpoints.

API Security Components

API Security Measures

1. Rate Limiting: Prevents abuse by limiting request frequency
2. CORS Configuration: Controls cross-origin resource sharing
3. Content Security Policy: Prevents XSS and data injection attacks
4. Input Validation: Validates and sanitizes all input data
5. CSRF Protection: Prevents cross-site request forgery attacks

Security Monitoring and Auditing

The framework includes comprehensive monitoring and auditing capabilities.

Security Monitoring Components

Audit Logging

The framework logs security-relevant events with the following information:

1. Who: User identifier
2. What: Action performed
3. When: Timestamp
4. Where: Source (IP, device)
5. How: Method used
6. Status: Success or failure
7. Target: Resource affected

Secure Development Practices

The framework promotes secure development practices through its architecture and tooling.

Security by Design

Security Testing

The framework includes tools and patterns for security testing:

1. Static Analysis: Identifying security issues in code
2. Dependency Scanning: Checking for vulnerable dependencies
3. Security Unit Tests: Testing security controls
4. Penetration Testing: Identifying vulnerabilities in running applications

Vulnerability Protection

The framework includes protections against common vulnerabilities.

OWASP Top 10 Protections

Security Configuration

The framework provides flexible security configuration options while maintaining secure defaults.

Configuration Areas

1. Authentication: Configure authentication providers, token lifetimes, MFA settings
2. Authorization: Define roles, permissions, and access control rules
3. Encryption: Configure encryption algorithms, key management
4. API Security: Configure rate limiting, CORS, CSP
5. Logging: Configure audit logging, log storage, retention

Example Security Configuration

// Security configuration example
export const securityConfig = {
  authentication: {
    jwtSecret: process.env.JWT_SECRET,
    accessTokenExpiry: '15m',
    refreshTokenExpiry: '7d',
    mfa: {
      enabled: true,
      methods: ['totp', 'email']
    },
    oauth: {
      google: {
        enabled: true,
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET
      },
      github: {
        enabled: true,
        clientId: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET
      }
    }
  },
  authorization: {
    defaultRole: 'user',
    superAdminRole: 'superadmin',
    rbacEnabled: true
  },
  encryption: {
    algorithm: 'aes-256-gcm',
    keyRotationDays: 90
  },
  api: {
    rateLimit: {
      windowMs: 15 * 60 * 1000, // 15 minutes
      max: 100 // limit each IP to 100 requests per windowMs
    },
    cors: {
      origin: process.env.ALLOWED_ORIGINS.split(','),
      methods: ['GET', 'POST', 'PUT', 'DELETE'],
      allowedHeaders: ['Content-Type', 'Authorization']
    }
  },
  logging: {
    audit: {
      enabled: true,
      sensitiveFields: ['password', 'creditCard', 'ssn']
    }
  }
};

Security Best Practices

The framework documentation includes security best practices for developers:

1. Authentication: Implement MFA, secure password policies, proper token handling
2. Authorization: Follow principle of least privilege, implement proper access controls
3. Data Protection: Encrypt sensitive data, implement proper data handling
4. API Security: Validate all inputs, implement rate limiting, use proper error handling
5. Secure Coding: Follow secure coding guidelines, avoid common vulnerabilities
6. Deployment: Use secure deployment practices, implement proper security controls
7. Monitoring: Implement comprehensive logging and monitoring

Conclusion

The security architecture of the Typus Development Framework provides a comprehensive approach to application security. By implementing multiple layers of security controls, the framework helps developers build secure applications by default while providing flexibility for specific security requirements.

The security model follows industry best practices and addresses common security concerns, including authentication, authorization, data protection, and vulnerability prevention. The framework's security components work together to provide a robust security posture for applications built with the framework.