@solana/keychain-aws-kms 0.0.0 → 0.3.0

package/src/__tests__/aws-kms-signer.test.ts

@@ -0,0 +1,425 @@
+import { generateKeyPairSigner } from '@solana/signers';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { assertIsSolanaSigner } from '@solana/keychain-core';
+
+import { AwsKmsSigner } from '../aws-kms-signer.js';
+import type { AwsKmsSignerConfig } from '../types.js';
+
+// Mock AWS SDK
+const mockSend = vi.fn();
+
+vi.mock('@aws-sdk/client-kms', () => {
+    // Create proper constructor mock classes
+    class MockKMSClient {
+        send = mockSend;
+    }
+
+    class MockSignCommand {
+        input: unknown;
+        constructor(params: unknown) {
+            this.input = params;
+        }
+    }
+
+    class MockDescribeKeyCommand {
+        input: unknown;
+        constructor(params: unknown) {
+            this.input = params;
+        }
+    }
+
+    return {
+        KMSClient: MockKMSClient,
+        SignCommand: MockSignCommand,
+        DescribeKeyCommand: MockDescribeKeyCommand,
+        MessageType: {
+            RAW: 'RAW',
+            DIGEST: 'DIGEST',
+        },
+        SigningAlgorithmSpec: {
+            ED25519_SHA_512: 'ED25519_SHA_512',
+            ED25519_PH_SHA_512: 'ED25519_PH_SHA_512',
+        },
+    };
+});
+
+describe('AwsKmsSigner', () => {
+    const TEST_KEY_ID = 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012';
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('constructor', () => {
+        it('creates an AwsKmsSigner with valid config', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            const config: AwsKmsSignerConfig = {
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            };
+
+            const signer = new AwsKmsSigner(config);
+
+            expect(signer.address).toBe(keyPair.address);
+            assertIsSolanaSigner(signer);
+            expect(signer.signMessages).toBeDefined();
+            expect(signer.signTransactions).toBeDefined();
+            expect(signer.isAvailable).toBeDefined();
+        });
+
+        it('sets address field correctly from config', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            const config: AwsKmsSignerConfig = {
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            };
+
+            const signer = new AwsKmsSigner(config);
+            expect(signer.address).toBe(keyPair.address);
+        });
+
+        it('should throw error for missing keyId', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            expect(() => {
+                new AwsKmsSigner({
+                    keyId: '',
+                    publicKey: keyPair.address,
+                });
+            }).toThrow('Missing required keyId field');
+        });
+
+        it('should throw error for missing publicKey', () => {
+            expect(() => {
+                new AwsKmsSigner({
+                    keyId: TEST_KEY_ID,
+                    publicKey: '',
+                });
+            }).toThrow('Missing required publicKey field');
+        });
+
+        it('should throw error for invalid public key', () => {
+            expect(() => {
+                new AwsKmsSigner({
+                    keyId: TEST_KEY_ID,
+                    publicKey: 'invalid-key',
+                });
+            }).toThrow('Invalid Solana public key format');
+        });
+
+        it('should validate requestDelayMs', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            expect(() => {
+                new AwsKmsSigner({
+                    keyId: TEST_KEY_ID,
+                    publicKey: keyPair.address,
+                    requestDelayMs: -1,
+                });
+            }).toThrow('requestDelayMs must not be negative');
+        });
+
+        it('should warn for high requestDelayMs', async () => {
+            const keyPair = await generateKeyPairSigner();
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+            new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+                requestDelayMs: 5000,
+            });
+
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('requestDelayMs is greater than 3000ms'));
+
+            warnSpy.mockRestore();
+        });
+
+        it('should accept region configuration', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+                region: 'us-west-2',
+            });
+
+            expect(signer).toBeDefined();
+        });
+
+        it('should accept credentials configuration', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+                credentials: {
+                    accessKeyId: 'test-access-key',
+                    secretAccessKey: 'test-secret-key',
+                },
+            });
+
+            expect(signer).toBeDefined();
+        });
+
+        it('should accept session token in credentials', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+                credentials: {
+                    accessKeyId: 'test-access-key',
+                    secretAccessKey: 'test-secret-key',
+                    sessionToken: 'test-session-token',
+                },
+            });
+
+            expect(signer).toBeDefined();
+        });
+    });
+
+    describe('signMessages', () => {
+        it('should sign a message successfully', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                Signature: new Uint8Array(64).fill(0x42),
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            // Provide required 'signatures' property to satisfy the type
+            const message = {
+                content: new Uint8Array([1, 2, 3, 4]),
+                signatures: {},
+            };
+            const result = await signer.signMessages([message]);
+
+            expect(result).toHaveLength(1);
+            expect(result[0]?.[signer.address]).toBeDefined();
+            expect(mockSend).toHaveBeenCalledTimes(1);
+        });
+
+        it('should handle multiple messages with delay', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                Signature: new Uint8Array(64).fill(0x42),
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+                requestDelayMs: 10,
+            });
+
+            const messages = [
+                { content: new Uint8Array([1]) },
+                { content: new Uint8Array([2]) },
+                { content: new Uint8Array([3]) },
+            ];
+
+            // Add missing 'signatures' property for each message to satisfy the type requirement
+            const messagesWithSignatures = messages.map(msg => ({
+                ...msg,
+                signatures: {},
+            }));
+
+            const startTime = Date.now();
+            const result = await signer.signMessages(messagesWithSignatures);
+            const endTime = Date.now();
+
+            expect(result).toHaveLength(3);
+            expect(mockSend).toHaveBeenCalledTimes(3);
+            // Should have some delay (at least 15ms for 2 delays of 10ms each)
+            expect(endTime - startTime).toBeGreaterThanOrEqual(15);
+        });
+
+        it('should throw error on invalid signature length', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                Signature: new Uint8Array(32), // Wrong length
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const message = { content: new Uint8Array([1, 2, 3, 4]), signatures: {} };
+
+            await expect(signer.signMessages([message])).rejects.toThrow('Invalid signature length');
+        });
+
+        it('should throw error on missing signature', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                Signature: undefined,
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const message = { content: new Uint8Array([1, 2, 3, 4]), signatures: {} };
+
+            await expect(signer.signMessages([message])).rejects.toThrow('No signature in AWS KMS response');
+        });
+    });
+
+    describe('signTransactions', () => {
+        it('should sign a transaction successfully', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                Signature: new Uint8Array(64).fill(0x42),
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const transaction = {
+                messageBytes: new Uint8Array([1, 2, 3, 4]),
+                signatures: {},
+            } as unknown as Parameters<typeof signer.signTransactions>[0][0];
+
+            const result = await signer.signTransactions([transaction]);
+
+            expect(result).toHaveLength(1);
+            expect(result[0]).toHaveProperty(signer.address);
+            expect(mockSend).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('isAvailable', () => {
+        it('should return true for valid Ed25519 key', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                KeyMetadata: {
+                    KeyId: TEST_KEY_ID,
+                    KeySpec: 'ECC_NIST_EDWARDS25519',
+                    KeyUsage: 'SIGN_VERIFY',
+                    KeyState: 'Enabled',
+                },
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(true);
+        });
+
+        it('should return false for wrong key spec', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                KeyMetadata: {
+                    KeyId: TEST_KEY_ID,
+                    KeySpec: 'RSA_2048',
+                    KeyUsage: 'SIGN_VERIFY',
+                    KeyState: 'Enabled',
+                },
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false for wrong key usage', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                KeyMetadata: {
+                    KeyId: TEST_KEY_ID,
+                    KeySpec: 'ECC_NIST_EDWARDS25519',
+                    KeyUsage: 'ENCRYPT_DECRYPT',
+                    KeyState: 'Enabled',
+                },
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false for disabled key', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                KeyMetadata: {
+                    KeyId: TEST_KEY_ID,
+                    KeySpec: 'ECC_NIST_EDWARDS25519',
+                    KeyUsage: 'SIGN_VERIFY',
+                    KeyState: 'Disabled',
+                },
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false on error', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockRejectedValue(new Error('AWS error'));
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false on missing metadata', async () => {
+            const keyPair = await generateKeyPairSigner();
+
+            mockSend.mockResolvedValue({
+                KeyMetadata: undefined,
+            });
+
+            const signer = new AwsKmsSigner({
+                keyId: TEST_KEY_ID,
+                publicKey: keyPair.address,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+    });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,5 @@
+// Test setup for AWS KMS signer tests
+// This file can be used for shared test utilities or setup
+
+export const TEST_KEY_ID = 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012';
+export const TEST_REGION = 'us-east-1';

package/src/aws-kms-signer.ts

@@ -0,0 +1,214 @@
+import { DescribeKeyCommand, KMSClient, MessageType, SignCommand, SigningAlgorithmSpec } from '@aws-sdk/client-kms';
+import { Address, assertIsAddress } from '@solana/addresses';
+import { createSignatureDictionary, SignerErrorCode, SolanaSigner, throwSignerError } from '@solana/keychain-core';
+import { SignatureBytes } from '@solana/keys';
+import { SignableMessage, SignatureDictionary } from '@solana/signers';
+import { Transaction, TransactionWithinSizeLimit, TransactionWithLifetime } from '@solana/transactions';
+
+import type { AwsCredentials, AwsKmsSignerConfig } from './types.js';
+
+/**
+ * AWS KMS-based signer using EdDSA (Ed25519) signing
+ *
+ * The AWS KMS key must be created with:
+ * - Key spec: ECC_NIST_EDWARDS25519
+ * - Key usage: SIGN_VERIFY
+ *
+ * Example AWS CLI command to create a key:
+ * ```bash
+ * aws kms create-key \
+ *   --key-spec ECC_NIST_EDWARDS25519 \
+ *   --key-usage SIGN_VERIFY \
+ *   --description "Solana signing key"
+ * ```
+ */
+export class AwsKmsSigner<TAddress extends string = string> implements SolanaSigner<TAddress> {
+    readonly address: Address<TAddress>;
+    private readonly keyId: string;
+    private readonly client: KMSClient;
+    private readonly requestDelayMs: number;
+
+    constructor(config: AwsKmsSignerConfig) {
+        if (!config.keyId) {
+            throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: 'Missing required keyId field',
+            });
+        }
+
+        if (!config.publicKey) {
+            throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: 'Missing required publicKey field',
+            });
+        }
+
+        try {
+            assertIsAddress(config.publicKey);
+            this.address = config.publicKey as Address<TAddress>;
+        } catch (error) {
+            throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                cause: error,
+                message: 'Invalid Solana public key format',
+            });
+        }
+
+        this.keyId = config.keyId;
+        this.requestDelayMs = config.requestDelayMs || 0;
+        this.validateRequestDelayMs(this.requestDelayMs);
+
+        // Create AWS KMS client
+        const clientConfig: {
+            credentials?: AwsCredentials;
+            region?: string;
+        } = {};
+
+        if (config.region) {
+            clientConfig.region = config.region;
+        }
+
+        if (config.credentials) {
+            clientConfig.credentials = config.credentials;
+        }
+
+        this.client = new KMSClient(clientConfig);
+    }
+
+    /**
+     * Validate request delay ms
+     */
+    private validateRequestDelayMs(requestDelayMs: number): void {
+        if (requestDelayMs < 0) {
+            throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: 'requestDelayMs must not be negative',
+            });
+        }
+        if (requestDelayMs > 3000) {
+            console.warn(
+                'requestDelayMs is greater than 3000ms, this may result in blockhash expiration errors for signing messages/transactions',
+            );
+        }
+    }
+
+    /**
+     * Add delay between concurrent requests
+     */
+    private async delay(index: number): Promise<void> {
+        if (this.requestDelayMs > 0 && index > 0) {
+            await new Promise(resolve => setTimeout(resolve, index * this.requestDelayMs));
+        }
+    }
+
+    /**
+     * Sign message bytes using AWS KMS EdDSA signing
+     */
+    private async signBytes(messageBytes: Uint8Array): Promise<SignatureBytes> {
+        try {
+            const command = new SignCommand({
+                KeyId: this.keyId,
+                Message: messageBytes,
+                MessageType: MessageType.RAW,
+                SigningAlgorithm: SigningAlgorithmSpec.ED25519_SHA_512,
+            });
+
+            const response = await this.client.send(command);
+
+            if (!response.Signature) {
+                throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                    message: 'No signature in AWS KMS response',
+                });
+            }
+
+            // Ed25519 signatures are 64 bytes
+            const signature = new Uint8Array(response.Signature);
+            if (signature.length !== 64) {
+                throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+                    message: `Invalid signature length: expected 64 bytes, got ${signature.length}`,
+                });
+            }
+
+            return signature as SignatureBytes;
+        } catch (error: unknown) {
+            // Re-throw SignerError as-is
+            if (error instanceof Error && error.name === 'SignerError') {
+                throw error;
+            }
+            if (error instanceof Error) {
+                // AWS SDK errors
+                const awsError = error as { $metadata?: { httpStatusCode?: number }; message?: string; name?: string };
+                throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                    cause: error,
+                    message: `AWS KMS Sign operation failed: ${awsError.message || error.message}`,
+                    status: awsError.$metadata?.httpStatusCode,
+                });
+            }
+            throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                cause: error,
+                message: 'AWS KMS Sign operation failed',
+            });
+        }
+    }
+
+    /**
+     * Sign multiple messages using AWS KMS
+     */
+    async signMessages(messages: readonly SignableMessage[]): Promise<readonly SignatureDictionary[]> {
+        return await Promise.all(
+            messages.map(async (message, index) => {
+                await this.delay(index);
+                const messageBytes =
+                    message.content instanceof Uint8Array
+                        ? message.content
+                        : new Uint8Array(Array.from(message.content));
+                const signatureBytes = await this.signBytes(messageBytes);
+                return createSignatureDictionary({
+                    signature: signatureBytes,
+                    signerAddress: this.address,
+                });
+            }),
+        );
+    }
+
+    /**
+     * Sign multiple transactions using AWS KMS
+     */
+    async signTransactions(
+        transactions: readonly (Transaction & TransactionWithinSizeLimit & TransactionWithLifetime)[],
+    ): Promise<readonly SignatureDictionary[]> {
+        return await Promise.all(
+            transactions.map(async (transaction, index) => {
+                await this.delay(index);
+                // Sign the transaction message bytes
+                const signatureBytes = await this.signBytes(new Uint8Array(transaction.messageBytes));
+                return createSignatureDictionary({
+                    signature: signatureBytes,
+                    signerAddress: this.address,
+                });
+            }),
+        );
+    }
+
+    /**
+     * Check if AWS KMS is available and the key is accessible
+     */
+    async isAvailable(): Promise<boolean> {
+        try {
+            const command = new DescribeKeyCommand({
+                KeyId: this.keyId,
+            });
+
+            const response = await this.client.send(command);
+
+            if (!response.KeyMetadata) {
+                return false;
+            }
+
+            // Verify the key spec is ECC_NIST_EDWARDS25519
+            const keySpec = response.KeyMetadata.KeySpec;
+            const keyUsage = response.KeyMetadata.KeyUsage;
+            const keyState = response.KeyMetadata.KeyState;
+
+            return keySpec === 'ECC_NIST_EDWARDS25519' && keyUsage === 'SIGN_VERIFY' && keyState === 'Enabled';
+        } catch {
+            return false;
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { AwsKmsSigner } from './aws-kms-signer.js';
+export type { AwsKmsSignerConfig, AwsCredentials, KmsKeyMetadata } from './types.js';

package/src/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration for creating an AwsKmsSigner
+ */
+export interface AwsKmsSignerConfig {
+    /** Optional AWS credentials (defaults to default credential provider chain) */
+    credentials?: AwsCredentials;
+    /** AWS KMS key ID or ARN (must be an ECC_NIST_EDWARDS25519 key) */
+    keyId: string;
+    /** Solana public key (base58) corresponding to the AWS KMS key */
+    publicKey: string;
+    /** Optional AWS region (defaults to default region from AWS config) */
+    region?: string;
+    /** Optional delay in ms between concurrent signing requests to avoid rate limits (default: 0) */
+    requestDelayMs?: number;
+}
+
+/**
+ * AWS credentials configuration
+ */
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+
+/**
+ * AWS KMS key metadata for validation
+ */
+export interface KmsKeyMetadata {
+    /** The AWS account ID that owns the key */
+    AWSAccountId?: string;
+    /** The key ID */
+    KeyId: string;
+    /** The key spec (must be ECC_NIST_EDWARDS25519 for EdDSA) */
+    KeySpec: 'ECC_NIST_EDWARDS25519';
+    /** The key state */
+    KeyState: 'Disabled' | 'Enabled' | 'PendingDeletion' | 'PendingImport';
+    /** The key usage (must be SIGN_VERIFY for signing) */
+    KeyUsage: 'SIGN_VERIFY';
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};