morok-bot-sdk 1.0.1

package/dist/flow/groups.js

@@ -0,0 +1,768 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { SendRejectedError, SendUncertainError } from './direct.js';
+import { parseChannelWire, decryptChannelWire, encryptChannelWire, } from '../crypto/channel-cipher.js';
+import { unsealEpochKey, sealEpochKey, GROUP_SECRET_BYTES } from '../crypto/group-secret-cipher.js';
+function mintFanoutId() {
+    return randomBytes(12).toString('base64url');
+}
+function mintClientMsgId() {
+    return randomUUID().replace(/-/g, '');
+}
+export class GroupsFlow {
+    botUserId;
+    http;
+    ws;
+    signal;
+    store;
+    gsStore;
+    convCache;
+    logger;
+    inflightInstalls = new Map();
+    pendingSends = new Map();
+    inflightGroupSecret = new Map();
+    inflightBackfills = new Set();
+    constructor(botUserId, http, ws, signal, store, gsStore, convCache, logger) {
+        this.botUserId = botUserId;
+        this.http = http;
+        this.ws = ws;
+        this.signal = signal;
+        this.store = store;
+        this.gsStore = gsStore;
+        this.convCache = convCache;
+        this.logger = logger;
+        this.ws.on('frame', (frame) => { this.onFrame(frame); });
+        this.ws.on('close', (info) => { if (info.willReconnect)
+            this.failPendingUncertain(); });
+    }
+    async installFromServer(conversationId, opts = {}) {
+        const since = opts.sinceEpoch ?? -1;
+        const cacheKey = `${conversationId}:${since}`;
+        const inFlight = this.inflightInstalls.get(cacheKey);
+        if (inFlight)
+            return inFlight;
+        const promise = this.doInstall(conversationId, since)
+            .finally(() => {
+            if (this.inflightInstalls.get(cacheKey) === promise) {
+                this.inflightInstalls.delete(cacheKey);
+            }
+        });
+        this.inflightInstalls.set(cacheKey, promise);
+        return promise;
+    }
+    async doInstall(conversationId, since) {
+        const res = await this.http.get(`/groups/${conversationId}/channel-key`, { params: { sinceEpoch: since } });
+        const body = res.data;
+        if (!body || !Array.isArray(body.keys)) {
+            this.logger?.warn({ conversationId }, '[groups] /channel-key returned malformed body');
+            return 0;
+        }
+        if (body.keys.length === 0) {
+            this.logger?.debug({ conversationId, since, pending: body.pending }, '[groups] no new channel-key epochs available');
+            return 0;
+        }
+        const merged = [];
+        for (const k of body.keys) {
+            if (!Number.isInteger(k.epoch) || k.epoch < 0) {
+                this.logger?.warn({ conversationId, entry: k }, '[groups] dropping channel-key entry with bad epoch');
+                continue;
+            }
+            if (k.messageType !== 1 && k.messageType !== 3) {
+                this.logger?.warn({ conversationId, epoch: k.epoch, messageType: k.messageType }, '[groups] dropping channel-key entry with non-Signal type');
+                continue;
+            }
+            if (typeof k.sharedByUserId !== 'number'
+                || typeof k.sharedByDeviceId !== 'number') {
+                this.logger?.warn({ conversationId, epoch: k.epoch }, '[groups] dropping channel-key entry missing sharer coords');
+                continue;
+            }
+            const sharerId = k.sharedByUserId;
+            const sharerDevice = k.sharedByDeviceId;
+            let plaintextBytes;
+            try {
+                plaintextBytes = await this.signal.withPeerLock(sharerId, sharerDevice, () => this.signal.decrypt(sharerId, sharerDevice, k.messageType, k.encryptedKey));
+            }
+            catch (err) {
+                this.logger?.warn({
+                    conversationId, epoch: k.epoch,
+                    sharerId, sharerDevice, messageType: k.messageType,
+                    err: err.message,
+                }, '[groups] channel-key envelope decrypt failed');
+                continue;
+            }
+            const secretBase64 = new TextDecoder('utf-8', { fatal: false })
+                .decode(plaintextBytes)
+                .trim();
+            if (!/^[A-Za-z0-9+/=]+$/.test(secretBase64) || secretBase64.length < 40) {
+                this.logger?.warn({ conversationId, epoch: k.epoch }, '[groups] channel-key plaintext not a base64 secret');
+                continue;
+            }
+            merged.push({ epoch: k.epoch, secretBase64 });
+        }
+        const haveEpoch = new Set(merged.map(m => m.epoch));
+        const bundles = Array.isArray(body.sealedBundles) ? body.sealedBundles : [];
+        const SEAL_BUNDLE_CAP = 10_000;
+        if (bundles.length > SEAL_BUNDLE_CAP) {
+            this.logger?.warn({ conversationId, bundleCount: bundles.length, cap: SEAL_BUNDLE_CAP }, '[groups] sealedBundles array exceeds cap - truncating');
+        }
+        const interesting = bundles
+            .slice(0, SEAL_BUNDLE_CAP)
+            .filter(b => Number.isInteger(b.epoch) && b.epoch >= 0 && !haveEpoch.has(b.epoch));
+        if (interesting.length > 0) {
+            let needFetch = false;
+            for (const b of interesting) {
+                if (Number.isInteger(b.groupSecretVersion)) {
+                    const have = await this.gsStore.getSecret(conversationId, b.groupSecretVersion);
+                    if (!have) {
+                        needFetch = true;
+                        break;
+                    }
+                }
+            }
+            if (needFetch) {
+                try {
+                    await this.installGroupSecret(conversationId);
+                }
+                catch (err) {
+                    this.logger?.warn({ conversationId, err: err.message }, '[groups] sealedBundle path: installGroupSecret failed');
+                }
+            }
+            for (const b of interesting) {
+                if (typeof b.sealedToGroupSecret !== 'string'
+                    || typeof b.sealedToGroupSecretIv !== 'string'
+                    || !Number.isInteger(b.groupSecretVersion)) {
+                    this.logger?.warn({ conversationId, bundle: b }, '[groups] dropping malformed sealedBundle');
+                    continue;
+                }
+                const secret = await this.gsStore.getSecret(conversationId, b.groupSecretVersion);
+                if (!secret) {
+                    this.logger?.debug({ conversationId, epoch: b.epoch, version: b.groupSecretVersion }, '[groups] sealedBundle skipped: no matching group_secret available');
+                    continue;
+                }
+                try {
+                    const epochKey = await unsealEpochKey({
+                        ciphertextBase64: b.sealedToGroupSecret,
+                        ivBase64: b.sealedToGroupSecretIv,
+                        groupSecret: secret,
+                        conversationId,
+                        version: b.groupSecretVersion,
+                        expectedEpoch: b.epoch,
+                    });
+                    merged.push({
+                        epoch: b.epoch,
+                        secretBase64: Buffer.from(epochKey).toString('base64'),
+                    });
+                    haveEpoch.add(b.epoch);
+                }
+                catch (err) {
+                    this.logger?.warn({
+                        conversationId, epoch: b.epoch, version: b.groupSecretVersion,
+                        err: err.message,
+                    }, '[groups] sealedBundle unseal failed');
+                }
+            }
+        }
+        if (merged.length === 0)
+            return 0;
+        await this.store.mergeEpochs(conversationId, merged);
+        this.logger?.info({ conversationId, installed: merged.map(m => m.epoch) }, '[groups] installed channel-key epochs');
+        return merged.length;
+    }
+    async decryptGroupMessage(conversationId, wireBase64) {
+        const wire = Buffer.from(wireBase64, 'base64');
+        const parsed = parseChannelWire(new Uint8Array(wire.buffer, wire.byteOffset, wire.byteLength));
+        let secret = await this.store.getSecret(conversationId, parsed.epoch);
+        if (!secret) {
+            try {
+                await this.installFromServer(conversationId, {
+                    sinceEpoch: Math.max(-1, parsed.epoch - 1),
+                });
+            }
+            catch (err) {
+                this.logger?.warn({
+                    conversationId, epoch: parsed.epoch,
+                    err: err.message,
+                }, '[groups] lazy channel-key fetch failed');
+            }
+            secret = await this.store.getSecret(conversationId, parsed.epoch);
+        }
+        if (!secret) {
+            throw new Error(`[groups] no channel key for epoch ${parsed.epoch} in conv ${conversationId}`);
+        }
+        return decryptChannelWire(secret, conversationId, parsed);
+    }
+    async forgetConversation(conversationId) {
+        await this.store.drop(conversationId);
+        await this.gsStore.drop(conversationId);
+        this.inflightGroupSecret.delete(conversationId);
+    }
+    async sendMessage(conversationId, plaintext, opts = {}) {
+        if (!Number.isInteger(conversationId) || conversationId < 1) {
+            throw new Error(`sendMessage: conversationId must be a positive integer, got ${conversationId}`);
+        }
+        let info = this.convCache.peek(conversationId);
+        if (!info) {
+            info = await this.convCache.load(conversationId).catch(() => null);
+        }
+        const isChannelComment = info?.isChannel === true
+            && opts.replyToId !== undefined && opts.replyToId !== null;
+        if (info && !info.canPost && !isChannelComment) {
+            const where = info.isChannel ? 'channel' : 'group';
+            throw new Error(`[groups] bot lacks post permission in ${where} ${conversationId} ` +
+                `(myRole=${info.myRole}, canPost=false). Ask an admin to grant /can-post.`);
+        }
+        if (isChannelComment && info?.commentsEnabled === false) {
+            throw new Error(`[groups] channel ${conversationId} has comments disabled - ` +
+                `cannot post a comment (replyToId=${opts.replyToId})`);
+        }
+        let state = await this.store.load(conversationId);
+        if (!state || state.currentEpoch < 0) {
+            await this.installFromServer(conversationId, { sinceEpoch: -1 });
+            state = await this.store.load(conversationId);
+        }
+        if (!state || state.currentEpoch < 0) {
+            throw new Error(`[groups] no channel key for conv ${conversationId} - bot may have just joined; ` +
+                `wait for channel_key_rotated or ask an admin to share`);
+        }
+        const epoch = state.currentEpoch;
+        const secretBase64 = state.keys[String(epoch)];
+        if (!secretBase64) {
+            throw new Error(`[groups] currentEpoch=${epoch} has no key entry in store for conv ${conversationId}`);
+        }
+        const secret = Buffer.from(secretBase64, 'base64');
+        if (secret.byteLength !== 32) {
+            throw new Error(`[groups] currentEpoch=${epoch} key is ${secret.byteLength} bytes; expected 32`);
+        }
+        const secretBytes = new Uint8Array(secret.buffer, secret.byteOffset, secret.byteLength);
+        const wire = await encryptChannelWire(secretBytes, conversationId, epoch, plaintext);
+        const ciphertextBase64 = Buffer.from(wire).toString('base64');
+        const fanoutId = mintFanoutId();
+        const clientMsgId = mintClientMsgId();
+        const timeoutMs = opts.sendTimeoutMs ?? 10_000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.pendingSends.delete(fanoutId)) {
+                    reject(new Error(`group send timeout after ${timeoutMs}ms (conv=${conversationId})`));
+                }
+            }, timeoutMs);
+            this.pendingSends.set(fanoutId, {
+                resolve: (messageId) => resolve({ messageId, clientMsgId, fanoutId, conversationId, epoch }),
+                reject,
+                timer,
+                clientMsgId,
+                conversationId,
+            });
+            const frame = {
+                type: 'group_message',
+                conversationId,
+                ciphertext: ciphertextBase64,
+                messageType: 8,
+                fanoutId,
+                clientMsgId,
+            };
+            if (opts.replyToId !== undefined)
+                frame.replyToId = opts.replyToId;
+            if (opts.replyToClientMsgId !== undefined)
+                frame.replyToClientMsgId = opts.replyToClientMsgId;
+            if (opts.threadRootId !== undefined)
+                frame.threadRootId = opts.threadRootId;
+            if (opts.fileId !== undefined)
+                frame.fileId = opts.fileId;
+            if (opts.kind !== undefined)
+                frame.kind = opts.kind;
+            if (opts.expiresInSeconds !== undefined)
+                frame.expiresInSeconds = opts.expiresInSeconds;
+            if (opts.additionalFileIds !== undefined && opts.additionalFileIds.length > 0) {
+                frame.additionalFileIds = opts.additionalFileIds;
+            }
+            this.ws.send(frame);
+        });
+    }
+    async encryptForChannel(conversationId, plaintext) {
+        let state = await this.store.load(conversationId);
+        if (!state || state.currentEpoch < 0) {
+            await this.installFromServer(conversationId, { sinceEpoch: -1 });
+            state = await this.store.load(conversationId);
+        }
+        if (!state || state.currentEpoch < 0) {
+            throw new Error(`[groups] no channel key for conv ${conversationId} - bot may have just joined; ` +
+                `wait for channel_key_rotated or ask an admin to share`);
+        }
+        const epoch = state.currentEpoch;
+        const secretBase64 = state.keys[String(epoch)];
+        if (!secretBase64) {
+            throw new Error(`[groups] currentEpoch=${epoch} has no key entry in store for conv ${conversationId}`);
+        }
+        const secret = Buffer.from(secretBase64, 'base64');
+        if (secret.byteLength !== 32) {
+            throw new Error(`[groups] currentEpoch=${epoch} key is ${secret.byteLength} bytes; expected 32`);
+        }
+        const secretBytes = new Uint8Array(secret.buffer, secret.byteOffset, secret.byteLength);
+        const wire = await encryptChannelWire(secretBytes, conversationId, epoch, plaintext);
+        return { ciphertext: Buffer.from(wire).toString('base64'), epoch };
+    }
+    async rotateChannelKey(conversationId) {
+        if (!Number.isInteger(conversationId) || conversationId < 1) {
+            throw new Error(`rotateChannelKey: bad conversationId ${conversationId}`);
+        }
+        const devsRes = await this.http.get(`/conversations/${conversationId}/peer-devices`);
+        const devicesMap = devsRes.data?.devices ?? {};
+        const targets = [];
+        for (const [uidStr, devs] of Object.entries(devicesMap)) {
+            const uid = parseInt(uidStr, 10);
+            if (!Number.isInteger(uid))
+                continue;
+            for (const d of devs) {
+                if (typeof d?.deviceId !== 'number')
+                    continue;
+                if (uid === this.botUserId && d.deviceId === 1)
+                    continue;
+                targets.push({ userId: uid, deviceId: d.deviceId });
+            }
+        }
+        const rawBuf = randomBytes(32);
+        const rawBytes = new Uint8Array(rawBuf.buffer, rawBuf.byteOffset, rawBuf.byteLength);
+        const keyBase64 = rawBuf.toString('base64');
+        const distributions = [];
+        const keyPlaintext = new TextEncoder().encode(keyBase64);
+        for (const t of targets) {
+            try {
+                const env = await this.signal.withPeerLock(t.userId, t.deviceId, async () => {
+                    if (!(await this.signal.hasOpenSession(t.userId, t.deviceId))) {
+                        const bundle = await this.http.get(`/prekeys/${t.userId}/${t.deviceId}`);
+                        await this.signal.processPreKeyBundle(bundle.data);
+                    }
+                    return this.signal.encrypt(t.userId, t.deviceId, keyPlaintext);
+                });
+                if (env.type !== 1 && env.type !== 3) {
+                    this.logger?.warn({ target: t, messageType: env.type }, '[groups] rotate: signal envelope produced unexpected type, skipping device');
+                    continue;
+                }
+                distributions.push({
+                    recipientId: t.userId,
+                    recipientDeviceId: t.deviceId,
+                    encryptedKey: env.body,
+                    messageType: env.type,
+                });
+            }
+            catch (err) {
+                this.logger?.warn({
+                    target: t,
+                    err: err.message,
+                }, '[groups] rotate: per-device wrap failed, skipping');
+            }
+        }
+        const rotatePayload = { distributions };
+        try {
+            const gsState = await this.gsStore.load(conversationId);
+            if (gsState && gsState.currentVersion >= 0) {
+                const bestVersion = gsState.currentVersion;
+                const bestSecret = await this.gsStore.getSecret(conversationId, bestVersion);
+                if (bestSecret) {
+                    const state = await this.store.load(conversationId);
+                    const localMax = state?.currentEpoch ?? -1;
+                    const predictedEpoch = Math.max(0, localMax + 1);
+                    const sealed = await sealEpochKey({
+                        epochKey: rawBytes,
+                        groupSecret: bestSecret,
+                        conversationId,
+                        version: bestVersion,
+                        predictedEpoch,
+                    });
+                    rotatePayload.sealedToGroupSecret = sealed.ciphertext;
+                    rotatePayload.sealedToGroupSecretIv = sealed.iv;
+                    rotatePayload.groupSecretVersion = bestVersion;
+                }
+            }
+        }
+        catch (err) {
+            this.logger?.warn({ conversationId, err: err.message }, '[groups] rotate: sealing under group_secret failed (continuing without bundle)');
+        }
+        const res = await this.http.post(`/groups/${conversationId}/channel-key/rotate`, rotatePayload);
+        const epoch = res.data?.epoch;
+        if (typeof epoch !== 'number' || !Number.isInteger(epoch) || epoch < 0) {
+            throw new Error(`[groups] rotate: server returned malformed epoch ${epoch}`);
+        }
+        await this.store.mergeEpochs(conversationId, [{ epoch, secretBase64: keyBase64 }]);
+        this.logger?.info({
+            conversationId, epoch,
+            wraps: distributions.length,
+            skipped: targets.length - distributions.length,
+            sealed: rotatePayload.sealedToGroupSecret !== undefined,
+        }, '[groups] channel key rotated');
+        rawBytes.fill(0);
+        return { epoch };
+    }
+    async rotateGroupSecret(conversationId) {
+        try {
+            return await this.rotateGroupSecretOnce(conversationId);
+        }
+        catch (err) {
+            const code = err?.response?.data?.code;
+            if (code !== 'SECRET_VERSION_STALE')
+                throw err;
+            this.logger?.warn({ conversationId }, '[groups] rotateGroupSecret stale, refreshing and retrying once');
+            await this.installGroupSecret(conversationId);
+            return await this.rotateGroupSecretOnce(conversationId);
+        }
+    }
+    async rotateGroupSecretOnce(conversationId) {
+        if (!Number.isInteger(conversationId) || conversationId < 1) {
+            throw new Error(`rotateGroupSecret: bad conversationId ${conversationId}`);
+        }
+        let state = await this.gsStore.load(conversationId);
+        if (!state || state.currentVersion < 0) {
+            await this.installGroupSecret(conversationId);
+            state = await this.gsStore.load(conversationId);
+        }
+        if (!state || state.currentVersion < 0) {
+            throw new Error(`[groups] rotateGroupSecret: no current group_secret known for conv ${conversationId} - bot may have just joined; wait for installGroupSecret to settle`);
+        }
+        const expectedCurrentVersion = state.currentVersion;
+        const devsRes = await this.http.get(`/conversations/${conversationId}/peer-devices`);
+        const devicesMap = devsRes.data?.devices ?? {};
+        const targets = [];
+        for (const [uidStr, devs] of Object.entries(devicesMap)) {
+            const uid = parseInt(uidStr, 10);
+            if (!Number.isInteger(uid))
+                continue;
+            for (const d of devs) {
+                if (typeof d?.deviceId !== 'number')
+                    continue;
+                if (uid === this.botUserId && d.deviceId === 1)
+                    continue;
+                targets.push({ userId: uid, deviceId: d.deviceId });
+            }
+        }
+        const newSecretBuf = randomBytes(32);
+        const newSecretBytes = new Uint8Array(newSecretBuf.buffer, newSecretBuf.byteOffset, newSecretBuf.byteLength);
+        const newSecretBase64 = newSecretBuf.toString('base64');
+        const newChanKeyBuf = randomBytes(32);
+        const newChanKeyBytes = new Uint8Array(newChanKeyBuf.buffer, newChanKeyBuf.byteOffset, newChanKeyBuf.byteLength);
+        const newChanKeyBase64 = newChanKeyBuf.toString('base64');
+        const secretWraps = [];
+        const channelKeyDistributions = [];
+        const secretPlaintext = new TextEncoder().encode(newSecretBase64);
+        const chanKeyPlaintext = new TextEncoder().encode(newChanKeyBase64);
+        for (const t of targets) {
+            try {
+                const wraps = await this.signal.withPeerLock(t.userId, t.deviceId, async () => {
+                    if (!(await this.signal.hasOpenSession(t.userId, t.deviceId))) {
+                        const bundle = await this.http.get(`/prekeys/${t.userId}/${t.deviceId}`);
+                        await this.signal.processPreKeyBundle(bundle.data);
+                    }
+                    const sEnv = await this.signal.encrypt(t.userId, t.deviceId, secretPlaintext);
+                    const ckEnv = await this.signal.encrypt(t.userId, t.deviceId, chanKeyPlaintext);
+                    return { sEnv, ckEnv };
+                });
+                if ((wraps.sEnv.type !== 1 && wraps.sEnv.type !== 3)
+                    || (wraps.ckEnv.type !== 1 && wraps.ckEnv.type !== 3)) {
+                    this.logger?.warn({ target: t, sType: wraps.sEnv.type, ckType: wraps.ckEnv.type }, '[groups] rotateGroupSecret: unexpected envelope type, skipping device');
+                    continue;
+                }
+                secretWraps.push({
+                    recipientUserId: t.userId,
+                    recipientDeviceId: t.deviceId,
+                    encryptedSecret: wraps.sEnv.body,
+                    messageType: wraps.sEnv.type,
+                });
+                channelKeyDistributions.push({
+                    recipientId: t.userId,
+                    recipientDeviceId: t.deviceId,
+                    encryptedKey: wraps.ckEnv.body,
+                    messageType: wraps.ckEnv.type,
+                });
+            }
+            catch (err) {
+                this.logger?.warn({ target: t, err: err.message }, '[groups] rotateGroupSecret: per-device wrap failed, skipping');
+            }
+        }
+        const newVersion = expectedCurrentVersion + 1;
+        const ckState = await this.store.load(conversationId);
+        const predictedEpoch = Math.max(0, (ckState?.currentEpoch ?? -1) + 1);
+        const sealed = await sealEpochKey({
+            epochKey: newChanKeyBytes,
+            groupSecret: newSecretBytes,
+            conversationId,
+            version: newVersion,
+            predictedEpoch,
+        });
+        const resealHistorical = [];
+        const HISTORY_CAP = 10_000;
+        if (ckState) {
+            const epochs = Object.keys(ckState.keys)
+                .map(s => parseInt(s, 10))
+                .filter(n => Number.isInteger(n) && n >= 0)
+                .sort((a, b) => a - b)
+                .slice(0, HISTORY_CAP);
+            for (const e of epochs) {
+                const raw = await this.store.getSecret(conversationId, e);
+                if (!raw)
+                    continue;
+                try {
+                    const oneSealed = await sealEpochKey({
+                        epochKey: raw,
+                        groupSecret: newSecretBytes,
+                        conversationId,
+                        version: newVersion,
+                        predictedEpoch: e,
+                    });
+                    resealHistorical.push({
+                        epoch: e,
+                        sealedToGroupSecret: oneSealed.ciphertext,
+                        sealedToGroupSecretIv: oneSealed.iv,
+                    });
+                }
+                catch (err) {
+                    this.logger?.warn({ conversationId, epoch: e, err: err.message }, '[groups] rotateGroupSecret: per-epoch reseal failed, skipping');
+                }
+            }
+        }
+        const res = await this.http.post(`/groups/${conversationId}/group-secret/rotate`, {
+            expectedCurrentVersion,
+            secretWraps,
+            channelKeyDistributions,
+            sealedToGroupSecret: sealed.ciphertext,
+            sealedToGroupSecretIv: sealed.iv,
+            ...(resealHistorical.length > 0 ? { resealHistorical } : {}),
+        });
+        const epoch = res.data?.epoch;
+        const version = res.data?.version;
+        if (typeof epoch !== 'number' || !Number.isInteger(epoch) || epoch < 0
+            || typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+            throw new Error(`[groups] rotateGroupSecret: server returned malformed response (epoch=${epoch}, version=${version})`);
+        }
+        await this.gsStore.mergeVersions(conversationId, [
+            { version, secretBase64: newSecretBase64 },
+        ]);
+        await this.store.mergeEpochs(conversationId, [
+            { epoch, secretBase64: newChanKeyBase64 },
+        ]);
+        this.logger?.info({
+            conversationId, epoch, version,
+            wraps: secretWraps.length,
+            skipped: targets.length - secretWraps.length,
+            resealed: resealHistorical.length,
+        }, '[groups] group_secret + channel_key rotated atomically');
+        newSecretBytes.fill(0);
+        newChanKeyBytes.fill(0);
+        return { epoch, version };
+    }
+    async backfillChannelKeys(conversationId, target, opts = {}) {
+        if (!Number.isInteger(conversationId) || conversationId < 1) {
+            throw new Error(`backfillChannelKeys: bad conversationId ${conversationId}`);
+        }
+        if (!Number.isInteger(target.userId) || target.userId < 1) {
+            throw new Error(`backfillChannelKeys: bad target.userId ${target.userId}`);
+        }
+        if (target.userId === this.botUserId) {
+            throw new Error('backfillChannelKeys: cannot backfill to self - use /channel-key sibling-share for own devices');
+        }
+        let deviceIds;
+        if (Array.isArray(target.deviceIds) && target.deviceIds.length > 0) {
+            deviceIds = target.deviceIds.filter(d => Number.isInteger(d) && d >= 1);
+        }
+        else {
+            const res = await this.http.get(`/prekeys/${target.userId}/devices`);
+            deviceIds = Array.isArray(res.data?.deviceIds) ? res.data.deviceIds : [];
+        }
+        if (deviceIds.length === 0) {
+            this.logger?.warn({ conversationId, targetUserId: target.userId }, '[groups] backfill: target has no addressable devices');
+            return { accepted: 0 };
+        }
+        const state = await this.store.load(conversationId);
+        if (!state) {
+            this.logger?.warn({ conversationId }, '[groups] backfill: no local channel-key state - nothing to share');
+            return { accepted: 0 };
+        }
+        const known = Object.keys(state.keys).map(s => parseInt(s, 10)).filter(Number.isInteger);
+        const epochs = Array.isArray(opts.epochs)
+            ? opts.epochs.filter(e => Number.isInteger(e) && e >= 0 && known.includes(e))
+            : known;
+        if (epochs.length === 0)
+            return { accepted: 0 };
+        const distributions = [];
+        for (const epoch of epochs) {
+            const keyBase64 = state.keys[String(epoch)];
+            if (!keyBase64)
+                continue;
+            const keyPlaintext = new TextEncoder().encode(keyBase64);
+            for (const deviceId of deviceIds) {
+                try {
+                    const env = await this.signal.withPeerLock(target.userId, deviceId, async () => {
+                        if (!(await this.signal.hasOpenSession(target.userId, deviceId))) {
+                            const bundle = await this.http.get(`/prekeys/${target.userId}/${deviceId}`);
+                            await this.signal.processPreKeyBundle(bundle.data);
+                        }
+                        return this.signal.encrypt(target.userId, deviceId, keyPlaintext);
+                    });
+                    if (env.type !== 1 && env.type !== 3) {
+                        this.logger?.warn({ target: { userId: target.userId, deviceId }, epoch, messageType: env.type }, '[groups] backfill: unexpected envelope type, skipping');
+                        continue;
+                    }
+                    distributions.push({
+                        recipientId: target.userId,
+                        recipientDeviceId: deviceId,
+                        encryptedKey: env.body,
+                        messageType: env.type,
+                        epoch,
+                    });
+                }
+                catch (err) {
+                    this.logger?.warn({
+                        target: { userId: target.userId, deviceId }, epoch,
+                        err: err.message,
+                    }, '[groups] backfill: per-wrap failure, skipping');
+                }
+            }
+        }
+        if (distributions.length === 0)
+            return { accepted: 0 };
+        const BACKFILL_CHUNK_SIZE = 500;
+        let totalAccepted = 0;
+        for (let i = 0; i < distributions.length; i += BACKFILL_CHUNK_SIZE) {
+            const chunk = distributions.slice(i, i + BACKFILL_CHUNK_SIZE);
+            try {
+                const res = await this.http.post(`/groups/${conversationId}/channel-key/backfill`, { distributions: chunk });
+                let accepted;
+                if (typeof res.data?.acceptedCount === 'number' && res.data.acceptedCount >= 0) {
+                    accepted = res.data.acceptedCount;
+                }
+                else if (typeof res.data?.count === 'number' && res.data.count >= 0) {
+                    accepted = res.data.count;
+                }
+                else {
+                    this.logger?.warn({ conversationId, targetUserId: target.userId, chunkLen: chunk.length }, '[groups] backfill: server response missing acceptedCount / count - treating as 0 accepted');
+                    accepted = 0;
+                }
+                totalAccepted += accepted;
+            }
+            catch (err) {
+                this.logger?.warn({ conversationId, targetUserId: target.userId, chunkStart: i, err: err.message }, '[groups] backfill: chunk POST failed');
+            }
+        }
+        this.logger?.info({
+            conversationId, targetUserId: target.userId,
+            attempted: distributions.length, accepted: totalAccepted,
+            deviceCount: deviceIds.length, epochCount: epochs.length,
+        }, '[groups] channel-key backfill complete');
+        return { accepted: totalAccepted };
+    }
+    async installGroupSecret(conversationId) {
+        if (!Number.isInteger(conversationId) || conversationId < 1) {
+            throw new Error(`installGroupSecret: bad conversationId ${conversationId}`);
+        }
+        const inFlight = this.inflightGroupSecret.get(conversationId);
+        if (inFlight)
+            return inFlight;
+        const p = this.doInstallGroupSecret(conversationId).finally(() => {
+            if (this.inflightGroupSecret.get(conversationId) === p) {
+                this.inflightGroupSecret.delete(conversationId);
+            }
+        });
+        this.inflightGroupSecret.set(conversationId, p);
+        return p;
+    }
+    async doInstallGroupSecret(conversationId) {
+        let body;
+        try {
+            const res = await this.http.get(`/groups/${conversationId}/group-secret`);
+            body = res.data ?? {};
+        }
+        catch (err) {
+            this.logger?.warn({ conversationId, err: err.message }, '[groups] /group-secret fetch failed');
+            return;
+        }
+        if (body.initialized === false) {
+            this.logger?.debug({ conversationId }, '[groups] conv has no group_secret yet - skipping');
+            return;
+        }
+        if (typeof body.version !== 'number'
+            || typeof body.encryptedSecret !== 'string'
+            || (body.messageType !== 1 && body.messageType !== 3)
+            || typeof body.sharedByUserId !== 'number'
+            || typeof body.sharedByDeviceId !== 'number') {
+            this.logger?.warn({ conversationId, body }, '[groups] /group-secret malformed body');
+            return;
+        }
+        const version = body.version;
+        const sharerId = body.sharedByUserId;
+        const sharerDevice = body.sharedByDeviceId;
+        const messageType = body.messageType;
+        const encryptedKey = body.encryptedSecret;
+        let plaintext;
+        try {
+            plaintext = await this.signal.withPeerLock(sharerId, sharerDevice, () => this.signal.decrypt(sharerId, sharerDevice, messageType, encryptedKey));
+        }
+        catch (err) {
+            this.logger?.warn({
+                conversationId, version, sharerId, sharerDevice, messageType,
+                err: err.message,
+            }, '[groups] group_secret envelope decrypt failed');
+            return;
+        }
+        const secretBase64 = new TextDecoder('utf-8', { fatal: false })
+            .decode(plaintext)
+            .trim();
+        const raw = Buffer.from(secretBase64, 'base64');
+        if (raw.byteLength !== GROUP_SECRET_BYTES) {
+            this.logger?.warn({ conversationId, version, gotBytes: raw.byteLength }, `[groups] unwrapped group_secret has wrong length; expected ${GROUP_SECRET_BYTES}`);
+            return;
+        }
+        await this.gsStore.mergeVersions(conversationId, [{ version, secretBase64 }]);
+        this.logger?.info({ conversationId, version }, '[groups] installed group_secret');
+    }
+    failPendingUncertain() {
+        for (const [, p] of this.pendingSends) {
+            clearTimeout(p.timer);
+            p.reject(new SendUncertainError('group send interrupted by a disconnect before the server confirmed', p.clientMsgId, p.conversationId));
+        }
+        this.pendingSends.clear();
+    }
+    shutdown() {
+        for (const [fanoutId, p] of this.pendingSends) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`group send aborted: SDK shutting down (fanoutId=${fanoutId})`));
+        }
+        this.pendingSends.clear();
+        this.inflightBackfills.clear();
+    }
+    trackBackfill(p) {
+        this.inflightBackfills.add(p);
+        p.finally(() => { this.inflightBackfills.delete(p); }).catch(() => { });
+    }
+    onFrame(frame) {
+        const fanoutId = frame.fanoutId;
+        if (typeof fanoutId !== 'string')
+            return;
+        const pending = this.pendingSends.get(fanoutId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pendingSends.delete(fanoutId);
+        if (frame.type === 'error') {
+            const msg = typeof frame.message === 'string'
+                ? frame.message
+                : typeof frame.code === 'string'
+                    ? frame.code
+                    : 'group send rejected by server';
+            const codeStr = typeof frame.code === 'string' ? ` (code=${frame.code})` : '';
+            pending.reject(new SendRejectedError(`group send rejected: ${msg}${codeStr}`, typeof frame.code === 'string' ? frame.code : undefined));
+            return;
+        }
+        if (frame.type === 'message') {
+            if (frame.messageType !== 8) {
+                pending.reject(new Error(`unexpected messageType ${frame.messageType} on own-echo (expected 8)`));
+                return;
+            }
+            const id = typeof frame.id === 'number' ? frame.id : null;
+            if (id === null) {
+                pending.reject(new Error('group own-echo missing message id'));
+                return;
+            }
+            pending.resolve(id);
+            return;
+        }
+        pending.reject(new Error(`unexpected frame type "${frame.type}" for fanoutId ${fanoutId}`));
+    }
+}
+//# sourceMappingURL=groups.js.map