Fleetmesh fleetmesh
Fleetmesh · Operator note · Protocol fleetmesh/0.1-draft@a3074ca76a554e27...

Private networks, fleets & enrolment

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.

What ships in P1

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.

01 · The kinds

A definition that is the roster, grants, and revocations

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.

02 · Join policies

Four ways onto a network, and who decides each

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.

open
Reach a network relay with a descriptor

Anyone whose kind 11801 has arrived on the network’s relays is admitted; the roster still names the founders. Nobody decides.

Decider: nobody
credentialed
On the roster, or carrying a credential

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.

Decider: an issuer
approved
Only the roster, but asking is allowed

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.

Decider: the creator or controller
invite
Only the roster, no asking

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.

Decider: the creator or controller

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.

03 · Relays

A roster-protected relay

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.

04 · Capabilities

Vocabulary, tiers and grant chains

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:

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:

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.

05 · Revocation

Saying no after you have said yes

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.

How lists reach a node

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.

06 · Fleets & enrolment

A fleet is yours to see, not everyone's

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.

01
meshnode whoami On the node: its DID, npub and hex pubkey, plus the operator it has, if any. The operator needs the pubkey.
02
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.
03
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.
04
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:

CodeMeaning
already_enrolledThe node names a different operator and --force was not given. The only code that is the node’s own.
audience_mismatchThe token’s aud is another node’s pubkey.
token_malformedNot fmenrol1 plus a three-part BIP340 UCAN, or no parseable issuer.
token_legacyA pre-D18 signed bundle; ask the operator for a fleet/enrol grant.
bad_signatureThe UCAN’s signature does not verify against its issuer.
grant_expired / grant_not_yet_validOutside nbf ≤ now < exp.
grant_revokedIts id is on a 30833 the node holds.
capability_missingThe grant does not carry fleet/enrol.
operator_unsupported / issuer_unsupportedThe 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.

07 · Worked example

A private network with 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.

08 · Circles

A circle operates nodes by a quorum of its members

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

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.

Voting from a browser extension or a remote signer

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.

# 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 });
09 · Remote control

Running a command on a node, with the chain that allows it

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.

10 · Not built yet

Read this before you rely on the rest

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.