@solana/keychain-gcp-kms 0.0.0 → 0.4.0

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

@@ -0,0 +1,361 @@
+import { address } from '@solana/addresses';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { assertIsSolanaSigner } from '@solana/keychain-core';
+
+import { GcpKmsSigner } from '../gcp-kms-signer.js';
+import type { GcpKmsSignerConfig } from '../types.js';
+
+// Mock GCP KMS SDK
+const mockAsymmetricSign = vi.fn();
+const mockGetPublicKey = vi.fn();
+
+vi.mock('@google-cloud/kms', () => {
+    return {
+        v1: {
+            KeyManagementServiceClient: class {
+                asymmetricSign = mockAsymmetricSign;
+                getPublicKey = mockGetPublicKey;
+            },
+        },
+    };
+});
+
+describe('GcpKmsSigner', () => {
+    const TEST_KEY_NAME =
+        'projects/test-project/locations/us-east1/keyRings/test-ring/cryptoKeys/test-key/cryptoKeyVersions/1';
+    const TEST_PUBLIC_KEY = address('11111111111111111111111111111111');
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('constructor', () => {
+        it('creates a GcpKmsSigner with valid config', () => {
+            const config: GcpKmsSignerConfig = {
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            };
+
+            const signer = new GcpKmsSigner(config);
+
+            expect(signer.address).toBe(TEST_PUBLIC_KEY);
+            assertIsSolanaSigner(signer);
+            expect(signer.signMessages).toBeDefined();
+            expect(signer.signTransactions).toBeDefined();
+            expect(signer.isAvailable).toBeDefined();
+        });
+
+        it('should throw error for missing keyName', () => {
+            expect(() => {
+                new GcpKmsSigner({
+                    keyName: '',
+                    publicKey: TEST_PUBLIC_KEY,
+                });
+            }).toThrow('Missing required keyName field');
+        });
+
+        it('should throw error for missing publicKey', () => {
+            expect(() => {
+                new GcpKmsSigner({
+                    keyName: TEST_KEY_NAME,
+                    publicKey: '',
+                });
+            }).toThrow('Missing required publicKey field');
+        });
+        it('should throw error for invalid public key', () => {
+            expect(() => {
+                new GcpKmsSigner({
+                    keyName: TEST_KEY_NAME,
+                    publicKey: 'invalid-key',
+                });
+            }).toThrow('Invalid Solana public key format');
+        });
+
+        it('should validate requestDelayMs', () => {
+            expect(() => {
+                new GcpKmsSigner({
+                    keyName: TEST_KEY_NAME,
+                    publicKey: TEST_PUBLIC_KEY,
+                    requestDelayMs: -1,
+                });
+            }).toThrow('requestDelayMs must not be negative');
+        });
+
+        it('should warn for high requestDelayMs', () => {
+            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+            new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+                requestDelayMs: 5000,
+            });
+
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('requestDelayMs is greater than 3000ms'));
+
+            warnSpy.mockRestore();
+        });
+    });
+
+    describe('signMessages', () => {
+        it('should sign a message successfully', async () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(64).fill(0x42),
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            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(mockAsymmetricSign).toHaveBeenCalledTimes(1);
+            expect(mockAsymmetricSign).toHaveBeenCalledWith({
+                data: message.content,
+                name: TEST_KEY_NAME,
+            });
+        });
+
+        it('should handle multiple messages with delay', async () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(64).fill(0x42),
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+                requestDelayMs: 10,
+            });
+
+            const messages = [
+                { content: new Uint8Array([1]), signatures: {} },
+                { content: new Uint8Array([2]), signatures: {} },
+                { content: new Uint8Array([3]), signatures: {} },
+            ] as any;
+
+            const startTime = Date.now();
+            const result = await signer.signMessages(messages);
+            const endTime = Date.now();
+
+            expect(result).toHaveLength(3);
+            expect(mockAsymmetricSign).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 () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(32), // Wrong length
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            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 () => {
+            mockAsymmetricSign.mockResolvedValue([{}]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const message = { content: new Uint8Array([1, 2, 3, 4]), signatures: {} };
+
+            await expect(signer.signMessages([message])).rejects.toThrow('No signature in GCP KMS response');
+        });
+
+        it('should handle GCP KMS API errors', async () => {
+            const apiError = new Error('GCP Error');
+            (apiError as any).code = 403;
+            mockAsymmetricSign.mockRejectedValue(apiError);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const message = { content: new Uint8Array([1, 2, 3, 4]), signatures: {} };
+
+            await expect(signer.signMessages([message])).rejects.toThrow('GCP KMS Sign operation failed: GCP Error');
+        });
+    });
+
+    describe('signTransactions', () => {
+        it('should sign a transaction successfully', async () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(64).fill(0x42),
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const transaction = {
+                messageBytes: new Uint8Array([1, 2, 3, 4]),
+                signatures: {},
+            } as any;
+
+            const result = await signer.signTransactions([transaction]);
+
+            expect(result).toHaveLength(1);
+            expect(result[0]).toHaveProperty(signer.address);
+            expect(mockAsymmetricSign).toHaveBeenCalledTimes(1);
+        });
+
+        it('should sign multiple transactions successfully', async () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(64).fill(0x42),
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const transactions = [
+                { messageBytes: new Uint8Array([1]), signatures: {} },
+                { messageBytes: new Uint8Array([2]), signatures: {} },
+            ] as any;
+
+            const result = await signer.signTransactions(transactions);
+
+            expect(result).toHaveLength(2);
+            expect(mockAsymmetricSign).toHaveBeenCalledTimes(2);
+        });
+
+        it('should throw error on invalid signature length', async () => {
+            mockAsymmetricSign.mockResolvedValue([
+                {
+                    signature: new Uint8Array(32),
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const transaction = { messageBytes: new Uint8Array([1, 2, 3, 4]), signatures: {} } as any;
+
+            await expect(signer.signTransactions([transaction])).rejects.toThrow('Invalid signature length');
+        });
+
+        it('should throw error on missing signature', async () => {
+            mockAsymmetricSign.mockResolvedValue([{}]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const transaction = { messageBytes: new Uint8Array([1, 2, 3, 4]), signatures: {} } as any;
+
+            await expect(signer.signTransactions([transaction])).rejects.toThrow('No signature in GCP KMS response');
+        });
+
+        it('should handle GCP KMS API errors', async () => {
+            const apiError = new Error('GCP Error');
+            (apiError as any).code = 403;
+            mockAsymmetricSign.mockRejectedValue(apiError);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const transaction = { messageBytes: new Uint8Array([1, 2, 3, 4]), signatures: {} } as any;
+
+            await expect(signer.signTransactions([transaction])).rejects.toThrow(
+                'GCP KMS Sign operation failed: GCP Error',
+            );
+        });
+    });
+
+    describe('isAvailable', () => {
+        it('should return true for valid Ed25519 key', async () => {
+            mockGetPublicKey.mockResolvedValue([
+                {
+                    name: TEST_KEY_NAME,
+                    algorithm: 'EC_SIGN_ED25519',
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(true);
+        });
+
+        it('should return false for wrong algorithm', async () => {
+            mockGetPublicKey.mockResolvedValue([
+                {
+                    name: TEST_KEY_NAME,
+                    algorithm: 'RSA_SIGN_PKCS1_2048_SHA256',
+                },
+            ]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false for missing public key response', async () => {
+            mockGetPublicKey.mockResolvedValue([undefined]);
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+
+        it('should return false on error', async () => {
+            mockGetPublicKey.mockRejectedValue(new Error('GCP error'));
+
+            const signer = new GcpKmsSigner({
+                keyName: TEST_KEY_NAME,
+                publicKey: TEST_PUBLIC_KEY,
+            });
+
+            const available = await signer.isAvailable();
+
+            expect(available).toBe(false);
+        });
+    });
+});

package/src/gcp-kms-signer.ts

@@ -0,0 +1,191 @@
+import { v1 } from '@google-cloud/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 { GcpKmsSignerConfig } from './types.js';
+
+/**
+ * Google Cloud KMS-based signer using EdDSA (Ed25519) signing
+ *
+ * The GCP KMS key must be created with:
+ * - Algorithm: EC_SIGN_ED25519
+ * - Purpose: ASYMMETRIC_SIGN
+ *
+ * Example gcloud CLI command to create a key:
+ * ```bash
+ * gcloud kms keys create my-key \
+ *   --keyring=my-keyring \
+ *   --location=us-east1 \
+ *   --purpose=asymmetric-signing \
+ *   --default-algorithm=ec-sign-ed25519
+ * ```
+ */
+export class GcpKmsSigner<TAddress extends string = string> implements SolanaSigner<TAddress> {
+    readonly address: Address<TAddress>;
+    private readonly keyName: string;
+    private readonly client: v1.KeyManagementServiceClient;
+    private readonly requestDelayMs: number;
+
+    constructor(config: GcpKmsSignerConfig) {
+        if (!config.keyName) {
+            throwSignerError(SignerErrorCode.CONFIG_ERROR, {
+                message: 'Missing required keyName 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.keyName = config.keyName;
+        this.requestDelayMs = config.requestDelayMs || 0;
+        this.validateRequestDelayMs(this.requestDelayMs);
+        this.client = new v1.KeyManagementServiceClient();
+    }
+
+    /**
+     * 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 GCP KMS EdDSA signing
+     */
+    private async signBytes(messageBytes: Uint8Array): Promise<SignatureBytes> {
+        try {
+            // GCP KMS AsymmetricSign expects the raw message for Ed25519 (PureEdDSA)
+            const [response] = await this.client.asymmetricSign({
+                data: messageBytes,
+                name: this.keyName,
+            });
+
+            if (!response.signature) {
+                throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                    message: 'No signature in GCP KMS response',
+                });
+            }
+
+            // Ed25519 signatures are 64 bytes
+            const signature = response.signature as Uint8Array;
+            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) {
+                // GCP SDK errors
+                const gcpError = error as { code?: number; message?: string };
+                throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                    cause: error,
+                    message: `GCP KMS Sign operation failed: ${gcpError.message || error.message}`,
+                    status: gcpError.code,
+                });
+            }
+            throwSignerError(SignerErrorCode.REMOTE_API_ERROR, {
+                cause: error,
+                message: 'GCP KMS Sign operation failed',
+            });
+        }
+    }
+
+    /**
+     * Sign multiple messages using GCP 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 GCP 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 GCP KMS is available and the key is accessible
+     */
+    async isAvailable(): Promise<boolean> {
+        try {
+            const [publicKey] = await this.client.getPublicKey({
+                name: this.keyName,
+            });
+
+            if (!publicKey) {
+                return false;
+            }
+
+            // Verify the algorithm is EC_SIGN_ED25519
+            return publicKey.algorithm === 'EC_SIGN_ED25519';
+        } catch {
+            return false;
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { GcpKmsSigner } from './gcp-kms-signer.js';
+export type { GcpKmsSignerConfig } from './types.js';

package/src/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Configuration for creating a GcpKmsSigner
+ */
+export interface GcpKmsSignerConfig {
+    /** Full resource name of the crypto key version */
+    keyName: string;
+    /** Solana public key (base58-encoded) */
+    publicKey: string;
+    /** Optional delay in ms between concurrent signing requests to avoid rate limits (default: 0) */
+    requestDelayMs?: number;
+}