Skip to content

The open alternative to Salesforce, designed for AI.

feat(apps): hide marketplace apps the server version does not satisfy (#27843)

martmull9997d385b7b3
diff --git a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
index 3bbd46c69cd..d278b704d57 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
@@ -117,7 +117,8 @@ The value is a standard [semver range](https://github.com/npm/node-semver#ranges
**What happens at deploy and install time:**
- If `engines.twenty` is set and the target server's version does not satisfy the range, the deploy (tarball upload) or install is rejected with a `SERVER_VERSION_INCOMPATIBLE` error and a message indicating both the required range and the actual server version.
-- If `engines.twenty` is **not set**, the app is accepted on any server version (backward-compatible with existing apps).
+- If `engines.twenty` is **not set**, no version check runs and the app is accepted on any server version (backward-compatible with existing apps). A blank value is rejected as an invalid range.
+- The marketplace does not list an app whose latest version declares an `engines.twenty` range the server does not satisfy, or an invalid one. The app stays registered and visible in the admin panel.
- If the server has no `APP_VERSION` configured, the check is skipped.
<Note>
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-catalog-cache-provider.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-catalog-cache-provider.service.ts
index 99084d4981c..6da9c59ccc0 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-catalog-cache-provider.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-catalog-cache-provider.service.ts
@@ -3,6 +3,7 @@ import { Injectable } from '@nestjs/common';
import { CoreEntityCache } from 'src/engine/core-entity-cache/decorators/core-entity-cache.decorator';
import { CoreEntityCacheProvider } from 'src/engine/core-entity-cache/interfaces/core-entity-cache-provider.service';
import { MarketplaceAppDTO } from 'src/engine/core-modules/application/application-marketplace/dtos/marketplace-app.dto';
+import { ApplicationVersionValidationService } from 'src/engine/core-modules/application/application-package/application-version-validation.service';
import { ApplicationRegistrationVariableService } from 'src/engine/core-modules/application/application-registration-variable/application-registration-variable.service';
import {
type ApplicationRegistrationCatalogCard,
@@ -17,6 +18,7 @@ export class MarketplaceCatalogCacheProviderService extends CoreEntityCacheProvi
constructor(
private readonly applicationRegistrationService: ApplicationRegistrationService,
private readonly applicationRegistrationVariableService: ApplicationRegistrationVariableService,
+ private readonly applicationVersionValidationService: ApplicationVersionValidationService,
) {
super();
}
@@ -34,8 +36,20 @@ export class MarketplaceCatalogCacheProviderService extends CoreEntityCacheProvi
registrations.map((registration) => registration.id),
);
- return registrations
- .filter((registration) => configuredStatuses.get(registration.id) ?? true)
+ const configuredRegistrations = registrations.filter(
+ (registration) => configuredStatuses.get(registration.id) ?? true,
+ );
+
+ const serverCompatibilities =
+ await this.applicationVersionValidationService.validateManyServerCompatibilities(
+ configuredRegistrations.map(
+ (registration) =>
+ registration.requiredServerVersionRange ?? undefined,
+ ),
+ );
+
+ return configuredRegistrations
+ .filter((_registration, index) => serverCompatibilities[index].compatible)
.reduce<Record<string, MarketplaceAppDTO>>(
(accumulator, registration) => {
accumulator[registration.universalIdentifier] =
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace.module.ts b/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace.module.ts
index 0637a2dd266..288e56ece37 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace.module.ts
@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
import { CoreEntityCacheModule } from 'src/engine/core-entity-cache/core-entity-cache.module';
import { ApplicationModule } from 'src/engine/core-modules/application/application.module';
+import { ApplicationPackageModule } from 'src/engine/core-modules/application/application-package/application-package.module';
import { ApplicationRegistrationLookupModule } from 'src/engine/core-modules/application/application-registration/application-registration-lookup/application-registration-lookup.module';
import { ApplicationRegistrationModule } from 'src/engine/core-modules/application/application-registration/application-registration.module';
import { MarketplaceCatalogSyncCronCommand } from 'src/engine/core-modules/application/application-marketplace/crons/commands/marketplace-catalog-sync.cron.command';
@@ -18,6 +19,7 @@ import { MarketplaceCatalogSyncCommand } from 'src/engine/core-modules/applicati
@Module({
imports: [
ApplicationModule,
+ ApplicationPackageModule,
ApplicationRegistrationLookupModule,
ApplicationRegistrationModule,
CoreEntityCacheModule,
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-package/application-version-validation.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-package/application-version-validation.service.ts
index 4a066e5dd01..db493090f39 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-package/application-version-validation.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-package/application-version-validation.service.ts
@@ -1,5 +1,6 @@
import { Injectable } from '@nestjs/common';
+import { isNonEmptyString, isString } from '@sniptt/guards';
import semver from 'semver';
import { UpgradeStatusService } from 'src/engine/core-modules/upgrade/services/upgrade-status.service';
import { isDefined } from 'twenty-shared/utils';
@@ -39,26 +40,41 @@ export class ApplicationVersionValidationService {
async validateServerCompatibility(
requiredServerVersion: string | undefined,
): Promise<VersionValidationResult> {
- if (!isDefined(requiredServerVersion)) {
- return { compatible: true };
- }
-
- if (!isDefined(semver.validRange(requiredServerVersion))) {
- return {
- compatible: false,
- reason: 'INVALID_REQUIRED_VERSION',
- message: `App manifest declares invalid engines.twenty value "${requiredServerVersion}". Must be a valid semver range.`,
- };
- }
+ const [validation] = await this.validateManyServerCompatibilities([
+ requiredServerVersion,
+ ]);
- const instanceCompletedVersion =
- await this.upgradeStatusService.getInstanceCompletedVersion();
+ return validation;
+ }
- return this.validateVersionAgainstRange({
- version: instanceCompletedVersion,
- requiredVersionRange: requiredServerVersion,
- scope: 'instance',
- });
+ async validateManyServerCompatibilities(
+ requiredServerVersions: (string | undefined)[],
+ ): Promise<VersionValidationResult[]> {
+ const instanceCompletedVersion = requiredServerVersions.some(isDefined)
+ ? await this.upgradeStatusService.getInstanceCompletedVersion()
+ : null;
+
+ return requiredServerVersions.map(
+ (requiredServerVersion): VersionValidationResult => {
+ if (!isDefined(requiredServerVersion)) {
+ return { compatible: true };
+ }
+
+ if (!this.isValidRequiredServerVersionRange(requiredServerVersion)) {
+ return {
+ compatible: false,
+ reason: 'INVALID_REQUIRED_VERSION',
+ message: `App manifest declares invalid engines.twenty value "${requiredServerVersion}". Must be a valid semver range.`,
+ };
+ }
+
+ return this.validateVersionAgainstRange({
+ version: instanceCompletedVersion,
+ requiredVersionRange: requiredServerVersion,
+ scope: 'instance',
+ });
+ },
+ );
}
async validateWorkspaceCompatibility({
@@ -72,7 +88,7 @@ export class ApplicationVersionValidationService {
return { compatible: true };
}
- if (!isDefined(semver.validRange(requiredServerVersion))) {
+ if (!this.isValidRequiredServerVersionRange(requiredServerVersion)) {
return {
compatible: false,
reason: 'INVALID_REQUIRED_VERSION',
@@ -152,6 +168,16 @@ export class ApplicationVersionValidationService {
return { allowed: true };
}
+ private isValidRequiredServerVersionRange(
+ requiredServerVersion: string,
+ ): boolean {
+ return (
+ isString(requiredServerVersion) &&
+ isNonEmptyString(requiredServerVersion.trim()) &&
+ isDefined(semver.validRange(requiredServerVersion))
+ );
+ }
+
private validateVersionAgainstRange({
version,
requiredVersionRange,
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-registration/application-registration.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-registration/application-registration.service.ts
index f621e73bcad..78ec6381117 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-registration/application-registration.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-registration/application-registration.service.ts
@@ -97,6 +97,7 @@ export type ApplicationRegistrationCatalogCard = {
author: string | null;
category: string | null;
logoUrl: string | null;
+ requiredServerVersionRange: string | null;
};
@Injectable()
@@ -1042,6 +1043,7 @@ export class ApplicationRegistrationService {
'description',
'author',
'category',
+ 'manifest',
],
where: {
isListed: true,
@@ -1060,6 +1062,8 @@ export class ApplicationRegistrationService {
category: registration.category,
logoUrl:
this.applicationRegistrationAssetUrlService.buildLogoUrl(registration),
+ requiredServerVersionRange:
+ registration.manifest?.application?.requiredServerVersionRange ?? null,
}));
}
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-upload-application-server-version.integration-spec.ts.snap b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-upload-application-server-version.integration-spec.ts.snap
index e4b42227a35..784ef51c3af 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-upload-application-server-version.integration-spec.ts.snap
+++ b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-upload-application-server-version.integration-spec.ts.snap
@@ -1,5 +1,17 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP
+exports[`Publish application is gated by the instance server version rejects publishing when the app declares a blank engines.twenty 1`] = `
+{
+ "extensions": {
+ "code": "BAD_USER_INPUT",
+ "subCode": "INVALID_APP_ENGINE_REQUIREMENT",
+ "userFriendlyMessage": "The app manifest declares an invalid server version requirement.",
+ },
+ "message": "App manifest declares invalid engines.twenty value " ". Must be a valid semver range.",
+ "name": "UserInputError",
+}
+`;
+
exports[`Publish application is gated by the instance server version rejects publishing when the app requires a server version the instance does not satisfy 1`] = `
{
"extensions": {
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/failing-upload-application-server-version.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/failing-upload-application-server-version.integration-spec.ts
index af37e22bcc8..3ccb0ff1829 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/failing-upload-application-server-version.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/application/failing-upload-application-server-version.integration-spec.ts
@@ -57,4 +57,30 @@ describe('Publish application is gated by the instance server version', () => {
normalizeMessage: scrubSemverVersions,
});
});
+
+ it('rejects publishing when the app declares a blank engines.twenty', async () => {
+ const universalIdentifier = uuidv4();
+ const roleId = uuidv4();
+
+ const tarball = await createAppTarball({
+ 'manifest.json': JSON.stringify(
+ buildBaseManifest({ appId: universalIdentifier, roleId }),
+ ),
+ 'package.json': JSON.stringify({
+ name: `test-blank-server-version-${universalIdentifier}`,
+ version: '1.0.0',
+ engines: { twenty: ' ' },
+ }),
+ });
+
+ createdApplicationUniversalIdentifiers.push(universalIdentifier);
+
+ const { errors } = await uploadAppTarball({
+ tarballBuffer: tarball,
+ universalIdentifier,
+ expectToFail: true,
+ });
+
+ expectOneNotInternalServerErrorSnapshot({ errors });
+ });
});
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/marketplace-catalog-sync.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/marketplace-catalog-sync.integration-spec.ts
index 98a5de68f82..7cb75d7e206 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/marketplace-catalog-sync.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/application/marketplace-catalog-sync.integration-spec.ts
@@ -88,6 +88,10 @@ describe('Marketplace Catalog Sync (integration)', () => {
const npmUid = crypto.randomUUID();
const tarballUid = crypto.randomUUID();
const curatedUid = 'a1b2c3d4-0000-0000-0000-000000000001';
+ const serverCompatibleUid = crypto.randomUUID();
+ const serverIncompatibleUid = crypto.randomUUID();
+ const blankServerRangeUid = crypto.randomUUID();
+ const nonStringServerRangeUid = crypto.randomUUID();
// Insert all data before queries so the in-memory cache is populated once
// with complete data rather than being stale for later tests.
@@ -132,6 +136,42 @@ describe('Marketplace Catalog Sync (integration)', () => {
},
category: 'Data',
});
+
+ await insertCatalogRegistration({
+ universalIdentifier: serverCompatibleUid,
+ name: 'Server Compatible App',
+ sourcePackage: '@test/server-compatible-app',
+ manifest: {
+ application: { requiredServerVersionRange: '>=1.0.0' },
+ },
+ });
+
+ await insertCatalogRegistration({
+ universalIdentifier: serverIncompatibleUid,
+ name: 'Server Incompatible App',
+ sourcePackage: '@test/server-incompatible-app',
+ manifest: {
+ application: { requiredServerVersionRange: '>=999.0.0' },
+ },
+ });
+
+ await insertCatalogRegistration({
+ universalIdentifier: blankServerRangeUid,
+ name: 'Blank Server Range App',
+ sourcePackage: '@test/blank-server-range-app',
+ manifest: {
+ application: { requiredServerVersionRange: ' ' },
+ },
+ });
+
+ await insertCatalogRegistration({
+ universalIdentifier: nonStringServerRangeUid,
+ name: 'Non String Server Range App',
+ sourcePackage: '@test/non-string-server-range-app',
+ manifest: {
+ application: { requiredServerVersionRange: 2 },
+ },
+ });
});
it('should return npm-sourced registrations from the database', async () => {
@@ -168,6 +208,27 @@ describe('Marketplace Catalog Sync (integration)', () => {
expect(curatedApp.name).toBe('Data Enrichment');
expect(curatedApp.category).toBe('Data');
});
+
+ it('should not list apps whose required server version the server does not satisfy', async () => {
+ const res = await gqlRequest(MARKETPLACE_QUERY).expect(200);
+ const appIds = res.body.data.findManyMarketplaceApps.map(
+ (app: { id: string }) => app.id,
+ );
+
+ expect(appIds).toContain(serverCompatibleUid);
+ expect(appIds).not.toContain(serverIncompatibleUid);
+ expect(appIds).not.toContain(blankServerRangeUid);
+ expect(appIds).not.toContain(nonStringServerRangeUid);
+ });
+
+ it('should list apps that declare no required server version', async () => {
+ const res = await gqlRequest(MARKETPLACE_QUERY).expect(200);
+ const appIds = res.body.data.findManyMarketplaceApps.map(
+ (app: { id: string }) => app.id,
+ );
+
+ expect(appIds).toEqual(expect.arrayContaining([npmUid, curatedUid]));
+ });
});
describe('catalog sync', () => {
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/successful-app-installation-without-required-server-version.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/successful-app-installation-without-required-server-version.integration-spec.ts
new file mode 100644
index 00000000000..0b0636f40d3
--- /dev/null
+++ b/packages/twenty-server/test/integration/metadata/suites/application/successful-app-installation-without-required-server-version.integration-spec.ts
@@ -0,0 +1,102 @@
+import { buildBaseManifest } from 'test/integration/metadata/suites/application/utils/build-base-manifest.util';
+import { cleanupApplicationAndAppRegistration } from 'test/integration/metadata/suites/application/utils/cleanup-application-and-app-registration.util';
+import { createAppTarball } from 'test/integration/metadata/suites/application/utils/create-app-tarball.util';
+import { installApplication } from 'test/integration/metadata/suites/application/utils/install-application.util';
+import { uploadAppTarball } from 'test/integration/metadata/suites/application/utils/upload-app-tarball.util';
+import {
+ type EachTestingContext,
+ eachTestingContextFilter,
+} from 'twenty-shared/testing';
+import { v4 as uuidv4 } from 'uuid';
+
+import { SEED_APPLE_WORKSPACE_ID } from 'src/engine/workspace-manager/dev-seeder/core/constants/seeder-workspaces.constant';
+
+jest.setTimeout(120000);
+
+const INJECTED_CURSOR_MARKER =
+ 'integration-test-install-without-required-server-version';
+
+type TestContext = {
+ engines: Record<string, string> | undefined;
+};
+
+const SUCCESSFUL_TEST_CASES: EachTestingContext<TestContext>[] = [
+ {
+ title: 'when package.json declares no engines',
+ context: { engines: undefined },
+ },
+ {
+ title: 'when package.json declares engines without twenty',
+ context: { engines: { node: '^24.5.0' } },
+ },
+];
+
+describe('Install application without a required server version', () => {
+ let universalIdentifier: string;
+
+ beforeAll(() => {
+ jest.useRealTimers();
+ });
+
+ beforeEach(() => {
+ universalIdentifier = uuidv4();
+ });
+
+ afterEach(async () => {
+ await global.testDataSource.query(
+ `DELETE FROM core."upgradeMigration"
+ WHERE "workspaceId" = $1 AND "executedByVersion" = $2`,
+ [SEED_APPLE_WORKSPACE_ID, INJECTED_CURSOR_MARKER],
+ );
+
+ await cleanupApplicationAndAppRegistration({
+ applicationUniversalIdentifier: universalIdentifier,
+ });
+ });
+
+ afterAll(() => {
+ jest.useFakeTimers();
+ });
+
+ it.each(eachTestingContextFilter(SUCCESSFUL_TEST_CASES))(
+ 'installs without checking the server version $title',
+ async ({ context }) => {
+ const tarball = await createAppTarball({
+ 'manifest.json': JSON.stringify(
+ buildBaseManifest({ appId: universalIdentifier, roleId: uuidv4() }),
+ ),
+ 'package.json': JSON.stringify({
+ name: `test-install-without-required-server-version-${universalIdentifier}`,
+ version: '1.0.0',
+ ...(context.engines ? { engines: context.engines } : {}),
+ }),
+ });
+
+ const uploadResult = await uploadAppTarball({
+ tarballBuffer: tarball,
+ universalIdentifier,
+ });
+
+ expect(uploadResult.errors).toBeUndefined();
+
+ await global.testDataSource.query(
+ `INSERT INTO core."upgradeMigration"
+ (name, status, attempt, "executedByVersion", "workspaceId", "isInitial")
+ VALUES ($1, 'completed', 2, $2, $3, false)`,
+ [
+ '1.0.0_UnknownLegacyCommand_1700000000000',
+ INJECTED_CURSOR_MARKER,
+ SEED_APPLE_WORKSPACE_ID,
+ ],
+ );
+
+ const { data, errors } = await installApplication({
+ input: { universalIdentifier },
+ expectToFail: false,
+ });
+
+ expect(errors).toBeUndefined();
+ expect(data.installApplication.id).toEqual(expect.any(String));
+ },
+ );
+});