kladero / veratag-typo3-extension
vera[tag] - Synchronize disclosure data from vera[tag], manage your integration in TYPO3, and deliver language-aware AI content disclosures to website visitors.
Package info
github.com/kladero/veratag-typo3-extension
Language:TypeScript
Type:typo3-cms-extension
pkg:composer/kladero/veratag-typo3-extension
Requires
- php: >=8.4.0 <8.5.0
- ext-sodium: *
- typo3/cms-backend: >=14.3.0 <14.4.0
- typo3/cms-core: >=14.3.0 <14.4.0
- typo3/cms-frontend: >=14.3.0 <14.4.0
- typo3/cms-scheduler: >=14.3.0 <14.4.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
AI content disclosures, seamlessly connected to TYPO3.
The official vera[tag] TYPO3 integration by Kladero GmbH.
Synchronize disclosure data from vera[tag], manage your integration in TYPO3,
and deliver language-aware AI content disclosures to website visitors.
Explore vera[tag] · Get started · Build from source · How it works
Disclosure data belongs in one place. Manage your AI content disclosures in the vera[tag] platform; let the TYPO3 integration take care of synchronization and delivery on your website.
At a glance
| Capability | Description |
|---|---|
| Centralized disclosure management | Connect a TYPO3 site to its corresponding vera[tag] channel. |
| Automatic synchronization | Periodically fetch current disclosure data from the platform with the TYPO3 Scheduler. |
| Optional push updates | Receive authenticated changes from vera[tag] without waiting for the next scheduled pull. |
| Language-aware delivery | Use the site's primary language or visitors' preferred languages, according to the configured mode and available disclosure translations. |
| Content visibility | Review synchronized content and disclosure-related issues in the TYPO3 backend. |
| Integrated administration | Manage connection settings, verification, synchronization, and disclosure status directly in a TYPO3 backend module. |
Explore the admin experience
Getting started
Requirements
| For a TYPO3 installation | Requirement |
|---|---|
| TYPO3 | 14.3.x in Composer mode (Backend, Frontend and Scheduler system extensions) |
| PHP | 8.4 (the extension declares >=8.4.0 <8.5.0) with the sodium extension |
| Server | A working HTTPS site, a database, a backend administrator, and shell access for one-time setup |
| vera[tag] | A vera[tag] account, a TYPO3-enabled channel, and an API key |
| Channel verification | Follow the domain-verification instructions in the vera[tag] platform |
Note: Node.js is not required on a TYPO3 server. It is needed only if you want to build the extension ZIP from this source repository.
1. Install the extension
In your TYPO3 Composer project:
composer require kladero/veratag-typo3-extension vendor/bin/typo3 extension:setup
extension:setup creates the extension's database tables (tx_veratag_*, from ext_tables.sql).
Prefer a ZIP? Download the release ZIP from the GitHub releases page, unpack it as packages/veratag in your project, register it as a Composer path repository, and require kladero/veratag-typo3-extension:*@dev. The extension supports Composer-mode TYPO3 only.
Cloned or downloaded this GitHub source instead? Composer can install the repository directly, because composer.json and the compiled admin UI are part of it. To create your own release ZIP, see build from source.
2. Prepare the server (one-time)
The extension cannot change web-server or cron configuration itself. Some steps are automatic and some need an administrator with server access:
| Step | Automatic? | What to do |
|---|---|---|
| Database tables | After setup | Run vendor/bin/typo3 extension:setup. |
| Encryption secret | Manual | Provide VERATAG_SECRET_ENCRYPTION_KEY (base64 of 32 random bytes) in the PHP and web-server environment. It must be readable by both web and command-line PHP. Credentials are encrypted with it, and it must never be committed. |
| Scheduler tasks | Manual, once | Select Finish setup in the module under Settings → Extension setup, or run vendor/bin/typo3 veratag:scheduler:install. This registers the two recurring tasks (pull and renderer sync, every 45 minutes). Both ways are safe to repeat. |
| System cron | Manual, once | Registered tasks only run when something calls vendor/bin/typo3 scheduler:run. Add an OS cron job that runs it every minute. Most TYPO3 sites already have one. TYPO3 has no page-view-triggered cron, so without it the scheduled pull never runs. |
Authorization header for push |
Manual | Only needed for push. See step 4. |
| Renderer script folder | Created on demand | public/fileadmin/veratag/render-scripts/ must be writable by the PHP user, and the web server must serve static files there without executing scripts. |
The Extension setup section in Settings lists what is still open and warns when the vera[tag] tasks are overdue.
3. Connect your vera[tag] channel
- Open the vera[tag] backend module in TYPO3.
- Follow the connection instructions in the vera[tag] platform to obtain the API key for your channel.
- Go to Settings and save the API key. Saving the key starts the first pull synchronization.
- Complete domain verification as instructed by the platform. The extension serves the verification resource at
/.well-known/veratag-verify-{token}.txt. - Check General or Synchronization to confirm that the first pull succeeded.
4. Choose your synchronization setup
Pull synchronization is the standard connection mechanism. It runs when you save the API key, when you start it manually in the module, and every 45 minutes through the TYPO3 Scheduler (which needs the system cron from step 2).
For more immediate updates, you can optionally configure push synchronization in Settings. When it is enabled and configured, the platform sends authenticated updates to POST /veratag/v1/push-api/receive. This endpoint must be reachable from the platform. Push does not need the cron job, and the scheduled pull then acts as a regular catch-up.
Push returns 401 Unauthorized? The Authorization header must reach PHP
The platform authenticates each push with Authorization: Bearer <secret>. Apache with mod_php and many CGI/FastCGI setups do not pass that header into PHP's $_SERVER. TYPO3 then sees no credential, and the receiver answers 401 veratag_push_api_unauthorized (the platform only reports "401 Unauthorized … [no body]"). Add one of the following to the public .htaccess or to the Apache virtual host, then check that a push succeeds:
RewriteEngine On RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
or
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1
On PHP-FPM or CGI, CGIPassAuth On is the usual equivalent.
5. Configure disclosure language
Under Settings → Visitor Disclosure Language, choose how the extension selects the disclosure language:
- Site-preferred: Use the TYPO3 site's primary language.
- Visitor-preferred: Consider the visitor's preferred browser language and the configured fallback.
A disclosure is served in a selected language only when the relevant disclosure configuration contains the necessary information in that language. If a synchronized content record is malformed or missing required identification fields, the extension skips that record while still delivering valid disclosures on the same page.
6. Review the result
Use the Content page to review synchronized content and disclosure state. The extension loads applicable disclosure data for the requested page, and its frontend renderer script draws the disclosures for visitors. If /fileadmin/veratag/render-scripts/…js returns 404, check that a renderer sync has run and that the file exists in the public fileadmin folder.
How it works
The TYPO3 extension connects your website to the matching vera[tag] channel. Disclosure information is managed in the vera[tag] platform, synchronized into TYPO3, and used to render the relevant disclosures for website visitors.
flowchart TD
A["vera[tag] platform<br/>Channel & disclosure configuration"]
B["Scheduled pull<br/>TYPO3 → vera[tag]"]
C["Optional authenticated push<br/>vera[tag] → TYPO3"]
D["TYPO3 extension<br/>Local disclosure storage"]
E["Page request<br/>Match content & language"]
F["Frontend renderer<br/>Visitor-facing disclosures"]
A --> B
A --> C
B --> D
C --> D
D --> E
E --> F
classDef platform fill:#002255,color:#fff,stroke:#002255;
classDef process fill:#F0F6FF,color:#002255,stroke:#99C2FF;
classDef output fill:#0066FF,color:#fff,stroke:#0066FF;
class A platform;
class B,C,D,E process;
class F output;
Loading
Behind the scenes:
- Connect — An administrator configures the channel API key and domain verification.
- Synchronize — The TYPO3 Scheduler periodically fetches disclosure data; an optional authenticated push endpoint accepts platform-originated changes.
- Store — The PHP persistence layer maintains local disclosure and synchronization records in TYPO3 database tables.
- Resolve — On a page request, a TYPO3 frontend middleware selects applicable disclosure data and determines the language according to the configured mode.
- Render — The extension serves the frontend rendering script from your own origin and supplies the applicable disclosure data to the page.
For further implementation detail, inspect src/php/Service/, src/php/Middleware/ and src/php/Persistence/.
Built for transparency
This repository contains the readable PHP implementation, the React/TypeScript admin UI source, the public release builder, and a version-locked npm dependency graph.
| What you can inspect | Where |
|---|---|
| Extension bootstrap and configuration | src/php/Bootstrap/ · Configuration/ |
| Backend module and authenticated Ajax API | src/php/Backend/ |
| Frontend middlewares (page injection, verification file, push receiver) | src/php/Middleware/ |
| Synchronization, renderer and setup services | src/php/Service/ · src/php/Scheduler/ · src/php/Command/ |
| Persistence and database schema | src/php/Persistence/ · ext_tables.sql |
| Secret handling | src/php/Security/ |
| React admin UI and styles | src/ui/admin/ |
| Public, standalone ZIP builder | scripts/build-zip-release.mjs |
| Third-party dependencies and licenses | package-lock.json · THIRD_PARTY_NOTICES.txt |
Security and service boundaries
- The extension communicates with the configured vera[tag] backend using HTTPS and a restricted list of allowed origins.
- The API key and the push credential are encrypted at rest (libsodium) with a deployment secret,
VERATAG_SECRET_ENCRYPTION_KEY, that is not stored in the repository or the web root. - TYPO3 backend operations run in the authenticated TYPO3 backend context; the push receiver uses a separate credential check and an explicit enable switch.
- The extension can serve a publicly reachable verification file so the platform can verify continued site control.
- The frontend rendering script is downloaded by the extension and served from your site's own origin (
/fileadmin/veratag/render-scripts/). - An active connection requires the external vera[tag] service. It is not a standalone disclosure-management platform.
Handling credentials: Never put real API keys, push secrets, verification tokens, or personal information in screenshots, GitHub issues, pull requests, or example configuration files.
For precise request behavior and data handling, consult the relevant PHP service classes. Before deploying, also review the applicable vera[tag] service terms and privacy documentation provided by Kladero GmbH.
Build from source
Want to verify the public source or create your own installable ZIP? The repository includes everything needed for the public release build.
Prerequisites
- Node.js 22.12.0 or newer, with npm
- An internet connection for the initial npm dependency installation
- PHP 8.4 only if you also want to run the PHP test suite (
npm run test:php)
The ZIP build itself needs no Composer and no PHP, and the installed extension does not need Node.js.
Build commands
# Install the exact dependencies from package-lock.json npm ci # Optional: lint the React/TypeScript admin UI npm run lint:ui # Optional: run the offline test suites (the PHP suite needs PHP 8.4) npm test # Compile the admin UI and create the installable ZIP npm run zip:release
Output
dist/
└── veratag-typo3-extension-<version>.zip
The command runs the TypeScript/Vite UI build and then the standalone ZIP packager at scripts/build-zip-release.mjs.
What's inside the generated ZIP?
veratag/
├── composer.json # Composer package kladero/veratag-typo3-extension
├── ext_tables.sql # Database schema
├── Configuration/ # Backend module, icons, services, middlewares
├── src/php/ # PHP implementation
├── Resources/Public/ # Compiled admin UI and brand assets
├── LICENSE
├── TRADEMARKS.md
└── THIRD_PARTY_NOTICES.txt
The TYPO3 extension key is veratag, and the version comes from package.json.
How reproducible is the release build?
npm ciinstalls dependency versions locked inpackage-lock.json.- The Node.js ZIP writer sorts entries, normalizes text line endings, and uses fixed ZIP timestamps, so identical packaged inputs yield identical ZIP bytes.
- Vite output can still vary with the Node/npm version, operating system, or toolchain environment. Match the original build environment when comparing release hashes.
- The checked-in compiled admin assets are reference outputs;
npm run zip:releaserebuilds them from the included source.
Repository map
.
├── Configuration/ # TYPO3 module, icon, service and middleware configuration
├── Resources/Public/ # Compiled admin UI and brand assets
├── assets/ # Static assets + compiled admin UI
├── src/
│ ├── php/ # Extension implementation (PHP, PSR-4 classes)
│ │ ├── Backend/
│ │ ├── Bootstrap/
│ │ ├── Command/
│ │ ├── Domain/
│ │ ├── Http/
│ │ ├── Middleware/
│ │ ├── Persistence/
│ │ ├── Scheduler/
│ │ ├── Security/
│ │ ├── Service/
│ │ └── Storage/
│ └── ui/admin/ # React + TypeScript + Vite
├── tests/ # PHP and UI test suites
├── scripts/
│ └── build-zip-release.mjs # Standalone public release builder
├── composer.json # Composer package definition
├── ext_tables.sql # Database schema
├── package.json # Build scripts and extension version
├── package-lock.json # Locked npm dependency graph
├── LICENSE
├── TRADEMARKS.md
└── THIRD_PARTY_NOTICES.txt
FAQ
Is a vera[tag] account required?
Yes. The extension connects a TYPO3 installation to a channel on the external vera[tag] platform. You need the relevant channel and API key to synchronize disclosures.
Do I need to enable push synchronization?
No. Pull synchronization runs independently. Push synchronization is an optional mechanism for receiving platform changes more directly.
Do disclosures update automatically?
Yes, once the one-time setup is done. Registered Scheduler tasks pull the disclosures every 45 minutes, but only while the TYPO3 Scheduler itself is called by a system cron job (vendor/bin/typo3 scheduler:run, every minute). Without that cron job, no scheduled pull happens. Push updates arrive without the cron job, once push is enabled and configured.
Does it work on TYPO3 without Composer?
No. The extension supports Composer-mode TYPO3 14.3 only. It requires PHP 8.4.
Does my TYPO3 server need npm or Node.js?
No. Node.js and npm are used only to build the release ZIP from source. A site installing the extension with Composer needs neither.
What happens if my extension version is no longer supported?
The admin UI includes a compatibility check against the vera[tag] backend. When the backend reports an unsupported version, the extension shows an update-required screen instead of opening the normal admin pages.
Contributing and reporting issues
Source transparency is an important part of vera[tag]. You can inspect the implementation, reproduce the release build, and use this repository to discuss code-level issues or potential improvements. Please open an issue for bug reports. See docs/TESTING.md for how the extension is verified, and docs/CHANGELOG.md for release notes.
For a useful report, include your TYPO3 and PHP versions, the vera[tag] extension version, the affected backend page or feature, and steps to reproduce the problem. Redact all credentials and personal data.
Security issues: Please report suspected vulnerabilities privately to Kladero GmbH through the official company website, rather than publicly disclosing exploit details in an issue.
Licensing and trademarks
The TYPO3 extension is published under the GNU General Public License, version 2 or later. See LICENSE for the complete license text.
Additional details:
THIRD_PARTY_NOTICES.txtlists relevant third-party components and their licenses.TRADEMARKS.mdexplains the trademark and branding status of vera[tag] and Kladero.- The extension is an integration with the separately operated vera[tag] service. Publishing the extension source does not mean that the service itself is part of this repository.
Content transparency, connected.
Developed and maintained by Kladero GmbH.
vera-tag.com
![vera[tag] TYPO3 integration — product overview](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/veratag-typo3-banner.png)
![vera[tag] General page showing the channel and connection overview](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/typo3-general.png)
![vera[tag] Content page with synchronized content and disclosure information](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/typo3-content.png)
![vera[tag] Synchronization page showing pull and push activity](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/typo3-synchronization.png)
![vera[tag] Settings page with integration configuration](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/typo3-settings.png)
![Example of a vera[tag] disclosure displayed on a TYPO3 site](https://rawcdn.githack.com/kladero/veratag-typo3-extension/HEAD/docs/images/typo3-frontend.png)