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	Recorded holder of one workspace maintenance lock.
ManifestVerification	What verifying one manifest against one tree established.

Functions

read_maintenance_lock(→ MaintenanceLock | None)	Describe the workspace maintenance lock, or None when it is absent.
release_maintenance_lock(→ str)	Remove a stale, or with force any, maintenance lock and report it.
workspace_maintenance_guard(...)	Fence manager launches while a project snapshot is inspected.
create_manifest(→ pathlib.Path)	Create and atomically publish the signed v2 project manifest.
resolve_trusted_keys(→ tuple[str, Ellipsis])	Return the trust anchors of project plus every explicitly named key.
verify_v2_manifest(→ bool)	Report whether a v2 manifest describes root and its signature verifies.
verify_legacy_manifest(→ bool)	Verify a legacy manifest without modifying its project tree.
verify_manifest(→ ManifestVerification)	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

Recorded holder of one workspace maintenance lock.

path: pathlib.Path

pid: int | None

hostname: str | None

created: str | None

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: float = MAINTENANCE_LOCK_MAX_AGE_SECONDS) → bool

Whether the lock can be reclaimed without operator confirmation.

describe() → str

Describe the holder for an operator diagnostic.

httk.workflow.manifests.read_maintenance_lock(workspace: httk.workflow.workspace.Workspace) → MaintenanceLock | None

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

httk.workflow.manifests.release_maintenance_lock(workspace: httk.workflow.workspace.Workspace, *, force: bool = False) → str

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

httk.workflow.manifests.workspace_maintenance_guard(workspace: httk.workflow.workspace.Workspace) → collections.abc.Iterator[None]

Fence manager launches while a project snapshot is inspected.

httk.workflow.manifests.create_manifest(project: str | os.PathLike[str] | None = None, *, output: str | os.PathLike[str] | None = None) → pathlib.Path

Create and atomically publish the signed v2 project manifest.

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.

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() → dict[str, object]

Return the JSON representation of this verdict.

httk.workflow.manifests.resolve_trusted_keys(project: str | os.PathLike[str] | None = None, *, trusted_keys: collections.abc.Sequence[str | os.PathLike[str]] | None = None) → tuple[str, Ellipsis]

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.

httk.workflow.manifests.verify_v2_manifest(root: pathlib.Path, path: pathlib.Path) → bool

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.

httk.workflow.manifests.verify_legacy_manifest(root: pathlib.Path, path: pathlib.Path) → bool

Verify a legacy manifest without modifying its project tree.

httk.workflow.manifests.verify_manifest(project: str | os.PathLike[str] | None = None, *, manifest: str | os.PathLike[str] | None = None, trusted_keys: collections.abc.Sequence[str | os.PathLike[str]] | None = None) → ManifestVerification

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.