apostrophe 4.28.1 → 4.30.0-alpha.1

package/CHANGELOG.md

@@ -1,12 +1,43 @@
 # Changelog
 
-## 4.28.1
+## 4.30.0-alpha.1
 
-### Patch Changes
+### Adds
+
+- Postgres and SQLite alpha release
+
+## 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
 
-- f8d1952: Bug fix: the "pretty URLs" feature of @apostrophecms/file is now compatible with locale prefixes.
+- 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
+## 4.28.0 (2026-03-19)
 
 ### Adds
 

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <a href="https://github.com/apostrophecms/apostrophe">
-    <img src="logo.svg" alt="ApostropheCMS logo" width="80" height="80">
+    <img src="https://static.apostrophecms.com/apostrophecms/apostrophe/logo.svg" alt="ApostropheCMS logo" width="80" height="80">
   </a>
 
   <h1>ApostropheCMS</h1>
@@ -139,4 +139,4 @@ ApostropheCMS is open source software licensed under the [MIT License](https://g
   <p>
     <em>Built with ❤️ by the <a href="https://apostrophecms.com">ApostropheCMS team</a></em>
   </p>
-</div>
+</div>

package/claude-tools/detect-handles.js

@@ -0,0 +1,46 @@
+// Require this before running mocha to detect what activates process.stdin
+// Usage: npx mocha -t 10000 --require ./claude-tools/detect-handles.js test/assets.js
+
+console.log(`stdin paused at startup: ${process.stdin.isPaused()}`);
+console.log(`stdin readableFlowing at startup: ${process.stdin.readableFlowing}`);
+
+// Monkey-patch stdin.resume to capture the call stack
+const origResume = process.stdin.resume.bind(process.stdin);
+process.stdin.resume = function(...args) {
+  console.log('\n=== process.stdin.resume() called ===');
+  console.log(new Error().stack);
+  return origResume(...args);
+};
+
+// Monkey-patch stdin.on to detect 'data' listener additions
+const origOn = process.stdin.on.bind(process.stdin);
+process.stdin.on = function(event, ...args) {
+  if (event === 'data' || event === 'readable') {
+    console.log(`\n=== process.stdin.on('${event}') called ===`);
+    console.log(new Error().stack);
+  }
+  return origOn(event, ...args);
+};
+
+// Periodically check stdin state changes
+let lastState = process.stdin.readableFlowing;
+const checker = setInterval(() => {
+  if (process.stdin.readableFlowing !== lastState) {
+    console.log(`\n=== stdin readableFlowing changed: ${lastState} -> ${process.stdin.readableFlowing} ===`);
+    console.log(new Error().stack);
+    lastState = process.stdin.readableFlowing;
+  }
+}, 100);
+checker.unref();
+
+const origRun = require('mocha/lib/runner').prototype.run;
+require('mocha/lib/runner').prototype.run = function(fn) {
+  return origRun.call(this, function(failures) {
+    console.log(`\nstdin paused at end: ${process.stdin.isPaused()}`);
+    console.log(`stdin readableFlowing at end: ${process.stdin.readableFlowing}`);
+    setTimeout(() => {
+      process.exit(failures ? 3 : 0);
+    }, 2000);
+    if (fn) fn(failures);
+  });
+};

package/claude-tools/minimal-hang-test.js

@@ -0,0 +1,28 @@
+// Minimal test to isolate what causes the hang.
+// Must reference the test/ directory as root for proper module resolution.
+const t = require('../test-lib/test.js');
+const path = require('path');
+
+// Fake a module object rooted in test/ like the real tests do
+const fakeModule = {
+  id: path.join(__dirname, '../test/fake'),
+  filename: path.join(__dirname, '../test/fake.js'),
+  paths: [path.join(__dirname, '../test/node_modules')]
+};
+
+describe('Minimal hang test', function() {
+  this.timeout(60000);
+  let apos;
+
+  after(async function() {
+    await t.destroy(apos);
+    console.log('after: destroy complete');
+  });
+
+  it('should create and use apos without hanging', async function() {
+    apos = await t.create({
+      root: fakeModule
+    });
+    console.log('apos created successfully');
+  });
+});

package/claude-tools/mongo-close-test.js

@@ -0,0 +1,11 @@
+// Test whether a MongoDB connection keeps the process alive after close()
+const mongoConnect = require('../../../packages/db-connect/lib/mongodb-connect');
+
+(async () => {
+  const uri = 'mongodb://localhost:27017/test_handle_leak';
+  console.log('Connecting...');
+  const client = await mongoConnect(uri);
+  console.log('Connected. Closing...');
+  await client.close();
+  console.log('Closed. Process should exit now if no leaked handles.');
+})();

package/claude-tools/stdin-ref-test.js

@@ -0,0 +1,14 @@
+// Check if process.stdin keeps the process alive
+// If this script hangs, stdin is ref'd. If it exits, stdin is unref'd.
+
+console.log(`stdin isTTY: ${process.stdin.isTTY}`);
+console.log(`stdin readableFlowing: ${process.stdin.readableFlowing}`);
+console.log(`stdin isPaused: ${process.stdin.isPaused()}`);
+
+// Check ref status
+if (typeof process.stdin.unref === 'function') {
+  console.log('stdin has unref method');
+}
+
+console.log('Waiting to see if process exits on its own...');
+// Don't do anything - just see if the process exits

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/eslint.config.js

@@ -7,7 +7,8 @@ module.exports = defineConfig([
     '**/blueimp/**/*.js',
     'test/public',
     'test/apos-build',
-    'coverage'
+    'coverage',
+    'claude-tools'
   ]),
   apostrophe
 ]);

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/db/index.js

@@ -4,11 +4,12 @@
 //
 // ### `uri`
 //
-// The MongoDB connection URI. See the [MongoDB URI documentation](https://docs.mongodb.com/manual/reference/connection-string/).
+// The databse connection URI. See the [MongoDB URI documentation](https://docs.mongodb.com/manual/reference/connection-string/)
+// and the postgres documentation.
 //
 // ### `connect`
 //
-// If present, this object is passed on as options to MongoDB's "connect"
+// If present, this object is passed on as options to the database adapters "connect"
 // method, along with the uri. See the [MongoDB connect settings documentation](http://mongodb.github.io/node-mongodb-native/2.2/reference/connecting/connection-settings/).
 //
 // By default, Apostrophe sets options to retry lost connections forever,
@@ -20,9 +21,16 @@
 //
 // ### `client`
 //
-// An existing MongoDB connection (MongoClient) object. If present, it is used
+// An existing MongoDB-compatible client object. If present, it is used
 // and `uri`, `host`, `connect`, etc. are ignored.
 //
+// ### `adapters`
+//
+// An array of adapters, each of which must provide `name`, `connect(uri, options)`,
+// and `protocols` properties. `name` may be used to override a core adapter,
+// such as `postgres` or `mongodb`. `connect` must resolve to a client object
+// supporting a sufficient subset of the mongodb API.
+//
 // ### `versionCheck`
 //
 // If `true`, check to make sure the database does not belong to an
@@ -49,15 +57,15 @@
 // in your project. However you may find it easier to just use the
 // `client` option.
 
-const mongodbConnect = require('../../../lib/mongodb-connect');
-const escapeHost = require('../../../lib/escape-host');
+const dbConnect = require('@apostrophecms/db-connect');
+const escapeHost = require('../../../lib/escape-host.js');
 
 module.exports = {
   options: {
     versionCheck: true
   },
   async init(self) {
-    await self.connectToMongo();
+    await self.connectToDb();
     await self.versionCheck();
   },
   handlers(self) {
@@ -81,14 +89,12 @@ module.exports = {
   },
   methods(self) {
     return {
-      // Open the database connection. Always uses MongoClient with its
-      // sensible defaults. Builds a URI if necessary, so we can call it
-      // in a consistent way.
-      //
-      // One default we override: if the connection is lost, we keep
-      // attempting to reconnect forever. This is the most sensible behavior
-      // for a persistent process that requires MongoDB in order to operate.
-      async connectToMongo() {
+      // Connect to the database and sets self.apos.dbClient
+      // and self.apos.db. Builds a mongodb URI by default,
+      // accepting host, port, user, password and name options
+      // if present. More typically a URI is specified via
+      // APOS_DB_URI, or via APOS_MONGODB_URI for bc.
+      async connectToDb() {
         if (self.options.client) {
           // Reuse a single client connection http://mongodb.github.io/node-mongodb-native/2.2/api/Db.html#db
           self.apos.dbClient = self.options.client;
@@ -96,32 +102,67 @@ module.exports = {
           self.connectionReused = true;
           return;
         }
-        let uri = 'mongodb://';
-        if (process.env.APOS_MONGODB_URI) {
-          uri = process.env.APOS_MONGODB_URI;
+        let uri;
+        const viaEnv = process.env.APOS_DB_URI || process.env.APOS_MONGODB_URI;
+        if (viaEnv) {
+          uri = viaEnv;
         } else if (self.options.uri) {
           uri = self.options.uri;
         } else {
-          if (self.options.user) {
-            uri += self.options.user + ':' + self.options.password + '@';
-          }
-          if (!self.options.host) {
-            self.options.host = 'localhost';
-          }
-          if (!self.options.port) {
-            self.options.port = 27017;
+          const validAdapters = [ 'mongodb', 'sqlite', 'postgres', 'multipostgres' ];
+          const adapter = process.env.APOS_DEFAULT_DB_ADAPTER || self.options.defaultAdapter || 'mongodb';
+          if (!validAdapters.includes(adapter)) {
+            throw new Error(`Invalid defaultAdapter: "${adapter}". Must be one of: ${validAdapters.join(', ')}`);
           }
           if (!self.options.name) {
             self.options.name = self.apos.shortName;
           }
-          uri += escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+          if (adapter === 'sqlite') {
+            const path = require('path');
+            uri = `sqlite://${path.resolve(self.apos.rootDir, 'data', self.options.name + '.sqlite')}`;
+          } else {
+            const credentials = self.options.user
+              ? encodeURIComponent(self.options.user) + ':' + encodeURIComponent(self.options.password) + '@'
+              : '';
+            if (adapter === 'mongodb') {
+              if (!self.options.host) {
+                self.options.host = 'localhost';
+              }
+              if (!self.options.port) {
+                self.options.port = 27017;
+              }
+              uri = 'mongodb://' + credentials + escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+            } else {
+              // postgres or multipostgres
+              if (!self.options.host) {
+                self.options.host = 'localhost';
+              }
+              if (!self.options.port) {
+                self.options.port = 5432;
+              }
+              uri = adapter + '://' + credentials + escapeHost(self.options.host) + ':' + self.options.port + '/' + self.options.name;
+            }
+          }
         }
 
-        self.apos.dbClient = await mongodbConnect(uri, self.options.connect);
+        self.apos.dbClient = await dbConnect(uri, {
+          ...self.options.connect,
+          adapters: self.options.adapters
+        });
         self.uri = uri;
         // Automatically uses the db name in the connection string
         self.apos.db = self.apos.dbClient.db();
       },
+      // Connect to a database using the appropriate adapter based on the URI protocol.
+      // Returns a client object compatible with the MongoDB driver interface.
+      // This method has no side effects — it does not set apos.db or apos.dbClient.
+      // It can be used to make temporary connections, e.g. for dropping a test database.
+      async connectToAdapter(uri, options) {
+        return dbConnect(uri, {
+          ...options,
+          adapters: self.options.adapters
+        });
+      },
       async versionCheck() {
         if (!self.options.versionCheck) {
           return;

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) {