Security and Operations

Security and Operations

Deployment checklist

1. Serve Agent4API over HTTPS and set CHAT4OPENAPI_SECURE_COOKIES=true.
2. Configure System Base URL to the externally reachable origin.
3. Keep the administrator interface and backend behind the intended reverse proxy and access policy.
4. Add exact host origins to each Embed; avoid an empty list unless public framing is intentional.
5. Register each API Source's displayed effective OAuth callback with its provider.
6. Back up data/chat4openapi.db and data/.chat4openapi.key together.
7. Run Alembic migrations before serving a new release.
8. Verify CSP permits the generated loader and iframe only where intended.

Browser security model

The host and iframe are different origins. Host login cookies are not readable by Agent4API, and Agent4API cookies are not exposed to the host. The loader exchanges only narrow initialization and close messages with exact source-window and origin checks.

Embed Sessions use in-memory bearer tokens in the iframe. They are bound to the public Embed, fixed Agent, and normalized parent origin. The public loader reveals no administrator or Agent API key.

OAuth and Swagger authorization uses a top-level popup so upstream login and consent remain visible to the user. Popup results contain only a hashed-at-rest, single-use grant with a maximum five-minute lifetime.

Secret handling

• Provider keys, upstream credentials, OAuth tokens, client secrets, PKCE verifiers, and Swagger login results are encrypted at rest.
• Agent API keys, session tokens, and Embed grants are stored as hashes where lookup semantics permit.
• Secrets are omitted from later responses and application logs.
• Losing or mismatching the encryption key makes encrypted data unrecoverable.

Network and resource controls

API-source fetches and redirects apply SSRF controls. Private or non-routable targets require explicit source opt-in. URL credentials, fragments, unsafe redirects, transport-sensitive headers, and undeclared credential names are rejected.

OpenAPI documents, Tool request/response bodies, bulk Tool operations, Skill bindings, prompt lengths, Agent iterations, WebMCP Tools, and WebMCP messages all have bounded limits.

Backup and upgrade

Stop writes and copy the database and encryption key as one backup set. Then run:

python -m alembic -c backend/alembic.ini upgrade head

Downgrades are for controlled validation, not a backup strategy. Restore both files from the same backup set when rolling back.

Release verification

From the repository root, with the Conda Python environment and nvm-managed Node active:

python -m pytest backend/tests -q
python -m ruff check backend/src backend/migrations backend/tests
nvm use 20.19.4
npm --prefix frontend test
npm --prefix frontend run build
npm --prefix frontend run test:e2e
git diff --check

The WebMCP action scenario may skip only when the selected browser does not expose the draft capability. Basic Widget and authorization scenarios must still run.

Operational troubleshooting

• OAuth callback mismatch: copy the displayed effective callback, not an assumed URL.
• Encrypted data fails after restore: restore the matching encryption key.
• Widget unavailable: verify Base URL, Embed/Agent enabled state, exact allowed origin, and reverse-proxy routing.
• Popup blocked: authorization must be launched directly from the user's button click.
• WebMCP absent: confirm browser support, host registration, exposedTo, and iframe allow="tools".
• Unexpected 401 from an upstream Tool: revoke/re-authorize that source; Agent4API never opens an interactive flow inside Tool execution.