@signalapp/libsignal-client 0.78.0 → 0.78.2

package/dist/Errors.d.ts

@@ -35,8 +35,8 @@ export declare enum ErrorCode {
     SvrDataMissing = 31,
     SvrRequestFailed = 32,
     SvrRestoreFailed = 33,
-    SvrMultipleErrors = 34,
-    SvrAttestationError = 35,
+    SvrAttestationError = 34,
+    SvrInvalidData = 35,
     ChatServiceInactive = 36,
     AppExpired = 37,
     DeviceDelinked = 38,
@@ -188,12 +188,12 @@ export type SvrRestoreFailedError = LibSignalErrorCommon & {
     code: ErrorCode.SvrRestoreFailed;
     readonly triesRemaining: number;
 };
-export type SvrMultipleErrorsError = LibSignalErrorCommon & {
-    code: ErrorCode.SvrMultipleErrors;
-};
 export type SvrAttestationError = LibSignalErrorCommon & {
     code: ErrorCode.SvrAttestationError;
 };
+export type SvrInvalidDataError = LibSignalErrorCommon & {
+    code: ErrorCode.SvrInvalidData;
+};
 export type BackupValidationError = LibSignalErrorCommon & {
     code: ErrorCode.BackupValidation;
     readonly unknownFields: ReadonlyArray<string>;
@@ -207,4 +207,4 @@ export type KeyTransparencyError = LibSignalErrorCommon & {
 export type KeyTransparencyVerificationFailed = LibSignalErrorCommon & {
     code: ErrorCode.KeyTransparencyVerificationFailed;
 };
-export type LibSignalError = GenericError | DuplicatedMessageError | SealedSenderSelfSendError | UntrustedIdentityError | InvalidRegistrationIdError | InvalidProtocolAddress | VerificationFailedError | InvalidSessionError | InvalidSenderKeySessionError | NicknameCannotBeEmptyError | CannotStartWithDigitError | MissingSeparatorError | BadNicknameCharacterError | NicknameTooShortError | NicknameTooLongError | DiscriminatorCannotBeEmptyError | DiscriminatorCannotBeZeroError | DiscriminatorCannotBeSingleDigitError | DiscriminatorCannotHaveLeadingZerosError | BadDiscriminatorCharacterError | DiscriminatorTooLargeError | InputDataTooLong | InvalidEntropyDataLength | InvalidUsernameLinkEncryptedData | IoError | CdsiInvalidTokenError | InvalidUriError | InvalidMediaInputError | SvrDataMissingError | SvrRestoreFailedError | SvrRequestFailedError | SvrMultipleErrorsError | SvrAttestationError | UnsupportedMediaInputError | ChatServiceInactive | AppExpiredError | DeviceDelinkedError | ConnectionInvalidatedError | ConnectedElsewhereError | RateLimitedError | RateLimitChallengeError | BackupValidationError | CancellationError | KeyTransparencyError | KeyTransparencyVerificationFailed;
+export type LibSignalError = GenericError | DuplicatedMessageError | SealedSenderSelfSendError | UntrustedIdentityError | InvalidRegistrationIdError | InvalidProtocolAddress | VerificationFailedError | InvalidSessionError | InvalidSenderKeySessionError | NicknameCannotBeEmptyError | CannotStartWithDigitError | MissingSeparatorError | BadNicknameCharacterError | NicknameTooShortError | NicknameTooLongError | DiscriminatorCannotBeEmptyError | DiscriminatorCannotBeZeroError | DiscriminatorCannotBeSingleDigitError | DiscriminatorCannotHaveLeadingZerosError | BadDiscriminatorCharacterError | DiscriminatorTooLargeError | InputDataTooLong | InvalidEntropyDataLength | InvalidUsernameLinkEncryptedData | IoError | CdsiInvalidTokenError | InvalidUriError | InvalidMediaInputError | SvrDataMissingError | SvrRestoreFailedError | SvrRequestFailedError | SvrAttestationError | SvrInvalidDataError | UnsupportedMediaInputError | ChatServiceInactive | AppExpiredError | DeviceDelinkedError | ConnectionInvalidatedError | ConnectedElsewhereError | RateLimitedError | RateLimitChallengeError | BackupValidationError | CancellationError | KeyTransparencyError | KeyTransparencyVerificationFailed;

package/dist/Errors.js

@@ -42,8 +42,8 @@ var ErrorCode;
     ErrorCode[ErrorCode["SvrDataMissing"] = 31] = "SvrDataMissing";
     ErrorCode[ErrorCode["SvrRequestFailed"] = 32] = "SvrRequestFailed";
     ErrorCode[ErrorCode["SvrRestoreFailed"] = 33] = "SvrRestoreFailed";
-    ErrorCode[ErrorCode["SvrMultipleErrors"] = 34] = "SvrMultipleErrors";
-    ErrorCode[ErrorCode["SvrAttestationError"] = 35] = "SvrAttestationError";
+    ErrorCode[ErrorCode["SvrAttestationError"] = 34] = "SvrAttestationError";
+    ErrorCode[ErrorCode["SvrInvalidData"] = 35] = "SvrInvalidData";
     ErrorCode[ErrorCode["ChatServiceInactive"] = 36] = "ChatServiceInactive";
     ErrorCode[ErrorCode["AppExpired"] = 37] = "AppExpired";
     ErrorCode[ErrorCode["DeviceDelinked"] = 38] = "DeviceDelinked";

package/dist/net/SvrB.d.ts

@@ -96,10 +96,13 @@ export type RestoreBackupResponse = {
  * ## Secret handling
  *
  * 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.
+ * {@link SvrB#store} or {@link SvrB#restore} that succeeded. This "chaining" is used to construct
+ * each backup file so that it can be decrypted with either the *previous* token stored in SVR-B, or
+ * the *next* one, which is important in case the overall backup upload is ever interrupted.
+ *
+ * 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
  *
@@ -159,7 +162,14 @@ export declare class SvrB {
      * @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.
+     * @throws {SvrInvalidDataError} if the previous secret data is malformed. There's no choice here
+     * but to **start a new chain**.
+     * @throws {RateLimitedError} if the server is rate limiting this client. This is **retryable**
+     * after waiting the designated delay.
+     * @throws {IoError} if the network operation fails (connection, service, or timeout errors).
+     * These are **retryable**, but some may indicate a possible bug in libsignal or in the enclave.
+     * @throws {SvrAttestationError} if enclave attestation fails. This indicates a possible bug in
+     * libsignal or in the enclave.
      */
     store(backupKey: BackupKey, previousSecretData: Uint8Array, options?: {
         abortSignal?: AbortSignal;
@@ -168,8 +178,8 @@ export declare class SvrB {
      * Fetches the forward secrecy token needed to decrypt a backup.
      *
      * This function makes a network call to the SVR-B server to retrieve the forward secrecy token
-     * associated with a specific backup. The token is required to derive the message backup keys
-     * for decryption.
+     * associated with a specific backup. The token is required to derive the message backup keys for
+     * decryption.
      *
      * The typical restore flow:
      * 1. Fetch the backup metadata (stored in a header in the backup file)
@@ -179,12 +189,23 @@ export declare class SvrB {
      * 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.
+     * @param metadata The metadata that was stored in a header in the backup file during backup
+     * creation.
      * @param options Optional configuration.
      * @param options.abortSignal An AbortSignal that will cancel the request.
      * @returns The forward secrecy token needed to derive keys for decrypting the backup.
-     * @throws Error if the metadata is invalid, the network operation fails, or the
-     *   backup cannot be found.
+     * @throws {SvrInvalidDataError} if the previous secret data is malformed. In this case the user's
+     * data is **not recoverable**.
+     * @throws {SvrRestoreFailedError} if restoration fails (with remaining tries count). This should
+     * never happen but if it does the user's data is **not recoverable**.
+     * @throws {SvrDataMissingError} if the backup data is not found on the server, indicating an
+     * **incorrect backup key** (which may in turn imply the user's data is not recoverable).
+     * @throws {RateLimitedError} if the server is rate limiting this client. This is **retryable**
+     * after waiting the designated delay.
+     * @throws {IoError} if the network operation fails (connection, service, or timeout errors).
+     * These are **retryable**, but some may indicate a possible bug in libsignal or in the enclave.
+     * @throws {SvrAttestationError} if enclave attestation fails. This indicates a possible bug in
+     * libsignal or in the enclave.
      */
     restore(backupKey: BackupKey, metadata: Uint8Array, options?: {
         abortSignal?: AbortSignal;

package/dist/net/SvrB.js

@@ -67,10 +67,13 @@ class RestoreBackupResponseImpl {
  * ## Secret handling
  *
  * 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.
+ * {@link SvrB#store} or {@link SvrB#restore} that succeeded. This "chaining" is used to construct
+ * each backup file so that it can be decrypted with either the *previous* token stored in SVR-B, or
+ * the *next* one, which is important in case the overall backup upload is ever interrupted.
+ *
+ * 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
  *
@@ -130,7 +133,14 @@ class SvrB {
      * @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.
+     * @throws {SvrInvalidDataError} if the previous secret data is malformed. There's no choice here
+     * but to **start a new chain**.
+     * @throws {RateLimitedError} if the server is rate limiting this client. This is **retryable**
+     * after waiting the designated delay.
+     * @throws {IoError} if the network operation fails (connection, service, or timeout errors).
+     * These are **retryable**, but some may indicate a possible bug in libsignal or in the enclave.
+     * @throws {SvrAttestationError} if enclave attestation fails. This indicates a possible bug in
+     * libsignal or in the enclave.
      */
     async store(backupKey, previousSecretData, options) {
         const promise = Native.SecureValueRecoveryForBackups_StoreBackup(this.asyncContext, backupKey.serialize(), previousSecretData, this.connectionManager, this.auth.username, this.auth.password);
@@ -141,8 +151,8 @@ class SvrB {
      * Fetches the forward secrecy token needed to decrypt a backup.
      *
      * This function makes a network call to the SVR-B server to retrieve the forward secrecy token
-     * associated with a specific backup. The token is required to derive the message backup keys
-     * for decryption.
+     * associated with a specific backup. The token is required to derive the message backup keys for
+     * decryption.
      *
      * The typical restore flow:
      * 1. Fetch the backup metadata (stored in a header in the backup file)
@@ -152,12 +162,23 @@ class SvrB {
      * 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.
+     * @param metadata The metadata that was stored in a header in the backup file during backup
+     * creation.
      * @param options Optional configuration.
      * @param options.abortSignal An AbortSignal that will cancel the request.
      * @returns The forward secrecy token needed to derive keys for decrypting the backup.
-     * @throws Error if the metadata is invalid, the network operation fails, or the
-     *   backup cannot be found.
+     * @throws {SvrInvalidDataError} if the previous secret data is malformed. In this case the user's
+     * data is **not recoverable**.
+     * @throws {SvrRestoreFailedError} if restoration fails (with remaining tries count). This should
+     * never happen but if it does the user's data is **not recoverable**.
+     * @throws {SvrDataMissingError} if the backup data is not found on the server, indicating an
+     * **incorrect backup key** (which may in turn imply the user's data is not recoverable).
+     * @throws {RateLimitedError} if the server is rate limiting this client. This is **retryable**
+     * after waiting the designated delay.
+     * @throws {IoError} if the network operation fails (connection, service, or timeout errors).
+     * These are **retryable**, but some may indicate a possible bug in libsignal or in the enclave.
+     * @throws {SvrAttestationError} if enclave attestation fails. This indicates a possible bug in
+     * libsignal or in the enclave.
      */
     async restore(backupKey, metadata, options) {
         const promise = Native.SecureValueRecoveryForBackups_RestoreBackupFromServer(this.asyncContext, backupKey.serialize(), metadata, this.connectionManager, this.auth.username, this.auth.password);

package/package.json

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