orphograph 0.1.0__py3-none-any.whl

orphograph/__init__.py

@@ -0,0 +1,175 @@
+"""orphograph — Python SDK for anchoring folders to Bitcoin.
+
+The SDK constructs an RFC 6962-style Merkle tree from a local folder, then
+submits only the manifest (paths, per-file SHA-256 digests, leaf hashes,
+and a 32-byte root) to the Orphograph hosted service. File bodies do not
+cross the network at any point in this module.
+
+Public API:
+
+    anchor_folder(folder_path, server_url=..., api_key=..., client_label=..., exclude=...)
+    verify_folder(folder_path, receipt_id, server_url=...)
+    inclusion_proof(receipt_id, path, server_url=...)
+    verify_inclusion(file_path, rel_path, proof, root_hex)
+
+Algorithm tag: ``orphograph-merkle-v1-rfc6962``.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Optional, Sequence
+
+from . import _client
+from ._client import OrphographError
+from ._merkle import ALGORITHM, MerkleTree
+
+__all__ = [
+    "ALGORITHM",
+    "OrphographError",
+    "anchor_folder",
+    "verify_folder",
+    "inclusion_proof",
+    "verify_inclusion",
+]
+
+__version__ = "0.1.0"
+
+
+def anchor_folder(
+    folder_path: str,
+    *,
+    server_url: str = _client.DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+    client_label: Optional[str] = None,
+    exclude: Optional[Sequence[str]] = None,
+) -> dict:
+    """Anchor a folder to Bitcoin via the Orphograph hosted service.
+
+    The Merkle tree is constructed locally; only the resulting manifest
+    (paths + SHA-256 digests + leaf hashes + root) is transmitted to the
+    server. File contents stay on disk.
+
+    Returns a dict with keys: ``receipt_id``, ``root_hex``, ``leaf_count``,
+    ``calendars_ok``, ``calendars_total``.
+    """
+    root = Path(folder_path)
+    if not root.is_dir():
+        raise ValueError(f"not a directory: {folder_path}")
+    excl_list = list(exclude) if exclude is not None else None
+    tree = MerkleTree.from_folder(root, exclude=excl_list)
+    manifest = tree.manifest()
+    response = _client.post_anchor_folder(
+        manifest,
+        server_url=server_url,
+        api_key=api_key,
+        client_label=client_label,
+    )
+    return {
+        "receipt_id": response.get("receipt_id"),
+        "root_hex": response.get("root_hex", tree.root_hex()),
+        "leaf_count": response.get("leaf_count", len(manifest["leaves"])),
+        "calendars_ok": response.get("calendars_ok"),
+        "calendars_total": response.get("calendars_total"),
+    }
+
+
+def verify_folder(
+    folder_path: str,
+    receipt_id: str,
+    *,
+    server_url: str = _client.DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+    exclude: Optional[list] = None,
+) -> bool:
+    """Verify a local folder against a previously anchored receipt.
+
+    Rebuilds the Merkle root locally from the folder on disk and compares
+    it byte-for-byte to the root recorded in the receipt's manifest. The
+    server is consulted only to fetch the manifest; file contents are not
+    transmitted.
+    """
+    root = Path(folder_path)
+    if not root.is_dir():
+        raise ValueError(f"not a directory: {folder_path}")
+    response = _client.get_verify_folder(receipt_id, server_url=server_url, api_key=api_key)
+    manifest = response.get("manifest") or {}
+    server_root = manifest.get("root_hex")
+    if not server_root:
+        return False
+    # The manifest is authoritative for its own scope.
+    #
+    # Previously this mirrored whatever the CALLER passed, which only moved the
+    # problem: a folder anchored with custom excludes still could not verify
+    # unless the verifier independently remembered the exact list used at
+    # capture, months earlier, possibly on another machine. That is not a
+    # property evidence should have.
+    #
+    # Manifests now record the effective patterns (see merkle.build_scope), so
+    # they are read from the manifest when present. The caller's `exclude` is
+    # only a fallback for manifests issued before scope existed.
+    effective_exclude = exclude
+    scope = manifest.get("scope")
+    if isinstance(scope, dict) and isinstance(scope.get("exclude"), list):
+        effective_exclude = list(scope["exclude"])
+    tree = MerkleTree.from_folder(root, exclude=effective_exclude)
+    return tree.root_hex() == server_root
+
+
+def inclusion_proof(
+    receipt_id: str,
+    path: str,
+    *,
+    server_url: str = _client.DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+) -> dict:
+    """Fetch an inclusion proof for one POSIX-relative path in a folder receipt.
+
+    Returns the server's JSON payload: ``receipt_id``, ``root_hex``,
+    ``path``, ``file_sha256_hex``, ``proof`` (list of ``[direction, hex]``).
+    """
+    return _client.get_inclusion_proof(
+        receipt_id, path, server_url=server_url, api_key=api_key
+    )
+
+
+def verify_inclusion(
+    file_path: str,
+    rel_path: str,
+    proof: Sequence,
+    root_hex: str,
+) -> bool:
+    """Verify locally that a file was included in an anchored folder.
+
+    Reads the file from disk, computes its SHA-256, and walks the proof
+    upward against the supplied root. No network call is made.
+
+    Raises ``FileNotFoundError`` when ``file_path`` does not exist (or is
+    not a regular file). A missing local file is an I/O precondition
+    failure, not a "not included" verdict — for a notary, a distinguishable
+    error beats a silent ``False`` (audit D7; matches the Node SDK, whose
+    ``verifyInclusion`` rejects with the filesystem error). A malformed
+    proof or root still returns ``False`` per VERIFIER_SPEC §4.1.
+    """
+    p = Path(file_path)
+    if not p.is_file():
+        raise FileNotFoundError(f"no such file: {file_path}")
+    h = hashlib.sha256()
+    with p.open("rb") as f:
+        while True:
+            chunk = f.read(1024 * 1024)
+            if not chunk:
+                break
+            h.update(chunk)
+    file_hash = h.digest()
+    try:
+        root = bytes.fromhex(root_hex)
+    except (ValueError, TypeError):
+        return False
+    # Coerce proof entries (which may arrive as lists from JSON) to tuples.
+    normalised: list = []
+    for step in proof:
+        if not isinstance(step, (list, tuple)) or len(step) != 2:
+            return False
+        normalised.append((step[0], step[1]))
+    return MerkleTree.verify_inclusion(file_hash, rel_path, normalised, root)

orphograph/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m orphograph``."""
+from ._cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orphograph/_cli.py

@@ -0,0 +1,129 @@
+"""orphograph._cli — argparse-based command-line interface.
+
+Subcommands:
+
+    anchor <folder>                 Anchor a folder; prints one line of JSON.
+    verify <folder> <receipt_id>    Verify a folder against a receipt.
+    inclusion-proof <rid> <path>    Fetch an inclusion proof; prints JSON.
+
+Both ``anchor`` and ``verify`` accept repeatable ``--exclude GLOB`` flags.
+A folder anchored with custom excludes can only re-derive the same Merkle
+root when verified with the SAME excludes (AUDIT_VERIFIER_DRIFT D2). Since
+Wedge 01 the manifest records them in its ``scope`` block and ``verify``
+reads them from there (the manifest is authoritative — VERIFIER_SPEC §4.2);
+the ``--exclude`` flag on ``verify`` only applies to manifests that carry no
+scope block (issued before scope existed).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional
+
+from . import anchor_folder, inclusion_proof, verify_folder
+from ._client import DEFAULT_SERVER_URL, OrphographError
+
+
+def _env_server() -> str:
+    return os.environ.get("ORPHO_SERVER_URL", DEFAULT_SERVER_URL)
+
+
+def _env_api_key() -> Optional[str]:
+    val = os.environ.get("ORPHO_API_KEY", "").strip()
+    return val or None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="orphograph",
+        description="Anchor folders to Bitcoin via the Orphograph service.",
+    )
+    parser.add_argument(
+        "--server-url",
+        default=None,
+        help="Base URL of the Orphograph service (default: ORPHO_SERVER_URL or https://orphograph.com).",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="Optional API key (default: ORPHO_API_KEY).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    exclude_help = (
+        "Glob pattern to exclude (repeatable). Supplying any --exclude "
+        "REPLACES the default deny-list rather than extending it. "
+        "On verify: applies only to manifests without a scope block — a "
+        "manifest's recorded scope.exclude is authoritative (VERIFIER_SPEC §4.2)."
+    )
+
+    p_anchor = sub.add_parser("anchor", help="Anchor a folder.")
+    p_anchor.add_argument("folder", help="Local folder to anchor.")
+    p_anchor.add_argument("--label", default=None, help="Optional short client label.")
+    p_anchor.add_argument(
+        "--exclude", action="append", default=None, metavar="GLOB", help=exclude_help
+    )
+
+    p_verify = sub.add_parser("verify", help="Verify a folder against a receipt.")
+    p_verify.add_argument("folder", help="Local folder to verify.")
+    p_verify.add_argument("receipt_id", help="Receipt id returned at anchor time.")
+    p_verify.add_argument(
+        "--exclude", action="append", default=None, metavar="GLOB", help=exclude_help
+    )
+
+    p_proof = sub.add_parser("inclusion-proof", help="Fetch an inclusion proof.")
+    p_proof.add_argument("receipt_id", help="Folder receipt id.")
+    p_proof.add_argument("path", help="POSIX relative path inside the folder.")
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    server_url = args.server_url or _env_server()
+    api_key = args.api_key if args.api_key is not None else _env_api_key()
+
+    try:
+        if args.command == "anchor":
+            result = anchor_folder(
+                args.folder,
+                server_url=server_url,
+                api_key=api_key,
+                client_label=args.label,
+                exclude=args.exclude,
+            )
+            sys.stdout.write(json.dumps(result) + "\n")
+            return 0
+        if args.command == "verify":
+            ok = verify_folder(
+                args.folder,
+                args.receipt_id,
+                server_url=server_url,
+                api_key=api_key,
+                exclude=args.exclude,
+            )
+            sys.stdout.write(json.dumps({"match": bool(ok)}) + "\n")
+            return 0 if ok else 1
+        if args.command == "inclusion-proof":
+            proof = inclusion_proof(
+                args.receipt_id,
+                args.path,
+                server_url=server_url,
+                api_key=api_key,
+            )
+            sys.stdout.write(json.dumps(proof) + "\n")
+            return 0
+    except OrphographError as e:
+        sys.stderr.write(json.dumps({"error": e.message, "status": e.status}) + "\n")
+        return 2
+    except (OSError, ValueError) as e:
+        sys.stderr.write(json.dumps({"error": str(e)}) + "\n")
+        return 2
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orphograph/_client.py

@@ -0,0 +1,148 @@
+"""orphograph._client — HTTP transport to the Orphograph REST API.
+
+This client never reads file contents. It builds a Merkle manifest from
+on-disk SHA-256 digests, then transmits only the manifest and root hash.
+File bodies remain on the local machine at all times. The wire payload is
+the manifest JSON described in ``orphograph-merkle-v1-rfc6962`` — relative
+POSIX paths, per-file SHA-256 digests, leaf hashes, and a 32-byte root.
+
+The module uses ``urllib.request`` and ``json`` from the standard library
+only. No third-party HTTP dependency is introduced on the runtime path.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+DEFAULT_SERVER_URL = "https://orphograph.com"
+DEFAULT_TIMEOUT = 60.0
+# Honest, self-identifying User-Agent. NEVER a browser-spoofing string.
+#
+# The comment that used to sit here said the service "sits behind a CDN whose
+# default-deny posture blocks scripted clients identifying themselves as such"
+# and that "only the leading Mozilla/5.0 appeases the gateway". It was tested
+# on 2026-08-20 against https://orphograph.com/api/health:
+#
+#   Python-urllib/3.11 ............................ 403
+#   no User-Agent header at all ................... 200
+#   curl/8.7.1 .................................... 200
+#   orphograph-python-sdk/0.1 (+https://…) ........ 200
+#
+# The premise was right and the conclusion was wrong: the gateway blocks one
+# literal token, not scripted clients as a class. An SDK that impersonates
+# Safari is also lying to its own server logs about what its traffic is, and
+# this SDK ships to third parties, so the lie propagated to every user of it.
+# All that is required is that a UA is SET, so urllib never falls back to its
+# default.
+USER_AGENT = "orphograph-python-sdk/0.1 (+https://orphograph.com)"
+
+
+class OrphographError(RuntimeError):
+    """Raised when the hosted service returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str, payload: Optional[dict] = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.payload = payload or {}
+
+
+def _normalise_base(server_url: str) -> str:
+    if not server_url:
+        raise ValueError("server_url is required")
+    return server_url.rstrip("/")
+
+
+def _build_headers(api_key: Optional[str], content_type: Optional[str]) -> dict:
+    headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+    if content_type is not None:
+        headers["Content-Type"] = content_type
+    if api_key:
+        headers["X-Orpho-Api-Key"] = api_key.strip()
+    return headers
+
+
+def _request(
+    method: str,
+    url: str,
+    *,
+    body: Optional[bytes] = None,
+    headers: Optional[dict] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    req = urllib.request.Request(url=url, data=body, method=method, headers=headers or {})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            status = resp.getcode()
+    except urllib.error.HTTPError as e:
+        raw = e.read() or b""
+        status = e.code
+        payload: dict = {}
+        try:
+            payload = json.loads(raw.decode("utf-8")) if raw else {}
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            payload = {"error": raw[:200].decode("utf-8", "replace")}
+        raise OrphographError(status, payload.get("error") or e.reason or "request failed", payload)
+    if not (200 <= status < 300):
+        raise OrphographError(status, "unexpected status")
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise OrphographError(status, f"invalid JSON response: {e}")
+
+
+def post_anchor_folder(
+    manifest: dict,
+    *,
+    server_url: str = DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+    client_label: Optional[str] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """POST a manifest to /api/anchor_folder.
+
+    Only the manifest (paths + per-file SHA-256 + leaf hashes + root) is
+    transmitted. File contents are not part of the payload.
+    """
+    base = _normalise_base(server_url)
+    payload: dict[str, Any] = {"manifest": manifest}
+    if client_label is not None:
+        payload["client_label"] = str(client_label)[:200]
+    body = json.dumps(payload).encode("utf-8")
+    headers = _build_headers(api_key, "application/json")
+    return _request("POST", base + "/api/anchor_folder", body=body, headers=headers, timeout=timeout)
+
+
+def get_verify_folder(
+    receipt_id: str,
+    *,
+    server_url: str = DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """GET /api/verify_folder/<receipt_id>."""
+    base = _normalise_base(server_url)
+    rid = urllib.parse.quote(receipt_id, safe="")
+    headers = _build_headers(api_key, None)
+    return _request("GET", f"{base}/api/verify_folder/{rid}", headers=headers, timeout=timeout)
+
+
+def get_inclusion_proof(
+    receipt_id: str,
+    rel_path: str,
+    *,
+    server_url: str = DEFAULT_SERVER_URL,
+    api_key: Optional[str] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """GET /api/inclusion_proof?receipt_id=<rid>&path=<rel_path>."""
+    base = _normalise_base(server_url)
+    qs = urllib.parse.urlencode({"receipt_id": receipt_id, "path": rel_path})
+    headers = _build_headers(api_key, None)
+    return _request("GET", f"{base}/api/inclusion_proof?{qs}", headers=headers, timeout=timeout)

orphograph/_merkle.py

@@ -0,0 +1,493 @@
+#!/usr/bin/env python3
+# AUTO-COPIED from server/merkle.py — keep in sync.
+# Source SHA-256 (server/merkle.py at copy time):
+#   e68c897382a41e5cb479d00af5fb31e8cb50a45490702ead82d03a25948a87f5
+# If the upstream file changes, recompute with:
+#   shasum -a 256 server/merkle.py
+# and update both this banner and this file. The SDK refuses to drift
+# silently from the server's reference implementation.
+"""merkle.py — RFC 6962-compliant Merkle tree for folder anchoring.
+
+The office uses this module to commit a whole folder of evidence to a single
+32-byte root, which is then submitted to OpenTimestamps the same way a single
+file hash is. Every file's path is bound into its leaf so that renaming a file
+changes the root — paths are evidence, not incidental metadata.
+
+Design notes (intentional, formal):
+
+  * Leaf:     SHA-256(0x00 || rel_path_utf8 || 0x00 || file_sha256)
+  * Internal: SHA-256(0x01 || left || right)
+  * Odd-level handling: the lone last node is PROMOTED to the next level
+    (RFC 6962). The tree never duplicates a node — duplication produces the
+    CVE-2012-2459 second-preimage ambiguity, which the office rejects.
+  * Algorithm tag: "orphograph-merkle-v1-rfc6962" — embedded in every manifest
+    so a future v2 can be distinguished without ambiguity.
+  * Streaming: files are hashed in 1 MiB chunks; no file is ever fully buffered.
+  * Empty folders are rejected. A single-file folder yields root == leaf hash.
+  * Symlinks are skipped (not followed). Hidden dotfiles are included by
+    default — evidentiary cases often need them.
+  * Paths are normalised to POSIX form (forward slashes) before sorting.
+    Unicode normalisation is NOT performed; the receipt is committed as-is
+    in NFC by convention. This is a documented v1 limitation.
+
+This module is MIT licensed and uses only the Python standard library.
+"""
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Iterable
+
+ALGORITHM = "orphograph-merkle-v1-rfc6962"
+VERSION = 1
+CHUNK_SIZE = 1024 * 1024  # 1 MiB
+
+LEAF_PREFIX = b"\x00"
+INTERNAL_PREFIX = b"\x01"
+
+# ── scope: the intake record ────────────────────────────────────────
+# A manifest says what WAS captured. It has never said what was deliberately
+# left out, who captured it, or under what instruction — so the first question
+# a hostile reader asks ("what did you omit?") could only be answered by the
+# holder's memory, months later, which is not evidence.
+#
+# `scope` is strictly ADDITIVE metadata. It is NOT an input to the Merkle root
+# — the root derives from the leaves alone — so adding it cannot invalidate any
+# previously issued receipt, and VERSION is deliberately NOT bumped.
+#
+# LIMIT, stated plainly: scope_hex makes the block self-checksummed, so an
+# accidental or careless edit is detectable inside the manifest. It does NOT
+# make scope tamper-evident against a determined party, because the anchored
+# value is still root_hex alone. Binding scope into the anchor is a separate
+# change to the anchoring contract and is not claimed here.
+SCOPE_FIELDS = (
+    "exclude",
+    "exclude_source",
+    "captured_at",
+    "captured_by",
+    "instruction",
+    "omitted_note",
+)
+
+
+def _canonical_scope_bytes(scope: dict) -> bytes:
+    """Deterministic serialisation of the scope block, minus its own hash."""
+    payload = {k: scope[k] for k in SCOPE_FIELDS if scope.get(k) not in (None, "")}
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def scope_hex(scope: dict) -> str:
+    """SHA-256 over the canonical scope block, excluding ``scope_hex``."""
+    return hashlib.sha256(_canonical_scope_bytes(scope)).hexdigest()
+
+
+def build_scope(
+    *,
+    exclude: list[str],
+    exclude_source: str = "custom",
+    captured_at: str | None = None,
+    captured_by: str | None = None,
+    instruction: str | None = None,
+    omitted_note: str | None = None,
+) -> dict:
+    """Assemble a scope block and stamp it with its own checksum."""
+    scope: dict = {
+        "exclude": list(exclude),
+        "exclude_source": exclude_source,
+    }
+    for key, value in (("captured_at", captured_at), ("captured_by", captured_by),
+                       ("instruction", instruction), ("omitted_note", omitted_note)):
+        if value not in (None, ""):
+            scope[key] = str(value)
+    scope["scope_hex"] = scope_hex(scope)
+    return scope
+
+# Default deny-list — files the office considers incidental to the evidence
+# itself (OS detritus, editor backups, build caches). The caller may supply a
+# different list; supplying [] disables exclusion entirely.
+DEFAULT_EXCLUDE = (
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    ".git/*",
+    "node_modules/*",
+    "__pycache__/*",
+    "*.tmp",
+    "*.swp",
+    "*.swo",
+    "~$*",
+)
+
+
+def _matches_any(rel_path: str, patterns: Iterable[str]) -> bool:
+    """Return True if rel_path is excluded by any glob pattern.
+
+    A pattern with no slash matches against the basename only (so ``.DS_Store``
+    catches the file at any depth). A pattern with a slash matches against the
+    full POSIX relative path (so ``.git/*`` catches everything inside .git).
+    """
+    name = rel_path.rsplit("/", 1)[-1]
+    for pat in patterns:
+        if "/" in pat:
+            if fnmatch.fnmatch(rel_path, pat):
+                return True
+            # Also match if any ancestor segment is the prefix dir.
+            # e.g. ``.git/*`` should also catch ``.git/sub/file``.
+            prefix = pat.rstrip("*").rstrip("/")
+            if prefix and (rel_path == prefix or rel_path.startswith(prefix + "/")):
+                return True
+        else:
+            if fnmatch.fnmatch(name, pat):
+                return True
+    return False
+
+
+def _hash_file(path: Path) -> tuple[bytes, int]:
+    """Stream a file through SHA-256 in 1 MiB chunks. Returns (digest, size)."""
+    h = hashlib.sha256()
+    size = 0
+    with path.open("rb") as f:
+        while True:
+            chunk = f.read(CHUNK_SIZE)
+            if not chunk:
+                break
+            h.update(chunk)
+            size += len(chunk)
+    return h.digest(), size
+
+
+def _leaf_hash(rel_path: str, file_digest: bytes) -> bytes:
+    """Compute the RFC 6962-style leaf hash with the relative path bound in."""
+    if len(file_digest) != 32:
+        raise ValueError("file_digest must be exactly 32 bytes")
+    return hashlib.sha256(
+        LEAF_PREFIX + rel_path.encode("utf-8") + b"\x00" + file_digest
+    ).digest()
+
+
+def _internal_hash(left: bytes, right: bytes) -> bytes:
+    """Compute the RFC 6962-style internal node hash."""
+    if len(left) != 32 or len(right) != 32:
+        raise ValueError("internal hash inputs must be 32 bytes")
+    return hashlib.sha256(INTERNAL_PREFIX + left + right).digest()
+
+
+def _walk_folder(
+    root: Path, exclude: Iterable[str]
+) -> list[tuple[str, Path]]:
+    """Walk root and return [(rel_posix_path, absolute_path), ...] sorted.
+
+    Symlinks are skipped (not followed). The sort is by the UTF-8 byte order
+    of the POSIX relative path, which is the canonical order the office uses
+    when building the tree.
+    """
+    entries: list[tuple[str, Path]] = []
+    root = root.resolve()
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        # Skip symlinked directories — os.walk would otherwise descend into
+        # them with followlinks=True. With followlinks=False they appear in
+        # dirnames but are not recursed into. We additionally filter them
+        # out so they aren't reported as files either.
+        dirnames[:] = [d for d in dirnames if not (Path(dirpath) / d).is_symlink()]
+        for fname in filenames:
+            abs_path = Path(dirpath) / fname
+            if abs_path.is_symlink():
+                continue
+            if not abs_path.is_file():
+                continue
+            rel = abs_path.relative_to(root)
+            # Normalise to POSIX (forward slashes) regardless of host OS.
+            rel_posix = rel.as_posix().replace("\\", "/")
+            if _matches_any(rel_posix, exclude):
+                continue
+            entries.append((rel_posix, abs_path))
+    # UTF-8 byte order on the POSIX path string.
+    entries.sort(key=lambda e: e[0].encode("utf-8"))
+    return entries
+
+
+def _build_levels(leaves: list[bytes]) -> list[list[bytes]]:
+    """Build the full set of tree levels, bottom-up, RFC 6962 promotion.
+
+    Returns a list of levels where level[0] is the leaves and level[-1] is
+    the single-node root. For a single leaf, returns ``[[leaf]]``.
+    """
+    if not leaves:
+        raise ValueError("cannot build a tree with no leaves")
+    levels: list[list[bytes]] = [list(leaves)]
+    while len(levels[-1]) > 1:
+        cur = levels[-1]
+        nxt: list[bytes] = []
+        i = 0
+        while i + 1 < len(cur):
+            nxt.append(_internal_hash(cur[i], cur[i + 1]))
+            i += 2
+        if i < len(cur):
+            # Odd remainder: PROMOTE the lone node unchanged.
+            nxt.append(cur[i])
+        levels.append(nxt)
+    return levels
+
+
+class MerkleTree:
+    """An immutable Merkle tree over a sorted list of (path, file_hash) leaves.
+
+    Instances are constructed from a folder on disk via :meth:`from_folder` or
+    from a previously emitted manifest via :meth:`from_manifest`. The tree
+    object holds the leaves, the per-leaf metadata (path, size, file hash),
+    and every internal level so inclusion proofs can be served without
+    rebuilding.
+    """
+
+    __slots__ = ("_leaves_meta", "_levels", "_scope")
+
+    def __init__(self, leaves_meta: list[dict], levels: list[list[bytes]],
+                 scope: dict | None = None):
+        # Internal constructor — callers use the classmethods.
+        self._leaves_meta = leaves_meta
+        self._levels = levels
+        self._scope = dict(scope) if scope else None
+
+    # ------------------------------------------------------------------ build
+
+    @classmethod
+    def from_folder(
+        cls, root: Path, exclude: list[str] | None = None,
+        *,
+        captured_by: str | None = None,
+        instruction: str | None = None,
+        omitted_note: str | None = None,
+        captured_at: str | None = None,
+    ) -> "MerkleTree":
+        """Build a tree by walking ``root`` and streaming each file.
+
+        ``exclude`` defaults to the office's standard deny-list. Passing
+        ``[]`` disables exclusion entirely; passing a custom list replaces
+        the defaults (it does not extend them).
+
+        The remaining keyword arguments record the SCOPING DECISION — who
+        captured, under what instruction, and what was deliberately left out.
+        A hash set with no scoping record invites the obvious question in a
+        dispute ("what did you omit?"), and a manifest that cannot answer it
+        from its own contents makes the holder's memory part of the evidence.
+        All are optional; the effective exclude patterns are recorded whether
+        or not the caller supplies anything.
+
+        This does not affect ``root_hex``: the root derives from the leaves
+        alone, so scope is metadata ABOUT a tree, never an input to it.
+        """
+        root = Path(root)
+        if not root.is_dir():
+            raise ValueError(f"not a directory: {root}")
+        patterns = DEFAULT_EXCLUDE if exclude is None else tuple(exclude)
+        entries = _walk_folder(root, patterns)
+        if not entries:
+            raise ValueError("Empty folders are not supported in v1.")
+
+        leaves_meta: list[dict] = []
+        leaf_hashes: list[bytes] = []
+        for rel_path, abs_path in entries:
+            file_digest, size = _hash_file(abs_path)
+            leaf = _leaf_hash(rel_path, file_digest)
+            leaves_meta.append({
+                "path": rel_path,
+                "file_sha256_hex": file_digest.hex(),
+                "leaf_hex": leaf.hex(),
+                "size_bytes": size,
+            })
+            leaf_hashes.append(leaf)
+
+        levels = _build_levels(leaf_hashes)
+        scope = build_scope(
+            exclude=list(patterns),
+            exclude_source="default" if exclude is None else "custom",
+            captured_by=captured_by,
+            instruction=instruction,
+            omitted_note=omitted_note,
+            captured_at=captured_at,
+        )
+        return cls(leaves_meta, levels, scope)
+
+    @classmethod
+    def from_manifest(cls, manifest: dict) -> "MerkleTree":
+        """Reconstruct a tree from a manifest produced by :meth:`manifest`.
+
+        The reconstruction recomputes every internal node from the leaf
+        hashes in the manifest, then verifies that the recomputed root
+        matches the manifest's ``root_hex``. A mismatch raises ValueError —
+        the office will not certify a manifest whose root does not derive
+        from its own leaves.
+        """
+        if not isinstance(manifest, dict):
+            raise ValueError("manifest must be a dict")
+        if manifest.get("algorithm") != ALGORITHM:
+            raise ValueError(f"unsupported algorithm: {manifest.get('algorithm')!r}")
+        if manifest.get("version") != VERSION:
+            raise ValueError(f"unsupported version: {manifest.get('version')!r}")
+        leaves = manifest.get("leaves")
+        if not isinstance(leaves, list) or not leaves:
+            raise ValueError("manifest leaves must be a non-empty list")
+
+        leaves_meta: list[dict] = []
+        leaf_hashes: list[bytes] = []
+        for entry in leaves:
+            path = entry["path"]
+            file_hex = entry["file_sha256_hex"]
+            leaf_hex = entry["leaf_hex"]
+            size = int(entry["size_bytes"])
+            file_digest = bytes.fromhex(file_hex)
+            recomputed = _leaf_hash(path, file_digest)
+            if recomputed.hex() != leaf_hex:
+                raise ValueError(
+                    f"manifest leaf hash mismatch for {path!r}: "
+                    "the stored leaf does not derive from the stored file hash"
+                )
+            leaves_meta.append({
+                "path": path,
+                "file_sha256_hex": file_hex,
+                "leaf_hex": leaf_hex,
+                "size_bytes": size,
+            })
+            leaf_hashes.append(recomputed)
+
+        levels = _build_levels(leaf_hashes)
+        root_hex_expected = manifest.get("root_hex")
+        if levels[-1][0].hex() != root_hex_expected:
+            raise ValueError("manifest root_hex does not match recomputed root")
+
+        # Scope is optional: manifests issued before it existed carry none, and
+        # must keep verifying unchanged. When present it is checked against its
+        # own recorded hash so a careless edit does not pass silently.
+        scope = manifest.get("scope")
+        if scope is not None:
+            if not isinstance(scope, dict):
+                raise ValueError("manifest scope must be an object")
+            recorded = scope.get("scope_hex")
+            if recorded is not None and recorded != scope_hex(scope):
+                raise ValueError(
+                    "manifest scope_hex does not match the scope block it describes"
+                )
+        return cls(leaves_meta, levels, scope)
+
+    # --------------------------------------------------------------- accessors
+
+    def root(self) -> bytes:
+        """Return the 32-byte root of the tree."""
+        return self._levels[-1][0]
+
+    def root_hex(self) -> str:
+        """Return the root as 64 lowercase hex characters."""
+        return self.root().hex()
+
+    def scope(self) -> dict | None:
+        """The intake record, or None for a tree built without one."""
+        return dict(self._scope) if self._scope else None
+
+    def exclude_patterns(self) -> list[str] | None:
+        """The exclude patterns this tree was built with, if recorded.
+
+        This is what makes verification self-sufficient: a verifier reads the
+        patterns from the manifest instead of requiring the caller to remember
+        which list was used at capture time, months earlier, possibly on a
+        different machine.
+        """
+        if not self._scope:
+            return None
+        got = self._scope.get("exclude")
+        return list(got) if isinstance(got, list) else None
+
+    def manifest(self) -> dict:
+        """Return a JSON-serialisable manifest describing the tree."""
+        out = {
+            "algorithm": ALGORITHM,
+            "version": VERSION,
+            "root_hex": self.root_hex(),
+            "leaves": [dict(m) for m in self._leaves_meta],
+        }
+        # Additive and optional: a manifest emitted before scope existed is
+        # still valid, and one emitted now is still readable by an old verifier
+        # that ignores unknown keys.
+        if self._scope:
+            out["scope"] = dict(self._scope)
+        return out
+
+    # --------------------------------------------------------------- proofs
+
+    def inclusion_proof(self, file_path: str) -> list[tuple[str, str]]:
+        """Return the inclusion proof for ``file_path`` (POSIX relative).
+
+        The proof is a list of (direction, sibling_hex) tuples ordered from
+        the leaf upward. ``direction == "L"`` means the sibling sits on the
+        LEFT of the running hash at that level; ``"R"`` means it sits on the
+        right. A promoted (lone-last) node contributes no proof step at that
+        level — there is no sibling to record.
+        """
+        idx = None
+        for i, m in enumerate(self._leaves_meta):
+            if m["path"] == file_path:
+                idx = i
+                break
+        if idx is None:
+            raise ValueError(f"path not in tree: {file_path!r}")
+
+        proof: list[tuple[str, str]] = []
+        for level in self._levels[:-1]:
+            # Was this node the lone-last (promoted) node at this level?
+            if idx == len(level) - 1 and len(level) % 2 == 1:
+                # No sibling — promote to next level with the same index/2.
+                idx = idx // 2
+                continue
+            if idx % 2 == 0:
+                # Current is left, sibling is on the right.
+                sibling = level[idx + 1]
+                proof.append(("R", sibling.hex()))
+            else:
+                # Current is right, sibling is on the left.
+                sibling = level[idx - 1]
+                proof.append(("L", sibling.hex()))
+            idx = idx // 2
+        return proof
+
+    @staticmethod
+    def verify_inclusion(
+        file_hash: bytes,
+        rel_path: str,
+        proof: list[tuple[str, str]],
+        root: bytes,
+    ) -> bool:
+        """Verify a file's inclusion against a known root.
+
+        ``file_hash`` is the raw SHA-256 of the file content (not the leaf).
+        ``rel_path`` is the POSIX path under which the file was committed.
+        ``proof`` is the list of (direction, sibling_hex) tuples returned by
+        :meth:`inclusion_proof`. ``root`` is the 32-byte tree root.
+        """
+        try:
+            current = _leaf_hash(rel_path, file_hash)
+        except ValueError:
+            return False
+        if not isinstance(root, (bytes, bytearray)) or len(root) != 32:
+            return False
+        for step in proof:
+            if (
+                not isinstance(step, tuple)
+                or len(step) != 2
+                or step[0] not in ("L", "R")
+            ):
+                return False
+            direction, sibling_hex = step
+            try:
+                sibling = bytes.fromhex(sibling_hex)
+            except ValueError:
+                return False
+            if len(sibling) != 32:
+                return False
+            if direction == "L":
+                current = _internal_hash(sibling, current)
+            else:
+                current = _internal_hash(current, sibling)
+        return current == bytes(root)

orphograph-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: orphograph
+Version: 0.1.0
+Summary: Anchor folders to Bitcoin via the Orphograph hosted service. File contents stay on the local machine.
+Author: the Orphograph contributors
+License: MIT License
+        
+        Copyright (c) 2026 the Orphograph contributors
+        
+        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.
+        
+Project-URL: Homepage, https://orphograph.com
+Project-URL: Documentation, https://orphograph.com/method/architecture.html
+Keywords: bitcoin,opentimestamps,merkle,notarization,provenance
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# orphograph
+
+A Python SDK for anchoring a local folder to the Bitcoin chain through the
+[Orphograph](https://orphograph.com) hosted service.
+
+- License: MIT
+- Python: 3.9 or newer
+- Runtime dependencies: Python standard library only
+
+## Privacy contract
+
+The library does not transmit file contents. For each file the SDK reads
+the bytes locally, streams them through SHA-256 in one megabyte chunks,
+and commits the digest into an RFC 6962 Merkle leaf bound to the file's
+POSIX relative path. Only the resulting manifest (paths, per-file digests,
+leaf hashes, and the 32-byte root) is sent across the network. The
+verification path is symmetric: the root is recomputed locally from the
+folder on disk and compared to the root recorded in the receipt.
+
+The Merkle module is a verbatim copy of the server's reference
+implementation, carrying the source SHA-256 in its header so divergence
+from the canonical algorithm is immediately visible.
+
+## Install
+
+```
+pip install orphograph
+```
+
+## Anchor a folder
+
+```python
+from orphograph import anchor_folder
+
+result = anchor_folder("/path/to/folder")
+# {
+#   "receipt_id": "...",
+#   "root_hex": "...",
+#   "leaf_count": 42,
+#   "calendars_ok": 5,
+#   "calendars_total": 5,
+# }
+```
+
+Optional arguments:
+
+| Argument       | Purpose                                                  |
+| -------------- | -------------------------------------------------------- |
+| `server_url`   | Base URL of the service (default `https://orphograph.com`). |
+| `api_key`      | Sent as `X-Orpho-Api-Key` when present.                  |
+| `client_label` | Short free-form label persisted with the receipt.        |
+| `exclude`      | Sequence of `fnmatch` patterns. `None` selects the default deny list (OS detritus, editor backups, build caches). Passing `[]` disables exclusion. |
+
+## Verify a folder
+
+```python
+from orphograph import verify_folder
+
+ok = verify_folder("/path/to/folder", receipt_id="...")
+```
+
+The folder is walked locally, the Merkle root is recomputed, and the SDK
+returns `True` only if the recomputed root equals the root recorded in
+the receipt's manifest.
+
+## Inclusion proofs
+
+A folder receipt can be queried for a proof that a single file belonged
+to the anchored tree. The proof is verified locally; no further network
+call is required to confirm it.
+
+```python
+from orphograph import inclusion_proof, verify_inclusion
+
+proof = inclusion_proof(receipt_id="...", path="sub/photo.jpg")
+ok = verify_inclusion(
+    file_path="/path/to/sub/photo.jpg",
+    rel_path="sub/photo.jpg",
+    proof=proof["proof"],
+    root_hex=proof["root_hex"],
+)
+```
+
+## Command line
+
+The package installs an `orphograph` console script and is also runnable
+as a module.
+
+```
+python -m orphograph anchor /path/to/folder
+python -m orphograph verify /path/to/folder <receipt_id>
+python -m orphograph inclusion-proof <receipt_id> <posix/rel/path>
+```
+
+Each subcommand writes a single line of JSON to standard output. The
+`verify` subcommand exits with status `0` on a match and `1` on a
+mismatch.
+
+Environment variables:
+
+| Variable           | Purpose                                       |
+| ------------------ | --------------------------------------------- |
+| `ORPHO_SERVER_URL` | Default base URL.                             |
+| `ORPHO_API_KEY`    | Default API key (sent as `X-Orpho-Api-Key`).  |
+
+## Algorithm
+
+The Merkle construction is RFC 6962 with a domain-separated leaf
+(`0x00 || rel_path_utf8 || 0x00 || file_sha256`) and a domain-separated
+internal node (`0x01 || left || right`). Odd-level remainders are
+promoted, never duplicated, to avoid the second-preimage ambiguity of
+the duplicate-last construction. The algorithm tag
+`orphograph-merkle-v1-rfc6962` is embedded in every manifest.
+
+## License
+
+MIT. See `LICENSE`.

orphograph-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+orphograph/__init__.py,sha256=KRtS14L18yhuTskbh_N_uG7m27wMwxiyWDXOy_4vNtM,6243
+orphograph/__main__.py,sha256=ojo5MJFMfWYDSnU5bzsHD9aMAFOrsaaNBPPYsaaMerE,128
+orphograph/_cli.py,sha256=hf7WVDf2vpWUS-OTe9DqTqjUYnJ88Q5h_8486Bfgdbc,4684
+orphograph/_client.py,sha256=wXt0122pvVL6I4GX7CXdMo7d2s9RYAUrf2ilFsBMU9E,5613
+orphograph/_merkle.py,sha256=uNFfUPA1OdByhriNxeP7S6-aY_pD1lz73zWfRbqOx0o,19939
+orphograph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orphograph-0.1.0.dist-info/licenses/LICENSE,sha256=AFKEEvMxB7rzLplVIBRip-2usNwTa6NkKSmoKYpfbpM,1084
+orphograph-0.1.0.dist-info/METADATA,sha256=Rnt_qOWJekfD3iM4RfoMRJPex3neheZPIedtpFM65qU,5955
+orphograph-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+orphograph-0.1.0.dist-info/entry_points.txt,sha256=b31Ke7uY6DQ-HiQda-uSdAgKtVd3xvVcV4QtDyXeriE,52
+orphograph-0.1.0.dist-info/top_level.txt,sha256=A_gaRwagHQPhdQry16YNuBGHkKLUhzihvHthpxNiclc,11
+orphograph-0.1.0.dist-info/RECORD,,

orphograph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

orphograph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orphograph = orphograph._cli:main

orphograph-0.1.0.dist-info/licenses/LICENSE

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

orphograph-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+orphograph