@solana/keychain-gcp-kms 0.0.0 → 0.4.0

package/dist/gcp-kms-signer.js

@@ -0,0 +1,161 @@
+import { v1 } from '@google-cloud/kms';
+import { assertIsAddress } from '@solana/addresses';
+import { createSignatureDictionary, SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+/**
+ * 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 {
+    constructor(config) {
+        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;
+        }
+        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
+     */
+    validateRequestDelayMs(requestDelayMs) {
+        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
+     */
+    async delay(index) {
+        if (this.requestDelayMs > 0 && index > 0) {
+            await new Promise(resolve => setTimeout(resolve, index * this.requestDelayMs));
+        }
+    }
+    /**
+     * Sign message bytes using GCP KMS EdDSA signing
+     */
+    async signBytes(messageBytes) {
+        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;
+            if (signature.length !== 64) {
+                throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+                    message: `Invalid signature length: expected 64 bytes, got ${signature.length}`,
+                });
+            }
+            return signature;
+        }
+        catch (error) {
+            // Re-throw SignerError as-is
+            if (error instanceof Error && error.name === 'SignerError') {
+                throw error;
+            }
+            if (error instanceof Error) {
+                // GCP SDK errors
+                const gcpError = error;
+                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) {
+        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) {
+        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() {
+        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;
+        }
+    }
+}
+//# sourceMappingURL=gcp-kms-signer.js.map

package/dist/gcp-kms-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-kms-signer.js","sourceRoot":"","sources":["../src/gcp-kms-signer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GcpKmsSigner } from './gcp-kms-signer.js';
+export type { GcpKmsSignerConfig } from './types.js';
+//# 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":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { GcpKmsSigner } from './gcp-kms-signer.js';
+//# 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,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,12 +1,59 @@
 {
   "name": "@solana/keychain-gcp-kms",
-  "version": "0.0.0",
-  "description": "",
-  "license": "ISC",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "author": "Solana Foundation",
+  "version": "0.4.0",
+  "description": "Google Cloud KMS-based signer for Solana transactions using EdDSA (Ed25519)",
+  "license": "MIT",
+  "repository": "https://github.com/solana-foundation/solana-keychain",
+  "keywords": [
+    "solana",
+    "signing",
+    "wallet",
+    "gcp",
+    "kms",
+    "ed25519",
+    "eddsa"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@google-cloud/kms": "^5.2.1",
+    "@solana/addresses": "^6.0.1",
+    "@solana/keys": "^6.0.1",
+    "@solana/signers": "^6.0.1",
+    "@solana/transactions": "^6.0.1",
+    "@solana/keychain-core": "0.4.0"
+  },
+  "devDependencies": {
+    "@solana-program/memo": "^0.11.0",
+    "@solana/kit": "^6.0.1",
+    "dotenv": "^17.2.3",
+    "@solana/keychain-test-utils": "0.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:unit": "vitest run --config ../../vitest.config.unit.ts",
+    "test:integration": "vitest run --config ../../vitest.config.integration.ts",
+    "test:watch": "vitest",
+    "test:watch:unit": "vitest --config ../../vitest.config.unit.ts",
+    "test:watch:integration": "vitest --config ../../vitest.config.integration.ts",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

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

@@ -0,0 +1,82 @@
+import {
+    appendTransactionMessageInstructions,
+    createSolanaRpc,
+    createTransactionMessage,
+    pipe,
+    setTransactionMessageFeePayerSigner,
+    setTransactionMessageLifetimeUsingBlockhash,
+    signTransactionMessageWithSigners,
+} from '@solana/kit';
+import { getAddMemoInstruction } from '@solana-program/memo';
+import { config } from 'dotenv';
+import { describe, expect, it } from 'vitest';
+
+import { GcpKmsSigner } from '../gcp-kms-signer.js';
+
+config();
+
+const REQUIRED_ENV_VARS = ['GCP_KMS_KEY_NAME', 'GCP_KMS_SIGNER_PUBKEY'];
+
+function hasRequiredEnvVars(): boolean {
+    return REQUIRED_ENV_VARS.every(v => process.env[v]);
+}
+
+function createGcpKmsSigner(): GcpKmsSigner {
+    return new GcpKmsSigner({
+        keyName: process.env.GCP_KMS_KEY_NAME!,
+        publicKey: process.env.GCP_KMS_SIGNER_PUBKEY!,
+    });
+}
+
+describe('GcpKmsSigner Integration', () => {
+    it.skipIf(!hasRequiredEnvVars())(
+        'signs transactions with GCP KMS',
+        async () => {
+            const signer = createGcpKmsSigner();
+            const rpcUrl = process.env.SOLANA_RPC_URL ?? 'https://api.devnet.solana.com';
+
+            // Get real blockhash from devnet
+            const rpc = createSolanaRpc(rpcUrl);
+            const {
+                value: { blockhash, lastValidBlockHeight },
+            } = await rpc.getLatestBlockhash().send();
+
+            // Create memo transaction (doesn't need funds)
+            const transaction = pipe(
+                createTransactionMessage({ version: 0 }),
+                tx => setTransactionMessageFeePayerSigner(signer, tx),
+                tx => appendTransactionMessageInstructions([getAddMemoInstruction({ memo: 'GCP KMS test' })], tx),
+                tx => setTransactionMessageLifetimeUsingBlockhash({ blockhash, lastValidBlockHeight }, tx),
+            );
+
+            // Sign via GCP KMS
+            const signed = await signTransactionMessageWithSigners(transaction);
+
+            // Verify signature returned
+            expect(signed.signatures[signer.address]).toBeDefined();
+            expect(signed.signatures[signer.address]?.length).toBe(64);
+        },
+        60_000,
+    ); // 1 minute timeout
+
+    it.skipIf(!hasRequiredEnvVars())('signs messages', async () => {
+        const signer = createGcpKmsSigner();
+
+        const message = {
+            content: new Uint8Array([1, 2, 3, 4, 5]),
+            signatures: {},
+        };
+
+        const result = await signer.signMessages([message]);
+
+        expect(result).toHaveLength(1);
+        expect(result[0]?.[signer.address]).toBeDefined();
+        expect(result[0]?.[signer.address]?.length).toBe(64);
+    });
+
+    it.skipIf(!hasRequiredEnvVars())('checks availability', async () => {
+        const signer = createGcpKmsSigner();
+        const available = await signer.isAvailable();
+        expect(available).toBe(true);
+    });
+});