@wireapp/core-crypto 1.0.0-rc.1 → 1.0.0-rc.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireapp/core-crypto",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.10",
   "description": "CoreCrypto bindings for the Web",
   "type": "module",
   "module": "platforms/web/corecrypto.js",

package/platforms/web/corecrypto.d.ts

@@ -79,6 +79,24 @@ export interface ConversationConfiguration {
 	 * Implementation specific configuration
 	 */
 	custom?: CustomConfiguration;
+	/**
+	 * Trust anchors to be added in the group's context extensions
+	 */
+	perDomainTrustAnchors?: PerDomainTrustAnchor[];
+}
+/**
+ * A wrapper containing the configuration for trust anchors to be added in the group's context
+ * extensions
+ */
+export interface PerDomainTrustAnchor {
+	/**
+	 * Domain name of the owning backend this anchor refers to. One of the certificate in the chain has to have this domain in its SANs
+	 */
+	domain_name: string;
+	/**
+	 * PEM encoded (partial) certificate chain. This contains the certificate chain for the CA certificate issuing the E2E Identity certificates
+	 */
+	intermediate_certificate_chain: string;
 }
 /**
  * see [core_crypto::prelude::MlsWirePolicy]
@@ -244,7 +262,7 @@ export interface RotateBundle {
 	 *
 	 * @readonly
 	 */
-	commits: CommitBundle[];
+	commits: Map<string, CommitBundle>;
 	/**
 	 * Fresh KeyPackages with the new Credential
 	 *
@@ -368,6 +386,45 @@ export interface DecryptedMessage {
 	 * Present for all messages
 	 */
 	identity?: WireIdentity;
+	/**
+	 * Only set when the decrypted message is a commit.
+	 * Contains buffered messages for next epoch which were received before the commit creating the epoch
+	 * because the DS did not fan them out in order.
+	 */
+	bufferedMessages?: BufferedDecryptedMessage[];
+}
+/**
+ * Almost same as {@link DecryptedMessage} but avoids recursion
+ */
+export interface BufferedDecryptedMessage {
+	/**
+	 * see {@link DecryptedMessage.message}
+	 */
+	message?: Uint8Array;
+	/**
+	 * see {@link DecryptedMessage.proposals}
+	 */
+	proposals: ProposalBundle[];
+	/**
+	 * see {@link DecryptedMessage.isActive}
+	 */
+	isActive: boolean;
+	/**
+	 * see {@link DecryptedMessage.commitDelay}
+	 */
+	commitDelay?: number;
+	/**
+	 * see {@link DecryptedMessage.senderClientId}
+	 */
+	senderClientId?: ClientId;
+	/**
+	 * see {@link DecryptedMessage.hasEpochChanged}
+	 */
+	hasEpochChanged: boolean;
+	/**
+	 * see {@link DecryptedMessage.identity}
+	 */
+	identity?: WireIdentity;
 }
 /**
  * Represents the identity claims identifying a client. Those claims are verifiable by any member in the group
@@ -389,6 +446,10 @@ export interface WireIdentity {
 	 * DNS domain for which this identity proof was generated e.g. `whitehouse.gov`
 	 */
 	domain: string;
+	/**
+	 * X509 certificate identifying this client in the MLS group ; PEM encoded
+	 */
+	certificate: string;
 }
 /**
  * Returned by all methods creating proposals. Contains a proposal message and an identifier to roll back the proposal
@@ -607,7 +668,7 @@ export declare class CoreCrypto {
 	/**
 	 * Closes this {@link CoreCrypto} instance and deallocates all loaded resources
 	 *
-	 * **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!
+	 * **CAUTION**: This {@link CoreCrypto} instance won't be usable 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>;
 	/**
@@ -673,7 +734,12 @@ export declare class CoreCrypto {
 	 */
 	createConversation(conversationId: ConversationId, creatorCredentialType: CredentialType, configuration?: ConversationConfiguration): Promise<any>;
 	/**
-	 * Decrypts a message for a given conversation
+	 * Decrypts a message for a given conversation.
+	 *
+	 * Note: you should catch & ignore the following error reasons:
+	 * * "We already decrypted this message once"
+	 * * "You tried to join with an external commit but did not merge it yet. We will reapply this message for you when you merge your external commit"
+	 * * "Incoming message is for a future epoch. We will buffer it until the commit for that epoch arrives"
 	 *
 	 * @param conversationId - The ID of the conversation
 	 * @param payload - The encrypted message buffer
@@ -690,16 +756,39 @@ export declare class CoreCrypto {
 	 * @returns The encrypted payload for the given group. This needs to be fanned out to the other members of the group.
 	 */
 	encryptMessage(conversationId: ConversationId, message: Uint8Array): Promise<Uint8Array>;
+	/**
+	 * Updates the trust anchors for a conversation. This should be called when a federated event happens (new team added/removed).
+	 * Clients should add and/or remove trust anchors from the new backend to the conversation. The method will check
+	 * for duplicated domains and the validity of the certificate chain.
+	 *
+	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
+	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
+	 * epoch, use new encryption secrets etc...
+	 *
+	 * @param conversationId - The ID of the conversation
+	 * @param removeDomainNames - Domains to remove from the trust anchors
+	 * @param addTrustAnchors - New trust anchors to add to the conversation
+	 *
+	 * @returns A {@link CommitBundle}
+	 */
+	updateTrustAnchorsFromConversation(conversationId: ConversationId, removeDomainNames: string[], addTrustAnchors: PerDomainTrustAnchor[]): Promise<CommitBundle>;
 	/**
 	 * Ingest a TLS-serialized MLS welcome message to join an existing MLS group
 	 *
+	 * Important: you have to catch the error with this reason "Although this Welcome seems valid, the local KeyPackage
+	 * it references has already been deleted locally. Join this group with an external commit", ignore it and then try
+	 * to join this group with an external commit.
+	 *
 	 * @param welcomeMessage - TLS-serialized MLS Welcome message
 	 * @param configuration - configuration of the MLS group
 	 * @returns The conversation ID of the newly joined group. You can use the same ID to decrypt/encrypt messages
 	 */
 	processWelcomeMessage(welcomeMessage: Uint8Array, configuration?: CustomConfiguration): Promise<ConversationId>;
 	/**
-	 * @returns The client's public key
+	 * Get the client's public signature key. To upload to the DS for further backend side validation
+	 *
+	 * @param ciphersuite - of the signature key to get
+	 * @returns the client's public signature key
 	 */
 	clientPublicKey(ciphersuite: Ciphersuite): Promise<Uint8Array>;
 	/**
@@ -728,7 +817,7 @@ export declare class CoreCrypto {
 	/**
 	 * Adds new clients to a conversation, assuming the current client has the right to add new clients to the conversation.
 	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
+	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterward **ONLY IF** the Delivery Service responds
 	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
 	 * epoch, use new encryption secrets etc...
 	 *
@@ -742,7 +831,7 @@ export declare class CoreCrypto {
 	 * Removes the provided clients from a conversation; Assuming those clients exist and the current client is allowed
 	 * to do so, otherwise this operation does nothing.
 	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
+	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterward **ONLY IF** the Delivery Service responds
 	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
 	 * epoch, use new encryption secrets etc...
 	 *
@@ -753,9 +842,9 @@ export declare class CoreCrypto {
 	 */
 	removeClientsFromConversation(conversationId: ConversationId, clientIds: ClientId[]): Promise<CommitBundle>;
 	/**
-	 * Creates an update commit which forces every client to update their keypackages in the conversation
+	 * Creates an update commit which forces every client to update their LeafNode in the conversation
 	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
+	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterward **ONLY IF** the Delivery Service responds
 	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
 	 * epoch, use new encryption secrets etc...
 	 *
@@ -785,6 +874,9 @@ export declare class CoreCrypto {
 	 * @returns A {@link ProposalBundle} containing the Proposal and its reference in order to roll it back if necessary
 	 */
 	newProposal(proposalType: ProposalType, args: ProposalArgs | AddProposalArgs | RemoveProposalArgs): Promise<ProposalBundle>;
+	/**
+	 * Creates a new external Add proposal for self client to join a conversation.
+	 */
 	newExternalProposal(externalProposalType: ExternalProposalType, args: ExternalAddProposalArgs): Promise<Uint8Array>;
 	/**
 	 * Allows to create an external commit to "apply" to join a group through its GroupInfo.
@@ -809,8 +901,9 @@ export declare class CoreCrypto {
 	 * and deletes the temporary one. This step makes the group operational and ready to encrypt/decrypt message
 	 *
 	 * @param conversationId - The ID of the conversation
+	 * @returns eventually decrypted buffered messages if any
 	 */
-	mergePendingGroupFromExternalCommit(conversationId: ConversationId): Promise<DecryptedMessage[] | undefined>;
+	mergePendingGroupFromExternalCommit(conversationId: ConversationId): Promise<BufferedDecryptedMessage[] | undefined>;
 	/**
 	 * In case the external commit generated by {@link CoreCrypto.joinByExternalCommit} is rejected by the Delivery Service, and we
 	 * want to abort this external commit once for all, we can wipe out the pending group from the keystore in order
@@ -820,26 +913,24 @@ export declare class CoreCrypto {
 	 */
 	clearPendingGroupFromExternalCommit(conversationId: ConversationId): Promise<void>;
 	/**
-	 * Allows to mark the latest commit produced as "accepted" and be able to safely merge it
-	 * into the local group state
+	 * Allows to mark the latest commit produced as "accepted" and be able to safely merge it into the local group state
 	 *
 	 * @param conversationId - The group's ID
+	 * @returns the messages from current epoch which had been buffered, if any
 	 */
-	commitAccepted(conversationId: ConversationId): Promise<void>;
+	commitAccepted(conversationId: ConversationId): Promise<BufferedDecryptedMessage[] | undefined>;
 	/**
-	 * Allows to remove a pending proposal (rollback). Use this when backend rejects the proposal you just sent e.g. if permissions
-	 * have changed meanwhile.
+	 * Allows to remove a pending proposal (rollback). Use this when backend rejects the proposal you just sent e.g. if permissions have changed meanwhile.
 	 *
 	 * **CAUTION**: only use this when you had an explicit response from the Delivery Service
-	 * e.g. 403 or 409. Do not use otherwise e.g. 5xx responses, timeout etc..
+	 * e.g. 403 or 409. Do not use otherwise e.g. 5xx responses, timeout etc…
 	 *
 	 * @param conversationId - The group's ID
 	 * @param proposalRef - A reference to the proposal to delete. You get one when using {@link CoreCrypto.newProposal}
 	 */
 	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.
+	 * Allows to remove a pending commit (rollback). Use this when backend rejects the commit you just sent e.g. if permissions have changed meanwhile.
 	 *
 	 * **CAUTION**: only use this when you had an explicit response from the Delivery Service
 	 * e.g. 403. Do not use otherwise e.g. 5xx responses, timeout etc..
@@ -883,7 +974,7 @@ export declare class CoreCrypto {
 	 */
 	reseedRng(seed: Uint8Array): Promise<void>;
 	/**
-	 * Initiailizes the proteus client
+	 * Initializes the proteus client
 	 */
 	proteusInit(): Promise<void>;
 	/**
@@ -1016,47 +1107,49 @@ export declare class CoreCrypto {
 	 * Creates an enrollment instance with private key material you can use in order to fetch
 	 * a new x509 certificate from the acme server.
 	 *
-	 * @param clientId client identifier with user b64Url encoded & clientId hex encoded e.g. `NDUyMGUyMmY2YjA3NGU3NjkyZjE1NjJjZTAwMmQ2NTQ:6add501bacd1d90e@example.com`
-	 * @param displayName human readable name displayed in the application e.g. `Smith, Alice M (QA)`
-	 * @param handle user handle e.g. `alice.smith.qa@example.com`
-	 * @param expiryDays generated x509 certificate expiry
+	 * @param clientId - client identifier with user b64Url encoded & clientId hex encoded e.g. `NDUyMGUyMmY2YjA3NGU3NjkyZjE1NjJjZTAwMmQ2NTQ:6add501bacd1d90e@example.com`
+	 * @param displayName - human-readable name displayed in the application e.g. `Smith, Alice M (QA)`
+	 * @param handle - user handle e.g. `alice.smith.qa@example.com`
+	 * @param expiryDays - generated x509 certificate expiry
 	 * @param ciphersuite - for generating signing key material
-	 * @returns The new {@link WireE2eIdentity} object
+	 * @returns The new {@link E2eiEnrollment} enrollment instance to use with {@link CoreCrypto.e2eiMlsInitOnly}
 	 */
-	e2eiNewEnrollment(clientId: string, displayName: string, handle: string, expiryDays: number, ciphersuite: Ciphersuite): Promise<WireE2eIdentity>;
+	e2eiNewEnrollment(clientId: string, displayName: string, handle: string, expiryDays: number, ciphersuite: Ciphersuite): Promise<E2eiEnrollment>;
 	/**
 	 * Generates an E2EI enrollment instance for a "regular" client (with a Basic credential) willing to migrate to E2EI.
-	 * As a consequence, this method does not support changing the ClientId which should remain the same as the Basic one.
 	 * Once the enrollment is finished, use the instance in {@link CoreCrypto.e2eiRotateAll} to do the rotation.
 	 *
-	 * @param displayName human readable name displayed in the application e.g. `Smith, Alice M (QA)`
-	 * @param handle user handle e.g. `alice.smith.qa@example.com`
-	 * @param expiryDays generated x509 certificate expiry
+	 * @param clientId - client identifier with user b64Url encoded & clientId hex encoded e.g. `NDUyMGUyMmY2YjA3NGU3NjkyZjE1NjJjZTAwMmQ2NTQ:6add501bacd1d90e@example.com`
+	 * @param displayName - human-readable name displayed in the application e.g. `Smith, Alice M (QA)`
+	 * @param handle - user handle e.g. `alice.smith.qa@example.com`
+	 * @param expiryDays - generated x509 certificate expiry
 	 * @param ciphersuite - for generating signing key material
-	 * @returns The new {@link WireE2eIdentity} object
+	 * @returns The new {@link E2eiEnrollment} enrollment instance to use with {@link CoreCrypto.e2eiRotateAll}
 	 */
-	e2eiNewActivationEnrollment(displayName: string, handle: string, expiryDays: number, ciphersuite: Ciphersuite): Promise<WireE2eIdentity>;
+	e2eiNewActivationEnrollment(clientId: string, displayName: string, handle: string, expiryDays: number, ciphersuite: Ciphersuite): Promise<E2eiEnrollment>;
 	/**
 	 * Generates an E2EI enrollment instance for a E2EI client (with a X509 certificate credential)
 	 * having to change/rotate their credential, either because the former one is expired or it
-	 * has been revoked. As a consequence, this method does not support changing neither ClientId which
-	 * should remain the same as the previous one. It lets you change the DisplayName or the handle
+	 * has been revoked. It lets you change the DisplayName or the handle
 	 * if you need to. Once the enrollment is finished, use the instance in {@link CoreCrypto.e2eiRotateAll} to do the rotation.
 	 *
-	 * @param expiryDays generated x509 certificate expiry
+	 * @param clientId - client identifier with user b64Url encoded & clientId hex encoded e.g. `NDUyMGUyMmY2YjA3NGU3NjkyZjE1NjJjZTAwMmQ2NTQ:6add501bacd1d90e@example.com`
+	 * @param expiryDays - generated x509 certificate expiry
 	 * @param ciphersuite - for generating signing key material
-	 * @param displayName human readable name displayed in the application e.g. `Smith, Alice M (QA)`
-	 * @param handle user handle e.g. `alice.smith.qa@example.com`
-	 * @returns The new {@link WireE2eIdentity} object
+	 * @param displayName - human-readable name displayed in the application e.g. `Smith, Alice M (QA)`
+	 * @param handle - user handle e.g. `alice.smith.qa@example.com`
+	 * @returns The new {@link E2eiEnrollment} enrollment instance to use with {@link CoreCrypto.e2eiRotateAll}
 	 */
-	e2eiNewRotateEnrollment(expiryDays: number, ciphersuite: Ciphersuite, displayName?: string, handle?: string): Promise<WireE2eIdentity>;
+	e2eiNewRotateEnrollment(clientId: string, expiryDays: number, ciphersuite: Ciphersuite, displayName?: string, handle?: string): Promise<E2eiEnrollment>;
 	/**
-	 * Use this method to initialize end-to-end identity when a client signs up and the grace period is already expired ; that means he cannot initialize with a Basic credential
+	 * Use this method to initialize end-to-end identity when a client signs up and the grace period is already expired ;
+	 * that means he cannot initialize with a Basic credential
 	 *
 	 * @param enrollment - the enrollment instance used to fetch the certificates
 	 * @param certificateChain - the raw response from ACME server
+	 * @returns a MlsClient initialized with only a x509 credential
 	 */
-	e2eiMlsInitOnly(enrollment: WireE2eIdentity, certificateChain: string): Promise<void>;
+	e2eiMlsInitOnly(enrollment: E2eiEnrollment, certificateChain: string): Promise<void>;
 	/**
 	 * Creates a commit in all local conversations for changing the credential. Requires first
 	 * having enrolled a new X509 certificate with either {@link CoreCrypto.e2eiNewActivationEnrollment}
@@ -1065,8 +1158,9 @@ export declare class CoreCrypto {
 	 * @param enrollment - the enrollment instance used to fetch the certificates
 	 * @param certificateChain - the raw response from ACME server
 	 * @param newKeyPackageCount - number of KeyPackages with new identity to generate
+	 * @returns a {@link RotateBundle} with commits to fan-out to other group members, KeyPackages to upload and old ones to delete
 	 */
-	e2eiRotateAll(enrollment: WireE2eIdentity, certificateChain: string, newKeyPackageCount: number): Promise<RotateBundle>;
+	e2eiRotateAll(enrollment: E2eiEnrollment, certificateChain: string, newKeyPackageCount: number): Promise<RotateBundle>;
 	/**
 	 * Allows persisting an active enrollment (for example while redirecting the user during OAuth) in order to resume
 	 * it later with {@link e2eiEnrollmentStashPop}
@@ -1074,22 +1168,38 @@ export declare class CoreCrypto {
 	 * @param enrollment the enrollment instance to persist
 	 * @returns a handle to fetch the enrollment later with {@link e2eiEnrollmentStashPop}
 	 */
-	e2eiEnrollmentStash(enrollment: WireE2eIdentity): Promise<Uint8Array>;
+	e2eiEnrollmentStash(enrollment: E2eiEnrollment): Promise<Uint8Array>;
 	/**
 	 * Fetches the persisted enrollment and deletes it from the keystore
 	 *
 	 * @param handle returned by {@link e2eiEnrollmentStash}
 	 * @returns the persisted enrollment instance
 	 */
-	e2eiEnrollmentStashPop(handle: Uint8Array): Promise<WireE2eIdentity>;
+	e2eiEnrollmentStashPop(handle: Uint8Array): Promise<E2eiEnrollment>;
 	/**
 	 * Indicates when to mark a conversation as degraded i.e. when not all its members have a X509.
 	 * Credential generated by Wire's end-to-end identity enrollment
 	 *
 	 * @param conversationId The group's ID
-	 * @returns true if all the members have valid X509 credentials
+	 * @returns the conversation state given current members
 	 */
-	e2eiIsDegraded(conversationId: ConversationId): Promise<boolean>;
+	e2eiConversationState(conversationId: ConversationId): Promise<E2eiConversationState>;
+	/**
+	 * Returns true when end-to-end-identity is enabled for the given Ciphersuite
+	 *
+	 * @param ciphersuite of the credential to check
+	 * @returns true if end-to-end identity is enabled for the given ciphersuite
+	 */
+	e2eiIsEnabled(ciphersuite: Ciphersuite): Promise<boolean>;
+	/**
+	 * From a given conversation, get the identity of the members supplied. Identity is only present for members with a
+	 * Certificate Credential (after turning on end-to-end identity).
+	 *
+	 * @param conversationId - identifier of the conversation
+	 * @param clientIds - identifiers of the user
+	 * @returns identities or if no member has a x509 certificate, it will return an empty List
+	 */
+	getUserIdentities(conversationId: ConversationId, clientIds: ClientId[]): Promise<WireIdentity[]>;
 	/**
 	 * Returns the current version of {@link CoreCrypto}
 	 *
@@ -1098,7 +1208,7 @@ export declare class CoreCrypto {
 	static version(): string;
 }
 type JsonRawData = Uint8Array;
-export declare class WireE2eIdentity {
+export declare class E2eiEnrollment {
 	#private;
 	/** @hidden */
 	constructor(e2ei: unknown);
@@ -1207,7 +1317,7 @@ export declare class WireE2eIdentity {
 	 * Parses the response from `POST /acme/{provisioner-name}/order/{order-id}`.
 	 *
 	 * @param order HTTP response body
-	 * @return the finalize url to use with {@link finalizeRequest}
+	 * @return finalize url to use with {@link finalizeRequest}
 	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
 	 */
 	checkOrderResponse(order: JsonRawData): string;
@@ -1257,6 +1367,12 @@ export interface AcmeDirectory {
 	 * @readonly
 	 */
 	newOrder: string;
+	/**
+	 * Revocation URL
+	 *
+	 * @readonly
+	 */
+	revokeCert: string;
 }
 /**
  * Result of an order creation
@@ -1325,5 +1441,24 @@ export interface AcmeChallenge {
 	 */
 	target: string;
 }
+/**
+ * Indicates the state of a Conversation regarding end-to-end identity.
+ * Note: this does not check pending state (pending commit, pending proposals) so it does not
+ * consider members about to be added/removed
+ */
+export declare enum E2eiConversationState {
+	/**
+	 * All clients have a valid E2EI certificate
+	 */
+	Verified = 1,
+	/**
+	 * Some clients are either still Basic or their certificate is expired
+	 */
+	Degraded = 2,
+	/**
+	 * All clients are still Basic. If all client have expired certificates, Degraded is returned.
+	 */
+	NotEnabled = 3
+}
 
 export {};