solana-kms-signer 0.1.0

package/dist/kms/signer.js

@@ -0,0 +1,230 @@
+import { PublicKey, } from '@solana/web3.js';
+import nacl from 'tweetnacl';
+import { KmsClient } from './client.js';
+import { extractEd25519PublicKey } from '../utils/publicKey.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 {
+    /**
+     * 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) {
+        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() {
+        // 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() {
+        // 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) {
+        // 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) {
+        // 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) {
+        // 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) {
+        return Promise.all(transactions.map((transaction) => this.signTransaction(transaction)));
+    }
+}
+//# sourceMappingURL=signer.js.map

package/dist/kms/signer.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 {
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ;;WAEG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;WAEG;QACH,eAAe,EAAE,MAAM,CAAC;QAExB;;WAEG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,SAAS;CAEvD"}

package/dist/types/index.js

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

package/dist/types/index.js.map

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

package/dist/utils/publicKey.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function extractEd25519PublicKey(derEncoded: Uint8Array): Uint8Array;
+//# sourceMappingURL=publicKey.d.ts.map

package/dist/utils/publicKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicKey.d.ts","sourceRoot":"","sources":["../../src/utils/publicKey.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAyC1E"}

package/dist/utils/publicKey.js

@@ -0,0 +1,56 @@
+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) {
+    // 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);
+}
+//# sourceMappingURL=publicKey.js.map

package/dist/utils/publicKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicKey.js","sourceRoot":"","sources":["../../src/utils/publicKey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAsB;IAC5D,kEAAkE;IAClE,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,wBAAwB,CAChC,4CAA4C,CAC7C,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,oEAAoE;IACpE,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,wBAAwB,CAChC,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,MAAM,yBAAyB,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAEhD,uDAAuD;IACvD,gEAAgE;IAChE,MAAM,cAAc,GAAG,CAAC,GAAG,yBAAyB,CAAC;IAErD,+BAA+B;IAC/B,IAAI,UAAU,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,wBAAwB,CAChC,0CAA0C,CAC3C,CAAC;IACJ,CAAC;IAED,uFAAuF;IACvF,MAAM,eAAe,GAAG,UAAU,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IACvD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,wBAAwB,CAChC,iEAAiE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,MAAM,cAAc,GAAG,cAAc,GAAG,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,KAAK,CAAC,cAAc,EAAE,cAAc,GAAG,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "solana-kms-signer",
+  "version": "0.1.0",
+  "description": "AWS KMS-based Solana signer with ED25519 support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "example:sign-message": "tsx examples/sign-message.ts",
+    "example:sign-transaction": "tsx examples/sign-transaction.ts",
+    "example:sign-versioned-transaction": "tsx examples/sign-versioned-transaction.ts",
+    "example:multiple-signatures": "tsx examples/multiple-signatures.ts",
+    "example:create-kms-key": "tsx examples/create-kms-key.ts"
+  },
+  "keywords": [
+    "solana",
+    "kms",
+    "aws",
+    "signature",
+    "ed25519",
+    "transaction",
+    "signing",
+    "key-management",
+    "cryptography",
+    "blockchain"
+  ],
+  "author": "Taegeon Alan Go",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gtg7784/solana-kms-signer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gtg7784/solana-kms-signer/issues"
+  },
+  "homepage": "https://github.com/gtg7784/solana-kms-signer#readme",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@vitest/coverage-v8": "^4.0.8",
+    "@vitest/ui": "^4.0.8",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8"
+  },
+  "packageManager": "pnpm@9.0.1+sha1.0e0a9c2d140ddf9aab730067eb7bcfb9e18bdee7",
+  "dependencies": {
+    "@aws-sdk/client-kms": "^3.928.0",
+    "@solana/web3.js": "^1.98.4",
+    "tweetnacl": "^1.0.3"
+  }
+}

package/src/errors/index.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import { KmsClientError, PublicKeyExtractionError, SignatureVerificationError } from './index.js';
+
+describe('Error Classes', () => {
+  describe('KmsClientError', () => {
+    it('should create error with message', () => {
+      // given
+      const message = 'Test KMS error';
+
+      // when
+      const error = new KmsClientError(message);
+
+      // then
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(KmsClientError);
+      expect(error.message).toBe(message);
+      expect(error.name).toBe('KmsClientError');
+      expect(error.cause).toBeUndefined();
+    });
+
+    it('should create error with message and cause', () => {
+      // given
+      const message = 'Test KMS error';
+      const cause = new Error('Original error');
+
+      // when
+      const error = new KmsClientError(message, cause);
+
+      // then
+      expect(error.message).toBe(message);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('KmsClientError');
+    });
+
+    it('should create error with cause as object', () => {
+      // given
+      const message = 'Test KMS error';
+      const cause = { code: 'AccessDeniedException', statusCode: 403 };
+
+      // when
+      const error = new KmsClientError(message, cause);
+
+      // then
+      expect(error.cause).toBe(cause);
+    });
+
+    it('should have stack trace', () => {
+      // given
+      const message = 'Test KMS error';
+
+      // when
+      const error = new KmsClientError(message);
+
+      // then
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('KmsClientError');
+    });
+  });
+
+  describe('PublicKeyExtractionError', () => {
+    it('should create error with message', () => {
+      // given
+      const message = 'Invalid DER encoding';
+
+      // when
+      const error = new PublicKeyExtractionError(message);
+
+      // then
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(PublicKeyExtractionError);
+      expect(error.message).toBe(message);
+      expect(error.name).toBe('PublicKeyExtractionError');
+      expect(error.cause).toBeUndefined();
+    });
+
+    it('should create error with message and cause', () => {
+      // given
+      const message = 'Invalid DER encoding';
+      const cause = new Error('DER parsing failed');
+
+      // when
+      const error = new PublicKeyExtractionError(message, cause);
+
+      // then
+      expect(error.message).toBe(message);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('PublicKeyExtractionError');
+    });
+
+    it('should have stack trace', () => {
+      // given
+      const message = 'Invalid DER encoding';
+
+      // when
+      const error = new PublicKeyExtractionError(message);
+
+      // then
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('PublicKeyExtractionError');
+    });
+  });
+
+  describe('SignatureVerificationError', () => {
+    it('should create error with message', () => {
+      // given
+      const message = 'Signature verification failed';
+
+      // when
+      const error = new SignatureVerificationError(message);
+
+      // then
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(SignatureVerificationError);
+      expect(error.message).toBe(message);
+      expect(error.name).toBe('SignatureVerificationError');
+      expect(error.cause).toBeUndefined();
+    });
+
+    it('should create error with message and cause', () => {
+      // given
+      const message = 'Signature verification failed';
+      const cause = { signature: new Uint8Array(64), publicKey: new Uint8Array(32) };
+
+      // when
+      const error = new SignatureVerificationError(message, cause);
+
+      // then
+      expect(error.message).toBe(message);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('SignatureVerificationError');
+    });
+
+    it('should have stack trace', () => {
+      // given
+      const message = 'Signature verification failed';
+
+      // when
+      const error = new SignatureVerificationError(message);
+
+      // then
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('SignatureVerificationError');
+    });
+  });
+
+  describe('Error Chaining', () => {
+    it('should support error chaining with nested causes', () => {
+      // given
+      const rootCause = new Error('Root cause error');
+      const intermediateCause = new PublicKeyExtractionError('Intermediate error', rootCause);
+
+      // when
+      const topLevelError = new KmsClientError('Top level error', intermediateCause);
+
+      // then
+      expect(topLevelError.cause).toBe(intermediateCause);
+      expect((topLevelError.cause as PublicKeyExtractionError).cause).toBe(rootCause);
+    });
+
+    it('should preserve cause immutability', () => {
+      // given
+      const message = 'Test error';
+      const cause = { code: 'TEST_ERROR' };
+      const error = new KmsClientError(message, cause);
+
+      // when/then
+      // TypeScript should prevent reassignment:
+      // error.cause = { code: 'DIFFERENT_ERROR' }; // This would cause TypeScript error
+
+      expect(error.cause).toBe(cause);
+    });
+  });
+});