techtree 0.1.0__py3-none-any.whl

techtree/publication/keccak.py

@@ -0,0 +1,183 @@
+"""Keccak-256, because EIP-55 is defined over it and nothing here provides it.
+
+This module exists for one reason and has one caller. The mixed-case spelling
+of an Ethereum address is a checksum, and the checksum is the original Keccak
+submission rather than the NIST standard that came out of it. The two differ by
+one byte of padding and produce entirely different digests, so ``hashlib``'s
+``sha3_256`` cannot be used and quietly produces a checksum that is wrong for
+every address. ``cryptography`` exposes SHA-3 and SHAKE and does not expose
+Keccak either.
+
+The alternative to sixty lines here is a third-party dependency in a package
+whose dependency list is deliberately eight entries long, pulled in so that a
+forty-character string can be checked before it is sent. That trade is not
+worth making, and the permutation is fixed for ever: Keccak-f[1600] has not
+changed since 2011 and cannot, because the digests it produces are what
+everything already published is addressed by.
+
+So this is a plain transcription of the permutation, and it is held to the
+published vectors in ``tests/unit/test_contributor_address.py`` rather than to
+a reading of the code.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = ["keccak256"]
+
+#: Keccak-f[1600] operates on twenty-five 64-bit lanes.
+_LANE_BITS: Final = 64
+_LANE_MASK: Final = (1 << _LANE_BITS) - 1
+_LANE_BYTES: Final = _LANE_BITS // 8
+
+#: The sponge rate for a 256-bit digest: 1600 bits of state less twice the
+#: capacity, in bytes.
+_RATE_BYTES: Final = (1600 - 2 * 256) // 8
+
+_DIGEST_BYTES: Final = 32
+
+#: The domain separator Keccak pads with. SHA-3 pads with ``0x06`` instead, and
+#: that single byte is the whole of the difference between this function and
+#: ``hashlib.sha3_256``.
+_PAD_BYTE: Final = 0x01
+_PAD_FINAL_BIT: Final = 0x80
+
+#: Rotation offsets, indexed ``[x][y]``.
+_ROTATIONS: Final[tuple[tuple[int, ...], ...]] = (
+    (0, 36, 3, 41, 18),
+    (1, 44, 10, 45, 2),
+    (62, 6, 43, 15, 61),
+    (28, 55, 25, 21, 56),
+    (27, 20, 39, 8, 14),
+)
+
+_ROUND_CONSTANTS: Final[tuple[int, ...]] = (
+    0x0000000000000001,
+    0x0000000000008082,
+    0x800000000000808A,
+    0x8000000080008000,
+    0x000000000000808B,
+    0x0000000080000001,
+    0x8000000080008081,
+    0x8000000000008009,
+    0x000000000000008A,
+    0x0000000000000088,
+    0x0000000080008009,
+    0x000000008000000A,
+    0x000000008000808B,
+    0x800000000000008B,
+    0x8000000000008089,
+    0x8000000000008003,
+    0x8000000000008002,
+    0x8000000000000080,
+    0x000000000000800A,
+    0x800000008000000A,
+    0x8000000080008081,
+    0x8000000000008080,
+    0x0000000080000001,
+    0x8000000080008008,
+)
+
+type _State = list[list[int]]
+
+
+def keccak256(data: bytes) -> bytes:
+    """Return the Keccak-256 digest of ``data``.
+
+    This is the pre-standardisation Keccak that Ethereum addresses, not
+    SHA3-256.
+    """
+    state: _State = [[0] * 5 for _ in range(5)]
+    for block in _blocks(data):
+        _absorb(state, block)
+        _permute(state)
+    return _squeeze(state)
+
+
+def _blocks(data: bytes) -> list[bytes]:
+    """Return the padded message as whole rate-sized blocks.
+
+    Keccak's ``pad10*1``: a one bit, as many zero bits as it takes, and a final
+    one bit. Written here in the byte order the lanes are read in, which is why
+    the two one bits are the low bit of the first pad byte and the high bit of
+    the last.
+    """
+    padded = bytearray(data)
+    padded.append(_PAD_BYTE)
+    while len(padded) % _RATE_BYTES != 0:
+        padded.append(0)
+    padded[-1] |= _PAD_FINAL_BIT
+    return [
+        bytes(padded[start : start + _RATE_BYTES])
+        for start in range(0, len(padded), _RATE_BYTES)
+    ]
+
+
+def _absorb(state: _State, block: bytes) -> None:
+    """Exclusive-or one block into the rate portion of the state."""
+    for position in range(_RATE_BYTES // _LANE_BYTES):
+        lane = int.from_bytes(
+            block[position * _LANE_BYTES : (position + 1) * _LANE_BYTES],
+            "little",
+        )
+        state[position % 5][position // 5] ^= lane
+
+
+def _squeeze(state: _State) -> bytes:
+    """Return the first 32 bytes of the state, in lane order.
+
+    A 256-bit digest is shorter than the rate, so the sponge never squeezes
+    twice and there is no second permutation to perform here.
+    """
+    out = bytearray()
+    position = 0
+    while len(out) < _DIGEST_BYTES:
+        out += state[position % 5][position // 5].to_bytes(_LANE_BYTES, "little")
+        position += 1
+    return bytes(out[:_DIGEST_BYTES])
+
+
+def _permute(state: _State) -> None:
+    """Apply the twenty-four rounds of Keccak-f[1600] in place."""
+    for constant in _ROUND_CONSTANTS:
+        _theta(state)
+        state[:] = _rho_and_pi(state)
+        _chi(state)
+        state[0][0] ^= constant
+
+
+def _theta(state: _State) -> None:
+    columns = [
+        state[x][0] ^ state[x][1] ^ state[x][2] ^ state[x][3] ^ state[x][4]
+        for x in range(5)
+    ]
+    parities = [
+        columns[(x - 1) % 5] ^ _rotate(columns[(x + 1) % 5], 1) for x in range(5)
+    ]
+    for x in range(5):
+        for y in range(5):
+            state[x][y] ^= parities[x]
+
+
+def _rho_and_pi(state: _State) -> _State:
+    moved: _State = [[0] * 5 for _ in range(5)]
+    for x in range(5):
+        for y in range(5):
+            moved[y][(2 * x + 3 * y) % 5] = _rotate(state[x][y], _ROTATIONS[x][y])
+    return moved
+
+
+def _chi(state: _State) -> None:
+    previous = [list(column) for column in state]
+    for x in range(5):
+        for y in range(5):
+            state[x][y] = previous[x][y] ^ (
+                (~previous[(x + 1) % 5][y] & _LANE_MASK) & previous[(x + 2) % 5][y]
+            )
+
+
+def _rotate(lane: int, places: int) -> int:
+    """Return one 64-bit lane rotated left."""
+    places %= _LANE_BITS
+    return ((lane << places) | (lane >> (_LANE_BITS - places))) & _LANE_MASK

techtree/publication/models.py

@@ -0,0 +1,209 @@
+"""What is sent, and what comes back. Decisions document 0038.
+
+Four documents cross the one boundary this package opens, and they are separate
+objects because they are made by different parties and prove different things.
+
+A :class:`PublicationSubmission` is what the participant sends: the proof
+directory, file by file, exactly as it sits on disk. Nothing is summarised,
+nothing is re-derived, and nothing is added — the bundle already commits to
+every one of those files by digest under the participant's own signature, so
+sending anything but the stored bytes would be sending something nobody signed.
+It carries no episodes and no transcripts, because the proof directory holds
+none: an episode receipt carries digests, task hashes and scores, and the raw
+episodes live outside the directory entirely.
+
+The submission is a mapping of path to bytes and it has exactly four members,
+which decisions 0038's wire contract fixes so that the two halves of this
+feature cannot drift. Both of those shapes are refusals rather than
+preferences, and each is written into the model below beside the field it
+constrains.
+
+A :class:`PublicationReceiptPayload` is what the network sends back: where the
+entry landed in the log, which bundle it accepted, when, and which of its own
+checks it ran. The participant signed their run and the network countersigns
+that it accepted it, which is what makes an accepted entry checkable by somebody
+who trusts neither party's word about the other.
+
+It travels inside an :class:`~techtree.models.base.ObjectEnvelope`, which is how
+every other signed document in this protocol travels: payload, the digest of the
+payload's canonical bytes, and a detached signature over that digest. An earlier
+draft carried the signature flat beside the fields it covered, and that shape
+cannot say which members the digest was taken over — two implementations would
+have had to agree on it by reading the same paragraph the same way, which is
+exactly the drift decisions 0038's wire contract exists to prevent. The envelope
+answers it structurally: the digest is over ``payload`` and over nothing else.
+
+A :class:`WithdrawalRequest` is the participant asking that a published entry be
+marked withdrawn, signed with the same key that signed the run. It carries no
+free text: nothing a submitter writes appears on the site, and a reason field
+would be the one string that did. A :class:`WithdrawalReceiptPayload` is the
+network's countersigned record that the entry is now marked withdrawn — the
+entry stays where it is, because a published entry is withdrawn and never
+deleted. Both travel in the same envelope, for the same reason.
+
+The one field that is none of them is the contributor address. It is optional,
+it is volunteered, and its name says it is unverified, because a string somebody
+typed is not proof of control of an account. It travels in the
+``x-techtree-contributor-address`` header, beside the submission and never
+inside it, because the run log serves a stored submission back at a public
+address. It is kept nowhere on this machine.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import Field, model_validator
+
+from techtree.models.base import (
+    Base64String,
+    Digest,
+    NonEmptyString,
+    ProtocolModel,
+    PublicKeyRef,
+    UtcDateTime,
+)
+
+__all__ = [
+    "PublicationCheck",
+    "PublicationReceiptPayload",
+    "PublicationSubmission",
+    "WithdrawalReceiptPayload",
+    "WithdrawalRequest",
+]
+
+
+class PublicationSubmission(ProtocolModel):
+    """Everything one publication sends, and nothing else.
+
+    Four members, fixed by decisions 0038 and by nothing else. The document is
+    stored by the run log and served back at a public address, so a member that
+    arrived here without being in the contract would be published without
+    anybody having agreed to publish it. The receiving side refuses a body that
+    carries more; ``extra="forbid"`` on :class:`~techtree.models.base.
+    ProtocolModel` means this side cannot build one.
+    """
+
+    schema_version: Literal["techtree.publication-submission.v1alpha1"]
+    run_id: NonEmptyString
+    #: The digest of the bundle's own signed manifest, which commits to every
+    #: file below. One value identifies the whole submission.
+    bundle_digest: Digest
+    #: Where each file sits inside the proof directory, in POSIX spelling,
+    #: against the base64 of its bytes. The key is the same string the bundle
+    #: manifest places the file under, so the receiving side can find each file
+    #: in the manifest that arrived with it.
+    #:
+    #: A mapping, and deliberately nothing richer. An earlier shape put a
+    #: digest and a size beside each file's content, and both were the
+    #: submitter's own claims about the submitter's own bytes: worth nothing if
+    #: honest and dangerous if believed. Every digest and every length the
+    #: receiving side works with has to come from the bundle's own signed
+    #: manifest, which is inside this mapping under ``bundle.json`` and is
+    #: signed by the key the bundle carries. Sending a digest beside the
+    #: content invites somebody downstream to trust it instead, and the only
+    #: reliable way to stop that is to have none to trust. Base64 because every
+    #: file in a proof bundle is canonical JSON, and base64 is what carries
+    #: bytes through JSON without a second encoding decision.
+    files: dict[NonEmptyString, Base64String]
+
+    @model_validator(mode="after")
+    def _check_the_files_are_a_bundle(self) -> Self:
+        """Reject a submission that places no file.
+
+        A mapping cannot place one file twice, which is the second reason the
+        contract chose one: the shape refuses a whole class of malformed
+        submission rather than a validator having to notice it.
+        """
+        if not self.files:
+            raise ValueError("a publication submits at least one file")
+        return self
+
+
+class PublicationCheck(ProtocolModel):
+    """One check the network ran on a submission, and how it came out."""
+
+    id: NonEmptyString
+    passed: bool
+    detail: NonEmptyString
+
+
+class PublicationReceiptPayload(ProtocolModel):
+    """What the network countersigns when it accepts one submission.
+
+    The payload of an :class:`~techtree.models.base.ObjectEnvelope`, so the
+    digest the network signs is the digest of exactly these members and the two
+    halves of this feature need not agree about anything else.
+    """
+
+    schema_version: Literal["techtree.publication-receipt.v1alpha1"]
+    id: NonEmptyString
+    run_id: NonEmptyString
+    #: Where this entry sits in the log. The log is ordered by arrival and by
+    #: nothing else, so this is a position in time rather than a rank, and it
+    #: may have gaps.
+    log_sequence: int = Field(ge=0)
+    bundle_digest: Digest
+    accepted_at: UtcDateTime
+    checks: list[PublicationCheck]
+    #: Where the entry can now be read.
+    entry_url: NonEmptyString
+    #: The network's own key, carried so that the receipt can be checked later
+    #: by anybody holding the network's published public half, including by
+    #: somebody who was not party to the exchange. The participant's own CLI
+    #: does not learn the key from here — it checks this against the key the
+    #: release pins, because a key learned from the answer proves nothing about
+    #: who wrote the answer.
+    public_key: PublicKeyRef
+
+    @model_validator(mode="after")
+    def _check_the_receipt_reports_its_own_checks(self) -> Self:
+        """Reject a receipt that accepted a submission it never checked."""
+        if not self.checks:
+            raise ValueError("a publication receipt names the checks that ran")
+        identifiers = [check.id for check in self.checks]
+        if len(set(identifiers)) != len(identifiers):
+            raise ValueError("a publication receipt reports each check once")
+        return self
+
+    @property
+    def failed_checks(self) -> list[PublicationCheck]:
+        """Return every check the network ran and did not pass."""
+        return [check for check in self.checks if not check.passed]
+
+
+class WithdrawalRequest(ProtocolModel):
+    """The participant asking that one published entry be marked withdrawn.
+
+    Three members and no fourth. There is no reason field and there will not be
+    one: decisions 0038 settled that nothing a submitter writes appears on the
+    site, and a free-text reason attached to a public entry is exactly that.
+
+    The bundle digest is the whole of the subject, because a run is addressed on
+    the log by its bundle digest. ``requested_at`` makes the request a dated
+    statement rather than a bare assertion, and the signature over the payload's
+    digest is what proves it came from the key that signed the run. Nothing here
+    carries a public key: the network already holds the participant's, inside
+    the bundle it accepted, and looking the key up there rather than believing
+    one that arrived with the request is the point.
+    """
+
+    schema_version: Literal["techtree.publication-withdrawal.v1alpha1"]
+    bundle_digest: Digest
+    requested_at: UtcDateTime
+
+
+class WithdrawalReceiptPayload(ProtocolModel):
+    """The network's countersigned record that an entry is marked withdrawn.
+
+    The entry itself stays: withdrawal is an appended event, not a deletion, so
+    what comes back names where the entry still lives rather than saying it is
+    gone.
+    """
+
+    schema_version: Literal["techtree.publication-withdrawal-receipt.v1alpha1"]
+    bundle_digest: Digest
+    #: Where the entry, now marked withdrawn, can still be read.
+    entry_url: NonEmptyString
+    withdrawn_at: UtcDateTime
+    public_key: PublicKeyRef

techtree/publication/offer.py

@@ -0,0 +1,35 @@
+"""The offer to publish, written once. Decisions document 0038.
+
+Two surfaces make this offer — the finished result and the proof check — and
+they are the two places somebody has just been told their run holds together.
+An offer that read differently depending on which of them a person happened to
+be looking at would be two offers, so it is one function and both call it.
+
+It carries ``requires_user_confirmation``, which is not advisory. Publishing is
+the one thing this product does that leaves the machine, and the flag is how a
+host agent is told to ask rather than act. The plugin itself publishes nothing
+and can open no network connection at all; what it may do is put this command in
+front of a person.
+"""
+
+from __future__ import annotations
+
+from techtree.models.cli import NextAction
+
+__all__ = ["publish_action"]
+
+
+def publish_action(run_id: str) -> NextAction:
+    """Return the offer to publish one verified run."""
+    return NextAction(
+        id="publish_run",
+        label="Publish this run to the public run log",
+        reason=(
+            "The proof just verified, so the run's own evidence travels with "
+            "it. It shows what would be sent and asks before sending anything."
+        ),
+        cli=["techtree", "publish", run_id],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=True,
+    )