Capabilities and namespaces¶
Two Vault-only additions on top of the API shared with the OpenBao SDK: capability checks, so a caller can test a policy before acting, and namespace views for Vault Enterprise.
| Function | What it does |
|---|---|
sys.capabilitiesSelf(paths) |
POST sys/capabilities-self: the capabilities of the client token on each path. paths is one path or a list (surrounding slashes are removed; at least one path, else VALIDATION). |
sys.capabilities(token, paths) |
POST sys/capabilities: the capabilities of another token. The caller needs update on sys/capabilities (PERMISSION_DENIED otherwise). |
Capabilities |
map from each requested path to its capabilities (create, read, update, patch, delete, list, sudo, root or deny) |
Capabilities.allows(path, capability) |
deny → false; root → true; a path that was not requested → false; surrounding slashes of path are ignored |
client.withNamespace(ns) |
a client view that sends X-Vault-Namespace: <ns> on every request |
Check a policy before acting¶
import { Capability } from "@grow-codes/hashicorp-vault";
const path = "secret/data/app/db";
const caps = await client.sys.capabilitiesSelf([path, "sys/mounts"]);
if (caps.allows(path, Capability.Read)) {
const { data } = await client.kv().read("app/db");
}
console.log(caps[path]); // ["read", "update"]
// Another token (needs update on sys/capabilities):
const other = await client.sys.capabilities(appToken, path);
use grow_hashicorp_vault::capability;
let path = "secret/data/app/db";
let caps = client.sys().capabilities_self([path, "sys/mounts"]).await?;
if caps.allows(path, capability::READ) {
let secret = client.kv_v2().read("app/db", None).await?;
}
println!("{:?}", caps.of(path)); // ["read", "update"]
// Another token (needs update on sys/capabilities):
let other = client.sys().capabilities(app_token, [path]).await?;
path := "secret/data/app/db"
caps, err := client.Sys().CapabilitiesSelf(ctx, path, "sys/mounts")
if err != nil {
return err
}
if caps.Allows(path, vault.CapabilityRead) {
secret, err := client.KVv2("secret").Read(ctx, "app/db", nil)
// ...
}
fmt.Println(caps[path]) // [read update]
// Another token (needs update on sys/capabilities):
other, err := client.Sys().Capabilities(ctx, appToken, path)
import grow_hashicorp_vault as sdk
path = "secret/data/app/db"
caps = client.sys.capabilities_self([path, "sys/mounts"])
if caps.allows(path, sdk.CAPABILITY_READ):
secret = client.kv().read("app/db")
print(caps[path]) # ['read', 'update']
# Another token (needs update on sys/capabilities):
other = client.sys.capabilities(app_token, path)
String path = "secret/data/app/db";
Capabilities caps = client.sys().capabilitiesSelf(path, "sys/mounts");
if (caps.allows(path, Capabilities.READ)) {
KvSecret secret = client.kv().read("app/db");
}
System.out.println(caps.get(path)); // [read, update]
// Another token (needs update on sys/capabilities):
Capabilities other = client.sys().capabilities(appToken, path);
Namespace views (Vault Enterprise)¶
withNamespace(ns) returns a view of the client whose requests carry X-Vault-Namespace: <ns>.
- Surrounding whitespace and slashes are removed;
""(or"/") selects the root namespace (no header). A namespace that still contains whitespace is aCONFIGerror at once; calling it on a closed client is aVALIDATIONerror. - The view shares the connection pool. It starts with the parent's current token and then owns its
token: a login or
setTokenon the view does not change the parent, and the other way round. KV version detection, token renewers, managed leases and secret watchers are per view. - The parent is unchanged. Closing the view stops only its own background work; closing the parent also closes every view.
- A view can make further views (
team.withNamespace("team-a/child")replaces the namespace).
Vault Enterprise only
Vault Community Edition silently ignores X-Vault-Namespace and serves the root namespace, so a
view reads and writes the root namespace there and a wrong namespace is not detected. The
namespace setting (GROW_HASHICORP_VAULT_NAMESPACE, VAULT_NAMESPACE) applies the same header
to the whole client.