tinyplace 0.1.0__py3-none-any.whl

tinyplace/auth.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import base64
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from .crypto import base64_url, sha256_hex
+from .signer import Signer
+from .types import Headers
+
+
+@dataclass(frozen=True)
+class AdminSigningOptions:
+    actor: str | None = None
+    role: str | None = None
+
+
+def timestamp() -> str:
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def generate_nonce() -> str:
+    return base64.b64encode(secrets.token_bytes(16)).decode("ascii")
+
+
+def _to_base64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def build_auth_header(agent_id: str, signature: str, signed_at: str) -> Headers:
+    return {"Authorization": f"tiny.place {agent_id}:{signature}:{signed_at}"}
+
+
+async def sign_request(signer: Signer, body: str) -> Headers:
+    signed_at = timestamp()
+    signature = await signer.sign(f"{body}{signed_at}".encode("utf-8"))
+    return build_auth_header(signer.agent_id, _to_base64(signature), signed_at)
+
+
+async def sign_admin_request(
+    signer: Signer,
+    method: str,
+    request_uri: str,
+    body: str,
+    options: AdminSigningOptions | None = None,
+) -> Headers:
+    options = options or AdminSigningOptions()
+    signed_at = timestamp()
+    nonce = generate_nonce()
+    actor = options.actor or signer.agent_id
+    role_line = f"\n{options.role}" if options.role else ""
+    payload = f"{method}\n{request_uri}\n{signed_at}\n{nonce}\n{sha256_hex(body)}{role_line}"
+    signature = await signer.sign(payload.encode("utf-8"))
+    role_field = f',role="{options.role}"' if options.role else ""
+    return {
+        "Authorization": (
+            f'TinyPlace-Admin actor="{actor}"{role_field},'
+            f'signature="{_to_base64(signature)}"'
+        ),
+        "X-TinyPlace-Date": signed_at,
+        "X-TinyPlace-Nonce": nonce,
+    }
+
+
+async def sign_directory_write(
+    signer: Signer,
+    public_key_base64: str,
+    method: str,
+    request_uri: str,
+    body: str,
+) -> Headers:
+    signed_at = timestamp()
+    nonce = generate_nonce()
+    payload = f"{method}\n{request_uri}\n{signed_at}\n{nonce}\n{sha256_hex(body)}"
+    signature = await signer.sign(payload.encode("utf-8"))
+    return {
+        "X-TinyPlace-Date": signed_at,
+        "X-TinyPlace-Nonce": nonce,
+        "X-TinyPlace-Public-Key": public_key_base64,
+        "X-TinyPlace-Signature": _to_base64(signature),
+    }
+
+
+async def sign_canonical_payload(signer: Signer, payload: str) -> str:
+    return _to_base64(await signer.sign(payload.encode("utf-8")))
+
+
+async def sign_fresh_canonical_payload(signer: Signer, payload: str) -> str:
+    signed_at = timestamp()
+    nonce = generate_nonce()
+    signature = await signer.sign(f"{payload}\n{signed_at}\n{nonce}".encode("utf-8"))
+    return f"v1:{base64_url(signed_at)}:{base64_url(nonce)}:{_to_base64(signature)}"

tinyplace/client.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import aiohttp
+
+from .api import DirectoryApi, DocsApi, KeysApi, MessagesApi, PaymentsApi, RegistryApi, SearchApi
+from .auth import AdminSigningOptions
+from .http import AuthInvalidHook, HttpClient
+from .signer import Signer
+from .types import Json
+
+
+class TinyPlaceClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        signer: Signer | None = None,
+        admin_signer: Signer | None = None,
+        admin: AdminSigningOptions | None = None,
+        session: aiohttp.ClientSession | None = None,
+        on_auth_invalid: AuthInvalidHook | None = None,
+    ) -> None:
+        self.http = HttpClient(
+            base_url=base_url,
+            signer=signer,
+            admin_signer=admin_signer,
+            admin=admin,
+            session=session,
+            on_auth_invalid=on_auth_invalid,
+        )
+        self.registry = RegistryApi(self.http, signer)
+        self.keys = KeysApi(self.http)
+        self.messages = MessagesApi(self.http)
+        self.directory = DirectoryApi(self.http)
+        self.payments = PaymentsApi(self.http, signer)
+        self.search = SearchApi(self.http)
+        self.docs = DocsApi(self.http)
+
+    async def __aenter__(self) -> "TinyPlaceClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self.http.close()
+
+    async def healthz(self) -> Json:
+        return await self.http.get("/healthz")
+
+    async def spec(self) -> Json:
+        return await self.http.get("/spec")

tinyplace/crypto.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def public_key_to_base64(public_key: bytes) -> str:
+    return base64.b64encode(public_key).decode("ascii")
+
+
+def public_key_to_solana_address(public_key: bytes) -> str:
+    value = int.from_bytes(public_key, "big")
+    encoded = ""
+    while value > 0:
+        value, digit = divmod(value, 58)
+        encoded = BASE58_ALPHABET[digit] + encoded
+
+    leading_zeroes = 0
+    for byte in public_key:
+        if byte != 0:
+            break
+        leading_zeroes += 1
+    return ("1" * leading_zeroes) + encoded if encoded else "1"
+
+
+def derive_crypto_id(public_key: bytes) -> str:
+    return public_key_to_solana_address(public_key)
+
+
+def sha256_hex(data: bytes | str) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def canonical_payload(action: str, fields: dict[str, Any]) -> str:
+    return _stable_json({"action": action, "fields": fields})
+
+
+def _stable_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def base64_url(value: str) -> str:
+    return base64.urlsafe_b64encode(value.encode("utf-8")).decode("ascii").rstrip("=")
+
+
+def decode_base58(value: str) -> bytes:
+    decoded = 0
+    for char in value:
+        digit = BASE58_ALPHABET.find(char)
+        if digit == -1:
+            raise ValueError(f"Invalid base58 character: {char}")
+        decoded = decoded * 58 + digit
+
+    raw = decoded.to_bytes((decoded.bit_length() + 7) // 8, "big") if decoded else b""
+    leading_zeroes = len(value) - len(value.lstrip("1"))
+    return (b"\x00" * leading_zeroes) + raw

tinyplace/http.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+from urllib.parse import quote, urlencode
+
+import aiohttp
+
+from .auth import AdminSigningOptions, sign_admin_request, sign_directory_write, sign_request
+from .signer import Signer
+from .types import Headers, Json, Query
+
+AuthInvalidHook = Callable[[int, Json], None]
+
+
+@dataclass(frozen=True)
+class PaymentChallenge:
+    scheme: str | None = None
+    network: str | None = None
+    asset: str | None = None
+    amount: str | None = None
+    from_: str | None = None
+    to: str | None = None
+    nonce: str | None = None
+    expires_at: str | None = None
+    signature: str | None = None
+    metadata: dict[str, str] | None = None
+
+
+@dataclass(frozen=True)
+class PaymentRequiredChallenge:
+    payment: dict[str, Any]
+    error: str | None = None
+
+
+class TinyPlaceError(Exception):
+    def __init__(
+        self,
+        status: int,
+        body: Json,
+        message: str | None = None,
+        *,
+        headers: Headers | None = None,
+        payment_required: PaymentRequiredChallenge | None = None,
+    ) -> None:
+        super().__init__(message or f"HTTP {status}")
+        self.status = status
+        self.body = body
+        self.headers = headers or {}
+        self.payment_required = payment_required or _payment_required_from_body(body)
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        signer: Signer | None = None,
+        admin_signer: Signer | None = None,
+        admin: AdminSigningOptions | None = None,
+        session: aiohttp.ClientSession | None = None,
+        on_auth_invalid: AuthInvalidHook | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.signer = signer
+        self.public_key_base64 = signer.public_key_base64 if signer else None
+        self.admin_signer = admin_signer
+        self.admin = admin or AdminSigningOptions()
+        self._session = session
+        self._owns_session = session is None
+        self._on_auth_invalid = on_auth_invalid
+
+    async def close(self) -> None:
+        if self._session and self._owns_session:
+            await self._session.close()
+        self._session = None
+
+    def signing_public_key(self) -> str | None:
+        return self.public_key_base64
+
+    async def get(self, path: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query)
+
+    async def get_auth(self, path: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query, auth="signed")
+
+    async def get_admin(self, path: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query, auth="admin")
+
+    async def get_text(self, path: str, query: Query = None) -> str:
+        return await self._request("GET", path, query=query, response_type="text")
+
+    async def get_directory_auth(self, path: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query, auth="directory")
+
+    async def get_directory_auth_as(self, path: str, actor: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query, auth="directory", actor=actor)
+
+    async def get_agent_auth(self, path: str, query: Query = None) -> Json:
+        return await self._request("GET", path, query=query, auth="agent")
+
+    async def post(self, path: str, body: Json = None) -> Json:
+        return await self._request("POST", path, body=body, auth="signed")
+
+    async def post_public(self, path: str, body: Json = None) -> Json:
+        return await self._request("POST", path, body=body)
+
+    async def post_admin(self, path: str, body: Json = None) -> Json:
+        return await self._request("POST", path, body=body, auth="admin")
+
+    async def post_directory_auth(self, path: str, body: Json = None) -> Json:
+        return await self._request("POST", path, body=body, auth="directory")
+
+    async def post_directory_auth_as(self, path: str, actor: str, body: Json = None) -> Json:
+        return await self._request("POST", path, body=body, auth="directory", actor=actor)
+
+    async def put(self, path: str, body: Json = None) -> Json:
+        return await self._request("PUT", path, body=body, auth="signed")
+
+    async def put_directory_auth(self, path: str, body: Json = None) -> Json:
+        return await self._request("PUT", path, body=body, auth="directory")
+
+    async def put_directory_auth_as(self, path: str, actor: str, body: Json = None) -> Json:
+        return await self._request("PUT", path, body=body, auth="directory", actor=actor)
+
+    async def put_agent_auth(self, path: str, body: Json = None) -> Json:
+        return await self._request("PUT", path, body=body, auth="agent")
+
+    async def delete(self, path: str, body: Json = None) -> Json:
+        return await self._request("DELETE", path, body=body, auth="signed")
+
+    async def delete_public(
+        self,
+        path: str,
+        body: Json = None,
+        headers: Headers | None = None,
+    ) -> Json:
+        return await self._request("DELETE", path, body=body, headers=headers)
+
+    async def delete_directory_auth(self, path: str, body: Json = None) -> Json:
+        return await self._request("DELETE", path, body=body, auth="directory")
+
+    async def delete_directory_auth_as(self, path: str, actor: str, body: Json = None) -> Json:
+        return await self._request("DELETE", path, body=body, auth="directory", actor=actor)
+
+    async def delete_agent_auth(self, path: str, body: Json = None) -> Json:
+        return await self._request("DELETE", path, body=body, auth="agent")
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Query = None,
+        body: Json = None,
+        auth: str | None = None,
+        actor: str | None = None,
+        headers: Headers | None = None,
+        response_type: str = "json",
+    ) -> Json:
+        query_string = _build_query(query)
+        request_uri = f"{path}{query_string}"
+        url = f"{self.base_url}{request_uri}"
+        body_text = "" if body is None else json.dumps(body, separators=(",", ":"))
+        request_headers = {"Content-Type": "application/json", **(headers or {})}
+
+        await self._apply_auth(request_headers, auth, method, request_uri, body_text, actor)
+        session = self._get_session()
+        response = await session.request(
+            method,
+            url,
+            headers=request_headers,
+            data=body_text or None,
+        )
+
+        if response.status < 200 or response.status >= 300:
+            await self._raise_error(path, response)
+
+        if response.status == 204:
+            return None
+        if response_type == "raw":
+            return response
+        if response_type == "text":
+            return await response.text()
+        text = await response.text()
+        return None if text == "" else json.loads(text)
+
+    async def _apply_auth(
+        self,
+        headers: Headers,
+        auth: str | None,
+        method: str,
+        request_uri: str,
+        body: str,
+        actor: str | None,
+    ) -> None:
+        if auth == "admin" and self.admin_signer:
+            headers.update(
+                await sign_admin_request(self.admin_signer, method, request_uri, body, self.admin)
+            )
+        elif auth in ("directory", "agent") and self.signer and self.public_key_base64:
+            headers.update(
+                await sign_directory_write(
+                    self.signer,
+                    self.public_key_base64,
+                    method,
+                    request_uri,
+                    body,
+                )
+            )
+            headers["X-Agent-ID"] = self.signer.agent_id if auth == "agent" else actor or self.public_key_base64
+        elif auth == "signed" and self.signer:
+            headers.update(await sign_request(self.signer, body))
+
+    async def _raise_error(self, path: str, response: Any) -> None:
+        text = await response.text()
+        try:
+            body = json.loads(text)
+        except json.JSONDecodeError:
+            body = text
+        headers = {str(k): str(v) for k, v in getattr(response, "headers", {}).items()}
+        if response.status in (401, 403) and self._on_auth_invalid:
+            self._on_auth_invalid(response.status, body)
+        raise TinyPlaceError(
+            response.status,
+            body,
+            f"HTTP {response.status}: {path}",
+            headers=headers,
+            payment_required=_payment_required_from_header(headers),
+        )
+
+    def _get_session(self) -> Any:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+
+def encode(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _build_query(query: Query) -> str:
+    if not query:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    for key, value in query.items():
+        if value is None:
+            continue
+        if isinstance(value, list):
+            pairs.extend((key, str(item)) for item in value)
+        else:
+            pairs.append((key, str(value)))
+    return f"?{urlencode(pairs)}" if pairs else ""
+
+
+def _payment_required_from_body(body: Json) -> PaymentRequiredChallenge | None:
+    if isinstance(body, dict) and isinstance(body.get("payment"), dict):
+        return PaymentRequiredChallenge(error=body.get("error"), payment=body["payment"])
+    return None
+
+
+def _payment_required_from_header(headers: Headers) -> PaymentRequiredChallenge | None:
+    value = headers.get("X-Payment-Required") or headers.get("x-payment-required")
+    if not value:
+        return None
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError:
+        return None
+    if isinstance(parsed, dict) and isinstance(parsed.get("payment"), dict):
+        return PaymentRequiredChallenge(error=parsed.get("error"), payment=parsed["payment"])
+    return None

tinyplace/signer.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from nacl.signing import SigningKey
+
+from .crypto import decode_base58, derive_crypto_id, public_key_to_base64
+
+
+class Signer(ABC):
+    """Abstract signing strategy for agent, directory, and admin auth."""
+
+    agent_id: str
+    public_key_base64: str
+
+    @abstractmethod
+    async def sign(self, data: bytes) -> bytes:
+        """Return an Ed25519 signature over ``data``."""
+
+
+class LocalSigner(Signer):
+    """Local Ed25519 signer backed by PyNaCl."""
+
+    def __init__(self, signing_key: SigningKey) -> None:
+        self._signing_key = signing_key
+        self.public_key = bytes(signing_key.verify_key)
+        self.agent_id = derive_crypto_id(self.public_key)
+        self.public_key_base64 = public_key_to_base64(self.public_key)
+
+    @classmethod
+    def generate(cls) -> "LocalSigner":
+        return cls(SigningKey.generate())
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "LocalSigner":
+        if len(seed) != 32:
+            raise ValueError(f"Ed25519 seed must be 32 bytes, got {len(seed)}")
+        return cls(SigningKey(seed))
+
+    @classmethod
+    def from_solana_secret_key(cls, secret_key: str | bytes) -> "LocalSigner":
+        secret = decode_base58(secret_key) if isinstance(secret_key, str) else secret_key
+        if len(secret) not in (32, 64):
+            raise ValueError(f"Solana secret key must be 32 or 64 bytes, got {len(secret)}")
+        signer = cls.from_seed(secret[:32])
+        if len(secret) == 64 and signer.public_key != secret[32:]:
+            raise ValueError("Solana secret key public key does not match seed")
+        return signer
+
+    async def sign(self, data: bytes) -> bytes:
+        return bytes(self._signing_key.sign(data).signature)