"""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