"""The relay score a node projects for clients: kind 30385 under NIP-85,
derived from a kind 30802 and from nothing else.
A kind 30802 is a peer verdict, read by nodes setting budgets. A client
choosing a relay reads none of that. It reads NIP-85, where a provider it has
chosen publishes a rank for a subject, and for a URL the subject is a NIP-73
identifier: kind 30385, `d` the URL, `k` the word `web`. This module writes one
of those per ws or wss endpoint the reported node declares, so a client that
already understands NIP-85 learns what the mesh found without learning the
mesh.
Adverse only. A node publishes a score for a peer it has reported and for no
other peer. The rank is not the peer's standing - standing lives in blinded
grants and unpublished clean windows precisely so that it is not on a relay -
it is how far the reporter's own budget for the subject fell: 100 times the
multiplier the ladder applied. The report is cited by coordinate in an `a` tag,
so the evidence is one fetch away and the score never says more than the
report does.
The specification had held this back while nostr-protocol/nips PR 2418, which
proposes a differently shaped relay assertion under the same kind number,
settled. It has not settled and never discussed the number. Merged NIP-85
already assigns kind 30385 to NIP-73 identifiers and a relay URL is one, so the
projection is published under the documents that exist. If the proposal merges
on another number a second serialiser follows it.
Everything here reads its shape from `projection` in constants.json.
"""
from __future__ import annotations
import ipaddress
import re
from typing import Optional, Sequence
from ..wire import schema_files
from ..storage import store
from ..wire import spelling
from ..wire.interfaces import (
EventLike,
ProjectionConstants,
SchemaConstantsDocument,
UnsignedNostrEvent,
)
CONSTANTS: SchemaConstantsDocument = schema_files.load_constants()
P: ProjectionConstants = CONSTANTS['projection']
KIND: int = P['kind']
REPORT: int = 30802
RANK: dict[str, int] = P['rank_by_outcome']
IDENTIFIER_TYPE: str = 'web'
DEFAULT_PORT: dict[str, int] = {'ws': 80, 'wss': 443}
def _is_hex64(s: object) -> bool:
return spelling.is_hex(s, 64)
# ---------------------------------------------------------- the identifier --
[docs]def canonical_relay(url: str) -> str:
"""The one spelling of a relay address, per projection.canonical_relay.
Two nodes reporting the same relay must publish the same `d`, or a client
sees two subjects where there is one. NIP-73 says a URL is normalised with
no fragment and stops there; this says the rest, and it says it by
refusing: a general URL parser (urlsplit, WHATWG) normalises IDNA, IP
shorthand, dot segments and percent-encoding each in its own way, so two
runtimes agree only if neither is asked to. The grammar is
scheme "://" host [":" port] [path] ["?" ...] ["#" ...]
scheme ws | wss, any case, lowercased
host an LDH domain name (lowercased; a non-ASCII name is presented as
its A-labels), a dotted-quad IPv4, or a bracketed IPv6 literal in
its RFC 5952 spelling; nothing else, no userinfo
port ASCII digits 1..65535 without leading zeros; the default is dropped
path "/"-separated segments of URL path characters (no ".", "..", "",
space, backslash or non-ASCII); trailing slashes are dropped
query and fragment are not part of a relay's identity and are dropped.
Raises ValueError for an address that is not a relay's.
"""
if not isinstance(url, str) or not url.strip():
raise ValueError('a relay address is a non-empty string')
s = url.strip()
scheme, sep, rest = s.partition('://')
scheme = scheme.lower()
if not sep or scheme not in DEFAULT_PORT:
raise ValueError('scheme must be ws or wss, not %r' % (scheme or s))
for cut in '#?':
rest = rest.split(cut, 1)[0]
slash = rest.find('/')
authority, path = (rest, '') if slash < 0 else (rest[:slash], rest[slash:])
if '@' in authority:
raise ValueError('a relay address carries no userinfo')
if authority.startswith('['):
close = authority.find(']')
if close < 0:
raise ValueError('an IPv6 literal closes its bracket')
host, port_part = authority[:close + 1], authority[close + 1:]
else:
host, _, port_text = authority.partition(':')
port_part = ':' + port_text if _ else ''
host = _canonical_host(host)
port = None
if port_part:
digits = port_part[1:]
port = store.ascii_int(digits)
if port is None or digits != str(port) or not 0 < port < 65536:
raise ValueError('port out of range')
netloc = host if port in (None, DEFAULT_PORT[scheme]) else '%s:%d' % (host, port)
return '%s://%s%s' % (scheme, netloc, _canonical_path(path))
_LDH = re.compile(r'^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$')
_PATH_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@%")
def _canonical_host(host: str) -> str:
if not host:
raise ValueError('a relay address names a host')
if host.startswith('['):
if not host.endswith(']'):
raise ValueError('an IPv6 literal closes its bracket')
text = host[1:-1]
if '%' in text:
raise ValueError('an IPv6 literal carries no zone id')
try:
addr = ipaddress.IPv6Address(text)
except ValueError:
raise ValueError('not an IPv6 address: %s' % host)
if int(addr) >> 32 in (0, 0xffff):
raise ValueError('an IPv4 address is written as a dotted quad, not embedded in IPv6')
if str(addr) != text:
raise ValueError('an IPv6 literal is written in its RFC 5952 form: [%s]' % addr)
return host
if host.replace('.', '').isdigit() and host.isascii():
parts = host.split('.')
if len(parts) != 4 or any(not p or p != str(int(p)) or int(p) > 255 for p in parts):
raise ValueError('an IPv4 address is four decimal octets')
return host
lowered = host.lower()
if not lowered.isascii():
raise ValueError('a non-ASCII host is presented as its A-labels (xn--)')
labels = lowered.split('.')
if len(lowered) > 253 or any(not _LDH.match(label) for label in labels):
raise ValueError('host is not a valid domain name')
for label in labels:
if label.startswith('xn--') and not _punycode_ok(label[4:]):
raise ValueError('%s is not a well-formed A-label' % label)
return lowered
def _punycode_ok(tail: str) -> bool:
"""Punycode that decodes to a non-ASCII name and re-encodes to itself."""
try:
name = tail.encode('ascii').decode('punycode')
except UnicodeError:
return False
return bool(name) and not name.isascii() and name.encode('punycode').decode('ascii') == tail
def _canonical_path(path: str) -> str:
path = path.rstrip('/')
if not path:
return ''
for seg in path[1:].split('/'):
if seg in ('', '.', '..') or any(ch not in _PATH_CHARS for ch in seg):
raise ValueError('path is not canonical: %r' % path)
return path
[docs]def relay_endpoints(descriptor: EventLike) -> list[str]:
"""The relay addresses a kind 11801 declares: ws and wss endpoints,
canonical, deduplicated, sorted. An endpoint that does not canonicalise is
skipped rather than fatal; it is the descriptor's defect and the validator
reports it there.
"""
out: set[str] = set()
for t in store.tags(descriptor, 'endpoint'):
if len(t) >= 3 and t[1] in DEFAULT_PORT:
try:
out.add(canonical_relay(t[2]))
except ValueError:
continue
return sorted(out)
# ----------------------------------------------------------- the assertion --
[docs]def coordinate(report: EventLike) -> str:
"""The NIP-01 `a` value of a kind 30802: kind, author, and its `d`."""
d = store.first_tag(report, 'd')
return '%d:%s:%s' % (REPORT, report.get('pubkey', ''), d[1] if d and len(d) > 1 else '')
[docs]def project(
report: EventLike,
endpoints: Sequence[str],
now: Optional[int] = None,
) -> list[UnsignedNostrEvent]:
"""The kind 30385 events a report projects to: one per endpoint, unsigned.
`endpoints` is what relay_endpoints() returned for the subject's
descriptor. A subject with none projects to nothing, which is right: a
client cannot connect to it, so there is nothing to score. `now` is the
created_at; a node stamps it past the last one at that coordinate, like
every other addressable event it republishes.
"""
# `!=` let 30802.0 and True-shaped kinds through; a kind is a JSON integer.
if not store.is_int(report.get('kind')) or report.get('kind') != REPORT:
raise ValueError('only a kind 30802 projects; this is kind %r' % report.get('kind'))
if not store.is_hex64(report.get('pubkey')):
raise ValueError('a report has a 64-hex pubkey')
if now is None and not store.is_int(report.get('created_at')):
raise ValueError('a report has an integer created_at')
outcome = store.first_tag(report, 'outcome')
if outcome is None or len(outcome) < 2 or outcome[1] not in RANK:
raise ValueError('outcome %r is not a finding the projection prices'
% (outcome[1] if outcome and len(outcome) > 1 else None))
subject = store.first_tag(report, 'd')
if subject is None or len(subject) < 2 or not _is_hex64(subject[1]):
raise ValueError('a report names its subject in d')
created_at = report['created_at'] if now is None else now
# Only a well-formed expiration is carried across (store.expiration's
# rule); garbage on the report does not become garbage on the projection.
exp_ts = store.expiration(report)
out: list[UnsignedNostrEvent] = []
for url in sorted(set(endpoints)):
if canonical_relay(url) != url:
raise ValueError('endpoint %r is not canonical' % url)
tags: list[list[str]] = [
['d', url],
['k', IDENTIFIER_TYPE],
['p', subject[1]],
['a', coordinate(report)],
['rank', str(RANK[outcome[1]])],
]
if exp_ts is not None:
tags.append(['expiration', str(exp_ts)])
out.append(store.make_event(report['pubkey'], created_at, KIND, tags, ''))
return out
[docs]def check_projection(
event: EventLike,
report: Optional[EventLike] = None,
endpoints: Optional[Sequence[str] | set[str]] = None,
) -> list[str]:
"""Everything a reader may hold a projection to. Returns the problems.
Alone, the shape: the tags NIP-85 and this protocol require, a canonical
`d`, a rank the ladder can produce. With the report, the derivation: same
author, the coordinate really is that report's, the rank is the report's
outcome priced, the expiry is the report's. With the subject's endpoints,
that `d` is one of them.
"""
p: list[str] = []
if not store.is_int(event.get('kind')) or event.get('kind') != KIND:
p.append('kind must be %d' % KIND)
if not isinstance(event.get('tags'), list) or any(
not isinstance(t, list) or not t or not all(isinstance(x, str) for x in t) for t in event['tags']):
p.append('every tag must be a non-empty array of strings')
d = store.first_tag(event, 'd')
if d is None or len(d) < 2 or not d[1]:
p.append('d is required')
else:
try:
if canonical_relay(d[1]) != d[1]:
p.append('d is not canonical: %r' % d[1])
except ValueError as e:
p.append('d is not a relay address: %s' % e)
k = store.first_tag(event, 'k')
if k is None or len(k) < 2 or k[1] != IDENTIFIER_TYPE:
p.append('k must be %s' % IDENTIFIER_TYPE)
subj = store.first_tag(event, 'p')
if subj is None or len(subj) < 2 or not _is_hex64(subj[1]):
p.append('p must name the subject node')
a = store.first_tag(event, 'a')
if a is None or len(a) < 2:
p.append('a must cite the report')
else:
parts = a[1].split(':')
if (len(parts) != 3 or parts[0] != str(REPORT) or not _is_hex64(parts[1])
or not _is_hex64(parts[2])):
p.append('a is not a kind 30802 coordinate: %r' % a[1])
else:
if parts[1] != event.get('pubkey'):
p.append('a cites a report by someone else; a projection is of its author\'s own report')
if subj is not None and len(subj) >= 2 and parts[2] != subj[1]:
p.append('a cites a report about a different subject than p')
rank = store.first_tag(event, 'rank')
if rank is None or len(rank) < 2 or store.ascii_int(rank[1]) is None:
p.append('rank must be a decimal integer')
elif store.ascii_int(rank[1]) not in RANK.values():
p.append('rank %s is not one the ladder produces' % rank[1])
if event.get('content', '') != '':
p.append('content is empty')
if len(store.tags(event, 'd')) > 1 or len(store.tags(event, 'rank')) > 1:
p.append('one d and one rank')
if report is not None:
if report.get('pubkey') != event.get('pubkey'):
p.append('the report and the projection have different authors')
if a is not None and len(a) >= 2 and a[1] != coordinate(report):
p.append('a does not cite this report')
outcome = store.first_tag(report, 'outcome')
outcome_name = outcome[1] if outcome is not None and len(outcome) > 1 else None
want = RANK.get(outcome_name) if outcome_name is not None else None
if want is None:
p.append('the report has no outcome the projection prices')
elif rank is not None and len(rank) >= 2 and rank[1] != str(want):
p.append('rank %s but the report is %s, which prices at %d' % (rank[1], outcome_name, want))
if store.expiration(report) != store.expiration(event):
p.append('expiration is the report\'s')
if endpoints is not None and d is not None and len(d) >= 2 and d[1] not in endpoints:
p.append('d is not an endpoint the subject declares')
return p
# ---------------------------------------------------------- NIP-32 Labels --
LABEL_KIND: int = 1985
LABEL_NAMESPACE: str = 'fleetmesh.reputation'
LABEL_BY_OUTCOME: dict[str, str] = {
'S1': 's1-divergence',
'S2': 's2-misreport',
'S3': 's3-overrun',
'S4': 's4-tamper',
}
[docs]def label(
report: EventLike,
now: Optional[int] = None,
) -> UnsignedNostrEvent:
"""Build a NIP-32 kind 1985 moderation/reputation label derived from an adverse report."""
if not store.is_int(report.get('kind')) or report.get('kind') != REPORT:
raise ValueError('only a kind 30802 projects a label; this is kind %r' % report.get('kind'))
outcome = store.first_tag(report, 'outcome')
if outcome is None or len(outcome) < 2 or outcome[1] not in LABEL_BY_OUTCOME:
raise ValueError('outcome %r is not a finding with a label mapping'
% (outcome[1] if outcome and len(outcome) > 1 else None))
subject = store.first_tag(report, 'd')
if subject is None or len(subject) < 2 or not _is_hex64(subject[1]):
raise ValueError('a report names its subject in d')
created_at = report.get('created_at', 0) if now is None else now
expiration = store.first_tag(report, 'expiration')
label_value = LABEL_BY_OUTCOME[outcome[1]]
tags: list[list[str]] = [
['L', LABEL_NAMESPACE],
['l', label_value, LABEL_NAMESPACE],
['p', subject[1]],
['a', coordinate(report)],
]
if report.get('id'):
tags.append(['e', report['id']])
if expiration is not None and len(expiration) > 1:
tags.append(['expiration', expiration[1]])
return store.make_event(report.get('pubkey', ''), created_at, LABEL_KIND, tags, '')