evm-kms-signer 1.0.0 → 1.1.0

package/README.md

@@ -1,38 +1,41 @@
-# kms-signer-evm
+# evm-kms-signer
 
-A TypeScript library that integrates AWS KMS (Key Management Service) with [viem](https://viem.sh) to create secure Ethereum signers. This allows you to sign Ethereum transactions and messages using keys stored in AWS KMS, providing enterprise-grade security for your Ethereum operations.
+A TypeScript library that integrates AWS/GCP KMS (Key Management Service) with [viem](https://viem.sh) to create secure Ethereum signers. This allows you to sign Ethereum transactions and messages using keys stored in AWS or GCP KMS, providing enterprise-grade security for your Ethereum operations.
 
 ## Features
 
 - **AWS KMS Integration**: Sign Ethereum transactions using keys securely stored in AWS KMS
+- **GCP KMS Support**: Also supports Google Cloud Platform KMS for multi-cloud deployments
 - **Full EIP Compliance**: Supports EIP-191 (personal messages), EIP-712 (typed data), EIP-155 (replay protection), EIP-2 (signature normalization)
 - **Type-Safe**: Built with TypeScript in strict mode with comprehensive type definitions
 - **viem Compatible**: Seamlessly integrates with viem's Account system via `toAccount`
-- **DER Signature Parsing**: Automatically converts AWS KMS DER-encoded signatures to Ethereum format
+- **DER Signature Parsing**: Automatically converts AWS/GCP KMS DER-encoded signatures to Ethereum format
 - **Comprehensive Error Handling**: Custom error classes for better debugging
-- **Well-Tested**: 51 tests covering all functionality with 100% type safety
+- **Well-Tested**: 169 tests covering all functionality with 100% type safety
 
 ## Installation
 
 ```bash
-pnpm add kms-signer-evm
+pnpm add evm-kms-signer
 ```
 
 Or with npm:
 
 ```bash
-npm install kms-signer-evm
+npm install evm-kms-signer
 ```
 
 Or with yarn:
 
 ```bash
-yarn add kms-signer-evm
+yarn add evm-kms-signer
 ```
 
-## Prerequisites
+## Usage
 
-### AWS KMS Key Setup
+### AWS KMS
+
+#### Prerequisites
 
 1. **Create an ECC Key in AWS KMS**:
    - Go to AWS KMS Console
@@ -50,7 +53,7 @@ yarn add kms-signer-evm
 3. **Note Your Key ID**:
    Copy the Key ARN or Key ID for use in your application.
 
-### Environment Variables
+#### Environment Variables
 
 Create a `.env` file in your project root:
 
@@ -63,13 +66,11 @@ AWS_ACCESS_KEY_ID=your_access_key
 AWS_SECRET_ACCESS_KEY=your_secret_key
 ```
 
-## Quick Start
-
-### Signing a Message
+#### Basic Usage
 
 ```typescript
 import 'dotenv/config'
-import { KmsSigner, toKmsAccount } from 'kms-signer-evm'
+import { KmsSigner, toKmsAccount } from 'evm-kms-signer'
 
 async function main() {
   // Initialize the KMS signer
@@ -93,13 +94,13 @@ async function main() {
 main().catch(console.error)
 ```
 
-### Sending a Transaction
+#### Use with viem
 
 ```typescript
 import 'dotenv/config'
 import { createWalletClient, http } from 'viem'
 import { sepolia } from 'viem/chains'
-import { KmsSigner, toKmsAccount } from 'kms-signer-evm'
+import { KmsSigner, toKmsAccount } from 'evm-kms-signer'
 
 async function main() {
   // Initialize the KMS signer
@@ -130,6 +131,63 @@ async function main() {
 main().catch(console.error)
 ```
 
+### GCP KMS
+
+#### Prerequisites
+
+1. **Create a KMS key ring and crypto key in GCP Console**:
+   - Go to Google Cloud Console → Security → Key Management
+   - Create a new key ring in your desired location
+   - Create a crypto key with purpose "Asymmetric sign"
+   - Choose **Elliptic Curve P-256 - SHA256 Digest** algorithm (secp256k1 for Ethereum)
+
+2. **Grant Permissions**:
+   Grant `roles/cloudkms.cryptoKeySignerVerifier` permission to your service account:
+   ```bash
+   gcloud kms keys add-iam-policy-binding KEY_ID \
+     --location=LOCATION \
+     --keyring=KEYRING_ID \
+     --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
+     --role=roles/cloudkms.cryptoKeySignerVerifier
+   ```
+
+3. **Set up authentication**:
+   - Set `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to your service account key file, or
+   - Pass `keyFilename` in config
+
+#### Basic Usage
+
+```typescript
+import { GcpSigner } from 'evm-kms-signer';
+
+const signer = new GcpSigner({
+  projectId: 'your-project-id',
+  locationId: 'global',
+  keyRingId: 'your-keyring-id',
+  keyId: 'your-key-id',
+  keyVersion: '1',
+  keyFilename: '/path/to/service-account-key.json', // optional
+});
+
+const address = await signer.getAddress();
+const signature = await signer.signMessage({ message: 'Hello!' });
+```
+
+#### Use with viem
+
+```typescript
+import { createWalletClient, http } from 'viem';
+import { mainnet } from 'viem/chains';
+import { toGcpKmsAccount } from 'evm-kms-signer';
+
+const account = await toGcpKmsAccount(signer);
+const client = createWalletClient({
+  account,
+  chain: mainnet,
+  transport: http(),
+});
+```
+
 ## API Documentation
 
 ### `KmsSigner`
@@ -302,4 +360,5 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 - Built with [viem](https://viem.sh) - Modern TypeScript Ethereum library
 - Uses [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)
+- Uses [Google Cloud KMS Client Library](https://cloud.google.com/nodejs/docs/reference/kms/latest)
 - Inspired by the need for secure key management in Ethereum applications

package/dist/account.d.ts

@@ -1,5 +1,6 @@
 import type { LocalAccount } from 'viem';
-import { KmsSigner } from './kms/signer';
+import type { GcpSigner } from './gcp/signer';
+import type { KmsSigner } from './kms/signer';
 /**
  * Create a viem Account from KmsSigner.
  *
@@ -22,4 +23,32 @@ import { KmsSigner } from './kms/signer';
  * ```
  */
 export declare function toKmsAccount(signer: KmsSigner): Promise<LocalAccount>;
+/**
+ * Create a viem Account from GcpSigner.
+ *
+ * Wraps GcpSigner methods to match viem's Account interface,
+ * enabling use with viem clients (walletClient, etc.)
+ *
+ * @param signer - GcpSigner instance
+ * @returns viem Account with GCP KMS signing capabilities
+ *
+ * @example
+ * ```typescript
+ * const signer = new GcpSigner({
+ *   projectId: 'my-project',
+ *   locationId: 'global',
+ *   keyRingId: 'my-keyring',
+ *   keyId: 'my-key',
+ *   keyVersion: '1'
+ * })
+ * const account = await toGcpKmsAccount(signer)
+ *
+ * const client = createWalletClient({
+ *   account,
+ *   chain: mainnet,
+ *   transport: http()
+ * })
+ * ```
+ */
+export declare function toGcpKmsAccount(signer: GcpSigner): Promise<LocalAccount>;
 //# sourceMappingURL=account.d.ts.map

package/dist/account.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAa3E"}
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAe3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CACpC,MAAM,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,CAAC,CAevB"}

package/dist/account.js

@@ -30,7 +30,47 @@ export async function toKmsAccount(signer) {
             return signer.signMessage({ message: messageStr });
         },
         signTransaction: async (transaction, options) => signer.signTransaction(transaction, options),
-        signTypedData: async (typedData) => signer.signTypedData(typedData)
+        signTypedData: async (typedData) => signer.signTypedData(typedData),
+    });
+}
+/**
+ * Create a viem Account from GcpSigner.
+ *
+ * Wraps GcpSigner methods to match viem's Account interface,
+ * enabling use with viem clients (walletClient, etc.)
+ *
+ * @param signer - GcpSigner instance
+ * @returns viem Account with GCP KMS signing capabilities
+ *
+ * @example
+ * ```typescript
+ * const signer = new GcpSigner({
+ *   projectId: 'my-project',
+ *   locationId: 'global',
+ *   keyRingId: 'my-keyring',
+ *   keyId: 'my-key',
+ *   keyVersion: '1'
+ * })
+ * const account = await toGcpKmsAccount(signer)
+ *
+ * const client = createWalletClient({
+ *   account,
+ *   chain: mainnet,
+ *   transport: http()
+ * })
+ * ```
+ */
+export async function toGcpKmsAccount(signer) {
+    const address = await signer.getAddress();
+    return toAccount({
+        address,
+        signMessage: async ({ message }) => {
+            // Convert SignableMessage to string for GcpSigner
+            const messageStr = typeof message === 'string' ? message : message.raw.toString();
+            return signer.signMessage({ message: messageStr });
+        },
+        signTransaction: async (transaction, options) => signer.signTransaction(transaction, options),
+        signTypedData: async (typedData) => signer.signTypedData(typedData),
     });
 }
 //# sourceMappingURL=account.js.map

package/dist/account.js.map

@@ -1 +1 @@
-{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAIzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IAClD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAA;IAEzC,OAAO,SAAS,CAAC;QACf,OAAO;QACP,WAAW,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;YACjC,kDAAkD;YAClD,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAA;YACjF,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAA;QACpD,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC;QAC7F,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;KACpE,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IACnD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAE1C,OAAO,SAAS,CAAC;QAChB,OAAO;QACP,WAAW,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;YAClC,kDAAkD;YAClD,MAAM,UAAU,GACf,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAChE,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAC/C,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC;QAC7C,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;KACnE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,MAAiB;IAEjB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAE1C,OAAO,SAAS,CAAC;QAChB,OAAO;QACP,WAAW,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;YAClC,kDAAkD;YAClD,MAAM,UAAU,GACf,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAChE,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAC/C,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC;QAC7C,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;KACnE,CAAC,CAAC;AACJ,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,cAAe,SAAQ,cAAc;aACH,KAAK,CAAC,EAAE,KAAK;gBAA9C,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAI3D;AAED,qBAAa,2BAA4B,SAAQ,cAAc;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,0BAA2B,SAAQ,cAAc;gBAChD,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B;AAED,qBAAa,eAAgB,SAAQ,cAAc;gBACtC,OAAO,EAAE,MAAM;CAI3B;AAED,qBAAa,cAAe,SAAQ,cAAc;aAGhC,KAAK,CAAC,EAAE,KAAK;gBAD7B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,KAAK,YAAA;CAK9B;AAED,qBAAa,2BAA4B,SAAQ,cAAc;gBAClD,OAAO,EAAE,MAAM;CAI3B;AAED,qBAAa,0BAA2B,SAAQ,cAAc;gBACjD,OAAO,EAAE,MAAM;CAI3B"}

package/dist/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,YAAY,OAAe,EAAkB,KAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAA;QAD6B,UAAK,GAAL,KAAK,CAAQ;QAExD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,cAAc;IAC7D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;IAC1C,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACxC,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC9B,CAAC;CACD;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IAClD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AAED,MAAM,OAAO,cAAe,SAAQ,cAAc;IACjD,YACC,OAAe,EACC,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC9B,CAAC;CACD;AAED,MAAM,OAAO,2BAA4B,SAAQ,cAAc;IAC9D,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC3C,CAAC;CACD;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC7D,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC1C,CAAC;CACD"}

package/dist/gcp/client.d.ts

@@ -0,0 +1,91 @@
+import type { GcpKmsConfig } from '../types';
+/**
+ * GcpClient wraps GCP KMS SDK operations for key management and signing.
+ *
+ * This class provides a simplified interface to GCP KMS for:
+ * - Retrieving public keys from KMS
+ * - Signing message digests with KMS-stored private keys
+ *
+ * @example
+ * ```typescript
+ * const client = new GcpClient({
+ *   projectId: 'my-project',
+ *   locationId: 'global',
+ *   keyRingId: 'my-keyring',
+ *   keyId: 'my-key',
+ *   keyVersion: '1'
+ * })
+ *
+ * const publicKey = await client.getPublicKey()
+ * const signature = await client.sign(messageHash)
+ * ```
+ */
+export declare class GcpClient {
+    private client;
+    private keyName;
+    /**
+     * Creates a new GCP KMS client instance.
+     *
+     * @param config - GCP KMS configuration including project, location, key ring, key, and version
+     *
+     * @remarks
+     * If keyFilename is not provided, the GCP SDK will use the default credential provider chain:
+     * - GOOGLE_APPLICATION_CREDENTIALS environment variable
+     * - Application Default Credentials (ADC)
+     * - Service account attached to the compute resource
+     */
+    constructor(config: GcpKmsConfig);
+    /**
+     * Retrieves the public key from GCP KMS.
+     *
+     * @returns The public key in DER-encoded SubjectPublicKeyInfo (SPKI) format
+     * @throws {KmsClientError} If the KMS API call fails or returns no public key
+     *
+     * @remarks
+     * GCP KMS returns the public key in PEM format, which is converted to DER format.
+     * The returned public key is in SPKI format with a variable-length DER header.
+     * The last 65 bytes contain the uncompressed secp256k1 public key (0x04 + x + y).
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Signs a message hash using the GCP KMS-stored private key.
+     *
+     * @param messageHash - The pre-hashed message to sign (32 bytes for keccak256)
+     * @returns The signature in DER-encoded format (SEQUENCE { INTEGER r, INTEGER s })
+     * @throws {KmsClientError} If the KMS API call fails or returns no signature
+     *
+     * @remarks
+     * - The messageHash should already be hashed (e.g., with keccak256)
+     * - GCP KMS uses EC_SIGN_SECP256K1_SHA256 algorithm for signing
+     * - The returned signature is DER-encoded and needs to be parsed to extract r and s values
+     */
+    sign(messageHash: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Converts PEM-encoded data to DER-encoded format.
+     *
+     * @param pem - PEM-encoded public key string
+     * @returns DER-encoded public key as Uint8Array
+     * @throws {KmsClientError} If PEM format is invalid
+     *
+     * @remarks
+     * PEM format consists of:
+     * - Header line: -----BEGIN PUBLIC KEY-----
+     * - Base64-encoded DER data
+     * - Footer line: -----END PUBLIC KEY-----
+     *
+     * This method extracts the Base64 data and decodes it to DER format.
+     */
+    private pemToDer;
+    /**
+     * Calculates CRC32C checksum for data integrity verification.
+     *
+     * @param data - Data to calculate checksum for
+     * @returns CRC32C checksum as number
+     *
+     * @remarks
+     * GCP KMS requires CRC32C checksums for request/response integrity verification.
+     * This is a simple implementation using a lookup table.
+     */
+    private calculateCrc32c;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/gcp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/gcp/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;;;;OAUG;gBACS,MAAM,EAAE,YAAY;IAUhC;;;;;;;;;;OAUG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAqBzC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAqDxD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,QAAQ;IAkBhB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;CAkBvB"}

package/dist/gcp/client.js

@@ -0,0 +1,179 @@
+import { KeyManagementServiceClient } from '@google-cloud/kms';
+import { KmsClientError } from '../errors';
+/**
+ * GcpClient wraps GCP KMS SDK operations for key management and signing.
+ *
+ * This class provides a simplified interface to GCP KMS for:
+ * - Retrieving public keys from KMS
+ * - Signing message digests with KMS-stored private keys
+ *
+ * @example
+ * ```typescript
+ * const client = new GcpClient({
+ *   projectId: 'my-project',
+ *   locationId: 'global',
+ *   keyRingId: 'my-keyring',
+ *   keyId: 'my-key',
+ *   keyVersion: '1'
+ * })
+ *
+ * const publicKey = await client.getPublicKey()
+ * const signature = await client.sign(messageHash)
+ * ```
+ */
+export class GcpClient {
+    /**
+     * Creates a new GCP KMS client instance.
+     *
+     * @param config - GCP KMS configuration including project, location, key ring, key, and version
+     *
+     * @remarks
+     * If keyFilename is not provided, the GCP SDK will use the default credential provider chain:
+     * - GOOGLE_APPLICATION_CREDENTIALS environment variable
+     * - Application Default Credentials (ADC)
+     * - Service account attached to the compute resource
+     */
+    constructor(config) {
+        this.client = new KeyManagementServiceClient(config.keyFilename ? { keyFilename: config.keyFilename } : {});
+        // Construct the full key resource name
+        // Format: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{key}/cryptoKeyVersions/{version}
+        this.keyName = `projects/${config.projectId}/locations/${config.locationId}/keyRings/${config.keyRingId}/cryptoKeys/${config.keyId}/cryptoKeyVersions/${config.keyVersion}`;
+    }
+    /**
+     * Retrieves the public key from GCP KMS.
+     *
+     * @returns The public key in DER-encoded SubjectPublicKeyInfo (SPKI) format
+     * @throws {KmsClientError} If the KMS API call fails or returns no public key
+     *
+     * @remarks
+     * GCP KMS returns the public key in PEM format, which is converted to DER format.
+     * The returned public key is in SPKI format with a variable-length DER header.
+     * The last 65 bytes contain the uncompressed secp256k1 public key (0x04 + x + y).
+     */
+    async getPublicKey() {
+        try {
+            const [publicKey] = await this.client.getPublicKey({
+                name: this.keyName,
+            });
+            if (!publicKey.pem) {
+                throw new KmsClientError('No public key returned from GCP KMS');
+            }
+            // Convert PEM to DER format
+            return this.pemToDer(publicKey.pem);
+        }
+        catch (error) {
+            if (error instanceof KmsClientError)
+                throw error;
+            throw new KmsClientError(`Failed to get public key from GCP KMS: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Signs a message hash using the GCP KMS-stored private key.
+     *
+     * @param messageHash - The pre-hashed message to sign (32 bytes for keccak256)
+     * @returns The signature in DER-encoded format (SEQUENCE { INTEGER r, INTEGER s })
+     * @throws {KmsClientError} If the KMS API call fails or returns no signature
+     *
+     * @remarks
+     * - The messageHash should already be hashed (e.g., with keccak256)
+     * - GCP KMS uses EC_SIGN_SECP256K1_SHA256 algorithm for signing
+     * - The returned signature is DER-encoded and needs to be parsed to extract r and s values
+     */
+    async sign(messageHash) {
+        try {
+            // Create CRC32C checksum for message integrity
+            const crc32c = this.calculateCrc32c(messageHash);
+            const [response] = await this.client.asymmetricSign({
+                name: this.keyName,
+                digest: {
+                    sha256: messageHash,
+                },
+                digestCrc32c: {
+                    value: crc32c,
+                },
+            });
+            if (!response.signature) {
+                throw new KmsClientError('No signature returned from GCP KMS');
+            }
+            // Convert signature to Uint8Array
+            const signatureBytes = typeof response.signature === 'string'
+                ? Buffer.from(response.signature, 'base64')
+                : response.signature instanceof Buffer
+                    ? response.signature
+                    : new Uint8Array(response.signature);
+            // Verify the signature CRC32C if provided
+            if (response.signatureCrc32c && response.verifiedDigestCrc32c) {
+                const signatureCrc32c = this.calculateCrc32c(signatureBytes instanceof Buffer
+                    ? new Uint8Array(signatureBytes)
+                    : signatureBytes);
+                if (signatureCrc32c !== Number(response.signatureCrc32c.value)) {
+                    throw new KmsClientError('Signature CRC32C verification failed - data may be corrupted');
+                }
+            }
+            return signatureBytes instanceof Buffer
+                ? new Uint8Array(signatureBytes)
+                : signatureBytes;
+        }
+        catch (error) {
+            if (error instanceof KmsClientError)
+                throw error;
+            throw new KmsClientError(`Failed to sign with GCP KMS: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Converts PEM-encoded data to DER-encoded format.
+     *
+     * @param pem - PEM-encoded public key string
+     * @returns DER-encoded public key as Uint8Array
+     * @throws {KmsClientError} If PEM format is invalid
+     *
+     * @remarks
+     * PEM format consists of:
+     * - Header line: -----BEGIN PUBLIC KEY-----
+     * - Base64-encoded DER data
+     * - Footer line: -----END PUBLIC KEY-----
+     *
+     * This method extracts the Base64 data and decodes it to DER format.
+     */
+    pemToDer(pem) {
+        try {
+            // Remove PEM header, footer, and whitespace
+            const base64 = pem
+                .replace(/-----BEGIN PUBLIC KEY-----/, '')
+                .replace(/-----END PUBLIC KEY-----/, '')
+                .replace(/\s/g, '');
+            // Decode Base64 to DER
+            return Uint8Array.from(Buffer.from(base64, 'base64'));
+        }
+        catch (error) {
+            throw new KmsClientError(`Failed to convert PEM to DER: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Calculates CRC32C checksum for data integrity verification.
+     *
+     * @param data - Data to calculate checksum for
+     * @returns CRC32C checksum as number
+     *
+     * @remarks
+     * GCP KMS requires CRC32C checksums for request/response integrity verification.
+     * This is a simple implementation using a lookup table.
+     */
+    calculateCrc32c(data) {
+        // CRC32C polynomial lookup table
+        const crc32cTable = new Int32Array(256);
+        for (let i = 0; i < 256; i++) {
+            let c = i;
+            for (let j = 0; j < 8; j++) {
+                c = c & 1 ? 0x82f63b78 ^ (c >>> 1) : c >>> 1;
+            }
+            crc32cTable[i] = c;
+        }
+        let crc = 0xffffffff;
+        for (let i = 0; i < data.length; i++) {
+            crc = crc32cTable[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+        }
+        return (crc ^ 0xffffffff) >>> 0;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/gcp/client.js.map

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