@wireapp/core-crypto 8.0.3 → 9.0.0

package/src/corecrypto.d.ts

@@ -2,7 +2,13 @@
 
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * Construct a ciphersuite enum instance from its discriminant.
+ */
 export function ciphersuiteFromU16(discriminant: number): Ciphersuite;
+/**
+ * Get an instance of the default ciphersuite.
+ */
 export function ciphersuiteDefault(): Ciphersuite;
 /**
  * Updates the key of the CoreCrypto database.
@@ -46,6 +52,9 @@ export enum Ciphersuite {
 	 */
 	MLS_256_DHKEMP384_AES256GCM_SHA384_P384 = 7
 }
+/**
+ * Type of Credential
+ */
 export enum CredentialType {
 	/**
 	 * Basic credential i.e. a KeyPair
@@ -56,6 +65,11 @@ export enum CredentialType {
 	 */
 	X509 = 2
 }
+/**
+ * Indicates the standalone status of a device Credential in a MLS group at a moment T.
+ *
+ * This does not represent the states where a device is not using MLS or is not using end-to-end identity
+ */
 export enum DeviceStatus {
 	/**
 	 * All is fine
@@ -165,15 +179,24 @@ declare class AcmeDirectory {
 declare class BufferedDecryptedMessage {
 	private constructor();
 	free(): void;
+	/**
+	 * Decrypted plaintext
+	 */
 	readonly message: Uint8Array | undefined;
 	/**
-	 * It is set to false if ingesting this MLS message has resulted in the client being removed from the group (i.e. a Remove commit)
+	 * False if processing this message caused the client to be removed from the group, i.e. due to a Remove commit
 	 */
 	readonly isActive: boolean;
 	/**
-	 * Commit delay hint (in milliseconds) to prevent clients from hammering the server with epoch changes
+	 * Commit delay in seconds.
+	 *
+	 * When set, clients must delay this long before processing a commit.
+	 * This reduces load on the backend, which otherwise would receive epoch change notifications from all clients simultaneously.
 	 */
 	readonly commitDelay: bigint | undefined;
+	/**
+	 * [ClientId] of the sender of the message being decrypted. Only present for application messages.
+	 */
 	readonly senderClientId: ClientId | undefined;
 	/**
 	 * true when the decrypted message resulted in an epoch change i.e. it was a commit
@@ -181,9 +204,12 @@ declare class BufferedDecryptedMessage {
 	 * Deprecated: this member will be removed in the future. Prefer using the `EpochObserver` interface.
 	 */
 	readonly hasEpochChanged: boolean;
+	/**
+	 * Identity claims present in the sender credential
+	 */
 	readonly identity: WireIdentity;
 	/**
-	 * New CRL Distribution of members of this group
+	 * New CRL distribution points that appeared by the introduction of a new credential
 	 */
 	readonly crlNewDistributionPoints: string[] | undefined;
 }
@@ -238,16 +264,41 @@ export class BuildMetadata {
 	 */
 	readonly gitDirty: string;
 }
+/**
+ * A Client identifier
+ *
+ * A unique identifier for clients. A client is an identifier for each App a user is using, such as desktop,
+ * mobile, etc. Users can have multiple clients.
+ * More information [here](https://messaginglayersecurity.rocks/mls-architecture/draft-ietf-mls-architecture.html#name-group-members-and-clients)
+ */
 export class ClientId {
 	free(): void;
+	/**
+	 * Instantiate a client id from a byte array.
+	 */
 	constructor(bytes: Uint8Array);
+	/**
+	 * Copy the id into a new byte array.
+	 */
 	copyBytes(): Uint8Array;
 }
 declare class ConversationConfiguration {
 	free(): void;
+	/**
+	 * Construct a `ConversationConfiguration` from its parts.
+	 */
 	constructor(ciphersuite?: Ciphersuite | null, external_senders?: ExternalSenderKey[] | null, key_rotation_span?: number | null, wire_policy?: WirePolicy | null);
+	/**
+	 * The ciphersuite used in the group
+	 */
 	readonly ciphersuite: Ciphersuite | undefined;
+	/**
+	 * Delivery service public signature key and credential
+	 */
 	readonly externalSenders: ExternalSenderKey[];
+	/**
+	 * Implementation specific configuration
+	 */
 	readonly custom: CustomConfiguration;
 }
 /**
@@ -465,6 +516,15 @@ declare class CoreCryptoContext {
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_decrypt]
 	 */
 	proteus_decrypt(session_id: string, ciphertext: Uint8Array): Promise<Uint8Array>;
+	/**
+	 * Decrypt a message whether or not the proteus session already exists, and saves the session.
+	 *
+	 * This is intended to replace simple usages of `proteusDecrypt`.
+	 *
+	 * However, when decrypting large numbers of messages in a single session, the existing methods
+	 * may be more efficient.
+	 */
+	proteus_decrypt_safe(session_id: string, ciphertext: Uint8Array): Promise<Uint8Array>;
 	/**
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_encrypt]
 	 */
@@ -474,10 +534,18 @@ declare class CoreCryptoContext {
 	 */
 	proteus_encrypt_batched(sessions: string[], plaintext: Uint8Array): Promise<Map<string, Uint8Array>>;
 	/**
+	 * Creates a new Proteus prekey with the given id and returns the CBOR-serialized version of the prekey bundle
+	 *
+	 * Warning: The Proteus client **MUST** be initialized with `proteus_init` first or an error will be returned
+	 *
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_new_prekey]
 	 */
 	proteus_new_prekey(prekey_id: number): Promise<Uint8Array>;
 	/**
+	 * Creates a new Proteus prekey with an automatically incremented ID and returns the CBOR-serialized version of the prekey bundle
+	 *
+	 * Warning: The Proteus client **MUST** be initialized with `proteus_init` first or an error will be returned
+	 *
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_new_prekey_auto]
 	 */
 	proteus_new_prekey_auto(): Promise<ProteusAutoPrekeyBundle>;
@@ -497,10 +565,6 @@ declare class CoreCryptoContext {
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_fingerprint_remote]
 	 */
 	proteus_fingerprint_remote(session_id: string): Promise<string>;
-	/**
-	 * See [core_crypto::transaction_context::TransactionContext::proteus_cryptobox_migrate]
-	 */
-	proteus_cryptobox_migrate(path: string): Promise<void>;
 	/**
 	 * See [core_crypto::transaction_context::TransactionContext::proteus_reload_sessions]
 	 */
@@ -528,6 +592,9 @@ declare class CoreCryptoContext {
 }
 declare class CrlRegistration {
 	free(): void;
+	/**
+	 * Contstruct a CRL registration from its fields
+	 */
 	constructor(dirty: boolean, expiration?: bigint | null);
 	/**
 	 * Whether this CRL modifies the old CRL (i.e. has a different revocated cert list)
@@ -547,6 +614,9 @@ declare class CrlRegistration {
  */
 export class CustomConfiguration {
 	free(): void;
+	/**
+	 * Construct a `CustomConfiguration` from its parts.
+	 */
 	constructor(key_rotation_span?: number | null, wire_policy?: WirePolicy | null);
 	/**
 	 *  Duration in seconds after which we will automatically force a self-update commit
@@ -569,22 +639,37 @@ export class CustomConfiguration {
 	 */
 	set wirePolicy(value: WirePolicy | null | undefined);
 }
+/**
+ * The key used to encrypt the database.
+ */
 export class DatabaseKey {
 	free(): void;
+	/**
+	 * Construct a new instance from a byte vector.
+	 */
 	constructor(buf: Uint8Array);
 }
 declare class DecryptedMessage {
 	private constructor();
 	free(): void;
+	/**
+	 * Decrypted plaintext
+	 */
 	readonly message: Uint8Array | undefined;
 	/**
-	 * It is set to false if ingesting this MLS message has resulted in the client being removed from the group (i.e. a Remove commit)
+	 * False if processing this message caused the client to be removed from the group, i.e. due to a Remove commit
 	 */
 	readonly isActive: boolean;
 	/**
-	 * Commit delay hint (in milliseconds) to prevent clients from hammering the server with epoch changes
+	 * Commit delay in seconds.
+	 *
+	 * When set, clients must delay this long before processing a commit.
+	 * This reduces load on the backend, which otherwise would receive epoch change notifications from all clients simultaneously.
 	 */
 	readonly commitDelay: bigint | undefined;
+	/**
+	 * [ClientId] of the sender of the message being decrypted. Only present for application messages.
+	 */
 	readonly senderClientId: ClientId | undefined;
 	/**
 	 * true when the decrypted message resulted in an epoch change i.e. it was a commit
@@ -592,10 +677,19 @@ declare class DecryptedMessage {
 	 * Deprecated: this member will be removed in the future. Prefer using the `EpochObserver` interface.
 	 */
 	readonly hasEpochChanged: boolean;
+	/**
+	 * Identity claims present in the sender credential
+	 */
 	readonly 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.
+	 */
 	readonly bufferedMessages: BufferedDecryptedMessage[] | undefined;
 	/**
-	 * New CRL Distribution of members of this group
+	 * New CRL distribution points that appeared by the introduction of a new credential
 	 */
 	readonly crlNewDistributionPoints: string[] | undefined;
 }
@@ -721,9 +815,19 @@ declare class KeyPackage {
 	 */
 	copyBytes(): Uint8Array;
 }
+/**
+ * An entity / data which has been packaged by the application to be encrypted
+ * and transmitted in an application message.
+ */
 export class MlsTransportData {
 	free(): void;
+	/**
+	 * Construct `MlsTransportData` by providing data
+	 */
 	constructor(buf: Uint8Array);
+	/**
+	 * The specific data which has been packaged to be encrypted/transmitted.
+	 */
 	readonly data: Uint8Array;
 }
 /**
@@ -757,13 +861,25 @@ export class NewAcmeAuthz {
 export class NewAcmeOrder {
 	private constructor();
 	free(): void;
+	/**
+	 * Opaque raw json value
+	 */
 	readonly delegate: Uint8Array;
+	/**
+	 * Authorizations to create with `new_authz_request`
+	 */
 	readonly authorizations: string[];
 }
 declare class ProteusAutoPrekeyBundle {
 	private constructor();
 	free(): void;
+	/**
+	 * Prekey id (automatically incremented)
+	 */
 	readonly id: number;
+	/**
+	 * CBOR serialization of prekey
+	 */
 	readonly pkb: Uint8Array;
 }
 /**
@@ -819,7 +935,8 @@ export class WelcomeBundle {
 	readonly crlNewDistributionPoints: string[] | undefined;
 }
 /**
- * See [core_crypto::prelude::WireIdentity]
+ * Represents the identity claims identifying a client
+ * Those claims are verifiable by any member in the group
  */
 export class WireIdentity {
 	private constructor();
@@ -836,21 +953,51 @@ export class WireIdentity {
 	 * MLS thumbprint
 	 */
 	readonly thumbprint: string;
+	/**
+	 * Indicates whether the credential is Basic or X509
+	 */
 	credentialType: CredentialType;
+	/**
+	 * In case 'credential_type' is [CredentialType::X509] this is populated
+	 */
 	readonly x509Identity: X509Identity | undefined;
 }
 /**
- * See [core_crypto::prelude::X509Identity]
+ * Represents the parts of [WireIdentity][crate::WireIdentity] that are specific to a X509 certificate (and not a Basic one).
+ *
+ * We don't use an enum here since the sole purpose of this is to be exposed through the FFI (and
+ * union types are impossible to carry over the FFI boundary)
  */
 export class X509Identity {
 	private constructor();
 	free(): void;
+	/**
+	 * user handle e.g. `john_wire`
+	 */
 	readonly handle: string;
+	/**
+	 * Name as displayed in the messaging application e.g. `John Fitzgerald Kennedy`
+	 */
 	readonly displayName: string;
+	/**
+	 * DNS domain for which this identity proof was generated e.g. `whitehouse.gov`
+	 */
 	readonly domain: string;
+	/**
+	 * X509 certificate identifying this client in the MLS group ; PEM encoded
+	 */
 	readonly certificate: string;
+	/**
+	 * X509 certificate serial number
+	 */
 	readonly serialNumber: string;
+	/**
+	 * X509 certificate not before as Unix timestamp
+	 */
 	readonly notBefore: bigint;
+	/**
+	 * X509 certificate not after as Unix timestamp
+	 */
 	readonly notAfter: bigint;
 }
 interface ConversationConfiguration$1 {
@@ -1642,12 +1789,6 @@ declare class CoreCryptoContext$1 {
 	 * @returns Hex-encoded public key string
 	 **/
 	static proteusFingerprintPrekeybundle(prekey: Uint8Array): string;
-	/**
-	 * Imports all the data stored by Cryptobox into the CoreCrypto keystore
-	 *
-	 * @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.