Apostrophe 4.33.0: Free and improved version history, in-context field editing, and AI connectors in core

[BoDonkey]

Hello Apostrophe Community!

Apostrophe 4.33.0 brings three major improvements to the editing and development experience. Version history, called Document Versions in Apostrophe, has moved from a Pro extension into the open source core. It's also been improved to show a more detailed view of changes. String and rich text fields can now be edited directly on the page, wherever your JSX, Nunjucks or Astro templates render them. Core also gains a shared, provider-agnostic AI engine for building AI-powered features across Apostrophe. This release also includes important improvements to JSX, logging, and security, so we recommend updating promptly.

Version history: now open source and part of core

document-versions.mp4

Document version history, previously the Pro @apostrophecms-pro/document-versions extension, is now open source and built into Apostrophe core as @apostrophecms/document-versions. There is nothing extra to install and no license required. It is on for pages and pieces by default, and can be configured per type with the versions option.

It has also been reworked to show a much clearer view of what’s changed. The new interface makes it much easier to see what changed in each version, who made the change, and when. Drafts are now recorded as well as published versions, including whether AI was involved, and images and files have their own version history in the media manager. See the Document Versions guide for a full tour. Accessing this feature will work the same for editors, but experience once they open the Document Versions modal looks quite different.

If your project uses the extension, remove it when you upgrade. If you upgrade both, the extension will print a polite warning and do nothing since the feature is now in core. Your existing history is converted automatically when the site first starts. Some configuration options, REST API routes and methods have changed, so see the migration guide for the full steps, including notes for rolling deployments.

In-Context Field Editing

Areas have always been editable right where they appear on the page. Now ordinary schema fields can be too. This change makes it much easier for developers to deliver a true in-context visual editing experience for schema fields. Instead of opening the editor modal for a hero to change a headline, an editor clicks the headline on the page and types over it. Existing string fields work this way, as do fields of the new richText type, and custom field types can opt in.

This is a template choice, not a schema change. When a template renders a field with the new field tag, that field becomes editable where it appears. Fields rendered the usual way behave exactly as before, and every field stays in the editor modal and the REST API. The one exception is Astro: because it receives its data before its templates run, each field it edits in place also needs wysiwyg: true in the schema.

For example, take a widget with an ordinary string field:

// modules/hero-widget/index.js
export default {
  extend: '@apostrophecms/widget-type',
  fields: {
    add: {
      headline: {
        type: 'string',
        label: 'Headline'
      }
    }
  }
};

Rendering it with Field in the widget's JSX template makes the headline editable right on the page:

// modules/hero-widget/views/widget.jsx
export default function ({ widget }, { Field }) {
  return (
    <section className="hero">
      <Field doc={widget} name="headline" with={{ tag: 'h1' }} />
    </section>
  );
}

The Nunjucks equivalent is {% field data.widget, 'headline' with { tag: 'h1' } %}, and in Astro it is <AposField doc={widget} name="headline" tag="h1" />, with wysiwyg: true added to the schema field.

In edit mode, the editor takes on the page's own typography and takes up no more room than the text it replaces, so editing feels like typing on the page rather than filling in a form. Outside edit mode, only the value is rendered, so the tag is safe to use anywhere. See the inline editing guide for the details.

The new richText schema field type also means rich text no longer has to live in a widget inside an area. It uses the same editor, sanitization rules, and configuration as the rich text widget, so any customizations you've already made apply automatically.

AI Connectors in Core

Apostrophe now includes apos.ai, a provider-agnostic API for AI text and image generation. Features can be written once against a shared interface, while switching between Anthropic, OpenAI, Google, OpenAI-compatible services, or a local Ollama is handled through configuration rather than feature-specific integrations.

This connector engine is opt-in: no provider or API key is configured by default. It also provides shared infrastructure for tool calling, permissions, background jobs, retries, testing, and content extraction, giving current and future AI features a consistent way to work with Apostrophe content.

Our Pro modules are the first to use it:

• Automatic Translation can now translate through the AI provider already configured for the project, and now supports richText fields. Automatic translation still supports traditional providers like deepl as well.
• SEO Assistant 2.0 (major version bump, edit package.json to get it) now generates through apos.ai and no longer requires Automatic Translation. Existing projects should review the migration notes in the module README.

JSX Across Our Documentation and Starter Kits

When we introduced JSX templates in Apostrophe 4.31.0, we said we would update our documentation over time to show JSX as the preferred authoring path. The documentation now leads with JSX, and our starter kits use JSX templates as well, so we recommend starting new projects with JSX. Nunjucks remains fully supported, and the two can coexist in the same project, so existing sites can keep their templates as they are or migrate one at a time.

Security

This release fixes 22 responsibly disclosed security vulnerabilities across core and several supporting packages, three of them rated high severity. We recommend all users upgrade promptly. This release addresses:

• Unauthenticated uploads that could fill the disk, in chunked uploads, the rich text CSV-to-table import and form submissions
• Authorization gaps in several REST routes, page reordering, notifications and the AI Helper's image routes
• Session and password hardening, including throttled password confirmation and cryptographically secure login tokens
• Injection and XSS fixes in the admin UI, sanitize-html, Import/Export, CAPTCHA verification, the SQL database adapters and uploadfs

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:

• viewRole now applies to logged-out visitors, as was always intended. In particular, users (viewRole: 'admin') reached through a relationship, such as the author of an article, will no longer load for logged-out visitors in templates or public APIs. Use a separate piece type, such as an "author" type, to represent people publicly. See our public-demo repository for an updated example of this.
• apos.http.bigUploadMiddleware() now requires a logged-in user by default. A route that genuinely accepts anonymous uploads must pass its own authorize callback or authorize: false.
• If you ever deployed uploadfs with an Azure SAS token in replicateClusters, revoke or rotate that token due to token exposure. However, it should be noted that this configuration did not actually work prior to this release. So it is unlikely that it was in practical use.

Additional Improvements

Faster, more predictable undo and redo: Undo now reverses the edit itself instead of replaying your whole editing session and re-rendering the page. The page no longer flashes or jumps, the change is scrolled into view and briefly outlined, each undo is a small, fast save, and your typing history survives the page being refreshed around it.

Structured logging, everywhere: Apostrophe's structured logger now covers boot messages, warnings, runtime errors, long-running tasks, and diagnostics from modules and supporting libraries such as uploadfs and sanitize-html. Development output remains readable and colorized, while production defaults to one JSON object per line. A new top-level log option in app.js configures logging for the entire process, including multisite projects. Developers using custom loggers should review the changelog below for changes to event metadata.

Node.js 22.12 or Newer Required

Apostrophe now requires Node.js 22.12 or newer, since it relies on the ability to require() ES modules that arrived in that release. If you are on an earlier Node.js 22 release, upgrade Node.js before you update Apostrophe.

---

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.33.0

Adds

• Added apos.ai, a provider-agnostic AI API for text generation with tool calling, image generation and background jobs. Feature code is written once, against one normalized surface: switching between Anthropic, OpenAI, Google or any OpenAI-compatible service is a configuration change, not a rewrite. It is opt-in: no provider and no key are configured out of the box.

  • @apostrophecms/ai: the engine, with normalized request and result shapes, a tool registry, an agent loop, effort levels, retries, a permission seam and a mock mode for tests.
  • @apostrophecms/ai-adapter-anthropic: Anthropic (Claude) support, via the Messages API. An entry may set workspaceId (or export APOS_ANTHROPIC_WORKSPACE_ID) to send the anthropic-workspace-id header, required with an identity-linked API key that is not scoped to a single workspace.
  • @apostrophecms/ai-adapter-openai: OpenAI support, via the Responses and Images APIs.
  • @apostrophecms/ai-adapter-openai-compatible: support for any Chat Completions service (Groq, Mistral, OpenRouter, Ollama, vLLM and others) with no adapter code of your own.
  • @apostrophecms/ai-adapter-google: Google (Gemini) support, text and images through one API.

  AI actions check permissions through apos.ai.can(req, ...) rather than apos.permission.can() directly. The signature is the same, with AI policy on top: user accounts and permission groups are denied to the AI outright, for every action including reading, whatever the user's own permissions allow.

  Supporting changes, useful on their own:

  • Notifications: a notification sent with bus: true is a pure event carrier. It is never rendered, and its event is emitted on apos.bus in exactly one browser tab, then dismissed. The options object may be passed in place of the message.
  • Jobs: cooperative cancellation (reporting.isCanceling(), a cancel route and a canceled status), an expireAfter option that expires job records from the database, userId ownership that restricts the status and cancel routes, a notifications: false option for callers with their own progress transport, and the error of a failed job recorded on its document.
  • Schema: apos.schema.extract() returns the content of a doc or widget as a flat array of text and image items with dot paths, selected by the new extractable policy on field types and schema fields.
  • Widgets: widget managers implement extract(), defaulting to a walk of their own schema. Rich text and image widgets contribute their content directly, and extractable is accepted as a widget type option.

• Added a richText schema field type, so rich text is no longer available only as a widget in an area. A richText field is edited with the same editor, sanitized with the same rules, and indexed for search the same way as the content of a rich text widget.

  fields: {
    add: {
      body: {
        label: 'Body',
        type: 'richText',
        // Exactly the options a rich text widget accepts in an area,
        // merged over the `defaultOptions` of `@apostrophecms/rich-text-widget`
        options: {
          toolbar: [ 'styles', 'bold', 'italic', 'link' ],
          styles: [
            { tag: 'p', label: 'Paragraph' },
            { tag: 'h3', label: 'Heading 3' }
          ]
        }
      }
    }
  }

  Rich text is still configured in exactly one place, the @apostrophecms/rich-text-widget module: its defaultOptions, its tools and its methods govern richText fields too, so a project that has customized rich text gets the same customizations in schema fields without doing anything. To support this, the editor was factored out of AposRichTextWidgetEditor.vue into a new, reusable AposRichTextEditor.vue, used by both the widget editor and the new AposInputRichText.vue field. The widget editor keeps its name, props, events and markup, so nothing changes for existing rich text widgets or for projects that have overridden either component.

  Permalinks are stored as placeholders in a richText field, just as in a rich text widget. They are replaced with real URLs when rendered with {% field %} (or Field in JSX, or AposField in Astro). To use a richText field without placing it on the page in a WYSIWYG way, call apos.modules['@apostrophecms/rich-text-widget'].renderRichText(req, html) on the markup.

• Added the {% field %} custom tag, which outputs one schema field of a document, widget, array item or object and lets the user edit it in place, right where it appears on the page:

  {% field data.page, 'headline' with { tag: 'h1', class: 'article__headline' } %}
  {% field data.page, 'body' %}
  {% for section in data.page.sections %}
    {% field section, 'caption' with { tag: 'h2' } %}
  {% endfor %}
  

  If the field is an area, {% field %} is exactly {% area %}: same markup, same editor, same with clause. Otherwise the field type must offer an on-page editor, which today means richText and string. Any other type throws an exception naming the field and its type, rather than displaying something the user cannot edit.

  A single-line string is rendered and edited inline: Name: {% field data.page, 'name' %} keeps its place on the line when the editor arrives, rather than becoming a block of its own. The tag is chosen by the field type: a string is a span, while a string with textarea: true and rich text are a div. Nothing is printed after the closing tag, not even a newline, so a field can be followed immediately by punctuation.

  Outside of edit mode only the value is rendered, so the tag is safe to use on any page: rich text renders as it does in a widget, permalinks and all, and a string is escaped as text, with the line breaks of a textarea: true string preserved. In edit mode the editor is mounted in place, inheriting the page's own typography and taking up no more room than the markup it replaced, so nothing on the page moves when editing begins. Edits are saved exactly as an area on the page saves them, patching one field at a time. Read-only fields, and fields of a document other than the one the page is about, are displayed but not editable, just like an area. Hovering near a field outlines it and shows the same breadcrumb trail a widget has.

  The with clause accepts tag (overriding the tag the field type chose), class (or className), style, attrs, and edit: false to render a field that is never editable in place.

  Field types opt in with a wysiwyg property, and can customize the rest:

  • wysiwyg: true: this type can be edited in place.
  • wysiwygComponent: the editor component, by convention AposWysiwygInput plus the capitalized type name.
  • wysiwygRender(req, field, value): the markup for the value; escaped text by default.
  • wysiwygTag(field): the tag the value is rendered as when the template does not say; div by default.
  • wysiwygModifiers(field): extra apos-wysiwyg-field--* classes, so one type can be styled differently depending on its configuration.
  • wysiwygIcon: the icon that opens the breadcrumb trail, pencil-icon by default. An individual field can override it with its own wysiwygIcon property.

  Supporting changes, useful on their own: apos.area.renderAreaTag() and apos.schema.renderFieldTag() carry out the work of the two tags and can be invoked directly, and the with clause is now parsed by one shared implementation. The breadcrumb trail is now defined once, as a set of SCSS mixins in @apostrophecms/ui, shared by the widget and field trails. AposRichTextEditor accepts an inline prop, which drops the padding and spacing the editor wears in a widget or a modal.

• Fields can now be edited in place from JSX templates and from external front ends such as Astro, not only from Nunjucks. JSX templates get a Field helper alongside Area, which is the {% field %} tag with the same with clause:

  export default function ({ page }, { Field, Area }) {
    return (
      <article>
        <Field
          doc={page}
          name="headline"
          with={{ tag: "h1", className: "article__headline" }}
        />
        <Area area={page.main} />
      </article>
    );
  }

  External front ends receive what they need to display and edit a field under _wysiwygFields on the document, widget, array item or object the field belongs to. @apostrophecms/apostrophe-astro renders it with its new AposField component.

  When using Astro, a non-area field must be explicitly declared as WYSIWYG, by setting wysiwyg: true on the field or by adding it to the wysiwygFields array option of the module. A name in wysiwygFields that is not in the schema throws at startup. Nunjucks and JSX need no such flag, since they run inside Apostrophe. An external front end receives its data before its templates run, so it has to say in advance which fields it will render in place; annotating every field of every document on a page would add substantially to the response.

  A visitor who cannot edit a field is sent only what it takes to display it, so a page served to the public carries no editors, icons or patch keys. Fields rendered in place also carry the editor only for the document the page is actually about (the piece on a show page, otherwise the page itself); other documents rendered on the page, such as the pieces of an index page, navigation, and the global doc, are emitted as their values only.

  A field rendered in place now names its definition with data-field-id instead of carrying a copy of it in data-field, since each doc type and widget type already ships its schema to the browser.

  Supporting change, useful on its own: apos.schema.wysiwygFieldData(req, object, field, with) returns everything needed to render a field in place and edit it.

• Document Versions is now open source and ships in core as @apostrophecms/document-versions, on for pages and pieces by default and configured per type with the versions option. It provides a history of drafts and publications with the editor who saved each one and whether AI was involved, a list of what every version changed field by field, those changes marked on the document where they render, restore from a version's own entry, and Undo Publish through the history. Existing version records from @apostrophecms-pro/document-versions are converted on upgrade. See the migration guide.

• Added the direction option to @apostrophecms/login (ltr or rtl) to force the text direction of the login page and related pages (password reset, additional login requirements) regardless of the direction of the current locale. When unset, the login page keeps following the locale. Projects that override TheAposLogin.vue keep the <html dir> fix but lose the root direction class; projects that override login.html without extending data.outerLayout must set the dir attribute themselves.

• The video widget now has an in-context empty state you can paste a video URL into.

Changes

• Undo and redo on the page now reverse the edit itself, rather than replaying every edit made since the page was loaded and then rendering the whole page again. While editing, this means:

  • The page stays where it is. Only the widget or field that changed is updated, so nothing else on the page is torn down and rebuilt around you. Undo no longer flashes, and the scroll position no longer has to be pinned to stop the page jumping.
  • Undo shows you what it did. The change is scrolled into view if it is off-screen, and briefly outlined. Previously an undo could quietly change something you could not see.
  • Each press is one small save. Undo used to send the whole history — the page as it was when you started, plus every edit since, which could be hundreds of patches — and the server had to re-check the entire document each time, so undo got slower the longer you worked. Now it sends a single change, which takes the server's fast path for a single widget.
  • Typing comes back a burst at a time, and the same burst whether you undo inside a rich text editor or from the admin bar. It used to be taken back in arbitrary once-a-second slices when undone from outside the editor.
  • Rich text history survives the page being rendered again. Editing a piece, or anything else that refreshes the main content area, used to destroy every editor on the page and the typing history with it. The history now holds the editing steps rather than the editor, so it also survives deleting a widget and undoing that deletion — which used to lose everything you had typed in it.
  • Undoing typing no longer throws away your redo. A rich text editor kept a second history of its own, which could disagree with the page's: undoing typing in one widget wiped the redo of edits elsewhere, and undo appeared to do nothing at all once the editor's own history ran out.
  • An undo can no longer be quietly undone by an autosave that was still in flight. History changes go through the same queue as every other edit, in order, so an undo made while offline still reaches the server when the connection is back.
  • The publish and discard controls stay accurate. Undoing everything you did leaves nothing to publish and no draft to discard, where the admin bar used to go on offering both.
  • The history is bounded, so a long editing session no longer accumulates without limit.

  Two things are deliberately unchanged. A rich text editor in a modal keeps its own undo history, since there is no page history there to join. And code that reports edits the old way, with a bare patch, still works exactly as it did, undone by replaying the history and rendering the page again.

  For developers: context-edited now accepts { patch, inverse, target }, where inverse is the patch that takes the edit back and target describes what was edited (widgetId, anchorId or patchKey). A bare patch, as emitted until now, is still accepted.

• Logging is now fully structured. Every diagnostic Apostrophe emits (boot and cluster notices, fatal startup errors, deprecations, runtime error catches, and long-running tasks, which now report a start, periodic progress and a summary instead of a line per item) is a typed event rather than a raw console call. Program output such as task help, listings and reports is unchanged.

  • The new top-level log option configures logging for the whole process from its first line, with format, a custom logger, messageAs and filter. When present it is the entire configuration, and the legacy @apostrophecms/log and @apostrophecms/util logging options are ignored, with a startup warning listing them.
  • format defaults to auto: colorized pretty output in development, one JSON object per line in production. format: 'legacy' pins the output shape of earlier releases. APOS_LOG_FORMAT, APOS_FILTER_LOGS, NO_COLOR and FORCE_COLOR set or override this per process.
  • The moment the site starts listening is the apos-listening event, drawn as a startup banner in development and kept by the default filter in production.
  • require('apostrophe/logger') provides the same logger as a standalone factory, usable before or entirely without an apos object.
  • Libraries that have no apos object, including uploadfs, express-cache-on-demand and sanitize-html, now receive a logger from Apostrophe and join the pipeline.
  • In a call to apos.util.log and related methods, an object in final position is now treated as the event data regardless of the number of arguments, so its keys become queryable fields. Previously only a call of exactly (message, object) was read that way.
  • The logger's severities are debug, info, warn and error, and its first argument is always an event type. There is deliberately no log method: calling one throws an error naming the four severities.
  • For custom loggers, the message no longer carries the '<module>: <event-type>' prefix; read the module and type fields instead. apos.util.warnDev no longer prefixes a warning icon.
  • An event's stack is now the error's own stack string, rather than an array of trimmed lines with the first one dropped.

• Errors passed to next(err) by Express middleware are now logged as structured request-error events and answered with JSON for the API, external front ends and any client not preferring HTML, and with plain text for browser navigations, instead of Express's raw stack on stderr and its HTML error page.

• Notifications now expire at the database level, rather than lingering forever when nothing dismisses them and being re-sent on every admin page load. The lifetime is set by the new expireAfter option of the @apostrophecms/notification module, in seconds, defaulting to 86400 (one day); set it to 0 for the previous behavior. A one-time migration clears the existing backlog.

• Reduced the size of the logged-in admin UI JavaScript bundle by roughly 200KB minified (about 90KB gzipped) with no change in behavior. lodash and @paralleldrive/cuid2 are no longer bundled into the admin UI; the few functions the browser needed from them now come from small, dependency-free implementations in apostrophe/lib/beneath.js. Server-side id generation (apos.util.generateId) still uses cuid2. Because beneath.js is an ES module that is also loaded on the server, Apostrophe now requires Node.js 22.12 or newer (for require(esm)), and the package's engines field has been updated accordingly.

• A relationship field with an array withType now fails at startup, instead of passing validation and throwing on every query that loads it.

• The orphaned document type warning at startup now says "collection" rather than "mongodb collection", so it no longer misreports the database on SQLite and other non-MongoDB projects.

Fixes

• The undo and redo keyboard shortcuts no longer capture Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z while a modal is open, which rolled back page changes the editor could not see. Native text undo works inside dialogs again, and page-level undo and redo work as before when no modal is open.
• The rich text widget bubble menu now stays within its container (including the piece editor modal body beside the right rail) and wraps toolbar controls onto additional rows instead of being clipped.
• Rich text permalinks are now substituted as quoted href attributes. Previously they were emitted as <a href=/contact> rather than <a href="/contact">, so a URL containing a space became two attributes. This affects both rich text widgets and richText fields.
• Relationship autocomplete suggestions are now ordered by how well they match what you typed, so typing "about" puts "About Us" first. Previously they were sorted by relationshipSuggestionSort (most recently updated first, by default), which now applies only to the suggestions listed for an empty input.
• Fixed the breadcrumb trail of a widget, or of a field edited in place, picking up the site's own list styling, such as a ::before checkmark on every crumb.
• Fixed a field edited in place with {% field %} leaving the browser's copy of its widget out of date, so that copying, cutting, duplicating or opening that widget's editor could quietly undo the user's typing.
• Fixed fields rendered by {% field %} occasionally becoming uneditable until the next full page load, while areas on the same page stayed editable.
• apos.notification.dismiss() no longer creates a stray database document when the notification it names is already gone.
• retryUntilUnique no longer retries an _id collision that fixUniqueError handlers cannot resolve.
• apos.migration.each now closes its cursor when the iterator throws, instead of leaving it open.

Security

• apos.http.bigUploadMiddleware() now requires a logged-in user by default, and the aposBigUpload protocol it implements has been hardened (CWE-400, CWE-306, CWE-770, GHSA-86wm-68pq-5jwq).

  The middleware accepted an optional authorize callback, but a route that did not supply one processed start, chunk and end requests from anyone. Since the protocol allocates server-side upload state and writes chunks to uploadfs before the route's own handler runs, any permission check made by the route was made too late. An unauthenticated request could create upload records, store chunk data and drive filesystem work on a site using such a route. Specifically:

  • The middleware now refuses any request without req.user unless the route supplies its own authorize callback. Authorization runs before the request body is parsed, so an unauthorized request no longer reaches multer or leaves a temporary file behind. A route that genuinely accepts anonymous big uploads may pass authorize: false to opt out, and is then responsible for its own protection against abuse. Only false opts out: any other non-function value now throws at startup, so a misspelled or undefined variable cannot quietly leave a route open.
  • The client-declared chunk count per file is now required to be a positive integer (or zero, for a zero-byte file) no greater than the new bigUploadMaxChunks option (default 10000, allowing a 40GB file at the client's 4MB chunk size), and the number of files may not exceed the new bigUploadMaxFiles option (default 10). The count drives a loop over uploadfs both when assembling a file and when cleaning it up; a declared count of Number.MAX_SAFE_INTEGER left cleanup running effectively forever, and because expired uploads are cleaned up at the start of every new one, one such record stalled every later upload on the site. Cleanup also bounds the chunk count and the number of files it reads back from an existing record, so a record written before this release cannot hang it.
  • When assembling an upload fails partway through end, the temporary files already assembled for it are now removed rather than left behind.
  • A failed end request no longer crashes the process. A request naming an upload id that does not exist sent its response and then passed null to the background cleanup routine, producing an unhandled rejection, which by default terminates Node. As a backstop, the middleware no longer returns a promise to Express, which ignores it; anything that rejects on the way to the route is now logged and answered with a 500.
  • The upload id sent to chunk and end is now laundered to a string. As an object it reached the MongoDB selector as a query operator, so aposBigUpload[id][$ne]= selected an arbitrary upload in progress rather than the caller's own (CWE-943). Uploads additionally record the user that started them and are only readable by that same user.
  • start, chunk and end now report a rejected request with its own status code (400 or 404) instead of a blanket 500, a 500 carries the underlying error and stack to the log rather than an empty event, and a refused request is logged without a stack.

  Thanks to Kai Zhi and Bp0lr for reporting the vulnerability, and to Bp0lr for contributing additional hardening.

• The rich text widget's CSV-to-table upload route accepted uploads from anyone, including logged-out visitors, and never removed the temporary file it staged on disk, whether the upload was rejected or accepted. Repeated requests could fill the system temporary directory. The route now requires the same permission as uploading attachments (checked before anything is written to disk), limits uploads to a single file of at most csvTableMaxSize bytes (a new rich text widget option, 10MB by default), and always removes the temporary file when the request completes (CWE-459, CWE-400, CWE-862, GHSA-qhcq-9pm2-c9w9). Thanks to Bp0lr for reporting the vulnerability.

• The project query builder now discards field names containing __proto__, constructor or prototype segments, as defense in depth against a denial of service in the SQLite and PostgreSQL adapters. See @apostrophecms/db-connect below for details (CWE-1321, CWE-400, GHSA-j5rq-xfvr-p969). Thanks to Daniel Coles and Jace for reporting the vulnerability.

• The page REST API now enforces view permissions when fetching a single page, when fetching the full page tree (all=1) and when autocompleting page titles. Previously these requests skipped view permission checks, so users could read pages they were not allowed to view: with a publicApiProjection configured, anonymous visitors could see the projected fields of loginRequired pages, and logged-in contributors and editors could read pages whose type has a viewRole above their role. The page tree still includes pages the user can view but not edit. Fields restricted with viewPermission are now also removed from single-page responses, as they already are for pieces. In addition, a viewRole set on a page or piece type now applies to anonymous site visitors too, as was always intended; before this change it only restricted logged-in users, a bug that should not have been relied upon (CWE-285, CWE-862, GHSA-2j32-q6rx-h844). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

• Reordering a page among its siblings under the same parent now requires permission to create pages under that parent, just like moving a page to a new parent or inserting a page there. Previously that check only applied when a page moved to a different parent. As a result, a user who could edit one page nested under a restricted parent (for example a page type with editRole: 'admin') could reorder it and so change the rank, and therefore the navigation order, of that parent's other children, which they had no permission to edit. Reordering within the archive is still allowed (CWE-862, GHSA-2jrp-qc93-h2j8). Thanks to Daniel Coles for reporting the vulnerability.

• Confirming the current password in @apostrophecms/settings subforms, including the password change form (PATCH /api/v1/@apostrophecms/settings/password), was not throttled, so someone holding an authenticated session but not the password could guess it without limit and then replace it. These confirmations are now throttled according to the throttle options of the @apostrophecms/login module, just like logging in. Attempts are counted per user in a separate namespace, so mistakes in the settings dialog never lock the user out of the login form, and simultaneous guesses are held to the same limit as sequential ones (CWE-307, GHSA-653j-g8j7-gh54). Thanks to thota murari for reporting the vulnerability.

• The :_id/locales REST route of piece types and pages did not apply the public API check used by the other read routes, and apos.doc.getLocales() did not apply document-level view permissions. As a result, a caller could learn which locales exist for documents they are not allowed to view, including draft locales of document types restricted by viewRole for logged-in users. The route now requires the same public API access as its sibling routes, and only the locale versions of a document that the current user is permitted to view are returned (CWE-862, CWE-200, GHSA-gqh3-7856-rjjg). Thanks to Santosh Kumar Puppala and thota murari for reporting the vulnerability.

• Hardened the single-use token that moves a logged-in session to a locale served from another hostname. The token was generated with a non-cryptographic ID generator, stayed valid for an hour, could be redeemed on any hostname, and could be redeemed more than once by simultaneous requests. It is now 256 bits from a cryptographically secure source, expires after 60 seconds, is accepted only on the hostname it was minted for, and is consumed atomically. The redirect that strips it from the URL is sent with Referrer-Policy: no-referrer and Cache-Control: no-store. The session is adopted under a freshly generated session id, and an invalid token no longer wipes the visitor's existing session. @apostrophecms/passport-bridge now mints its cross-locale tokens through the same code (CWE-598, CWE-384, GHSA-hhvr-8m24-qqr3).

  In addition, the @paralleldrive/cuid2 dependency has been updated to version 3, which draws on the platform's cryptographically secure random number generator rather than Math.random. This strengthens every identifier and token Apostrophe generates with it, including login bearer tokens and password reset tokens. The format of generated ids is unchanged.

  Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

• The browser-side apos.http.parseQuery helper, which the admin UI runs on the current page's query string, let parameter names containing __proto__, constructor or prototype segments modify Object.prototype. A crafted link could therefore alter the behavior of the admin UI for a logged-in user who opened it. Such parameters are now ignored, and the parser only descends into the result's own properties. The dot-path setter used to replay undo and redo in areas is hardened the same way (CWE-1321, CWE-79, GHSA-m2m5-rw3w-cwmj). Thanks to LoGiCaL__ for reporting the vulnerability.

• The exist-in-locale route of the @apostrophecms/i18n module only checked that the user was logged in. It then reported which of the requested documents existed in a given locale and mode, without checking whether the user was allowed to view them. A low-privilege user could therefore learn whether restricted documents, including drafts, existed in a given locale. The route now reports only documents the user is permitted to view. It rejects draft mode for users who cannot view drafts, and it rejects modes other than draft and published (CWE-862, CWE-200, GHSA-vmxh-77cw-65j7). Thanks to thota murari for reporting the vulnerability.

• The notification REST API's PATCH and DELETE routes and the clear-event route did not check who was asking, so anyone who knew a notification's _id could dismiss it, delete it or clear its event, even without logging in. These routes, the single-notification GET route and the server-side dismiss method now require a logged-in user and act only on that user's own notifications. A notification belonging to someone else is left alone, the same way a notification that no longer exists is (CWE-862, CWE-639, GHSA-vwwx-px9w-crrc). The practical risk was low: notification ids are randomly generated and are only ever sent to the notification's own recipient, and there is no known way for anyone else to obtain one. Thanks to K Shanmukha Srinivasulu Royal for reporting the vulnerability.

• A doc type's viewRole option did not apply to the general public (logged-out visitors), only to logged-in users below the required role. As a result, the public could load @apostrophecms/user docs, which have viewRole: 'admin', through a relationship, e.g. via a piece type's REST API publicApiProjection or a template. viewRole was always intended to apply to the public as well, and this was a bug that should not have been relied upon. The public, and any user without a recognized role, now rank below guest, so viewRole (as well as editRole and publishRole) restricts them as intended. This may change what your site displays: if your templates or public APIs show users reached through a relationship (for instance as the author of an article), those users will no longer be loaded for logged-out visitors. Use a separate piece type, such as an "author" type, to represent people publicly (CWE-863, GHSA-xf6w-q65w-4f2w).

Pro Modules

@apostrophecms-pro/advanced-permission 3.1.0

This module provides more granular control over content permission. It allows the creation of custom groups with proscribed abilities and the ability to assign users to as few or as many groups as desired. Users and groups can also be assigned per-document and per-locale permissions allowing for fine control of who can edit and publish any document. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Changes

• A missing subpage encountered while replicating permissions is now reported as a structured log entry rather than a plain error message.

@apostrophecms-pro/automatic-translation 1.6.0

This bundle allows automatic translation of documents (pages and pieces) when localizing content. It comes with two translation providers: Google Cloud Translation and DeepL, and supports custom providers. Explore our documentation to learn how this extension can enhance your project. Once you're ready, obtain a license and install it through Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Added a new optional provider module, @apostrophecms-pro/automatic-translation-llm, shipped in this bundle. It translates through the provider already configured for the Apostrophe core AI engine (apos.ai), so a project that has configured AI once needs no translation-specific AI client, key or model. Enable it in app.js and select it with provider: 'llm'. The routing options effort, provider and model are all optional and inherit the core AI configuration. The provider module is inert in library mode (enabled: false on the main module): it does not register and does not require a configured AI stack. See the README.
• Rich text schema fields (the core richText field type) are now translated, and convert back as HTML exactly as the content of a rich text widget does. Previously they were extracted and sent, but the translated markup came back through the plain text conversion, which decodes HTML entities, so an escaped <b> returned as a real tag and corrupted the surrounding markup. Opt a field out with extractable: [ 'notranslate' ], as for any other field.
• The module now exposes extractionVersion (an integer, currently 1), a capability marker for modules integrating with the extraction API. Check it instead of feature-sniffing internal methods.
• Library mode is now documented in the README: with enabled: false the module registers no providers and no UI, but keeps the extraction API available to other modules.

Changes

• Requires Node.js 22.12 or newer, matching the Apostrophe core requirement.
• Text extraction is now built on the Apostrophe core schema content extraction (apos.schema.extract) and its extractable field policy. The module requires a core version providing it and refuses to start otherwise. Translation extracts the items tagged text, excluding those carrying the new notranslate tag.
• The legacy translate: true/false flags (at the field, field type, widget module and area widget configuration levels) are deprecated. They keep working through an automatic startup mapping (true → extractable: [ 'text' ], false → extractable: [ 'notranslate' ]) with a once-per-boot deprecation warning. Migrating to extractable is highly recommended; see the migration guide in the README.
• Behavior change: custom field types carrying text are now translated by default. Extending string (or another text-carrying type) is enough, and fields of an enabled type no longer need translate: true of their own. Previously both the type and every field required explicit flags, so fields that silently never translated will start translating. Review your custom types after updating, and tag any field that must stay untranslated with extractable: [ 'notranslate' ].
• Behavior change: fields opted out of translation (legacy translate: false, now the notranslate tag) remain visible to other consumers of content extraction, since the legacy flag only ever scoped translation. Use extractable: false to hide content from every consumer.
• Behavior change: a container (array or area) whose content is entirely excluded from translation now still records its own field meta entry.
• The html widget now opts out of translation via extractable: [ 'notranslate' ] instead of the legacy flag. To re-enable it, override extractable in your project rather than setting translate: true; a startup warning flags that combination.
• extractText is now extractText(req, schema, values), and extractTranslationMeta now takes req as its first argument. The req-less signatures are deprecated: they use an anonymous task request and warn on every call. The recursive signature extractText(schema, values, fields, valuePath, schemaPath) is also deprecated but keeps working, with a single deprecation warning.
• The legacy extraction hooks are deprecated but remain fully functional: a widget's own getTranslationText method, and a translation type registered with its own getText via addTranslationType, are consulted exactly as before. Each hook logs a once-per-type deprecation warning; see the migration guide in the README for moving to the core extract method.
• applyFieldText now refuses a field it cannot write back safely (a missing value path, a failing conversion, or a target holding a non-string value such as a whole widget), leaving the document untouched and logging a structured apply-field-skipped warning instead of corrupting content or crashing the run. The number of refused fields is recorded on aposTranslationMeta.skippedFields (when non-zero) and reported as skippedFields in the afterTranslate event payload.
• Translation meta items, and the input items of the afterTranslate event, now carry the label of the field they were extracted from, when it has one. The public extractText result does not include it, so its shape still matches the legacy engine's.
• Extraction now logs a structured warning when a widget contributes a text item without a path, since such an item cannot be applied back to the document.
• A failed translation now logs the error's own stack as stack, rather than an array of trimmed lines nested in the reported error.

Fixes

• Fixed README links that pointed at a private repository, and turned the cross-reference to the "Content Extraction Policy" section into an anchor link.
• Added a homepage field to package.json, pointing at the public extension page.

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

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

• The README's "API Reference" link pointed at a private repository. Since API.md ships in the package, the link is now relative and resolves wherever the README does.
• homepage in package.json pointed at the same private repository. It now points at the public extension page.

@apostrophecms-pro/data-set 2.1.0

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.

Changes

• The warning about an already-removed temporary import file is now a structured log entry.

@apostrophecms-pro/doc-template-library 2.3.0

This module solves the "blank page problem" for developers and product managers, and makes it faster for editors to create content. doc-template-library allows for the configuration of default widgets and pre-populated content on piece or page templates, and to re-use existing layouts. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Changes

• The module's diagnostics are now structured log entries rather than plain messages.

@apostrophecms-pro/document-versions 3.0.0

Changes

• This is the final release of the extension, which has been replaced by the open source @apostrophecms/document-versions module in Apostrophe core. It has no features: installed alongside a core version that includes the module, it only logs a warning that it can be removed, and with an older core version it refuses to start. See the migration guide.

@apostrophecms-pro/import-export-translation 1.1.0

The purpose of this module is to create a specialized JSON file containing the text of the site, which can be downloaded and manually edited into a different language before being imported into a new locale. Upon import, pages from the default locale will be localized into the new locale substituting the translated text.

Changes

• Upgrade note: exports may grow. Custom field types extending string are now extracted by default, where the legacy engine required translate: true on the type. See the README.
• The module now refuses to start when the installed @apostrophecms-pro/automatic-translation is too old to extract through the Apostrophe core. This is checked via that module's extractionVersion capability marker; at least version 1 is required.
• Extraction now passes the exporting request to @apostrophecms-pro/automatic-translation, instead of using its deprecated request-less signature.
• The import result, and the import route response, now include a skippedFields count: individual fields the translation library refused to write back rather than risk corrupting a document. Each refusal is logged as a structured import-field-skipped warning naming the document and entry, replacing the former import-document-error log with its guessed "Invalid text data" message, and the rest of the document imports normally.
• The warning about a still-enabled @apostrophecms-pro/automatic-translation is now a structured log entry, and is no longer silent in production.
• A failed document import now logs the error's own stack as stack, rather than an array of trimmed lines under trace.

Fixes

• homepage in package.json pointed at a private repository, so tools that surface it, including the extension page on apostrophecms.com, offered a link that 404s. It now points at the public extension page.

@apostrophecms-pro/multisite 4.6.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

• The sites(site) configuration function now receives a second argument, { logger }, bound to the site it is configuring, so you can log from a function that runs before the site has an apos object.

Changes

• Multisite logging is now structured. The site name is a field of every entry rather than a prefix on the message, the production default format is JSON, and the log option of the root app.js (format, logger, filter) configures multisite, the dashboard and every site at once. LOG_LEVEL and VERBOSE keep working as aliases for the severity filter. A site can still take over delivery by returning { log: { logger } } from sites(site). See the Logging section of the README.
• multisite.destroy() now destroys the sites, then the dashboard, then the logger, so a shared transport is torn down once and only after everything that writes to it.

Fixes

• Corrected a race condition in the unit tests, which now pass as expected with the latest apostrophe.

@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.

Changes

• The dashboard's own diagnostics are now structured log entries rather than raw console output.

Fixes

• Fixed two README links to the @apostrophecms-pro/multisite extension that used an outdated slug, which now returns a server error.
• Added a homepage field to package.json, pointing at the public extension page.

@apostrophecms-pro/section-template-library 1.1.0

Accelerate content creation and maintain design consistency by turning your best widgets into reusable section templates. Content teams can instantly insert components without recreating layouts from scratch. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Changes

• Updated the trigger tooltip text to better describe its action.
• The module's configuration warnings are now structured log entries rather than plain messages, and the unconfigured "content" area is now reported in production too.

@apostrophecms-pro/seo-assistant 2.0.0

The SEO Assistant module generates SEO page metadata automatically through the use of AI. This extension requires that the project also have the @apostrophecms/seo extension installed. For further details or inquiries, feel free to contact us or visit our pricing page.

Breaking changes

• The assistant now generates through the Apostrophe AI engine (apos.ai), configured once for the whole project, instead of carrying its own OpenAI client. The openai dependency is gone. Configure a provider on @apostrophecms/ai; see "Migrating from 1.x" in the README.
• @apostrophecms-pro/seo-assistant-openai is retired. It still loads, so an existing app.js entry does not break the boot, but it does nothing except report that it should be removed. Its apiKey and model options no longer have any effect.
• The provider registry is removed: registerProvider, getProvider, hasProvider, getProviderManager, addCurrentProvider, getCurrentProviderManager and the currentProvider property are gone, along with the provider option that named a provider module. Custom providers become either an AI engine provider adapter or a method override on this module.
• generatePrompt now returns { system, messages }, the options the AI engine is called with, rather than an array of chat messages. The page context and the editor's instruction now travel as one user message instead of two consecutive ones, which no provider accepts.
• SEO_ASSISTANT_DEV is removed. Use APOS_AI_MOCK=1 instead, which answers every AI call offline through the engine's own pipeline.

Adds

• New effort, provider, model and reasoning options steer generation, using the AI engine's own vocabulary. All are optional; without them the assistant follows the engine's routing.
• Configuration is now validated when the site starts: no configured provider, an effort level or model that resolves to nothing, or a provider without a model each stop the boot with the configuration to paste.

Changes

• The page context is now built with the Apostrophe core schema content extraction (apos.schema.extract). This requires a core version providing it; the module refuses to start otherwise.
• The @apostrophecms-pro/automatic-translation extension is no longer required, and the enabled: false workaround it needed can be removed from your project configuration.
• The seoTitle and seoDescription fields are now tagged extractable: [ 'seo' ], which is how they are kept out of the page context. Any field carrying that tag is excluded from the context.
• Context field names now include their containers: content in an area, array or object is named body.content or rows.cell rather than the bare content or cell.
• An unexpected error while generating a suggestion now logs the error's own stack as stack, rather than an array of lines with the first one dropped.

Free Modules

@apostrophecms/ai-helper 1.0.0-beta.13

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.

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.

Security

• When accepting or making a variation of an AI-generated image that the provider returned as base64 data, the server fetched the image over HTTP from an address built from the request's Host header. This allowed a logged-in user to make the server send requests to hosts of their choosing. These images are now read directly from uploadfs, and no HTTP request is involved. The accept and variation routes also let a user act on AI images generated by other users, and the accept, list and delete routes did not check whether the user may edit any content. Users can now only accept images they generated themselves or make variations of them, and all of the AI image routes require the same permissions as generating an image. The package now has a mocha test suite (CWE-918, CWE-862, CWE-639, GHSA-527g-ff96-x6wj). Thanks to Daniel Coles for reporting the vulnerability.

@apostrophecms/anchors 1.1.1

This Anchors module adds a wrapping element with an anchor linking target around all widgets. Developers may customize or opt-out individual widget types.

Fixes

• Corrected grammar and removed an off-topic section from the README.
• Fixed broken links in the README and package.json: the license badge and "Give us a star on GitHub!" link pointed at the archived standalone repository, and the missing bugs field has been added. No code changes.

@apostrophecms/apostrophe-astro 1.16.0

This module integrates ApostropheCMS into your Astro application.

Adds

• Added the AposField component, which displays one schema field of a document, widget, array item or object and lets the user edit it right where it appears on the page, the way AposArea does for areas:

  <AposField doc={page} name="title" tag="h1" class="article__headline" />

  The value is rendered by Apostrophe, so rich text arrives with its permalinks resolved, a string arrives escaped, and a field type added by a module renders as that module specifies. A single-line string is inline: Name: <AposField doc={person} name="name" />. keeps its place on the line, and its full stop, when the editor arrives.

  tag overrides the tag the field type chose, class is added to the classes it asks for rather than replacing them, style and attrs are passed through, edit={false} never offers editing, and any other prop reaches the editor as its options.

  Apostrophe only sends the editing information for fields that ask for it, with wysiwyg: true on the field or the wysiwygFields option of the module, since it cannot tell from the data which fields a template renders in place. While developing, AposField writes a note to the terminal when it displays a field that did not ask, naming the field and the option to set. A field that was not annotated is still displayed, just not editable, so a page never breaks over it.

Changes

• Console output now carries a consistent [apostrophe-astro] prefix and honors NO_COLOR.

Fixes

• Corrected README code examples that would not run as written, along with typos and grammar elsewhere in the README.

@apostrophecms/cache-redis 1.1.1

Fixes

• Corrected README code examples that would not run as written.

@apostrophecms/favicon 1.1.4

This module allows users to edit the "favicon" (browser tab icon) of the site via the global settings of the site. As such, it pairs well with the Apostrophe palette and multisite modules.

Fixes

• Removed README references to the deprecated @apostrophecms-pro/palette extension, pointing to the built-in global styles feature instead where an equivalent exists.
• Fixed broken links in the README and package.json: the license badge pointed at the retired standalone repository, repository.directory was misspelled as packages/favison, and the missing bugs field has been added. No code changes.

@apostrophecms/form 1.5.5

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

Fixes

• Removed README references to the deprecated @apostrophecms-pro/palette extension, pointing to the built-in global styles feature instead where an equivalent exists.
• Fixed broken links in the README: the license badge and "Give us a star on GitHub!" link pointed at the archived standalone repository, and the link to @apostrophecms-pro/advanced-permission pointed at a private repository; it now links to the public extension page. No code changes.

Security

• The CAPTCHA token submitted by the browser was inserted without encoding into the server-side verification request sent to reCAPTCHA (forms and login) or hCaptcha (login), so a crafted token could add or override parameters of that request. The verification parameters are now encoded with URLSearchParams and sent as a form-encoded POST body, and tokens that are not strings are rejected without being verified (CWE-88, GHSA-44qr-rrjg-2cqq). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.
• The public form submission route wrote every uploaded file to the system temporary directory with no size or count limits, before checking which form it was for or whether that form accepts files at all. Anonymous visitors could use this to fill the disk. Uploaded files are now only accepted after the form has been identified, and only for that form's file fields; anything else is rejected before it reaches the disk. Multipart submissions are also limited in file size, file count and field count, configurable with the new uploadLimits option. The file size limit defaults to the attachment module's maxSize option if set, otherwise 20MB. Upload errors and aborted requests now stop the submission instead of processing it with incomplete data. The form widget's browser code now sends the form data before the files, which the server requires (CWE-400, CWE-770, GHSA-89mh-mm8c-mv7f). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

@apostrophecms/form-submission-google 1.0.3

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.

Fixes

• Corrected README code examples that would not run as written, along with typos and grammar elsewhere in the README.
• Fixed broken links in the README and package.json: the license badge pointed at the Blog module's license rather than this module's own, and the missing bugs field has been added. No code changes.

@apostrophecms/i18n-static 1.2.0

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

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.

@apostrophecms/import-export 3.7.0

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

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.
• Documents translated during an import are now recorded as AI-assisted versions in Document Versions.

Fixes

• The two hidden notifications used to carry the locale-differs and duplicated-docs events to the browser now dismiss themselves. Previously nothing dismissed them, so every import that hit either path left a permanent notification in the database, re-sent to the browser on every admin page load thereafter.
• Fixed race conditions occasionally seen during import.
• An expired export download that has already been removed is no longer reported as an error.
• Importing a document that a handler published during the draft insert (for example, a template on a type that is not autopublished) no longer fails with a duplicate _id error.
• Corrected README code examples that would not run as written, fixed a misplaced backtick in the format documentation, and updated links that pointed at the standalone repositories of modules since migrated into the monorepo.
• Fixed broken links in the README and package.json: @apostrophecms/import-export-xlsx was linked to its archived repository, and packages/ was missing from the homepage field. No code changes.

Security

• The importExportImport routes of @apostrophecms/import-export-page and @apostrophecms/import-export-piece-type now authorize the chunked upload before it is processed (CWE-400, CWE-306, GHSA-86wm-68pq-5jwq).

  Both routes passed no authorize callback to apos.http.bigUploadMiddleware(), so an unauthenticated request could complete the aposBigUpload start, chunk and end steps — creating upload state, storing chunk data and assembling a temporary file — before import() reached its own req.user check and rejected the import. Each route now makes that same check up front, and unauthenticated requests are refused before any upload state exists.

  The middleware in apostrophe itself now requires a logged-in user by default and bounds the client-declared chunk count, so this module is protected even without the explicit callback; the callback keeps the routes safe when installed alongside an older apostrophe.

  Thanks to Kai Zhi and Bp0lr for reporting the vulnerability, and to Bp0lr for contributing additional hardening.

• When extracting an uploaded gzip archive, the check meant to keep tar entries inside the extraction directory only looked for a literal ../ in each entry name, so names such as .. or ./.. still pointed outside of it. Entry paths are now resolved and must land strictly inside the extraction directory (absolute names are skipped too), and a failed write now fails the import cleanly and stops reading the archive rather than risking an unhandled error that stops the process (CWE-22, GHSA-97wv-p4xx-c7mg). Thanks to Arpit Jain for reporting the vulnerability.

• When importing with a :key column to update existing documents, the key column's name and value were used as-is in the database query that finds the document to update. Because gzip archives are parsed with EJSON and CSV cells are JSON-parsed, a crafted file could supply a MongoDB query operator instead of a plain value (or an operator such as $where as the column name) and overwrite existing documents it never actually identified. Key values must now be plain strings or numbers and key column names may not start with $ or contain .; rows that break these rules are reported as failed and nothing is updated or inserted for them (CWE-943, CWE-284, GHSA-jqw5-w6h3-44g6). Thanks to carfeii for reporting the vulnerability and proposing a fix, and to Anisetti Chaitanya Eshwar Prasad for independently reporting it via CSV import.

@apostrophecms/import-export-xlsx 1.2.0

This module improves @apostrophecms/import-export by adding the xlsx format.

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.

Fixes

• Updated README links that pointed at the standalone repositories of modules since migrated into the monorepo. They now point at the corresponding extension page on apostrophecms.com.

@apostrophecms/login-hcaptcha 1.3.0

This login verification module adds a hCaptcha check when any user logs into the site.

Adds

• The hCaptcha widget is now displayed in the language of the admin UI (defaultAdminLocale, otherwise the locale of the login page). The new hcaptcha.hl option of @apostrophecms/login forces a specific language.

Security

• The CAPTCHA token submitted by the browser was inserted without encoding into the server-side verification request sent to reCAPTCHA (forms and login) or hCaptcha (login), so a crafted token could add or override parameters of that request. The verification parameters are now encoded with URLSearchParams and sent as a form-encoded POST body, and tokens that are not strings are rejected without being verified (CWE-88, GHSA-44qr-rrjg-2cqq). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

@apostrophecms/login-recaptcha 1.2.1

This login verification module adds a reCAPTCHA check when any user logs into the site.

Security

• The CAPTCHA token submitted by the browser was inserted without encoding into the server-side verification request sent to reCAPTCHA (forms and login) or hCaptcha (login), so a crafted token could add or override parameters of that request. The verification parameters are now encoded with URLSearchParams and sent as a form-encoded POST body, and tokens that are not strings are rejected without being verified (CWE-88, GHSA-44qr-rrjg-2cqq). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

@apostrophecms/openapi-generator 1.1.0

This module automatically generates custom API documentation and client SDKs for your ApostropheCMS project. It discovers all routes—including Pro module endpoints—and creates comprehensive OpenAPI 3.1 specs with zero configuration.

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.

@apostrophecms/passport-bridge 1.6.1

apostrophe-passport works together with passport-google-oauth20, passport-gitlab2 and similar passport strategy modules to let users log in to Apostrophe CMS sites via Google, Gitlab and other identity providers. This feature is often called federation or single sign-on.

Fixes

• The login error page now follows the direction option of @apostrophecms/login.
• Updated README links that pointed at the standalone repositories of modules since migrated into the monorepo. They now point at the corresponding extension page on apostrophecms.com.

Security

• Cross-locale login tokens are now minted through the same hardened code as Apostrophe core: 256 bits from a cryptographically secure source, valid for 60 seconds, accepted only on the hostname they were minted for, and consumed atomically (CWE-598, CWE-384, GHSA-hhvr-8m24-qqr3). Thanks to Anisetti Chaitanya Eshwar Prasad for reporting the vulnerability.

@apostrophecms/redirect 1.7.1

Manages site redirects for Apostrophe.

Fixes

• Corrected typos and grammar, removed duplicated lines from the wildcard redirect examples, and dropped an off-topic section from the README.
• Fixed broken links in the README and package.json: the license badge pointed at the Blog module's license rather than this module's own. No code changes.

@apostrophecms/scheduled-publishing 1.0.6

This module allows you to schedule publishing of your pieces (which includes pages) on specific dates.

Fixes

• Corrected typos and grammar in the README.

@apostrophecms/seo 1.7.0

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

Changes

• Diagnostics are now structured log events rather than raw console calls, so they flow through Apostrophe's log pipeline. Task listings and reports still print as program output.
• Code-like and configuration-like fields are now marked as non-translatable, so automatic translation leaves them untouched.

Fixes

• Corrected typos and grammar in the README.

@apostrophecms/sitemap 1.5.1

The Apostrophe Sitemap module generates XML sitemaps for websites powered by ApostropheCMS.

Fixes

• Per-locale sitemap generation (perLocale: true) now uses the scheme (http/https) of the site's configured baseUrl for locales with their own hostname (separateHost: true or a hostname locale option), instead of always defaulting to http. Previously, <loc> and xhtml:link hreflang URLs for such locales could be emitted as http:// even when the site and that host are served exclusively over HTTPS.

@apostrophecms/vite 1.2.0

This extension provides Vite integration for ApostropheCMS projects, enabling module bundling and hot module replacement (HMR) during development.

Changes

• Vite's own build output is now indented under the build entry it belongs to in the human-readable log formats, and becomes structured events when the log format is machine-readable. Build and HMR notices carry event types. A logged error's stack is now the stack string itself, rather than an array of trimmed lines.
• Assets from a module's public/ folder that are referenced from CSS, such as web fonts loaded with url('/modules/...'), are now emitted at their original path instead of as a content-hashed copy under assets/. As a result, apos.asset.url('/modules/...') in a template now matches the URL requested by the built CSS, so <link rel="preload"> tags for web fonts work as intended rather than downloading each font twice. Cache busting is still provided by the release directory. Note that Vite still inlines assets smaller than 4 KB into the CSS, so such small fonts should not be preloaded.

Fixes

• Fixed the assetsDir build option, which was misspelled and silently ignored.
• Corrected three typos in the README's asset import and @/ alias documentation.

Utilities

@apostrophecms/cli 3.7.1

The Apostrophe CLI is a cross-platform starting point for creating and configuring ApostropheCMS projects, providing a simple boilerplate generator and wrapping other useful functions into an easy to use command line tool.

Changes

• Updated the README for the new create action.

@apostrophecms/db-connect 1.1.0

Adds

• Added support for TTL indexes (expireAfterSeconds) to the PostgreSQL and SQLite adapters. As in MongoDB, a background task removes expired documents every 60 seconds.
• The driver's EJSON (Extended JSON) is now exported, so Apostrophe modules can serialize documents without a direct driver dependency.

Fixes

• The PostgreSQL cursor now returns its pooled connection when iteration stops early: on a query error inside next(), and when a for await loop exits through break, return or a throwing body. Previously each abandoned cursor kept a connection checked out for the life of the process.
• The PostgreSQL adapter's sort() now orders numbers numerically instead of as text, so 10 no longer sorts before 2, and the children of a page with ten or more of them stay in rank order.

Security

• On the SQLite and PostgreSQL adapters, the in-memory helpers that apply projections and update operators to dotted field paths did not stop a path from walking into Object.prototype or other built-ins shared by the whole Node.js process. Since the project query builder of the REST API accepts field names from logged-in users with editing access, a single request could delete a built-in method such as hasOwnProperty and break the site for every user until restart. Field paths containing __proto__, constructor or prototype are now ignored, and the helpers only traverse properties a document actually has, never inherited ones. As defense in depth, the project query builder now also discards field names containing those segments. The default MongoDB adapter was not affected (CWE-1321, CWE-400, GHSA-j5rq-xfvr-p969). Thanks to Daniel Coles and Jace for reporting the vulnerability.

apostrophecms-openapi 1.1.1

The official OpenAPI 3.1 specification for the ApostropheCMS REST API. Explore endpoints interactively, mock the API for rapid prototyping, or generate type-safe SDKs in your preferred language.

Fixes

• Updated README links that pointed at the standalone repositories of modules since migrated into the monorepo. They now point at the corresponding extension page on apostrophecms.com.

boring 1.1.2

Changes

• The package is now linted with the shared Apostrophe ESLint configuration. No behavior change.

eslint-config-apostrophe 6.1.0

An ESLint configuration for ApostropheCMS core and official modules.

Adds

• Added a new eslint-config-apostrophe/strict entry point that promotes no-console to an error in server-side code, for projects ready to enforce it.

Changes

• no-console is now a warning for server-side code, where diagnostics belong in Apostrophe's log pipeline rather than on the console. It was already an error in browser and test code.
• Browser code in ui/ written as .mjs is now recognized as browser code, like its .js neighbors.

express-cache-on-demand 1.1.0

Express middleware providing "on demand" caching that kicks in only when requests arrive simultaneously.

Adds

• Added a console-shaped logger option. Apostrophe passes one, so the unsupported-response error now joins its log pipeline.

launder 1.7.2

Fixes

• Added the missing LICENSE.md file. The license type was always correctly stated as MIT. Thanks to Leonardo Cardozo Vargas for pointing out the omission.

sanitize-html 2.18.0

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

Adds

• Added a logger option: pass any console-shaped object, with debug, info, warn and error methods, and sanitize-html's own diagnostics are delivered to it rather than to the console, so an application with its own logging pipeline can route them. Missing methods, and no option at all, fall back to the console.

Changes

• sanitize-html's diagnostic messages no longer include decorative line breaks and a warning icon, so each is now a single line of text. Their wording is otherwise unchanged.

Fixes

• allowedSchemesByTag is now applied to srcset and imagesrcset URLs. Previously the per-tag lookup used the attribute name instead of the tag name, so these attributes always fell back to the global allowedSchemes and ignored a tag-specific scheme allowlist.
• Starting in version 2.17.6, markup preserved inside a disallowed iframe tag was escaped, a change in behavior caused by an upstream change in htmlparser2. This "fallback markup" is now preserved without escaping, and is still fully sanitized according to the same rules as the original input. Thanks to sumitjhacodes for the fix.

Security

• When meta was allowed together with its http-equiv and content attributes, the destination URL of a <meta http-equiv="refresh" content="0;url=..."> was never checked against allowedSchemes, because it is embedded in content rather than being an attribute of its own. So javascript:, data: and other disallowed destinations passed through. The refresh URL is now extracted the way browsers do it, allowing for the different spellings, separators, quoting and letter case of url=, and checked against allowedSchemes (or allowedSchemesByTag.meta). If it is rejected, or the content cannot be parsed as a refresh, the content attribute is removed. content on other meta elements is unchanged. The default configuration does not allow meta and was not affected (CWE-79, CWE-601, GHSA-cv27-6wvh-8x7j). Thanks to adrbogacz for reporting the vulnerability.
• The check that drops SVG animation elements (animate, animateColor, animateMotion, animateTransform, set) when they retarget a URL attribute such as href compared the full tag name, so a namespace-prefixed spelling like svg:animate was not recognized when such tags were allowed (for example with allowedTags: false). In XML serializations such as XHTML or standalone SVG, the prefixed element is a real animation element and could retarget a link to a javascript: URL after sanitization. The element and attributeName are now matched by their local names, ignoring any prefix (CWE-79, CWE-184, GHSA-374f-7chj-9948). Thanks to Kai Aizen (SnailSploit) for reporting the vulnerability.
• When noscript is listed in nonTextTags, the discarded region could end too early. Browsers with scripting enabled treat <noscript> content as raw text up to the first </noscript>, but the underlying parser treats it as markup, so an end tag for an enclosing element inside <noscript> closed it implicitly and the rest of its content was emitted as ordinary sanitized markup. The discard region now continues until the point where a browser would end the <noscript> element, while implied closes of other nonTextTags such as <option> behave as before (CWE-79, CWE-436, GHSA-x3q4-9hxx-gx8m). Thanks to joaquiniglesiaslug for reporting the vulnerability.

sluggo 1.0.1

Changes

• The package is now linted with the shared Apostrophe ESLint configuration. No behavior change.

uploadfs 1.28.0

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.

Adds

• Added a console-shaped logger option, documented in the README. Apostrophe passes one, so uploadfs diagnostics now join its log pipeline.

Security

• When the Azure backend was configured with a SAS token (sas: true), getUrl() returned a base URL that still carried the SAS token as its query string, so the credential was included in public attachment URLs (CWE-522, CWE-200, GHSA-hhph-8536-gfq5). getUrl() now strips the query string from the container URL, so public URLs contain no credentials and are well formed. The top-level sas option is now also honored when replicateClusters is not used, as documented.

  The practical impact is expected to be very limited, because this configuration could not have worked in production:

  • The file path was appended after the query string, which altered the signature, so every attachment URL generated this way was broken. A site in this state would not have displayed any images or served any file downloads.
  • The top-level sas: true option was ignored, so a SAS token configured that way was treated as an account key and could not authenticate. Only a sas: true setting inside replicateClusters took effect, and only when that was the first cluster listed.
  • Sites using the cdn option never had the token in their URLs.

  If you ever deployed uploadfs with a SAS token in replicateClusters, revoke or rotate that token.

  Thanks to Kimi Security Team for reporting the vulnerability.

• uploadfs did not validate the paths passed to its methods, so an application that passed an untrusted path to copyIn, copyOut, streamOut, remove, enable or disable could read, write, delete or change the permissions of files outside the uploads folder when using the local backend. Apostrophe itself builds these paths from generated ids and sanitized file names, but uploadfs now enforces this on its own: paths containing .. segments are refused with an error for every backend (this also stops keys that cloud SDKs would normalize into another bucket or container), and the local backend additionally verifies that every filesystem path it touches resolves to a location inside uploadsPath (CWE-22, GHSA-gmfx-5g6x-rr72). Thanks to loulu1ou for reporting the vulnerability.