"""The conformance op catalogue: every operation a harness may ask of a node.
Each op is a name, the plane it belongs to (docs/implementing.md), one line
about it and a handler that takes the JSON `args` and returns a JSON result.
Names are `<domain>.<verb>`; the domain is a wire surface or a mechanism named
in the spec, never a Python module. Argument shapes are the vector files'
shapes - `fleetmesh.org/scripts/conform.py` derives its requests straight from
`vectors/*.json`, so the catalogue and the vectors cannot say different things.
Everything that crosses this boundary is plain JSON: bytes are hex, bounds and
items are lists, refusals are `{"refused": why}` results (see `conformance.py`).
This file is marshalling only; the mechanisms live in their own modules.
The catalogue is NOT inside the schema digest yet: op names may still move while
a second implementation pushes on them. They are promoted into schema/ at the
first non-draft tag.
"""
from __future__ import annotations
import dataclasses
import hashlib
import json
from typing import Any, Callable, Mapping
from ..accounting import accounting, capacity, paidfetch, standing, window
from ..crypto import bech32, crypto, giftwrap, nip44
from ..identity import auth_wire, did, identity, relaylist, web_auth
from ..network import brand, control, definition, descriptor_split, enrol_token, fleet, grant, group, join, join_request, relay_allow, roster
from ..peering import complaint, coverage, peering, projection, release, reports
from ..products import (
ProductRefused,
listing as product_listing,
read_fiber as product_read_fiber,
verify_log as product_verify_log,
)
from ..commerce import (
CommerceRefused,
build_message as commerce_build_message,
order_paid as commerce_order_paid,
paid_through as commerce_paid_through,
read_message as commerce_read_message,
)
from ..services import discover, discovery, dvm, lifecycle, nsite, telemetry
from ..storage import blossom_auth, negentropy, replication, store
from ..textile import types as textile_types
from ..textile import strand_event as textile_strand_event
from .conformance import Args, Op, Refused
OPS: dict[str, Op] = {}
[docs]def op(name: str, plane: str, about: str) -> Callable[[Callable[[Args], object]], Callable[[Args], object]]:
def deco(fn: Callable[[Args], object]) -> Callable[[Args], object]:
OPS[name] = Op(plane=plane, about=about, handler=fn)
return fn
return deco
def _r6(d: Mapping[str, float]) -> dict[str, float]:
return {k: round(v, 6) for k, v in d.items()}
def _items(v: Any) -> list[tuple[int, str]]:
return [(int(t), str(i)) for t, i in v]
def _refuse(fn: Callable[[], object], *exc: type[BaseException]) -> object:
try:
return fn()
except exc as e:
raise Refused(str(e))
def _int(value: object, what: str = 'argument') -> int:
"""An integer argument. JSON integers only: int() also took "12",
12.0 and True, so a vector that spelt a number wrongly got an answer
from one implementation and bad_args from the other."""
if not store.is_int(value):
raise ValueError('%s must be a JSON integer' % what)
return value # type: ignore[return-value]
# ---------------------------------------------------------------- identity & keys
@op('did.key', 'identity', 'did:key of a key kind over raw hex (node = x-only hex)')
def _did_key(a: Args) -> object:
raw = bytes.fromhex(a['raw'])
if a['kind'] == 'node':
return _refuse(lambda: did.node_did_key(a['raw']), ValueError)
return _refuse(lambda: did.did_key(a['kind'], raw), ValueError)
@op('did.parse', 'identity', '{method, node[, kind]} of a did:nostr / did:key / did:peer, or refused')
def _did_parse(a: Args) -> object:
return _refuse(lambda: did.parse(a['did']), ValueError)
@op('did.operator_parse', 'identity', '{method, did, pubkey, slug, refusal} of an operator DID (bare hex, did:nostr, did:group), or refused')
def _did_operator_parse(a: Args) -> object:
return _refuse(lambda: did.parse_operator(a['did']), ValueError)
@op('did.peer', 'identity', 'did:peer:2 of node x-only hex, agreement hex or null, DIDComm service or null')
def _did_peer(a: Args) -> object:
agr = bytes.fromhex(a['agreement']) if a.get('agreement') else None
return _refuse(lambda: did.did_peer(a['node'], agr, a.get('service')), ValueError)
@op('did.peer_parse', 'identity', '{node, agreement, service} read back from a did:peer:2, or refused')
def _did_peer_parse(a: Args) -> object:
return _refuse(lambda: did.parse_did_peer(a['did']), ValueError)
@op('did.document', 'identity', 'the resolved node profile for a kind 11801, aliases included')
def _did_document(a: Args) -> object:
return did.document(a['descriptor'])
@op('crypto.pubkey', 'identity', 'x-only public key of a secret key')
def _pubkey(a: Args) -> object:
return crypto.pubkey(a['sk'])
@op('crypto.ecdh_x', 'identity', 'x coordinate of the ECDH shared point')
def _ecdh(a: Args) -> object:
return crypto.ecdh_x(a['sk'], a['pk'])
@op('crypto.hkdf', 'identity', 'HKDF-SHA256 (RFC 5869); ikm/info/salt hex, length bytes')
def _hkdf(a: Args) -> object:
return crypto.hkdf(bytes.fromhex(a['ikm']), bytes.fromhex(a['info']), bytes.fromhex(a['salt']),
_int(a.get('length', 32), 'length')).hex()
@op('crypto.schnorr_sign', 'identity', 'BIP-340 signature of a 32-byte message with zero aux')
def _sign(a: Args) -> object:
return crypto.schnorr_sign(bytes.fromhex(a['msg']), a['sk'])
@op('event.verify', 'identity', 'id and signature of a Nostr event check out')
def _verify(a: Args) -> object:
return store.verify_event(a['event'])
@op('event.expiration', 'identity', 'NIP-40 expiration of an event, or null: the first well-formed tag, ASCII digits only')
def _expiration(a: Args) -> object:
return store.expiration(a['event'])
@op('descriptor.validate', 'identity', 'problems a kind 11801 has at a given clock')
def _desc_validate(a: Args) -> object:
return identity.validate_descriptor(a['event'], now=_int(a['now'], 'now'))
@op('protocol.version', 'identity', '[name, major, minor] of a fleetmesh protocol identifier, or null')
def _proto_version(a: Args) -> object:
if not isinstance(a['identifier'], str):
raise ValueError('identifier must be a string')
v = identity.protocol_version(a['identifier'])
return list(v) if v is not None else None
@op('blinding.derive', 'identity', 'blinding scalar d from shared x, info and salt strings')
def _blind(a: Args) -> object:
return crypto.hkdf(bytes.fromhex(a['shared']), a['info'].encode(), a['salt'].encode()).hex()
@op('projection.canonical_relay', 'identity', 'canonical spelling of a relay URL, or refused')
def _canon(a: Args) -> object:
return _refuse(lambda: projection.canonical_relay(a['url']), ValueError)
@op('projection.relay_endpoints', 'identity', 'relay endpoints a descriptor advertises')
def _endpoints(a: Args) -> object:
return projection.relay_endpoints({'tags': a['tags']})
@op('projection.rank', 'identity', 'rank by outcome table')
def _rank(a: Args) -> object:
return projection.RANK
@op('projection.project', 'identity', 'NIP-85 assertions from one report')
def _project(a: Args) -> object:
return _refuse(lambda: projection.project(a['report'], a['endpoints']), ValueError)
@op('projection.check', 'identity', 'problems an assertion has against its report ([] = holds)')
def _project_check(a: Args) -> object:
return projection.check_projection(a['event'], a['report'], a['endpoints'])
@op('discovery.network', 'identity', 'NIP-66 network label of a URL')
def _network(a: Args) -> object:
return discovery.network(a['url'])
@op('discovery.events', 'identity', 'NIP-66 discovery events from a descriptor and NIP-11 document')
def _disc_events(a: Args) -> object:
return discovery.discovery(a['descriptor'], a['nip11'], a['shards'])
@op('discovery.check', 'identity', 'problems a discovery event has against its descriptor')
def _disc_check(a: Args) -> object:
return discovery.check_discovery(a['event'], a['descriptor'])
@op('nip44.conversation_key', 'identity', 'NIP-44 conversation key from sk and pk')
def _n44key(a: Args) -> object:
return nip44.conversation_key(a['sk'], a['pk']).hex()
@op('nip44.encrypt', 'identity', 'NIP-44 v2 payload with a given nonce')
def _n44enc(a: Args) -> object:
return nip44.encrypt(a['plaintext'], bytes.fromhex(a['key']), bytes.fromhex(a['nonce']))
@op('nip44.decrypt', 'identity', 'NIP-44 v2 plaintext')
def _n44dec(a: Args) -> object:
return nip44.decrypt(a['payload'], bytes.fromhex(a['key']))
@op('nip44.padded_len', 'identity', 'padded length for an unpadded length')
def _n44pad(a: Args) -> object:
return _refuse(lambda: nip44.calc_padded_len(_int(a['n'], 'n')), nip44.Nip44Error)
@op('giftwrap.constants', 'identity', 'seal/live/stored kinds, skew max and retention')
def _gwconst(a: Args) -> object:
return {'kinds': {'seal': giftwrap.SEAL, 'live': giftwrap.WRAP_LIVE, 'stored': giftwrap.WRAP_STORED},
'skew_max': giftwrap.SKEW_MAX, 'retention': giftwrap.RETENTION}
@op('giftwrap.unwrap', 'identity', 'open a wrap for a recipient: {payload, from}, or refused')
def _unwrap(a: Args) -> object:
def go() -> object:
payload, who = giftwrap.unwrap(a['wrap'], a['recipient_sk'])
return {'payload': payload, 'from': who}
return _refuse(go, giftwrap.GiftWrapError)
@op('giftwrap.wrap_kind_allowed', 'identity', 'refusal text when wrapping a kind the profile forbids')
def _wrapkind(a: Args) -> object:
if not store.is_hex64(a['sender_sk']) or not store.is_hex64(a['recipient_pk']):
raise ValueError('sender_sk and recipient_pk are 64 hex')
return _refuse(lambda: giftwrap.wrap(a['payload'], a['sender_sk'], a['recipient_pk'], _int(a['now'], 'now'),
kind=_int(a['kind'], 'kind')) and None, giftwrap.GiftWrapError)
@op('bech32.npub', 'identity', 'npub of a hex pubkey')
def _npub(a: Args) -> object:
return bech32.bech32_encode('npub', bytes.fromhex(a['pubkey']))
# ------------------------------------------------------------ store & reconciliation
@op('fingerprint.varint', 'store', 'negentropy varint encoding')
def _varint(a: Args) -> object:
return replication.varint(_int(a['n'], 'n')).hex()
@op('fingerprint.of', 'store', 'range fingerprint of a set of event ids')
def _fp(a: Args) -> object:
return replication.fingerprint(a['ids'])
@op('fingerprint.union', 'store', 'fingerprint of two disjoint id sets composed')
def _fpu(a: Args) -> object:
return replication.fingerprint_union(a['a'], a['b'])
@op('receipt_chain.sha256', 'store', 'canonical JSON and sha256 of a receipt link')
def _chain(a: Args) -> object:
canon = crypto.canonical(a['receipt'])
return {'canonical': canon.decode(), 'sha256': hashlib.sha256(canon).hexdigest()}
@op('envelope.verify', 'store', 'problems a delivery envelope path has ([] = verifies)')
def _env(a: Args) -> object:
return replication.verify_envelope(a['envelope'])
@op('envelope.hop_message', 'store', 'sha256 hop message for domain|event|prev|at')
def _hop(a: Args) -> object:
return hashlib.sha256(('%s|%s|%s|%d' % (a['domain'], a['event_id'], a['prev'], _int(a['at'], 'at'))).encode()).hexdigest()
@op('store.replay', 'store', 'insert events; result {enumerate: [id], ranges: [fingerprint hex, one per range in order]}')
def _store(a: Args) -> object:
st = store.MemoryStore()
now = _int(a['now'], 'now')
for e in a['events']:
st.insert_event(e, now)
return {'enumerate': st.enumerate_range({}, 0, 2 ** 31, now),
'ranges': [st.fingerprint_range(r['filter'], r['since'], r['until'], now) for r in a['ranges']]}
@op('negentropy.version', 'store', 'protocol version byte, hex')
def _nver(a: Args) -> object:
return '%02x' % negentropy.VERSION
@op('negentropy.encode', 'store', 'encode ranges: [[timestamp, prefix_hex, mode, payload], ...]')
def _nenc(a: Args) -> object:
rs = []
for ts, prefix, mode, payload in a['ranges']:
p = bytes.fromhex(payload) if mode == negentropy.FINGERPRINT else payload
rs.append((negentropy.Bound(int(ts), bytes.fromhex(prefix)), int(mode), p))
return negentropy.encode_message(rs).hex()
@op('negentropy.decode', 'store', 'decode a message to [[timestamp, prefix_hex, mode], ...]')
def _ndec(a: Args) -> object:
return [[b.timestamp, b.prefix.hex(), m] for b, m, _p in negentropy.decode_message(bytes.fromhex(a['message']))]
@op('negentropy.minimal_bound', 'store', 'shortest prefix separating previous from item')
def _nmb(a: Args) -> object:
prev = tuple(a['previous']) if a.get('previous') else None
return negentropy.minimal_bound(prev, tuple(a['item'])).prefix.hex()
@op('negentropy.reconcile', 'store', 'have/need after a full reconciliation')
def _nrec(a: Args) -> object:
got = negentropy.reconcile(_items(a['client_items']), _items(a['server_items']))
return {'have': got['have'], 'need': got['need']}
@op('lifecycle.endpoints_digest', 'store', 'digest of a descriptor endpoint tag set')
def _edig(a: Args) -> object:
return lifecycle.endpoints_digest(a['endpoint_tags'])
@op('coverage.check', 'store', 'problems a coverage claim has for a node class')
def _covchk(a: Args) -> object:
return coverage.check_coverage(a['event'], a.get('node_class'))
@op('coverage.handover_id', 'store', 'id of a handover artefact')
def _hoid(a: Args) -> object:
return coverage.handover_id(a['artefact'])
@op('coverage.handover_verify', 'store', 'handover verifies under its signer')
def _hover(a: Args) -> object:
return coverage.verify_handover(a['artefact'], a.get('signer'))
@op('coverage.handover_check', 'store', 'problems a handover artefact has')
def _hochk(a: Args) -> object:
return coverage.check_handover(a['artefact'])
@op('coverage.inline_handover', 'store', 'the handover a replica claim carries inline')
def _hoinl(a: Args) -> object:
return coverage.inline_handover(a['claim'])
@op('coverage.barred_reporter', 'store', 'why a reporter is barred from reporting on a claim, or null')
def _bar(a: Args) -> object:
return coverage.barred_reporter(a['claim'], a['reporter'])
@op('coverage.handover_chain', 'store', 'the from-pubkeys of a claim\'s handover chain, in order')
def _hochain(a: Args) -> object:
return [h['from'] for h in coverage.handover_chain(a['claim'])]
@op('coverage.chain_check', 'store', 'problems a bare handover chain has')
def _chchk(a: Args) -> object:
return coverage.check_chain(a['chain'])
@op('heartbeat.is_retiring', 'store', 'heartbeat announces retirement')
def _ret(a: Args) -> object:
return lifecycle.is_retiring(a['event'])
@op('heartbeat.check', 'store', '[problems, notices] of a heartbeat against a descriptor')
def _hbchk(a: Args) -> object:
p, n = lifecycle.check_heartbeat(a['event'], a['descriptor'])
return [p, [list(x) for x in n]]
@op('telemetry.constants', 'store', 'kind and bin labels')
def _tmc(a: Args) -> object:
return {'kind': telemetry.KIND, 'bins': list(telemetry.BINS)}
@op('telemetry.bin_of', 'store', 'order-of-magnitude bin of a counter')
def _tmb(a: Args) -> object:
return telemetry.bin_of(_int(a['n'], 'n'))
@op('telemetry.event', 'store', 'the kind 21802 event for counters (unsigned fields)')
def _tme(a: Args) -> object:
return telemetry.telemetry(a['pubkey'], _int(a['created_at'], 'created_at'), _int(a['sample_window'], 'sample_window'), a['counters'],
expiration=a.get('expiration'))
@op('telemetry.read', 'store', 'metrics read back from a telemetry event')
def _tmr(a: Args) -> object:
return telemetry.read(a['event'])
@op('telemetry.check', 'store', 'problems a telemetry event has')
def _tmk(a: Args) -> object:
return telemetry.check_telemetry(a['event'])
@op('blossom.auth_event', 'store', 'BUD-01 authorization event (unsigned fields given signer)')
def _baev(a: Args) -> object:
return blossom_auth.auth_event(a['signer_sk'], a['verb'], a['sha256'], _int(a['now'], 'now'))
@op('blossom.auth_header', 'store', 'Authorization header for an auth event')
def _bah(a: Args) -> object:
return blossom_auth.auth_header(a['event'])
@op('blossom.parse_auth_header', 'store', 'auth event from an Authorization header')
def _baph(a: Args) -> object:
return blossom_auth.parse_auth_header(a['header'])
@op('blossom.x_tag', 'store', 'the x tag of an auth event')
def _bax(a: Args) -> object:
return blossom_auth.x_tag(a['event'])
@op('blossom.check_auth', 'store', 'pubkey an auth event authorizes for verb/now/sha, or refused')
def _back(a: Args) -> object:
return _refuse(lambda: blossom_auth.check_auth(a['event'], a['verb'], _int(a['now'], 'now'), a.get('sha256')),
blossom_auth.AuthError)
@op('blossom.mirror_request', 'store', 'BUD-04 mirror request body')
def _bamr(a: Args) -> object:
return blossom_auth.mirror_request(a['source'], a['sha256'])
@op('blossom.mirror_response', 'store', 'blob descriptor after a mirror')
def _bamp(a: Args) -> object:
return blossom_auth.mirror_response(a['sha256'], _int(a['size'], 'size'), a['type'], _int(a['uploaded'], 'uploaded'), a['cid'])
# -------------------------------------------------------------- peering & accounting
@op('window.evaluate', 'peering', 'severity of a window from limits, measured and claimed')
def _wev(a: Args) -> object:
return window.evaluate_window(a['limits'], a['measured'], a['claimed'])
@op('window.adjust', 'peering', '{limits_after, tier_after} after a severity; refused for a severity or tier not on the ladder')
def _wadj(a: Args) -> object:
def go() -> object:
after, tier, _ = window.adjust(a['limits'], a['tier'], a['severity'], a.get('measured'))
return {'limits_after': _r6(after), 'tier_after': tier}
return _refuse(go, ValueError)
@op('window.opening_limits', 'peering', 'opening limits of a tier')
def _wopen(a: Args) -> object:
return window.opening_limits(a['tier'])
@op('window.ceilings', 'peering', 'ceilings of a tier')
def _wceil(a: Args) -> object:
return window.ceilings(a['tier'])
@op('trust.reporter_weight', 'peering', 'weight of a reporter')
def _tw(a: Args) -> object:
return round(window.reporter_weight(a['tier'], _int(a['clean_windows'], 'clean_windows'), _int(a['contradicted'], 'contradicted'), _int(a['evaluated'], 'evaluated')), 6)
@op('trust.view', 'peering', 'own view given weighted reports')
def _tv(a: Args) -> object:
return window.view(a['own_severity'], a['reports'])
@op('capacity.pressure', 'peering', '{pressure, binding} from measured against total')
def _cp(a: Args) -> object:
p, b = capacity.pressure(a['measured'], a['total'])
return {'pressure': round(p, 6), 'binding': b}
@op('capacity.rungs', 'peering', 'ladder rungs at a pressure')
def _cr(a: Args) -> object:
return capacity.rungs(float(a['pressure']))
@op('capacity.shed_floor', 'peering', 'the floor a shed never crosses, from probation ceilings')
def _csf(a: Args) -> object:
return capacity.shed_floor(a['probation'])
@op('peering.offer', 'peering', 'an acceptor\'s reply to a proposal (type, and code or tier/limits/transports)')
def _offer(a: Args) -> object:
acc = a['acceptor']
node = peering.Node(acc['sk'], acc['descriptor'], peering.Policy(**acc['policy']), acc['class'])
reply = node.offer(json.loads(json.dumps(a['proposal'])), a['peer_descriptor'], _int(a['now'], 'now'))
body = reply['body']
kind = reply['type'].rsplit('/', 1)[1]
if kind == 'decline':
return {'type': kind, 'code': body.get('code')}
return {'type': kind, 'tier': body.get('tier'), 'limits': body.get('limits'), 'transports': body.get('transports')}
@op('receipt.link', 'peering', 'link hash of a receipt body (signature excluded)')
def _rlink(a: Args) -> object:
return accounting.link(a['receipt'])
@op('receipt.sign', 'peering', 'signature over an unsigned receipt')
def _rsign(a: Args) -> object:
return accounting.sign_receipt(a['receipt'], a['sk']).get('sig')
@op('receipt.verify', 'peering', 'a receipt verifies for its subject')
def _rver(a: Args) -> object:
return accounting.verify_receipt(a['receipt'], a['subject'])
@op('report.evidence_id', 'peering', 'evidence id of a signed receipt')
def _evid(a: Args) -> object:
return reports.evidence_id(a['receipt'])
@op('report.admissible', 'peering', 'a report is admissible given which referenced events resolve')
def _adm(a: Args) -> object:
resolve: Mapping[str, Any] = a['resolve']
def look(id_: str) -> Any:
return resolve.get(id_)
return reports.admissible(a['event'], a['grant_publisher'], look, lambda e: True)[0]
@op('standing.tell', 'peering', 'standing tell after a sequence of windows')
def _tell(a: Args) -> object:
led = standing.Ledger()
if not a['windows']:
return None # nothing observed: no tell, in every implementation
for i, sev in enumerate(a['windows']):
led.record(a['subject'], _int(a.get('epoch0', 496380), 'epoch0') + i, sev, a['tier'])
return led.tell(a['subject'])
@op('complaint.may_publish', 'peering', 'whether a complaint of a severity may be published now')
def _mp(a: Args) -> object:
ws = a.get('window_seconds', 3600)
if not store.is_int(ws) or ws <= 0:
raise ValueError('window_seconds must be a positive integer')
if not isinstance(a['reachable'], bool):
raise ValueError('reachable must be true or false')
return complaint.may_publish(a['severity'], _int(a['now'], 'now'), notice_at=a['notice_at'],
window_seconds=ws, reachable=a['reachable'])
@op('discover.protocols', 'peering', 'protocol ids a descriptor discloses')
def _dprot(a: Args) -> object:
return sorted(peering.Node('11' * 32, a['descriptor']).protocols)
@op('discover.parse', 'peering', 'query list of a discover-features queries message')
def _dparse(a: Args) -> object:
return discover.query_list(a['queries'])
@op('discover.answer', 'peering', 'the disclose message a descriptor answers a query with')
def _dans(a: Args) -> object:
node = peering.Node('11' * 32, a['descriptor'])
return discover.disclose(a['from'], a['to'], a['thid'], node.disclose(a.get('parsed') or None))
@op('discover.ids', 'peering', 'disclosed ids of a disclose message')
def _dids(a: Args) -> object:
return discover.disclosed_ids(a['disclose'])
# ------------------------------------------------------------------ transport & doors
@op('relaylist.filter', 'transport', 'the REQ filter that fetches a pubkey\'s kind 10050')
def _rlf(a: Args) -> object:
return relaylist.filter_for(a['pubkey'])
@op('relaylist.build', 'transport', 'the tags of the kind 10050 a node publishes for its own inbox')
def _rlb(a: Args) -> object:
rs = a['relays']
if not isinstance(rs, list) or not all(isinstance(r, str) for r in rs):
raise ValueError('relays must be a list of strings')
try:
return relaylist.build(rs)
except ValueError as e:
return {'refused': str(e)}
@op('relaylist.dm_relays', 'transport', 'inbox relays read from a kind 10050 event')
def _rld(a: Args) -> object:
if not isinstance(a['event'], dict):
raise ValueError('event must be an object')
return relaylist.dm_relays(a['event'])
@op('control.open_sealed', 'transport', 'open a sealed control/1.0 {wrap} with {recipient_sk} at {now} inside {window} seconds: {message, sender}, or refused <code> (not_control, from_mismatch, to_mismatch, stale, body_invalid)')
def _control_open_sealed(a: Args) -> object:
try:
message, sender = control.open_sealed(a['wrap'], a['recipient_sk'],
_int(a['now'], 'now'), _int(a['window'], 'window'))
except control.ControlRefused as e:
raise Refused(e.code)
except (giftwrap.GiftWrapError, ValueError) as e:
# The transport refused before the message could be judged: not this
# path's five codes, but still a refusal a harness can pin.
raise Refused(str(e))
return {'message': message, 'sender': sender}
# ---------------------------------------------------------------------- services
@op('nip90.constants', 'services', 'default kinds and feedback states')
def _dvmc(a: Args) -> object:
return {'default_kinds': list(dvm.DEFAULT_KINDS), 'feedback_states': list(dvm.FEEDBACK_STATES)}
@op('nip90.parse', 'services', '{is_request, parsed, executor, job} of a job request')
def _dvmp(a: Args) -> object:
ev = a['request']
parsed = dvm.parse_request(ev)
return {'is_request': dvm.is_request(ev), 'parsed': parsed, 'executor': dvm.executor_of(parsed),
'job': _refuse(lambda: dvm.request_to_job(ev), dvm.DVMError)}
@op('nip90.result_kind', 'services', 'result kind for a request kind')
def _dvmrk(a: Args) -> object:
return dvm.result_kind(_int(a['kind'], 'kind'))
@op('nip90.feedback', 'services', 'a feedback event (unsigned fields given signer)')
def _dvmf(a: Args) -> object:
return dvm.feedback(a['signer_sk'], a['request'], a['status'], _int(a['now'], 'now'))
@op('nip90.result', 'services', 'a result event (unsigned fields given signer)')
def _dvmr(a: Args) -> object:
return dvm.result(a['signer_sk'], a['request'], a['content'], _int(a['now'], 'now'),
amount_msat=_int(a.get('amount_msat', 0), 'amount_msat'), commit=str(a.get('commit', '')),
extra_tags=a.get('extra_tags'))
@op('paidfetch.quote', 'services', '{headers, body} of a 402 quote')
def _pfq(a: Args) -> object:
q = a['quote']
quote = paidfetch.Quote(q['sha256'], q['size'], [paidfetch.Item(i['to'], i['payee'], i['msat']) for i in q['items']],
q['expires'], q['offers'])
return {'headers': quote.headers(), 'body': quote.body(a['error'])}
@op('paidfetch.sat_ceil', 'services', 'msat rounded up to sat')
def _pfs(a: Args) -> object:
return paidfetch.msat_to_sat_ceil(_int(a['msat'], 'msat'))
@op('paidfetch.tokens', 'services', 'tokens of an X-Cashu header')
def _pft(a: Args) -> object:
return paidfetch.tokens_of(a['header'])
def _ref(r: Any) -> object:
return dataclasses.asdict(r) if r else None
@op('nsite.base36', 'services', 'base36 of a hex pubkey')
def _ns36(a: Args) -> object:
return nsite.b36_encode(bytes.fromhex(a['pubkey']))
@op('nsite.base36_decode', 'services', 'hex pubkey of a base36 label, or null')
def _ns36d(a: Args) -> object:
raw = nsite.b36_decode(a['label'])
return raw.hex() if raw else None
@op('nsite.label', 'services', '{ref, filter, canonical} of a site label')
def _nsl(a: Args) -> object:
r = nsite.parse_label(a['label'])
return {'ref': _ref(r), 'filter': r.filter() if r else None, 'canonical': r.label if r else None}
@op('nsite.host', 'services', 'site ref of a host under suffixes')
def _nsh(a: Args) -> object:
return _ref(nsite.parse_host(a['host'], a['suffixes']))
@op('nsite.txt', 'services', 'site ref of a TXT binding')
def _nst(a: Args) -> object:
return _ref(nsite.parse_txt_binding(a['txt']))
@op('nsite.manifest', 'services', '{paths, aggregate, domains, servers} of a manifest')
def _nsm(a: Args) -> object:
m = a['manifest']
return {'paths': nsite.paths_of(m), 'aggregate': nsite.aggregate(m), 'domains': sorted(nsite.claimed_domains(m)),
'servers': nsite.blossom_servers(m, a.get('user_servers'), a.get('defaults', []))}
@op('nsite.resolve', 'services', 'resolution of a request path against manifest paths')
def _nsr(a: Args) -> object:
return _ref(nsite.resolve_path(a['paths'], a['path']))
@op('nsite.guess_type', 'services', 'content type of a path')
def _nsg(a: Args) -> object:
return nsite.guess_type(a['path'])
# ---------------------------------------------------------------- web auth (fleetmesh-auth wire)
# Pinned by vectors/web-auth.json. Every op is one call with no state of its
# own: webauth.verify is handed the challenges a node has issued and the
# event ids it has already seen, so a replay is a vector, not a sequence.
def _webauth_refused(fn: Callable[[], object]) -> object:
try:
return fn()
except web_auth.AuthRefused as e:
raise Refused(e.code)
@op('webauth.constants', 'identity', 'minted/accepted ticket prefixes and challenge schemes, ticket bounds, kinds, error codes')
def _wa_constants(a: Args) -> object:
return {
'ticket_prefix': web_auth.TICKET_PREFIX,
'accepted_ticket_prefixes': list(web_auth.ACCEPTED_TICKET_PREFIXES),
'ticket_content_prefix': web_auth.TICKET_CONTENT_PREFIX,
'ticket_ttl': [web_auth.TICKET_TTL_MIN_SEC, web_auth.TICKET_TTL_MAX_SEC],
'ticket_future_skew': web_auth.TICKET_FUTURE_SKEW_SEC,
'ticket_kind': web_auth.NIP98_HTTP_AUTH_KIND,
'auth_event_kinds': [web_auth.NIP98_HTTP_AUTH_KIND, web_auth.NIP42_AUTH_KIND],
'auth_scheme': web_auth.AUTH_SCHEME,
'accepted_schemes': list(web_auth.ACCEPTED_SCHEMES),
'error_codes': sorted(web_auth.ERRORS),
}
@op('webauth.challenge_message', 'identity', 'the signed challenge string, its sha256, and the digest under every accepted scheme')
def _wa_message(a: Args) -> object:
scheme = a.get('scheme', web_auth.AUTH_SCHEME)
msg = web_auth.challenge_message(a['challenge'], a['origin_url'], scheme=scheme)
return {'message': msg, 'sha256': hashlib.sha256(msg.encode('utf-8')).hexdigest(),
'digests': web_auth.challenge_digests(a['challenge'], a['origin_url'])}
def _wa(a: Args, *, ttl: int = web_auth.DEFAULT_CHALLENGE_TTL_SEC) -> web_auth.FederatedWebAuth:
return web_auth.FederatedWebAuth(origin_url=a['origin_url'], node_did=a.get('node_did', ''),
scheme=a.get('scheme', web_auth.AUTH_SCHEME),
challenge_ttl_sec=_int(a.get('challenge_ttl_sec', ttl), 'challenge_ttl_sec'),
clock=lambda: _int(a['now'], 'now'))
@op('webauth.issue_challenge', 'identity', 'the challenge reply for a fixed challenge id at a given clock')
def _wa_issue(a: Args) -> object:
return dict(_wa(a).issue_challenge(now=_int(a['now'], 'now'), challenge=a['challenge']))
@op('webauth.ticket_mint', 'identity', 'a portable ticket (bundle and fmpass_ string) from a secret key, fixed nonce and clock')
def _wa_mint(a: Args) -> object:
if not store.is_hex64(a['sk']):
raise ValueError('sk is 64 hex')
doc = web_auth.encode_portable_ticket(
a['sk'], home_instance_url=a.get('home_instance_url', ''), home_node_did=a.get('home_node_did', ''),
target_url=a.get('target_url', ''), ttl_sec=_int(a.get('ttl_sec', web_auth.DEFAULT_CHALLENGE_TTL_SEC), 'ttl_sec'),
identity_event=a.get('identity_event'), now=_int(a['now'], 'now'), nonce_hex=a['nonce_hex'],
prefix=a.get('prefix', web_auth.TICKET_PREFIX))
return json.loads(json.dumps(doc))
@op('webauth.ticket_decode', 'identity', 'the bundle inside a ticket string of any accepted prefix, or refused ticket_malformed')
def _wa_decode(a: Args) -> object:
return _webauth_refused(lambda: dict(web_auth.decode_portable_ticket(a['ticket'])))
@op('webauth.verify', 'identity',
'verify a login body given the challenges issued and event ids seen: the verified result, or refused <code>')
def _wa_verify(a: Args) -> object:
now = _int(a['now'], 'now')
wa = _wa(a)
for ch in a.get('issued_challenges', []):
wa.issue_challenge(now=_int(ch.get('issued_at', now), 'issued_at'), challenge=ch['challenge'])
for used in a.get('used_event_ids', []):
wa.consume_auth_event_id(used, '', now + 3600, now=now)
return _webauth_refused(lambda: wa.verify_login_payload(
a['body'], now=now, expected_identity_kind=a.get('expected_identity_kind')).to_dict())
@op('auth.normalize_payload', 'identity', 'a login body with method and short-field aliases filled in')
def _auth_norm(a: Args) -> object:
return auth_wire.normalize_login_payload(a['payload'])
@op('auth.expand_roles', 'identity', 'roles closed under implication, in canonical order')
def _auth_roles(a: Args) -> object:
return auth_wire.expand_roles(list(a['roles']))
@op('auth.principal', 'identity', 'the principal dict the wire shows for a set of principal fields')
def _auth_principal(a: Args) -> object:
return auth_wire.principal_dict(a['fields'])
# ---------------------------------------------------------------- operations: release channel
def _rel_info(r: object) -> object:
return r.as_dict() if isinstance(r, release.ReleaseInfo) else r
@op('release.semver', 'operations', '[major, minor, patch, prerelease] of a semver, or refused')
def _rsv(a: Args) -> object:
p = release.parse_semver(a['version'])
if p is None:
raise Refused('not a semver: %r' % (a['version'],))
return list(p)
@op('release.compare', 'operations', '-1/0/1 for a <,==,> b; prerelease below its release; refused when either is not a semver')
def _rcmp(a: Args) -> object:
return _refuse(lambda: release.compare(a['a'], a['b']), ValueError)
@op('release.classify', 'operations', "'major'|'minor'|'patch' when candidate is newer than running, else null")
def _rcls(a: Args) -> object:
return _refuse(lambda: release.classify(a['running'], a['candidate']), ValueError)
@op('release.parse', 'operations', 'a kind 9900 read for {release_key[, name]}: the ReleaseInfo dict, or the refusal string')
def _rparse(a: Args) -> object:
return _rel_info(release.parse_release_event(a['event'], a['release_key'], a.get('name', release.NAME)))
@op('release.revocation', 'operations', '[revoked event id, reason] of a kind 9901 by release_key that verifies, else null')
def _rrev(a: Args) -> object:
rv = release.parse_revocation(a['event'], a['release_key'])
return list(rv) if rv else None
@op('release.select', 'operations', 'newest_compatible / incompatible_newer / refused / revoked from events for {release_key, running, digest[, name, already_revoked]}')
def _rsel(a: Args) -> object:
return release.select(a['events'], a['release_key'], a['running'], a['digest'], a.get('name', release.NAME),
a.get('already_revoked', ())).as_dict()
# ---------------------------------------------------------------- private networks, fleets, grants
# Admission (network.*, relay.allow) sits in the peering plane, the fleet token
# and fleet/grant reading in identity: the six planes of docs/implementing.md
# are an architectural map, and a seventh is a documentation decision, not an
# op-catalogue one.
def _now(a: Args) -> int | None:
return _int(a['now'], 'now') if a.get('now') is not None else None
@op('network.definition_validate', 'peering', 'problems a kind 30830 has at a given clock ([] = well formed)')
def _net_validate(a: Args) -> object:
return definition.validate(a['event'], now=_now(a))
@op('network.current', 'peering', '{current}: the newest unexpired well-formed kind 30830 at {id} among events at {now}, or null')
def _net_current(a: Args) -> object:
return {'current': definition.current(a['events'], a['id'], _int(a['now'], 'now'))}
@op('network.roster', 'peering', '{members, unresolved}: member node pubkeys of a definition given the descriptors seen on its relays')
def _net_roster(a: Args) -> object:
return _refuse(lambda: roster.roster(a['definition'], a.get('descriptors', []), _now(a)), ValueError)
@op('network.join_decide', 'peering', '{verdict, code, reason} for a sender under {policy, roster[, credential, issuers, now]}')
def _net_join(a: Args) -> object:
return _refuse(lambda: join.decide(a.get('policy'), a.get('roster'), a['sender'], a.get('credential'),
a.get('issuers', []), _now(a)), ValueError)
@op('join_request.open', 'peering', 'open a sealed network/1.0 {wrap} with {recipient_sk} against the current {definition} at {now}, a created_time no older than {max_age} seconds and no more than {skew} seconds ahead: the join-request, or refused <code> (not_join_request, from_mismatch, to_mismatch, stale, wrong_network, not_approved, already_member, bad_descriptor, controller_unsupported)')
def _join_request_open(a: Args) -> object:
try:
return join_request.open(a['wrap'], a['recipient_sk'], a['definition'],
_int(a['now'], 'now'), _int(a['max_age'], 'max_age'), _int(a['skew'], 'skew'))
except join_request.JoinRefused as e:
raise Refused(e.code)
except (giftwrap.GiftWrapError, ValueError) as e:
# The transport (or a malformed definition) refused before the request
# could be judged: not this op's codes, but still a refusal to pin.
raise Refused(str(e))
@op('join_request.approve', 'peering', 'the new signed kind 30830 that admits {node} to {definition}, signed by the controller {controller_sk} at {created_at}: the current tags plus one member tag, everything else unchanged, created_at strictly later; refused already_member when the roster already names the node')
def _join_request_approve(a: Args) -> object:
try:
return join_request.approve(a['definition'], a['node'], a['controller_sk'],
_int(a['created_at'], 'created_at'))
except join_request.JoinRefused as e:
raise Refused(e.code)
except ValueError as e:
raise Refused(str(e))
@op('network.descriptor_split', 'peering', '{public, private} unsigned templates of a kind 11801 for {networks}; public carries no network/expose tag')
def _net_split(a: Args) -> object:
return _refuse(lambda: descriptor_split.split(a['descriptor'], a['networks']), ValueError)
@op('relay.allow', 'peering', 'whether a roster-protected relay lets {pubkey} do {op} (auth|event|req) on {kind}')
def _relay_allow(a: Args) -> object:
return relay_allow.allow(a.get('roster', []), a['pubkey'], a.get('kind'), a['op'])
@op('enrol.token_issue', 'identity', '{token, ucan, id, operator, pubkey, node, with, can, tier, exp, nbf} of a fleet/enrol grant minted by {sk} for {node} (aud) with a fixed {nonce}, fmenrol1-encoded')
def _enrol_issue(a: Args) -> object:
return _refuse(lambda: enrol_token.issue(a['sk'], a['node'], _int(a['exp'], 'exp'),
nbf=_int(a['nbf'], 'nbf') if a.get('nbf') is not None else None,
nonce=a.get('nonce')), ValueError)
@op('enrol.token_decode', 'identity', 'the grant an fmenrol1 token carries ({ucan, id, operator, node, with, can, tier, exp, nbf}), shape-checked only, or refused token_malformed | token_legacy')
def _enrol_decode(a: Args) -> object:
try:
return enrol_token.decode(a['token'])
except enrol_token.TokenRefused as e:
raise Refused(e.code)
@op('enrol.token_assemble', 'identity', 'the circle form of a fleet/enrol token: fmenrol1 + the member {copies} + the circle\'s kind 30834 {group_events}, ~-joined; or refused (shape)')
def _enrol_assemble(a: Args) -> object:
return _refuse(lambda: enrol_token.assemble(a['copies'], a['group_events']), ValueError)
@op('enrol.token_verify', 'identity', '{token, operator, pubkey, node, id, exp[, group_events, quorum]} of a token whose fleet/enrol grant verifies for {node} (aud) at {now} given {revocations} (a circle token: by quorum, against its own controller documents), or refused <grant code>')
def _enrol_verify(a: Args) -> object:
try:
return enrol_token.verify(a['token'], a['node'], _int(a['now'], 'now'), a.get('revocations', []))
except enrol_token.TokenRefused as e:
raise Refused(e.code)
@op('fleet.members', 'identity', 'sorted pubkeys of the current kind 11801s whose operator is {operator} in any spelling')
def _fleet_members(a: Args) -> object:
return _refuse(lambda: fleet.members(a['descriptors'], a['operator'], _now(a)), ValueError)
@op('roster.open', 'identity', 'open a kind 30835 {event} with the owner key {key}: {name, nodes}, or refused <code> (not_roster, not_author, bad_content, bad_shape)')
def _roster_open(a: Args) -> object:
try:
return roster.open(a['event'], a['key'])
except roster.RosterRefused as e:
raise Refused(e.code)
except ValueError as e:
raise Refused(str(e).split(chr(10))[0][:200])
@op('fleet.from_roster', 'identity', 'the roster {nodes} joined to {descriptors} and {heartbeats} by node pubkey at {now}: one entry per node, sorted, status online|stale|unknown')
def _fleet_from_roster(a: Args) -> object:
return fleet.from_roster(a['nodes'], a['descriptors'], a['heartbeats'], _int(a['now'], 'now'))
@op('brand.read_endorsement', 'identity', 'read a kind 1985 NIP-32 brand endorsement {event} at {now}: {namespace, brand, target, issuer, created_at, expiration}, or refused <code> (not_brand_label, wrong_namespace, bad_signature, expired, ttl_exceeded)')
def _brand_read_endorsement(a: Args) -> object:
try:
return brand.read_endorsement(a['event'], _now(a))
except brand.BrandRefused as e:
raise Refused(e.code)
@op('brand.read_claim', 'identity', "read a tool event {event}'s own NIP-32 brand self-label: {namespace, brand, kind, pubkey}, or refused <code> (not_a_tool, wrong_namespace, bad_signature, not_claimed)")
def _brand_read_claim(a: Args) -> object:
try:
return brand.read_claim(a['event'])
except brand.BrandRefused as e:
raise Refused(e.code)
@op('brand.members', 'identity', 'the sorted tool refs of a brand {brand} run by {authority}: tools both endorsed in {endorsements} and self-labelled in {claimed_events} at {now}, or refused brand_unsupported')
def _brand_members(a: Args) -> object:
try:
return brand.members(a['brand'], a['authority'], a.get('endorsements', []),
a.get('claimed_events', []), _now(a))
except brand.BrandRefused as e:
raise Refused(e.code)
except ValueError as e:
raise Refused(str(e).split(chr(10))[0][:200])
@op('product.read_fiber', 'store', 'the product fiber of {product} (its {mime, schema, digest, bao_root, canonical, byte_length}) or the fields read back from {fiber}: an optional {mime} must be the fleetmesh product MIME, or refused <code> (not_a_product, bad_mime, bad_price)')
def _product_read_fiber(a: Args) -> object:
try:
return product_read_fiber(a)
except ProductRefused as e:
raise Refused(e.code)
@op('product.verify_log', 'store', 'verify a product {product} and its lifecycle log: {product_id, count, version, digest, bao_root, active_recall_id, attested_stages, price_points, events} or refused <code> (not_a_product, bad_price, fiber_digest_mismatch, unknown_event_kind, event_wrong_product, bad_recall, bad_event_digest)')
def _product_verify_log(a: Args) -> object:
try:
return product_verify_log(a['product'])
except ProductRefused as e:
raise Refused(e.code)
@op('product.listing', 'services', 'build a kind 30402 NIP-99 listing for a product {strand} (with {listing_id, title, price, currency, frequency, description, status, categories}, price a GammaMarkets [amount, currency[, frequency]]), or read one back from {event}: {d, title, price, product_ref, status}; refused <code> (not_a_listing, bad_listing, bad_price, no_product_ref)')
def _product_listing(a: Args) -> object:
try:
if 'event' in a:
return product_listing.read_listing(a['event'])
return product_listing.build_listing(
a['strand'], listing_id=a['listing_id'], title=a['title'], price=a['price'],
currency=a.get('currency', 'USD'), frequency=a.get('frequency'),
description=a.get('description', ''), status=a.get('status'),
categories=a.get('categories', ()), now=_int(a['now'], 'now') if a.get('now') is not None else None)
except ProductRefused as e:
raise Refused(e.code)
@op('commerce.read_message', 'services', 'build a market-spec checkout message from {message} (kind 16 {type, p, order, amount, items, status, payments, expiration, subject} or a kind 17 receipt) or read one back from {event}: {kind, type, subject, order, p, amount, status, items, payments, expiration}; refused <code> (not_order_message, wrong_type, bad_amount, bad_payment, expired_request)')
def _commerce_read_message(a: Args) -> object:
try:
if 'event' in a:
now = _int(a['now'], 'now') if a.get('now') is not None else None
return commerce_read_message(a['event'], now=now)
return commerce_build_message(a['message'])
except CommerceRefused as e:
raise Refused(e.code)
@op('commerce.order_paid', 'services', 'whether {order} is paid under the fulfiller rule (plan D30): open the NIP-17 {statuses} with {key} against the maker of the kind 30402 {listing} at {now} -> {paid, order, maker, signer, status}, or refused <code> (not_order_message, wrong_type, not_sealed_by_maker, unknown_order, not_confirmed)')
def _commerce_order_paid(a: Args) -> object:
try:
return commerce_order_paid(a['order'], a.get('statuses', []), a['listing'], a['key'], _int(a['now'], 'now'))
except CommerceRefused as e:
raise Refused(e.code)
@op('commerce.paid_through', 'services', 'whether the current period of a recurring {listing} is covered at {now} by {orders} ([{order, period_start, paid}] as a fulfiller resolved them): {covered, through, period_seconds, order}, or refused for a listing with no price frequency')
def _commerce_paid_through(a: Args) -> object:
return commerce_paid_through(a.get('orders', []), a['listing'], _int(a['now'], 'now'))
@op('grant.coordinate', 'identity', '{ok, d, expected, problems}: whether a kind 30832 d is sha256 of its content')
def _grant_coord(a: Args) -> object:
return grant.coordinate(a['event'])
@op('grant.revoked', 'identity', 'whether a kind 30833 names {grant}')
def _grant_revoked(a: Args) -> object:
return grant.revoked(a.get('list'), a['grant'])
@op('grant.issue', 'identity', '{token, id, iss, aud, exp} of a kind 30832 grant minted by {sk} to {aud} for {with}, {can[]}, {tier}, {exp}[, nbf, poll, ratify_by, nonce, group, epoch, alg, created_at]; alg NIP01 (plan D21) signs the envelope event at created_at')
def _grant_issue(a: Args) -> object:
def mint() -> object:
g = grant.issue(a['sk'], a['aud'], a['with'], a['can'], a['tier'], _int(a['exp'], 'exp'),
nbf=None if a.get('nbf') is None else _int(a['nbf'], 'nbf'),
poll=a.get('poll'),
ratify_by=None if a.get('ratify_by') is None else _int(a['ratify_by'], 'ratify_by'),
nonce=a.get('nonce'), group=a.get('group'),
epoch=None if a.get('epoch') is None else _int(a['epoch'], 'epoch'),
alg=a.get('alg') or grant.ALG,
created_at=None if a.get('created_at') is None else _int(a['created_at'], 'created_at'))
return {'token': g['token'], 'id': g['id'], 'iss': g['iss'], 'aud': g['aud'], 'exp': g['exp']}
return _refuse(mint, ValueError)
@op('grant.decode', 'identity', 'the claims a grant token carries plus its id, shape-checked only, or refused token_malformed')
def _grant_decode(a: Args) -> object:
try:
return grant.decode(a['token'])
except grant.ChainRefused as e:
raise Refused(e.code)
@op('grant.envelope', 'identity', "the unsigned kind 30832 event for a BIP340 {token} at {created_at}; for a NIP01 token the signed event it was cut from (created_at is the token's own); or refused token_malformed")
def _grant_envelope(a: Args) -> object:
try:
return grant.envelope(a['token'], _int(a['created_at'], 'created_at'))
except grant.ChainRefused as e:
raise Refused(e.code)
@op('grant.template', 'identity', 'the unsigned kind 30832 event that any nostr event signer signs to mint a NIP01 token: {iss} (a pubkey or did:nostr), {aud}, {with}, {can[]}, {tier}, {exp}, {created_at}[, nbf, poll, ratify_by, nonce, group, epoch], or refused with the issue error')
def _grant_template(a: Args) -> object:
def build() -> object:
return grant.template(a['iss'], a['aud'], a['with'], a['can'], a['tier'], _int(a['exp'], 'exp'),
_int(a['created_at'], 'created_at'),
nbf=None if a.get('nbf') is None else _int(a['nbf'], 'nbf'),
poll=a.get('poll'),
ratify_by=None if a.get('ratify_by') is None else _int(a['ratify_by'], 'ratify_by'),
nonce=a.get('nonce'), group=a.get('group'),
epoch=None if a.get('epoch') is None else _int(a['epoch'], 'epoch'))
return _refuse(build, ValueError)
@op('grant.from_event', 'identity', '{token, id} of the NIP01 token a signed kind 30832 {event} carries, or refused token_malformed (not a NIP01 envelope, tags not those the claims derive, pubkey not the iss) or bad_signature')
def _grant_from_event(a: Args) -> object:
try:
return grant.from_event(a['event'])
except grant.ChainRefused as e:
raise Refused(e.code)
@op('grant.verify', 'identity', '{accepted, via, operator, grantee, depth, capability, tier, grants[, quorum]} when {chain} authorises {audience} to {can} on {resource} at {now} under {operator}[, revocations, group_events, early], or refused <code>')
def _grant_verify(a: Args) -> object:
try:
return grant.verify(a['chain'], a.get('operator'), a['can'], a['resource'], _int(a['now'], 'now'),
a.get('audience'), a.get('revocations') or (), a.get('group_events') or (),
a.get('early') or ())
except grant.ChainRefused as e:
raise Refused(e.code)
@op('group.read', 'identity', '{id, pubkey, created_at, did, type, epoch, controllers, thresholds, expiration, body} of a kind 30834 {event}, or refused (shape or signature)')
def _group_read(a: Args) -> object:
return _refuse(lambda: group.read(a['event']), ValueError)
@op('group.resolve', 'identity', '{did, genesis, current, epochs[{epoch, type, controllers, thresholds, expiration, signers, seen_at}]} of {group} from the kind 30834 {events} in the order seen, at {now}, or refused group_unresolved')
def _group_resolve(a: Args) -> object:
try:
return group.resolve(a['events'], a['group'], _int(a['now'], 'now'))
except group.GroupRefused as e:
raise Refused(e.code)
@op('group.revoked', 'identity', 'whether a kind 30833 at the group DID by a current controller of {group} (resolved from {events} at {now}) names {grant}')
def _group_revoked(a: Args) -> object:
try:
g = group.resolve(a['events'], a['group'], _int(a['now'], 'now'))
except group.GroupRefused as e:
raise Refused(e.code)
return group.revoked(g, a.get('lists') or (), a['grant'])
# ------------------------------------------------------- strand types (D35): types as fibers
def _textile_layer(a: Args) -> str:
layer = a.get('layer', 'strand')
if layer not in textile_types.SCHEMA_LAYERS:
raise ValueError('layer must be strand or fabric')
return layer
@op('textile.schema_root', 'store', 'the Bao root and canonical bytes of a schema fiber payload ({schema} in its fields, {layer} strand|fabric)')
def _textile_schema_root(a: Args) -> object:
layer = _textile_layer(a)
schema = a.get('schema')
if not isinstance(schema, dict):
raise ValueError('schema must be an object')
raw = textile_types.schema_bytes(schema, layer)
payload = textile_types.schema_payload(schema, layer)
return {'root': textile_types.schema_root(schema, layer), 'schema_id': payload['schema_id'],
'layer': layer, 'byte_length': len(raw), 'canonical': raw.decode('utf-8')}
@op('textile.schema_fiber', 'store', 'the fibers entry a strand carries for its type (role schema), from a {schema} and {layer}')
def _textile_schema_fiber(a: Args) -> object:
layer = _textile_layer(a)
schema = a.get('schema')
if not isinstance(schema, dict):
raise ValueError('schema must be an object')
return textile_types.schema_fiber(schema, layer)
@op('textile.read_schema_fiber', 'store', 'the payload, root and schema_id read from a schema fiber ({canonical} or {bytes_hex}[, root]); refused schema_fiber_invalid')
def _textile_read_schema_fiber(a: Args) -> object:
data = a.get('bytes_hex')
if data is not None:
if not isinstance(data, str):
raise ValueError('bytes_hex must be a string')
data = bytes.fromhex(data)
else:
data = a.get('canonical', a.get('schema'))
try:
payload, root = textile_types.read_schema_fiber(data, a.get('root'))
except textile_types.TypeRefused as e:
raise Refused(e.code)
return {'root': root, 'schema_id': payload['schema_id'], 'layer': payload['layer'],
'kind': payload['kind']}
@op('textile.builtin_schema', 'store', 'the built-in schema fiber of a strand {kind}: its payload and root; refused type_unknown')
def _textile_builtin_schema(a: Args) -> object:
try:
schema = textile_types.builtin_strand_schema(str(a.get('kind') or ''))
except textile_types.TypeRefused as e:
raise Refused(e.code)
return {'root': textile_types.schema_root(schema, 'strand'), 'schema_id': schema['schema_id'],
'kind': schema['kind'], 'schema': schema}
@op('textile.catalog', 'store', 'the built-in strand types: schema_id -> published root, sorted')
def _textile_catalog(a: Args) -> object:
return textile_types.catalog()
@op('textile.resolve_type', 'store', "a strand {manifest}'s type: {source (fiber|builtin), schema_id, kind, schema_fiber_root} given {known_schemas}; refused type_unknown|schema_fiber_invalid")
def _textile_resolve_type(a: Args) -> object:
manifest = a.get('manifest')
if not isinstance(manifest, dict):
raise ValueError('manifest must be an object')
known = a.get('known_schemas')
if known is not None and not isinstance(known, dict):
raise ValueError('known_schemas must be an object')
try:
schema, source, root = textile_types.resolve_type(manifest, known)
except textile_types.TypeRefused as e:
raise Refused(e.code)
return {'source': source, 'schema_id': schema['schema_id'], 'kind': schema['kind'],
'schema_fiber_root': root}
@op('textile.validate_typed', 'store', "problems a strand {manifest} has against its type, as refusal codes ([{valid, errors, schema_id}]), from {schema} or by resolving with {known_schemas}")
def _textile_validate_typed(a: Args) -> object:
manifest = a.get('manifest')
if not isinstance(manifest, dict):
raise ValueError('manifest must be an object')
schema = a.get('schema')
if schema is not None:
if not isinstance(schema, dict):
raise ValueError('schema must be an object')
else:
known = a.get('known_schemas')
if known is not None and not isinstance(known, dict):
raise ValueError('known_schemas must be an object')
try:
schema, _source, _root = textile_types.resolve_type(manifest, known)
except textile_types.TypeRefused as e:
raise Refused(e.code)
errors = textile_types.validate_typed(manifest, schema)
return {'valid': not errors, 'errors': errors, 'schema_id': schema.get('schema_id')}
@op('textile.strand_root', 'store', "a strand {manifest}'s root and version: v1 unchanged, v2 when it carries refs")
def _textile_strand_root(a: Args) -> object:
manifest = a.get('manifest')
if not isinstance(manifest, dict):
raise ValueError('manifest must be an object')
return {'root': textile_types.compute_typed_strand_root(manifest),
'version': textile_types.strand_root_version(manifest),
'canonical': textile_types.strand_root_payload(manifest).decode('utf-8')}
@op('textile.strand_event', 'store',
'the unsigned kind 30821 strand event for {manifest} by {pubkey} at {created_at}[, primary_sha256, primary_mime]: content is the canonical root payload, tags d/strand_kind/root and, when the strand carries them, schema/x/m; refused strand_manifest_invalid when the manifest fails the strand document check')
def _textile_strand_event(a: Args) -> object:
manifest = a.get('manifest')
if not isinstance(manifest, dict):
raise ValueError('manifest must be an object')
if 'pubkey' not in a:
raise ValueError('pubkey is required')
try:
return textile_strand_event.build_strand_event(
manifest, a['pubkey'], _int(a['created_at'], 'created_at'),
primary_sha256=a.get('primary_sha256'), primary_mime=a.get('primary_mime'))
except textile_strand_event.StrandEventRefused as e:
raise Refused(e.code)
@op('textile.read_strand_event', 'store',
"read a kind 30821 strand {event}: {payload, root, kind, schema_root}, or refused <code> (strand_event_invalid, strand_content_missing, strand_root_mismatch, strand_d_mismatch, strand_kind_mismatch, strand_schema_mismatch)")
def _textile_read_strand_event(a: Args) -> object:
try:
return textile_strand_event.read_strand_event(a['event'])
except textile_strand_event.StrandEventRefused as e:
raise Refused(e.code)
PLANES: tuple[str, ...] = ('identity', 'store', 'peering', 'transport', 'services', 'operations')