voiceledger 0.1.3__tar.gz

voiceledger-0.1.3/.gitignore

@@ -0,0 +1,11 @@
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+dist/
+.pytest_cache/
+.ruff_cache/
+recordings/

voiceledger-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digvijay Singh
+
+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.

voiceledger-0.1.3/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: voiceledger
+Version: 0.1.3
+Summary: Hash-chained, signed event ledger with pluggable rules and a standalone verifier.
+Project-URL: Repository, https://github.com/digvijaysingh-ai/voiceops
+Project-URL: Documentation, https://github.com/digvijaysingh-ai/voiceops/blob/main/docs/guide.md
+Author: Digvijay Singh
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# voiceledger
+
+A hash-chained, signed event ledger with pluggable rules and a standalone verifier. One dependency (`cryptography`): an auditor can verify a ledger without installing the system that wrote it.
+
+```bash
+pip install voiceledger
+voiceledger verify bundle.zip --trusted-key <hex> --rules rules.toml
+```
+
+```
+PASS  1707 events
+  PASS         chain: 1707 events linked
+  PASS         identity_before_detail: 300 detail_disclosed events, all after identity_verified
+  PASS         list_order: 14 snapshots followed in order (per slot_id)
+  PASS         head: signed head matches
+```
+
+- **chain**: each event's hash covers the event and the previous hash, so editing, inserting, deleting or reordering any event breaks every later link.
+- **head**: the last hash is signed with Ed25519; with the trusted key, the whole chain can't be regenerated and re-signed by anyone else.
+- **rules**: what the project declares, e.g. `requires_before` (no detail before identity, per call), `follows_snapshot_order` (offers in the customer's list order), `always_followed_by`, `never`. Custom rules subclass `voiceledger.Rule`.
+
+A bundle is a zip with `ledger.jsonl`, `list_snapshots.jsonl` and `head.json`. Reading is defensive (size caps, known members only, JSON only). Exit code 0 when every check holds, 1 otherwise, 2 for unreadable input.
+
+What it proves: the record wasn't changed after the head was signed, and the declared rules hold over it. What it doesn't: that the events were true. Reconcile against the system of record for that.
+
+Part of [voiceops](https://github.com/digvijaysingh-ai/voiceops); rules reference in its [guide](https://github.com/digvijaysingh-ai/voiceops/blob/main/docs/guide.md). MIT licence.

voiceledger-0.1.3/README.md

@@ -0,0 +1,26 @@
+# voiceledger
+
+A hash-chained, signed event ledger with pluggable rules and a standalone verifier. One dependency (`cryptography`): an auditor can verify a ledger without installing the system that wrote it.
+
+```bash
+pip install voiceledger
+voiceledger verify bundle.zip --trusted-key <hex> --rules rules.toml
+```
+
+```
+PASS  1707 events
+  PASS         chain: 1707 events linked
+  PASS         identity_before_detail: 300 detail_disclosed events, all after identity_verified
+  PASS         list_order: 14 snapshots followed in order (per slot_id)
+  PASS         head: signed head matches
+```
+
+- **chain**: each event's hash covers the event and the previous hash, so editing, inserting, deleting or reordering any event breaks every later link.
+- **head**: the last hash is signed with Ed25519; with the trusted key, the whole chain can't be regenerated and re-signed by anyone else.
+- **rules**: what the project declares, e.g. `requires_before` (no detail before identity, per call), `follows_snapshot_order` (offers in the customer's list order), `always_followed_by`, `never`. Custom rules subclass `voiceledger.Rule`.
+
+A bundle is a zip with `ledger.jsonl`, `list_snapshots.jsonl` and `head.json`. Reading is defensive (size caps, known members only, JSON only). Exit code 0 when every check holds, 1 otherwise, 2 for unreadable input.
+
+What it proves: the record wasn't changed after the head was signed, and the declared rules hold over it. What it doesn't: that the events were true. Reconcile against the system of record for that.
+
+Part of [voiceops](https://github.com/digvijaysingh-ai/voiceops); rules reference in its [guide](https://github.com/digvijaysingh-ai/voiceops/blob/main/docs/guide.md). MIT licence.

voiceledger-0.1.3/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "voiceledger"
+version = "0.1.3"
+description = "Hash-chained, signed event ledger with pluggable rules and a standalone verifier."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Digvijay Singh" }]
+requires-python = ">=3.12"
+dependencies = ["cryptography>=42"]
+
+[project.urls]
+Repository = "https://github.com/digvijaysingh-ai/voiceops"
+Documentation = "https://github.com/digvijaysingh-ai/voiceops/blob/main/docs/guide.md"
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.2"]
+
+[project.scripts]
+voiceledger = "voiceledger.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

voiceledger-0.1.3/src/voiceledger/__init__.py

@@ -0,0 +1,51 @@
+"""voiceledger: hash-chained, signed event ledger with pluggable rules and a standalone verifier.
+
+No web framework or database driver needed to verify (Postgres storage is the optional
+`voiceledger[postgres]` extra). Rules: see voiceledger.rules and docs/PLAN.md §4.2.
+"""
+
+from voiceledger.bundle import BundleInvalid, read_bundle, write_bundle
+from voiceledger.chain import GENESIS, Event, append, seal, snapshot_hash
+from voiceledger.result import Check, Report
+from voiceledger.rules import (
+    AlwaysFollowedBy,
+    FollowsSnapshotOrder,
+    Matcher,
+    Never,
+    RequiresBefore,
+    Rule,
+    RuleConfigError,
+    load_rules,
+    load_rules_file,
+    register_rule,
+)
+from voiceledger.sign import SignedHead, SigningKeyMissing, sign_head
+from voiceledger.verify import verify
+
+__version__ = "0.1.3"
+__all__ = [
+    "GENESIS",
+    "AlwaysFollowedBy",
+    "BundleInvalid",
+    "Check",
+    "Event",
+    "FollowsSnapshotOrder",
+    "Matcher",
+    "Never",
+    "Report",
+    "RequiresBefore",
+    "Rule",
+    "RuleConfigError",
+    "SignedHead",
+    "SigningKeyMissing",
+    "append",
+    "load_rules",
+    "load_rules_file",
+    "read_bundle",
+    "register_rule",
+    "seal",
+    "sign_head",
+    "snapshot_hash",
+    "verify",
+    "write_bundle",
+]

voiceledger-0.1.3/src/voiceledger/bundle.py

@@ -0,0 +1,83 @@
+"""Evidence bundle: a zip with ledger.jsonl, list_snapshots.jsonl and head.json.
+
+Reading is defensive: bundles are uploaded by anyone, so we cap the size, read only
+the three known members, and parse JSON (never execute anything).
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+
+from voiceledger.chain import Event, canonical_json
+from voiceledger.sign import SignedHead
+
+MAX_BUNDLE_BYTES = 5 * 1024 * 1024
+MAX_MEMBER_BYTES = 20 * 1024 * 1024  # uncompressed, guards against zip bombs
+LEDGER, SNAPSHOTS, HEAD = "ledger.jsonl", "list_snapshots.jsonl", "head.json"
+
+
+class BundleInvalid(ValueError):
+    pass
+
+
+def write_bundle(events: list[Event], snapshots: dict[str, list[str]], head: SignedHead | None):
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr(LEDGER, "\n".join(e.to_json() for e in events) + "\n")
+        z.writestr(
+            SNAPSHOTS,
+            "".join(
+                canonical_json({"snapshot_id": k, "ordered_pids": v}) + "\n"
+                for k, v in sorted(snapshots.items())
+            ),
+        )
+        if head is not None:
+            z.writestr(HEAD, canonical_json(head.to_dict()))
+    return buf.getvalue()
+
+
+def _read_member(z: zipfile.ZipFile, name: str) -> str | None:
+    try:
+        info = z.getinfo(name)
+    except KeyError:
+        return None
+    if info.file_size > MAX_MEMBER_BYTES:
+        raise BundleInvalid(f"{name} is too large")
+    return z.read(name).decode("utf-8")
+
+
+def read_bundle(data: bytes):
+    """Returns (events, snapshots | None, head | None). Raises BundleInvalid."""
+    if len(data) > MAX_BUNDLE_BYTES:
+        raise BundleInvalid("file over 5 MB")
+    try:
+        z = zipfile.ZipFile(io.BytesIO(data))
+    except zipfile.BadZipFile as e:
+        raise BundleInvalid("not a ledger bundle (not a zip file)") from e
+    with z:
+        ledger = _read_member(z, LEDGER)
+        if ledger is None:
+            raise BundleInvalid("not a ledger bundle (no ledger.jsonl)")
+        try:
+            events = [Event.from_dict(json.loads(line)) for line in ledger.splitlines() if line]
+            snap_text = _read_member(z, SNAPSHOTS)
+            snapshots = None
+            if snap_text is not None:
+                snapshots = {
+                    row["snapshot_id"]: list(row["ordered_pids"])
+                    for row in map(json.loads, filter(None, snap_text.splitlines()))
+                }
+            head_text = _read_member(z, HEAD)
+            head = SignedHead(**json.loads(head_text)) if head_text else None
+        except (json.JSONDecodeError, TypeError, KeyError) as e:
+            raise BundleInvalid(f"malformed bundle: {e}") from e
+    return events, snapshots, head
+
+
+def read_ledger_jsonl(text: str) -> list[Event]:
+    try:
+        return [Event.from_dict(json.loads(line)) for line in text.splitlines() if line]
+    except (json.JSONDecodeError, TypeError) as e:
+        raise BundleInvalid(f"malformed ledger: {e}") from e

voiceledger-0.1.3/src/voiceledger/chain.py

@@ -0,0 +1,94 @@
+"""Hash chain primitives. Pure functions, no storage.
+
+Each event is hashed over its canonical JSON plus the previous event's hash:
+
+    hash_n = sha256( prev_hash_n || canonical_json(event_n without "hash") )
+
+so changing, inserting, deleting or reordering any event breaks every later link.
+A chain is one stream of events, typically per tenant per day ("<tenant>:<YYYY-MM-DD>").
+
+The event fields (including `slot_id`, the event's subject key) are the v1 wire format:
+renaming any of them would change every hash and invalidate existing bundles.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Collection
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+GENESIS = "0" * 64
+
+
+def canonical_json(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class Event:
+    chain_id: str
+    seq: int
+    ts: str
+    type: str
+    actor: str  # "agent" | "system" | "staff"
+    payload: dict = field(default_factory=dict)
+    slot_id: str | None = None
+    prev_hash: str = GENESIS
+    hash: str = ""
+
+    def body(self) -> dict:
+        d = asdict(self)
+        d.pop("hash")
+        return d
+
+    def to_json(self) -> str:
+        return canonical_json(asdict(self))
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Event:
+        return cls(**d)
+
+
+def event_hash(body: dict) -> str:
+    return hashlib.sha256((body["prev_hash"] + canonical_json(body)).encode("utf-8")).hexdigest()
+
+
+def seal(
+    chain_id: str,
+    seq: int,
+    ts: str,
+    type: str,
+    actor: str,
+    payload: dict | None = None,
+    slot_id: str | None = None,
+    prev_hash: str = GENESIS,
+    types: Collection[str] | None = None,
+) -> Event:
+    """Seal one event. `types`, when given, is the project's allow-list of event types."""
+    if types is not None and type not in types:
+        raise ValueError(f"unknown event type: {type}")
+    unsealed = Event(chain_id, seq, ts, type, actor, payload or {}, slot_id, prev_hash)
+    return Event(**{**asdict(unsealed), "hash": event_hash(unsealed.body())})
+
+
+def append(events: list[Event], ts: str, type: str, actor: str, **kw) -> Event:
+    """In-memory append, used by tests and replays. Storage uses pg.record_and_apply."""
+    chain_id = kw.pop("chain_id", events[0].chain_id if events else "demo:1970-01-01")
+    prev = events[-1] if events else None
+    ev = seal(
+        chain_id,
+        (prev.seq + 1) if prev else 1,
+        ts,
+        type,
+        actor,
+        prev_hash=prev.hash if prev else GENESIS,
+        **kw,
+    )
+    events.append(ev)
+    return ev
+
+
+def snapshot_hash(ordered_ids: list[str]) -> str:
+    return hashlib.sha256(canonical_json(ordered_ids).encode("utf-8")).hexdigest()

voiceledger-0.1.3/src/voiceledger/cli.py

@@ -0,0 +1,59 @@
+"""`voiceledger verify <bundle.zip | ledger.jsonl> [--trusted-key HEX] [--rules FILE]`
+
+`--rules` takes a TOML file with `rules = [...]` or a `[ledger] rules` table (so a
+project's voiceops.toml works as is). Without it only `chain` and `head` are checked.
+
+Exit code 0 when every supplied invariant holds, 1 otherwise, 2 for unreadable input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from voiceledger.bundle import BundleInvalid, read_bundle, read_ledger_jsonl
+from voiceledger.rules import RuleConfigError, load_rules_file
+from voiceledger.verify import verify
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="voiceledger")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    v = sub.add_parser("verify", help="verify a bundle or a bare ledger.jsonl")
+    v.add_argument("path", type=Path)
+    v.add_argument("--trusted-key", help="trusted public key of the head signer (hex)")
+    v.add_argument("--rules", type=Path, help="TOML file declaring the ledger rules")
+    v.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    try:
+        rules = load_rules_file(args.rules) if args.rules else []
+    except (OSError, RuleConfigError, ValueError) as e:
+        print(f"invalid rules: {e}", file=sys.stderr)
+        return 2
+    data = args.path.read_bytes()
+    try:
+        if args.path.suffix == ".jsonl":
+            events, snapshots, head = read_ledger_jsonl(data.decode("utf-8")), None, None
+        else:
+            events, snapshots, head = read_bundle(data)
+    except BundleInvalid as e:
+        print(f"invalid: {e}", file=sys.stderr)
+        return 2
+    report = verify(events, snapshots, head, args.trusted_key, rules)
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(("PASS" if report.ok else "FAIL") + f"  {report.events} events")
+        for name, c in report.checks.items():
+            where = f" at #{c.seq}" if c.seq else ""
+            print(f"  {c.status.upper():12} {name}{where}: {c.detail}")
+        if not rules:
+            print("  (no rules configured: only chain and head were checked)")
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

voiceledger-0.1.3/src/voiceledger/pg.py

@@ -0,0 +1,133 @@
+"""Postgres storage for the ledger (optional extra: `voiceledger[postgres]`).
+
+record_and_apply() writes a state change and its ledger event in ONE transaction:
+
+    BEGIN
+      SELECT ... FROM ledger_heads WHERE chain_id = $1 FOR UPDATE   -- only this chain waits
+      apply(conn)                                                  -- caller's state change
+      INSERT INTO ledger_events (seq = head.seq + 1, prev_hash = head.hash, ...)
+      UPDATE ledger_heads SET seq, hash
+    COMMIT
+
+A crash anywhere rolls back both, so the ledger and the state can never disagree.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Collection
+
+from voiceledger.chain import GENESIS, Event, seal, snapshot_hash
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS ledger_heads (
+    chain_id  text PRIMARY KEY,
+    seq       integer NOT NULL,
+    hash      text NOT NULL
+);
+CREATE TABLE IF NOT EXISTS ledger_events (
+    chain_id   text NOT NULL,
+    seq        integer NOT NULL,
+    ts         text NOT NULL,
+    type       text NOT NULL,
+    actor      text NOT NULL,
+    slot_id    text,
+    payload    jsonb NOT NULL,
+    prev_hash  text NOT NULL,
+    hash       text NOT NULL,
+    PRIMARY KEY (chain_id, seq)
+);
+CREATE INDEX IF NOT EXISTS ledger_events_slot ON ledger_events (chain_id, slot_id);
+CREATE TABLE IF NOT EXISTS list_snapshots (
+    chain_id       text NOT NULL,
+    snapshot_id    text NOT NULL,
+    ordered_pids   jsonb NOT NULL,
+    snapshot_hash  text NOT NULL,
+    PRIMARY KEY (chain_id, snapshot_id)
+);
+CREATE TABLE IF NOT EXISTS ledger_signed_heads (
+    chain_id   text NOT NULL,
+    seq        integer NOT NULL,
+    head       jsonb NOT NULL,
+    PRIMARY KEY (chain_id, seq)
+);
+"""
+
+
+def apply_schema(conn) -> None:
+    conn.execute(SCHEMA_SQL)
+
+
+def record_and_apply(
+    conn,
+    chain_id: str,
+    ts: str,
+    type: str,
+    actor: str,
+    payload: dict | None = None,
+    slot_id: str | None = None,
+    apply: Callable[[object], None] | None = None,
+    types: Collection[str] | None = None,
+) -> Event:
+    """Append one event and run `apply(conn)` atomically. Raises whatever apply raises.
+
+    `types`, when given, is the project's allow-list of event types (see chain.seal).
+    """
+    with conn.transaction():
+        conn.execute(
+            "INSERT INTO ledger_heads (chain_id, seq, hash) VALUES (%s, 0, %s)"
+            " ON CONFLICT (chain_id) DO NOTHING",
+            (chain_id, GENESIS),
+        )
+        seq, prev_hash = conn.execute(
+            "SELECT seq, hash FROM ledger_heads WHERE chain_id = %s FOR UPDATE", (chain_id,)
+        ).fetchone()
+        if apply is not None:
+            apply(conn)
+        ev = seal(chain_id, seq + 1, ts, type, actor, payload, slot_id, prev_hash, types)
+        conn.execute(
+            "INSERT INTO ledger_events (chain_id, seq, ts, type, actor, slot_id, payload,"
+            " prev_hash, hash) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)",
+            (
+                ev.chain_id,
+                ev.seq,
+                ev.ts,
+                ev.type,
+                ev.actor,
+                ev.slot_id,
+                json.dumps(ev.payload),
+                ev.prev_hash,
+                ev.hash,
+            ),
+        )
+        conn.execute(
+            "UPDATE ledger_heads SET seq = %s, hash = %s WHERE chain_id = %s",
+            (ev.seq, ev.hash, chain_id),
+        )
+    return ev
+
+
+def save_snapshot(conn, chain_id: str, snapshot_id: str, ordered_pids: list[str]) -> str:
+    h = snapshot_hash(ordered_pids)
+    conn.execute(
+        "INSERT INTO list_snapshots (chain_id, snapshot_id, ordered_pids, snapshot_hash)"
+        " VALUES (%s, %s, %s, %s)",
+        (chain_id, snapshot_id, json.dumps(ordered_pids), h),
+    )
+    return h
+
+
+def load_events(conn, chain_id: str) -> list[Event]:
+    rows = conn.execute(
+        "SELECT chain_id, seq, ts, type, actor, payload, slot_id, prev_hash, hash"
+        " FROM ledger_events WHERE chain_id = %s ORDER BY seq",
+        (chain_id,),
+    ).fetchall()
+    return [Event(*r) for r in rows]
+
+
+def load_snapshots(conn, chain_id: str) -> dict[str, list[str]]:
+    rows = conn.execute(
+        "SELECT snapshot_id, ordered_pids FROM list_snapshots WHERE chain_id = %s", (chain_id,)
+    ).fetchall()
+    return {sid: list(pids) for sid, pids in rows}

voiceledger-0.1.3/src/voiceledger/result.py

@@ -0,0 +1,33 @@
+"""Check results and the verification report."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Check:
+    status: str = "pass"  # pass | fail | not_checked
+    detail: str = ""
+    seq: int | None = None
+
+    def fail(self, seq: int | None, detail: str) -> None:
+        if self.status != "fail":  # keep the first failure
+            self.status, self.seq, self.detail = "fail", seq, detail
+
+
+@dataclass
+class Report:
+    events: int
+    checks: dict[str, Check] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return all(c.status != "fail" for c in self.checks.values())
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "events": self.events,
+            "checks": {k: vars(v) for k, v in self.checks.items()},
+        }