apostrophe 4.28.0 → 4.29.0

package/CHANGELOG.md

@@ -1,6 +1,37 @@
 # Changelog
 
-## 4.28.0
+## 4.29.0 (2026-04-15)
+
+### Adds
+
+- Added support for pretty URL file attachments in the static build metadata pipeline. When `@apostrophecms/file` has `options.prettyUrls` enabled, the `getAllUrlMetadata` API now annotates affected attachments properly. The backend streaming proxy route was also fixed to correctly resolve relative uploadfs URLs during static builds.
+- Introduced Recently Edited manager as Admin Bar action, next to the existing Submitted Drafts. Allows modules to contribute filter choices.
+- Fix batch operations executed in a modal in a different locale causing wrong browser URL rewrite
+- Add background preset to the Styles Editor, supporting image, color, and gradient background CSS generation.
+
+### Fixes
+
+- Fix a focus trap bug where in the context menu focus would jump back to the first element when reaching the last one.
+- Bug fix: the "pretty URLs" feature of `@apostrophecms/file` is now compatible with locale prefixes.
+- Removed misleading return from `pruneDataForExternalFront`, a method intended to be overridden to modify data "in place" before it is sent to Astro or a similar frontend.
+- Fix layout column breadcrumb operations leaking in layout edit mode.
+- Fix edge case where widgets having styles and fields at the same time would show "Ungrouped" tab. Add `hideSingleTab` option that can be enabled in any widget to hide tabs from the widget editor when there is only one tab containing fields. This option can also be enabled globally in `@apostrophecms/widget-type` options.
+- Add background preset, supporting image, color and gradient background CSS generation.
+
+### Changes
+
+- Combine Styles and Column configuration in a single Styles Editor experience.
+- Use shorter placeholder text for relationship inputs in small/micro contexts.
+
+### Security
+
+- Fix an XSS vulnerability allowing arbitrary markup to be inserted via the "SEO Title" or "Meta Description" fields provided by the `@apostrophecms/seo` module. The fix requires upgrading BOTH `apostrophe` and `@apostrophecms/seo`. A new mechanism for safely emitting JSON nodes has been introduced to make this type of vulnerability unlikely in the future. Thanks to [K Shanmukha Srinivasulu Royal](https://github.com/Chittu13) for reporting the vulnerability.
+- Fixed a security hole in the `.choices()` and `.counts()` query builders: formerly, these query builders could be used by the public to exfiltrate schema fields not included in the `publicApiProjection`, or fields locked down with a `viewPermission` property. Thanks to [offset](https://github.com/offset) for reporting this issue, which was not made public prior to the release of the fix.
+- Fixed an XSS vulnerability in color fields, which formerly accepted `-` followed by anything, including `</style>`, which could be used to inject other markup. Thanks to [restriction](https://github.com/restriction) for reporting the issue and proposing the fix.
+- Resolved a `publicApiProjection` bypass vulnerability for piece types. Thanks to [restriction](https://github.com/restriction) for reporting the issue and proposing the fix.
+- Ensured a minimum 2-second delay in the password reset flow to avoid disclosing whether the email or username was valid or not. Thanks to [restriction](https://github.com/restriction) for reporting the issue and proposing the fix.
+
+## 4.28.0 (2026-03-19)
 
 ### Adds
 
@@ -8,7 +39,6 @@
 - Adds widget graph store, accessible in Admin UI.
 - Support for the new `prettyUrls: true` option for @apostrophecms/file, which enables "pretty URLs" for PDFs and other items in the file library, in exchange for a small performance impact. Edit the slug field to adjust the pretty URL
 
-
 ### Fixes
 
 - Fix a bug when rich text link open in new tab checkbox can't be cleared
@@ -27,7 +57,7 @@
 - Improve re-rendering UX while keeping the performance optimization
 - raise the user's widget z-index context only when focused
 - Hide add content buttons on rich text editing, like widget controls
--  Refine in-context focus states for calmer UX
+- Refine in-context focus states for calmer UX
 - Simplifies some in-context UI rendering checks
 - Updated dependencies
 

package/README.md

@@ -0,0 +1,142 @@
+<div align="center">
+  <a href="https://github.com/apostrophecms/apostrophe">
+    <img src="https://static.apostrophecms.com/apostrophecms/apostrophe/logo.svg" alt="ApostropheCMS logo" width="80" height="80">
+  </a>
+
+  <h1>ApostropheCMS</h1>
+
+  <p>
+    <a aria-label="Join the community on Discord" href="http://chat.apostrophecms.org">
+      <img alt="" src="https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20" />
+    </a>
+    <a aria-label="License" href="https://github.com/apostrophecms/apostrophe/blob/main/LICENSE.md">
+      <img alt="" src="https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639" />
+    </a>
+  </p>
+
+  <p>
+    <strong>Full-stack CMS for developers and content teams</strong><br />
+    Build websites with in-context editing and headless flexibility using Node.js and MongoDB.
+    <br />
+    <a href="https://docs.apostrophecms.org/"><strong>Documentation »</strong></a>
+    <br />
+    <br />
+    <a href="http://demo.apostrophecms.com">Demo</a>
+    ·
+    <a href="https://roadmap.apostrophecms.com/roadmap">Roadmap</a>
+    ·
+    <a href="https://github.com/apostrophecms/apostrophe/issues/new?assignees=&labels=bug,3.0&template=bug_report.md&title=">Report Bug</a>
+  </p>
+</div>
+
+## About
+
+ApostropheCMS is a full-stack content management system built with Node.js and MongoDB. Content creators can edit directly on live pages without switching between admin interfaces, while developers can build with modern JavaScript or use it headlessly with any frontend framework.
+
+### Key Features
+
+- **🎯 In-Context Editing** - Content creators edit directly on the live page, seeing changes instantly
+- **⚡ Headless-Ready** - Use any frontend framework while keeping the powerful admin experience
+- **🛠️ Developer-First** - Built with Node.js and MongoDB for full-stack JavaScript development
+- **📈 Scales Beautifully** - From small sites to enterprise applications handling millions of pages
+- **🔐 Enterprise Features** - Advanced permissions, workflow management, automated translations, and more
+
+## System Requirements
+
+| Requirement | Version | Installation Notes |
+|-------------|---------|-------------------|
+| **Node.js** | 20.x+ | Use [NVM](https://github.com/nvm-sh/nvm) for version management |
+| **MongoDB** | 6.0+ | [MongoDB Atlas](https://www.mongodb.com/atlas) (cloud) or local install |
+| **npm** | 10.x+ | Included with Node.js |
+
+See our [setup guides](https://docs.apostrophecms.org/guide/development-setup.html) for installation instructions.
+
+## Quick Start
+
+Get ApostropheCMS running locally in minutes:
+
+```bash
+# Option 1: Install CLI globally (recommended for multiple projects)
+npm install -g @apostrophecms/cli
+apos create my-website
+cd my-website
+npm run dev
+
+# Option 2: Use npx for one-time project creation
+npx @apostrophecms/cli create my-website
+cd my-website
+npm run dev
+```
+
+Your new ApostropheCMS site will be available at `http://localhost:3000` with a powerful admin interface at `/login`.
+
+### Prefer to Go Headless?
+
+**Get started with Astro integration** - the easiest way to build headless sites while keeping visual editing:
+
+- **[Apollo Starter Kit (Astro)](https://apostrophecms.com/starter-kits/apollo-starter-kit-for-astro-cms)** - Production-ready foundation with beautiful design system and rich content features
+- **[Essentials Starter Kit (Astro)](git clone https://github.com/apostrophecms/starter-kit-astro-essentials)** - Minimal, clean foundation for building custom designs from scratch
+
+Both starter kits provide headless CMS power with in-context editing, letting content creators edit directly on the live site while you build with modern frontend tools. Our Astro integration handles all the content fetching automatically—no REST API calls to write.
+
+**Desire a different frontend framework?** Use our REST APIs with React, Vue, Svelte, or any other framework:
+
+- **[REST API Documentation](https://docs.apostrophecms.org/reference/api/pieces.html)** - Complete API reference
+- **[Headless CMS Guide](https://docs.apostrophecms.org/guide/headless-cms.html)** - Integration walkthrough for any framework
+
+### Hosting & Deployment
+
+Choose [ApostropheCMS hosting](https://apostrophecms.com/hosting) for turnkey solutions with optimized performance and dedicated support, or deploy to [any platform where Node.js runs](https://docs.apostrophecms.org/guide/hosting.html).
+
+## Built With Modern Tech
+
+- **[Node.js](https://nodejs.org/)** - JavaScript runtime for server-side development
+- **[MongoDB](https://www.mongodb.com/)** - Flexible document database for content storage
+- **ESM Modules** - Native ES6 module support for modern JavaScript
+- **Vite** - Lightning-fast build tool and development server
+- **Modern JavaScript** - ES6+, async/await, and contemporary development patterns
+
+## Community & Support
+
+**Join other developers and content creators using ApostropheCMS:**
+
+- **[Discord](https://discord.com/invite/XkbRNq7)** - Get help, share projects, and connect with other users
+- **[GitHub Discussions](https://github.com/apostrophecms/apostrophe/discussions)** - Feature requests, technical discussions, and community support
+- **[Documentation](https://docs.apostrophecms.org/)** - Comprehensive guides, tutorials, and API references
+
+## Contributing
+
+We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help makes ApostropheCMS better for everyone.
+
+- **[Contribution Guide](https://github.com/apostrophecms/apostrophe/blob/main/CONTRIBUTING.md)** - How to contribute code, documentation, and feedback
+- **[Good First Issues](https://github.com/apostrophecms/apostrophe/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** - Perfect starting points for new contributors
+
+
+## Pro Features
+
+**For teams and organizations requiring additional features:**
+
+- **🔐 Advanced User Management** - Granular permissions, user groups, and access controls
+- **🌍 Automated Translation** - AI-powered translation with DeepL, Google Translate, and Azure
+- **📊 Analytics & SEO** - Built-in SEO optimization and content analytics
+- **⚡ Performance Optimization** - Advanced caching, CDN integration, and performance monitoring
+- **🏢 Multisite Management** - Manage multiple sites from a single dashboard with shared resources
+- **💼 Professional Support** - Dedicated support, training, and consultation services
+
+[Explore all the pro extensions](https://apostrophecms.com/extensions?autocomplete=&license=assembly&license=pro) and [sign up](https://app.apostrophecms.com/login) for a Pro license in our self-service Apostrophe Workspaces, or [contact us](https://apostrophecms.com/contact-us) to learn about licensing and support options.
+
+## License
+
+ApostropheCMS is open source software licensed under the [MIT License](https://github.com/apostrophecms/apostrophe/blob/main/LICENSE.md). This means you're free to use, modify, and distribute it for both personal and commercial projects.
+
+---
+
+<div align="center">
+  <p>
+    <strong>Ready to build something amazing?</strong><br>
+    <a href="https://docs.apostrophecms.org/">Get started with our documentation</a> or <a href="https://apostrophecms.com/contact-us">talk to our team</a>
+  </p>
+  <p>
+    <em>Built with ❤️ by the <a href="https://apostrophecms.com">ApostropheCMS team</a></em>
+  </p>
+</div>

package/defaults.js

@@ -61,6 +61,7 @@ module.exports = {
     '@apostrophecms/file-tag': {},
     '@apostrophecms/soft-redirect': {},
     '@apostrophecms/submitted-draft': {},
+    '@apostrophecms/recently-edited': {},
     '@apostrophecms/command-menu': {},
     '@apostrophecms/translation': {}
   }

package/lib/safe-json-script.js

@@ -0,0 +1,27 @@
+// Serialize `data` to a JSON string that is safe to embed inside an HTML
+// `<script>` element. `JSON.stringify` on its own does NOT escape the
+// sequences `</script>`, `<!--` or `<![CDATA[`, so untrusted data (e.g.
+// editor-provided SEO fields) in a JSON body could otherwise break out of
+// the surrounding script tag and inject arbitrary HTML/JS (stored XSS).
+// Escaping `<` as its `\u003c` form keeps the JSON valid while neutralizing
+// all of those sequences. Line and paragraph separators are also escaped
+// since they are valid in JSON but illegal in some JavaScript parsers.
+//
+// This is the single source of truth for that escaping. The template
+// `renderNodes` helper uses it to render `{ json: ... }` node bodies, so in
+// most cases you should just build a node like:
+//
+//   {
+//     name: 'script',
+//     attrs: { type: 'application/ld+json' },
+//     body: [ { json: data } ]
+//   }
+//
+// and let `renderNodes` do the right thing.
+
+module.exports = function safeJsonForScript(data) {
+  return JSON.stringify(data, null, 2)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+};

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarLocale.vue

@@ -123,7 +123,7 @@ export default {
             itemName: '@apostrophecms/i18n:localize',
             props: {
               doc: apos.adminBar.context,
-              locale
+              targetLocale: locale
             }
           });
         } else {

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBar.vue

@@ -579,6 +579,7 @@ export default {
         doc = await apos.http.get(`${action}/${this.context.aposDocId}`, {
           qs: {
             aposMode: this.draftMode,
+            aposLocale: apos.i18n.locale,
             project: { _url: 1 }
           }
         });

package/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue

@@ -83,6 +83,7 @@
           :tiny-screen="tinyScreen"
           :widget="widget"
           :options="options"
+          :breadcrumb-operations="widgetBreadcrumbOperations"
           :disabled="disabled"
           :is-focused="isFocused"
           @widget-focus="getFocus"
@@ -304,10 +305,6 @@ export default {
       type: Boolean,
       default: false
     },
-    breadcrumbDisabled: {
-      type: Boolean,
-      default: false
-    },
     generation: {
       type: Number,
       required: false,
@@ -426,7 +423,8 @@ export default {
       return apos.modules[this.moduleOptions?.widgetManagers[this.widget?.type]] ?? {};
     },
     widgetBreadcrumbOperations() {
-      return (this.widgetModuleOptions.widgetBreadcrumbOperations || []);
+      return (this.widgetModuleOptions.widgetBreadcrumbOperations || [])
+        .filter(op => op.hidden !== true);
     },
     shouldSkipEdit() {
       return !this.widgetModuleOptions.widgetOperations

package/modules/@apostrophecms/area/ui/apos/components/AposBreadcrumbOperations.vue

@@ -75,6 +75,15 @@ export default {
         return {};
       }
     },
+    // Override module breadcrumb operations.
+    // If not provided (undefined or null), operations will be pulled from the
+    // widget's module options.
+    breadcrumbOperations: {
+      type: Array,
+      default() {
+        return null;
+      }
+    },
     isFocused: {
       type: Boolean,
       default: false
@@ -130,7 +139,10 @@ export default {
       return apos.modules[this.moduleOptions?.widgetManagers[this.widget?.type]] ?? {};
     },
     widgetBreadcrumbOperations() {
-      return (this.widgetModuleOptions.widgetBreadcrumbOperations || [])
+      return (
+        this.breadcrumbOperations ||
+        this.widgetModuleOptions.widgetBreadcrumbOperations || []
+      )
         .map((operation) => ({
           component: this.getOperationComponent(operation),
           props: this.getOperationProps(operation),

package/modules/@apostrophecms/asset/lib/globalIcons.js

@@ -23,6 +23,7 @@ module.exports = {
   'arrow-expand-vertical-icon': 'ArrowExpandVertical',
   'arrow-left-icon': 'ArrowLeft',
   'arrow-right-icon': 'ArrowRight',
+  'arrow-top-right-icon': 'ArrowTopRight',
   'arrow-up-icon': 'ArrowUp',
   'binoculars-icon': 'Binoculars',
   'calendar-icon': 'Calendar',
@@ -109,6 +110,7 @@ module.exports = {
   'keyboard-tab': 'KeyboardTab',
   'label-icon': 'Label',
   'lightbulb-on-icon': 'LightbulbOn',
+  'link-external-icon': 'OpenInNew',
   'link-icon': 'Link',
   'list-status-icon': 'ListStatus',
   'lock-icon': 'Lock',
@@ -124,6 +126,7 @@ module.exports = {
   'play-box-icon': 'PlayBox',
   'playlist-edit-icon': 'PlaylistEdit',
   'plus-icon': 'Plus',
+  'recently-edited-icon': 'ClockOutline',
   'redo-icon': 'RedoVariant',
   'refresh-icon': 'Refresh',
   'resize-bottom-right-icon': 'ResizeBottomRight',

package/modules/@apostrophecms/attachment/index.js

@@ -217,6 +217,11 @@ module.exports = {
 
             await self.crop(req, _id, sanitizedCrop);
 
+            if (req.body.annotate) {
+              const attachment = await self.db.findOne({ _id });
+              return self.annotateAttachment(attachment, sanitizedCrop);
+            }
+
             return true;
           }
         ]
@@ -611,6 +616,42 @@ module.exports = {
           height: sanitizeInteger(crop.height, 0, 0, 10000)
         };
       },
+      // Given an attachment object and an optional crop,
+      // return a clone with `_urls` fully populated for all
+      // configured image sizes. For non-image attachments
+      // a single `_url` is set instead.
+      annotateAttachment(attachment, crop) {
+        const result = { ...attachment };
+        result._isCroppable = self.isCroppable(result);
+        if (crop && crop.width) {
+          result._crop = _.pick(crop, 'width', 'height', 'top', 'left');
+        }
+        if (result.group === 'images') {
+          result._urls = {};
+          if (result._crop) {
+            result._urls.uncropped = {};
+          }
+          for (const size of self.imageSizes) {
+            result._urls[size.name] = self.url(result, { size: size.name });
+            if (result._crop) {
+              result._urls.uncropped[size.name] = self.url(result, {
+                size: size.name,
+                crop: false
+              });
+            }
+          }
+          result._urls.original = self.url(result, { size: 'original' });
+          if (result._crop) {
+            result._urls.uncropped.original = self.url(result, {
+              size: 'original',
+              crop: false
+            });
+          }
+        } else {
+          result._url = self.url(result);
+        }
+        return result;
+      },
       // This method return a default icon url if an attachment is missing
       // to avoid template errors
       getMissingAttachmentUrl() {
@@ -1459,7 +1500,8 @@ module.exports = {
           uploadsUrl: self.uploadfs.getUrl(),
           croppable: self.croppable,
           sized: self.sized,
-          maxSize: self.options.maxSize
+          maxSize: self.options.maxSize,
+          imageSizes: self.imageSizes
         };
       },
       // Middleware method used when only those with attachment privileges

package/modules/@apostrophecms/color-field/index.js

@@ -32,9 +32,15 @@ module.exports = {
               throw self.apos.error('required');
             }
 
+            const isVariable = destination[field.name].startsWith('--');
             const test = new TinyColor(destination[field.name]);
-            if (!test.isValid && !destination[field.name].startsWith('--')) {
+            if (!test.isValid && !isVariable) {
               destination[field.name] = null;
+            } else if (isVariable) {
+              // CSS custom property names: only allow alphanumeric, hyphens, underscores
+              if (!/^--[a-zA-Z0-9_-]+$/.test(destination[field.name])) {
+                destination[field.name] = null;
+              }
             }
           },
           isEmpty: function (field, value) {

package/modules/@apostrophecms/doc/index.js

@@ -1553,7 +1553,8 @@ module.exports = {
         ];
 
         function validate ({
-          action, context, type = 'modal', label, modal, conditions, if: ifProps
+          action, context, type = 'modal', label, modal, conditions, if: ifProps,
+          crossLocale
         }) {
           const allowedConditions = [
             'canPublish',
@@ -1596,6 +1597,15 @@ module.exports = {
               'invalid', 'The if property in addContextOperation must be an object containing properties and values that will be checked against the current document in order to show or not the context operation.'
             );
           }
+
+          if (
+            crossLocale !== undefined &&
+            typeof crossLocale !== 'boolean'
+          ) {
+            throw self.apos.error(
+              'invalid', 'The crossLocale property in addContextOperation must be a boolean.'
+            );
+          }
         }
       },
       getBrowserData(req) {