docs: align trust documentation for router updates

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I1c2eeda1271671cac6cc69a8aaa12ddf6a6a6964

Author: NotAShelf

README.md

@@ -116,7 +116,6 @@ further in the [architechture document].
 - `GET /metrics`: Prometheus metrics
 - `GET /health`: JSON health summary of configured upstreams
 - `GET /trust/<hash>.narinfo`: trust decision and matching claim count
-- `GET /provenance/<hash>.narinfo`: stored signer claims for a narinfo hash
 
 ### Notes
 
@@ -148,7 +147,8 @@ further in the [architechture document].
 [trust documentation]: ./docs/trust.md
 
 `trust.mode = "signed"` accepts only narinfos that verify against the selected
-upstream's configured `public_key`. `trust.mode = "quorum"` records signed
+upstream's configured signer keys (`public_key` and `public_keys`).
+`trust.mode = "quorum"` records signed
 claims and accepts a route only after enough distinct signer keys agree on the
 same `StorePath`, `NarHash`, `NarSize`, and `References`. With
 `mesh.gossip_trust_claims`, peers relay re-verified claims so a quorum can form
@@ -247,7 +247,6 @@ mode = "off"                    # off | signed | quorum
 threshold = 2                   # signer agreement needed in quorum mode
 require_distinct_signers = true # count signer keys, not upstream URLs
 fail_closed = true              # reject untrusted candidates when enabled
-# claim_ttl = "30d"             # optional: ignore claims older than this in quorum
 
 [logging]
 level = "info"    # tracing filter directive, e.g. debug or ncro=debug,tower_http=warn
@@ -556,9 +555,9 @@ from unlisted senders or with invalid signatures are silently dropped.
 
 > [!TIP]
 > Setting `mesh.gossip_trust_claims = true` additionally gossips the trust
-> claims this node has verified locally and accepts claims relayed by peers,
+> claims this node has verified and accepts claims relayed by peers,
 > letting a `quorum` policy form across the mesh. A relayed claim only counts if
-> its signer key is trusted (a configured upstream key or one listed in
+> its signer key is trusted (a configured upstream or enabled fallback key, or one listed in
 > `trust.trusted_keys`) **and** its narinfo re-verifies against that key, so a
 > peer can only relay real signatures from trusted signers, never fabricate a
 > quorum with throwaway keys.

config.example.toml

@@ -60,7 +60,8 @@ upstream_cooldown         = "15s"
 
 [trust]
 # off | signed | quorum. In signed mode, accepted narinfos must verify against
-# the selected upstream's public_key. In quorum mode, at least threshold
+# one of the selected upstream's configured signer keys (`public_key` or
+# `public_keys`). In quorum mode, at least threshold
 # distinct configured signer keys must agree on StorePath, NarHash, NarSize,
 # and References before ncro stores a route. See docs/trust.md for the full
 # model.
@@ -69,14 +70,11 @@ mode                     = "off"
 require_distinct_signers = true
 threshold                = 2
 
-# Optional maximum age for a claim to count toward a quorum. Unset = never
-# expires. Prevents a long-dead signer from propping up a quorum forever.
-# claim_ttl              = "30d"
 # Signer keys trusted to vouch for content in quorum mode, in addition to the
-# public_key of every configured upstream. A quorum counts only claims signed
-# by a key in this set; without it an attacker could self-sign forged content
-# under throwaway keys and forge agreement. In a mesh, list the other nodes'
-# upstream signer keys here so their relayed claims count.
+# keys configured on regular upstreams and an enabled fallback cache. A quorum
+# counts only claims signed by a key in this set; without it an attacker could
+# self-sign forged content under throwaway keys and forge agreement. In a mesh,
+# list the other nodes' upstream signer keys here so their relayed claims count.
 # trusted_keys           = ["cache-b-1:base64key=", "cache-c-1:base64key="]
 
 [discovery]
@@ -93,10 +91,10 @@ gossip_interval = "30s"
 peers           = [  ]
 private_key     = "/etc/ncro/node.key"
 
-# When true, this node also gossips locally-verified trust claims to peers and
-# accepts claims relayed by peers (each re-verified against its original Nix
-# signer key before being trusted). Lets a quorum form across a mesh where each
-# node sees only one upstream. Only meaningful with trust.mode = "quorum".
+# When true, this node gossips trust claims it has verified and accepts claims
+# relayed by peers (each re-verified against its original Nix signer key before
+# being trusted). Lets a quorum form across a mesh where each node sees only one
+# upstream. Only meaningful with trust.mode = "quorum".
 gossip_trust_claims = false
 
 [logging]

docs/trust.md

@@ -62,7 +62,7 @@ is cached.
 | Mode     | Requirement to accept a candidate                                               |
 | -------- | ------------------------------------------------------------------------------- |
 | `off`    | No verification. Route-only behavior (default).                                 |
-| `signed` | The narinfo must verify against the serving upstream's configured `public_key`. |
+| `signed` | The narinfo must verify against one of the serving upstream's configured signer keys. |
 | `quorum` | A verified signature **plus** at least `threshold` matching claims (below).     |
 
 <!--markdownlint-enable MD013-->
@@ -77,16 +77,18 @@ Every time ncro verifies a signature it records a **trust claim** in SQLite (see
 vouched for what:
 
 - `signer_key` / `signer_name` -> the Nix signing key that verified.
-- `upstream_url` -> which upstream served this observation.
+- `upstream_url` -> the serving upstream for a local claim, or the
+  `mesh://<relay-address>` that supplied a relayed claim.
 - the signed content tuple: `nar_hash`, `nar_size`, `references` (and the
   `store_path` / `narinfo_hash`).
 - provenance-only fields recorded for audit but **not** covered by the
   signature: `deriver`, `ca`, `file_hash`, `file_size`, and the raw `narinfo`
   bytes.
 
 Claims are what make `quorum` and the mesh integration possible: they are a
-durable, queryable record of "signer X, via upstream Y, attests that path H has
-this NAR hash."
+durable, queryable record that signer X attests that path H has this NAR hash.
+For relayed claims, the relay address is recorded rather than an unverified
+assertion about the original upstream.
 
 ## Quorum counting
 
@@ -114,7 +116,7 @@ The signature check alone would be theatre.
 ncro therefore counts a claim toward a quorum **only if its `signer_key` is in
 the trusted set**:
 
-$$\text{trusted set} = \left\{ \text{upstream}_i.\text{public\_key} \right\} \cup
+$$\text{trusted set} = \left\{ \text{all configured upstream and enabled fallback signing keys} \right\} \cup
   \text{trust.trusted\_keys}$$
 
 - Locally-recorded claims always use a configured upstream key, so a single node
@@ -124,11 +126,6 @@ $$\text{trusted set} = \left\{ \text{upstream}_i.\text{public\_key} \right\} \cu
   signed by an unknown key is dropped (and never even stored). This is what
   bounds a quorum to _trusted_ signers rather than _any_ signer.
 
-`trust.claim_ttl` (optional, e.g. `"30d"`) bounds how old a claim may be and
-still count. Claims whose `last_seen` is older than the TTL are ignored when
-evaluating the quorum, so a signer that has long stopped serving a path cannot
-prop up a quorum forever. Unset means claims never expire.
-
 > [!WARNING]
 > Quorum needs more than one independent signer to ever see the same path. On a
 > single node that only races caches sharing one signing key, a `threshold > 1`
@@ -166,33 +163,29 @@ With `mesh.gossip_trust_claims = true`, a node:
      set (above). A claim from any other key is dropped immediately, this is
      what stops an attacker from minting throwaway keys to forge a quorum, and
      it also bounds how many claims a hostile peer can write to the database.
-   - **Valid signature.** The claim carries the original narinfo bytes, and the
-     receiver re-verifies that narinfo against the claim's `signer_key`. The
-     peer's packet signature only proves _which peer relayed it_, not that the
-     content was signed; re-verifying means a peer cannot forge a claim under a
-     trusted key it does not actually hold.
+   - **Valid signature and canonical fields.** The claim carries the original
+     narinfo bytes. The receiver re-verifies that narinfo against the claim's
+     `signer_key` and rebuilds every signed field from it, so a peer cannot
+     substitute a different path or content tuple.
 
 This means **a peer becomes a witness, never a substitute for a real Nix
 signature.** A malicious or compromised peer cannot inflate a quorum: a claim
 signed by an untrusted key is dropped, and a claim claiming a trusted key but
 without a valid signature fails re-verification. A quorum therefore counts
 distinct _trusted Nix signers_, whether those signatures were observed locally
-or relayed by a peer. Peers are also allowlisted by their mesh public key
-(`mesh.peers[].public_key`), so unknown senders are rejected before any claim is
-even parsed.
+or relayed by a peer. Configure `mesh.peers[].public_key` to also allowlist mesh
+senders; peers without configured keys are accepted at the transport layer but
+still cannot alter the signed claim tuple.
 
 ## Inspecting Trust (At Runtime)
 
-Two read endpoints expose the recorded claims:
+The trust endpoint exposes the recorded claims:
 
 - `GET /trust/<hash>.narinfo` - the current trust decision for a path: the mode,
   threshold, the count of matching claims, whether the path is currently
   trusted, and the full list of claims.
-- `GET /provenance/<hash>.narinfo` - the same claim list, framed as an audit of
-  who has vouched for the path (including the unsigned provenance fields).
-
-Both are useful for confirming that claims are propagating across a mesh: after
-a path is resolved on one node, it should appear in `/trust` on a peer within a
+It is useful for confirming that claims are propagating across a mesh: after a
+path is resolved on one node, it should appear in `/trust` on a peer within a
 gossip interval or two.
 
 ## Configuration Summary
@@ -203,7 +196,6 @@ mode                     = "quorum" # off | signed | quorum
 threshold                = 2        # matching claims required in quorum mode
 require_distinct_signers = true     # count distinct signer keys, not mirrors
 fail_closed              = true     # reject (true) vs serve+warn (false)
-claim_ttl                = "30d"    # optional: ignore claims older than this
 
 # Signer keys trusted to vouch in quorum mode, in addition to upstream keys.
 # In a mesh, list the OTHER nodes' upstream signer keys here.