aetheridentity 2.0.0__py3-none-any.whl

aetheridentity/__init__.py

@@ -0,0 +1,42 @@
+"""AetherIdentity v2.0.0 — Reference Implementation.
+
+This package implements the specification in SPECIFICATION.md and the
+invariants in INVARIANTS.md. It is a research artifact, not a production
+system.
+
+Public API:
+    records      — Record types and canonical serialization
+    signer       — Abstract Signer, FakeSigner, Ed25519Signer
+    simulator    — Replicated state S as a flat list
+    identity     — L1 Identity
+    continuity   — L2 Continuity
+    reputation   — L3 Reputation
+    sybil        — L4 Sybil resistance
+    delegation   — L5 Delegation
+"""
+
+__version__ = "2.0.0"
+__paper__ = "10.5281/zenodo.24102739"
+__osf__ = "10.17605/OSF.IO/B6AEN"
+
+from aetheridentity import (
+    continuity,
+    delegation,
+    identity,
+    records,
+    reputation,
+    signer,
+    simulator,
+    sybil,
+)
+
+__all__ = [
+    "continuity",
+    "delegation",
+    "identity",
+    "records",
+    "reputation",
+    "signer",
+    "simulator",
+    "sybil",
+]

aetheridentity/continuity.py

@@ -0,0 +1,119 @@
+"""L2 — Continuity (§6.2 of SPECIFICATION.md).
+
+Implements Definition 2 of the paper:
+- Continuity chain with pre-committed next keys.
+- Rotation requires the next key, kept offline.
+- Fork detection: two valid rotations with the same predecessor.
+
+Out of scope (v2.0.0):
+- Fork resolution.
+- Recovery after total key loss.
+- Single-instance enforcement.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable
+
+from aetheridentity.records import (
+    InceptionRecord,
+    RotationRecord,
+    canonical_bytes,
+)
+from aetheridentity.signer import Signer
+
+
+def hash_key(pk: bytes) -> bytes:
+    """Hash a public key for pre-commitment (H(pk))."""
+    return hashlib.sha256(pk).digest()
+
+
+def create_inception(
+    signer: Signer,
+    label: str,
+    next_pk: bytes,
+    alg: str = "ed25519",
+    created_at: int = 0,
+) -> InceptionRecord:
+    """Create an inception record that commits to the next key.
+
+    The inception record itself has no `next_pk` field in Definition 1,
+    but the commitment is stored as the first rotation's `commitment`
+    field when the first rotation is created. To keep the record types
+    simple, we store the commitment implicitly: the caller must pass
+    `next_pk` when creating the first rotation.
+    """
+    from aetheridentity.identity import identifier
+
+    pk = signer.public_key()
+    signer_id = identifier(alg, pk, label)
+    record = InceptionRecord(
+        record_type="inception",
+        signer_id=signer_id,
+        created_at=created_at,
+        alg=alg,
+        pk=pk,
+        label=label,
+        t_c=created_at,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return InceptionRecord(**{**record.__dict__, "signature": sig})
+
+
+def create_rotation(
+    signer: Signer,
+    ident: str,
+    epoch: int,
+    new_pk: bytes,
+    next_pk: bytes,
+    prev_hash: str,
+    created_at: int = 0,
+) -> RotationRecord:
+    """Create a rotation record that reveals `new_pk` and commits to `next_pk`."""
+    commitment = hash_key(next_pk)
+    record = RotationRecord(
+        record_type="rotation",
+        signer_id=ident,
+        created_at=created_at,
+        id=ident,
+        epoch=epoch,
+        new_pk=new_pk,
+        commitment=commitment,
+        prev_hash=prev_hash,
+        signing_pk=signer.public_key(),
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return RotationRecord(**{**record.__dict__, "signature": sig})
+
+
+def verify_rotation(
+    rotation: RotationRecord,
+    previous_commitment: bytes,
+) -> bool:
+    """Verify that a rotation reveals the pre-committed key."""
+    return hash_key(rotation.new_pk) == previous_commitment
+
+
+def detect_fork(rotations: Iterable[RotationRecord]) -> bool:
+    """A fork is two valid rotations with the same predecessor and different content."""
+    seen: dict[str, bytes] = {}
+    for r in rotations:
+        if r.record_type != "rotation":
+            continue
+        content = canonical_bytes(r)
+        if r.prev_hash in seen:
+            if seen[r.prev_hash] != content:
+                return True
+        else:
+            seen[r.prev_hash] = content
+    return False
+
+
+def continuity_chain(
+    records: Iterable,
+    ident: str,
+) -> list[RotationRecord]:
+    """Return the continuity chain for `ident`, ordered by epoch."""
+    chain = [r for r in records if isinstance(r, RotationRecord) and r.id == ident]
+    return sorted(chain, key=lambda r: r.epoch)

aetheridentity/delegation.py

@@ -0,0 +1,251 @@
+"""L5 — Delegation (§6.5 of SPECIFICATION.md).
+
+Implements Definition 4 of the paper:
+- Delegation record: (i, j, S_d, e_d, p_d).
+- Validity: S_d ⊆ S_p, e_d ≤ e_p, parent valid.
+- Effective scope: intersection. Effective expiry: minimum.
+- Revocation of any link invalidates downstream links.
+
+Out of scope (v2.0.0):
+- Expressive scopes (open question Q16).
+- Retroactive vs. prospective revocation (open question Q17).
+- Whether L5 is separable from AetherGovern (tested via governance_overlap).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from aetheridentity.records import DelegationRecord, canonical_bytes
+from aetheridentity.signer import Signer
+
+
+@dataclass(frozen=True)
+class Scope:
+    """A scope is a set of permissions (strings)."""
+
+    permissions: frozenset[str]
+
+    def is_subset_of(self, other: "Scope") -> bool:
+        return self.permissions.issubset(other.permissions)
+
+    def intersect(self, other: "Scope") -> "Scope":
+        return Scope(self.permissions & other.permissions)
+
+    def __str__(self) -> str:
+        return "|".join(sorted(self.permissions))
+
+
+def _parse_scope(s: str) -> Scope:
+    """Parse a scope string ('p1|p2|...') into a Scope."""
+    if not s:
+        return Scope(frozenset())
+    return Scope(frozenset(s.split("|")))
+
+
+def delegate(
+    signer: Signer,
+    delegator: str,
+    delegatee: str,
+    scope: Scope,
+    expiry: int,
+    parent: str = "",
+    created_at: int = 0,
+) -> DelegationRecord:
+    """Create and sign a delegation record."""
+    record = DelegationRecord(
+        record_type="delegation",
+        signer_id=delegator,
+        created_at=created_at,
+        delegator=delegator,
+        delegatee=delegatee,
+        scope=str(scope),
+        expiry=expiry,
+        parent=parent,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return DelegationRecord(**{**record.__dict__, "signature": sig})
+
+
+def _find_parent(
+    records: Iterable[DelegationRecord],
+    parent_id: str,
+) -> DelegationRecord | None:
+    """Find a parent delegation by its signature hash (acting as id)."""
+    if not parent_id:
+        return None
+    for r in records:
+        if r.record_type != "delegation":
+            continue
+        # Use the canonical hash as the delegation's identifier.
+        from aetheridentity.records import record_hash
+
+        if record_hash(r) == parent_id:
+            return r
+    return None
+
+
+def validate_delegation(
+    records: Iterable[DelegationRecord],
+    child: DelegationRecord,
+) -> bool:
+    """A delegation is valid iff:
+    - its scope is a subset of the parent's scope,
+    - its expiry is ≤ the parent's expiry,
+    - the parent is valid (recursively).
+    A root delegation (no parent) is valid iff its scope is non-empty and
+    its expiry is positive.
+    """
+    child_scope = _parse_scope(child.scope)
+
+    if not child.parent:
+        return len(child_scope.permissions) > 0 and child.expiry > 0
+
+    parent = _find_parent(records, child.parent)
+    if parent is None:
+        return False
+
+    parent_scope = _parse_scope(parent.scope)
+    if not child_scope.is_subset_of(parent_scope):
+        return False
+    if child.expiry > parent.expiry:
+        return False
+    return validate_delegation(records, parent)
+
+
+def effective_scope(
+    records: Iterable[DelegationRecord],
+    leaf: DelegationRecord,
+) -> Scope:
+    """The effective scope of a chain is the intersection of its scopes."""
+    records = list(records)
+    chain = _chain_of(records, leaf)
+    result = _parse_scope(chain[0].scope)
+    for r in chain[1:]:
+        result = result.intersect(_parse_scope(r.scope))
+    return result
+
+
+def effective_expiry(
+    records: Iterable[DelegationRecord],
+    leaf: DelegationRecord,
+) -> int:
+    """The effective expiry of a chain is the minimum of its expiries."""
+    records = list(records)
+    chain = _chain_of(records, leaf)
+    return min(r.expiry for r in chain)
+
+
+def _chain_of(
+    records: list[DelegationRecord],
+    leaf: DelegationRecord,
+) -> list[DelegationRecord]:
+    """Return the chain from root to leaf."""
+    chain = [leaf]
+    current = leaf
+    while current.parent:
+        parent = _find_parent(records, current.parent)
+        if parent is None:
+            break
+        chain.append(parent)
+        current = parent
+    return list(reversed(chain))
+
+
+def revoke(
+    signer: Signer,
+    target_delegation: DelegationRecord,
+    created_at: int = 0,
+) -> DelegationRecord:
+    """Create and sign a revocation record for a delegation.
+
+    A revocation is represented as a delegation with an empty scope and
+    expiry 0, targeting the original delegation via `parent`.
+    """
+    from aetheridentity.records import record_hash
+
+    target_id = record_hash(target_delegation)
+    record = DelegationRecord(
+        record_type="delegation",
+        signer_id=target_delegation.delegator,
+        created_at=created_at,
+        delegator=target_delegation.delegator,
+        delegatee=target_delegation.delegatee,
+        scope="",
+        expiry=0,
+        parent=target_id,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return DelegationRecord(**{**record.__dict__, "signature": sig})
+
+
+def is_revoked(
+    records: Iterable[DelegationRecord],
+    delegation: DelegationRecord,
+) -> bool:
+    """A delegation is revoked if any link in its chain has a revocation record."""
+    from aetheridentity.records import record_hash
+
+    records = list(records)
+    target_id = record_hash(delegation)
+    for r in records:
+        if r.record_type != "delegation":
+            continue
+        if r.scope == "" and r.expiry == 0 and r.parent == target_id:
+            return True
+    return False
+
+
+def is_valid_for_action(
+    records: Iterable[DelegationRecord],
+    delegation: DelegationRecord,
+    action_time: int,
+    required_permission: str,
+) -> bool:
+    """Check that a delegation authorizes an action.
+
+    - The chain must be valid (validate_delegation).
+    - The action_time must be ≤ the effective expiry.
+    - The required permission must be in the effective scope.
+    - No link in the chain may be revoked.
+    """
+    records = list(records)
+    if not validate_delegation(records, delegation):
+        return False
+    if action_time > effective_expiry(records, delegation):
+        return False
+    if required_permission not in effective_scope(records, delegation).permissions:
+        return False
+    chain = _chain_of(records, delegation)
+    for link in chain:
+        if is_revoked(records, link):
+            return False
+    return True
+
+
+def governance_overlap(
+    records: Iterable[DelegationRecord],
+    authority_chains: dict[str, frozenset[str]],
+) -> float:
+    """Measure the fraction of L5 decisions that can be re-expressed as
+    AetherGovern decisions (F3, tested in S6).
+
+    For each delegation in `records`, check whether its (delegator, delegatee)
+    pair already appears in the `authority_chains` mapping, where
+    authority_chains[delegator] is the set of principals authorized to act
+    on behalf of `delegator` under AetherGovern.
+
+    Returns:
+        Fraction in [0, 1]. 1.0 means every L5 decision is already an
+        AetherGovern decision (F3 falsified if ≥ the threshold 0.80).
+    """
+    records = [r for r in records if r.record_type == "delegation"]
+    if not records:
+        return 0.0
+    overlaps = 0
+    for r in records:
+        authorized = authority_chains.get(r.delegator, frozenset())
+        if r.delegatee in authorized:
+            overlaps += 1
+    return overlaps / len(records)

aetheridentity/identity.py

@@ -0,0 +1,53 @@
+"""L1 — Identity (§6.1 of SPECIFICATION.md)."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable
+
+from aetheridentity.records import InceptionRecord, canonical_bytes
+from aetheridentity.signer import Signer
+
+DOMAIN_TAG = b"AETHERIDENTITY/v2"
+
+
+def identifier(alg: str, pk: bytes, label: str) -> str:
+    """Definition 1: id(t) = H(tag ‖ alg ‖ pk ‖ λ)."""
+    h = hashlib.sha256()
+    h.update(DOMAIN_TAG)
+    h.update(b"\x00")
+    h.update(alg.encode("utf-8"))
+    h.update(b"\x00")
+    h.update(pk)
+    h.update(b"\x00")
+    h.update(label.encode("utf-8"))
+    return h.hexdigest()
+
+
+def create_identity(signer: Signer, label: str, alg: str = "ed25519", created_at: int = 0) -> InceptionRecord:
+    """Create an inception record and sign it."""
+    pk = signer.public_key()
+    signer_id = identifier(alg, pk, label)
+    record = InceptionRecord(
+        record_type="inception",
+        signer_id=signer_id,
+        created_at=created_at,
+        alg=alg,
+        pk=pk,
+        label=label,
+        t_c=created_at,
+    )
+    sig = signer.sign(canonical_bytes(record))
+    return InceptionRecord(
+        **{**record.__dict__, "signature": sig}
+    )
+
+
+def verify_identity(records: Iterable[InceptionRecord], ident: str) -> bool:
+    """Check that the identifier recomputes from the record's fields."""
+    for r in records:
+        if r.record_type != "inception":
+            continue
+        if identifier(r.alg, r.pk, r.label) == ident:
+            return True
+    return False

aetheridentity/records.py

@@ -0,0 +1,138 @@
+"""Record types for AetherIdentity.
+
+Implements §3 of SPECIFICATION.md:
+- Five record types (InceptionRecord, RotationRecord, ReputationRecord,
+  DelegationRecord, SybilClaim).
+- Canonical JSON serialization (§3.3).
+- Record hashing (SHA-256 over canonical JSON).
+
+No signatures are verified here. Signature verification belongs to signer.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Any, Literal
+
+RecordType = Literal["inception", "rotation", "reputation", "delegation", "sybil_claim"]
+
+
+def _canonical_json(obj: dict[str, Any]) -> bytes:
+    """Canonical JSON serialization (§3.3 of SPECIFICATION.md).
+
+    - Keys sorted lexicographically.
+    - No whitespace.
+    - UTF-8 encoding.
+    - Bytes encoded as lowercase hex.
+    """
+    return json.dumps(
+        obj,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=_json_default,
+    ).encode("utf-8")
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, bytes):
+        return obj.hex()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def canonical_bytes(record: "BaseRecord") -> bytes:
+    """Canonical serialization of a record, without its signature field."""
+    data = asdict(record)
+    data.pop("signature", None)
+    return _canonical_json(data)
+
+
+def record_hash(record: "BaseRecord") -> str:
+    """SHA-256 hash of the canonical serialization (without signature)."""
+    return hashlib.sha256(canonical_bytes(record)).hexdigest()
+
+
+@dataclass(frozen=True)
+class BaseRecord:
+    """Common fields for all record types (§3.2 of SPECIFICATION.md)."""
+
+    record_type: RecordType
+    signer_id: str
+    created_at: int
+    signature: bytes = field(default=b"", compare=False)
+
+
+@dataclass(frozen=True)
+class InceptionRecord(BaseRecord):
+    """Identity creation (Definition 1 of the paper)."""
+
+    alg: str = ""
+    pk: bytes = field(default=b"", compare=False)
+    label: str = ""
+    t_c: int = 0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "record_type", "inception")
+
+
+@dataclass(frozen=True)
+class RotationRecord(BaseRecord):
+    """Key rotation (Definition 2 of the paper)."""
+
+    id: str = ""
+    epoch: int = 0
+    new_pk: bytes = field(default=b"", compare=False)
+    commitment: bytes = field(default=b"", compare=False)
+    prev_hash: str = ""
+    signing_pk: bytes = field(default=b"", compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "record_type", "rotation")
+
+
+@dataclass(frozen=True)
+class ReputationRecord(BaseRecord):
+    """Signed observation (Definition 3 of the paper)."""
+
+    observer: str = ""
+    subject: str = ""
+    evidence: str = ""
+    outcome: int = 0
+    t: int = 0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "record_type", "reputation")
+        if self.outcome not in (-1, 0, 1):
+            raise ValueError("outcome must be -1, 0, or +1")
+
+
+@dataclass(frozen=True)
+class DelegationRecord(BaseRecord):
+    """Scoped authority (Definition 4 of the paper)."""
+
+    delegator: str = ""
+    delegatee: str = ""
+    scope: str = ""
+    expiry: int = 0
+    parent: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "record_type", "delegation")
+
+
+@dataclass(frozen=True)
+class SybilClaim(BaseRecord):
+    """Evidence-backed claim of shared control (§6.4 of SPECIFICATION.md)."""
+
+    attester: str = ""
+    target: str = ""
+    evidence: str = ""
+    t: int = 0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "record_type", "sybil_claim")
+
+
+AnyRecord = InceptionRecord | RotationRecord | ReputationRecord | DelegationRecord | SybilClaim