fleetmesh/0.1-draft@a3074ca76a554e27...A fleetmesh node is public by default: anyone can read its descriptor and any peer it grants can send it traffic. Two optional layers narrow that. A private network is a signed, published roster of keys with a policy for how keys get onto it, enforced by the network’s relays and by the nodes themselves. A fleet is the set of nodes one operator runs, and enrolment is how a node comes to name that operator. This page is the prose; the field-by-field definitions live in the spec, the schema catalogue and the NIP.
Five addressable kinds, one grant verifier, one token format, three meshctl
command groups, three node control verbs and a relay write policy.
The kinds are 30830–30834. The verifier is
fleetmesh_core.network.grant. The enrol token is a fleet/enrol UCAN
serialised as fmenrol1…. The commands are meshctl network,
meshctl fleet and meshctl enrol; a running node answers
network.show, network.poll and network.decide. The relay side
is the strfry-bridge write
policy with a roster_file. What is not built is listed
at the end; read it before you depend on anything here.
Every kind here is addressable: the newest unexpired event at a coordinate is the truth and
there is no separate “remove” event anywhere. Fields and tags are in the schemas
under schemas/events/kind-3083x-*.schema.json; this is only what each is for.
| Kind | Name | Coordinate (d) |
What it says |
|---|---|---|---|
| 30830 | Private network definition | <creator pubkey hex>:<slug> |
The network and its roster: the join policy, the relays
the network uses (and no others), the issuers whose credentials count, an optional
controller DID that may republish, and one member tag per member. A member
is a node (DID or hex) or an operator DID, in which case every node of that fleet is on the network.
The current event at the coordinate is the roster; a member missing from the newest version is out. |
| 30831 | Fleet profile | the operator DID | A label for a fleet: display name, brand credential, the relays the operator’s nodes publish to. It does not list the fleet. The fleet is derived from descriptors (see fleets); a verifier that reads only this has learned a name, not a membership. |
| 30832 | Capability grant envelope | the grant id, sha256 of the token | One key (aud) may do some capabilities (can) on a resource (with:
a node pubkey, a DID, or a network id) at a tier until expiration. The content is the
UCAN itself as a compact JWT. Grants chain; see capabilities. |
| 30833 | Grant revocation list | the issuer DID | One revoked tag per grant id the issuer no longer stands behind. Content is empty: the ids
are the message. Each issuer has exactly one current list. See revocation. |
| 30834 | Group controller document | the group DID | Who signs for a did:group right now (steward, multisig or FROST) and at which epoch.
Defined in P1 so coordinates are stable; did:group issuers and members are resolved in P2,
and until then are reported as unresolved, never silently expanded. |
None of these touch what a node is. The kind 11801 descriptor still says what a
node does and how to reach it; it names its operator only if it opts in (plan D26), and its
network and expose tags say which networks it is on. A node on a private
network publishes its descriptor twice (plan D11, fleetmesh_core.network.descriptor_split):
the public relays get a copy without the network tags, the network relays get the copy with them.
The definition carries one policy from constants.json#join_policy. It
fixes what evidence admits a key, and therefore who holds the power to admit. The node enforces
it alone; a relay or UI only renders it. fleetmesh_core.network.join.decide is the one
function that evaluates a sender against the policy and the roster, and it declines with one of
three codes: network_policy (no usable definition), not_member, or
credential_refused.
Anyone whose kind 11801 has arrived on the network’s relays is admitted; the roster still names the founders. Nobody decides.
A roster member is in. So is a sender presenting a credential: in P1 that is a
signed, unexpired Nostr event by one of the definition’s issuers carrying a
p tag for the sender. VC semantics on its content are P2.
Admits exactly the keys the current definition names. It differs from
invite only in that a candidate may ask; the answer to an ask is a new definition,
not a different rule. There is no on-wire ask yet, so asking is out of band.
The roster is exactly what the creator (or the named controller) publishes,
and nothing a candidate does changes that. This is meshctl network create’s
default.
Under every policy the roster is a signed, replaceable event. Removing a member is
meshctl network invite <network> --remove <member>: the definition is
republished without them, and a node is on the network only while the current version names it
or its operator — never because it once was, never inferred from traffic.
A network is only private if its relays enforce the roster. The rule is one function,
fleetmesh_core.network.relay_allow (plan D6): a network relay is a plain Nostr relay
whose policy is “NIP-42
AUTH, then only roster members”, for auth, event and
req alike. One exception lets a network be born: a relay with an empty roster
(no current definition yet) still accepts a kind 30830. meshctl’s own
relay client speaks AUTH, and its tests run against a fake relay that serves nothing
until authenticated.
The shipped relay-side implementation is the
strfry-bridge write policy. It
gates writes: in its policy block, one key names the file a meshnode exports:
{
"roster_file": "/var/lib/meshnode/roster.json",
"allowed_pubkeys": ["<network creator pubkey hex>"]
}
The node writes that file from face.roster_export_path in its config.json,
atomically, as {"<network id>": ["<pubkey hex>", …]}, whenever a roster it
holds changes. The policy re-reads it when the mtime moves and merges every pubkey it finds with the
static allowed_pubkeys; naming a roster_file at all makes the relay
roster-only, and a missing or half-written file is nobody, not everybody. Two things to
know: the plugin does not implement the empty-roster 30830 exception — put the
creator’s pubkey in allowed_pubkeys so the first definition can land — and
read-side AUTH is strfry’s own configuration, not the plugin’s.
Every delegable act has a name: a URI https://fleetmesh.org/cap/<namespace>/<verb>
from the vocabulary in schema/constants.json#capability. There are five namespaces —
node (one node’s lifecycle: restart, scale, update, logs, config, destroy, key-rotate,
set-operator, set-visibility), fleet (enrol, profile),
network (create, invite, join, leave, relay), app (install, remove, config,
expose) and host (run, update, restart, delegate: a host/* grant to a host’s
DID is what hosting is). A grant naming anything outside the vocabulary is refused
capability_unknown.
Every grant carries a tier, and the node enforces the tier written in the grant, whatever anyone’s policy would have guessed:
max_ttl_sec), then
is re-issued. fleet/enrol, node/restart, network/join default here.ratify-by; it revokes itself at that time unless a poll-bearing grant has superseded it.
network/leave, app/remove, node/set-visibility default here.poll
tag naming the enactment that authorised it. node/set-operator, node/destroy,
network/create, network/relay, fleet/profile default here.
A node accepts a control command over the wire only from its operator (plan D7): either the
operator’s own signature — the zero-length chain, which publishes no envelope —
or a chain of 30832 grants that starts at the operator DID and ends at whoever signed the
command. fleetmesh_core.network.grant.verify walks it outward from the operator, in a
fixed order so two implementations refuse for the same reason:
capability.chain.max_depth), else chain_too_long;token_malformed / bad_signature;iss is the previous link’s aud, the operator first, else chain_broken;nbf ≤ now < exp, and the lifetime fits the tier, else grant_expired,
grant_not_yet_valid, ttl_exceeded, ratify_lapsed;with or narrows a fleet-wide grant to one
node, and its can is a subset, else attenuation_violated;grant_revoked;aud is who signed the command and carries what the command needs, else
audience_mismatch / capability_missing.
A refusal over the wire is refused <code>, logged with the ladder of checks. The local
control socket is exempt: whoever can open it is the operator.
A 30833 is the issuer’s one list of grant ids it has withdrawn; the newest version is the
whole list, so un-revoking is publishing a version without the id. Only the issuer’s own list
counts: a list someone else publishes about your grant revokes nothing. A revoked id breaks every
chain that passes through it. The list’s own expiration is ignored — what it withdrew
stays withdrawn until the grant’s own exp, and a relay evicting the list reinstates
nothing. It is published to the network relays the issuer’s nodes already read, not to a public
relay that would advertise which grants were withdrawn.
An enrol token is a grant, so its id (meshnode enrol prints it, and keeps it in
config.json as enrolment.token_id) is what a 30833 names to undo an
enrolment. The token’s exp bounds only the moment of enrolling; the enrolment then
lasts until it is revoked (plan D22). When the node holds a 30833 naming that id — from its
operator, or for a circle from a member of its current epoch — it clears its operator, saves the
config without the enrolment and answers the old operator no more; a fresh token enrols it again.
From private relays only (plan D26): the relays of the node’s private networks and any its
operator named (operator_relays), never by author from public relays, where the query
itself would link the node to its operator. A node on no private network gets them handed over
control instead (the ledger command). Every five minutes a node fetches the 30833s signed by its operator; before it judges
a remote command it refreshes those of the operator and of every issuer in the presented chain if they
are more than 30 seconds old, so a revocation counts at once. A list is kept only if its signature
verifies, and only the newest version per issuer, so a newer version without an id un-revokes it. A
circle’s lists arrive the same way (see Circles). What a node has fetched is kept in
groups.json, so it survives a restart.
Node ownership is blinded (plan D26). A node knows its operator from its own config and enrolment and
enforces it there, but its public kind 11801 names no operator, so nobody can list the
nodes a person or a circle runs. A node serving the public network as an anchor or mediator may opt in
(publish_operator) so leaves can pick independent anchors; only such nodes appear in
meshctl fleet list --declared. The owner’s own view is a roster only they
can read — sealed to themselves, or under a circle’s epoch key — which is kind
30835, read with meshctl fleet list --key-file <owner key>. A node
runs fine with no operator, and enrolment (plan
D18/D19) is how it comes to have one.
The instrument is an enrol token: a 30832 grant for fleet/enrol (standing tier),
issued by the operator’s key with aud set to one node’s pubkey and
with the operator DID. The node refuses a token minted for any other key. Serialised it
is fmenrol1 plus the UCAN, minted off the node and carried to it.
meshnode whoami
On the node: its DID, npub and hex pubkey, plus the operator it has, if any. The operator needs the pubkey.
meshctl fleet token <node-pubkey> --key-file operator.key
Off the node: sign the grant for exactly that node. --expires defaults to 7d and may not exceed 90d. The token alone goes to stdout, so $(meshctl fleet token …) works; --json prints the whole grant.
meshctl enrol <token>
Against the running node’s control socket (--dir or --socket to find it). The node verifies the token with the grant verifier, records the operator, and republishes its descriptor now. For a node that is not running, meshnode enrol TOKEN does the same verification and writes config.json; the next meshnode run publishes.
meshctl fleet list --relay wss://… --key-file operator.key
Read descriptors from the relays and list the current ones naming your DID (--operator to ask about someone else). The key file also answers relay AUTH.
Enrolling a node in the operator it already has is a no-op: the reply says changed: false
and nothing is republished. Enrolling it in a different operator is refused
already_enrolled unless you pass --force (on meshctl enrol or
meshnode enrol), in which case the node moves fleet and the reply names the one it left.
Both paths go through the same functions in fleetmesh_node/app/enrol.py, so they cannot disagree
about what a token means.
The result lives in config.json: operator is the operator’s 64-hex pubkey
(what the descriptor’s tag is built from), and enrolment is
{operator, token_id, at, exp} — the operator DID as written in the token, the grant id,
when it was accepted, and the token’s expiry — so the trail runs from the descriptor back to
the token that authorised it.
A refused token comes back with one of these codes:
| Code | Meaning |
|---|---|
already_enrolled | The node names a different operator and --force was not given. The only code that is the node’s own. |
audience_mismatch | The token’s aud is another node’s pubkey. |
token_malformed | Not fmenrol1 plus a three-part BIP340 UCAN, or no parseable issuer. |
token_legacy | A pre-D18 signed bundle; ask the operator for a fleet/enrol grant. |
bad_signature | The UCAN’s signature does not verify against its issuer. |
grant_expired / grant_not_yet_valid | Outside nbf ≤ now < exp. |
grant_revoked | Its id is on a 30833 the node holds. |
capability_missing | The grant does not carry fleet/enrol. |
operator_unsupported / issuer_unsupported | The issuer is not a did:nostr; did:group issuers are P2. |
Any other code from the grant verifier (ttl_exceeded,
tier_unknown, …) passes through unchanged. meshctl enrol and
meshnode enrol print the code and exit non-zero; --json prints the reply.
meshctl
You have an operator key in operator.key, two enrolled nodes, and a relay at
wss://relay.example running strfry with the fleetmesh write policy whose
allowed_pubkeys includes your pubkey.
# 1. Create the network. The id is <your pubkey hex>:ops. The definition is signed
# with your key and published to the relays it names - never to a public relay.
# Your own did:nostr goes on the roster (unless --no-self) so you can republish
# through the roster-protected relay later. --policy defaults to invite.
meshctl network create ops --key-file operator.key --relay wss://relay.example \
--name "Ops" --expires 90d
# 2. Invite the two nodes. The current definition is read from the relay, the
# members are added, and the definition is republished.
meshctl network invite <your pubkey hex>:ops did:nostr:<node-a> did:nostr:<node-b> \
--key-file operator.key --relay wss://relay.example
# 3. On each node: add the network to config.json's network block (the node
# re-reads it every tick) and, if the node is running, poll the relays now.
# Whether it gets in is the join policy, which the node enforces alone.
meshctl network join <your pubkey hex>:ops --relay wss://relay.example --dir /var/lib/meshnode
# 4. Ask a running node what it sees: its networks, the current definition of
# each, the roster it derived, and which ones it has no definition for.
meshctl network show --dir /var/lib/meshnode
The same network can be declared as a manifest and applied, which is how it goes into version
control. meshctl apply treats kind: Network specially: it is not node
state, so it is signed and published to the network’s relays rather than sent to a control
socket. The slug is spec.slug, else metadata.name;
spec.include_self (default true) puts the signer on the roster.
# ops.yaml
apiVersion: fleetmesh.org/v1alpha1
kind: Network
metadata:
name: ops
spec:
join_policy: invite
relays: [wss://relay.example]
members:
- did:nostr:<node-a>
- did:nostr:<node-b>
expires_in: 90d
# Validate without a key: parsed and checked, not signed, nothing sent.
meshctl apply -f ops.yaml --dry-run
# Sign and publish. --publish-to reaches the network's relays at another address.
meshctl apply -f ops.yaml --key-file operator.key
spec also takes issuers, controller, name,
description, expiration (unix seconds or a date) instead of
expires_in, and id to pin a full <creator>:<slug> when a
controller republishes someone else’s network. Applying without --key-file and
without --dry-run is refused, not silently skipped.
A circle is an operator with no key of its own (plan D20). Its identity is
did:group:<slug>, and who speaks for it is its kind 30834 controller
document: the members’ own pubkeys, one controller tag each, and how many of them must
agree, per tier. A grant from the circle is k identical grants, each signed by a different member
with their own key, where k is at least the threshold for that grant’s tier. Proposing is issuing the
first copy; voting is issuing an identical one; reaching the threshold enacts it. Nothing holds a circle
key, nothing runs a signing job, and every approval is a signed record anyone can audit.
{ "kind": 30834,
"tags": [
["d", "did:group:bristol-ops:0"], // <group DID>:<epoch> - one coordinate per epoch
["g", "did:group:bristol-ops"], // the group DID: #g finds every epoch
["type", "multisig"],
["epoch", "0"],
["controller", "<member A>"], ["controller", "<member B>"], ["controller", "<member C>"],
["threshold", "1"], // the default for every tier
["threshold", "2", "reserved"], // a tier that needs more
["expiration", "1830000000"] ] }
30833 with
d = the group DID, published by that member. Restoring it takes the full quorum again.ratify-by;
a reserved act needs its poll and the reserved threshold. Day-to-day work runs on grants a
position holder sub-delegates through the ordinary chain, so votes are for structure, not every action.
A node learns about its circle three ways: the circle’s enrol token carries its controller
documents (so a fresh node verifies offline and pins the circle on first sight); every five minutes it
fetches the circle’s documents and revocation lists from its relays; and before it judges a remote
command it refreshes them if they are more than 30 seconds old, so a member’s revocation counts at
once. What it has seen lives in groups.json beside config.json, in the order it
first saw it.
# Found the circle: you are the genesis member; B and C join you.
meshctl circle create bristol-ops --key-file a.key --member <B> --member <C> \
--threshold 1 --reserved 2 --relay wss://relay.example
meshctl circle show did:group:bristol-ops --relay wss://relay.example
# Enrol a node into the circle's fleet (on the node: meshnode whoami for its pubkey).
meshctl circle grant did:group:bristol-ops --key-file a.key --to <node pubkey> \
--can fleet/enrol --expires 1d --relay wss://relay.example # prints the grant id
meshctl circle bundle did:group:bristol-ops <grant id> --enrol --relay wss://relay.example
meshctl enrol fmenrol1...~...~... --dir /var/lib/meshnode # on the node
# A reserved act: A proposes, B votes, and the holder carries the two copies.
meshctl circle grant did:group:bristol-ops --key-file a.key --to <holder's node> \
--can node/destroy --tier reserved --poll prop-7 --relay wss://relay.example
meshctl circle sign did:group:bristol-ops <grant id> --key-file b.key --relay wss://relay.example
meshctl circle bundle did:group:bristol-ops <grant id> --relay wss://relay.example > chain.json
# Rotate: C out, E in. Takes effect when the reserved threshold (2) has published it.
meshctl circle amend did:group:bristol-ops --key-file a.key --remove <C> --add <E> --relay wss://relay.example
meshctl circle amend did:group:bristol-ops --key-file b.key --remove <C> --add <E> --relay wss://relay.example
# Any one member withdraws a grant.
meshctl circle revoke did:group:bristol-ops <grant id> --key-file c.key --relay wss://relay.example
A slug somebody else founded is taken: create suffixes it (-2, -3, …)
and says so, or --id <circle id> uses the circle’s id as the slug.
A NIP-07 browser extension or a NIP-46 remote signer signs nostr events, never raw bytes, so a member who
keeps their key in one could not sign a grant token that is a JWT signed directly (plan D21). A grant may
therefore also be signed as an event: its header says "alg": "NIP01", the unsigned
token header.claims is the content of the kind 30832 envelope, the envelope’s
tags are exactly the ones derived from the claims, and the envelope’s own event signature is the
token’s signature. The token carries that signature and the event’s created_at, so a
verifier rebuilds the event and checks it like any other. The published envelope is that signed event
itself, with nothing added.
created_at produces a copy that is refused as malformed.control/1.0 and the
fmenrol1 encoding carry the token string as before. For an event-signed copy the grant id is
the envelope’s d, the hash of header.claims.# From the command line, a copy in the event-signed form.
meshctl circle sign did:group:bristol-ops <grant id> --key-file b.key --event-signed --relay wss://relay.example
// In a web app, the member's own extension signs (@fleetmesh/circles).
import { issueWithEventSigner } from '@fleetmesh/circles';
const { token } = await issueWithEventSigner(window.nostr, { aud, with: resource, can: ['node/restart'],
tier: 'standing', exp, group: 'did:group:bristol-ops', epoch: 0 });
control/1.0 carries a command to a node and its answer back, gift-wrapped like every other
fleetmesh protocol, so the transport proves who sent it. A request is
{command, args, chain}; the node verifies the chain against its own operator DID - a
person’s zero-length chain, a grant chain from that person, or a circle’s quorum link - before
anything runs, and answers result {command, result} or
refused {command, code, detail} on the same thread.
# From your own running node, which signs the request (so the grant is to your node's key):
meshctl send <node pubkey> health --dir /var/lib/meshnode # you are its operator
meshctl send <node pubkey> retire --chain @chain.json --args '{"reason": "moved"}' --dir /var/lib/meshnode
Without a node of your own, your key signs the request itself (plan D25): the plain control message travels
inside a NIP-59 seal signed by your key, and the seal’s signature is the proof of who sent it. The node
answers the same way, sealed to your key on its relays, so it never needs to find you. This is how a person
on a browser extension or a remote signer, or anyone with just a key file, runs a command; a grant in
--chain can then be issued to a person’s key, not only a node’s. Only control/1.0
travels this way; every other protocol keeps the authenticated DIDComm envelope.
# With your own key and no node: --relay names where the node listens.
meshctl send <node pubkey> health --key-file me.key --relay wss://relay.example
meshctl send <node pubkey> restart --key-file me.key --chain @chain.json --relay wss://relay.example
meshctl send <node pubkey> health --key-file me.key --relay wss://relay.example --stored # collect later
A refusal is one of the grant verifier’s codes (not_operator,
audience_mismatch, quorum_short, grant_revoked,
ratify_lapsed, …) or the node’s own: unauthenticated (the transport did
not prove the sender), malformed, unknown_command, or command_failed
(authorised, and the command itself raised). A refused request runs nothing.
30835) has landed: a
node’s public descriptor names no operator, the owner reads their own roster with
meshctl fleet, and the sealed storage of a circle’s epoch-key form is the circles
repository’s next piece of work (Increment P2-I). A fleet view over a person’s
own signer follows.approved, asking is out of band; the
network/1.0 message set that would carry it is not declared. network.decide
exists on the control socket so an operator can ask what the node would answer, but nothing
in the node calls it on its own yet.roster_file policy decides
EVENTs; it does not implement the req or auth half of
relay_allow, and it has no empty-roster exception for the first 30830. Read-side
protection is strfry’s own NIP-42 configuration, and the creator must be in allowed_pubkeys.did:group resolves as an operator (steward and
multisig; FROST is a later controller type), but a did:group member tag on a
kind 30830 is still reported unresolved rather than expanded to the circle’s
fleet.
Reference implementations: fleetmesh_core/network/ in
core;
fleetmesh_node/planes/identity/network/compartment.py, fleetmesh_node/app/enrol.py,
fleetmesh_node/app/groups.py and fleetmesh_node/planes/operations/remote/ in
meshnode;
src/commands/network.rs, fleet.rs and circle.rs in
meshctl;
fleetmesh_strfry/policy.py in
strfry-bridge.
Specification: § Identity, kinds 30830–30834, and the
schema catalogue; the node operator’s view is in
Running a node.