solana-kms-signer 0.1.0

package/src/kms/signer.ts

@@ -0,0 +1,274 @@
+import {
+  PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from '@solana/web3.js';
+import nacl from 'tweetnacl';
+import { KmsClient } from './client.js';
+import { extractEd25519PublicKey } from '../utils/publicKey.js';
+import type { KmsConfig } from '../types/index.js';
+import { SignatureVerificationError } from '../errors/index.js';
+
+/**
+ * Solana transaction signer using AWS KMS ED25519 keys.
+ *
+ * Provides methods to sign Solana transactions and arbitrary messages
+ * using AWS KMS-managed ED25519 keys. Caches the public key after
+ * first retrieval to minimize KMS API calls.
+ *
+ * @example
+ * ```typescript
+ * // Create with KmsConfig
+ * const signer = new SolanaKmsSigner({
+ *   region: 'us-east-1',
+ *   keyId: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012'
+ * });
+ *
+ * // Or create with existing KmsClient
+ * const client = new KmsClient(config);
+ * const signer = new SolanaKmsSigner(client);
+ *
+ * // Get public key
+ * const publicKey = await signer.getPublicKey();
+ *
+ * // Sign message
+ * const message = new TextEncoder().encode('Hello, Solana!');
+ * const signature = await signer.signMessage(message);
+ *
+ * // Sign transaction
+ * const transaction = new Transaction().add(instruction);
+ * transaction.recentBlockhash = recentBlockhash;
+ * transaction.feePayer = publicKey;
+ * const signedTx = await signer.signTransaction(transaction);
+ * ```
+ */
+export class SolanaKmsSigner {
+  private readonly kmsClient: KmsClient;
+  private publicKey?: PublicKey;
+  private rawPublicKey?: Uint8Array;
+
+  /**
+   * Creates a new SolanaKmsSigner instance.
+   *
+   * @param config - Either KmsConfig or an existing KmsClient instance
+   *
+   * @example
+   * ```typescript
+   * // With KmsConfig
+   * const signer = new SolanaKmsSigner({
+   *   region: 'us-east-1',
+   *   keyId: 'key-id'
+   * });
+   *
+   * // With KmsClient
+   * const client = new KmsClient(config);
+   * const signer = new SolanaKmsSigner(client);
+   * ```
+   */
+  constructor(config: KmsConfig | KmsClient) {
+    if (config instanceof KmsClient) {
+      this.kmsClient = config;
+    } else {
+      this.kmsClient = new KmsClient(config);
+    }
+  }
+
+  /**
+   * Retrieves the Solana PublicKey associated with the KMS key.
+   *
+   * The public key is cached after first retrieval to minimize KMS API calls.
+   *
+   * @returns Solana PublicKey object
+   * @throws {KmsClientError} If KMS API call fails
+   * @throws {PublicKeyExtractionError} If DER decoding fails
+   *
+   * @example
+   * ```typescript
+   * const publicKey = await signer.getPublicKey();
+   * console.log('Address:', publicKey.toBase58());
+   * ```
+   */
+  async getPublicKey(): Promise<PublicKey> {
+    // Return cached public key if available
+    if (this.publicKey) {
+      return this.publicKey;
+    }
+
+    // Get DER-encoded public key from KMS
+    const derPublicKey = await this.kmsClient.getPublicKey();
+
+    // Extract raw 32-byte ED25519 public key
+    const rawPublicKey = extractEd25519PublicKey(derPublicKey);
+
+    // Create Solana PublicKey and cache both forms
+    this.rawPublicKey = rawPublicKey;
+    this.publicKey = new PublicKey(rawPublicKey);
+
+    return this.publicKey;
+  }
+
+  /**
+   * Retrieves the raw 32-byte ED25519 public key.
+   *
+   * The public key is cached after first retrieval to minimize KMS API calls.
+   *
+   * @returns Raw 32-byte public key as Uint8Array
+   * @throws {KmsClientError} If KMS API call fails
+   * @throws {PublicKeyExtractionError} If DER decoding fails
+   *
+   * @example
+   * ```typescript
+   * const rawPublicKey = await signer.getRawPublicKey();
+   * console.log('Raw public key length:', rawPublicKey.length); // 32
+   * ```
+   */
+  async getRawPublicKey(): Promise<Uint8Array> {
+    // Return cached raw public key if available
+    if (this.rawPublicKey) {
+      return this.rawPublicKey;
+    }
+
+    // Get DER-encoded public key from KMS
+    const derPublicKey = await this.kmsClient.getPublicKey();
+
+    // Extract raw 32-byte ED25519 public key
+    this.rawPublicKey = extractEd25519PublicKey(derPublicKey);
+
+    return this.rawPublicKey;
+  }
+
+  /**
+   * Signs an arbitrary message using the KMS key.
+   *
+   * The signature is verified using tweetnacl before being returned
+   * to ensure cryptographic correctness.
+   *
+   * @param message - Message to sign as Uint8Array
+   * @returns ED25519 signature (64 bytes)
+   * @throws {KmsClientError} If KMS API call fails
+   * @throws {SignatureVerificationError} If signature verification fails
+   *
+   * @example
+   * ```typescript
+   * const message = new TextEncoder().encode('Hello, Solana!');
+   * const signature = await signer.signMessage(message);
+   * console.log('Signature length:', signature.length); // 64
+   * ```
+   */
+  async signMessage(message: Uint8Array): Promise<Uint8Array> {
+    // Get signature from KMS
+    const signature = await this.kmsClient.sign(message);
+
+    // Get raw public key for verification
+    const rawPublicKey = await this.getRawPublicKey();
+
+    // Verify signature using tweetnacl
+    const isValid = nacl.sign.detached.verify(
+      message,
+      signature,
+      rawPublicKey
+    );
+
+    if (!isValid) {
+      throw new SignatureVerificationError(
+        'Signature verification failed: signature does not match public key and message'
+      );
+    }
+
+    return signature;
+  }
+
+  /**
+   * Signs a Solana legacy Transaction.
+   *
+   * The transaction must have recentBlockhash and feePayer set before signing.
+   *
+   * @param transaction - Transaction to sign
+   * @returns Signed transaction
+   * @throws {KmsClientError} If KMS API call fails
+   * @throws {SignatureVerificationError} If signature verification fails
+   *
+   * @example
+   * ```typescript
+   * const transaction = new Transaction().add(instruction);
+   * transaction.recentBlockhash = recentBlockhash;
+   * transaction.feePayer = await signer.getPublicKey();
+   * const signedTx = await signer.signTransaction(transaction);
+   * ```
+   */
+  async signTransaction(transaction: Transaction): Promise<Transaction> {
+    // Get public key for signing
+    const publicKey = await this.getPublicKey();
+
+    // Serialize transaction message
+    const message = transaction.serializeMessage();
+
+    // Sign the serialized message
+    const signature = await this.signMessage(message);
+
+    // Add signature to transaction
+    transaction.addSignature(publicKey, Buffer.from(signature));
+
+    return transaction;
+  }
+
+  /**
+   * Signs a Solana VersionedTransaction.
+   *
+   * The transaction must have a valid message with recentBlockhash set.
+   *
+   * @param transaction - VersionedTransaction to sign
+   * @returns Signed versioned transaction
+   * @throws {KmsClientError} If KMS API call fails
+   * @throws {SignatureVerificationError} If signature verification fails
+   *
+   * @example
+   * ```typescript
+   * const message = MessageV0.compile({
+   *   payerKey: await signer.getPublicKey(),
+   *   instructions: [instruction],
+   *   recentBlockhash: recentBlockhash
+   * });
+   * const transaction = new VersionedTransaction(message);
+   * const signedTx = await signer.signVersionedTransaction(transaction);
+   * ```
+   */
+  async signVersionedTransaction(
+    transaction: VersionedTransaction
+  ): Promise<VersionedTransaction> {
+    // Serialize transaction message
+    const message = transaction.message.serialize();
+
+    // Sign the serialized message
+    const signature = await this.signMessage(message);
+
+    // Add signature to transaction's signatures array
+    transaction.addSignature(await this.getPublicKey(), Buffer.from(signature));
+
+    return transaction;
+  }
+
+  /**
+   * Signs multiple Solana transactions in parallel.
+   *
+   * All transactions must have recentBlockhash and feePayer set before signing.
+   *
+   * @param transactions - Array of transactions to sign
+   * @returns Array of signed transactions in the same order
+   * @throws {KmsClientError} If any KMS API call fails
+   * @throws {SignatureVerificationError} If any signature verification fails
+   *
+   * @example
+   * ```typescript
+   * const transactions = [tx1, tx2, tx3];
+   * const signedTxs = await signer.signAllTransactions(transactions);
+   * ```
+   */
+  async signAllTransactions(
+    transactions: Transaction[]
+  ): Promise<Transaction[]> {
+    return Promise.all(
+      transactions.map((transaction) => this.signTransaction(transaction))
+    );
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Configuration for AWS KMS client.
+ */
+export interface KmsConfig {
+  /**
+   * AWS region where the KMS key is located (e.g., 'us-east-1').
+   */
+  region: string;
+
+  /**
+   * KMS key ID or ARN to use for signing operations.
+   */
+  keyId: string;
+
+  /**
+   * Optional AWS credentials. If not provided, the AWS SDK will use
+   * environment variables, IAM roles, or other credential providers.
+   */
+  credentials?: {
+    /**
+     * AWS access key ID.
+     */
+    accessKeyId: string;
+
+    /**
+     * AWS secret access key.
+     */
+    secretAccessKey: string;
+
+    /**
+     * Optional session token for temporary credentials.
+     */
+    sessionToken?: string;
+  };
+}
+
+/**
+ * Configuration for Solana KMS Signer.
+ * Currently extends KmsConfig with no additional fields.
+ * Additional configuration options can be added in the future.
+ */
+export interface SolanaKmsSignerConfig extends KmsConfig {
+  // Additional configuration options can be added here in the future
+}

package/src/utils/publicKey.test.ts

@@ -0,0 +1,135 @@
+import { extractEd25519PublicKey } from './publicKey.js';
+import { PublicKeyExtractionError } from '../errors/index.js';
+
+/**
+ * Mock DER-encoded ED25519 public key matching AWS KMS GetPublicKey format.
+ * Structure:
+ * - 30 2a: SEQUENCE, 42 bytes
+ * - 30 05: AlgorithmIdentifier SEQUENCE
+ * - 06 03 2b 65 70: OID 1.3.101.112 (Ed25519)
+ * - 03 21 00: BIT STRING, 33 bytes (32 bytes + 1 padding)
+ * - [32 bytes]: Mock public key data
+ */
+const MOCK_DER_PUBLIC_KEY = new Uint8Array([
+  0x30, 0x2a, // SEQUENCE, 42 bytes
+  0x30, 0x05, // AlgorithmIdentifier SEQUENCE, 5 bytes
+  0x06, 0x03, 0x2b, 0x65, 0x70, // OID: 1.3.101.112 (Ed25519)
+  0x03, 0x21, 0x00, // BIT STRING, 33 bytes (32 + 1 padding)
+  // Mock 32-byte ED25519 public key
+  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
+  0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10,
+  0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
+  0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+]);
+
+describe('extractEd25519PublicKey', () => {
+  describe('Happy Path', () => {
+    it('should extract 32-byte public key from valid DER encoding', () => {
+      // given: Valid DER-encoded public key from AWS KMS
+      const derEncoded = MOCK_DER_PUBLIC_KEY;
+
+      // when: Extracting public key
+      const publicKey = extractEd25519PublicKey(derEncoded);
+
+      // then: Should return exactly 32 bytes
+      expect(publicKey).toBeInstanceOf(Uint8Array);
+      expect(publicKey.length).toBe(32);
+
+      // then: Should match the mock public key bytes (starting at offset 12)
+      const expectedPublicKey = new Uint8Array([
+        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
+        0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10,
+        0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
+        0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+      ]);
+      expect(publicKey).toEqual(expectedPublicKey);
+    });
+  });
+
+  describe('Failure Paths', () => {
+    it('should throw PublicKeyExtractionError when SEQUENCE tag is missing', () => {
+      // given: Invalid DER with wrong first byte (not 0x30)
+      const invalidDer = new Uint8Array([
+        0x31, 0x2a, // Wrong tag (0x31 instead of 0x30)
+        0x30, 0x05,
+        0x06, 0x03, 0x2b, 0x65, 0x70,
+        0x03, 0x21, 0x00,
+        ...new Array(32).fill(0x01),
+      ]);
+
+      // when & then: Should throw PublicKeyExtractionError
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        PublicKeyExtractionError
+      );
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        'Invalid DER encoding: missing SEQUENCE tag'
+      );
+    });
+
+    it('should throw PublicKeyExtractionError when BIT STRING tag is missing', () => {
+      // given: Invalid DER without BIT STRING tag (0x03)
+      const invalidDer = new Uint8Array([
+        0x30, 0x2a, // SEQUENCE
+        0x30, 0x05, // AlgorithmIdentifier
+        0x06, 0x03, 0x2b, 0x65, 0x70, // OID
+        0x04, 0x21, 0x00, // Wrong tag (0x04 instead of 0x03)
+        ...new Array(32).fill(0x01),
+      ]);
+
+      // when & then: Should throw PublicKeyExtractionError
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        PublicKeyExtractionError
+      );
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        'Invalid DER encoding: missing BIT STRING'
+      );
+    });
+
+    it('should throw PublicKeyExtractionError when BIT STRING length is incorrect', () => {
+      // given: Invalid DER with wrong BIT STRING length (0x20 instead of 0x21)
+      const invalidDer = new Uint8Array([
+        0x30, 0x2a, // SEQUENCE
+        0x30, 0x05, // AlgorithmIdentifier
+        0x06, 0x03, 0x2b, 0x65, 0x70, // OID
+        0x03, 0x20, 0x00, // Wrong length (0x20 = 32 instead of 0x21 = 33)
+        ...new Array(32).fill(0x01),
+      ]);
+
+      // when & then: Should throw PublicKeyExtractionError with specific message
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        PublicKeyExtractionError
+      );
+      expect(() => extractEd25519PublicKey(invalidDer)).toThrow(
+        'Unexpected BIT STRING length: expected 0x21 (33 bytes), got 0x20'
+      );
+    });
+
+    it('should throw PublicKeyExtractionError when input is empty', () => {
+      // given: Empty Uint8Array
+      const emptyInput = new Uint8Array(0);
+
+      // when & then: Should throw PublicKeyExtractionError
+      expect(() => extractEd25519PublicKey(emptyInput)).toThrow(
+        PublicKeyExtractionError
+      );
+      expect(() => extractEd25519PublicKey(emptyInput)).toThrow(
+        'Invalid DER encoding: missing SEQUENCE tag'
+      );
+    });
+
+    it('should throw error when input is null or undefined', () => {
+      // given: Null input
+      const nullInput = null as unknown as Uint8Array;
+
+      // when & then: Should throw TypeError (not PublicKeyExtractionError)
+      // Note: This tests TypeScript runtime behavior - null/undefined are not Uint8Array
+      expect(() => extractEd25519PublicKey(nullInput)).toThrow();
+
+      // given: Undefined input
+      const undefinedInput = undefined as unknown as Uint8Array;
+
+      // when & then: Should throw TypeError
+      expect(() => extractEd25519PublicKey(undefinedInput)).toThrow();
+    });
+  });
+});

package/src/utils/publicKey.ts

@@ -0,0 +1,70 @@
+import { PublicKeyExtractionError } from '../errors/index.js';
+
+/**
+ * Extracts a 32-byte ED25519 public key from DER-encoded SubjectPublicKeyInfo.
+ *
+ * AWS KMS GetPublicKey returns DER-encoded public keys in X.509 SubjectPublicKeyInfo format:
+ * ```
+ * 30 2a          # SEQUENCE, 42 bytes
+ *   30 05        # SEQUENCE, 5 bytes (AlgorithmIdentifier)
+ *     06 03      # OID, 3 bytes
+ *       2b 65 70 # 1.3.101.112 (Ed25519)
+ *   03 21 00     # BIT STRING, 33 bytes (32 bytes + 1 byte padding)
+ *     [32 bytes] # ED25519 public key
+ * ```
+ *
+ * This function extracts the raw 32-byte public key from the DER structure.
+ *
+ * @param derEncoded - DER-encoded SubjectPublicKeyInfo from AWS KMS
+ * @returns Raw 32-byte ED25519 public key
+ * @throws {PublicKeyExtractionError} If the DER encoding is invalid or unexpected
+ *
+ * @example
+ * ```typescript
+ * const derEncoded = await kmsClient.getPublicKey();
+ * const rawPublicKey = extractEd25519PublicKey(derEncoded);
+ * // rawPublicKey is Uint8Array of 32 bytes
+ * ```
+ */
+export function extractEd25519PublicKey(derEncoded: Uint8Array): Uint8Array {
+  // Validate DER structure - first byte must be SEQUENCE tag (0x30)
+  if (derEncoded[0] !== 0x30) {
+    throw new PublicKeyExtractionError(
+      'Invalid DER encoding: missing SEQUENCE tag'
+    );
+  }
+
+  // Parse AlgorithmIdentifier SEQUENCE to find where BIT STRING starts
+  // Position 2 should be another SEQUENCE tag for AlgorithmIdentifier
+  if (derEncoded[2] !== 0x30) {
+    throw new PublicKeyExtractionError(
+      'Invalid DER encoding: missing AlgorithmIdentifier SEQUENCE'
+    );
+  }
+
+  // Get length of AlgorithmIdentifier content
+  const algorithmIdentifierLength = derEncoded[3];
+
+  // BIT STRING starts after AlgorithmIdentifier SEQUENCE
+  // Position = 4 (first content byte) + algorithmIdentifierLength
+  const bitStringIndex = 4 + algorithmIdentifierLength;
+
+  // Verify BIT STRING tag (0x03)
+  if (derEncoded[bitStringIndex] !== 0x03) {
+    throw new PublicKeyExtractionError(
+      'Invalid DER encoding: missing BIT STRING'
+    );
+  }
+
+  // Verify BIT STRING length (0x21 = 33 bytes: 1 byte unused bits + 32 bytes public key)
+  const bitStringLength = derEncoded[bitStringIndex + 1];
+  if (bitStringLength !== 0x21) {
+    throw new PublicKeyExtractionError(
+      `Unexpected BIT STRING length: expected 0x21 (33 bytes), got 0x${bitStringLength.toString(16)}`
+    );
+  }
+
+  // First byte after length is unused bits (0x00), next 32 bytes is the public key
+  const publicKeyStart = bitStringIndex + 3;
+  return derEncoded.slice(publicKeyStart, publicKeyStart + 32);
+}