httk.workflow.configuration

Manage XDG configuration and identity for workflow commands.

The per-user configuration and data directory functions are provided by httk.core.userdirs and re-exported here for workflow callers.

Attributes

CONFIG_FORMAT
CONFIG_FORMAT_VERSION
IDENTITY_SIGNATURE_DOMAIN
IDENTITY_KEY_MEMBER
IDENTITY_SIGNATURE_MEMBER
CONFIG_KEYS

Classes

ConfigKey	Describe one member the user configuration is allowed to carry.
DocumentSignature	Report what checking one document's optional identity signature established.

Functions

settable_config_keys()	Return the configuration keys config set accepts, in order.
adopt_legacy_data_home()	Adopt whatever an earlier release left in the data home, once.
remotes_home()	Return where this user's remote definitions live.
keys_home()	Return where this user's identity keys live.
config_path()	Return the path of this user's configuration file.
read_config()	Read the user configuration, returning an empty mapping if absent.
machine_names()	Return the configured names by which this machine is addressed.
write_config(values)	Write a versioned user configuration.
set_config_key(key, value)	Set one registered configuration key and return the written path.
unset_config_key(key)	Remove one registered configuration key and return the written path.
initialize_config(*, name, email)	Create or update the user identity and ensure a signing key exists.
identity_key_paths()	Return the paths of the local identity seed and public key.
ensure_identity_key()	Create the user's standard Ed25519 identity key if it is absent.
identity_seed()	Return the local identity seed, or None when no key was created.
identity_public_key()	Return the recorded local identity public key, or None.
signature_digest(document)	Return the domain-separated digest one identity signature covers.
sign_document(document)	Return document with a detached identity signature, when one is possible.
verify_document(document)	Check the optional identity signature of document.
import_v1_configuration([source])	Import safe metadata and public identity from a legacy ~/.httk tree.

Module Contents

httk.workflow.configuration.CONFIG_FORMAT = 'httk-config'

httk.workflow.configuration.CONFIG_FORMAT_VERSION = 1

httk.workflow.configuration.IDENTITY_SIGNATURE_DOMAIN = b'httk-workflow-identity-v1\x00'

httk.workflow.configuration.IDENTITY_KEY_MEMBER = 'operator_key'

httk.workflow.configuration.IDENTITY_SIGNATURE_MEMBER = 'signature'

class httk.workflow.configuration.ConfigKey

Describe one member the user configuration is allowed to carry.

Parameters:

• name – Configuration member name.

• description – Human-readable explanation shown to operators.

• settable – Whether config set may change the member.

name: str

description: str

settable: bool = True

httk.workflow.configuration.CONFIG_KEYS: collections.abc.Mapping[str, ConfigKey]

httk.workflow.configuration.settable_config_keys()

Return the configuration keys config set accepts, in order.

Returns:

Settable configuration member names.

Return type:

tuple[str, Ellipsis]

httk.workflow.configuration.adopt_legacy_data_home()

Adopt whatever an earlier release left in the data home, once.

Returns:

None.

Return type:

None

httk.workflow.configuration.remotes_home()

Return where this user’s remote definitions live.

Returns:

Per-user remote definition directory.

Return type:

pathlib.Path

httk.workflow.configuration.keys_home()

Return where this user’s identity keys live.

Returns:

Per-user identity key directory.

Return type:

pathlib.Path

httk.workflow.configuration.config_path()

Return the path of this user’s configuration file.

Returns:

User configuration path.

Return type:

pathlib.Path

httk.workflow.configuration.read_config()

Read the user configuration, returning an empty mapping if absent.

A document of an unrecognized format is refused by name rather than read as if its members meant what this implementation means by them. A document with no version at all predates versioning and is accepted as legacy, because that is what every configuration written before this check looks like.

Returns:

Configuration members, or an empty mapping when no file exists.

Raises:

ValueError – If the file is not a supported configuration document.

Return type:

dict[str, object]

httk.workflow.configuration.machine_names()

Return the configured names by which this machine is addressed.

Returns:

Names configured for this machine.

Raises:

ValueError – If machine_names is not a valid comma-separated value.

Return type:

frozenset[str]

httk.workflow.configuration.write_config(values)

Write a versioned user configuration.

Parameters:

values (collections.abc.Mapping[str, object]) – Configuration members to write.

Returns:

Path of the written configuration file.

Return type:

pathlib.Path

httk.workflow.configuration.set_config_key(key, value)

Set one registered configuration key and return the written path.

Parameters:

• key (str) – Settable configuration member name.

• value (str) – New member value.

Returns:

Path of the written configuration file.

Raises:

ValueError – If the key is not settable or its value is invalid.

Return type:

pathlib.Path

httk.workflow.configuration.unset_config_key(key)

Remove one registered configuration key and return the written path.

Parameters:

key (str) – Settable configuration member name.

Returns:

Path of the written configuration file.

Raises:

ValueError – If the key is not settable or is not configured.

Return type:

pathlib.Path

httk.workflow.configuration.initialize_config(*, name, email)

Create or update the user identity and ensure a signing key exists.

Parameters:

• name (str) – Operator name to record in the configuration.

• email (str) – Operator email address to record in the configuration.

Returns:

The resulting configuration members.

Return type:

dict[str, object]

httk.workflow.configuration.identity_key_paths()

Return the paths of the local identity seed and public key.

Returns:

Seed path followed by public-key path.

Return type:

tuple[pathlib.Path, pathlib.Path]

httk.workflow.configuration.ensure_identity_key()

Create the user’s standard Ed25519 identity key if it is absent.

Returns:

Seed path followed by public-key path.

Raises:

ValueError – If an existing seed is not a standard Ed25519 seed.

Return type:

tuple[pathlib.Path, pathlib.Path]

httk.workflow.configuration.identity_seed()

Return the local identity seed, or None when no key was created.

Nothing here creates a key. An installation that never ran config init simply has no identity, and every caller treats that as unsigned rather than as an error, which is what keeps a mixed deployment working.

Returns:

The local seed, or no value when no valid key exists.

Return type:

bytes | None

httk.workflow.configuration.identity_public_key()

Return the recorded local identity public key, or None.

Returns:

Encoded public key, or None when no identity exists.

Return type:

str | None

httk.workflow.configuration.signature_digest(document)

Return the domain-separated digest one identity signature covers.

The digest covers the whole document except the signature itself, in the same canonical JSON every other httk document is hashed as, so the signing key and the signed members travel together and neither can be swapped.

Parameters:

document (collections.abc.Mapping[str, object]) – Document whose detached signature is being calculated.

Returns:

Domain-separated digest of the unsigned document.

Return type:

bytes

httk.workflow.configuration.sign_document(document)

Return document with a detached identity signature, when one is possible.

Signing is optional by construction: a caller with no identity key returns the document unchanged, and a verifier accepts an unsigned document. The signature is attribution — it says which identity published this — and never authorization: nothing is permitted because a document is signed.

Parameters:

document (collections.abc.Mapping[str, object]) – Document to copy and optionally sign.

Returns:

Document with identity members when a local key exists.

Return type:

dict[str, object]

class httk.workflow.configuration.DocumentSignature

Report what checking one document’s optional identity signature established.

Parameters:

• present – Whether the document carried a signature block.

• valid – Whether the carried signature verified.

• operator_key – Encoded key from the signature, when present.

• reason – Explanation when the signature is absent or invalid.

present: bool

valid: bool

operator_key: str | None = None

reason: str | None = None

httk.workflow.configuration.verify_document(document)

Check the optional identity signature of document.

An absent signature is reported as absent rather than as a failure, so a document published by an installation without an identity key stays usable. A signature that is present and does not verify is a failure: it is either damaged or forged, and neither is something to act on.

Parameters:

document (collections.abc.Mapping[str, object]) – Document whose optional signature is checked.

Returns:

Signature presence and verification result.

Return type:

DocumentSignature

httk.workflow.configuration.import_v1_configuration(source=None)

Import safe metadata and public identity from a legacy ~/.httk tree.

Legacy 64-byte private material is deliberately left untouched.

Parameters:

source (str | os.PathLike[str] | None) – Legacy configuration root, or the default legacy home.

Returns:

Imported configuration members.

Raises:

FileNotFoundError – If the legacy configuration file is absent.

Return type:

dict[str, object]