matrym-hashchain 0.1.0__tar.gz

matrym_hashchain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Evans (MatrymLabs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matrym_hashchain-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: matrym-hashchain
+Version: 0.1.0
+Summary: A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).
+Author: Josh Evans (MatrymLabs)
+License: MIT
+Project-URL: Homepage, https://github.com/MatrymLabs/matrym-hashchain
+Project-URL: Repository, https://github.com/MatrymLabs/matrym-hashchain
+Project-URL: Changelog, https://github.com/MatrymLabs/matrym-hashchain/blob/main/CHANGELOG.md
+Keywords: audit,integrity,tamper-evident,hash-chain,append-only,ledger,provenance,compliance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# matrym-hashchain
+
+[![CI](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml/badge.svg)](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+
+**A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).**
+
+Each entry carries a SHA-256 over its own payload **and** the previous entry's hash, so any later
+edit, reorder, or deletion of a *past* record is detected the next time the log is read. It's a
+file-simple, zero-dependency primitive for **audit trails, transaction logs, and chain-of-custody
+records** - the kind of thing a compliance, finance, or records system needs and shouldn't hand-roll.
+
+## Install
+
+```bash
+pip install matrym-hashchain                                    # once released to PyPI
+pip install git+https://github.com/MatrymLabs/matrym-hashchain  # or straight from GitHub, today
+```
+
+PyPI publishing is wired up via [trusted publishing](RELEASING.md) (no stored token); the
+`pip install matrym-hashchain` line goes live with the first tagged release.
+
+## Use
+
+```python
+from pathlib import Path
+from hashchain import append, read, verify, HashChainError
+
+ledger = Path("audit.jsonl")
+
+append(ledger, {"event": "created", "who": "alice"})
+append(ledger, {"event": "approved", "who": "bob"})
+
+for entry in read(ledger):          # read() verifies the whole chain as it goes
+    print(entry.seq, entry.payload)
+
+verify(ledger)                      # True -- the history reads clean end to end
+
+# If anyone edits, reorders, or deletes a past record...
+ledger.write_text(ledger.read_text().replace("alice", "mallory"))
+verify(ledger)                      # False
+read(ledger)                        # raises HashChainError: record 0 was tampered ...
+```
+
+The store is plain JSON Lines (`.jsonl`) - one record per line, human-readable, greppable, and
+portable. No database, no daemon, no dependencies.
+
+## What it guarantees (and what it doesn't)
+
+This proves **integrity**, honestly labelled:
+
+| Attack | Detected? |
+|---|---|
+| A payload was edited | ✅ content-hash mismatch |
+| Records were reordered or one was inserted | ✅ sequence / prior-hash mismatch |
+| A *middle* record was deleted | ✅ the next record's prior-hash no longer links |
+| The *last* record(s) were dropped | ❌ not by the chain alone - anchor the head hash elsewhere (a receipt, a second store) if truncation must be caught |
+| Who wrote a record (authenticity) | ❌ integrity is not authenticity - sign the head hash (HMAC or a key) to prove authorship |
+
+Any break **fails loud** with `HashChainError` rather than returning a dishonest history.
+
+## API
+
+- `append(path, payload) -> Entry` - validate, hash-chain, and append one record. Verifies the
+  chain *before* extending it, so you can't quietly append onto an already-tampered log.
+- `read(path) -> list[Entry]` - read every record, verifying as it goes. Empty/missing store -> `[]`.
+- `verify(path) -> bool` - `True` if the ledger reads clean end to end, `False` if broken.
+- `content_hash(mapping) -> str` - the canonical SHA-256 (sorted keys, no whitespace) the chain uses.
+- `Entry(seq, payload, prior_hash, content_hash)` - one link; `HashChainError` - the loud failure.
+
+## Provenance
+
+This is a **MatrymLabs Hardware Store part**: a pattern first proven in the
+[CodeForge](https://github.com/MatrymLabs/codeforge) MUD engine (the "Chronicle" - the game's
+tamper-evident memory), then reused across the fleet (a federal guidance-check ledger; an AI-triage
+decision audit trail). Published standalone so any project can reuse the same tested primitive -
+*one well-made part, many jobs.*
+
+## License
+
+MIT

matrym_hashchain-0.1.0/README.md

@@ -0,0 +1,83 @@
+# matrym-hashchain
+
+[![CI](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml/badge.svg)](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+
+**A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).**
+
+Each entry carries a SHA-256 over its own payload **and** the previous entry's hash, so any later
+edit, reorder, or deletion of a *past* record is detected the next time the log is read. It's a
+file-simple, zero-dependency primitive for **audit trails, transaction logs, and chain-of-custody
+records** - the kind of thing a compliance, finance, or records system needs and shouldn't hand-roll.
+
+## Install
+
+```bash
+pip install matrym-hashchain                                    # once released to PyPI
+pip install git+https://github.com/MatrymLabs/matrym-hashchain  # or straight from GitHub, today
+```
+
+PyPI publishing is wired up via [trusted publishing](RELEASING.md) (no stored token); the
+`pip install matrym-hashchain` line goes live with the first tagged release.
+
+## Use
+
+```python
+from pathlib import Path
+from hashchain import append, read, verify, HashChainError
+
+ledger = Path("audit.jsonl")
+
+append(ledger, {"event": "created", "who": "alice"})
+append(ledger, {"event": "approved", "who": "bob"})
+
+for entry in read(ledger):          # read() verifies the whole chain as it goes
+    print(entry.seq, entry.payload)
+
+verify(ledger)                      # True -- the history reads clean end to end
+
+# If anyone edits, reorders, or deletes a past record...
+ledger.write_text(ledger.read_text().replace("alice", "mallory"))
+verify(ledger)                      # False
+read(ledger)                        # raises HashChainError: record 0 was tampered ...
+```
+
+The store is plain JSON Lines (`.jsonl`) - one record per line, human-readable, greppable, and
+portable. No database, no daemon, no dependencies.
+
+## What it guarantees (and what it doesn't)
+
+This proves **integrity**, honestly labelled:
+
+| Attack | Detected? |
+|---|---|
+| A payload was edited | ✅ content-hash mismatch |
+| Records were reordered or one was inserted | ✅ sequence / prior-hash mismatch |
+| A *middle* record was deleted | ✅ the next record's prior-hash no longer links |
+| The *last* record(s) were dropped | ❌ not by the chain alone - anchor the head hash elsewhere (a receipt, a second store) if truncation must be caught |
+| Who wrote a record (authenticity) | ❌ integrity is not authenticity - sign the head hash (HMAC or a key) to prove authorship |
+
+Any break **fails loud** with `HashChainError` rather than returning a dishonest history.
+
+## API
+
+- `append(path, payload) -> Entry` - validate, hash-chain, and append one record. Verifies the
+  chain *before* extending it, so you can't quietly append onto an already-tampered log.
+- `read(path) -> list[Entry]` - read every record, verifying as it goes. Empty/missing store -> `[]`.
+- `verify(path) -> bool` - `True` if the ledger reads clean end to end, `False` if broken.
+- `content_hash(mapping) -> str` - the canonical SHA-256 (sorted keys, no whitespace) the chain uses.
+- `Entry(seq, payload, prior_hash, content_hash)` - one link; `HashChainError` - the loud failure.
+
+## Provenance
+
+This is a **MatrymLabs Hardware Store part**: a pattern first proven in the
+[CodeForge](https://github.com/MatrymLabs/codeforge) MUD engine (the "Chronicle" - the game's
+tamper-evident memory), then reused across the fleet (a federal guidance-check ledger; an AI-triage
+decision audit trail). Published standalone so any project can reuse the same tested primitive -
+*one well-made part, many jobs.*
+
+## License
+
+MIT

matrym_hashchain-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrym-hashchain"
+version = "0.1.0"
+description = "A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Josh Evans (MatrymLabs)" }]
+keywords = [
+  "audit",
+  "integrity",
+  "tamper-evident",
+  "hash-chain",
+  "append-only",
+  "ledger",
+  "provenance",
+  "compliance",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[project.urls]
+Homepage = "https://github.com/MatrymLabs/matrym-hashchain"
+Repository = "https://github.com/MatrymLabs/matrym-hashchain"
+Changelog = "https://github.com/MatrymLabs/matrym-hashchain/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hashchain = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

matrym_hashchain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrym_hashchain-0.1.0/src/hashchain/__init__.py

@@ -0,0 +1,142 @@
+"""A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).
+
+Each entry carries a sha256 over its own payload AND the previous entry's hash, so any later edit,
+reorder, or removal of a PAST record is detected the next time the log is read. A file-simple,
+zero-dependency primitive for audit trails, transaction logs, and chain-of-custody records.
+
+    from pathlib import Path
+    from hashchain import append, read, verify
+
+    p = Path("audit.jsonl")
+    append(p, {"event": "created", "who": "alice"})
+    append(p, {"event": "approved", "who": "bob"})
+    verify(p)   # True -- the history reads clean end to end
+
+Honest bounds -- this proves INTEGRITY, not everything:
+- Detected: a changed payload (hash mismatch), a reordered or inserted record, a deleted MIDDLE
+  record (the next record's prior-hash no longer links).
+- NOT detected by the chain alone: dropping the LAST record(s) -- anchor the head hash elsewhere
+  (a receipt, a second store) if truncation must be caught. And integrity is not authenticity:
+  sign the head hash to prove WHO wrote it.
+Any break fails loud with `HashChainError` rather than returning a dishonest history.
+
+Provenance: this is a MatrymLabs Hardware Store part -- a pattern first proven in the CodeForge MUD
+engine (the "Chronicle", the game's tamper-evident memory) and reused across the fleet (a federal
+guidance-check ledger; an AI-triage decision audit trail). Published standalone so any project can
+reuse the same tested primitive.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__version__ = "0.1.0"
+__all__ = [
+    "GENESIS",
+    "Entry",
+    "HashChainError",
+    "append",
+    "content_hash",
+    "read",
+    "verify",
+]
+
+GENESIS = ""  # the prior_hash of the first entry: nothing precedes it
+_FIELDS = ("seq", "payload", "prior_hash", "content_hash")
+
+
+class HashChainError(Exception):
+    """Raised when the ledger is malformed or its chain is broken. Names the exact record."""
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One entry in the chain: its position, its data, and the hashes that bind it to the past."""
+
+    seq: int
+    payload: dict[str, Any]
+    prior_hash: str
+    content_hash: str
+
+
+def content_hash(payload: Mapping[str, Any]) -> str:
+    """A deterministic sha256 over a JSON-serializable mapping (canonical: sorted keys, compact)."""
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _digest(seq: int, payload: Mapping[str, Any], prior_hash: str) -> str:
+    return content_hash({"seq": seq, "payload": payload, "prior_hash": prior_hash})
+
+
+def append(path: Path, payload: dict[str, Any]) -> Entry:
+    """Validate, hash-chain, and append one record; return the new Entry. The chain is verified
+    before it is extended, so appending to a tampered ledger fails loud rather than hiding it."""
+    if not isinstance(payload, dict):
+        raise HashChainError("payload must be a JSON object (dict)")
+    existing = read(path)  # verifies the chain first
+    prior = existing[-1].content_hash if existing else GENESIS
+    seq = len(existing)
+    try:
+        digest = _digest(seq, payload, prior)
+    except (TypeError, ValueError) as exc:
+        raise HashChainError(f"payload is not JSON-serializable: {exc}") from exc
+    entry = Entry(seq=seq, payload=payload, prior_hash=prior, content_hash=digest)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(_as_row(entry), sort_keys=True) + "\n")
+    return entry
+
+
+def read(path: Path) -> list[Entry]:
+    """Read every record, verifying the chain as it goes. Fails loud (`HashChainError`) on a
+    tampered payload, a broken/reordered chain, or a malformed line. Empty/missing store -> []."""
+    if not path.exists():
+        return []
+    entries: list[Entry] = []
+    prev_hash = GENESIS
+    for lineno, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise HashChainError(f"line {lineno} is unreadable JSON: {exc}") from exc
+        if not isinstance(row, dict) or not all(field in row for field in _FIELDS):
+            raise HashChainError(f"line {lineno} is a malformed record (missing fields)")
+        expected_seq = len(entries)
+        if row["seq"] != expected_seq:
+            raise HashChainError(
+                f"record {row['seq']} is out of order (expected seq {expected_seq})"
+            )
+        if _digest(row["seq"], row["payload"], row["prior_hash"]) != row["content_hash"]:
+            raise HashChainError(f"record {row['seq']} was tampered: content hash mismatch")
+        if row["prior_hash"] != prev_hash:
+            raise HashChainError(f"broken chain at record {row['seq']}: prior hash does not link")
+        entries.append(Entry(row["seq"], row["payload"], row["prior_hash"], row["content_hash"]))
+        prev_hash = row["content_hash"]
+    return entries
+
+
+def verify(path: Path) -> bool:
+    """True if the ledger reads clean end to end, False if the chain is broken or a line is bad."""
+    try:
+        read(path)
+        return True
+    except HashChainError:
+        return False
+
+
+def _as_row(entry: Entry) -> dict[str, Any]:
+    return {
+        "seq": entry.seq,
+        "payload": entry.payload,
+        "prior_hash": entry.prior_hash,
+        "content_hash": entry.content_hash,
+    }

matrym_hashchain-0.1.0/src/matrym_hashchain.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: matrym-hashchain
+Version: 0.1.0
+Summary: A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).
+Author: Josh Evans (MatrymLabs)
+License: MIT
+Project-URL: Homepage, https://github.com/MatrymLabs/matrym-hashchain
+Project-URL: Repository, https://github.com/MatrymLabs/matrym-hashchain
+Project-URL: Changelog, https://github.com/MatrymLabs/matrym-hashchain/blob/main/CHANGELOG.md
+Keywords: audit,integrity,tamper-evident,hash-chain,append-only,ledger,provenance,compliance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# matrym-hashchain
+
+[![CI](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml/badge.svg)](https://github.com/MatrymLabs/matrym-hashchain/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+
+**A tamper-evident, append-only, hash-chained ledger. Dependency-free (stdlib only).**
+
+Each entry carries a SHA-256 over its own payload **and** the previous entry's hash, so any later
+edit, reorder, or deletion of a *past* record is detected the next time the log is read. It's a
+file-simple, zero-dependency primitive for **audit trails, transaction logs, and chain-of-custody
+records** - the kind of thing a compliance, finance, or records system needs and shouldn't hand-roll.
+
+## Install
+
+```bash
+pip install matrym-hashchain                                    # once released to PyPI
+pip install git+https://github.com/MatrymLabs/matrym-hashchain  # or straight from GitHub, today
+```
+
+PyPI publishing is wired up via [trusted publishing](RELEASING.md) (no stored token); the
+`pip install matrym-hashchain` line goes live with the first tagged release.
+
+## Use
+
+```python
+from pathlib import Path
+from hashchain import append, read, verify, HashChainError
+
+ledger = Path("audit.jsonl")
+
+append(ledger, {"event": "created", "who": "alice"})
+append(ledger, {"event": "approved", "who": "bob"})
+
+for entry in read(ledger):          # read() verifies the whole chain as it goes
+    print(entry.seq, entry.payload)
+
+verify(ledger)                      # True -- the history reads clean end to end
+
+# If anyone edits, reorders, or deletes a past record...
+ledger.write_text(ledger.read_text().replace("alice", "mallory"))
+verify(ledger)                      # False
+read(ledger)                        # raises HashChainError: record 0 was tampered ...
+```
+
+The store is plain JSON Lines (`.jsonl`) - one record per line, human-readable, greppable, and
+portable. No database, no daemon, no dependencies.
+
+## What it guarantees (and what it doesn't)
+
+This proves **integrity**, honestly labelled:
+
+| Attack | Detected? |
+|---|---|
+| A payload was edited | ✅ content-hash mismatch |
+| Records were reordered or one was inserted | ✅ sequence / prior-hash mismatch |
+| A *middle* record was deleted | ✅ the next record's prior-hash no longer links |
+| The *last* record(s) were dropped | ❌ not by the chain alone - anchor the head hash elsewhere (a receipt, a second store) if truncation must be caught |
+| Who wrote a record (authenticity) | ❌ integrity is not authenticity - sign the head hash (HMAC or a key) to prove authorship |
+
+Any break **fails loud** with `HashChainError` rather than returning a dishonest history.
+
+## API
+
+- `append(path, payload) -> Entry` - validate, hash-chain, and append one record. Verifies the
+  chain *before* extending it, so you can't quietly append onto an already-tampered log.
+- `read(path) -> list[Entry]` - read every record, verifying as it goes. Empty/missing store -> `[]`.
+- `verify(path) -> bool` - `True` if the ledger reads clean end to end, `False` if broken.
+- `content_hash(mapping) -> str` - the canonical SHA-256 (sorted keys, no whitespace) the chain uses.
+- `Entry(seq, payload, prior_hash, content_hash)` - one link; `HashChainError` - the loud failure.
+
+## Provenance
+
+This is a **MatrymLabs Hardware Store part**: a pattern first proven in the
+[CodeForge](https://github.com/MatrymLabs/codeforge) MUD engine (the "Chronicle" - the game's
+tamper-evident memory), then reused across the fleet (a federal guidance-check ledger; an AI-triage
+decision audit trail). Published standalone so any project can reuse the same tested primitive -
+*one well-made part, many jobs.*
+
+## License
+
+MIT

matrym_hashchain-0.1.0/src/matrym_hashchain.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/hashchain/__init__.py
+src/hashchain/py.typed
+src/matrym_hashchain.egg-info/PKG-INFO
+src/matrym_hashchain.egg-info/SOURCES.txt
+src/matrym_hashchain.egg-info/dependency_links.txt
+src/matrym_hashchain.egg-info/requires.txt
+src/matrym_hashchain.egg-info/top_level.txt
+tests/test_hashchain.py

matrym_hashchain-0.1.0/src/matrym_hashchain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matrym_hashchain-0.1.0/src/matrym_hashchain.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=8
+ruff>=0.6
+mypy>=1.11

matrym_hashchain-0.1.0/src/matrym_hashchain.egg-info/top_level.txt

@@ -0,0 +1 @@
+hashchain

matrym_hashchain-0.1.0/tests/test_hashchain.py

@@ -0,0 +1,119 @@
+"""Test twin for hashchain -- the tamper-evident append-only ledger.
+
+Acceptance: records append and read back in order; each entry chains to its predecessor; empty and
+missing stores read clean. Refusal (the whole point of a tamper-evident log): an edited payload, a
+reordered chain, a deleted middle record, a malformed line, and a non-serializable payload all fail
+loud with HashChainError rather than returning a dishonest history. Every test uses tmp_path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from hashchain import GENESIS, HashChainError, append, content_hash, read, verify
+
+
+def _ledger(root: Path) -> Path:
+    return root / "chain.jsonl"
+
+
+# --- acceptance --------------------------------------------------------------------------------
+
+
+def test_append_then_read_round_trips(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    append(p, {"event": "created", "who": "alice"})
+    append(p, {"event": "approved", "who": "bob"})
+    entries = read(p)
+    assert [e.payload["event"] for e in entries] == ["created", "approved"]
+    assert [e.seq for e in entries] == [0, 1]
+
+
+def test_the_chain_links_each_record_to_its_predecessor(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    a = append(p, {"n": 1})
+    b = append(p, {"n": 2})
+    assert a.prior_hash == GENESIS  # nothing precedes the first entry
+    assert b.prior_hash == a.content_hash  # chained
+    assert a.content_hash != b.content_hash
+
+
+def test_empty_and_missing_stores_read_clean(tmp_path: Path) -> None:
+    assert read(_ledger(tmp_path)) == []  # missing file
+    p = _ledger(tmp_path)
+    p.write_text("\n  \n", encoding="utf-8")  # only blank lines
+    assert read(p) == []
+    assert verify(p) is True
+
+
+def test_content_hash_is_canonical_and_order_independent() -> None:
+    assert content_hash({"a": 1, "b": 2}) == content_hash({"b": 2, "a": 1})
+
+
+# --- refusal / hostile -------------------------------------------------------------------------
+
+
+def test_a_non_dict_payload_fails_loud(tmp_path: Path) -> None:
+    with pytest.raises(HashChainError, match="must be a JSON object"):
+        append(_ledger(tmp_path), ["not", "a", "dict"])  # type: ignore[arg-type]
+
+
+def test_a_non_serializable_payload_fails_loud(tmp_path: Path) -> None:
+    with pytest.raises(HashChainError, match="not JSON-serializable"):
+        append(_ledger(tmp_path), {"tags": {1, 2, 3}})  # a set is not JSON-serializable
+    assert read(_ledger(tmp_path)) == []  # the bad record never reached disk
+
+
+def test_a_tampered_payload_is_detected_on_read(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    append(p, {"amount": 100})
+    p.write_text(p.read_text().replace("100", "999"), encoding="utf-8")  # edit without rehashing
+    with pytest.raises(HashChainError, match="tampered"):
+        read(p)
+    assert verify(p) is False
+
+
+def test_a_reordered_chain_is_detected(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    append(p, {"n": 1})
+    append(p, {"n": 2})
+    first, second = p.read_text().splitlines()
+    p.write_text(second + "\n" + first + "\n", encoding="utf-8")  # swap the two records
+    with pytest.raises(HashChainError, match="out of order|broken chain"):
+        read(p)
+
+
+def test_deleting_a_middle_record_breaks_the_chain(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    append(p, {"n": 1})
+    append(p, {"n": 2})
+    append(p, {"n": 3})
+    lines = p.read_text().splitlines()
+    p.write_text(lines[0] + "\n" + lines[2] + "\n", encoding="utf-8")  # drop the middle record
+    with pytest.raises(HashChainError, match="out of order|broken chain"):
+        read(p)
+
+
+def test_a_malformed_line_fails_loud(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    p.write_text("{not valid json}\n", encoding="utf-8")
+    with pytest.raises(HashChainError, match="unreadable JSON"):
+        read(p)
+
+
+def test_a_record_missing_a_field_fails_loud(tmp_path: Path) -> None:
+    p = _ledger(tmp_path)
+    p.write_text('{"seq": 0, "payload": {}}\n', encoding="utf-8")  # no prior/content hash
+    with pytest.raises(HashChainError, match="malformed record"):
+        read(p)
+
+
+def test_appending_to_a_tampered_ledger_fails_loud(tmp_path: Path) -> None:
+    """You cannot quietly extend a history that has already been broken."""
+    p = _ledger(tmp_path)
+    append(p, {"n": 1})
+    p.write_text(p.read_text().replace('"n": 1', '"n": 2'), encoding="utf-8")
+    with pytest.raises(HashChainError, match="tampered"):
+        append(p, {"n": 3})