httk.core.project.anchor

The httk project anchor: the .httk-project directory and its metadata.

A project is to a campaign what a Git repository is to a source tree: a directory marked, at its root, by a small control directory that every command discovers by walking upward from wherever it is run. Here that directory is .httk-project and its manifest is project.json.

This module owns the anchor and nothing above it. It creates the control directory, reads and validates project.json, walks upward to discover the nearest project, and manages the project’s Ed25519 identity key and the trust anchors a signed manifest is later checked against. It creates no workflow workspace: that is an add-on a workflow installation layers on top of the anchor, so the anchor stays useful to a core-only installation.

The on-disk format — the format and format_version members, the key file names and modes, and the directory layout — is shared with httk-workflow so its manifests and doctor interoperate with core projects.

Attributes

PROJECT_DIRECTORY
PROJECT_FILE
PUBLIC_KEY_PREFIX

Functions

discover_project(→ pathlib.Path | None)	Find the nearest project root at or above start.
require_project(→ pathlib.Path)	Return the nearest project root, refusing when there is none.
read_project(→ dict[str, object])	Read and validate the project.json of the project rooted at root.
read_project_section(→ dict[str, object])	Return one named object member of project.json, empty when absent.
write_project_section(→ dict[str, object])	Store one named object member of project.json and return the metadata.
format_public_key(→ str)	Return the recorded representation of one raw Ed25519 public key.
parse_public_key(→ bytes)	Decode a recorded public key, accepting the bare base64 spelling too.
canonical_public_key(→ str)	Normalize any accepted public key spelling to the recorded one.
key_fingerprint(→ str)	Return the stable display fingerprint of one public key.
project_public_key_path(→ pathlib.Path)	Return where a project keeps its own signing key's public half.
read_public_key_file(→ str)	Read one *.pub file and return its recorded public key.
pinned_project_key(→ str | None)	Return the project's own pinned public key, or None when absent.
trusted_project_keys(→ tuple[str, Ellipsis])	Return every key metadata pins: the project's own and any adopted one.
pin_project_key(→ dict[str, object])	Adopt the project's current keys/project.pub as its trust anchor.
trust_project_key(→ dict[str, object])	Adopt one further public key as a trust anchor of this project.
initialize_project() → dict[str, object])	Initialize the project anchor: its metadata, its key, and its remotes dir.
import_v1_project(→ dict[str, object])	Create the project anchor from a legacy ht.project directory.

Module Contents

httk.core.project.anchor.PROJECT_DIRECTORY = '.httk-project'

httk.core.project.anchor.PROJECT_FILE = 'project.json'

httk.core.project.anchor.PUBLIC_KEY_PREFIX = 'ed25519:'

httk.core.project.anchor.discover_project(start: str | os.PathLike[str] | None = None) → pathlib.Path | None

Find the nearest project root at or above start.

httk.core.project.anchor.require_project(start: str | os.PathLike[str] | None = None) → pathlib.Path

Return the nearest project root, refusing when there is none.

httk.core.project.anchor.read_project(root: str | os.PathLike[str]) → dict[str, object]

Read and validate the project.json of the project rooted at root.

httk.core.project.anchor.read_project_section(root: str | os.PathLike[str], name: str) → dict[str, object]

Return one named object member of project.json, empty when absent.

A section is a top-level member of the project manifest that some layer above the anchor owns — the workflow workspace registry, a campaign map — and reads and writes as a whole. The anchor does not interpret the member; it only guarantees that what a caller stores under a name comes back as the object it was, and refuses a member that some other writer has left as a non-object so a caller never silently reads a scalar as a mapping.

httk.core.project.anchor.write_project_section(root: str | os.PathLike[str], name: str, value: collections.abc.Mapping[str, object]) → dict[str, object]

Store one named object member of project.json and return the metadata.

The write is an ordinary read-modify-write of the validated manifest, so the members the anchor owns are preserved untouched and only the named section is replaced. The section must be a mapping; the anchor stores its members verbatim without interpreting them.

httk.core.project.anchor.format_public_key(raw: bytes) → str

Return the recorded representation of one raw Ed25519 public key.

httk.core.project.anchor.parse_public_key(value: str) → bytes

Decode a recorded public key, accepting the bare base64 spelling too.

httk.core.project.anchor.canonical_public_key(value: str) → str

Normalize any accepted public key spelling to the recorded one.

httk.core.project.anchor.key_fingerprint(value: str) → str

Return the stable display fingerprint of one public key.

httk.core.project.anchor.project_public_key_path(root: str | os.PathLike[str]) → pathlib.Path

Return where a project keeps its own signing key’s public half.

httk.core.project.anchor.read_public_key_file(path: str | os.PathLike[str]) → str

Read one *.pub file and return its recorded public key.

httk.core.project.anchor.pinned_project_key(metadata: collections.abc.Mapping[str, object]) → str | None

Return the project’s own pinned public key, or None when absent.

httk.core.project.anchor.trusted_project_keys(metadata: collections.abc.Mapping[str, object]) → tuple[str, Ellipsis]

Return every key metadata pins: the project’s own and any adopted one.

The pinned key of project.json is the trust anchor a manifest is checked against. trusted_keys carries the additional anchors an operator has adopted deliberately — most often the legacy identities an imported httk v1 project signed its old manifests with.

httk.core.project.anchor.pin_project_key(root: str | os.PathLike[str] | None = None) → dict[str, object]

Adopt the project’s current keys/project.pub as its trust anchor.

Pinning is always an explicit act. Verification trusts the key recorded in project.json and never the key a manifest carries in its own header, so adopting the key that is in the tree right now is exactly the decision an operator has to make consciously for an older project that has no pin.

httk.core.project.anchor.trust_project_key(root: str | os.PathLike[str] | None, key: str) → dict[str, object]

Adopt one further public key as a trust anchor of this project.

httk.core.project.anchor.initialize_project(root: str | os.PathLike[str], *, name: str, description: str = '', default_queue: str | None = None, manifest_exclusions: collections.abc.Iterable[str] = ()) → dict[str, object]

Initialize the project anchor: its metadata, its key, and its remotes dir.

This creates only the anchor — .httk-project with project.json, the project’s Ed25519 signing key, and the remotes directory. It creates no workflow workspace; a workflow installation layers that on top of the anchor so that a core-only installation still has a working project.

httk.core.project.anchor.import_v1_project(root: str | os.PathLike[str], *, source: str | os.PathLike[str] | None = None, name: str | None = None) → dict[str, object]

Create the project anchor from a legacy ht.project directory.

Only the anchor is created: the project’s metadata and the adoption of the legacy identities its old manifests were signed with. A workflow installation adds the workspace and any queue import on top of this.