feat(1861): eip-712 signing plugin (#1914)

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

Author: mmyslblocky

README.md

@@ -307,6 +307,7 @@ The Hiero CLI is built on a plugin architecture. The following default plugins a
 - **[Swap Plugin](src/plugins/swap/README.md)** - Build and execute multi-party HBAR/token swaps in a single transaction
 - **[Batch Plugin](src/plugins/batch/README.md)** - Group multiple transactions into a single atomic batch transaction
 - **[Schedule Plugin](src/plugins/schedule/README.md)** - Create, sign, delete, and manage Hedera scheduled transactions
+- **[EIP-712 Plugin](src/plugins/eip712/README.md)** - Sign and verify EIP-712 structured typed data using ECDSA keys managed by the CLI KMS
 
 Each plugin has its own README with detailed documentation about available commands, usage examples, and architecture details. Click on the plugin name above to learn more.
 

docs/architecture.md

@@ -55,6 +55,7 @@ The Hiero CLI is built on a plugin-based architecture designed to be extensible,
 │  ├── Contract Plugin                                        │
 │  ├── Contract ERC-20 Plugin                                 │
 │  ├── Contract ERC-721 Plugin                                │
+│  ├── EIP-712 Plugin                                         │
 │  └── [Custom Plugins]                                       │
 └─────────────────────────────────────────────────────────────┘
 ```

docs/documentation-overview.md

@@ -68,6 +68,7 @@ hiero-cli/
 │   │   ├── token/              # Fungible and non-fungible token management plugin
 │   │   ├── swap/               # Multi-party HBAR/token swap plugin
 │   │   ├── topic/              # Topic (HCS) management plugin
+│   │   ├── eip712/             # EIP-712 typed data sign/verify plugin
 │   │   └── test/               # Test plugin (development/testing)
 │   └── hiero-cli.ts           # Main CLI entry point
 ├── docs/                       # Technical documentation

jest.config.js

@@ -4,7 +4,10 @@ module.exports = {
   },
   testEnvironment: 'node',
   testTimeout: 10000,
-  testPathIgnorePatterns: ['.*/__tests__/helpers/.*'],
+  testPathIgnorePatterns: [
+    '.*/__tests__/.*/helpers/.*',
+    '.*/__tests__/helpers/.*',
+  ],
   reporters: ['default', 'jest-junit'],
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',

skills/hiero-cli/SKILL.md

@@ -82,6 +82,7 @@ State is persisted in `~/.hiero-cli/state/` as JSON files, one per plugin namesp
 | `credentials`       | Key/credentials management | list, remove stored credentials                                                                                                                                                                                                                                                         |
 | `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                                                        |
 | `plugin-management` | Plugin lifecycle           | add, remove, enable, disable, list, reset, info                                                                                                                                                                                                                                         |
 
 ## Agent instruction

skills/hiero-cli/references/eip712.md

@@ -0,0 +1,135 @@
+# eip712 plugin
+
+Sign and verify EIP-712 structured typed data using ECDSA or Ed25519 keys managed by the CLI KMS. Stateless — no local state is written. Useful for permit flows, off-chain authorizations, meta-transactions, and dApp integrations on Hedera.
+
+Domain, types, and message each accept either an **inline JSON string** or a **path to a JSON file**.
+
+For sign/verify commands you can provide either:
+
+- **`--hash`** — a pre-computed EIP-712 digest (0x-prefixed keccak256 hex), OR
+- **`--domain` + `--types` + `--message`** — the full typed data (all three required together)
+
+These two input modes are mutually exclusive.
+
+---
+
+### `hcli eip712 hash`
+
+Compute the EIP-712 digest (keccak256 hash) for a typed data payload without signing.
+
+| Option      | Short | Type   | Required | Description                                                    |
+| ----------- | ----- | ------ | -------- | -------------------------------------------------------------- |
+| `--domain`  | `-d`  | string | **yes**  | EIP-712 domain as inline JSON or path to a JSON file           |
+| `--types`   | `-t`  | string | **yes**  | EIP-712 types definition as inline JSON or path to a JSON file |
+| `--message` | `-m`  | string | **yes**  | Message object as inline JSON or path to a JSON file           |
+
+**Example:**
+
+```
+hcli eip712 hash --domain '{"name":"MyApp","version":"1","chainId":295}' --types '{"Mail":[{"name":"from","type":"address"}]}' --message '{"from":"0xAb..."}'
+
+hcli eip712 hash --domain ./domain.json --types ./types.json --message ./message.json
+```
+
+**Output:** `{ hash }`
+
+- `hash` — EIP-712 digest (0x-prefixed keccak256)
+
+---
+
+### `hcli eip712 sign`
+
+Sign an EIP-712 typed data payload using a KMS-managed key. The algorithm (ECDSA or Ed25519) is **auto-detected from the key type** stored in the KMS.
+
+| Option          | Short | Type   | Required | Default        | Description                                                                                                             |
+| --------------- | ----- | ------ | -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `--key`         | `-K`  | string | no       | operator       | Signing key: `accountId:privateKey`, `ecdsa:private:{hex}`, `ed25519:private:{hex}`, key reference (`kr_xxx`), or alias |
+| `--key-manager` | `-k`  | string | no       | config default | Key manager: `local` or `local_encrypted`                                                                               |
+| `--hash`        | `-H`  | string | no\*     | —              | Pre-computed EIP-712 digest (0x-prefixed hex). Mutually exclusive with typed data options                               |
+| `--domain`      | `-d`  | string | no\*     | —              | EIP-712 domain as inline JSON or path to a JSON file                                                                    |
+| `--types`       | `-t`  | string | no\*     | —              | EIP-712 types definition as inline JSON or path to a JSON file                                                          |
+| `--message`     | `-m`  | string | no\*     | —              | Message object as inline JSON or path to a JSON file                                                                    |
+
+\* Provide either `--hash` OR all three of `--domain`, `--types`, `--message`.
+
+**Example:**
+
+```
+hcli eip712 sign --key my-ecdsa-key --domain ./domain.json --types ./types.json --message ./message.json
+
+hcli eip712 sign --key my-ed25519-key --hash 0x<keccak256-hex>
+```
+
+**Output (ECDSA key):** `{ signerEvm, signature, hash, r, s, v }`
+
+- `signerEvm` — EVM address of the signer (checksum format)
+- `signature` — combined 65-byte hex string (`0x` + r + s + v)
+- `hash` — EIP-712 digest that was signed (0x-prefixed keccak256)
+- `r`, `s` — 32-byte hex components
+- `v` — recovery id (27 or 28)
+
+**Output (Ed25519 key):** `{ signerPublicKey, hash, signature }`
+
+- `signerPublicKey` — Ed25519 public key of the signer (0x-prefixed hex)
+- `hash` — EIP-712 digest that was signed (0x-prefixed keccak256)
+- `signature` — 64-byte Ed25519 signature over the digest (0x-prefixed hex)
+
+---
+
+### `hcli eip712 verify`
+
+Verify an EIP-712 signature. The algorithm is **auto-detected from the signature length**:
+
+- **65-byte signature** (0x + 130 hex chars) → ECDSA path: recovers the EVM signer address via `ecrecover`, optionally asserts it matches `--expected-signer`
+- **64-byte signature** (0x + 128 hex chars) → Ed25519 path: verifies the signature against a KMS-managed public key
+
+Passing `--key`/`--key-manager` with a 65-byte signature, or `--expected-signer` with a 64-byte signature, is a validation error.
+
+| Option              | Short | Type   | Required | Default        | Description                                                                                |
+| ------------------- | ----- | ------ | -------- | -------------- | ------------------------------------------------------------------------------------------ |
+| `--key`             | `-K`  | string | no       | operator       | Public key to verify against (Ed25519 only). Key reference, account alias, or account ID   |
+| `--key-manager`     | `-k`  | string | no       | config default | Key manager: `local` or `local_encrypted` (Ed25519 only)                                   |
+| `--hash`            | `-H`  | string | no\*     | —              | Pre-computed EIP-712 digest (0x-prefixed hex). Mutually exclusive with typed data options  |
+| `--domain`          | `-d`  | string | no\*     | —              | EIP-712 domain as inline JSON or path to a JSON file                                       |
+| `--types`           | `-t`  | string | no\*     | —              | EIP-712 types definition as inline JSON or path to a JSON file                             |
+| `--message`         | `-m`  | string | no\*     | —              | Signed message object as inline JSON or path to a JSON file                                |
+| `--signature`       | `-s`  | string | **yes**  | —              | Signature to verify: 0x-prefixed 65-byte hex (ECDSA) or 64-byte hex (Ed25519)              |
+| `--expected-signer` | `-e`  | string | no       | —              | Assert recovered address matches (ECDSA only): EVM address (`0x...`), account ID, or alias |
+
+\* Provide either `--hash` OR all three of `--domain`, `--types`, `--message`.
+
+**Example:**
+
+```
+# ECDSA — recover signer
+hcli eip712 verify --domain ./domain.json --types ./types.json --message ./message.json --signature 0x<65-byte-hex>
+
+# ECDSA — assert expected signer
+hcli eip712 verify --hash 0x<keccak256> --signature 0x<65-byte-hex> --expected-signer 0xAbCd...1234
+hcli eip712 verify --hash 0x<keccak256> --signature 0x<65-byte-hex> --expected-signer 0.0.12345
+hcli eip712 verify --hash 0x<keccak256> --signature 0x<65-byte-hex> --expected-signer my-alias
+
+# Ed25519 — verify against key
+hcli eip712 verify --key my-ed25519-key --domain ./domain.json --types ./types.json --message ./message.json --signature 0x<64-byte-hex>
+hcli eip712 verify --key my-ed25519-key --hash 0x<keccak256> --signature 0x<64-byte-hex>
+```
+
+**Output (ECDSA):** `{ recoveredSigner, match? }`
+
+- `recoveredSigner` — EVM address recovered from the signature
+- `match` — boolean, only present when `--expected-signer` is provided
+
+**Output (Ed25519):** `{ signerPublicKey, hash, verified }`
+
+- `signerPublicKey` — Ed25519 public key used for verification (raw hex)
+- `hash` — EIP-712 digest that was verified (0x-prefixed keccak256)
+- `verified` — boolean, whether the signature is valid for the given key and message
+
+---
+
+## Notes
+
+- `--primary-type` is not a CLI option. ethers.js infers the primary type from the types definition automatically.
+- The plugin is stateless — no entries are written to `~/.hiero-cli/state/`.
+- `sign` auto-detects the algorithm from the resolved key's type in the KMS. Passing an unsupported algorithm throws a `ValidationError`.
+- `verify` auto-detects the algorithm from the signature length. Mixing algorithm-specific options with the wrong signature length throws a `ValidationError`.

src/core/schemas/common-schemas.ts

@@ -8,6 +8,7 @@
  */
 import type { Credential } from '@/core/services/kms/kms-types.interface';
 
+import { existsSync, readFileSync } from 'fs';
 import { z } from 'zod';
 
 import { ValidationError } from '@/core/errors';
@@ -25,6 +26,7 @@ import {
 } from '@/core/shared/constants';
 import {
   EntityReferenceType,
+  JsonInputType,
   SupplyType,
   SupportedNetwork,
 } from '@/core/types/shared.types';
@@ -795,6 +797,82 @@ export const FilePathSchema = z
   .min(1, 'File path cannot be empty')
   .describe('Filesystem path (absolute or relative)');
 
+/**
+ * JSON Input Schema
+ * Accepts either an inline JSON string (starts with { or [) or a filesystem path
+ * to a JSON file. Transforms to { type, value } where value is the parsed object.
+ */
+export const JsonInputSchema = z
+  .string()
+  .trim()
+  .min(1, 'JSON input cannot be empty')
+  .transform((val): { type: JsonInputType; value: unknown } => {
+    const trimmed = val.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      try {
+        return { type: JsonInputType.INLINE, value: JSON.parse(trimmed) };
+      } catch {
+        throw new ValidationError(
+          `Invalid inline JSON: ${trimmed.slice(0, 80)}`,
+        );
+      }
+    }
+    if (!existsSync(trimmed)) {
+      throw new ValidationError(`File not found: ${trimmed}`);
+    }
+    try {
+      return {
+        type: JsonInputType.FILE,
+        value: JSON.parse(readFileSync(trimmed, 'utf-8')),
+      };
+    } catch {
+      throw new ValidationError(`Could not parse JSON from file: ${trimmed}`);
+    }
+  })
+  .describe('Inline JSON string or path to a JSON file');
+
+/**
+ * EIP-712 Ecdsa Signature
+ * 0x-prefixed 65-byte ECDSA signature (r + s + v)
+ */
+export const Eip712EcdsaSignatureSchema = z
+  .string()
+  .regex(
+    /^0x[0-9a-fA-F]{130}$/,
+    'Signature must be a 0x-prefixed 65-byte hex string',
+  )
+  .describe('EIP-712 signature (0x-prefixed 65-byte hex)');
+/**
+ * EIP-712 Signature
+ * 0x-prefixed 65-byte ECDSA signature (r + s + v)
+ */
+export const Eip712Ed25519SignatureSchema = z
+  .string()
+  .regex(
+    /^0x[0-9a-fA-F]{128}$/,
+    'Signature must be a 0x-prefixed 64-byte hex string',
+  )
+  .describe('EIP-712 signature (0x-prefixed 64-byte hex)');
+
+export const Eip712TypedDataFieldSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+});
+
+export const Eip712DomainSchema = z
+  .object({
+    name: z.string().optional(),
+    version: z.string().optional(),
+    chainId: z.union([z.number(), z.bigint()]).optional(),
+    verifyingContract: z.string().optional(),
+    salt: z.string().optional(),
+  })
+  .describe('EIP-712 domain object');
+
+export const Eip712TypesSchema = z
+  .record(z.string(), z.array(Eip712TypedDataFieldSchema))
+  .describe('EIP-712 types definition');
+
 /**
  * Token Name
  * Name of a token (alphanumeric, spaces, hyphens)

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

@@ -269,6 +269,7 @@ describe('KmsServiceImpl', () => {
     const localManager = getLocalKeyManager(KeyManager.local);
     const signer = {
       sign: jest.fn(),
+      signWithWallet: jest.fn(),
       getPublicKey: jest.fn(),
     } as unknown as Signer;
     localManager.createSigner.mockReturnValue(signer);
@@ -327,6 +328,7 @@ describe('KmsServiceImpl', () => {
     const signerHandle = {
       getPublicKey: jest.fn().mockReturnValue('sign-public'),
       sign: jest.fn().mockResolvedValue(new Uint8Array([9])),
+      signHashWithEcdsaKey: jest.fn(),
     };
     getLocalKeyManager(KeyManager.local).createSigner.mockReturnValue(
       signerHandle as Signer,
@@ -363,6 +365,7 @@ describe('KmsServiceImpl', () => {
     const signerHandle = {
       getPublicKey: jest.fn().mockReturnValue('sign-flow-public'),
       sign: jest.fn().mockResolvedValue(new Uint8Array([42])),
+      signHashWithEcdsaKey: jest.fn(),
     };
     getLocalKeyManager(KeyManager.local).createSigner.mockReturnValue(
       signerHandle as Signer,

src/core/services/kms/signers/private-key-signer.ts

@@ -2,8 +2,9 @@ import type { KmsCredentialSecret } from '@/core/services/kms/kms-types.interfac
 import type { Signer } from './signer.interface';
 
 import { PrivateKey } from '@hiero-ledger/sdk';
+import { SigningKey } from 'ethers';
 
-import { ConfigurationError } from '@/core/errors';
+import { ConfigurationError, ValidationError } from '@/core/errors';
 import { KeyAlgorithm } from '@/core/shared/constants';
 
 /**
@@ -31,6 +32,22 @@ export class PrivateKeySigner implements Signer {
     return new Uint8Array(signature);
   }
 
+  signHashWithEcdsaKey(hash: string): string {
+    if (!this.secret.privateKey) {
+      throw new ConfigurationError('Missing private key in secret');
+    }
+    if (this.algorithm !== KeyAlgorithm.ECDSA) {
+      throw new ValidationError(
+        'Wallet signing can be only done with ECDSA key',
+      );
+    }
+    const rawPrivateKey = PrivateKey.fromStringECDSA(
+      this.secret.privateKey,
+    ).toStringRaw();
+    const signingKey = new SigningKey(`0x${rawPrivateKey}`);
+    return signingKey.sign(hash).serialized;
+  }
+
   getPublicKey(): string {
     return this.publicKey;
   }

src/core/services/kms/signers/signer.interface.ts

@@ -15,6 +15,8 @@ export interface Signer {
    */
   sign(bytes: Uint8Array): Uint8Array;
 
+  signHashWithEcdsaKey(hash: string): string;
+
   /**
    * Returns the public key associated with this signer.
    *