Download the PHP package webwerkwien/contao-ai-backend-bundle without Composer

contao-ai-backend-bundle

In-browser AI agent for the Contao 5 backend. Editors and admins chat with a Claude (or GPT) agent that can read and modify Contao content through a curated set of tools — no SSH, no CLI. Plus an HTTPS bridge endpoint that lets contao-ai-cli trigger bulk macro operations from the terminal without switching to the browser.

Beta software. Bundle interfaces (tool signatures, bridge JSON, DCA fields) may change between minor versions. Underlying symfony/ai-bundle is pre-1.0. Use at your own risk in production.

You bring your own LLM API key. Each backend user must provide an Anthropic or OpenAI key in their profile (System → Users → AI agent). Without a key, the chat module is disabled for that user. The bundle does not ship with a service-level key.

The contao-ai ecosystem

What it does

contao-ai-backend-bundle is the browser client for AI-powered Contao content management. Authentication, session, CSRF and permissions ride on top of the existing Contao backend — each backend user brings their own API key. A second entry point exposes the macro tools (record_clone, record_rewrite) over HTTPS for the contao-ai-cli bridge workflow.

Requirements

• PHP ^8.2
• Contao ^5.3
• webwerkwien/contao-ai-core-bundle ^0.2
• symfony/ai-bundle ^0.7

Installation

The Contao Manager auto-discovers the bundle via the contao-manager-plugin entry.

Per-user setup

In System → Users → (user), three new fields appear in the AI agent legend:

Grant the AI Chat module under "Allowed modules" to enable the chat entry. The CLI bridge does not require the module mount but still respects the same per-record permission voters.

Available tools

Permissions inherit from Contao's existing module rights. Admins see everything. Non-admins only see tools whose backing module they are allowed to use, and delete sub-tools are admin-only regardless of module membership. Per-record checks (page hierarchy, news-archive access, article parent-page, FAQ category access) run via Symfony voters (ContaoCorePermissions::USER_CAN_*) before each call.

CLI bridge — terminal access for admins and agents

Editors use the chat module above. Developers and admins live in the terminal — and switching to a browser for bulk LLM jobs ("translate all news in archive 5", "clone this page tree with all children") is a workflow break.

The bundle exposes a HTTPS endpoint at POST /_ai_cli/macro that the contao-ai-cli Python client (contao-ai-cli bridge ...) calls with a Bearer token. The macro tools (record_clone, record_rewrite) execute server-side with the full voter pipeline + atomic tl_version audit — same code path as the chat module, just a different transport.

Why /_ai_cli/macro and not /contao/...?

The contao_backend firewall would 302-redirect any unauthenticated request to /contao/login before our Bearer auth runs. Routing the bridge outside /contao/* lets it fall through to the frontend (anonymous) firewall, where the controller does its own auth.

Security model

The bundle was hardened in a four-sprint security pass against findings from two independent reviewers (Opus + Codex). Full breakdown in CHANGELOG.md.

Authentication and authorization

• Auth (chat) rides on the existing Contao backend session (passkey, password, 2FA — whatever the install uses).
• Auth (bridge) uses Bearer tokens stored as password_hash in tl_user.ai_cli_token; constant-time password_verify comparison.
• Module gate: Symfony voter AI_CHAT_USE requires ai_chat in BackendUser->modules for the chat module.
• Tool gate: ToolAccessChecker validates the underlying module per tool. Delete tools require BackendUser::isAdmin === true.
• Per-record gate: every tool that touches a content row asserts ContaoCorePermissions::USER_CAN_* against the record's parent (news archive, page hierarchy, article parent-page) before delegating to the core command.

Field allow-lists

Each *_update tool defines a strict allowedFields() allow-list. The agent cannot set protected DCA columns (pid, tstamp, chmod, cuser, …) even if it asks. Values containing control chars or NULs are rejected.

Prompt-injection mitigation

• Tool outputs are wrapped in <tool_output_data tool="…">…</tool_output_data> sentinels. The system prompt instructs the model to treat anything inside as untrusted data.
• Free-text fields larger than 500 bytes are truncated with …[truncated].
• Chat history lives server-side in the Symfony session keyed by user ID. Client-supplied history is ignored — fabricated assistant turns cannot be smuggled in.
• username / language template substitutions are regex-validated before flowing into the system prompt.

Information disclosure

• API keys are stored with the Contao DCA encrypt flag, never logged, never returned to the browser. The UserAiConfigDto wraps the key behind a private property + getter; __debugInfo() redacts to ***<last4> so casual dump() cannot leak it.
• Exception messages are masked (sk-ant-…, sk-…, Bearer … patterns), scrubbed of kernel.project_dir, truncated to 200 chars, and logged as LogLevel::error for diagnostics.
• dca_schema is restricted to a table allow-list and strips canonical credential/session column names.

Audit trail

Backend invocations stamp tl_version.username and the audit log with the actual Contao username via the --operator option on the underlying core commands. CLI invocations still attribute to $_SERVER['USER'].

Transport hardening

• Cache-Control: no-store, private, max-age=0 + Vary: Cookie + X-Robots-Tag: noindex, nofollow. charset=utf-8 is explicit.
• CSRF: every chat POST requires the Contao backend CSRF token. Bridge POSTs use Bearer auth instead.
• Same-origin verified via Sec-Fetch-Site and Origin request headers.
• Rate limit: 30 requests/minute and 500/day per user — sliding window backed by the session.

Streaming

Chat responses arrive as text/event-stream (SSE-style frames over fetch-ReadableStream, since EventSource cannot POST). Events:

• start — model id
• message — content chunk (currently emitted once per response; chunked streaming will be added when the underlying platform bridge supports it)
• done — successful completion
• error — kind: access_denied | tool_failed | agent_failed

Development

License

MIT — see LICENSE.

This software is provided "as is", without warranty of any kind. The authors accept no liability for any damages arising from its use.