@wireapp/core-crypto 0.8.2 → 0.9.0

package/package.json

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

package/platforms/web/corecrypto.d.ts

@@ -49,6 +49,16 @@ export declare enum Ciphersuite {
 	 */
 	MLS_256_DHKEMP384_AES256GCM_SHA384_P384 = 7
 }
+export declare enum CredentialType {
+	/**
+	 * Just a KeyPair
+	 */
+	Basic = 1,
+	/**
+	 * A certificate obtained through e2e identity enrollment process
+	 */
+	X509 = 2
+}
 /**
  * Configuration object for new conversations
  */
@@ -235,6 +245,10 @@ export interface CoreCryptoDeferredParams {
 	 * This should be appropriately stored in a secure location (i.e. WebCrypto private key storage)
 	 */
 	key: string;
+	/**
+	 * All the ciphersuites this MLS client can support
+	 */
+	ciphersuites: Ciphersuite[];
 	/**
 	 * External PRNG entropy pool seed.
 	 * This **must** be exactly 32 bytes
@@ -440,6 +454,17 @@ export interface ExternalRemoveProposalArgs extends ExternalProposalArgs {
 	 */
 	keyPackageRef: Uint8Array;
 }
+export interface ExternalAddProposalArgs extends ExternalProposalArgs {
+	/**
+	 * {@link Ciphersuite} to propose to join the MLS group with.
+	 */
+	ciphersuite: Ciphersuite;
+	/**
+	 * Fails when it is {@link CredentialType.X509} and no Credential has been created
+	 * for it beforehand with {@link CoreCrypto.e2eiMlsInit} or variants.
+	 */
+	credentialType: CredentialType;
+}
 export interface CoreCryptoCallbacks {
 	/**
 	 * This callback is called by CoreCrypto to know whether a given clientId is authorized to "write"
@@ -513,7 +538,7 @@ export declare class CoreCrypto {
 	 * });
 	 * ````
 	 */
-	static init({ databaseName, key, clientId, wasmFilePath, entropySeed }: CoreCryptoParams): Promise<CoreCrypto>;
+	static init({ databaseName, key, clientId, wasmFilePath, ciphersuites, entropySeed }: CoreCryptoParams): Promise<CoreCrypto>;
 	/**
 	 * Almost identical to {@link CoreCrypto.init} but allows a 2 phase initialization of MLS.
 	 * First, calling this will set up the keystore and will allow generating proteus prekeys.
@@ -521,29 +546,32 @@ export declare class CoreCrypto {
 	 * Use this clientId to initialize MLS with {@link CoreCrypto.mlsInit}.
 	 * @param params - {@link CoreCryptoDeferredParams}
 	 */
-	static deferredInit({ databaseName, key, entropySeed, wasmFilePath }: CoreCryptoDeferredParams): Promise<CoreCrypto>;
+	static deferredInit({ databaseName, key, ciphersuites, entropySeed, wasmFilePath }: CoreCryptoDeferredParams): Promise<CoreCrypto>;
 	/**
 	 * Use this after {@link CoreCrypto.deferredInit} when you have a clientId. It initializes MLS.
 	 *
 	 * @param clientId - {@link CoreCryptoParams#clientId} but required
+	 * @param ciphersuites - All the ciphersuites supported by this MLS client
 	 */
-	mlsInit(clientId: ClientId): Promise<void>;
+	mlsInit(clientId: ClientId, ciphersuites: Ciphersuite[]): Promise<void>;
 	/**
 	 * Generates a MLS KeyPair/CredentialBundle with a temporary, random client ID.
-	 * This method is designed to be used in conjunction with {@link CoreCrypto.mlsInitWithClientID} and represents the first step in this process
+	 * This method is designed to be used in conjunction with {@link CoreCrypto.mlsInitWithClientId} and represents the first step in this process
 	 *
+	 * @param ciphersuites - All the ciphersuites supported by this MLS client
 	 * @returns This returns the TLS-serialized identity key (i.e. the signature keypair's public key)
 	 */
-	mlsGenerateKeypair(): Promise<Uint8Array>;
+	mlsGenerateKeypair(ciphersuites: Ciphersuite[]): Promise<Uint8Array[]>;
 	/**
 	 * Updates the current temporary Client ID with the newly provided one. This is the second step in the externally-generated clients process
 	 *
-	 * Important: This is designed to be called after {@link CoreCrypto.mlsGenerateKeyPair}
+	 * Important: This is designed to be called after {@link CoreCrypto.mlsGenerateKeypair}
 	 *
 	 * @param clientId - The newly-allocated client ID by the MLS Authentication Service
-	 * @param signaturePublicKey - The public key you were given at the first step; This is for authentication purposes
+	 * @param signaturePublicKeys - The public key you were given at the first step; This is for authentication purposes
+	 * @param ciphersuites - All the ciphersuites supported by this MLS client
 	 */
-	mlsInitWithClientId(clientId: ClientId, signaturePublicKey: Uint8Array): Promise<void>;
+	mlsInitWithClientId(clientId: ClientId, signaturePublicKeys: Uint8Array[], ciphersuites: Ciphersuite[]): Promise<void>;
 	/** @hidden */
 	private constructor();
 	/**
@@ -655,18 +683,21 @@ export declare class CoreCrypto {
 	/**
 	 * @returns The client's public key
 	 */
-	clientPublicKey(): Promise<Uint8Array>;
+	clientPublicKey(ciphersuite: Ciphersuite): Promise<Uint8Array>;
 	/**
+	 *
+	 * @param ciphersuite - of the KeyPackages to count
 	 * @returns The amount of valid, non-expired KeyPackages that are persisted in the backing storage
 	 */
-	clientValidKeypackagesCount(): Promise<number>;
+	clientValidKeypackagesCount(ciphersuite: Ciphersuite): Promise<number>;
 	/**
 	 * Fetches a requested amount of keypackages
 	 *
+	 * @param ciphersuite - of the KeyPackages to generate
 	 * @param amountRequested - The amount of keypackages requested
 	 * @returns An array of length `amountRequested` containing TLS-serialized KeyPackages
 	 */
-	clientKeypackages(amountRequested: number): Promise<Array<Uint8Array>>;
+	clientKeypackages(ciphersuite: Ciphersuite, amountRequested: number): Promise<Array<Uint8Array>>;
 	/**
 	 * Adds new clients to a conversation, assuming the current client has the right to add new clients to the conversation.
 	 *
@@ -727,7 +758,7 @@ 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>;
-	newExternalProposal(externalProposalType: ExternalProposalType, args: ExternalProposalArgs | ExternalRemoveProposalArgs): Promise<Uint8Array>;
+	newExternalProposal(externalProposalType: ExternalProposalType, args: ExternalAddProposalArgs | ExternalRemoveProposalArgs): Promise<Uint8Array>;
 	/**
 	 * Exports public group state for use in external commits
 	 *
@@ -746,10 +777,13 @@ export declare class CoreCrypto {
 	 * bad can happen if you forget to except some storage space wasted.
 	 *
 	 * @param publicGroupState - a TLS encoded PublicGroupState fetched from the Delivery Service
+	 * @param credentialType - kind of Credential to use for joining this group. If {@link CredentialType.Basic} is
+	 * chosen and no Credential has been created yet for it, a new one will be generated.
 	 * @param configuration - configuration of the MLS group
+	 * When {@link CredentialType.X509} is chosen, it fails when no Credential has been created for the given {@link Ciphersuite}.
 	 * @returns see {@link ConversationInitBundle}
 	 */
-	joinByExternalCommit(publicGroupState: Uint8Array, configuration?: CustomConfiguration): Promise<ConversationInitBundle>;
+	joinByExternalCommit(publicGroupState: Uint8Array, credentialType: CredentialType, configuration?: CustomConfiguration): Promise<ConversationInitBundle>;
 	/**
 	 * This merges the commit generated by {@link CoreCrypto.joinByExternalCommit}, persists the group permanently
 	 * and deletes the temporary one. This step makes the group operational and ready to encrypt/decrypt message
@@ -966,17 +1000,32 @@ export declare class CoreCrypto {
 	 * @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. Only {@link Ciphersuite.MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519} is supported currently
+	 * @param ciphersuite - for generating signing key material
 	 * @returns The new {@link WireE2eIdentity} object
 	 */
-	newAcmeEnrollment(clientId: string, displayName: string, handle: string, expiryDays: number, ciphersuite?: Ciphersuite): Promise<WireE2eIdentity>;
+	e2eiNewEnrollment(clientId: string, displayName: string, handle: string, expiryDays: number, ciphersuite: Ciphersuite): Promise<WireE2eIdentity>;
 	/**
 	 * Parses the ACME server response from the endpoint fetching x509 certificates and uses it to initialize the MLS client with a certificate
 	 *
-	 * @param e2ei - the enrollment instance used to fetch the certificates
+	 * @param enrollment - the enrollment instance used to fetch the certificates
 	 * @param certificateChain - the raw response from ACME server
 	 */
-	e2eiMlsInit(e2ei: WireE2eIdentity, certificateChain: string): Promise<void>;
+	e2eiMlsInit(enrollment: WireE2eIdentity, certificateChain: string): Promise<void>;
+	/**
+	 * Allows persisting an active enrollment (for example while redirecting the user during OAuth) in order to resume
+	 * it later with {@link e2eiEnrollmentStashPop}
+	 *
+	 * @param enrollment the enrollment instance to persist
+	 * @returns a handle to fetch the enrollment later with {@link e2eiEnrollmentStashPop}
+	 */
+	e2eiEnrollmentStash(enrollment: WireE2eIdentity): 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>;
 	/**
 	 * Returns the current version of {@link CoreCrypto}
 	 *
@@ -1055,11 +1104,10 @@ export declare class WireE2eIdentity {
 	 * Then send it to `POST /clients/{id}/access-token`
 	 * {@link https://staging-nginz-https.zinfra.io/api/swagger-ui/#/default/post_clients__cid__access_token} on wire-server.
 	 *
-	 * @param accessTokenUrl backend endpoint where this token will be sent. Should be this one {@link https://staging-nginz-https.zinfra.io/api/swagger-ui/#/default/post_clients__cid__access_token}
 	 * @param expirySecs of the client Dpop JWT. This should be equal to the grace period set in Team Management
 	 * @param backendNonce you get by calling `GET /clients/token/nonce` on wire-server as defined here {@link https://staging-nginz-https.zinfra.io/api/swagger-ui/#/default/get_clients__client__nonce}
 	 */
-	createDpopToken(accessTokenUrl: string, expirySecs: number, backendNonce: string): Uint8Array;
+	createDpopToken(expirySecs: number, backendNonce: string): Uint8Array;
 	/**
 	 * Creates a new challenge request for Wire Dpop challenge.
 	 *
@@ -1096,9 +1144,10 @@ 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}
 	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
 	 */
-	checkOrderResponse(order: JsonRawData): void;
+	checkOrderResponse(order: JsonRawData): string;
 	/**
 	 * Final step before fetching the certificate.
 	 *
@@ -1111,9 +1160,10 @@ export declare class WireE2eIdentity {
 	 * Parses the response from `POST /acme/{provisioner-name}/order/{order-id}/finalize`.
 	 *
 	 * @param finalize HTTP response body
+	 * @return the certificate url to use with {@link certificateRequest}
 	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
 	 */
-	finalizeResponse(finalize: JsonRawData): void;
+	finalizeResponse(finalize: JsonRawData): string;
 	/**
 	 * Creates a request for finally fetching the x509 certificate.
 	 *
@@ -1205,6 +1255,13 @@ export interface AcmeChallenge {
 	 * @readonly
 	 */
 	url: string;
+	/**
+	 * Non-standard, Wire specific claim. Indicates the consumer from where it should get the challenge proof.
+	 * Either from wire-server "/access-token" endpoint in case of a DPoP challenge, or from an OAuth token endpoint for an OIDC challenge
+	 *
+	 * @readonly
+	 */
+	target: string;
 }
 
 export {};