Apostrophe 4.34.0: AI usage tracking and Assembly polish

[BoDonkey]

Hello Apostrophe Community!

Apostrophe 4.34.0 is a maintenance release that builds on the AI connectors and Astro work in 4.33.0, with a focus on Assembly, our multitenant platform for delivering sites to your own customers. AI usage can now be recorded and attributed to each tenant site, and in Assembly projects using Astro, every site now serves its own robots.txt and llms.txt. The release also brings translation and accessibility fixes in the admin UI and dependency upgrades that address several security advisories.

AI Usage Tracking

The new @apostrophecms/ai:usage event delivers one record for each provider response, with its token counts. The new usageMetadata option lets you attach your own attribution to each record, which can help when pricing or billing AI use for your own customers. In Assembly projects, every record automatically names the site it was spent on, or the dashboard. If you offer AI-powered features to your customers, you can see what each tenant uses and price or bill accordingly. Please note that AI providers' billing policies are subject to change. See Tracking AI usage in the documentation for details.

The Anthropic, OpenAI and Google adapters also default to newer models. The Google adapter now uses the Gemini Interactions API, so earlier Gemini transcripts lose their reasoning context.

Each Assembly site serves its own robots.txt and llms.txt

Astro now routes literal content files such as robots.txt and llms.txt to the right site in multisite projects, using the new literalRoutesScope option of @apostrophecms/url. The SEO module also answers these files with a proper 404 or 500 when it has nothing to serve, rather than an empty 200.

Security

This release fixes 11 responsibly disclosed security vulnerabilities in core, Import/Export and sanitize-html. None are rated high severity, but we recommend all users upgrade promptly. This release addresses:

• Access control gaps in the REST API, where viewPermission fields could appear in related documents and write responses, the public API's sort and filter options could get around publicApiProjection, and the slug check could reveal whether private content exists
• Publication roles, which are now enforced when editing or creating published content, including through Import/Export
• Stored XSS through widget style attributes and color field values
• Import/Export hardening: imports can no longer fill the disk or overwrite content they did not offer to replace, cleanup routes require a login, and export downloads use unguessable filenames
• A crash in sanitize-html 2.18.0 when re-sanitizing certain discarded iframes

Full details and reporter credits are in the changelog below and in the published GitHub security advisories.

A few of these fixes change behavior you may be relying on:

• Editing published content now requires the type's publishRole. An editor can no longer change published documents of a type whose publishRole is admin, including through the REST API, without going through the normal publishing workflow.
• Public API requests ignore sorts and filters on fields outside publicApiProjection. If logged-out visitors or your front end sort or filter on a field, add it to the projection. Full text search is unchanged, so mark sensitive text fields searchable: false.
• Color fields discard values that are not entirely a valid color, such as a color with extra text before or after it.
• The slug-taken route now requires the ability to edit content, so guests can no longer call it.

Additional Improvements

• Smaller page data for Astro: Page data sent to Astro and other external front ends no longer includes bestPage, which made the payload about a third larger. Use page instead. The changelog below explains how to restore it if you need to.
• Translation and accessibility fixes: Translations for German, Spanish, French, Italian, Portuguese (Brazil) and Slovak are more complete and more accurate, and screen readers now announce icon-only widget buttons by name.

---

How to Update

Update your projects with npm update and let us know what you think on our roadmap.

---

The “stable” option

Everything above reflects our standard “latest” releases. Customers also have the option of following our “stable” release channel. The difference is simple: stable releases receive new features one full quarter later, but receive bug fixes and security fixes at the same time as “latest.” For this to be an effective way to increase stability, customers still need to actively evaluate “latest” so that they have a meaningful head start on what is coming in “stable.” Customers interested in following this path should reach out for complete information on how to point their dependencies to “stable.”

Everything we ship as “latest” is 100% ready for production. The “stable” series is an option for those with a large investment in training, automated testing, etc. It allows delayed implementation of new features without falling behind on fixes.

🚀 Happy coding!

---

Apostrophe 4.34.0

Adds

• Added the @apostrophecms/ai:usage event: one record per provider response, with its own token counts, and the ability to add attribution via the new usageMetadata option. This may be helpful in pricing and billing AI use by your own customers. Please note that the billing policies of AI providers are subject to change.
• Astro now routes literal content files such as robots.txt and llms.txt to the right site in multisite projects, using the new literalRoutesScope option of @apostrophecms/url.

Changes

• The Anthropic and OpenAI AI adapters now default to Claude Haiku 5.5, Sonnet 5.5 and Opus 5.5, and to GPT-6 Luna and GPT-6.1 Sol.
• The Google AI adapter now speaks the Gemini Interactions API and defaults to newer Gemini models; earlier Gemini transcripts lose their reasoning context. This also fixes Gemini rejecting conversations with tool calls made by another provider, and Gemini 3.1 Flash-Lite Image rejecting high quality requests.
• Page data sent to Astro and other external fronts no longer includes bestPage, which only serves to populate page and made the payload a third larger; use page instead. A project that still needs it can restore it by extending the pruneDataForExternalFront(req, template, data, moduleName) method of @apostrophecms/template and setting data.bestPage = req.data.bestPage.
• Test suites that use the testModule option now run under mocha 12.
• Updated dependencies: sanitize-html@2.18.1, uploadfs@1.28.1

Fixes

• Fields rendered in place with AposField in a widget can be edited as soon as the widget is added or saved in Astro, rather than only after the page is refreshed. Rich text fields in such a widget no longer appear as escaped markup during live preview and inline editing. Empty fields of a widget that was just saved can be selected and edited on the page right away, as they can be in a Nunjucks or JSX project.
• Fixed icon-only widget breadcrumb operations, such as the Styles button on a layout column, being announced by screen readers as "Provide a Button Label". These buttons now take their accessible name from the operation's label, or from its tooltip when no label is set. This also covers breadcrumb operations added by project code.
• Widget editor modals now show server-side validation errors on the fields they belong to. When a widget's sanitize method throws an invalid error whose data.errors entries name fields by path, the modal switches to that field's tab and displays the message beneath it. Previously the save was blocked with no feedback at all.
• The image editor in the media manager now disables "Save" until the image's fields are changed, as other editors do.
• Cancelling an image selection in the media manager now asks to discard the selection rather than changes to the active image.
• The decorative shadow above the media manager's editor footer no longer shows a "Shadow" tooltip or reads as an image to screen readers.
• Choosing images, pieces or pages for a relationship field no longer displays an untranslated tooltip such as apostrophe:image wherever the mouse hovers in the manager modal.
• Relationship chooser modals (pages, pieces and images) carry a data-apos-test="relationship-chooser:<field label>" attribute, so end-to-end tests can find them now that the field label is no longer rendered as a title attribute on the modal.
• Preserve UTF-8 filenames when uploading attachments, rather than converting incorrectly to latin1 as multer does by default. Thanks to yoshimasa sugawara for this fix.
• Command line tasks that printed to the console before structured logging do so again, including in production.
• Fix interpolation variables that were mistyped or translated in several locales, which made i18next render them as empty strings. The batch localization notifications now show the localized and skipped document counts in German, Spanish, Italian, Portuguese (Brazil) and Slovak, the minimum image size shows its dimensions in Spanish and Slovak, and the import error notifications show the file type in all translated locales. The German "Create new" command menu label no longer has the English text appended. A test now checks that bundled translations only use variables declared in en.json. Thanks to Michael Lip for the contribution.
• Fixes translated strings whose interpolation variables were misspelled or translated (e.g. {{ skipcount }}, {{ ancho }}, {{ format }}), so values like counts, image dimensions and file types now render in de, es, fr, it, pt-BR and sk. Removes two stale Slovak tag keys.
• Adds missing de, es, fr, it, pt-BR and sk translations for the Recently Edited manager, background styles, layout column editing, breakpoint preview, publication status and other admin UI strings, the import-export draft and AI translation options, and the AI Helper "Generate Variant" button.
• Corrects mistranslated, truncated and partly English admin UI strings in de, es, fr, it, pt-BR and sk. Slovak plurals now use the numbered forms i18next expects for Slovak (key_1 for 2–4, key_2 for 0 and 5+), so counts no longer always show the singular. Fixes the German date format rendering "Uhr" as an hour.

Security

• Upgrade csv-parse to 7.x to address a security advisory.
• Upgrade nodemailer to 10.x to address several security advisories.
• For anonymous REST API requests restricted by publicApiProjection, the sort query parameter and the per-field filter query parameters could operate on fields excluded by the projection, revealing the relative order of hidden values or which documents had a given hidden value. Sort keys and field filters not permitted by the projection are now ignored for these requests. In addition, the related pages embedded in anonymous page REST API responses (_ancestors and _children) were not limited to publicApiProjection when the projection included path; they now are. Authenticated requests and API key requests are not affected. Only sites that set publicApiProjection were affected. Full text search (search, autocomplete) is unchanged: it covers every field not marked searchable: false, exactly as the public site search does, so sensitive text fields should be marked searchable: false (CWE-200, CWE-639, GHSA-rqgm-cfrp-4hx8). Thanks to N.HARSHA VARDHAN for reporting the vulnerability.
• Fields restricted by viewPermission are now removed from every document in every REST API response (apiRoutes and restApiRoutes of all modules) for a user who lacks that permission, not just from the documents requested from the page and piece REST APIs. This includes documents loaded through relationships (also nested and reverse relationships, and relationships inside widgets, array fields and object fields), the related pages embedded in page responses (_ancestors and _children), the home page response, page autocomplete results, areas rendered with render-areas, and the documents returned after a write: POST, PUT and PATCH (including archiving, restoring and moving pages), publish, unpublish, revert, localize and share, as well as GET /api/v1/@apostrophecms/doc/:_id and a single document version. The document version history also no longer reveals changes to those fields: the change list of a version (GET /api/v1/@apostrophecms/document-versions/:versionId/changes) leaves them out, the change counts of the version list and of a single version no longer count them, and a version's document with annotate=1 no longer highlights them as changed. Saving a document without those fields in the request body still leaves their stored values untouched, as before. Each document is filtered according to its own type's schema. A project query parameter can also no longer exclude type or metaType, which could previously be used to keep a page's restricted fields in the response. The reported problems with GET /api/v1/@apostrophecms/page/:_id, which in 4.32.2 and earlier ignored type-level viewRole and did not remove viewPermission fields, were already corrected in 4.33.0 and are now covered by additional tests. Enforcing viewRole on that route was always the intended behavior, and the earlier behavior was a bug that should not have been relied upon. This only affects sites that use viewPermission. Anonymous visitors were affected only where a publicApiProjection includes a relationship to documents of a type with such fields (CWE-200, CWE-863, GHSA-vh56-5m88-39rq). Thanks to harshavardhan98899-lab for reporting the vulnerability.
• The slug-taken route of @apostrophecms/doc told any logged-in user, including guests who cannot edit anything, whether a slug was in use, even by documents they could not view. It now requires the ability to edit content (the view-draft permission held by contributors, editors and admins). Because slugs are unique across all documents, users who can choose a slug still learn that it is already taken; this is inherent in globally unique slugs, and the route reveals nothing about the document beyond that (CWE-200, CWE-203, GHSA-f66c-mpj2-3r8h). Thanks to T.Jaswanth for reporting the vulnerability.
• Editing or creating the published version of a document now requires the type's publishRole. A type's publishRole was always meant to govern its published content, but an editor could change published documents of a type whose publishRole is admin, including through the REST API and Import/Export, without publishing them through the normal workflow. That was a bug and should not have been relied upon. Types with autopublish: true, types without a draft/published distinction, and permission checks made with a type name rather than a document are unchanged (CWE-285, CWE-863, GHSA-5m22-7pfq-vp65). Thanks to Mufeed VH and Vivek R for reporting the vulnerability.
• Widget style values were written into the generated wrapper's style and class attributes without HTML attribute escaping, so a project-defined free-form string style field could be used by an editor to inject additional HTML attributes into the published page. All attribute values rendered by getWidgetAttributes() and the apos.styles.attributes() helper are now escaped. Only projects that define a free-form style field are affected, and exploitation requires permission to edit the widget (CWE-79, CWE-116, GHSA-7jg5-frgc-c67w). Thanks to Fariskhi Vidyan for reporting the vulnerability.
• The color field accepted any value that merely contained a valid rgb(), hsl() or similar color, so extra content before or after the color was stored as-is. When such a color is used by a widget style field rendered inline (no selector), that content reached the wrapper's style attribute and could inject HTML attributes into the published page. The whole value must now be a valid color, otherwise it is discarded like any other invalid color. Legitimate values (hex, named colors, transparent, rgb()/rgba()/hsl()/hsla() notations, CSS variable names) are stored unchanged. Exploitation requires permission to edit content using a color field (CWE-20, CWE-79, GHSA-vmgj-9cwm-cf3h). Thanks to N.HARSHA VARDHAN for reporting the vulnerability.

Pro Modules

@apostrophecms-pro/cypress-tools 1.0.0-beta.31

Automated functional browser tests are an important part of quality assurance for enterprise websites and web applications. Cypress is an industry-standard, open-source library for carrying out automated functional browser tests. This module provides a collection of conveniences for testing ApostropheCMS sites and applications within Cypress. Contact us or visit our new pricing page to learn more.

Fixes

• getRelationshipPagesModal finds the chooser by its data-apos-test marker. Apostrophe no longer renders the relationship label as a title attribute on the modal, which the command relied on.

@apostrophecms-pro/data-set 2.1.1

This module provides an easy avenue for low-code data presentation. It creates a data-set piece for the import of comma-separated values (CSV) files. A separate widget allows for the dynamic selection of columns, and display of the data as an HTML table, or in other templates provided by the developer. Contact us or visit our pricing page to learn more.

Security

• Upgrade csv-parse to 7.x to address a security advisory.

@apostrophecms-pro/multisite 4.7.0

This module lets you have many ApostropheCMS websites running on a single codebase in a single Node.js process. Each has its own database, users, media uploads, etc. Sites can be created and managed via a dashboard site. Explore our documentation to discover how this extension can enhance your project. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Every AI usage record names the site it was spent on, or the dashboard, through the usageMetadata option of @apostrophecms/ai. See "AI usage per site" in the README.

Fixes

• Each site declares its literal content routes per host, so Astro serves every site its own robots.txt, llms.txt and similar files.

@apostrophecms-pro/multisite-dashboard 1.8.1

This extension creates the new default multisite dashboard with infinite scroll, search functionality, and the ability to save templates. This extension requires that the project also have the @apostrophecms-pro/multisite extension installed and configured. Explore our documentation to discover how this extension can enhance your project. For further details or inquiries, feel free to contact us or visit our pricing page.

Fixes

• The site:transition-shortname task no longer crashes when it has to fall back to the slug for a site's short name.

Free Modules

@apostrophecms/ai-helper 1.0.0-beta.14

This module enhances Apostrophe with AI-driven helpers. Currently this module offers:

• A button to generate an image from a text prompt via OpenAI.
• An insert menu option to generate rich text from a prompt via OpenAI.

See the extension page for more info.

Fixes

• Adds missing de, es, fr, it, pt-BR and sk translations for the Recently Edited manager, background styles, layout column editing, breakpoint preview, publication status and other admin UI strings, the import-export draft and AI translation options, and the AI Helper "Generate Variant" button.

@apostrophecms/apostrophe-astro 1.17.0

This module integrates ApostropheCMS into your Astro application.

Adds

• Astro now routes literal content files such as robots.txt and llms.txt to the right site in multisite projects, using the new literalRoutesScope option of @apostrophecms/url.

Fixes

• Fields rendered in place with AposField in a widget can be edited as soon as the widget is added or saved in Astro, rather than only after the page is refreshed. Rich text fields in such a widget no longer appear as escaped markup during live preview and inline editing. Empty fields of a widget that was just saved can be selected and edited on the page right away, as they can be in a Nunjucks or JSX project.

@apostrophecms/form 1.5.6

Allow ApostropheCMS editors to build their own forms. They can then place any form in one or more content areas across the website.

Fixes

• Corrects mistranslated, truncated and partly English admin UI strings in de, es, fr, it, pt-BR and sk. Slovak plurals now use the numbered forms i18next expects for Slovak (key_1 for 2–4, key_2 for 0 and 5+), so counts no longer always show the singular. Fixes the German date format rendering "Uhr" as an hour.

@apostrophecms/form-submission-google 1.0.4

This module adds an additional form submission option to Apostrophe Forms. It allows website managers to configure individual forms to submit to a specific Google Docs spreadsheet.

Security

• Upgrade googleapis to the latest version to address node-forge and uuid security advisories.

@apostrophecms/i18n-static 1.2.1

This module makes it possible to edit the translations of static text strings found in templates through the ApostropheCMS admin UI.

Fixes

• Corrects mistranslated, truncated and partly English admin UI strings in de, es, fr, it, pt-BR and sk. Slovak plurals now use the numbered forms i18next expects for Slovak (key_1 for 2–4, key_2 for 0 and 5+), so counts no longer always show the singular. Fixes the German date format rendering "Uhr" as an hour.

@apostrophecms/import-export 3.7.1

This module enables import and export of pages and pieces, with or without related documents such as files, images and other related types.

Fixes

• Fix interpolation variables that were mistyped or translated in several locales, which made i18next render them as empty strings. The batch localization notifications now show the localized and skipped document counts in German, Spanish, Italian, Portuguese (Brazil) and Slovak, the minimum image size shows its dimensions in Spanish and Slovak, and the import error notifications show the file type in all translated locales. The German "Create new" command menu label no longer has the English text appended. A test now checks that bundled translations only use variables declared in en.json. Thanks to Michael Lip for the contribution.
• Fixes translated strings whose interpolation variables were misspelled or translated (e.g. {{ skipcount }}, {{ ancho }}, {{ format }}), so values like counts, image dimensions and file types now render in de, es, fr, it, pt-BR and sk. Removes two stale Slovak tag keys.
• Adds missing de, es, fr, it, pt-BR and sk translations for the Recently Edited manager, background styles, layout column editing, breakpoint preview, publication status and other admin UI strings, the import-export draft and AI translation options, and the AI Helper "Generate Variant" button.

Security

• Upgrade csv-parse to 7.x to address a security advisory.
• Extracting an import archive had no limit on the size or number of the files it wrote, so a small, highly compressed archive could fill the server's disk, and a failed import left the uploaded archive, its copy in uploadfs and its partial extraction behind. Extraction now stops as soon as the archive goes over a limit on the number of entries (100,000 by default) or on the total extracted size (100 times the size of the archive, at least 64MB, by default), counted on the bytes actually written. The limits can be changed with the new importLimits option of the module. Everything an import uploaded or extracted is removed whenever it fails. Exploiting this required a logged-in user (CWE-400, CWE-409, CWE-459, GHSA-9g7p-m758-rp72). Thanks to Mufeed VH and Vivek R for reporting the vulnerability.
• When continuing an import after the user confirmed which duplicates to replace, the server trusted the list of documents and replacement targets sent back by the browser, and checked the importable type against the imported file rather than against the existing document being overwritten. A logged-in user allowed to import could overwrite documents the import never offered to replace, including documents of types they may not import, and continue the import of another user. The duplicates found by the import are now remembered on the server for the user who started it, the browser can only narrow that list down, and the type of every replaced document must be importable (CWE-639, CWE-863, GHSA-jf5h-36mg-rp6x). Thanks to Mufeed VH and Vivek R for reporting the vulnerability.
• Importing could write the published version of documents the importing user was not allowed to publish. A contributor could create or replace published content with a crafted archive, and an editor could import or update published documents of a type whose publishRole is admin. Import now refuses documents whose mode, locale and _id disagree, and relies on the corrected publishRole check in Apostrophe 4.34.0 for the rest. Exploiting this required a logged-in user allowed to import the type (CWE-285, CWE-863, GHSA-5m22-7pfq-vp65). Thanks to Mufeed VH and Vivek R for reporting the vulnerability.
• Export downloads are published under the public /uploads/exports/ URL until they expire, and their file names were built only from the site's short name, the exported type and a timestamp to the second, so anyone could guess the URL of a fresh export and download it without logging in. Export file names now include a random, unguessable id, and the type in the name is reduced to a slug so it can no longer place the file outside the exports folder. Exposure was limited: a privileged user had to have just run an export, and the download is removed after 10 minutes by default (CWE-200, CWE-330, GHSA-5gc8-frw3-3vqm). Thanks to tikisan_ for reporting the vulnerability.
• The clean-export and override-duplicates routes did not require a login. Also, clean-export would discard the pending files of an import started by someone else and mark any import job as completed, without checking who owned either. Both routes now require a logged-in user. clean-export only acts on an import uploaded by the caller, and only ends that caller's own job. Import jobs are now recorded as belonging to the user who started them. Exposure was limited because the pending import's ID is random and only shown to the user who uploaded it, so in practice an attacker could only interfere with an import they could already identify (CWE-306, CWE-862, CWE-639, GHSA-rw26-wwfc-9wvm). Thanks to Liuhuo Wan for reporting the vulnerability.

@apostrophecms/seo 1.7.1

Comprehensive SEO module providing meta field management and Schema.org structured data generation (JSON-LD) for all pages and pieces.

Fixes

• llms.txt and robots.txt no longer answer 200 when they have nothing to serve: a disabled llms.txt answers 404, and a failure while generating either file answers 500.

Utilities

sanitize-html 2.18.1

This module provides a simple HTML sanitizer with a clear API.

Changes

• Remove the deepmerge dependency, which was used only to combine tag-specific and * (all tags) entries in allowedClasses and allowedStyles. That is now done by a few lines of code within sanitize-html.

  This is not a fix for a vulnerability in sanitize-html. Security scanners such as Snyk now report CVE-2026-93753 in deepmerge, which can affect applications that merge untrusted objects, such as parsed JSON request bodies. sanitize-html only ever merged the developer's own configuration, never anything taken from the HTML being sanitized, so it was not exploitable through sanitize-html. Since we needed only a small part of what deepmerge does, we removed the dependency so that these reports no longer appear for sanitize-html users.

Security

• Since 2.18.0, the fallback markup of a discarded <iframe> was re-sanitized by a recursive call with no limit, one level per nested unclosed <iframe>. A few kilobytes of crafted input could throw RangeError: Maximum call stack size exceeded with the default options, and the nestingLimit option was not enforced across the fallback because each nested call started counting from zero. The fallback of a discarded <iframe> is still sanitized and kept, but only up to eight nested <iframe> elements (deeper fallback is escaped as text, as before 2.18.0), and the current nesting depth now carries into the nested call so nestingLimit applies to the whole output. Only 2.18.0 was affected, and the exception is thrown synchronously, so applications that catch errors from sanitizeHtml only lost the affected request (CWE-674, GHSA-c9rx-x947-fp3h). Thanks to hkmj19, JohnBeckley, and amikhailovstiltsoft for reporting the vulnerability.

uploadfs 1.28.1

uploadfs copies files to a web-accessible location and provides a consistent way to get the URLs that correspond to those files. uploadfs can also resize, crop and autorotate uploaded images. uploadfs includes S3-based, Azure-based, GCS-based and local filesystem-based backends and you may supply others.

Security

• Upgrade the optional @google-cloud/storage dependency to 8.x to address a uuid security advisory. The Google Cloud Storage backend now requires Node.js 22 or later.