herald-run 0.3.0b1__tar.gz

herald_run-0.3.0b1/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+dist-python/
+dist-npm/
+.venv/
+__pycache__/
+*.pyc
+.env*
+.DS_Store

herald_run-0.3.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herald contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

herald_run-0.3.0b1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: herald-run
+Version: 0.3.0b1
+Summary: Python client for Herald, the human-in-the-loop inbox for agents
+Project-URL: Homepage, https://herald.run
+Project-URL: Documentation, https://herald.run/docs/python/
+Project-URL: Source, https://github.com/herald-run/sdk
+Project-URL: Issues, https://github.com/herald-run/sdk/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: websockets<17,>=14
+Description-Content-Type: text/markdown
+
+# herald-run
+
+Python client for [Herald](https://herald.run), the human-in-the-loop inbox for agents: send messages, ask for approvals, run tasks, and move files and secrets. Python 3.11+. The import name is `herald`.
+
+```sh
+pip install --pre herald-run
+```
+
+## Authentication
+
+Create a token in Herald under Settings → Connections, or run `npx @herald-run/cli login`. Pass it as `api_key`, or set `HERALD_API_KEY` (or `HERALD_TOKEN`). `HERALD_URL` selects another server. Never commit tokens.
+
+## One-minute example
+
+```python
+import asyncio
+from herald import Herald
+
+async def main():
+    async with Herald() as herald:
+        await herald.send(title="Build passed", body="Preview is ready.")
+        answer = await herald.ask_action(
+            title="Deploy to production?",
+            actions=[{"id": "approve", "label": "Approve", "values": {}}, {"id": "reject", "label": "Reject", "values": {}}],
+            timeout=600,
+        )
+        print(answer.action_id)
+
+asyncio.run(main())
+```
+
+Without asyncio, use `SyncHerald`, which has the same methods: `SyncHerald().send(title="Hi")`. Failures raise `HeraldError` with `status`, `code`, `message_id` and `retry_after`. Methods are snake_case and return Pydantic models (`.wire()` gives the JSON). Documentation: [herald.run/docs/python](https://herald.run/docs/python/); API reference: [herald.run/docs/api](https://herald.run/docs/api/). MIT licensed.

herald_run-0.3.0b1/README.md

@@ -0,0 +1,32 @@
+# herald-run
+
+Python client for [Herald](https://herald.run), the human-in-the-loop inbox for agents: send messages, ask for approvals, run tasks, and move files and secrets. Python 3.11+. The import name is `herald`.
+
+```sh
+pip install --pre herald-run
+```
+
+## Authentication
+
+Create a token in Herald under Settings → Connections, or run `npx @herald-run/cli login`. Pass it as `api_key`, or set `HERALD_API_KEY` (or `HERALD_TOKEN`). `HERALD_URL` selects another server. Never commit tokens.
+
+## One-minute example
+
+```python
+import asyncio
+from herald import Herald
+
+async def main():
+    async with Herald() as herald:
+        await herald.send(title="Build passed", body="Preview is ready.")
+        answer = await herald.ask_action(
+            title="Deploy to production?",
+            actions=[{"id": "approve", "label": "Approve", "values": {}}, {"id": "reject", "label": "Reject", "values": {}}],
+            timeout=600,
+        )
+        print(answer.action_id)
+
+asyncio.run(main())
+```
+
+Without asyncio, use `SyncHerald`, which has the same methods: `SyncHerald().send(title="Hi")`. Failures raise `HeraldError` with `status`, `code`, `message_id` and `retry_after`. Methods are snake_case and return Pydantic models (`.wire()` gives the JSON). Documentation: [herald.run/docs/python](https://herald.run/docs/python/); API reference: [herald.run/docs/api](https://herald.run/docs/api/). MIT licensed.

herald_run-0.3.0b1/herald/__init__.py

@@ -0,0 +1,11 @@
+"""Herald's async client (`Herald`) and its blocking wrapper (`SyncHerald`). Runtime checkpoints remain with the caller."""
+from ._version import __version__
+from .client import Herald
+from .crypto import create_keys, seal, unseal
+from .http import HeraldError
+from .live import LiveSocket, backoff
+from .models import Account, ActionAnswer, Attachment, CreatedIntegration, Destination, Envelope, FileDownload, Integration, Lease, Message, Ping, Response, SecretReceiver, TaskClaim, TaskExecution, TaskInput, TaskLog, TaskResult, ThreadPage, TokenInfo, Tombstone
+from .sync import SyncHerald
+from .webhook import verify_webhook
+
+__all__ = ["Account", "ActionAnswer", "Attachment", "CreatedIntegration", "Destination", "Envelope", "FileDownload", "Herald", "HeraldError", "Integration", "Lease", "LiveSocket", "Message", "Ping", "Response", "SecretReceiver", "SyncHerald", "TaskClaim", "TaskExecution", "TaskInput", "TaskLog", "TaskResult", "ThreadPage", "TokenInfo", "Tombstone", "__version__", "backoff", "create_keys", "seal", "unseal", "verify_webhook"]

herald_run-0.3.0b1/herald/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0b1"

herald_run-0.3.0b1/herald/client.py

@@ -0,0 +1,336 @@
+import asyncio
+import os
+import re
+import uuid
+from urllib.parse import quote, unquote, urlencode, urlparse
+
+import httpx
+from pydantic import BaseModel
+from websockets.asyncio.client import connect
+
+from ._version import __version__
+from .crypto import unseal
+from .http import HeraldError, chunks, idle_body, parse_retry_after, raise_error, read_json, retry_delay, retryable
+from .live import LiveSocket
+from .models import Account, ActionAnswer, Attachment, CreatedIntegration, Destination, Envelope, FileDownload, Integration, Lease, Message, Ping, SecretReceiver, TaskClaim, TaskLog, ThreadPage, TokenInfo, Tombstone
+
+RETRIES = 2
+# Seconds between HTTP checks while the live socket is quiet or down.
+POLL = 30
+FINAL = ("answered", "expired", "cancelled")
+
+
+class OriginConnection(connect):
+    # Some supported websockets versions resend additional_headers on redirect.
+    # Herald event streams must stay on the configured origin on every version.
+    def process_redirect(self, error):
+        return error
+
+
+def path(value):
+    return quote(value, safe="")
+
+
+def file_name(header):
+    """The file name from `Content-Disposition`, without any directory part."""
+    encoded = re.search(r"filename\*=UTF-8''([^;]+)", header or "", re.I)
+    plain = re.search(r'filename="([^"]*)"', header or "", re.I)
+    name = unquote(encoded[1]) if encoded else plain[1] if plain else ""
+    return re.split(r"[\\/]", name)[-1]
+
+
+def wire(value):
+    """Request JSON: models nested anywhere become their camelCase records."""
+    if isinstance(value, BaseModel):
+        return value.wire()
+    if isinstance(value, dict):
+        return {key: wire(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [wire(item) for item in value]
+    return value
+
+
+class Herald:
+    def __init__(self, api_key=None, url=None, *, max_retry_after=60, transport=None, user_agent=None):
+        self.url = (url or os.getenv("HERALD_URL", "https://app.herald.run")).rstrip("/")
+        origin = urlparse(self.url)
+        if origin.scheme != "https" and not (origin.scheme == "http" and origin.hostname in ("localhost", "127.0.0.1")):
+            raise ValueError("Use HTTPS for Herald.")
+        if origin.username or origin.password or origin.query or origin.fragment or origin.path not in ("", "/"):
+            raise ValueError("Use a server URL without credentials, path, query or fragment.")
+        self.key = api_key or os.getenv("HERALD_API_KEY") or os.getenv("HERALD_TOKEN", "")
+        # Longest server Retry-After, in seconds, that a request waits out before failing.
+        self.max_retry_after = max_retry_after
+        # `transport` replaces the network, e.g. with `httpx.MockTransport` in tests.
+        self.user_agent = user_agent or "herald-python/" + __version__
+        self.http = httpx.AsyncClient(timeout=15, follow_redirects=False, headers={"Authorization": "Bearer " + self.key, "User-Agent": self.user_agent}, transport=transport)
+        # One socket shared by every wait() and watch() on this client.
+        self.live = LiveSocket(self.socket)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()
+
+    async def close(self):
+        await self.http.aclose()
+
+    async def request(self, path, body=None, *, method=None, idempotency_key=None, retry=True):
+        """Calls `/api/v1` + `path`. Reads and keyed writes retry network errors and 5xx; any request
+        retries a rate limit that sends Retry-After, since the server rejected it unprocessed."""
+        response = await self._fetch("/api/v1" + path, body, method=method, idempotency_key=idempotency_key, retry=retry)
+        return read_json(response, parse_retry_after(response.headers.get("Retry-After")))
+
+    async def _fetch(self, path, body=None, *, method=None, idempotency_key=None, retry=True, stream=False):
+        safe = body is None or bool(idempotency_key)
+        retries = RETRIES if retry else 0
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        attempt = 0
+        while True:
+            try:
+                request = self.http.build_request(method or ("GET" if body is None else "POST"), self.url + path, json=wire(body), headers=headers)
+                response = await self.http.send(request, stream=stream)
+            except httpx.TransportError:
+                if attempt >= retries or not safe:
+                    raise
+                await asyncio.sleep(retry_delay(attempt))
+                attempt += 1
+                continue
+            if 300 <= response.status_code < 400:
+                await response.aclose()
+                raise HeraldError("Herald does not accept API redirects.", response.status_code)
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+            status = response.status_code
+            again = (safe or retry_after is not None) if status == 429 else (status >= 500 and safe)
+            if again and attempt < retries and (retry_after or 0) <= self.max_retry_after:
+                await response.aclose()
+                await asyncio.sleep(retry_delay(attempt) if retry_after is None else retry_after)
+                attempt += 1
+                continue
+            return response
+
+    async def ping(self):
+        """Public liveness check; needs no token."""
+        return Ping.model_validate(read_json(await self._fetch("/api/ping")))
+
+    async def token(self):
+        """The calling token's name, scopes and account."""
+        return TokenInfo.model_validate(await self.request("/token"))
+
+    async def revoke_token(self):
+        """Revokes the calling token; later requests with it fail with 401."""
+        await self.request("/token", method="DELETE")
+
+    async def account(self):
+        """Plan, usage and limits of the token's account."""
+        return Account.model_validate(await self.request("/account"))
+
+    async def send(self, *, idempotency_key=None, **message):
+        return Message.model_validate(await self.request("/messages", message, idempotency_key=idempotency_key or str(uuid.uuid4())))
+
+    async def get(self, message_id):
+        return Message.model_validate(await self.request("/messages/" + path(message_id)))
+
+    async def messages(self, **query):
+        """One page of the revision feed (`after=`, with `Tombstone`s for `tombstones=1`), or
+        messages matching `status`/`direction`."""
+        search = urlencode({key: value for key, value in query.items() if value is not None})
+        page = await self.request("/messages" + ("?" + search if search else ""))
+        return [(Tombstone if m.get("deleted") is True else Message).model_validate(m) for m in page]
+
+    async def thread(self, message_id, *, after=0):
+        return ThreadPage.model_validate(await self.request("/messages/" + path(message_id) + "/thread?after=" + str(after)))
+
+    async def thread_messages(self, message_id):
+        after = 0
+        while True:
+            page = await self.thread(message_id, after=after)
+            for message in page.messages:
+                yield message
+            if page.next is None:
+                return
+            after = page.next
+
+    async def cancel(self, message_id):
+        """Cancels a pending request this integration sent."""
+        return Message.model_validate(await self.request("/messages/" + path(message_id) + "/cancel", {}))
+
+    async def task_logs(self, message_id, *, after=None):
+        """A task's retained log lines after `after` (a sequence number)."""
+        query = "" if after is None else "?after=" + str(int(after))
+        page = await self.request(f"/messages/{path(message_id)}/logs{query}")
+        return [TaskLog.model_validate(log) for log in page["logs"]]
+
+    async def download(self, file_id):
+        """An attachment's name and bytes."""
+        response = await self._fetch("/api/v1/files/" + path(file_id), stream=True)
+        try:
+            if response.is_error:
+                await response.aread()
+                raise_error(response, "File download failed.")
+            data = await response.aread()
+        finally:
+            await response.aclose()
+        name = file_name(response.headers.get("Content-Disposition")) or file_id
+        return FileDownload(name=name, type=response.headers.get("Content-Type", "application/octet-stream"), data=data)
+
+    async def register(self, **destination):
+        """Creates a destination, or updates the one registered with the same `key`."""
+        return Destination.model_validate(await self.request("/destinations", destination))
+
+    async def destinations(self):
+        return [Destination.model_validate(d) for d in await self.request("/destinations")]
+
+    async def update_destination(self, destination_id, **destination):
+        return Destination.model_validate(await self.request("/destinations/" + path(destination_id), destination, method="PUT"))
+
+    async def delete_destination(self, destination_id):
+        """Removes a destination and cancels its queued tasks."""
+        await self.request("/destinations/" + path(destination_id), method="DELETE")
+
+    async def rotate_destination_secret(self, destination_id):
+        """Replaces a webhook destination's signing secret, returned once."""
+        return Destination.model_validate(await self.request(f"/destinations/{path(destination_id)}/secret", {}))
+
+    async def claim_task(self, task_id, *, runner_id, heartbeat=False):
+        """`heartbeat=True` asks for a lease that lapses unless renewed with `heartbeat_task`."""
+        return TaskClaim.model_validate(await self.request(f"/tasks/{path(task_id)}/claim", {"runnerId": runner_id, "heartbeat": heartbeat}))
+
+    async def heartbeat_task(self, task_id, lease):
+        return Lease.model_validate(await self.request(f"/tasks/{path(task_id)}/heartbeat", {"lease": lease}))
+
+    async def update_task(self, task_id, *, lease=None, status=None, error=None, logs=None, idempotency_key=None, retry=True):
+        """Reports logs and/or the outcome; keyed log batches retry safely."""
+        update = {"lease": lease, "status": status, "error": error, "logs": logs}
+        body = {key: value for key, value in update.items() if value is not None}
+        return Message.model_validate(await self.request(f"/tasks/{path(task_id)}/update", body, idempotency_key=idempotency_key, retry=retry))
+
+    async def collect_secrets(self, message_id):
+        """Consumes the encrypted envelopes of an answered request's secret fields."""
+        envelopes = await self.request(f"/messages/{path(message_id)}/secrets", {})
+        return {field: Envelope.model_validate(envelope) for field, envelope in envelopes.items()}
+
+    async def reveal_secrets(self, message_id, private_key):
+        """`collect_secrets`, decrypted with the private JWK whose public key the request carried."""
+        return {field: unseal(envelope, private_key) for field, envelope in (await self.collect_secrets(message_id)).items()}
+
+    async def secret_receiver(self, message_id):
+        """For a `kind="secret"` offer: the receiver's claim and public key once a device claims it."""
+        return SecretReceiver.model_validate(await self.request(f"/messages/{path(message_id)}/secret-receiver"))
+
+    async def deliver_secret(self, message_id, *, claim_id, envelope):
+        """Deposits the value sealed to the claimed receiver's key; repeating the same deposit is safe."""
+        await self.request(f"/messages/{path(message_id)}/secret-delivery", {"claimId": claim_id, "envelope": envelope})
+
+    async def integrations(self):
+        """Human sessions only: the account's connections."""
+        return [Integration.model_validate(i) for i in await self.request("/integrations")]
+
+    async def create_integration(self, *, name, scopes):
+        """Human sessions only; the token is returned once. Not retried, so it never creates two."""
+        return CreatedIntegration.model_validate(await self.request("/integrations", {"name": name, "scopes": scopes}))
+
+    async def delete_integration(self, integration_id):
+        """Human sessions only: revokes the token and removes the connection's destinations."""
+        await self.request("/integrations/" + path(integration_id), method="DELETE")
+
+    def socket(self):
+        return OriginConnection(self.url.replace("http", "ws", 1) + "/ws", additional_headers={"Authorization": "Bearer " + self.key}, user_agent_header=self.user_agent, open_timeout=15)
+
+    async def wait(self, message_id, *, wait_timeout=3600):
+        if not 0 < wait_timeout <= 86400:
+            raise ValueError("Wait timeout must be between zero and 24 hours.")
+        event = self.live.subscribe()
+        try:
+            async with asyncio.timeout(wait_timeout):
+                while True:
+                    event.clear()
+                    try:
+                        message = await self.get(message_id)
+                        if message.status in FINAL:
+                            return message
+                    except HeraldError as error:
+                        if not retryable(error):
+                            raise
+                    except httpx.TransportError:
+                        pass
+                    try:
+                        await asyncio.wait_for(event.wait(), POLL)
+                    except TimeoutError:
+                        pass
+        except TimeoutError as error:
+            raise HeraldError("Wait timed out; resume with the message ID. The request remains available.", 408, message_id) from error
+        finally:
+            self.live.unsubscribe(event)
+
+    async def ask(self, *, title, schema=None, timeout=None, wait_timeout=3600, idempotency_key=None, **message):
+        result, model = await self._answer(title=title, schema=schema, timeout=timeout, wait_timeout=wait_timeout, idempotency_key=idempotency_key, **message)
+        values = result.response.values
+        return model.model_validate(values) if model else values
+
+    async def ask_action(self, *, title, actions, schema=None, timeout=None, wait_timeout=3600, idempotency_key=None, **message):
+        if not actions:
+            raise ValueError("ask_action requires declared actions.")
+        result, model = await self._answer(title=title, actions=actions, schema=schema, timeout=timeout, wait_timeout=wait_timeout, idempotency_key=idempotency_key, **message)
+        action_id = result.response and result.response.action_id
+        if not action_id or not any(action["id"] == action_id for action in actions):
+            raise HeraldError("The response does not identify a declared action.", 502, result.id)
+        values = result.response.values
+        return ActionAnswer(action_id=action_id, values=model.model_validate(values) if model else values)
+
+    async def _answer(self, *, title, schema=None, timeout=None, wait_timeout=3600, idempotency_key=None, **message):
+        model = schema if isinstance(schema, type) and issubclass(schema, BaseModel) else None
+        if schema is not None:
+            message["schema"] = model.model_json_schema() if model else schema
+        if timeout is not None:
+            if not isinstance(timeout, (float, int)) or not 0 < timeout <= 86400:
+                raise ValueError("Timeout must be seconds between zero and 24 hours.")
+            if "expiresAt" in message or "expiresIn" in message:
+                raise ValueError("Use timeout or expiresAt, not both.")
+            message["expiresIn"] = timeout
+        sent = await self.send(title=title, kind="form", idempotency_key=idempotency_key, **message)
+        result = await self.wait(sent.id, wait_timeout=wait_timeout)
+        if result.status != "answered":
+            raise HeraldError("Request " + result.status + ".", 410, sent.id)
+        return result, model
+
+    async def watch(self, *, after=0):
+        if not isinstance(after, int) or after < 0:
+            raise ValueError("Use a nonnegative revision.")
+        event = self.live.subscribe()
+        try:
+            while True:
+                event.clear()
+                try:
+                    page = await self.messages(after=after)
+                except (HeraldError, httpx.TransportError) as error:
+                    if isinstance(error, HeraldError) and not retryable(error):
+                        raise
+                    await asyncio.sleep(3)
+                    continue
+                for message in page:
+                    yield message
+                    after = max(after, message.revision or 0)
+                if len(page) == 100:
+                    continue
+                try:
+                    await asyncio.wait_for(event.wait(), POLL)
+                except TimeoutError:
+                    pass
+        finally:
+            self.live.unsubscribe(event)
+
+    async def upload(self, name, data, content_type="application/octet-stream", *, size=None, idle_timeout=60):
+        """Reserves and uploads bytes or an async iterable of bytes (pass `size`); aborts only
+        after `idle_timeout` seconds without progress."""
+        if isinstance(data, (bytes, bytearray)):
+            size = len(data)
+            data = chunks(data)
+        if not isinstance(size, int) or size < 0:
+            raise ValueError("Pass the byte size for streamed uploads.")
+        file = Attachment.model_validate(await self.request("/files", {"name": name, "type": content_type, "size": size}))
+        response = await self.http.put(self.url + "/api/v1/files/" + path(file.id), content=idle_body(data, idle_timeout), headers={"Content-Length": str(size)}, timeout=idle_timeout)
+        if not response.is_success:
+            raise_error(response, "File upload failed.")
+        return Attachment(id=file.id, name=file.name, size=file.size, type=file.type)

herald_run-0.3.0b1/herald/crypto.py

@@ -0,0 +1,54 @@
+"""Secret envelopes, compatible with the TypeScript SDK: RSA-OAEP-256 wraps an AES-256-GCM key."""
+import base64
+import os
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .models import Envelope
+
+OAEP = padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()), algorithm=hashes.SHA256(), label=None)
+
+
+def _b64url(number):
+    raw = number.to_bytes((number.bit_length() + 7) // 8, "big")
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def _int(value):
+    return int.from_bytes(base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)), "big")
+
+
+def create_keys():
+    """A request key pair as JWK dicts: send `public_key` with the form, keep `private_key` private."""
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    priv, pub = key.private_numbers(), key.public_key().public_numbers()
+    public = {"kty": "RSA", "n": _b64url(pub.n), "e": _b64url(pub.e), "alg": "RSA-OAEP-256", "ext": True, "key_ops": ["encrypt"]}
+    private = {**public, "key_ops": ["decrypt"], "d": _b64url(priv.d), "p": _b64url(priv.p), "q": _b64url(priv.q), "dp": _b64url(priv.dmp1), "dq": _b64url(priv.dmq1), "qi": _b64url(priv.iqmp)}
+    return public, private
+
+
+def _public(jwk):
+    return rsa.RSAPublicNumbers(_int(jwk["e"]), _int(jwk["n"])).public_key()
+
+
+def _private(jwk):
+    public = rsa.RSAPublicNumbers(_int(jwk["e"]), _int(jwk["n"]))
+    return rsa.RSAPrivateNumbers(_int(jwk["p"]), _int(jwk["q"]), _int(jwk["d"]), _int(jwk["dp"]), _int(jwk["dq"]), _int(jwk["qi"]), public).private_key()
+
+
+def seal(value, public_key):
+    """Encrypts `value` to a receiver's public JWK."""
+    aes, iv = AESGCM.generate_key(bit_length=256), os.urandom(12)
+    data = AESGCM(aes).encrypt(iv, value.encode(), None)
+    encode = lambda raw: base64.b64encode(raw).decode()
+    return Envelope(key=encode(_public(public_key).encrypt(aes, OAEP)), iv=encode(iv), data=encode(data))
+
+
+def unseal(envelope, private_key):
+    """Decrypts an envelope with the private JWK whose public key the request carried."""
+    if not isinstance(envelope, Envelope):
+        envelope = Envelope.model_validate(envelope)
+    aes = _private(private_key).decrypt(base64.b64decode(envelope.key), OAEP)
+    return AESGCM(aes).decrypt(base64.b64decode(envelope.iv), base64.b64decode(envelope.data), None).decode()

herald_run-0.3.0b1/herald/http.py

@@ -0,0 +1,100 @@
+import asyncio
+import math
+import random
+import re
+import time
+from email.utils import parsedate_to_datetime
+
+
+class HeraldError(Exception):
+    def __init__(self, message, status, message_id=None, retry_after=None, code=None):
+        super().__init__(message)
+        self.status = status
+        self.message_id = message_id
+        # Seconds from the server's Retry-After header, when sent.
+        self.retry_after = retry_after
+        # Machine-readable code from the server's error body, e.g. "RATE_LIMITED".
+        self.code = code
+
+
+def retryable(error):
+    return error.status == 429 or error.status >= 500
+
+
+def parse_retry_after(value):
+    """Retry-After as seconds: delta-seconds or an HTTP date."""
+    if value is None or not value.strip():
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return int(value)
+    try:
+        seconds = parsedate_to_datetime(value).timestamp() - time.time()
+    except (TypeError, ValueError):
+        return None
+    return max(0, math.ceil(seconds))
+
+
+def retry_delay(attempt):
+    """Network and 5xx retry delay in seconds: 250 ms doubling, with 50-100% jitter."""
+    return 0.25 * 2 ** attempt * (0.5 + random.random() / 2)
+
+
+def error_text(data):
+    error = data.get("error") if isinstance(data, dict) else None
+    if isinstance(error, dict):
+        return error.get("message")
+    return error or (data.get("message") if isinstance(data, dict) else None)
+
+
+def error_code(data):
+    body = data if isinstance(data, dict) else {}
+    code = body.get("error").get("code") if isinstance(body.get("error"), dict) else body.get("code")
+    return code if isinstance(code, str) else None
+
+
+def json_body(response):
+    if not re.match(r"application/([\w.-]+\+)?json\b", response.headers.get("Content-Type", ""), re.I):
+        return False, None
+    try:
+        return True, response.json()
+    except ValueError:
+        return True, None
+
+
+def raise_error(response, fallback):
+    """Raises the failed response's error message and code."""
+    _, data = json_body(response)
+    raise HeraldError(error_text(data) or fallback, response.status_code, retry_after=parse_retry_after(response.headers.get("Retry-After")), code=error_code(data))
+
+
+def read_json(response, retry_after=None):
+    """Checks status and content type before parsing, so proxies' HTML pages never reach JSON."""
+    is_json, data = json_body(response)
+    if response.is_error:
+        raise HeraldError(error_text(data) or f"Herald request failed ({response.status_code}).", response.status_code, retry_after=retry_after, code=error_code(data))
+    if response.status_code == 204:
+        return None
+    if not is_json or data is None:
+        raise HeraldError("Herald returned a response that is not JSON.", response.status_code)
+    return data
+
+
+async def chunks(data, size=1 << 14):
+    for start in range(0, len(data), size):
+        yield bytes(data[start:start + size])
+
+
+async def idle_body(source, idle_timeout):
+    """Yields `source` in 16 KiB slices, so each socket write is small progress that resets
+    httpx's write timeout; raises when the source stalls for `idle_timeout` seconds."""
+    iterator = aiter(source)
+    while True:
+        try:
+            chunk = await asyncio.wait_for(anext(iterator), idle_timeout)
+        except StopAsyncIteration:
+            return
+        except TimeoutError as error:
+            raise HeraldError(f"Upload stalled for {idle_timeout} s.", 408) from error
+        for start in range(0, len(chunk), 1 << 14):
+            yield bytes(chunk[start:start + (1 << 14)])