aics-cli 0.1.0__py3-none-any.whl

aics_cli/encoding.py

@@ -0,0 +1,125 @@
+"""Base64 helpers.
+
+* ``b64e`` / ``b64d_strict``: standard alphabet with padding, canonical -
+  the form used by signed notes, checkpoints and the text protocol's
+  ``pub`` / ``sig`` lines.
+* ``b64d_lenient``: what the gate accepts from an agent - standard or
+  URL-safe alphabet, padding optional, ASCII whitespace ignored.
+* ``b64u_e`` / ``b64u_d``: base64url without padding (JWS, RFC 7515 §2).
+
+It also holds :func:`escape_untrusted`, which every text-mode output uses for
+strings that come from a server (card free text, error details): they must
+never add lines or terminal escape sequences to the verifier's own verdict.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+
+_WS = str.maketrans("", "", " \t\r\n\v\f")
+_B64URL_RE = re.compile(r"[A-Za-z0-9_-]*")
+
+
+def b64e(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def b64d_strict(text: str) -> bytes:
+    """Canonical standard base64 with padding; anything else raises ValueError."""
+    if not isinstance(text, str) or not text or len(text) % 4:
+        raise ValueError("not canonical base64")
+    try:
+        raw = base64.b64decode(text, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"invalid base64: {exc}") from None
+    if base64.b64encode(raw).decode("ascii") != text:
+        raise ValueError("not canonical base64")
+    return raw
+
+
+def b64d_lenient(text: str) -> bytes:
+    """Standard or URL-safe alphabet, padding optional, whitespace ignored."""
+    if isinstance(text, bytes):
+        text = text.decode("ascii")
+    compact = text.translate(_WS)
+    if "-" in compact or "_" in compact:
+        if "+" in compact or "/" in compact:
+            raise ValueError("base64 mixes the standard and URL-safe alphabets")
+        compact = compact.replace("-", "+").replace("_", "/")
+    stripped = compact.rstrip("=")
+    if len(compact) - len(stripped) > 2 or len(stripped) % 4 == 1 or not stripped:
+        raise ValueError("invalid base64 length or padding")
+    try:
+        return base64.b64decode(stripped + "=" * (-len(stripped) % 4), validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"invalid base64: {exc}") from None
+
+
+def b64u_e(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def b64u_d(text: str) -> bytes:
+    """base64url without padding (RFC 7515); rejects characters outside the alphabet."""
+    if not isinstance(text, str):
+        raise ValueError("base64url value must be a string")
+    if not _B64URL_RE.fullmatch(text) or len(text) % 4 == 1:
+        raise ValueError("invalid base64url")
+    try:
+        return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"invalid base64url: {exc}") from None
+
+
+def escape_untrusted(text: str) -> str:
+    """``text`` with every non-printable character (control, format, line and
+    paragraph separators, ...) written as ``\\uXXXX`` / ``\\UXXXXXXXX``, so an
+    untrusted string prints as exactly one line with no escape sequences."""
+    if not isinstance(text, str):
+        text = str(text)
+    out = []
+    for c in text:
+        if c.isprintable() and c != "\\":
+            out.append(c)
+        elif c == "\\":
+            out.append("\\\\")
+        elif ord(c) <= 0xFFFF:
+            out.append(f"\\u{ord(c):04x}")
+        else:
+            out.append(f"\\U{ord(c):08x}")
+    return "".join(out)
+
+
+def printable_line(line: str) -> str:
+    """The last pass over every text-mode output line: non-printable
+    characters become ``\\uXXXX`` (backslashes are left alone, so JSON
+    printed as text stays valid JSON)."""
+    if line.isprintable():
+        return line
+    return "".join(c if c.isprintable() else (f"\\u{ord(c):04x}" if ord(c) <= 0xFFFF else f"\\U{ord(c):08x}")
+                   for c in line)
+
+
+def parse_hash_lines(text: str, *, max_hashes: int = 256) -> list[bytes]:
+    """One 32-byte hash per line, base64 or 64 hex characters (the
+    ``aics-tlog`` proof-file format).  Blank lines are ignored."""
+    out: list[bytes] = []
+    for lineno, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        if len(line) == 64 and all(c in "0123456789abcdefABCDEF" for c in line):
+            h = bytes.fromhex(line)
+        else:
+            try:
+                h = b64d_lenient(line)
+            except ValueError as exc:
+                raise ValueError(f"proof line {lineno}: {exc}") from None
+        if len(h) != 32:
+            raise ValueError(f"proof line {lineno}: hash must be 32 bytes, got {len(h)}")
+        out.append(h)
+        if len(out) > max_hashes:
+            raise ValueError("proof too long")
+    return out

aics_cli/errors.py

@@ -0,0 +1,57 @@
+"""Exceptions and exit codes shared by every command.
+
+Exit codes (the contract every ``aics`` command keeps):
+
+* 0 - verified;
+* 1 - error: bad input, missing policy, network failure, or a check that
+  could not be completed (inconclusive), a stale head, an older head kept as
+  historical, or an invalid note from a source other than the log origin;
+* 2 - verification failed and the output carries the evidence;
+* 3 - the command needs a server feature that does not exist yet.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_EVIDENCE = 2
+EXIT_UNAVAILABLE = 3
+
+
+class AicsError(Exception):
+    """An error that ends a command with exit code 1."""
+
+    exit_code = EXIT_ERROR
+
+    def __init__(self, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+
+class UsageError(AicsError):
+    """Bad command line (argparse would exit 2, which means evidence here)."""
+
+
+class PolicyError(AicsError):
+    """The pinned policy is missing, malformed or refused."""
+
+
+class FetchError(AicsError):
+    """A network fetch failed at the transport level (no HTTP answer)."""
+
+
+class DnsError(AicsError):
+    """A DNS TXT lookup failed (not "no such record": that returns [])."""
+
+
+class VerificationFailed(AicsError):
+    """Verification failed; ``evidence`` is printed so others can check it."""
+
+    exit_code = EXIT_EVIDENCE
+
+    def __init__(self, message: str, evidence: dict[str, Any] | None = None, **details: Any) -> None:
+        super().__init__(message, **details)
+        self.evidence = evidence or {}

aics_cli/evidence.py

@@ -0,0 +1,88 @@
+"""Split-view evidence bundles (docs/DESIGN.md §3 G5, docs/spec/AICS-1.md §14.6).
+
+A bundle is self-contained: the pinned log key and witness policy, every
+log-signed note involved (full text, so signatures and cosignatures can be
+re-checked), the authenticated proof material, and the ``aics-tlog``
+commands a third party runs to check it without this tool.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from . import __version__
+from .checkpoints import Cp
+from .consistency import Attempt, Relation
+from .encoding import b64e
+from .policy import Policy
+
+BUNDLE_TYPE = "aics-split-view-evidence/v1"
+
+REASONS = {
+    "equal-size-different-root": "two log-signed checkpoints with the same origin and size but different roots",
+    "not-a-prefix": "a log-signed checkpoint is not a prefix of a newer log-signed checkpoint: its root differs "
+                    "from the newer tree's authenticated root at that size",
+    "rollback": "the log now serves a smaller tree than one it signed earlier; an append-only log never shrinks, "
+                "so the smaller head is not accepted as current",
+    "bad-empty-root": "a log-signed checkpoint of size 0 whose root is not SHA-256(\"\"); no append-only log can "
+                      "produce it (AICS-1 §14.2 step 1)",
+}
+
+
+def _check_commands(policy: Policy, old: Cp, new: Cp, att: Attempt | None) -> list[str]:
+    cmds = [
+        f"aics-tlog verify-checkpoint --note note-{i}.txt --log-key '{cp.log_vkey or policy.log_vkey}' "
+        f"--origin '{policy.origin}'"
+        for i, cp in ((1, old), (2, new))
+    ]
+    if att is not None and att.proof is not None and att.prefix_root is not None:
+        cmds.append(
+            f"aics-tlog verify-consistency --old-size {old.size} --new-size {new.size} "
+            f"--old-root '{b64e(att.prefix_root)}' --new-root '{new.root_b64}' --proof proof.b64"
+            f"   # succeeds; compare --old-root with note 1's root {old.root_b64}"
+        )
+    return cmds
+
+
+def split_bundle(policy: Policy, rel: Relation, *, now: int, context: str,
+                 witness_status: dict[str, bool] | None = None) -> dict[str, Any]:
+    """Evidence for every inconsistent pair found while relating two notes.
+
+    ``witness_status`` maps note SHA-256 to whether that note met the
+    witness policy; a conflict between notes that did not all meet it is
+    labelled ``log-equivocation`` rather than ``split-proven`` (the log key
+    signed both, but clients following the policy would not have accepted
+    both).  Notes saved under an earlier pinned log key carry that key."""
+    pairs = []
+    met_all = True
+    for old, new, att in rel.split_pairs:
+        notes = [old.evidence(), new.evidence()]
+        if witness_status is not None:
+            for n in notes:
+                n["witness_policy_met"] = witness_status.get(n["sha256"])
+                if n["witness_policy_met"] is False:
+                    met_all = False
+        entry: dict[str, Any] = {"notes": notes, "check": _check_commands(policy, old, new, att)}
+        if att is not None:
+            entry["proof"] = att.report()
+        pairs.append(entry)
+    reason = rel.reason or "not-a-prefix"
+    classification = "split-proven" if met_all else "log-equivocation"
+    if reason == "rollback":
+        classification = "rollback"
+    return {
+        "type": BUNDLE_TYPE,
+        "classification": classification,
+        "reason": reason,
+        "explanation": REASONS.get(reason, reason),
+        "context": context,
+        "origin": policy.origin,
+        "log_vkey": policy.log_vkey,
+        "witness_policy": {"quorum": policy.quorum, "witnesses": policy.witness_vkeys,
+                           "max_checkpoint_age": policy.max_checkpoint_age},
+        "pairs": pairs,
+        "attempts": [a.report() for a in rel.attempts],
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now)),
+        "generator": f"aics {__version__}",
+    }

aics_cli/home.py

@@ -0,0 +1,112 @@
+"""Layout of the agent's local state directory (default ``~/.aics``).
+
+::
+
+    ~/.aics/                    0700
+      aics.key                  Ed25519 private key, PKCS#8 PEM (what
+                                ``openssl genpkey -algorithm ed25519`` writes), 0600
+      aics-x.key                X25519 private key, PKCS#8 PEM (what
+                                ``openssl genpkey -algorithm X25519`` writes), 0600
+      identity.json             public keys only
+      policy.toml               pinned keys and URLs (``aics policy init``)
+      policy-history/           policies replaced with ``--force``
+      checkpoints/              append-only: verified checkpoint notes
+        index.jsonl             one line per save, with its role (head/evidence/observed)
+                                and log key; ``reset`` lines (--reset-history)
+        <origin>/<size>-<sha256>.note
+      cards/                    append-only: verified assurance cards
+        index.jsonl
+        <policy key>/<card hash>.json
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+ED25519_KEY = "aics.key"
+X25519_KEY = "aics-x.key"
+IDENTITY = "identity.json"
+POLICY = "policy.toml"
+
+
+def default_home() -> Path:
+    env = os.environ.get("AICS_HOME")
+    if env:
+        return Path(env).expanduser()
+    return Path("~/.aics").expanduser()
+
+
+def ensure_dir(path: Path, mode: int = 0o700) -> Path:
+    path.mkdir(parents=True, exist_ok=True, mode=mode)
+    return path
+
+
+def slug(text: str) -> str:
+    """A filesystem-safe, collision-resistant directory name for an origin or host."""
+    safe = re.sub(r"[^A-Za-z0-9._-]+", "_", text).strip("._") or "_"
+    if safe != text:
+        import hashlib
+
+        safe = f"{safe[:80]}-{hashlib.sha256(text.encode('utf-8')).hexdigest()[:8]}"
+    return safe
+
+
+def write_new(path: Path, data: bytes, mode: int = 0o644) -> bool:
+    """Create ``path`` with ``data``; never replace an existing file.
+
+    Returns True if created, False if the file already holds exactly
+    ``data``.  Raises FileExistsError if it holds something else.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+    except FileExistsError:
+        if path.read_bytes() == data:
+            return False
+        raise
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+            fh.flush()
+            os.fsync(fh.fileno())
+    except BaseException:
+        try:
+            path.unlink()
+        except OSError:
+            pass
+        raise
+    return True
+
+
+def append_jsonl(path: Path, record: dict[str, Any]) -> None:
+    """Append one JSON line (O_APPEND; never rewrites earlier lines)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    line = (json.dumps(record, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        os.write(fd, line)
+    finally:
+        os.close(fd)
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    try:
+        text = path.read_text("utf-8")
+    except FileNotFoundError:
+        return out
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            continue  # a torn final line from a crash; earlier lines stay valid
+        if isinstance(obj, dict):
+            out.append(obj)
+    return out

aics_cli/keystore.py

@@ -0,0 +1,189 @@
+"""The agent's own keys: ``aics keys new`` / ``aics keys show``.
+
+Ed25519 (identity, signing) and X25519 (end-to-end encryption) private
+keys are generated locally and written as PKCS#8 PEM with mode 0600, the
+same file format ``openssl genpkey -algorithm ed25519`` produces, so the
+agent can also sign with ``openssl pkeyutl`` as docs/PROTOCOL-TEXT.md §3
+describes.  An OpenSSH private key (``ssh-keygen -t ed25519``) is accepted
+for signing as well.
+
+Public forms printed are the gate's replies (docs/spec/AICS-1.md §11.4,
+PROTOCOL-TEXT.md §3): ``pub <base64 of the raw 32 bytes>`` for the Ed25519
+key and ``enc <base64 of 32 bytes>`` for the X25519 key, then the signing
+``did:key`` (the agent's ``kid``) and the encryption DID.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from aics_identity import keys as idkeys
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+
+from . import home as _home
+from .encoding import b64e
+from .errors import AicsError
+
+
+@dataclass
+class PublicIdentity:
+    ed25519: bytes
+    x25519: bytes | None
+
+    def to_dict(self) -> dict[str, Any]:
+        pub = idkeys.public_key_from_bytes(self.ed25519)
+        d: dict[str, Any] = {
+            "pub": f"pub {b64e(self.ed25519)}",
+            "ed25519": b64e(self.ed25519),
+            "kid": idkeys.did_key(pub),
+            "enc": None,
+            "x25519": None,
+            "x25519_did": None,
+        }
+        if self.x25519 is not None:
+            from aics_identity.sealed import x25519_did_key
+
+            d.update(enc=f"enc {b64e(self.x25519)}", x25519=b64e(self.x25519),
+                     x25519_did=x25519_did_key(self.x25519))
+        return d
+
+    def lines(self) -> list[str]:
+        d = self.to_dict()
+        out = [d["pub"]]
+        if d["enc"]:
+            out.append(d["enc"])
+        out.append(d["kid"])
+        if d["x25519_did"]:
+            out.append(d["x25519_did"])
+        return out
+
+
+def _pem(key: Ed25519PrivateKey | X25519PrivateKey) -> bytes:
+    return key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def _write_private(path: Path, data: bytes) -> None:
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "wb") as fh:
+        os.fchmod(fh.fileno(), 0o600)
+        fh.write(data)
+        fh.flush()
+        os.fsync(fh.fileno())
+
+
+def new_keys(directory: Path) -> tuple[PublicIdentity, list[Path]]:
+    """Generate Ed25519 + X25519 keys in ``directory``; refuses to overwrite."""
+    _home.ensure_dir(directory)
+    try:
+        os.chmod(directory, 0o700)
+    except OSError:
+        pass
+    ed_path = directory / _home.ED25519_KEY
+    x_path = directory / _home.X25519_KEY
+    existing = [p for p in (ed_path, x_path) if p.exists()]
+    if existing:
+        raise AicsError(
+            "refusing to overwrite existing keys (losing them loses the identity); "
+            "move them away or use another --dir",
+            existing=[str(p) for p in existing],
+        )
+    ed_key = idkeys.generate_keypair()
+    x_key = X25519PrivateKey.generate()
+    _write_private(ed_path, _pem(ed_key))
+    _write_private(x_path, _pem(x_key))
+    ident = PublicIdentity(
+        ed25519=idkeys.public_key_bytes(ed_key.public_key()),
+        x25519=x_key.public_key().public_bytes_raw(),
+    )
+    info = ident.to_dict()
+    info["created"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    id_path = directory / _home.IDENTITY
+    tmp = id_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(info, indent=2, sort_keys=True) + "\n", "utf-8")
+    os.replace(tmp, id_path)
+    return ident, [ed_path, x_path, id_path]
+
+
+def load_ed25519_private(path: Path) -> Ed25519PrivateKey:
+    """Load an Ed25519 private key: PKCS#8 PEM/DER (openssl) or OpenSSH."""
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        raise AicsError(f"no key at {path}; run: aics keys new") from None
+    try:
+        if b"BEGIN OPENSSH PRIVATE KEY" in data:
+            key = serialization.load_ssh_private_key(data, password=None)
+        elif data.lstrip().startswith(b"-----BEGIN"):
+            key = serialization.load_pem_private_key(data, password=None)
+        else:
+            key = serialization.load_der_private_key(data, password=None)
+    except (ValueError, TypeError) as exc:
+        raise AicsError(f"cannot read private key {path}: {exc} (encrypted keys are not supported)") from None
+    if not isinstance(key, Ed25519PrivateKey):
+        raise AicsError(f"{path} is not an Ed25519 private key")
+    return key
+
+
+def load_x25519_private(path: Path) -> X25519PrivateKey | None:
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return None
+    try:
+        key = serialization.load_pem_private_key(data, password=None)
+    except (ValueError, TypeError) as exc:
+        raise AicsError(f"cannot read X25519 key {path}: {exc}") from None
+    if not isinstance(key, X25519PrivateKey):
+        raise AicsError(f"{path} is not an X25519 private key")
+    return key
+
+
+def permission_warning(path: Path) -> str | None:
+    try:
+        mode = stat.S_IMODE(path.stat().st_mode)
+    except OSError:
+        return None
+    if mode & 0o077:
+        return f"{path} is readable by others (mode {mode:o}); chmod 600 it"
+    return None
+
+
+def show_keys(directory: Path) -> tuple[PublicIdentity, list[str]]:
+    ed = load_ed25519_private(directory / _home.ED25519_KEY)
+    x = load_x25519_private(directory / _home.X25519_KEY)
+    warnings = [w for w in (permission_warning(directory / _home.ED25519_KEY),
+                            permission_warning(directory / _home.X25519_KEY)) if w]
+    ident = PublicIdentity(
+        ed25519=idkeys.public_key_bytes(ed.public_key()),
+        x25519=x.public_key().public_bytes_raw() if x is not None else None,
+    )
+    return ident, warnings
+
+
+def parse_public_key_text(text: str) -> Ed25519PublicKey:
+    """The public-key forms an agent hands the gate (PROTOCOL-TEXT.md §3):
+    ``pub <base64>``, ``pub ssh-ed25519 <base64> [comment]``, bare base64
+    (either alphabet, padding optional) or ``did:key:z...``.  Small-order and
+    non-canonical keys are refused (aics_identity)."""
+    import re
+
+    t = text.strip()
+    m = re.match(r"pub(?::\s*|\s+)(.*)$", t, re.IGNORECASE | re.DOTALL)
+    if m:
+        t = m.group(1).strip()
+    try:
+        return idkeys.parse_public_key_text(t)
+    except (ValueError, TypeError) as exc:
+        raise AicsError(f"bad public key: {exc}") from None