Search by

kladero / veratag-typo3-extension

kladero

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

Homepage

Language:TypeScript

Type:typo3-cms-extension

pkg:composer/kladero/veratag-typo3-extension

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-21 18:37 UTC

This package is auto-updated.

Last update: 2026-11-21 19:10:44 UTC


README

vera[tag]

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

Release 1.0.0 TYPO3 14.3 PHP 8.4 License GPL version 2 or later Source available

vera[tag] TYPO3 integration — product overview

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

vera[tag] General page showing the channel and connection overview
01 — General
Connection overview, channel information, and synchronization status.
vera[tag] Content page with synchronized content and disclosure information
02 — Content
Content overview, disclosure status, and render-script information.
vera[tag] Synchronization page showing pull and push activity
03 — Synchronization
Latest pull and push activity, with status and diagnostics.
vera[tag] Settings page with integration configuration
04 — Settings
API connection, domain verification, optional push, language preferences, and extension setup status.

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

  1. Open the vera[tag] backend module in TYPO3.
  2. Follow the connection instructions in the vera[tag] platform to obtain the API key for your channel.
  3. Go to Settings and save the API key. Saving the key starts the first pull synchronization.
  4. Complete domain verification as instructed by the platform. The extension serves the verification resource at /.well-known/veratag-verify-{token}.txt.
  5. 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.

Example of a vera[tag] disclosure displayed on a TYPO3 site

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:

  1. Connect — An administrator configures the channel API key and domain verification.
  2. Synchronize — The TYPO3 Scheduler periodically fetches disclosure data; an optional authenticated push endpoint accepts platform-originated changes.
  3. Store — The PHP persistence layer maintains local disclosure and synchronization records in TYPO3 database tables.
  4. Resolve — On a page request, a TYPO3 frontend middleware selects applicable disclosure data and determines the language according to the configured mode.
  5. 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 ci installs dependency versions locked in package-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:release rebuilds 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.txt lists relevant third-party components and their licenses.
  • TRADEMARKS.md explains 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.
vera[tag]

Content transparency, connected.

Developed and maintained by Kladero GmbH.
vera-tag.com