@wireapp/core-crypto 0.4.0 → 0.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@wireapp/core-crypto",
-    "version": "0.4.0",
-    "description": "CoreCrypto bindings for the Web - Dev version",
+    "version": "0.5.1",
+    "description": "CoreCrypto bindings for the Web",
     "type": "module",
     "module": "platforms/web/corecrypto.js",
     "types": "platforms/web/corecrypto.d.js",
@@ -40,24 +40,24 @@
     },
     "devDependencies": {
         "@rollup/plugin-html": "^0.2.4",
-        "@types/jest": "^28.1.6",
+        "@types/jest": "^29.0.1",
         "@types/jest-dev-server": "^5.0.0",
-        "@typescript-eslint/eslint-plugin": "^5.33.0",
-        "@typescript-eslint/parser": "^5.33.0",
-        "@wasm-tool/rollup-plugin-rust": "^2.2.2",
-        "dts-bundle-generator": "^6.12.0",
-        "eslint": "^8.21.0",
+        "@typescript-eslint/eslint-plugin": "^5.36.2",
+        "@typescript-eslint/parser": "^5.36.2",
+        "@wasm-tool/rollup-plugin-rust": "^2.3.1",
+        "dts-bundle-generator": "^6.13.0",
+        "eslint": "^8.23.1",
         "eslint-config-prettier": "^8.5.0",
         "eslint-plugin-prettier": "^4.2.1",
-        "jest": "^28.1.3",
+        "jest": "^29.0.3",
         "jest-dev-server": "^6.1.1",
         "prettier": "^2.7.1",
-        "puppeteer": "^16.1.0",
-        "rollup": "^2.77.2",
+        "puppeteer": "^17.1.3",
+        "rollup": "^2.79.0",
         "rollup-jest": "^3.0.0",
         "rollup-plugin-ts": "^3.0.2",
-        "ts-jest": "^28.0.7",
+        "ts-jest": "^29.0.0",
         "ts-loader": "^9.3.1",
-        "typescript": "^4.7.4"
+        "typescript": "^4.8.3"
     }
 }

package/platforms/web/corecrypto.d.ts

@@ -189,7 +189,10 @@ export interface DecryptedMessage {
 	 */
 	message?: Uint8Array;
 	/**
-	 * List of proposals that were retrieved from the decrypted message, in addition to the pending local proposals
+	 * Only when decrypted message is a commit, CoreCrypto will renew local proposal which could not make it in the commit.
+	 * This will contain either:
+	 *   * local pending proposal not in the accepted commit
+	 *   * If there is a pending commit, its proposals which are not in the accepted commit
 	 */
 	proposals: ProposalBundle[];
 	/**
@@ -216,7 +219,7 @@ export interface ProposalBundle {
 	 */
 	proposal: Uint8Array;
 	/**
-	 * Unique identifier of a proposal. Use this in {@link CoreCrypto.clear_pending_proposal} to roll back (delete) the proposal
+	 * Unique identifier of a proposal. Use this in {@link CoreCrypto.clearPendingProposal} to roll back (delete) the proposal
 	 *
 	 * @readonly
 	 */
@@ -225,7 +228,7 @@ export interface ProposalBundle {
 /**
  * MLS Proposal type
  */
-export declare const enum ProposalType {
+export declare enum ProposalType {
 	/**
 	 * This allows to propose the addition of other clients to the MLS group/conversation
 	 */
@@ -269,7 +272,7 @@ export interface RemoveProposalArgs extends ProposalArgs {
 /**
  * MLS External Proposal type
  */
-export declare const enum ExternalProposalType {
+export declare enum ExternalProposalType {
 	/**
 	 * This allows to propose the addition of other clients to the MLS group/conversation
 	 */
@@ -296,6 +299,25 @@ export interface ExternalRemoveProposalArgs extends ExternalProposalArgs {
 	 */
 	keyPackageRef: Uint8Array;
 }
+export interface CoreCryptoCallbacks {
+	/**
+	 * This callback is called by CoreCrypto to know whether a given clientId is authorized to "write"
+	 * in the given conversationId. Think of it as a "isAdmin" callback conceptually
+	 *
+	 * This callback exists because there are many business cases where CoreCrypto doesn't have enough knowledge
+	 * (such as what can exists on a backend) to inform the decision
+	 *
+	 * @param conversationId - id of the group/conversation
+	 * @param clientId - id of the client performing an operation requiring authorization
+	 * @returns whether the user is authorized by the logic layer to perform the operation
+	 */
+	authorize: (conversationId: Uint8Array, clientId: Uint8Array) => boolean;
+	/**
+	 * Callback to ensure that the given `clientId` belongs to one of the provided `otherClients`
+	 * This basically allows to defer the client ID parsing logic to the caller - because CoreCrypto is oblivious to such things
+	 */
+	clientIdBelongsToOneOf: (clientId: Uint8Array, otherClients: Uint8Array[]) => boolean;
+}
 /**
  * Wrapper for the WASM-compiled version of CoreCrypto
  */
@@ -349,6 +371,12 @@ export declare class CoreCrypto {
 	 * **CAUTION**: This {@link CoreCrypto} instance won't be useable after a call to this method, but there's no way to express this requirement in TypeScript so you'll get errors instead!
 	 */
 	close(): Promise<void>;
+	/**
+	 * Registers the callbacks for CoreCrypto to use in order to gain additional information
+	 *
+	 * @param callbacks - Any interface following the {@link CoreCryptoCallbacks} interface
+	 */
+	registerCallbacks(callbacks: CoreCryptoCallbacks): void;
 	/**
 	 * Checks if the Client is member of a given conversation and if the MLS Group is loaded up
 	 *
@@ -402,7 +430,7 @@ export declare class CoreCrypto {
 	 * @param conversationId - The ID of the conversation
 	 * @param payload - The encrypted message buffer
 	 *
-	 * @returns Either a {@link DecryptedMessage} payload or `undefined` - This happens when the encrypted payload contains a system message such a proposal or commit
+	 * @returns a {@link DecryptedMessage}. Note that {@link DecryptedMessage#message} is `undefined` when the encrypted payload contains a system message such a proposal or commit
 	 */
 	decryptMessage(conversationId: ConversationId, payload: Uint8Array): Promise<DecryptedMessage>;
 	/**
@@ -460,7 +488,7 @@ export declare class CoreCrypto {
 	 * @param conversationId - The ID of the conversation
 	 * @param clientIds - Array of Client IDs to remove.
 	 *
-	 * @returns A {@link CommitBundle}, or `undefined` if for any reason, the operation would result in an empty commit
+	 * @returns A {@link CommitBundle}
 	 */
 	removeClientsFromConversation(conversationId: ConversationId, clientIds: ClientId[]): Promise<CommitBundle>;
 	/**
@@ -484,9 +512,9 @@ export declare class CoreCrypto {
 	 *
 	 * @param conversationId - The ID of the conversation
 	 *
-	 * @returns A {@link CommitBundle}
+	 * @returns A {@link CommitBundle} or `undefined` when there was no pending proposal to commit
 	 */
-	commitPendingProposals(conversationId: ConversationId): Promise<CommitBundle>;
+	commitPendingProposals(conversationId: ConversationId): Promise<CommitBundle | undefined>;
 	/**
 	 * Adds new clients to a conversation, assuming the current client has the right to add new clients to the conversation.
 	 * The returned {@link CommitBundle} is a TLS struct that needs to be fanned out to Delivery Service in order to validate the commit.
@@ -550,9 +578,9 @@ export declare class CoreCrypto {
 	 *
 	 * @param conversationId - The ID of the conversation
 	 *
-	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service
+	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service or `undefined` when there was no pending proposal to commit
 	 */
-	finalCommitPendingProposals(conversationId: ConversationId): Promise<TlsCommitBundle>;
+	finalCommitPendingProposals(conversationId: ConversationId): Promise<TlsCommitBundle | undefined>;
 	/**
 	 * Creates a new proposal for the provided Conversation ID
 	 *
@@ -595,21 +623,6 @@ export declare class CoreCrypto {
 	 * @param conversationId - The group's ID
 	 */
 	commitAccepted(conversationId: ConversationId): Promise<void>;
-	/**
-	 * Allows {@link CoreCrypto} to act as a CSPRNG provider
-	 * @note The underlying CSPRNG algorithm is ChaCha20 and takes in account the external seed provider either at init time or provided with {@link CoreCrypto.reseedRng}
-	 *
-	 * @param length - The number of bytes to be returned in the `Uint8Array`
-	 *
-	 * @returns A `Uint8Array` buffer that contains `length` cryptographically-secure random bytes
-	 */
-	randomBytes(length: number): Promise<Uint8Array>;
-	/**
-	 * Allows to reseed {@link CoreCrypto}'s internal CSPRNG with a new seed.
-	 *
-	 * @param seed - **exactly 32** bytes buffer seed
-	 */
-	reseedRng(seed: Uint8Array): Promise<void>;
 	/**
 	 * Allows to remove a pending proposal (rollback). Use this when backend rejects the proposal you just sent e.g. if permissions
 	 * have changed meanwhile.
@@ -620,7 +633,7 @@ export declare class CoreCrypto {
 	 * @param conversationId - The group's ID
 	 * @param proposalRef - A reference to the proposal to delete. You get one when using {@link CoreCrypto.newProposal}
 	 */
-	clear_pending_proposal(conversationId: ConversationId, proposalRef: ProposalRef): Promise<void>;
+	clearPendingProposal(conversationId: ConversationId, proposalRef: ProposalRef): Promise<void>;
 	/**
 	 * Allows to remove a pending commit (rollback). Use this when backend rejects the commit you just sent e.g. if permissions
 	 * have changed meanwhile.
@@ -632,7 +645,22 @@ export declare class CoreCrypto {
 	 *
 	 * @param conversationId - The group's ID
 	 */
-	clear_pending_commit(conversationId: ConversationId): Promise<void>;
+	clearPendingCommit(conversationId: ConversationId): Promise<void>;
+	/**
+	 * Allows {@link CoreCrypto} to act as a CSPRNG provider
+	 * @note The underlying CSPRNG algorithm is ChaCha20 and takes in account the external seed provider either at init time or provided with {@link CoreCrypto.reseedRng}
+	 *
+	 * @param length - The number of bytes to be returned in the `Uint8Array`
+	 *
+	 * @returns A `Uint8Array` buffer that contains `length` cryptographically-secure random bytes
+	 */
+	randomBytes(length: number): Promise<Uint8Array>;
+	/**
+	 * Allows to reseed {@link CoreCrypto}'s internal CSPRNG with a new seed.
+	 *
+	 * @param seed - **exactly 32** bytes buffer seed
+	 */
+	reseedRng(seed: Uint8Array): Promise<void>;
 	/**
 	 * Returns the current version of {@link CoreCrypto}
 	 *