evm-kms-signer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taegeon Alan Go
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# kms-signer-evm
+
+A TypeScript library that integrates AWS KMS (Key Management Service) with [viem](https://viem.sh) to create secure Ethereum signers. This allows you to sign Ethereum transactions and messages using keys stored in AWS KMS, providing enterprise-grade security for your Ethereum operations.
+
+## Features
+
+- **AWS KMS Integration**: Sign Ethereum transactions using keys securely stored in AWS KMS
+- **Full EIP Compliance**: Supports EIP-191 (personal messages), EIP-712 (typed data), EIP-155 (replay protection), EIP-2 (signature normalization)
+- **Type-Safe**: Built with TypeScript in strict mode with comprehensive type definitions
+- **viem Compatible**: Seamlessly integrates with viem's Account system via `toAccount`
+- **DER Signature Parsing**: Automatically converts AWS KMS DER-encoded signatures to Ethereum format
+- **Comprehensive Error Handling**: Custom error classes for better debugging
+- **Well-Tested**: 51 tests covering all functionality with 100% type safety
+
+## Installation
+
+```bash
+pnpm add kms-signer-evm
+```
+
+Or with npm:
+
+```bash
+npm install kms-signer-evm
+```
+
+Or with yarn:
+
+```bash
+yarn add kms-signer-evm
+```
+
+## Prerequisites
+
+### AWS KMS Key Setup
+
+1. **Create an ECC Key in AWS KMS**:
+   - Go to AWS KMS Console
+   - Click "Create key"
+   - Choose "Asymmetric" key type
+   - Select "Sign and verify" key usage
+   - Choose **ECC_SECG_P256K1** as the key spec (this is secp256k1, Ethereum's curve)
+   - Complete the key creation process
+
+2. **Grant Permissions**:
+   Ensure your AWS credentials have the following permissions:
+   - `kms:GetPublicKey`
+   - `kms:Sign`
+
+3. **Note Your Key ID**:
+   Copy the Key ARN or Key ID for use in your application.
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+AWS_REGION=us-east-1
+KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
+
+# Optional: If not using IAM roles or default credentials
+AWS_ACCESS_KEY_ID=your_access_key
+AWS_SECRET_ACCESS_KEY=your_secret_key
+```
+
+## Quick Start
+
+### Signing a Message
+
+```typescript
+import 'dotenv/config'
+import { KmsSigner, toKmsAccount } from 'kms-signer-evm'
+
+async function main() {
+  // Initialize the KMS signer
+  const signer = new KmsSigner({
+    region: process.env.AWS_REGION!,
+    keyId: process.env.KMS_KEY_ID!,
+  })
+
+  // Convert to viem account
+  const account = await toKmsAccount(signer)
+
+  console.log('Account address:', account.address)
+
+  // Sign a message
+  const message = 'Hello from AWS KMS!'
+  const signature = await account.signMessage({ message })
+
+  console.log('Signature:', signature)
+}
+
+main().catch(console.error)
+```
+
+### Sending a Transaction
+
+```typescript
+import 'dotenv/config'
+import { createWalletClient, http } from 'viem'
+import { sepolia } from 'viem/chains'
+import { KmsSigner, toKmsAccount } from 'kms-signer-evm'
+
+async function main() {
+  // Initialize the KMS signer
+  const signer = new KmsSigner({
+    region: process.env.AWS_REGION!,
+    keyId: process.env.KMS_KEY_ID!,
+  })
+
+  // Convert to viem account
+  const account = await toKmsAccount(signer)
+
+  // Create a wallet client
+  const client = createWalletClient({
+    account,
+    chain: sepolia,
+    transport: http()
+  })
+
+  // Send a transaction
+  const hash = await client.sendTransaction({
+    to: '0xa5D3241A1591061F2a4bB69CA0215F66520E67cf',
+    value: 1000000000000000n, // 0.001 ETH
+  })
+
+  console.log('Transaction hash:', hash)
+}
+
+main().catch(console.error)
+```
+
+## API Documentation
+
+### `KmsSigner`
+
+The main class for signing operations using AWS KMS.
+
+#### Constructor
+
+```typescript
+new KmsSigner(config: KmsConfig)
+```
+
+**Parameters:**
+- `config.region`: AWS region where your KMS key is located
+- `config.keyId`: AWS KMS key ID or ARN
+- `config.credentials` (optional): AWS credentials object with `accessKeyId` and `secretAccessKey`
+
+#### Methods
+
+##### `getAddress(): Promise<Address>`
+
+Returns the Ethereum address derived from the KMS public key.
+
+```typescript
+const address = await signer.getAddress()
+```
+
+##### `getPublicKey(): Promise<Uint8Array>`
+
+Returns the uncompressed public key (65 bytes) from AWS KMS.
+
+```typescript
+const publicKey = await signer.getPublicKey()
+```
+
+##### `signMessage({ message }): Promise<Hex>`
+
+Signs a personal message (EIP-191).
+
+```typescript
+const signature = await signer.signMessage({ message: 'Hello World' })
+```
+
+##### `signTransaction(transaction, options?): Promise<Hex>`
+
+Signs an Ethereum transaction with EIP-155 replay protection.
+
+```typescript
+const signedTx = await signer.signTransaction({
+  to: '0x...',
+  value: 1000000000000000n,
+  chainId: 11155111,
+  nonce: 0,
+  maxFeePerGas: 20000000000n,
+  maxPriorityFeePerGas: 1000000000n,
+})
+```
+
+##### `signTypedData(typedData): Promise<Hex>`
+
+Signs structured data (EIP-712).
+
+```typescript
+const signature = await signer.signTypedData({
+  domain: {
+    name: 'Ether Mail',
+    version: '1',
+    chainId: 1,
+    verifyingContract: '0x...'
+  },
+  types: {
+    Person: [
+      { name: 'name', type: 'string' },
+      { name: 'wallet', type: 'address' }
+    ]
+  },
+  primaryType: 'Person',
+  message: {
+    name: 'Bob',
+    wallet: '0x...'
+  }
+})
+```
+
+### `toKmsAccount(signer: KmsSigner): Promise<LocalAccount>`
+
+Converts a `KmsSigner` instance to a viem `LocalAccount` that can be used with viem's wallet clients.
+
+```typescript
+const account = await toKmsAccount(signer)
+
+const client = createWalletClient({
+  account,
+  chain: mainnet,
+  transport: http()
+})
+```
+
+### Error Classes
+
+The library provides custom error classes for better error handling:
+
+- `KmsSignerError`: Base error class
+- `DerParsingError`: Thrown when DER signature parsing fails
+- `KmsClientError`: Thrown when AWS KMS operations fail
+- `SignatureNormalizationError`: Thrown when signature normalization fails
+- `RecoveryIdCalculationError`: Thrown when recovery ID calculation fails
+
+## Security Considerations
+
+### Key Management
+
+- **Private keys never leave AWS KMS**: All signing operations happen within AWS KMS
+- **IAM Permissions**: Use least-privilege IAM policies for KMS access
+- **Key Rotation**: Consider AWS KMS key rotation policies for your use case
+
+### Signature Security
+
+- **EIP-2 Compliance**: All signatures are normalized to prevent malleability attacks
+- **Replay Protection**: Transaction signatures include EIP-155 chainId by default
+- **Recovery ID**: Automatically calculated and verified for all signatures
+
+### Best Practices
+
+1. **Use IAM Roles**: Prefer IAM roles over hardcoded credentials in production
+2. **Environment Variables**: Never commit `.env` files with credentials
+3. **Key Policies**: Restrict KMS key usage to specific AWS principals
+4. **Audit Logging**: Enable AWS CloudTrail to monitor KMS key usage
+5. **Network Security**: Use VPC endpoints for KMS in production environments
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test:run
+```
+
+### Type Checking
+
+```bash
+pnpm type-check
+```
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Running Examples
+
+```bash
+# Sign a message
+pnpm example:sign
+
+# Send a transaction
+pnpm example:tx
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Acknowledgments
+
+- Built with [viem](https://viem.sh) - Modern TypeScript Ethereum library
+- Uses [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)
+- Inspired by the need for secure key management in Ethereum applications

package/dist/account.d.ts

@@ -0,0 +1,25 @@
+import type { LocalAccount } from 'viem';
+import { KmsSigner } from './kms/signer';
+/**
+ * Create a viem Account from KmsSigner.
+ *
+ * Wraps KmsSigner methods to match viem's Account interface,
+ * enabling use with viem clients (walletClient, etc.)
+ *
+ * @param signer - KmsSigner instance
+ * @returns viem Account with KMS signing capabilities
+ *
+ * @example
+ * ```typescript
+ * const signer = new KmsSigner({ region: 'us-east-1', keyId: 'key-id' })
+ * const account = await toKmsAccount(signer)
+ *
+ * const client = createWalletClient({
+ *   account,
+ *   chain: mainnet,
+ *   transport: http()
+ * })
+ * ```
+ */
+export declare function toKmsAccount(signer: KmsSigner): Promise<LocalAccount>;
+//# sourceMappingURL=account.d.ts.map

package/dist/account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAa3E"}

package/dist/account.js

@@ -0,0 +1,36 @@
+import { toAccount } from 'viem/accounts';
+/**
+ * Create a viem Account from KmsSigner.
+ *
+ * Wraps KmsSigner methods to match viem's Account interface,
+ * enabling use with viem clients (walletClient, etc.)
+ *
+ * @param signer - KmsSigner instance
+ * @returns viem Account with KMS signing capabilities
+ *
+ * @example
+ * ```typescript
+ * const signer = new KmsSigner({ region: 'us-east-1', keyId: 'key-id' })
+ * const account = await toKmsAccount(signer)
+ *
+ * const client = createWalletClient({
+ *   account,
+ *   chain: mainnet,
+ *   transport: http()
+ * })
+ * ```
+ */
+export async function toKmsAccount(signer) {
+    const address = await signer.getAddress();
+    return toAccount({
+        address,
+        signMessage: async ({ message }) => {
+            // Convert SignableMessage to string for KmsSigner
+            const messageStr = typeof message === 'string' ? message : message.raw.toString();
+            return signer.signMessage({ message: messageStr });
+        },
+        signTransaction: async (transaction, options) => signer.signTransaction(transaction, options),
+        signTypedData: async (typedData) => signer.signTypedData(typedData)
+    });
+}
+//# sourceMappingURL=account.js.map

package/dist/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAIzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IAClD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAA;IAEzC,OAAO,SAAS,CAAC;QACf,OAAO;QACP,WAAW,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;YACjC,kDAAkD;YAClD,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAA;YACjF,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAA;QACpD,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC;QAC7F,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;KACpE,CAAC,CAAA;AACJ,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,17 @@
+export declare class KmsSignerError extends Error {
+    constructor(message: string);
+}
+export declare class DerParsingError extends KmsSignerError {
+    constructor(message: string);
+}
+export declare class KmsClientError extends KmsSignerError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class SignatureNormalizationError extends KmsSignerError {
+    constructor(message: string);
+}
+export declare class RecoveryIdCalculationError extends KmsSignerError {
+    constructor(message: string);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,cAAe,SAAQ,cAAc;aACH,KAAK,CAAC,EAAE,KAAK;gBAA9C,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAI3D;AAED,qBAAa,2BAA4B,SAAQ,cAAc;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,0BAA2B,SAAQ,cAAc;gBAChD,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors/index.js

@@ -0,0 +1,32 @@
+export class KmsSignerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KmsSignerError';
+    }
+}
+export class DerParsingError extends KmsSignerError {
+    constructor(message) {
+        super(message);
+        this.name = 'DerParsingError';
+    }
+}
+export class KmsClientError extends KmsSignerError {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'KmsClientError';
+    }
+}
+export class SignatureNormalizationError extends KmsSignerError {
+    constructor(message) {
+        super(message);
+        this.name = 'SignatureNormalizationError';
+    }
+}
+export class RecoveryIdCalculationError extends KmsSignerError {
+    constructor(message) {
+        super(message);
+        this.name = 'RecoveryIdCalculationError';
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,YAAY,OAAe,EAAkB,KAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAA;QAD6B,UAAK,GAAL,KAAK,CAAQ;QAExD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,cAAc;IAC7D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;IAC1C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { KmsSigner } from './kms/signer';
+export { toKmsAccount } from './account';
+export type { KmsConfig, DerSignature, SignatureData } from './types';
+export { KmsSignerError, DerParsingError, KmsClientError, SignatureNormalizationError, RecoveryIdCalculationError } from './errors';
+export type { Address, Hex } from 'viem';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGxC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAGrE,OAAO,EACL,cAAc,EACd,eAAe,EACf,cAAc,EACd,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,UAAU,CAAA;AAGjB,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// Main classes and functions
+export { KmsSigner } from './kms/signer';
+export { toKmsAccount } from './account';
+// Errors
+export { KmsSignerError, DerParsingError, KmsClientError, SignatureNormalizationError, RecoveryIdCalculationError } from './errors';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAKxC,SAAS;AACT,OAAO,EACL,cAAc,EACd,eAAe,EACf,cAAc,EACd,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,UAAU,CAAA"}

package/dist/kms/client.d.ts

@@ -0,0 +1,60 @@
+import type { KmsConfig } from '../types';
+/**
+ * KmsClient wraps AWS KMS SDK operations for key management and signing.
+ *
+ * This class provides a simplified interface to AWS KMS for:
+ * - Retrieving public keys from KMS
+ * - Signing message digests with KMS-stored private keys
+ *
+ * @example
+ * ```typescript
+ * const client = new KmsClient({
+ *   region: 'us-east-1',
+ *   keyId: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
+ * })
+ *
+ * const publicKey = await client.getPublicKey()
+ * const signature = await client.sign(messageHash)
+ * ```
+ */
+export declare class KmsClient {
+    private client;
+    private keyId;
+    /**
+     * Creates a new KMS client instance.
+     *
+     * @param config - KMS configuration including region, keyId, and optional credentials
+     *
+     * @remarks
+     * If credentials are not provided, the AWS SDK will use the default credential provider chain:
+     * - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+     * - Shared credentials file (~/.aws/credentials)
+     * - IAM role for EC2 instances or ECS tasks
+     */
+    constructor(config: KmsConfig);
+    /**
+     * Retrieves the public key from AWS KMS.
+     *
+     * @returns The public key in DER-encoded SubjectPublicKeyInfo (SPKI) format
+     * @throws {KmsClientError} If the KMS API call fails or returns no public key
+     *
+     * @remarks
+     * The returned public key is in SPKI format with a variable-length DER header.
+     * The last 65 bytes contain the uncompressed secp256k1 public key (0x04 + x + y).
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Signs a message hash using the KMS-stored private key.
+     *
+     * @param messageHash - The pre-hashed message to sign (32 bytes for keccak256)
+     * @returns The signature in DER-encoded format (SEQUENCE { INTEGER r, INTEGER s })
+     * @throws {KmsClientError} If the KMS API call fails or returns no signature
+     *
+     * @remarks
+     * - Uses MessageType.DIGEST because the message is already hashed
+     * - Uses ECDSA_SHA_256 signing algorithm (required for secp256k1)
+     * - The returned signature is DER-encoded and needs to be parsed to extract r and s values
+     */
+    sign(messageHash: Uint8Array): Promise<Uint8Array>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/kms/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/kms/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;;OAUG;gBACS,MAAM,EAAE,SAAS;IAQ7B;;;;;;;;;OASG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAmBzC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAuBzD"}

package/dist/kms/client.js

@@ -0,0 +1,98 @@
+import { KMSClient, GetPublicKeyCommand, SignCommand, MessageType, SigningAlgorithmSpec, } from '@aws-sdk/client-kms';
+import { KmsClientError } from '../errors';
+/**
+ * KmsClient wraps AWS KMS SDK operations for key management and signing.
+ *
+ * This class provides a simplified interface to AWS KMS for:
+ * - Retrieving public keys from KMS
+ * - Signing message digests with KMS-stored private keys
+ *
+ * @example
+ * ```typescript
+ * const client = new KmsClient({
+ *   region: 'us-east-1',
+ *   keyId: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
+ * })
+ *
+ * const publicKey = await client.getPublicKey()
+ * const signature = await client.sign(messageHash)
+ * ```
+ */
+export class KmsClient {
+    /**
+     * Creates a new KMS client instance.
+     *
+     * @param config - KMS configuration including region, keyId, and optional credentials
+     *
+     * @remarks
+     * If credentials are not provided, the AWS SDK will use the default credential provider chain:
+     * - Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+     * - Shared credentials file (~/.aws/credentials)
+     * - IAM role for EC2 instances or ECS tasks
+     */
+    constructor(config) {
+        this.client = new KMSClient({
+            region: config.region,
+            ...(config.credentials && { credentials: config.credentials }),
+        });
+        this.keyId = config.keyId;
+    }
+    /**
+     * Retrieves the public key from AWS KMS.
+     *
+     * @returns The public key in DER-encoded SubjectPublicKeyInfo (SPKI) format
+     * @throws {KmsClientError} If the KMS API call fails or returns no public key
+     *
+     * @remarks
+     * The returned public key is in SPKI format with a variable-length DER header.
+     * The last 65 bytes contain the uncompressed secp256k1 public key (0x04 + x + y).
+     */
+    async getPublicKey() {
+        try {
+            const command = new GetPublicKeyCommand({ KeyId: this.keyId });
+            const response = await this.client.send(command);
+            if (!response.PublicKey) {
+                throw new KmsClientError('No public key returned from KMS');
+            }
+            return new Uint8Array(response.PublicKey);
+        }
+        catch (error) {
+            if (error instanceof KmsClientError)
+                throw error;
+            throw new KmsClientError(`Failed to get public key from KMS: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Signs a message hash using the KMS-stored private key.
+     *
+     * @param messageHash - The pre-hashed message to sign (32 bytes for keccak256)
+     * @returns The signature in DER-encoded format (SEQUENCE { INTEGER r, INTEGER s })
+     * @throws {KmsClientError} If the KMS API call fails or returns no signature
+     *
+     * @remarks
+     * - Uses MessageType.DIGEST because the message is already hashed
+     * - Uses ECDSA_SHA_256 signing algorithm (required for secp256k1)
+     * - The returned signature is DER-encoded and needs to be parsed to extract r and s values
+     */
+    async sign(messageHash) {
+        try {
+            const command = new SignCommand({
+                KeyId: this.keyId,
+                Message: messageHash,
+                MessageType: MessageType.DIGEST,
+                SigningAlgorithm: SigningAlgorithmSpec.ECDSA_SHA_256,
+            });
+            const response = await this.client.send(command);
+            if (!response.Signature) {
+                throw new KmsClientError('No signature returned from KMS');
+            }
+            return new Uint8Array(response.Signature);
+        }
+        catch (error) {
+            if (error instanceof KmsClientError)
+                throw error;
+            throw new KmsClientError(`Failed to sign with KMS: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/kms/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/kms/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,oBAAoB,GACrB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,SAAS;IAIpB;;;;;;;;;;OAUG;IACH,YAAY,MAAiB;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;SAC/D,CAAC,CAAA;QACF,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC3B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,YAAY;QAChB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;YAC9D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAEhD,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAA;YAC7D,CAAC;YAED,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,cAAc;gBAAE,MAAM,KAAK,CAAA;YAChD,MAAM,IAAI,cAAc,CACtB,sCAAsC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,EAChG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAA;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,WAAuB;QAChC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC;gBAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,OAAO,EAAE,WAAW;gBACpB,WAAW,EAAE,WAAW,CAAC,MAAM;gBAC/B,gBAAgB,EAAE,oBAAoB,CAAC,aAAa;aACrD,CAAC,CAAA;YACF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAEhD,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CAAC,gCAAgC,CAAC,CAAA;YAC5D,CAAC;YAED,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,cAAc;gBAAE,MAAM,KAAK,CAAA;YAChD,MAAM,IAAI,cAAc,CACtB,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,EACtF,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAA;QACH,CAAC;IACH,CAAC;CACF"}