feat(messaging-groups): add TTL expiry to DEK cache matching session key lifetime

Author: ioannischtz

ts-sdks/packages/messaging-groups/src/encryption/envelope-encryption.ts

@@ -4,7 +4,8 @@
 import type { SealClient, SessionKey } from '@mysten/seal';
 import { EncryptedObject, NoAccessError } from '@mysten/seal';
 import { bcs } from '@mysten/sui/bcs';
-import type { ClientCache, ClientWithCoreApi } from '@mysten/sui/client';
+import { ClientCache } from '@mysten/sui/client';
+import type { ClientWithCoreApi } from '@mysten/sui/client';
 import { Transaction } from '@mysten/sui/transactions';
 import { fromHex, isValidSuiAddress } from '@mysten/sui/utils';
 
@@ -17,6 +18,7 @@ import { getDefaultCryptoPrimitives } from './crypto-primitives.js';
 import { DEKManager, NONCE_LENGTH, type GeneratedDEK } from './dek-manager.js';
 import { DefaultSealPolicy, type SealPolicy } from './seal-policy.js';
 import { SessionKeyManager } from './session-key-manager.js';
+import { TtlMap } from './ttl-map.js';
 
 // === AAD (Additional Authenticated Data) ===
 
@@ -164,18 +166,20 @@ export class EnvelopeEncryption<TApproveContext = void> {
 				config.versionId,
 			)) as SealPolicy<TApproveContext>;
 		this.#crypto = config.encryption.cryptoPrimitives ?? getDefaultCryptoPrimitives();
-		this.#dekCache = config.suiClient.cache.scope('dek');
+		this.#sessionKeyManager = new SessionKeyManager({
+			sessionKeyConfig: config.encryption.sessionKey,
+			packageId: config.originalPackageId,
+			suiClient: config.suiClient,
+		});
+		this.#dekCache = new ClientCache({
+			cache: new TtlMap(this.#sessionKeyManager.ttlMs),
+		});
 		this.#dekManager = new DEKManager({
 			sealClient: config.sealClient,
 			sealPolicy: this.#sealPolicy,
 			cryptoPrimitives: config.encryption.cryptoPrimitives,
 			defaultThreshold: config.encryption.sealThreshold,
 		});
-		this.#sessionKeyManager = new SessionKeyManager({
-			sessionKeyConfig: config.encryption.sessionKey,
-			packageId: config.originalPackageId,
-			suiClient: config.suiClient,
-		});
 	}
 
 	// === High-Level API ===

ts-sdks/packages/messaging-groups/src/encryption/session-key-manager.ts

@@ -7,6 +7,9 @@ import type { ClientWithCoreApi } from '@mysten/sui/client';
 
 import type { SessionKeyConfig } from '../types.js';
 
+/** Default session key TTL in minutes. */
+export const DEFAULT_SESSION_KEY_TTL_MIN = 10;
+
 export interface SessionKeyManagerConfig {
 	/** Configuration for how session keys are obtained (tier 1/2/3). */
 	sessionKeyConfig: SessionKeyConfig;
@@ -35,6 +38,16 @@ export class SessionKeyManager {
 		this.#refreshBufferMs = this.#resolveRefreshBuffer();
 	}
 
+	/** The configured session key TTL in milliseconds. */
+	get ttlMs(): number {
+		const skConfig = this.#config.sessionKeyConfig;
+		const ttlMin =
+			'ttlMin' in skConfig
+				? (skConfig.ttlMin ?? DEFAULT_SESSION_KEY_TTL_MIN)
+				: DEFAULT_SESSION_KEY_TTL_MIN;
+		return ttlMin * 60_000;
+	}
+
 	/** Returns a valid, non-expired session key — creating or refreshing as needed. */
 	async getSessionKey(): Promise<SessionKey> {
 		if (this.#sessionKey && !this.#needsRefresh()) {
@@ -87,7 +100,7 @@ export class SessionKeyManager {
 				address: skConfig.signer.toSuiAddress(),
 				packageId: this.#config.packageId,
 				mvrName: skConfig.mvrName,
-				ttlMin: skConfig.ttlMin ?? 10,
+				ttlMin: skConfig.ttlMin ?? DEFAULT_SESSION_KEY_TTL_MIN,
 				signer: skConfig.signer,
 				suiClient: this.#config.suiClient,
 			});
@@ -100,7 +113,7 @@ export class SessionKeyManager {
 			address: skConfig.address,
 			packageId: this.#config.packageId,
 			mvrName: skConfig.mvrName,
-			ttlMin: skConfig.ttlMin ?? 10,
+			ttlMin: skConfig.ttlMin ?? DEFAULT_SESSION_KEY_TTL_MIN,
 			suiClient: this.#config.suiClient,
 		});
 		const message = sessionKey.getPersonalMessage();

ts-sdks/packages/messaging-groups/src/encryption/ttl-map.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+interface TtlEntry {
+	value: unknown;
+	expiresAt: number;
+}
+
+/**
+ * A `Map<string, unknown>`-compatible class that expires entries after a TTL.
+ *
+ * Designed to be injected into `ClientCache` via its `cache` constructor option,
+ * making the cache TTL-aware without modifying `ClientCache` itself.
+ *
+ * Entries are lazily evicted: stale entries are removed on `get()` / `has()`.
+ */
+export class TtlMap extends Map<string, unknown> {
+	readonly #ttlMs: number;
+
+	constructor(ttlMs: number) {
+		super();
+		this.#ttlMs = ttlMs;
+	}
+
+	override set(key: string, value: unknown): this {
+		super.set(key, { value, expiresAt: Date.now() + this.#ttlMs } satisfies TtlEntry);
+		return this;
+	}
+
+	override get(key: string): unknown {
+		const entry = super.get(key) as TtlEntry | undefined;
+		if (!entry) return undefined;
+		if (Date.now() >= entry.expiresAt) {
+			this.delete(key);
+			return undefined;
+		}
+		return entry.value;
+	}
+
+	override has(key: string): boolean {
+		return this.get(key) !== undefined;
+	}
+}

ts-sdks/packages/messaging-groups/test/unit/envelope-encryption.test.ts

@@ -5,7 +5,7 @@ import { SessionKey } from '@mysten/seal';
 import type { SealCompatibleClient } from '@mysten/seal';
 import { ClientCache, type ClientWithCoreApi } from '@mysten/sui/client';
 import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { MessagingGroupsView } from '../../src/view.js';
 import { MessagingGroupsDerive } from '../../src/derive.js';
@@ -320,4 +320,81 @@ describe('EnvelopeEncryption', () => {
 			expect(Array.from(env0.ciphertext)).not.toEqual(Array.from(env1.ciphertext));
 		});
 	});
+
+	describe('cache TTL', () => {
+		beforeEach(() => {
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.useRealTimers();
+		});
+
+		it('should serve cached DEK before TTL expires', async () => {
+			const view = createMockView();
+			const encryptedKeySpy = vi.fn();
+			view.encryptedKey = encryptedKeySpy;
+
+			const ee = new EnvelopeEncryption({
+				sealClient: createMockSealClient(),
+				suiClient: createMockSuiClient(),
+				view,
+				derive: createMockDerive(),
+				originalPackageId: MOCK_PACKAGE_ID,
+				latestPackageId: MOCK_PACKAGE_ID,
+				versionId: MOCK_VERSION_ID,
+				encryption: {
+					sessionKey: { getSessionKey: () => createTestSessionKey() },
+				},
+			});
+
+			const data = new TextEncoder().encode('hello');
+			const { uuid } = await ee.generateGroupDEK();
+
+			// Encrypt immediately — cache is warm from generateGroupDEK
+			await ee.encrypt({ uuid, keyVersion: 0n, data });
+			expect(encryptedKeySpy).not.toHaveBeenCalled();
+
+			// Advance time but stay within TTL (default 10 min = 600_000ms)
+			vi.advanceTimersByTime(300_000);
+
+			await ee.encrypt({ uuid, keyVersion: 0n, data });
+			// Still no call to view.encryptedKey — cache hit
+			expect(encryptedKeySpy).not.toHaveBeenCalled();
+		});
+
+		it('should evict cached DEK after TTL expires and re-fetch', async () => {
+			const view = createMockView();
+			const encryptedKeySpy = vi.fn();
+			view.encryptedKey = encryptedKeySpy;
+
+			const ee = new EnvelopeEncryption({
+				sealClient: createMockSealClient(),
+				suiClient: createMockSuiClient(),
+				view,
+				derive: createMockDerive(),
+				originalPackageId: MOCK_PACKAGE_ID,
+				latestPackageId: MOCK_PACKAGE_ID,
+				versionId: MOCK_VERSION_ID,
+				encryption: {
+					sessionKey: { getSessionKey: () => createTestSessionKey() },
+				},
+			});
+
+			const data = new TextEncoder().encode('hello');
+			const { uuid } = await ee.generateGroupDEK();
+
+			// Encrypt — cache hit, no view call
+			await ee.encrypt({ uuid, keyVersion: 0n, data });
+			expect(encryptedKeySpy).not.toHaveBeenCalled();
+
+			// Advance past the TTL (default 10 min for Tier 3)
+			vi.advanceTimersByTime(600_001);
+
+			// Next encrypt triggers cache miss → calls view.encryptedKey.
+			// The spy will throw (no real return value), proving the cache was evicted.
+			await expect(ee.encrypt({ uuid, keyVersion: 0n, data })).rejects.toThrow();
+			expect(encryptedKeySpy).toHaveBeenCalledTimes(1);
+		});
+	});
 });

ts-sdks/packages/messaging-groups/test/unit/ttl-map.test.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TtlMap } from '../../src/encryption/ttl-map.js';
+
+describe('TtlMap', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it('returns a stored value before TTL expires', () => {
+		const map = new TtlMap(1000);
+		map.set('key', 'value');
+
+		expect(map.get('key')).toBe('value');
+		expect(map.has('key')).toBe(true);
+	});
+
+	it('returns undefined after TTL expires', () => {
+		const map = new TtlMap(1000);
+		map.set('key', 'value');
+
+		vi.advanceTimersByTime(1000);
+
+		expect(map.get('key')).toBeUndefined();
+		expect(map.has('key')).toBe(false);
+	});
+
+	it('evicts only expired entries', () => {
+		const map = new TtlMap(1000);
+		map.set('early', 'a');
+
+		vi.advanceTimersByTime(500);
+		map.set('late', 'b');
+
+		vi.advanceTimersByTime(500);
+
+		// 'early' was set 1000ms ago — expired
+		expect(map.has('early')).toBe(false);
+		// 'late' was set 500ms ago — still alive
+		expect(map.get('late')).toBe('b');
+	});
+
+	it('deletes expired entries lazily on get()', () => {
+		const map = new TtlMap(1000);
+		map.set('key', 'value');
+
+		vi.advanceTimersByTime(1000);
+		map.get('key');
+
+		// Entry should be deleted from the underlying Map
+		expect(map.size).toBe(0);
+	});
+
+	it('refreshes TTL when re-setting the same key', () => {
+		const map = new TtlMap(1000);
+		map.set('key', 'v1');
+
+		vi.advanceTimersByTime(800);
+		map.set('key', 'v2');
+
+		vi.advanceTimersByTime(800);
+
+		// 800ms since last set — still alive
+		expect(map.get('key')).toBe('v2');
+
+		vi.advanceTimersByTime(200);
+
+		// 1000ms since last set — expired
+		expect(map.has('key')).toBe(false);
+	});
+});