@wireapp/core-crypto 0.6.0-rc.2 → 0.6.0-rc.4

package/README.md

@@ -114,7 +114,7 @@ cargo make wasm
 
 ### Android / JVM
 
-You can publish the JVM and Android bindings to maven using gradle after you'be build the corresponding target.
+You can publish the JVM and Android bindings to maven using gradle after you've built the corresponding target.
 
 ```ignore
 cd kotlin

package/package.json

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

package/platforms/web/corecrypto.d.ts

@@ -1,34 +1,155 @@
+declare class WireE2eIdentity {
+	free(): void;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::directory_response]
+	* @param {Uint8Array} directory
+	* @returns {any}
+	*/
+	directory_response(directory: Uint8Array): any;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_account_request]
+	* @param {any} directory
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	new_account_request(directory: any, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_account_response]
+	* @param {Uint8Array} account
+	* @returns {Uint8Array}
+	*/
+	new_account_response(account: Uint8Array): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_order_request]
+	* @param {string} handle
+	* @param {string} client_id
+	* @param {number} expiry_days
+	* @param {any} directory
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	new_order_request(handle: string, client_id: string, expiry_days: number, directory: any, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_order_response]
+	* @param {Uint8Array} order
+	* @returns {any}
+	*/
+	new_order_response(order: Uint8Array): any;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_authz_request]
+	* @param {string} url
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	new_authz_request(url: string, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_authz_response]
+	* @param {Uint8Array} authz
+	* @returns {any}
+	*/
+	new_authz_response(authz: Uint8Array): any;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::create_dpop_token]
+	* @param {string} access_token_url
+	* @param {string} user_id
+	* @param {bigint} client_id
+	* @param {string} domain
+	* @param {any} client_id_challenge
+	* @param {string} backend_nonce
+	* @param {number} expiry_days
+	* @returns {string}
+	*/
+	create_dpop_token(access_token_url: string, user_id: string, client_id: bigint, domain: string, client_id_challenge: any, backend_nonce: string, expiry_days: number): string;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_challenge_request]
+	* @param {any} handle_challenge
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	new_challenge_request(handle_challenge: any, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::new_challenge_response]
+	* @param {Uint8Array} challenge
+	*/
+	new_challenge_response(challenge: Uint8Array): void;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::check_order_request]
+	* @param {string} order_url
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	check_order_request(order_url: string, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::check_order_response]
+	* @param {Uint8Array} order
+	* @returns {Uint8Array}
+	*/
+	check_order_response(order: Uint8Array): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::finalize_request]
+	* @param {(Uint8Array)[]} domains
+	* @param {Uint8Array} order
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	finalize_request(domains: (Uint8Array)[], order: Uint8Array, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::finalize_response]
+	* @param {Uint8Array} finalize
+	* @returns {any}
+	*/
+	finalize_response(finalize: Uint8Array): any;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::certificate_request]
+	* @param {any} finalize
+	* @param {Uint8Array} account
+	* @param {string} previous_nonce
+	* @returns {Uint8Array}
+	*/
+	certificate_request(finalize: any, account: Uint8Array, previous_nonce: string): Uint8Array;
+	/**
+	* See [core_crypto::e2e_identity::WireE2eIdentity::certificate_response]
+	* @param {string} certificate_chain
+	* @returns {(Uint8Array)[]}
+	*/
+	certificate_response(certificate_chain: string): (Uint8Array)[];
+}
 /**
-* see [core_crypto::prelude::CiphersuiteName]
-*/
+ * see [core_crypto::prelude::CiphersuiteName]
+ */
 export declare enum Ciphersuite {
 	/**
-	* DH KEM x25519 | AES-GCM 128 | SHA2-256 | Ed25519
-	*/
+	 * DH KEM x25519 | AES-GCM 128 | SHA2-256 | Ed25519
+	 */
 	MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 = 1,
 	/**
-	* DH KEM P256 | AES-GCM 128 | SHA2-256 | EcDSA P256
-	*/
+	 * DH KEM P256 | AES-GCM 128 | SHA2-256 | EcDSA P256
+	 */
 	MLS_128_DHKEMP256_AES128GCM_SHA256_P256 = 2,
 	/**
-	* DH KEM x25519 | Chacha20Poly1305 | SHA2-256 | Ed25519
-	*/
+	 * DH KEM x25519 | Chacha20Poly1305 | SHA2-256 | Ed25519
+	 */
 	MLS_128_DHKEMX25519_CHACHA20POLY1305_SHA256_Ed25519 = 3,
 	/**
-	* DH KEM x448 | AES-GCM 256 | SHA2-512 | Ed448
-	*/
+	 * DH KEM x448 | AES-GCM 256 | SHA2-512 | Ed448
+	 */
 	MLS_256_DHKEMX448_AES256GCM_SHA512_Ed448 = 4,
 	/**
-	* DH KEM P521 | AES-GCM 256 | SHA2-512 | EcDSA P521
-	*/
+	 * DH KEM P521 | AES-GCM 256 | SHA2-512 | EcDSA P521
+	 */
 	MLS_256_DHKEMP521_AES256GCM_SHA512_P521 = 5,
 	/**
-	* DH KEM x448 | Chacha20Poly1305 | SHA2-512 | Ed448
-	*/
+	 * DH KEM x448 | Chacha20Poly1305 | SHA2-512 | Ed448
+	 */
 	MLS_256_DHKEMX448_CHACHA20POLY1305_SHA512_Ed448 = 6,
 	/**
-	* DH KEM P384 | AES-GCM 256 | SHA2-384 | EcDSA P384
-	*/
+	 * DH KEM P384 | AES-GCM 256 | SHA2-384 | EcDSA P384
+	 */
 	MLS_256_DHKEMP384_AES256GCM_SHA384_P384 = 7
 }
 /**
@@ -689,7 +810,7 @@ export declare class CoreCrypto {
 	 * **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..
 	 * **DO NOT** use when Delivery Service responds 409, pending state will be renewed
-	 * in {@link CoreCrypto.decrypt_message}
+	 * in {@link CoreCrypto.decryptMessage}
 	 *
 	 * @param conversationId - The group's ID
 	 */
@@ -750,6 +871,8 @@ export declare class CoreCrypto {
 	/**
 	 * Locally persists a session to the keystore
 	 *
+	 * **Note**: This isn't usually needed as persisting sessions happens automatically when decrypting/encrypting messages and initializing Sessions
+	 *
 	 * @param sessionId - ID of the Proteus session
 	 */
 	proteusSessionSave(sessionId: string): Promise<void>;
@@ -800,6 +923,12 @@ export declare class CoreCrypto {
 	 * @returns: A CBOR-serialized version of the PreKeyBundle corresponding to the newly generated and stored PreKey
 	 */
 	proteusNewPrekey(prekeyId: number): Promise<Uint8Array>;
+	/**
+	 * Creates a new prekey with an automatically generated ID..
+	 *
+	 * @returns: A CBOR-serialized version of the PreKeyBundle corresponding to the newly generated and stored PreKey
+	 */
+	proteusNewPrekeyAuto(): Promise<Uint8Array>;
 	/**
 	 * Proteus public key fingerprint
 	 * It's basically the public key encoded as an hex string
@@ -826,7 +955,7 @@ export declare class CoreCrypto {
 	 *
 	 * @param prekey - the prekey bundle to get the fingerprint from
 	 * @returns Hex-encoded public key string
-	**/
+	 **/
 	static proteusFingerprintPrekeybundle(prekey: Uint8Array): string;
 	/**
 	 * Imports all the data stored by Cryptobox into the CoreCrypto keystore
@@ -834,6 +963,15 @@ export declare class CoreCrypto {
 	 * @param storeName - The name of the IndexedDB store where the data is stored
 	 */
 	proteusCryptoboxMigrate(storeName: string): Promise<void>;
+	/**
+	 * Creates an enrollment instance with private key material you can use in order to fetch
+	 * a new x509 certificate from the acme server.
+	 * Make sure to call [WireE2eIdentity::free] (not yet available) to dispose this instance and its associated
+	 * keying material.
+	 *
+	 * @param ciphersuite - For generating signing key material. Only {@link Ciphersuite.MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519} is supported currently
+	 */
+	newAcmeEnrollment(): Promise<WireE2eIdentity>;
 	/**
 	 * Returns the current version of {@link CoreCrypto}
 	 *
@@ -841,5 +979,261 @@ export declare class CoreCrypto {
 	 */
 	static version(): string;
 }
+type JsonRawData = Uint8Array;
+type AcmeAccount = Uint8Array;
+type AcmeOrder = Uint8Array;
+export declare class WireE2eIdentity {
+	#private;
+	/** @hidden */
+	constructor(e2ei: CoreCryptoFfiTypes.WireE2eIdentity, module: typeof CoreCryptoFfiTypes);
+	/**
+	 * Parses the response from `GET /acme/{provisioner-name}/directory`.
+	 * Use this {@link AcmeDirectory} in the next step to fetch the first nonce from the acme server. Use
+	 * {@link AcmeDirectory.newNonce}.
+	 *
+	 * @param directory HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.1.1
+	 */
+	directoryResponse(directory: JsonRawData): AcmeDirectory;
+	/**
+	 * For creating a new acme account. This returns a signed JWS-alike request body to send to
+	 * `POST /acme/{provisioner-name}/new-account`.
+	 *
+	 * @param directory you got from {@link directoryResponse}
+	 * @param previousNonce you got from calling `HEAD {@link AcmeDirectory.newNonce}`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.3
+	 */
+	newAccountRequest(directory: AcmeDirectory, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/new-account`.
+	 * @param account HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.3
+	 */
+	newAccountResponse(account: JsonRawData): AcmeAccount;
+	/**
+	 * Creates a new acme order for the handle (userId + display name) and the clientId.
+	 *
+	 * @param handle domain of the authorization server e.g. `idp.example.org`
+	 * @param clientId domain of the wire-server e.g. `wire.example.org`
+	 * @param expiryDays generated x509 certificate expiry
+	 * @param directory you got from {@link directoryResponse}
+	 * @param account you got from {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/new-account`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	newOrderRequest(handle: string, clientId: string, expiryDays: number, directory: AcmeDirectory, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/new-order`.
+	 *
+	 * @param order HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	newOrderResponse(order: JsonRawData): NewAcmeOrder;
+	/**
+	 * Creates a new authorization request.
+	 *
+	 * @param url one of the URL in new order's authorizations (use {@link NewAcmeOrder.authorizations} from {@link newOrderResponse})
+	 * @param account you got from {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/new-order` (or from the
+	 * previous to this method if you are creating the second authorization)
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5
+	 */
+	newAuthzRequest(url: string, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/authz/{authz-id}`
+	 *
+	 * You then have to map the challenge from this authorization object. The `client_id_challenge`
+	 * will be the one with the `client_id_host` (you supplied to {@link newOrderRequest}) identifier,
+	 * the other will be your `handle_challenge`.
+	 *
+	 * @param authz HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5
+	 */
+	newAuthzResponse(authz: JsonRawData): NewAcmeAuthz;
+	/**
+	 * Generates a new client Dpop JWT token. It demonstrates proof of possession of the nonces
+	 * (from wire-server & acme server) and will be verified by the acme server when verifying the
+	 * challenge (in order to deliver a certificate).
+	 *
+	 * 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 userId an UUIDv4 uniquely identifying the user
+	 * @param clientId client identifier
+	 * @param domain owning backend domain e.g. `wire.com`
+	 * @param clientIdChallenge you found after {@link newAuthzResponse}
+	 * @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}
+	 * @param expiryDays token expiry in days
+	 */
+	createDpopToken(accessTokenUrl: string, userId: string, clientId: bigint, domain: string, clientIdChallenge: AcmeChallenge, backendNonce: string, expiryDays: number): string;
+	/**
+	 * Creates a new challenge request.
+	 *
+	 * @param handleChallenge you found after {@link newAuthzResponse}
+	 * @param account you found after {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/authz/{authz-id}`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5.1
+	 */
+	newChallengeRequest(handleChallenge: AcmeChallenge, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/challenge/{challenge-id}`.
+	 *
+	 * @param challenge HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5.1
+	 */
+	newChallengeResponse(challenge: JsonRawData): void;
+	/**
+	 * Verifies that the previous challenge has been completed.
+	 *
+	 * @param orderUrl `location` header from http response you got from {@link newOrderResponse}
+	 * @param account you found after {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/challenge/{challenge-id}`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	checkOrderRequest(orderUrl: string, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/order/{order-id}`.
+	 *
+	 * @param order HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	checkOrderResponse(order: JsonRawData): AcmeOrder;
+	/**
+	 * Final step before fetching the certificate.
+	 *
+	 * @param domains you want to generate a certificate for e.g. `["wire.com"]`
+	 * @param order you got from {@link checkOrderResponse}
+	 * @param account you found after {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/order/{order-id}`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	finalizeRequest(domains: Uint8Array[], order: AcmeOrder, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/order/{order-id}/finalize`.
+	 *
+	 * @param finalize HTTP response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+	 */
+	finalizeResponse(finalize: JsonRawData): AcmeFinalize;
+	/**
+	 * Creates a request for finally fetching the x509 certificate.
+	 *
+	 * @param finalize you got from {@link finalizeResponse}
+	 * @param account you got from {@link newAccountResponse}
+	 * @param previousNonce `replay-nonce` response header from `POST /acme/{provisioner-name}/order/{order-id}/finalize`
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4.2
+	 */
+	certificateRequest(finalize: AcmeFinalize, account: AcmeAccount, previousNonce: string): JsonRawData;
+	/**
+	 * Parses the response from `POST /acme/{provisioner-name}/certificate/{certificate-id}`.
+	 *
+	 * @param certificateChain HTTP string response body
+	 * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4.2
+	 */
+	certificateResponse(certificateChain: string): Uint8Array[];
+}
+/**
+ * Holds URLs of all the standard ACME endpoint supported on an ACME server.
+ * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.1.1
+ */
+export interface AcmeDirectory {
+	/**
+	 * URL for fetching a new nonce. Use this only for creating a new account.
+	 *
+	 * @readonly
+	 */
+	newNonce: string;
+	/**
+	 * URL for creating a new account.
+	 *
+	 * @readonly
+	 */
+	newAccount: string;
+	/**
+	 * URL for creating a new order.
+	 *
+	 * @readonly
+	 */
+	newOrder: string;
+}
+/**
+ * Result of an order creation
+ * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+ */
+export interface NewAcmeOrder {
+	/**
+	 * Contains raw JSON data of this order. This is parsed by the underlying Rust library hence should not be accessed
+	 *
+	 * @readonly
+	 */
+	delegate: Uint8Array;
+	/**
+	 * An authorization for each domain to create
+	 *
+	 * @readonly
+	 */
+	authorizations: Uint8Array[];
+}
+/**
+ * Result of an authorization creation.
+ * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5
+ */
+export interface NewAcmeAuthz {
+	/**
+	 * DNS entry associated with those challenge
+	 *
+	 * @readonly
+	 */
+	identifier: string;
+	/**
+	 * Challenge for the clientId
+	 *
+	 * @readonly
+	 */
+	wireHttpChallenge: AcmeChallenge | null;
+	/**
+	 * Challenge for the userId and displayName
+	 *
+	 * @readonly
+	 */
+	wireOidcChallenge: AcmeChallenge | null;
+}
+/**
+ * For creating a challenge
+ * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.5.1
+ */
+export interface AcmeChallenge {
+	/**
+	 * Contains raw JSON data of this challenge. This is parsed by the underlying Rust library hence should not be accessed
+	 *
+	 * @readonly
+	 */
+	delegate: Uint8Array;
+	/**
+	 * URL of this challenge
+	 *
+	 * @readonly
+	 */
+	url: string;
+}
+/**
+ * Result from finalize.
+ * @see https://www.rfc-editor.org/rfc/rfc8555.html#section-7.4
+ */
+export interface AcmeFinalize {
+	/**
+	 * Contains raw JSON data of this finalize. This is parsed by the underlying Rust library hence should not be accessed
+	 *
+	 * @readonly
+	 */
+	delegate: Uint8Array;
+	/**
+	 * URL of to use for the last request to fetch the x509 certificate
+	 *
+	 * @readonly
+	 */
+	certificateUrl: string;
+}
 
 export {};