@droponair/sdk-js 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,48 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+- **Message edit (E2EE + cleartext):** `editMessage(originalMessageId, toUserId, newText)` and `editCleartextMessage(originalMessageId, toUserId, newText)`. Edits are re-encrypted per-device with the same shared key as the original message; the server stores them as immutable separate records and forwards opaquely.
+- **Message delete:** `deleteMessage(originalMessageId, toUserId, scope)` with `scope` of `"FOR_EVERYONE"` (recipient receives tombstone, cleartext plaintext is also wiped server-side) or `"FOR_ME"` (only sender's other devices receive the tombstone).
+- **New event types:** `MessageEditEvent` and `MessageDeleteEvent` with `onMessageEdit()` / `onMessageDelete()` listeners.
+- **Offline catch-up:** Pending edits and tombstones are now replayed alongside offline messages when the client reconnects (`pendingEdits` and `pendingTombstones` returned by `/api/messages/offline`).
+- **PROTOCOL_VERSION = 3** and `features` now advertises `message_edit` + `message_delete` from `GET /api/info`.
+
+### Notes
+- Each edit and each `FOR_EVERYONE` delete counts as **one** MESSAGE usage record (subject to plan quotas + rate limits).
+- Wire-level additive: legacy 0.3.x clients ignore unknown frame types (proto3 forwards-compat), so existing TwinFlame and CrowdSyncer apps continue to work unchanged.
+- Requires sdk-be `0.4.0` server.
+
+---
+
+## [0.3.1], 2026-04-19
+
+### Changed
+- Patch version bump for npm publish alignment
+
+---
+
 ## [0.3.0], 2026-04-04
 
 ### 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 |

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 });