@droponair/sdk-js 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.8.0], 2026-05-19
+
+### BREAKING
+
+- `sendGroupMessage(groupId, plaintext)` is **renamed to `sendCleartextGroupMessage(groupId, plaintext)`**. The previous JS method was cleartext-only despite the name, while the Android and iOS SDKs reserved the same name for an end-to-end encrypted send. This release aligns all three SDKs on the same naming.
+  - **Update existing JS callers**: replace `client.sendGroupMessage(groupId, text)` with `client.sendCleartextGroupMessage(groupId, text)`.
+
+### Added
+
+- **End-to-end encrypted group send.** New `sendGroupMessage(groupId, plaintext, memberUserIds, options?)` that mirrors the Android and iOS SDKs: the SDK encrypts the plaintext per-recipient-per-device (sender-side fan-out) before sending. Pass `options.attachments` for E2EE group attachments.
+- **Group attachments.** Both `sendGroupMessage` and the wire `GroupEnvelope` now carry an optional `attachments` field; previously this was 1:1 only on JS.
+
+### Fixed
+
+- **JS `GroupEnvelope` / `GroupMessageNotification` protobuf field numbers** now match the source-of-truth `messaging.proto`. The previous JS schema had a field-number drift versus the Android/iOS generated proto bindings, which meant group sends from JS arrived at the server with values in the wrong fields (and were silently tolerated by proto3's unknown-field handling). With this release JS group send/receive is wire-correct.
+
+### Notes
+
+- Wire protocol unchanged (PROTOCOL_VERSION stays 4). The proto schema was already correct; only the JS hand-rolled codec was out of sync.
+- `protoFieldNumbers` for the group types are now documented in `droponair-sdk-shared/test-vectors/protobuf-vectors.json` for cross-platform reference.
+
+---
+
 ## [0.7.0], 2026-05-19
 
 ### Added

package/README.md

@@ -182,7 +182,8 @@ client.onMessage(async (msg) => {
 | `addGroupMembers(groupId, userIds)` | `Promise<GroupInfo>` | Add members (owner/admin) |
 | `removeGroupMember(groupId, userId)` | `Promise<GroupInfo>` | Remove a member (owner/admin) |
 | `deleteGroup(groupId)` | `Promise<void>` | Delete a group (owner only) |
-| `sendGroupMessage(groupId, plaintext)` | `Promise<{ messageId }>` | Send a group message |
+| `sendGroupMessage(groupId, plaintext, memberUserIds, options?)` | `Promise<{ messageId }>` | Send an end-to-end encrypted group message (sender-side per-recipient fan-out). `options.attachments` for E2EE group attachments. |
+| `sendCleartextGroupMessage(groupId, plaintext)` | `Promise<{ messageId }>` | Send a plaintext (non-encrypted) group message; server fans out to every other member. |
 | `onGroupMessage(callback)` | `() => void` | Listen for group messages |
 
 ### 1-to-1 Calls

package/dist/core/messaging-client.d.ts

@@ -127,7 +127,32 @@ export declare class MessagingClient implements DropOnAirClient {
     addGroupMembers(groupId: string, userIds: string[]): Promise<GroupInfo>;
     removeGroupMember(groupId: string, userId: string): Promise<GroupInfo>;
     deleteGroup(groupId: string): Promise<void>;
-    sendGroupMessage(groupId: string, plaintext: string): Promise<{
+    /**
+     * Send an end-to-end encrypted group message. Mirrors the Android and iOS
+     * SDKs: the SDK encrypts the plaintext per recipient device (sender-side
+     * fan-out), producing one `GroupMemberPayload` per member that the server
+     * then routes to that member's devices without ever seeing the plaintext.
+     *
+     * `memberUserIds` should be the current group membership minus the sender;
+     * fetch it from your backend / `getGroup()` before calling.
+     *
+     * For unencrypted group messaging (bots, public channels), use
+     * {@link sendCleartextGroupMessage} instead.
+     */
+    sendGroupMessage(groupId: string, plaintext: string, memberUserIds: string[], options?: {
+        attachments?: AttachmentRef[];
+    }): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Send a plaintext (non-encrypted) group message. The server fans out the
+     * cleartext to every other member of the group; useful for bots and public
+     * channels where E2EE isn't required.
+     *
+     * For E2EE group messaging, use {@link sendGroupMessage} which encrypts
+     * per-recipient before sending.
+     */
+    sendCleartextGroupMessage(groupId: string, plaintext: string): Promise<{
         messageId: string;
     }>;
     onGroupMessage(callback: GroupMessageCallback): () => void;

package/dist/core/messaging-client.js

@@ -679,7 +679,19 @@ class MessagingClient {
     // ---------------------------------------------------------------------------
     // Group messaging
     // ---------------------------------------------------------------------------
-    async sendGroupMessage(groupId, plaintext) {
+    /**
+     * Send an end-to-end encrypted group message. Mirrors the Android and iOS
+     * SDKs: the SDK encrypts the plaintext per recipient device (sender-side
+     * fan-out), producing one `GroupMemberPayload` per member that the server
+     * then routes to that member's devices without ever seeing the plaintext.
+     *
+     * `memberUserIds` should be the current group membership minus the sender;
+     * fetch it from your backend / `getGroup()` before calling.
+     *
+     * For unencrypted group messaging (bots, public channels), use
+     * {@link sendCleartextGroupMessage} instead.
+     */
+    async sendGroupMessage(groupId, plaintext, memberUserIds, options) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new Error('DropOnAir websocket is not connected');
         }
@@ -692,20 +704,110 @@ class MessagingClient {
         if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
             throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
         }
+        if (!memberUserIds || memberUserIds.length === 0) {
+            throw new Error('sendGroupMessage requires at least one recipient userId in memberUserIds');
+        }
         const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
         const messageId = crypto.randomUUID();
+        const clientMessageId = messageId;
         const timestamp = Date.now();
-        // For now, group messages use cleartext (E2EE group fanout requires
-        // fetching device keys for every member, which is a future enhancement).
+        const myIdentity = await this.cryptoService.getOrCreateIdentity();
+        const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);
+        // Per-member sender-side fan-out: one GroupMemberPayload per member, each
+        // containing one DeviceEncryptedPayload per device the member has registered.
+        const memberPayloads = [];
+        for (const memberId of memberUserIds) {
+            if (memberId === this.currentUserId)
+                continue; // skip self
+            const deviceKeys = await this.fetchDeviceKeys(memberId);
+            const devicePayloads = [];
+            if (deviceKeys.length > 0) {
+                for (const dk of deviceKeys) {
+                    const sharedKey = await this.cryptoService.deriveSharedSecret(memberId, dk.publicKey, this.currentUserId);
+                    const encrypted = await this.cryptoService.encrypt(plaintext, sharedKey, {
+                        messageId,
+                        senderId: this.currentUserId,
+                        recipientId: memberId,
+                        timestamp,
+                    });
+                    devicePayloads.push({
+                        deviceId: dk.deviceId,
+                        encryptedPayload: encrypted,
+                        senderPublicKey: myPublicKeyBytes,
+                    });
+                }
+            }
+            else {
+                // Legacy fallback: peer reports no multi-device keys. Encrypt once
+                // against the single legacy public key under deviceId="default", which
+                // matches the Android SDK convention.
+                const sharedKey = await this.getPeerSharedKey(memberId);
+                const encrypted = await this.cryptoService.encrypt(plaintext, sharedKey, {
+                    messageId,
+                    senderId: this.currentUserId,
+                    recipientId: memberId,
+                    timestamp,
+                });
+                devicePayloads.push({
+                    deviceId: 'default',
+                    encryptedPayload: encrypted,
+                    senderPublicKey: myPublicKeyBytes,
+                });
+            }
+            memberPayloads.push({ userId: memberId, devicePayloads });
+        }
         const frame = {
             messageId,
+            appId: this.options.appId,
             groupId,
             fromUserId: this.currentUserId,
+            timestamp,
+            clientMessageId,
+            senderDeviceId: myDeviceId,
+            encryptionType: 0, // E2EE
+            memberPayloads,
+        };
+        if (options?.attachments && options.attachments.length > 0) {
+            frame.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
+        }
+        this.ws.send(this.codec.encodeGroupEnvelope(frame));
+        return { messageId };
+    }
+    /**
+     * Send a plaintext (non-encrypted) group message. The server fans out the
+     * cleartext to every other member of the group; useful for bots and public
+     * channels where E2EE isn't required.
+     *
+     * For E2EE group messaging, use {@link sendGroupMessage} which encrypts
+     * per-recipient before sending.
+     */
+    async sendCleartextGroupMessage(groupId, plaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const messageId = crypto.randomUUID();
+        const timestamp = Date.now();
+        const frame = {
+            messageId,
+            appId: this.options.appId,
+            groupId,
+            fromUserId: this.currentUserId,
+            timestamp,
+            clientMessageId: messageId,
             senderDeviceId: myDeviceId,
-            memberPayloads: [],
             encryptionType: 1, // CLEARTEXT
             plaintextPayload: plaintext,
-            timestamp,
+            memberPayloads: [],
         };
         this.ws.send(this.codec.encodeGroupEnvelope(frame));
         return { messageId };

package/dist/core/types.d.ts

@@ -238,8 +238,23 @@ export interface DropOnAirClient {
     removeGroupMember(groupId: string, userId: string): Promise<GroupInfo>;
     /** Delete a group (requires OWNER role). */
     deleteGroup(groupId: string): Promise<void>;
-    /** Send a cleartext message to a group. */
-    sendGroupMessage(groupId: string, plaintext: string): Promise<{
+    /**
+     * Send an end-to-end encrypted group message. The SDK encrypts the
+     * plaintext per recipient device (sender-side fan-out) before sending.
+     * `memberUserIds` should be the current group membership minus the sender;
+     * pass `options.attachments` for per-recipient encrypted attachment refs.
+     */
+    sendGroupMessage(groupId: string, plaintext: string, memberUserIds: string[], options?: {
+        attachments?: import('../attachment/attachment-types').AttachmentRef[];
+    }): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Send a plaintext (non-encrypted) group message. The server fans out the
+     * cleartext to every other member. Use this for bots and public channels;
+     * use {@link sendGroupMessage} for E2EE group messaging.
+     */
+    sendCleartextGroupMessage(groupId: string, plaintext: string): Promise<{
         messageId: string;
     }>;
     /** Register a listener for incoming group messages. Returns an unsubscribe function. */

package/dist/transport/protobuf-codec.d.ts

@@ -82,23 +82,27 @@ export interface WireGroupMemberPayload {
 }
 export interface WireGroupEnvelope {
     messageId: string;
+    appId?: string;
     groupId: string;
     fromUserId: string;
+    timestamp: number;
+    clientMessageId?: string;
     senderDeviceId: string;
-    memberPayloads: WireGroupMemberPayload[];
     encryptionType: number;
     plaintextPayload?: string;
-    timestamp: number;
+    memberPayloads: WireGroupMemberPayload[];
+    attachments?: WireAttachmentRef[];
 }
 export interface WireGroupMessageNotification {
     messageId: string;
     groupId: string;
     fromUserId: string;
-    senderDeviceId: string;
-    devicePayloads: WireDeviceEncryptedPayload[];
+    timestamp: number;
     encryptionType: number;
     plaintextPayload?: string;
-    timestamp: number;
+    devicePayloads: WireDeviceEncryptedPayload[];
+    senderDeviceId: string;
+    attachments?: WireAttachmentRef[];
 }
 export interface WireGroupAck {
     messageId: string;

package/dist/transport/protobuf-codec.js

@@ -124,20 +124,22 @@ const GroupMemberPayloadType = new protobuf.Type('GroupMemberPayload')
     .add(new protobuf.Field('userId', 1, 'string'))
     .add(new protobuf.Field('devicePayloads', 2, 'DeviceEncryptedPayload', 'repeated'));
 const GroupEnvelopeEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
-// NOTE: GroupEnvelope JS field numbers diverge from the proto contract (tracked
-// under phase 2.3 "JS encrypted group send parity"). Attachments support for
-// groups in JS will land with phase 2.3 / 2.4 once field numbers are aligned.
 const GroupEnvelopeType = new protobuf.Type('GroupEnvelope')
     .add(GroupEnvelopeEncryptionTypeEnum)
     .add(GroupMemberPayloadType)
+    .add(AttachmentRefType)
     .add(new protobuf.Field('messageId', 1, 'string'))
-    .add(new protobuf.Field('groupId', 2, 'string'))
-    .add(new protobuf.Field('fromUserId', 3, 'string'))
-    .add(new protobuf.Field('senderDeviceId', 4, 'string'))
-    .add(new protobuf.Field('memberPayloads', 5, 'GroupMemberPayload', 'repeated'))
-    .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
-    .add(new protobuf.Field('plaintextPayload', 7, 'string'))
-    .add(new protobuf.Field('timestamp', 8, 'int64'));
+    .add(new protobuf.Field('appId', 2, 'string'))
+    .add(new protobuf.Field('groupId', 3, 'string'))
+    .add(new protobuf.Field('fromUserId', 4, 'string'))
+    .add(new protobuf.Field('timestamp', 5, 'int64'))
+    .add(new protobuf.Field('clientMessageId', 6, 'string'))
+    .add(new protobuf.Field('senderDeviceId', 7, 'string'))
+    .add(new protobuf.Field('encryptionType', 8, 'EncryptionType'))
+    .add(new protobuf.Field('plaintextPayload', 9, 'string'))
+    .add(new protobuf.Field('memberPayloads', 10, 'GroupMemberPayload', 'repeated'))
+    // field 11 reserved upstream
+    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'));
 const GroupNotifEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
 const GroupNotifDeviceType = new protobuf.Type('DeviceEncryptedPayload')
     .add(new protobuf.Field('deviceId', 1, 'string'))
@@ -149,11 +151,12 @@ const GroupMessageNotificationType = new protobuf.Type('GroupMessageNotification
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('groupId', 2, 'string'))
     .add(new protobuf.Field('fromUserId', 3, 'string'))
-    .add(new protobuf.Field('senderDeviceId', 4, 'string'))
-    .add(new protobuf.Field('devicePayloads', 5, 'DeviceEncryptedPayload', 'repeated'))
-    .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
-    .add(new protobuf.Field('plaintextPayload', 7, 'string'))
-    .add(new protobuf.Field('timestamp', 8, 'int64'));
+    .add(new protobuf.Field('timestamp', 4, 'int64'))
+    .add(new protobuf.Field('encryptionType', 5, 'EncryptionType'))
+    .add(new protobuf.Field('plaintextPayload', 6, 'string'))
+    .add(new protobuf.Field('devicePayloads', 7, 'DeviceEncryptedPayload', 'repeated'))
+    .add(new protobuf.Field('senderDeviceId', 8, 'string'))
+    .add(new protobuf.Field('attachments', 9, 'AttachmentRef', 'repeated'));
 const GroupAckType = new protobuf.Type('GroupAck')
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('groupId', 2, 'string'))

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.8.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.7.0';
+exports.SDK_VERSION = '0.8.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",