@droponair/sdk-js 0.24.3 → 0.25.1

package/CHANGELOG.md

@@ -1,12 +1,65 @@
 # Changelog
 
+## 0.25.1
+
+### Changed
+
+- Documentation only, no behaviour or API change. Comments and notes that shipped in the
+  package described the platform's own internals rather than the integration surface: some
+  named components a consumer never talks to, and some carried planning tags that mean nothing
+  outside our own backlog. They are rewritten in terms of what the code does and what the
+  platform offers.
+- Where availability used to be described as a specific plan flag, it now points at the pricing
+  page and the app's subscription, which are the two places that stay correct as plans change.
+- `PROTOCOL_VERSION` references are untouched. That is the contract a consumer integrates
+  against and it remains the way to tell what a relay supports.
+- Em dashes are gone from the shipped text, per the house style. Each was judged in place
+  rather than swapped mechanically, so clauses read as sentences rather than comma splices.
+
+## 0.25.0
+
+### Added
+
+- **`keyCustody` on the client**, reporting how the identity private key is held:
+  `'non-extractable'` when the key exists only inside the platform's crypto agent and cannot
+  be read by script, `'software'` when it is bytes the process can read. Every release before
+  this one behaved as `'software'`, and still does unless the new option below is used. Read it
+  rather than assuming: a consumer that believes it has the stronger custody and does not is
+  worse off than one that knows.
+- **`createSecureIdentity()`** and **`InitializeOptions.identity`**, an opt-in identity whose
+  private key script cannot read. The key is generated non-extractable and used through the
+  agent for the key agreement, so an attacker who runs script on the origin can ask it to
+  derive while the page is open, and cannot steal the key for later or elsewhere.
+- **`WebCryptoIdentityProvider`**, **`IndexedDbIdentityRecordStore`**,
+  **`MemoryIdentityRecordStore`** and the **`IdentityRecordStore`** interface are exported, so
+  custody can be implemented against something else entirely.
+
+### Notes
+
+- **Opt-in, and unchanged by default.** Passing no `identity` keeps exactly the previous
+  behaviour. The stronger path is offered, not imposed.
+- **`createSecureIdentity()` returns `null` where the platform cannot deliver it**, rather than
+  throwing or quietly substituting something weaker. Two conditions are checked: whether the
+  primitive exists, and whether a key survives being stored and read back.
+- **Availability differs by engine.** The protected path requires an X25519 key that persists.
+  Chromium provides that. WebKit generates and derives correctly and then loses the key when it
+  is stored, reporting the write as successful, so `createSecureIdentity()` returns `null`
+  there and the ordinary path is used. This is checked at runtime rather than assumed from a
+  user agent.
+- **Existing identities can be carried over** with `migrateFromKeyStorage()`, which imports the
+  stored key, verifies it, and only then removes the readable copy. The public key is unchanged,
+  so peers still address the same identity and existing conversations keep decrypting. Nothing
+  is re-keyed and no history is lost.
+- The wire format is untouched. Both paths perform the same X25519 agreement and derive the
+  same message key, which is covered by tests in both directions.
+
 ## 0.24.3
 
 - Fix: broadcasts (and events/acks) misrouted. Inbound Ack/GroupAck discriminators now require a real SCREAMING_SNAKE ack token, so a BroadcastNotification (publisherId in the type slot) is no longer decoded as a GroupAck before reaching the broadcast branch. Completes the frame-classifier fix.
 
 ## 0.24.2
 
-- Fix: E2EE group message decryption failed because the decrypt AAD bound `recipientId` to the group id instead of the receiving user's own id (which is what the sender encrypts against). Now matches the sender and the other SDKs. Requires sdk-be that preserves the sender timestamp on group notifications.
+- Fix: E2EE group message decryption failed because the decrypt AAD bound `recipientId` to the group id instead of the receiving user's own id (which is what the sender encrypts against). Now matches the sender and the other SDKs. Requires a relay that preserves the sender timestamp on group notifications.
 
 ## 0.24.1
 
@@ -184,7 +237,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
-- **`revokeAttachment` accepts an `AttachmentRef`.** Calling `revokeAttachment(ref)` now also revokes the linked preview thumbnail (`ref.thumbnailAttachmentId`) in the same call. `revokeAttachment(attachmentId)` with a plain id string is unchanged and revokes only that one attachment. Additive — no breaking change.
+- **`revokeAttachment` accepts an `AttachmentRef`.** Calling `revokeAttachment(ref)` now also revokes the linked preview thumbnail (`ref.thumbnailAttachmentId`) in the same call. `revokeAttachment(attachmentId)` with a plain id string is unchanged and revokes only that one attachment. Additive, so no breaking change.
 
 ---
 
@@ -193,13 +246,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Added
 
 - **Group read receipts.** When a group has `readReceiptsVisibleToGroup` enabled, a member's `markRead(messageId, groupId)` is fanned to every other member, not just the reader's own devices. The inbound `ReadReceiptEvent` now carries `fromUserId` so you know which member read the message. New `client.updateGroup(groupId, { name?, readReceiptsVisibleToGroup? })` controls the per-group flag (it is a group-level choice; off by default). Broadcasts stay own-device only by design.
-- **Attachment revoke.** New `client.revokeAttachment(attachmentId)` — the platform stops issuing download URLs for it and recipients with a live connection get an `ATTACHMENT_REVOKED` event via `onEvent` (metadata = attachmentId). Bytes already downloaded cannot be recalled.
-- **Attachment preview thumbnails.** `prepareAttachmentAndUpload` accepts an optional `thumbnail` (and `thumbnailMimeType`). Entirely optional — if provided, the SDK uploads it as a separate attachment encrypted the same way and links it via `AttachmentRef.thumbnailAttachmentId`; download it like any attachment. If omitted, there is simply no thumbnail.
+- **Attachment revoke.** New `client.revokeAttachment(attachmentId)`. The platform stops issuing download URLs for it and recipients with a live connection get an `ATTACHMENT_REVOKED` event via `onEvent` (metadata = attachmentId). Bytes already downloaded cannot be recalled.
+- **Attachment preview thumbnails.** `prepareAttachmentAndUpload` accepts an optional `thumbnail` (and `thumbnailMimeType`). Entirely optional: if provided, the SDK uploads it as a separate attachment encrypted the same way and links it via `AttachmentRef.thumbnailAttachmentId`; download it like any attachment. If omitted, there is simply no thumbnail.
 
 ### Notes
 
 - Download authorization for GROUP attachments is now checked against *current* group membership: a user removed from a group can no longer download its attachments even if they were a recipient at upload time.
-- No PROTOCOL_VERSION change — additive proto fields (`SyncFrame.fromUserId`, `AttachmentRef.thumbnailAttachmentId`) and an additive event type.
+- No PROTOCOL_VERSION change: additive proto fields (`SyncFrame.fromUserId`, `AttachmentRef.thumbnailAttachmentId`) and an additive event type.
 
 ---
 
@@ -207,14 +260,14 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Notification clear sync.** `client.clearNotification(conversationId)` tells the user's other devices a conversation's notifications were dismissed; `client.onNotificationCleared(cb)` listens for it. Always available (no opt-out) — it is plain own-device hygiene.
+- **Notification clear sync.** `client.clearNotification(conversationId)` tells the user's other devices a conversation's notifications were dismissed; `client.onNotificationCleared(cb)` listens for it. Always available (no opt-out), since it is plain own-device hygiene.
 - **Draft sync.** `client.syncDraft(conversationId, draftText)` pushes a conversation draft to the user's other devices; `client.onDraftSync(cb)` listens for it. **Opt-in:** the app owner enables it in the dashboard, and the draft text crosses the relay in cleartext (fanned out, never stored). When disabled the server drops the frame.
 - New exported types: `NotificationClearEvent` / `NotificationClearCallback`, `DraftSyncEvent` / `DraftSyncCallback`.
 
 ### Notes
 
 - Both ride the existing `SyncFrame` wire type (own-device fan-out only, never delivered to a different user). No PROTOCOL_VERSION change.
-- Your app decides when to call `clearNotification()` / `syncDraft()` — the platform never infers dismissal or tracks drafts.
+- Your app decides when to call `clearNotification()` / `syncDraft()`. The platform never infers dismissal or tracks drafts.
 
 ---
 
@@ -222,13 +275,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Cross-device read receipts.** New `client.markRead(messageId, conversationId?)` reports a message as read; the receipt is relayed to the user's *other* devices (never to the message's sender). New `client.onReadReceipt(callback)` listens for receipts reported by the user's other devices — use it to clear unread state your app maintains.
+- **Cross-device read receipts.** New `client.markRead(messageId, conversationId?)` reports a message as read; the receipt is relayed to the user's *other* devices (never to the message's sender). New `client.onReadReceipt(callback)` listens for receipts reported by the user's other devices. Use it to clear unread state your app maintains.
 - New exported `ReadReceiptEvent` type and `ReadReceiptCallback`.
 - **PROTOCOL_VERSION bumped to 6.** Additive only: new `SyncFrame` wire type. Existing 0.10.x clients keep working against the new server.
 
 ### Notes
 
-- The platform is deliberately unopinionated: **your app decides when `markRead()` is called** — the server never infers read state, and unread counts stay client-side. The app owner can disable read receipts entirely from the dashboard, in which case the server silently drops the frame.
+- The platform is deliberately unopinionated: **your app decides when `markRead()` is called**. The server never infers read state, and unread counts stay client-side. The app owner can disable read receipts entirely from the dashboard, in which case the server silently drops the frame.
 - This release is own-device sync only: the *sender* of a message is not told when a recipient read it. Sender-side read notifications are a separate future capability.
 
 ---
@@ -237,7 +290,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Device trust.** New `client.listMyDevices()` returns the current user's registered devices; `client.revokeMyDevice(deviceId)` revokes one of them. A revoked device's live session is closed immediately and all future connections from it are denied (revoke is permanent — re-registering yields a fresh deviceId).
+- **Device trust.** New `client.listMyDevices()` returns the current user's registered devices; `client.revokeMyDevice(deviceId)` revokes one of them. A revoked device's live session is closed immediately and all future connections from it are denied (revoke is permanent, and re-registering yields a fresh deviceId).
 - **`DEVICE_REVOKED` event.** When this device is revoked (from another of the user's devices, or by the app owner), the SDK stops its reconnect loop, closes the socket, and surfaces a `DEVICE_REVOKED` event through `onEvent` so the app can clear local key storage and show a re-register prompt.
 - New exported `DeviceInfo` type.
 
@@ -289,7 +342,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Notes
 
 - Wire protocol unchanged (PROTOCOL_VERSION stays 4). The proto schema was already correct; only the JS hand-rolled codec was out of sync.
-- `protoFieldNumbers` for the group types are now documented in `droponair-sdk-shared/test-vectors/protobuf-vectors.json` for cross-platform reference.
+- `protoFieldNumbers` for the group types are now documented alongside the shared protocol test vectors, for cross-platform reference.
 
 ---
 
@@ -358,9 +411,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `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).
+- Availability depends on the app's plan; see the pricing page or the app's
+  subscription in the dashboard.
 
 ---
 

package/README.md

@@ -107,9 +107,54 @@ const client = await initialize(options);
 | `syncDraft(conversationId, draftText)` | `void` | Push a conversation draft to the user's other devices (opt-in, cleartext). |
 | `onDraftSync(callback)` | `() => void` | Listen for draft syncs from the user's other devices. |
 
+### Key custody
+
+Every client reports how it is holding the identity private key:
+
+```ts
+const client = await initialize({ /* ... */ });
+console.log(client.keyCustody); // 'software' | 'non-extractable'
+```
+
+`'software'` means the key is bytes the process can read. That is what every release before
+0.25.0 did, and what this one still does unless you opt in below.
+
+`'non-extractable'` means the key exists only inside the browser's crypto agent: your code can
+ask it to derive a shared secret, and cannot read the key itself. Script that runs on your
+origin can therefore use the identity while the page is open, and cannot copy it and decrypt
+elsewhere or later.
+
+Opt in by supplying an identity:
+
+```ts
+import { initialize, createSecureIdentity } from '@droponair/sdk-js';
+
+const identity = await createSecureIdentity();
+if (identity) {
+  // Optional, once: carry an existing key over so the identity and its history survive.
+  await identity.migrateFromKeyStorage(myStorage);
+}
+
+const client = await initialize({
+  appId, publicApiKey, getUserJwt,
+  identity: identity ?? undefined,   // null means this browser cannot provide it
+});
+```
+
+`createSecureIdentity()` returns `null` where the platform cannot deliver the guarantee, rather
+than throwing or quietly giving you something weaker. It checks two things: whether the
+primitive exists, and whether a key survives being stored and read back. That second check
+matters, because one major engine generates and derives with the key correctly and then loses
+it on write while reporting success. Read `client.keyCustody` afterwards to see what you
+actually got.
+
+Migration is yours to trigger, not automatic, because it removes the readable copy of the key.
+It imports the existing key, verifies it, and only then deletes the original. The public key is
+unchanged, so peers still address the same identity and existing conversations keep decrypting.
+
 ### Cross-device read receipts
 
-Available since SDK `0.11.0`. **Your app decides when a message is read** — the platform never infers it. Call `markRead()` at that moment; the receipt syncs to the user's *other* devices so they can clear their unread UI. It is not sent to the message's sender. The app owner can switch read receipts off entirely from the dashboard.
+Available since SDK `0.11.0`. **Your app decides when a message is read**, and the platform never infers it. Call `markRead()` at that moment; the receipt syncs to the user's *other* devices so they can clear their unread UI. It is not sent to the message's sender. The app owner can switch read receipts off entirely from the dashboard.
 
 ```typescript
 // When your UI decides the message has been read
@@ -117,11 +162,11 @@ client.markRead(messageId, peerUserId);
 
 // On the user's other devices
 client.onReadReceipt(e => {
-  // e.messageId was read elsewhere — clear your unread state for it
+  // e.messageId was read elsewhere, so clear your unread state for it
 });
 ```
 
-**Group read receipts.** Since SDK `0.13.0`, a group can opt into sharing read receipts with every member. Call `updateGroup(groupId, { readReceiptsVisibleToGroup: true })` (owner/admin); after that, a member's `markRead()` on a group message is broadcast to every other member, and `onReadReceipt` fires with `e.fromUserId` set to the member who read it. It is **opt-in per group** — the platform never enables it for you, and it has no effect unless read receipts are also enabled for your app.
+**Group read receipts.** Since SDK `0.13.0`, a group can opt into sharing read receipts with every member. Call `updateGroup(groupId, { readReceiptsVisibleToGroup: true })` (owner/admin); after that, a member's `markRead()` on a group message is broadcast to every other member, and `onReadReceipt` fires with `e.fromUserId` set to the member who read it. It is **opt-in per group**. The platform never enables it for you, and it has no effect unless read receipts are also enabled for your app.
 
 ```typescript
 await client.updateGroup(groupId, { readReceiptsVisibleToGroup: true });
@@ -133,7 +178,7 @@ client.onReadReceipt(e => {
 
 ### Notification clear & draft sync
 
-Available since SDK `0.12.0`, both own-device only. `clearNotification()` tells your user's other devices a conversation's notifications were dismissed — always available. `syncDraft()` pushes a draft so the user can keep typing on another device — **opt-in** (the app owner enables it in the dashboard) and the draft text crosses the relay in cleartext.
+Available since SDK `0.12.0`, both own-device only. `clearNotification()` tells your user's other devices a conversation's notifications were dismissed, and is always available. `syncDraft()` pushes a draft so the user can keep typing on another device, and is **opt-in** (the app owner enables it in the dashboard) and the draft text crosses the relay in cleartext.
 
 ```typescript
 client.clearNotification(conversationId);
@@ -145,7 +190,7 @@ client.onDraftSync(e => { /* pre-fill composer with e.draftText */ });
 
 ### Device trust
 
-Available since SDK `0.10.0`. Any device that completes a connection is implicitly trusted. `listMyDevices()` powers a "Your devices" screen; `revokeMyDevice()` cuts a device off immediately. When the *current* device is revoked, the SDK stops reconnecting and emits a `DEVICE_REVOKED` event via `onEvent` — listen for it to clear local key storage and prompt re-registration.
+Available since SDK `0.10.0`. Any device that completes a connection is implicitly trusted. `listMyDevices()` powers a "Your devices" screen; `revokeMyDevice()` cuts a device off immediately. When the *current* device is revoked, the SDK stops reconnecting and emits a `DEVICE_REVOKED` event via `onEvent`. Listen for it to clear local key storage and prompt re-registration.
 
 ```typescript
 const devices = await client.listMyDevices();
@@ -434,7 +479,7 @@ await wt.connect();
 await wt.sendEnvelope(envelopeBytes);
 ```
 
-Uses the browser-native `WebTransport` API; opens a single bidirectional stream and rides raw bytes both ways. Browser support: Chromium 97+ (stable), Firefox 125+ (stable), Safari Technology Preview only, Node 22+ behind experimental flags. The `droponair.com` endpoint advertises `transports: ["webtransport"]` only when the `droponair-webtransport` sidecar is live; check `GET /api/info.transports` and `features.transport_webtransport` to detect availability. Bring your own protobuf decoder. WebSocket remains the default; this primitive is purely opt-in.
+Uses the browser-native `WebTransport` API; opens a single bidirectional stream and rides raw bytes both ways. Browser support: Chromium 97+ (stable), Firefox 125+ (stable), Safari Technology Preview only, Node 22+ behind experimental flags. The endpoint advertises `transports: ["webtransport"]` only where the lane is available; check `GET /api/info.transports` and `features.transport_webtransport` to detect it. Bring your own protobuf decoder. WebSocket remains the default; this primitive is purely opt-in.
 
 ### Transport auto-select
 
@@ -455,7 +500,7 @@ Foundation for an `init({ transport: 'auto' })` shortcut once full `MessagingCli
 
 ### Call Recording
 
-Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage — the platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.
+Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage. The platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.
 
 | Method | Description |
 |--------|-------------|

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

@@ -44,7 +44,7 @@ export declare class AttachmentClient {
      */
     prepareAttachmentAndUpload(input: Uint8Array, opts: PrepareAttachmentOptions): Promise<AttachmentRef>;
     /**
-     * Revoke an attachment you sent (Phase 2f). After revoke the platform
+     * Revoke an attachment you sent. After revoke the platform
      * refuses to issue further download URLs and recipients with a live
      * connection get an ATTACHMENT_REVOKED event. Bytes a recipient already
      * downloaded cannot be recalled.

package/dist/attachment/attachment-client.js

@@ -147,7 +147,7 @@ class AttachmentClient {
         };
     }
     /**
-     * Revoke an attachment you sent (Phase 2f). After revoke the platform
+     * Revoke an attachment you sent. After revoke the platform
      * refuses to issue further download URLs and recipients with a live
      * connection get an ATTACHMENT_REVOKED event. Bytes a recipient already
      * downloaded cannot be recalled.

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

@@ -1,6 +1,6 @@
 import { CryptoService } from '../crypto/crypto-service';
 import { SessionManager } from './session-manager';
-import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback, KeyCustody } from './types';
 import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
@@ -39,7 +39,7 @@ export declare class MessagingClient implements DropOnAirClient {
     /** Pending startGroupCall resolver. */
     private pendingGroupInviteResolve;
     private pendingGroupInviteReject;
-    /** Pending joinRoom resolver (Feature 3.1), keyed by roomId. */
+    /** Pending joinRoom resolver, keyed by roomId. */
     private readonly pendingRoomJoins;
     private reconnectDelayMs;
     /** Schedule a single reconnect, replacing any pending one (never stack timers). */
@@ -100,6 +100,13 @@ export declare class MessagingClient implements DropOnAirClient {
     finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
     downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
     revokeAttachment(attachment: string | AttachmentRef): Promise<void>;
+    /**
+     * How the identity private key is held. See {@link KeyCustody}.
+     *
+     * Read from the crypto service rather than remembered at construction, so it
+     * reflects what is actually in use rather than what was requested.
+     */
+    get keyCustody(): KeyCustody;
     connect(): Promise<void>;
     disconnect(): void;
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
@@ -231,7 +238,7 @@ export declare class MessagingClient implements DropOnAirClient {
     getGroup(groupId: string): Promise<GroupInfo>;
     /**
      * Update a group. Any omitted field is left unchanged. `readReceiptsVisibleToGroup`
-     * (Phase 2e) controls whether members' group read receipts are visible to
+     * controls whether members' group read receipts are visible to
      * the whole group or stay own-device only.
      */
     updateGroup(groupId: string, update: {

package/dist/core/messaging-client.js

@@ -246,7 +246,7 @@ class MessagingClient {
         /** Pending startGroupCall resolver. */
         this.pendingGroupInviteResolve = null;
         this.pendingGroupInviteReject = null;
-        /** Pending joinRoom resolver (Feature 3.1), keyed by roomId. */
+        /** Pending joinRoom resolver, keyed by roomId. */
         this.pendingRoomJoins = new Map();
         this.messageListeners = new Set();
         this.eventListeners = new Set();
@@ -313,6 +313,15 @@ class MessagingClient {
             await this.attachmentClient.revokeAttachment(attachment.thumbnailAttachmentId);
         }
     }
+    /**
+     * How the identity private key is held. See {@link KeyCustody}.
+     *
+     * Read from the crypto service rather than remembered at construction, so it
+     * reflects what is actually in use rather than what was requested.
+     */
+    get keyCustody() {
+        return this.cryptoService.keyCustody;
+    }
     async connect() {
         this.log('connect_start');
         this.shouldReconnect = true;
@@ -649,7 +658,7 @@ class MessagingClient {
         this.transport.send(this.codec.encodePushRegistrationFrame(frame));
     }
     // ---------------------------------------------------------------------------
-    // Device trust (PROTOCOL_VERSION 5+ / Phase 2b)
+    // Device trust (PROTOCOL_VERSION 5+)
     // ---------------------------------------------------------------------------
     /**
      * List the current user's registered devices. Each device is implicitly
@@ -702,7 +711,7 @@ class MessagingClient {
         }
     }
     // ---------------------------------------------------------------------------
-    // Cross-device read receipts (PROTOCOL_VERSION 6+ / Phase 2c)
+    // Cross-device read receipts (PROTOCOL_VERSION 6+)
     // ---------------------------------------------------------------------------
     /**
      * Mark a message as read. Call this when YOUR app decides a message has
@@ -941,7 +950,7 @@ class MessagingClient {
     }
     /**
      * Update a group. Any omitted field is left unchanged. `readReceiptsVisibleToGroup`
-     * (Phase 2e) controls whether members' group read receipts are visible to
+     * controls whether members' group read receipts are visible to
      * the whole group or stay own-device only.
      */
     async updateGroup(groupId, update) {
@@ -986,7 +995,7 @@ class MessagingClient {
             throw new Error(`deleteGroup failed (HTTP ${res.status})`);
     }
     // ---------------------------------------------------------------------------
-    // Rooms (Feature 3.1 - scheduled & persistent meeting rooms)
+    // Rooms (scheduled & persistent meeting rooms)
     // ---------------------------------------------------------------------------
     async createRoom(options) {
         const jwt = await this.getValidDropOnAirJwt(false);
@@ -1316,7 +1325,7 @@ class MessagingClient {
         return () => this.groupCallListeners.delete(callback);
     }
     // Group call moderation + waiting room. The server validates host/co-host
-    // authority and the `featuresEnabled.moderation` plan flag; on denial it
+    // authority and whether moderation is available on the app's plan; on denial it
     // emits a LIMIT_REACHED event with reason="MODERATION_NOT_ENABLED".
     transferHost(callId, groupId, newHostUserId) {
         this.sendGroupCallFrame({
@@ -1390,7 +1399,7 @@ class MessagingClient {
             payload: JSON.stringify({ userId }),
         });
     }
-    // Live stage controls (Feature 3.2). These act on a room call running in
+    // Live stage controls. These act on a room call running in
     // stage mode; pass the callId from joinRoom(). raiseHand / lowerHand and
     // submitStageQuestion are open to any participant; promote / demote are
     // host / co-host authority. Roles surface via GROUP_CALL_ROLE_CHANGED.
@@ -1419,7 +1428,7 @@ class MessagingClient {
     submitStageQuestion(callId, text) {
         this.sendGroupCallFrame({ type: 'GROUP_CALL_STAGE_QUESTION', callId, groupId: '', payload: text });
     }
-    // Call recording (Feature 3.5a). These SIGNAL recording state; the actual
+    // Call recording. These SIGNAL recording state; the actual
     // media capture + upload to your storage is your app's job (same split as
     // screen sharing). The platform broadcasts the signal to every participant.
     startRecording(callId) {
@@ -1580,7 +1589,7 @@ class MessagingClient {
                 plaintext = await this.cryptoService.decrypt(myPayload.encryptedPayload, sharedKey, {
                     messageId: notif.messageId,
                     senderId: notif.fromUserId,
-                    // AAD recipientId is the receiving user's own id — this MUST match the
+                    // AAD recipientId is the receiving user's own id, and this MUST match the
                     // sender's encrypt AAD, which binds recipientId to the target member's
                     // userId (memberId). Using notif.groupId here (the previous value) never
                     // matched, so E2EE group messages failed GCM auth on decrypt. android /
@@ -1625,7 +1634,7 @@ class MessagingClient {
             this.pendingGroupInviteReject = null;
             reject(new Error(`GROUP_CALL_ALREADY_ACTIVE:${wire.payload ?? ''}`));
         }
-        // Resolve / reject a pending joinRoom() (Feature 3.1). Room-call frames
+        // Resolve / reject a pending joinRoom(). Room-call frames
         // carry roomId; the join outcome is one of these four types.
         if (wire.roomId) {
             const pending = this.pendingRoomJoins.get(wire.roomId);

package/dist/core/types.d.ts

@@ -117,7 +117,7 @@ export interface GroupInfo {
     members: GroupMemberInfo[];
     createdAt: number;
     /**
-     * Phase 2e. When true, a member's group read receipt is fanned to all other
+     * When true, a member's group read receipt is fanned to all other
      * members; when false it stays own-device only. Controlled via updateGroup().
      */
     readReceiptsVisibleToGroup?: boolean;
@@ -140,7 +140,7 @@ export interface GroupCallEvent {
     type: GroupCallEventType | string;
     callId: string;
     groupId: string;
-    /** Set instead of groupId when the event belongs to a room call (Feature 3.1). */
+    /** Set instead of groupId when the event belongs to a room call. */
     roomId?: string;
     targetUserId?: string;
     payload?: string;
@@ -160,7 +160,7 @@ export interface RoomPolicy {
     /** When true, the room flips to CLOSED once the last participant leaves the call. */
     autoCloseWhenEmpty?: boolean;
     /**
-     * When true, the room's live call runs in stage mode (Feature 3.2): hosts
+     * When true, the room's live call runs in stage mode: hosts
      * join as speakers, everyone else as receive-only audience who can raise a
      * hand to be promoted. Mesh-scale - suited to panels and small stages.
      */
@@ -191,7 +191,7 @@ export interface SfuToken {
     expiresAt: number;
 }
 /**
- * A server-side recording of an SFU-mode room (Phase 3.7.5). The platform
+ * A server-side recording of an SFU-mode room. The platform
  * never holds the recorded bytes - LiveKit Egress uploads the finalized file
  * directly to the destination configured in the panel under `destinationId`.
  */
@@ -251,6 +251,57 @@ export interface KeyStorageAdapter {
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
 }
+/**
+ * How the identity private key is held.
+ *
+ * - `non-extractable`: the key lives in the agent as a CryptoKey that script
+ *   cannot export. An attacker running script on the origin can still use it
+ *   while the page is open, which is unavoidable, but cannot copy it out and use
+ *   it later or elsewhere.
+ * - `software`: the key exists as bytes reachable from script, so anything that
+ *   can run script on the origin can read it once and decrypt that user's
+ *   conversations from anywhere, indefinitely.
+ *
+ * Exposed so an application can tell its users the truth rather than assume.
+ */
+export type KeyCustody = 'non-extractable' | 'software';
+/**
+ * Owns the identity keypair and the key agreement that uses it.
+ *
+ * This exists because a storage interface alone cannot make key material
+ * XSS-resistant. The strongest browsers offer is a non-extractable CryptoKey,
+ * and by definition its bytes cannot be handed back to a caller, so any design
+ * shaped as "give me the private key and I will do the maths" forces the key to
+ * be extractable. The agreement has to happen behind the same boundary that
+ * holds the key, which is what this interface is.
+ *
+ * Implement it to hold keys somewhere the SDK cannot reach, for example an OS
+ * keychain or a hardware token. The SDK ships two implementations and picks the
+ * conservative one unless asked otherwise; it never silently upgrades you.
+ */
+export interface SecureIdentityProvider {
+    /** Base64 X25519 public key for this device, created on first use. */
+    getPublicKey(): Promise<string>;
+    /**
+     * Perform X25519 with the peer's public key, then HKDF-SHA256 to an AES-GCM
+     * key, and return it.
+     *
+     * Returns the derived key rather than the shared secret so the secret need
+     * never exist outside the implementation. The returned key must be
+     * non-extractable: it is used for encrypt and decrypt and nothing else.
+     *
+     * `salt` and `info` are supplied by the SDK and are part of the wire format.
+     * An implementation that changes them will produce keys that no other
+     * participant can reproduce.
+     */
+    deriveMessageKey(params: {
+        peerPublicKey: string;
+        salt: Uint8Array;
+        info: Uint8Array;
+    }): Promise<CryptoKey>;
+    /** Whether the private key can be read by script. See {@link KeyCustody}. */
+    readonly keyCustody: KeyCustody;
+}
 export interface InitializeOptions {
     appId: string;
     publicApiKey: string;
@@ -262,6 +313,22 @@ export interface InitializeOptions {
     keyDirectoryEndpoint?: string;
     fetchFn?: typeof fetch;
     storage?: KeyStorageAdapter;
+    /**
+     * Owns the identity keypair instead of {@link storage}, when the consumer wants
+     * a private key that script cannot read.
+     *
+     * Optional and off by default, deliberately. Passing nothing keeps exactly the
+     * behaviour every existing release has: the identity is a raw key held through
+     * {@link storage}. Switching that silently would change key custody under
+     * applications that never asked for it, and on engines where the stronger path
+     * cannot persist it would do so without delivering anything.
+     *
+     * Build one with `createSecureIdentity()`, which returns `null` where the
+     * platform cannot support it so the choice is explicit rather than accidental.
+     * Read {@link DropOnAirClient.keyCustody} afterwards to see what was actually
+     * obtained.
+     */
+    identity?: SecureIdentityProvider;
     /** When true, verbose diagnostic logs are emitted to console for all SDK operations. */
     debug?: boolean;
     /**
@@ -299,6 +366,20 @@ export interface DeviceInfo {
     revokedBy?: 'END_USER' | 'APP_OWNER' | 'SYSTEM';
 }
 export interface DropOnAirClient {
+    /**
+     * How this client is holding the identity private key.
+     *
+     * `'non-extractable'` means the key exists only inside the platform's crypto
+     * agent: script may ask it to derive, and cannot read it, so storage taken from
+     * the device yields nothing usable. `'software'` means the key is bytes the
+     * process can read, which is what every release before this one did and what
+     * this one still does unless {@link InitializeOptions.identity} is supplied.
+     *
+     * Exposed because a consumer that believes it has the stronger custody and does
+     * not is worse off than one that knows. Log it, show it, or gate a feature on
+     * it, but do not assume it.
+     */
+    readonly keyCustody: KeyCustody;
     connect(): Promise<void>;
     disconnect(): void;
     /**

package/dist/crypto/crypto-service.d.ts

@@ -1,9 +1,16 @@
 import { SessionManager } from '../core/session-manager';
-import { KeyStorageAdapter } from '../core/types';
+import { KeyCustody, KeyStorageAdapter, SecureIdentityProvider } from '../core/types';
 export declare class CryptoService {
-    private readonly storage;
     private readonly sessionManager;
-    constructor(storage: KeyStorageAdapter, sessionManager: SessionManager);
+    private readonly identity;
+    /**
+     * Accepts either an identity provider or, for compatibility, the storage
+     * adapter it used to take. Passing storage keeps the previous behaviour
+     * exactly, by wrapping it in the tweetnacl provider.
+     */
+    constructor(storageOrIdentity: KeyStorageAdapter | SecureIdentityProvider, sessionManager: SessionManager);
+    /** How the identity private key is held. See {@link KeyCustody}. */
+    get keyCustody(): KeyCustody;
     generateIdentity(): Promise<{
         publicKey: string;
     }>;
@@ -23,6 +30,5 @@ export declare class CryptoService {
         recipientId: string;
         timestamp: number;
     }): Promise<string>;
-    private deriveAesKey;
     private buildAad;
 }