@brightchain/brightchain-lib 0.29.26 → 0.30.1

package/src/lib/services/communication/channelService.js

@@ -6,7 +6,17 @@
  * Supports channel creation with visibility modes, join/leave, messaging,
  * search, invite token generation/redemption, mute/kick operations.
  *
- * Requirements: 10.3
+ * Uses epoch-aware key management via IKeyEpochState for forward secrecy.
+ * Each key rotation creates a new epoch. Messages record which epoch they
+ * were encrypted under. On member removal, all epoch keys are re-wrapped
+ * for remaining members only.
+ *
+ * When an IChatStorageProvider is injected, channels, channel messages, and
+ * invite tokens are also persisted to the provider's collections (write-through).
+ * Sync helper methods continue to read from the in-memory Maps so their
+ * signatures remain unchanged.
+ *
+ * Requirements: 10.3, 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 9.1
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChannelService = exports.InviteTokenNotFoundError = exports.InviteTokenExpiredError = exports.ChannelJoinDeniedError = exports.ChannelNameConflictError = exports.MemberAlreadyInChannelError = exports.ChannelReactionNotFoundError = exports.NotMessageAuthorError = exports.ChannelMemberMutedError = exports.ChannelPermissionError = exports.ChannelMessageNotFoundError = exports.NotChannelMemberError = exports.ChannelNotFoundError = void 0;
@@ -14,9 +24,12 @@ exports.extractChannelKeyFromDefault = extractChannelKeyFromDefault;
 const uuid_1 = require("uuid");
 const platformCrypto_1 = require("../../crypto/platformCrypto");
 const communication_1 = require("../../enumerations/communication");
+const attachmentUtils_1 = require("./attachmentUtils");
 const events_1 = require("../../interfaces/events");
 const pagination_1 = require("../../utils/pagination");
+const encryptionErrors_1 = require("../../errors/encryptionErrors");
 const messageOperationsService_1 = require("./messageOperationsService");
+const rehydrationHelpers_1 = require("./rehydrationHelpers");
 // ─── Error classes ──────────────────────────────────────────────────────────
 class ChannelNotFoundError extends Error {
     constructor(channelId) {
@@ -134,24 +147,115 @@ class ChannelService {
     channels = new Map();
     /** channelId → messages (ordered by createdAt ascending) */
     messages = new Map();
-    /** channelId → raw symmetric key (Uint8Array) */
-    symmetricKeys = new Map();
+    /** channelId → epoch-aware key state (raw keys + wrapped keys per epoch) */
+    keyEpochStates = new Map();
     /** token string → IInviteToken */
     inviteTokens = new Map();
-    /** channel name (lowercase) → channelId for uniqueness */
+    /**
+     * Per-server channel name uniqueness index.
+     * Outer key = serverId (or '__standalone__' for channels without a server).
+     * Inner key = normalized channel name → channelId.
+     */
     nameIndex = new Map();
+    /** Sentinel key for channels that don't belong to any server. */
+    static STANDALONE_KEY = '__standalone__';
+    /** Whether init() has already been called (idempotency guard). */
+    initialized = false;
     permissionService;
     encryptKey;
     messageOps;
     eventEmitter;
     randomBytesProvider;
-    constructor(permissionService, encryptKey = defaultKeyEncryption, messageOps, eventEmitter, randomBytesProvider) {
+    /** Optional persistent collection for channels (write-through). */
+    channelCollection;
+    /** Optional persistent collection for channel messages (write-through). */
+    channelMessageCollection;
+    /** Optional persistent collection for invite tokens (write-through). */
+    inviteTokenCollection;
+    /** Optional block content store for storing message content as blocks. */
+    blockContentStore;
+    constructor(permissionService, encryptKey = defaultKeyEncryption, messageOps, eventEmitter, randomBytesProvider, storageProvider, blockContentStore) {
         this.permissionService = permissionService;
         this.encryptKey = encryptKey;
         this.messageOps =
             messageOps ?? new messageOperationsService_1.MessageOperationsService(permissionService);
         this.eventEmitter = eventEmitter ?? new events_1.NullEventEmitter();
         this.randomBytesProvider = randomBytesProvider ?? platformCrypto_1.getRandomBytes;
+        this.blockContentStore = blockContentStore;
+        if (storageProvider) {
+            this.channelCollection = storageProvider.channels;
+            this.channelMessageCollection = storageProvider.channelMessages;
+            this.inviteTokenCollection = storageProvider.inviteTokens;
+        }
+    }
+    // ─── Rehydration ──────────────────────────────────────────────────────
+    /**
+     * Load persisted channels, channel messages, and invite tokens back into
+     * in-memory Maps, rebuilding derived indexes, key epoch states, and
+     * permission registrations.
+     *
+     * Idempotent: only the first call performs rehydration. No-op when no
+     * storage provider was supplied at construction time.
+     *
+     * Requirements: 1.3, 1.5, 1.6, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 8.1, 8.2, 8.3, 9.1, 9.3, 9.4
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        if (!this.channelCollection)
+            return;
+        this.initialized = true;
+        // ── Load channels ─────────────────────────────────────────────────
+        let loadedChannels;
+        try {
+            loadedChannels = await this.channelCollection.findMany();
+        }
+        catch (error) {
+            console.error('[ChannelService] Failed to load from channels collection:', error);
+            throw error;
+        }
+        for (const channel of loadedChannels) {
+            this.channels.set(channel.id, channel);
+            // Rebuild name index (scoped by serverId)
+            this.registerName(this.nameScope(channel.serverId), channel.name.toLowerCase(), channel.id);
+            // Reconstruct key epoch state
+            const epochState = (0, rehydrationHelpers_1.reconstructKeyEpochState)(channel.encryptedSharedKey);
+            if (epochState) {
+                this.keyEpochStates.set(channel.id, epochState);
+            }
+            else {
+                console.warn(`[ChannelService] Skipping key epoch reconstruction for channel ${channel.id}: malformed encryptedSharedKey`);
+            }
+            // Register permissions for each member
+            for (const member of channel.members) {
+                this.permissionService.assignRole(member.memberId, channel.id, member.role);
+            }
+        }
+        // ── Load channel messages ───────────────────────────────────────────
+        let loadedMessages;
+        try {
+            loadedMessages = await this.channelMessageCollection.findMany();
+        }
+        catch (error) {
+            console.error('[ChannelService] Failed to load from channelMessages collection:', error);
+            throw error;
+        }
+        const grouped = (0, rehydrationHelpers_1.groupAndSortMessages)(loadedMessages);
+        for (const [contextId, msgs] of grouped) {
+            this.messages.set(contextId, msgs);
+        }
+        // ── Load invite tokens ──────────────────────────────────────────────
+        let loadedTokens;
+        try {
+            loadedTokens = await this.inviteTokenCollection.findMany();
+        }
+        catch (error) {
+            console.error('[ChannelService] Failed to load from inviteTokens collection:', error);
+            throw error;
+        }
+        for (const token of loadedTokens) {
+            this.inviteTokens.set(token.token, token);
+        }
     }
     // ─── Helpers ────────────────────────────────────────────────────────────
     assertChannelExists(channelId) {
@@ -179,32 +283,150 @@ class ChannelService {
     generateSymmetricKey() {
         return this.randomBytesProvider(32);
     }
-    encryptKeyForMembers(memberIds, symmetricKey) {
+    /**
+     * Encrypt a symmetric key for multiple members, returning a Map<memberId, wrappedKey>.
+     * Wraps key wrapping failures as KeyUnwrapError with context information.
+     *
+     * Requirements: 12.3
+     */
+    encryptKeyForMembers(memberIds, symmetricKey, contextId, epoch) {
         const encrypted = new Map();
         for (const id of memberIds) {
-            encrypted.set(id, this.encryptKey(id, symmetricKey));
+            try {
+                encrypted.set(id, this.encryptKey(id, symmetricKey));
+            }
+            catch (error) {
+                if (contextId !== undefined && epoch !== undefined) {
+                    throw new encryptionErrors_1.KeyUnwrapError(contextId, id, epoch);
+                }
+                throw error;
+            }
         }
         return encrypted;
     }
-    rotateKey(channel) {
+    /**
+     * Create initial epoch state (epoch 0) for a new channel.
+     * Uses KeyEpochManager pattern: creates epoch 0 with wrapped keys for all members.
+     *
+     * Requirements: 1.3, 2.1
+     */
+    createInitialEpochState(symmetricKey, memberIds) {
+        const epochKeys = new Map();
+        epochKeys.set(0, symmetricKey);
+        const wrappedKeys = this.encryptKeyForMembers(memberIds, symmetricKey);
+        const encryptedEpochKeys = new Map();
+        encryptedEpochKeys.set(0, wrappedKeys);
+        return { currentEpoch: 0, epochKeys, encryptedEpochKeys };
+    }
+    /**
+     * Add a member to an existing epoch state: wrap ALL epoch keys for the new member.
+     * This gives the new member access to full message history.
+     *
+     * Requirements: 2.2, 6.1, 6.3
+     */
+    addMemberToEpochState(state, newMemberId) {
+        for (const [epoch, rawKey] of state.epochKeys) {
+            const epochMap = state.encryptedEpochKeys.get(epoch) ?? new Map();
+            epochMap.set(newMemberId, this.encryptKey(newMemberId, rawKey));
+            state.encryptedEpochKeys.set(epoch, epochMap);
+        }
+    }
+    /**
+     * Rotate key: increment epoch, add new key, delete removed member from ALL epochs,
+     * re-wrap ALL epoch keys for remaining members.
+     *
+     * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6
+     */
+    rotateEpochState(state, newKey, remainingMemberIds, removedMemberId) {
+        const newEpoch = state.currentEpoch + 1;
+        // Add new epoch key
+        state.epochKeys.set(newEpoch, newKey);
+        // Delete removed member from ALL epochs
+        for (const [, memberMap] of state.encryptedEpochKeys) {
+            memberMap.delete(removedMemberId);
+        }
+        // Re-wrap ALL epoch keys for remaining members
+        for (const [epoch, rawKey] of state.epochKeys) {
+            state.encryptedEpochKeys.set(epoch, this.encryptKeyForMembers(remainingMemberIds, rawKey));
+        }
+        return { ...state, currentEpoch: newEpoch };
+    }
+    /**
+     * Rotate the channel's symmetric key using epoch-aware key management.
+     * Generates a new key, increments epoch, re-wraps all epoch keys for remaining members,
+     * and removes the departed member from all epochs.
+     *
+     * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5
+     */
+    rotateKey(channel, removedMemberId) {
         const newKey = this.generateSymmetricKey();
-        this.symmetricKeys.set(channel.id, newKey);
-        channel.encryptedSharedKey = this.encryptKeyForMembers(channel.members.map((m) => m.memberId), newKey);
+        const state = this.keyEpochStates.get(channel.id);
+        if (state) {
+            const remainingMemberIds = channel.members.map((m) => m.memberId);
+            const newState = this.rotateEpochState(state, newKey, remainingMemberIds, removedMemberId);
+            this.keyEpochStates.set(channel.id, newState);
+            channel.encryptedSharedKey = newState.encryptedEpochKeys;
+        }
+    }
+    /**
+     * Assert that a key epoch exists in the epoch state for a given context.
+     * Throws KeyEpochNotFoundError if the epoch is not found.
+     *
+     * Requirements: 12.3
+     */
+    assertEpochExists(contextId, keyEpoch) {
+        const state = this.keyEpochStates.get(contextId);
+        if (!state || !state.epochKeys.has(keyEpoch)) {
+            throw new encryptionErrors_1.KeyEpochNotFoundError(contextId, keyEpoch);
+        }
     }
     normalizeChannelName(name) {
         return name.toLowerCase().replace(/\s+/g, '-');
     }
+    /** Get the nameIndex scope key for a channel's server (or standalone). */
+    nameScope(serverId) {
+        return serverId ?? ChannelService.STANDALONE_KEY;
+    }
+    /** Check if a channel name is taken within a given server scope. */
+    isNameTaken(scope, normalized, excludeChannelId) {
+        const scopeMap = this.nameIndex.get(scope);
+        if (!scopeMap)
+            return false;
+        const existingId = scopeMap.get(normalized);
+        return !!existingId && existingId !== excludeChannelId;
+    }
+    /** Register a channel name in the scoped index. */
+    registerName(scope, normalized, channelId) {
+        let scopeMap = this.nameIndex.get(scope);
+        if (!scopeMap) {
+            scopeMap = new Map();
+            this.nameIndex.set(scope, scopeMap);
+        }
+        scopeMap.set(normalized, channelId);
+    }
+    /** Remove a channel name from the scoped index. */
+    unregisterName(scope, normalized) {
+        const scopeMap = this.nameIndex.get(scope);
+        if (scopeMap) {
+            scopeMap.delete(normalized);
+            if (scopeMap.size === 0) {
+                this.nameIndex.delete(scope);
+            }
+        }
+    }
     // ─── Channel lifecycle ──────────────────────────────────────────────────
     /**
      * Create a new channel.
      * Generates a shared symmetric key and encrypts it for the creator.
      * The creator is assigned the OWNER role.
+     * Uses KeyEpochManager pattern to create initial epoch 0.
      *
-     * Requirement 10.3: channel creation with visibility.
+     * Requirements: 10.3, 1.3, 2.1, 9.1
      */
-    async createChannel(name, creatorId, visibility, topic = '') {
+    async createChannel(name, creatorId, visibility, topic = '', serverId) {
         const normalized = this.normalizeChannelName(name);
-        if (this.nameIndex.has(normalized)) {
+        const scope = this.nameScope(serverId);
+        if (this.isNameTaken(scope, normalized)) {
             throw new ChannelNameConflictError(name);
         }
         const now = new Date();
@@ -217,7 +439,8 @@ class ChannelService {
                 joinedAt: now,
             },
         ];
-        const encryptedSharedKey = this.encryptKeyForMembers([creatorId], symmetricKey);
+        // Create initial epoch state (epoch 0) with wrapped key for creator
+        const epochState = this.createInitialEpochState(symmetricKey, [creatorId]);
         const channel = {
             id: channelId,
             name: normalized,
@@ -225,17 +448,22 @@ class ChannelService {
             creatorId,
             visibility,
             members,
-            encryptedSharedKey,
+            encryptedSharedKey: epochState.encryptedEpochKeys,
             createdAt: now,
             lastMessageAt: now,
             pinnedMessageIds: [],
             historyVisibleToNewMembers: true,
+            serverId,
         };
         this.channels.set(channelId, channel);
         this.messages.set(channelId, []);
-        this.symmetricKeys.set(channelId, symmetricKey);
-        this.nameIndex.set(normalized, channelId);
+        this.keyEpochStates.set(channelId, epochState);
+        this.registerName(scope, normalized, channelId);
         this.permissionService.assignRole(creatorId, channelId, communication_1.DefaultRole.OWNER);
+        // Persist to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.create(channel);
+        }
         return channel;
     }
     /**
@@ -274,13 +502,13 @@ class ChannelService {
         this.assertPermission(requesterId, channelId, communication_1.Permission.MANAGE_CHANNEL);
         if (updates.name !== undefined) {
             const normalized = this.normalizeChannelName(updates.name);
-            const existingId = this.nameIndex.get(normalized);
-            if (existingId && existingId !== channelId) {
+            const scope = this.nameScope(channel.serverId);
+            if (this.isNameTaken(scope, normalized, channelId)) {
                 throw new ChannelNameConflictError(updates.name);
             }
-            this.nameIndex.delete(channel.name);
+            this.unregisterName(scope, channel.name);
             channel.name = normalized;
-            this.nameIndex.set(normalized, channelId);
+            this.registerName(scope, normalized, channelId);
         }
         if (updates.topic !== undefined) {
             channel.topic = updates.topic;
@@ -292,6 +520,10 @@ class ChannelService {
             channel.historyVisibleToNewMembers = updates.historyVisibleToNewMembers;
         }
         this.eventEmitter.emitChannelUpdated(channelId, channelId, requesterId);
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         return channel;
     }
     /**
@@ -301,16 +533,21 @@ class ChannelService {
         const channel = this.assertChannelExists(channelId);
         this.assertIsMember(channel, requesterId);
         this.assertPermission(requesterId, channelId, communication_1.Permission.MANAGE_CHANNEL);
-        this.nameIndex.delete(channel.name);
+        this.unregisterName(this.nameScope(channel.serverId), channel.name);
         this.channels.delete(channelId);
         this.messages.delete(channelId);
-        this.symmetricKeys.delete(channelId);
+        this.keyEpochStates.delete(channelId);
+        // Persist deletion to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.delete(channelId);
+        }
     }
     // ─── Join / Leave ─────────────────────────────────────────────────────
     /**
      * Join a public channel. Rejects invite-only channels.
+     * Wraps ALL epoch keys for the new member so they can read history.
      *
-     * Requirement 10.3: add member, reject invite-only without invitation.
+     * Requirements: 10.3, 2.2
      */
     async joinChannel(channelId, memberId) {
         const channel = this.assertChannelExists(channelId);
@@ -326,60 +563,211 @@ class ChannelService {
             role: communication_1.DefaultRole.MEMBER,
             joinedAt: now,
         });
-        const currentKey = this.symmetricKeys.get(channelId);
-        channel.encryptedSharedKey.set(memberId, this.encryptKey(memberId, currentKey));
+        // Add member to epoch state: wrap ALL epoch keys for the new member
+        const state = this.keyEpochStates.get(channelId);
+        if (state) {
+            this.addMemberToEpochState(state, memberId);
+            channel.encryptedSharedKey = state.encryptedEpochKeys;
+        }
+        this.permissionService.assignRole(memberId, channelId, communication_1.DefaultRole.MEMBER);
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
+        this.eventEmitter.emitMemberJoined('channel', channelId, memberId);
+    }
+    /**
+     * Remove a member from a channel (server-level operation).
+     * Bypasses permission checks — used by ServerService when a member is removed
+     * from a server so that key rotation is performed for each affected channel.
+     * Silently skips if the member is not in the channel.
+     *
+     * Requirements: 7.1, 7.2, 7.3
+     */
+    async removeMemberFromChannel(channelId, memberId) {
+        const channel = this.assertChannelExists(channelId);
+        // Skip if not a member
+        if (!channel.members.some((m) => m.memberId === memberId)) {
+            return;
+        }
+        channel.members = channel.members.filter((m) => m.memberId !== memberId);
+        if (channel.members.length > 0) {
+            this.rotateKey(channel, memberId);
+        }
+        else {
+            // No members left — clean up epoch state
+            const state = this.keyEpochStates.get(channelId);
+            if (state) {
+                for (const [, epochMap] of state.encryptedEpochKeys) {
+                    epochMap.delete(memberId);
+                }
+                channel.encryptedSharedKey = state.encryptedEpochKeys;
+            }
+        }
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
+        this.eventEmitter.emitMemberLeft('channel', channelId, memberId);
+    }
+    /**
+     * Add a member to a channel (server-level operation).
+     * Bypasses visibility checks — used by ServerService when a member joins a server
+     * so that all epoch keys are wrapped for the new member across all server channels.
+     * Silently skips if the member is already in the channel.
+     *
+     * Requirements: 6.1, 6.2, 6.3
+     */
+    async addMemberToChannel(channelId, memberId) {
+        const channel = this.assertChannelExists(channelId);
+        // Skip if already a member
+        if (channel.members.some((m) => m.memberId === memberId)) {
+            return;
+        }
+        const now = new Date();
+        channel.members.push({
+            memberId,
+            role: communication_1.DefaultRole.MEMBER,
+            joinedAt: now,
+        });
+        // Add member to epoch state: wrap ALL epoch keys for the new member
+        const state = this.keyEpochStates.get(channelId);
+        if (state) {
+            this.addMemberToEpochState(state, memberId);
+            channel.encryptedSharedKey = state.encryptedEpochKeys;
+        }
         this.permissionService.assignRole(memberId, channelId, communication_1.DefaultRole.MEMBER);
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         this.eventEmitter.emitMemberJoined('channel', channelId, memberId);
     }
     /**
      * Leave a channel voluntarily. Rotates the shared key.
+     *
+     * Requirements: 3.5
      */
     async leaveChannel(channelId, memberId) {
         const channel = this.assertChannelExists(channelId);
         this.assertIsMember(channel, memberId);
         channel.members = channel.members.filter((m) => m.memberId !== memberId);
-        channel.encryptedSharedKey.delete(memberId);
         if (channel.members.length > 0) {
-            this.rotateKey(channel);
+            this.rotateKey(channel, memberId);
+        }
+        else {
+            // No members left — clean up epoch state
+            const state = this.keyEpochStates.get(channelId);
+            if (state) {
+                for (const [, epochMap] of state.encryptedEpochKeys) {
+                    epochMap.delete(memberId);
+                }
+                channel.encryptedSharedKey = state.encryptedEpochKeys;
+            }
+        }
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
         }
         this.eventEmitter.emitMemberLeft('channel', channelId, memberId);
     }
     // ─── Messaging ────────────────────────────────────────────────────────
     /**
      * Send a message to a channel.
-     * Requirement 10.3: messaging with permission and mute checks.
+     * Encrypts content with the current epoch's CEK and records the keyEpoch.
+     * Optionally accepts attachments which are validated against platform limits.
+     *
+     * Requirements: 10.3, 1.1, 1.4, 9.1, 11.1, 11.2, 11.4, 11.5
      */
-    async sendMessage(channelId, senderId, content) {
+    async sendMessage(channelId, senderId, content, attachments) {
         const channel = this.assertChannelExists(channelId);
         this.assertIsMember(channel, senderId);
         this.assertPermission(senderId, channelId, communication_1.Permission.SEND_MESSAGES);
         this.assertNotMuted(senderId, channelId);
+        // Validate and prepare attachment metadata before creating the message
+        const attachmentMetadata = attachments?.length
+            ? (0, attachmentUtils_1.validateAndPrepareAttachments)(attachments)
+            : [];
+        const state = this.keyEpochStates.get(channelId);
+        const currentEpoch = state?.currentEpoch ?? 0;
+        // Store content via block content store if available; otherwise use raw content
+        let messageContent = content;
+        if (this.blockContentStore) {
+            const memberIds = channel.members.map((m) => m.memberId);
+            const { blockReference } = await this.blockContentStore.storeContent(content, senderId, memberIds);
+            messageContent = blockReference;
+        }
         const now = new Date();
         const message = {
             id: (0, uuid_1.v4)(),
             contextType: 'channel',
             contextId: channelId,
             senderId,
-            encryptedContent: content,
+            encryptedContent: messageContent,
             createdAt: now,
             editHistory: [],
             deleted: false,
             pinned: false,
             reactions: [],
+            keyEpoch: currentEpoch,
+            attachments: attachmentMetadata,
         };
         this.messages.get(channelId).push(message);
         channel.lastMessageAt = now;
+        // Persist to storage provider if available
+        if (this.channelMessageCollection) {
+            await this.channelMessageCollection.create(message);
+        }
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         this.eventEmitter.emitMessageSent('channel', channelId, message.id, senderId);
-        return message;
+        // Return the message with the original readable content for display,
+        // while the stored version retains the block reference (magnet URL)
+        return this.blockContentStore
+            ? { ...message, encryptedContent: content }
+            : message;
     }
     /**
      * Get messages in a channel with cursor-based pagination.
+     * Messages are returned with their keyEpoch so clients can decrypt
+     * using the appropriate epoch's CEK.
+     * Validates that each message's keyEpoch exists in the epoch state;
+     * throws KeyEpochNotFoundError if a message references a non-existent epoch.
+     *
+     * Requirements: 1.2, 12.3
      */
     async getMessages(channelId, memberId, cursor, limit = 50) {
         const channel = this.assertChannelExists(channelId);
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
-        return (0, pagination_1.paginateItems)(msgs, cursor, limit);
+        // Validate that each message's keyEpoch exists in the epoch state
+        for (const msg of msgs) {
+            this.assertEpochExists(channelId, msg.keyEpoch);
+        }
+        const result = (0, pagination_1.paginateItems)(msgs, cursor, limit);
+        // Resolve block references (magnet URLs) back to readable content
+        if (this.blockContentStore) {
+            const resolved = await Promise.all(result.items.map(async (msg) => {
+                if (msg.deleted)
+                    return msg;
+                try {
+                    const contentBytes = await this.blockContentStore.retrieveContent(msg.encryptedContent);
+                    if (contentBytes) {
+                        return {
+                            ...msg,
+                            encryptedContent: new TextDecoder().decode(contentBytes),
+                        };
+                    }
+                }
+                catch {
+                    // Fall back to stored value if retrieval fails
+                }
+                return msg;
+            }));
+            return { ...result, items: resolved };
+        }
+        return result;
     }
     /**
      * Search messages in a channel by keyword.
@@ -389,6 +777,23 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         const lowerQuery = query.toLowerCase();
+        if (this.blockContentStore) {
+            // Retrieve content from block store for each non-deleted message before searching
+            const matching = [];
+            for (const m of msgs) {
+                if (m.deleted)
+                    continue;
+                const contentBytes = await this.blockContentStore.retrieveContent(m.encryptedContent);
+                if (contentBytes) {
+                    const contentText = new TextDecoder().decode(contentBytes);
+                    if (contentText.toLowerCase().includes(lowerQuery)) {
+                        matching.push(m);
+                    }
+                }
+            }
+            return (0, pagination_1.paginateItems)(matching, cursor, limit);
+        }
+        // Fall back to current direct string search when block store is absent
         const matching = msgs.filter((m) => !m.deleted &&
             typeof m.encryptedContent === 'string' &&
             m.encryptedContent.toLowerCase().includes(lowerQuery));
@@ -416,12 +821,17 @@ class ChannelService {
             currentUses: 0,
         };
         this.inviteTokens.set(token.token, token);
+        // Persist invite token to storage provider if available
+        if (this.inviteTokenCollection) {
+            await this.inviteTokenCollection.create(token);
+        }
         return token;
     }
     /**
      * Redeem an invite token to join a channel.
+     * Wraps ALL epoch keys for the joining member.
      *
-     * Requirement 10.3: validate expiry and usage limits.
+     * Requirements: 10.3, 2.2
      */
     async redeemInvite(token, memberId) {
         const invite = this.inviteTokens.get(token);
@@ -444,10 +854,21 @@ class ChannelService {
             role: communication_1.DefaultRole.MEMBER,
             joinedAt: now,
         });
-        const currentKey = this.symmetricKeys.get(channel.id);
-        channel.encryptedSharedKey.set(memberId, this.encryptKey(memberId, currentKey));
+        // Add member to epoch state: wrap ALL epoch keys for the new member
+        const state = this.keyEpochStates.get(channel.id);
+        if (state) {
+            this.addMemberToEpochState(state, memberId);
+            channel.encryptedSharedKey = state.encryptedEpochKeys;
+        }
         this.permissionService.assignRole(memberId, channel.id, communication_1.DefaultRole.MEMBER);
         invite.currentUses++;
+        // Persist changes to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channel.id, channel);
+        }
+        if (this.inviteTokenCollection) {
+            await this.inviteTokenCollection.update(invite.token, invite);
+        }
         this.eventEmitter.emitMemberJoined('channel', channel.id, memberId);
     }
     // ─── Moderation ───────────────────────────────────────────────────────
@@ -467,13 +888,17 @@ class ChannelService {
         if (member) {
             member.mutedUntil = new Date(Date.now() + durationMs);
         }
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         this.eventEmitter.emitMemberMuted('channel', channelId, targetId, requesterId, durationMs);
     }
     /**
-     * Kick a member from a channel. Rotates encryption keys.
+     * Kick a member from a channel. Rotates encryption keys using epoch-aware rotation.
      * Requires KICK_MEMBERS permission.
      *
-     * Requirement 10.3: remove member and rotate keys.
+     * Requirements: 10.3, 3.1, 3.2, 3.3, 3.4
      */
     async kickMember(channelId, requesterId, targetId) {
         const channel = this.assertChannelExists(channelId);
@@ -481,9 +906,22 @@ class ChannelService {
         this.assertIsMember(channel, targetId);
         this.assertPermission(requesterId, channelId, communication_1.Permission.KICK_MEMBERS);
         channel.members = channel.members.filter((m) => m.memberId !== targetId);
-        channel.encryptedSharedKey.delete(targetId);
         if (channel.members.length > 0) {
-            this.rotateKey(channel);
+            this.rotateKey(channel, targetId);
+        }
+        else {
+            // No members left — clean up epoch state
+            const state = this.keyEpochStates.get(channelId);
+            if (state) {
+                for (const [, epochMap] of state.encryptedEpochKeys) {
+                    epochMap.delete(targetId);
+                }
+                channel.encryptedSharedKey = state.encryptedEpochKeys;
+            }
+        }
+        // Persist channel update to storage provider if available
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
         }
         this.eventEmitter.emitMemberKicked('channel', channelId, targetId, requesterId);
     }
@@ -496,7 +934,36 @@ class ChannelService {
         const channel = this.assertChannelExists(channelId);
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
+        if (this.blockContentStore) {
+            // Find the message manually to handle block storage
+            const message = msgs.find((m) => m.id === messageId);
+            if (!message)
+                throw new ChannelMessageNotFoundError(messageId);
+            if (message.senderId !== memberId)
+                throw new NotMessageAuthorError();
+            // Store new content as a new block
+            const memberIds = channel.members.map((m) => m.memberId);
+            const { blockReference } = await this.blockContentStore.storeContent(newContent, memberId, memberIds);
+            // Push old block reference to edit history
+            message.editHistory.push({
+                content: message.encryptedContent,
+                editedAt: new Date(),
+            });
+            // Update encryptedContent to new block reference
+            message.encryptedContent = blockReference;
+            message.editedAt = new Date();
+            // Persist edited message to storage provider if available
+            if (this.channelMessageCollection) {
+                await this.channelMessageCollection.update(messageId, message);
+            }
+            this.eventEmitter.emitMessageEdited('channel', channelId, messageId, memberId);
+            return message;
+        }
         const edited = this.messageOps.editMessage(msgs, messageId, memberId, newContent, (id) => new ChannelMessageNotFoundError(id), () => new NotMessageAuthorError());
+        // Persist edited message to storage provider if available
+        if (this.channelMessageCollection) {
+            await this.channelMessageCollection.update(messageId, edited);
+        }
         this.eventEmitter.emitMessageEdited('channel', channelId, messageId, memberId);
         return edited;
     }
@@ -509,6 +976,13 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         this.messageOps.deleteMessage(msgs, channelId, messageId, memberId, (id) => new ChannelMessageNotFoundError(id), (p) => new ChannelPermissionError(p));
+        // Persist deleted message to storage provider if available
+        if (this.channelMessageCollection) {
+            const deletedMsg = msgs.find((m) => m.id === messageId);
+            if (deletedMsg) {
+                await this.channelMessageCollection.update(messageId, deletedMsg);
+            }
+        }
         this.eventEmitter.emitMessageDeleted('channel', channelId, messageId, memberId);
     }
     /**
@@ -520,6 +994,16 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         this.messageOps.pinMessage(msgs, channelId, messageId, memberId, channel, (id) => new ChannelMessageNotFoundError(id), (p) => new ChannelPermissionError(p));
+        // Persist pin changes to storage provider if available
+        if (this.channelMessageCollection) {
+            const pinnedMsg = msgs.find((m) => m.id === messageId);
+            if (pinnedMsg) {
+                await this.channelMessageCollection.update(messageId, pinnedMsg);
+            }
+        }
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         this.eventEmitter.emitMessagePinEvent(communication_1.CommunicationEventType.MESSAGE_PINNED, 'channel', channelId, messageId, memberId);
     }
     /**
@@ -531,6 +1015,16 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         this.messageOps.unpinMessage(msgs, channelId, messageId, memberId, channel, (id) => new ChannelMessageNotFoundError(id), (p) => new ChannelPermissionError(p));
+        // Persist unpin changes to storage provider if available
+        if (this.channelMessageCollection) {
+            const unpinnedMsg = msgs.find((m) => m.id === messageId);
+            if (unpinnedMsg) {
+                await this.channelMessageCollection.update(messageId, unpinnedMsg);
+            }
+        }
+        if (this.channelCollection) {
+            await this.channelCollection.update(channelId, channel);
+        }
         this.eventEmitter.emitMessagePinEvent(communication_1.CommunicationEventType.MESSAGE_UNPINNED, 'channel', channelId, messageId, memberId);
     }
     /**
@@ -542,6 +1036,13 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         const reactionId = this.messageOps.addReaction(msgs, messageId, memberId, emoji, (id) => new ChannelMessageNotFoundError(id));
+        // Persist reaction change to storage provider if available
+        if (this.channelMessageCollection) {
+            const msg = msgs.find((m) => m.id === messageId);
+            if (msg) {
+                await this.channelMessageCollection.update(messageId, msg);
+            }
+        }
         this.eventEmitter.emitReactionEvent(communication_1.CommunicationEventType.REACTION_ADDED, 'channel', channelId, messageId, memberId, emoji, reactionId);
         return reactionId;
     }
@@ -554,14 +1055,34 @@ class ChannelService {
         this.assertIsMember(channel, memberId);
         const msgs = this.messages.get(channelId) ?? [];
         this.messageOps.removeReaction(msgs, messageId, reactionId, (id) => new ChannelMessageNotFoundError(id), (id) => new ChannelReactionNotFoundError(id));
+        // Persist reaction removal to storage provider if available
+        if (this.channelMessageCollection) {
+            const msg = msgs.find((m) => m.id === messageId);
+            if (msg) {
+                await this.channelMessageCollection.update(messageId, msg);
+            }
+        }
         this.eventEmitter.emitReactionEvent(communication_1.CommunicationEventType.REACTION_REMOVED, 'channel', channelId, messageId, memberId, '', reactionId);
     }
     // ─── Accessors (for testing / internal use) ───────────────────────────
     getChannelById(channelId) {
         return this.channels.get(channelId);
     }
+    /**
+     * Get the current epoch's raw symmetric key for a channel.
+     * Returns the key for the latest epoch (backward-compatible accessor).
+     */
     getSymmetricKey(channelId) {
-        return this.symmetricKeys.get(channelId);
+        const state = this.keyEpochStates.get(channelId);
+        if (!state)
+            return undefined;
+        return state.epochKeys.get(state.currentEpoch);
+    }
+    /**
+     * Get the full epoch state for a channel (testing / internal use).
+     */
+    getKeyEpochState(channelId) {
+        return this.keyEpochStates.get(channelId);
     }
     getAllMessages(channelId) {
         return this.messages.get(channelId) ?? [];