fleetmesh-node 0.2.0__py3-none-any.whl

node/commands/nsite_cmds.py

@@ -0,0 +1,141 @@
+"""nsite: publish this node's static site and watch the gateway.
+
+`publish` is the only command that moves bytes: it walks a directory,
+PUTs each file to the node's own Blossom face (signed with the node key,
+over loopback, so the face's auth switch does not matter), then asks the
+daemon to sign and publish the manifest from the resulting hashes. The
+control socket never carries file bodies.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any, Mapping, Optional, TypedDict
+
+from node import keystore
+from node.config.parameter import Parameter
+from node.planes.services.nsite.client import upload_site_blobs, walk_site_files
+from node.planes.services.nsite.compartment import DomainBinding, NsiteGateway, NsiteState, PublishResult
+from .adapter import CommandDispatcher
+from .base import _ask, _live, _status_file, add_command, emit, fail
+
+
+class DomainsResponse(TypedDict, total=False):
+    domains: list[DomainBinding]
+
+
+def _face_http(a: argparse.Namespace) -> str:
+    st = _live(a, 'status') or _status_file(a.dir) or {}
+    url = st.get('face') or ''
+    if not url.startswith(('ws://', 'wss://')):
+        fail('the node is not running or its face is unknown (status has no face url)')
+    return 'http' + url[2:]
+
+
+def _show_status(r: NsiteState) -> None:
+    print('nsite gateway:')
+    print('  manifests cached: %d' % r.get('manifests_cached', 0))
+    print('  domains verified: %d' % r.get('domains_verified', 0))
+    print('  bytes cached:     %d' % r.get('cached_bytes', 0))
+
+
+def _fmt_binding(b: Optional[DomainBinding]) -> str:
+    if not b:
+        return '(none)'
+    return '%-32s %-10s %s%s' % (b.get('domain'), b.get('status'), b.get('site_key') or '-',
+                                 (' - ' + (b.get('why') or '')) if b.get('why') else '')
+
+
+def _show_domains(r: DomainsResponse | Mapping[str, Any]) -> None:
+    rows = r.get('domains') or []
+    if not rows:
+        print('no custom-domain bindings yet')
+        return
+    for b in rows:
+        print(_fmt_binding(b))
+
+
+def _show_published(r: PublishResult) -> None:
+    print('published %d files, %d bytes' % (int(r.get('files', 0)), int(r.get('bytes', 0))))
+    print('  manifest  %s (kind %s)' % (r.get('manifest'), r.get('kind')))
+    print('  version   %s' % r.get('aggregate'))
+    if r.get('snapshot'):
+        print('  snapshot  %s' % r['snapshot'])
+    for h in r.get('hosts') or []:
+        print('  https://%s/' % h)
+    if r.get('snapshot_label'):
+        print('  (snapshot label %s)' % r['snapshot_label'])
+    for p in r.get('published_to') or []:
+        print('  relays: %s %s' % ('ok' if p.get('ok') else 'FAILED', p.get('why') or ''))
+
+
+def cmd_publish(a: argparse.Namespace) -> int:
+    if not a.path:
+        fail('publish requires --path <directory>')
+    try:
+        files = walk_site_files(a.path)
+    except ValueError as e:
+        fail(str(e))
+    if '/index.html' not in {p for p, _ in files}:
+        print('warning: no /index.html at the root; browsers asking for / get the 404 page')
+
+    ks = keystore.Keystore.load(a.dir)
+    face = _face_http(a)
+
+    def progress(rel: str, h: str, size: int) -> None:
+        if not getattr(a, 'json', False):
+            print('  %-40s %s %7d' % (rel, h[:12], size))
+
+    paths, total = upload_site_blobs(files, face, ks.node_sk, progress=progress)
+    res = _ask(
+        a.dir,
+        'nsite.publish',
+        paths=paths,
+        site=a.site,
+        snapshot=bool(a.snapshot),
+        domains=a.domain_claim or [],
+        servers=a.server or [],
+        title=a.title,
+        timeout=60,
+    )
+    res['files'] = len(paths)
+    res['bytes'] = total
+    return emit(a, res, _show_published)
+
+
+# Build declarative dispatcher from NsiteGateway.COMMANDS
+_cmd_map = {c.key: c for c in NsiteGateway.COMMANDS}
+dispatcher = CommandDispatcher('nsite', default_action='status')
+dispatcher.add_command('status', _cmd_map['sites'], human=_show_status, timeout=10)
+dispatcher.add_command('domains', _cmd_map['domains'], human=_show_domains, timeout=10)
+dispatcher.add_command('verify', _cmd_map['verify'], human=lambda r, a: print(_fmt_binding(r.get('binding'))), timeout=30)
+dispatcher.add_command(
+    'forget',
+    _cmd_map['forget'],
+    human=lambda r, a: print('forgot %s' % a.domain if r.get('dropped') else 'no binding for %s' % a.domain),
+    timeout=30,
+)
+dispatcher.add_custom(
+    'publish',
+    handler=cmd_publish,
+    parameters=(
+        Parameter(key='path', name='path', description='publish: directory to publish', type=str, default=''),
+        Parameter(key='site', name='site', description='publish: named-site id (d tag, 1-13 of [a-z0-9-]); default is the root site', type=str, default=''),
+        Parameter(key='snapshot', name='snapshot', description='publish: also publish an immutable kind-5128 snapshot', type=bool, default=False),
+        Parameter(key='domain_claim', name='domain_claim', description='publish: claim a custom domain in the manifest (repeatable)', type=list, default=list, cli_name='--domain-claim'),
+        Parameter(key='server', name='server', description='publish: extra Blossom server URL the blobs are mirrored on (repeatable)', type=list, default=list, cli_name='--server'),
+        Parameter(key='title', name='title', description='publish: site title tag', type=str, default=''),
+    ),
+)
+
+
+def cmd_nsite(a: argparse.Namespace) -> int:
+    return dispatcher.dispatch(a)
+
+
+class NsiteCommandProvider:
+    """Registers the nsite (NIP-5A static site) commands."""
+
+    @classmethod
+    def register(cls, sub: argparse._SubParsersAction) -> None:
+        p = add_command(sub, 'nsite', cmd_nsite, 'host static sites (NIP-5A): publish this node\'s site, manage custom domains', js=True)
+        dispatcher.register_arguments(p, action_choices=('status', 'domains', 'verify', 'forget', 'publish'))

node/commands/peering.py

@@ -0,0 +1,402 @@
+"""Peering management, bilateral grants, accounting windows, and trust tiers."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import time
+from typing import Any, Mapping, cast
+
+from node import app as app_mod
+from node.app import socket as control
+from node.storage import accounts as accounts_mod, grants as grants_mod
+from .base import (
+    TIERS,
+    _ask,
+    _grants,
+    _live,
+    _peer,
+    _status_file,
+    _table,
+    _when,
+    add_command,
+    emit,
+    fail,
+    load_json_arg,
+)
+
+
+def _peers_table(view: list) -> None:
+    if not view:
+        print('no peers: nothing granted and nothing held')
+        return
+    rows = []
+    for v in view:
+        last = v.get('last_evaluated') or {}
+        standing = v.get('standing') or {}
+        rows.append((v['peer'][:16], (v.get('issued') or {}).get('tier') or '-', (v.get('received') or {}).get('tier') or '-',
+                     ('%s from %s' % (v['pending']['tier'], v['pending']['from_epoch'])) if v.get('pending') else '-',
+                     ('%s %s' % (last.get('epoch'), last.get('severity'))) if last else '-',
+                     ('%d clean / %d' % (standing['clean_windows'], standing['evaluated_windows'])) if standing else '-',
+                     ','.join(v.get('pulls') or []) or '-',
+                     ('%d' % len(v['shared'])) if v.get('shared') else '-',
+                     ('other %s' % v['digest'][:8]) if v.get('digest') else 'same' if v.get('descriptor') else '-'))
+    _table(('peer', 'issued', 'received', 'pending', 'last window', 'streak', 'pulling', 'shared', 'schema'), rows)
+    for v in view:
+        for n in v.get('notices') or []:
+            print('%s: %s' % (v['peer'][:16], n))
+        if v.get('not_shared'):
+            print('%s: not shared with this node: %s' % (v['peer'][:16], ', '.join(v['not_shared'])))
+    zeroed = [v for v in view if v.get('zeroed_until')]
+    for v in zeroed:
+        print('%s is zeroed after S3 until %s UTC' % (v['peer'][:16], time.strftime('%Y-%m-%d %H:%M', time.gmtime(v['zeroed_until']))))
+
+
+def cmd_peers(a: argparse.Namespace) -> int:
+    view = _live(a, 'peers', timeout=15)
+    if view is None:
+        # From disk: the grants and what the last status said.
+        g = _grants(a.dir)
+        st: Mapping[str, Any] = {}
+        try:
+            st = dict(_status_file(a.dir))
+        except SystemExit:
+            pass
+        cfg_peers: dict[str, list[str]] = {}
+        try:
+            for p in app_mod.load_config(a.dir).get('peers', []):
+                cfg_peers.setdefault(p['pubkey'], []).append(p['shard'])
+        except (OSError, ValueError):
+            pass
+        view = []
+        for pk in sorted({r['peer'] for r in g.list()}):
+            issued, received, pend = g.get(pk, grants_mod.ISSUED), g.get(pk, grants_mod.RECEIVED), g.pending(pk)
+            ev = [e for e in st.get('evaluations', []) if pk.startswith(e['peer'])]
+            view.append({'peer': pk,
+                         'issued': {'tier': issued['payload'].get('tier'), 'status': issued['status']} if issued else None,
+                         'received': {'tier': received['payload'].get('tier'), 'status': received['status']} if received else None,
+                         'pending': {'tier': pend['payload'].get('tier'), 'from_epoch': pend['decided_epoch'] + 1} if pend else None,
+                         'last_evaluated': ev[-1] if ev else None, 'standing': None,
+                         'zeroed_until': None, 'pulls': cfg_peers.get(pk, []), 'descriptor': None,
+                         'shared': [], 'not_shared': [], 'digest': None, 'notices': []})
+    return emit(a, view, _peers_table)
+
+
+def cmd_grant(a: argparse.Namespace) -> int:
+    pk = _peer(a.dir, a.peer)
+    out = app_mod.grant_view(_grants(a.dir), pk)
+    if a.json:
+        return emit(a, out)
+    if out['issued'] is None and out['received'] is None:
+        fail('no grant either way with %s' % pk[:16])
+    out_dict = cast(Mapping[str, Any], out)
+    for direction in (grants_mod.ISSUED, grants_mod.RECEIVED):
+        row = out_dict.get(direction)
+        print('%s %s' % (direction, '(none)' if row is None else ''))
+        if row is None:
+            continue
+        p = row['payload']
+        print('  envelope %s  tier %s  status %s  window %ss  receipt every %ss'
+              % (row['envelope_id'][:16] + '…', p.get('tier'), row['status'], p.get('window'), (p.get('receipt') or ['?'])[0]))
+        limits = p.get('limits') or {}
+        print('  limits   ' + '  '.join('%s %s' % (k, v) for k, v in sorted(limits.items())))
+        scope = p.get('scope') or {}
+        print('  scope    pull %s  push %s' % (json.dumps(scope.get('pull')), json.dumps(scope.get('push'))))
+        hist = out_dict.get(direction + '_history', [])
+        if len(hist) > 1:
+            print('  history  ' + '; '.join('%s… %s from %s' % (h['envelope_id'][:8], h['tier'], h['effective_epoch']) for h in hist))
+    if out['pending']:
+        p = out['pending']
+        print('waiting   tier %s from window %s (%s UTC): %s' % (p['payload'].get('tier'), p['decided_epoch'] + 1,
+                                                                 _when(p['decided_epoch'] + 1), p['note']))
+    if out['seed_applied']:
+        print('seed      %s, decided at %s' % (out['seed_applied'][0], time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(out['seed_applied'][1]))
+                                              if out['seed_applied'][1] else 'time zero'))
+    return 0
+
+
+def cmd_windows(a: argparse.Namespace) -> int:
+    pk = _peer(a.dir, a.peer)
+    path = os.path.join(a.dir, 'accounts.sqlite')
+    if not os.path.exists(path):
+        fail('no accounts.sqlite yet: nothing has been metered')
+    # Through the store, not a bare sqlite3 connection: `windows_view` already
+    # prefers `_all` when it is given one, and a store reaches whatever backend
+    # is configured. readonly=True keeps exactly what the direct connection
+    # gave - no writes, no schema, no WAL writer lock beside a running node.
+    acc = accounts_mod.AccountStore(path, readonly=True)
+    try:
+        out = app_mod.windows_view(acc, pk, a.last)
+    finally:
+        acc.close()
+    rows = []
+    for rec in out:
+        m, cl = rec['measured'], rec['claimed'] or {}
+        rows.append((rec['epoch'], _when(rec['epoch'] + 1), rec['severity'] or 'not evaluated',
+                     '%s/%s' % (m.get('req', 0), cl.get('req', '-')), '%s/%s' % (m.get('events_in', 0), cl.get('events_in', '-')),
+                     '%s/%s' % (m.get('bytes_in', 0), cl.get('bytes_in', '-')), rec['receipts_in'], rec['my_receipts_sent']))
+    if a.json:
+        return emit(a, out)
+    if not rows:
+        fail('no windows metered with %s' % pk[:16])
+    print('windows with %s  (measured/claimed, in the issuer frame)' % pk[:16])
+    _table(('window', 'closed UTC', 'severity', 'req', 'events_in', 'bytes_in', 'receipts in', 'sent'), rows)
+    return 0
+
+
+def cmd_peer(a: argparse.Namespace) -> int:
+    cfg = dict(app_mod.load_config(a.dir))
+    pk = _peer(a.dir, a.peer)
+    filt = load_json_arg(a.filter, '--filter')
+    if not isinstance(filt, dict):
+        fail('--filter must be a nostr filter object')
+    if a.every < 1:
+        fail('--every must be a positive number of seconds')
+    entry = {'pubkey': pk, 'shard': a.shard, 'filter': filt, 'pull_every': a.every}
+    others = [p for p in cfg.get('peers', []) if (p['pubkey'], p['shard']) != (pk, a.shard)]
+    if entry in cfg.get('peers', []):
+        # Already exactly this. Saying "will peer" here made every deploy pass
+        # restart every node, which on a public mesh is a round of farewells,
+        # replays and conn_rate refusals for nothing.
+        return emit(a, {'action': 'peer', 'peer': pk, 'shard': a.shard, 'every': a.every,
+                        'peers_configured': len(cfg['peers']), 'changed': False},
+                    lambda _: print('already peered with %s for shard %s; %d peers configured'
+                                    % (pk[:16], a.shard, len(cfg['peers']))))
+    cfg['peers'] = others + [entry]
+    app_mod.save_config(a.dir, cfg)
+    return emit(a, {'action': 'peer', 'peer': pk, 'shard': a.shard, 'every': a.every, 'peers_configured': len(cfg['peers']), 'changed': True},
+                lambda _: print('will peer with %s for shard %s on the next %s; %d peers configured'
+                                % (pk[:16], a.shard, 'tick' if control.running(a.dir) else 'run', len(cfg['peers']))))
+
+
+def cmd_unpeer(a: argparse.Namespace) -> int:
+    cfg = dict(app_mod.load_config(a.dir))
+    pk = _peer(a.dir, a.peer)
+    before = len(cfg.get('peers', []))
+    cfg['peers'] = [p for p in cfg.get('peers', []) if p['pubkey'] != pk or (a.shard and p['shard'] != a.shard)]
+    app_mod.save_config(a.dir, cfg)
+    n = before - len(cfg['peers'])
+    if not n:
+        fail('%s was not being pulled from' % pk[:16])
+    return emit(a, {'action': 'unpeer', 'peer': pk, 'shard': a.shard, 'shards_removed': n, 'peers_configured': len(cfg['peers'])},
+                lambda _: print('stopped pulling %d shard(s) from %s; the grants stay live (`terminate` ends the peering)' % (n, pk[:16])))
+
+
+def _trust_table(st: dict) -> None:
+    decided = st['decided']
+    if not decided:
+        print('no operator trust decisions recorded')
+        return
+    print('%-16s %-12s %-12s %-12s %s' % ('peer', 'decided', 'held', 'state', 'when'))
+    for pk, d in sorted(decided.items()):
+        when = time.strftime('%Y-%m-%d %H:%M', time.gmtime(d['at'])) if d.get('at') else 'initial'
+        print('%-16s %-12s %-12s %-12s %s' % (pk[:16], d.get('tier', '-'), str(d.get('held') or '-'), d.get('state', '-'), when))
+    print('\nin force: %d  pending: %d  overridden: %d  waiting: %d' % (
+        st.get('in_force', 0), len(st.get('pending') or []),
+        len(st.get('overridden') or []), len(st.get('waiting') or [])))
+
+
+def cmd_trust(a: argparse.Namespace) -> int:
+    """The one decision that raises a tier, and it is a person's."""
+    if not getattr(a, 'tier', None):
+        st = _live(a, 'trust')
+        if st is None:
+            cfg = app_mod.load_config(a.dir)
+            trust_cfg = dict(cfg.get('trust') or {})
+            st = {
+                'decided': {
+                    pk[:16]: {
+                        'tier': e.get('tier') if isinstance(e, dict) else e,
+                        'at': e.get('at', 0) if isinstance(e, dict) else 0,
+                        'held': None,
+                        'state': 'offline',
+                    }
+                    for pk, e in trust_cfg.items()
+                },
+                'in_force': 0,
+                'pending': [],
+                'overridden': [],
+                'waiting': [pk[:16] for pk in trust_cfg],
+            }
+        decided = st.get('decided') or {}
+        if getattr(a, 'peer', None):
+            pk_filter = _peer(a.dir, a.peer)
+            decided = {k: v for k, v in decided.items() if k == pk_filter[:16] or k == pk_filter}
+        out = dict(st)
+        out['decided'] = decided
+        return emit(a, out, _trust_table)
+
+    if not getattr(a, 'peer', None):
+        fail('meshnode trust: error: setting a tier requires a peer')
+
+    cfg = dict(app_mod.load_config(a.dir))
+    pk = _peer(a.dir, a.peer)
+    trust = dict(cfg.get('trust') or {})
+    trust[pk] = {'tier': a.tier, 'at': int(time.time())}
+    cfg['trust'] = trust
+    app_mod.save_config(a.dir, cfg)
+
+    def seeded(_: dict) -> None:
+        print('%s is %s' % (pk[:16], a.tier))
+        if _grants(a.dir).get(pk, 'issued') is None:
+            print('  no grant issued to it yet; it will open at %s when you peer' % a.tier)
+        else:
+            print('  the live grant will be re-issued at %s at the next window boundary' % a.tier)
+    return emit(a, {'peer': pk, 'tier': a.tier, 'at': trust[pk]['at']}, seeded)
+
+
+def cmd_terminate(a: argparse.Namespace) -> int:
+    pk = _peer(a.dir, a.peer)
+    r = _ask(a.dir, 'terminate', peer=pk, reason=a.reason)
+
+    def human(r: dict) -> None:
+        told = r.get('told') or {}
+        print('terminated the peering with %s (%s); both grants are zero here' % (pk[:16], r.get('reason')))
+        if 'error' in told:
+            print('  the peer could not be told: %s' % told['error'])
+        else:
+            print('  told via %s' % ', '.join(u for u, v in told.items() if v[0]) or 'no relay accepted the message')
+        if r.get('pulls_removed'):
+            print('  %d scheduled pull(s) removed from the config' % r['pulls_removed'])
+    return emit(a, r, human)
+
+
+def _retired(r: dict) -> None:
+    print('retiring: %s' % r.get('reason'))
+    for d in r.get('did') or []:
+        print('  %s' % ' '.join(str(x) for x in d))
+    print('  %d handover(s) to %d peer(s); %d claim(s) withdrawn'
+          % (r.get('handed', 0), len(r.get('peers') or []), r.get('withdrawn', 0)))
+    if r.get('revoked'):
+        print('  the node key is revoked: a successor inherits nothing and starts on probation')
+    else:
+        print('  the key is NOT revoked; this node can be started again')
+    print('  the node is stopping, and says farewell to every peer on the way out')
+
+
+def cmd_retire(a: argparse.Namespace) -> int:
+    """Leave the mesh in order. Not what a restart does."""
+    r = _ask(a.dir, 'retire', reason=a.reason, revoke=bool(a.revoke), lapses_in=a.lapses_in)
+    return emit(a, r, _retired)
+
+
+def cmd_withdraw(a: argparse.Namespace) -> int:
+    pk = _peer(a.dir, a.peer)
+    r = _ask(a.dir, 'withdraw', peer=pk, window=a.window, why=a.why)
+
+    def human(r: dict | list) -> None:
+        for row in (r if isinstance(r, list) else [r]):
+            if row['was_published']:
+                print('withdrew the report about %s for window %s (%s)' % (pk[:16], row['window'], row['report'][:16]))
+                print('  the kind 30802 is not deleted; it carries its own expiration and lapses on it')
+            else:
+                print('withdrew the finding about %s for window %s; it had not been published'
+                      % (pk[:16], row['window']))
+            print('  the subject was told: %s' % row['why'])
+    return emit(a, r, human)
+
+
+def cmd_standing(a: argparse.Namespace) -> int:
+    pk = _peer(a.dir, a.peer)
+    target = _peer(a.dir, a.target)
+    r = _ask(a.dir, 'standing', peer=pk, target=target)
+
+    def human(r: dict) -> None:
+        if r['answer'] == 'decline':
+            print('%s declined to say: %s' % (pk[:16], (r['body'] or {}).get('reason')))
+            return
+        b = r['body']
+        print('%s says of %s: tier %s, %s clean window(s) in a row, %s evaluated, %s'
+              % (pk[:16], target[:16], b.get('tier'), b.get('clean_windows'), b.get('evaluated_windows'),
+                 'has adverse reports' if b.get('has_adverse_reports') else 'no adverse reports'))
+    return emit(a, r, human)
+
+
+def cmd_reports(a: argparse.Namespace) -> int:
+    target = _peer(a.dir, a.target)
+    r = _ask(a.dir, 'reports', target=target, timeout=60)
+
+    def human(r: dict) -> None:
+        reps = r.get('reports') or []
+        if not reps:
+            print('no kind 30802 about %s on this node\'s relays' % target[:16])
+            return
+        _table(('reporter', 'severity', 'admissible', 'weight here', 'published UTC'),
+               [(x['reporter'][:16], x['severity'], 'yes' if x['admissible'] else 'no: ' + '; '.join(x['reasons'])[:60],
+                 x['weight'], time.strftime('%Y-%m-%d %H:%M', time.gmtime(x['created_at']))) for x in reps])
+        print('\nthis node\'s view of %s, its own S0 weighed against them: %s' % (target[:16], r.get('view')))
+    return emit(a, r, human)
+
+
+from ..config.parameter import Parameter
+from .adapter import add_parameter_argument
+
+PARAM_WIN_LAST = Parameter(key='last', name='last', description='how many, newest last (0 for all)', type=int, default=24)
+
+PARAM_PEER_SHARD = Parameter(key='shard', name='shard', description='shard name', type=str, default='', required=True)
+PARAM_PEER_FILTER = Parameter(key='filter', name='filter', description='a nostr filter, JSON or @file', type=str, default='', required=True)
+PARAM_PEER_EVERY = Parameter(
+    key='every', name='every',
+    description='seconds between pulls. The default is the probation connection ceiling: four an hour. It was 600, which is six, so a peering that used the shipped default overran the grant it was shipped with',
+    type=int, default=900,
+)
+
+PARAM_UNPEER_SHARD = Parameter(key='shard', name='shard', description='only this shard', type=str, default='')
+
+PARAM_TRUST_PEER = Parameter(key='peer', name='peer', description='the peer to seed a tier for (pubkey, did, npub or prefix)', type=str, default='', positional=True, required=False, nargs='?')
+PARAM_TRUST_TIER = Parameter(key='tier', name='tier', description='the tier to seed for this peer', type=str, default=None, choices=TIERS)
+
+PARAM_TERM_REASON = Parameter(key='reason', name='reason', description='reason for termination', type=str, default='operator')
+
+PARAM_RET_REASON = Parameter(key='reason', name='reason', description='reason for retirement', type=str, default='operator')
+PARAM_RET_REVOKE = Parameter(key='revoke', name='revoke', description='publish a kind 11802 as well: the key is retired for good and a successor inherits nothing', type=bool, default=False)
+PARAM_RET_LAPSES = Parameter(key='lapses_in', name='lapses_in', cli_name='--lapses-in', description='how long the withdrawn claims stay on the relays before they expire', type=int, default=86400)
+
+PARAM_WD_WINDOW = Parameter(key='window', name='window', description='the window epoch the finding is about', type=int, default=0, positional=True, required=True)
+PARAM_WD_WHY = Parameter(key='why', name='why', description='what to tell the subject; recorded on the complaint thread', type=str, default=None)
+
+PARAM_ST_TARGET = Parameter(key='target', name='target', description='the node asked about: pubkey, did:nostr or prefix', type=str, default='', positional=True, required=True)
+
+PARAM_RP_TARGET = Parameter(key='target', name='target', description='pubkey, did:nostr or prefix', type=str, default='', positional=True, required=True)
+
+
+class PeeringCommandProvider:
+    """Registers peer management, trust tier, bilateral grant, and report commands."""
+
+    @classmethod
+    def register(cls, sub: argparse._SubParsersAction) -> None:
+        add_command(sub, 'peers', cmd_peers, 'every peer: tiers, pending grant, last window, standing', js=True)
+        add_command(sub, 'grant', cmd_grant, 'both grants with a peer, their history, and what waits for the boundary', peer=True, js=True)
+
+        w = add_command(sub, 'windows', cmd_windows, 'the windows this node priced for a peer', peer=True, js=True)
+        add_parameter_argument(w, PARAM_WIN_LAST)
+
+        p = add_command(sub, 'peer', cmd_peer, 'add a peer and shard to pull from', peer=True, js=True)
+        add_parameter_argument(p, PARAM_PEER_SHARD, require_flag=True)
+        add_parameter_argument(p, PARAM_PEER_FILTER, require_flag=True)
+        add_parameter_argument(p, PARAM_PEER_EVERY)
+
+        u = add_command(sub, 'unpeer', cmd_unpeer, 'stop pulling from a peer; the grants stay live', peer=True, js=True)
+        add_parameter_argument(u, PARAM_UNPEER_SHARD)
+
+        t = add_command(sub, 'trust', cmd_trust, "inspect or set a peer's tier, which nothing else can raise", js=True)
+        add_parameter_argument(t, PARAM_TRUST_PEER)
+        add_parameter_argument(t, PARAM_TRUST_TIER)
+
+        te = add_command(sub, 'terminate', cmd_terminate, 'end a peering: zero both grants and tell the peer (needs the node running)', peer=True, js=True)
+        add_parameter_argument(te, PARAM_TERM_REASON)
+
+        rt = add_command(sub, 'retire', cmd_retire, 'leave the mesh in order: hand over every asserted shard, withdraw the claims, stop', js=True)
+        add_parameter_argument(rt, PARAM_RET_REASON)
+        add_parameter_argument(rt, PARAM_RET_REVOKE)
+        add_parameter_argument(rt, PARAM_RET_LAPSES)
+
+        wd = add_command(sub, 'withdraw', cmd_withdraw, 'withdraw a finding this node made about one window (needs the node running)', peer=True, js=True)
+        add_parameter_argument(wd, PARAM_WD_WINDOW)
+        add_parameter_argument(wd, PARAM_WD_WHY)
+
+        st = add_command(sub, 'standing', cmd_standing, 'ask a peer what it knows about a third node (needs the node running)', peer=True, js=True)
+        add_parameter_argument(st, PARAM_ST_TARGET)
+
+        r = add_command(sub, 'reports', cmd_reports, 'the kind 30802s about a node, weighed by this one (needs the node running)', js=True)
+        add_parameter_argument(r, PARAM_RP_TARGET)