fleetmesh-node 0.2.0__py3-none-any.whl

node/protocols/nostr/blossom.py

@@ -0,0 +1,627 @@
+"""Blossom Media Protocol (BUD-01..BUD-04) server and client implementation.
+
+Spec reference: spec.html section "Content Addressing & CIDs" and "Blobs" (lines 3768-3776).
+Provides HTTP endpoints on the node relay face:
+- GET /<sha256>[.<ext>]: Download blob with SHA-256 integrity verification.
+- HEAD /<sha256>[.<ext>]: Check blob presence and size (BUD-02).
+- GET /cid/<cid>: Download blob by standard IPFS CIDv1 (raw-sha2-256).
+- HEAD /cid/<cid>: Check blob by CIDv1.
+- PUT /upload: Upload blob with BUD-01 Nostr Kind 24242 authorization.
+- PUT /mirror: Mirror blob from remote HTTP source with BUD-04 hash verification.
+- GET /list/<pubkey>: List blobs uploaded by a pubkey.
+- DELETE /<sha256>: Delete blob (requires uploader authorization).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import socket
+import time
+from typing import Any, Optional, TypedDict
+
+from fleetmesh_core.wire.interfaces import NostrEvent
+from . import blobstore
+from .blobstore import BlobDescriptor
+from node.transport import netfetch, ws
+from fleetmesh_core.storage import blossom_auth
+from fleetmesh_core.accounting import paidfetch
+from fleetmesh_core.crypto.bech32 import bech32_decode
+
+BLOSSOM_KIND: int = 24242
+HEX64_RE = re.compile(r'^[0-9a-f]{64}$')
+
+
+class BlossomBlobMetadata(TypedDict, total=False):
+    """Metadata returned by HEAD /<sha256> (BUD-02)."""
+    sha256: str
+    size: int
+    type: str
+    cid: Optional[str]
+
+
+class BlossomUploadDescriptor(TypedDict, total=False):
+    """Descriptor returned by PUT /upload (BUD-01)."""
+    url: str
+    sha256: str
+    size: int
+    type: str
+    uploaded: int
+
+
+class BlossomMirrorDescriptor(TypedDict, total=False):
+    """Descriptor returned by PUT /mirror (BUD-04)."""
+    url: str
+    sha256: str
+    size: int
+    type: str
+
+
+def _account_of(segment: str) -> Optional[str]:
+    """`npub1…` or 64 hex → hex pubkey, else None."""
+    seg = segment.lower()
+    if seg.startswith('npub1'):
+        raw = bech32_decode('npub', seg)
+        return raw.hex() if raw is not None and len(raw) == 32 else None
+    return seg if HEX64_RE.match(seg) else None
+
+
+def _cashu_tokens(req: Optional[ws.PlainHTTP]) -> list[str]:
+    """Every cashuB token in the request's X-Cashu header(s), in order. NUT-24
+    puts one token in the header; an itemised 402 may ask for two (operator,
+    account), sent comma-separated in one header or as repeated headers."""
+    if req is None:
+        return []
+    raw = req.headers.get(b'x-cashu')
+    if not raw:
+        return []
+    text = raw.decode('latin1') if isinstance(raw, (bytes, bytearray)) else str(raw)
+    return [t.strip() for t in text.split(',') if t.strip()]
+
+
+def create_auth_event(signer_sk: str, action: str, sha256_hex: str, now: Optional[int] = None,
+                      expiration_seconds: int = 300, content: str = '') -> NostrEvent:
+    """A signed BUD-01/BUD-04 authorization (kind 24242); the bytes are fleetmesh_core/blossom_auth.py's."""
+    return blossom_auth.auth_event(signer_sk, action, sha256_hex, int(now if now is not None else time.time()),
+                                   expiration_seconds, content)
+
+
+auth_header = blossom_auth.auth_header
+parse_auth_header = blossom_auth.parse_auth_header
+
+
+class BlossomServer:
+    """Blossom HTTP service provider (BUD-01 to BUD-04)."""
+
+    def __init__(
+        self,
+        store: blobstore.BlobStore,
+        node_pk: Optional[str] = None,
+        operator_pk: Optional[str] = None,
+        require_auth: bool = False,
+        max_upload_bytes: int = 64 * 1024 * 1024,
+        clock: Optional[Any] = None,
+        allow_private_mirror: Any = False,
+        pricing: Optional[Any] = None,
+    ) -> None:
+        self.store: blobstore.BlobStore = store
+        # node/fetch_pricing.PaidFetch or None. None means every fetch is
+        # free and no price header is ever written: the pre-payment server.
+        self.pricing: Optional[Any] = pricing
+        self.node_pk: Optional[str] = node_pk
+        self.operator_pk: Optional[str] = operator_pk
+        self.require_auth: bool = require_auth
+        self.max_upload_bytes: int = max_upload_bytes
+        self.clock = clock or (lambda: int(time.time()))
+        # /mirror source URLs are caller-chosen, so by default only public
+        # addresses may be fetched (see netfetch). An operator who mirrors
+        # from LAN peers can pass True or a list of exempt hosts.
+        self.allow_private_mirror: Any = allow_private_mirror
+
+    def handle_request(self, conn: socket.socket, req: ws.PlainHTTP) -> bool:
+        """Route PlainHTTP request to appropriate Blossom handler.
+
+        Returns True if request was handled, False if not a Blossom path.
+        """
+        path = req.path.split('?', 1)[0].rstrip('/')
+        method = req.method.upper()
+
+        # CORS preflight
+        if method == 'OPTIONS':
+            ws.http_response(conn, '204 No Content', b'')
+            return True
+
+        # 1. /upload
+        if path == '/upload' and method == 'PUT':
+            self._handle_upload(conn, req)
+            return True
+
+        # 2. /mirror
+        if path == '/mirror' and method == 'PUT':
+            self._handle_mirror(conn, req)
+            return True
+
+        # 2b. /sidecar-session/<name>/<subject>: not a Blossom path, but the
+        # same quote/settle machinery - Caddy's forward_auth calls this in
+        # front of a sidecar whose manifest says pricing.mode == session to
+        # gate the whole session (a git clone/fetch) the way Blossom gates a
+        # blob fetch. 200 = proceed (free, partner, or paid); 402 = quote,
+        # same body shape as a blob 402. /grasp-session/<subject> is the
+        # older spelling of /sidecar-session/grasp/<subject>. See
+        # docs/sidecars.md and PaidFetch.quote_session.
+        session = None
+        if path.startswith('/sidecar-session/') and method in ('GET', 'HEAD'):
+            rest = path[len('/sidecar-session/'):]
+            if '/' in rest:
+                name, subject = rest.split('/', 1)
+                if name and subject:
+                    session = '%s:%s' % (name, subject)
+        elif path.startswith('/grasp-session/') and method in ('GET', 'HEAD'):
+            subject = path[len('/grasp-session/'):]
+            if subject:
+                session = 'grasp:' + subject
+        if session is not None:
+            if self.pricing is not None:
+                self._handle_sidecar_session(conn, req, session)
+            else:
+                ws.http_response(conn, '200 OK', b'')
+            return True
+
+        # 3. /list/<pubkey>
+        if path.startswith('/list/') and method == 'GET':
+            pubkey = path[len('/list/'):]
+            self._handle_list(conn, pubkey)
+            return True
+
+        # 4. /cid/<cid>
+        if path.startswith('/cid/'):
+            cid = path[len('/cid/'):]
+            try:
+                sha256_hex = blobstore.cid_to_sha256(cid)
+            except Exception:
+                ws.http_response(conn, '400 Bad Request', b'{"error":"invalid CID"}')
+                return True
+            if self._dispatch_blob(conn, req, method, sha256_hex):
+                return True
+
+        # 5. /<npub>/<sha256>[.<ext>]: a fetch that names the account whose
+        # upload it is, so that account's fee (if the operator allows one)
+        # applies. The blob is the same blob; only the price differs.
+        parts = path.lstrip('/').split('/')
+        if len(parts) == 2 and method in ('GET', 'HEAD'):
+            account = _account_of(parts[0])
+            digest = parts[1].split('.', 1)[0].lower()
+            if account and HEX64_RE.match(digest):
+                if self._dispatch_blob(conn, req, method, digest, account=account):
+                    return True
+
+        # 6. /<cid> or /<sha256>[.<ext>]
+        clean_path = path.lstrip('/')
+        if '.' in clean_path:
+            clean_path = clean_path.split('.', 1)[0]
+
+        if clean_path.startswith('bafkrei') or (clean_path.startswith('b') and len(clean_path) >= 50):
+            cid_hex: Optional[str]
+            try:
+                cid_hex = blobstore.cid_to_sha256(clean_path)
+            except Exception:
+                # Not a decodable CID; it may still be a bare hex digest below.
+                cid_hex = None
+            if cid_hex is not None and self._dispatch_blob(conn, req, method, cid_hex):
+                return True
+
+        if HEX64_RE.match(clean_path.lower()):
+            if self._dispatch_blob(conn, req, method, clean_path.lower()):
+                return True
+
+        return False
+
+    def _dispatch_blob(self, conn: socket.socket, req: ws.PlainHTTP, method: str, sha256_hex: str,
+                       account: Optional[str] = None) -> bool:
+        """Route a blob-addressed request by HTTP method (BUD-01/02).
+
+        Returns False for a method Blossom does not define on a blob so the
+        caller can fall through to its own 404/405 handling.
+        """
+        match method:
+            case 'GET':
+                self._serve_blob(conn, sha256_hex, req=req, account=account)
+            case 'HEAD':
+                self._head_blob(conn, sha256_hex, req=req, account=account)
+            case 'DELETE':
+                self._handle_delete(conn, req, sha256_hex)
+            case _:
+                return False
+        return True
+
+    def _handle_sidecar_session(self, conn: socket.socket, req: ws.PlainHTTP, session: str) -> None:
+        """Answer Caddy's forward_auth check in front of a session-priced
+        sidecar: 200 to let the session through, 402 (same body shape as a
+        blob fetch) with a quote to pay. `session` is `<name>:<subject>`,
+        the subject being whatever Caddy is told to pass - a repo identifier
+        is enough; coarse, one quote per session, not per object (see
+        docs/sidecars.md)."""
+        assert self.pricing is not None
+        quote = self.pricing.quote_session(session, self._fetcher(req))
+        if quote is None:
+            ws.http_response(conn, '200 OK', b'')
+            return
+        tokens = _cashu_tokens(req)
+        if not tokens:
+            self._payment_required(conn, quote)
+            return
+        res = self.pricing.settle(quote, tokens)
+        if not hasattr(res, 'amount_msat'):
+            self._payment_required(conn, quote, why=res.reason)
+            return
+        ws.http_response(conn, '200 OK', b'', headers=self._price_headers(quote))
+
+    def _verify_auth(self, req: ws.PlainHTTP, action: str, expected_sha256: Optional[str] = None) -> Optional[str]:
+        """Verify Kind 24242 authorization event. Returns uploader pubkey."""
+        auth_hdr = req.headers.get(b'authorization', b'').decode('latin1')
+        if not auth_hdr:
+            if not self.require_auth:
+                return None
+            raise ValueError('Authorization required')
+
+        ev = parse_auth_header(auth_hdr)
+        if not ev:
+            raise ValueError('invalid Nostr Authorization header')
+        try:
+            return blossom_auth.check_auth(ev, action, int(self.clock()), expected_sha256)
+        except blossom_auth.AuthError as e:
+            raise ValueError(str(e)) from e
+
+    @staticmethod
+    def _auth_x_tag(req: ws.PlainHTTP) -> Optional[str]:
+        """Return the lowercase ``x`` (sha256) tag of the request's auth event, if any.
+
+        Used by /mirror, which must know the digest the client committed to
+        *before* it downloads anything, so the auth check cannot depend on
+        the fetched bytes. Signature validity is _verify_auth's job; this
+        only reads the tag from an already-verified header.
+        """
+        auth_hdr = req.headers.get(b'authorization', b'').decode('latin1')
+        if not auth_hdr:
+            return None
+        ev = parse_auth_header(auth_hdr)
+        if not ev or not isinstance(ev, dict):
+            return None
+        for t in ev.get('tags', []):
+            if len(t) >= 2 and t[0] == 'x' and isinstance(t[1], str) and t[1]:
+                return t[1].lower()
+        return None
+
+    # -- paid fetch (plan §3.3, NUT-24) ------------------------------------------
+
+    def _fetcher(self, req: Optional[ws.PlainHTTP]) -> Optional[str]:
+        """Who is fetching, for the partner rule and the free allowance: the
+        signer of a kind 24242 `get` Authorization when one is sent, else None
+        (anonymous, pooled). Never the IP."""
+        if req is None or not req.headers.get(b'authorization'):
+            return None
+        try:
+            return self._verify_auth(req, 'get')
+        except ValueError:
+            return None
+
+    def _quote(self, stat: BlobDescriptor, req: Optional[ws.PlainHTTP], account: Optional[str]) -> Any:
+        if self.pricing is None:
+            return None
+        return self.pricing.quote(stat, self._fetcher(req), account)
+
+    @staticmethod
+    def _price_headers(quote: paidfetch.Quote) -> dict[str, str]:
+        return quote.headers()
+
+    def _payment_required(self, conn: socket.socket, quote: Any, why: Optional[str] = None) -> None:
+        body = quote.body(why)
+        ws.http_response(conn, '402 Payment Required', json.dumps(body).encode(), 'application/json',
+                         headers=self._price_headers(quote))
+
+    def _serve_blob(self, conn: socket.socket, sha256_hex: str, req: Optional[ws.PlainHTTP] = None,
+                    account: Optional[str] = None) -> None:
+        stat = self.store.stat(sha256_hex)
+        if stat is None:
+            ws.http_response(conn, '404 Not Found', b'{"error":"blob not found"}')
+            return
+        quote = self._quote(stat, req, account)
+        if quote is not None and self.pricing is not None:
+            tokens = _cashu_tokens(req)
+            if not tokens:
+                self._payment_required(conn, quote)
+                return
+            res = self.pricing.settle(quote, tokens)
+            if not hasattr(res, 'amount_msat'):
+                self._payment_required(conn, quote, why=res.reason)
+                return
+        data = self.store.get(sha256_hex)
+        if data is None:
+            ws.http_response(conn, '404 Not Found', b'{"error":"blob not found"}')
+            return
+        if self.pricing is not None:
+            self.pricing.note_served(self._fetcher(req), len(data))
+
+        ctype = stat.get('type') or 'application/octet-stream'
+        cid = stat.get('cid') or blobstore.sha256_to_cid(sha256_hex)
+        headers = {
+            'X-SHA-256': sha256_hex,
+            'X-CID': cid,
+            'ETag': f'"{sha256_hex}"',
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        }
+        ws.http_response(conn, '200 OK', data, ctype, headers=headers)
+
+    def _head_blob(self, conn: socket.socket, sha256_hex: str, req: Optional[ws.PlainHTTP] = None,
+                   account: Optional[str] = None) -> None:
+        stat = self.store.stat(sha256_hex)
+        if stat is None:
+            ws.http_response(conn, '404 Not Found', b'')
+            return
+
+        cid = stat.get('cid') or blobstore.sha256_to_cid(sha256_hex)
+        headers = {
+            'X-SHA-256': sha256_hex,
+            'X-CID': cid,
+            'Content-Length': str(stat['size']),
+            'ETag': f'"{sha256_hex}"',
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        }
+        # HEAD prices without transferring: 200 with the price and the
+        # payment request, so a client learns the cost the cheap way. It is
+        # a 200 because the blob exists and nothing was refused.
+        quote = self._quote(stat, req, account)
+        if quote is not None:
+            headers.update(self._price_headers(quote))
+            headers['Cache-Control'] = 'no-store'
+        ws.http_response(conn, '200 OK', b'', stat.get('type', 'application/octet-stream'), headers=headers)
+
+    def _handle_upload(self, conn: socket.socket, req: ws.PlainHTTP) -> None:
+        try:
+            body = ws.read_body(conn, req, max_bytes=self.max_upload_bytes)
+        except Exception as e:
+            ws.http_response(conn, '413 Payload Too Large', json.dumps({'error': str(e)}).encode())
+            return
+
+        if not body:
+            ws.http_response(conn, '400 Bad Request', b'{"error":"empty upload body"}')
+            return
+
+        actual_sha256 = hashlib.sha256(body).hexdigest().lower()
+
+        try:
+            uploader = self._verify_auth(req, 'upload', expected_sha256=actual_sha256)
+        except ValueError as e:
+            ws.http_response(conn, '401 Unauthorized', json.dumps({'error': str(e)}).encode())
+            return
+
+        ctype = req.headers.get(b'content-type', b'application/octet-stream').decode('latin1').split(';')[0].strip()
+        descriptor = self.store.put(body, content_type=ctype, uploaded_by=uploader, now=self.clock())
+
+        resp_body = json.dumps({
+            'url': f"/{descriptor['sha256']}",
+            'sha256': descriptor['sha256'],
+            'size': descriptor['size'],
+            'type': descriptor['type'],
+            'uploaded': descriptor['uploaded'],
+            'cid': descriptor['cid'],
+        }).encode('utf-8')
+        ws.http_response(conn, '200 OK', resp_body, 'application/json', headers={'X-CID': descriptor['cid']})
+
+    def _handle_mirror(self, conn: socket.socket, req: ws.PlainHTTP) -> None:
+        """BUD-04 HTTP Mirroring.
+
+        Order matters: the authorization event is verified *before* anything
+        is fetched. The previous order (fetch, then check auth) let anyone
+        with no credentials at all use the node as a free HTTP proxy -- and
+        an SSRF probe, since the URL was theirs. Now an unauthenticated
+        request costs the node nothing but a signature check, and the fetch
+        is bounded by netfetch's address policy and the upload cap. The
+        digest the auth event commits to (its ``x`` tag) is then compared
+        to what was actually downloaded.
+        """
+        try:
+            body = ws.read_body(conn, req, max_bytes=65536)
+            data = json.loads(body.decode('utf-8'))
+            source_url = data.get('url')
+            if not source_url:
+                raise ValueError("missing 'url' in mirror body")
+        except Exception as e:
+            ws.http_response(conn, '400 Bad Request', json.dumps({'error': str(e)}).encode())
+            return
+
+        # 1. Authorization first. The x tag names the digest the client
+        #    expects; we hold it and compare after the download.
+        try:
+            uploader = self._verify_auth(req, 'mirror')
+        except ValueError as e:
+            ws.http_response(conn, '401 Unauthorized', json.dumps({'error': str(e)}).encode())
+            return
+        expected_sha256 = self._auth_x_tag(req)
+        if self.require_auth and not expected_sha256:
+            ws.http_response(conn, '401 Unauthorized', b'{"error":"Authorization event must name the blob sha256 in an x tag"}')
+            return
+
+        # 2. Fetch, bounded. The 502 body is deliberately generic: echoing
+        #    the fetch error would tell a caller which internal hosts answer
+        #    and which do not, which is exactly what an SSRF probe wants.
+        try:
+            remote_data, remote_headers = netfetch.fetch(
+                str(source_url),
+                max_bytes=self.max_upload_bytes,
+                timeout=10.0,
+                allow_private=self.allow_private_mirror,
+                headers={'User-Agent': 'fleetmesh-blossom/1.0'},
+            )
+        except netfetch.FetchTooLarge:
+            ws.http_response(conn, '413 Payload Too Large', b'{"error":"remote payload too large"}')
+            return
+        except netfetch.FetchError:
+            ws.http_response(conn, '502 Bad Gateway', b'{"error":"failed to fetch remote blob"}')
+            return
+        remote_ctype = (remote_headers.get('Content-Type') or 'application/octet-stream').split(';', 1)[0].strip()
+
+        # 3. Re-check the digest against what the auth event committed to.
+        actual_sha256 = hashlib.sha256(remote_data).hexdigest().lower()
+        if expected_sha256 and expected_sha256 != actual_sha256:
+            ws.http_response(conn, '401 Unauthorized', json.dumps({
+                'error': f"Authorization hash mismatch: expected {expected_sha256[:16]}, got {actual_sha256[:16]}",
+            }).encode())
+            return
+
+        descriptor = self.store.put(remote_data, content_type=remote_ctype, uploaded_by=uploader, now=self.clock())
+        resp_body = json.dumps({
+            'url': f"/{descriptor['sha256']}",
+            'sha256': descriptor['sha256'],
+            'size': descriptor['size'],
+            'type': descriptor['type'],
+            'uploaded': descriptor['uploaded'],
+            'cid': descriptor['cid'],
+        }).encode('utf-8')
+        ws.http_response(conn, '200 OK', resp_body, 'application/json', headers={'X-CID': descriptor['cid']})
+
+    def _handle_list(self, conn: socket.socket, pubkey: str) -> None:
+        pk = pubkey.strip().lower()
+        if not HEX64_RE.match(pk):
+            ws.http_response(conn, '400 Bad Request', b'{"error":"invalid pubkey"}')
+            return
+
+        items = self.store.list_by(uploaded_by=pk)
+        ws.http_response(conn, '200 OK', json.dumps(items).encode('utf-8'), 'application/json')
+
+    def _handle_delete(self, conn: socket.socket, req: ws.PlainHTTP, sha256_hex: str) -> None:
+        stat = self.store.stat(sha256_hex)
+        if stat is None:
+            ws.http_response(conn, '404 Not Found', b'{"error":"blob not found"}')
+            return
+
+        try:
+            signer_pk = self._verify_auth(req, 'delete', expected_sha256=sha256_hex)
+        except ValueError as e:
+            ws.http_response(conn, '401 Unauthorized', json.dumps({'error': str(e)}).encode())
+            return
+
+        # Check permissions: must be uploader or operator
+        if stat.get('uploaded_by') and signer_pk != stat.get('uploaded_by'):
+            if signer_pk != self.operator_pk and signer_pk != self.node_pk:
+                ws.http_response(conn, '403 Forbidden', b'{"error":"only original uploader or operator may delete"}')
+                return
+
+        self.store.delete(sha256_hex)
+        ws.http_response(conn, '200 OK', b'{"status":"deleted"}')
+
+
+class BlossomClient:
+    """Standard-library HTTP client for Blossom servers."""
+
+    # Peer server URLs reach the client two ways: operator config (partner
+    # servers) and the ``blossom_servers`` list inside a compute job payload,
+    # which the *requester* wrote. The second path is why every method below
+    # goes through netfetch with the public-address policy by default and a
+    # mandatory size cap; callers that know the server is a LAN peer opt in
+    # with ``allow_private``.
+    DEFAULT_MAX_BYTES: int = 64 * 1024 * 1024
+
+    @staticmethod
+    def get_blob(
+        server_url: str,
+        sha256_hex: str,
+        timeout: float = 10.0,
+        *,
+        max_bytes: Optional[int] = None,
+        allow_private: Any = False,
+    ) -> bytes:
+        """Download and verify blob from Blossom server.
+
+        ``max_bytes`` caps the body (default DEFAULT_MAX_BYTES); a server that
+        sends more raises netfetch.FetchTooLarge rather than filling memory.
+        """
+        base = server_url.rstrip('/')
+        url = f"{base}/{sha256_hex.lower()}"
+        data, _ = netfetch.fetch(
+            url,
+            max_bytes=int(max_bytes if max_bytes is not None else BlossomClient.DEFAULT_MAX_BYTES),
+            timeout=timeout,
+            allow_private=allow_private,
+            headers={'Accept': '*/*'},
+        )
+        if hashlib.sha256(data).hexdigest().lower() != sha256_hex.lower():
+            raise ValueError("downloaded blob SHA-256 hash mismatch")
+        return data
+
+    @staticmethod
+    def head_blob(
+        server_url: str,
+        sha256_hex: str,
+        timeout: float = 5.0,
+        *,
+        allow_private: Any = False,
+    ) -> Optional[BlossomBlobMetadata]:
+        """Query blob metadata via HEAD request."""
+        base = server_url.rstrip('/')
+        url = f"{base}/{sha256_hex.lower()}"
+        try:
+            _, hdrs = netfetch.fetch(url, max_bytes=0, timeout=timeout, method='HEAD',
+                                     allow_private=allow_private)
+        except netfetch.FetchHTTPError as e:
+            if e.code == 404:
+                return None
+            raise
+        # HEAD legitimately declares the size without a body, so read the
+        # header ourselves rather than letting netfetch's Content-Length
+        # pre-check (which assumes a body follows) refuse it.
+        return {
+            'sha256': sha256_hex.lower(),
+            'size': int(hdrs.get('Content-Length', 0) or 0),
+            'type': hdrs.get('Content-Type', 'application/octet-stream'),
+            'cid': hdrs.get('X-CID'),
+        }
+
+    @staticmethod
+    def upload_blob(
+        server_url: str,
+        data: bytes,
+        content_type: str = 'application/octet-stream',
+        signer_sk: Optional[str] = None,
+        timeout: float = 30.0,
+        *,
+        allow_private: Any = False,
+    ) -> BlossomUploadDescriptor:
+        """Upload blob to Blossom server (BUD-01)."""
+        base = server_url.rstrip('/')
+        url = f"{base}/upload"
+        h = hashlib.sha256(data).hexdigest().lower()
+        headers = {'Content-Type': content_type}
+
+        if signer_sk:
+            ev = create_auth_event(signer_sk, 'upload', h)
+            headers['Authorization'] = auth_header(ev)
+
+        res_body, _ = netfetch.fetch(url, max_bytes=1 << 20, timeout=timeout, method='PUT',
+                                     data=data, headers=headers, allow_private=allow_private)
+        return json.loads(res_body.decode('utf-8'))
+
+    @staticmethod
+    def mirror_blob(
+        server_url: str,
+        source_url: str,
+        sha256_hex: str,
+        signer_sk: Optional[str] = None,
+        timeout: float = 30.0,
+        *,
+        allow_private: Any = False,
+    ) -> BlossomMirrorDescriptor:
+        """Mirror remote blob to Blossom server (BUD-04)."""
+        base = server_url.rstrip('/')
+        url = f"{base}/mirror"
+        h = sha256_hex.lower()
+        headers = {'Content-Type': 'application/json'}
+
+        if signer_sk:
+            ev = create_auth_event(signer_sk, 'mirror', h)
+            headers['Authorization'] = auth_header(ev)
+
+        req_body = json.dumps({'url': source_url}).encode('utf-8')
+        res_body, _ = netfetch.fetch(url, max_bytes=1 << 20, timeout=timeout, method='PUT',
+                                     data=req_body, headers=headers, allow_private=allow_private)
+        return json.loads(res_body.decode('utf-8'))