Skip to content

Secrets over KV

client.secrets() implements the shared Grow Codes Secrets interface (get, getString, getJson, require, exists, getMany, getAll, list, set, delete, metadata, loadEnv, watch, SecretCache) on top of a KV mount. Code written against it works unchanged with every other Grow Codes secrets package.

Mapping

Topic Behaviour
Location secret name → KV path <secretsPath>/<name> (or <options.path>/<name>) on kvMount (default secret, KV version auto-detected)
Value stored as {"value": "<text>"} (field valueField); bytes that are not valid UTF-8 as base64 with "encoding": "base64"; objects JSON-encoded into value
Existing multi-field secrets a path without the value field is returned as the JSON encoding of the whole map (getJson decodes it)
Versions SecretValue.version and set(...) return the KV v2 version as a string; "" on KV v1; get(name, {version}) reads that version (KV v1 → VALIDATION)
set options cas (check-and-set, CONFLICT on mismatch), tags and description (custom metadata); KV v1 → UNSUPPORTED
delete options default soft-deletes the latest version; versions deletes those versions; permanent removes every version and the metadata; NOT_FOUND when missing
list(prefix) names directly under the folder, sorted, sub-folders skipped; on KV v2 with metadata (read per key, 8 at a time)
metadata(name) version (current), createdAt, updatedAt, tags (custom metadata), versions (count), extra: maxVersions, casRequired, deleteVersionAfter (e.g. "0s"), oldestVersion
Deleted versions a key whose current version is deleted or destroyed counts as missing everywhere

Example

const secrets = client.secrets({ path: "apps/web" }); // or GROW_HASHICORP_VAULT_SECRETS_PATH
const version = await secrets.set("db-password", "s3cret", { tags: { owner: "team-a" } });
const password = await secrets.require("db-password");
connect(password.reveal());
await secrets.set("db-password", "rotated", { cas: Number(version) });
const previous = await secrets.get("db-password", { version });
console.log(await secrets.list()); // [{ name: "db-password", version: "2", tags: {...}, ... }]
await secrets.delete("db-password", { permanent: true });
use grow_hashicorp_vault::secrets::{GetOptions, SecretsProvider};
use grow_hashicorp_vault::SecretsProviderOptions;

let secrets = client.secrets_with(SecretsProviderOptions {
    path: Some("apps/web".into()),
    ..Default::default()
});
let version = secrets.set("db-password", "s3cret".into(), None).await?;
let password = secrets.require("db-password", None).await?;
connect(password.reveal()?);
let previous = secrets
    .get("db-password", Some(&GetOptions { version: Some(version), ..Default::default() }))
    .await?;
secrets := client.SecretsWith(vault.SecretsProviderOptions{Path: "apps/web"})
version, err := secrets.Set(ctx, "db-password", "s3cret", &vault.SetOptions{Tags: map[string]string{"owner": "team-a"}})
if err != nil {
    return err
}
password, err := secrets.Require(ctx, "db-password", nil)
text, _ := password.Reveal()
connect(text)
previous, err := secrets.Get(ctx, "db-password", &vault.GetOptions{Version: version})
err = secrets.Delete(ctx, "db-password", &vault.DeleteOptions{Permanent: true})
secrets = client.secrets(path="apps/web")
version = secrets.set("db-password", "s3cret", tags={"owner": "team-a"})
connect(secrets.require("db-password").reveal())
secrets.set("db-password", "rotated", cas=int(version))
previous = secrets.get("db-password", version=version)
secrets.delete("db-password", permanent=True)
VaultSecretsProvider secrets =
    client.secrets(SecretsOptions.builder().path("apps/web").build());
String version = secrets.set("db-password", "s3cret");
connect(secrets.require("db-password").reveal());
Optional<SecretValue> previous =
    secrets.get("db-password", GetOptions.builder().version(version).build());
secrets.delete("db-password", DeleteOptions.builder().permanent(true).build());