@solana/keychain-aws-kms 0.0.0 → 0.2.1

package/dist/aws-kms-signer.js

@@ -0,0 +1,174 @@
+import { DescribeKeyCommand, KMSClient, MessageType, SignCommand, SigningAlgorithmSpec } from '@aws-sdk/client-kms';
+import { assertIsAddress } from '@solana/addresses';
+import { createSignatureDictionary, SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+/**
+ * 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 {
+    constructor(config) {
+        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;
+        }
+        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 = {};
+        if (config.region) {
+            clientConfig.region = config.region;
+        }
+        if (config.credentials) {
+            clientConfig.credentials = config.credentials;
+        }
+        this.client = new KMSClient(clientConfig);
+    }
+    /**
+     * 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 AWS KMS EdDSA signing
+     */
+    async signBytes(messageBytes) {
+        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;
+        }
+        catch (error) {
+            // Re-throw SignerError as-is
+            if (error instanceof Error && error.name === 'SignerError') {
+                throw error;
+            }
+            if (error instanceof Error) {
+                // AWS SDK errors
+                const awsError = error;
+                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) {
+        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) {
+        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() {
+        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;
+        }
+    }
+}
+//# sourceMappingURL=aws-kms-signer.js.map

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

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AwsKmsSigner } from './aws-kms-signer.js';
+export type { AwsKmsSignerConfig, AwsCredentials, KmsKeyMetadata } 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,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AwsKmsSigner } from './aws-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,39 @@
+/**
+ * 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';
+}
+//# 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,+EAA+E;IAC/E,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,uBAAuB,CAAC;IACjC,oBAAoB;IACpB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,eAAe,CAAC;IACvE,sDAAsD;IACtD,QAAQ,EAAE,aAAa,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,58 @@
 {
   "name": "@solana/keychain-aws-kms",
-  "version": "0.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "author": "Solana Foundation",
+  "version": "0.2.1",
+  "description": "AWS KMS-based signer for Solana transactions using EdDSA (Ed25519)",
+  "license": "MIT",
+  "repository": "https://github.com/solana-foundation/solana-keychain",
+  "keywords": [
+    "solana",
+    "signing",
+    "wallet",
+    "aws",
+    "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": {
+    "@aws-sdk/client-kms": "^3.700.0",
+    "@solana/addresses": "^5.0.0",
+    "@solana/codecs-strings": "^5.0.0",
+    "@solana/keys": "^5.0.0",
+    "@solana/signers": "^5.0.0",
+    "@solana/transactions": "^5.0.0",
+    "@solana/keychain-core": "0.2.1"
+  },
+  "devDependencies": {
+    "dotenv": "^17.2.3",
+    "@solana/keychain-test-utils": "0.2.1"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "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"
+  }
+}