@droponair/sdk-js 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,60 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0], 2026-05-18
+
+### Added
+- **Screen sharing signaling.** New client APIs and event types so apps can
+  coordinate the start/stop of a screen-share track on top of the existing
+  WebRTC call. The SDK only signals - capture (`getDisplayMedia()` on web) and
+  track management remain in the app layer.
+- **1:1 calls:**
+  - `client.startScreenShare(callId, payload?)` and `client.stopScreenShare(callId, payload?)`.
+  - New `CallEventType` values: `'CALL_SCREEN_SHARE_STARTED'`, `'CALL_SCREEN_SHARE_STOPPED'`.
+- **Group calls:**
+  - `client.startGroupScreenShare(callId, groupId, payload?)` and `client.stopGroupScreenShare(callId, groupId, payload?)`.
+  - New `GroupCallEventType` values: `'GROUP_CALL_SCREEN_SHARE_STARTED'`, `'GROUP_CALL_SCREEN_SHARE_STOPPED'`.
+  - Server enforces a single concurrent sharer per group call. If another
+    participant already holds the slot when you call `startGroupScreenShare`,
+    you'll receive a `GROUP_CALL_SCREEN_SHARE_STOPPED` event with the current
+    holder's userId in `payload`, so the app can roll back its optimistic UI.
+  - When a sharer leaves the call, the server broadcasts a STOPPED event to
+    remaining participants before they see `PARTICIPANT_LEFT`.
+- `GET /api/info` now advertises `"screen_sharing"` in the `features` array.
+
+### Notes
+- Wire-level additive: legacy 0.5.x clients ignore the new signal type strings
+  (string discriminators on existing `CallFrame.type` / `GroupCallFrame.type`).
+  No proto schema change, no `PROTOCOL_VERSION` bump.
+- Screen content is opaque WebRTC media; the server never sees it. Use
+  `getDisplayMedia()` (web) / `MediaProjection` (Android) / `ReplayKit` (iOS)
+  in the app, add the track to the existing peer connection, then call
+  `startScreenShare(...)` to notify the peer.
+- Plan gate: `screen_sharing` is enabled on PRO/GROWTH/PAYG/ENTERPRISE and
+  disabled on FREE. Check `subscription.featuresEnabled.screen_sharing` (server
+  side, on the customer's backend).
+
+---
+
+## [0.5.0], 2026-05-18
+
+### Added
+- **Attachment pointers with customer-managed storage.** DropOnAir never holds file bytes; the SDK uploads/downloads directly against the customer's bucket via short-lived presigned URLs.
+- **New high-level API:** `client.prepareAttachmentAndUpload(bytes, options)` encrypts (for E2EE), uploads to the customer's bucket, finalizes, and returns an `AttachmentRef` ready to drop into `sendMessage(toUserId, text, { attachments: [...] })`.
+- **New low-level API:** `client.createUploadSession(options)`, `client.finalizeAttachment(id, sha256)`, `client.downloadAttachment(ref)`.
+- **E2EE attachments:** per-attachment AES-256-GCM file key wrapped per recipient device using X25519 + HKDF, mirroring the per-device key model used for message payloads. Server never sees the unwrapped file key.
+- **`DecryptedMessage.attachments`:** incoming messages now carry the optional `attachments: AttachmentRef[]` field.
+- **PROTOCOL_VERSION = 4.** `features` now advertises `attachments` from `GET /api/info`.
+- New public types: `AttachmentRef`, `DeviceWrappedKey`, `AttachmentEncryptionType`, `AttachmentConversationType`, `CreateUploadSessionOptions`, `UploadSession`, `PrepareAttachmentOptions`, `DownloadedAttachment`.
+
+### Notes
+- Wire-level additive: legacy 0.4.x clients ignore the new `Envelope.attachments` field (proto3 forwards-compat). Existing apps continue to work unchanged.
+- v1 storage adapters supported by the server: S3-compatible (S3, R2, MinIO, B2, Wasabi), Google Cloud Storage, Azure Blob.
+- Plan limits: `maxAttachmentSizeMb` per file + `maxAttachmentsPerMonth`. FREE = attachments disabled. PRO = 25 MB / 1000 per month. GROWTH = 100 MB / 10000. PAYG = 250 MB / metered. ENTERPRISE = custom.
+- Requires sdk-be `0.5.0` server.
+
+---
+
 ## [0.4.0], 2026-04-21
 
 ### Added

package/README.md

@@ -45,6 +45,7 @@ await client.sendMessage('recipient-user-id', 'Hello!');
 ## Features
 
 - **E2EE Messaging** - X25519 key agreement, AES-256-GCM encryption, multi-device support
+- **Message Edit & Delete** - Edit sent messages or tombstone them for everyone or only your own devices
 - **Cleartext Messaging** - Lightweight messages without E2EE overhead
 - **Broadcast Channels** - Pub/sub for announcements and notifications
 - **Group Messaging** - Server-managed groups with member roles
@@ -86,11 +87,82 @@ const client = await initialize(options);
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `sendMessage(toUserId, plaintext)` | `Promise<{ messageId }>` | Send an encrypted message |
+| `editMessage(originalMessageId, toUserId, newText)` | `Promise<{ editId }>` | Edit a previously sent encrypted message |
+| `deleteMessage(originalMessageId, toUserId, scope)` | `Promise<{ deleteId }>` | Delete a previously sent 1:1 message. `scope` is `FOR_EVERYONE` or `FOR_ME` |
 | `sendCleartextMessage(toUserId, plaintext)` | `Promise<{ messageId }>` | Send a cleartext message (no E2EE) |
+| `editCleartextMessage(originalMessageId, toUserId, newText)` | `Promise<{ editId }>` | Edit a previously sent cleartext message |
 | `onMessage(callback)` | `() => void` | Listen for incoming messages. Returns unsubscribe function |
+| `onMessageEdit(callback)` | `() => void` | Listen for inbound edits to 1:1 messages |
+| `onMessageDelete(callback)` | `() => void` | Listen for inbound delete tombstones for 1:1 messages |
 | `onEvent(callback)` | `() => void` | Listen for system events (CONNECTED, DELIVERED, ERROR, etc.) |
 | `ack(messageId)` | `Promise<void>` | Manually acknowledge a message |
 
+### Message Edit & Delete
+
+Available since SDK `0.4.0` and requires sdk-be `0.4.0`.
+
+```typescript
+// Edit an encrypted message
+await client.editMessage(originalMessageId, 'recipient-user-id', 'Updated text');
+
+// Edit a cleartext message
+await client.editCleartextMessage(originalMessageId, 'recipient-user-id', 'Updated text');
+
+// Delete for everyone
+await client.deleteMessage(originalMessageId, 'recipient-user-id', 'FOR_EVERYONE');
+
+// Delete only on the sender's own devices
+await client.deleteMessage(originalMessageId, 'recipient-user-id', 'FOR_ME');
+
+client.onMessageEdit((edit) => {
+  console.log('edited', edit.originalMessageId, edit.text);
+});
+
+client.onMessageDelete((del) => {
+  console.log('deleted', del.originalMessageId, del.scope);
+});
+```
+
+- E2EE edits are re-encrypted per recipient device; the relay never sees the new plaintext.
+- `FOR_EVERYONE` notifies the recipient; `FOR_ME` only syncs the tombstone to the sender's other devices.
+- Each edit and each `FOR_EVERYONE` delete counts as one `MESSAGE` usage record.
+
+### Attachments (Customer-Managed Storage)
+
+Available since SDK `0.5.0` and requires sdk-be `0.5.0`. Configure your bucket once in the DropOnAir panel (S3-compatible, GCS, or Azure Blob). DropOnAir never holds file bytes - the SDK uploads/downloads directly against your bucket via short-lived presigned URLs.
+
+```typescript
+// Convenience: encrypt + upload + finalize in one call, then send with the message.
+const ref = await client.prepareAttachmentAndUpload(fileBytes, {
+  toUserId: 'recipient-user-id',
+  mimeType: 'image/jpeg',
+  encryptionType: 'E2EE',          // or 'CLEARTEXT' for public files
+});
+
+await client.sendMessage('recipient-user-id', 'Here is the file', { attachments: [ref] });
+
+// Recipient side: incoming DecryptedMessage carries optional attachments[]
+client.onMessage(async (msg) => {
+  console.log(msg.plaintext);
+  for (const att of msg.attachments ?? []) {
+    const dl = await client.downloadAttachment(att);
+    // dl.bytes is Uint8Array, dl.mimeType / dl.sizeBytes / dl.sha256 are populated
+  }
+});
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `prepareAttachmentAndUpload(bytes, options)` | `Promise<AttachmentRef>` | Encrypt (E2EE), upload, finalize, return ref |
+| `createUploadSession(options)` | `Promise<UploadSession>` | Low-level: presigned PUT URL only |
+| `finalizeAttachment(attachmentId, sha256)` | `Promise<void>` | Low-level: commit integrity hash |
+| `downloadAttachment(ref)` | `Promise<DownloadedAttachment>` | Get presigned URL + download + decrypt |
+| `sendMessage(toUserId, text, { attachments })` | `Promise<{ messageId }>` | Send with attachments |
+
+- E2EE: a random AES-256-GCM file key encrypts the bytes; the file key is wrapped per recipient device using X25519 + HKDF (same model as message payloads). Server never sees the unwrapped file key.
+- Plan limits: `maxAttachmentSizeMb` per file + `maxAttachmentsPerMonth`. Enforced server-side before the presigned URL is issued.
+- Upload URL TTL = 15 min. Download URL TTL = 5 min. Download authorization checks that the requester is the original sender or in the captured recipient list.
+
 ### Broadcast Channels
 
 | Method | Returns | Description |
@@ -137,6 +209,51 @@ const client = await initialize(options);
 | `sendGroupCallSignal(type, callId, groupId, targetUserId, payload)` | `void` | Send SDP/ICE to a peer |
 | `onGroupCallEvent(callback)` | `() => void` | Listen for group call events |
 
+### Screen Sharing
+
+Available since SDK `0.6.0`. The SDK only signals start/stop - capture (via the browser's `getDisplayMedia()`) and adding the resulting `MediaStreamTrack` to the existing peer connection are the app's responsibility.
+
+```typescript
+// 1:1 call
+async function shareMyScreen(callId: string, peerConnection: RTCPeerConnection) {
+  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
+  const track  = stream.getVideoTracks()[0];
+  peerConnection.addTrack(track, stream);
+  client.startScreenShare(callId);
+  track.onended = () => client.stopScreenShare(callId);
+}
+
+// Group call
+async function shareMyScreenInGroup(callId: string, groupId: string, peerConnections: RTCPeerConnection[]) {
+  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
+  const track  = stream.getVideoTracks()[0];
+  peerConnections.forEach(pc => pc.addTrack(track, stream));
+  client.startGroupScreenShare(callId, groupId);
+  track.onended = () => client.stopGroupScreenShare(callId, groupId);
+}
+
+client.onCallEvent((evt) => {
+  if (evt.type === 'CALL_SCREEN_SHARE_STARTED')  showShareIndicator(evt.callId);
+  if (evt.type === 'CALL_SCREEN_SHARE_STOPPED')  hideShareIndicator(evt.callId);
+});
+
+client.onGroupCallEvent((evt) => {
+  if (evt.type === 'GROUP_CALL_SCREEN_SHARE_STARTED')  showShareIndicator(evt.callId, evt.payload);  // payload = sharer userId
+  if (evt.type === 'GROUP_CALL_SCREEN_SHARE_STOPPED')  hideShareIndicator(evt.callId);
+});
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `startScreenShare(callId, payload?)` | `void` | Signal start in a 1:1 call |
+| `stopScreenShare(callId, payload?)` | `void` | Signal stop in a 1:1 call |
+| `startGroupScreenShare(callId, groupId, payload?)` | `void` | Signal start in a group call |
+| `stopGroupScreenShare(callId, groupId, payload?)` | `void` | Signal stop in a group call |
+
+- The server enforces **one concurrent sharer per group call**. If another participant already holds the slot when you call `startGroupScreenShare`, the SDK delivers a `GROUP_CALL_SCREEN_SHARE_STOPPED` event with the current holder's userId in `payload`, so you can roll back the optimistic UI.
+- When a sharer leaves the call, the server broadcasts a STOPPED event to remaining participants before they see `PARTICIPANT_LEFT`.
+- Plan gate: `screen_sharing` is on `PRO`/`GROWTH`/`PAYG`/`ENTERPRISE`, off on `FREE`. Read `subscription.featuresEnabled.screen_sharing` on your backend to decide whether to expose the share button.
+
 ## Security
 
 - **X25519 ECDH** key agreement for shared secrets

package/dist/attachment/attachment-client.d.ts

@@ -0,0 +1,74 @@
+import { CryptoService } from '../crypto/crypto-service';
+import { WireAttachmentRef } from '../transport/protobuf-codec';
+interface DeviceKeyInfo {
+    deviceId: string;
+    publicKey: string;
+}
+import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from './attachment-types';
+interface AttachmentClientDeps {
+    httpUrl: string;
+    fetchFn: typeof fetch;
+    getValidDropOnAirJwt: () => Promise<string>;
+    fetchDeviceKeys: (userId: string) => Promise<DeviceKeyInfo[]>;
+    fetchMyOtherDeviceKeys: (myDeviceId: string) => Promise<DeviceKeyInfo[]>;
+    getCurrentUserId: () => string;
+    getCurrentDeviceId: () => Promise<string>;
+    getKeyStorage: () => {
+        get(k: string): Promise<string | null>;
+    };
+    cryptoService: CryptoService;
+    log: (stage: string, data?: Record<string, unknown>) => void;
+    logError: (stage: string, data?: Record<string, unknown>) => void;
+}
+/**
+ * SDK-side coordinator for phase1/attachments. Handles:
+ *  - createUploadSession: reserves an attachmentId + presigned PUT URL via sdk-be.
+ *  - uploadBytes: PUTs bytes directly to the customer's bucket.
+ *  - finalize: confirms upload + commits sha256.
+ *  - prepareAttachmentAndUpload: convenience wrapper that does upload session,
+ *    optional E2EE encryption + per-device key wrap, PUT, finalize, and returns
+ *    a fully-populated AttachmentRef ready to drop into sendMessage.
+ *  - downloadAttachment: fetches presigned GET, downloads, decrypts if E2EE.
+ *
+ * DropOnAir never holds file bytes - the SDK transfers bytes directly between
+ * the client and the customer's storage bucket.
+ */
+export declare class AttachmentClient {
+    private readonly deps;
+    constructor(deps: AttachmentClientDeps);
+    createUploadSession(opts: CreateUploadSessionOptions): Promise<UploadSession>;
+    finalize(attachmentId: string, sha256: string): Promise<void>;
+    /**
+     * Convenience: encrypts bytes if E2EE, uploads to the customer's bucket,
+     * finalizes, and returns a fully-formed AttachmentRef for sendMessage.
+     */
+    prepareAttachmentAndUpload(input: Uint8Array, opts: PrepareAttachmentOptions): Promise<AttachmentRef>;
+    getDownloadUrl(attachmentId: string): Promise<{
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        mimeType: string;
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    /**
+     * Downloads + decrypts an attachment. For E2EE, finds the wrappedKey for the
+     * current device, unwraps it, then decrypts the stored bytes.
+     */
+    downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
+    /** Convert public AttachmentRef into the wire-format type for proto encoding. */
+    toWire(ref: AttachmentRef): WireAttachmentRef;
+    /** Convert a wire AttachmentRef (from a received message) into the public type. */
+    static fromWire(wire: WireAttachmentRef): AttachmentRef;
+    private uploadBytes;
+    private wrapKeyForRecipients;
+    private unwrapKey;
+    /**
+     * HKDF for the attachment file-key wrap. Sender and recipient both compute
+     * the same X25519 shared secret (by symmetry of curve25519) and derive the
+     * same AES-GCM key via this HKDF. Distinct info/salt from the message-payload
+     * HKDF in CryptoService to avoid key reuse across protocols.
+     */
+    private deriveAttachmentWrapKey;
+}
+export {};

package/dist/attachment/attachment-client.js

@@ -0,0 +1,323 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentClient = void 0;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const bytes_1 = require("../core/bytes");
+const STORAGE_PRIVATE = 'droponair.identity.privateKey.v1';
+function asBufferSource(data) {
+    return new Uint8Array(data);
+}
+async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', asBufferSource(bytes));
+    const hex = [];
+    const view = new Uint8Array(digest);
+    for (let i = 0; i < view.length; i += 1) {
+        hex.push(view[i].toString(16).padStart(2, '0'));
+    }
+    return hex.join('');
+}
+/**
+ * SDK-side coordinator for phase1/attachments. Handles:
+ *  - createUploadSession: reserves an attachmentId + presigned PUT URL via sdk-be.
+ *  - uploadBytes: PUTs bytes directly to the customer's bucket.
+ *  - finalize: confirms upload + commits sha256.
+ *  - prepareAttachmentAndUpload: convenience wrapper that does upload session,
+ *    optional E2EE encryption + per-device key wrap, PUT, finalize, and returns
+ *    a fully-populated AttachmentRef ready to drop into sendMessage.
+ *  - downloadAttachment: fetches presigned GET, downloads, decrypts if E2EE.
+ *
+ * DropOnAir never holds file bytes - the SDK transfers bytes directly between
+ * the client and the customer's storage bucket.
+ */
+class AttachmentClient {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async createUploadSession(opts) {
+        const jwt = await this.deps.getValidDropOnAirJwt();
+        const body = {
+            mimeType: opts.mimeType ?? '',
+            sizeBytes: opts.sizeBytes,
+            encryptionType: opts.encryptionType ?? 'E2EE',
+            conversationType: opts.conversationType ?? 'ONE_TO_ONE',
+            conversationId: opts.conversationId ?? '',
+            recipientUserIds: opts.recipientUserIds ?? [],
+        };
+        const resp = await this.deps.fetchFn(`${this.deps.httpUrl}/v1/attachments/upload-session`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            this.deps.logError('attachment_upload_session_failed', { status: resp.status, body: text.slice(0, 400) });
+            throw new Error(`Failed to create upload session (HTTP ${resp.status}): ${text}`);
+        }
+        return (await resp.json());
+    }
+    async finalize(attachmentId, sha256) {
+        const jwt = await this.deps.getValidDropOnAirJwt();
+        const resp = await this.deps.fetchFn(`${this.deps.httpUrl}/v1/attachments/${encodeURIComponent(attachmentId)}/finalize`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sha256 }),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Failed to finalize attachment (HTTP ${resp.status}): ${text}`);
+        }
+    }
+    /**
+     * Convenience: encrypts bytes if E2EE, uploads to the customer's bucket,
+     * finalizes, and returns a fully-formed AttachmentRef for sendMessage.
+     */
+    async prepareAttachmentAndUpload(input, opts) {
+        if (!input || input.length === 0) {
+            throw new Error('attachment bytes are empty');
+        }
+        const encryptionType = opts.encryptionType ?? 'E2EE';
+        const conversationType = opts.groupId ? 'GROUP' : 'ONE_TO_ONE';
+        if (conversationType === 'ONE_TO_ONE' && !opts.toUserId) {
+            throw new Error('toUserId is required for one-to-one attachments');
+        }
+        if (conversationType === 'GROUP' && (!opts.recipientUserIds || opts.recipientUserIds.length === 0)) {
+            throw new Error('recipientUserIds is required for group attachments');
+        }
+        let storedBytes;
+        let fileKey = null;
+        let fileNonce = null;
+        if (encryptionType === 'E2EE') {
+            fileKey = (0, bytes_1.randomBytes)(32);
+            fileNonce = (0, bytes_1.randomBytes)(12);
+            const aesKey = await crypto.subtle.importKey('raw', asBufferSource(fileKey), { name: 'AES-GCM' }, false, ['encrypt']);
+            const cipher = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: asBufferSource(fileNonce), tagLength: 128 }, aesKey, asBufferSource(input));
+            // Pack nonce || ciphertext so download side can split without separate transport.
+            const ct = new Uint8Array(cipher);
+            storedBytes = new Uint8Array(fileNonce.length + ct.length);
+            storedBytes.set(fileNonce, 0);
+            storedBytes.set(ct, fileNonce.length);
+        }
+        else {
+            storedBytes = input;
+        }
+        const sha256 = await sha256Hex(storedBytes);
+        // Reserve upload session up-front so the server can validate plan limits
+        // before we burn bandwidth on a bucket PUT we know would fail later.
+        const recipientUserIds = opts.recipientUserIds ?? (opts.toUserId ? [opts.toUserId] : []);
+        const session = await this.createUploadSession({
+            mimeType: opts.mimeType ?? '',
+            sizeBytes: storedBytes.length,
+            encryptionType,
+            conversationType,
+            conversationId: opts.groupId,
+            recipientUserIds,
+        });
+        await this.uploadBytes(session, storedBytes, opts.onUploadProgress);
+        await this.finalize(session.attachmentId, sha256);
+        let wrappedKeys = [];
+        if (encryptionType === 'E2EE' && fileKey) {
+            wrappedKeys = await this.wrapKeyForRecipients(fileKey, opts);
+        }
+        return {
+            attachmentId: session.attachmentId,
+            storageHint: session.storageHint,
+            mimeType: opts.mimeType ?? '',
+            sizeBytes: storedBytes.length,
+            sha256,
+            encryptionType,
+            wrappedKeys,
+        };
+    }
+    async getDownloadUrl(attachmentId) {
+        const jwt = await this.deps.getValidDropOnAirJwt();
+        const resp = await this.deps.fetchFn(`${this.deps.httpUrl}/v1/attachments/${encodeURIComponent(attachmentId)}/download-url`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Failed to get download URL (HTTP ${resp.status}): ${text}`);
+        }
+        const body = await resp.json();
+        return {
+            url: body.downloadUrl,
+            method: body.downloadMethod,
+            headers: body.downloadHeaders ?? {},
+            mimeType: body.mimeType,
+            sizeBytes: body.sizeBytes,
+            sha256: body.sha256,
+        };
+    }
+    /**
+     * Downloads + decrypts an attachment. For E2EE, finds the wrappedKey for the
+     * current device, unwraps it, then decrypts the stored bytes.
+     */
+    async downloadAttachment(ref) {
+        const info = await this.getDownloadUrl(ref.attachmentId);
+        const resp = await this.deps.fetchFn(info.url, { method: info.method, headers: info.headers });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Failed to download attachment bytes (HTTP ${resp.status}): ${text}`);
+        }
+        const arrayBuf = await resp.arrayBuffer();
+        let stored = new Uint8Array(arrayBuf);
+        if (ref.encryptionType === 'CLEARTEXT') {
+            return { attachmentId: ref.attachmentId, mimeType: info.mimeType, sizeBytes: info.sizeBytes, sha256: info.sha256, bytes: stored };
+        }
+        const myDeviceId = await this.deps.getCurrentDeviceId();
+        const myWrapped = ref.wrappedKeys.find(wk => wk.deviceId === myDeviceId);
+        if (!myWrapped) {
+            throw new Error('No wrapped key for the current device on this attachment');
+        }
+        const fileKey = await this.unwrapKey(myWrapped);
+        // stored = fileNonce(12) || ciphertext
+        if (stored.length < 13) {
+            throw new Error('Encrypted attachment payload too short');
+        }
+        const fileNonce = stored.slice(0, 12);
+        const ciphertext = stored.slice(12);
+        const aesKey = await crypto.subtle.importKey('raw', asBufferSource(fileKey), { name: 'AES-GCM' }, false, ['decrypt']);
+        const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: asBufferSource(fileNonce), tagLength: 128 }, aesKey, asBufferSource(ciphertext));
+        return {
+            attachmentId: ref.attachmentId,
+            mimeType: info.mimeType,
+            sizeBytes: info.sizeBytes,
+            sha256: info.sha256,
+            bytes: new Uint8Array(plain),
+        };
+    }
+    /** Convert public AttachmentRef into the wire-format type for proto encoding. */
+    toWire(ref) {
+        return {
+            attachmentId: ref.attachmentId,
+            storageHint: ref.storageHint,
+            mimeType: ref.mimeType,
+            sizeBytes: ref.sizeBytes,
+            sha256: ref.sha256,
+            encryptionType: ref.encryptionType === 'CLEARTEXT' ? 1 : 0,
+            wrappedKeys: ref.wrappedKeys.map(wk => ({
+                deviceId: wk.deviceId,
+                wrappedKey: wk.wrappedKey,
+                senderPublicKey: wk.senderPublicKey,
+                nonce: wk.nonce,
+            })),
+        };
+    }
+    /** Convert a wire AttachmentRef (from a received message) into the public type. */
+    static fromWire(wire) {
+        return {
+            attachmentId: wire.attachmentId,
+            storageHint: wire.storageHint,
+            mimeType: wire.mimeType,
+            sizeBytes: Number(wire.sizeBytes),
+            sha256: wire.sha256,
+            encryptionType: wire.encryptionType === 1 ? 'CLEARTEXT' : 'E2EE',
+            wrappedKeys: (wire.wrappedKeys ?? []).map((wk) => ({
+                deviceId: wk.deviceId,
+                wrappedKey: new Uint8Array(wk.wrappedKey),
+                senderPublicKey: new Uint8Array(wk.senderPublicKey),
+                nonce: new Uint8Array(wk.nonce),
+            })),
+        };
+    }
+    // ─── internals ───
+    async uploadBytes(session, bytes, onProgress) {
+        const resp = await this.deps.fetchFn(session.uploadUrl, {
+            method: session.uploadMethod || 'PUT',
+            headers: session.uploadHeaders,
+            body: asBufferSource(bytes),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Storage upload failed (HTTP ${resp.status}): ${text.slice(0, 400)}`);
+        }
+        // fetch does not surface upload-progress; report the final byte count.
+        if (onProgress) {
+            onProgress(bytes.length, bytes.length);
+        }
+    }
+    async wrapKeyForRecipients(fileKey, opts) {
+        const currentUserId = this.deps.getCurrentUserId();
+        const myDeviceId = await this.deps.getCurrentDeviceId();
+        const myIdentity = await this.deps.cryptoService.getOrCreateIdentity();
+        const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);
+        const myPrivBase64 = await this.deps.getKeyStorage().get(STORAGE_PRIVATE);
+        if (!myPrivBase64) {
+            throw new Error('Local identity keypair is missing; cannot wrap attachment key');
+        }
+        const myPriv = (0, bytes_1.fromBase64)(myPrivBase64);
+        // Resolve target devices: recipients' devices + sender's other devices.
+        const recipientUserIds = opts.recipientUserIds ?? (opts.toUserId ? [opts.toUserId] : []);
+        const seenDeviceIds = new Set();
+        const targets = [];
+        for (const uid of recipientUserIds) {
+            const keys = await this.deps.fetchDeviceKeys(uid);
+            for (const k of keys) {
+                if (seenDeviceIds.has(k.deviceId))
+                    continue;
+                seenDeviceIds.add(k.deviceId);
+                targets.push({ deviceId: k.deviceId, publicKey: k.publicKey });
+            }
+        }
+        const myOther = await this.deps.fetchMyOtherDeviceKeys(myDeviceId);
+        for (const k of myOther) {
+            if (seenDeviceIds.has(k.deviceId))
+                continue;
+            seenDeviceIds.add(k.deviceId);
+            targets.push({ deviceId: k.deviceId, publicKey: k.publicKey });
+        }
+        const wrapped = [];
+        for (const target of targets) {
+            const peerPub = (0, bytes_1.fromBase64)(target.publicKey);
+            if (peerPub.length !== 32) {
+                this.deps.logError('attachment_invalid_peer_pubkey', { deviceId: target.deviceId, len: peerPub.length });
+                continue;
+            }
+            const shared = tweetnacl_1.default.scalarMult(myPriv, peerPub);
+            const aesKey = await this.deriveAttachmentWrapKey(shared);
+            const nonce = (0, bytes_1.randomBytes)(12);
+            const cipherBuf = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: asBufferSource(nonce), tagLength: 128 }, aesKey, asBufferSource(fileKey));
+            wrapped.push({
+                deviceId: target.deviceId,
+                wrappedKey: new Uint8Array(cipherBuf),
+                senderPublicKey: myPublicKeyBytes,
+                nonce,
+            });
+        }
+        return wrapped;
+    }
+    async unwrapKey(wrapped) {
+        const privBase64 = await this.deps.getKeyStorage().get(STORAGE_PRIVATE);
+        if (!privBase64) {
+            throw new Error('Local identity keypair is missing; cannot unwrap attachment key');
+        }
+        const myPriv = (0, bytes_1.fromBase64)(privBase64);
+        if (myPriv.length !== 32 || wrapped.senderPublicKey.length !== 32) {
+            throw new Error('Invalid X25519 key length on wrapped attachment key');
+        }
+        const shared = tweetnacl_1.default.scalarMult(myPriv, wrapped.senderPublicKey);
+        const aesKey = await this.deriveAttachmentWrapKey(shared);
+        const plainBuf = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: asBufferSource(wrapped.nonce), tagLength: 128 }, aesKey, asBufferSource(wrapped.wrappedKey));
+        const plain = new Uint8Array(plainBuf);
+        if (plain.length !== 32) {
+            throw new Error(`unwrapped attachment key has unexpected length ${plain.length}`);
+        }
+        return plain;
+    }
+    /**
+     * HKDF for the attachment file-key wrap. Sender and recipient both compute
+     * the same X25519 shared secret (by symmetry of curve25519) and derive the
+     * same AES-GCM key via this HKDF. Distinct info/salt from the message-payload
+     * HKDF in CryptoService to avoid key reuse across protocols.
+     */
+    async deriveAttachmentWrapKey(sharedSecret) {
+        const info = (0, bytes_1.utf8Encode)('droponair-attachment-key-wrap-v1');
+        const salt = (0, bytes_1.utf8Encode)('droponair-attachment-hkdf-salt-v1');
+        const ikm = await crypto.subtle.importKey('raw', asBufferSource(sharedSecret), 'HKDF', false, ['deriveKey']);
+        return crypto.subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: asBufferSource(salt), info: asBufferSource(info) }, ikm, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    }
+}
+exports.AttachmentClient = AttachmentClient;

package/dist/attachment/attachment-types.d.ts

@@ -0,0 +1,77 @@
+/** Encryption mode for an attachment. */
+export type AttachmentEncryptionType = 'E2EE' | 'CLEARTEXT';
+/** Conversation scope used for download authorization on the server side. */
+export type AttachmentConversationType = 'ONE_TO_ONE' | 'GROUP';
+/**
+ * Per-device wrapped AES-256-GCM file key for an E2EE attachment.
+ * The wrapped bytes decrypt to a 32-byte raw AES key that decrypts the file.
+ */
+export interface DeviceWrappedKey {
+    deviceId: string;
+    wrappedKey: Uint8Array;
+    senderPublicKey: Uint8Array;
+    nonce: Uint8Array;
+}
+/**
+ * Reference to an attachment hosted in the customer's storage bucket,
+ * carried inside Envelope.attachments. After the SDK uploads the bytes
+ * and finalizes, this is the structure the sender embeds in the message.
+ */
+export interface AttachmentRef {
+    attachmentId: string;
+    storageHint: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Hex-encoded SHA-256 of stored bytes (ciphertext for E2EE, plaintext for CLEARTEXT). */
+    sha256: string;
+    encryptionType: AttachmentEncryptionType;
+    /** Empty for CLEARTEXT. One entry per recipient device for E2EE. */
+    wrappedKeys: DeviceWrappedKey[];
+}
+/** Optional metadata for {@link DropOnAirClient.createUploadSession}. */
+export interface CreateUploadSessionOptions {
+    mimeType?: string;
+    sizeBytes: number;
+    encryptionType?: AttachmentEncryptionType;
+    conversationType?: AttachmentConversationType;
+    /** For GROUP conversations: the groupId. For ONE_TO_ONE: omit. */
+    conversationId?: string;
+    /** Recipient user IDs (used by the server for download authorization). */
+    recipientUserIds?: string[];
+}
+/** Result of reserving an upload session. */
+export interface UploadSession {
+    attachmentId: string;
+    storageHint: string;
+    uploadUrl: string;
+    uploadMethod: string;
+    uploadHeaders: Record<string, string>;
+    expiresAt: string;
+}
+/** Options for the convenience method {@link DropOnAirClient.prepareAttachmentAndUpload}. */
+export interface PrepareAttachmentOptions {
+    /** Recipient user ID for ONE_TO_ONE conversations. */
+    toUserId?: string;
+    /** Group ID for GROUP conversations. Mutually exclusive with toUserId. */
+    groupId?: string;
+    /**
+     * Roster of recipient user IDs the server should authorize for download.
+     * For ONE_TO_ONE: defaults to {@code [toUserId]} if omitted.
+     * For GROUP: required - the SDK does not infer group membership.
+     */
+    recipientUserIds?: string[];
+    /** Defaults to {@code 'E2EE'}. Use {@code 'CLEARTEXT'} for public/unencrypted content. */
+    encryptionType?: AttachmentEncryptionType;
+    /** Override the mime type detected from the File object. */
+    mimeType?: string;
+    /** Progress callback called with bytes uploaded so far. */
+    onUploadProgress?: (bytesUploaded: number, totalBytes: number) => void;
+}
+/** Bytes payload returned by downloadAttachment. */
+export interface DownloadedAttachment {
+    attachmentId: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    bytes: Uint8Array;
+}

package/dist/attachment/attachment-types.js

@@ -0,0 +1,11 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Attachment types (PROTOCOL_VERSION 4+)
+//
+// DropOnAir never holds file bytes. The SDK uploads/downloads directly
+// against the customer's storage bucket via short-lived presigned URLs
+// minted by sdk-be. For E2EE messages a per-attachment AES-256-GCM file
+// key is wrapped per recipient device using the same X25519 + HKDF path
+// used for message payloads.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,6 +1,7 @@
 import { CryptoService } from '../crypto/crypto-service';
 import { SessionManager } from './session-manager';
 import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, GroupCallEventCallback, GroupInfo, GroupMessageCallback, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials } from './types';
+import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
     private readonly cryptoService;
@@ -12,6 +13,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly keyDirectoryEndpoint;
     private readonly fetchFn;
     private readonly codec;
+    private attachmentClient;
     private ws;
     private shouldReconnect;
     private reconnectTimer;
@@ -84,9 +86,15 @@ export declare class MessagingClient implements DropOnAirClient {
     /** Redact a JWT to keep subject + expiry visible while hiding the signature. */
     private jwtSummary;
     constructor(options: InitializeOptions, cryptoService: CryptoService, sessionManager: SessionManager, storage: import('./types').KeyStorageAdapter);
+    prepareAttachmentAndUpload(bytes: Uint8Array, options: PrepareAttachmentOptions): Promise<AttachmentRef>;
+    createUploadSession(options: CreateUploadSessionOptions): Promise<UploadSession>;
+    finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
+    downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
     connect(): Promise<void>;
     disconnect(): void;
-    sendMessage(toUserId: string, plaintextMessage: string): Promise<{
+    sendMessage(toUserId: string, plaintextMessage: string, options?: {
+        attachments?: AttachmentRef[];
+    }): Promise<{
         messageId: string;
     }>;
     ack(messageId: string): Promise<void>;
@@ -128,6 +136,8 @@ export declare class MessagingClient implements DropOnAirClient {
     leaveGroupCall(callId: string): Promise<void>;
     endGroupCall(callId: string): Promise<void>;
     sendGroupCallSignal(type: 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE', callId: string, groupId: string, targetUserId: string, payload: string): void;
+    startGroupScreenShare(callId: string, groupId: string, payload?: string): void;
+    stopGroupScreenShare(callId: string, groupId: string, payload?: string): void;
     onGroupCallEvent(callback: GroupCallEventCallback): () => void;
     private sendGroupCallFrame;
     /**
@@ -141,6 +151,8 @@ export declare class MessagingClient implements DropOnAirClient {
     endCall(callId: string): Promise<void>;
     toggleVideo(callId: string, enabled: boolean): void;
     sendCallSignal(type: 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE', callId: string, payload: string): void;
+    startScreenShare(callId: string, payload?: string): void;
+    stopScreenShare(callId: string, payload?: string): void;
     fetchTurnCredentials(): Promise<TurnCredentials>;
     private sendCallFrame;
     private emitCallEvent;

package/dist/core/messaging-client.js

@@ -4,6 +4,7 @@ exports.MessagingClient = void 0;
 const bytes_1 = require("./bytes");
 const protobuf_codec_1 = require("../transport/protobuf-codec");
 const version_1 = require("../version");
+const attachment_client_1 = require("../attachment/attachment-client");
 const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
 class MessagingClient {
     reconnectDelayMs() {
@@ -235,6 +236,36 @@ class MessagingClient {
             return resolvedFetch.call(fetchContext, input, init);
         });
         this.autoAckIncomingMessages = options.autoAckIncomingMessages !== false;
+        this.attachmentClient = new attachment_client_1.AttachmentClient({
+            httpUrl: this.httpUrl,
+            fetchFn: this.fetchFn,
+            getValidDropOnAirJwt: () => this.getValidDropOnAirJwt(false),
+            fetchDeviceKeys: (userId) => this.fetchDeviceKeys(userId),
+            fetchMyOtherDeviceKeys: (myDeviceId) => this.fetchMyOtherDeviceKeys(myDeviceId),
+            getCurrentUserId: () => {
+                if (!this.currentUserId)
+                    throw new Error('Not connected; userId unknown');
+                return this.currentUserId;
+            },
+            getCurrentDeviceId: () => this.deviceId ? Promise.resolve(this.deviceId) : this.getOrCreateDeviceId(),
+            getKeyStorage: () => this.storage,
+            cryptoService: this.cryptoService,
+            log: (stage, data) => this.log(stage, data),
+            logError: (stage, data) => this.logError(stage, data),
+        });
+    }
+    // Attachment API (phase1/attachments, PROTOCOL_VERSION 4+)
+    async prepareAttachmentAndUpload(bytes, options) {
+        return this.attachmentClient.prepareAttachmentAndUpload(bytes, options);
+    }
+    async createUploadSession(options) {
+        return this.attachmentClient.createUploadSession(options);
+    }
+    async finalizeAttachment(attachmentId, sha256) {
+        return this.attachmentClient.finalize(attachmentId, sha256);
+    }
+    async downloadAttachment(ref) {
+        return this.attachmentClient.downloadAttachment(ref);
     }
     async connect() {
         this.log('connect_start');
@@ -267,7 +298,7 @@ class MessagingClient {
         }
         this.emitEvent({ type: 'DISCONNECTED' });
     }
-    async sendMessage(toUserId, plaintextMessage) {
+    async sendMessage(toUserId, plaintextMessage, options) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new Error('DropOnAir websocket is not connected');
         }
@@ -327,6 +358,9 @@ class MessagingClient {
                 devicePayloads,
                 senderDeviceId: myDeviceId,
             };
+            if (options?.attachments && options.attachments.length > 0) {
+                envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
+            }
             this.ws.send(this.codec.encodeEnvelope(envelope));
         }
         else {
@@ -347,6 +381,9 @@ class MessagingClient {
                 encryptedPayload,
                 clientMessageId: messageId
             };
+            if (options?.attachments && options.attachments.length > 0) {
+                envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
+            }
             this.ws.send(this.codec.encodeEnvelope(envelope));
         }
         return { messageId };
@@ -703,6 +740,24 @@ class MessagingClient {
     sendGroupCallSignal(type, callId, groupId, targetUserId, payload) {
         this.sendGroupCallFrame({ type, callId, groupId, targetUserId, payload });
     }
+    startGroupScreenShare(callId, groupId, payload) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_SCREEN_SHARE_STARTED',
+            callId,
+            groupId,
+            targetUserId: '',
+            payload: payload ?? '',
+        });
+    }
+    stopGroupScreenShare(callId, groupId, payload) {
+        this.sendGroupCallFrame({
+            type: 'GROUP_CALL_SCREEN_SHARE_STOPPED',
+            callId,
+            groupId,
+            targetUserId: '',
+            payload: payload ?? '',
+        });
+    }
     onGroupCallEvent(callback) {
         this.groupCallListeners.add(callback);
         return () => this.groupCallListeners.delete(callback);
@@ -744,6 +799,12 @@ class MessagingClient {
     sendCallSignal(type, callId, payload) {
         this.sendCallFrame({ type, callId, payload });
     }
+    startScreenShare(callId, payload) {
+        this.sendCallFrame({ type: 'CALL_SCREEN_SHARE_STARTED', callId, payload: payload ?? '' });
+    }
+    stopScreenShare(callId, payload) {
+        this.sendCallFrame({ type: 'CALL_SCREEN_SHARE_STOPPED', callId, payload: payload ?? '' });
+    }
     async fetchTurnCredentials() {
         const jwt = await this.getValidDropOnAirJwt(false);
         const url = `${this.httpUrl}/api/v1/turn/credentials`;
@@ -1191,15 +1252,20 @@ class MessagingClient {
                     timestamp: envelope.timestamp
                 });
             }
+            const attachments = envelope.attachments && envelope.attachments.length > 0
+                ? envelope.attachments.map(w => attachment_client_1.AttachmentClient.fromWire(w))
+                : undefined;
             this.emitMessage({
                 messageId: envelope.messageId,
                 fromUserId: envelope.fromUserId,
                 toUserId: envelope.toUserId,
                 timestamp: envelope.timestamp,
-                plaintext
+                plaintext,
+                attachments,
             });
             this.log('incoming_envelope_emitted', {
                 messageId: envelope.messageId,
+                attachmentCount: attachments?.length ?? 0,
             });
             if (this.autoAckIncomingMessages) {
                 await this.ack(envelope.messageId);

package/dist/core/types.d.ts

@@ -10,6 +10,12 @@ export interface DecryptedMessage {
     toUserId: string;
     timestamp: number;
     plaintext: string;
+    /**
+     * Attachment pointers (phase1/attachments, PROTOCOL_VERSION 4+).
+     * Empty/undefined for messages with no attachments. To fetch and decrypt the
+     * bytes, call {@code client.downloadAttachment(ref)}.
+     */
+    attachments?: import('../attachment/attachment-types').AttachmentRef[];
 }
 export type MessageCallback = (message: DecryptedMessage) => void;
 export type EventCallback = (event: DropOnAirEvent) => void;
@@ -51,7 +57,7 @@ export interface BroadcastMessage {
     sequenceNumber: number;
 }
 export type BroadcastCallback = (message: BroadcastMessage) => void;
-export type CallEventType = 'CALL_INVITE' | 'CALL_RINGING' | 'CALL_ACCEPTED' | 'CALL_REJECTED' | 'CALL_ENDED' | 'CALL_CANCELLED' | 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE' | 'CALL_VIDEO_TOGGLE' | 'CALL_DENIED_LIMIT_REACHED';
+export type CallEventType = 'CALL_INVITE' | 'CALL_RINGING' | 'CALL_ACCEPTED' | 'CALL_REJECTED' | 'CALL_ENDED' | 'CALL_CANCELLED' | 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE' | 'CALL_VIDEO_TOGGLE' | 'CALL_SCREEN_SHARE_STARTED' | 'CALL_SCREEN_SHARE_STOPPED' | 'CALL_DENIED_LIMIT_REACHED';
 export interface CallEvent {
     type: CallEventType | string;
     callId?: string;
@@ -86,7 +92,7 @@ export interface DecryptedGroupMessage {
     plaintext: string;
 }
 export type GroupMessageCallback = (message: DecryptedGroupMessage) => void;
-export type GroupCallEventType = 'GROUP_CALL_INVITE' | 'GROUP_CALL_RINGING' | 'GROUP_CALL_JOIN' | 'GROUP_CALL_LEAVE' | 'GROUP_CALL_END' | 'GROUP_CALL_ENDED' | 'GROUP_CALL_PARTICIPANT_JOINED' | 'GROUP_CALL_PARTICIPANT_LEFT' | 'GROUP_CALL_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE';
+export type GroupCallEventType = 'GROUP_CALL_INVITE' | 'GROUP_CALL_RINGING' | 'GROUP_CALL_JOIN' | 'GROUP_CALL_LEAVE' | 'GROUP_CALL_END' | 'GROUP_CALL_ENDED' | 'GROUP_CALL_PARTICIPANT_JOINED' | 'GROUP_CALL_PARTICIPANT_LEFT' | 'GROUP_CALL_ALREADY_ACTIVE' | 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE' | 'GROUP_CALL_SCREEN_SHARE_STARTED' | 'GROUP_CALL_SCREEN_SHARE_STOPPED';
 export interface GroupCallEvent {
     type: GroupCallEventType | string;
     callId: string;
@@ -129,7 +135,13 @@ export interface InitializeOptions {
 export interface DropOnAirClient {
     connect(): Promise<void>;
     disconnect(): void;
-    sendMessage(toUserId: string, plaintextMessage: string): Promise<{
+    /**
+     * Send a 1:1 E2EE message. Optionally attach one or more attachments
+     * prepared via {@link prepareAttachmentAndUpload} or {@link createUploadSession}.
+     */
+    sendMessage(toUserId: string, plaintextMessage: string, options?: {
+        attachments?: import('../attachment/attachment-types').AttachmentRef[];
+    }): Promise<{
         messageId: string;
     }>;
     onMessage(callback: MessageCallback): () => void;
@@ -158,6 +170,18 @@ export interface DropOnAirClient {
     onMessageEdit(callback: MessageEditCallback): () => void;
     /** Register a listener for incoming message-delete notifications. */
     onMessageDelete(callback: MessageDeleteCallback): () => void;
+    /**
+     * Convenience: encrypts (E2EE), uploads to the customer's bucket, finalizes,
+     * and returns an AttachmentRef ready to pass into {@link sendMessage}.
+     * For CLEARTEXT, bytes are uploaded unencrypted.
+     */
+    prepareAttachmentAndUpload(bytes: Uint8Array, options: import('../attachment/attachment-types').PrepareAttachmentOptions): Promise<import('../attachment/attachment-types').AttachmentRef>;
+    /** Low-level: reserve an upload session (presigned URL) without uploading. */
+    createUploadSession(options: import('../attachment/attachment-types').CreateUploadSessionOptions): Promise<import('../attachment/attachment-types').UploadSession>;
+    /** Low-level: finalize an upload, committing the integrity hash. */
+    finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
+    /** Download (and for E2EE decrypt) an attachment referenced inside a received message. */
+    downloadAttachment(ref: import('../attachment/attachment-types').AttachmentRef): Promise<import('../attachment/attachment-types').DownloadedAttachment>;
     /** Send a cleartext message to a user (no encryption). */
     sendCleartextMessage(toUserId: string, plaintext: string): Promise<{
         messageId: string;
@@ -188,6 +212,16 @@ export interface DropOnAirClient {
      * The payload is forwarded opaquely, the server does NOT inspect or store it.
      */
     sendCallSignal(type: 'CALL_SDP_OFFER' | 'CALL_SDP_ANSWER' | 'CALL_ICE_CANDIDATE', callId: string, payload: string): void;
+    /**
+     * Signal that this user started sharing their screen in a 1:1 call
+     * (phase1/screen-sharing, PROTOCOL_VERSION 4+). The actual screen MediaStreamTrack
+     * is added to the existing peer connection by the application; the SDK only
+     * broadcasts the start/stop notification so the remote SDK can update its UI.
+     * Optional `payload` (JSON string) can carry track-id or app-specific metadata.
+     */
+    startScreenShare(callId: string, payload?: string): void;
+    /** Signal that this user stopped sharing their screen in a 1:1 call. */
+    stopScreenShare(callId: string, payload?: string): void;
     /** Register a listener for all incoming call events. Returns an unsubscribe function. */
     onCallEvent(callback: CallEventCallback): () => void;
     /** Fetch short-lived TURN credentials for ICE negotiation. */
@@ -220,6 +254,16 @@ export interface DropOnAirClient {
     endGroupCall(callId: string): Promise<void>;
     /** Send a signaling frame to a specific peer in a group call. */
     sendGroupCallSignal(type: 'GROUP_CALL_SDP_OFFER' | 'GROUP_CALL_SDP_ANSWER' | 'GROUP_CALL_ICE_CANDIDATE', callId: string, groupId: string, targetUserId: string, payload: string): void;
+    /**
+     * Signal that this user started sharing their screen in a group call.
+     * The server enforces one concurrent sharer per group call; if another
+     * participant already holds the slot, the SDK will receive a
+     * `GROUP_CALL_SCREEN_SHARE_STOPPED` event echoing the current holder's
+     * userId in `payload` so the app can roll back its optimistic UI.
+     */
+    startGroupScreenShare(callId: string, groupId: string, payload?: string): void;
+    /** Signal that this user stopped sharing their screen in a group call. */
+    stopGroupScreenShare(callId: string, groupId: string, payload?: string): void;
     /** Register a listener for group call events. Returns an unsubscribe function. */
     onGroupCallEvent(callback: GroupCallEventCallback): () => void;
 }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { InitializeOptions, DropOnAirClient } from './core/types';
 export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version';
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
 export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, } from './core/types';
+export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 declare const _default: {
     initialize: typeof initialize;
 };

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

@@ -4,6 +4,23 @@ export interface WireDeviceEncryptedPayload {
     encryptedPayload: Uint8Array;
     senderPublicKey: Uint8Array;
 }
+/** Per-device wrapped AES-256-GCM file key for E2EE attachments. */
+export interface WireDeviceWrappedKey {
+    deviceId: string;
+    wrappedKey: Uint8Array;
+    senderPublicKey: Uint8Array;
+    nonce: Uint8Array;
+}
+/** Pointer to an attachment in the customer's storage bucket. */
+export interface WireAttachmentRef {
+    attachmentId: string;
+    storageHint: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    encryptionType: number;
+    wrappedKeys?: WireDeviceWrappedKey[];
+}
 export interface WireEnvelope {
     messageId: string;
     appId: string;
@@ -20,6 +37,8 @@ export interface WireEnvelope {
     encryptionType?: number;
     /** Populated only when encryptionType = CLEARTEXT. */
     plaintextPayload?: string;
+    /** Zero or more attachment pointers (PROTOCOL_VERSION 4+). */
+    attachments?: WireAttachmentRef[];
 }
 export interface WireAck {
     messageId: string;

package/dist/transport/protobuf-codec.js

@@ -42,9 +42,28 @@ 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'));
+// Per-device wrapped file key for E2EE attachments (PROTOCOL_VERSION 4+)
+const DeviceWrappedKeyType = new protobuf.Type('DeviceWrappedKey')
+    .add(new protobuf.Field('deviceId', 1, 'string'))
+    .add(new protobuf.Field('wrappedKey', 2, 'bytes'))
+    .add(new protobuf.Field('senderPublicKey', 3, 'bytes'))
+    .add(new protobuf.Field('nonce', 4, 'bytes'));
+// Reference to an out-of-band attachment in customer-managed storage.
+const AttachmentRefEncTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
+const AttachmentRefType = new protobuf.Type('AttachmentRef')
+    .add(AttachmentRefEncTypeEnum)
+    .add(DeviceWrappedKeyType)
+    .add(new protobuf.Field('attachmentId', 1, 'string'))
+    .add(new protobuf.Field('storageHint', 2, 'string'))
+    .add(new protobuf.Field('mimeType', 3, 'string'))
+    .add(new protobuf.Field('sizeBytes', 4, 'int64'))
+    .add(new protobuf.Field('sha256', 5, 'string'))
+    .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
+    .add(new protobuf.Field('wrappedKeys', 7, 'DeviceWrappedKey', 'repeated'));
 const EnvelopeType = new protobuf.Type('Envelope')
     .add(EncryptionTypeEnum)
     .add(DeviceEncryptedPayloadType) // nested type must be added first
+    .add(AttachmentRefType)
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('appId', 2, 'string'))
     .add(new protobuf.Field('fromUserId', 3, 'string'))
@@ -55,7 +74,8 @@ const EnvelopeType = new protobuf.Type('Envelope')
     .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'));
+    .add(new protobuf.Field('plaintextPayload', 11, 'string'))
+    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'));
 const AckType = new protobuf.Type('Ack')
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('type', 2, 'string'));
@@ -104,6 +124,9 @@ 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)
@@ -289,6 +312,23 @@ class ProtobufCodec {
                     senderPublicKey: new Uint8Array(dp.senderPublicKey),
                 }));
             }
+            // Normalize attachments (PROTOCOL_VERSION 4+)
+            if (decoded.attachments && decoded.attachments.length > 0) {
+                result.attachments = decoded.attachments.map(att => ({
+                    attachmentId: att.attachmentId,
+                    storageHint: att.storageHint,
+                    mimeType: att.mimeType,
+                    sizeBytes: Number(att.sizeBytes),
+                    sha256: att.sha256,
+                    encryptionType: att.encryptionType ?? 0,
+                    wrappedKeys: att.wrappedKeys?.map(wk => ({
+                        deviceId: wk.deviceId,
+                        wrappedKey: new Uint8Array(wk.wrappedKey),
+                        senderPublicKey: new Uint8Array(wk.senderPublicKey),
+                        nonce: new Uint8Array(wk.nonce),
+                    })) ?? [],
+                }));
+            }
             return result;
         }
         catch {

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.4.0";
+export declare const SDK_VERSION = "0.6.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can
@@ -19,4 +19,4 @@ export declare const PAYLOAD_FORMAT_VERSION = 1;
  * 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 = 3;
+export declare const PROTOCOL_VERSION = 4;

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.4.0';
+exports.SDK_VERSION = '0.6.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can
@@ -22,4 +22,4 @@ exports.PAYLOAD_FORMAT_VERSION = 1;
  * Increment when adding required proto fields or changing frame semantics.
  * The server advertises its supported range via GET /api/info.
  */
-exports.PROTOCOL_VERSION = 3;
+exports.PROTOCOL_VERSION = 4;

package/package.json

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