Disciplines · Reference

Security Policy

If you discover a security vulnerability in the Oshun platform, please report it responsibly.

12sections8 minread
Markdown source
On this page

This document describes the security practices, policies, and architecture of the Oshun platform.

Table of Contents#

Reporting Vulnerabilities#

If you discover a security vulnerability in the Oshun platform, please report it responsibly.

How to Report#

  1. Do NOT open a public issue. Security vulnerabilities should never be disclosed publicly before they are addressed.

  2. Email the security team with the following details:

    • Description of the vulnerability
    • Steps to reproduce
    • Affected components (domain, library, service)
    • Potential impact assessment
    • Any suggested mitigation

  3. Expected response times:

    • Acknowledgment: Within 48 hours
    • Initial assessment: Within 5 business days
    • Fix timeline: Depends on severity (see below)

Severity Levels and Response#

Severity Example Target Fix Time
Critical Remote code execution, auth bypass 24-48 hours
High SQL injection, XSS, data exposure 1 week
Medium CSRF, information disclosure 2 weeks
Low Security header missing, minor leak Next release

Recognition#

We appreciate responsible disclosure. Contributors who report valid security vulnerabilities will be acknowledged (with their permission) in release notes.

Security Architecture#

Domain Isolation#

Oshun is an Nx monorepo with strict domain boundaries enforced at the build level. The @nx/enforce-module-boundaries ESLint rule prevents cross-domain imports that violate the dependency graph.

Each domain can only depend on:

  • scope:shared -- Foundation libraries
  • scope:contracts -- Cross-domain type contracts
  • scope:auth -- Authentication libraries
  • Its own scope

This isolation ensures that a vulnerability in one domain does not cascade to others through direct code dependencies.

Layer Architecture#

The codebase enforces a layered architecture:

text
contracts (most foundational)
   |
   v
infra (infrastructure services)
   |
   v
data (data access)
   |
   v
domain (business logic)
   |
   v
ui (user-facing)

Each layer can only depend on layers below it. This prevents UI code from directly accessing infrastructure, and ensures that business logic is separated from data access concerns.

Security-Sensitive Code Ownership#

Files in security-sensitive directories are protected by CODEOWNERS:

text
**/auth/**       -> @oshun/security @oshun/core-team
**/security/**   -> @oshun/security @oshun/core-team
**/identity/**   -> @oshun/security @oshun/core-team
**/database/**   -> @oshun/core-team @oshun/platform
**/migrations/** -> @oshun/core-team @oshun/platform

Any pull request modifying these paths automatically requires review from the security and core teams.

Authentication and Authorization#

@oshun/auth-primitives#

The @oshun/auth-primitives library (libs/shared/auth-primitives/) provides low-level, framework-agnostic authentication building blocks:

JWT Service:

  • Token signing and verification with configurable algorithms (HMAC, RSA)
  • JWT ID generation for token tracking
  • Authorization header parsing and creation
  • Configurable token expiration and issuer validation

Password Handling:

  • PasswordHasher -- Secure password hashing (bcrypt-based)
  • PasswordValidator -- Configurable password policy enforcement
  • generatePassword() -- Cryptographically secure password generation
  • Default policy enforces minimum length, uppercase, lowercase, numbers, and special characters

Session Management:

  • SessionManager -- Session creation, validation, and revocation
  • InMemorySessionStore -- Development/testing session store
  • Device information tracking (user agent parsing)
  • Session ID generation with cryptographic randomness

Token Refresh:

  • TokenRefreshManager -- Refresh token rotation with family tracking
  • Refresh token reuse detection (revokes entire token family on reuse)
  • Configurable refresh token TTL

API Key Management:

  • ApiKeyManager -- API key creation, validation, and revocation
  • Key hashing (keys are never stored in plaintext)
  • Key masking for display (sk_...abc)
  • Extraction from headers and query parameters

@oshun/auth#

The @oshun/auth library (libs/shared/auth/) builds on auth-primitives to provide a complete authentication and authorization service:

Authentication Service (AuthService):

  • User registration with email verification
  • Login with credential validation
  • Token pair management (access + refresh)
  • OAuth provider integration helpers
  • Event-driven audit logging (login, logout, registration, token refresh)

Role-Based Access Control (RBAC):

  • Hierarchical roles with ROLE_HIERARCHY
  • hasMinimumRole() -- Check if a user meets a minimum role level
  • getRolesAtOrBelow() -- Get all roles at or below a given level

Permission-Based Authorization:

  • Fine-grained permissions mapped to roles via ROLE_PERMISSIONS
  • hasPermission(), hasAllPermissions(), hasAnyPermission()
  • Role-to-permission resolution

Account Lockout Protection:

  • AccountLockoutManager -- Local lockout tracking
  • DistributedLockoutManager -- Redis-backed distributed lockout
  • Configurable: max attempts (default 5), lockout duration, auto-reset period

Middleware:

  • createAuthMiddleware() -- Framework-agnostic authentication middleware
  • requireAuth() / optionalAuth() -- Authentication gates
  • requireRole() / requireRoles() -- Role-based authorization
  • requirePermissions() / requireAnyPermission() -- Permission-based authorization
  • requireOwnership() / requireOwnershipOrPermission() -- Resource ownership checks
  • denySelf() -- Prevents users from performing actions on their own accounts (e.g., self-promotion)
  • Token extraction from Bearer headers and cookies

@oshun/security#

The @oshun/security library (libs/shared/security/) provides security utilities:

Audit Logging:

  • AuditLogger -- Structured audit event recording
  • Event types: authentication, authorization, data access, data modification, system events
  • Actor tracking (user, service, system, anonymous)
  • Target tracking (what resource was accessed/modified)
  • Request context (IP address, user agent, geo-location)
  • Batched writes for performance
  • Stores: MemoryAuditStore (development), DatabaseAuditStore (production)
  • Query support with filtering, pagination, and aggregation

Security Scanning:

  • BuiltinSecurityScanner -- Pattern-based secret and threat detection
  • ClamAVScanner -- Antivirus integration for file scanning
  • Scans for: API keys, tokens, passwords, AWS credentials, private keys, credit card numbers, SSNs
  • File and text content scanning

Secret Management:

  • SecretManager -- Secret lifecycle management
  • Secret creation, retrieval, update, and deletion
  • Automatic rotation with configurable intervals
  • Version history tracking
  • Caching with configurable TTL
  • Stores: MemorySecretStore (development), DatabaseSecretStore (production)
  • Secret types: API keys, database credentials, encryption keys, certificates, OAuth secrets

@oshun/identity#

The @oshun/identity library (libs/shared/identity/) provides user identity management utilities for the platform.

@oshun/rate-limit#

The @oshun/rate-limit library (libs/shared/rate-limit/) provides rate limiting capabilities to protect APIs from abuse.

Secrets Management#

Environment Variables#

All secrets are managed through environment variables. The repository enforces strict separation:

  • .env files are excluded via .gitignore
  • .env.example files provide templates with placeholder values
  • No secrets are ever committed to the repository

The .gitignore file explicitly excludes:

text
.env
.env.local
.env.development
.env.development.local
.env.test
.env.test.local
.env.production
.env.production.local
.env.staging
.env.staging.local
.env*.local
*.env
*.pem
*.key
*.crt
*.p12
*.pfx
**/certs/*.pem
**/certs/*.key

Runtime Secret Management#

The @oshun/security library provides SecretManager for runtime secret management with:

  • Encrypted storage
  • Automatic rotation with configurable intervals (e.g., 30-day database password rotation)
  • Version tracking for rollback
  • In-memory caching with TTL to reduce store lookups
  • Pluggable store backends (memory for development, database for production)

CI/CD Secrets#

Secrets used in CI/CD are stored as GitHub repository secrets and referenced via ${{ secrets.SECRET_NAME }}. The CI workflows use:

  • NX_CLOUD_ACCESS_TOKEN -- Nx Cloud for distributed caching
  • GITHUB_TOKEN -- GitHub API access (automatically provided)

Dependency Scanning#

Automated Auditing#

The CI pipeline includes a security audit job that runs on every push to main/develop and on every pull request:

  1. pnpm audit -- Scans all dependencies for known vulnerabilities at the high severity level and above.

  2. Critical vulnerability gate -- The CI fails if any critical vulnerabilities are found.

  3. Hardcoded secret scan -- Searches source code for patterns matching passwords, API keys, tokens, and secrets.

Iris Domain-Specific Security#

The Iris AI Assistant platform has an additional dedicated security workflow (.github/workflows/iris-security.yml) that runs daily:

  • Dependency vulnerability scanning with reporting
  • Detection of deprecated/problematic dependencies (lodash, moment, request)
  • Iris-specific package analysis

Dependency Management Practices#

  • pnpm catalog (pnpm-workspace.yaml) centralizes shared dependency versions. This ensures consistent versions across all packages and makes it easier to update vulnerable packages in one place.

  • pnpm overrides in the root package.json force minimum versions for packages with known vulnerabilities:

    json
    "pnpm": {
  "overrides": {
    "glob": ">=10.0.0",
    "qs": ">=6.14.0",
    "validator": ">=13.15.0",
    "zod": ">=3.23.0",
    "esbuild": ">=0.25.0",
    "tmp": ">=0.2.4"
  }
}

  • PR dependency review -- The CI bot automatically detects and comments on dependency changes in pull requests, listing added and removed packages for manual review.

Static Analysis and Code Scanning#

CodeQL#

GitHub CodeQL analysis runs on:

  • Every push to main and develop (for .ts, .tsx, .js, .jsx files)
  • Every pull request to main
  • Weekly scheduled scans (Sundays at 2 AM UTC)

Configuration:

  • Language: javascript-typescript
  • Query suites: security-extended and security-and-quality
  • Scans libs/, apps/, yemaya/packages/, yemaya/apps/, lilith/services/
  • Excludes: node_modules, dist, test files

ESLint Security Rules#

The Iris security workflow runs ESLint with security-focused rules and scans for dangerous patterns:

Dangerous patterns detected:

  • eval() and new Function()
  • innerHTML assignment
  • dangerouslySetInnerHTML
  • document.write()
  • child_process usage
  • spawn() and execSync()
  • __proto__ access
  • constructor[] access

SQL injection detection:

  • Raw SQL queries with string concatenation
  • Template literal interpolation in SQL statements

XSS prevention:

  • innerHTML / outerHTML assignment
  • document.write()
  • insertAdjacentHTML()

Secret Scanning#

Gitleaks#

The Iris security workflow uses Gitleaks for secret scanning:

  • Scans the full git history for leaked secrets
  • Detects: passwords, API keys, tokens, Bearer tokens, AWS access keys (AKIA...), OpenAI keys (sk-...)
  • Fails the build if potential secrets are found

Hardcoded Value Detection#

Both the main CI and Iris security workflows scan source code for hardcoded sensitive values using pattern matching:

text
password\s*[:=]\s*['"][^'"]{8,}['"]
api[_-]?key\s*[:=]\s*['"][^'"]{16,}['"]
secret\s*[:=]\s*['"][^'"]{8,}['"]
token\s*[:=]\s*['"][^'"]{20,}['"]
Bearer\s+[A-Za-z0-9\-_]{20,}
sk-[A-Za-z0-9]{20,}
AKIA[0-9A-Z]{16}

Test files, examples, and mock data are excluded from these scans.

Container Security#

Dockerfile Scanning#

When Dockerfiles are present, the Iris security workflow uses Trivy to scan for:

  • Misconfiguration in Dockerfiles
  • High and critical severity issues

Dockerfile Best Practices#

The CI checks Dockerfiles for:

  • USER instruction -- Containers should not run as root
  • HEALTHCHECK instruction -- Containers should define health checks
  • No :latest tag -- Use specific version tags for reproducibility
  • Multi-stage builds -- Recommended for smaller, more secure images

License Compliance#

The Iris security workflow includes license compliance checking. Allowed licenses:

text
MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD,
CC0-1.0, Unlicense, WTFPL, CC-BY-3.0, CC-BY-4.0

Packages with GPL, LGPL, AGPL, or UNKNOWN licenses are flagged for review.

Secure Development Practices#

Input Validation#

  • Use Zod (^3.23.0) for runtime type validation and schema enforcement
  • Validate all external input at API boundaries
  • Use parameterized queries for database access (the @oshun/database library uses positional parameter replacement via tagged template literals)

Error Handling#

  • Never expose internal error details to clients in production
  • Use the @oshun/errors library for structured, typed error handling
  • Log detailed errors server-side via @oshun/logger (Pino-based structured logging)

Authentication Best Practices#

  • Passwords are hashed using bcrypt (via @oshun/auth-primitives)
  • JWT tokens have configurable short-lived access tokens (default 15 minutes) and longer-lived refresh tokens (default 7 days)
  • Refresh token rotation with family tracking detects token reuse attacks
  • Account lockout after configurable failed attempts (default 5)
  • Rate limiting on authentication endpoints

Data Protection#

  • Audit logging for all authentication and authorization events
  • Structured audit trails with actor, target, and request context
  • Secret scanning in CI prevents accidental credential commits
  • Domain-isolated databases prevent cross-domain data access at the infrastructure level

Environment and Configuration Security#

Development Environment#

The local development environment uses Docker Compose with default credentials for convenience:

  • PostgreSQL: oshun:oshun_dev@localhost:5432
  • MinIO: minioadmin:minioadmin@localhost:9000
  • Redis: No password (localhost only)

These credentials are for local development only and must never be used in staging or production environments.

Production Considerations#

  • All secrets must be provided via environment variables or a secrets manager
  • Database connections must use SSL/TLS
  • Redis connections must be authenticated
  • S3/MinIO connections must use proper IAM credentials
  • All inter-service communication should be encrypted in transit
  • Use the @oshun/security SecretManager for runtime secret access with automatic rotation

Infrastructure as Code#

Terraform configurations are stored in infra/terraform/. Terraform state files and variable files are excluded from the repository via .gitignore:

text
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
.terraform.lock.hcl