yera.creds.store

Secret storage contracts and durable identities.

Symbols

class CredentialGroupInfo — Non-sensitive information about one credential group.
class CredentialStoreBackend — Storage boundary for credential groups and their opaque secrets.
class SecretIdentity — Durable identity of one stored secret.
class SecretInfo — Non-sensitive information about one stored secret.
class SecretStore — Storage boundary for individual opaque secrets.
class SecretStoreCapabilities — Security and lifecycle capabilities exposed by a secret backend.
class SecretValue — Opaque serialized secret value.

CredentialGroupInfo

Non-sensitive information about one credential group.

Attributes

name
type: str

Mutable user-facing group name.

id
type: str

Stable owner identity retained when the group is renamed.

authorised_roots
type: tuple[str, ...]

Project roots authorized to use the group.

CredentialStoreBackend

Inherits: SecretStore
Subclasses: ProtectedFileSecretStore

Storage boundary for credential groups and their opaque secrets.

Methods

create_credential_group — Create and persist a credential group.
get_credential_group — Return one credential group's metadata.
list_credential_groups — List credential groups without exposing secret values.
rename_credential_group — Rename a credential group without changing its stable identity.
delete_credential_group — Delete a credential group and its owned secrets.
authorise_credential_group — Authorize a project root to use a credential group.
update_secrets — Apply multiple secret writes and deletions atomically.
export_credential_group — Serialize one credential group and all its owned secrets.

CredentialStoreBackend.create_credential_group

create_credential_group(
    name: str,
    authorised_roots: list[str],
) → CredentialGroupInfo

Create and persist a credential group.

Parameters

name
type: str

User-facing credential-group name.

authorised_roots
type: list[str]

Project roots initially authorized for the group.

Returns

type: CredentialGroupInfo

Non-sensitive metadata for the created group.

CredentialStoreBackend.get_credential_group

get_credential_group(
    name: str,
) → CredentialGroupInfo

Return one credential group's metadata.

Parameters

name
type: str

User-facing credential-group name.

Returns

type: CredentialGroupInfo

Non-sensitive metadata for the requested group.

CredentialStoreBackend.list_credential_groups

list_credential_groups() → tuple[CredentialGroupInfo, ...]

List credential groups without exposing secret values.

Returns

type: tuple[CredentialGroupInfo, ...]

Credential-group metadata ordered by name.

CredentialStoreBackend.rename_credential_group

rename_credential_group(
    old_name: str,
    new_name: str,
) → CredentialGroupInfo

Rename a credential group without changing its stable identity.

Parameters

old_name
type: str

Existing user-facing group name.

new_name
type: str

Replacement user-facing group name.

Returns

type: CredentialGroupInfo

Metadata for the renamed group.

CredentialStoreBackend.delete_credential_group

delete_credential_group(
    name: str,
) → int

Delete a credential group and its owned secrets.

Parameters

name
type: str

User-facing credential-group name.

Returns

type: int

Number of associated secrets deleted.

CredentialStoreBackend.authorise_credential_group

authorise_credential_group(
    name: str,
    project_root: Path,
) → CredentialGroupInfo

Authorize a project root to use a credential group.

Parameters

name
type: str

User-facing credential-group name.

project_root
type: Path

Project root to authorize.

Returns

type: CredentialGroupInfo

Updated non-sensitive group metadata.

CredentialStoreBackend.update_secrets

update_secrets(
    values: Mapping[SecretIdentity, SecretValue],
    delete: Collection[SecretIdentity] = (),
) → tuple[SecretInfo, ...]

Apply multiple secret writes and deletions atomically.

Parameters

values
type: Mapping[SecretIdentity, SecretValue]

Secret values to create or replace.

delete
type: Collection[SecretIdentity] = ()

Secret identities to remove before applying writes.

Returns

type: tuple[SecretInfo, ...]

Metadata for the created or replaced secrets.

CredentialStoreBackend.export_credential_group

export_credential_group(
    name: str,
) → bytes

Serialize one credential group and all its owned secrets.

Parameters

name
type: str

User-facing credential-group name.

Returns

type: bytes

A portable version-two credential-store document containing only the requested group and its secrets.

SecretIdentity

Durable identity of one stored secret.

Attributes

namespace
type: str

Secret category kept separate from other consumers.

owner_id
type: str

Stable identifier of the owning group or connection.

name
type: str

Secret name within the owner.

account_id
type: str | None

Optional stable account identity.

SecretInfo

Non-sensitive information about one stored secret.

Attributes

identity
type: SecretIdentity

Durable identity of the stored secret.

created_at
type: datetime

Time at which the secret was first stored.

updated_at
type: datetime

Time at which the secret was last replaced.

SecretStore

Inherits: ABC
Subclasses: CredentialStoreBackend, InMemorySecretStore

Storage boundary for individual opaque secrets.

Methods

get — Return one secret value.
set — Create or replace one secret.
compare_and_set — Replace one secret when its current state matches expectations.
delete — Delete one secret.
exists — Return whether one secret exists.
list_info — List non-sensitive information about matching secrets.

SecretStore.get

get(
    identity: SecretIdentity,
) → SecretValue

Return one secret value.

Parameters

identity
type: SecretIdentity

Durable identity of the requested secret.

Returns

type: SecretValue

The opaque serialized secret value.

SecretStore.set

set(
    identity: SecretIdentity,
    value: SecretValue,
) → SecretInfo

Create or replace one secret.

Parameters

identity
type: SecretIdentity

Durable identity of the secret.

value
type: SecretValue

Opaque serialized value to store.

Returns

type: SecretInfo

Non-sensitive information about the stored secret.

SecretStore.compare_and_set

compare_and_set(
    identity: SecretIdentity,
    expected_updated_at: datetime | None,
    value: SecretValue,
) → SecretInfo

Replace one secret when its current state matches expectations.

Parameters

identity
type: SecretIdentity

Durable identity of the secret.

expected_updated_at
type: datetime | None

Expected update time, or None when the secret is expected not to exist.

value
type: SecretValue

Opaque serialized replacement value.

Returns

type: SecretInfo

Non-sensitive information about the stored secret.

SecretStore.delete

delete(
    identity: SecretIdentity,
) → None

Delete one secret.

Parameters

identity
type: SecretIdentity

Durable identity of the secret to delete.

SecretStore.exists

exists(
    identity: SecretIdentity,
) → bool

Return whether one secret exists.

Parameters

identity
type: SecretIdentity

Durable identity to test.

Returns

type: bool

Whether the secret exists.

SecretStore.list_info

list_info(
    namespace: str | None = None,
    owner_id: str | None = None,
) → tuple[SecretInfo, ...]

List non-sensitive information about matching secrets.

Parameters

namespace
type: str | None = None

Optional namespace filter.

owner_id
type: str | None = None

Optional owning identifier filter.

Returns

type: tuple[SecretInfo, ...]

Matching secret information without values.

SecretStoreCapabilities

Security and lifecycle capabilities exposed by a secret backend.

Attributes

protected_at_rest
type: bool

Whether the backend restricts stored data from unrelated local users.

encrypted_at_rest
type: bool

Whether secret values are encrypted while persisted.

requires_unlock
type: bool

Whether the backend requires an unlock operation.

supports_atomic_update
type: bool

Whether mutations replace values atomically.

SecretValue

Opaque serialized secret value.

Methods

__repr__ — Return a redacted developer representation.
__str__ — Return a redacted user-facing representation.

SecretValue.__repr__

__repr__() → str

Return a redacted developer representation.

SecretValue.__str__

__str__() → str

Return a redacted user-facing representation.