The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Keep upgrade command code in its version folder (#26672)
Félix Malfaitfff96c016877
diff --git a/CLAUDE.md b/CLAUDE.mdindex 86c0ed959b6..c13194f3027 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -44,7 +44,7 @@ npx nx run twenty-front:graphql:generate # after GraphQL schema changes (--- **Nx caching can serve a stale pass.** To verify a fix, run `npx tsgo -p tsconfig.json --noEmit` in the package directly rather than `nx typecheck`.- **Do not commit translation catalogs unless translations are the task.** `lingui extract`/`compile` regenerate `packages/twenty-server/src/engine/core-modules/i18n/locales/*.po` and `locales/generated/*` with thousands of lines of churn as a side effect of touching any `msg` string. The i18n pipeline maintains them; leave them out of your commit.- **Commit messages must not carry AI attribution.** CI rejects commits containing `@anthropic.com` co-author trailers or "Generated with Claude Code" lines.-- **Upgrade commands** (`packages/twenty-server/src/database/commands/upgrade-version-command/`): add or edit files only under the current `TWENTY_CURRENT_VERSION` directory, with a real epoch-ms timestamp strictly greater than every existing one in that directory — CI enforces both, and the upgrade cursor silently skips a command that sorts before an already-applied one. Include `up` and `down`; never rewrite committed command logic. See `packages/twenty-server/docs/UPGRADE_COMMANDS.md`.+- **Upgrade commands** (`packages/twenty-server/src/database/commands/upgrade-version-command/`): add or edit files only under the current `TWENTY_CURRENT_VERSION` directory, with a real epoch-ms timestamp strictly greater than every existing one in that directory — CI enforces both, and the upgrade cursor silently skips a command that sorts before an already-applied one. Include `up` and `down`; never rewrite committed command logic. Keep command-only helpers and constants in the version folder, never in runtime modules, and never make runtime code branch on migration state. See `packages/twenty-server/docs/UPGRADE_COMMANDS.md`.- **Entity file changes need a generated instance command**: `npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>` (slow = adds a data-backfill step).- A read-only Postgres MCP server is configured in `.mcp.json` for inspecting workspace data, metadata, and migration results. Writes go through the CLI commands above.- E2E login: click "Continue with Email" and use the prefilled credentials.diff --git a/packages/twenty-oxlint-rules/oxlint-plugin.ts b/packages/twenty-oxlint-rules/oxlint-plugin.tsindex bb8968ee68d..3f05235672b 100644--- a/packages/twenty-oxlint-rules/oxlint-plugin.ts+++ b/packages/twenty-oxlint-rules/oxlint-plugin.ts@@ -64,6 +64,10 @@ import {rule as noNavigatePreferLink,RULE_NAME as noNavigatePreferLinkName,} from './rules/no-navigate-prefer-link';+import {+ rule as noRuntimeImportFromUpgradeCommand,+ RULE_NAME as noRuntimeImportFromUpgradeCommandName,+} from './rules/no-runtime-import-from-upgrade-command';import {rule as noStateUseref,RULE_NAME as noStateUserefName,@@ -117,6 +121,7 @@ export default definePlugin({[noMiscasedAcronymInIdentifierName]: noMiscasedAcronymInIdentifier,[noMiscasedAcronymInMessageName]: noMiscasedAcronymInMessage,[noNavigatePreferLinkName]: noNavigatePreferLink,+ [noRuntimeImportFromUpgradeCommandName]: noRuntimeImportFromUpgradeCommand,[noStateUserefName]: noStateUseref,[noStorybookA11yDisableName]: noStorybookA11yDisable,[preferWorkspaceScopedRepositoryName]: preferWorkspaceScopedRepository,diff --git a/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.spec.ts b/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.spec.tsnew file mode 100644index 00000000000..efbe944d8ca--- /dev/null+++ b/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.spec.ts@@ -0,0 +1,63 @@+import { RuleTester } from 'oxlint/plugins-dev';++import { rule, RULE_NAME } from './no-runtime-import-from-upgrade-command';++const ruleTester = new RuleTester();++const SERVER = '/project/packages/twenty-server';+const COMMAND_IMPORT =+ "import { run } from 'src/database/commands/upgrade-version-command/2-42/utils/run.util';";++ruleTester.run(RULE_NAME, rule, {+ valid: [+ {+ code: "import { NAME } from 'src/database/commands/upgrade-version-command/2-42/2-42-upgrade-command-name.constant';",+ filename: `${SERVER}/src/engine/core-modules/foo/foo.service.ts`,+ },+ {+ code: "import { NAMES } from 'src/database/commands/upgrade-version-command/2-42/2-42-upgrade-command-name.constants';",+ filename: `${SERVER}/src/engine/core-modules/foo/foo.service.ts`,+ },+ {+ code: "import { FooService } from 'src/engine/core-modules/foo/foo.service';",+ filename: `${SERVER}/src/engine/core-modules/bar/bar.service.ts`,+ },+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/src/database/commands/upgrade-version-command/2-43/2-43-upgrade-version-command.module.ts`,+ },+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service.ts`,+ },+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/src/engine/core-modules/foo/foo.service.spec.ts`,+ },+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/src/engine/core-modules/foo/__tests__/foo.util.ts`,+ },+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/test/integration/upgrade/suites/foo.integration-spec.ts`,+ },+ ],+ invalid: [+ {+ code: COMMAND_IMPORT,+ filename: `${SERVER}/src/engine/core-modules/foo/foo.service.ts`,+ errors: [{ messageId: 'noRuntimeImportFromUpgradeCommand' }],+ },+ {+ code: "export { run } from 'src/database/commands/upgrade-version-command/2-42/utils/run.util';",+ filename: `${SERVER}/src/engine/core-modules/foo/index.ts`,+ errors: [{ messageId: 'noRuntimeImportFromUpgradeCommand' }],+ },+ {+ code: "const load = () => import('src/database/commands/upgrade-version-command/2-42/utils/run.util');",+ filename: `${SERVER}/src/engine/core-modules/foo/foo.service.ts`,+ errors: [{ messageId: 'noRuntimeImportFromUpgradeCommand' }],+ },+ ],+});diff --git a/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.ts b/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.tsnew file mode 100644index 00000000000..7d2b5d67059--- /dev/null+++ b/packages/twenty-oxlint-rules/rules/no-runtime-import-from-upgrade-command.ts@@ -0,0 +1,65 @@+import { defineRule } from '@oxlint/plugins';++export const RULE_NAME = 'no-runtime-import-from-upgrade-command';++const UPGRADE_COMMAND_IMPORT_PREFIX =+ 'src/database/commands/upgrade-version-command/';++const ALLOWED_IMPORT_REGEX = /-upgrade-command-name\.constants?$/;++const EXEMPT_FILE_REGEXES = [+ /\/src\/database\/commands\//,+ /\/src\/engine\/core-modules\/upgrade\//,+ /\/test\//,+ /\/__tests__\//,+ /\.spec\.ts$/,+ /\.integration-spec\.ts$/,+];++const isExemptFile = (filename: string): boolean =>+ EXEMPT_FILE_REGEXES.some((regex) => regex.test(filename));++const isForbiddenImportSource = (source: string): boolean =>+ source.startsWith(UPGRADE_COMMAND_IMPORT_PREFIX) &&+ !ALLOWED_IMPORT_REGEX.test(source);++export const rule = defineRule({+ meta: {+ type: 'problem',+ docs: {+ description:+ 'Forbid runtime code from importing upgrade command code, which is frozen once released',+ },+ schema: [],+ messages: {+ noRuntimeImportFromUpgradeCommand:+ "Runtime code must not import '{{ source }}'. Keep migration-only logic, constants and legacy formats in the version folder, and move shared primitives out of it instead.",+ },+ },+ create: (context) => {+ if (isExemptFile(context.filename)) {+ return {};+ }++ const checkSource = (sourceNode: any) => {+ const source = sourceNode?.value;++ if (typeof source !== 'string' || !isForbiddenImportSource(source)) {+ return;+ }++ context.report({+ node: sourceNode,+ messageId: 'noRuntimeImportFromUpgradeCommand',+ data: { source },+ });+ };++ return {+ ImportDeclaration: (node: any) => checkSource(node.source),+ ExportNamedDeclaration: (node: any) => checkSource(node.source),+ ExportAllDeclaration: (node: any) => checkSource(node.source),+ ImportExpression: (node: any) => checkSource(node.source),+ };+ },+});diff --git a/packages/twenty-server/.oxlintrc.json b/packages/twenty-server/.oxlintrc.jsonindex fdfb5e27a88..651ecf69090 100644--- a/packages/twenty-server/.oxlintrc.json+++ b/packages/twenty-server/.oxlintrc.json@@ -93,6 +93,7 @@"twenty/rest-api-methods-should-be-guarded": "error","twenty/graphql-resolvers-should-be-guarded": "error","twenty/upgrade-command-filename": "error",+ "twenty/no-runtime-import-from-upgrade-command": "error","twenty/no-data-mutation-in-fast-instance-command": "error","twenty/no-icu-escaping-apostrophe": "error","twenty/no-miscased-acronym-in-identifier": "error",diff --git a/packages/twenty-server/docs/UPGRADE_COMMANDS.md b/packages/twenty-server/docs/UPGRADE_COMMANDS.mdindex 76ce9c8efae..ee80b1f7ced 100644--- a/packages/twenty-server/docs/UPGRADE_COMMANDS.md+++ b/packages/twenty-server/docs/UPGRADE_COMMANDS.md@@ -127,6 +127,15 @@ All pre-2.19 commands follow this rule, including `upgrade:2-10:sync-call-recordKnown gap: the static definition does not yet declare `callRecording`'s `searchVector` GIN index (every other searchable standard object declares its GIN index statically), so workspaces upgrading through 2-10 on the legacy path create the `searchVector` column unindexed. The static declaration plus a backfill for already-upgraded workspaces land in a follow-up (twentyhq/core-team-issues#2672), which must ship in the same release as this legacy path.+## Keeping command code in the command++An upgrade command is frozen once released: self-hosters can jump several versions in one upgrade, so the code that runs for them is whatever the current release ships for that old command. Two rules follow.++- **Command logic lives in its version folder.** Helpers, SQL builders, constants and legacy formats that only a command needs go under `upgrade-version-command/<version>/` (or its `utils/`), never in `src/engine` or `src/modules`. Generic primitives (flat-entity utils, schema managers, repositories) are fine to call. The `twenty/no-runtime-import-from-upgrade-command` lint rule rejects runtime imports from `upgrade-version-command/`, except the `*-upgrade-command-name.constant` files that upgrade-aware entities use.+- **Runtime code never branches on migration state.** Do not teach the runtime to serve both the old and the new shape. When a runtime must not run against a workspace mid-migration, fence it with one explicit check and remove that check once the command leaves the cross-upgrade window.++A command should also not reach into runtime services to do its work. Their behavior changes with every release; the command's must not.+## Execution OrderWithin a given version of Twenty, the upgrade pipeline runs commands in this order, sorted by timestamp within each group:diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/build-timeline-activity-type-backfill-query.util.spec.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/build-timeline-activity-type-backfill-query.util.spec.tsindex f8c7e80b8fe..c7288930c58 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/build-timeline-activity-type-backfill-query.util.spec.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/build-timeline-activity-type-backfill-query.util.spec.ts@@ -2,7 +2,7 @@ import { buildTimelineActivityTypeBackfillQuery } from 'src/database/commands/upimport { STANDARD_OBJECTS } from 'twenty-shared/metadata';import { isDefined } from 'twenty-shared/utils';-import { type TimelineActivityTypeResolutionMaps } from 'src/modules/timeline/utils/resolve-timeline-activity-type-id.util';+import { type TimelineActivityTypeResolutionMaps } from 'src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util';const TYPE_ID_BY_ACTION = {created: '00000000-0000-4000-8000-000000000001',@@ -35,7 +35,9 @@ const getTypeIdForCondition = (condition: string,): string | undefined => {const placeholder = query.sql.match(- new RegExp(`WHEN ${condition.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} THEN \\$(\\d+)::uuid`),+ new RegExp(+ `WHEN ${condition.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} THEN \\$(\\d+)::uuid`,+ ),);return isDefined(placeholder)@@ -180,8 +182,8 @@ describe('buildTimelineActivityTypeBackfillQuery', () => {buildFlatTimelineActivityTypeMapsWithObjectBoundTypes(),});- expect(query!.sql.indexOf(`WHEN "name" = 'linked-note.created'`)).toBeLessThan(- query!.sql.indexOf(`WHEN "name" LIKE 'linked-%'`),- );+ expect(+ query!.sql.indexOf(`WHEN "name" = 'linked-note.created'`),+ ).toBeLessThan(query!.sql.indexOf(`WHEN "name" LIKE 'linked-%'`));});});diff --git a/packages/twenty-server/src/modules/timeline/utils/__tests__/resolve-timeline-activity-type-id.util.spec.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/resolve-timeline-activity-type-id.util.spec.tssimilarity index 95%rename from packages/twenty-server/src/modules/timeline/utils/__tests__/resolve-timeline-activity-type-id.util.spec.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/resolve-timeline-activity-type-id.util.spec.tsindex 7827e923417..8eee8c7e1dd 100644--- a/packages/twenty-server/src/modules/timeline/utils/__tests__/resolve-timeline-activity-type-id.util.spec.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/resolve-timeline-activity-type-id.util.spec.ts@@ -1,7 +1,7 @@import {buildTimelineActivityTypeResolver,type TimelineActivityTypeResolutionMaps,-} from 'src/modules/timeline/utils/resolve-timeline-activity-type-id.util';+} from 'src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util';const SHARED_LINKED_ID = '00000000-0000-4000-8000-000000000001';const NOTE_LINKED_ID = '00000000-0000-4000-8000-000000000002';diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/build-timeline-activity-type-backfill-query.util.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/build-timeline-activity-type-backfill-query.util.tsindex 0cdd5165ef2..2807a1c7e37 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/build-timeline-activity-type-backfill-query.util.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/build-timeline-activity-type-backfill-query.util.ts@@ -5,7 +5,7 @@ import { isDefined } from 'twenty-shared/utils';import {buildTimelineActivityTypeResolver,type TimelineActivityTypeResolutionMaps,-} from 'src/modules/timeline/utils/resolve-timeline-activity-type-id.util';+} from 'src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util';// The legacy name held `<object>.<databaseAction>` for a record's own events and// `linked-<object>.<databaseAction>` for events about a linked record. A junction@@ -30,8 +30,14 @@ const SELF_ACTION_BY_DATABASE_ACTION: Record<string, TimelineActivityAction> = {// events through their own listeners, which is why only the first two carry the// `linked-` prefix.const LEGACY_JUNCTION_OBJECTS = [- { legacyName: 'note', universalIdentifier: STANDARD_OBJECTS.note.universalIdentifier },- { legacyName: 'task', universalIdentifier: STANDARD_OBJECTS.task.universalIdentifier },+ {+ legacyName: 'note',+ universalIdentifier: STANDARD_OBJECTS.note.universalIdentifier,+ },+ {+ legacyName: 'task',+ universalIdentifier: STANDARD_OBJECTS.task.universalIdentifier,+ },] as const;const LEGACY_PARTICIPANT_NAMES = [diff --git a/packages/twenty-server/src/modules/timeline/utils/resolve-timeline-activity-type-id.util.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util.tssimilarity index 100%rename from packages/twenty-server/src/modules/timeline/utils/resolve-timeline-activity-type-id.util.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util.tsdiff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-37/2-37-workspace-command-1787832413051-backfill-message-calendar-targets.command.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-37/2-37-workspace-command-1787832413051-backfill-message-calendar-targets.command.tsindex 20b7898e78e..8ac6d22c48a 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-37/2-37-workspace-command-1787832413051-backfill-message-calendar-targets.command.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-37/2-37-workspace-command-1787832413051-backfill-message-calendar-targets.command.ts@@ -9,7 +9,7 @@ import { RegisteredWorkspaceCommand } from 'src/engine/core-modules/upgrade/decoimport {MESSAGE_CALENDAR_TARGET_BACKFILL_TIMESTAMP,MESSAGE_CALENDAR_TARGET_MIGRATION_VERSION,-} from 'src/engine/core-modules/target/constants/message-calendar-target-migration.constants';+} from 'src/database/commands/upgrade-version-command/2-37/message-calendar-target-migration.constant';import { getWorkspaceSchemaName } from 'src/engine/workspace-datasource/utils/get-workspace-schema-name.util';const BACKFILL_BATCH_SIZE = 5_000;diff --git a/packages/twenty-server/src/engine/core-modules/target/constants/message-calendar-target-migration.constants.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-37/message-calendar-target-migration.constant.tssimilarity index 100%rename from packages/twenty-server/src/engine/core-modules/target/constants/message-calendar-target-migration.constants.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-37/message-calendar-target-migration.constant.tsdiff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-workspace-command-1788338950836-convert-logic-functions-to-prebuilt.command.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-workspace-command-1788338950836-convert-logic-functions-to-prebuilt.command.tsindex 060d3137bc3..97917f446f1 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-workspace-command-1788338950836-convert-logic-functions-to-prebuilt.command.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-workspace-command-1788338950836-convert-logic-functions-to-prebuilt.command.ts@@ -21,7 +21,7 @@ import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/import { LogicFunctionExecutionMode } from 'src/engine/metadata-modules/logic-function/logic-function.entity';import { type FlatLogicFunctionMaps } from 'src/engine/metadata-modules/logic-function/types/flat-logic-function-maps.type';import { type FlatLogicFunction } from 'src/engine/metadata-modules/logic-function/types/flat-logic-function.type';-import { isLogicFunctionEligibleForPrebuiltConversion } from 'src/engine/metadata-modules/logic-function/utils/is-logic-function-eligible-for-prebuilt-conversion.util';+import { isLogicFunctionEligibleForPrebuiltConversion } from 'src/database/commands/upgrade-version-command/2-39/utils/is-logic-function-eligible-for-prebuilt-conversion.util';import { UpdateLogicFunctionActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/logic-function/services/update-logic-function-action-handler.service';const LOGIC_FUNCTION_PREBUILT_CONVERSION_BATCH_SIZE = 100;diff --git a/packages/twenty-server/src/engine/metadata-modules/logic-function/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.tssimilarity index 95%rename from packages/twenty-server/src/engine/metadata-modules/logic-function/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.tsindex 1c97705a718..2c89cd3dc14 100644--- a/packages/twenty-server/src/engine/metadata-modules/logic-function/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.ts@@ -3,7 +3,7 @@ import { LogicFunctionExecutionMode } from 'src/engine/metadata-modules/logic-fuimport {isLogicFunctionEligibleForPrebuiltConversion,type LogicFunctionPrebuiltConversionFields,-} from 'src/engine/metadata-modules/logic-function/utils/is-logic-function-eligible-for-prebuilt-conversion.util';+} from 'src/database/commands/upgrade-version-command/2-39/utils/is-logic-function-eligible-for-prebuilt-conversion.util';const buildFlatLogicFunction = (overrides: Partial<LogicFunctionPrebuiltConversionFields> = {},diff --git a/packages/twenty-server/src/engine/metadata-modules/logic-function/utils/is-logic-function-eligible-for-prebuilt-conversion.util.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/is-logic-function-eligible-for-prebuilt-conversion.util.tssimilarity index 100%rename from packages/twenty-server/src/engine/metadata-modules/logic-function/utils/is-logic-function-eligible-for-prebuilt-conversion.util.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/is-logic-function-eligible-for-prebuilt-conversion.util.tsdiff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000005000-encrypt-application-variable.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000005000-encrypt-application-variable.tsindex a703653a630..ab72f028808 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000005000-encrypt-application-variable.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000005000-encrypt-application-variable.ts@@ -3,6 +3,7 @@ import { Logger } from '@nestjs/common';import { isDefined } from 'twenty-shared/utils';import { DataSource, QueryRunner } from 'typeorm';+import { legacyDecryptVersionedWithFallback } from 'src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util';import { type EncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/encrypted-string.type';import { isEncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/is-encrypted-string.util';import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';@@ -85,11 +86,11 @@ export class EncryptApplicationVariableSlowInstanceCommandif (looksLikeLegacyCtrCiphertext(row.value)) {try {- plaintext =- this.secretEncryptionService.legacyDecryptVersionedWithFallback(- row.value as EncryptedString,- { workspaceId: row.workspaceId },- );+ plaintext = legacyDecryptVersionedWithFallback({+ secretEncryptionService: this.secretEncryptionService,+ value: row.value as EncryptedString,+ workspaceId: row.workspaceId,+ });} catch (error) {this.logger.warn(`applicationVariable row ${row.id} value not valid ciphertext; treating as plaintext. ${diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000006000-encrypt-application-registration-variable.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000006000-encrypt-application-registration-variable.tsindex cad38a8d2b8..2a20bd7c63b 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000006000-encrypt-application-registration-variable.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000006000-encrypt-application-registration-variable.ts@@ -1,6 +1,7 @@import { isDefined } from 'twenty-shared/utils';import { DataSource, QueryRunner } from 'typeorm';+import { legacyDecryptVersionedWithFallback } from 'src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util';import { type EncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/encrypted-string.type';import { isEncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/is-encrypted-string.util';import { SECRET_ENCRYPTION_ENVELOPE_V2_PREFIX } from 'src/engine/core-modules/secret-encryption/constants/secret-encryption.constant';@@ -57,10 +58,10 @@ export class EncryptApplicationRegistrationVariableSlowInstanceCommandcontinue;}- const plaintext =- this.secretEncryptionService.legacyDecryptVersionedWithFallback(- row.encryptedValue as EncryptedString,- );+ const plaintext = legacyDecryptVersionedWithFallback({+ secretEncryptionService: this.secretEncryptionService,+ value: row.encryptedValue as EncryptedString,+ });if (!isDefined(plaintext)) {continue;diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000007000-encrypt-signing-key-private-keys.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000007000-encrypt-signing-key-private-keys.tsindex b2b016526f5..f56978ea660 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000007000-encrypt-signing-key-private-keys.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000007000-encrypt-signing-key-private-keys.ts@@ -1,6 +1,7 @@import { isDefined } from 'twenty-shared/utils';import { DataSource, QueryRunner } from 'typeorm';+import { legacyDecryptVersionedWithFallback } from 'src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util';import { type EncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/encrypted-string.type';import { isEncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/is-encrypted-string.util';import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';@@ -54,10 +55,10 @@ export class EncryptSigningKeyPrivateKeysSlowInstanceCommand implements SlowInstcontinue;}- const plaintext =- this.secretEncryptionService.legacyDecryptVersionedWithFallback(- row.privateKey as EncryptedString,- );+ const plaintext = legacyDecryptVersionedWithFallback({+ secretEncryptionService: this.secretEncryptionService,+ value: row.privateKey as EncryptedString,+ });if (!isDefined(plaintext)) {continue;diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000008000-encrypt-sensitive-config-storage.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000008000-encrypt-sensitive-config-storage.tsindex e8556797d18..47a08a1cf9e 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000008000-encrypt-sensitive-config-storage.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000008000-encrypt-sensitive-config-storage.ts@@ -1,6 +1,7 @@import { isDefined } from 'twenty-shared/utils';import { DataSource, QueryRunner } from 'typeorm';+import { legacyDecryptVersionedWithFallback } from 'src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util';import { KeyValuePairType } from 'src/engine/core-modules/key-value-pair/key-value-pair.entity';import { type EncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/encrypted-string.type';import { isEncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/is-encrypted-string.util';@@ -57,10 +58,10 @@ export class EncryptSensitiveConfigStorageSlowInstanceCommand implements SlowInscontinue;}- const plaintext =- this.secretEncryptionService.legacyDecryptVersionedWithFallback(- rawValue as EncryptedString,- );+ const plaintext = legacyDecryptVersionedWithFallback({+ secretEncryptionService: this.secretEncryptionService,+ value: rawValue as EncryptedString,+ });if (!isDefined(plaintext)) {continue;diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.tsindex 4a4da98a6c7..999fd984745 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.ts@@ -4,7 +4,7 @@ import { DataSource, QueryRunner } from 'typeorm';import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';import { SECRET_ENCRYPTION_ENVELOPE_V2_PREFIX } from 'src/engine/core-modules/secret-encryption/constants/secret-encryption.constant';import { SecretEncryptionService } from 'src/engine/core-modules/secret-encryption/secret-encryption.service';-import { SimpleSecretEncryptionUtil } from 'src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util';+import { SimpleSecretEncryptionUtil } from 'src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util';import { RegisteredInstanceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-instance-command.decorator';import { SlowInstanceCommand } from 'src/engine/core-modules/upgrade/interfaces/slow-instance-command.interface';diff --git a/packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.spec.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/__tests__/simple-secret-encryption.util.spec.tssimilarity index 96%rename from packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.spec.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/__tests__/simple-secret-encryption.util.spec.tsindex bc80a76f216..dc5a9df302e 100644--- a/packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.spec.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/__tests__/simple-secret-encryption.util.spec.ts@@ -5,7 +5,7 @@ import { createCipheriv, createHash, randomBytes } from 'crypto';import { JwtTokenTypeEnum } from 'src/engine/core-modules/auth/types/jwt-token-type.enum';import { JwtWrapperService } from 'src/engine/core-modules/jwt/services/jwt-wrapper.service';-import { SimpleSecretEncryptionUtil } from './simple-secret-encryption.util';+import { SimpleSecretEncryptionUtil } from 'src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util';// Mirrors the production write path the util used to perform; kept inside// the spec so the deprecated decryptSecret can still be exercised end-to-enddiff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util.tsnew file mode 100644index 00000000000..d7f1a37b712--- /dev/null+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/legacy-decrypt-versioned-with-fallback.util.ts@@ -0,0 +1,32 @@+import { isDefined } from 'twenty-shared/utils';++import { type EncryptedString } from 'src/engine/core-modules/secret-encryption/branded-strings/encrypted-string.type';+import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';+import { type SecretEncryptionService } from 'src/engine/core-modules/secret-encryption/secret-encryption.service';+import { parseSecretEncryptionEnvelopeOrThrow } from 'src/engine/core-modules/secret-encryption/utils/parse-secret-encryption-envelope-or-throw.util';++// Pre-2.5 rows hold legacy AES-CTR ciphertext; rows already backfilled hold an+// enc:v2 envelope. The 2.5 encryption backfills must read both.+export const legacyDecryptVersionedWithFallback = ({+ secretEncryptionService,+ value,+ workspaceId,+}: {+ secretEncryptionService: SecretEncryptionService;+ value: EncryptedString;+ workspaceId?: string;+}): PlaintextString => {+ if (!isDefined(value)) {+ return value;+ }++ const parsed = parseSecretEncryptionEnvelopeOrThrow({ value });++ if (parsed.version === 2) {+ return secretEncryptionService.decryptVersionedOrThrow(value, {+ workspaceId,+ });+ }++ return secretEncryptionService.decrypt(value) as PlaintextString;+};diff --git a/packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util.tssimilarity index 65%rename from packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util.tsindex cc2f5419886..8fb45db30d2 100644--- a/packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util.ts@@ -6,17 +6,8 @@ import { JwtTokenTypeEnum } from 'src/engine/core-modules/auth/types/jwt-token-timport { JwtWrapperService } from 'src/engine/core-modules/jwt/services/jwt-wrapper.service';import { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';-// TODO: delete this util once the 2.5 cross-upgrade window closes and every-// `core.twoFactorAuthenticationMethod.secret` row is known to be in the-// `enc:v2:` envelope. Also drop the call sites in TwoFactorAuthenticationService-// and the matching slow instance command, and stop providing this util in-// TwoFactorAuthenticationModule and InstanceCommandProviderModule.-/**- * @deprecated Legacy TOTP secret decryption (AES-256-CBC keyed off- * `APP_SECRET + userId + workspaceId + 'otp-secret' + 'KEY_ENCRYPTION_KEY'`).- * Kept only to read pre-2.5 rows during the cross-upgrade window. New rows are- * written by `SecretEncryptionService.encryptVersioned` (enc:v2 envelope).- */+// Legacy TOTP secret decryption (AES-256-CBC), used only by the 2.5+// encrypt-totp-secrets slow command to re-encrypt pre-2.5 rows into enc:v2.@Injectable()export class SimpleSecretEncryptionUtil {private readonly algorithm = 'aes-256-cbc';diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-instance-command-slow-1799000010000-migrate-ai-model-preferences.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-instance-command-slow-1799000010000-migrate-ai-model-preferences.tsindex 9bf4168d6a6..184560bd739 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-instance-command-slow-1799000010000-migrate-ai-model-preferences.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-instance-command-slow-1799000010000-migrate-ai-model-preferences.ts@@ -9,7 +9,7 @@ import {} from 'src/engine/core-modules/key-value-pair/key-value-pair.entity';import { RegisteredInstanceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-instance-command.decorator';import { SlowInstanceCommand } from 'src/engine/core-modules/upgrade/interfaces/slow-instance-command.interface';-import { aiModelPreferencesSchema } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-preferences.schema';+import { aiModelPreferencesSchema } from 'src/database/commands/upgrade-version-command/2-9/ai-model-preferences.schema';const NEW_KEYS = ['AI_MODELS_DEFAULT_FAST',diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000000000-migrate-ai-model-preferences.command.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000000000-migrate-ai-model-preferences.command.tsindex c05361d39f8..97a4b5d332f 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000000000-migrate-ai-model-preferences.command.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/2-9-workspace-command-1799000000000-migrate-ai-model-preferences.command.ts@@ -12,7 +12,7 @@ import {KeyValuePairType,} from 'src/engine/core-modules/key-value-pair/key-value-pair.entity';import { RegisteredWorkspaceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-workspace-command.decorator';-import { aiModelPreferencesSchema } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-preferences.schema';+import { aiModelPreferencesSchema } from 'src/database/commands/upgrade-version-command/2-9/ai-model-preferences.schema';const NEW_KEYS = ['AI_MODELS_DEFAULT_FAST',diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-preferences.schema.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-9/ai-model-preferences.schema.tssimilarity index 100%rename from packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-preferences.schema.tsrename to packages/twenty-server/src/database/commands/upgrade-version-command/2-9/ai-model-preferences.schema.tsdiff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/instance-command-provider.module.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/instance-command-provider.module.tsindex 7f5230f6d1c..5c5fce2aa07 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/instance-command-provider.module.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/instance-command-provider.module.ts@@ -3,7 +3,7 @@ import { Module } from '@nestjs/common';import { INSTANCE_COMMANDS } from 'src/database/commands/upgrade-version-command/instance-commands.constant';import { JwtModule } from 'src/engine/core-modules/jwt/jwt.module';import { SecretEncryptionModule } from 'src/engine/core-modules/secret-encryption/secret-encryption.module';-import { SimpleSecretEncryptionUtil } from 'src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util';+import { SimpleSecretEncryptionUtil } from 'src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util';import { ConnectedAccountTokenEncryptionModule } from 'src/engine/metadata-modules/connected-account/services/connected-account-token-encryption.module';import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache.module';diff --git a/packages/twenty-server/src/engine/core-modules/secret-encryption/secret-encryption.service.ts b/packages/twenty-server/src/engine/core-modules/secret-encryption/secret-encryption.service.tsindex a37354522aa..9ffc4cc9957 100644--- a/packages/twenty-server/src/engine/core-modules/secret-encryption/secret-encryption.service.ts+++ b/packages/twenty-server/src/engine/core-modules/secret-encryption/secret-encryption.service.ts@@ -1,4 +1,4 @@-import { Injectable, Logger } from '@nestjs/common';+import { Injectable } from '@nestjs/common';import { isDefined } from 'twenty-shared/utils';@@ -26,9 +26,6 @@ type VersionedOptions = {@Injectable()export class SecretEncryptionService {- private readonly logger = new Logger(SecretEncryptionService.name);- private hasLoggedLegacyCtrDecryption = false;-constructor(private readonly environmentConfigDriver: EnvironmentConfigDriver,) {}@@ -143,52 +140,4 @@ export class SecretEncryptionService {workspaceId: opts.workspaceId,}) as PlaintextString;}-- /**- * @deprecated Legacy variant kept only for the 2.5 encryption backfill- * instance commands, which read pre-v2 rows (legacy AES-CTR ciphertext or- * plaintext) and re-encrypt them into the enc:v2 envelope. Runtime and- * rotation paths must use `decryptVersionedOrThrow` instead.- */- public legacyDecryptVersionedWithFallback(- value: EncryptedString,- opts: VersionedOptions = {},- ): PlaintextString {- if (!isDefined(value)) {- return value;- }-- const parsed = parseSecretEncryptionEnvelopeOrThrow({ value });-- if (parsed.version === 2) {- const keys = resolveEncryptionKeysOrThrow({- environmentConfigDriver: this.environmentConfigDriver,- });- const rawKey = pickEncryptionKeyByKeyIdOrThrow({- keyId: parsed.keyId,- keys,- });-- return decryptAesGcmV2OrThrow({- payloadBase64: parsed.payload,- rawKey,- workspaceId: opts.workspaceId,- }) as PlaintextString;- }-- this.warnLegacyCtrDecryptionOnce();-- return this.decrypt(value) as PlaintextString;- }-- private warnLegacyCtrDecryptionOnce(): void {- if (this.hasLoggedLegacyCtrDecryption) {- return;- }-- this.hasLoggedLegacyCtrDecryption = true;- this.logger.warn(- 'Decrypted a legacy unprefixed AES-CTR ciphertext. These rows should be re-encrypted into the enc:v2 envelope in a follow-up migration.',- );- }}diff --git a/packages/twenty-server/test/integration/upgrade/suites/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.integration-spec.ts b/packages/twenty-server/test/integration/upgrade/suites/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.integration-spec.tsindex 71b8fa2e163..80a8729237d 100644--- a/packages/twenty-server/test/integration/upgrade/suites/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.integration-spec.ts+++ b/packages/twenty-server/test/integration/upgrade/suites/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets.integration-spec.ts@@ -11,7 +11,7 @@ import { type JwtWrapperService } from 'src/engine/core-modules/jwt/services/jwtimport { type PlaintextString } from 'src/engine/core-modules/secret-encryption/branded-strings/plaintext-string.type';import { SECRET_ENCRYPTION_ENVELOPE_V2_PREFIX } from 'src/engine/core-modules/secret-encryption/constants/secret-encryption.constant';import { SecretEncryptionService } from 'src/engine/core-modules/secret-encryption/secret-encryption.service';-import { SimpleSecretEncryptionUtil } from 'src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util';+import { SimpleSecretEncryptionUtil } from 'src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util';import { EncryptTotpSecretsSlowInstanceCommand } from 'src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets';