@signalapp/libsignal-client 0.77.1 → 0.78.0

package/Native.d.ts

@@ -228,9 +228,11 @@ export function BackupKey_DeriveLocalBackupMetadataKey(backupKey: Uint8Array): U
 export function BackupKey_DeriveMediaEncryptionKey(backupKey: Uint8Array, mediaId: Uint8Array): Uint8Array;
 export function BackupKey_DeriveMediaId(backupKey: Uint8Array, mediaName: string): Uint8Array;
 export function BackupKey_DeriveThumbnailTransitEncryptionKey(backupKey: Uint8Array, mediaId: Uint8Array): Uint8Array;
-export function BackupResponse_GetForwardSecrecyToken(response: Wrapper<BackupResponse>): Uint8Array;
-export function BackupResponse_GetNextBackupSecretData(response: Wrapper<BackupResponse>): Uint8Array;
-export function BackupResponse_GetOpaqueMetadata(response: Wrapper<BackupResponse>): Uint8Array;
+export function BackupRestoreResponse_GetForwardSecrecyToken(response: Wrapper<BackupRestoreResponse>): Uint8Array;
+export function BackupRestoreResponse_GetNextBackupSecretData(response: Wrapper<BackupRestoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetForwardSecrecyToken(response: Wrapper<BackupStoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetNextBackupSecretData(response: Wrapper<BackupStoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetOpaqueMetadata(response: Wrapper<BackupStoreResponse>): Uint8Array;
 export function BridgedStringMap_insert(map: Wrapper<BridgedStringMap>, key: string, value: string): void;
 export function BridgedStringMap_new(initialCapacity: number): BridgedStringMap;
 export function CallLinkAuthCredentialPresentation_CheckValidContents(presentationBytes: Uint8Array): void;
@@ -501,8 +503,9 @@ export function SealedSender_DecryptToUsmc(ctext: Uint8Array, identityStore: Ide
 export function SealedSender_Encrypt(destination: Wrapper<ProtocolAddress>, content: Wrapper<UnidentifiedSenderMessageContent>, identityKeyStore: IdentityKeyStore): Promise<Uint8Array>;
 export function SealedSender_MultiRecipientEncrypt(recipients: Wrapper<ProtocolAddress>[], recipientSessions: Wrapper<SessionRecord>[], excludedRecipients: Uint8Array, content: Wrapper<UnidentifiedSenderMessageContent>, identityKeyStore: IdentityKeyStore): Promise<Uint8Array>;
 export function SealedSender_MultiRecipientMessageForSingleRecipient(encodedMultiRecipientMessage: Uint8Array): Uint8Array;
-export function SecureValueRecoveryForBackups_RestoreBackupFromServer(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, metadata: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<Uint8Array>;
-export function SecureValueRecoveryForBackups_StoreBackup(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, previousSecretData: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupResponse>;
+export function SecureValueRecoveryForBackups_CreateNewBackupChain(environment: number, backupKey: Uint8Array): Uint8Array;
+export function SecureValueRecoveryForBackups_RestoreBackupFromServer(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, metadata: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupRestoreResponse>;
+export function SecureValueRecoveryForBackups_StoreBackup(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, previousSecretData: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupStoreResponse>;
 export function SenderCertificate_Deserialize(data: Uint8Array): SenderCertificate;
 export function SenderCertificate_GetCertificate(obj: Wrapper<SenderCertificate>): Uint8Array;
 export function SenderCertificate_GetDeviceId(obj: Wrapper<SenderCertificate>): number;
@@ -719,7 +722,8 @@ export function initLogger(maxLevel: LogLevel, callback: (level: LogLevel, targe
 export function test_only_fn_returns_123(): number;
 interface Aes256GcmSiv { readonly __type: unique symbol; }
 interface AuthenticatedChatConnection { readonly __type: unique symbol; }
-interface BackupResponse { readonly __type: unique symbol; }
+interface BackupRestoreResponse { readonly __type: unique symbol; }
+interface BackupStoreResponse { readonly __type: unique symbol; }
 interface BridgedStringMap { readonly __type: unique symbol; }
 interface CdsiLookup { readonly __type: unique symbol; }
 interface ChatConnectionInfo { readonly __type: unique symbol; }

package/dist/net/SvrB.d.ts

@@ -30,7 +30,33 @@ export type StoreBackupResponse = {
      */
     metadata: Uint8Array;
     /**
-     * Opaque value that must be persisted and provided to the next call to {@link SvrB#storeBackup}.
+     * Opaque value that must be persisted and provided to the next call to {@link SvrB#store}.
+     *
+     * See the {@link SvrB} documentation for lifecycle and persistence handling
+     * for this value.
+     */
+    nextBackupSecretData: Uint8Array;
+};
+/**
+ * The result of preparing a backup to be stored with forward secrecy guarantees.
+ *
+ * This context contains all the necessary components to encrypt and store a backup using a
+ * key derived from both the user's Account Entropy Pool and the SVR-B-protected
+ * Forward Secrecy Token.
+ *
+ * @see {@link BackupForwardSecrecyToken}
+ */
+export type RestoreBackupResponse = {
+    /**
+     * The forward secrecy token used to derive MessageBackupKey instances.
+     *
+     * This token provides forward secrecy guarantees by ensuring that compromise of the backup key
+     * alone is insufficient to decrypt backups. Each backup is protected by a value stored on
+     * the SVR-B server that must be retrieved during restoration.
+     */
+    forwardSecrecyToken: BackupForwardSecrecyToken;
+    /**
+     * Opaque value that must be persisted and provided to the next call to {@link SvrB#store}.
      *
      * See the {@link SvrB} documentation for lifecycle and persistence handling
      * for this value.
@@ -56,23 +82,24 @@ export type StoreBackupResponse = {
  * ## Storage Flow
  *
  * 1. Create a {@link Net} instance and get the {@link SvrB} service via {@link Net#svrB}
- * 2. Call {@link SvrB#storeBackup}
- *    - Pass the secret data from the last **successful** {@link SvrB#storeBackup} call
- *    - If no previous backup exists or the secret data is unavailable, pass `undefined`
- * 3. Use the returned forward secrecy token to derive encryption keys
- * 4. Encrypt and upload the backup data to the user's remote, off-device storage location, including the
- *    returned {@link StoreBackupResponse#metadata}. The upload **must succeed**
+ * 2. If this is a fresh install, call {@link SvrB#createNewBackupChain} and store the result
+ *    locally. Otherwise, retrieve the secret data from the last **successful** backup operation
+ *    (store or restore).
+ * 3. Call {@link SvrB#store}
+ * 4. Use the returned forward secrecy token to derive encryption keys
+ * 5. Encrypt and upload the backup data to the user's remote, off-device storage location,
+ *    including the returned {@link StoreBackupResponse#metadata}. The upload **must succeed**
  *    before proceeding or the previous backup might become unretrievable.
- * 5. Store the {@link StoreBackupResponse#nextBackupSecretData} locally, overwriting any previously-saved value.
+ * 6. Store the {@link StoreBackupResponse#nextBackupSecretData} locally, overwriting any
+ *    previously-saved value.
  *
  * ## Secret handling
  *
- * When calling {@link SvrB#storeBackup}, the `previousSecretData` parameter
- * must be from the last call to {@link SvrB#storeBackup} that
- * succeeded. The returned secret from a successful `storeBackup()` call should
- * be persisted until it is overwritten by the value from a subsequent
- * successful call. The caller should pass `undefined` as `previousSecretData`
- * only for the very first backup from a device.
+ * When calling {@link SvrB#store}, the `previousSecretData` parameter must be from the last call to
+ * {@link SvrB#store} or {@link SvrB#restore} that succeeded. The returned secret from a successful
+ * store or restore should be persisted until it is overwritten by the value from a subsequent
+ * successful call. The caller should use {@link SvrB#createNewBackupChain} only for the very first
+ * backup with a particular backup key.
  *
  * ## Restore Flow
  *
@@ -81,6 +108,7 @@ export type StoreBackupResponse = {
  * 3. Call {@link SvrB#fetchForwardSecrecyTokenFromServer} to get the forward secrecy token
  * 4. Use the token to derive decryption keys
  * 5. Decrypt and restore the backup data
+ * 6. Store the returned {@link RestoreBackupResponse#nextBackupSecretData} locally.
  *
  * ## Usage
  * ```typescript
@@ -105,26 +133,35 @@ export declare class SvrB {
         username: string;
         password: string;
     }>, environment: Environment);
+    /**
+     * Generates backup "secret data" for a fresh install.
+     *
+     * Should not be used if any previous backups exist for this `backupKey`, whether uploaded or
+     * restored by the local device. See {@link SvrB} for more information.
+     */
+    createNewBackupChain(backupKey: BackupKey): Uint8Array;
     /**
      * Prepares a backup for storage with forward secrecy guarantees.
      *
-     * This makes a network call to the SVR-B server to store the forward secrecy token
-     * and returns a {@link StoreBackupResponse}. See its fields' documentation and {@link SvrB}
-     * for how to continue persisting the backup on success.
+     * This makes a network call to the SVR-B server to store the forward secrecy token and returns a
+     * {@link StoreBackupResponse}. See its fields' documentation and {@link SvrB} for how to continue
+     * persisting the backup on success.
      *
      * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
      * @param previousSecretData Optional secret data from the most recent previous backup.
-     * **Critical**: This MUST be the {@link StoreBackupResponse#nextBackupSecretData} data
-     * from the last {@link #storeBackup} whose returned {@link StoreBackupResponse#metadata} was
+     * **Critical**: This MUST be the secret data from the most recent of the following:
+     * - the last {@link #store} call whose returned {@link StoreBackupResponse#metadata} was
      * successfully uploaded, and whose `nextBackupSecretData` was persisted.
-     * If `undefined`, starts a new chain and renders any prior backups unretrievable; this should
-     * only be used for the very first backup from a device.
+     * - the last {@link #restore} call
+     * - the already-persisted result from {@link #createNewBackupChain}, only if neither of the other
+     * two are available.
      * @param options Optional configuration.
      * @param options.abortSignal An AbortSignal that will cancel the request.
-     * @returns a {@link StoreBackupResponse} containing the forward secrecy token, metadata, and secret data.
-     * @throws Error if the previous secret data is malformed, or if  processing or upload fail.
+     * @returns a {@link StoreBackupResponse} containing the forward secrecy token, metadata, and
+     * secret data.
+     * @throws Error if the previous secret data is malformed, or if processing or upload fail.
      */
-    storeBackup(backupKey: BackupKey, previousSecretData?: Uint8Array, options?: {
+    store(backupKey: BackupKey, previousSecretData: Uint8Array, options?: {
         abortSignal?: AbortSignal;
     }): Promise<StoreBackupResponse>;
     /**
@@ -139,6 +176,7 @@ export declare class SvrB {
      * 2. Call this function to retrieve the forward secrecy token from SVR-B
      * 3. Use the token to derive message backup keys
      * 4. Decrypt and restore the backup data
+     * 5. Store the returned {@link RestoreBackupResponse#nextBackupSecretData} locally.
      *
      * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
      * @param metadata The metadata that was stored in a header in the backup file during backup creation.
@@ -148,8 +186,8 @@ export declare class SvrB {
      * @throws Error if the metadata is invalid, the network operation fails, or the
      *   backup cannot be found.
      */
-    fetchForwardSecrecyTokenFromServer(backupKey: BackupKey, metadata: Uint8Array, options?: {
+    restore(backupKey: BackupKey, metadata: Uint8Array, options?: {
         abortSignal?: AbortSignal;
-    }): Promise<BackupForwardSecrecyToken>;
+    }): Promise<RestoreBackupResponse>;
 }
 export {};

package/dist/net/SvrB.js

@@ -12,14 +12,26 @@ class StoreBackupResponseImpl {
         this._nativeHandle = handle;
     }
     get forwardSecrecyToken() {
-        const tokenBytes = Native.BackupResponse_GetForwardSecrecyToken(this);
+        const tokenBytes = Native.BackupStoreResponse_GetForwardSecrecyToken(this);
         return new AccountKeys_1.BackupForwardSecrecyToken(tokenBytes);
     }
     get metadata() {
-        return Native.BackupResponse_GetOpaqueMetadata(this);
+        return Native.BackupStoreResponse_GetOpaqueMetadata(this);
     }
     get nextBackupSecretData() {
-        return Native.BackupResponse_GetNextBackupSecretData(this);
+        return Native.BackupStoreResponse_GetNextBackupSecretData(this);
+    }
+}
+class RestoreBackupResponseImpl {
+    constructor(handle) {
+        this._nativeHandle = handle;
+    }
+    get forwardSecrecyToken() {
+        const tokenBytes = Native.BackupRestoreResponse_GetForwardSecrecyToken(this);
+        return new AccountKeys_1.BackupForwardSecrecyToken(tokenBytes);
+    }
+    get nextBackupSecretData() {
+        return Native.BackupRestoreResponse_GetNextBackupSecretData(this);
     }
 }
 /**
@@ -41,23 +53,24 @@ class StoreBackupResponseImpl {
  * ## Storage Flow
  *
  * 1. Create a {@link Net} instance and get the {@link SvrB} service via {@link Net#svrB}
- * 2. Call {@link SvrB#storeBackup}
- *    - Pass the secret data from the last **successful** {@link SvrB#storeBackup} call
- *    - If no previous backup exists or the secret data is unavailable, pass `undefined`
- * 3. Use the returned forward secrecy token to derive encryption keys
- * 4. Encrypt and upload the backup data to the user's remote, off-device storage location, including the
- *    returned {@link StoreBackupResponse#metadata}. The upload **must succeed**
+ * 2. If this is a fresh install, call {@link SvrB#createNewBackupChain} and store the result
+ *    locally. Otherwise, retrieve the secret data from the last **successful** backup operation
+ *    (store or restore).
+ * 3. Call {@link SvrB#store}
+ * 4. Use the returned forward secrecy token to derive encryption keys
+ * 5. Encrypt and upload the backup data to the user's remote, off-device storage location,
+ *    including the returned {@link StoreBackupResponse#metadata}. The upload **must succeed**
  *    before proceeding or the previous backup might become unretrievable.
- * 5. Store the {@link StoreBackupResponse#nextBackupSecretData} locally, overwriting any previously-saved value.
+ * 6. Store the {@link StoreBackupResponse#nextBackupSecretData} locally, overwriting any
+ *    previously-saved value.
  *
  * ## Secret handling
  *
- * When calling {@link SvrB#storeBackup}, the `previousSecretData` parameter
- * must be from the last call to {@link SvrB#storeBackup} that
- * succeeded. The returned secret from a successful `storeBackup()` call should
- * be persisted until it is overwritten by the value from a subsequent
- * successful call. The caller should pass `undefined` as `previousSecretData`
- * only for the very first backup from a device.
+ * When calling {@link SvrB#store}, the `previousSecretData` parameter must be from the last call to
+ * {@link SvrB#store} or {@link SvrB#restore} that succeeded. The returned secret from a successful
+ * store or restore should be persisted until it is overwritten by the value from a subsequent
+ * successful call. The caller should use {@link SvrB#createNewBackupChain} only for the very first
+ * backup with a particular backup key.
  *
  * ## Restore Flow
  *
@@ -66,6 +79,7 @@ class StoreBackupResponseImpl {
  * 3. Call {@link SvrB#fetchForwardSecrecyTokenFromServer} to get the forward secrecy token
  * 4. Use the token to derive decryption keys
  * 5. Decrypt and restore the backup data
+ * 6. Store the returned {@link RestoreBackupResponse#nextBackupSecretData} locally.
  *
  * ## Usage
  * ```typescript
@@ -88,28 +102,38 @@ class SvrB {
         this.auth = auth;
         this.environment = environment;
     }
+    /**
+     * Generates backup "secret data" for a fresh install.
+     *
+     * Should not be used if any previous backups exist for this `backupKey`, whether uploaded or
+     * restored by the local device. See {@link SvrB} for more information.
+     */
+    createNewBackupChain(backupKey) {
+        return Native.SecureValueRecoveryForBackups_CreateNewBackupChain(this.environment, backupKey.serialize());
+    }
     /**
      * Prepares a backup for storage with forward secrecy guarantees.
      *
-     * This makes a network call to the SVR-B server to store the forward secrecy token
-     * and returns a {@link StoreBackupResponse}. See its fields' documentation and {@link SvrB}
-     * for how to continue persisting the backup on success.
+     * This makes a network call to the SVR-B server to store the forward secrecy token and returns a
+     * {@link StoreBackupResponse}. See its fields' documentation and {@link SvrB} for how to continue
+     * persisting the backup on success.
      *
      * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
      * @param previousSecretData Optional secret data from the most recent previous backup.
-     * **Critical**: This MUST be the {@link StoreBackupResponse#nextBackupSecretData} data
-     * from the last {@link #storeBackup} whose returned {@link StoreBackupResponse#metadata} was
+     * **Critical**: This MUST be the secret data from the most recent of the following:
+     * - the last {@link #store} call whose returned {@link StoreBackupResponse#metadata} was
      * successfully uploaded, and whose `nextBackupSecretData` was persisted.
-     * If `undefined`, starts a new chain and renders any prior backups unretrievable; this should
-     * only be used for the very first backup from a device.
+     * - the last {@link #restore} call
+     * - the already-persisted result from {@link #createNewBackupChain}, only if neither of the other
+     * two are available.
      * @param options Optional configuration.
      * @param options.abortSignal An AbortSignal that will cancel the request.
-     * @returns a {@link StoreBackupResponse} containing the forward secrecy token, metadata, and secret data.
-     * @throws Error if the previous secret data is malformed, or if  processing or upload fail.
+     * @returns a {@link StoreBackupResponse} containing the forward secrecy token, metadata, and
+     * secret data.
+     * @throws Error if the previous secret data is malformed, or if processing or upload fail.
      */
-    async storeBackup(backupKey, previousSecretData, options) {
-        const secretData = previousSecretData ?? new Uint8Array(0);
-        const promise = Native.SecureValueRecoveryForBackups_StoreBackup(this.asyncContext, backupKey.serialize(), secretData, this.connectionManager, this.auth.username, this.auth.password);
+    async store(backupKey, previousSecretData, options) {
+        const promise = Native.SecureValueRecoveryForBackups_StoreBackup(this.asyncContext, backupKey.serialize(), previousSecretData, this.connectionManager, this.auth.username, this.auth.password);
         const response = await this.asyncContext.makeCancellable(options?.abortSignal, promise);
         return new StoreBackupResponseImpl(response);
     }
@@ -125,6 +149,7 @@ class SvrB {
      * 2. Call this function to retrieve the forward secrecy token from SVR-B
      * 3. Use the token to derive message backup keys
      * 4. Decrypt and restore the backup data
+     * 5. Store the returned {@link RestoreBackupResponse#nextBackupSecretData} locally.
      *
      * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
      * @param metadata The metadata that was stored in a header in the backup file during backup creation.
@@ -134,10 +159,10 @@ class SvrB {
      * @throws Error if the metadata is invalid, the network operation fails, or the
      *   backup cannot be found.
      */
-    async fetchForwardSecrecyTokenFromServer(backupKey, metadata, options) {
+    async restore(backupKey, metadata, options) {
         const promise = Native.SecureValueRecoveryForBackups_RestoreBackupFromServer(this.asyncContext, backupKey.serialize(), metadata, this.connectionManager, this.auth.username, this.auth.password);
-        const tokenBytes = await this.asyncContext.makeCancellable(options?.abortSignal, promise);
-        return new AccountKeys_1.BackupForwardSecrecyToken(tokenBytes);
+        const response = await this.asyncContext.makeCancellable(options?.abortSignal, promise);
+        return new RestoreBackupResponseImpl(response);
     }
 }
 exports.SvrB = SvrB;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalapp/libsignal-client",
-  "version": "0.77.1",
+  "version": "0.78.0",
   "license": "AGPL-3.0-only",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",