@signalapp/libsignal-client 0.76.7 → 0.77.1

package/Native.d.ts

@@ -228,6 +228,9 @@ 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 BridgedStringMap_insert(map: Wrapper<BridgedStringMap>, key: string, value: string): void;
 export function BridgedStringMap_new(initialCapacity: number): BridgedStringMap;
 export function CallLinkAuthCredentialPresentation_CheckValidContents(presentationBytes: Uint8Array): void;
@@ -373,8 +376,8 @@ export function LookupRequest_addE164(request: Wrapper<LookupRequest>, e164: str
 export function LookupRequest_addPreviousE164(request: Wrapper<LookupRequest>, e164: string): void;
 export function LookupRequest_new(): LookupRequest;
 export function LookupRequest_setToken(request: Wrapper<LookupRequest>, token: Uint8Array): void;
-export function MessageBackupKey_FromAccountEntropyPool(accountEntropy: AccountEntropyPool, aci: Uint8Array): MessageBackupKey;
-export function MessageBackupKey_FromBackupKeyAndBackupId(backupKey: Uint8Array, backupId: Uint8Array): MessageBackupKey;
+export function MessageBackupKey_FromAccountEntropyPool(accountEntropy: AccountEntropyPool, aci: Uint8Array, forwardSecrecyToken: Uint8Array | null): MessageBackupKey;
+export function MessageBackupKey_FromBackupKeyAndBackupId(backupKey: Uint8Array, backupId: Uint8Array, forwardSecrecyToken: Uint8Array | null): MessageBackupKey;
 export function MessageBackupKey_GetAesKey(key: Wrapper<MessageBackupKey>): Uint8Array;
 export function MessageBackupKey_GetHmacKey(key: Wrapper<MessageBackupKey>): Uint8Array;
 export function MessageBackupValidator_Validate(key: Wrapper<MessageBackupKey>, firstStream: InputStream, secondStream: InputStream, len: bigint, purpose: number): Promise<MessageBackupValidationOutcome>;
@@ -498,6 +501,8 @@ 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 SenderCertificate_Deserialize(data: Uint8Array): SenderCertificate;
 export function SenderCertificate_GetCertificate(obj: Wrapper<SenderCertificate>): Uint8Array;
 export function SenderCertificate_GetDeviceId(obj: Wrapper<SenderCertificate>): number;
@@ -609,7 +614,7 @@ export function TESTING_ChatRequestGetPath(request: Wrapper<HttpRequest>): strin
 export function TESTING_ChatResponseConvert(bodyPresent: boolean): ChatResponse;
 export function TESTING_ChatSendErrorConvert(errorDescription: string): void;
 export function TESTING_ConnectionManager_isUsingProxy(manager: Wrapper<ConnectionManager>): number;
-export function TESTING_ConnectionManager_newLocalOverride(userAgent: string, chatPort: number, cdsiPort: number, svr2Port: number, rootCertificateDer: Uint8Array): ConnectionManager;
+export function TESTING_ConnectionManager_newLocalOverride(userAgent: string, chatPort: number, cdsiPort: number, svr2Port: number, svrBPort: number, rootCertificateDer: Uint8Array): ConnectionManager;
 export function TESTING_ConvertOptionalUuid(present: boolean): Uuid | null;
 export function TESTING_ErrorOnBorrowAsync(_input: null): Promise<void>;
 export function TESTING_ErrorOnBorrowIo(asyncRuntime: Wrapper<NonSuspendingBackgroundThreadRuntime>, _input: null): CancellablePromise<void>;
@@ -714,6 +719,7 @@ 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 BridgedStringMap { readonly __type: unique symbol; }
 interface CdsiLookup { readonly __type: unique symbol; }
 interface ChatConnectionInfo { readonly __type: unique symbol; }

package/dist/AccountKeys.d.ts

@@ -99,3 +99,14 @@ export declare class BackupKey extends ByteArray {
      */
     deriveThumbnailTransitEncryptionKey(mediaId: Uint8Array): Uint8Array;
 }
+/**
+ * A forward secrecy token used for deriving message backup keys.
+ *
+ * This token is retrieved from the server when restoring a backup and is used together
+ * with the backup key to derive the actual encryption keys for message backups.
+ */
+export declare class BackupForwardSecrecyToken extends ByteArray {
+    private readonly __type?;
+    static SIZE: number;
+    constructor(contents: Uint8Array);
+}

package/dist/AccountKeys.js

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 //
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BackupKey = exports.AccountEntropyPool = void 0;
+exports.BackupForwardSecrecyToken = exports.BackupKey = exports.AccountEntropyPool = void 0;
 /**
  * Cryptographic hashing, randomness generation, etc. related to SVR/Backup Keys.
  *
@@ -140,4 +140,17 @@ class BackupKey extends ByteArray_1.default {
 }
 exports.BackupKey = BackupKey;
 BackupKey.SIZE = 32;
+/**
+ * A forward secrecy token used for deriving message backup keys.
+ *
+ * This token is retrieved from the server when restoring a backup and is used together
+ * with the backup key to derive the actual encryption keys for message backups.
+ */
+class BackupForwardSecrecyToken extends ByteArray_1.default {
+    constructor(contents) {
+        super(contents, BackupForwardSecrecyToken.checkLength(BackupForwardSecrecyToken.SIZE));
+    }
+}
+exports.BackupForwardSecrecyToken = BackupForwardSecrecyToken;
+BackupForwardSecrecyToken.SIZE = 32;
 //# sourceMappingURL=AccountKeys.js.map

package/dist/Errors.d.ts

@@ -35,15 +35,17 @@ export declare enum ErrorCode {
     SvrDataMissing = 31,
     SvrRequestFailed = 32,
     SvrRestoreFailed = 33,
-    ChatServiceInactive = 34,
-    AppExpired = 35,
-    DeviceDelinked = 36,
-    ConnectionInvalidated = 37,
-    ConnectedElsewhere = 38,
-    BackupValidation = 39,
-    Cancelled = 40,
-    KeyTransparencyError = 41,
-    KeyTransparencyVerificationFailed = 42
+    SvrMultipleErrors = 34,
+    SvrAttestationError = 35,
+    ChatServiceInactive = 36,
+    AppExpired = 37,
+    DeviceDelinked = 38,
+    ConnectionInvalidated = 39,
+    ConnectedElsewhere = 40,
+    BackupValidation = 41,
+    Cancelled = 42,
+    KeyTransparencyError = 43,
+    KeyTransparencyVerificationFailed = 44
 }
 export declare class LibSignalErrorBase extends Error {
     readonly code: ErrorCode;
@@ -186,6 +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 BackupValidationError = LibSignalErrorCommon & {
     code: ErrorCode.BackupValidation;
     readonly unknownFields: ReadonlyArray<string>;
@@ -199,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 | 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 | SvrMultipleErrorsError | SvrAttestationError | UnsupportedMediaInputError | ChatServiceInactive | AppExpiredError | DeviceDelinkedError | ConnectionInvalidatedError | ConnectedElsewhereError | RateLimitedError | RateLimitChallengeError | BackupValidationError | CancellationError | KeyTransparencyError | KeyTransparencyVerificationFailed;

package/dist/Errors.js

@@ -42,15 +42,17 @@ var ErrorCode;
     ErrorCode[ErrorCode["SvrDataMissing"] = 31] = "SvrDataMissing";
     ErrorCode[ErrorCode["SvrRequestFailed"] = 32] = "SvrRequestFailed";
     ErrorCode[ErrorCode["SvrRestoreFailed"] = 33] = "SvrRestoreFailed";
-    ErrorCode[ErrorCode["ChatServiceInactive"] = 34] = "ChatServiceInactive";
-    ErrorCode[ErrorCode["AppExpired"] = 35] = "AppExpired";
-    ErrorCode[ErrorCode["DeviceDelinked"] = 36] = "DeviceDelinked";
-    ErrorCode[ErrorCode["ConnectionInvalidated"] = 37] = "ConnectionInvalidated";
-    ErrorCode[ErrorCode["ConnectedElsewhere"] = 38] = "ConnectedElsewhere";
-    ErrorCode[ErrorCode["BackupValidation"] = 39] = "BackupValidation";
-    ErrorCode[ErrorCode["Cancelled"] = 40] = "Cancelled";
-    ErrorCode[ErrorCode["KeyTransparencyError"] = 41] = "KeyTransparencyError";
-    ErrorCode[ErrorCode["KeyTransparencyVerificationFailed"] = 42] = "KeyTransparencyVerificationFailed";
+    ErrorCode[ErrorCode["SvrMultipleErrors"] = 34] = "SvrMultipleErrors";
+    ErrorCode[ErrorCode["SvrAttestationError"] = 35] = "SvrAttestationError";
+    ErrorCode[ErrorCode["ChatServiceInactive"] = 36] = "ChatServiceInactive";
+    ErrorCode[ErrorCode["AppExpired"] = 37] = "AppExpired";
+    ErrorCode[ErrorCode["DeviceDelinked"] = 38] = "DeviceDelinked";
+    ErrorCode[ErrorCode["ConnectionInvalidated"] = 39] = "ConnectionInvalidated";
+    ErrorCode[ErrorCode["ConnectedElsewhere"] = 40] = "ConnectedElsewhere";
+    ErrorCode[ErrorCode["BackupValidation"] = 41] = "BackupValidation";
+    ErrorCode[ErrorCode["Cancelled"] = 42] = "Cancelled";
+    ErrorCode[ErrorCode["KeyTransparencyError"] = 43] = "KeyTransparencyError";
+    ErrorCode[ErrorCode["KeyTransparencyVerificationFailed"] = 44] = "KeyTransparencyVerificationFailed";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
 class LibSignalErrorBase extends Error {
     constructor(message, name, operation, extraProps) {

package/dist/MessageBackup.d.ts

@@ -4,7 +4,7 @@
  * @module MessageBackup
  */
 import * as Native from '../Native';
-import { BackupKey } from './AccountKeys';
+import { BackupForwardSecrecyToken, BackupKey } from './AccountKeys';
 import { Aci } from './Address';
 import { InputStream } from './io';
 export type InputStreamFactory = () => InputStream;
@@ -32,9 +32,11 @@ export declare class ValidationOutcome {
 export type MessageBackupKeyInput = Readonly<{
     accountEntropy: string;
     aci: Aci;
+    forwardSecrecyToken?: BackupForwardSecrecyToken;
 } | {
     backupKey: BackupKey | Uint8Array;
     backupId: Uint8Array;
+    forwardSecrecyToken?: BackupForwardSecrecyToken;
 }>;
 /**
  * Key used to encrypt and decrypt a message backup bundle.
@@ -47,8 +49,7 @@ export declare class MessageBackupKey {
      * Create a backup bundle key from an account entropy pool and ACI.
      *
      * ...or from a backup key and ID, used when reading from a local backup, which may have been
-     * created with a different ACI. This still uses AccountEntropyPool-based key derivation rules; it
-     * cannot be used to read a backup created from a master key.
+     * created with a different ACI.
      *
      * The account entropy pool must be **validated**; passing an arbitrary string here is considered
      * a programmer error. Similarly, passing a backup key or ID of the wrong length is also an error.

package/dist/MessageBackup.js

@@ -41,24 +41,23 @@ class MessageBackupKey {
      * Create a backup bundle key from an account entropy pool and ACI.
      *
      * ...or from a backup key and ID, used when reading from a local backup, which may have been
-     * created with a different ACI. This still uses AccountEntropyPool-based key derivation rules; it
-     * cannot be used to read a backup created from a master key.
+     * created with a different ACI.
      *
      * The account entropy pool must be **validated**; passing an arbitrary string here is considered
      * a programmer error. Similarly, passing a backup key or ID of the wrong length is also an error.
      */
     constructor(input) {
         if ('accountEntropy' in input) {
-            const { accountEntropy, aci } = input;
-            this._nativeHandle = Native.MessageBackupKey_FromAccountEntropyPool(accountEntropy, aci.getServiceIdFixedWidthBinary());
+            const { accountEntropy, aci, forwardSecrecyToken } = input;
+            this._nativeHandle = Native.MessageBackupKey_FromAccountEntropyPool(accountEntropy, aci.getServiceIdFixedWidthBinary(), forwardSecrecyToken?.contents ?? null);
         }
         else {
-            const { backupId } = input;
+            const { backupId, forwardSecrecyToken } = input;
             let { backupKey } = input;
             if (backupKey instanceof AccountKeys_1.BackupKey) {
                 backupKey = backupKey.contents;
             }
-            this._nativeHandle = Native.MessageBackupKey_FromBackupKeyAndBackupId(backupKey, backupId);
+            this._nativeHandle = Native.MessageBackupKey_FromBackupKeyAndBackupId(backupKey, backupId, forwardSecrecyToken?.contents ?? null);
         }
     }
     /** An HMAC key used to sign a backup file. */

package/dist/acknowledgments.md

@@ -2,7 +2,7 @@
 
 libsignal makes use of the following open source projects.
 
-## spqr 0.1.0, partial-default-derive 0.1.0, partial-default 0.1.0
+## spqr 1.2.0, partial-default-derive 0.1.0, partial-default 0.1.0
 
 ```
                     GNU AFFERO GENERAL PUBLIC LICENSE

package/dist/net/SvrB.d.ts

@@ -0,0 +1,155 @@
+import * as Native from '../../Native';
+import { TokioAsyncContext, Environment } from '../net';
+import { BackupKey, BackupForwardSecrecyToken } from '../AccountKeys';
+type ConnectionManager = Native.Wrapper<Native.ConnectionManager>;
+/**
+ * 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 StoreBackupResponse = {
+    /**
+     * 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 metadata that must be stored in the backup file.
+     *
+     * This metadata contains the encrypted forward secrecy token and other information required
+     * to restore the backup. It must be retrievable when restoring the backup, as it's required
+     * to fetch the forward secrecy token from SVR-B. This is currently stored in the header of
+     * the backup file.
+     */
+    metadata: Uint8Array;
+    /**
+     * Opaque value that must be persisted and provided to the next call to {@link SvrB#storeBackup}.
+     *
+     * See the {@link SvrB} documentation for lifecycle and persistence handling
+     * for this value.
+     */
+    nextBackupSecretData: Uint8Array;
+};
+/**
+ * Service for Secure Value Recovery for Backups (SVR-B) operations.
+ *
+ * This service provides forward secrecy for Signal backups using SVR-B. Forward secrecy ensures
+ * that even if the user's Account Entropy Pool or Backup Key is compromised, the attacker can
+ * decrypt a very small number of past backups. This is achieved by storing a token
+ * in a secure enclave inside the SVR-B server, which provably attests that it
+ * only stores a single token at a time for each user.
+ *
+ * ## Overview
+ *
+ * To achieve these properties, a secret token is required to derive the actual encryption
+ * keys for the backup. At backup time, this token must be stored in the SVR-B server, overwriting the
+ * previous token. At restore time, the token must be retrieved from the SVR-B server, and used to
+ * derive the encryption keys for the backup.
+ *
+ * ## 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**
+ *    before proceeding or the previous backup might become unretrievable.
+ * 5. 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.
+ *
+ * ## Restore Flow
+ *
+ * 1. Create a {@link Net} instance and get the {@link SvrB} service via {@link Net#svrB}
+ * 2. Fetch the backup metadata from storage
+ * 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
+ *
+ * ## Usage
+ * ```typescript
+ * const net = new Net({ env: Environment.Production, userAgent: 'MyApp' });
+ * const auth = { username: 'myUsername', password: 'myPassword' };
+ * const svrB = net.svrB(auth);
+ *
+ * // Prepare a backup
+ * const stored = await svrB.storeBackup(myKey, previousSecretData);
+ * // ... store backup with stored.forwardSecrecyToken remotely ...
+ * // Securely persist stored.nextBackupSecretData for the next backup
+ * ```
+ *
+ * @see {@link BackupKey}, {@link MessageBackupKey}, {@link BackupForwardSecrecyToken}
+ */
+export declare class SvrB {
+    private readonly asyncContext;
+    private readonly connectionManager;
+    private readonly auth;
+    private readonly environment;
+    constructor(asyncContext: TokioAsyncContext, connectionManager: ConnectionManager, auth: Readonly<{
+        username: string;
+        password: string;
+    }>, environment: Environment);
+    /**
+     * 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.
+     *
+     * @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
+     * 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.
+     * @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.
+     */
+    storeBackup(backupKey: BackupKey, previousSecretData?: Uint8Array, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<StoreBackupResponse>;
+    /**
+     * 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.
+     *
+     * The typical restore flow:
+     * 1. Fetch the backup metadata (stored in a header in the backup file)
+     * 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
+     *
+     * @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 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.
+     */
+    fetchForwardSecrecyTokenFromServer(backupKey: BackupKey, metadata: Uint8Array, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<BackupForwardSecrecyToken>;
+}
+export {};

package/dist/net/SvrB.js

@@ -0,0 +1,144 @@
+"use strict";
+//
+// Copyright 2025 Signal Messenger, LLC.
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SvrB = void 0;
+const Native = require("../../Native");
+const AccountKeys_1 = require("../AccountKeys");
+class StoreBackupResponseImpl {
+    constructor(handle) {
+        this._nativeHandle = handle;
+    }
+    get forwardSecrecyToken() {
+        const tokenBytes = Native.BackupResponse_GetForwardSecrecyToken(this);
+        return new AccountKeys_1.BackupForwardSecrecyToken(tokenBytes);
+    }
+    get metadata() {
+        return Native.BackupResponse_GetOpaqueMetadata(this);
+    }
+    get nextBackupSecretData() {
+        return Native.BackupResponse_GetNextBackupSecretData(this);
+    }
+}
+/**
+ * Service for Secure Value Recovery for Backups (SVR-B) operations.
+ *
+ * This service provides forward secrecy for Signal backups using SVR-B. Forward secrecy ensures
+ * that even if the user's Account Entropy Pool or Backup Key is compromised, the attacker can
+ * decrypt a very small number of past backups. This is achieved by storing a token
+ * in a secure enclave inside the SVR-B server, which provably attests that it
+ * only stores a single token at a time for each user.
+ *
+ * ## Overview
+ *
+ * To achieve these properties, a secret token is required to derive the actual encryption
+ * keys for the backup. At backup time, this token must be stored in the SVR-B server, overwriting the
+ * previous token. At restore time, the token must be retrieved from the SVR-B server, and used to
+ * derive the encryption keys for the backup.
+ *
+ * ## 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**
+ *    before proceeding or the previous backup might become unretrievable.
+ * 5. 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.
+ *
+ * ## Restore Flow
+ *
+ * 1. Create a {@link Net} instance and get the {@link SvrB} service via {@link Net#svrB}
+ * 2. Fetch the backup metadata from storage
+ * 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
+ *
+ * ## Usage
+ * ```typescript
+ * const net = new Net({ env: Environment.Production, userAgent: 'MyApp' });
+ * const auth = { username: 'myUsername', password: 'myPassword' };
+ * const svrB = net.svrB(auth);
+ *
+ * // Prepare a backup
+ * const stored = await svrB.storeBackup(myKey, previousSecretData);
+ * // ... store backup with stored.forwardSecrecyToken remotely ...
+ * // Securely persist stored.nextBackupSecretData for the next backup
+ * ```
+ *
+ * @see {@link BackupKey}, {@link MessageBackupKey}, {@link BackupForwardSecrecyToken}
+ */
+class SvrB {
+    constructor(asyncContext, connectionManager, auth, environment) {
+        this.asyncContext = asyncContext;
+        this.connectionManager = connectionManager;
+        this.auth = auth;
+        this.environment = environment;
+    }
+    /**
+     * 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.
+     *
+     * @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
+     * 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.
+     * @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.
+     */
+    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);
+        const response = await this.asyncContext.makeCancellable(options?.abortSignal, promise);
+        return new StoreBackupResponseImpl(response);
+    }
+    /**
+     * 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.
+     *
+     * The typical restore flow:
+     * 1. Fetch the backup metadata (stored in a header in the backup file)
+     * 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
+     *
+     * @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 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.
+     */
+    async fetchForwardSecrecyTokenFromServer(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);
+    }
+}
+exports.SvrB = SvrB;
+//# sourceMappingURL=SvrB.js.map

package/dist/net.d.ts

@@ -3,9 +3,11 @@ import * as Native from '../Native';
 import { CDSRequestOptionsType, CDSResponseType } from './net/CDSI';
 import { ConnectionEventsListener, UnauthenticatedChatConnection, AuthenticatedChatConnection, ChatServiceListener } from './net/Chat';
 import { RegistrationService } from './net/Registration';
+import { SvrB } from './net/SvrB';
 export * from './net/CDSI';
 export * from './net/Chat';
 export * from './net/Registration';
+export * from './net/SvrB';
 export declare enum Environment {
     Staging = 0,
     Production = 1
@@ -39,6 +41,7 @@ export type NetConstructorOptions = Readonly<{
     TESTING_localServer_chatPort: number;
     TESTING_localServer_cdsiPort: number;
     TESTING_localServer_svr2Port: number;
+    TESTING_localServer_svrBPort: number;
     TESTING_localServer_rootCertificateDer: Uint8Array;
 }>;
 /** See {@link Net.setProxy()}. */
@@ -214,4 +217,18 @@ export declare class Net {
      */
     onNetworkChange(): void;
     cdsiLookup(auth: Readonly<ServiceAuth>, options: ReadonlyDeep<CDSRequestOptionsType>): Promise<CDSResponseType<string, string>>;
+    /**
+     * Get the SVR-B (Secure Value Recovery for Backups) service for this network instance.
+     *
+     * SVR-B provides forward secrecy for Signal backups, ensuring that even if the user's
+     * Account Entropy Pool or Backup Key is compromised, the attacker cannot
+     * compromise all past backups. This is achieved by storing the forward
+     * secrecy token in a secure enclave inside the SVR-B server, which provably
+     * attests that it only stores a single token at a time for each user.
+     *
+     * @param auth The authentication credentials to use when connecting to the SVR-B server.
+     * @returns An SvrB service instance configured for this network environment
+     * @see {@link SvrB}
+     */
+    svrB(auth: Readonly<ServiceAuth>): SvrB;
 }

package/dist/net.js

@@ -23,10 +23,12 @@ const Native = require("../Native");
 const CDSI_1 = require("./net/CDSI");
 const Chat_1 = require("./net/Chat");
 const Registration_1 = require("./net/Registration");
+const SvrB_1 = require("./net/SvrB");
 const internal_1 = require("./internal");
 __exportStar(require("./net/CDSI"), exports);
 __exportStar(require("./net/Chat"), exports);
 __exportStar(require("./net/Registration"), exports);
+__exportStar(require("./net/SvrB"), exports);
 // This must match the libsignal-bridge Rust enum of the same name.
 var Environment;
 (function (Environment) {
@@ -62,7 +64,7 @@ class Net {
         this.options = options;
         this.asyncContext = new TokioAsyncContext(Native.TokioAsyncContext_new());
         if (options.localTestServer) {
-            this._connectionManager = (0, internal_1.newNativeHandle)(Native.TESTING_ConnectionManager_newLocalOverride(options.userAgent, options.TESTING_localServer_chatPort, options.TESTING_localServer_cdsiPort, options.TESTING_localServer_svr2Port, options.TESTING_localServer_rootCertificateDer));
+            this._connectionManager = (0, internal_1.newNativeHandle)(Native.TESTING_ConnectionManager_newLocalOverride(options.userAgent, options.TESTING_localServer_chatPort, options.TESTING_localServer_cdsiPort, options.TESTING_localServer_svr2Port, options.TESTING_localServer_svrBPort, options.TESTING_localServer_rootCertificateDer));
         }
         else {
             this._connectionManager = (0, internal_1.newNativeHandle)(Native.ConnectionManager_new(options.env, options.userAgent, new internal_1.BridgedStringMap(options.remoteConfig || new Map())));
@@ -282,6 +284,25 @@ class Net {
             connectionManager: this._connectionManager,
         }, auth, options);
     }
+    /**
+     * Get the SVR-B (Secure Value Recovery for Backups) service for this network instance.
+     *
+     * SVR-B provides forward secrecy for Signal backups, ensuring that even if the user's
+     * Account Entropy Pool or Backup Key is compromised, the attacker cannot
+     * compromise all past backups. This is achieved by storing the forward
+     * secrecy token in a secure enclave inside the SVR-B server, which provably
+     * attests that it only stores a single token at a time for each user.
+     *
+     * @param auth The authentication credentials to use when connecting to the SVR-B server.
+     * @returns An SvrB service instance configured for this network environment
+     * @see {@link SvrB}
+     */
+    svrB(auth) {
+        const env = this.options.localTestServer
+            ? Environment.Staging
+            : this.options.env;
+        return new SvrB_1.SvrB(this.asyncContext, this._connectionManager, auth, env);
+    }
 }
 exports.Net = Net;
 //# sourceMappingURL=net.js.map

package/package.json

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