Source code for fleetmesh_core.services.nsite

"""nsite (NIP-5A static websites): the pure part of the host server.

Everything here is a function of its arguments - no sockets, no stores - so
a node's compartment (meshnode: `node/nsite.py`) can be thin and these rules
are held to vectors/nsite.json and the NIP's own vectors (core/tests/test_nsite.py).

What the NIP says, in the order a request meets it:

  1. A site is an event. Kind 15128 is the pubkey's ROOT site (replaceable,
     no `d`), kind 35128 a NAMED site (`d` = site id), kind 5128 a SNAPSHOT
     (regular event; an immutable copy of a manifest at one moment).
  2. The host parses the LEFT-MOST DNS label of the Host header:
       npub1...                        root site of that pubkey
       v + 50 base36 chars             snapshot by event id
       50 base36 chars + 1-13 [a-z0-9-] named site: base36(pubkey) + d tag
     Anything else is "not found".
  3. The manifest's `path` tags map an absolute path to a sha256. A request
     path that does not end in a file name gets `index.html` appended. A path
     with no tag falls back to `/404.html`; without that too, 404.
  4. The blob comes from the manifest's `server` tags first, then the
     author's kind-10063 (BUD-03) server list, then whatever the operator
     configured. Its sha256 MUST match before a byte is served.

The `aggregate` function is the NIP's site version hash: sha256 of the sorted
`<sha> <path>\\n` lines of the `path` tags, nothing else.

The `domain` tag is NOT in NIP-5A. It is this node's extension: a manifest
that carries `["domain", "example.com"]` consents to being served under that
name, so a DNS record alone cannot make a gateway front someone's site under
a look-alike domain. The node that serves checks it; this module only reads it.
"""
from __future__ import annotations

import dataclasses
import hashlib
import posixpath
import re
from typing import Any, Mapping, Optional, Sequence

from ..crypto import bech32
from ..wire.interfaces import EventLike, NostrFilter

KIND_ROOT = 15128
KIND_NAMED = 35128
KIND_SNAPSHOT = 5128
KIND_USER_SERVERS = 10063          # BUD-03
KIND_LEGACY_ROOT = 34128           # pre-2026 nsite drafts; read-only compatibility

# Base36 of a 32-byte value, lowercase, is always this wide: 36**49 < 2**256 < 36**50.
B36_WIDTH = 50
_B36 = '0123456789abcdefghijklmnopqrstuvwxyz'

_RE_SNAPSHOT = re.compile(r'^v([0-9a-z]{50})$')
_RE_NAMED = re.compile(r'^([0-9a-z]{50})([a-z0-9-]{1,13})$')
_RE_SHA = re.compile(r'^[0-9a-f]{64}$')
_RE_SITE_NAME = re.compile(r'^[a-z0-9-]{1,13}$')

# Content types by extension, pinned here rather than taken from the host's
# mimetypes database so every node answers the same bytes. text/*, JSON and
# SVG carry `; charset=utf-8`; anything not listed is application/octet-stream.
EXT_TYPES: dict[str, str] = {
    'html': 'text/html', 'htm': 'text/html', 'css': 'text/css', 'js': 'text/javascript',
    'mjs': 'text/javascript', 'json': 'application/json', 'txt': 'text/plain', 'md': 'text/markdown',
    'xml': 'application/xml', 'svg': 'image/svg+xml', 'png': 'image/png', 'jpg': 'image/jpeg',
    'jpeg': 'image/jpeg', 'gif': 'image/gif', 'webp': 'image/webp', 'ico': 'image/vnd.microsoft.icon',
    'woff': 'font/woff', 'woff2': 'font/woff2', 'ttf': 'font/ttf', 'otf': 'font/otf',
    'wasm': 'application/wasm', 'pdf': 'application/pdf', 'mp4': 'video/mp4', 'webm': 'video/webm',
    'mp3': 'audio/mpeg', 'csv': 'text/csv',
}
_CHARSET_TYPES = ('application/json', 'image/svg+xml')


# ---- base36 -------------------------------------------------------------------

[docs]def b36_encode(raw: bytes) -> str: """32 bytes -> 50 lowercase base36 chars, zero-padded on the left.""" if len(raw) != 32: raise ValueError('base36 labels encode exactly 32 bytes') n = int.from_bytes(raw, 'big') out: list[str] = [] while n: n, r = divmod(n, 36) out.append(_B36[r]) s = ''.join(reversed(out)) return s.rjust(B36_WIDTH, '0')
[docs]def b36_decode(s: str) -> Optional[bytes]: """50 base36 chars -> 32 bytes; None if it is not that.""" if len(s) != B36_WIDTH or any(c not in _B36 for c in s): return None n = 0 for c in s: n = n * 36 + _B36.index(c) if n >= 1 << 256: return None return n.to_bytes(32, 'big')
# ---- labels -------------------------------------------------------------------
[docs]@dataclasses.dataclass(frozen=True, slots=True) class SiteRef: """Which manifest a request is for. `kind` is KIND_ROOT, KIND_NAMED or KIND_SNAPSHOT. `pubkey` is hex (empty for a snapshot, whose author is whoever signed it), `d` the named-site id ('' otherwise), `event_id` the snapshot id ('' otherwise). """ kind: int pubkey: str = '' d: str = '' event_id: str = '' @property def label(self) -> str: """The canonical left-most DNS label for this site.""" if self.kind == KIND_SNAPSHOT: return 'v' + b36_encode(bytes.fromhex(self.event_id)) if self.kind == KIND_NAMED: return b36_encode(bytes.fromhex(self.pubkey)) + self.d return bech32.bech32_encode('npub', bytes.fromhex(self.pubkey))
[docs] def filter(self) -> NostrFilter: """The REQ filter that fetches this manifest.""" if self.kind == KIND_SNAPSHOT: return {'ids': [self.event_id], 'kinds': [KIND_SNAPSHOT]} if self.kind == KIND_NAMED: return {'kinds': [KIND_NAMED], 'authors': [self.pubkey], '#d': [self.d], 'limit': 1} return {'kinds': [KIND_ROOT], 'authors': [self.pubkey], 'limit': 1}
[docs]def parse_label(label: str) -> Optional[SiteRef]: """The NIP's left-most-label grammar. None means 'not found'.""" label = label.lower() if label.startswith('npub1'): raw = bech32.bech32_decode('npub', label) if raw is None or len(raw) != 32: return None return SiteRef(KIND_ROOT, pubkey=raw.hex()) m = _RE_SNAPSHOT.match(label) if m: raw = b36_decode(m.group(1)) return SiteRef(KIND_SNAPSHOT, event_id=raw.hex()) if raw else None m = _RE_NAMED.match(label) if m and not m.group(2).endswith('-'): raw = b36_decode(m.group(1)) return SiteRef(KIND_NAMED, pubkey=raw.hex(), d=m.group(2)) if raw else None return None
[docs]def parse_host(host: str, suffixes: Sequence[str]) -> Optional[SiteRef]: """A Host header against the gateway's configured suffixes. `host` may carry a port. For `npub1x.nsite.example.org` with suffix `nsite.example.org` the label is `npub1x`. A host that is exactly a suffix (the gateway's own landing page) or under no suffix is None. """ h = host.lower().rsplit(':', 1)[0] if host.count(':') <= 1 else host.lower() h = h.rstrip('.') for suf in sorted(suffixes, key=len, reverse=True): suf = suf.lower().strip('.') if suf and h.endswith('.' + suf): label = h[: -len(suf) - 1] if '.' in label: continue # the NIP wants ONE label; deeper names are not sites return parse_label(label) return None
[docs]def parse_txt_binding(txt: str) -> Optional[SiteRef]: """A `_nsite.<domain>` TXT value: `npub1…`, `npub1…:<d>` or `v<snapshot>`. The named-site form takes the d tag after a colon so the domain owner does not have to produce the base36 label by hand. """ v = txt.strip().strip('"').strip() if v.lower().startswith('nsite='): # the DNS-TXT key convention, as `v=spf1` v = v[len('nsite='):].strip() if not v: return None if v.lower().startswith('npub1'): npub, _, d = v.partition(':') ref = parse_label(npub) if ref is None: return None if d: d = d.lower() # the host grammar is case-folded; so is this if not _RE_SITE_NAME.match(d) or d.endswith('-'): return None return SiteRef(KIND_NAMED, pubkey=ref.pubkey, d=d) return ref return parse_label(v) if v.lower().startswith('v') else None
# ---- manifests -----------------------------------------------------------------
[docs]def is_manifest(ev: EventLike, ref: SiteRef, *, allow_legacy: bool = False) -> bool: """Does this event answer `ref`? Kind, author, `d`, id as the NIP demands. Signature verification is the caller's (fleetmesh_core.crypto.giftwrap.verify_event); this is only the shape check, so a snapshot cannot be substituted for a root. """ kind = ev.get('kind') tags = ev.get('tags') or [] if ref.kind == KIND_SNAPSHOT: return kind == KIND_SNAPSHOT and ev.get('id') == ref.event_id if ev.get('pubkey') != ref.pubkey: return False if ref.kind == KIND_NAMED: return kind == KIND_NAMED and tag_value(tags, 'd') == ref.d if kind == KIND_ROOT: return not any(t and t[0] == 'd' for t in tags) return bool(allow_legacy and kind == KIND_LEGACY_ROOT)
[docs]def tag_value(tags: Sequence[Sequence[str]], name: str) -> Optional[str]: for t in tags: if len(t) >= 2 and t[0] == name: return t[1] return None
[docs]def tag_values(tags: Sequence[Sequence[str]], name: str) -> list[str]: return [t[1] for t in tags if len(t) >= 2 and t[0] == name]
[docs]def paths_of(ev: EventLike) -> dict[str, str]: """`path` tags as {absolute path: sha256}. Malformed tags are skipped, not fatal: one bad tag must not take down the pages that are fine.""" out: dict[str, str] = {} for t in ev.get('tags') or []: if len(t) >= 3 and t[0] == 'path' and isinstance(t[1], str) and isinstance(t[2], str): p, sha = t[1], t[2].lower() if p.startswith('/') and _RE_SHA.match(sha): out[p] = sha return out
[docs]def aggregate(ev: EventLike) -> str: """The NIP's aggregate hash: sha256 over sorted `<sha> <path>\n` lines.""" lines = sorted('%s %s\n' % (sha, p) for p, sha in paths_of(ev).items()) return hashlib.sha256(''.join(lines).encode()).hexdigest()
[docs]def claimed_domains(ev: EventLike) -> set[str]: """`domain` tags (this node's extension), normalised.""" out = {normalize_domain(d) for d in tag_values(ev.get('tags') or [], 'domain')} out.discard('') # a blank or dots-only tag names no domain return out
[docs]def normalize_domain(d: str) -> str: return d.strip().lower().rstrip('.')
[docs]def allows_embed(ev: EventLike) -> bool: """Whether the manifest opts into cross-origin iframe embedding (`["embed", "allow"]`).""" for v in tag_values(ev.get('tags') or [], 'embed'): if str(v).strip().lower() in ('allow', 'true', '1', '*'): return True return bool(frame_ancestors_of(ev))
[docs]def frame_ancestors_of(ev: EventLike) -> list[str]: """Explicit frame-ancestor origins declared via `["frame-ancestors", "<origin>"]` or `["embed", "https://..."]`.""" out: list[str] = [] for t in ev.get('tags') or []: if len(t) >= 2 and t[0] in ('frame-ancestors', 'embed'): val = str(t[1]).strip() if val.startswith(('http://', 'https://', 'fips://')) and val not in out: out.append(val.rstrip('/')) return out
[docs]def wants_cross_origin_isolation(ev: EventLike) -> bool: """Whether the manifest requests COOP/COEP headers (`["isolation", "coop-coep"]`) for SharedArrayBuffer WASM.""" for v in tag_values(ev.get('tags') or [], 'isolation'): if str(v).strip().lower() in ('coop-coep', 'cross-origin', 'true', '1'): return True return False
[docs]def blossom_servers(ev: EventLike, user_servers: Optional[EventLike], fallback: Sequence[str]) -> list[str]: """Where to look for the site's blobs, in the NIP's order, de-duplicated: manifest `server` tags, the author's 10063 `server` tags, then the operator's fallback list.""" seen: list[str] = [] def add(u: Any) -> None: if isinstance(u, str) and u.startswith(('http://', 'https://')): u = u.rstrip('/') if u not in seen: seen.append(u) for u in tag_values(ev.get('tags') or [], 'server'): add(u) if user_servers: for u in tag_values(user_servers.get('tags') or [], 'server'): add(u) for u in fallback: add(u) return seen
# ---- paths -------------------------------------------------------------------
[docs]@dataclasses.dataclass(frozen=True, slots=True) class Resolved: """What to serve: the blob and how to label it. `status` is 200 for the asked-for path, 404 when `/404.html` stood in for it.""" path: str sha256: str content_type: str status: int = 200
[docs]def resolve_path(paths: Mapping[str, str], request_path: str) -> Optional[Resolved]: """Map a request path onto the manifest as the NIP says. Directory requests (no file name, or a trailing slash) become `index.html`. `..` and `//` are collapsed before lookup so a manifest cannot be walked. A miss serves `/404.html` with status 404 when the site has one; None means the site has nothing to say for this path. """ p = request_path.split('?', 1)[0].split('#', 1)[0] or '/' while p.startswith('//'): # posixpath keeps a leading `//`; the web does not p = p[1:] if not p.startswith('/'): p = '/' + p wants_dir = p.endswith('/') p = posixpath.normpath(p) if p == '.': p = '/' if wants_dir or not posixpath.splitext(posixpath.basename(p))[1]: p = posixpath.join(p, 'index.html') sha = paths.get(p) if sha: return Resolved(p, sha, guess_type(p), 200) nf = paths.get('/404.html') if nf: return Resolved('/404.html', nf, 'text/html; charset=utf-8', 404) return None
[docs]def guess_type(path: str) -> str: ext = posixpath.splitext(path)[1].lstrip('.').lower() t = EXT_TYPES.get(ext) if t is None: return 'application/octet-stream' if t.startswith('text/') or t in _CHARSET_TYPES: return t + '; charset=utf-8' return t