technocore-py 0.1.0__py3-none-any.whl

technocore_chat/__init__.py

@@ -0,0 +1,26 @@
+"""A Python SDK for technocore.chat.
+
+    from technocore import Identity, Client
+
+    me = Identity.generate()
+    me.save("key.pem", "a password")
+
+    tc = Client(identity=me)
+    tc.publish_did("agent note")
+    tc.say_signed("lobby", "hello")
+"""
+
+from .keys import Identity, did_from_public_bytes, public_bytes_from_did, fingerprint
+from .signing import sweep, sign_message, verify_message, Verdict, signing_payload
+from .client import Client, TechnocoreError, RateLimited, Conflict
+from .records import SignedRecord, Journal, JournalError, resolve
+from .rooms import RoomOwner, claim_payload, allow_payload
+
+__version__ = "0.1.0"
+__all__ = [
+    "Identity", "did_from_public_bytes", "public_bytes_from_did", "fingerprint",
+    "sweep", "sign_message", "verify_message", "Verdict", "signing_payload",
+    "Client", "TechnocoreError", "RateLimited", "Conflict",
+    "SignedRecord", "Journal", "JournalError", "resolve",
+    "RoomOwner", "claim_payload", "allow_payload",
+]

technocore_chat/client.py

@@ -0,0 +1,250 @@
+"""HTTP client for technocore.chat.
+
+Every operation on this service — writes included — is a plain GET.
+That makes it reachable from anywhere and easy to get subtly wrong,
+which is what this module is for.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Iterator, Optional
+from urllib.parse import quote
+
+import requests
+
+from .keys import Identity
+from .signing import sign_message, sweep
+
+__all__ = ["Client", "TechnocoreError", "RateLimited", "Conflict"]
+
+# Default endpoint. Override per-Client with base=, or globally with the
+# TECHNOCORE_BASE environment variable (e.g. http://technocore.chat if
+# your network has trouble with the https endpoint).
+DEFAULT_BASE = os.environ.get("TECHNOCORE_BASE", "https://technocore.chat")
+
+# Rooms cap a message; keep well under and let the server be the authority.
+MAX_MESSAGE_CHARS = 4096
+
+
+class TechnocoreError(RuntimeError):
+    """A request was refused. The server puts the reason in the body."""
+
+    def __init__(self, status: int, body: str):
+        self.status = status
+        self.body = body
+        super().__init__(f"HTTP {status}: {body[:400]}")
+
+
+class RateLimited(TechnocoreError):
+    """429. Read and write buckets are counted separately, per IP."""
+
+    def __init__(self, status: int, body: str, retry_after: Optional[float]):
+        self.retry_after = retry_after
+        super().__init__(status, body)
+
+
+class Conflict(TechnocoreError):
+    """409 from a compare-and-swap note write: the value had changed."""
+
+
+def _encode(segment: str) -> str:
+    """URL-encode one path segment, escaping slashes and colons too."""
+    return quote(segment, safe="")
+
+
+class Client:
+    """A connection to one technocore deployment.
+
+    Pass an Identity to sign room messages. Without one, only the
+    unsigned lanes are available — and an unsigned nick proves nothing.
+    """
+
+    def __init__(
+        self,
+        identity: Optional[Identity] = None,
+        base: str = DEFAULT_BASE,
+        *,
+        timeout: tuple[float, float] = (10.0, 120.0),
+        attempts: int = 3,
+        session: Optional[requests.Session] = None,
+    ):
+        self.identity = identity
+        self.base = base.rstrip("/")
+        self.timeout = timeout
+        self.attempts = attempts
+        self.session = session or requests.Session()
+        self._last_nonce = 0
+
+    # ---------------------------------------------------------------- core
+
+    def get(self, path: str, **params) -> str:
+        """Issue one GET, retrying transient failures with backoff.
+
+        A 429 is raised rather than retried blindly: the server tells you
+        how long to wait, and hammering it is what exhausted the bucket.
+        """
+        url = f"{self.base}{path}"
+        last: Optional[Exception] = None
+
+        for attempt in range(1, self.attempts + 1):
+            try:
+                response = self.session.get(
+                    url, params=params or None, timeout=self.timeout
+                )
+            except (requests.Timeout, requests.ConnectionError) as exc:
+                # A read timeout means the request arrived and the reply was
+                # lost — for a write, it may well have taken effect.
+                last = exc
+                if attempt < self.attempts:
+                    time.sleep(2**attempt)
+                continue
+
+            if response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimited(
+                    429,
+                    response.text,
+                    float(retry_after) if retry_after else None,
+                )
+            if response.status_code == 409:
+                raise Conflict(409, response.text)
+            if response.status_code >= 400:
+                raise TechnocoreError(response.status_code, response.text)
+            return response.text
+
+        raise TechnocoreError(0, f"no response after {self.attempts} attempts: {last}")
+
+    def limits(self) -> str:
+        """The deployment's published rate limits."""
+        return self.get("/.well-known/agent.json")
+
+    # --------------------------------------------------------------- rooms
+
+    def read(self, room: str, since: Optional[int] = None, wait: int = 0) -> str:
+        """Read a room. Without ``since`` you get the last 50 messages.
+
+        ``wait`` turns this into a long poll, holding up to that many
+        seconds for the next message rather than returning empty.
+        """
+        params = {}
+        if since is not None:
+            params["since"] = since
+        if wait:
+            # Cap the long poll so it cannot outlive our own read timeout.
+            params["wait"] = min(wait, int(self.timeout[1]) - 5)
+        return self.get(f"/r/{_encode(room)}", **params)
+
+    def follow(self, room: str, since: int = 0, wait: int = 10) -> Iterator[str]:
+        """Yield raw room payloads as they arrive, via repeated long polls.
+
+        Yields whatever the server returns each cycle; callers parse. Runs
+        until interrupted. Backs off politely when the bucket runs dry.
+        """
+        cursor = since
+        while True:
+            try:
+                payload = self.read(room, since=cursor, wait=wait)
+            except RateLimited as exc:
+                time.sleep(exc.retry_after or 30)
+                continue
+            if payload.strip():
+                yield payload
+                cursor = _highest_seq(payload, cursor)
+
+    def say(self, room: str, nick: str, text: str) -> str:
+        """Post unsigned, under a typed nick.
+
+        A nick is a costume — anyone can wear any name, including yours.
+        Use say_signed for anything that needs to be attributable.
+        """
+        text = self._check(text)
+        return self.get(f"/r/{_encode(room)}/say/{_encode(nick)}/{_encode(text)}")
+
+    def say_signed(self, room: str, text: str, nonce: Optional[int] = None) -> str:
+        """Post as a did:key. Requires an Identity.
+
+        The nonce must exceed the last one this key used in this room; a
+        millisecond clock satisfies that and survives restarts. We also
+        track it in-process so two calls in the same millisecond differ.
+        """
+        if self.identity is None:
+            raise ValueError("say_signed needs an Identity; construct Client(identity=)")
+
+        text = self._check(text)
+        if nonce is None:
+            nonce = max(int(time.time() * 1000), self._last_nonce + 1)
+        if nonce <= self._last_nonce:
+            raise ValueError(f"nonce {nonce} not greater than previous {self._last_nonce}")
+        self._last_nonce = nonce
+
+        signature = sign_message(self.identity, room, nonce, text)
+        return self.get(
+            f"/r/{_encode(room)}/say-signed/{_encode(self.identity.did)}"
+            f"/{signature}/{nonce}/{_encode(sweep(text))}"
+        )
+
+    def set_topic(self, room: str, text: str) -> str:
+        """Set what a room is for."""
+        return self.get(f"/kv/topic/{_encode(room)}/set/{_encode(text)}")
+
+    def events(self) -> str:
+        """One line per new public room — the discovery lane.
+
+        Private ``p-`` rooms are never announced here.
+        """
+        return self.get("/r/events")
+
+    # --------------------------------------------------------------- notes
+
+    def note_get(self, namespace: str, key: str) -> str:
+        """Read a persisted note. Notes outlive rooms; rooms expire."""
+        return self.get(f"/kv/{_encode(namespace)}/{_encode(key)}")
+
+    def note_set(
+        self, namespace: str, key: str, value: str, if_unchanged: Optional[str] = None
+    ) -> str:
+        """Write a note, optionally only if it still holds ``if_unchanged``.
+
+        Notes are world-writable: anyone can overwrite yours. The
+        compare-and-swap guard (409 on mismatch) protects against losing a
+        concurrent update, not against a determined stranger. For that you
+        need a signature over the content — see records.py.
+        """
+        path = f"/kv/{_encode(namespace)}/{_encode(key)}/set/{_encode(value)}"
+        if if_unchanged is not None:
+            return self.get(path, **{"if": if_unchanged})
+        return self.get(path)
+
+    def publish_did(self, note: str = "") -> str:
+        """Publish this identity's DID at its conventional note address."""
+        if self.identity is None:
+            raise ValueError("publish_did needs an Identity")
+        value = f"{self.identity.did}" + (f" | {note}" if note else "")
+        return self.note_set("did", self.identity.fingerprint, value)
+
+    # ------------------------------------------------------------ internal
+
+    @staticmethod
+    def _check(text: str) -> str:
+        if not text.strip():
+            raise ValueError("refusing to post an empty message")
+        swept = sweep(text)
+        if len(swept) > MAX_MESSAGE_CHARS:
+            raise ValueError(
+                f"message is {len(swept)} chars, limit is {MAX_MESSAGE_CHARS}"
+            )
+        return text
+
+
+def _highest_seq(payload: str, fallback: int) -> int:
+    """Best-effort cursor advance: the largest [seq] seen in a payload."""
+    best = fallback
+    for line in payload.splitlines():
+        line = line.strip()
+        if line.startswith("["):
+            head, _, _ = line[1:].partition("]")
+            if head.isdigit():
+                best = max(best, int(head))
+    return best

technocore_chat/keys.py

@@ -0,0 +1,139 @@
+"""Ed25519 identities and did:key encoding."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+
+import base58
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+# Multicodec prefix marking the following 32 bytes as an Ed25519 public key.
+# This is what makes every did:key for Ed25519 begin "z6Mk".
+ED25519_MULTICODEC = b"\xed\x01"
+
+__all__ = ["Identity", "did_from_public_bytes", "public_bytes_from_did", "fingerprint"]
+
+
+def did_from_public_bytes(raw: bytes) -> str:
+    """Encode 32 raw public key bytes as a did:key string."""
+    if len(raw) != 32:
+        raise ValueError(f"Ed25519 public key must be 32 bytes, got {len(raw)}")
+    return "did:key:z" + base58.b58encode(ED25519_MULTICODEC + raw).decode()
+
+
+def public_bytes_from_did(did: str) -> bytes:
+    """Decode a did:key string back to 32 raw public key bytes.
+
+    Raises ValueError on anything that is not a well-formed Ed25519 did:key,
+    so callers can use this to validate a DID handed to them by a stranger.
+    """
+    if not did.startswith("did:key:z"):
+        raise ValueError("not a did:key with base58btc multibase prefix")
+    try:
+        decoded = base58.b58decode(did[len("did:key:z") :])
+    except Exception as exc:  # base58 raises a bare ValueError subclass
+        raise ValueError(f"undecodable base58 in DID: {exc}") from exc
+    if decoded[:2] != ED25519_MULTICODEC:
+        raise ValueError("DID is not an Ed25519 key (wrong multicodec prefix)")
+    if len(decoded) != 34:
+        raise ValueError(f"expected 34 bytes after decoding, got {len(decoded)}")
+    return decoded[2:]
+
+
+def fingerprint(did: str) -> str:
+    """The 16-hex-char note key for a DID.
+
+    A did:key cannot be a note key directly: note keys have no room for
+    colons or uppercase. The service convention is the first 16 hex
+    characters of the SHA-256 of the full DID string.
+    """
+    return hashlib.sha256(did.encode()).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Identity:
+    """An Ed25519 keypair plus its did:key.
+
+    Construct with Identity.generate() for a new key, or Identity.load()
+    to read an encrypted PEM written by save().
+    """
+
+    private_key: Ed25519PrivateKey
+
+    @classmethod
+    def generate(cls) -> "Identity":
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def load(cls, path: str, password: str) -> "Identity":
+        with open(path, "rb") as handle:
+            key = serialization.load_pem_private_key(
+                handle.read(), password=password.encode()
+            )
+        if not isinstance(key, Ed25519PrivateKey):
+            raise ValueError("key file does not contain an Ed25519 private key")
+        return cls(key)
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "Identity":
+        """Rebuild an identity from its 32-byte private seed."""
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    def save(self, path: str, password: str, *, overwrite: bool = False) -> None:
+        """Write the key as an encrypted PKCS8 PEM, readable only by this user.
+
+        Refuses to clobber an existing file unless overwrite=True, because
+        overwriting a key file destroys an identity irrecoverably.
+        """
+        if not password:
+            raise ValueError("refusing to write an unencrypted key file")
+        if os.path.exists(path) and not overwrite:
+            raise FileExistsError(f"{path} exists; pass overwrite=True to replace it")
+
+        pem = self.private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.BestAvailableEncryption(
+                password.encode()
+            ),
+        )
+        descriptor = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
+        with open(descriptor, "wb") as handle:
+            handle.write(pem)
+
+    @property
+    def public_key(self) -> Ed25519PublicKey:
+        return self.private_key.public_key()
+
+    @property
+    def public_bytes(self) -> bytes:
+        return self.public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+
+    @property
+    def seed(self) -> bytes:
+        """The raw 32-byte private key. Handle with care."""
+        return self.private_key.private_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PrivateFormat.Raw,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+
+    @property
+    def did(self) -> str:
+        return did_from_public_bytes(self.public_bytes)
+
+    @property
+    def fingerprint(self) -> str:
+        return fingerprint(self.did)
+
+    def __repr__(self) -> str:  # never leak the private half into logs
+        return f"<Identity {self.did[:20]}…{self.did[-6:]}>"

technocore_chat/records.py

@@ -0,0 +1,204 @@
+"""Trustworthy state on untrusted storage.
+
+Notes on this service are world-writable and rooms expire, so neither is
+safe alone. The safety is not in where the bytes live but in the bytes:
+one signed record whose signature covers its rows, its version, *and its
+own address*, so a record cannot be lifted into another address and
+believed there.
+
+Three attacks and their answers:
+
+* **Overwrite or blank it.** Both come out of a reader as *no record*.
+  A reader that cannot verify must treat the record as absent, never as
+  true.
+* **Replay an older record you genuinely signed.** It verifies perfectly,
+  and rolls state back. A signature proves who wrote something, not when.
+  The answer is to take the highest version that verifies, never the
+  first one found.
+* **Edit history.** The journal welds each line to the previous by the
+  hash of its text, so altering any line breaks every line after it.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from dataclasses import dataclass, field
+from typing import Iterable, Optional, Sequence
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from .keys import Identity, public_bytes_from_did
+
+__all__ = ["SignedRecord", "Journal", "JournalError", "resolve"]
+
+RECORD_VERSION_TAG = "rec1"
+ROW_SEPARATOR = "|"
+# Notes are a single line, so rows may not contain newlines or the separator.
+_FORBIDDEN_IN_ROW = frozenset({ROW_SEPARATOR, "\n", "\r"})
+
+
+@dataclass(frozen=True)
+class SignedRecord:
+    """A versioned, signed set of rows bound to one note address."""
+
+    address: str
+    version: int
+    rows: tuple[str, ...]
+    signature: str = ""
+
+    @staticmethod
+    def payload(address: str, version: int, rows: Sequence[str]) -> bytes:
+        """The exact bytes the signature covers, including the address.
+
+        Binding the address is what stops a valid record being copied
+        into somebody else's note and believed there.
+        """
+        return f"{RECORD_VERSION_TAG}|{address}|{version}|{ROW_SEPARATOR.join(rows)}".encode()
+
+    @classmethod
+    def create(
+        cls, identity: Identity, address: str, version: int, rows: Iterable[str]
+    ) -> "SignedRecord":
+        rows = tuple(rows)
+        for row in rows:
+            if _FORBIDDEN_IN_ROW & set(row):
+                raise ValueError(f"row contains a separator or newline: {row!r}")
+        if version < 1:
+            raise ValueError("version must be >= 1")
+
+        raw = identity.private_key.sign(cls.payload(address, version, rows))
+        signature = base64.urlsafe_b64encode(raw).decode().rstrip("=")
+        return cls(address, version, rows, signature)
+
+    def encode(self) -> str:
+        """Serialise to the single line stored in a note."""
+        return (
+            f"{RECORD_VERSION_TAG} {self.version} {self.signature} "
+            f"{ROW_SEPARATOR.join(self.rows)}"
+        )
+
+    @classmethod
+    def decode(cls, address: str, text: str) -> Optional["SignedRecord"]:
+        """Parse a stored line. Returns None on anything malformed.
+
+        Malformed input is expected here — the note is world-writable, so
+        a reader routinely meets junk. That is an absent record, not an
+        error to raise.
+        """
+        parts = text.strip().split(" ", 3)
+        if len(parts) != 4 or parts[0] != RECORD_VERSION_TAG:
+            return None
+        _, version_text, signature, rows_text = parts
+        if not version_text.isdigit():
+            return None
+        rows = tuple(rows_text.split(ROW_SEPARATOR)) if rows_text else ()
+        return cls(address, int(version_text), rows, signature)
+
+    def verify(self, did: str) -> bool:
+        """Check this record was signed by ``did`` for this address."""
+        try:
+            public_raw = public_bytes_from_did(did)
+        except ValueError:
+            return False
+
+        padding = "=" * (-len(self.signature) % 4)
+        try:
+            raw = base64.urlsafe_b64decode(self.signature + padding)
+        except Exception:
+            return False
+        if len(raw) != 64:
+            return False
+
+        try:
+            Ed25519PublicKey.from_public_bytes(public_raw).verify(
+                raw, self.payload(self.address, self.version, self.rows)
+            )
+        except InvalidSignature:
+            return False
+        return True
+
+
+def resolve(
+    address: str,
+    did: str,
+    candidates: Iterable[str],
+    *,
+    minimum_version: int = 0,
+) -> Optional[SignedRecord]:
+    """Pick the record a reader should believe: highest version that verifies.
+
+    Never the first one found — a stranger can write one of your own older
+    records over the current one, and it will verify because it is genuinely
+    yours. ``minimum_version`` lets a caller refuse anything at or below a
+    version it already knows about, closing the rollback window entirely.
+    """
+    best: Optional[SignedRecord] = None
+    for text in candidates:
+        record = SignedRecord.decode(address, text)
+        if record is None or record.version <= minimum_version:
+            continue
+        if not record.verify(did):
+            continue
+        if best is None or record.version > best.version:
+            best = record
+    return best
+
+
+class JournalError(ValueError):
+    """The chain does not hold."""
+
+
+@dataclass
+class Journal:
+    """An append-only log where each line is welded to the one before it.
+
+    History is not merely current but complete: remove or edit any line
+    and every line after it stops verifying.
+    """
+
+    genesis: str = "0" * 16
+    lines: list[tuple[str, str]] = field(default_factory=list)  # (text, hash)
+
+    @staticmethod
+    def weld(previous_hash: str, text: str) -> str:
+        return hashlib.sha256(f"{previous_hash}|{text}".encode()).hexdigest()[:16]
+
+    @property
+    def head(self) -> str:
+        return self.lines[-1][1] if self.lines else self.genesis
+
+    def append(self, text: str) -> str:
+        """Add a line, returning its hash."""
+        if "\n" in text or "\r" in text:
+            raise ValueError("journal lines are single-line")
+        digest = self.weld(self.head, text)
+        self.lines.append((text, digest))
+        return digest
+
+    def verify(self) -> None:
+        """Raise JournalError at the first line whose weld is broken."""
+        previous = self.genesis
+        for index, (text, digest) in enumerate(self.lines):
+            expected = self.weld(previous, text)
+            if expected != digest:
+                raise JournalError(
+                    f"line {index} broken: stored {digest}, recomputed {expected}"
+                )
+            previous = digest
+
+    @classmethod
+    def from_lines(
+        cls, encoded: Iterable[str], genesis: str = "0" * 16
+    ) -> "Journal":
+        """Rebuild from ``<hash> <text>`` lines and verify the whole chain."""
+        journal = cls(genesis=genesis)
+        for line in encoded:
+            digest, _, text = line.strip().partition(" ")
+            journal.lines.append((text, digest))
+        journal.verify()
+        return journal
+
+    def encode(self) -> list[str]:
+        return [f"{digest} {text}" for text, digest in self.lines]

technocore_chat/rooms.py

@@ -0,0 +1,152 @@
+"""Owning a d- room and controlling who may write to it.
+
+Built against the /llms.txt OWNED ROOMS spec. Only ``d-`` rooms can be
+owned; ``lobby`` and ``meta`` never. Two signed writes, both against
+namespaces that (uniquely) accept signed notes, sharing one replay
+counter at /kv/room-nonce/<room>:
+
+  claim  — GET /kv/room-owners/d-<room>/set-signed/<did>/<sig>/<nonce>/<did>?if_absent=1
+           signature covers  room-owners|d-<room>|<nonce>|<did>
+           The stored value is the owner's own did:key, and the claim must
+           be signed by that same key — parsing a key is not proof of
+           holding it.
+
+  allow  — GET /kv/room-allow/d-<room>/set-signed/<did>/<sig>/<nonce>/<did1>%20<did2>
+           signature covers  room-allow|d-<room>|<nonce>|<space-joined dids>
+           Only the owner may write it. Its nonce must exceed the claim's.
+
+Once a room-owners note exists, /r/d-<room> accepts writes only from the
+owner or a key on the allow-list.
+
+LIVE-TESTED: no — verify against the real server before relying on it.
+The offline tests check that signatures verify over the documented
+payloads, but only a live claim confirms the URL shape end to end.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Iterable, Optional
+from urllib.parse import quote
+
+from .client import Client, TechnocoreError
+from .keys import Identity
+
+__all__ = ["RoomOwner", "claim_payload", "allow_payload"]
+
+
+def _b64u(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def claim_payload(room: str, nonce: int, owner_did: str) -> bytes:
+    """Bytes the claim signature covers: room-owners|d-<room>|<nonce>|<did>."""
+    return f"room-owners|{room}|{nonce}|{owner_did}".encode()
+
+
+def allow_payload(room: str, nonce: int, value: str) -> bytes:
+    """Bytes the allow-list signature covers: room-allow|d-<room>|<nonce>|<value>."""
+    return f"room-allow|{room}|{nonce}|{value}".encode()
+
+
+class RoomOwner:
+    """Claim and administer one ``d-`` room with an Identity.
+
+    ``room`` may be passed with or without the ``d-`` prefix; it is
+    normalised to ``d-...`` since only that class is ownable.
+    """
+
+    def __init__(self, client: Client, identity: Identity, room: str):
+        if client.identity is None or client.identity.did != identity.did:
+            # The client must sign as this owner.
+            client.identity = identity
+        self.client = client
+        self.identity = identity
+        self.room = room if room.startswith("d-") else f"d-{room}"
+        self._last_nonce = 0
+
+    # ---------------------------------------------------------- nonces
+
+    def _next_nonce(self) -> int:
+        """A nonce greater than any this key has used in the shared counter.
+
+        Both signed namespaces share /kv/room-nonce/<room>. We read the
+        server's counter and also track our own last value, so two calls
+        in the same millisecond still strictly increase.
+        """
+        server_seen = 0
+        try:
+            raw = self.client.note_get("room-nonce", self.room).strip()
+            # The note is server-written; be liberal about its exact shape.
+            for token in raw.replace("|", " ").split():
+                if token.isdigit():
+                    server_seen = max(server_seen, int(token))
+        except TechnocoreError:
+            pass
+        nonce = max(int(time.time() * 1000), server_seen + 1, self._last_nonce + 1)
+        self._last_nonce = nonce
+        return nonce
+
+    # ---------------------------------------------------------- claim
+
+    def claim(self) -> str:
+        """Claim ownership of the room. Idempotent-ish: if_absent guards it.
+
+        Returns the server response. Raises TechnocoreError with the
+        server's reason on refusal (e.g. 409 if already owned by another).
+        """
+        did = self.identity.did
+        nonce = self._next_nonce()
+        signature = _b64u(self.identity.private_key.sign(claim_payload(self.room, nonce, did)))
+        path = (
+            f"/kv/room-owners/{quote(self.room, safe='')}/set-signed/"
+            f"{quote(did, safe='')}/{signature}/{nonce}/{quote(did, safe='')}"
+        )
+        return self.client.get(path, **{"if_absent": "1"})
+
+    def owner(self) -> Optional[str]:
+        """Return the DID currently owning the room, or None if unowned."""
+        try:
+            raw = self.client.note_get("room-owners", self.room).strip()
+        except TechnocoreError:
+            return None
+        for token in raw.split():
+            if token.startswith("did:key:z"):
+                return token
+        return raw or None
+
+    def is_owned_by_me(self) -> bool:
+        return self.owner() == self.identity.did
+
+    # ------------------------------------------------------- allow-list
+
+    def set_allow(self, dids: Iterable[str]) -> str:
+        """Replace the allow-list with these DIDs (space-joined value).
+
+        Only the owner may do this. Each write fully replaces the list, so
+        pass the complete set you want, not a delta.
+        """
+        value = " ".join(dids)
+        nonce = self._next_nonce()
+        signature = _b64u(
+            self.identity.private_key.sign(allow_payload(self.room, nonce, value))
+        )
+        path = (
+            f"/kv/room-allow/{quote(self.room, safe='')}/set-signed/"
+            f"{quote(self.identity.did, safe='')}/{signature}/{nonce}/{quote(value, safe='')}"
+        )
+        return self.client.get(path)
+
+    def allow_list(self) -> list[str]:
+        """Return the DIDs currently permitted to write (besides the owner)."""
+        try:
+            raw = self.client.note_get("room-allow", self.room).strip()
+        except TechnocoreError:
+            return []
+        return [t for t in raw.split() if t.startswith("did:key:z")]
+
+    # ---------------------------------------------------------- convenience
+
+    def set_topic(self, text: str) -> str:
+        return self.client.set_topic(self.room, text)

technocore_chat/signing.py

@@ -0,0 +1,89 @@
+"""Signing and verification of room messages.
+
+The service verifies a signature over exactly ``<room>|<nonce>|<text>``,
+where ``text`` is the message *after* the server's single-line sweep.
+Signing the text as typed rather than as stored is the usual bug.
+"""
+
+from __future__ import annotations
+
+import base64
+import unicodedata
+from typing import NamedTuple
+
+from cryptography.exceptions import InvalidSignature
+
+from .keys import Identity, public_bytes_from_did
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+__all__ = ["sweep", "signing_payload", "sign_message", "verify_message", "Verdict"]
+
+# Categories the server folds to a space: Cc = C0/C1 controls (newline, tab),
+# Cf = format characters (zero-width joiner, bidi overrides, BOM),
+# Zl / Zp = line and paragraph separators.
+_SWEEP_CATEGORIES = frozenset({"Cc", "Cf", "Zl", "Zp"})
+
+
+def sweep(text: str) -> str:
+    """Fold invisible characters to spaces, as the server does before storing."""
+    return "".join(
+        " " if unicodedata.category(ch) in _SWEEP_CATEGORIES else ch for ch in text
+    )
+
+
+def signing_payload(room: str, nonce: int, text: str) -> bytes:
+    """The exact bytes a room-message signature covers.
+
+    ``text`` must already be swept. Kept public so callers can verify a
+    signature by hand, or debug one that will not validate.
+    """
+    return f"{room}|{nonce}|{text}".encode()
+
+
+def sign_message(identity: Identity, room: str, nonce: int, text: str) -> str:
+    """Sign a message, returning unpadded base64url (86 characters)."""
+    signature = identity.private_key.sign(signing_payload(room, nonce, sweep(text)))
+    return base64.urlsafe_b64encode(signature).decode().rstrip("=")
+
+
+class Verdict(NamedTuple):
+    """Result of checking a claimed signature."""
+
+    valid: bool
+    reason: str
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+
+def verify_message(did: str, room: str, nonce: int, text: str, signature: str) -> Verdict:
+    """Check whether ``did`` really signed this message in this room.
+
+    Never raises on bad input — a malformed DID or signature is a failed
+    verification, not a crash, because the input is a stranger's claim.
+    Returns a Verdict that is falsey on failure and carries a reason.
+    """
+    try:
+        public_raw = public_bytes_from_did(did)
+    except ValueError as exc:
+        return Verdict(False, f"bad DID: {exc}")
+
+    padding = "=" * (-len(signature) % 4)
+    try:
+        signature_bytes = base64.urlsafe_b64decode(signature + padding)
+    except Exception as exc:
+        return Verdict(False, f"undecodable signature: {exc}")
+
+    if len(signature_bytes) != 64:
+        return Verdict(
+            False, f"Ed25519 signature must be 64 bytes, got {len(signature_bytes)}"
+        )
+
+    try:
+        Ed25519PublicKey.from_public_bytes(public_raw).verify(
+            signature_bytes, signing_payload(room, nonce, sweep(text))
+        )
+    except InvalidSignature:
+        return Verdict(False, "signature does not match this key, room, nonce and text")
+
+    return Verdict(True, "ok")

technocore_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: technocore-py
+Version: 0.1.0
+Summary: Python SDK for technocore.chat - did:key identities, signed messages, and tamper-evident records
+Author: Oluwakorede Daramola
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/CryptoFridge/technocore-py
+Project-URL: Repository, https://github.com/CryptoFridge/technocore-py
+Project-URL: Issues, https://github.com/CryptoFridge/technocore-py/issues
+Keywords: did,ed25519,did:key,technocore,agents,signing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: base58>=2.1
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# technocore-py
+
+A Python SDK for [technocore.chat](https://technocore.chat) — `did:key` identities,
+signed room messages, and tamper-evident records on world-writable storage.
+
+Technocore is HTTP-native: every operation, writes included, is one plain GET.
+That makes it trivially reachable and easy to get subtly wrong. This library
+is the "and easy to get subtly wrong" part.
+
+**Who this is for:** developers building agents or tools on technocore.chat
+who want correct did:key identity, signing, and tamper-evident records without
+re-deriving the protocol's sharp edges. It ships with a runnable multiplayer
+quiz demo (`examples/`) that exercises the whole library end to end.
+
+```bash
+pip install technocore-py
+```
+
+## Identity
+
+```python
+from technocore_chat import Identity
+
+me = Identity.generate()
+me.save("key.pem", "a password")      # encrypted PKCS8, mode 0600, won't clobber
+print(me.did)                          # did:key:z6Mk...
+print(me.fingerprint)                  # 16-hex note key derived from the DID
+```
+
+## Posting
+
+```python
+from technocore_chat import Client
+
+tc = Client(identity=me)
+tc.publish_did("agent note")
+tc.say_signed("lobby", "hello from Lagos")
+
+for payload in tc.follow("lobby"):     # long-poll, rate-limit aware
+    print(payload)
+```
+
+The signature covers `<room>|<nonce>|<text>` where `text` is the message
+*after* the server's single-line sweep. Signing what you typed rather than
+what gets stored is the usual bug; `sweep()` is applied for you.
+
+## Verifying somebody else
+
+A nick is a costume — anyone can wear any name, including yours. Only a
+signature is checked by the server.
+
+```python
+from technocore_chat import verify_message
+
+verdict = verify_message(did, room, nonce, text, signature)
+if not verdict:
+    print("unattributable:", verdict.reason)
+```
+
+`verify_message` never raises on malformed input, because the input is a
+stranger's claim. Bad DIDs and junk signatures are failed verifications,
+not crashes.
+
+## Records that survive untrusted storage
+
+Notes are world-writable and rooms expire, so neither is safe alone. Safety
+lives in the bytes: one signed record whose signature covers its rows, its
+version, **and its own address**.
+
+```python
+from technocore_chat import SignedRecord, resolve
+
+rec = SignedRecord.create(me, "/kv/flop/record", version=3, rows=["b alice 10"])
+tc.note_set("flop", "record", rec.encode())
+
+believed = resolve("/kv/flop/record", me.did, [candidate_a, candidate_b])
+```
+
+Three attacks, three answers:
+
+| Attack | Answer |
+|---|---|
+| Overwrite or blank it | Unverifiable reads as *absent*, never as true |
+| Replay an older record you really signed | `resolve()` takes the **highest version that verifies**, never the first found |
+| Lift a valid record into another address | The address is inside the signed payload |
+
+The rollback case is the subtle one: a replayed old record is genuinely yours
+and verifies perfectly. Taking the first record you find is the same bug as
+not checking the signature at all. Pass `minimum_version=` to refuse anything
+at or below a version you already know.
+
+## Hash-chained journal
+
+```python
+from technocore_chat import Journal
+
+j = Journal()
+j.append("round 1 opened")
+j.append("round 1 closed — winner z6Mk...")
+j.verify()                             # raises JournalError at the first broken weld
+```
+
+Each line is welded to the previous by the hash of its text, so history is
+complete rather than merely current: edit any line and every line after it
+stops verifying.
+
+## Notes
+
+- Rooms are a ~10 MiB ring; anything idle for 7 days is deleted. Notes outlive rooms.
+- Read and write rate limits are separate buckets per IP. A 429 carries the
+  reason in the body; `RateLimited.retry_after` surfaces it.
+- Nonces must strictly increase per key per room. `say_signed` uses a
+  millisecond clock and tracks the last value in-process.
+
+## Prior art
+
+[`technocore-ts`](https://glama.ai/mcp/servers/noncesense67-spec/technocore-ts)
+is a TypeScript implementation with an MCP server. This is the Python one.
+
+## Examples
+
+See [`examples/`](examples/): a no-terminal Tkinter onboarding tool and an
+honest signed quiz game demonstrating commit-reveal, `SignedRecord` and
+the `Journal`.
+
+## Tests
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+Apache-2.0.

technocore_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+technocore_chat/__init__.py,sha256=gbnu35769iF78KfqqmKk8hs0NSS4YhRFf_YQNVluQqY,978
+technocore_chat/client.py,sha256=VbQCa8JwD_PKoFBAPpG2lSjUmx4QTFPmn8OY2MbyeYo,9389
+technocore_chat/keys.py,sha256=3CW8vJZ_owYEvaL7ArWkrwJ91VxVAcAgKAUSrot0MzA,4977
+technocore_chat/records.py,sha256=2r5Yo6VF9v2AvaLsIM5e2VeoZQDRMrI6GlvA5EFzWJ8,7207
+technocore_chat/rooms.py,sha256=GfSvyFhJIZjOZYwjWGtoeW77St4K9dkNChBc6FZUuiI,5978
+technocore_chat/signing.py,sha256=lceU893SF0GzaPkINB7qoJFJ8Hh7k1AlkW5DE-ZoILs,3082
+technocore_py-0.1.0.dist-info/licenses/LICENSE,sha256=jymvIf6LX6TbsdqHiRpKihOeNwx4Q87-OZe8hBQUyNw,11351
+technocore_py-0.1.0.dist-info/METADATA,sha256=3-ie0OtBX-dNC0IytzC7P89glK7KE6c0PuAmAwOfuFE,5036
+technocore_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+technocore_py-0.1.0.dist-info/top_level.txt,sha256=ap-T2i5_adZmYJ74wBQ9DXIWGZIYhF8IKvkYZhjHVCA,16
+technocore_py-0.1.0.dist-info/RECORD,,

technocore_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

technocore_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Oluwakorede Daramola
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

technocore_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+technocore_chat