import type { Hasher } from './hasher.js';
import type { Signer } from './signer.js';
import type { KeyIdentifier } from './identifier.js';
import type { AsymmetricKeyGenerator } from './key-generator.js';
import type {
  KmsSignParams,
  KmsDigestParams,
  KmsVerifyParams,
  KmsGetKeyUriParams,
  KmsGenerateKeyParams,
  KmsGetPublicKeyParams,
} from './params-kms.js';

/**
 * The `CryptoApi` interface integrates key generation, hashing, and signing functionalities,
 * designed for use with a Key Management System (KMS). It extends `AsymmetricKeyGenerator` for
 * generating asymmetric keys, `Hasher` for hash digest computations, and `Signer` for signing and
 * verifying operations.
 *
 * Concrete implementations of this interface are intended to be used with a KMS, which is
 * responsible for generating and storing cryptographic keys. The KMS is also responsible for
 * performing cryptographic operations using the keys it manages. The KMS is typically a cloud
 * service, but it can also be a hardware device or software application.
 *
 * Guidelines for implementing this interface:
 * - Must use JSON Web Keys ({@link Jwk | JWK}) as the key format.
 * - Must IANA registered JSON Object Signing and Encryption
 *   {@ link https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms | (JOSE)}
 *   names for algorithm, curves, etc. whenever possible.
 * - All I/O that interacts with private or secret keys must be done via reference using a
 *   {@link KeyIdentifier | `KeyIdentifier`}. Implementations can use any string as the key
 *   identifier (e.g. JWK thumbprint, UUID generated by hosted KMS, etc.).
 * - Must support key generation, hashing, signing, and verifying operations.
 * - May be extended to support other cryptographic operations.
 * - Implementations of the `CryptoApi` interface can be passed as an argument to the public API
 *   methods of Web5 libraries that involve key material (e.g., DID creation, VC signing, arbitrary
 *   data signing/verification, etc.).
 */
export interface CryptoApi<
  GenerateKeyInput = KmsGenerateKeyParams,
  GenerateKeyOutput = KeyIdentifier,
  GetPublicKeyInput = KmsGetPublicKeyParams,
  DigestInput = KmsDigestParams,
  SignInput = KmsSignParams,
  VerifyInput = KmsVerifyParams
> extends AsymmetricKeyGenerator<GenerateKeyInput, GenerateKeyOutput, GetPublicKeyInput>,
          Hasher<DigestInput>,
          Signer<SignInput, VerifyInput> {
  /**
   *
   * @param params - The parameters for getting the key URI.
   * @param params.key - The key to get the URI for.
   * @returns The key URI.
   */
  getKeyUri(params: KmsGetKeyUriParams): Promise<KeyIdentifier>;
}