Operations and Security

Operations and Security

Backup and migration

Stop the application and back up the SQLite database together with its encryption key before upgrading. By default, these files are data/chat4openapi.db and data/.chat4openapi.key. The database alone cannot recover encrypted provider, Tool Session, or OAuth secrets.

Windows Command Prompt:

mkdir backup
copy data\chat4openapi.db backup\chat4openapi.db
copy data\.chat4openapi.key backup\.chat4openapi.key
python -m alembic -c backend/alembic.ini upgrade head

Linux or macOS shell:

mkdir -p backup
cp data/chat4openapi.db backup/chat4openapi.db
cp data/.chat4openapi.key backup/.chat4openapi.key
python -m alembic -c backend/alembic.ini upgrade head

The migration chain preserves API sources, Tools, parameter overrides, providers, Skills, ordered bindings, Agents, keys, and conversations.

On default paths only, startup and Alembic atomically migrate legacy database and key filenames when the destination does not exist. Current files are never overwritten. Custom paths are never moved automatically.

Downgrades are intended for controlled validation, not as a backup strategy. Restore the database and key from the same backup set when rolling back.

Security boundaries and limits

• Provider keys, upstream credentials, OAuth material, and PKCE verifiers are encrypted at rest.
• Agent API keys and opaque session tokens are hashed.
• Plaintext secrets are not logged or returned after creation.
• Set CHAT4OPENAPI_SECURE_COOKIES=true behind HTTPS.
• Do not expose the default development listener directly to an untrusted network.
• API-source fetches and redirects apply SSRF controls. Private or non-routable targets require an explicit source opt-in.
• URL credentials, fragments, and unsafe redirects are rejected.
• OpenAPI documents are limited to 5 MiB, Tool requests to 1 MiB, Tool responses to 4 MiB, and redirects to 3.
• Bulk Tool requests accept 1-200 unique positive integer IDs.
• Skills bind at most 128 Tools; Agent iterations range from 2 to 32.
• Chat messages and Agent or Skill prompts are capped at 100,000 characters.
• Credential names must be declared by the API source.
• Transport-sensitive headers such as Host, Content-Length, forwarding, connection, proxy, transfer, and raw Cookie are prohibited.
• OAuth and CAPTCHA interaction never occurs during a Tool call.

Verification

Run the following gates serially from the repository root with the Python environment active:

python -m pytest backend/tests -q
python -m ruff check backend/src backend/migrations backend/tests
nvm use 20.19.4
cd frontend
npm test -- --run --testTimeout=15000
npm run typecheck
npm run build
cd ..
git diff --check

After npm run build, FastAPI serves frontend/dist with SPA fallback. Unknown /api/*, /v1/*, and /anthropic/* paths remain JSON 404 responses.