yera.creds.backends.protected_file

Protected file secret-store backend.

Symbols

class ProtectedFileSecretStore — Persist opaque secrets in an atomically replaced protected file.

ProtectedFileSecretStore

Inherits: CredentialStoreBackend

Persist opaque secrets in an atomically replaced protected file.

Methods

get — Return one stored secret.
set — Create or replace one secret.
compare_and_set — Conditionally create or replace one secret.
delete — Delete one secret.
exists — Return whether one secret exists.
list_info — List non-sensitive information about matching secrets.
create_credential_group — Create and persist a credential group.
list_credential_groups — List credential groups without exposing secret values.
get_credential_group — Return one credential group's non-sensitive metadata.
rename_credential_group — Rename a credential group while retaining its stable identity.
delete_credential_group — Delete a credential group and every secret it owns.
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.

ProtectedFileSecretStore.get

get(
    identity: SecretIdentity,
) → SecretValue

Return one stored secret.

Parameters

identity
type: SecretIdentity

Durable identity of the requested secret.

Returns

type: SecretValue

The opaque stored value.

Raises

SecretNotFoundError

If the secret does not exist.

ProtectedFileSecretStore.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.

ProtectedFileSecretStore.compare_and_set

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

Conditionally create or replace one secret.

Parameters

identity
type: SecretIdentity

Durable identity of the secret.

expected_updated_at
type: datetime | None

Expected update time, or None when absent.

value
type: SecretValue

Opaque serialized replacement value.

Returns

type: SecretInfo

Non-sensitive information about the stored secret.

Raises

SecretConflictError

If current state differs from the expectation.

ProtectedFileSecretStore.delete

delete(
    identity: SecretIdentity,
) → None

Delete one secret.

Parameters

identity
type: SecretIdentity

Durable identity of the secret.

Raises

SecretNotFoundError

If the secret does not exist.

ProtectedFileSecretStore.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.

ProtectedFileSecretStore.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 metadata in stable identity order.

ProtectedFileSecretStore.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.

Raises

CredentialGroupAlreadyExistsError

If the name is already in use.

CredentialGroupNameError

If the name is invalid.

ProtectedFileSecretStore.list_credential_groups

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

List credential groups without exposing secret values.

Returns

type: tuple[CredentialGroupInfo, ...]

Credential-group metadata ordered by group name.

ProtectedFileSecretStore.get_credential_group

get_credential_group(
    name: str,
) → CredentialGroupInfo

Return one credential group's non-sensitive metadata.

Parameters

name
type: str

User-facing credential-group name.

Returns

type: CredentialGroupInfo

Metadata for the requested group.

Raises

CredentialGroupNotFoundError

If the group does not exist.

ProtectedFileSecretStore.rename_credential_group

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

Rename a credential group while retaining 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.

Raises

CredentialGroupNotFoundError

If the source group does not exist.

CredentialGroupAlreadyExistsError

If the target name is already used.

CredentialGroupNameError

If the target name is invalid.

ProtectedFileSecretStore.delete_credential_group

delete_credential_group(
    name: str,
) → int

Delete a credential group and every secret it owns.

Parameters

name
type: str

User-facing credential-group name.

Returns

type: int

Number of associated secrets deleted with the group.

Raises

CredentialGroupNotFoundError

If the group does not exist.

ProtectedFileSecretStore.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 credential-group metadata.

Raises

CredentialGroupNotFoundError

If the group does not exist.

ProtectedFileSecretStore.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.

ProtectedFileSecretStore.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.

Raises

CredentialGroupNotFoundError

If the group does not exist.