orphograph 0.1.0__tar.gz

orphograph-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/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-0.1.0/orphograph/__main__.py

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

orphograph-0.1.0/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())