Implement HashiCorp Vault module

Author: inf1nite-lo0p

package-lock.json

@@ -0,0 +1 @@
+FROM hashicorp/vault:1.13.0

packages/modules/vault/Dockerfile

@@ -0,0 +1,38 @@
+{
+  "name": "@testcontainers/vault",
+  "version": "11.2.1",
+  "license": "MIT",
+  "keywords": [
+    "vault",
+    "hashicorp",
+    "testing",
+    "docker",
+    "testcontainers"
+  ],
+  "description": "HashiCorp Vault module for Testcontainers",
+  "homepage": "https://github.com/testcontainers/testcontainers-node#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/testcontainers/testcontainers-node"
+  },
+  "bugs": {
+    "url": "https://github.com/testcontainers/testcontainers-node/issues"
+  },
+  "main": "build/index.js",
+  "files": [
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "shx cp ../../../README.md . && shx cp ../../../LICENSE .",
+    "build": "tsc --project tsconfig.build.json"
+  },
+  "devDependencies": {
+    "node-vault": "^0.10.5"
+  },
+  "dependencies": {
+    "testcontainers": "^11.2.1"
+  }
+}

packages/modules/vault/package.json

@@ -0,0 +1 @@
+export { StartedVaultContainer, VaultContainer } from "./vault-container";

packages/modules/vault/src/index.ts

@@ -0,0 +1,50 @@
+import vault from "node-vault";
+import { setTimeout } from "node:timers/promises";
+import { StartedVaultContainer, VaultContainer } from "./vault-container";
+
+const VAULT_TOKEN = "my-root-token";
+
+describe("vault", { timeout: 180_000 }, () => {
+  let container: StartedVaultContainer;
+
+  afterEach(async () => {
+    await container?.stop();
+  });
+
+  it("should start Vault and allow reading/writing secrets", async () => {
+    container = await new VaultContainer().withVaultToken(VAULT_TOKEN).start();
+
+    const client = vault({
+      apiVersion: "v1",
+      endpoint: container.getAddress(),
+      token: container.getRootToken(),
+    });
+
+    await client.write("secret/data/hello", {
+      data: {
+        message: "world",
+        other: "vault",
+      },
+    });
+
+    await setTimeout(1000);
+
+    const result = await client.read("secret/data/hello");
+    const data = result?.data?.data;
+
+    expect(data.message).toBe("world");
+    expect(data.other).toBe("vault");
+  });
+
+  it("should execute init commands using vault CLI", async () => {
+    container = await new VaultContainer()
+      .withVaultToken(VAULT_TOKEN)
+      .withInitCommands("secrets enable transit", "write -f transit/keys/my-key")
+      .start();
+
+    const result = await container.exec(["vault", "read", "-format=json", "transit/keys/my-key"]);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.output).toContain("my-key");
+  });
+});

packages/modules/vault/src/vault-container.test.ts

@@ -0,0 +1,129 @@
+import { AbstractStartedContainer, GenericContainer, Wait } from "testcontainers";
+
+const VAULT_PORT = 8200;
+
+/**
+ * Testcontainers module for HashiCorp Vault.
+ *
+ * Based on the upstream image `hashicorp/vault:1.13.0`, this container exposes Vault
+ * on port 8200, sets up a wait strategy using the health check endpoint, and supports:
+ * - Supplying a root token
+ * - Executing post-start CLI init commands
+ */
+export class VaultContainer extends GenericContainer {
+  private readonly initCommands: string[] = [];
+  private token?: string;
+
+  /**
+   * Constructs a VaultContainer with a default image and healthcheck strategy.
+   *
+   * - Sets VAULT_ADDR to internal container address
+   * - Adds IPC_LOCK capability (required by Vault)
+   * - Exposes Vault on port 8200
+   * - Waits for HTTP 200 response from /v1/sys/health
+   *
+   * @param image Optional Docker image to use (default: hashicorp/vault:1.13.0)
+   */
+  constructor(image: string = "hashicorp/vault:1.13.0") {
+    super(image);
+
+    this.withExposedPorts(VAULT_PORT)
+      .withEnvironment({ VAULT_ADDR: `http://0.0.0.0:${VAULT_PORT}` })
+      .withAddedCapabilities("IPC_LOCK")
+      .withWaitStrategy(Wait.forHttp("/v1/sys/health", VAULT_PORT).forStatusCode(200));
+  }
+
+  /**
+   * Sets a root token to be used with Vault, passed via environment variables.
+   *
+   * @param token Vault root token
+   * @returns this
+   */
+  public withVaultToken(token: string): this {
+    this.token = token;
+    this.withEnvironment({
+      VAULT_DEV_ROOT_TOKEN_ID: token,
+      VAULT_TOKEN: token,
+    });
+    return this;
+  }
+
+  /**
+   * Registers one or more Vault CLI init commands to be run after container starts.
+   *
+   * Example:
+   *   .withInitCommands("secrets enable transit", "kv put secret/foo bar=baz")
+   *
+   * @param commands Vault CLI commands (without `vault` prefix)
+   * @returns this
+   */
+  public withInitCommands(...commands: string[]): this {
+    this.initCommands.push(...commands);
+    return this;
+  }
+
+  /**
+   * Starts the Vault container and executes any registered init commands.
+   *
+   * Wraps the base container in a StartedVaultContainer with helper accessors.
+   */
+  public override async start(): Promise<StartedVaultContainer> {
+    const started = await super.start();
+    const container = new StartedVaultContainer(started, this.token);
+
+    if (this.initCommands.length > 0) {
+      await container.execVaultCommands(this.initCommands);
+    }
+
+    return container;
+  }
+}
+
+/**
+ * A running Vault container, with accessors for port, address, and exec helper.
+ */
+export class StartedVaultContainer extends AbstractStartedContainer {
+  constructor(
+    startedTestContainer: AbstractStartedContainer["startedTestContainer"],
+    private readonly token?: string
+  ) {
+    super(startedTestContainer);
+  }
+
+  /**
+   * Returns the mapped host port for Vault (default: 8200).
+   */
+  public getVaultPort(): number {
+    return this.getMappedPort(VAULT_PORT);
+  }
+
+  /**
+   * Returns the full Vault HTTP address (e.g., http://localhost:32768).
+   */
+  public getAddress(): string {
+    return `http://${this.getHost()}:${this.getVaultPort()}`;
+  }
+
+  /**
+   * Returns the root token set at container creation time, if any.
+   */
+  public getRootToken(): string | undefined {
+    return this.token;
+  }
+
+  /**
+   * Executes a list of Vault CLI commands inside the container after it has started.
+   *
+   * This is typically used to pre-configure secret engines or seed test data.
+   *
+   * @param commands Array of CLI commands (without `vault` prefix)
+   */
+  public async execVaultCommands(commands: string[]): Promise<void> {
+    const cmd = commands.map((c) => `vault ${c}`).join(" && ");
+    const result = await this.exec(["/bin/sh", "-c", cmd]);
+
+    if (result.exitCode !== 0) {
+      throw new Error(`Vault init commands failed: ${result.output}`);
+    }
+  }
+}

packages/modules/vault/src/vault-container.ts

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [
+    "build",
+    "src/**/*.test.ts"
+  ],
+  "references": [
+    {
+      "path": "../../testcontainers"
+    }
+  ]
+}

packages/modules/vault/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build",
+    "paths": {
+      "testcontainers": [
+        "../../testcontainers/src"
+      ]
+    }
+  },
+  "exclude": [
+    "build"
+  ],
+  "references": [
+    {
+      "path": "../../testcontainers"
+    }
+  ]
+}