ping-openmls-sdk 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -1,18 +1,30 @@
-import { M as MessageEnvelope, S as Storage, T as Transport, C as ConversationId, a as ConversationMeta, U as UserId, b as DeviceId, I as IncomingMessage, L as LinkingTicket } from './types-jd8CLdi_.cjs';
-export { B as Bytes, c as DeviceInfo, D as DiscoveredDevice, H as Hlc, d as MessageKind } from './types-jd8CLdi_.cjs';
+import { M as MessageEnvelope, S as Storage, T as Transport, C as ConversationId, K as KeyPackageEntry, a as ConversationMeta, L as LinkingTicket, U as UserId, b as DeviceId, I as IncomingMessage, c as CatchupAppEvent, d as CatchupSnapshotView } from './types-DYtsj5dy.cjs';
+export { B as Bytes, e as CatchupSnapshotEntry, f as DeviceInfo, D as DiscoveredDevice, H as Hlc, g as MessageKind } from './types-DYtsj5dy.cjs';
 export { IndexedDbStorage } from './storage/indexeddb.cjs';
 export { WebSocketTransport } from './transport/websocket.cjs';
 
-/** Ping wire contract version. Bumped on incompatible profile changes. */
-declare const PING_WIRE_CONTRACT_VERSION = 1;
-/** Canonical CBOR content type. Production transports MUST use this. */
-declare const CONTENT_TYPE_CBOR = "application/vnd.ping.wire.v1+cbor";
+/**
+ * Ping wire contract version. Bumped on incompatible profile changes.
+ *
+ * Currently `2` — CR-6 changes the `content_hash` semantics for `Application` envelopes
+ * (now hashed over plaintext, not the MLS ciphertext). Receivers run a 90-day dual-accept
+ * window per Q-ARCH-02; see [[validate]] for the per-version routing.
+ */
+declare const PING_WIRE_CONTRACT_VERSION = 2;
+/** Lowest envelope version accepted by [[validate]] during the dual-accept window. */
+declare const WIRE_VERSION_MIN_ACCEPTED = 1;
+/** Canonical CBOR content type. Production transports SHOULD use this. */
+declare const CONTENT_TYPE_CBOR = "application/vnd.ping.wire.v2+cbor";
 /** JSON projection — development and tooling only. Production MUST NOT use this. */
-declare const CONTENT_TYPE_JSON = "application/vnd.ping.wire.v1+json";
+declare const CONTENT_TYPE_JSON = "application/vnd.ping.wire.v2+json";
+/** Legacy v1 CBOR type, accepted during the CR-6 dual-accept window. */
+declare const CONTENT_TYPE_CBOR_LEGACY_V1 = "application/vnd.ping.wire.v1+cbor";
+/** Legacy v1 JSON type, accepted during the CR-6 dual-accept window. */
+declare const CONTENT_TYPE_JSON_LEGACY_V1 = "application/vnd.ping.wire.v1+json";
 /** Header used over transports that don't surface a content type (e.g. WebSocket). */
 declare const PING_WIRE_CONTRACT_HEADER = "X-Ping-Wire-Contract";
 /** Header value: `ping/<VERSION>`. */
-declare const PING_WIRE_CONTRACT_HEADER_VALUE = "ping/1";
+declare const PING_WIRE_CONTRACT_HEADER_VALUE = "ping/2";
 type ValidationErrorKind = "UnsupportedVersion" | "BadConversationIdLen" | "BadSenderDeviceLen" | "ContentHashMismatch";
 declare class ValidationError extends Error {
     readonly kind: ValidationErrorKind;
@@ -24,12 +36,25 @@ declare class ValidationError extends Error {
  * Receivers claiming contract conformance MUST call this before applying any envelope.
  * External consumers using the raw envelope under their own profile are not bound by
  * these rules.
+ *
+ * CR-6 dual-accept window: `v ∈ [WIRE_VERSION_MIN_ACCEPTED, PING_WIRE_CONTRACT_VERSION]`
+ * passes the version gate. For v=2 `Application` envelopes the content_hash is over
+ * plaintext, so this function skips that check — callers MUST run
+ * [[verifyApplicationContentHash]] after MLS decrypt to close the loop.
  */
 declare function validate(env: MessageEnvelope): Promise<void>;
+/**
+ * Verify a v=2 `Application` envelope's content_hash against the decrypted plaintext.
+ *
+ * Caller MUST run this after MLS decrypt for application envelopes whose `v >= 2`. For
+ * v=1 envelopes or handshake kinds this is a no-op (those are covered by [[validate]]).
+ */
+declare function verifyApplicationContentHash(env: MessageEnvelope, plaintext: Uint8Array): Promise<void>;
 /**
  * True if the supplied content type negotiates the ping-wire-contract.
  *
- * Tolerates whitespace and parameters (e.g. `; charset=utf-8`).
+ * Accepts the v2 canonical types AND the v1 legacy types during the CR-6 dual-accept
+ * window. Tolerates whitespace and parameters (e.g. `; charset=utf-8`).
  */
 declare function negotiates(contentType: string | null | undefined): boolean;
 
@@ -44,7 +69,9 @@ interface ClientConfig {
 interface Conversation {
     readonly id: ConversationId;
     send(plaintext: Uint8Array): Promise<MessageEnvelope>;
-    addMembers(keyPackages: Uint8Array[]): Promise<void>;
+    /** [CR-2] Add members by (device_id, KeyPackage) pair. Hosts typically pull these
+     *  straight from `transport.discoverDevices(userId)`. */
+    addMembers(entries: KeyPackageEntry[]): Promise<void>;
     removeMembers(leafIndexes: number[]): Promise<void>;
     meta(): ConversationMeta;
 }
@@ -63,6 +90,30 @@ declare class MessagingClient {
     private constructor();
     /** Generate a fresh identity. The returned bytes are a secret — store them encrypted. */
     static generateIdentity(): Promise<Uint8Array>;
+    /**
+     * HPKE-seal a `LinkingTicket` for delivery to a new device ([CR-3]).
+     *
+     * Returns CBOR-encoded bytes safe to relay through an untrusted inbox. The new device's
+     * X25519 public key (`newDevicePub`) is exchanged out-of-band — typically as part of a
+     * QR-encoded handshake on the linking screen. Pure function; runs in an ephemeral
+     * worker so no live `MessagingClient` is required on the sender side.
+     *
+     * Suite: `DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM` (matches MLS).
+     */
+    static sealLinkingTicket(ticket: LinkingTicket, newDevicePub: Uint8Array): Promise<Uint8Array>;
+    /**
+     * HPKE-open a sealed `LinkingTicket` on the new device ([CR-3]).
+     *
+     * The receiving device hasn't booted a `MessagingClient` yet — it only has its X25519
+     * ephemeral keypair. This static method runs the open in an ephemeral worker, returning
+     * the cleartext ticket which the host then feeds to `init()` + `consumeLinkingTicket()`.
+     *
+     * On failure the error message is deliberately generic (no discriminator between "wrong
+     * key" vs "tampered ciphertext") so a probing attacker can't tell the new device's key
+     * was the issue.
+     */
+    static openLinkingTicket(sealed: Uint8Array, newDevicePriv: Uint8Array): Promise<LinkingTicket>;
+    private static ephemeralWorkerCall;
     static init(cfg: ClientConfig): Promise<MessagingClient>;
     /** Internal: route an inbound envelope to the right handler. */
     private dispatchIncoming;
@@ -83,8 +134,81 @@ declare class MessagingClient {
     listConversations(): Promise<ConversationMeta[]>;
     syncConversations(): Promise<IncomingMessage[]>;
     processEnvelope(envelope: MessageEnvelope): Promise<IncomingMessage | null>;
-    buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Uint8Array): Promise<LinkingTicket>;
+    /**
+     * Build a `LinkingTicket` for a new device.
+     *
+     * [CR-13] `lastAppEvents` is host-supplied per-conversation "what you missed" data
+     * (decrypted AppEvent bytes the new device will render before sync catches up).
+     * Pass `[]` to suppress catchup data — the new device will see an empty conversation
+     * list until normal sync runs.
+     *
+     * Caller is responsible for HPKE-sealing the returned ticket via
+     * `MessagingClient.sealLinkingTicket` before transmitting (CR-3).
+     */
+    buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Uint8Array, lastAppEvents?: CatchupAppEvent[]): Promise<LinkingTicket>;
+    /**
+     * Decode a `LinkingTicket.catchup_snapshot` blob ([CR-13]).
+     *
+     * Pure WASM — runs in an ephemeral worker so the new device can call this before
+     * `MessagingClient.init()` completes (just like `openLinkingTicket`). Returns the
+     * structured view: per-conversation metas + last-known AppEvent bytes.
+     *
+     * Throws on malformed or oversized inputs. Empty bytes return `null` — that's the
+     * "no catchup data" case (sender passed `[]` to buildLinkingTicket).
+     */
+    static decodeCatchupSnapshot(snapshotBytes: Uint8Array): Promise<CatchupSnapshotView | null>;
     consumeLinkingTicket(ticket: LinkingTicket): Promise<void>;
+    /**
+     * Revoke a device ([CR-2]).
+     *
+     * Removes `deviceId`'s leaf from every conversation where this client locally
+     * tracked the device→leaf mapping (i.e. conversations where this client itself
+     * admitted the device via `addMembers`, or where this client is the device being
+     * revoked). The SDK has already broadcast each Commit envelope via
+     * `transport.send`; the returned array is for any additional host-side handling
+     * (audit logs, UI). An empty array is a valid outcome — the device wasn't locally
+     * known anywhere.
+     *
+     * **Scope note.** Conversations where a peer admitted the device on this client's
+     * behalf are silently skipped — the leaf index isn't locally known. Host can fall
+     * back to `transport.discoverDevices` + a manual `remove_members(leafIndex)` for
+     * those, or wait for the affected user to revoke from a device that did the admit.
+     * See `docs/architecture/multi-device.md §Device removal`.
+     */
+    revokeDevice(deviceId: DeviceId): Promise<MessageEnvelope[]>;
+    /**
+     * Export a portable MLS state snapshot for one conversation ([CR-7]).
+     *
+     * Returned bytes can be embedded in a recovery blob or shipped through a
+     * linking ticket so another device of the same user identity can re-attach to
+     * the group via [[importStateSnapshot]]. The bytes contain past epoch secrets;
+     * never log, never persist unencrypted, wipe (`.fill(0)`) after use.
+     */
+    exportConversationStateSnapshot(conv: ConversationId): Promise<Uint8Array>;
+    /**
+     * Import a `GroupStateSnapshot` from another device of the same user identity
+     * ([CR-7]).
+     *
+     * On success, the conversation appears in [[listConversations]] and decryption
+     * of subsequent peer-originated traffic works against the imported state. For
+     * full multi-device participation, the recovered device SHOULD then issue an
+     * MLS Update Proposal to rotate onto a fresh leaf (post-v1 follow-up — see
+     * `docs/design/CR4_CR7_PERSISTENCE.md` open question #3).
+     */
+    importStateSnapshot(snapshotBytes: Uint8Array): Promise<ConversationId>;
+    /**
+     * Export a derived secret from a conversation's MLS exporter ([CR-8]).
+     *
+     * Used to seed the ephemeral channel (`ping/ephemeral`), call-media keys
+     * (`ping/calls/media/<call_id>`), and call-ephemeral framer keys
+     * (`ping/calls/ephemeral/<call_id>`). The returned bytes are a secret — never log,
+     * persist only encrypted, and call `bytes.fill(0)` after use to wipe the typed array.
+     *
+     * Same `(conversationId, current_epoch, label, context, length)` produces the same
+     * bytes across every binding (Rust core, native UniFFI, WASM/JS). Cross-platform
+     * byte-equality is enforced by `protocol/conformance/export_secret/`.
+     */
+    exportConversationSecret(conv: ConversationId, label: string, context: Uint8Array, length: number): Promise<Uint8Array>;
     /** Subscribe to decrypted application messages. */
     onMessage(handler: (m: IncomingMessage) => void): () => void;
     /** Fired after every state-changing event for a conversation (Commit, member changes). */
@@ -100,4 +224,4 @@ declare class MessagingClient {
     private handleWorker;
 }
 
-export { CONTENT_TYPE_CBOR, CONTENT_TYPE_JSON, type ClientConfig, type Conversation, ConversationId, ConversationMeta, DeviceId, IncomingMessage, LinkingTicket, MessageEnvelope, MessagingClient, PING_WIRE_CONTRACT_HEADER, PING_WIRE_CONTRACT_HEADER_VALUE, PING_WIRE_CONTRACT_VERSION, Storage, Transport, UserId, ValidationError, negotiates, validate };
+export { CONTENT_TYPE_CBOR, CONTENT_TYPE_CBOR_LEGACY_V1, CONTENT_TYPE_JSON, CONTENT_TYPE_JSON_LEGACY_V1, CatchupAppEvent, CatchupSnapshotView, type ClientConfig, type Conversation, ConversationId, ConversationMeta, DeviceId, IncomingMessage, KeyPackageEntry, LinkingTicket, MessageEnvelope, MessagingClient, PING_WIRE_CONTRACT_HEADER, PING_WIRE_CONTRACT_HEADER_VALUE, PING_WIRE_CONTRACT_VERSION, Storage, Transport, UserId, ValidationError, WIRE_VERSION_MIN_ACCEPTED, negotiates, validate, verifyApplicationContentHash };

package/dist/index.d.ts

@@ -1,18 +1,30 @@
-import { M as MessageEnvelope, S as Storage, T as Transport, C as ConversationId, a as ConversationMeta, U as UserId, b as DeviceId, I as IncomingMessage, L as LinkingTicket } from './types-jd8CLdi_.js';
-export { B as Bytes, c as DeviceInfo, D as DiscoveredDevice, H as Hlc, d as MessageKind } from './types-jd8CLdi_.js';
+import { M as MessageEnvelope, S as Storage, T as Transport, C as ConversationId, K as KeyPackageEntry, a as ConversationMeta, L as LinkingTicket, U as UserId, b as DeviceId, I as IncomingMessage, c as CatchupAppEvent, d as CatchupSnapshotView } from './types-DYtsj5dy.js';
+export { B as Bytes, e as CatchupSnapshotEntry, f as DeviceInfo, D as DiscoveredDevice, H as Hlc, g as MessageKind } from './types-DYtsj5dy.js';
 export { IndexedDbStorage } from './storage/indexeddb.js';
 export { WebSocketTransport } from './transport/websocket.js';
 
-/** Ping wire contract version. Bumped on incompatible profile changes. */
-declare const PING_WIRE_CONTRACT_VERSION = 1;
-/** Canonical CBOR content type. Production transports MUST use this. */
-declare const CONTENT_TYPE_CBOR = "application/vnd.ping.wire.v1+cbor";
+/**
+ * Ping wire contract version. Bumped on incompatible profile changes.
+ *
+ * Currently `2` — CR-6 changes the `content_hash` semantics for `Application` envelopes
+ * (now hashed over plaintext, not the MLS ciphertext). Receivers run a 90-day dual-accept
+ * window per Q-ARCH-02; see [[validate]] for the per-version routing.
+ */
+declare const PING_WIRE_CONTRACT_VERSION = 2;
+/** Lowest envelope version accepted by [[validate]] during the dual-accept window. */
+declare const WIRE_VERSION_MIN_ACCEPTED = 1;
+/** Canonical CBOR content type. Production transports SHOULD use this. */
+declare const CONTENT_TYPE_CBOR = "application/vnd.ping.wire.v2+cbor";
 /** JSON projection — development and tooling only. Production MUST NOT use this. */
-declare const CONTENT_TYPE_JSON = "application/vnd.ping.wire.v1+json";
+declare const CONTENT_TYPE_JSON = "application/vnd.ping.wire.v2+json";
+/** Legacy v1 CBOR type, accepted during the CR-6 dual-accept window. */
+declare const CONTENT_TYPE_CBOR_LEGACY_V1 = "application/vnd.ping.wire.v1+cbor";
+/** Legacy v1 JSON type, accepted during the CR-6 dual-accept window. */
+declare const CONTENT_TYPE_JSON_LEGACY_V1 = "application/vnd.ping.wire.v1+json";
 /** Header used over transports that don't surface a content type (e.g. WebSocket). */
 declare const PING_WIRE_CONTRACT_HEADER = "X-Ping-Wire-Contract";
 /** Header value: `ping/<VERSION>`. */
-declare const PING_WIRE_CONTRACT_HEADER_VALUE = "ping/1";
+declare const PING_WIRE_CONTRACT_HEADER_VALUE = "ping/2";
 type ValidationErrorKind = "UnsupportedVersion" | "BadConversationIdLen" | "BadSenderDeviceLen" | "ContentHashMismatch";
 declare class ValidationError extends Error {
     readonly kind: ValidationErrorKind;
@@ -24,12 +36,25 @@ declare class ValidationError extends Error {
  * Receivers claiming contract conformance MUST call this before applying any envelope.
  * External consumers using the raw envelope under their own profile are not bound by
  * these rules.
+ *
+ * CR-6 dual-accept window: `v ∈ [WIRE_VERSION_MIN_ACCEPTED, PING_WIRE_CONTRACT_VERSION]`
+ * passes the version gate. For v=2 `Application` envelopes the content_hash is over
+ * plaintext, so this function skips that check — callers MUST run
+ * [[verifyApplicationContentHash]] after MLS decrypt to close the loop.
  */
 declare function validate(env: MessageEnvelope): Promise<void>;
+/**
+ * Verify a v=2 `Application` envelope's content_hash against the decrypted plaintext.
+ *
+ * Caller MUST run this after MLS decrypt for application envelopes whose `v >= 2`. For
+ * v=1 envelopes or handshake kinds this is a no-op (those are covered by [[validate]]).
+ */
+declare function verifyApplicationContentHash(env: MessageEnvelope, plaintext: Uint8Array): Promise<void>;
 /**
  * True if the supplied content type negotiates the ping-wire-contract.
  *
- * Tolerates whitespace and parameters (e.g. `; charset=utf-8`).
+ * Accepts the v2 canonical types AND the v1 legacy types during the CR-6 dual-accept
+ * window. Tolerates whitespace and parameters (e.g. `; charset=utf-8`).
  */
 declare function negotiates(contentType: string | null | undefined): boolean;
 
@@ -44,7 +69,9 @@ interface ClientConfig {
 interface Conversation {
     readonly id: ConversationId;
     send(plaintext: Uint8Array): Promise<MessageEnvelope>;
-    addMembers(keyPackages: Uint8Array[]): Promise<void>;
+    /** [CR-2] Add members by (device_id, KeyPackage) pair. Hosts typically pull these
+     *  straight from `transport.discoverDevices(userId)`. */
+    addMembers(entries: KeyPackageEntry[]): Promise<void>;
     removeMembers(leafIndexes: number[]): Promise<void>;
     meta(): ConversationMeta;
 }
@@ -63,6 +90,30 @@ declare class MessagingClient {
     private constructor();
     /** Generate a fresh identity. The returned bytes are a secret — store them encrypted. */
     static generateIdentity(): Promise<Uint8Array>;
+    /**
+     * HPKE-seal a `LinkingTicket` for delivery to a new device ([CR-3]).
+     *
+     * Returns CBOR-encoded bytes safe to relay through an untrusted inbox. The new device's
+     * X25519 public key (`newDevicePub`) is exchanged out-of-band — typically as part of a
+     * QR-encoded handshake on the linking screen. Pure function; runs in an ephemeral
+     * worker so no live `MessagingClient` is required on the sender side.
+     *
+     * Suite: `DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM` (matches MLS).
+     */
+    static sealLinkingTicket(ticket: LinkingTicket, newDevicePub: Uint8Array): Promise<Uint8Array>;
+    /**
+     * HPKE-open a sealed `LinkingTicket` on the new device ([CR-3]).
+     *
+     * The receiving device hasn't booted a `MessagingClient` yet — it only has its X25519
+     * ephemeral keypair. This static method runs the open in an ephemeral worker, returning
+     * the cleartext ticket which the host then feeds to `init()` + `consumeLinkingTicket()`.
+     *
+     * On failure the error message is deliberately generic (no discriminator between "wrong
+     * key" vs "tampered ciphertext") so a probing attacker can't tell the new device's key
+     * was the issue.
+     */
+    static openLinkingTicket(sealed: Uint8Array, newDevicePriv: Uint8Array): Promise<LinkingTicket>;
+    private static ephemeralWorkerCall;
     static init(cfg: ClientConfig): Promise<MessagingClient>;
     /** Internal: route an inbound envelope to the right handler. */
     private dispatchIncoming;
@@ -83,8 +134,81 @@ declare class MessagingClient {
     listConversations(): Promise<ConversationMeta[]>;
     syncConversations(): Promise<IncomingMessage[]>;
     processEnvelope(envelope: MessageEnvelope): Promise<IncomingMessage | null>;
-    buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Uint8Array): Promise<LinkingTicket>;
+    /**
+     * Build a `LinkingTicket` for a new device.
+     *
+     * [CR-13] `lastAppEvents` is host-supplied per-conversation "what you missed" data
+     * (decrypted AppEvent bytes the new device will render before sync catches up).
+     * Pass `[]` to suppress catchup data — the new device will see an empty conversation
+     * list until normal sync runs.
+     *
+     * Caller is responsible for HPKE-sealing the returned ticket via
+     * `MessagingClient.sealLinkingTicket` before transmitting (CR-3).
+     */
+    buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Uint8Array, lastAppEvents?: CatchupAppEvent[]): Promise<LinkingTicket>;
+    /**
+     * Decode a `LinkingTicket.catchup_snapshot` blob ([CR-13]).
+     *
+     * Pure WASM — runs in an ephemeral worker so the new device can call this before
+     * `MessagingClient.init()` completes (just like `openLinkingTicket`). Returns the
+     * structured view: per-conversation metas + last-known AppEvent bytes.
+     *
+     * Throws on malformed or oversized inputs. Empty bytes return `null` — that's the
+     * "no catchup data" case (sender passed `[]` to buildLinkingTicket).
+     */
+    static decodeCatchupSnapshot(snapshotBytes: Uint8Array): Promise<CatchupSnapshotView | null>;
     consumeLinkingTicket(ticket: LinkingTicket): Promise<void>;
+    /**
+     * Revoke a device ([CR-2]).
+     *
+     * Removes `deviceId`'s leaf from every conversation where this client locally
+     * tracked the device→leaf mapping (i.e. conversations where this client itself
+     * admitted the device via `addMembers`, or where this client is the device being
+     * revoked). The SDK has already broadcast each Commit envelope via
+     * `transport.send`; the returned array is for any additional host-side handling
+     * (audit logs, UI). An empty array is a valid outcome — the device wasn't locally
+     * known anywhere.
+     *
+     * **Scope note.** Conversations where a peer admitted the device on this client's
+     * behalf are silently skipped — the leaf index isn't locally known. Host can fall
+     * back to `transport.discoverDevices` + a manual `remove_members(leafIndex)` for
+     * those, or wait for the affected user to revoke from a device that did the admit.
+     * See `docs/architecture/multi-device.md §Device removal`.
+     */
+    revokeDevice(deviceId: DeviceId): Promise<MessageEnvelope[]>;
+    /**
+     * Export a portable MLS state snapshot for one conversation ([CR-7]).
+     *
+     * Returned bytes can be embedded in a recovery blob or shipped through a
+     * linking ticket so another device of the same user identity can re-attach to
+     * the group via [[importStateSnapshot]]. The bytes contain past epoch secrets;
+     * never log, never persist unencrypted, wipe (`.fill(0)`) after use.
+     */
+    exportConversationStateSnapshot(conv: ConversationId): Promise<Uint8Array>;
+    /**
+     * Import a `GroupStateSnapshot` from another device of the same user identity
+     * ([CR-7]).
+     *
+     * On success, the conversation appears in [[listConversations]] and decryption
+     * of subsequent peer-originated traffic works against the imported state. For
+     * full multi-device participation, the recovered device SHOULD then issue an
+     * MLS Update Proposal to rotate onto a fresh leaf (post-v1 follow-up — see
+     * `docs/design/CR4_CR7_PERSISTENCE.md` open question #3).
+     */
+    importStateSnapshot(snapshotBytes: Uint8Array): Promise<ConversationId>;
+    /**
+     * Export a derived secret from a conversation's MLS exporter ([CR-8]).
+     *
+     * Used to seed the ephemeral channel (`ping/ephemeral`), call-media keys
+     * (`ping/calls/media/<call_id>`), and call-ephemeral framer keys
+     * (`ping/calls/ephemeral/<call_id>`). The returned bytes are a secret — never log,
+     * persist only encrypted, and call `bytes.fill(0)` after use to wipe the typed array.
+     *
+     * Same `(conversationId, current_epoch, label, context, length)` produces the same
+     * bytes across every binding (Rust core, native UniFFI, WASM/JS). Cross-platform
+     * byte-equality is enforced by `protocol/conformance/export_secret/`.
+     */
+    exportConversationSecret(conv: ConversationId, label: string, context: Uint8Array, length: number): Promise<Uint8Array>;
     /** Subscribe to decrypted application messages. */
     onMessage(handler: (m: IncomingMessage) => void): () => void;
     /** Fired after every state-changing event for a conversation (Commit, member changes). */
@@ -100,4 +224,4 @@ declare class MessagingClient {
     private handleWorker;
 }
 
-export { CONTENT_TYPE_CBOR, CONTENT_TYPE_JSON, type ClientConfig, type Conversation, ConversationId, ConversationMeta, DeviceId, IncomingMessage, LinkingTicket, MessageEnvelope, MessagingClient, PING_WIRE_CONTRACT_HEADER, PING_WIRE_CONTRACT_HEADER_VALUE, PING_WIRE_CONTRACT_VERSION, Storage, Transport, UserId, ValidationError, negotiates, validate };
+export { CONTENT_TYPE_CBOR, CONTENT_TYPE_CBOR_LEGACY_V1, CONTENT_TYPE_JSON, CONTENT_TYPE_JSON_LEGACY_V1, CatchupAppEvent, CatchupSnapshotView, type ClientConfig, type Conversation, ConversationId, ConversationMeta, DeviceId, IncomingMessage, KeyPackageEntry, LinkingTicket, MessageEnvelope, MessagingClient, PING_WIRE_CONTRACT_HEADER, PING_WIRE_CONTRACT_HEADER_VALUE, PING_WIRE_CONTRACT_VERSION, Storage, Transport, UserId, ValidationError, WIRE_VERSION_MIN_ACCEPTED, negotiates, validate, verifyApplicationContentHash };