@signalapp/libsignal-client 0.39.2 → 0.40.0

package/dist/zkgroup/groups/UuidCiphertext.js

@@ -10,6 +10,22 @@ class UuidCiphertext extends ByteArray_1.default {
     constructor(contents) {
         super(contents, Native.UuidCiphertext_CheckValidContents);
     }
+    static serializeAndConcatenate(ciphertexts) {
+        if (ciphertexts.length == 0) {
+            return Buffer.of();
+        }
+        const uuidCiphertextLen = ciphertexts[0].contents.length;
+        const concatenated = Buffer.alloc(ciphertexts.length * uuidCiphertextLen);
+        let offset = 0;
+        for (const next of ciphertexts) {
+            if (next.contents.length !== uuidCiphertextLen) {
+                throw TypeError('UuidCiphertext with unexpected length');
+            }
+            concatenated.set(next.contents, offset);
+            offset += uuidCiphertextLen;
+        }
+        return concatenated;
+    }
 }
 exports.default = UuidCiphertext;
 //# sourceMappingURL=UuidCiphertext.js.map

package/dist/zkgroup/groupsend/GroupSendCredential.d.ts

@@ -2,9 +2,29 @@
 import ByteArray from '../internal/ByteArray';
 import GroupSendCredentialPresentation from './GroupSendCredentialPresentation';
 import ServerPublicParams from '../ServerPublicParams';
+/**
+ * A credential indicating membership in a group, based on the set of *other* users in the
+ * group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential
+ * -> verify presentation".
+ *
+ * @see {@link GroupSendCredentialResponse}
+ * @see {@link GroupSendCredentialPresentation}
+ */
 export default class GroupSendCredential extends ByteArray {
     private readonly __type?;
     constructor(contents: Buffer);
+    /**
+     * Generates a new presentation, so that multiple uses of this credential are harder to link.
+     */
     present(serverParams: ServerPublicParams): GroupSendCredentialPresentation;
+    /**
+     * Generates a new presentation with a dedicated source of randomness.
+     *
+     * Should only be used for testing purposes.
+     *
+     * @see {@link GroupSendCredential#present}
+     */
     presentWithRandom(serverParams: ServerPublicParams, random: Buffer): GroupSendCredentialPresentation;
 }

package/dist/zkgroup/groupsend/GroupSendCredential.js

@@ -9,14 +9,34 @@ const ByteArray_1 = require("../internal/ByteArray");
 const Constants_1 = require("../internal/Constants");
 const Native = require("../../../Native");
 const GroupSendCredentialPresentation_1 = require("./GroupSendCredentialPresentation");
+/**
+ * A credential indicating membership in a group, based on the set of *other* users in the
+ * group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential
+ * -> verify presentation".
+ *
+ * @see {@link GroupSendCredentialResponse}
+ * @see {@link GroupSendCredentialPresentation}
+ */
 class GroupSendCredential extends ByteArray_1.default {
     constructor(contents) {
         super(contents, Native.GroupSendCredential_CheckValidContents);
     }
+    /**
+     * Generates a new presentation, so that multiple uses of this credential are harder to link.
+     */
     present(serverParams) {
         const random = (0, crypto_1.randomBytes)(Constants_1.RANDOM_LENGTH);
         return this.presentWithRandom(serverParams, random);
     }
+    /**
+     * Generates a new presentation with a dedicated source of randomness.
+     *
+     * Should only be used for testing purposes.
+     *
+     * @see {@link GroupSendCredential#present}
+     */
     presentWithRandom(serverParams, random) {
         return new GroupSendCredentialPresentation_1.default(Native.GroupSendCredential_PresentDeterministic(this.contents, serverParams.contents, random));
     }

package/dist/zkgroup/groupsend/GroupSendCredentialPresentation.d.ts

@@ -2,8 +2,23 @@
 import ByteArray from '../internal/ByteArray';
 import ServerSecretParams from '../ServerSecretParams';
 import { ServiceId } from '../../Address';
+/**
+ * A credential presentation indicating membership in a group, based on the set of *other* users in
+ * the group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential ->
+ * verify presentation".
+ *
+ * @see {@link GroupSendCredentialResponse}
+ * @see {@link GroupSendCredential}
+ */
 export default class GroupSendCredentialPresentation extends ByteArray {
     private readonly __type?;
     constructor(contents: Buffer);
+    /**
+     * Verifies that the credential is valid for a group containing the holder and `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
     verify(groupMembers: ServiceId[], serverParams: ServerSecretParams, now?: Date): void;
 }

package/dist/zkgroup/groupsend/GroupSendCredentialPresentation.js

@@ -7,10 +7,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const ByteArray_1 = require("../internal/ByteArray");
 const Native = require("../../../Native");
 const Address_1 = require("../../Address");
+/**
+ * A credential presentation indicating membership in a group, based on the set of *other* users in
+ * the group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential ->
+ * verify presentation".
+ *
+ * @see {@link GroupSendCredentialResponse}
+ * @see {@link GroupSendCredential}
+ */
 class GroupSendCredentialPresentation extends ByteArray_1.default {
     constructor(contents) {
         super(contents, Native.GroupSendCredentialPresentation_CheckValidContents);
     }
+    /**
+     * Verifies that the credential is valid for a group containing the holder and `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
     verify(groupMembers, serverParams, now = new Date()) {
         Native.GroupSendCredentialPresentation_Verify(this.contents, Address_1.ServiceId.toConcatenatedFixedWidthBinary(groupMembers), Math.floor(now.getTime() / 1000), serverParams.contents);
     }

package/dist/zkgroup/groupsend/GroupSendCredentialResponse.d.ts

@@ -6,11 +6,62 @@ import ServerSecretParams from '../ServerSecretParams';
 import ServerPublicParams from '../ServerPublicParams';
 import UuidCiphertext from '../groups/UuidCiphertext';
 import { Aci, ServiceId } from '../../Address';
+/**
+ * The issuance of a credential indicating membership in a group, based on the set of *other* users
+ * in the group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential ->
+ * verify presentation".
+ *
+ * @see {@link GroupSendCredential}
+ * @see {@link GroupSendCredentialPresentation}
+ */
 export default class GroupSendCredentialResponse extends ByteArray {
     private readonly __type?;
     constructor(contents: Buffer);
     private static defaultExpiration;
+    /**
+     * Issues a new credential stating that `requestingMember` is a member of a group containing
+     * `groupMembers`.
+     *
+     * `groupMembers` should include `requestingMember` as well.
+     */
     static issueCredential(groupMembers: UuidCiphertext[], requestingMember: UuidCiphertext, params: ServerSecretParams): GroupSendCredentialResponse;
+    /**
+     * Issues a new credential stating that `requestingMember` is a member of a group containing
+     * `groupMembers`, with an explicity-chosen expiration and source of randomness.
+     *
+     * Should only be used for testing purposes.
+     *
+     * @see {@link GroupSendCredentialResponse#issueCredential}
+     */
     static issueCredentialWithExpirationAndRandom(groupMembers: UuidCiphertext[], requestingMember: UuidCiphertext, expiration: Date, params: ServerSecretParams, random: Buffer): GroupSendCredentialResponse;
+    /**
+     * Receives, validates, and extracts the credential from a response.
+     *
+     * Note that the `receive` operation is provided for both {@link ServiceId}s and
+     * {@link UuidCiphertext}s. If you already have the ciphertexts for the group members available,
+     * {@link GroupSendCredentialResponse#receiveWithCiphertexts} will be *significantly* faster; if
+     * you don't, this method is faster than generating the ciphertexts and throwing them away
+     * afterwards.
+     *
+     * `localUser` should be included in `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
     receive(groupMembers: ServiceId[], localUser: Aci, serverParams: ServerPublicParams, groupParams: GroupSecretParams, now?: Date): GroupSendCredential;
+    /**
+     * Receives, validates, and extracts the credential from a response.
+     *
+     * Note that the `receive` operation is provided for both {@link ServiceId}s and
+     * {@link UuidCiphertext}s. If you already have the ciphertexts for the group members available,
+     * this method will be *significantly* faster; if you don't,
+     * {@link GroupSendCredentialResponse#receive} is faster than generating the ciphertexts and
+     * throwing them away afterwards.
+     *
+     * `localUser` should be included in `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
+    receiveWithCiphertexts(groupMembers: UuidCiphertext[], localUser: UuidCiphertext, serverParams: ServerPublicParams, groupParams: GroupSecretParams, now?: Date): GroupSendCredential;
 }

package/dist/zkgroup/groupsend/GroupSendCredentialResponse.js

@@ -9,7 +9,18 @@ const ByteArray_1 = require("../internal/ByteArray");
 const Native = require("../../../Native");
 const Constants_1 = require("../internal/Constants");
 const GroupSendCredential_1 = require("./GroupSendCredential");
+const UuidCiphertext_1 = require("../groups/UuidCiphertext");
 const Address_1 = require("../../Address");
+/**
+ * The issuance of a credential indicating membership in a group, based on the set of *other* users
+ * in the group with you.
+ *
+ * Follows the usual zkgroup pattern of "issue response -> receive response -> present credential ->
+ * verify presentation".
+ *
+ * @see {@link GroupSendCredential}
+ * @see {@link GroupSendCredentialPresentation}
+ */
 class GroupSendCredentialResponse extends ByteArray_1.default {
     constructor(contents) {
         super(contents, Native.GroupSendCredentialResponse_CheckValidContents);
@@ -18,26 +29,59 @@ class GroupSendCredentialResponse extends ByteArray_1.default {
         const expirationInSeconds = Native.GroupSendCredentialResponse_DefaultExpirationBasedOnCurrentTime();
         return new Date(expirationInSeconds * 1000);
     }
+    /**
+     * Issues a new credential stating that `requestingMember` is a member of a group containing
+     * `groupMembers`.
+     *
+     * `groupMembers` should include `requestingMember` as well.
+     */
     static issueCredential(groupMembers, requestingMember, params) {
         const random = (0, crypto_1.randomBytes)(Constants_1.RANDOM_LENGTH);
         return this.issueCredentialWithExpirationAndRandom(groupMembers, requestingMember, this.defaultExpiration(), params, random);
     }
+    /**
+     * Issues a new credential stating that `requestingMember` is a member of a group containing
+     * `groupMembers`, with an explicity-chosen expiration and source of randomness.
+     *
+     * Should only be used for testing purposes.
+     *
+     * @see {@link GroupSendCredentialResponse#issueCredential}
+     */
     static issueCredentialWithExpirationAndRandom(groupMembers, requestingMember, expiration, params, random) {
-        const uuidCiphertextLen = requestingMember.contents.length;
-        const concatenated = Buffer.alloc(groupMembers.length * uuidCiphertextLen);
-        let offset = 0;
-        for (const member of groupMembers) {
-            if (member.contents.length !== uuidCiphertextLen) {
-                throw TypeError('UuidCiphertext with unexpected length');
-            }
-            concatenated.set(member.contents, offset);
-            offset += uuidCiphertextLen;
-        }
-        return new GroupSendCredentialResponse(Native.GroupSendCredentialResponse_IssueDeterministic(concatenated, requestingMember.contents, Math.floor(expiration.getTime() / 1000), params.contents, random));
+        return new GroupSendCredentialResponse(Native.GroupSendCredentialResponse_IssueDeterministic(UuidCiphertext_1.default.serializeAndConcatenate(groupMembers), requestingMember.contents, Math.floor(expiration.getTime() / 1000), params.contents, random));
     }
+    /**
+     * Receives, validates, and extracts the credential from a response.
+     *
+     * Note that the `receive` operation is provided for both {@link ServiceId}s and
+     * {@link UuidCiphertext}s. If you already have the ciphertexts for the group members available,
+     * {@link GroupSendCredentialResponse#receiveWithCiphertexts} will be *significantly* faster; if
+     * you don't, this method is faster than generating the ciphertexts and throwing them away
+     * afterwards.
+     *
+     * `localUser` should be included in `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
     receive(groupMembers, localUser, serverParams, groupParams, now = new Date()) {
         return new GroupSendCredential_1.default(Native.GroupSendCredentialResponse_Receive(this.contents, Address_1.ServiceId.toConcatenatedFixedWidthBinary(groupMembers), localUser.getServiceIdFixedWidthBinary(), Math.floor(now.getTime() / 1000), serverParams.contents, groupParams.contents));
     }
+    /**
+     * Receives, validates, and extracts the credential from a response.
+     *
+     * Note that the `receive` operation is provided for both {@link ServiceId}s and
+     * {@link UuidCiphertext}s. If you already have the ciphertexts for the group members available,
+     * this method will be *significantly* faster; if you don't,
+     * {@link GroupSendCredentialResponse#receive} is faster than generating the ciphertexts and
+     * throwing them away afterwards.
+     *
+     * `localUser` should be included in `groupMembers`.
+     *
+     * @throws {VerificationFailedError} if the credential is not valid for any reason
+     */
+    receiveWithCiphertexts(groupMembers, localUser, serverParams, groupParams, now = new Date()) {
+        return new GroupSendCredential_1.default(Native.GroupSendCredentialResponse_ReceiveWithCiphertexts(this.contents, UuidCiphertext_1.default.serializeAndConcatenate(groupMembers), localUser.contents, Math.floor(now.getTime() / 1000), serverParams.contents, groupParams.contents));
+    }
 }
 exports.default = GroupSendCredentialResponse;
 //# sourceMappingURL=GroupSendCredentialResponse.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalapp/libsignal-client",
-  "version": "0.39.2",
+  "version": "0.40.0",
   "license": "AGPL-3.0-only",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,6 +48,7 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-header": "^3.1.0",
     "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jsdoc": "^48.0.2",
     "eslint-plugin-mocha": "^10.1.0",
     "eslint-plugin-more": "^1.0.0",
     "mocha": "^9",