iqa-org 0.1.0__py3-none-any.whl

iqa/__init__.py

@@ -0,0 +1,62 @@
+"""iqa — reference implementation of the IQA attestation layer (RFC-009 §10/§11).
+
+What is in the box
+------------------
+* :mod:`iqa.iqa_uri` — the ``iqa://`` URI codec: validate, canonicalise,
+  classify (hash vs name subject), enforce the two **closed sets**
+  (``organ`` / ``action``), report §11.3 action safety classes, and derive
+  ``IQA_ROUTE`` (SPEC/IQA-URI-ATTEST-v1.2.6 §3).
+* :mod:`iqa.attest` — the sovereign **attestation envelope** (Ed25519,
+  self-certifying, domain prefix ``iqa-attest-v1``). Optional dependency.
+* :mod:`iqa.vectors` — the published conformance vectors, shipped inside the
+  wheel so the self-test works from an installed package with no repository
+  checkout.
+
+Scope
+-----
+This is the **codec**, not the organism. Staking, vitality monitoring and the
+post-quantum Lattice Guard are RFC-009 narrative with no object here — see the
+package README's scope table and SPEC §8.
+
+Verify it
+---------
+    $ python -m iqa.selftest
+    [PASS] all N checks passed
+
+Offline. No account. No network. ``[PASS]`` or it is not.
+"""
+
+from . import iqa_uri
+from .iqa_uri import (
+    ACTIONS,
+    HASH_LENGTHS,
+    ORGANS,
+    SAFE_ACTIONS,
+    SCHEME,
+    STANDINGS,
+    UNSAFE_ACTIONS,
+    IqaUriError,
+    derive_route,
+    derive_route_hex,
+    is_valid_action,
+    parse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "iqa_uri",
+    "SCHEME",
+    "ORGANS",
+    "ACTIONS",
+    "STANDINGS",
+    "HASH_LENGTHS",
+    "SAFE_ACTIONS",
+    "UNSAFE_ACTIONS",
+    "IqaUriError",
+    "parse",
+    "derive_route",
+    "derive_route_hex",
+    "is_valid_action",
+]

iqa/attest.py

@@ -0,0 +1,351 @@
+"""
+attest — the sovereign **attestation envelope** (Ed25519, self-certifying)
+
+Why this module exists
+----------------------
+An ``iqa://`` URI is a *claim about standing* (RFC-009 §10.4: "parsing is not
+attestation"). To act on the claim, a verifier needs evidence. The evidence
+travels as an **envelope**: a signed object that cites the subject URI and
+carries the standing an Organ rendered.
+
+Layout: identical to the RTTP sovereign seal
+(``SPEC/RTTP-SEAL-ENVELOPE-v1.2.6.md`` §3) with two changes fixed by
+``SPEC/IQA-URI-ATTEST-v1.2.6.md`` §5:
+
+    1. **Domain separation.** The signing-input prefix is ``b"iqa-attest-v1\\n"``
+       — a signature made for one scheme can never be replayed as the other.
+    2. **Payload semantics.** ``{"subject_uri", "organ", "standing"}``, with
+       ``standing`` a closed set (``ghost`` / ``probation`` / ``radiant`` /
+       ``genesis``, RFC-009-C §3).
+
+Identity: ``AID = SHA-256(public key)`` — self-certifying, recomputed by the
+verifier from the in-band key. No registry, no issuer, no directory. Lose the
+key, lose the identity; there is no operator who can restore it.
+
+``ts`` and ``nonce`` are **inside** the signature: rewriting them must require
+breaking Ed25519, not just editing JSON. Freshness window: 120 seconds for any
+envelope arriving over a network; archival validation only may disable it.
+
+Installing
+----------
+    pip install iqa[ed25519]
+
+Without the extra, importing this module succeeds but every call raises
+``AttestError`` with that instruction — it never degrades to an unsigned path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+
+from . import iqa_uri
+from .iqa_uri import IqaUriError
+
+try:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey,
+        Ed25519PublicKey,
+    )
+
+    HAVE_ED25519 = True
+    _IMPORT_ERROR = None
+except ImportError as _exc:  # pragma: no cover - depends on the environment
+    HAVE_ED25519 = False
+    _IMPORT_ERROR = _exc
+
+ALG = "ed25519"
+ENVELOPE_VERSION = 1
+
+#: Maximum accepted |now - ts|, in seconds.
+MAX_CLOCK_SKEW = 120
+
+#: Nonce length in bytes (hex-encoded on the wire).
+NONCE_BYTES = 8
+
+AID_BYTES = 32
+PUBLIC_KEY_BYTES = 32
+SIGNATURE_BYTES = 64
+SEED_BYTES = 32
+
+#: SPEC/IQA-URI-ATTEST-v1.2.6 §5.2 — domain separation from the RTTP seal.
+CANONICAL_PREFIX = b"iqa-attest-v1\n"
+
+#: Closed set of standings an Organ may render (RFC-009-C §3).
+STANDINGS = iqa_uri.STANDINGS
+
+INSTALL_HINT = "pip install iqa-org[ed25519]"
+
+
+class AttestError(Exception):
+    """The envelope is unavailable, unparsable or malformed."""
+
+
+def _require_backend() -> None:
+    if not HAVE_ED25519:
+        raise AttestError(
+            f"Ed25519 backend unavailable - install it with '{INSTALL_HINT}' "
+            f"(import error: {_IMPORT_ERROR})")
+
+
+# ---------------------------------------------------------------------------
+# Identity
+# ---------------------------------------------------------------------------
+
+def aid_from_public_key(public_key: bytes) -> bytes:
+    """AID = SHA-256(public_key), 32 bytes — self-certifying by construction."""
+    if not isinstance(public_key, (bytes, bytearray)):
+        raise AttestError("public_key must be bytes")
+    if len(public_key) != PUBLIC_KEY_BYTES:
+        raise AttestError(f"public_key must be {PUBLIC_KEY_BYTES} bytes")
+    return hashlib.sha256(bytes(public_key)).digest()
+
+
+def generate_keypair(seed: bytes = None) -> dict:
+    """Generate an Ed25519 key pair and its AID.
+
+    :param seed: 32-byte seed. **For reproducible test vectors only**; omit in
+                 production and let the OS entropy source decide.
+    """
+    _require_backend()
+    if seed is None:
+        private_key = Ed25519PrivateKey.generate()
+    else:
+        if not isinstance(seed, (bytes, bytearray)) or len(seed) != SEED_BYTES:
+            raise AttestError(f"seed must be {SEED_BYTES} bytes")
+        private_key = Ed25519PrivateKey.from_private_bytes(bytes(seed))
+
+    raw_seed = private_key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    public_key = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    aid_bytes = aid_from_public_key(public_key)
+
+    return {
+        "private_key": private_key,          # signing use — never share
+        "seed": raw_seed,                    # 32B seed — never share
+        "public_key": public_key,            # 32B
+        "aid": aid_bytes,                    # 32B = sha256(public_key)
+        "seed_hex": raw_seed.hex(),
+        "public_hex": public_key.hex(),
+        "aid_hex": aid_bytes.hex(),
+    }
+
+
+def public_bundle(keypair: dict) -> dict:
+    """The safely publishable part (identity + public key), no private material."""
+    return {"alg": ALG, "aid": keypair["aid_hex"], "pub": keypair["public_hex"]}
+
+
+# ---------------------------------------------------------------------------
+# Canonical signing input
+# ---------------------------------------------------------------------------
+
+def _hex_lower(value, what: str, nbytes: int) -> str:
+    if not isinstance(value, str):
+        raise AttestError(f"{what} must be a hex string")
+    if value != value.lower():
+        raise AttestError(f"{what} must be lowercase hex (RFC-009 §10.3 discipline)")
+    if len(value) != nbytes * 2:
+        raise AttestError(f"{what} must be {nbytes} bytes ({nbytes * 2} hex chars)")
+    try:
+        bytes.fromhex(value)
+    except ValueError as exc:
+        raise AttestError(f"{what} is not valid hex: {exc}") from exc
+    return value
+
+
+def json_canonical(obj) -> bytes:
+    """Deterministic JSON encoding (UTF-8, sorted keys, no insignificant whitespace)."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def signing_input(alg: str, aid_hex: str, pub_hex: str, ts: int, nonce: str,
+                  payload: dict) -> bytes:
+    """The signed byte sequence. Every envelope field except ``sig`` enters it.
+
+    ``ts`` / ``nonce`` MUST be inside the signature — beside it, rewriting the
+    replay window would not touch Ed25519 at all.
+    """
+    return CANONICAL_PREFIX + json_canonical({
+        "alg": alg,
+        "aid": aid_hex,
+        "pub": pub_hex,
+        "ts": ts,
+        "nonce": nonce,
+        "payload": payload,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Attestation claims
+# ---------------------------------------------------------------------------
+
+def build_claim(subject_uri: str, organ: str, standing: str) -> dict:
+    """Build and validate an attestation payload (closed sets enforced).
+
+    The subject URI must parse; ``organ`` and ``standing`` must be members of
+    their closed sets. A claim that violates the grammar is not built — it is
+    rejected, so an envelope can never carry a subject URI the codec itself
+    would reject.
+    """
+    parsed = iqa_uri.parse(subject_uri)  # raises IqaUriError on any violation
+    if organ not in iqa_uri.ORGANS:
+        raise AttestError(f"organ {organ!r} is outside the closed set {list(iqa_uri.ORGANS)}")
+    if standing not in STANDINGS:
+        raise AttestError(f"standing {standing!r} is outside the closed set {list(STANDINGS)}")
+    if organ != parsed["organ"]:
+        raise AttestError("organ does not match the subject URI's organ")
+    return {
+        "subject_uri": parsed["canonical_uri"],
+        "organ": organ,
+        "standing": standing,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Seal / verify
+# ---------------------------------------------------------------------------
+
+def seal(payload: dict, keypair: dict, ts: int = None, nonce: str = None) -> dict:
+    """Seal a payload into a self-certifying envelope with your own key.
+
+    :param ts:    unix seconds. Omitted = now. **Pass it only to produce
+                  reproducible vectors** — in production it pins the replay window.
+    :param nonce: ``NONCE_BYTES`` bytes as lowercase hex. Omitted = OS entropy.
+    """
+    _require_backend()
+    if not isinstance(payload, dict):
+        raise AttestError("payload must be a dict")
+    if not isinstance(keypair, dict) or "private_key" not in keypair:
+        raise AttestError("keypair must come from generate_keypair()")
+
+    if ts is None:
+        ts = int(time.time())
+    if not isinstance(ts, int) or isinstance(ts, bool):
+        raise AttestError("ts must be an integer (unix seconds)")
+
+    if nonce is None:
+        nonce = os.urandom(NONCE_BYTES).hex()
+    _hex_lower(nonce, "nonce", NONCE_BYTES)
+
+    aid_hex = keypair["aid_hex"]
+    pub_hex = keypair["public_hex"]
+    signature = keypair["private_key"].sign(
+        signing_input(ALG, aid_hex, pub_hex, ts, nonce, payload))
+
+    return {
+        "v": ENVELOPE_VERSION,
+        "alg": ALG,
+        "aid": aid_hex,
+        "pub": pub_hex,
+        "ts": ts,
+        "nonce": nonce,
+        "sig": signature.hex(),
+        "payload": payload,
+    }
+
+
+def verify_envelope(envelope: dict, now: int = None,
+                    max_skew: int = MAX_CLOCK_SKEW,
+                    check_freshness: bool = True) -> tuple:
+    """Verify an envelope. Returns ``(ok: bool, reason: str, aid_hex | None)``.
+
+    Any failed step returns False — **a check that cannot be performed is a
+    failure, never a pass.**
+
+    :param check_freshness: default True. False is **only** for archived
+        envelopes (audit records, test vectors). On live network input it must
+        stay True — turn it off and replay attacks become trivial.
+    """
+    try:
+        _require_backend()
+
+        if not isinstance(envelope, dict):
+            return False, "envelope must be a dict", None
+        if envelope.get("v") != ENVELOPE_VERSION:
+            return False, f"unsupported envelope version: {envelope.get('v')!r}", None
+        if envelope.get("alg") != ALG:
+            return False, f"unsupported algorithm: {envelope.get('alg')!r}", None
+
+        aid_hex = _hex_lower(envelope.get("aid"), "aid", AID_BYTES)
+        pub_hex = _hex_lower(envelope.get("pub"), "pub", PUBLIC_KEY_BYTES)
+        sig_hex = _hex_lower(envelope.get("sig"), "sig", SIGNATURE_BYTES)
+        nonce = _hex_lower(envelope.get("nonce"), "nonce", NONCE_BYTES)
+
+        ts = envelope.get("ts")
+        if not isinstance(ts, int) or isinstance(ts, bool):
+            return False, "ts must be an integer (unix seconds)", None
+
+        payload = envelope.get("payload")
+        if not isinstance(payload, dict):
+            return False, "payload must be an object", None
+
+        if check_freshness:
+            reference = int(time.time()) if now is None else now
+            drift = abs(reference - ts)
+            if drift > max_skew:
+                return False, (f"timestamp skew too large ({drift}s > {max_skew}s)"
+                               " - replay?"), None
+
+        public_key = bytes.fromhex(pub_hex)
+
+        # --- self-certification: identity is derived, not claimed ---
+        if aid_from_public_key(public_key).hex() != aid_hex:
+            return False, "AID does not match public key (self-certification failed)", None
+
+        Ed25519PublicKey.from_public_bytes(public_key).verify(
+            bytes.fromhex(sig_hex),
+            signing_input(ALG, aid_hex, pub_hex, ts, nonce, payload),
+        )
+        return True, "sealed", aid_hex
+
+    except InvalidSignature:
+        return False, "bad seal (signature does not verify)", None
+    except AttestError as exc:
+        return False, str(exc), None
+    except (ValueError, TypeError, KeyError) as exc:
+        return False, f"malformed envelope: {exc}", None
+
+
+def verify_attestation(envelope: dict, expected_subject_uri: str = None,
+                       now: int = None, check_freshness: bool = True) -> tuple:
+    """Verify an envelope **and** its claim payload (closed sets, URI grammar).
+
+    The signature proves who said it; the claim checks make sure what they said
+    is at least well-formed. Neither proves the standing is true — trusting an
+    attestation is a different act from verifying one.
+    """
+    ok, reason, _aid = verify_envelope(envelope, now=now,
+                                       check_freshness=check_freshness)
+    if not ok:
+        return False, reason
+    payload = envelope["payload"]
+    try:
+        claim = build_claim(payload.get("subject_uri"), payload.get("organ"),
+                            payload.get("standing"))
+    except (AttestError, IqaUriError) as exc:
+        return False, f"claim payload malformed: {exc}", None
+    if expected_subject_uri is not None:
+        if claim["subject_uri"] != iqa_uri.parse(expected_subject_uri)["canonical_uri"]:
+            return False, "subject URI mismatch (cited a different subject?)", None
+    return True, "sealed", None
+
+
+def unseal(envelope: dict, now: int = None, check_freshness: bool = True) -> dict:
+    """Return the payload if the envelope verifies; raise AttestError otherwise."""
+    ok, reason, _aid = verify_envelope(envelope, now=now,
+                                       check_freshness=check_freshness)
+    if not ok:
+        raise AttestError(reason)
+    return envelope["payload"]

iqa/iqa_uri.py

@@ -0,0 +1,170 @@
+"""iqa:// URI codec — validate, canonicalise, derive (RFC-009 §10/§11).
+
+Authority boundaries
+    Grammar ......... RFC-009 §10.2 ABNF (sole authority; this module implements it)
+    Closed sets ..... §10.1 ("Closed set" stated for both organ and action)
+    Case discipline . §10.3 (lowercase US-ASCII only) + §12 #8 (fail closed)
+    Deref safety .... §11.3 (action safety classes)
+    Route derivation  SPEC/IQA-URI-ATTEST-v1.2.6.md §3 (IQA_ROUTE)
+
+Design rules inherited from the RTTP codec discipline:
+    * Malformed input is REJECTED, never normalised.
+    * A check that cannot be performed is a failure, never a pass.
+    * Zero dependencies: standard library only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+SCHEME = "iqa"
+
+#: RFC-009 §10.1 — organ is a CLOSED set (RFC-009-A/-B/-C).
+ORGANS = ("forge", "tss", "gateway")
+
+#: RFC-009 §10.1 — action is a CLOSED set (differs from `rttp`, whose verb set
+#: is open; here anything outside the four verbs is rejected).
+ACTIONS = ("verify", "audit", "attest", "revoke")
+
+#: RFC-009 §11.3 — safety classes. Omitted action = standing read (SAFE);
+#: `verify` compares, writes nothing (SAFE). The other three are state
+#: transitions or potentially harmful measurements (NOT SAFE).
+SAFE_ACTIONS = frozenset({None, "verify"})
+UNSAFE_ACTIONS = frozenset({"audit", "attest", "revoke"})
+
+#: Standing values an Organ may render (RFC-009-C §3) — closed set, lowercase.
+STANDINGS = ("ghost", "probation", "radiant", "genesis")
+
+#: RFC-009 §10.2 — hash-subject lengths: routing short form / 128-bit / 256-bit.
+HASH_LENGTHS = (8, 32, 64)
+
+_LOWHEX = frozenset("0123456789abcdef")
+_NAME_CHARS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789-")
+#: §10.3: a string containing any of these is NOT a valid iqa URI. Enforced
+#: implicitly by the allowed-charset scan; listed here for documentation.
+_FORBIDDEN_CHARS = "@:?#[]"
+
+_ALLOWED = _LOWHEX | _NAME_CHARS | frozenset("./")
+
+
+class IqaUriError(ValueError):
+    """The only error type raised by this module."""
+
+
+def _fail(uri: str, reason: str) -> "IqaUriError":
+    return IqaUriError(f"{uri!r}: {reason}")
+
+
+def is_valid_action(value: str) -> bool:
+    """§10.2 action test — True only for the closed four-verb set."""
+    return value in ACTIONS
+
+
+def derive_route(authority: str) -> bytes:
+    """IQA_ROUTE = SHA-256(ASCII(canonical_authority))[0:4].
+
+    Pure computation, DNS-free (RFC-009 §12 #9). Mirrors the RTTP ROUTE_SHARD
+    rule (SHA-256(authority)[0:16]) so the two schemes of the same addressing
+    family derive the same way. NOTE: this is the *address* fingerprint — it is
+    NOT the subject hash, which is a routing hint for the *AID*. The two numbers
+    are about different things and MUST NOT be conflated.
+    """
+    if not authority:
+        raise IqaUriError("derive_route: authority is empty")
+    return hashlib.sha256(authority.encode("ascii")).digest()[:4]
+
+
+def derive_route_hex(authority: str) -> str:
+    """The same four bytes, as 8 lowercase hex characters."""
+    return derive_route(authority).hex()
+
+
+def parse(uri: str) -> dict:
+    """Validate, canonicalise and derive. Raises IqaUriError on any violation.
+
+    Returned fields are snake_case ON PURPOSE so the Python and JavaScript
+    implementations compare field for field against the published vectors.
+    """
+    if not isinstance(uri, str):
+        raise _fail(uri, "input must be a string")
+
+    # Scheme — exact lowercase prefix. IQA://, iqas://, https:// ... all fail here.
+    prefix = SCHEME + "://"
+    if not uri.startswith(prefix):
+        raise _fail(uri, f"scheme must be exactly {prefix!r} - no other scheme, "
+                         "no case variant, no fallback (RFC-009 §10.3, §12 #8)")
+    rest = uri[len(prefix):]
+
+    # Charset gate: lowercase US-ASCII only (§10.3). This single scan rejects
+    # uppercase anywhere (scheme, subject, organ, action), userinfo '@', port
+    # ':', query '?', fragment '#', whitespace and every other foreign byte.
+    for ch in rest:
+        if ch not in _ALLOWED:
+            if ch in _FORBIDDEN_CHARS:
+                raise _fail(uri, f"{ch!r} is not defined by the scheme (RFC-009 §10.3)")
+            if ch.isspace():
+                raise _fail(uri, "whitespace is not allowed (RFC-009 §10.3 lowercase US-ASCII only)")
+            raise _fail(uri, f"character {ch!r} is outside the allowed set "
+                             "(lowercase US-ASCII, digits, '-', '.', '/')")
+
+    # Path: at most one '/', and the action behind it must be non-empty.
+    if "/" in rest:
+        authority, _, action = rest.partition("/")
+        if action == "":
+            raise _fail(uri, "trailing '/' with empty action - action is a "
+                             "closed-set verb, not omissible by empty string (§10.2)")
+        if "/" in action:
+            raise _fail(uri, "second path segment - path is a single '/<action>' (§10.2)")
+    else:
+        authority, action = rest, None
+
+    # Authority: exactly three segments.
+    segments = authority.split(".")
+    if len(segments) != 3:
+        raise _fail(uri, f"authority has {len(segments)} segment(s), "
+                         "must be <subject>.<organ>.<root> (RFC-009 §10.2)")
+    subject, organ, root = segments
+    if subject == "" or root == "":
+        raise _fail(uri, "authority segments must be non-empty (RFC-009 §10.2)")
+
+    # Subject: hash form (8/32/64 lowercase hex) or name form (RFC-009 §10.2).
+    # Ordered choice per the ABNF: all-lowerhex input is tried as hash-subject
+    # first; a lowercase-hex string of another length is therefore a NAME
+    # subject, exactly as the grammar says. Documented, not "fixed".
+    if all(c in _LOWHEX for c in subject):
+        if len(subject) in HASH_LENGTHS:
+            subject_is_hash = True
+            subject_hex = subject
+        else:
+            subject_is_hash = False
+            subject_hex = None
+    else:
+        subject_is_hash = False
+        subject_hex = None
+
+    # Organ — CLOSED set, case-sensitive (§10.1). 'Forge', 'forgery', '' all fail.
+    if organ not in ORGANS:
+        raise _fail(uri, f"organ {organ!r} is outside the closed set "
+                         f"{list(ORGANS)} (RFC-009 §10.1/§10.3)")
+
+    # Action — CLOSED set (§10.1). This is the deliberate difference from rttp.
+    if action is not None and action not in ACTIONS:
+        raise _fail(uri, f"action {action!r} is outside the closed set "
+                         f"{list(ACTIONS)} (RFC-009 §10.1)")
+
+    canonical_uri = SCHEME + "://" + authority + ("/" + action if action else "")
+
+    return {
+        "scheme": SCHEME,
+        "subject": subject,
+        "subject_is_hash": subject_is_hash,
+        "subject_hex": subject_hex,
+        "organ": organ,
+        "root": root,
+        "authority": authority,
+        "action": action,
+        "action_omitted": action is None,
+        "action_safe": action in SAFE_ACTIONS,          # §11.3
+        "canonical_uri": canonical_uri,
+        "route_hex": derive_route_hex(authority),       # SPEC §3
+    }