fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/nsite/compartment.py

@@ -0,0 +1,752 @@
+"""nsite: the node as a NIP-5A static-site host, reachable from the plain web.
+
+Two kinds of hostname reach a site here:
+
+  npub1….<suffix>   v<snapshot>.<suffix>   <base36 pubkey><d>.<suffix>
+      the NIP's own grammar under each configured `suffixes` entry;
+  www.example.com
+      a CUSTOM DOMAIN the owner pointed here: a CNAME (or A) to the gateway
+      plus a TXT at `_nsite.example.com` naming the site. With
+      `require_domain_tag` (the default) the site's manifest must also carry
+      `["domain", "example.com"]`, so a DNS record someone else controls
+      cannot put a well-known pubkey's site behind a look-alike name.
+
+The compartment holds no site state of its own beyond two small sqlite
+tables (manifest cache, domain bindings) in the node's blob store database
+directory. Blobs it fetches are verified against their sha256 and kept in the
+node's BlobStore, which makes this node a Blossom mirror for every site it
+serves; the store's own LRU quota bounds that, with a per-site cap on top.
+
+Anything the outside world gets wrong - unknown label, no manifest, hash
+mismatch, blob too big, unbound domain - is a refusal: counted, kept with
+detail, and answered to the browser with a short status. Only our own bugs
+are errors.
+
+TLS for custom domains is not this process's job. The Ansible role's Caddy
+asks `GET /nsite/_ask?domain=` before issuing a certificate; 200 means the
+domain is verified here, anything else means Caddy must not. See
+ops/roles/meshnode/templates/Caddyfile.j2.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import urllib.parse
+from typing import cast, Any, Callable, Mapping, Optional, Sequence
+
+from node import compartment
+from node.protocols.nostr import blossom
+from node.transport import ws
+from node import channels as ch_mod
+from node import metrics as mx_mod
+from node.compartment import stores as st
+from node.compartment import Command, Compartment, Need
+from node.compartment.schema import Column, Table
+from node.config.parameter import Parameter
+from node.storage import SqliteStore
+from node.transport import dnstxt, netfetch
+from fleetmesh_core.services import nsite as nr
+from fleetmesh_core.wire.interfaces import NostrEvent
+from node.config.compartments import NsiteConfig
+
+
+from .types import (
+    DomainBinding,
+    NsiteState,
+    PublishResult,
+)
+
+
+try:
+    from fleetmesh_core.crypto.giftwrap import verify_event
+except Exception:  # pragma: no cover - giftwrap is part of the tree
+    def verify_event(ev: Mapping[str, Any]) -> bool:
+        return True
+
+log = logging.getLogger(__name__)
+
+SECURITY_HEADERS: dict[str, str] = {
+    # Third-party HTML on our origin's subdomains: keep it inside its own
+    # document, keep sniffing off, keep it out of frames elsewhere.
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'SAMEORIGIN',
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), gamepad=(self), fullscreen=(self), autoplay=(self)',
+}
+
+_SCHEMA = (
+    Table('nsite_manifest', (
+        Column('site_key', 'TEXT', primary_key=True),
+        Column('event_id', 'TEXT', not_null=True),
+        Column('json', 'TEXT', not_null=True),
+        Column('aggregate', 'TEXT', not_null=True),
+        Column('fetched_at', 'INTEGER', not_null=True),
+    )),
+    Table('nsite_domain', (
+        Column('domain', 'TEXT', primary_key=True),
+        Column('site_key', 'TEXT'),
+        Column('status', 'TEXT', not_null=True),
+        Column('why', 'TEXT'),
+        Column('checked_at', 'INTEGER', not_null=True),
+    )),
+    Table('nsite_site_bytes', (
+        Column('site_key', 'TEXT', not_null=True),
+        Column('sha256', 'TEXT', not_null=True),
+        Column('size', 'INTEGER', not_null=True),
+    ), primary_key=('site_key', 'sha256')),
+)
+
+
+def site_key(ref: nr.SiteRef) -> str:
+    if ref.kind == nr.KIND_SNAPSHOT:
+        return 'v:%s' % ref.event_id
+    if ref.kind == nr.KIND_NAMED:
+        return 'n:%s:%s' % (ref.pubkey, ref.d)
+    return 'r:%s' % ref.pubkey
+
+
+def ref_from_key(key: str) -> nr.SiteRef:
+    kind, _, rest = key.partition(':')
+    if kind == 'v':
+        return nr.SiteRef(nr.KIND_SNAPSHOT, event_id=rest)
+    if kind == 'n':
+        pk, _, d = rest.partition(':')
+        return nr.SiteRef(nr.KIND_NAMED, pubkey=pk, d=d)
+    return nr.SiteRef(nr.KIND_ROOT, pubkey=rest)
+
+
+class NsiteStore(SqliteStore):
+    """The three tables: resolved manifests, domain bindings, cached bytes.
+
+    On `BaseSqliteStore` like every other store in the node. It was not, until
+    storage step 4 asked what still imported sqlite3 and found this one keeping
+    its own connection - the subclass census had counted classes on the base,
+    not connections, so it was invisible. Being on the base is what lets a
+    second dialect reach it (docs/storage-backends.md).
+    """
+
+    SCHEMA = _SCHEMA
+
+    def manifest(self, key: str) -> Optional[tuple[NostrEvent, int]]:
+        r = self._one('SELECT json, fetched_at FROM nsite_manifest WHERE site_key=?', (key,))
+        return (json.loads(r[0]), int(r[1])) if r else None
+
+    def remember_manifest(self, key: str, ev: Mapping[str, Any], now: int) -> None:
+        self.execute('INSERT OR REPLACE INTO nsite_manifest VALUES (?,?,?,?,?)',
+                     (key, ev['id'], json.dumps(ev, separators=(',', ':')), nr.aggregate(ev), now))
+        self.commit()
+
+    def forget_manifest(self, key: str) -> None:
+        self.execute('DELETE FROM nsite_manifest WHERE site_key=?', (key,))
+        self.commit()
+
+    def domain(self, domain: str) -> Optional[DomainBinding]:
+        r = self._one('SELECT site_key, status, why, checked_at FROM nsite_domain WHERE domain=?',
+                      (domain,))
+        return {'domain': domain, 'site_key': r[0], 'status': r[1], 'why': r[2],
+                'checked_at': int(r[3])} if r else None
+
+    def set_domain(self, domain: str, key: Optional[str], status: str, why: Optional[str], now: int) -> None:
+        self.execute('INSERT OR REPLACE INTO nsite_domain VALUES (?,?,?,?,?)',
+                     (domain, key, status, why, now))
+        self.commit()
+
+    def drop_domain(self, domain: str) -> bool:
+        with self._lock:
+            n = self.execute('DELETE FROM nsite_domain WHERE domain=?', (domain,)).rowcount
+            self.commit()
+        return n > 0
+
+    def domains(self) -> list[DomainBinding]:
+        rows = self._all('SELECT domain, site_key, status, why, checked_at '
+                         'FROM nsite_domain ORDER BY domain')
+        return [{'domain': r[0], 'site_key': r[1], 'status': r[2], 'why': r[3],
+                 'checked_at': int(r[4])} for r in rows]
+
+    def note_bytes(self, key: str, sha: str, size: int) -> None:
+        self.execute('INSERT OR IGNORE INTO nsite_site_bytes VALUES (?,?,?)', (key, sha, size))
+        self.commit()
+
+    def site_bytes(self, key: str) -> int:
+        r = self._one('SELECT COALESCE(SUM(size),0) FROM nsite_site_bytes WHERE site_key=?', (key,))
+        return int(r[0]) if r else 0
+
+    def totals(self) -> dict[str, int]:
+        with self._lock:
+            m = self._one('SELECT COUNT(*) FROM nsite_manifest')
+            d = self._one("SELECT COUNT(*) FROM nsite_domain WHERE status='verified'")
+            b = self._one('SELECT COALESCE(SUM(size),0) FROM nsite_site_bytes')
+        return {'manifests_cached': int(m[0] if m else 0),
+                'domains_verified': int(d[0] if d else 0),
+                'cached_bytes': int(b[0] if b else 0)}
+
+
+class NsiteGateway(Compartment):
+    """The compartment. Mounted on the relay face's HTTP fallthrough."""
+
+    name: str = 'nsite'
+    optional: bool = True
+    enabled_by: Optional[str] = 'nsite'
+    requires: tuple[str, ...] = ()
+    uses: tuple[str, ...] = ('bridge',)
+    reads: tuple[str, ...] = ('nsite', 'relays')
+    live: tuple[str, ...] = ('nsite',)
+    config_cls = NsiteConfig
+    SCHEMA = _SCHEMA
+    STORE_CLS = NsiteStore      # builds its own; the base opens nothing for it (B5)
+    STORES = (
+        st.Store(key='recent_requests', description='recent HTTP requests served, newest last',
+                 kind=st.RING, shape=tuple, bound=128),
+    )
+    recent_requests: st.Ring[tuple[Any, ...]]
+
+    CHANNELS = (
+        ch_mod.Channel('site_served', 'A static site resource was served to an HTTP client',
+                       level=ch_mod.INFO, say='served {path} for site {site_key} ({bytes_sent} bytes)',
+                       tags=('nsite', 'http')),
+        ch_mod.Channel('site_published', 'A NIP-5A nsite manifest was signed and published',
+                       level=ch_mod.INFO, say='published nsite manifest {event_id} for site {site}',
+                       tags=('nsite', 'publish')),
+        ch_mod.Channel('domain_verified', 'A custom domain was verified via DNS TXT and site manifest',
+                       level=ch_mod.INFO, say='verified custom domain {domain} -> {site_key}',
+                       tags=('nsite', 'dns')),
+        ch_mod.Channel('domain_refused', 'A custom domain verification was refused',
+                       level=ch_mod.TROUBLE, say='refused custom domain {domain}: {why}',
+                       tags=('nsite', 'dns')),
+    )
+    METRICS = (
+        mx_mod.Metric(name='nsite_requests_served', description='Static site HTTP requests served.',
+                      kind=mx_mod.COUNTER, counts='site_served', tags=('nsite', 'http')),
+        mx_mod.Metric(name='nsite_sites_published', description='Static sites published.',
+                      kind=mx_mod.COUNTER, counts='site_published', tags=('nsite', 'publish')),
+        mx_mod.Metric(name='nsite_domains_verified', description='Custom domains verified.',
+                      kind=mx_mod.COUNTER, counts='domain_verified', tags=('nsite', 'dns')),
+        mx_mod.Metric(name='nsite_domains_refused', description='Custom domain verification failures.',
+                      kind=mx_mod.COUNTER, counts='domain_refused', tags=('nsite', 'dns')),
+    )
+    NEEDS = (
+        Need('events', 'stores.events'),
+        Need('blobs', 'stores.blobs'),
+        Need('cfg', block=NsiteConfig),
+        Need('relays'),
+        Need('db_path', path='nsite.db'),
+        Need('bridge'),
+        Need('ks'),
+        Need('face'),
+    )
+    COMMANDS = (
+        Command(
+            key='domains',
+            name='Custom Domains',
+            description='list custom-domain bindings and their state',
+            tags=('nsite', 'domains'),
+            permission='nsite/domains',
+            run='domains_cmd',
+            reply='domains',
+        ),
+        Command(
+            key='sites',
+            name='Sites Summary',
+            description='cached manifests, verified domains and bytes',
+            tags=('nsite', 'sites'),
+            permission='nsite/sites',
+            run='sites_cmd',
+            reply='totals',
+        ),
+        Command(
+            key='verify',
+            name='Verify Domain',
+            description='re-check one custom domain now',
+            tags=('nsite', 'verify'),
+            parameters=(
+                Parameter(key='domain', name='domain', description='domain to verify', type=str, default='', required=True),
+            ),
+            permission='nsite/verify',
+            run='verify_cmd',
+            reply='binding',
+        ),
+        Command(
+            key='forget',
+            name='Forget Domain',
+            description='drop a binding; it is re-resolved on the next request',
+            tags=('nsite', 'forget'),
+            parameters=(
+                Parameter(key='domain', name='domain', description='domain binding to drop', type=str, default='', required=True),
+            ),
+            permission='nsite/forget',
+            run='forget_cmd',
+            reply='dropped',
+        ),
+        Command(
+            key='publish',
+            name='Publish Site',
+            description="sign this node's own site manifest from blobs already uploaded and publish it",
+            tags=('nsite', 'publish'),
+            parameters=(
+                Parameter(key='paths', name='paths', description='mapping of paths to sha256', type=dict, default=dict, required=True, cli=False),
+                Parameter(key='site', name='site', description='d tag (named site)', type=str, default=None, required=False),
+                Parameter(key='snapshot', name='snapshot', description='also publish immutable kind-5128 copy', type=bool, default=None, required=False),
+                Parameter(key='domains', name='domains', description='domains claimed for custom-domain proof', type=list, default=None, required=False, cli_name='--domain-claim'),
+                Parameter(key='servers', name='servers', description='Blossom URLs the blobs are on', type=list, default=None, required=False, cli_name='--server'),
+                Parameter(key='title', name='title', description='site title', type=str, default=None, required=False),
+            ),
+            permission='nsite/publish',
+            run='publish_cmd',
+            reply='manifest (+ snapshot) event ids and the site labels',
+        ),
+    )
+
+    def __init__(self, events: Any, blobs: Any, cfg: Optional[NsiteConfig] = None,
+                 relays: Sequence[str] = (), store: Optional[NsiteStore] = None,
+                 bridge: Optional[Any] = None, clock: Optional[Callable[[], int]] = None,
+                 node: Optional[Any] = None,
+                 query_relays: Optional[Callable[[Sequence[str], Sequence[Mapping[str, Any]]], list[NostrEvent]]] = None,
+                 fetch_blob: Optional[Callable[[str, str, int], bytes]] = None,
+                 lookup_txt: Optional[Callable[[str], list[str]]] = None,
+                 ks: Optional[Any] = None, face: Optional[Any] = None,
+                 blossom_url: Optional[str] = None,
+                 db_path: Optional[str] = None) -> None:
+        super().__init__(node, clock)
+        # The keystore a manifest is signed with, the face whose HTTP side
+        # serves the site (and doubles as the Blossom server when the node
+        # has no separate one). A fake node in a suite supplies the same.
+        self.ks: Optional[Any] = ks if ks is not None else getattr(node, 'ks', None)
+        self.face: Optional[Any] = face if face is not None else getattr(node, 'face', None)
+        self.blossom_url: Optional[str] = blossom_url if blossom_url is not None else getattr(node, 'blossom_url', None)
+        self.events = events
+        self.blobs = blobs
+        self.cfg: NsiteConfig = cfg or NsiteConfig()
+        self.relays: tuple[str, ...] = tuple(self.cfg.relays or relays)
+        if store is not None:
+            self.store = store
+        elif db_path:
+            self.store = NsiteStore(db_path)
+        else:
+            self.store = NsiteStore()
+        self.bridge = bridge
+        self._query = query_relays or self._query_relays
+        self._fetch = fetch_blob or self._fetch_blob
+        self._txt = lookup_txt or (lambda name: dnstxt.lookup_txt(name, timeout=self.cfg.fetch_timeout))
+        self.served: int = 0
+        self.bytes_served: int = 0
+
+    # ---- lifecycle ----------------------------------------------------------
+    def start(self) -> None:
+        if self.face is not None and hasattr(self.face, 'http_handlers'):
+            self.face.http_handlers.append(self.handle_request)
+
+    def stop(self) -> None:
+        try:
+            self.store.close()
+        except Exception:
+            pass
+        super().stop()
+
+    def state(self) -> NsiteState:
+        return self.snapshot_state()
+
+    def snapshot_state(self) -> NsiteState:
+        t = self.store.totals()
+        return {'manifests_cached': t['manifests_cached'], 'domains_verified': t['domains_verified'],
+                'cached_bytes': t['cached_bytes'], 'served': self.served, 'bytes_served': self.bytes_served,
+                'suffixes': list(self.cfg.suffixes), 'custom_domains': self.cfg.custom_domains,
+                'require_domain_tag': self.cfg.require_domain_tag, 'closed': bool(self.cfg.allow_domains)}
+
+    def trouble(self) -> list[str]:
+        out: list[str] = []
+        now = self.clock()
+        bad = self.refusals.within(self.TROUBLE_WINDOW, now, kind='blob', why='hash mismatch')
+        if bad:
+            out.append('nsite: %d blobs failed their hash in the last %ds - an upstream Blossom server is lying'
+                       % (len(bad), self.TROUBLE_WINDOW))
+        return out
+
+    # ---- commands (control socket) -----------------------------------------
+    def domains_cmd(self) -> Mapping[str, Any]:
+        return {'domains': self.store.domains()}
+
+    def sites_cmd(self) -> Mapping[str, Any]:
+        return self.store.totals()
+
+    def verify_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        domain = nr.normalize_domain(str(args.get('domain', '')))
+        if not domain:
+            raise ValueError('domain required')
+        return {'binding': self.bind_domain(domain, force=True)}
+
+    def forget_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        domain = nr.normalize_domain(str(args.get('domain', '')))
+        if not domain:
+            raise ValueError('domain required')
+        return {'dropped': self.store.drop_domain(domain)}
+
+    def publish_cmd(self, args: Mapping[str, Any]) -> PublishResult:
+        return self.publish(args)
+
+    def publish(self, args: Mapping[str, Any]) -> PublishResult:
+        """The node's own site: a manifest signed with the node key.
+
+        The blobs are already on a Blossom server (the CLI PUTs them to this
+        node's face before asking) - the control socket carries hashes, never
+        file bodies. Every path must be absolute and every hash 64 hex chars;
+        the blobs this node holds are checked to exist so a typo in a hash
+        cannot publish a site with holes in it.
+        """
+        sk = getattr(self.ks, 'node_sk', None)
+        if not sk:
+            raise ValueError('this node has no signing key for the manifest')
+        paths = args.get('paths')
+        if not isinstance(paths, Mapping) or not paths:
+            raise ValueError('paths must be a non-empty {path: sha256} object')
+        tags: list[list[str]] = []
+        missing: list[str] = []
+        for pth, h in sorted(paths.items()):
+            if not isinstance(pth, str) or not pth.startswith('/') or not isinstance(h, str) or not nr._RE_SHA.match(h.lower()):
+                raise ValueError('bad path entry %r' % (pth,))
+            if not self.blobs.has(h.lower()):
+                missing.append(pth)
+            tags.append(['path', pth, h.lower()])
+        if missing:
+            raise ValueError('blobs not on this node for: %s' % ', '.join(missing[:5]))
+        servers = list(args.get('servers') or [])
+        own = self.blossom_url
+        if not own:
+            face_url = getattr(self.face, 'url', '') or ''
+            if isinstance(face_url, str) and face_url.startswith(('ws://', 'wss://')):
+                own = 'http' + face_url[2:]        # the face is also the Blossom server
+        if own and own not in servers:
+            servers.insert(0, own)
+        for u in servers:
+            tags.append(['server', str(u)])
+        for d in args.get('domains') or []:
+            tags.append(['domain', nr.normalize_domain(str(d))])
+        if args.get('title'):
+            tags.append(['title', str(args['title'])])
+        if args.get('embed'):
+            tags.append(['embed', 'allow'])
+        if args.get('isolation'):
+            tags.append(['isolation', 'coop-coep'])
+        site = args.get('site')
+        kind = nr.KIND_ROOT
+        if site:
+            if not nr._RE_NAMED.match('0' * 50 + str(site)):
+                raise ValueError('site id must be 1-13 of [a-z0-9-]')
+            kind = nr.KIND_NAMED
+            tags.append(['d', str(site)])
+        from fleetmesh_core.storage import store as refstore
+        now = self.clock()
+        ev = refstore.make_signed_event(sk, now, kind, tags, '')
+        tags_x = [t for t in tags if t[0] != 'd'] + [['x', nr.aggregate(ev)]]
+        ev = refstore.make_signed_event(sk, now, kind, tags + [['x', nr.aggregate(ev)]], '')
+        out: PublishResult = {'manifest': ev['id'], 'kind': kind, 'aggregate': nr.aggregate(ev), 'published_to': []}
+        ref = nr.SiteRef(kind, pubkey=ev['pubkey'], d=str(site or ''))
+        out['label'] = ref.label
+        events = [ev]
+        if args.get('snapshot'):
+            snap = refstore.make_signed_event(sk, now, nr.KIND_SNAPSHOT, tags_x, '')
+            out['snapshot'] = snap['id']
+            out['snapshot_label'] = nr.SiteRef(nr.KIND_SNAPSHOT, event_id=snap['id']).label
+            events.append(snap)
+        for e in events:
+            self.events.insert_event(e, now)
+            if self.bridge is not None and hasattr(self.bridge, 'publish'):
+                try:
+                    okp, why = self.bridge.publish(e)
+                    out['published_to'].append({'id': e['id'], 'ok': bool(okp), 'why': why})
+                except Exception as e2:
+                    self.refusals.refuse('publish', 'bridge failed', e['id'], compartment.why_detail(e2))
+        self.store.forget_manifest(site_key(ref))
+        out['hosts'] = ['%s.%s' % (out['label'], s) for s in self.cfg.suffixes]
+        self.say('site_published', event_id=out.get('manifest', ''), site=out.get('label', ''))
+        return out
+
+    # ---- the request ---------------------------------------------------------
+    def handle_request(self, conn: Any, req: Any) -> bool:
+        """The face's hook: True if this was ours (answered), False to let
+        the rest of the face have it."""
+        headers = getattr(req, 'headers', {}) or {}
+        host_b = headers.get(b'host') or headers.get(b'Host') or b''
+        host = host_b.decode('latin-1', errors='replace') if isinstance(host_b, bytes) else str(host_b)
+        method = (getattr(req, 'method', 'GET') or 'GET').upper()
+        path = getattr(req, 'path', '/') or '/'
+
+        if path.startswith('/nsite/_ask'):
+            return self._ask(conn, path)
+
+        if method not in ('GET', 'HEAD'):
+            return False
+        ref = self.route(host)
+        if ref is None:
+            if not self.under_suffix(host):
+                return False
+            self.refusals.refuse('label', 'not a site label', host, {})
+            status, body, ctype, extra = self._refusal_response('404 Not Found', 'no site here')
+        else:
+            status, body, ctype, extra = self.serve(ref, path)
+        if method == 'HEAD':
+            body_out = b''
+        else:
+            body_out = body
+        hdrs = dict(SECURITY_HEADERS)
+        hdrs.update(extra)
+        hdrs = {k: v for k, v in hdrs.items() if v != ''}
+        hdrs.setdefault('Content-Length', str(len(body)))
+        ws.http_response(conn, status, body_out, ctype, hdrs)
+        return True
+
+    def route(self, host: str) -> Optional[nr.SiteRef]:
+        """Host header -> site, or None when the host is not a site here."""
+        ref = nr.parse_host(host, self.cfg.suffixes)
+        if ref is not None:
+            return ref
+        h = nr.normalize_domain(host.rsplit(':', 1)[0] if host.count(':') == 1 else host)
+        if not h or not self.cfg.custom_domains:
+            return None
+        if h in {nr.normalize_domain(x) for x in self.cfg.suffixes}:
+            return None       # the bare suffix is the face itself
+        # A name under the suffix that is not a site label (www.<suffix>,
+        # docs.<suffix>) is the operator's own zone: it may still be bound
+        # like any custom domain, and when it is not, the 404 is ours.
+        b = self.bind_domain(h)
+        key = b.get('site_key')
+        if b.get('status') == 'verified' and key:
+            return ref_from_key(key)
+        return None
+
+    def under_suffix(self, host: str) -> bool:
+        """True for any name under a suffix - the zone this gateway owns,
+        where a host that is neither a site label nor a bound custom domain is
+        still our 404, never the relay's NIP-11 document."""
+        h = nr.normalize_domain(host.rsplit(':', 1)[0] if host.count(':') == 1 else host)
+        for sfx in self.cfg.suffixes:
+            sfx = nr.normalize_domain(sfx)
+            if h.endswith('.' + sfx):
+                return True
+        return False
+
+    def serve(self, ref: nr.SiteRef, path: str) -> tuple[str, bytes, str, dict[str, str]]:
+        """(status line, body, content type, extra headers)."""
+        ev = self.manifest(ref)
+        if ev is None:
+            return self._refusal_response('404 Not Found', 'no site here')
+        resolved = nr.resolve_path(nr.paths_of(ev), path)
+        if resolved is None:
+            self.refusals.refuse('path', 'not in manifest', site_key(ref), {'path': path})
+            return self._refusal_response('404 Not Found', 'not found')
+        data = self.blob(ref, ev, resolved.sha256)
+        if data is None:
+            return self._refusal_response('502 Bad Gateway', 'blob unavailable')
+        self.served += 1
+        self.bytes_served += len(data)
+        status = '200 OK' if resolved.status == 200 else '404 Not Found'
+        self.recent_requests.append((site_key(ref), path, len(data), status))
+        self.say('site_served', path=path, site_key=site_key(ref), bytes_sent=len(data))
+        headers = {
+            'ETag': '"%s"' % resolved.sha256,
+            'X-Nsite-Site': ref.label,
+            'X-Nsite-Version': nr.aggregate(ev),
+        }
+        if ref.kind == nr.KIND_SNAPSHOT:
+            headers['Cache-Control'] = 'public, max-age=31536000, immutable'
+        else:
+            headers['Cache-Control'] = 'public, max-age=%d' % max(60, min(self.cfg.manifest_ttl_seconds, 3600))
+        embed_origins = list(self.cfg.frame_ancestors)
+        for origin in nr.frame_ancestors_of(ev):
+            if origin not in embed_origins:
+                embed_origins.append(origin)
+        if embed_origins or nr.allows_embed(ev):
+            ancestors_clause = " ".join(["'self'"] + embed_origins) if embed_origins else "'self' *"
+            headers['Content-Security-Policy'] = 'frame-ancestors %s' % ancestors_clause
+            headers['X-Frame-Options'] = ''
+        if self.cfg.cross_origin_isolation or nr.wants_cross_origin_isolation(ev):
+            headers['Cross-Origin-Opener-Policy'] = 'same-origin'
+            headers['Cross-Origin-Embedder-Policy'] = 'credentialless'
+        return status, data, resolved.content_type, headers
+
+    def _refusal_response(self, status: str, text: str) -> tuple[str, bytes, str, dict[str, str]]:
+        return status, (text + '\n').encode(), 'text/plain; charset=utf-8', {'Cache-Control': 'no-store'}
+
+    # ---- manifests -------------------------------------------------------------
+    def manifest(self, ref: nr.SiteRef) -> Optional[NostrEvent]:
+        key = site_key(ref)
+        now = self.clock()
+        cached = self.store.manifest(key)
+        ttl = 10 ** 9 if ref.kind == nr.KIND_SNAPSHOT else self.cfg.manifest_ttl_seconds
+        if cached and now - cached[1] < ttl:
+            return cached[0]
+        ev = self._local_manifest(ref)
+        if ev is None:
+            ev = self._remote_manifest(ref)
+        if ev is None:
+            if cached:
+                return cached[0]      # stale is better than a blank page when the relays are down
+            self.refusals.refuse('manifest', 'not found', key)
+            return None
+        self.store.remember_manifest(key, ev, now)
+        return ev
+
+    def _local_manifest(self, ref: nr.SiteRef) -> Optional[NostrEvent]:
+        filt = dict(ref.filter())
+        if ref.kind == nr.KIND_ROOT and self.cfg.allow_legacy_kind:
+            filt['kinds'] = [nr.KIND_ROOT, nr.KIND_LEGACY_ROOT]
+        try:
+            rows = self.events.newest_matching(filt, 0, 1 << 40, self.clock(), 8)
+        except Exception as e:
+            log.debug('nsite: local lookup failed: %s', e)
+            return None
+        return self._pick(rows, ref)
+
+    def _remote_manifest(self, ref: nr.SiteRef) -> Optional[NostrEvent]:
+        if not self.relays:
+            return None
+        filt = dict(ref.filter())
+        if ref.kind == nr.KIND_ROOT and self.cfg.allow_legacy_kind:
+            filt['kinds'] = [nr.KIND_ROOT, nr.KIND_LEGACY_ROOT]
+        try:
+            rows = self._query(self.relays, [filt])
+        except Exception as e:
+            self.refusals.refuse('manifest', 'relays unreachable', site_key(ref), compartment.why_detail(e))
+            return None
+        ev = self._pick(rows, ref)
+        if ev is not None:
+            try:
+                self.events.insert_event(ev, self.clock())
+            except Exception as e:
+                log.debug('nsite: keeping manifest locally failed: %s', e)
+        return ev
+
+    def _pick(self, rows: Sequence[Mapping[str, Any]], ref: nr.SiteRef) -> Optional[NostrEvent]:
+        best: Optional[NostrEvent] = None
+        for ev in rows:
+            if not nr.is_manifest(ev, ref, allow_legacy=self.cfg.allow_legacy_kind):
+                continue
+            if not verify_event(ev):
+                self.refusals.refuse('manifest', 'bad signature', site_key(ref), {'id': str(ev.get('id'))})
+                continue
+            if best is None or (int(ev.get('created_at', 0)), ev.get('kind') == nr.KIND_ROOT) > \
+                    (int(best.get('created_at', 0)), best.get('kind') == nr.KIND_ROOT):
+                best = cast(NostrEvent, ev)
+        return best
+
+    def _query_relays(self, relays: Sequence[str], filters: Sequence[Mapping[str, Any]]) -> list[NostrEvent]:
+        from node.protocols.nostr import client as relay
+        return relay.query_all(list(relays), list(filters), timeout=self.cfg.fetch_timeout)
+
+    def user_servers(self, pubkey: str) -> Optional[NostrEvent]:
+        """The author's kind-10063 server list, local then relays."""
+        filt = {'kinds': [nr.KIND_USER_SERVERS], 'authors': [pubkey], 'limit': 1}
+        try:
+            rows = self.events.newest_matching(filt, 0, 1 << 40, self.clock(), 1)
+        except Exception:
+            rows = []
+        if not rows and self.relays:
+            try:
+                rows = self._query(self.relays, [filt])
+            except Exception:
+                rows = []
+        rows = [r for r in rows if r.get('kind') == nr.KIND_USER_SERVERS and r.get('pubkey') == pubkey]
+        return max(rows, key=lambda r: int(r.get('created_at', 0))) if rows else None
+
+    # ---- blobs ----------------------------------------------------------------
+    def blob(self, ref: nr.SiteRef, ev: Mapping[str, Any], sha: str) -> Optional[bytes]:
+        key = site_key(ref)
+        data = self.blobs.get(sha)
+        if data is not None:
+            return data
+        if self.store.site_bytes(key) >= self.cfg.max_site_bytes:
+            self.refusals.refuse('quota', 'site over cap', key, {'cap': self.cfg.max_site_bytes})
+            return None
+        servers = nr.blossom_servers(ev, self.user_servers(ev.get('pubkey', '')) if ev.get('pubkey') else None,
+                                     self.cfg.fallback_servers)
+        if not servers:
+            self.refusals.refuse('blob', 'no servers', key, {'sha256': sha})
+            return None
+        for server in servers:
+            try:
+                data = self._fetch(server, sha, self.cfg.max_blob_bytes)
+            except netfetch.FetchTooLarge:
+                self.refusals.refuse('blob', 'too large', key, {'sha256': sha, 'server': server})
+                return None
+            except ValueError as e:
+                self.refusals.refuse('blob', 'hash mismatch', key, {'sha256': sha, 'server': server, 'why': str(e)})
+                continue
+            except Exception as e:
+                self.refusals.refuse('blob', 'server unreachable', key,
+                                     dict(compartment.why_detail(e), server=server))
+                continue
+            if hashlib.sha256(data).hexdigest() != sha:
+                self.refusals.refuse('blob', 'hash mismatch', key, {'sha256': sha, 'server': server})
+                continue
+            try:
+                self.blobs.put(data, nr.guess_type(sha), uploaded_by=ev.get('pubkey'), now=self.clock())
+            except Exception as e:
+                log.debug('nsite: caching %s failed: %s', sha, e)
+            self.store.note_bytes(key, sha, len(data))
+            return data
+        return None
+
+    def _fetch_blob(self, server: str, sha: str, max_bytes: int) -> bytes:
+        return blossom.BlossomClient.get_blob(server, sha, timeout=self.cfg.fetch_timeout, max_bytes=max_bytes)
+
+    # ---- custom domains -----------------------------------------------------------
+    def bind_domain(self, domain: str, force: bool = False) -> DomainBinding:
+        """The binding for `domain`, re-checked when older than the TTL.
+
+        verified   TXT names a site we can see and (when required) the
+                   manifest claims the domain
+        unbound    no `_nsite.<domain>` TXT, or not parseable
+        unclaimed  TXT points at a site whose manifest does not list the domain
+        denied     operator deny list, or not on the allow list of a closed gateway
+        """
+        now = self.clock()
+        cur = self.store.domain(domain)
+        if cur and not force and now - cur['checked_at'] < self.cfg.domain_ttl_seconds:
+            return cur
+
+        def settle(status: str, key: Optional[str], why: Optional[str]) -> DomainBinding:
+            self.store.set_domain(domain, key, status, why, now)
+            if status != 'verified':
+                self.refusals.refuse('domain', status, domain, {'why': why or ''})
+                self.say('domain_refused', domain=domain, why=why or status)
+            else:
+                self.say('domain_verified', domain=domain, site_key=key or '')
+            return {'domain': domain, 'site_key': key, 'status': status, 'why': why, 'checked_at': now}
+
+        if domain in {nr.normalize_domain(d) for d in self.cfg.deny_domains}:
+            return settle('denied', None, 'operator deny list')
+        if self.cfg.allow_domains and domain not in {nr.normalize_domain(d) for d in self.cfg.allow_domains}:
+            return settle('denied', None, 'not on the allow list')
+        try:
+            txts = self._txt('_nsite.' + domain)
+        except dnstxt.DnsError as e:
+            if cur and cur['status'] == 'verified':
+                return cur         # a resolver hiccup must not take a live site down
+            return settle('unbound', None, 'dns: %s' % e)
+        ref: Optional[nr.SiteRef] = None
+        for t in txts:
+            ref = nr.parse_txt_binding(t)
+            if ref:
+                break
+        if ref is None:
+            return settle('unbound', None, 'no _nsite TXT naming a site' if not txts else 'TXT present but not a site')
+        ev = self.manifest(ref)
+        if ev is None:
+            return settle('unbound', site_key(ref), 'site has no manifest')
+        if self.cfg.require_domain_tag and domain not in nr.claimed_domains(ev):
+            return settle('unclaimed', site_key(ref), 'manifest has no ["domain", "%s"] tag' % domain)
+        return settle('verified', site_key(ref), None)
+
+    def _ask(self, conn: Any, path: str) -> bool:
+        """Caddy on_demand_tls `ask`: 200 only for a verified custom domain."""
+        q = urllib.parse.parse_qs(urllib.parse.urlsplit(path).query)
+        domain = nr.normalize_domain((q.get('domain') or [''])[0])
+        ok = False
+        if domain:
+            if nr.parse_host(domain, self.cfg.suffixes) is not None or domain in {s.lower() for s in self.cfg.suffixes}:
+                ok = True
+            elif self.cfg.custom_domains:
+                ok = self.bind_domain(domain).get('status') == 'verified'
+        ws.http_response(conn, '200 OK' if ok else '403 Forbidden', b'ok\n' if ok else b'no\n',
+                         'text/plain; charset=utf-8', {'Cache-Control': 'no-store'})
+        return True