decdn 0.1.0__py3-none-any.whl

decdn/_verify.py

@@ -0,0 +1,119 @@
+"""The body guard: a stream that passes the gateway's bytes through, hashes them as they go when
+the request named the bytes by hash, and ends with an error instead of finishing when they do not
+hash to it, when fewer bytes arrive than declared, or when more arrive than the body may hold."""
+
+from collections.abc import AsyncIterator, Iterator
+from dataclasses import dataclass
+
+import httpx
+
+from decdn.errors import DecdnError
+from decdn.hashing import create_blake3
+
+_READ_ERRORS = (httpx.HTTPError, httpx.StreamError)
+
+
+@dataclass(frozen=True)
+class GuardOptions:
+    """What a guarded body must satisfy."""
+
+    # The hash the whole body must have, or `None` to skip the check.
+    hash: str | None = None
+    # The fewest bytes the body holds: the manifest's size, or Content-Length.
+    length: int | None = None
+    # The most bytes the body may hold: the manifest's size, or the window asked for.
+    max: int | None = None
+
+
+class _State:
+    """The running count and hash of a guarded body."""
+
+    def __init__(self, opts: GuardOptions) -> None:
+        self.opts = opts
+        self.hasher = create_blake3() if opts.hash is not None else None
+        self.delivered = 0
+
+    def accept(self, chunk: bytes) -> None:
+        """Count `chunk`, or raise `TRUNCATED` when it runs past `max`."""
+        self.delivered += len(chunk)
+        if self.opts.max is not None and self.delivered > self.opts.max:
+            raise DecdnError("TRUNCATED", f"the body ran past the {self.opts.max} bytes it may hold")
+        if self.hasher is not None:
+            self.hasher.update(chunk)
+
+    def finish(self) -> None:
+        """Raise when the body ended short or hashes to something else."""
+        length = self.opts.length
+        if length is not None and self.delivered < length:
+            raise DecdnError("TRUNCATED", f"the body ended after {self.delivered} of {length} bytes")
+        if self.hasher is not None and self.opts.hash is not None:
+            got = self.hasher.hex()
+            if got != self.opts.hash:
+                raise DecdnError("HASH_MISMATCH", f"the body hashes to {got}, not {self.opts.hash}")
+
+
+def guard(chunks: Iterator[bytes], opts: GuardOptions) -> Iterator[bytes]:
+    """Yield `chunks`, guarded.
+
+    A failed read is `TRUNCATED`, a short or long body `TRUNCATED`, a wrong hash `HASH_MISMATCH`.
+    """
+    state = _State(opts)
+    try:
+        while True:
+            try:
+                chunk = next(chunks)
+            except StopIteration:
+                break
+            except _READ_ERRORS as e:
+                raise DecdnError("TRUNCATED", "the body ended early") from e
+            state.accept(chunk)
+            yield chunk
+        state.finish()
+    finally:
+        close = getattr(chunks, "close", None)
+        if close is not None:
+            close()
+
+
+async def aguard(chunks: AsyncIterator[bytes], opts: GuardOptions) -> AsyncIterator[bytes]:
+    """Yield `chunks`, guarded: the async form of `guard`."""
+    state = _State(opts)
+    try:
+        while True:
+            try:
+                chunk = await anext(chunks)
+            except StopAsyncIteration:
+                break
+            except _READ_ERRORS as e:
+                raise DecdnError("TRUNCATED", "the body ended early") from e
+            state.accept(chunk)
+            yield chunk
+        state.finish()
+    finally:
+        aclose = getattr(chunks, "aclose", None)
+        if aclose is not None:
+            await aclose()
+
+
+def collect(chunks: Iterator[bytes], limit: int | None = None) -> bytes:
+    """Return every byte of `chunks`, joined."""
+    parts: list[bytes] = []
+    total = 0
+    for chunk in chunks:
+        total += len(chunk)
+        if limit is not None and total > limit:
+            raise DecdnError("MALFORMED_MANIFEST", f"the body is larger than {limit} bytes")
+        parts.append(chunk)
+    return b"".join(parts)
+
+
+async def acollect(chunks: AsyncIterator[bytes], limit: int | None = None) -> bytes:
+    """Return every byte of `chunks`, joined: the async form of `collect`."""
+    parts: list[bytes] = []
+    total = 0
+    async for chunk in chunks:
+        total += len(chunk)
+        if limit is not None and total > limit:
+            raise DecdnError("MALFORMED_MANIFEST", f"the body is larger than {limit} bytes")
+        parts.append(chunk)
+    return b"".join(parts)

decdn/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

decdn/base32.py

@@ -0,0 +1,54 @@
+"""Site labels: a bundle's manifest hash as RFC 4648 base32, lowercase and unpadded.
+
+A label is 52 characters, inside the 63-character DNS label limit, as the gateway writes them
+(https://github.com/decdn/decdn/blob/main/crates/cli/src/commands/gateway/site.rs).
+"""
+
+from decdn._hex import from_hex, is_hash, to_hex
+from decdn.errors import DecdnError
+
+_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567"
+_LABEL_LEN = 52
+
+
+def hash_to_base32(hash: str) -> str:
+    """Return the site label of a 64-hex-character hash."""
+    data = from_hex(hash) if is_hash(hash) else None
+    if data is None:
+        raise DecdnError("BAD_URI", f"not a 64-hex-character hash: {hash}")
+    out: list[str] = []
+    buffer = 0
+    bits = 0
+    for b in data:
+        buffer = (buffer << 8) | b
+        bits += 8
+        while bits >= 5:
+            bits -= 5
+            out.append(_ALPHABET[(buffer >> bits) & 31])
+        buffer &= (1 << bits) - 1
+    if bits > 0:
+        out.append(_ALPHABET[(buffer << (5 - bits)) & 31])
+    return "".join(out)
+
+
+def base32_to_hash(label: str) -> str | None:
+    """Return the hash a canonical site label encodes, as 64 lowercase hex characters.
+
+    Return `None` for anything else: the wrong length, uppercase, or nonzero trailing bits (a
+    second spelling the gateway refuses).
+    """
+    if len(label) != _LABEL_LEN or any(c not in _ALPHABET for c in label):
+        return None
+    out = bytearray()
+    buffer = 0
+    bits = 0
+    for c in label:
+        buffer = (buffer << 5) | _ALPHABET.index(c)
+        bits += 5
+        if bits >= 8:
+            bits -= 8
+            out.append((buffer >> bits) & 0xFF)
+            buffer &= (1 << bits) - 1
+    if buffer != 0:
+        return None
+    return to_hex(bytes(out))

decdn/capability.py

@@ -0,0 +1,109 @@
+"""`dcap1:` capability tokens, as the Rust encoder writes them.
+
+The encoder is
+https://github.com/decdn/decdn/blob/main/crates/incentive/src/capability_grant.rs. A token
+is `dcap1:` + base64url (no padding) of the postcard encoding of
+`{pool_id: [u8;32], signer: [u8;20], spending_cap: u64, expiry: u64,
+owner_signature: Vec<u8>}`. Postcard writes a byte string as a varint length and the
+bytes, and an integer as a LEB128 varint.
+"""
+
+from dataclasses import dataclass
+
+from decdn._hex import to_hex
+from decdn.errors import DecdnError
+
+_PREFIX = "dcap1:"
+_B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+
+
+@dataclass(frozen=True)
+class Capability:
+    """A pool owner's spending grant to a delegate signer."""
+
+    pool_id: str
+    """The on-chain pool, `0x` + 64 hex."""
+    signer: str
+    """The delegate voucher-signing address, `0x` + 40 hex."""
+    spending_cap: int
+    """Cumulative spend ceiling in USDC base units."""
+    expiry: int
+    """Unix-seconds expiry."""
+    owner_signature: str
+    """The owner's raw EIP-712 signature, `0x` + hex."""
+
+
+def _bad(message: str) -> DecdnError:
+    return DecdnError("BAD_CAPABILITY", message)
+
+
+def _truncated() -> DecdnError:
+    return _bad("capability token payload is malformed (truncated or corrupt)")
+
+
+def _from_base64url(body: str) -> bytes:
+    out = bytearray()
+    buffer = 0
+    bits = 0
+    for c in body:
+        v = _B64URL.find(c)
+        if v < 0:
+            raise _bad("capability token body is not valid base64url")
+        buffer = ((buffer << 6) | v) & 0xFFFF
+        bits += 6
+        if bits >= 8:
+            bits -= 8
+            out.append((buffer >> bits) & 0xFF)
+    if len(body) % 4 == 1 or (buffer & ((1 << bits) - 1)) != 0:
+        raise _bad("capability token body is not valid base64url")
+    return bytes(out)
+
+
+class _Reader:
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+        self._at = 0
+
+    def varint(self) -> int:
+        value = 0
+        for shift in range(0, 70, 7):
+            if self._at >= len(self._data):
+                raise _truncated()
+            b = self._data[self._at]
+            self._at += 1
+            value |= (b & 0x7F) << shift
+            if b & 0x80 == 0:
+                if value >= 1 << 64:
+                    raise _truncated()
+                return value
+        raise _truncated()
+
+    def bytes_of(self, length: int | None = None) -> bytes:
+        n = self.varint()
+        if length is not None and n != length:
+            raise _truncated()
+        if self._at + n > len(self._data):
+            raise _truncated()
+        out = self._data[self._at : self._at + n]
+        self._at += n
+        return out
+
+    def done(self) -> bool:
+        return self._at == len(self._data)
+
+
+def parse_capability(token: str) -> Capability:
+    """Decode a `dcap1:` token. Raises `BAD_CAPABILITY` for anything else."""
+    if not token.startswith(_PREFIX):
+        raise _bad("not a dcap1 capability token (missing the `dcap1:` prefix)")
+    r = _Reader(_from_base64url(token[len(_PREFIX) :]))
+    capability = Capability(
+        pool_id=f"0x{to_hex(r.bytes_of(32))}",
+        signer=f"0x{to_hex(r.bytes_of(20))}",
+        spending_cap=r.varint(),
+        expiry=r.varint(),
+        owner_signature=f"0x{to_hex(r.bytes_of())}",
+    )
+    if not r.done():
+        raise _truncated()
+    return capability