node-tkms 0.11.0-rc8 → 0.11.0

package/kms_lib.d.ts

@@ -1,14 +1,21 @@
 /* tslint:disable */
 /* eslint-disable */
+export function ml_kem_pke_pk_len(): number;
+export function ml_kem_pke_sk_len(): number;
 export function public_sig_key_to_u8vec(pk: PublicSigKey): Uint8Array;
 export function u8vec_to_public_sig_key(v: Uint8Array): PublicSigKey;
 export function private_sig_key_to_u8vec(sk: PrivateSigKey): Uint8Array;
 export function u8vec_to_private_sig_key(v: Uint8Array): PrivateSigKey;
+/**
+ * Create a new [ServerIdAddr] structure that holds an ID and an address
+ * which must be a valid EIP-55 address, notably prefixed with "0x".
+ */
+export function new_server_id_addr(id: number, addr: string): ServerIdAddr;
 /**
  * Instantiate a new client.
  *
- * * `server_addrs` - a list of KMS server EIP-55 addresses,
- * must be prefixed with "0x".
+ * * `server_addrs` - a list of KMS server ID with EIP-55 addresses,
+ * the elements in the list can be created using [new_server_id_addr].
  *
  * * `client_address_hex` - the client (wallet) address in hex,
  * must be prefixed with "0x".
@@ -16,26 +23,35 @@ export function u8vec_to_private_sig_key(v: Uint8Array): PrivateSigKey;
  * * `fhe_parameter` - the parameter choice, which can be either `"test"` or `"default"`.
  * The "default" parameter choice is selected if no matching string is found.
  */
-export function new_client(server_addrs: string[], client_address_hex: string, fhe_parameter: string): Client;
-export function get_server_addrs(client: Client): string[];
+export function new_client(server_addrs: ServerIdAddr[], client_address_hex: string, fhe_parameter: string): Client;
+export function get_server_addrs(client: Client): ServerIdAddr[];
 export function get_client_secret_key(client: Client): PrivateSigKey | undefined;
 export function get_client_address(client: Client): string;
-export function cryptobox_keygen(): PrivateEncKey;
-export function cryptobox_get_pk(sk: PrivateEncKey): PublicEncKey;
-export function cryptobox_pk_to_u8vec(pk: PublicEncKey): Uint8Array;
-export function cryptobox_sk_to_u8vec(sk: PrivateEncKey): Uint8Array;
-export function u8vec_to_cryptobox_pk(v: Uint8Array): PublicEncKey;
-export function u8vec_to_cryptobox_sk(v: Uint8Array): PrivateEncKey;
-export function cryptobox_encrypt(msg: Uint8Array, their_pk: PublicEncKey, my_sk: PrivateEncKey): CryptoBoxCt;
-export function cryptobox_decrypt(ct: CryptoBoxCt, my_sk: PrivateEncKey, their_pk: PublicEncKey): Uint8Array;
+export function ml_kem_pke_keygen(): PrivateEncKeyMlKem512;
+export function ml_kem_pke_get_pk(sk: PrivateEncKeyMlKem512): PublicEncKeyMlKem512;
+export function ml_kem_pke_pk_to_u8vec(pk: PublicEncKeyMlKem512): Uint8Array;
+export function ml_kem_pke_sk_to_u8vec(sk: PrivateEncKeyMlKem512): Uint8Array;
+export function u8vec_to_ml_kem_pke_pk(v: Uint8Array): PublicEncKeyMlKem512;
+export function u8vec_to_ml_kem_pke_sk(v: Uint8Array): PrivateEncKeyMlKem512;
+/**
+ * This function is *not* used by relayer-sdk because the encryption
+ * happens on the KMS side. It's just here for completeness and tests.
+ */
+export function ml_kem_pke_encrypt(msg: Uint8Array, their_pk: PublicEncKeyMlKem512): Uint8Array;
 /**
- * Process the reencryption response from JavaScript objects.
+ * This function is *not* used by relayer-sdk because the decryption
+ * is handled by [process_user_decryption_resp].
+ * It's just here for completeness and tests.
+ */
+export function ml_kem_pke_decrypt(ct: Uint8Array, my_sk: PrivateEncKeyMlKem512): Uint8Array;
+/**
+ * Process the user_decryption response from JavaScript objects.
  * The returned result is a byte array representing a plaintext of any length,
  * postprocessing is returned to turn it into an integer.
  *
- * * `client` - client that wants to perform reencryption.
+ * * `client` - client that wants to perform user_decryption.
  *
- * * `request` - the initial reencryption request JS object.
+ * * `request` - the initial user_decryption request JS object.
  * It can be set to null if `verify` is false.
  * Otherwise the caller needs to give the following JS object.
  * Note that `client_address` and `eip712_verifying_contract` follow EIP-55.
@@ -76,7 +92,8 @@ export function cryptobox_decrypt(ct: CryptoBoxCt, my_sk: PrivateEncKey, their_p
  * [
  *   {
  *     signature: '69e7e040cab157aa819015b321c012dccb1545ffefd325b359b492653f0347517e28e66c572cdc299e259024329859ff9fcb0096e1ce072af0b6e1ca1fe25ec6',
- *     payload: '0100000029...'
+ *     payload: '0100000029...',
+ *     extra_data: '01234...',
  *   }
  * ]
  * ```
@@ -88,22 +105,22 @@ export function cryptobox_decrypt(ct: CryptoBoxCt, my_sk: PrivateEncKey, their_p
  * * `verify` - Whether to perform signature verification for the response.
  * It is insecure if `verify = false`!
  */
-export function process_reencryption_resp_from_js(client: Client, request: any, eip712_domain: any, agg_resp: any, enc_pk: PublicEncKey, enc_sk: PrivateEncKey, verify: boolean): TypedPlaintext[];
+export function process_user_decryption_resp_from_js(client: Client, request: any, eip712_domain: any, agg_resp: any, enc_pk: PublicEncKeyMlKem512, enc_sk: PrivateEncKeyMlKem512, verify: boolean): TypedPlaintext[];
 /**
- * Process the reencryption response from Rust objects.
- * Consider using [process_reencryption_resp_from_js]
+ * Process the user_decryption response from Rust objects.
+ * Consider using [process_user_decryption_resp_from_js]
  * when using the JS API.
  * The result is a byte array representing a plaintext of any length.
  *
- * * `client` - client that wants to perform reencryption.
+ * * `client` - client that wants to perform user_decryption.
  *
- * * `request` - the initial reencryption request.
+ * * `request` - the initial user_decryption request.
  * Must be given if `verify` is true.
  *
  * * `eip712_domain` - the EIP-712 domain.
  * Must be given if `verify` is true.
  *
- * * `agg_resp` - the vector of reencryption responses.
+ * * `agg_resp` - the vector of user_decryption responses.
  *
  * * `enc_pk` - The ephemeral public key.
  *
@@ -112,7 +129,7 @@ export function process_reencryption_resp_from_js(client: Client, request: any,
  * * `verify` - Whether to perform signature verification for the response.
  * It is insecure if `verify = false`!
  */
-export function process_reencryption_resp(client: Client, request: ParsedReencryptionRequest | null | undefined, eip712_domain: Eip712DomainMsg | null | undefined, agg_resp: ReencryptionResponse[], enc_pk: PublicEncKey, enc_sk: PrivateEncKey, verify: boolean): TypedPlaintext[];
+export function process_user_decryption_resp(client: Client, request: ParsedUserDecryptionRequest | null | undefined, eip712_domain: Eip712DomainMsg | null | undefined, agg_resp: UserDecryptionResponse[], enc_pk: PublicEncKeyMlKem512, enc_sk: PrivateEncKeyMlKem512, verify: boolean): TypedPlaintext[];
 export class CiphertextHandle {
   private constructor();
   free(): void;
@@ -128,14 +145,10 @@ export class Client {
   private constructor();
   free(): void;
 }
-export class CryptoBoxCt {
-  private constructor();
-  free(): void;
-}
 /**
- * <https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator>
- * eventually chain_id, verifying_contract and salt will be parsed in to
- * solidity types
+ * Eip712 domain information.
+ * Any constraints specified in the [standard](<https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator>) _must_ be fulfilled.
+ * Furthermore, be aware that all parameters will eventually be parsed into Solidity types.
  */
 export class Eip712DomainMsg {
   private constructor();
@@ -150,11 +163,11 @@ export class Eip712DomainMsg {
 /**
  * Validity of this struct is not checked.
  */
-export class ParsedReencryptionRequest {
+export class ParsedUserDecryptionRequest {
   private constructor();
   free(): void;
 }
-export class PrivateEncKey {
+export class PrivateEncKeyMlKem512 {
   private constructor();
   free(): void;
 }
@@ -162,7 +175,7 @@ export class PrivateSigKey {
   private constructor();
   free(): void;
 }
-export class PublicEncKey {
+export class PublicEncKeyMlKem512 {
   private constructor();
   free(): void;
 }
@@ -170,7 +183,79 @@ export class PublicSigKey {
   private constructor();
   free(): void;
 }
-export class ReencryptionRequest {
+/**
+ * / A unique 32 Byte / 256 Bit ID, to be used to identify a request and
+ * / for retrieving the computed result later on.
+ * / Must be encoded in lower-case hex. The string must NOT contain a `0x` prefix.
+ */
+export class RequestId {
+  private constructor();
+  free(): void;
+  request_id: string;
+}
+export class ServerIdAddr {
+  private constructor();
+  free(): void;
+}
+export class TypedCiphertext {
+  private constructor();
+  free(): void;
+  /**
+   * The actual ciphertext to decrypt, taken directly from fhevm.
+   */
+  ciphertext: Uint8Array;
+  /**
+   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
+   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
+   */
+  fhe_type: number;
+  /**
+   * The external handle of the ciphertext (the handle used in the copro).
+   */
+  external_handle: Uint8Array;
+  /**
+   * The ciphertext format, see CiphertextFormat documentation for details.
+   * CiphertextFormat::default() is used if unspecified.
+   */
+  ciphertext_format: number;
+}
+export class TypedPlaintext {
+  private constructor();
+  free(): void;
+  /**
+   * The actual plaintext in bytes.
+   */
+  bytes: Uint8Array;
+  /**
+   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
+   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
+   */
+  fhe_type: number;
+}
+export class TypedSigncryptedCiphertext {
+  private constructor();
+  free(): void;
+  /**
+   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
+   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
+   */
+  fhe_type: number;
+  /**
+   * The signcrypted payload, using a hybrid encryption approach in
+   * sign-then-encrypt.
+   */
+  signcrypted_ciphertext: Uint8Array;
+  /**
+   * The external handles that were originally in the request.
+   */
+  external_handle: Uint8Array;
+  /**
+   * The packing factor determines whether the decrypted plaintext
+   * has a different way of packing compared to what is specified in the plaintext modulus.
+   */
+  packing_factor: number;
+}
+export class UserDecryptionRequest {
   private constructor();
   free(): void;
   /**
@@ -184,7 +269,7 @@ export class ReencryptionRequest {
    */
   set request_id(value: RequestId | null | undefined);
   /**
-   * The list of ciphertexts to reencrypt.
+   * The list of ciphertexts to decrypt for the user.
    */
   typed_ciphertexts: TypedCiphertext[];
   /**
@@ -198,43 +283,56 @@ export class ReencryptionRequest {
    */
   set key_id(value: RequestId | null | undefined);
   /**
-   * The client's (blockchain wallet) address,
-   * encoded using EIP-55.
+   * The client's (blockchain wallet) address, encoded using EIP-55. I.e. including `0x`.
    */
   client_address: string;
   /**
    * Encoding of the user's public encryption key for this request.
-   * Encoding using the default encoding of libsodium, i.e. the 32 bytes of a
-   * Montgomery point.
+   * This must be a bincode (v.1) encoded ML-KEM 512 key.
    */
   enc_key: Uint8Array;
+  /**
+   * The user's EIP712 domain. This MUST be present. Furthermore, the `verifying_contract` MUST be set and be distinct from `client_address`.
+   */
   get domain(): Eip712DomainMsg | undefined;
+  /**
+   * The user's EIP712 domain. This MUST be present. Furthermore, the `verifying_contract` MUST be set and be distinct from `client_address`.
+   */
   set domain(value: Eip712DomainMsg | null | undefined);
+  /**
+   * Extra data from the gateway.
+   */
+  extra_data: Uint8Array;
 }
-export class ReencryptionResponse {
+export class UserDecryptionResponse {
   private constructor();
   free(): void;
   signature: Uint8Array;
   /**
    * This is the external signature created from the Eip712 domain
-   * on the structure, where reencryptedShare is bincode::serialize(&payload)
+   * on the structure, where userDecryptedShare is bc2wrap::serialize(&payload)
    * struct UserDecryptResponseVerification {
    *      bytes publicKey;
    *      uint256\[\] ctHandles;
-   *      bytes reencryptedShare;
+   *      bytes userDecryptedShare; // serialization of payload
+   *      bytes extraData;
    * }
    */
   external_signature: Uint8Array;
   /**
-   * The actual \[ReencryptionResponsePayload\].
+   * The actual \[UserDecryptionResponsePayload\].
    */
-  get payload(): ReencryptionResponsePayload | undefined;
+  get payload(): UserDecryptionResponsePayload | undefined;
   /**
-   * The actual \[ReencryptionResponsePayload\].
+   * The actual \[UserDecryptionResponsePayload\].
    */
-  set payload(value: ReencryptionResponsePayload | null | undefined);
+  set payload(value: UserDecryptionResponsePayload | null | undefined);
+  /**
+   * Extra data used in the EIP712 signature - external_signature.
+   */
+  extra_data: Uint8Array;
 }
-export class ReencryptionResponsePayload {
+export class UserDecryptionResponsePayload {
   private constructor();
   free(): void;
   /**
@@ -256,7 +354,7 @@ export class ReencryptionResponsePayload {
    */
   signcrypted_ciphertexts: TypedSigncryptedCiphertext[];
   /**
-   * The ID of the MPC party doing the reencryption. Used for polynomial
+   * The ID of the MPC party doing the user decryption. Used for polynomial
    * reconstruction.
    */
   party_id: number;
@@ -265,73 +363,3 @@ export class ReencryptionResponsePayload {
    */
   degree: number;
 }
-/**
- * Simple response to return a 32 Byte / 256 Bit ID, to be used to retrieve the
- * computed result later on. This string does NOT contain a `0x` prefix.
- */
-export class RequestId {
-  private constructor();
-  free(): void;
-  request_id: string;
-}
-export class TypedCiphertext {
-  private constructor();
-  free(): void;
-  /**
-   * The actual ciphertext to decrypt, taken directly from fhevm.
-   */
-  ciphertext: Uint8Array;
-  /**
-   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
-   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
-   */
-  fhe_type: number;
-  /**
-   * The external handle of the ciphertext (the handle used in the copro).
-   */
-  external_handle: Uint8Array;
-  /**
-   * The ciphertext format, see CiphertextFormat documentation for details.
-   * CiphertextFormat::default() is used if unspecified.
-   */
-  ciphertext_format: number;
-}
-/**
- * The typed plaintext type, which is the result of decryption.
- */
-export class TypedPlaintext {
-  private constructor();
-  free(): void;
-  /**
-   * The actual plaintext in bytes.
-   */
-  bytes: Uint8Array;
-  /**
-   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
-   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
-   */
-  fhe_type: number;
-}
-export class TypedSigncryptedCiphertext {
-  private constructor();
-  free(): void;
-  /**
-   * The type of plaintext encrypted. The type should match FheType from tfhe-rs:
-   * <https://github.com/zama-ai/tfhe-rs/blob/main/tfhe/src/high_level_api/mod.rs>
-   */
-  fhe_type: number;
-  /**
-   * The signcrypted payload, using a hybrid encryption approach in
-   * sign-then-encrypt.
-   */
-  signcrypted_ciphertext: Uint8Array;
-  /**
-   * The external handles that were originally in the request.
-   */
-  external_handle: Uint8Array;
-  /**
-   * The packing factor determines whether the decrypted plaintext
-   * has a different way of packing compared to what is specified in the plaintext modulus.
-   */
-  packing_factor: number;
-}