feat(twenty-server): introduce ENCRYPTION_KEY env var with versioned envelope (#20528)

## Summary

- Adds `ENCRYPTION_KEY` (primary) and `FALLBACK_ENCRYPTION_KEY`
(decrypt-only fallback for rotation) env vars to twenty-server, with
backward-compatible fallback to `APP_SECRET` when `ENCRYPTION_KEY` is
unset.
- Introduces a versioned ciphertext envelope `enc:v2:<keyId>:<base64>`
using AES-256-GCM with HKDF-SHA256 derived per-context keys. The 8-hex
`keyId` fingerprint lets every row identify which physical key encrypted
it, so rotation routes directly to primary or fallback without trial
decryption; GCM's auth tag gives true integrity (legacy CTR has none).
- Migrates `ConnectedAccountTokenEncryptionService` to the new envelope
and plumbs `workspaceId` through every caller, so per-workspace HKDF
context binds each row to its tenant.

The remaining encryption sites (`jwt-key-manager`, `config-storage`,
`postgres-credentials`, `application-variable`, TOTP) stay on the legacy
unprefixed CTR path and will be migrated in follow-up PRs. The
operator-facing rotation runbook is out of scope here.

### Format details

`enc:v{N}:{keyId}:{base64}` — `N=2` is the only version produced by new
writes (`v1` exists for backward-compatible decryption of existing
connected-account rows). `keyId =
sha256(rawKey).slice(0,4).toString('hex')`. The CHECK constraint on
`core.connectedAccount.{accessToken,refreshToken}` is relaxed from `LIKE
'enc:v1:%'` to `LIKE 'enc:v_:%'` so both versions pass.

### Key resolution

| `ENCRYPTION_KEY` | `FALLBACK_ENCRYPTION_KEY` | `APP_SECRET` | Encrypt
with | Decrypt try order |
|---|---|---|---|---|
| set | set | (any) | `ENCRYPTION_KEY` | match `keyId` → primary →
fallback |
| set | unset | (any) | `ENCRYPTION_KEY` | match `keyId` → primary |
| unset | set | set | `APP_SECRET` | match `keyId` → `APP_SECRET` →
fallback |
| unset | unset | set | `APP_SECRET` | match `keyId` → `APP_SECRET` |
| unset | unset | unset | startup error | n/a |

## Test plan

- [x] `npx nx typecheck twenty-server` — clean
- [x] `npx jest
'secret-encryption|connected-account-token-encryption|connected-account-refresh-tokens|encrypt-connected-account-tokens|connection-provider-oauth-flow'`
— 87 tests pass
- [x] New `secret-encryption.service.versioned.spec.ts` covers: key
resolution table (no-key error, APP_SECRET fallback, ENCRYPTION_KEY
precedence), v2 round-trip with/without workspaceId, GCM tamper
rejection, workspaceId-mismatch rejection, keyId-based primary→fallback
routing, missing-key error names the fingerprint, v1 legacy decryption,
no-prefix legacy decryption, malformed envelope rejection.
- [x] Updated `connected-account-token-encryption.service.spec.ts`
covers workspaceId binding and HKDF context isolation.
- [x] Updated slow instance command spec verifies workspaceId is
threaded through encryption and the relaxed `enc:v_:%` LIKE pattern
matches both v1 and v2.
- [ ] Manual E2E: connect a Gmail account on a freshly deployed instance
with `APP_SECRET` only → confirm `core.connectedAccount.accessToken` is
`enc:v2:<keyId>:<base64>`.
- [ ] Manual E2E: rotate — set `ENCRYPTION_KEY=<new>` and
`FALLBACK_ENCRYPTION_KEY=<old APP_SECRET>`, restart, confirm
pre-rotation rows still decrypt and new rows carry the new `keyId`.
- [ ] Manual E2E: missing key — set `ENCRYPTION_KEY=<new>` without the
fallback, confirm decrypt error names the old `keyId` so the operator
can identify the missing key.

packages/twenty-server/src/modules/messaging/message-folder-manager/drivers/gmail/services/gmail-get-all-folders.service.ts

@@ -28,7 +28,12 @@ export class GmailGetAllFoldersService implements MessageFolderDriver {
   async getAllMessageFolders(
     connectedAccount: Pick<
       ConnectedAccountEntity,
-      'provider' | 'refreshToken' | 'accessToken' | 'id' | 'handle'
+      | 'provider'
+      | 'refreshToken'
+      | 'accessToken'
+      | 'id'
+      | 'handle'
+      | 'workspaceId'
     >,
     messageChannel: Pick<MessageChannelEntity, 'messageFolderImportPolicy'>,
   ): Promise<DiscoveredMessageFolder[]> {

packages/twenty-server/src/modules/messaging/message-folder-manager/drivers/microsoft/services/microsoft-get-all-folders.service.ts

@@ -38,7 +38,12 @@ export class MicrosoftGetAllFoldersService implements MessageFolderDriver {
   async getAllMessageFolders(
     connectedAccount: Pick<
       ConnectedAccountEntity,
-      'accessToken' | 'refreshToken' | 'id' | 'handle' | 'provider'
+      | 'accessToken'
+      | 'refreshToken'
+      | 'id'
+      | 'handle'
+      | 'provider'
+      | 'workspaceId'
     >,
     messageChannel: Pick<MessageChannelEntity, 'messageFolderImportPolicy'>,
   ): Promise<DiscoveredMessageFolder[]> {

packages/twenty-server/src/modules/messaging/message-folder-manager/interfaces/message-folder-driver.interface.ts

@@ -29,6 +29,7 @@ export type MessageFolderDriver = {
       | 'id'
       | 'handle'
       | 'connectionParameters'
+      | 'workspaceId'
     >,
     messageChannel: Pick<MessageChannelEntity, 'messageFolderImportPolicy'>,
   ): Promise<DiscoveredMessageFolder[]>;

packages/twenty-server/src/modules/messaging/message-folder-manager/services/sync-message-folders.service.spec.ts

@@ -49,6 +49,7 @@ const createMockMessageChannel = (
     accessToken: 'mock-access-token',
     refreshToken: 'mock-refresh-token',
     connectionParameters: {},
+    workspaceId: 'workspace-123',
   },
   messageFolders: overrides.messageFolders ?? [],
   visibility: MessageChannelVisibility.SHARE_EVERYTHING,

packages/twenty-server/src/modules/messaging/message-folder-manager/services/sync-message-folders.service.ts

@@ -53,6 +53,7 @@ export class SyncMessageFoldersService {
         | 'id'
         | 'handle'
         | 'connectionParameters'
+        | 'workspaceId'
       >;
       messageFolders: MessageFolder[];
     };
@@ -83,6 +84,7 @@ export class SyncMessageFoldersService {
       | 'handle'
       | 'provider'
       | 'connectionParameters'
+      | 'workspaceId'
     >,
     messageChannel: Pick<MessageChannelEntity, 'messageFolderImportPolicy'>,
   ): Promise<DiscoveredMessageFolder[]> {

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/services/gmail-get-message-list.service.spec.ts

@@ -40,6 +40,7 @@ describe('GmailGetMessageListService', () => {
     | 'id'
     | 'handle'
     | 'connectionParameters'
+    | 'workspaceId'
   > = {
     id: 'connected-account-id',
     provider: ConnectedAccountProvider.GOOGLE,
@@ -47,6 +48,7 @@ describe('GmailGetMessageListService', () => {
     refreshToken: 'refresh-token',
     handle: 'test@gmail.com',
     connectionParameters: {},
+    workspaceId: 'workspace-id',
   };
 
   beforeEach(async () => {

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/services/gmail-get-message-list.service.ts

@@ -31,7 +31,12 @@ export class GmailGetMessageListService {
   private async getMessageListWithoutCursor(
     connectedAccount: Pick<
       ConnectedAccountEntity,
-      'provider' | 'accessToken' | 'refreshToken' | 'id' | 'handle'
+      | 'provider'
+      | 'accessToken'
+      | 'refreshToken'
+      | 'id'
+      | 'handle'
+      | 'workspaceId'
     >,
     messageFolders: Pick<
       MessageFolderEntity,

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/services/gmail-get-messages.service.ts

@@ -33,6 +33,7 @@ export class GmailGetMessagesService {
       | 'id'
       | 'handle'
       | 'handleAliases'
+      | 'workspaceId'
     >,
     messageChannel: Pick<
       MessageChannelEntity,

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/imap/services/imap-get-message-list.service.spec.ts

@@ -38,6 +38,7 @@ describe('ImapGetMessageListService', () => {
     | 'id'
     | 'handle'
     | 'connectionParameters'
+    | 'workspaceId'
   > = {
     id: 'connected-account-id',
     provider: ConnectedAccountProvider.IMAP_SMTP_CALDAV,
@@ -45,6 +46,7 @@ describe('ImapGetMessageListService', () => {
     refreshToken: 'refresh-token',
     handle: 'test@example.com',
     connectionParameters: {},
+    workspaceId: 'workspace-id',
   };
 
   const mockImapClient = {

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-fetch-by-batch.service.ts

@@ -14,7 +14,7 @@ export class MicrosoftFetchByBatchService {
     messageIds: string[],
     connectedAccount: Pick<
       ConnectedAccountEntity,
-      'accessToken' | 'refreshToken' | 'id' | 'provider'
+      'accessToken' | 'refreshToken' | 'id' | 'provider' | 'workspaceId'
     >,
   ): Promise<{
     messageIdsByBatch: string[][];

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-message-list.service.dev.spec.ts

@@ -32,6 +32,7 @@ const mockConnectedAccount: Pick<
   | 'id'
   | 'handle'
   | 'connectionParameters'
+  | 'workspaceId'
 > = {
   id: 'connected-account-id',
   provider: ConnectedAccountProvider.MICROSOFT,
@@ -39,6 +40,7 @@ const mockConnectedAccount: Pick<
   refreshToken: refreshToken,
   handle: 'test@gmail.com',
   connectionParameters: {},
+  workspaceId: 'workspace-id',
 };
 
 const mockMessageChannel: Pick<
@@ -103,6 +105,7 @@ xdescribe('Microsoft dev tests : get message list service', () => {
       refreshToken: 'invalid-token',
       handle: 'test@microsoft.com',
       connectionParameters: {},
+      workspaceId: 'workspace-id',
     };
 
     await expect(

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-message-list.service.spec.ts

@@ -37,6 +37,7 @@ describe('MicrosoftGetMessageListService', () => {
     | 'id'
     | 'handle'
     | 'connectionParameters'
+    | 'workspaceId'
   > = {
     id: 'connected-account-id',
     provider: ConnectedAccountProvider.MICROSOFT,
@@ -44,6 +45,7 @@ describe('MicrosoftGetMessageListService', () => {
     refreshToken: 'refresh-token',
     handle: 'test@outlook.com',
     connectionParameters: {},
+    workspaceId: 'workspace-id',
   };
 
   const createMockMicrosoftClient = () => ({

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-message-list.service.ts

@@ -73,7 +73,7 @@ export class MicrosoftGetMessageListService {
   public async getMessageList(
     connectedAccount: Pick<
       ConnectedAccountEntity,
-      'provider' | 'accessToken' | 'id'
+      'provider' | 'accessToken' | 'id' | 'workspaceId'
     >,
     messageFolder: Pick<
       MessageFolderEntity,

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-messages.service.dev.spec.ts

@@ -52,6 +52,7 @@ xdescribe('Microsoft dev tests : get messages service', () => {
     handleAliases: [] as string[],
     accessToken: accessToken,
     refreshToken: refreshToken,
+    workspaceId: 'workspace-id',
   };
 
   it('should fetch and format messages successfully', async () => {

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-messages.service.spec.ts

@@ -72,6 +72,7 @@ describe('Microsoft get messages service', () => {
       refreshToken: 'refresh-token',
       handle: 'John.l@outlook.fr',
       handleAliases: [] as string[],
+      workspaceId: 'workspace-id',
     };
     const messages = service.formatBatchResponsesAsMessages(
       batchResponses,
@@ -173,6 +174,7 @@ describe('Microsoft get messages service', () => {
       refreshToken: 'refresh-token',
       handle: 'John.l@outlook.fr',
       handleAliases: [] as string[],
+      workspaceId: 'workspace-id',
     };
     const messages = service.formatBatchResponsesAsMessages(
       batchResponses,

packages/twenty-server/src/modules/messaging/message-import-manager/drivers/microsoft/services/microsoft-get-messages.service.ts

@@ -24,6 +24,7 @@ type ConnectedAccountType = Pick<
   | 'provider'
   | 'handle'
   | 'handleAliases'
+  | 'workspaceId'
 >;
 
 @Injectable()

packages/twenty-server/src/modules/messaging/message-import-manager/services/messaging-get-messages.service.ts

@@ -35,6 +35,7 @@ export class MessagingGetMessagesService {
       | 'handleAliases'
       | 'userWorkspaceId'
       | 'connectionParameters'
+      | 'workspaceId'
     >,
     messageChannel: Pick<
       MessageChannelEntity,

packages/twenty-server/src/modules/messaging/message-import-manager/types/get-message-lists-args.type.ts

@@ -16,6 +16,7 @@ export type GetMessageListsArgs = {
     | 'id'
     | 'handle'
     | 'connectionParameters'
+    | 'workspaceId'
   >;
   messageFolders: MessageFolder[];
 };