Credentials & Security

Relevant source files

The following files were used as context for generating this wiki page:

• KEYS_AND_CREDENTIALS.md
• DEPLOYMENT_GUIDE.md
• backend/server.py
• frontend/src/App.js
• frontend/plugins/visual-edits/dev-server-setup.js

The Credentials & Security system of the Promethean Conduit project encompasses the management of API keys, database connection strings, administrative access controls, and Cross-Origin Resource Sharing (CORS) policies. Its primary purpose is to secure the communication between the React-based frontend and the FastAPI backend, while ensuring restricted access to sensitive administrative functions and external AI services.

Security is enforced through a combination of environment variables, header-based authentication, and origin validation. The system is designed to support both development and production environments, with specific protocols for handling sensitive data like the Together.ai API key and MongoDB/Supabase connection strings.

Sources: KEYS_AND_CREDENTIALS.md, DEPLOYMENT_GUIDE.md, backend/server.py:1-60

Authentication & Authorization Architecture

The project utilizes several layers of authentication depending on the user role and the specific service being accessed. Standard user interactions are largely anonymous but isolated by session IDs, while administrative tasks require explicit secrets.

Admin Authentication

Administrative access to the backend is secured via a custom header check. The verify_admin function in the backend validates the Authorization header against a stored ADMIN_SECRET.

The diagram above illustrates the administrative login and verification flow for accessing protected system configurations.
Sources: backend/server.py:165-170, frontend/src/App.js:520-560

Key Credentials Summary

Credential	Purpose	Source
TOGETHER_API_KEY	Powers DeepSeek-V3 AI conversations	Environment Variable
MONGO_URL	Primary database connection string	Environment Variable
ADMIN_SECRET	Backend API authentication for admin tasks	Environment Variable
SUPER_ADMIN_USER_ID	Grants AI function calling privileges	Environment Variable
X-Admin-Secret	Custom header for admin requests	HTTP Header

Sources: KEYS_AND_CREDENTIALS.md:15-100, backend/server.py:75-80

Environment Configuration

The application relies heavily on .env files to separate code from configuration. Two distinct environment files are maintained for the backend and frontend.

Backend Environment (/backend/.env)

The backend manages the most sensitive data, including database credentials and AI provider keys.

• Database: MONGO_URL and DB_NAME.
• Security: CORS_ORIGINS (comma-separated list of allowed domains) and ADMIN_SECRET.
• AI: TOGETHER_API_KEY for the Together AI client.
• Role Logic: SUPER_ADMIN_USER_ID identifies which user account can trigger AI tool calls (e.g., create_library_entry).

Frontend Environment (/frontend/.env)

The frontend primarily stores connectivity and feature-flagging information.

• API Connection: REACT_APP_BACKEND_URL.
• Feature Flags: REACT_APP_ENABLE_VISUAL_EDITS and ENABLE_HEALTH_CHECK.

Sources: KEYS_AND_CREDENTIALS.md:105-130, DEPLOYMENT_GUIDE.md:185-210

Data Flow & Network Security

Network security is enforced through Cross-Origin Resource Sharing (CORS) and origin validation for specialized development endpoints.

CORS Implementation

The FastAPI backend uses CORSMiddleware to restrict requests to origins defined in the CORS_ORIGINS environment variable. This prevents unauthorized domains from making API calls to the conduit.

app.add_middleware(
    CORSMiddleware,
    allow_credentials=True,
    allow_origins=os.environ.get('CORS_ORIGINS', '*').split(','),
    allow_methods=["*"],
    allow_headers=["*"],
)

Sources: backend/server.py:530-536

Visual Edits Security

A specialized development server setup facilitates visual editing. This endpoint (/edit-file) includes its own security logic:

1. Origin Validation: Only allows localhost or specific emergent.sh/emergentagent.com subdomains.
2. Secret Verification: Requires an x-api-key header that matches the Supervisor code-server password.
3. Path Traversal Protection: Ensures file edits are restricted to the frontend root directory and excludes node_modules or .git.

The flow above represents the multi-stage validation process for the development-only file editing API.
Sources: frontend/plugins/visual-edits/dev-server-setup.js:30-130

Database Security & Schemas

The project supports both MongoDB (NoSQL) and Supabase (PostgreSQL). Security at the database level involves restricting connection access and maintaining user isolation in the data model.

User Isolation Logic

All conversation and message data models include a user_id field. The backend verifies that the requesting user owns the conversation_id before returning messages or processing new chat prompts, unless the conversation is marked as is_intergalactic (public).

if not conversation.get('is_intergalactic', False):
    if conversation.get('user_id') != request.user_id:
        raise HTTPException(status_code=403, detail="Access denied")

Sources: backend/server.py:315-320

Supabase Schema Implementation

When using the Supabase alternative, security is reinforced through standard relational constraints, such as ON DELETE CASCADE for messages linked to conversations.

Table	Security Features
conversations	PK: id, includes user_id for isolation
messages	FK: conversation_id with Cascade Delete
admin_config	Single row (id='main') for global system prompts

Sources: DEPLOYMENT_GUIDE.md:100-160

Security Best Practices

The project documentation outlines several critical security protocols for maintainers:

1. Credential Exclusion: .env files are explicitly included in .gitignore to prevent accidental commits to GitHub.
2. Production Hardening: Default values for ADMIN_SECRET and SUPER_ADMIN_USER_ID must be changed during deployment.
3. Key Rotation: Recommendations include rotating Together.ai keys every 90 days and Database credentials every 6 months.
4. 2FA: Enabling Two-Factor Authentication is required for all linked services (GitHub, MongoDB Atlas, Supabase, PythonAnywhere).

Sources: KEYS_AND_CREDENTIALS.md:135-160

Summary

The Credentials & Security framework of Promethean Conduit relies on a strict separation of configuration and code via environment variables. By combining CORS protection, session-based user isolation, and header-validated administrative endpoints, the system ensures that AI interactions and sensitive data remain protected across development and production environments.