GCP Secret Manager

Lightweight, dependency-free fake of Google Cloud Secret Manager that speaks the real Secret Manager v1 REST API (https://secretmanager.googleapis.com/v1), so application code using @google-cloud/secret-manager can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { GcpSecretmanagerServer } from "./services/gcp-secretmanager/src/server.js";

const server = new GcpSecretmanagerServer(4585);
await server.start();
// ... use it ...
await server.stop();

Connect with the real @google-cloud/secret-manager client. The fake speaks the HTTP/1.1 REST transport (the google-gax fallback mode), so the low-level gapic SecretManagerServiceClient must be constructed with fallback: true, protocol: "http", and an explicit apiEndpoint + port pointing at the fake:

import { v1 } from "@google-cloud/secret-manager";

const client = new v1.SecretManagerServiceClient({
  projectId: "parlel",
  fallback: true,          // use the HTTP/1.1 REST transport instead of gRPC
  protocol: "http",        // talk plain HTTP to the local fake
  apiEndpoint: "127.0.0.1",
  port: 4585,
  // Any credentials work — the fake never verifies them.
});

const parent = client.projectPath("parlel");

// Create a secret with automatic replication.
const [secret] = await client.createSecret({
  parent,
  secretId: "db-password",
  secret: { replication: { automatic: {} } },
});

// Add a secret version (the actual secret material).
await client.addSecretVersion({
  parent: secret.name,
  payload: { data: Buffer.from("s3cr3t-value", "utf8") },
});

// Access the latest version.
const [resp] = await client.accessSecretVersion({
  name: `${secret.name}/versions/latest`,
});
console.log(resp.payload.data.toString("utf8")); // "s3cr3t-value"

The high-level convenience client (SecretManagerServiceClient from the package root) works the same way — it is the same gapic client under the hood.

Implemented Operations

All 15 RPCs that the @google-cloud/secret-manager v1 client exposes are implemented. The library's listSecretsStream / listSecretsAsync / listSecretVersionsStream / listSecretVersionsAsync are client-side pagination variants of ListSecrets / ListSecretVersions and are exercised by the fake's pagination support.

Secrets

Secret Versions

IAM

Internal (parlel-only) endpoints

Regional bindings

Every RPC also has a regional additional_binding under projects/*/locations/*/.... The fake is region-agnostic: it normalizes the /locations/{loc} segment away, so a secret created globally is reachable via its regional name and vice-versa.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes / shapes

Errors are returned as the standard Google google.rpc.Status JSON body, which the google-gax REST decoder transcodes back into the canonical gRPC status code on the client (error.code):

{
  "error": {
    "code": 404,
    "message": "Secret [projects/parlel/secrets/missing] not found.",
    "status": "NOT_FOUND"
  }
}

Note on duplicate-create. The real service returns ALREADY_EXISTS (code 6). There is no HTTP status that the gax REST decoder maps back to code 6 (HTTP 409 decodes to ABORTED, which gax retries). To preserve the non-retryable, immediately-rejecting behavior callers expect, the fake surfaces duplicate-create conflicts as FAILED_PRECONDITION (code 9).

Running the tests

npx vitest run tests/gcp-secretmanager.test.ts

The suite starts the server on a high non-conflicting port, drives every operation through the real @google-cloud/secret-manager client over the REST transport, asserts the responses (happy paths + edge cases), and tears the server down in afterAll.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel