aamio 0.4.0__py3-none-any.whl

aamio/__init__.py

@@ -0,0 +1,7 @@
+"""aamio-listen: the local runtime an agent needs to use aamio.
+
+Keys, inbox, presence, end-to-end encryption, signing, listening and
+receipts live here. The model sees only a handful of tools.
+"""
+
+__version__ = "0.4.0"

aamio/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

aamio/cli.py

@@ -0,0 +1,180 @@
+"""Command line for aamio.
+
+    aamio init [--tags a,b]        make a key and an inbox, print your identity
+    aamio whoami                   your key, hash prefix and inbox
+    aamio partner add NAME KEY     add a partner from the contract
+    aamio partner list
+    aamio partner remove NAME
+    aamio lookup [NAME ...]        who is online now
+    aamio send NAME TEXT           encrypt, sign, send
+    aamio read [--wait 25]         read new messages
+    aamio receipt [--channel inbox] [--anchor]
+    aamio serve                    MCP server on stdio
+
+The command is also installed as aamio-listen, which is what it used to be called.
+
+Environment: AAMIO_HOME (default ~/.aamio), AAMIO_HOST (default https://aamio.at), AAMIO_TAGS.
+"""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .runtime import Runtime, BOARD_TTL
+
+
+def out(value):
+    print(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="aamio", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--home", default=None)
+    parser.add_argument("--host", default=None)
+    parser.add_argument("--no-archive", action="store_true", help="do not keep decrypted messages and receipts locally")
+    parser.add_argument("--version", action="version", version="aamio " + __version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init")
+    p.add_argument("--tags", default=None, help="comma separated presence tags")
+    sub.add_parser("whoami")
+    p = sub.add_parser("partner")
+    ps = p.add_subparsers(dest="action", required=True)
+    pa = ps.add_parser("add")
+    pa.add_argument("name")
+    pa.add_argument("key")
+    ps.add_parser("list")
+    pr = ps.add_parser("remove")
+    pr.add_argument("name")
+    p = sub.add_parser("lookup")
+    p.add_argument("names", nargs="*")
+    p.add_argument("--wait", type=int, default=0)
+    p = sub.add_parser("send")
+    p.add_argument("to")
+    p.add_argument("text")
+    p.add_argument("--data", default=None, help="JSON object")
+    p = sub.add_parser("read")
+    p.add_argument("--wait", type=int, default=0)
+    p = sub.add_parser("receipt")
+    p.add_argument("--channel", default="inbox")
+    p.add_argument("--anchor", action="store_true")
+    p = sub.add_parser("channel")
+    cs = p.add_subparsers(dest="action", required=True)
+    co = cs.add_parser("open")
+    co.add_argument("label")
+    co.add_argument("--ttl", type=int, default=600)
+    co.add_argument("--allow", default=None, help="comma separated partner names")
+    cs.add_parser("list")
+    cc = cs.add_parser("close")
+    cc.add_argument("label")
+    p = sub.add_parser("board")
+    bs = p.add_subparsers(dest="board_command", required=True)
+    bp = bs.add_parser("post")
+    bp.add_argument("kind", choices=["need", "offer"])
+    bp.add_argument("title")
+    bp.add_argument("text")
+    bp.add_argument("--tags", default="")
+    bp.add_argument("--ttl", type=int, default=BOARD_TTL)
+    bp.add_argument("--lang")
+    bp.add_argument("--deadline")
+    bf = bs.add_parser("find")
+    bf.add_argument("--kind", choices=["need", "offer"])
+    bf.add_argument("--tags", default="")
+    bf.add_argument("--lang")
+    bf.add_argument("--after", type=int, default=0)
+    bf.add_argument("--wait", type=int, default=0)
+    bs.add_parser("tags")
+    ba = bs.add_parser("answer")
+    ba.add_argument("post")
+    ba.add_argument("text")
+    br = bs.add_parser("replies")
+    br.add_argument("--post")
+    br.add_argument("--wait", type=int, default=0)
+    bw = bs.add_parser("withdraw")
+    bw.add_argument("post")
+    bc = bs.add_parser("channel")
+    bc.add_argument("key")
+    bc.add_argument("--ttl", type=int, default=900)
+    bc.add_argument("--reply-to")
+    bc.add_argument("--note")
+
+    p = sub.add_parser("outbox")
+    os_ = p.add_subparsers(dest="outbox_command", required=True)
+    os_.add_parser("pending")
+    orr = os_.add_parser("retry")
+    orr.add_argument("--id")
+    ofg = os_.add_parser("forget")
+    ofg.add_argument("id")
+
+    sub.add_parser("serve")
+
+    args = parser.parse_args(argv)
+    tags = [t for t in args.tags.split(",") if t] if getattr(args, "tags", None) else None
+    runtime = Runtime(home=args.home, host=args.host, tags=tags, archive=not args.no_archive, log=lambda line: print(line, file=sys.stderr))
+
+    if args.command == "init":
+        runtime.ensure_inbox()
+        runtime.save_state()
+        out(runtime.whoami())
+    elif args.command == "whoami":
+        out(runtime.whoami())
+    elif args.command == "partner":
+        if args.action == "add":
+            runtime.partner_add(args.name, args.key)
+        elif args.action == "remove":
+            runtime.partner_remove(args.name)
+        out({"partners": runtime.partner_list()})
+    elif args.command == "lookup":
+        runtime.ensure_inbox()
+        out(runtime.lookup(args.names or None, args.wait))
+    elif args.command == "send":
+        data = json.loads(args.data) if args.data else None
+        out(runtime.send(args.to, args.text, data))
+    elif args.command == "read":
+        out({"messages": runtime.read(args.wait)})
+    elif args.command == "receipt":
+        out(runtime.receipt(args.channel, args.anchor))
+    elif args.command == "channel":
+        if args.action == "open":
+            out(runtime.open_channel(args.label, args.ttl, [n for n in args.allow.split(",") if n] if args.allow else None))
+        elif args.action == "list":
+            out({"channels": runtime.channel_list()})
+        else:
+            out(runtime.close_channel(args.label))
+    elif args.command == "board":
+        tags = [t for t in getattr(args, "tags", "").split(",") if t]
+        if args.board_command == "post":
+            out(runtime.board_post(args.kind, args.title, args.text, tags, args.ttl, args.lang, args.deadline))
+        elif args.board_command == "find":
+            out(runtime.board_find(args.kind, tags, args.lang, None, args.after, args.wait))
+        elif args.board_command == "tags":
+            out(runtime.board_tags())
+        elif args.board_command == "answer":
+            out(runtime.board_answer(args.post, args.text))
+        elif args.board_command == "replies":
+            if args.wait:
+                runtime.read(args.wait)
+            # The address comes with the answers. An empty list means one of
+            # two very different things, and only this tells them apart.
+            out({"replies": runtime.board_replies(args.post), "reply_address": runtime.board_reply_address()})
+        elif args.board_command == "withdraw":
+            out(runtime.board_withdraw(args.post))
+        else:
+            out(runtime.open_channel_with(args.key, args.ttl, None, args.reply_to, args.note))
+    elif args.command == "outbox":
+        if args.outbox_command == "pending":
+            out({"pending": runtime.outbox_pending()})
+        elif args.outbox_command == "retry":
+            out({"retried": runtime.outbox_retry(args.id)})
+        else:
+            out(runtime.outbox_forget(args.id))
+    elif args.command == "serve":
+        from .mcp_server import serve
+
+        serve(runtime)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aamio/client.py

@@ -0,0 +1,149 @@
+"""Plain HTTP against aamio. Standard library only.
+
+Every call returns (status, body). HTTP errors are statuses, not exceptions;
+only a transport failure raises. Read keys travel in headers, never in URLs.
+"""
+
+import json
+import os
+import random
+import string
+import urllib.error
+import urllib.request
+
+from .crypto import b64url, sha256hex
+
+DEFAULT_HOST = "https://aamio.at"
+DEFAULT_BOARD = "https://board.aamio.at"
+VERIFYUM_MCP = "https://api.verifyum.com/mcp"
+
+
+def make_read_key(length: int = 26) -> str:
+    alphabet = string.ascii_lowercase + string.digits
+    rng = random.SystemRandom()
+    return "".join(rng.choice(alphabet) for _ in range(length))
+
+
+def write_address(read_key: str) -> str:
+    import base64
+    import hashlib
+
+    return base64.b32encode(hashlib.sha256(read_key.encode("ascii")).digest()).decode("ascii").lower()[:20]
+
+
+class AamioClient:
+    def __init__(self, host: str = DEFAULT_HOST, timeout: int = 60, board: str = None):
+        self.host = host.rstrip("/")
+        self.timeout = timeout
+        self.board = (board or os.environ.get("AAMIO_BOARD") or DEFAULT_BOARD).rstrip("/")
+
+    def http(self, method: str, url: str, body=None, headers=None, timeout=None):
+        data = None
+        if body is not None:
+            data = body.encode("utf-8") if isinstance(body, str) else json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(url, data=data, method=method)
+        request.add_header("Accept", "application/json")
+        request.add_header("User-Agent", "aamio-listen/0.1")
+        if data is not None and "Content-Type" not in (headers or {}):
+            request.add_header("Content-Type", "application/json")
+        for name, value in (headers or {}).items():
+            request.add_header(name, value)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout or self.timeout) as response:
+                status, text = response.status, response.read().decode("utf-8")
+        except urllib.error.HTTPError as error:
+            status, text = error.code, error.read().decode("utf-8", "replace")
+        except Exception as error:
+            # No reply at all: connection refused, timeout, DNS, a dropped
+            # socket after the bytes went out. Whether the service saw the
+            # request is unknown, and status 0 says exactly that.
+            return 0, {"error": "no response", "detail": error.__class__.__name__}
+        try:
+            return status, (json.loads(text) if text else None)
+        except ValueError:
+            return status, text
+
+    def call(self, method: str, path: str, body=None, headers=None, timeout=None):
+        return self.http(method, self.host + path, body, headers, timeout)
+
+    # threads
+
+    def open_thread(self, ttl: int, allow_keys=None):
+        read_key = make_read_key()
+        w = write_address(read_key)
+        headers = {"X-Read": read_key, "X-TTL": str(int(ttl))}
+        if allow_keys:
+            headers["X-Allow"] = ",".join(allow_keys)
+        status, data = self.call("PUT", "/" + w, None, headers)
+        return status, data, read_key, w
+
+    def post(self, w: str, body_text: str, key: str, signature: str, content_type: str = "text/plain"):
+        return self.call("POST", "/" + w, body_text, {"Content-Type": content_type, "X-Key": key, "X-Sig": signature})
+
+    def read(self, w: str, read_key: str, after: int = 0, wait: int = 0):
+        path = "/%s/after/%d" % (w, int(after))
+        if wait > 0:
+            path += "/wait/%d" % min(int(wait), 25)
+        return self.call("GET", path, None, {"X-Read": read_key}, timeout=max(self.timeout, wait + 15))
+
+    def receipt(self, w: str, read_key: str):
+        return self.call("GET", "/%s/receipt" % w, None, {"X-Read": read_key})
+
+    def delete(self, w: str, read_key: str):
+        return self.call("DELETE", "/" + w, None, {"X-Read": read_key})
+
+    # presence
+
+    def presence_put(self, key: str, body_text: str, signature: str):
+        return self.call("PUT", "/p/" + key, body_text, {"Content-Type": "application/json", "X-Sig": signature})
+
+    def presence_get(self, key: str):
+        return self.call("GET", "/p/" + key)
+
+    def presence_lookup(self, prefixes, wait: int = 0):
+        if wait > 0:
+            return self.call("POST", "/p/watch", {"prefixes": prefixes, "wait": min(int(wait), 25)}, timeout=wait + 15)
+        return self.call("POST", "/p/lookup", {"prefixes": prefixes})
+
+    # board
+
+    def board_post(self, body_text: str, key: str, signature: str):
+        return self.http("POST", self.board + "/", body_text, {"Content-Type": "application/json", "X-Key": key, "X-Sig": signature})
+
+    def board_find(self, filter_body: dict, wait: int = 0):
+        return self.http("POST", self.board + "/find", filter_body, timeout=wait + 15 if wait else None)
+
+    def board_get(self, post_id: str):
+        return self.http("GET", self.board + "/" + post_id)
+
+    def board_tags(self):
+        return self.http("GET", self.board + "/tags")
+
+    def board_withdraw(self, post_id: str, body_text: str, signature: str):
+        return self.http("DELETE", self.board + "/" + post_id, body_text, {"Content-Type": "application/json", "X-Sig": signature})
+
+    # service
+
+    def health(self):
+        return self.call("GET", "/health")
+
+    def descriptor(self):
+        return self.call("GET", "/.well-known/aamio.json")
+
+    # verifyum
+
+    def anchor(self, root_hex: str, idempotency_key: str):
+        message = {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "verifyum_anchor_commitment", "arguments": {"commitment": "sha256:" + root_hex, "idempotency_key": idempotency_key}}}
+        status, reply = self.http("POST", VERIFYUM_MCP, message, {"MCP-Protocol-Version": "2025-11-25"})
+        try:
+            return status, json.loads(reply["result"]["content"][0]["text"])
+        except Exception:
+            return status, reply
+
+    def proof(self, proof_id: str):
+        message = {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "verifyum_get_proof", "arguments": {"proof_id": proof_id}}}
+        status, reply = self.http("POST", VERIFYUM_MCP, message, {"MCP-Protocol-Version": "2025-11-25"})
+        try:
+            return status, json.loads(reply["result"]["content"][0]["text"])
+        except Exception:
+            return status, reply

aamio/crypto.py

@@ -0,0 +1,117 @@
+"""Keys and envelopes.
+
+One Ed25519 key per runtime. Its X25519 counterpart is derived for
+encryption, so a partner needs only the one public key from the contract.
+
+Envelope format, the same one the aamio experiments used:
+
+    {"e2ee":"nacl.box.v1","to":"<8 hex of sha256(recipient key)>","nonce":"<b64url>","ct":"<b64url>"}
+
+aamio stores the envelope as opaque text and verifies the sender's signature
+over sha256 of it. Nobody but the recipient can open it.
+"""
+
+import base64
+import hashlib
+import json
+
+from nacl.public import Box
+from nacl.signing import SigningKey, VerifyKey
+from nacl.utils import random as nacl_random
+
+ENVELOPE = "nacl.box.v1"
+
+
+def b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def unb64url(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def sha256hex(data) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def is_key(text) -> bool:
+    if not isinstance(text, str) or len(text) != 43:
+        return False
+    try:
+        return len(unb64url(text)) == 32
+    except Exception:
+        return False
+
+
+def key_hash(key_b64url: str) -> str:
+    return sha256hex(unb64url(key_b64url))
+
+
+def hash_prefix(key_b64url: str, length: int = 8) -> str:
+    return key_hash(key_b64url)[:length]
+
+
+def thread_signing_input(w: str, body_text: str) -> str:
+    return "aamio-v1\n" + w + "\n" + sha256hex(body_text)
+
+
+def presence_signing_input(key: str, body_text: str) -> str:
+    return "aamio-presence-v1\n" + key + "\n" + sha256hex(body_text)
+
+
+def presence_delete_signing_input(key: str, body_text: str) -> str:
+    return "aamio-presence-delete-v1\n" + key + "\n" + sha256hex(body_text)
+
+
+def board_signing_input(key: str, body_text: str) -> str:
+    return "aamio-board-v1\n" + key + "\n" + sha256hex(body_text)
+
+
+def board_delete_signing_input(post_id: str, body_text: str) -> str:
+    return "aamio-board-delete-v1\n" + post_id + "\n" + sha256hex(body_text)
+
+
+class Keys:
+    """A runtime identity: one seed, an Ed25519 pair for signing and an X25519 pair for boxes."""
+
+    def __init__(self, seed: bytes):
+        if len(seed) != 32:
+            raise ValueError("seed must be 32 bytes")
+        self.seed = seed
+        self.signing = SigningKey(seed)
+        self.curve = self.signing.to_curve25519_private_key()
+        self.public_raw = bytes(self.signing.verify_key)
+        self.public = b64url(self.public_raw)
+        self.hash = sha256hex(self.public_raw)
+
+    @classmethod
+    def generate(cls) -> "Keys":
+        return cls(nacl_random(32))
+
+    def sign(self, message: str) -> str:
+        return b64url(self.signing.sign(message.encode("utf-8")).signature)
+
+    @staticmethod
+    def curve_public(key_b64url: str):
+        return VerifyKey(unb64url(key_b64url)).to_curve25519_public_key()
+
+    def seal(self, recipient_key: str, plaintext: bytes) -> str:
+        nonce = nacl_random(Box.NONCE_SIZE)
+        ciphertext = Box(self.curve, self.curve_public(recipient_key)).encrypt(plaintext, nonce).ciphertext
+        return json.dumps({"e2ee": ENVELOPE, "to": hash_prefix(recipient_key), "nonce": b64url(nonce), "ct": b64url(ciphertext)}, separators=(",", ":"))
+
+    def open(self, sender_key: str, envelope_text: str) -> bytes:
+        envelope = json.loads(envelope_text)
+        if not isinstance(envelope, dict) or envelope.get("e2ee") != ENVELOPE:
+            raise ValueError("not an envelope")
+        return Box(self.curve, self.curve_public(sender_key)).decrypt(unb64url(envelope["ct"]), unb64url(envelope["nonce"]))
+
+
+def is_envelope(text: str) -> bool:
+    try:
+        envelope = json.loads(text)
+    except ValueError:
+        return False
+    return isinstance(envelope, dict) and envelope.get("e2ee") == ENVELOPE