aetheridentity 2.0.0__py3-none-any.whl

aetheridentity/reputation.py

@@ -0,0 +1,178 @@
+"""L3 — Reputation (§6.3 of SPECIFICATION.md).
+
+Implements Definition 3 of the paper:
+- Reputation record: signed observation.
+- Score: fixed point of an EigenTrust-style iteration, computed in exact
+  arithmetic with a fixed iteration count K and a canonical ordering.
+- The score is a view over S, not a stored value.
+
+Out of scope (v2.0.0):
+- Whether reputation may influence admission (policy decision).
+- Per-task-class reputation (open question Q10).
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import Iterable
+
+from aetheridentity.records import (
+    ReputationRecord,
+    canonical_bytes,
+)
+from aetheridentity.signer import Signer
+
+K = 100
+DAMPING = Fraction(1, 5)  # a = 0.2
+
+
+def record_observation(
+    signer: Signer,
+    observer: str,
+    subject: str,
+    evidence: str,
+    outcome: int,
+    created_at: int = 0,
+) -> ReputationRecord:
+    """Create and sign a reputation record."""
+    if outcome not in (-1, 0, 1):
+        raise ValueError("outcome must be -1, 0, or +1")
+    record = ReputationRecord(
+        record_type="reputation",
+        signer_id=observer,
+        created_at=created_at,
+        observer=observer,
+        subject=subject,
+        evidence=evidence,
+        outcome=outcome,
+        t=created_at,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return ReputationRecord(**{**record.__dict__, "signature": sig})
+
+
+def _build_local_trust(
+    records: Iterable[ReputationRecord],
+    observers: list[str],
+    subjects: list[str],
+) -> list[list[Fraction]]:
+    """Build the row-stochastic matrix C from reputation records.
+
+    C[i][j] = normalized positive outcome from observers[i] about subjects[j].
+    """
+    n = len(observers)
+    m = len(subjects)
+    raw = [[0 for _ in range(m)] for _ in range(n)]
+
+    # Accumulate positive outcomes only (v > 0), as in the paper's definition.
+    for r in records:
+        if r.record_type != "reputation":
+            continue
+        if r.observer not in observers or r.subject not in subjects:
+            continue
+        i = observers.index(r.observer)
+        j = subjects.index(r.subject)
+        if r.outcome > 0:
+            raw[i][j] += r.outcome
+
+    # Normalize each row. If a row is all zeros, use the uniform distribution.
+    C = [[Fraction(0) for _ in range(m)] for _ in range(n)]
+    for i in range(n):
+        total = sum(raw[i])
+        if total == 0:
+            for j in range(m):
+                C[i][j] = Fraction(1, m)
+        else:
+            for j in range(m):
+                C[i][j] = Fraction(raw[i][j], total)
+    return C
+
+
+def _anchor_distribution(anchors: list[str], subjects: list[str]) -> list[Fraction]:
+    """Uniform distribution over the anchor set Γ₀."""
+    m = len(subjects)
+    if not anchors:
+        return [Fraction(1, m) for _ in range(m)]
+    p = [Fraction(0) for _ in range(m)]
+    for a in anchors:
+        if a in subjects:
+            p[subjects.index(a)] = Fraction(1, len(anchors))
+    return p
+
+
+def _iterate(
+    C: list[list[Fraction]],
+    p: list[Fraction],
+    a: Fraction,
+    K: int,
+) -> list[Fraction]:
+    """Iterate t ← (1 − a) · Cᵀ t + a · p for K steps.
+
+    Initial t is the uniform distribution.
+    """
+    m = len(p)
+    t = [Fraction(1, m) for _ in range(m)]
+    one_minus_a = Fraction(1) - a
+
+    for _ in range(K):
+        # Compute Cᵀ t: for each j, sum_i C[i][j] * t[i].
+        ct = [Fraction(0) for _ in range(m)]
+        for i in range(len(C)):
+            ti = t[i]
+            if ti == 0:
+                continue
+            row = C[i]
+            for j in range(m):
+                ct[j] += row[j] * ti
+        t = [one_minus_a * ct[j] + a * p[j] for j in range(m)]
+    return t
+
+
+def reputation_of(
+    records: Iterable[ReputationRecord],
+    anchors: list[str] | None = None,
+) -> dict[str, Fraction]:
+    """Compute the reputation vector over all subjects in `records`.
+
+    - Observers and subjects are sorted canonically (lexicographic by id).
+    - Iteration count K = 100.
+    - Damping a = 1/5.
+    - Exact arithmetic (Fraction).
+    """
+    records = list(records)
+    observers_set = {r.observer for r in records if r.record_type == "reputation"}
+    subjects_set = {r.subject for r in records if r.record_type == "reputation"}
+    observers = sorted(observers_set)
+    subjects = sorted(subjects_set)
+
+    if not subjects:
+        return {}
+
+    C = _build_local_trust(records, observers, subjects)
+    p = _anchor_distribution(anchors or [], subjects)
+    t = _iterate(C, p, DAMPING, K)
+    return {subjects[j]: t[j] for j in range(len(subjects))}
+
+
+def reputation_residual(
+    records: Iterable[ReputationRecord],
+    anchors: list[str] | None = None,
+) -> Fraction:
+    """‖T(t_K) − t_K‖₁, for the convergence check (T06)."""
+    records = list(records)
+    observers = sorted({r.observer for r in records if r.record_type == "reputation"})
+    subjects = sorted({r.subject for r in records if r.record_type == "reputation"})
+    if not subjects:
+        return Fraction(0)
+
+    C = _build_local_trust(records, observers, subjects)
+    p = _anchor_distribution(anchors or [], subjects)
+    t_K = _iterate(C, p, DAMPING, K)
+    # One more iteration.
+    m = len(p)
+    ct = [Fraction(0) for _ in range(m)]
+    for i in range(len(C)):
+        for j in range(m):
+            ct[j] += C[i][j] * t_K[i]
+    t_next = [(Fraction(1) - DAMPING) * ct[j] + DAMPING * p[j] for j in range(m)]
+    return sum(abs(t_next[j] - t_K[j]) for j in range(m))

aetheridentity/signer.py

@@ -0,0 +1,78 @@
+"""Abstract Signer interface (§4 of SPECIFICATION.md).
+
+Two implementations:
+- FakeSigner: for unit tests and scenarios. Not cryptographic.
+- Ed25519Signer: real Ed25519 via the `cryptography` library.
+
+A signature produced by one is not accepted by the other.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    PublicFormat,
+)
+
+
+class Signer(Protocol):
+    """Abstract signer interface."""
+
+    def sign(self, message: bytes) -> bytes: ...
+    def verify(self, message: bytes, signature: bytes, public_key: bytes) -> bool: ...
+    def public_key(self) -> bytes: ...
+
+
+class FakeSigner:
+    """Non-cryptographic signer for tests.
+
+    The signature is the SHA-256 of the message prefixed with a fixed tag.
+    This is NOT secure and MUST NOT be used outside tests.
+    """
+
+    TAG = b"FAKE-SIGNER:"
+
+    def __init__(self) -> None:
+        self._pk = b"fake-pk"
+
+    def sign(self, message: bytes) -> bytes:
+        import hashlib
+
+        return self.TAG + hashlib.sha256(message).digest()
+
+    def verify(self, message: bytes, signature: bytes, public_key: bytes) -> bool:
+        if not signature.startswith(self.TAG):
+            return False
+        return self.sign(message) == signature
+
+    def public_key(self) -> bytes:
+        return self._pk
+
+
+class Ed25519Signer:
+    """Real Ed25519 signer using the `cryptography` library."""
+
+    def __init__(self) -> None:
+        self._sk = Ed25519PrivateKey.generate()
+        self._pk = self._sk.public_key()
+
+    def sign(self, message: bytes) -> bytes:
+        return self._sk.sign(message)
+
+    def verify(self, message: bytes, signature: bytes, public_key: bytes) -> bool:
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(public_key)
+            pub.verify(signature, message)
+            return True
+        except (InvalidSignature, ValueError):
+            return False
+
+    def public_key(self) -> bytes:
+        return self._pk.public_bytes(Encoding.Raw, PublicFormat.Raw)

aetheridentity/simulator.py

@@ -0,0 +1,49 @@
+"""Minimal independent simulator of replicated state S (§8 of SPECIFICATION.md).
+
+S is a flat list of admitted records. Admission is sequential. No
+concurrency, no causal delivery, no fork resolution.
+"""
+
+from __future__ import annotations
+
+from aetheridentity.records import AnyRecord, record_hash
+from aetheridentity.signer import Signer
+
+
+class Simulator:
+    """Replicated state S as a flat list of records."""
+
+    def __init__(self, signer: Signer) -> None:
+        self._signer = signer
+        self._records: list[AnyRecord] = []
+        self._hashes: set[str] = set()
+
+    def admit(self, record: AnyRecord) -> bool:
+        """Admit a record. Returns True if admitted, False if duplicate.
+
+        Raises:
+            ValueError: if the record's signature does not verify.
+        """
+        # 1. Structural validation is the responsibility of the record class
+        #    (its __post_init__). A malformed record cannot be constructed.
+        # 2. Signature verification.
+        if record.signature:
+            from aetheridentity.records import canonical_bytes
+
+            if not self._signer.verify(canonical_bytes(record), record.signature, b""):
+                raise ValueError("signature verification failed")
+
+        # 3. Deduplication by canonical hash.
+        h = record_hash(record)
+        if h in self._hashes:
+            return False
+        self._hashes.add(h)
+        self._records.append(record)
+        return True
+
+    def records(self) -> list[AnyRecord]:
+        """Return a copy of S. The caller cannot mutate internal state."""
+        return list(self._records)
+
+    def __len__(self) -> int:
+        return len(self._records)

aetheridentity/sybil.py

@@ -0,0 +1,119 @@
+"""L4 — Sybil Resistance (§6.4 of SPECIFICATION.md).
+
+Implements:
+- SybilClaim: signed, evidence-backed claim of shared control.
+- Cluster formation: claims signed by at least tau distinct anchored attesters.
+- cluster_weight_of: divide each member's weight by cluster size.
+- detection_rates: separate false-positive and false-negative rates.
+
+Out of scope (v2.0.0):
+- Detection guarantees (none are claimed).
+- Admissible evidence (open question Q13).
+- Threshold tau (fixed at 2 in INVARIANTS.md).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from aetheridentity.records import SybilClaim, canonical_bytes
+from aetheridentity.signer import Signer
+
+TAU = 2  # threshold for cluster formation (INVARIANTS.md, O4)
+
+
+def issue_sybil_claim(
+    signer: Signer,
+    attester: str,
+    target: str,
+    evidence: str,
+    created_at: int = 0,
+) -> SybilClaim:
+    """Create and sign a Sybil claim."""
+    record = SybilClaim(
+        record_type="sybil_claim",
+        signer_id=attester,
+        created_at=created_at,
+        attester=attester,
+        target=target,
+        evidence=evidence,
+        t=created_at,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return SybilClaim(**{**record.__dict__, "signature": sig})
+
+
+def _cluster_of(
+    records: Iterable[SybilClaim],
+    anchored: set[str],
+    tau: int = TAU,
+) -> dict[str, set[str]]:
+    """Build clusters from claims.
+
+    A cluster is a set of identities linked by at least `tau` distinct
+    anchored attesters. The evidence string is used as a grouping key:
+    claims about the same evidence are considered to describe the same
+    cluster.
+    """
+    # Group claims by evidence.
+    by_evidence: dict[str, list[SybilClaim]] = {}
+    for r in records:
+        if r.record_type != "sybil_claim":
+            continue
+        by_evidence.setdefault(r.evidence, []).append(r)
+
+    clusters: dict[str, set[str]] = {}
+    for evidence, claims in by_evidence.items():
+        distinct_attesters = {c.attester for c in claims if c.attester in anchored}
+        if len(distinct_attesters) < tau:
+            continue
+        members: set[str] = set()
+        for c in claims:
+            members.add(c.attester)
+            members.add(c.target)
+        for m in members:
+            clusters[m] = members
+    return clusters
+
+
+def cluster_weight_of(
+    records: Iterable[SybilClaim],
+    ident: str,
+    anchored: set[str] | None = None,
+    tau: int = TAU,
+) -> float:
+    """Return the weight of `ident` in its cluster (1/m), or 1.0 if not in a cluster."""
+    anchored = anchored or set()
+    clusters = _cluster_of(records, anchored, tau)
+    if ident not in clusters:
+        return 1.0
+    return 1.0 / len(clusters[ident])
+
+
+def detection_rates(
+    predicted: set[str],
+    ground_truth: set[str],
+    honest_operators: set[str],
+) -> dict[str, float]:
+    """Compute false-positive and false-negative rates.
+
+    - False positive rate: fraction of honest operators wrongly flagged.
+    - False negative rate: fraction of true Sybils not flagged.
+    - Detection rate: fraction of true Sybils flagged.
+    """
+    true_positives = predicted & ground_truth
+    false_positives = (predicted - ground_truth) & honest_operators
+    false_negatives = ground_truth - predicted
+
+    fp_rate = len(false_positives) / len(honest_operators) if honest_operators else 0.0
+    fn_rate = len(false_negatives) / len(ground_truth) if ground_truth else 0.0
+    detection_rate = len(true_positives) / len(ground_truth) if ground_truth else 0.0
+
+    return {
+        "detection_rate": detection_rate,
+        "false_positive_rate": fp_rate,
+        "false_negative_rate": fn_rate,
+        "true_positives": len(true_positives),
+        "false_positives": len(false_positives),
+        "false_negatives": len(false_negatives),
+    }