feat(1953): added key generation and import commands (#1959)

Signed-off-by: mmyslblocky <michal.myslinski@blockydevs.com>

Author: mmyslblocky

README.md

@@ -297,7 +297,7 @@ The Hiero CLI is built on a plugin architecture. The following default plugins a
 - **[Token Plugin](src/plugins/token/README.md)** - Create, view, associate, and transfer fungible and non-fungible tokens
 - **[Network Plugin](src/plugins/network/README.md)** - Switch networks, manage operator credentials, and check network health
 - **[HBAR Plugin](src/plugins/hbar/README.md)** - Transfer HBAR between accounts
-- **[Credentials Plugin](src/plugins/credentials/README.md)** - Manage operator credentials and keys
+- **[Credentials Plugin](src/plugins/credentials/README.md)** - Generate and import standalone private keys, list and remove stored key credentials
 - **[Plugin Management Plugin](src/plugins/plugin-management/README.md)** - Add, remove, enable/disable, and inspect plugins
 - **[Topic Plugin](src/plugins/topic/README.md)** - Create topics and manage topic messages
 - **[Config Plugin](src/plugins/config/README.md)** - Inspect and update CLI configuration values

skills/hiero-cli/SKILL.md

@@ -79,7 +79,7 @@ State is persisted in `~/.hiero-cli/state/` as JSON files, one per plugin namesp
 | `contract-erc721`   | ERC-721 contract calls     | balanceOf, ownerOf, approve, setApprovalForAll, safeTransferFrom, transferFrom, mint, name, symbol, tokenURI, getApproved, isApprovedForAll. **Requires `contract` plugin** (contract must be deployed first)                                                                           |
 | `network`           | Network configuration      | list networks, switch network, set/get operator                                                                                                                                                                                                                                         |
 | `config`            | CLI configuration          | list, get, set config options                                                                                                                                                                                                                                                           |
-| `credentials`       | Key/credentials management | list, remove stored credentials                                                                                                                                                                                                                                                         |
+| `credentials`       | Key/credentials management | generate new key, import existing key, list, remove stored credentials (by id or alias)                                                                                                                                                                                                 |
 | `batch`             | Batch transactions         | create batch, add transactions, execute, list, delete                                                                                                                                                                                                                                   |
 | `swap`              | Multi-party asset exchange | create swap, add HBAR/FT/NFT transfers, view, list, execute, delete                                                                                                                                                                                                                     |
 | `eip712`            | EIP-712 typed data signing | `hash` compute digest, `sign-ecdsa` / `sign-ed25519` sign payload (accepts pre-computed hash or domain+types+message), `verify-ecdsa` recover signer EVM address, `verify-ed25519` verify Ed25519 signature against a public key                                                        |

skills/hiero-cli/references/credentials.md

@@ -1,39 +1,87 @@
 # credentials plugin
 
-Manage stored credentials (keys) in the KMS: list all key references, remove specific credentials.
+Generate, import, list, and remove standalone private keys (key credentials) in the KMS.
 
 Key references (format: `kr_xxx`) are identifiers for keys stored in the local key manager. They can be used in place of inline `accountId:privateKey` pairs in any command that accepts keys.
 
+Key aliases (`--alias`) are human-readable names scoped to the current network that point to a key reference. They are distinct from account aliases — a key alias has no associated Hedera account ID.
+
+---
+
+### `hcli credentials generate`
+
+Generate a new private key in KMS and optionally assign a key alias.
+
+| Option          | Short | Type   | Required | Description                                   |
+| --------------- | ----- | ------ | -------- | --------------------------------------------- |
+| `--alias`       | `-a`  | string | no       | Human-readable alias to assign to this key    |
+| `--key-type`    | `-t`  | string | no       | Key algorithm: `ecdsa` (default) or `ed25519` |
+| `--key-manager` | `-k`  | string | no       | Storage method: `local` or `local_encrypted`  |
+
+**Example:**
+
+```
+hcli credentials generate
+hcli credentials generate --alias my-signing-key --key-type ed25519
+```
+
+**Output:** `{ keyRefId, publicKey, keyAlgorithm, keyManager, alias?, network? }`
+
+---
+
+### `hcli credentials import`
+
+Import an existing private key into KMS and optionally assign a key alias.
+
+| Option          | Short | Type   | Required | Description                                                                                    |
+| --------------- | ----- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
+| `--key`         | `-K`  | string | **yes**  | Key to import: `{accountId}:{privateKey}`, `{ed25519\|ecdsa}:private:{hex}`, key ref, or alias |
+| `--alias`       | `-a`  | string | no       | Alias to assign to this key                                                                    |
+| `--key-manager` | `-k`  | string | no       | Storage method: `local` or `local_encrypted` (defaults to config setting)                      |
+
+**Example:**
+
+```
+hcli credentials import --key ecdsa:private:abc123... --alias my-key
+hcli credentials import --key 0.0.123456:302e... --key-manager local_encrypted
+```
+
+**Output:** `{ keyRefId, publicKey, keyManager, alias?, network? }`
+
 ---
 
 ### `hcli credentials list`
 
-Show all stored credentials and their key reference IDs. No options.
+Show all stored credentials and their metadata, including any linked key alias on the current network. No options.
 
 **Example:**
 
 ```
 hcli credentials list
 ```
 
-**Output:** Array of `{ keyRefId, accountId?, keyType, keyManager }`
+**Output:** `{ credentials: [{ keyRefId, keyManager, publicKey, keyAlgorithm, alias?, labels? }], totalCount }`
 
 ---
 
 ### `hcli credentials remove`
 
-Remove credentials by key reference ID from KMS storage.
+Remove credentials by key reference ID or key alias. Exactly one of `--id` or `--alias` must be provided.
+
+Removing by `--id` also unregisters any key alias on the current network that points to that key, preventing dangling alias references.
 
-⚠️ Requires confirmation. Use `--confirm` to skip.
+⚠️ Requires confirmation. Use `--confirm` (`-Y`) to skip.
 
-| Option | Short | Type   | Required | Description                                   |
-| ------ | ----- | ------ | -------- | --------------------------------------------- |
-| `--id` | `-i`  | string | **yes**  | Key reference ID to remove (e.g. `kr_abc123`) |
+| Option    | Short | Type   | Required    | Description                                      |
+| --------- | ----- | ------ | ----------- | ------------------------------------------------ |
+| `--id`    | `-i`  | string | one of both | Key reference ID to remove (e.g. `kr_abc123`)    |
+| `--alias` | `-a`  | string | one of both | Key alias to remove (also unregisters the alias) |
 
 **Example:**
 
 ```
 hcli credentials remove --id kr_abc123 --confirm
+hcli credentials remove --alias my-signing-key --confirm
 ```
 
-**Output:** `{ keyRefId, removed: true }`
+**Output:** `{ keyRefId }`

src/__tests__/integration/credentials/credentials.integration.test.ts

@@ -44,7 +44,6 @@ describe('Credentials Integration Tests', () => {
     });
     const removeOutput = removeResult.result as CredentialsRemoveOutput;
     expect(removeOutput.keyRefId).toBe('test-key');
-    expect(removeOutput.removed).toBe(true);
 
     const listAfterResult = await credentialsList({
       args: {},

src/core/services/key-resolver/__tests__/unit/key-resolver-service.test.ts

@@ -78,12 +78,26 @@ const makeKmsMock = (): jest.Mocked<
 
 const makeAliasMock = (): jest.Mocked<Pick<AliasService, 'resolve'>> => ({
   resolve: jest.fn().mockReturnValue({
+    alias: 'my-alias',
+    type: AliasType.Account,
+    network: SupportedNetwork.TESTNET,
     entityId: ACCOUNT_ID,
     publicKey: PUBLIC_KEY,
     keyRefId: KEY_REF_ID,
+    createdAt: '2024-01-01T00:00:00Z',
   }),
 });
 
+const makeKeyAliasRecord = (overrides?: Record<string, unknown>) => ({
+  alias: 'my-key',
+  type: AliasType.Key,
+  network: SupportedNetwork.TESTNET,
+  publicKey: PUBLIC_KEY,
+  keyRefId: KEY_REF_ID,
+  createdAt: '2024-01-01T00:00:00Z',
+  ...overrides,
+});
+
 const makeNetworkMock = (): jest.Mocked<
   Pick<NetworkService, 'getCurrentNetwork' | 'getCurrentOperatorOrThrow'>
 > => ({
@@ -173,7 +187,7 @@ describe('resolveAccountCredentials', () => {
 
     expect(alias.resolve).toHaveBeenCalledWith(
       'my-alias',
-      AliasType.Account,
+      undefined,
       SupportedNetwork.TESTNET,
     );
     expect(result.accountId).toBe(ACCOUNT_ID);
@@ -224,6 +238,86 @@ describe('resolveAccountCredentials', () => {
   });
 });
 
+// ── resolveAlias (Key aliases) ────────────────────────────────────────────────
+
+describe('resolveAlias - Key aliases', () => {
+  test('resolves a Key alias to a signing key (publicKey + keyRefId, no accountId)', async () => {
+    const { service } = makeService({
+      alias: { resolve: jest.fn().mockReturnValue(makeKeyAliasRecord()) },
+    });
+
+    const result = await service.resolveSigningKey(
+      { type: CredentialType.ALIAS, alias: 'my-key', rawValue: 'my-key' },
+      KEY_MGR,
+    );
+
+    expect(result).toEqual({ keyRefId: KEY_REF_ID, publicKey: PUBLIC_KEY });
+  });
+
+  test('resolves a Key alias via getPublicKey', async () => {
+    const { service } = makeService({
+      alias: { resolve: jest.fn().mockReturnValue(makeKeyAliasRecord()) },
+    });
+
+    const result = await service.getPublicKey(
+      { type: CredentialType.ALIAS, alias: 'my-key', rawValue: 'my-key' },
+      KEY_MGR,
+    );
+
+    expect(result).toEqual({ keyRefId: KEY_REF_ID, publicKey: PUBLIC_KEY });
+  });
+
+  test('rejects a Key alias used as a full account credential (no accountId)', async () => {
+    const { service } = makeService({
+      alias: { resolve: jest.fn().mockReturnValue(makeKeyAliasRecord()) },
+      mirror: { getAccounts: jest.fn().mockResolvedValue({ accounts: [] }) },
+    });
+
+    await expect(
+      service.resolveAccountCredentials(
+        { type: CredentialType.ALIAS, alias: 'my-key', rawValue: 'my-key' },
+        KEY_MGR,
+      ),
+    ).rejects.toThrow(StateError);
+  });
+
+  test('throws StateError when Key alias is missing keyRefId', async () => {
+    const { service } = makeService({
+      alias: {
+        resolve: jest
+          .fn()
+          .mockReturnValue(makeKeyAliasRecord({ keyRefId: undefined })),
+      },
+    });
+
+    await expect(
+      service.resolveSigningKey(
+        { type: CredentialType.ALIAS, alias: 'my-key', rawValue: 'my-key' },
+        KEY_MGR,
+      ),
+    ).rejects.toThrow(StateError);
+  });
+
+  test('throws ValidationError when alias is neither account nor key (e.g. Token)', async () => {
+    const { service } = makeService({
+      alias: {
+        resolve: jest
+          .fn()
+          .mockReturnValue(
+            makeKeyAliasRecord({ type: AliasType.Token, alias: 'my-token' }),
+          ),
+      },
+    });
+
+    await expect(
+      service.resolveSigningKey(
+        { type: CredentialType.ALIAS, alias: 'my-token', rawValue: 'my-token' },
+        KEY_MGR,
+      ),
+    ).rejects.toThrow(ValidationError);
+  });
+});
+
 // ── getPublicKey ──────────────────────────────────────────────────────────────
 
 describe('getPublicKey', () => {

src/core/services/key-resolver/key-resolver-service.ts

@@ -217,7 +217,7 @@ export class KeyResolverServiceImpl implements KeyResolverService {
       case CredentialType.KEY_REFERENCE:
         return this.resolveKeyReference(credential);
       case CredentialType.ALIAS:
-        return Promise.resolve(this.resolveAlias(credential));
+        return this.resolveAlias(credential);
       case CredentialType.EVM_ADDRESS:
         return this.resolveEvmAddress(credential, keyManager, labels);
     }
@@ -467,43 +467,65 @@ export class KeyResolverServiceImpl implements KeyResolverService {
     return { accountId, evmAddress, publicKey, keyRefId };
   }
 
-  private resolveAlias(aliasCredential: AliasCredential): ResolvedKey {
+  private async resolveAlias(
+    aliasCredential: AliasCredential,
+  ): Promise<ResolvedKey> {
     const currentNetwork = this.network.getCurrentNetwork();
 
-    const account = this.alias.resolve(
+    // Alias names are unique per network regardless of type, so resolve
+    // without a type expectation and branch on the record's type.
+    const record = this.alias.resolve(
       aliasCredential.alias,
-      AliasType.Account,
+      undefined,
       currentNetwork,
     );
 
-    if (!account) {
-      throw new NotFoundError(
-        `Account alias not found: ${aliasCredential.alias}`,
-        {
-          context: { alias: aliasCredential.alias, network: currentNetwork },
-        },
-      );
+    if (!record) {
+      throw new NotFoundError(`Alias not found: ${aliasCredential.alias}`, {
+        context: { alias: aliasCredential.alias, network: currentNetwork },
+      });
     }
 
-    if (!account.publicKey || !account.keyRefId || !account.entityId) {
-      throw new StateError(
-        'Account alias exists but missing required key data',
-        {
-          context: {
-            alias: aliasCredential.alias,
-            hasPublicKey: !!account.publicKey,
-            hasKeyRefId: !!account.keyRefId,
-            hasEntityId: !!account.entityId,
+    switch (record.type) {
+      case AliasType.Account: {
+        return {
+          accountId: record.entityId,
+          publicKey: record.publicKey,
+          keyRefId: record.keyRefId,
+        };
+      }
+
+      case AliasType.Key: {
+        const { accounts } = await this.mirror.getAccounts({
+          accountPublicKey: record.publicKey,
+        });
+        let accountId;
+        if (accounts.length == 1) {
+          accountId = accounts[0].accountId;
+        } else {
+          this.logger.warn(
+            `There cannot be one single account ID assigned to key as there are ${accounts.length} results from Hedera Mirror Node`,
+          );
+        }
+        return {
+          accountId,
+          publicKey: record.publicKey,
+          keyRefId: record.keyRefId,
+        };
+      }
+
+      default:
+        throw new ValidationError(
+          `Alias "${aliasCredential.alias}" is not a usable account or key`,
+          {
+            context: {
+              alias: aliasCredential.alias,
+              type: record.type,
+              network: currentNetwork,
+            },
           },
-        },
-      );
+        );
     }
-
-    return {
-      accountId: account.entityId,
-      publicKey: account.publicKey,
-      keyRefId: account.keyRefId,
-    };
   }
 
   public async resolveSigningKeys(

src/core/services/kms/__tests__/unit/kms-service.test.ts

@@ -421,4 +421,31 @@ describe('KmsServiceImpl', () => {
       expect.any(Object),
     );
   });
+
+  it('list() includes keyAlgorithm for each credential', () => {
+    const { service } = setupService();
+    credentialStorageMockInstance.list.mockReturnValue([
+      {
+        keyRefId: 'kr_one',
+        keyManager: KeyManager.local,
+        publicKey: 'pub-one',
+        labels: ['account:create'],
+        keyAlgorithm: KeyAlgorithm.ECDSA,
+        createdAt: '2024-01-01T00:00:00Z',
+        updatedAt: '2024-01-01T00:00:00Z',
+      },
+    ]);
+
+    const result = service.list();
+
+    expect(result).toEqual([
+      {
+        keyRefId: 'kr_one',
+        keyManager: KeyManager.local,
+        publicKey: 'pub-one',
+        labels: ['account:create'],
+        keyAlgorithm: KeyAlgorithm.ECDSA,
+      },
+    ]);
+  });
 });

src/core/services/kms/kms-service.interface.ts

@@ -88,6 +88,7 @@ export interface KmsService {
     keyManager: KeyManager;
     publicKey: string;
     labels?: string[];
+    keyAlgorithm: KeyAlgorithm;
   }>;
 
   /**