Design: trust-gating/anti-poisoning scoring rules for federated signal-bundle import

[JSONbored]

Problem

#1970 (opt-in federated fleet intelligence) needs self-hosted instances to import an anonymized signal/signature bundle from a peer or a chosen collector and fold it into local calibration + a "your gate precision vs peer median" benchmark. #1970's own Requirements already settle the shape (opt-in only, HMAC-anonymized, never sends code/diffs/logins), but the one piece deliberately left open is: what stops a malicious or compromised peer from poisoning another operator's calibration by submitting a fabricated bundle? That's the actual trust-gating design this issue exists to resolve — everything else in #1970 can and should proceed in parallel without presupposing the answer (see the sibling export/collector-client/docs issues, none of which are blocked by this one).

Area

src/selfhost/orb-collector.ts, src/orb/analytics.ts (existing local calibration this bundle draws from), the future import/validation path this design will be implemented against (a sibling contributor-open issue, filed once this design lands).

Proposal (open questions this design pass needs to answer — not yet decided)

• Signature scheme: HMAC keyed on what — a per-instance long-lived key established at opt-in time, a rotating key, or something else? How does a receiving instance obtain/trust a sender's public verification material without a central authority (matches ORB_AIR_GAP's existing no-central-service posture)?
• Poisoning resistance: what makes a single bad actor's bundle unable to meaningfully skew another operator's local calibration or the peer-median benchmark — outlier rejection, a reputation/trust score per peer built up over time, a cap on how much any single peer's data can move the aggregate, or some combination? State the actual rule, not "detect anomalies."
• Peer/collector trust model: when an operator points at a self-run collector vs. a peer-to-peer bundle exchange, does the trust-gating rule differ between the two modes?
• Abuse recovery: if an operator later discovers they imported a poisoned bundle, is there a way to identify and discount it retroactively, or is prevention-only sufficient for v1?

Deliverables

• A written design spec: the signature/key-trust scheme, the concrete poisoning-resistance rule (with justification), and whether peer vs. collector modes differ.
• Explicit sign-off before the import+validation implementation issue (sibling to this one, blocked by it) is unblocked for a contributor.

Resources

• Opt-in federated fleet intelligence across self-hosted instances #1970 (parent issue — Requirements already fix the opt-in/HMAC-anonymized/no-code-or-diffs shape; this issue only resolves the trust-gating mechanism)
• src/selfhost/orb-collector.ts (existing local calibration export surface, ORB_AIR_GAP posture)
• src/orb/analytics.ts

Boundaries

• Design only — no import/validation implementation in this issue.
• Must not require a central or managed service — mirrors the entire self-host-only posture Opt-in federated fleet intelligence across self-hosted instances #1970 and Roadmap: self-hosted review-stack enhancements (loopover orb) #1953 already commit to.

[linear-code]

JSO-4443

[JSONbored]

Decision (resolved)

Deliberately the simplest design that closes the real risk, matching this codebase's existing trust patterns rather than inventing a new scoring/reputation system:

• Signature scheme: each opted-in instance generates its own signing key locally at opt-in time (no central authority — consistent with ORB_AIR_GAP's no-central-service posture). Peer trust is explicit and operator-configured: an operator adds a peer's public key to their own .loopover.yml allowlist before that peer's bundles are ever considered, mirroring the existing MCP_READ_REPO_ALLOWLIST pattern exactly (explicit config-driven allowlist, not automatic discovery or a PKI). For the collector mode, the collector itself is the trust boundary — an operator who points at a collector has already made the trust decision by configuring it; the client doesn't need its own separate peer-vetting logic on top of that.
• Poisoning resistance: two layers, both already implied by decisions already made elsewhere in this issue tree rather than new machinery:
  1. The benchmark is a median, not a mean (Opt-in federated fleet intelligence across self-hosted instances #1970's own Requirements already specify "peer median") — medians are inherently robust to a bounded number of outliers, unlike a mean a single bad bundle can drag arbitrarily far.
  2. Only explicitly-allowlisted peers are ever considered at all (above) — a Sybil attack requires the receiving operator to have deliberately added many fake peer keys, which is self-limiting by construction, not something the protocol needs to detect at runtime.
• Peer vs. collector modes: same trust model — "did the operator explicitly configure this source" — no separate rule needed for the two modes.
• Abuse recovery: an operator who discovers a poisoned peer removes that key from their allowlist. No dedicated retroactive-detection mechanism for v1 — simple removal is sufficient given trust was explicit in the first place, and a more sophisticated mechanism can be scoped later only if this proves insufficient in practice.

This intentionally avoids building a reputation/decay/scoring system for trust itself — the explicit-allowlist + median-aggregation combination gets real poisoning resistance from two mechanisms this codebase already uses elsewhere (allowlist-gating, median-not-mean), not a new one to design, review, and maintain.

#6480 and #6482 (both blocked by this issue) are now unblocked.