Docs
Docs menu

How trust works

How a node decides whether a node key may sign, what it knows about hosts beyond each repository, and what to do when a host shows as revoked or not trusted.

Everything in a repository that isn’t plain git is signed by a node key: changes, comments, reviews, and the attestations that let a change merge. A node key may sign on behalf of its host when the host certifies it. Each repository carries the proof in its host objects: the host’s DID document (for a did:plc host, a signed snapshot of its log at the PLC directory), its certificates for node keys, and its revocations of keys it no longer stands behind.

A repository is one copy, though. A copy taken before a key was revoked doesn’t have the revocation, and a copy can carry a DID document older than the host’s current one. So a node checks each repository’s host objects together with what it knows about the host from elsewhere: the other repositories it holds, its own records of the keys its host revoked, and the PLC directory.

What the node knows only ever takes trust away or brings a DID document up to date. It never makes a key trusted that a repository’s own host objects don’t certify.

What a check decides#

Two checks depend on whether a key may sign:

  • Ops. Every op in an object must be signed by a key the author’s host certified at the op’s time and hadn’t revoked. An object holding an op that fails doesn’t load at all, and the error names the op and why: “op … isn’t authorized to sign for … at …: revoked by did:plc:… from 2026-11-12T09:00:00.000Z (known to this node)“. “Known to this node” means the repository itself doesn’t hold that revocation from that time.
  • Attestations. A revision merges only with an attestation from a trusted signer (see Provenance). A signer certified by a trusted host counts only while that host hasn’t revoked it. When a revocation is why it doesn’t count, the change page’s Evidence panel says “revoked by … from …”, with “(known to this node)” when the repository doesn’t carry it, and the API’s verify answer has a revoked field. When the trusted host that certifies the signer isn’t trusted on this node because its DID documents disagree, the panel says so and points to the Hosts tab of Settings → Network, and verify has an untrusted_host field (host, and reason: directory or docs).

The node gives the same answer for a repository whichever copy of it it holds, as long as it knows the revocation.

What the node knows#

The other repositories it holds#

When the node reads a repository’s host objects, it keeps their DID documents and revocations in hosts/ in the data directory, one file per host. It reads every repository once when it starts, again every 10 minutes for those whose host objects changed, and each time it loads a repository’s objects. Only signed DID documents and signed revocations are kept, each checked the way the repository’s own check does. Certificates are never kept.

hosts/ is rebuilt from the repositories (and the PLC directory) when it’s missing, so backups leave it out.

Its own revocation records#

moru-node revoke-node and retire-node record each revocation in host/revocations.json before they write anything into a repository: the key, the time it’s revoked from, and the checkpoint of what the key signed that the revocation vouches for, kept in host/checkpoints/. On the control node of a host with many nodes, revoking a node records it the same way, with the newest checkpoint the control node had received from that node by then. These records aren’t a cache: they’re how a node knows a revocation that a repository lacks, and nothing can rebuild them, so backups keep them.

A record by itself carries no map of what the key may still have signed: that’s in the host-signed revocation the node writes into each repository. Until a repository has it, see Revocations.

The PLC directory#

For a did:plc host it trusts as an attester (in trusted-attesters.json or in any repository’s trusted attesters), or one an imported repository carries a valid DID document of, the node fetches the host’s log from the PLC directory in the background: when it starts, then about every 12 hours, and right away when an import names a host it hasn’t seen. It never asks the directory while it answers a request. See DID documents.

On a host with many nodes#

The control node keeps the host’s revocation records and sends them to every node. A repo node keeps the last ones it heard in its copy of the control node’s state, and applies them from its start, even while the control node is down. It never forgets a revocation it heard of, even from a control node restored from an older backup. Each node keeps its own hosts/ from the repositories it holds and from the directory.

Revocations#

For each key, the node takes the earliest time any source revokes it from: the repository, another repository, its own records, or the control node’s. From that time on, nothing the key signs counts.

What the key signed before that time counts only where the host vouched for it. Every host-signed revocation at that time vouches for a set of objects; the node takes all of them together, from every repository it has seen, so one copy vouching for less doesn’t drop what another copy vouched for.

A revocation the node knows only from a record vouches for nothing. In a repository that doesn’t hold the host-signed revocation yet, every op the key signed is refused, from before the time too, until the node writes the revocation there. On a running node that’s usually seconds: see Writing revocations into repositories.

Objects the index already holds stay listed until their repository is indexed again, for example by its next push or a rebuild-index.

DID documents#

A host’s DID document says which key it signed with at each time. The node uses the longest valid document it has for the host, under these rules:

  • A longer document that agrees (the repository’s is a prefix of it) replaces the repository’s. A key the host rotated out stops certifying from the rotation on, even in a repository that never stored the rotation.
  • Another repository’s document never contradicts this one’s. Where documents diverge, each repository keeps its own, so one imported copy can’t make a host untrusted in every repository. A repository with no valid document of its own uses the node’s.
  • A repository whose own documents diverge doesn’t trust the host, as before.
  • The node’s own host is checked against its own identity, which serve refreshes when it starts.

The PLC directory’s log#

A log fetched from the directory counts as follows:

The logWhat happens
extends every document the node keepsIt becomes the host’s document.
is shorter than a document the node keeps, and agreesThe longer document stays. A directory can leave entries out, but it can’t forge them.
diverges, fetched in the last 24 hoursThe directory wins: documents that diverge from it stop counting, in every repository. This is how a recovery of the host’s log (an older entry nullified) takes effect.
diverges, older than 24 hours, and its recovery explains whyIt still wins. Every entry a diverging document adds is one the log shows nullified, with the same time, and the entries both hold carry the same times: the host’s recovery took that document back, and the node never takes a log that shows those entries live again.
diverges otherwise, and the last good fetch is older than 24 hoursThe host is not trusted on this node, in any repository, until a fetch settles it. For example, a document holds an entry the log doesn’t have at all, or the log dates a shared or nullified entry differently.
takes back what it served beforeRefused, and kept as a failed fetch: an entry live in it shows nullified in the log the node had or in a document the host signed, an entry carries a different time than there, or an entry of the log the node had is missing. The log the node had stays, and goes stale on schedule.

A fetch dated more than 5 minutes in the future counts as stale. When a fetched log alone can’t settle two documents that both extend it, it settles nothing and each repository keeps its own.

When the directory doesn’t answer, the node tries again every hour, and every 10 minutes from 3 hours before a log that diverges in a way its recovery doesn’t explain would go stale. A bad answer (a 4xx, a log that doesn’t verify, or one it refuses as above) is tried again at the next regular refresh, or in those last 3 hours every 10 minutes too.

A stale log that settles a recovery counts until a fetch brings a newer one. If a repository brings in a document from a later recovery the node’s log doesn’t hold, the host shows Not trusted until a fetch settles it. A document the node couldn’t keep (it keeps up to 32 diverging documents per host) is overridden by the log in its repository, as a fresh log would.

Turning the refresh off#

--no-plc-refresh (MORU_NO_PLC_REFRESH) is for a node that can’t or shouldn’t reach the PLC directory. With it the node fetches nothing for other hosts, and logs it fetched earlier count for nothing: DID documents come from the repositories alone, with the rules above. It’s a global option, so set it for every command you run on the data directory, not only serve. See moru-node.

Writing revocations into repositories#

The node’s own checks don’t depend on the repository holding a revocation. A copy that leaves the node does: a clone, an export, a move to another host. So the node writes its own host’s revocations into every repository it holds that lacks one, and repositories don’t stay in a state that only this node can judge correctly. It writes them:

  • before an imported repository is served, as for a repository restored from the trash, moved to another node, or restored from a revoked node’s backup;
  • when it learns a new revocation: from revoke-node or retire-node (even run from another process while serve runs: it looks for new records every second), or from the control node. It reads every repository at once and writes the revocation into each one that certifies the key;
  • when it finds a repository lacking one, for example after a push brought back host objects from an old copy.

On a single node, the node signs the revocation itself, at the recorded time, vouching for exactly what the record’s checkpoint lists for that repository, and for nothing where it lists nothing. It never works the map out from the repository as it is now: what the key signed since may be someone else’s work. On a repo node, the node asks the control node, which signs it from the checkpoint it keeps. A write that fails is tried again after 30 seconds, then after twice as long each time, up to an hour, for as long as the node runs. A repository paused for a move gets it once the move ends.

A repository’s host object can refuse the write: it already holds as many revocations as it may, or a revocation from the same time vouches for another version of an object. The node logs it as a warning and doesn’t try again until that host object changes. It still refuses the key there.

The node writes only its own host’s revocations. It can’t sign for another host, and copying another host’s revocation from one repository into another could undo what the second one vouches for. Another host’s revocations reach a repository in copies that host writes.

Imports#

moru-node import-repo and Import from another node write the node’s own host’s revocations into the copy before it’s served. If one can’t be written for a reason that may pass (the control node doesn’t answer, a record’s kept checkpoint can’t be read), the import fails and leaves nothing behind: try again. If the copy’s host object refuses it, the import goes on, the report says so, and the node keeps refusing the key there.

The import report has a Hosts part (hosts in the JSON): each host the repository names, whether the node knew it before, each revocation the node knows that the copy lacked (and for this node’s host whether it was written before the repository was served), and a conflict between the copy’s DID documents. Problems that didn’t stop the import are under warnings. A did:plc host the node hadn’t seen is fetched from the directory in the background.

A repository linked to GitHub with --push-moru-refs gets its host objects from GitHub after it’s created. The node writes its revocations right after that fetch, and link-github prints what it wrote. The repository is served from the moment it’s created, so a clone taken in those seconds lacks the revocation until its next fetch. The node itself refuses the key there all along.

Settings → Network#

The Hosts tab of Settings → Network, for site admins, lists what the nodes know: their own host, every trusted attester, and every host whose DID document or revocations a node found in a repository. Each node keeps its own list, so the tab is a grid: one row per host, one column per active node, and a Trusted attester column. A cell is that node’s state for that host (below), not seen when the node’s list doesn’t have the host, or didn’t answer when the node didn’t answer within 10 seconds, with a button in the column’s header to ask it again. This host comes first, then hosts with a problem on any node (Docs disagree, Not trusted, Refresh failed, or a node that didn’t answer), then the rest by DID. Stale and Recovered, stale aren’t problems: they’re the normal state between refreshes. Filter by DID, or tick Problems only; past 200 rows the grid shows the first 200 that match and how many more there are. On a node running on its own there’s one Status column. The tab’s count is how many rows have a problem. A row marked Node of this host is one of your own nodes’ keys, which nodes list among the signers they trust: it’s not another host.

Select a cell to see what that node knows of that host, under the grid:

  • Host: its DID, and whether it’s This host, a Trusted attester, or Imported (kept fresh because an imported repository carries a valid DID document of it). A host kept only because an import named it stops being refreshed once no repository on the node has named it for an hour, and leaves the list if the node holds no document or revocation of it.
  • DID document: its state, the head of the document the node goes by, and when the directory was last asked.
  • First seen: when the node first kept something of it, or “nothing held” for a trusted attester it hasn’t seen in a repository.
  • Revoked keys: each key with the time it’s revoked from and where the node knows it from: Repository (a host-signed revocation, with how many signed revocations and vouches it found for that time), Revocation record (this node’s host/revocations.json), Node registry (a node this host revoked), or Control node (the control node’s records). A repository revocation marked may not count is backed by only some of the host’s documents the node keeps (they diverge): it doesn’t count in a repository whose document disagrees with its signer’s.

The state is one of:

StateMeaning
This hostThe node’s own host, checked against its own identity.
No directoryA did:key host, which has no log to refresh.
FreshThe directory’s log is less than 24 hours old.
Not fetched yetThe node hasn’t asked the directory yet.
StaleThe log is older than 24 hours and agrees with the documents the node keeps. Nothing changes until the next refresh.
Recovered, staleThe log is older than 24 hours and diverges from a document the node keeps, but only by entries its recovery nullified. It still decides the host’s document, and the host stays trusted.
Refresh offThe node runs with --no-plc-refresh.
Refresh failedThe last fetch failed; the error is shown. A warning while the log the node has is still fresh, or settles a recovery as above.
Docs disagreeDocuments the node keeps diverge and nothing settles it. Each repository goes by its own.
Not trustedThe directory’s log diverges from a document the node keeps in a way its recovery doesn’t explain, and it’s older than 24 hours. Nothing the host signs is trusted on this node.

The same data is at GET /api/v0/hosts (?node=<did> for another node; see API).

When something goes wrong#

host/revocations.json can’t be read#

A file that isn’t valid JSON, or one written by a newer release, stops what writes revocations: revoke-node and retire-node refuse with what to do, and imports, restores from the trash and restores of a revoked node’s repositories fail rather than serve a repository without its revocations. A running node keeps applying the records it read last. A node that starts while the file can’t be read knows none of them, and goes by the revocations the repositories hold.

Put back a good copy from a backup if you have one. Otherwise move the file aside, keeping the copy, and for each key it held run revoke-node again with the recorded time as --at-ms and the kept checkpoint, host/checkpoints/<key>-<time>.json, as --vouched-from. On the control node of a host with many nodes, a restart records the node registry’s revocations again by itself; run revoke-node (without --vouched-from) only for keys the registry doesn’t list. Revocations already written into repositories stay. A file from a newer release means the node was downgraded: upgrade it.

A host shows Not trusted#

The directory’s log diverges from a document the node keeps in a way the log doesn’t explain, and the node hasn’t had a good answer from the directory for over a day. A host that recovered its log doesn’t land here on its own: a log that nullifies what an older document adds keeps counting when stale (Recovered, stale). So a repository carries a document with entries the node’s log doesn’t hold at all, or dates differently: a branch the directory never had, or a recovery newer than the node’s log. Look at Refresh failed next to it:

  • The directory doesn’t answer: check the node’s outbound network and --plc-url. The first good fetch makes the host trusted again, by the directory’s log.
  • The answer is refused as taking back an entry: the directory now serves a log that contradicts one it served before, or one the host signed. Find out why before trusting the host again.

Turning the refresh off also ends the state, because the node then ignores the directory’s logs. It then trusts the host by the documents its repositories carry, which may be ones the directory’s log set aside. Only do that once you know which document is the host’s own.

A host shows Docs disagree#

Two documents the node found in repositories diverge, and nothing fresh from the directory settles which one counts. Each repository goes by its own document, as before this node knew of the other. For a did:plc host, the next good fetch settles it. On a node with --no-plc-refresh, it stays.

You restored a node from an old backup#

A backup holds host/revocations.json as it was. A revocation made after the backup isn’t in the restored records, and the restored repositories may not hold it either. Run revoke-node again for that key, with the same --at-ms and checkpoint, or retire-node again for a key you retired. On a host with many nodes, run revoke-node again on a restored control node: the repo nodes still refuse the key, but the restored node list trusts the node again until you do (see Running many nodes).

A revocation command stopped partway#

Run it again. A rerun goes by the record: it revokes from the recorded time, adds what the repositories that already hold the revocation lack, and leaves the rest alone. retire-node maps what the key signed in the repositories it failed in at the time of the rerun. revoke-node with a later --at-ms than recorded says so and uses the recorded time; an earlier one replaces the record and widens the revocation. See moru-node.

Command menu
Search for a page, repository, change or request, or run a command