@agent-base/secret-client

A simple and modern TypeScript client for interacting with Google Cloud Secret Manager.

This package provides a convenient wrapper around the official @google-cloud/secret-manager library, offering a streamlined interface for common secret management operations.

Features

• Easy-to-use API for creating, retrieving, and checking existence of secrets.
• Strongly-typed for enhanced developer experience with TypeScript.
• Configurable for Google Cloud Project ID and credentials.
• Designed for ES Module environments.

Installation

1pnpm install @agent-base/secret-client
2# or
3yarn add @agent-base/secret-client
4# or
5npm install @agent-base/secret-client

Prerequisites

Before using this client, ensure you have:

1. A Google Cloud Platform project.
2. The Secret Manager API enabled for your project.
3. Authentication configured. This can be through:
   • Application Default Credentials (ADC) by running gcloud auth application-default login.
   • A service account key JSON file.

Usage

1import { GoogleSecretManager } from '@agent-base/secret-client';
2
3async function main() {
4  // Initialize the client
5  // Option 1: Using Application Default Credentials (ADC)
6  const gsmClient = new GoogleSecretManager({
7    projectId: 'your-gcp-project-id',
8  });
9
10  // Option 2: Using a service account key
11  /*
12  const credentials = {
13    client_email: 'your-service-account-email@your-project-id.iam.gserviceaccount.com',
14    private_key: '-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n',
15  };
16  const gsmClientWithCreds = new GoogleSecretManager({
17    projectId: 'your-gcp-project-id',
18    credentials,
19  });
20  */
21
22  const secretId = 'my-api-key';
23  const secretValue = 's3cr3tV@lu3';
24
25  try {
26    // Store a secret (creates if not exists, then adds a new version)
27    await gsmClient.storeSecret(secretId, secretValue);
28    console.log(`Secret '${secretId}' stored successfully.`);
29
30    // Retrieve the latest version of the secret
31    const retrievedValue = await gsmClient.getSecret(secretId);
32    if (retrievedValue !== null) {
33      console.log(`Retrieved secret '${secretId}': ${retrievedValue}`);
34    } else {
35      console.log(`Secret '${secretId}' not found or has no value.`);
36    }
37
38    // Check if a secret exists
39    const exists = await gsmClient.secretExists(secretId);
40    console.log(`Secret '${secretId}' exists: ${exists}`);
41
42    // Example: Storing another version
43    await gsmClient.storeSecret(secretId, 'newS3cr3tV@lu3_v2');
44    console.log(`Stored new version for secret '${secretId}'.`);
45    const updatedValue = await gsmClient.getSecret(secretId);
46    console.log(`Retrieved updated secret '${secretId}': ${updatedValue}`);
47
48
49    // Attempt to retrieve a non-existent secret
50    const nonExistentSecret = await gsmClient.getSecret('non-existent-secret');
51    console.log(`Value of 'non-existent-secret': ${nonExistentSecret}`); // Expected: null
52
53  } catch (error) {
54    console.error('An error occurred:', error);
55  }
56}
57
58main();

API

new GoogleSecretManager(config: GoogleSecretManagerConfig)

Creates a new instance of the GoogleSecretManager client.

Config:

• projectId: string: Your Google Cloud Project ID.
• credentials?: { client_email: string; private_key: string; }: Optional. Service account credentials. If not provided, ADC will be used.

async storeSecret(secretId: string, value: string): Promise<void>

Stores a secret value.

• If the secret does not exist, it creates the secret and adds the value as the first version.
• If the secret exists, it adds a new version with the provided value.

async getSecret(secretId: string): Promise<string | null>

Retrieves the latest version of a secret's value. Returns null if the secret or version is not found, or if the version has no data.

async secretExists(secretId: string): Promise<boolean>

Checks if a secret with the given secretId exists.

Error Handling

The client methods may throw errors originating from the @google-cloud/secret-manager library or custom errors like GoogleSecretManagerError for configuration issues.

Contributing

Contributions are welcome! Please see the main repository's contributing guidelines.

License

MIT