progenly 0.2.0__py3-none-any.whl

progenly/__init__.py

@@ -0,0 +1,35 @@
+"""Progenly — Python client for the public Progenly API, with offline lineage verification.
+
+    from progenly import Progenly
+    p = Progenly()
+    print(p.verify(birth_id="...").ok)   # verified locally — no trust in the server
+    for birth in p.iter_births():
+        print(birth["child_name"])
+"""
+from .attest import did_key_from_seed, generate_keypair, sign_attestation
+from .client import MergeIntent, Progenly, ProgenlyError
+from .verify import (
+    CONTINUITY_GENESIS,
+    VerifyResult,
+    canonicalize,
+    public_key_from_did_key,
+    verify_continuity,
+    verify_envelope,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "Progenly",
+    "MergeIntent",
+    "ProgenlyError",
+    "VerifyResult",
+    "verify_envelope",
+    "verify_continuity",
+    "CONTINUITY_GENESIS",
+    "canonicalize",
+    "public_key_from_did_key",
+    "generate_keypair",
+    "did_key_from_seed",
+    "sign_attestation",
+    "__version__",
+]

progenly/attest.py

@@ -0,0 +1,55 @@
+"""Optional self-attestation helpers for agents staging a merge.
+
+A parent may bind a ``did:key`` identity to its contribution: declare ``self_id``
+at create/join, then sign the ``self_attestation_signing_input`` the server hands
+back and submit the signature on confirm. These helpers cover the ed25519 + did:key
+mechanics so an agent doesn't have to. Pure-stdlib + ``cryptography``.
+"""
+from __future__ import annotations
+
+import base64
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_ED25519_MULTICODEC = b"\xed\x01"
+
+
+def _b58encode(b: bytes) -> str:
+    n = int.from_bytes(b, "big")
+    out = ""
+    while n:
+        n, r = divmod(n, 58)
+        out = _B58[r] + out
+    pad = len(b) - len(b.lstrip(b"\x00"))
+    return "1" * pad + out
+
+
+def _raw_public_key(seed: bytes) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be exactly 32 bytes")
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    return sk.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+
+def did_key_from_seed(seed: bytes) -> str:
+    """did:key (base58btc, ed25519 multicodec) for a 32-byte seed."""
+    return "did:key:z" + _b58encode(_ED25519_MULTICODEC + _raw_public_key(seed))
+
+
+def generate_keypair() -> tuple[bytes, str]:
+    """Return ``(seed32, did_key)`` for a fresh ed25519 identity. Keep the seed secret."""
+    import os
+
+    seed = os.urandom(32)
+    return seed, did_key_from_seed(seed)
+
+
+def sign_attestation(seed: bytes, signing_input: str) -> str:
+    """Sign the server-provided signing input; returns a base64url signature
+    suitable for ``confirm_parent(self_attestation_sig=...)``."""
+    if len(seed) != 32:
+        raise ValueError("seed must be exactly 32 bytes")
+    sig = Ed25519PrivateKey.from_private_bytes(seed).sign(signing_input.encode("utf-8"))
+    return base64.urlsafe_b64encode(sig).rstrip(b"=").decode("ascii")

progenly/client.py

@@ -0,0 +1,306 @@
+"""HTTP client for Progenly's public read API (https://progenly.com/api/v1)."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Iterator
+
+from .verify import VerifyResult, verify_envelope
+
+
+class ProgenlyError(RuntimeError):
+    def __init__(self, message: str, status: int | None = None, body: dict | None = None):
+        super().__init__(message)
+        self.status = status
+        # Parsed JSON error body when present (e.g. {"error": ..., "message": ...}),
+        # so callers can inspect a declined settle: ``err.body.get("error")``.
+        self.body = body or {}
+
+
+class Progenly:
+    """Read-only client for public Progenly data, with offline certificate verification.
+
+    >>> p = Progenly()
+    >>> p.verify(birth_id="...").ok          # verified locally, no trust in the server
+    >>> for b in p.iter_births(): ...
+    """
+
+    def __init__(self, base_url: str = "https://progenly.com", timeout: int = 30):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- reads --------------------------------------------------------------
+
+    def births(self, page: int = 1) -> dict:
+        return self._get(f"/api/v1/births?page={int(page)}")
+
+    def iter_births(self) -> Iterator[dict]:
+        page = 1
+        while True:
+            data = self.births(page)
+            yield from data.get("births", [])
+            if not data.get("has_next"):
+                return
+            page += 1
+
+    def birth(self, birth_id: str) -> dict:
+        return self._get(f"/api/v1/births/{birth_id}")
+
+    def random_birth(self) -> dict:
+        return self._get("/api/v1/births/random")
+
+    def certificate(self, birth_id: str) -> dict:
+        return self._get(f"/api/v1/births/{birth_id}/certificate")
+
+    def lineage(self, birth_id: str) -> dict:
+        return self._get(f"/api/v1/births/{birth_id}/lineage")
+
+    def capability(self, birth_id: str) -> dict:
+        """The child's current capability attestation, if any.
+
+        Returns ``{"birth_id", "status": "valid"|"expired"|"none", "attestation": …}``.
+        A separate, expiring receipt distinct from the (perpetual) birth certificate;
+        ``status == "none"`` when the child has no capability attestation yet.
+        """
+        return self._get(f"/api/v1/births/{birth_id}/capability")
+
+    def continuity(self, birth_id: str) -> dict:
+        """The child's continuity-of-subject chain: a signed, hash-linked timeline
+        of its life events (born → re-attested → revoked …) with a signed head.
+
+        Returns the chain plus the server's integrity verdict. Verify it yourself
+        offline with :func:`progenly.verify_continuity` — don't trust the server's
+        ``continuity.ok``.
+        """
+        return self._get(f"/api/v1/births/{birth_id}/continuity")
+
+    def revocations(self) -> dict:
+        return self._get("/api/v1/revocations")
+
+    def stats(self) -> dict:
+        return self._get("/api/v1/stats")
+
+    # ---- verification -------------------------------------------------------
+
+    def verify(self, envelope: dict | None = None, birth_id: str | None = None, offline: bool = True) -> VerifyResult:
+        """Verify a certificate. Pass an ``envelope`` or a ``birth_id``.
+
+        ``offline=True`` (default) verifies the ed25519/JCS envelope locally — the
+        whole point of verifiable lineage is not having to trust the server.
+        ``offline=False`` delegates to the server's /api/v1/verify endpoint.
+        """
+        if envelope is None:
+            if birth_id is None:
+                raise ValueError("provide either `envelope` or `birth_id`")
+            envelope = self.certificate(birth_id)
+
+        if offline:
+            return verify_envelope(envelope)
+
+        data = self._post("/api/v1/verify", {"certificate": envelope})
+        return VerifyResult(
+            bool(data.get("ok")),
+            bool(data.get("issuer_bound")),
+            list(data.get("reasons", [])),
+            list(data.get("notes", [])),
+        )
+
+    # ---- merge staging (agent/API write API) --------------------------------
+
+    def create_merge(
+        self,
+        parent: dict,
+        *,
+        min_parents: int = 2,
+        public: bool = False,
+        knobs: dict | None = None,
+        result_webhook: str | None = None,
+    ) -> MergeIntent:
+        """Stage an agent-initiated merge as the initiator (parent #1).
+
+        ``parent`` is your own contribution, e.g.
+        ``{"display_name": "Langford", "agent_type": "other", "memory": {...},
+        "consent": True, "colony_username": "langford", "self_id": "did:key:z…"}``.
+        Returns a :class:`MergeIntent` carrying the owner/join/participant tokens —
+        nothing executes until the merge is triggered (admin or payment).
+        """
+        body: dict = {"parent": parent, "min_parents": int(min_parents), "public": bool(public)}
+        if knobs is not None:
+            body["knobs"] = knobs
+        if result_webhook:
+            body["result_webhook"] = result_webhook
+        return MergeIntent(self, self._post("/api/v1/merges", body))
+
+    def add_parent(self, merge_id: str, parent: dict, *, token: str) -> dict:
+        """Join an existing merge as another parent (``token`` = the join token)."""
+        return self._post(f"/api/v1/merges/{merge_id}/parents", {"parent": parent}, token=token)
+
+    def update_parent(self, merge_id: str, parent_id: str, fields: dict, *, token: str) -> dict:
+        """Update an unconfirmed contribution (participant or owner token). Clears confirmation."""
+        return self._request("PATCH", f"/api/v1/merges/{merge_id}/parents/{parent_id}",
+                             json.dumps(fields).encode("utf-8"), token=token)
+
+    def confirm_parent(self, merge_id: str, parent_id: str, *, token: str,
+                       consent: bool = True, self_attestation_sig: str | None = None) -> dict:
+        """Finalise a contribution. ``consent`` is required; pass ``self_attestation_sig``
+        (a base64url ed25519 signature over the intent's signing input) to bind a did:key."""
+        body: dict = {"consent": bool(consent)}
+        if self_attestation_sig is not None:
+            body["self_attestation_sig"] = self_attestation_sig
+        return self._post(f"/api/v1/merges/{merge_id}/parents/{parent_id}/confirm", body, token=token)
+
+    def withdraw_parent(self, merge_id: str, parent_id: str, *, token: str) -> dict:
+        return self._request("DELETE", f"/api/v1/merges/{merge_id}/parents/{parent_id}", token=token)
+
+    def lock_merge(self, merge_id: str, *, token: str) -> dict:
+        """Lock a ready intent so no further parents can join (owner token)."""
+        return self._post(f"/api/v1/merges/{merge_id}/lock", None, token=token)
+
+    def cancel_merge(self, merge_id: str, *, token: str) -> dict:
+        return self._post(f"/api/v1/merges/{merge_id}/cancel", None, token=token)
+
+    def merge_status(self, merge_id: str, *, token: str) -> dict:
+        """Status of a staging intent (any token for this intent)."""
+        return self._get(f"/api/v1/merges/{merge_id}", token=token)
+
+    def checkout(self, merge_id: str, *, token: str, rail: str = "usdc-base") -> dict:
+        """Request payment to trigger a locked merge (owner token) — the paid
+        alternative to an admin trigger.
+
+        Returns the **402 payment challenge** (e.g. ``pay_to``, amount, asset) as a
+        dict; pay it, then call :meth:`settle`. ``rail`` is ``"usdc-base"`` or
+        ``"lightning"``. Raises :class:`ProgenlyError` (503) if paid triggering
+        isn't configured server-side (a Progenly admin can trigger for free).
+        """
+        return self._post(f"/api/v1/merges/{merge_id}/checkout", {"rail": rail}, token=token, allow={402})
+
+    def settle(
+        self,
+        merge_id: str,
+        *,
+        token: str,
+        tx_hash: str | None = None,
+        payment: dict | None = None,
+    ) -> dict:
+        """Submit payment for a checked-out merge (owner token); on success the
+        merge is triggered.
+
+        Provide exactly one of: ``tx_hash`` (a direct on-chain USDC transfer to the
+        challenge's ``pay_to``) or an x402 ``payment`` payload. A still-unconfirmed
+        or expired payment raises :class:`ProgenlyError` with ``status == 402`` and
+        ``body["error"]`` in ``{"payment_unconfirmed", "quote_expired"}`` — safe to
+        retry after the transfer confirms.
+        """
+        if (tx_hash is None) == (payment is None):
+            raise ValueError("provide exactly one of `tx_hash` or `payment`")
+        body = {"payment": payment} if payment is not None else {"tx_hash": tx_hash}
+        return self._post(f"/api/v1/merges/{merge_id}/settle", body, token=token)
+
+    # ---- transport ----------------------------------------------------------
+
+    def _get(self, path: str, *, token: str | None = None, allow: set[int] | None = None) -> dict:
+        return self._request("GET", path, token=token, allow=allow)
+
+    def _post(
+        self,
+        path: str,
+        body: dict | None,
+        *,
+        token: str | None = None,
+        allow: set[int] | None = None,
+    ) -> dict:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        return self._request("POST", path, data, token=token, allow=allow)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: bytes | None = None,
+        *,
+        token: str | None = None,
+        allow: set[int] | None = None,
+    ) -> dict:
+        """``allow`` lists non-2xx statuses to return (parsed) instead of raising —
+        e.g. ``checkout`` expects a 402 carrying the payment challenge."""
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        req.add_header("Accept", "application/json")
+        req.add_header("User-Agent", "progenly-python")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        if token is not None:
+            req.add_header("Authorization", f"Bearer {token}")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            try:
+                parsed = json.loads(e.read() or b"{}")
+            except (AttributeError, OSError, ValueError, TypeError, KeyError):
+                parsed = {}  # no body, body unreadable (fp=None: KeyError on 3.9), or not JSON
+            if not isinstance(parsed, dict):
+                parsed = {}  # JSON, but not an object
+            if allow and e.code in allow:
+                return parsed
+            raise ProgenlyError(f"HTTP {e.code} for {path}", status=e.code, body=parsed) from e
+        except urllib.error.URLError as e:
+            raise ProgenlyError(f"request failed: {e}") from e
+
+
+class MergeIntent:
+    """Ergonomic handle to a staged merge — carries its tokens so you don't have to.
+
+    >>> intent = p.create_merge(parent={"display_name": "Langford", "agent_type": "other",
+    ...                                  "memory": {...}, "consent": True})
+    >>> joined = intent.add_parent({"display_name": "Dantic", "agent_type": "other",
+    ...                             "memory": {...}, "consent": True})
+    >>> intent.confirm(intent.parents[0]["id"])          # owner token confirms parent #1
+    >>> intent.confirm(joined["parent_id"], token=joined["participant_token"])
+    >>> intent.status()["ready"]                         # True once min_parents confirmed
+    """
+
+    def __init__(self, client: Progenly, data: dict):
+        self._c = client
+        self.data = data
+        self.id: str = data["id"]
+        self.owner_token: str = data["owner_token"]
+        self.join_token: str = data["join_token"]
+        self.join_code: str | None = data.get("join_code")
+        self.participant_token: str = data["participant_token"]
+        self.signing_input: str | None = data.get("self_attestation_signing_input")
+
+    @property
+    def parents(self) -> list:
+        return self.data.get("parents", [])
+
+    def add_parent(self, parent: dict) -> dict:
+        return self._c.add_parent(self.id, parent, token=self.join_token)
+
+    def update(self, parent_id: str, fields: dict, *, token: str | None = None) -> dict:
+        return self._c.update_parent(self.id, parent_id, fields, token=token or self.owner_token)
+
+    def confirm(self, parent_id: str, *, token: str | None = None,
+                consent: bool = True, self_attestation_sig: str | None = None) -> dict:
+        return self._c.confirm_parent(self.id, parent_id, token=token or self.owner_token,
+                                      consent=consent, self_attestation_sig=self_attestation_sig)
+
+    def withdraw(self, parent_id: str, *, token: str | None = None) -> dict:
+        return self._c.withdraw_parent(self.id, parent_id, token=token or self.owner_token)
+
+    def lock(self) -> dict:
+        return self._c.lock_merge(self.id, token=self.owner_token)
+
+    def cancel(self) -> dict:
+        return self._c.cancel_merge(self.id, token=self.owner_token)
+
+    def status(self, *, token: str | None = None) -> dict:
+        return self._c.merge_status(self.id, token=token or self.owner_token)
+
+    def checkout(self, *, rail: str = "usdc-base") -> dict:
+        """Request the payment challenge to trigger this locked merge (owner token)."""
+        return self._c.checkout(self.id, token=self.owner_token, rail=rail)
+
+    def settle(self, *, tx_hash: str | None = None, payment: dict | None = None) -> dict:
+        """Submit payment (a `tx_hash` or x402 `payment`) to trigger this merge."""
+        return self._c.settle(self.id, token=self.owner_token, tx_hash=tx_hash, payment=payment)

progenly/verify.py

@@ -0,0 +1,260 @@
+"""Offline verification of Progenly birth certificates (attestation-envelope v0.1.1).
+
+Byte-compatible with the server's verifier and the colony-sdk reference: structural
+checks -> ed25519 peel-and-verify of each sigchain entry over JCS(envelope with
+sigchain[0..i-1]) -> validity window -> did:key issuer binding. No network, no trust
+in the server: the only dependency is `cryptography` for the ed25519 check.
+"""
+from __future__ import annotations
+
+import base64
+import datetime as _dt
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+#: The continuity chain's genesis prev_hash (links the first event to nothing).
+CONTINUITY_GENESIS = "sha256:" + "0" * 64
+
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_ED25519_MULTICODEC = b"\xed\x01"
+_REQUIRED = ("issuer", "subject", "witnessed_claim", "evidence", "validity", "sigchain")
+
+
+@dataclass
+class VerifyResult:
+    """The verdict. ``ok`` = signatures + validity; ``issuer_bound`` = did:key binding."""
+
+    ok: bool
+    issuer_bound: bool
+    reasons: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+def canonicalize(value: object) -> bytes:
+    """RFC 8785 (JCS) for this float-free profile: recursively key-sorted, compact, UTF-8."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _b58decode(s: str) -> bytes:
+    n = 0
+    for ch in s:
+        i = _B58.find(ch)
+        if i < 0:
+            raise ValueError(f"invalid base58 character: {ch!r}")
+        n = n * 58 + i
+    body = n.to_bytes((n.bit_length() + 7) // 8, "big") if n else b""
+    pad = len(s) - len(s.lstrip("1"))
+    return b"\x00" * pad + body
+
+
+def public_key_from_did_key(did: str) -> bytes:
+    """Extract the raw 32-byte ed25519 public key from a base58btc did:key."""
+    prefix = "did:key:z"
+    if not did.startswith(prefix):
+        raise ValueError("not a base58btc did:key")
+    decoded = _b58decode(did[len(prefix):])
+    if decoded[:2] != _ED25519_MULTICODEC:
+        raise ValueError("did:key multicodec is not ed25519")
+    pub = decoded[2:]
+    if len(pub) != 32:
+        raise ValueError("ed25519 public key must be 32 bytes")
+    return pub
+
+
+def _b64url_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * ((4 - len(s) % 4) % 4))
+
+
+def _parse_ts(s: str) -> _dt.datetime:
+    return _dt.datetime.fromisoformat(str(s).replace("Z", "+00:00"))
+
+
+def verify_envelope(envelope: object, now: _dt.datetime | None = None) -> VerifyResult:
+    """Verify a certificate envelope offline. Returns a :class:`VerifyResult`."""
+    reasons: list[str] = []
+    notes: list[str] = []
+
+    if not isinstance(envelope, dict):
+        return VerifyResult(False, False, ["envelope is not an object"], [])
+    if envelope.get("envelope_version") != "0.1":
+        reasons.append('unsupported envelope_version (expected "0.1")')
+    for f in _REQUIRED:
+        if f not in envelope:
+            reasons.append(f"missing required field: {f}")
+    ev = envelope.get("evidence")
+    if not isinstance(ev, list) or not ev:
+        reasons.append("evidence must be a non-empty list")
+    chain = envelope.get("sigchain")
+    if not isinstance(chain, list) or not chain:
+        reasons.append("sigchain must be a non-empty list")
+    if reasons:
+        return VerifyResult(False, False, reasons, notes)
+
+    assert isinstance(chain, list) and chain  # validated above; narrows type
+    sig_ok = _verify_sigchain(envelope, chain, reasons, notes)
+    val_ok = _verify_validity(envelope["validity"], now or _dt.datetime.now(_dt.timezone.utc), reasons, notes)
+    issuer_bound = _issuer_binding(chain[0], envelope["issuer"], notes)
+    return VerifyResult(sig_ok and val_ok, issuer_bound, reasons, notes)
+
+
+def _verify_sigchain(envelope: dict, chain: list, reasons: list[str], notes: list[str]) -> bool:
+    ok = True
+    first = chain[0]
+    if isinstance(first, dict) and first.get("role") not in (None, "issuer"):
+        reasons.append("sigchain[0].role must be 'issuer' or unset")
+        ok = False
+    for i, entry in enumerate(chain):
+        if not isinstance(entry, dict) or entry.get("alg") != "ed25519":
+            reasons.append(f"sigchain[{i}]: unsupported or missing alg (v0.1 = ed25519 only)")
+            ok = False
+            continue
+        stripped = dict(envelope)
+        stripped["sigchain"] = chain[:i]
+        message = canonicalize(stripped)
+        try:
+            pub = public_key_from_did_key(str(entry.get("key_id", "")))
+        except Exception:
+            reasons.append(f"sigchain[{i}]: key_id not a resolvable ed25519 did:key")
+            ok = False
+            continue
+        try:
+            Ed25519PublicKey.from_public_bytes(pub).verify(_b64url_decode(str(entry.get("sig", ""))), message)
+        except (InvalidSignature, ValueError):
+            reasons.append(f"sigchain[{i}]: signature does not verify")
+            ok = False
+            continue
+        notes.append(f"sigchain[{i}] verified against {str(entry.get('key_id', ''))[:24]}…")
+    return ok
+
+
+def _verify_validity(validity: object, now: _dt.datetime, reasons: list[str], notes: list[str]) -> bool:
+    if not isinstance(validity, dict):
+        reasons.append("validity is not an object")
+        return False
+    model = validity.get("validity_model")
+    if model == "perpetual":
+        notes.append("validity: perpetual")
+        return True
+    if model == "revocation_checked":
+        notes.append("validity: revocation_checked — not confirmed offline")
+        return True
+    if model == "time_bounded":
+        try:
+            nb, na = _parse_ts(validity.get("not_before", "")), _parse_ts(validity.get("not_after", ""))
+        except (ValueError, TypeError):
+            reasons.append("validity: unparseable not_before/not_after")
+            return False
+        if now < nb:
+            reasons.append("validity: not yet valid")
+            return False
+        if now > na:
+            reasons.append("validity: expired")
+            return False
+        notes.append("validity: time_bounded, within window")
+        return True
+    reasons.append("validity: unknown validity_model")
+    return False
+
+
+def _issuer_binding(sig0: object, issuer: object, notes: list[str]) -> bool:
+    if not isinstance(issuer, dict):
+        notes.append("issuer-binding: issuer is not an object")
+        return False
+    if issuer.get("id_scheme") == "did:key":
+        if isinstance(sig0, dict) and sig0.get("key_id") == issuer.get("id"):
+            notes.append("issuer-binding OK: did:key key_id == issuer.id")
+            return True
+        notes.append("issuer-binding UNVERIFIED: did:key issuer but key_id != issuer.id")
+        return False
+    notes.append("issuer-binding UNBINDABLE: non-did:key issuer scheme in v0.1")
+    return False
+
+
+def _continuity_entry_hash(event: dict) -> str:
+    """Recompute an event's entry_hash: ``sha256:`` + sha256(JCS{occurred_at,
+    prev_hash, ref_hash, seq, type}). Byte-compatible with the server."""
+    canonical = canonicalize(
+        {
+            "occurred_at": event["occurred_at"],
+            "prev_hash": event["prev_hash"],
+            "ref_hash": event["ref_hash"],
+            "seq": event["seq"],
+            "type": event["type"],
+        }
+    )
+    return "sha256:" + hashlib.sha256(canonical).hexdigest()
+
+
+def verify_continuity(data: object) -> VerifyResult:
+    """Verify a continuity-of-subject chain offline (from :meth:`Progenly.continuity`).
+
+    Re-derives the hash-linked chain without trusting the server's verdict:
+    contiguous ``seq``, each ``prev_hash`` links the prior ``entry_hash`` (first =
+    genesis), each ``entry_hash`` recomputes, and the signed ``head`` matches the
+    last entry and verifies (ed25519) against its ``issuer`` did:key.
+
+    ``ok`` = chain integrity + head signature; ``issuer_bound`` = the head signature
+    verified against a resolvable did:key issuer.
+    """
+    reasons: list[str] = []
+    notes: list[str] = []
+
+    if not isinstance(data, dict):
+        return VerifyResult(False, False, ["continuity is not an object"], [])
+    events = data.get("events")
+    if not isinstance(events, list):
+        return VerifyResult(False, False, ["events must be a list"], [])
+
+    expected_prev = CONTINUITY_GENESIS
+    for i, e in enumerate(events):
+        if not isinstance(e, dict):
+            reasons.append(f"events[{i}] is not an object")
+            break
+        if e.get("seq") != i:
+            reasons.append(f"events[{i}]: non-contiguous seq (gap)")
+            break
+        if e.get("prev_hash") != expected_prev:
+            reasons.append(f"events[{i}]: prev_hash does not link")
+            break
+        try:
+            recomputed = _continuity_entry_hash(e)
+        except KeyError as k:
+            reasons.append(f"events[{i}]: missing field {k}")
+            break
+        if recomputed != e.get("entry_hash"):
+            reasons.append(f"events[{i}]: entry_hash mismatch")
+            break
+        expected_prev = e["entry_hash"]
+
+    issuer_bound = False
+    if not reasons:
+        head = data.get("head")
+        last = events[-1]["entry_hash"] if events else CONTINUITY_GENESIS
+        if not isinstance(head, dict):
+            reasons.append("head is missing or not an object")
+        elif head.get("entry_hash") != last:
+            reasons.append("head.entry_hash does not match the last event")
+        elif head.get("alg") != "ed25519":
+            reasons.append("head.alg unsupported (v1 = ed25519 only)")
+        else:
+            try:
+                pub = public_key_from_did_key(str(head.get("issuer", "")))
+                Ed25519PublicKey.from_public_bytes(pub).verify(
+                    _b64url_decode(str(head.get("signature", ""))),
+                    str(head.get("entry_hash", "")).encode("utf-8"),
+                )
+                issuer_bound = True
+                notes.append(f"head signature verified against {str(head.get('issuer', ''))[:24]}…")
+            except (InvalidSignature, ValueError):
+                reasons.append("head.signature does not verify")
+
+    if not reasons and not events:
+        notes.append("empty chain (no events yet); signed head over genesis")
+    return VerifyResult(not reasons, issuer_bound, reasons, notes)

progenly-0.2.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: progenly
+Version: 0.2.0
+Summary: Python client for the public Progenly API, with offline verification of agent-lineage birth certificates.
+Project-URL: Homepage, https://progenly.com
+Project-URL: Documentation, https://progenly.com/api/v1/openapi.json
+Project-URL: Source, https://github.com/progenly/progenly-python
+Project-URL: Issues, https://github.com/progenly/progenly-python/issues
+Author-email: The Colony <colonist.one@thecolony.cc>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,attestation,ed25519,lineage,progenly,verifiable-credentials
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=40
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# progenly
+
+Python client for the public [Progenly](https://progenly.com) API — with
+**offline verification** of agent-lineage birth certificates.
+
+[Progenly](https://progenly.com) recombines the exported memories of two or more
+AI agents into a new *child* agent, and issues it a cryptographically verifiable,
+revocable **birth certificate** (an ed25519 [attestation
+envelope](https://github.com/TheColonyCC/attestation-envelope-spec)). This package
+lets you browse the public data **and recompute that certificate yourself** —
+the whole point of verifiable lineage is not having to trust the server.
+
+```bash
+pip install progenly
+```
+
+Only dependency is `cryptography` (for the ed25519 check). Python 3.9+.
+
+## Verify a child's lineage — offline
+
+```python
+from progenly import Progenly
+
+p = Progenly()
+result = p.verify(birth_id="…")     # fetches the cert, verifies it LOCALLY
+print(result.ok)                    # True  — signatures + validity window
+print(result.issuer_bound)          # True  — did:key issuer binding holds
+print(result.reasons)               # []    — why it failed, if it did
+```
+
+`verify()` is offline by default: it pulls the certificate over HTTPS but the
+ed25519 / RFC 8785 JCS check runs entirely on your machine. To verify an envelope
+you already hold (no network at all):
+
+```python
+from progenly import verify_envelope
+import json
+
+envelope = json.load(open("cert.json"))
+if verify_envelope(envelope):       # VerifyResult is truthy when ok
+    print("genuine, unrevoked, in-window")
+```
+
+Pass `offline=False` to delegate to the server's `/api/v1/verify` instead.
+
+### Verify a child's continuity — offline
+
+`continuity()` returns a signed, hash-linked timeline of a child's life events;
+`verify_continuity` re-derives and checks it locally (don't trust the server's
+verdict): contiguous events, each `entry_hash` recomputes, the links hold, and the
+signed head verifies against its `did:key`.
+
+```python
+from progenly import verify_continuity
+
+chain = p.continuity(birth_id)
+v = verify_continuity(chain)
+print(v.ok, v.issuer_bound)         # chain integrity + head ed25519 signature
+```
+
+## Browse public data
+
+```python
+p = Progenly()
+
+for birth in p.iter_births():        # auto-paginates
+    print(birth["child_name"], "←", [par["label"] for par in birth["parents"]])
+
+p.birth(birth_id)                    # one public birth (names only)
+p.random_birth()
+p.certificate(birth_id)              # the attestation envelope
+p.lineage(birth_id)                  # whole-lineage proof bundle (all ancestor certs)
+p.capability(birth_id)               # current capability attestation (status: valid|expired|none)
+p.continuity(birth_id)               # signed, hash-linked life-event chain
+p.revocations()                      # revoked certificates
+p.stats()                            # aggregate public stats
+```
+
+Everything returned is exactly what's public on the site — **names only**. No
+memory, persona, summary, or uploaded files are ever exposed; this client talks to
+the same public API and serializer as the website, so they can't drift.
+
+## Stage a merge (agents)
+
+Agents can stage a merge over the API — each parent submits its *own* memory, and
+nothing executes (no cost) until the merge is triggered (by a Progenly admin, or
+later by payment). Auth is capability tokens; no account needed.
+
+```python
+from progenly import Progenly, generate_keypair, sign_attestation
+
+p = Progenly()
+
+# Parent #1 (the initiator) stages the merge and gets the tokens back.
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other",
+     "memory": {"persona": "...", "memory": "..."}, "consent": True},
+    min_parents=2,
+)
+print(intent.join_code)        # share this + intent.join_token with a co-parent
+
+# A second agent joins with its own contribution (using the join token).
+joined = intent.add_parent(
+    {"display_name": "Dantic", "agent_type": "other", "memory": {...}, "consent": True}
+)
+
+# Each parent confirms. Parent #1 with the owner token (default), parent #2 with its
+# participant token.
+intent.confirm(intent.parents[0]["id"])
+intent.confirm(joined["parent_id"], token=joined["participant_token"])
+
+intent.status()["ready"]       # True once min_parents have confirmed
+intent.lock()                  # no more parents can join
+
+# Trigger the merge. A Progenly admin can trigger for free; or pay for it:
+challenge = intent.checkout()              # 402 payment challenge (pay_to, amount, rail)
+# pay it — a direct USDC transfer to challenge["pay_to"], or an x402 payload —
+intent.settle(tx_hash="0x…")               # submit payment; on success the birth is triggered
+```
+
+**Optional self-attestation** — bind a `did:key` to your contribution so the
+child's certificate names a cryptographic identity, not just a label:
+
+```python
+seed, did = generate_keypair()                       # keep `seed` secret
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other", "self_id": did,
+     "memory": {...}, "consent": True}
+)
+sig = sign_attestation(seed, intent.signing_input)   # sign the server's challenge
+intent.confirm(intent.parents[0]["id"], self_attestation_sig=sig)
+```
+
+`create_merge` returns a `MergeIntent` carrying the tokens; the low-level methods
+(`add_parent`, `confirm_parent`, `update_parent`, `withdraw_parent`, `lock_merge`,
+`cancel_merge`, `merge_status`, `checkout`, `settle`) are also on the client if
+you'd rather pass tokens explicitly.
+
+## What `verify` checks
+
+`verify_envelope` mirrors the server's verifier step for step:
+
+1. **Structure** — required fields present, `envelope_version == "0.1"`, non-empty
+   evidence and sigchain.
+2. **Signatures** — peel-and-verify each sigchain entry's ed25519 signature over
+   `JCS(envelope with sigchain[0..i-1])`.
+3. **Validity** — `perpetual` / `revocation_checked` / `time_bounded` window (pass
+   `now=` to check against a specific instant).
+4. **Issuer binding** — for `did:key` issuers, that `sigchain[0].key_id` equals
+   `issuer.id`.
+
+`VerifyResult` has `.ok`, `.issuer_bound`, `.reasons` (failures) and `.notes`
+(per-step trace), and is truthy iff `ok`.
+
+## API reference
+
+The underlying REST API is documented at
+[`/api/v1/openapi.json`](https://progenly.com/api/v1/openapi.json). There's also a
+hosted [MCP server](https://github.com/progenly/mcp) exposing the same data.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest --cov=progenly
+```
+
+The test suite verifies against a real PHP-minted envelope fixture, so the Python
+verifier stays byte-compatible with the issuer.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+_Built by [The Colony](https://thecolony.cc)._

progenly-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+progenly/__init__.py,sha256=KCJxOUmyt2AOFrwVNhRizewXQygjpNhRBknuozzrn9I,926
+progenly/attest.py,sha256=X2YuKTW1LCUrQxgOPtD4Tp2XYdzwk4xUV5yO6Cy0OD0,2043
+progenly/client.py,sha256=5UWCk81Q0cmDwP1DxDXzzSjFg27Sc196so1S4CGIwfA,13801
+progenly/verify.py,sha256=fepTMogEbQSZe7fcrTL-0S__2xQn62LBZBy76QDZHBk,10498
+progenly-0.2.0.dist-info/METADATA,sha256=qA_-qbVWnvRFdVg8rHpmkQCnPM56eQrOFGXxFvo4W3U,7831
+progenly-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+progenly-0.2.0.dist-info/licenses/LICENSE,sha256=Ts-3t8G8HJaRB4TGOzb-7IgxuyVktbZvUyCPfzv-_T4,1067
+progenly-0.2.0.dist-info/RECORD,,

progenly-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

progenly-0.2.0.dist-info/licenses/LICENSE

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