httk.workflow.manifests

Deterministic signed project manifests.

Attributes

MAINTENANCE_LOCK_FILE
MAINTENANCE_LOCK_MAX_AGE_SECONDS
VALID_TRUSTED
VALID_UNKNOWN_KEY
INVALID
VERDICT_EXIT_CODES

Classes

MaintenanceLock	Record the holder of one workspace maintenance lock.
ManifestVerification	What verifying one manifest against one tree established.

Functions

read_maintenance_lock(workspace)	Describe the workspace maintenance lock, or None when it is absent.
release_maintenance_lock(workspace, *[, force])	Remove a stale, or with force any, maintenance lock and report it.
workspace_maintenance_guard(workspace)	Fence manager launches while a project snapshot is inspected.
create_manifest([project, output])	Create and atomically publish the signed v2 project manifest.
resolve_trusted_keys([project, trusted_keys])	Return the trust anchors of project plus every explicitly named key.
verify_v2_manifest(root, path)	Report whether a v2 manifest describes root and its signature verifies.
verify_legacy_manifest(root, path)	Verify a legacy manifest without modifying its project tree.
verify_manifest([project, manifest, trusted_keys])	Auto-detect a v2 or legacy manifest and verify it against its trust anchors.

Module Contents

httk.workflow.manifests.MAINTENANCE_LOCK_FILE = 'maintenance.lock'

httk.workflow.manifests.MAINTENANCE_LOCK_MAX_AGE_SECONDS = 86400

httk.workflow.manifests.VALID_TRUSTED = 'valid_trusted'

httk.workflow.manifests.VALID_UNKNOWN_KEY = 'valid_unknown_key'

httk.workflow.manifests.INVALID = 'invalid'

httk.workflow.manifests.VERDICT_EXIT_CODES

class httk.workflow.manifests.MaintenanceLock

Record the holder of one workspace maintenance lock.

Parameters:

• path – Locate the lock file.

• pid – Record the holder process identifier, when readable.

• hostname – Record the holder host, when readable.

• created – Record the holder creation timestamp, when readable.

• readable – Mark whether the lock contents could be read.

path: pathlib.Path

pid: int | None

hostname: str | None

created: str | None

readable: bool = True

property age_seconds: float | None

Age of the lock, or None when its timestamp is unusable.

property local: bool

Whether the recorded host is the host inspecting the lock.

property dead: bool

Whether a same-host holder process is known to be gone.

is_stale(*, max_age_seconds=MAINTENANCE_LOCK_MAX_AGE_SECONDS)

Whether the lock can be reclaimed without operator confirmation.

describe()

Describe the holder for an operator diagnostic.

httk.workflow.manifests.read_maintenance_lock(workspace)

Describe the workspace maintenance lock, or None when it is absent.

Parameters:

workspace (httk.workflow.workspace.Workspace) – Locate the workspace whose lock to inspect.

Returns:

The recorded lock, or None when no lock exists.

Return type:

MaintenanceLock | None

httk.workflow.manifests.release_maintenance_lock(workspace, *, force=False)

Remove a stale, or with force any, maintenance lock and report it.

Parameters:

• workspace (httk.workflow.workspace.Workspace) – Locate the workspace whose lock to remove.

• force (bool) – Permit removal of a lock that does not appear stale.

Returns:

A human-readable removal result.

Raises:

ValueError – If a live lock is protected by the default policy.

Return type:

str

httk.workflow.manifests.workspace_maintenance_guard(workspace)

Fence manager launches while a project snapshot is inspected.

Parameters:

workspace (httk.workflow.workspace.Workspace) – Lock and inspect this workspace around the guarded work.

Returns:

A context manager that holds the maintenance lock.

Raises:

ValueError – If the workspace is already maintained or not quiescent.

Return type:

collections.abc.Iterator[None]

httk.workflow.manifests.create_manifest(project=None, *, output=None)

Create and atomically publish the signed v2 project manifest.

Parameters:

• project (str | os.PathLike[str] | None) – Locate the project to snapshot, or use discovery when unset.

• output (str | os.PathLike[str] | None) – Publish the manifest at this path, or use the project default.

Returns:

The published manifest path.

Raises:

ValueError – If the project is invalid or cannot be snapshotted.

Return type:

pathlib.Path

class httk.workflow.manifests.ManifestVerification

What verifying one manifest against one tree established.

A signature check answers two separate questions, and reporting them as one boolean loses the interesting one. Does this manifest describe this tree, unaltered? is answered by the digests and the signature. Was it made by somebody this project trusts? is answered only by comparing the signing key with a trust anchor that did not come from the manifest itself.

Parameters:

• verdict – Classify the verification result.

• reason – Explain the classification.

• manifest – Identify the verified manifest.

• manifest_format – Identify the manifest format used.

• public_key – Record the signing key, when readable.

• trusted_keys – Record the trust anchors consulted.

verdict: str

reason: str

manifest: pathlib.Path

manifest_format: str

public_key: str | None = None

trusted_keys: tuple[str, Ellipsis] = ()

property valid: bool

Whether the manifest describes this tree and its signature verified.

property trusted: bool

Whether the verified signature was made by a pinned key.

property exit_code: int

The command-line status this verdict reports.

as_mapping()

Return the JSON representation of this verdict.

httk.workflow.manifests.resolve_trusted_keys(project=None, *, trusted_keys=None)

Return the trust anchors of project plus every explicitly named key.

An entry of trusted_keys is either a recorded key — ed25519:BASE64 or the bare base64 — or the path of a *.pub file holding one.

Parameters:

• project (str | os.PathLike[str] | None) – Locate the project whose pinned keys to include.

• trusted_keys (collections.abc.Sequence[str | os.PathLike[str]] | None) – Add explicit recorded keys or public-key files.

Returns:

Unique canonical trust-anchor values in stable order.

Raises:

ValueError – If an explicit key cannot be canonicalized.

Return type:

tuple[str, Ellipsis]

httk.workflow.manifests.verify_v2_manifest(root, path)

Report whether a v2 manifest describes root and its signature verifies.

This deliberately says nothing about whose key signed it: the key comes out of the manifest header. Use verify_manifest() for the trust decision.

Parameters:

• root (pathlib.Path) – Locate the tree the manifest should describe.

• path (pathlib.Path) – Locate the v2 manifest to verify.

Returns:

Whether the tree and signature verify, without a trust decision.

Return type:

bool

httk.workflow.manifests.verify_legacy_manifest(root, path)

Verify a legacy manifest without modifying its project tree.

Parameters:

• root (pathlib.Path) – Locate the tree the manifest should describe.

• path (pathlib.Path) – Locate the legacy manifest to verify.

Returns:

Whether the legacy tree records and signature verify.

Return type:

bool

httk.workflow.manifests.verify_manifest(project=None, *, manifest=None, trusted_keys=None)

Auto-detect a v2 or legacy manifest and verify it against its trust anchors.

The trust anchor is the key pinned in project.json — never the key the manifest being verified names in its own header — plus any key passed in trusted_keys, as a recorded value or as the path of a *.pub file.

Parameters:

• project (str | os.PathLike[str] | None) – Locate the project to discover and verify.

• manifest (str | os.PathLike[str] | None) – Select a manifest path instead of the project default.

• trusted_keys (collections.abc.Sequence[str | os.PathLike[str]] | None) – Add explicit trust anchors to the project keys.

Returns:

The detailed verification verdict.

Raises:

ValueError – If no project or usable manifest exists.

Return type:

ManifestVerification