The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Reserve the TWENTY_ prefix for app variable names (#29210)
Paul Rastoin0c5752d843df
diff --git a/packages/twenty-agent-skills/references/concepts/how-apps-work.md b/packages/twenty-agent-skills/references/concepts/how-apps-work.mdindex df479fafdeb..c3fd5501607 100644--- a/packages/twenty-agent-skills/references/concepts/how-apps-work.md+++ b/packages/twenty-agent-skills/references/concepts/how-apps-work.md@@ -110,4 +110,4 @@ my-app/- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `twenty remote use <name>`.- **Sync**: `twenty app apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.- **Publish**: `twenty app publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.-- **Reserved variable names**: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` are set by Twenty for every logic function run. A manifest that declares one of them as an application or server variable is rejected on sync and publish.+- **Reserved variable names**: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` are set by Twenty for every logic function run, and every other name starting with `TWENTY_` is kept for variables Twenty adds later. A manifest that declares a reserved name as an application or server variable is rejected on sync and publish.diff --git a/packages/twenty-agent-skills/references/develop-app/logic.md b/packages/twenty-agent-skills/references/develop-app/logic.mdindex b291961349f..694078fd228 100644--- a/packages/twenty-agent-skills/references/develop-app/logic.md+++ b/packages/twenty-agent-skills/references/develop-app/logic.md@@ -22,7 +22,7 @@ Other rules:- Prefer idempotent behavior for jobs and repeated invocations.- Read secrets through the application-config helper, not raw `process.env`.- An application variable declared with `scope: 'USER'` is in `process.env` with the value of the member who triggered the run, or its default until they set their own; a run nobody triggered (cron, install hooks) gets no user variables. That member is not always the one the run is about: a database event runs as whoever edited the record. For example, with a user `SLACK_TOKEN`, a function on opportunity update posts with the editor's token, not the opportunity owner's. When the run is about someone else or every member, read the values with `myUserApplicationVariables` through `new MetadataApiClient({ runAs: 'application' })`.-- Twenty injects `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` into every run. Never declare an application or server variable with one of these names: the manifest is rejected on sync and publish.+- Twenty injects `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID` into every run. Never declare an application or server variable with one of these names, or any other name starting with `TWENTY_`: the manifest is rejected on sync and publish.- Do not hide customer-impacting side effects behind UI-only actions.Soft cap: a `*.logic-function.ts` or `*.post-install.ts` file over 200 lines is a refactor signal.diff --git a/packages/twenty-docs/developers/extend/apps/config/application.mdx b/packages/twenty-docs/developers/extend/apps/config/application.mdxindex c71513fd1e5..a63fda3d3cf 100644--- a/packages/twenty-docs/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/developers/extend/apps/config/application.mdx@@ -54,7 +54,7 @@ Notes:- An app can report its own configuration state with [`defineHealthCheck()`](/developers/extend/apps/logic/logic-functions#health-check), for what only the app can know — a key that is present but revoked, a third-party account on the wrong plan. `isRequired` covers what Twenty can see by itself; the health check covers the rest.- Both kinds of variable accept `isRequired: true`. A required variable the workspace has not filled in yet leaves the app unconfigured: its settings page shows a banner naming the missing variables, with a button that jumps to the tab where they are set. Mark as required only what the app genuinely cannot run without — an optional variable with a sensible default should stay optional.- Both kinds of variable accept `isDeprecated: true`. Use it to retire a variable instead of deleting it: keeping the key declared preserves the stored value (deleting it destroys the value the operator entered), and the variable is still injected, so your code can fall back to it — `process.env.NEW_API_KEY ?? process.env.API_KEY`. A deprecated variable disappears from the app's settings once it has no value, and never counts toward the app's configuration check, so `isDeprecated` beats `isRequired`.-- Twenty sets these names for every logic function run, so they are reserved: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID`. A manifest that declares one of them as an application or server variable is rejected when the app is synced or published.+- Twenty sets these names for every logic function run, so they are reserved: `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` and `APPLICATION_ID`. Every other name starting with `TWENTY_` is reserved too, for variables Twenty adds later. A manifest that declares a reserved name as an application or server variable is rejected when the app is synced or published.- To add your own entries to the app's settings menu (in place of the generated **Variables** page), declare a front component and point a [`defineSettingsMenuItem()`](/developers/extend/apps/layout/front-components#settings-menu-items) at it, in its own file. Declare as many as you need and order them with `position`; `scope` puts an item under the workspace settings or under each member's own settings. The system-managed **General** item (auto-upgrade, App URL, connections) always comes first, and App URL only shows when the app has HTTP-triggered functions.## Requested media capabilitiesdiff --git a/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.tsindex 48000a21fab..b4604c5ea4f 100644--- a/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts+++ b/packages/twenty-server/src/engine/core-modules/application/application-registration-variable/application-registration-variable.service.ts@@ -19,7 +19,7 @@ import {import { type UpdateApplicationRegistrationVariableInput } from 'src/engine/core-modules/application/application-registration-variable/dtos/update-application-registration-variable.input';import { type FlatApplication } from 'src/engine/core-modules/application/types/flat-application.type';import { canCallerReachApplicationRegistrationOrThrow } from 'src/engine/core-modules/application/utils/can-caller-reach-application-registration-or-throw.util';-import { findEngineInjectedEnvVariableNames } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util';+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';import { SecretEncryptionService } from 'src/engine/core-modules/secret-encryption/secret-encryption.service';import { ApplicationRegistrationVariableDTO } from 'src/engine/core-modules/application/application-registration-variable/dtos/application-registration-variable.dto';@@ -113,7 +113,7 @@ export class ApplicationRegistrationVariableService {const declaredKeys = Object.keys(serverVariables);- const reservedKeys = findEngineInjectedEnvVariableNames(declaredKeys);+ const reservedKeys = declaredKeys.filter(isReservedEnvVariableName);if (reservedKeys.length > 0) {throw new ApplicationRegistrationException(diff --git a/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.tsindex 924e437e0b0..ec22c603064 100644--- a/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts+++ b/packages/twenty-server/src/engine/core-modules/application/utils/__tests__/find-reserved-variable-names-in-application-manifest.util.spec.ts@@ -49,4 +49,18 @@ describe('findReservedVariableNamesInApplicationManifest', () => {}),).toEqual(['TWENTY_API_KEY']);});++ it('should return names starting with TWENTY_ that Twenty does not inject yet', () => {+ expect(+ findReservedVariableNamesInApplicationManifest({+ serverVariables: { TWENTY_SERVER_SETTING: { isSecret: true } },+ applicationVariables: {+ TWENTY_WORKSPACE_SETTING: {+ universalIdentifier: 'application-variable-id',+ isSecret: false,+ },+ },+ }),+ ).toEqual(['TWENTY_SERVER_SETTING', 'TWENTY_WORKSPACE_SETTING']);+ });});diff --git a/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts b/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.tsindex 41dc063ffb8..c833d712a7c 100644--- a/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts+++ b/packages/twenty-server/src/engine/core-modules/application/utils/find-reserved-variable-names-in-application-manifest.util.ts@@ -1,6 +1,6 @@import { type ApplicationManifest } from 'twenty-shared/application';-import { findEngineInjectedEnvVariableNames } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util';+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';export const findReservedVariableNamesInApplicationManifest = ({serverVariables,@@ -10,9 +10,9 @@ export const findReservedVariableNamesInApplicationManifest = ({'serverVariables' | 'applicationVariables'>): string[] => [...new Set(- findEngineInjectedEnvVariableNames([+ [...Object.keys(serverVariables ?? {}),...Object.keys(applicationVariables ?? {}),- ]),+ ].filter(isReservedEnvVariableName),),];diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.tsnew file mode 100644index 00000000000..d4c57af7ffc--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant.ts@@ -0,0 +1 @@+export const RESERVED_ENV_VARIABLE_NAME_PREFIX = 'TWENTY_';diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.tsnew file mode 100644index 00000000000..f813113df4f--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/__tests__/is-reserved-env-variable-name.util.spec.ts@@ -0,0 +1,19 @@+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';++describe('isReservedEnvVariableName', () => {+ it.each([+ 'TWENTY_API_URL',+ 'APPLICATION_ID',+ 'TWENTY_FUTURE_VARIABLE',+ 'TWENTY_',+ ])('should reserve %s', (name) => {+ expect(isReservedEnvVariableName(name)).toBe(true);+ });++ it.each(['APP_API_KEY', 'twenty_api_url', 'MY_TWENTY_VARIABLE', 'TWENTY'])(+ 'should not reserve %s',+ (name) => {+ expect(isReservedEnvVariableName(name)).toBe(false);+ },+ );+});diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.tsdeleted file mode 100644index 8f09c3fefcf..00000000000--- a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/find-engine-injected-env-variable-names.util.ts+++ /dev/null@@ -1,4 +0,0 @@-import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';--export const findEngineInjectedEnvVariableNames = (keys: string[]): string[] =>- keys.filter((key) => ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(key));diff --git a/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.ts b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.tsnew file mode 100644index 00000000000..ffe6614cec2--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util.ts@@ -0,0 +1,6 @@+import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';+import { RESERVED_ENV_VARIABLE_NAME_PREFIX } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/reserved-env-variable-name-prefix.constant';++export const isReservedEnvVariableName = (name: string): boolean =>+ ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(name) ||+ name.startsWith(RESERVED_ENV_VARIABLE_NAME_PREFIX);diff --git a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.tsindex 5e657b96006..ff192bd2b35 100644--- a/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts+++ b/packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-application-variable-validator.service.ts@@ -6,7 +6,7 @@ import { ALL_METADATA_NAME } from 'twenty-shared/metadata';import { isDefined } from 'twenty-shared/utils';import { ApplicationVariableEntityExceptionCode } from 'src/engine/core-modules/application/application-variable/application-variable.exception';-import { ENGINE_INJECTED_ENV_VARIABLE_NAMES } from 'src/engine/core-modules/logic-function/logic-function-executor/constants/engine-injected-env-variable-names.constant';+import { isReservedEnvVariableName } from 'src/engine/core-modules/logic-function/logic-function-executor/utils/is-reserved-env-variable-name.util';import { findFlatEntityByUniversalIdentifier } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-universal-identifier.util';import { type FailedFlatEntityValidation } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/types/failed-flat-entity-validation.type';import { getEmptyFlatEntityValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/utils/get-flat-entity-validation-error.util';@@ -42,7 +42,7 @@ export class FlatApplicationVariableValidatorService {});}- if (ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(flatApplicationVariable.key)) {+ if (isReservedEnvVariableName(flatApplicationVariable.key)) {const key = flatApplicationVariable.key;validationResult.errors.push({@@ -145,10 +145,7 @@ export class FlatApplicationVariableValidatorService {const keyUpdate = flatEntityUpdate.key;- if (- isDefined(keyUpdate) &&- ENGINE_INJECTED_ENV_VARIABLE_NAMES.has(keyUpdate)- ) {+ if (isDefined(keyUpdate) && isReservedEnvVariableName(keyUpdate)) {validationResult.errors.push({code: ApplicationVariableEntityExceptionCode.INVALID_APPLICATION_VARIABLE_INPUT,message: t`Application variable key ${keyUpdate} is reserved`,diff --git a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snapindex e19c4b85e24..f5b49c6ba26 100644--- a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap+++ b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/failing-sync-application-reserved-variable-name.integration-spec.ts.snap@@ -72,6 +72,18 @@ exports[`Sync application should fail on reserved variable names should refuse a}`;+exports[`Sync application should fail on reserved variable names should refuse a manifest declaring a server variable named TWENTY_FUTURE_VARIABLE 1`] = `+{+ "extensions": {+ "code": "BAD_USER_INPUT",+ "subCode": "INVALID_INPUT",+ "userFriendlyMessage": "Invalid input provided.",+ },+ "message": "Variable names are reserved: TWENTY_FUTURE_VARIABLE",+ "name": "UserInputError",+}+`;+exports[`Sync application should fail on reserved variable names should refuse a manifest declaring an application variable named APPLICATION_ID 1`] = `{"extensions": {@@ -143,3 +155,15 @@ exports[`Sync application should fail on reserved variable names should refuse a"name": "UserInputError",}`;++exports[`Sync application should fail on reserved variable names should refuse a manifest declaring an application variable named TWENTY_FUTURE_VARIABLE 1`] = `+{+ "extensions": {+ "code": "BAD_USER_INPUT",+ "subCode": "INVALID_INPUT",+ "userFriendlyMessage": "Invalid input provided.",+ },+ "message": "Variable names are reserved: TWENTY_FUTURE_VARIABLE",+ "name": "UserInputError",+}+`;diff --git a/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.tsindex 6c250553427..99b5984de53 100644--- a/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts+++ b/packages/twenty-server/test/integration/metadata/suites/application/failing-sync-application-reserved-variable-name.integration-spec.ts@@ -32,7 +32,7 @@ const BASELINE_APPLICATION_VARIABLES: ApplicationVariables = {},};-// The logic function executor injects these into every run+// Engine-injected names, plus an unused one under the reserved TWENTY_ prefixconst RESERVED_NAMES = ['TWENTY_API_URL','TWENTY_APP_ACCESS_TOKEN',@@ -40,6 +40,7 @@ const RESERVED_NAMES = ['TWENTY_API_KEY','TWENTY_FUNCTIONS_URL','APPLICATION_ID',+ 'TWENTY_FUTURE_VARIABLE',];type TestContext = {