@droponair/sdk-js 0.3.0

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

@@ -0,0 +1,138 @@
+/** Per-device encrypted payload on the wire. */
+export interface WireDeviceEncryptedPayload {
+    deviceId: string;
+    encryptedPayload: Uint8Array;
+    senderPublicKey: Uint8Array;
+}
+export interface WireEnvelope {
+    messageId: string;
+    appId: string;
+    fromUserId: string;
+    toUserId: string;
+    timestamp: number;
+    encryptedPayload: Uint8Array;
+    clientMessageId?: string;
+    /** Multi-device: per-device encrypted payloads. */
+    devicePayloads?: WireDeviceEncryptedPayload[];
+    /** Sender's device ID. */
+    senderDeviceId?: string;
+    /** 0 = E2EE (default), 1 = CLEARTEXT */
+    encryptionType?: number;
+    /** Populated only when encryptionType = CLEARTEXT. */
+    plaintextPayload?: string;
+}
+export interface WireAck {
+    messageId: string;
+    type: string;
+}
+export interface WireEvent {
+    type: string;
+    reason?: string;
+    metadata?: string;
+}
+export interface WireCallFrame {
+    type: string;
+    callId?: string;
+    targetUserId?: string;
+    payload?: string;
+}
+export interface WireBroadcastFrame {
+    broadcastId: string;
+    appId: string;
+    channelId: string;
+    publisherId: string;
+    timestamp: number;
+    encryptionType: number;
+    encryptedPayload: Uint8Array;
+    plaintextPayload: string;
+    sequenceNumber: number;
+}
+export interface WireBroadcastNotification {
+    broadcastId: string;
+    channelId: string;
+    publisherId: string;
+    timestamp: number;
+    encryptionType: number;
+    encryptedPayload: Uint8Array;
+    plaintextPayload: string;
+    sequenceNumber: number;
+}
+export interface WireGroupMemberPayload {
+    userId: string;
+    devicePayloads: WireDeviceEncryptedPayload[];
+}
+export interface WireGroupEnvelope {
+    messageId: string;
+    groupId: string;
+    fromUserId: string;
+    senderDeviceId: string;
+    memberPayloads: WireGroupMemberPayload[];
+    encryptionType: number;
+    plaintextPayload?: string;
+    timestamp: number;
+}
+export interface WireGroupMessageNotification {
+    messageId: string;
+    groupId: string;
+    fromUserId: string;
+    senderDeviceId: string;
+    devicePayloads: WireDeviceEncryptedPayload[];
+    encryptionType: number;
+    plaintextPayload?: string;
+    timestamp: number;
+}
+export interface WireGroupAck {
+    messageId: string;
+    groupId: string;
+    type: string;
+}
+export interface WireGroupCallFrame {
+    type: string;
+    callId: string;
+    groupId: string;
+    targetUserId?: string;
+    payload?: string;
+}
+export type InboundFrame = {
+    kind: 'envelope';
+    data: WireEnvelope;
+} | {
+    kind: 'ack';
+    data: WireAck;
+} | {
+    kind: 'event';
+    data: WireEvent;
+} | {
+    kind: 'call';
+    data: WireCallFrame;
+} | {
+    kind: 'broadcast';
+    data: WireBroadcastNotification;
+} | {
+    kind: 'groupMessage';
+    data: WireGroupMessageNotification;
+} | {
+    kind: 'groupAck';
+    data: WireGroupAck;
+} | {
+    kind: 'groupCall';
+    data: WireGroupCallFrame;
+};
+export declare class ProtobufCodec {
+    encodeEnvelope(value: WireEnvelope): Uint8Array;
+    encodeAck(value: WireAck): Uint8Array;
+    encodeCallFrame(value: WireCallFrame): Uint8Array;
+    encodeBroadcastFrame(value: WireBroadcastFrame): Uint8Array;
+    encodeGroupEnvelope(value: WireGroupEnvelope): Uint8Array;
+    encodeGroupCallFrame(value: WireGroupCallFrame): Uint8Array;
+    encodeGroupAck(value: WireGroupAck): Uint8Array;
+    decodeFrame(payload: Uint8Array): InboundFrame;
+    private tryDecodeEnvelope;
+    private tryDecodeAck;
+    private tryDecodeEvent;
+    private tryDecodeCallFrame;
+    private tryDecodeBroadcastNotification;
+    private tryDecodeGroupMessageNotification;
+    private tryDecodeGroupAck;
+    private tryDecodeGroupCallFrame;
+}

package/dist/transport/protobuf-codec.js

@@ -0,0 +1,337 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtobufCodec = void 0;
+const protobuf = __importStar(require("protobufjs/light"));
+// EncryptionType enum: E2EE = 0, CLEARTEXT = 1
+const EncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
+// Per-device encrypted payload for multi-device E2EE
+const DeviceEncryptedPayloadType = new protobuf.Type('DeviceEncryptedPayload')
+    .add(new protobuf.Field('deviceId', 1, 'string'))
+    .add(new protobuf.Field('encryptedPayload', 2, 'bytes'))
+    .add(new protobuf.Field('senderPublicKey', 3, 'bytes'));
+const EnvelopeType = new protobuf.Type('Envelope')
+    .add(EncryptionTypeEnum)
+    .add(DeviceEncryptedPayloadType) // nested type must be added first
+    .add(new protobuf.Field('messageId', 1, 'string'))
+    .add(new protobuf.Field('appId', 2, 'string'))
+    .add(new protobuf.Field('fromUserId', 3, 'string'))
+    .add(new protobuf.Field('toUserId', 4, 'string'))
+    .add(new protobuf.Field('timestamp', 5, 'int64'))
+    .add(new protobuf.Field('encryptedPayload', 6, 'bytes'))
+    .add(new protobuf.Field('clientMessageId', 7, 'string'))
+    .add(new protobuf.Field('devicePayloads', 8, 'DeviceEncryptedPayload', 'repeated'))
+    .add(new protobuf.Field('senderDeviceId', 9, 'string'))
+    .add(new protobuf.Field('encryptionType', 10, 'EncryptionType'))
+    .add(new protobuf.Field('plaintextPayload', 11, 'string'));
+const AckType = new protobuf.Type('Ack')
+    .add(new protobuf.Field('messageId', 1, 'string'))
+    .add(new protobuf.Field('type', 2, 'string'));
+const EventType = new protobuf.Type('Event')
+    .add(new protobuf.Field('type', 1, 'string'))
+    .add(new protobuf.Field('reason', 2, 'string'))
+    .add(new protobuf.Field('metadata', 3, 'string'));
+const CallFrameType = new protobuf.Type('CallFrame')
+    .add(new protobuf.Field('type', 1, 'string'))
+    .add(new protobuf.Field('callId', 2, 'string'))
+    .add(new protobuf.Field('targetUserId', 3, 'string'))
+    .add(new protobuf.Field('payload', 4, 'string'));
+// EncryptionType enum for standalone types (BroadcastFrame/BroadcastNotification)
+const BroadcastEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
+const BroadcastFrameType = new protobuf.Type('BroadcastFrame')
+    .add(BroadcastEncryptionTypeEnum)
+    .add(new protobuf.Field('broadcastId', 1, 'string'))
+    .add(new protobuf.Field('appId', 2, 'string'))
+    .add(new protobuf.Field('channelId', 3, 'string'))
+    .add(new protobuf.Field('publisherId', 4, 'string'))
+    .add(new protobuf.Field('timestamp', 5, 'int64'))
+    .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
+    .add(new protobuf.Field('encryptedPayload', 7, 'bytes'))
+    .add(new protobuf.Field('plaintextPayload', 8, 'string'))
+    .add(new protobuf.Field('sequenceNumber', 9, 'int32'));
+const BroadcastNotifEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
+const BroadcastNotificationType = new protobuf.Type('BroadcastNotification')
+    .add(BroadcastNotifEncryptionTypeEnum)
+    .add(new protobuf.Field('broadcastId', 1, 'string'))
+    .add(new protobuf.Field('channelId', 2, 'string'))
+    .add(new protobuf.Field('publisherId', 3, 'string'))
+    .add(new protobuf.Field('timestamp', 4, 'int64'))
+    .add(new protobuf.Field('encryptionType', 5, 'EncryptionType'))
+    .add(new protobuf.Field('encryptedPayload', 6, 'bytes'))
+    .add(new protobuf.Field('plaintextPayload', 7, 'string'))
+    .add(new protobuf.Field('sequenceNumber', 8, 'int32'));
+// ---------------------------------------------------------------------------
+// Group messaging types
+// ---------------------------------------------------------------------------
+const GroupMemberPayloadDeviceType = new protobuf.Type('DeviceEncryptedPayload')
+    .add(new protobuf.Field('deviceId', 1, 'string'))
+    .add(new protobuf.Field('encryptedPayload', 2, 'bytes'))
+    .add(new protobuf.Field('senderPublicKey', 3, 'bytes'));
+const GroupMemberPayloadType = new protobuf.Type('GroupMemberPayload')
+    .add(GroupMemberPayloadDeviceType)
+    .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 });
+const GroupEnvelopeType = new protobuf.Type('GroupEnvelope')
+    .add(GroupEnvelopeEncryptionTypeEnum)
+    .add(GroupMemberPayloadType)
+    .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'));
+const GroupNotifEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
+const GroupNotifDeviceType = new protobuf.Type('DeviceEncryptedPayload')
+    .add(new protobuf.Field('deviceId', 1, 'string'))
+    .add(new protobuf.Field('encryptedPayload', 2, 'bytes'))
+    .add(new protobuf.Field('senderPublicKey', 3, 'bytes'));
+const GroupMessageNotificationType = new protobuf.Type('GroupMessageNotification')
+    .add(GroupNotifEncryptionTypeEnum)
+    .add(GroupNotifDeviceType)
+    .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'));
+const GroupAckType = new protobuf.Type('GroupAck')
+    .add(new protobuf.Field('messageId', 1, 'string'))
+    .add(new protobuf.Field('groupId', 2, 'string'))
+    .add(new protobuf.Field('type', 3, 'string'));
+const GroupCallFrameType = new protobuf.Type('GroupCallFrame')
+    .add(new protobuf.Field('type', 1, 'string'))
+    .add(new protobuf.Field('callId', 2, 'string'))
+    .add(new protobuf.Field('groupId', 3, 'string'))
+    .add(new protobuf.Field('targetUserId', 4, 'string'))
+    .add(new protobuf.Field('payload', 5, 'string'));
+class ProtobufCodec {
+    encodeEnvelope(value) {
+        return EnvelopeType.encode(value).finish();
+    }
+    encodeAck(value) {
+        return AckType.encode(value).finish();
+    }
+    encodeCallFrame(value) {
+        return CallFrameType.encode(value).finish();
+    }
+    encodeBroadcastFrame(value) {
+        return BroadcastFrameType.encode(value).finish();
+    }
+    encodeGroupEnvelope(value) {
+        return GroupEnvelopeType.encode(value).finish();
+    }
+    encodeGroupCallFrame(value) {
+        return GroupCallFrameType.encode(value).finish();
+    }
+    encodeGroupAck(value) {
+        return GroupAckType.encode(value).finish();
+    }
+    decodeFrame(payload) {
+        const asEnvelope = this.tryDecodeEnvelope(payload);
+        if (asEnvelope) {
+            return { kind: 'envelope', data: asEnvelope };
+        }
+        // CallFrame must be checked before BroadcastNotification because protobuf
+        // field numbers overlap: CallFrame.type (1) parses into
+        // BroadcastNotification.broadcastId (1), causing call frames to be
+        // misclassified as broadcasts.
+        const asCall = this.tryDecodeCallFrame(payload);
+        if (asCall) {
+            return { kind: 'call', data: asCall };
+        }
+        // Group call frame must be checked before group message notification
+        const asGroupCall = this.tryDecodeGroupCallFrame(payload);
+        if (asGroupCall) {
+            return { kind: 'groupCall', data: asGroupCall };
+        }
+        // Group message notification (per-member stripped payload from server)
+        const asGroupMsg = this.tryDecodeGroupMessageNotification(payload);
+        if (asGroupMsg) {
+            return { kind: 'groupMessage', data: asGroupMsg };
+        }
+        // Group ack
+        const asGroupAck = this.tryDecodeGroupAck(payload);
+        if (asGroupAck) {
+            return { kind: 'groupAck', data: asGroupAck };
+        }
+        const asBroadcast = this.tryDecodeBroadcastNotification(payload);
+        if (asBroadcast) {
+            return { kind: 'broadcast', data: asBroadcast };
+        }
+        const asAck = this.tryDecodeAck(payload);
+        if (asAck) {
+            return { kind: 'ack', data: asAck };
+        }
+        const asEvent = this.tryDecodeEvent(payload);
+        if (asEvent) {
+            return { kind: 'event', data: asEvent };
+        }
+        throw new Error('Unsupported inbound protobuf frame');
+    }
+    tryDecodeEnvelope(payload) {
+        try {
+            const decoded = EnvelopeType.decode(payload);
+            if (!decoded.messageId || !decoded.toUserId) {
+                return null;
+            }
+            // Accept legacy encryptedPayload, multi-device devicePayloads, or cleartext
+            const hasLegacyPayload = decoded.encryptedPayload && decoded.encryptedPayload.length > 0;
+            const hasDevicePayloads = decoded.devicePayloads && decoded.devicePayloads.length > 0;
+            const isCleartext = decoded.encryptionType === 1 && !!decoded.plaintextPayload;
+            if (!hasLegacyPayload && !hasDevicePayloads && !isCleartext) {
+                return null;
+            }
+            const result = {
+                ...decoded,
+                timestamp: Number(decoded.timestamp),
+                encryptedPayload: decoded.encryptedPayload ? new Uint8Array(decoded.encryptedPayload) : new Uint8Array(0),
+            };
+            // Normalize device payloads
+            if (hasDevicePayloads) {
+                result.devicePayloads = decoded.devicePayloads.map(dp => ({
+                    deviceId: dp.deviceId,
+                    encryptedPayload: new Uint8Array(dp.encryptedPayload),
+                    senderPublicKey: new Uint8Array(dp.senderPublicKey),
+                }));
+            }
+            return result;
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeAck(payload) {
+        try {
+            const decoded = AckType.decode(payload);
+            if (!decoded.messageId || !decoded.type) {
+                return null;
+            }
+            return decoded;
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeEvent(payload) {
+        try {
+            const decoded = EventType.decode(payload);
+            if (!decoded.type) {
+                return null;
+            }
+            return decoded;
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeCallFrame(payload) {
+        try {
+            const decoded = CallFrameType.decode(payload);
+            if (!decoded.type || !decoded.type.startsWith('CALL_')) {
+                return null;
+            }
+            return decoded;
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeBroadcastNotification(payload) {
+        try {
+            const decoded = BroadcastNotificationType.decode(payload);
+            if (!decoded.broadcastId || !decoded.channelId) {
+                return null;
+            }
+            return {
+                ...decoded,
+                timestamp: Number(decoded.timestamp),
+                encryptedPayload: decoded.encryptedPayload ? new Uint8Array(decoded.encryptedPayload) : new Uint8Array(0),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeGroupMessageNotification(payload) {
+        try {
+            const decoded = GroupMessageNotificationType.decode(payload);
+            if (!decoded.messageId || !decoded.groupId) {
+                return null;
+            }
+            return {
+                ...decoded,
+                timestamp: Number(decoded.timestamp),
+                devicePayloads: decoded.devicePayloads?.map(dp => ({
+                    deviceId: dp.deviceId,
+                    encryptedPayload: new Uint8Array(dp.encryptedPayload),
+                    senderPublicKey: new Uint8Array(dp.senderPublicKey),
+                })) ?? [],
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeGroupAck(payload) {
+        try {
+            const decoded = GroupAckType.decode(payload);
+            if (!decoded.messageId || !decoded.groupId) {
+                return null;
+            }
+            return decoded;
+        }
+        catch {
+            return null;
+        }
+    }
+    tryDecodeGroupCallFrame(payload) {
+        try {
+            const decoded = GroupCallFrameType.decode(payload);
+            if (!decoded.type || !decoded.type.startsWith('GROUP_CALL_')) {
+                return null;
+            }
+            return decoded;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.ProtobufCodec = ProtobufCodec;

package/dist/version.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SDK version, follows semver. Bump on every release.
+ * Transmitted as X-SDK-Version header on WebSocket handshake and token exchange.
+ *
+ * Versioning rules:
+ *   MAJOR, breaking wire-format or API change (e.g. new proto field required by server)
+ *   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.3.0";
+/**
+ * Binary encrypted-payload format version.
+ * Included as the first byte of every encrypted payload so receivers can
+ * select the correct decryption path if the format ever changes.
+ */
+export declare const PAYLOAD_FORMAT_VERSION = 1;
+/**
+ * Protobuf wire protocol version.
+ * Increment when adding required proto fields or changing frame semantics.
+ * The server advertises its supported range via GET /api/info.
+ */
+export declare const PROTOCOL_VERSION = 2;

package/dist/version.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION = void 0;
+/**
+ * SDK version, follows semver. Bump on every release.
+ * Transmitted as X-SDK-Version header on WebSocket handshake and token exchange.
+ *
+ * Versioning rules:
+ *   MAJOR, breaking wire-format or API change (e.g. new proto field required by server)
+ *   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.3.0';
+/**
+ * Binary encrypted-payload format version.
+ * Included as the first byte of every encrypted payload so receivers can
+ * select the correct decryption path if the format ever changes.
+ */
+exports.PAYLOAD_FORMAT_VERSION = 1;
+/**
+ * Protobuf wire protocol version.
+ * Increment when adding required proto fields or changing frame semantics.
+ * The server advertises its supported range via GET /api/info.
+ */
+exports.PROTOCOL_VERSION = 2;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@droponair/sdk-js",
+  "version": "0.3.0",
+  "description": "DropOnAir SDK for end-to-end encrypted messaging",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "smoke": "ts-node smoke/messaging-client-smoke.ts",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "droponair",
+    "messaging",
+    "e2ee",
+    "encryption",
+    "end-to-end",
+    "sdk"
+  ],
+  "author": "DropOnAir",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://droponair.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "protobufjs": "^7.4.0",
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-util": "^0.15.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  }
+}