ratify-protocol 1.0.0a5__py3-none-any.whl

ratify_protocol/__init__.py

@@ -0,0 +1,209 @@
+"""Ratify Protocol v1 — Python reference SDK.
+
+A cryptographic trust protocol for human-agent and agent-agent interactions
+as agents start to transact. Every signature is hybrid Ed25519 + ML-DSA-65
+(FIPS 204): quantum-safe by design.
+
+Quickstart:
+
+    import asyncio
+    from ratify_protocol import (
+        generate_human_root, generate_agent,
+        DelegationCert, ProofBundle, VerifyOptions,
+        PROTOCOL_VERSION, SCOPE_MEETING_ATTEND,
+        issue_delegation, sign_challenge, generate_challenge,
+        derive_id, verify_bundle,
+    )
+
+    root, root_priv = generate_human_root()
+    agent, agent_priv = generate_agent("Alice's Assistant", "voice_agent")
+
+    cert = DelegationCert(
+        cert_id="cert-1", version=PROTOCOL_VERSION,
+        issuer_id=root.id, issuer_pub_key=root.public_key,
+        subject_id=agent.id, subject_pub_key=agent.public_key,
+        scope=[SCOPE_MEETING_ATTEND],
+        issued_at=0, expires_at=2000000000,
+        signature=None,  # filled by issue_delegation
+    )
+    issue_delegation(cert, root_priv)
+    # ... then agent builds a ProofBundle, verifier runs verify_bundle(bundle)
+
+See docs/EXPLAINED.md and docs/AGENT_TO_AGENT.md for full semantics.
+"""
+from .canonical import (
+    base64_standard_decode,
+    base64_standard_encode,
+    canonical_json,
+    hex_decode,
+    hex_encode,
+)
+from .crypto import (
+    chain_hash,
+    challenge_sign_bytes,
+    delegation_sign_bytes,
+    derive_id,
+    generate_agent,
+    generate_challenge,
+    generate_human_root,
+    generate_hybrid_keypair,
+    hybrid_keypair_from_seeds,
+    issue_delegation,
+    issue_key_rotation_statement,
+    issue_revocation_list,
+    issue_revocation_push,
+    issue_session_token,
+    issue_witness_entry,
+    key_rotation_sign_bytes,
+    revocation_push_sign_bytes,
+    revocation_sign_bytes,
+    session_token_sign_bytes,
+    sign_both,
+    sign_challenge,
+    sign_transaction_receipt_party,
+    transaction_receipt_sign_bytes,
+    verify_both,
+    verify_challenge_signature,
+    verify_delegation_signature,
+    verify_delegation_signature_e,
+    verify_key_rotation_statement,
+    verify_key_rotation_statement_e,
+    verify_revocation_list,
+    verify_revocation_push,
+    verify_session_token,
+    verify_session_token_e,
+    verify_witness_entry,
+    witness_entry_sign_bytes,
+)
+from .scope import (
+    CUSTOM_SCOPE_PREFIX,
+    SCOPE_COMMS_CALENDAR_READ,
+    SCOPE_COMMS_CALENDAR_WRITE,
+    SCOPE_COMMS_EMAIL_DELETE,
+    SCOPE_COMMS_EMAIL_READ,
+    SCOPE_COMMS_EMAIL_SEND,
+    SCOPE_COMMS_MESSAGE_DELETE,
+    SCOPE_COMMS_MESSAGE_READ,
+    SCOPE_COMMS_MESSAGE_SEND,
+    SCOPE_CONTRACT_READ,
+    SCOPE_CONTRACT_SIGN,
+    SCOPE_DATA_DELETE,
+    SCOPE_DATA_EXPORT,
+    SCOPE_DATA_READ,
+    SCOPE_DATA_SHARE,
+    SCOPE_DATA_WRITE,
+    SCOPE_EXECUTE_CODE,
+    SCOPE_EXECUTE_TOOL,
+    SCOPE_FILES_READ,
+    SCOPE_FILES_WRITE,
+    SCOPE_GENERATE_CONTENT,
+    SCOPE_GENERATE_DEEPFAKE,
+    SCOPE_IDENTITY_DELEGATE,
+    SCOPE_IDENTITY_PROVE,
+    SCOPE_MEETING_ATTEND,
+    SCOPE_MEETING_CHAT,
+    SCOPE_MEETING_RECORD,
+    SCOPE_MEETING_SHARE_SCREEN,
+    SCOPE_MEETING_SPEAK,
+    SCOPE_MEETING_VIDEO,
+    SCOPE_PAYMENTS_AUTHORIZE,
+    SCOPE_PAYMENTS_RECEIVE,
+    SCOPE_PAYMENTS_SEND,
+    SCOPE_TRANSACT_PURCHASE,
+    SCOPE_TRANSACT_SELL,
+    expand_scopes,
+    has_scope,
+    intersect_scopes,
+    is_sensitive,
+    validate_scopes,
+)
+from .types import (
+    CHALLENGE_WINDOW_SECONDS,
+    ED25519_PUBLIC_KEY_SIZE,
+    ED25519_SIGNATURE_SIZE,
+    MAX_DELEGATION_CHAIN_DEPTH,
+    MLDSA65_PUBLIC_KEY_SIZE,
+    MLDSA65_SIGNATURE_SIZE,
+    PROTOCOL_VERSION,
+    AgentIdentity,
+    Anchor,
+    Constraint,
+    DelegationCert,
+    HumanRoot,
+    HybridPrivateKey,
+    HybridPublicKey,
+    HybridSignature,
+    IdentityStatus,
+    KeyRotationReason,
+    KeyRotationStatement,
+    ProofBundle,
+    ReceiptParty,
+    ReceiptPartySignature,
+    RevocationList,
+    RevocationPush,
+    SessionToken,
+    StreamContext,
+    TransactionReceipt,
+    TransactionReceiptResult,
+    VerifierContext,
+    VerifyOptions,
+    VerifyResult,
+    WitnessEntry,
+)
+from .verify import verify_bundle, verify_streamed_turn, verify_transaction_receipt
+
+__version__ = "1.0.0a5"
+
+__all__ = [
+    # types
+    "PROTOCOL_VERSION", "MAX_DELEGATION_CHAIN_DEPTH", "CHALLENGE_WINDOW_SECONDS",
+    "ED25519_PUBLIC_KEY_SIZE", "ED25519_SIGNATURE_SIZE",
+    "MLDSA65_PUBLIC_KEY_SIZE", "MLDSA65_SIGNATURE_SIZE",
+    "HybridPublicKey", "HybridSignature", "HybridPrivateKey",
+    "Anchor", "HumanRoot", "AgentIdentity",
+    "DelegationCert", "ProofBundle", "KeyRotationStatement", "KeyRotationReason",
+    "VerifyResult", "VerifyOptions", "StreamContext", "SessionToken",
+    "RevocationList", "RevocationPush", "WitnessEntry", "IdentityStatus",
+    "TransactionReceipt", "ReceiptParty", "ReceiptPartySignature",
+    "TransactionReceiptResult",
+    # crypto
+    "derive_id", "generate_hybrid_keypair", "hybrid_keypair_from_seeds",
+    "generate_human_root", "generate_agent",
+    "delegation_sign_bytes", "challenge_sign_bytes", "revocation_sign_bytes",
+    "key_rotation_sign_bytes", "revocation_push_sign_bytes", "witness_entry_sign_bytes",
+    "session_token_sign_bytes", "chain_hash",
+    "transaction_receipt_sign_bytes", "sign_transaction_receipt_party",
+    "sign_both", "verify_both",
+    "issue_delegation", "verify_delegation_signature", "verify_delegation_signature_e",
+    "issue_key_rotation_statement", "verify_key_rotation_statement",
+    "verify_key_rotation_statement_e",
+    "issue_session_token", "verify_session_token", "verify_session_token_e",
+    "sign_challenge", "verify_challenge_signature",
+    "issue_revocation_list", "verify_revocation_list",
+    "issue_revocation_push", "verify_revocation_push",
+    "issue_witness_entry", "verify_witness_entry",
+    "generate_challenge",
+    # scope
+    "expand_scopes", "intersect_scopes", "has_scope", "is_sensitive", "validate_scopes",
+    # verify
+    "verify_bundle", "verify_streamed_turn", "verify_transaction_receipt",
+    # canonical / utils
+    "canonical_json", "base64_standard_encode", "base64_standard_decode",
+    "hex_encode", "hex_decode",
+    # all scope constants
+    "SCOPE_MEETING_ATTEND", "SCOPE_MEETING_SPEAK", "SCOPE_MEETING_VIDEO",
+    "SCOPE_MEETING_CHAT", "SCOPE_MEETING_SHARE_SCREEN", "SCOPE_MEETING_RECORD",
+    "SCOPE_COMMS_MESSAGE_READ", "SCOPE_COMMS_MESSAGE_SEND", "SCOPE_COMMS_MESSAGE_DELETE",
+    "SCOPE_COMMS_EMAIL_READ", "SCOPE_COMMS_EMAIL_SEND", "SCOPE_COMMS_EMAIL_DELETE",
+    "SCOPE_COMMS_CALENDAR_READ", "SCOPE_COMMS_CALENDAR_WRITE",
+    "SCOPE_FILES_READ", "SCOPE_FILES_WRITE",
+    "SCOPE_IDENTITY_PROVE", "SCOPE_IDENTITY_DELEGATE",
+    "SCOPE_TRANSACT_PURCHASE", "SCOPE_TRANSACT_SELL",
+    "SCOPE_PAYMENTS_SEND", "SCOPE_PAYMENTS_RECEIVE", "SCOPE_PAYMENTS_AUTHORIZE",
+    "SCOPE_CONTRACT_READ", "SCOPE_CONTRACT_SIGN",
+    "SCOPE_DATA_READ", "SCOPE_DATA_WRITE", "SCOPE_DATA_DELETE",
+    "SCOPE_DATA_EXPORT", "SCOPE_DATA_SHARE",
+    "SCOPE_EXECUTE_TOOL", "SCOPE_EXECUTE_CODE",
+    "SCOPE_GENERATE_CONTENT", "SCOPE_GENERATE_DEEPFAKE",
+    "CUSTOM_SCOPE_PREFIX",
+]

ratify_protocol/canonical.py

@@ -0,0 +1,156 @@
+"""Canonical JSON serialization per Ratify Protocol SPEC §6.
+
+Every implementation MUST produce byte-identical output for the same input
+or signatures will not verify across languages.
+
+Rules:
+  - Object members in lex order (byte order on UTF-8), RECURSIVELY.
+  - No whitespace between tokens. No trailing newline.
+  - UTF-8 encoding.
+  - Integers as shortest decimal (no leading zeros, no exponent).
+  - bytes-type values encoded as base64-standard strings with padding.
+  - '<', '>', '&' pass through unmodified (NO HTML escaping).
+  - U+2028 / U+2029 escaped as \\u2028 / \\u2029 (matches Go behavior).
+  - Minimum string escaping per RFC 8259.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import is_dataclass, fields
+from typing import Any
+
+
+_ESCAPE_MAP = {
+    ord('"'): b'\\"',
+    ord('\\'): b'\\\\',
+    0x08: b'\\b',
+    0x0c: b'\\f',
+    0x0a: b'\\n',
+    0x0d: b'\\r',
+    0x09: b'\\t',
+}
+
+
+def canonical_json(value: Any) -> bytes:
+    """Canonical JSON-encode a value. Returns UTF-8 bytes."""
+    text = _encode(value)
+    return text.encode("utf-8")
+
+
+def _encode(v: Any) -> str:
+    if v is None:
+        return "null"
+    if v is True:
+        return "true"
+    if v is False:
+        return "false"
+    if isinstance(v, int) and not isinstance(v, bool):
+        return str(v)
+    if isinstance(v, float):
+        # Shouldn't appear in v1 signable objects; fall back to repr-like
+        if v.is_integer():
+            return str(int(v))
+        return repr(v)
+    if isinstance(v, str):
+        return _encode_string(v)
+    if isinstance(v, (bytes, bytearray)):
+        # Project convention: base64-standard encoding.
+        return _encode_string(base64.b64encode(bytes(v)).decode("ascii"))
+    if isinstance(v, (list, tuple)):
+        return "[" + ",".join(_encode(x) for x in v) + "]"
+    if isinstance(v, dict):
+        return _encode_object(v)
+    if is_dataclass(v):
+        return _encode_dataclass(v)
+    raise TypeError(f"canonical_json: unsupported type {type(v).__name__}")
+
+
+def _encode_object(obj: dict) -> str:
+    keys = sorted(obj.keys())
+    parts = []
+    for k in keys:
+        val = obj[k]
+        if val is None:
+            # Skip None values — matches Go's omitempty for optional fields
+            continue
+        parts.append(_encode_string(k) + ":" + _encode(val))
+    return "{" + ",".join(parts) + "}"
+
+
+def _encode_dataclass(obj: Any) -> str:
+    """Serialize a dataclass as a JSON object.
+
+    Uses the dataclass field *definition* order as the input set, then sorts
+    by JSON key (field name) for canonical output. Omits fields whose value
+    is None or, for list[str] scope-like fields, empty — to match Go's
+    omitempty behavior on optional fields.
+    """
+    entries: dict[str, Any] = {}
+    for f in fields(obj):
+        val = getattr(obj, f.name)
+        if val is None:
+            continue
+        # Convert nested bytes to the right shape; strings / lists pass through.
+        entries[f.name] = val
+    return _encode_object(entries)
+
+
+def _encode_string(s: str) -> str:
+    """Encode a string per Ratify canonical rules.
+
+    No HTML escaping. U+2028/U+2029 escape as \\u2028/\\u2029. Control chars
+    below U+0020 escape as \\u00XX. Standard RFC 8259 escapes for ", \\, etc.
+    Everything else passes through.
+    """
+    out = ['"']
+    for ch in s:
+        cp = ord(ch)
+        if cp == 0x22:  # "
+            out.append('\\"')
+        elif cp == 0x5c:  # \
+            out.append('\\\\')
+        elif cp == 0x08:
+            out.append('\\b')
+        elif cp == 0x09:
+            out.append('\\t')
+        elif cp == 0x0a:
+            out.append('\\n')
+        elif cp == 0x0c:
+            out.append('\\f')
+        elif cp == 0x0d:
+            out.append('\\r')
+        elif cp < 0x20:
+            out.append(f'\\u{cp:04x}')
+        elif cp == 0x2028:
+            out.append('\\u2028')
+        elif cp == 0x2029:
+            out.append('\\u2029')
+        else:
+            # Everything else passes through as UTF-8 (no HTML escape).
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def base64_standard_encode(data: bytes) -> str:
+    """Base64-standard encoding with padding (A-Za-z0-9+/=)."""
+    return base64.b64encode(data).decode("ascii")
+
+
+def base64_standard_decode(s: str) -> bytes:
+    """Decode base64-standard (padded or unpadded)."""
+    # Add padding if needed
+    pad = (-len(s)) % 4
+    if pad:
+        s = s + "=" * pad
+    return base64.b64decode(s)
+
+
+def hex_encode(data: bytes) -> str:
+    """Lowercase hex."""
+    return data.hex()
+
+
+def hex_decode(s: str) -> bytes:
+    """Lower- or upper-case hex."""
+    return bytes.fromhex(s)

ratify_protocol/constraints.py

@@ -0,0 +1,205 @@
+"""Constraint evaluation — mirrors Go's constraints.go exactly.
+
+Every semantic must produce the same verdict for the same inputs, or
+cross-language conformance fails.
+"""
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from .types import Constraint, DelegationCert, VerifierContext
+
+
+def evaluate_constraints(
+    cert: DelegationCert,
+    ctx: VerifierContext | None,
+    now_sec: int,
+) -> str | None:
+    """Run every Constraint on cert against the caller-supplied
+    VerifierContext. Return None iff all pass; error message otherwise.
+
+    Fail-closed: unknown Type or missing required context field causes
+    rejection.
+    """
+    if ctx is None:
+        ctx = VerifierContext()
+    for i, c in enumerate(cert.constraints or []):
+        err = _evaluate_constraint(c, cert.cert_id, ctx, now_sec)
+        if err is not None:
+            return f"constraint[{i}] ({c.type}): {err}"
+    return None
+
+
+def _evaluate_constraint(
+    c: Constraint,
+    cert_id: str,
+    ctx: VerifierContext,
+    now_sec: int,
+) -> str | None:
+    t = c.type
+    if t == "geo_circle":
+        if ctx.current_lat is None or ctx.current_lon is None:
+            return "constraint_unverifiable: no current location in context"
+        d = _haversine_meters(ctx.current_lat, ctx.current_lon, c.lat, c.lon)
+        if d > c.radius_m:
+            return f"outside allowed radius: {d:.1f}m > {c.radius_m:.1f}m"
+        return None
+
+    if t == "geo_polygon":
+        if ctx.current_lat is None or ctx.current_lon is None:
+            return "constraint_unverifiable: no current location in context"
+        if not c.points or len(c.points) < 3:
+            return "polygon has fewer than 3 points"
+        # v1 polygon is defined over equirectangular projection — correct
+        # for small regions, incorrect for anti-meridian-crossing shapes.
+        # Fail closed rather than silently return wrong answers. SPEC §5.7.2
+        # documents the v1 small-region limitation; geodesic semantics are v2.
+        if _polygon_spans_antimeridian(c.points):
+            return "geo_polygon spans >180° longitude — v1 semantics are undefined for anti-meridian-crossing polygons (see SPEC §5.7.2)"
+        if not _point_in_polygon(ctx.current_lat, ctx.current_lon, c.points):
+            return "outside allowed polygon"
+        return None
+
+    if t == "geo_bbox":
+        if ctx.current_lat is None or ctx.current_lon is None:
+            return "constraint_unverifiable: no current location in context"
+        # Format mirrors Go's %.6f — cross-SDK error_reason parity requires it.
+        if ctx.current_lat < c.min_lat or ctx.current_lat > c.max_lat:
+            return f"latitude {ctx.current_lat:.6f} outside [{c.min_lat:.6f}, {c.max_lat:.6f}]"
+        # Anti-meridian-aware longitude check (SPEC §5.7.2).
+        #   min_lon <= max_lon → ordinary bbox, lon must be in [min_lon, max_lon]
+        #   min_lon >  max_lon → bbox wraps the 180° meridian (e.g.,
+        #     min_lon=170, max_lon=-170 = "from 170°E through 180 to -170°W")
+        #     — inside iff lon >= min_lon OR lon <= max_lon.
+        if c.min_lon <= c.max_lon:
+            if ctx.current_lon < c.min_lon or ctx.current_lon > c.max_lon:
+                return f"longitude {ctx.current_lon:.6f} outside [{c.min_lon:.6f}, {c.max_lon:.6f}]"
+        else:
+            if ctx.current_lon < c.min_lon and ctx.current_lon > c.max_lon:
+                return f"longitude {ctx.current_lon:.6f} outside wrapped [{c.min_lon:.6f}, {c.max_lon:.6f}]"
+        has_alt = c.min_alt_m != 0.0 or c.max_alt_m != 0.0
+        if has_alt:
+            if ctx.current_alt_m is None:
+                return "constraint_unverifiable: no altitude in context but bbox has altitude bounds"
+            if ctx.current_alt_m < c.min_alt_m or ctx.current_alt_m > c.max_alt_m:
+                return f"altitude {ctx.current_alt_m:.1f}m outside [{c.min_alt_m:.1f}m, {c.max_alt_m:.1f}m]"
+        return None
+
+    if t == "time_window":
+        if not c.tz or not c.start or not c.end:
+            return "malformed time_window: tz/start/end required"
+        start = _parse_hhmm(c.start)
+        end = _parse_hhmm(c.end)
+        if start is None:
+            return f"bad start time: {c.start}"
+        if end is None:
+            return f"bad end time: {c.end}"
+        try:
+            zone = ZoneInfo(c.tz)
+        except ZoneInfoNotFoundError:
+            return f'unknown timezone "{c.tz}"'
+        local = datetime.fromtimestamp(now_sec, tz=timezone.utc).astimezone(zone)
+        cur = local.hour * 60 + local.minute
+        if start <= end:
+            if cur < start or cur > end:
+                return f"current {local.hour:02d}:{local.minute:02d} outside [{c.start}, {c.end}] {c.tz}"
+        else:
+            # Wrapping window (e.g. 22:00 to 06:00).
+            if cur < start and cur > end:
+                return f"current {local.hour:02d}:{local.minute:02d} outside wrapped [{c.start}, {c.end}] {c.tz}"
+        return None
+
+    if t == "max_speed_mps":
+        if ctx.current_speed_mps is None:
+            return "constraint_unverifiable: no current speed in context"
+        if ctx.current_speed_mps > c.max_mps:
+            return f"speed {ctx.current_speed_mps:.2f}mps exceeds max {c.max_mps:.2f}mps"
+        return None
+
+    if t == "max_amount":
+        if ctx.requested_amount is None or ctx.requested_currency is None:
+            return "constraint_unverifiable: no requested amount in context"
+        if ctx.requested_currency != c.currency:
+            return f'currency mismatch: requested "{ctx.requested_currency}", constraint "{c.currency}"'
+        if ctx.requested_amount > c.max_amount:
+            return f"amount {ctx.requested_amount:.2f} {ctx.requested_currency} exceeds max {c.max_amount:.2f} {c.currency}"
+        return None
+
+    if t == "max_rate":
+        if ctx.invocations_in_window is None:
+            return "constraint_unverifiable: no rate counter in context"
+        if c.count <= 0 or c.window_s <= 0:
+            return "malformed max_rate: count and window_s must be positive"
+        got = ctx.invocations_in_window(cert_id, c.window_s)
+        if got >= c.count:
+            return f"rate limit exceeded: {got} invocations in last {c.window_s}s (max {c.count})"
+        return None
+
+    # Sentinel prefix lets verify.py route to identity_status=constraint_unknown.
+    # Matches Go reference unknownConstraintError shape.
+    return f'constraint_unknown: unknown constraint type "{t}"'
+
+
+# ---- helpers ----
+
+
+def _haversine_meters(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance on a sphere (WGS-84 mean radius)."""
+    earth_radius_m = 6371000.0
+    rad = math.pi / 180
+    d_lat = (lat2 - lat1) * rad
+    d_lon = (lon2 - lon1) * rad
+    a = (
+        math.sin(d_lat / 2) ** 2
+        + math.cos(lat1 * rad) * math.cos(lat2 * rad) * math.sin(d_lon / 2) ** 2
+    )
+    return 2 * earth_radius_m * math.asin(min(1.0, math.sqrt(a)))
+
+
+def _polygon_spans_antimeridian(points: list[list[float]]) -> bool:
+    """Return True if the polygon's longitudes span more than 180°.
+
+    The only way to span more than half the globe in longitude is to
+    cross the anti-meridian, and equirectangular ray-casting can't handle
+    that — so we refuse these polygons up-front (fail-closed) rather than
+    silently compute wrong inclusion. Mirrors Go's polygonSpansAntimeridian.
+    """
+    if len(points) < 3:
+        return False
+    min_lon = points[0][1]
+    max_lon = points[0][1]
+    for p in points:
+        if p[1] < min_lon:
+            min_lon = p[1]
+        if p[1] > max_lon:
+            max_lon = p[1]
+    return (max_lon - min_lon) > 180
+
+
+def _point_in_polygon(lat: float, lon: float, poly: list[list[float]]) -> bool:
+    """Ray casting in equirectangular projection. Fine for small polygons."""
+    inside = False
+    n = len(poly)
+    j = n - 1
+    for i in range(n):
+        yi, xi = poly[i][0], poly[i][1]  # lat, lon
+        yj, xj = poly[j][0], poly[j][1]
+        if ((yi > lat) != (yj > lat)) and lon < (xj - xi) * (lat - yi) / (yj - yi) + xi:
+            inside = not inside
+        j = i
+    return inside
+
+
+def _parse_hhmm(s: str) -> int | None:
+    if len(s) != 5 or s[2] != ":":
+        return None
+    try:
+        h = int(s[:2])
+        m = int(s[3:])
+    except ValueError:
+        return None
+    if h < 0 or h > 23 or m < 0 or m > 59:
+        return None
+    return h * 60 + m