Security Architecture

Security Principles

Four principles guide every security decision in the system. They are not aspirational. They are enforced in code and verified by tests.

Authentication

API key authentication is the single entry point for every protected endpoint. Keys are never stored in plaintext.

• Header: X-API-Key on every request to a protected endpoint
• Storage: SQLite user database with bcrypt hashing. The raw key never touches disk after issuance.
• Comparison: Constant-time comparison via secrets.compare_digest() to prevent timing attacks that could leak key material byte by byte
• Enforcement: All protected endpoints require a valid API key. No exceptions, no bypass paths.
• Admin endpoints: Router-level dependency injection enforces auth before the handler runs. The check happens once, at the framework layer, not inside each route function.

# Auth flow
1. Extract X-API-Key header
2. Look up user record in SQLite
3. bcrypt.verify(provided_key, stored_hash)
4. secrets.compare_digest on resolved key
5. Attach user context to request
6. Reject with 401 if any step fails

Rate Limiting

The slowapi library throttles requests at the application layer. Two tiers of limits apply depending on endpoint cost.

When a client exceeds the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. Both limits are configurable via environment variables, so operators can tune them for their deployment without code changes.

CORS

Cross-origin requests are controlled at the framework layer. Nothing is open by default.

• Allowed origins: Configurable via the CORS_ALLOWED_ORIGINS environment variable. No wildcard in production.
• Methods: GET, POST, PUT, DELETE. PUT and DELETE are enabled for admin API operations such as key rotation and configuration updates.
• Credentials: Support for authenticated cross-origin requests. Browsers send the API key header with proper preflight handling.
• Preflight caching: Enabled to reduce OPTIONS round-trips. Browsers cache the preflight response for the configured max age.

Input Security

File: SecurityEngine.check_input()

Every user input passes through the SecurityEngine before it reaches the cognitive pipeline. The engine runs pattern-based detection across five threat categories.

All detected threats are logged with the matched pattern and the raw input hash. The request is blocked. No partial processing occurs.

Output Security

File: SecurityEngine.check_output()

Output security operates on a different threat model than input security. The system checks generated output before it reaches the client. This runs as Stage 12 in the 18-stage pipeline.

Input and output security are separate by design. A clean input does not guarantee a clean output. Both must pass independently.

Docker Security

The container image is built to minimize attack surface. Build tools and development dependencies never reach the runtime image.

• Multi-stage build: First stage installs build dependencies and compiles assets. Second stage copies only the runtime artifact. The final image contains no compilers, no build tools, no test fixtures.
• Non-root user: The application runs as novaspire (UID 1000). If an attacker escapes the application process, they land in a non-root account with no sudo access.
• No package installation in runtime: The runtime image has no package manager cache. apt and pip caches are stripped. No runtime dependency installation is possible.
• Minimal base image: python:3.11-slim. Smaller surface area than full Debian-based images. Fewer packages means fewer CVEs.
• Health check: Container exposes a health endpoint for orchestration platforms to detect and restart unhealthy instances.

Kubernetes Security

Pod-level security controls enforce isolation and resource boundaries in production deployments.

CI/CD Security

Security scans run on every pull request and every push to the main branch. No merge lands without passing all checks.

Ethics and Content Policy

File: EthicsEngine

Content policy checks run on both input and output. The EthicsEngine evaluates generated content for harmful, biased, or inappropriate material before it reaches the user.

• Input checks: Harmful intent detection, harassment patterns, requests for dangerous content
• Output checks: Bias detection, harmful content filtering, inappropriate material screening
• Configuration: Policies are defined in a JSON configuration file. Operators can adjust thresholds and categories without code changes.
• Logging: Every ethics decision is logged with the category, the action taken, and the relevant content hash.

Security Testing

Security is verified by automated tests on every CI run. The test suite covers authentication, rate limiting, CORS, input injection, and output PII detection.

Tests cover the negative paths. Missing authentication returns 401. Invalid keys return 401. Rate limit violations return 429. Input injection attempts are blocked. Output PII is caught. These tests run on every pull request. A regression in any of them blocks the merge.

Known Limitations

No security architecture is finished. The following limitations are documented here so operators can plan around them.