p2party 0.14.3 → 0.14.7

package/lib/index.d.ts

@@ -1,19 +1,27 @@
 import { createSession, generateSessionIdentity, restoreSession } from "./session";
+import { validateMnemonic, validateMnemonicWords } from "./cryptography/mnemonic";
 import { setWasmSourceUrl } from "./cryptography/wasmLoader";
 import { setDebugLogging } from "./utils/debug";
 import { WIRE_CHUNK_FRAME_LEN } from "./utils/constants";
 import { DEFAULT_ROOM_POLICY_V1, MIN_COVER_CADENCE_MS, MAX_COVER_CADENCE_MS, MAX_COVER_LANES, MAX_COVER_FRAMES_PER_CELL, MIN_COVER_SLOT_MS, canonicalizeRoomPolicyV1, decodeRoomPolicyV1, encodeRoomPolicyV1, hashRoomPolicyV1, roomPoliciesEqualV1, validateRoomPolicyV1 } from "./roomPolicy";
-import type { State } from "./store";
+import { InvalidRecoveryPhraseError } from "./utils/identityRestore";
+import { RemoteRoomRevocationUnconfirmedError } from "./utils/roomLeaveCoordinator";
+import type { State as InternalState } from "./store";
 import type { Room, Peer, Channel, Message } from "./reducers/roomSlice";
 import type { SignalingState } from "./reducers/signalingServerSlice";
 import type { MimeType, FileExtension } from "./utils/messageTypes";
-import type { WebSocketMessageRoomIdRequest, WebSocketMessageRoomIdResponse, WebSocketMessageChallengeRequest, WebSocketMessageChallengeResponse, WebSocketMessageDescriptionSend, WebSocketMessageDescriptionReceive, WebSocketMessageCandidateSend, WebSocketMessageCandidateReceive, WebSocketMessageError } from "./utils/interfaces";
+import type { WebSocketMessageRoomIdRequest, WebSocketMessageRoomIdResponse, WebSocketMessageChallengeRequest, WebSocketMessageChallengeResponse, WebSocketMessageDescriptionSend, WebSocketMessageDescriptionReceive, WebSocketMessageCandidateSend, WebSocketMessageCandidateReceive, WebSocketMessageLeaveRoomRequest, WebSocketMessageRoomLeftResponse, WebSocketMessageError } from "./utils/interfaces";
 import type { RoomData } from "./api/webrtc/interfaces";
-import type { BlacklistedPeer, UsernamedPeer, UniqueRoom, RoomStats } from "./db/types";
+import type { BlacklistedPeer, IdentityDerivation, UsernamedPeer, UniqueRoom, RoomStats } from "./db/types";
+import type { CreatedRecoverableIdentity, CreateRecoverableIdentityOptions, RestoredIdentity } from "./utils/identityRestore";
 import type { KeyPair } from "./reducers/keyPairSlice";
 import type { RoomPolicyV1 } from "./roomPolicy";
 import type { SendMessageResult } from "./handlers/handleSendMessage";
 import { MessageDeliveryError } from "./handlers/handleSendMessage";
+/** Public projection; reducer state keeps its additional fields normalized. */
+type State = Omit<InternalState, "rooms"> & {
+    rooms: Room[];
+};
 export interface ConnectRoomOptions {
     /**
      * Canonical public room policy. Omit on reconnect to preserve the room's
@@ -121,11 +129,69 @@ export interface MessageTransferHandle {
     /** Cancels exactly this logical send, even before hashing/WASM setup finishes. */
     cancel(): Promise<void>;
 }
+/**
+ * Adopt the identity a recovery phrase encodes, in place of the current one.
+ *
+ * An invalid phrase rejects with `InvalidRecoveryPhraseError` before anything
+ * is disconnected, so a typo costs nothing. Only a phrase that derives a key
+ * opens the exclusive boundary: signaling is disconnected, every room's WebRTC
+ * transport is brought to a terminal state, the cross-signed X25519 identity is
+ * deleted (the next connection regenerates and re-signs it), the Ed25519 key is
+ * persisted, and the identity is adopted in memory last.
+ *
+ * Rooms, messages, the address book and cached room PINs are all kept. Peers
+ * see a new identity key for this device, exactly as they would after a purge,
+ * so the address book will report an identity change.
+ *
+ * Signaling is left disconnected: call `connect(roomUrl)` afterwards to come
+ * back online under the restored identity.
+ *
+ * @param mnemonic - The recovery phrase, in any transcription
+ * @param password - The passphrase the identity was created with, if any
+ * @returns The restored Ed25519 public key, hex-encoded
+ */
+declare const restoreIdentityFromMnemonic: (mnemonic: string, password?: string) => Promise<RestoredIdentity>;
+/**
+ * Replace the current identity with a freshly generated, recoverable one and
+ * return the phrase that restores it.
+ *
+ * The phrase is shown once and stored nowhere: it is the only backup, and a
+ * caller that drops it before the user has written it down has lost it. A
+ * `password` is folded into the derivation and is equally unrecoverable — the
+ * phrase alone will not restore the identity without it.
+ *
+ * As with `restoreIdentityFromMnemonic`, signaling is left disconnected; call
+ * `connect(roomUrl)` afterwards.
+ *
+ * @param options - Entropy bits (128 gives 12 words, 256 gives 24) and an
+ *   optional passphrase
+ * @returns The recovery phrase and the Ed25519 public key it now derives
+ */
+declare const createRecoverableIdentity: (options?: CreateRecoverableIdentityOptions) => Promise<CreatedRecoverableIdentity>;
+/** What the current account key is, and whether a phrase can reproduce it. */
+export interface IdentityBackupStatus {
+    publicKey: string;
+    derivation: IdentityDerivation | null;
+}
+/**
+ * Whether the identity in use can be backed up at all.
+ *
+ * `derivation` is "mnemonic" only for an identity that was created from a
+ * recovery phrase; a "random" one cannot be exported, and the only way to get a
+ * recoverable identity is `createRecoverableIdentity`, which replaces it. It is
+ * null when no identity is stored yet, and also when the stored flag no longer
+ * describes the stored key — an unreadable provenance hint must never be
+ * reported as "this can be backed up".
+ *
+ * @returns The current Ed25519 public key (empty when there is none) and how it
+ *   came into being
+ */
+declare const getIdentityBackupStatus: () => Promise<IdentityBackupStatus>;
 export declare const p2party: {
     store: import("@reduxjs/toolkit").EnhancedStore<{
         commonState: import("./reducers/commonSlice").CommonState;
         keyPair: KeyPair;
-        rooms: Room[];
+        rooms: import("./reducers/roomSlice").ManagedRoom[];
         signalingServer: SignalingState;
         signalingServerApi: import("@reduxjs/toolkit/query").CombinedState<{
             connectWebSocket: import("@reduxjs/toolkit/query").MutationDefinition<string, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/signalingServerApi").WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
@@ -137,6 +203,7 @@ export declare const p2party: {
             connectWithPeer: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCPeerConnectionParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
             setDescription: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSetDescriptionParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
             setCandidate: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSetCandidateParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
+            applyRoomConfiguration: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCApplyRoomConfigurationParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
             openChannel: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCOpenChannelParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
             sendMessage: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSendMessageParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, SendMessageResult | undefined, "webrtcApi", undefined>;
             disconnect: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCDisconnectParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
@@ -150,7 +217,7 @@ export declare const p2party: {
         dispatch: import("redux-thunk").ThunkDispatch<{
             commonState: import("./reducers/commonSlice").CommonState;
             keyPair: KeyPair;
-            rooms: Room[];
+            rooms: import("./reducers/roomSlice").ManagedRoom[];
             signalingServer: SignalingState;
             signalingServerApi: import("@reduxjs/toolkit/query").CombinedState<{
                 connectWebSocket: import("@reduxjs/toolkit/query").MutationDefinition<string, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/signalingServerApi").WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
@@ -162,6 +229,7 @@ export declare const p2party: {
                 connectWithPeer: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCPeerConnectionParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
                 setDescription: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSetDescriptionParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
                 setCandidate: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSetCandidateParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
+                applyRoomConfiguration: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCApplyRoomConfigurationParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
                 openChannel: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCOpenChannelParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
                 sendMessage: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCSendMessageParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, SendMessageResult | undefined, "webrtcApi", undefined>;
                 disconnect: import("@reduxjs/toolkit/query").MutationDefinition<import("./api/webrtc/interfaces").RTCDisconnectParams, import("@reduxjs/toolkit/query").BaseQueryFn<import("./api/webrtc/baseQuery").RTCPeerConnectionParamsExtend, undefined>, never, undefined, "webrtcApi", undefined>;
@@ -173,10 +241,18 @@ export declare const p2party: {
             }, never, "webrtcApi">;
         }, undefined, import("redux").UnknownAction> & ((action: import("redux").Action<"listenerMiddleware/add">) => import("@reduxjs/toolkit").UnsubscribeListener);
     }>, import("redux").StoreEnhancer]>>;
-    commonStateSelector: (state: State) => import("./reducers/commonSlice").CommonState;
-    signalingServerSelector: (state: State) => SignalingState;
-    roomSelector: (state: State) => Room[];
-    keyPairSelector: (state: State) => KeyPair;
+    commonStateSelector: (state: {
+        readonly commonState: import("./reducers/commonSlice").CommonState;
+    }) => import("./reducers/commonSlice").CommonState;
+    signalingServerSelector: (state: {
+        readonly signalingServer: SignalingState;
+    }) => SignalingState;
+    roomSelector: <TRoom extends Room>(state: {
+        readonly rooms: TRoom[];
+    }) => TRoom[];
+    keyPairSelector: (state: {
+        readonly keyPair: KeyPair;
+    }) => KeyPair;
     connect: (roomUrl: string, signalingServerUrl?: string, rtcConfig?: RTCConfiguration, options?: ConnectRoomOptions) => Promise<void>;
     connectToSignalingServer: (roomUrl: string, signalingServerUrl?: string) => Promise<void>;
     disconnectFromSignalingServer: () => Promise<void>;
@@ -242,7 +318,13 @@ export declare const p2party: {
     generateKeyPair: (module?: import("./cryptography/libcrypto").LibCrypto) => Promise<import("./cryptography/interfaces").SignKeyPair>;
     newKeyPair: (module?: import("./cryptography/libcrypto").LibCrypto) => Promise<import("./cryptography/interfaces").SignKeyPair>;
     generateMnemonic: (strength?: 128 | 160 | 192 | 224 | 256 | 288 | 320 | 352 | 384 | 416 | 448 | 480 | 512) => Promise<string>;
-    keyPairFromMnemonic: (mnemonic: string, password?: string) => Promise<import("./cryptography/interfaces").SignKeyPair>;
+    keyPairFromMnemonic: (mnemonic: string, password?: string, module?: import("./cryptography/libcrypto").LibCrypto) => Promise<import("./cryptography/interfaces").SignKeyPair>;
+    validateMnemonic: (mnemonic: string) => Promise<boolean>;
+    validateMnemonicWords: (words: string) => import(".").MnemonicValidation;
+    createRecoverableIdentity: (options?: CreateRecoverableIdentityOptions) => Promise<CreatedRecoverableIdentity>;
+    restoreIdentityFromMnemonic: (mnemonic: string, password?: string) => Promise<RestoredIdentity>;
+    getIdentityBackupStatus: () => Promise<IdentityBackupStatus>;
+    InvalidRecoveryPhraseError: typeof InvalidRecoveryPhraseError;
     MIN_CHUNKS: number;
     MIN_CHUNK_SIZE: number;
     MAX_CHUNK_SIZE: number;
@@ -254,6 +336,7 @@ export declare const p2party: {
     MIN_COVER_SLOT_MS: number;
     validateRoomPolicyV1: (policy: RoomPolicyV1) => void;
     MessageDeliveryError: typeof MessageDeliveryError;
+    RemoteRoomRevocationUnconfirmedError: typeof RemoteRoomRevocationUnconfirmedError;
     joinRoom: (roomUrl: string, signalingServerUrl?: string, rtcConfig?: RTCConfiguration, options?: ConnectRoomOptions & WaitForRoomOptions) => Promise<Room>;
     waitForRoom: (roomUrl: string, options?: WaitForRoomOptions) => Promise<Room>;
     waitForPeers: (roomId: string, options?: WaitForPeersOptions) => Promise<Peer[]>;
@@ -348,11 +431,13 @@ declare global {
         p2party: typeof p2party;
     }
 }
-export type { State, Room, Peer, Channel, Message, RoomData, MimeType, FileExtension, UsernamedPeer, BlacklistedPeer, UniqueRoom, RoomStats, SignalingState, KeyPair, RoomPolicyV1, WebSocketMessageRoomIdRequest, WebSocketMessageRoomIdResponse, WebSocketMessageChallengeRequest, WebSocketMessageChallengeResponse, WebSocketMessageDescriptionSend, WebSocketMessageDescriptionReceive, WebSocketMessageCandidateSend, WebSocketMessageCandidateReceive, WebSocketMessageError, };
-export { createSession, restoreSession, generateSessionIdentity, setWasmSourceUrl, MessageDeliveryError, joinRoom, waitForRoom, waitForPeers, onMessage, setDebugLogging, };
+export type { State, Room, Peer, Channel, Message, RoomData, MimeType, FileExtension, UsernamedPeer, BlacklistedPeer, UniqueRoom, RoomStats, SignalingState, KeyPair, RoomPolicyV1, IdentityDerivation, WebSocketMessageRoomIdRequest, WebSocketMessageRoomIdResponse, WebSocketMessageChallengeRequest, WebSocketMessageChallengeResponse, WebSocketMessageDescriptionSend, WebSocketMessageDescriptionReceive, WebSocketMessageCandidateSend, WebSocketMessageCandidateReceive, WebSocketMessageLeaveRoomRequest, WebSocketMessageRoomLeftResponse, WebSocketMessageError, };
+export { createSession, restoreSession, generateSessionIdentity, setWasmSourceUrl, MessageDeliveryError, RemoteRoomRevocationUnconfirmedError, createRecoverableIdentity, restoreIdentityFromMnemonic, getIdentityBackupStatus, validateMnemonic, validateMnemonicWords, InvalidRecoveryPhraseError, joinRoom, waitForRoom, waitForPeers, onMessage, setDebugLogging, };
 export { DEFAULT_ROOM_POLICY_V1, canonicalizeRoomPolicyV1, decodeRoomPolicyV1, encodeRoomPolicyV1, hashRoomPolicyV1, roomPoliciesEqualV1, };
 export { MIN_COVER_CADENCE_MS, MAX_COVER_CADENCE_MS, MAX_COVER_LANES, MAX_COVER_FRAMES_PER_CELL, MIN_COVER_SLOT_MS, validateRoomPolicyV1, WIRE_CHUNK_FRAME_LEN, };
 export type { TransferAck } from "./handlers/reconcile";
+export type { MnemonicValidation } from "./cryptography/mnemonic";
+export type { CreatedRecoverableIdentity, CreateRecoverableIdentityOptions, RestoredIdentity, } from "./utils/identityRestore";
 export type { RoomAuthMode, RoomCoverMode, RoomPqMode, RoomRendezvousMode, } from "./roomPolicy";
 export type { CreateSessionOptions, EncryptedSessionMessage, GenerateSessionIdentityOptions, GeneratedSessionIdentity, HandshakeTransport, LocalSessionIdentity, P2PartySession, SessionChannelBinding, SessionCryptoOptions, } from "./session";
 export default p2party;