Skip to content

The open alternative to Salesforce, designed for AI.

Keep upgrade command code in its version folder (#26672)

Félix Malfaitfff96c016877
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
index 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.md
index 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-record
Known 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 Order
Within 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.ts
index 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/up
import { 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.ts
similarity index 95%
rename from packages/twenty-server/src/modules/timeline/utils/__tests__/resolve-timeline-activity-type-id.util.spec.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/__tests__/resolve-timeline-activity-type-id.util.spec.ts
index 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.ts
index 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.ts
similarity index 100%
rename from packages/twenty-server/src/modules/timeline/utils/resolve-timeline-activity-type-id.util.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-33/utils/resolve-timeline-activity-type-id.util.ts
diff --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.ts
index 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/deco
import {
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.ts
similarity index 100%
rename from packages/twenty-server/src/engine/core-modules/target/constants/message-calendar-target-migration.constants.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-37/message-calendar-target-migration.constant.ts
diff --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.ts
index 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.ts
similarity index 95%
rename from packages/twenty-server/src/engine/metadata-modules/logic-function/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/__tests__/is-logic-function-eligible-for-prebuilt-conversion.util.spec.ts
index 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-fu
import {
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.ts
similarity index 100%
rename from packages/twenty-server/src/engine/metadata-modules/logic-function/utils/is-logic-function-eligible-for-prebuilt-conversion.util.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-39/utils/is-logic-function-eligible-for-prebuilt-conversion.util.ts
diff --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.ts
index 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 EncryptApplicationVariableSlowInstanceCommand
if (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.ts
index 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 EncryptApplicationRegistrationVariableSlowInstanceCommand
continue;
}
- 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.ts
index 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 SlowInst
continue;
}
- 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.ts
index 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 SlowIns
continue;
}
- 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.ts
index 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.ts
similarity index 96%
rename from packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.spec.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/__tests__/simple-secret-encryption.util.spec.ts
index 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-end
diff --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.ts
new file mode 100644
index 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.ts
similarity index 65%
rename from packages/twenty-server/src/engine/core-modules/two-factor-authentication/utils/simple-secret-encryption.util.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-5/utils/simple-secret-encryption.util.ts
index 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-t
import { 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.ts
index 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.ts
index 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.ts
similarity index 100%
rename from packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-preferences.schema.ts
rename to packages/twenty-server/src/database/commands/upgrade-version-command/2-9/ai-model-preferences.schema.ts
diff --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.ts
index 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.ts
index 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.ts
index 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/jwt
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 { EncryptTotpSecretsSlowInstanceCommand } from 'src/database/commands/upgrade-version-command/2-5/2-5-instance-command-slow-1798000009000-encrypt-totp-secrets';