httk.core.project.manifests

The deterministic, signed project manifest.

A manifest is a signed record of every file in a project tree at one moment: the same canonical, sorted record list a seal is built from, wrapped in a v2 JSONL.bz2 document with a domain-separated Ed25519 signature over its body. A manifest covers the whole tree minus what each member decides to leave out of its own internals, so payloads stay covered while working scratch does not.

Verification answers the two questions a signature always raises separately — does this manifest still describe this tree (the digests and signature) and was it made by a key this project pins (a trust anchor that never comes from the manifest itself).

Attributes

VALID_TRUSTED

VALID_UNKNOWN_KEY

INVALID

VERDICT_EXIT_CODES

DEFAULT_MANIFEST_EXCLUSIONS

Classes

ManifestVerification

What verifying one manifest against one tree established.

Functions

project_exclusions(metadata)

Return the default manifest exclusions plus the project's configured ones.

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.

verdict_for_key(public_key, trusted, *, manifest, ...)

Classify a verified signature against the trust anchors of a project.

verify_manifest([project, manifest, trusted_keys])

Verify a project's v2 manifest against the tree and its trust anchors.

Module Contents

httk.core.project.manifests.VALID_TRUSTED = 'valid_trusted'[source]
httk.core.project.manifests.VALID_UNKNOWN_KEY = 'valid_unknown_key'[source]
httk.core.project.manifests.INVALID = 'invalid'[source]
httk.core.project.manifests.VERDICT_EXIT_CODES[source]
httk.core.project.manifests.DEFAULT_MANIFEST_EXCLUSIONS[source]
httk.core.project.manifests.project_exclusions(metadata)[source]

Return the default manifest exclusions plus the project’s configured ones.

Parameters:

metadata (dict[str, object]) – Project metadata carrying the optional exclusion member.

Returns:

The exclusion patterns applied before members contribute their own.

Raises:

ValueError – If manifest_exclusions is not an array of strings.

Return type:

tuple[str, Ellipsis]

httk.core.project.manifests.create_manifest(project=None, *, output=None)[source]

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.core.project.manifests.ManifestVerification[source]

What verifying one manifest against one tree established.

A signature check answers two separate questions. 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.

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[source]
reason: str[source]
manifest: pathlib.Path[source]
manifest_format: str[source]
public_key: str | None = None[source]
trusted_keys: tuple[str, Ellipsis] = ()[source]
property valid: bool[source]

Whether the manifest describes this tree and its signature verified.

property trusted: bool[source]

Whether the verified signature was made by a pinned key.

property exit_code: int[source]

The command-line status this verdict reports.

as_mapping()[source]

Return the JSON representation of this verdict.

Returns:

JSON-compatible verification members.

Return type:

dict[str, object]

httk.core.project.manifests.resolve_trusted_keys(project=None, *, trusted_keys=None)[source]

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:
Returns:

Unique canonical trust-anchor values in stable order.

Raises:

ValueError – If an explicit key cannot be canonicalized.

Return type:

tuple[str, Ellipsis]

httk.core.project.manifests.verdict_for_key(public_key, trusted, *, manifest, manifest_format)[source]

Classify a verified signature against the trust anchors of a project.

Parameters:

  • public_key (str) – The recorded public key whose signature already verified.

  • trusted (collections.abc.Sequence[str]) – The project’s trust anchors.

  • manifest (pathlib.Path) – The manifest the verdict is about.

  • manifest_format (str) – The manifest format label carried into the verdict.

Returns:

The trusted or unknown-key verdict for the signer.

Return type:

ManifestVerification

httk.core.project.manifests.verify_manifest(project=None, *, manifest=None, trusted_keys=None)[source]

Verify a project’s v2 manifest against the tree and its trust anchors.

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

Parameters:
Returns:

The detailed verification verdict.

Raises:
Return type:

ManifestVerification