Key Value Store

Key Value (KV) storage interface for secure secret management.

This module provides a versioned key-value store for managing secrets and sensitive data with features like version control, soft-deletion, and check-and-set operations.

Use this when you need to: - Store and retrieve secrets (API keys, credentials, tokens) - Maintain version history of sensitive configuration - Implement atomic updates with optimistic locking (CAS) - Soft-delete and restore secrets without permanent data loss

Why use this: - Versioning: Track changes and rollback to previous secret versions - Safety: Soft-delete prevents accidental permanent data loss - Consistency: Check-and-set prevents concurrent modification conflicts - Abstraction: Unified interface across different secret backends (e.g., OpenBao)

BaseKeyValueStore

Bases: ABC

Abstract base class for Key Value (KV) implementations.

This interface defines the contract for KV implementations that handle key-value storage operations.

delete(path, *, versions) abstractmethod

Soft-delete secret versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to soft-delete.	required

Returns:

Type	Description
None	None

destroy(path, *, versions) abstractmethod

Permanently destroy secret versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to permanently destroy.	required

Returns:

Type	Description
None	None

list(path) abstractmethod

List child keys at a path.

Parameters:

Name	Type	Description	Default
path	str	The path to list keys from.	required

Returns:

Type	Description
list[str]	list[str]: List of key names at the given path.

patch(path, data, *, cas=None)

Merge keys into an existing secret and write a new version.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The data to merge into the existing secret.	required
cas	int | None	The version to write. Check the version available before writing.	None

Raises:

Type	Description
RequestException	If the secret cannot be patched.

read(path, *, options=None) abstractmethod

Read a secret.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
options	ReadOption | None	Read options including version. Defaults to None.	None

Returns:

Name	Type	Description
Secret	Secret	The secret data and metadata.

Raises:

Type	Description
RequestException	If the secret cannot be read.

undelete(path, *, versions) abstractmethod

Restore soft-deleted versions.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to restore.	required

Returns:

Type	Description
None	None

write(path, data, *, options=None) abstractmethod

Write a full secret snapshot.

This ALWAYS creates a new version. Partial updates must use patch().

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The secret data to write.	required
options	WriteOption | None	Write options including CAS. Defaults to None.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the secret cannot be written.

OpenBaoKeyValueStore(base_url, token, mount_point, namespace=None, timeout=30)

Bases: BaseKeyValueStore

OpenBao implementation of Key-Value storage.

This class provides KV v2 functionality using OpenBao's KV secrets engine for versioned key-value storage operations.

Attributes:

Name	Type	Description
base_url	str	The OpenBao server base URL.
token	str	The authentication token for OpenBao.
mount_point	str	The mount point for the KV v2 secrets engine.
namespace	str | None	The OpenBao namespace.
session	Session	The HTTP session for API calls.

Initialize the OpenBao KV client.

Parameters:

Name	Type	Description	Default
base_url	str	The OpenBao server base URL.	required
token	str	The authentication token for OpenBao.	required
mount_point	str	The mount point for KV v2 en`gine.	required
namespace	str | None	The OpenBao namespace. Defaults to None.	None
timeout	int	The timeout for API calls. Defaults to 30 seconds.	30

__repr__()

Return string representation with masked token.

Returns:

Name	Type	Description
str	str	String representation of the OpenBaoKeyValueStore instance.

delete(path, *, versions)

Soft-delete secret versions in OpenBao KV v2.

The versions can be undeleted later using undelete().

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to soft-delete.	required

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the versions cannot be deleted.

destroy(path, *, versions)

Permanently destroy secret versions in OpenBao KV v2.

This operation is irreversible.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to permanently destroy.	required

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the versions cannot be destroyed.

list(path)

List child keys at a path in OpenBao KV v2.

Parameters:

Name	Type	Description	Default
path	str	The path to list keys from.	required

Returns:

Type	Description
list[str]	list[str]: List of key names at the given path.

Raises:

Type	Description
RequestException	If the keys cannot be listed.

patch(path, data, *, options=None)

Merge keys into an existing secret and write a new version.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The data to merge into the existing secret.	required
options	WriteOptions | None	Write options including CAS. Defaults to None.	None

Raises:

Type	Description
RequestException	If the secret cannot be patched.

read(path, *, options=None)

Read a secret from OpenBao KV v2.

Retrieves the full secret at a given version (or latest if not specified).

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
options	ReadOptions | None	Read options including version. Defaults to None.	None

Returns:

Name	Type	Description
Secret	Secret	The secret data and metadata.

Raises:

Type	Description
RequestException	If the secret cannot be read.

undelete(path, *, versions)

Restore soft-deleted versions in OpenBao KV v2.

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
versions	Iterable[int]	The versions to restore.	required

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the versions cannot be undeleted.

write(path, data, *, options=None)

Write a full secret snapshot to OpenBao KV v2.

This ALWAYS creates a new version. For partial updates, use patch().

Parameters:

Name	Type	Description	Default
path	str	The path to the secret.	required
data	dict[str, str]	The secret data to write.	required
options	WriteOptions | None	Write options including CAS. Defaults to None.	None

Returns:

Type	Description
None	None

Raises:

Type	Description
RequestException	If the secret cannot be written.