skills/ruvnet__ruflo
1
0
Fork 0
mirror of https://github.com/ruvnet/ruflo.git synced 2026-09-14 14:01:28 +08:00
Code Issues Packages Projects Releases Wiki Activity
7,467 Commits 580 Branches 1,645 Tags
docs/chatgpt-plugin-reference
Commit Graph

2 Commits

Author SHA1 Message Date
rUv dbb1f1e1dd feat: capability brain and governed federation plane (#2825) 
Adds the live Ruflo capability brain, governed federation and Cognitum product planes, source-bound concurrent harness contracts, ADRs 325-329, and the v3.32.28 guarded release train.
 2026-07-29 00:13:16 -04:00
rUv 70e2339469 feat(federation): ADR-111 Phases 4-6 — firewall projection + witness chain + MCP tools (#1895) 
* feat(federation): ADR-111 Phases 4-6 — firewall projection + witness chain + MCP tools

Phases 4-6 of ADR-111. Phase 7 (cross-OS WG mesh bringup) is operator-mediated
and lives outside the package — staged but not auto-executed per CLAUDE.md
destructive-actions guidance.

## Phase 4 — Trust-graded firewall projection
`domain/services/wg-firewall-service.ts` (new)
- Two backends: linux-nftables (atomic `nft -f`, table `inet ruflo_fed`,
  default DROP, interface-scoped) and darwin-pf (anchor-scoped pfctl).
- Projects WG_NETWORK_GATES → concrete rule lines per peer.
- UNTRUSTED excluded (no mesh IP), peers without wgMeshIP skipped.
- Defense-in-depth: regex-validated rule args (no shell metachars in
  pubkey/IP/iface).
- Returns rule file content + the load command the operator runs —
  service never shells out.
- 16 unit tests.

## Phase 5 — Witness attestation chain
`domain/services/wg-witness-service.ts` (new)
- Append-only chain of Ed25519-signed entries. Each entry hash-links to
  the previous (`prevHash` = sha256 of previous canonical encoding).
- Canonical encoding: sorted keys, no whitespace, omitted-on-undefined.
- `verifyWitnessChain` walks the chain and reports `failedAt` + reason
  (`broken-chain-link` | `invalid-signature-or-hash`).
- `attestWgCommand` adapter maps WgCommand.verb → event type.
- 11 unit tests (canonicalization stability, deterministic hash,
  chain link integrity, signature-tamper detection).

## Phase 6 — Operator MCP tools
`mcp-tools.ts` (extended)
- `federation_wg_status` — per-peer mesh state (trust, meshIP, AllowedIPs,
  suspended/evicted flags) via `WgMeshService.summarize()`.
- `federation_wg_attest` — operator-signed witness chain entry. v1 stub
  returns wire-up instructions until plugin.ts integrates WgWitnessService.
- `federation_wg_keyrotate` — emits a new X25519 keypair (public key only
  via MCP; private key write is operator-mediated) + the upgrade checklist.
  Requires `confirm: true` (destructive — drops existing tunnels until peers
  fetch updated manifest).
- `createMcpTools` gets optional `getWgMesh` getter (additive, no break).
- `FederationCoordinator.listPeers()` added as public discovery accessor.

## Tests
- 543/543 pre-existing + new tests pass (513 + 27 phase 4/5 + 3 plugin
  test count assertions for the new MCP tools).

## Not in this PR (Phase 7 — operator-mediated)
- Real WG mesh bringup on mac↔ruvultra over tailscale: stage configs,
  operator-approved `wg-quick up`, peer-add via federation manifests,
  SUSPEND → confirm L3 isolation → reactivate restores, witness-verify
  the change log. Tracked alongside #1879.

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(federation): security — validate peer wg fields before splice (ADR-111)

Manual security audit of ADR-111 Phases 1-6 found a real vulnerability in
Phase 2's WgMeshService that the existing tests did not catch.

## The bug

`WgMeshService.buildInterfaceConfig()` and `summarize()` spliced
`peer.metadata.wgPublicKey` / `wgMeshIP` / `wgEndpoint` into the wg-quick
config string *without validation*. The ADR's threat model explicitly
includes "compromised federation peer with valid WG key" — that peer
signs their own manifest, so the Ed25519 signature only proves origin,
not content safety.

Concrete attack: a compromised peer publishes

  wgEndpoint = "host:51820\n[Peer]\nPublicKey = attacker\nEndpoint = ..."

and the operator's wg-quick config ends up with an extra [Peer] block.
Cross-peer lateral movement, bypassing the per-peer trust gates.

Phase 4 (WgFirewallService) already validated meshIP via
`assertSafeRuleArg`. Phase 2 didn't — fixed here.

## The fix

New `readSafePeerWgFields(peer)` returns the validated triple or null.
Three regexes:
  - wgPublicKey: ^[A-Za-z0-9+/]{43}=$            (base64 X25519, 32 raw bytes)
  - wgMeshIP:    ^d.d.d.d/32$ + octet range check
  - wgEndpoint:  ^(hostname|ipv4|[ipv6]):port$  + port range check

Mismatched fields → peer is skipped entirely (no [Peer] block, no
AllowedIPs, summarize() returns empty strings). Silent skip beats partial
write because partial writes can leak attacker content into operator
review while looking syntactically valid.

## Tests

7 new adversarial cases under `WgMeshService — readSafePeerWgFields
(compromised-peer defense)`:
  - newline injection in wgEndpoint
  - wrong-length / non-base64 wgPublicKey
  - out-of-range octet in wgMeshIP
  - missing /32 CIDR
  - port out of range
  - IPv6 bracket positive case
  - summarize() also sanitizes (regression: it used the same unsafe path)

Full suite: 550/550 pass.

Co-Authored-By: RuFlo <ruv@ruv.net>

* feat(federation): ADR-111 Phase 7 staging helper

Generates WG keypair + wg-quick config + per-OS firewall rules on the
current host, naming a single peer. Outputs go to /tmp/adr-111-stage.
Nothing loaded into the kernel — wg-quick up / nft -f / pfctl -f are
operator-mediated.

Usage:
  node scripts/phase7-stage.mjs <localId> <peerId> <peerPk> <peerIP> <peerEndpoint>

Workflow:
  1. Run on host A with placeholder peer values → emit host-A pubkey
  2. Run on host B with placeholder peer values → emit host-B pubkey
  3. Re-run on both with the OTHER host's pubkey → final config files
  4. Operator reviews + activates per the printed checklist

Co-Authored-By: RuFlo <ruv@ruv.net>

* fix(federation): ADR-111 phase7-stage idempotent — reuse key file

Without persistence, every run generates a fresh keypair, which breaks
the cross-feed workflow (run on host A → capture pubkey → run on host B
with A's pubkey → A regenerates a different key on its next run).

Now reads /tmp/adr-111-stage/wg-key-<nodeId>.json if present, falls back
to fresh generation if not. Operator can delete the file to force
rotation.

Co-Authored-By: RuFlo <ruv@ruv.net>

* docs(federation): user guide + Phase 7 bringup procedure + README link

Adds:
  - docs/federation/README.md — full user guide (when to use, MCP tools,
    trust levels, breaker, ADR-111 mesh layer, claude -p headless usage)
  - docs/federation/phase7-mesh-bringup.md — step-by-step cross-OS WG
    mesh activation procedure with operator review checklist
  - README.md — link to docs/federation/ from the existing Federation
    section

Co-Authored-By: RuFlo <ruv@ruv.net>

---------

Co-authored-by: Reuven <cohen@ruv-mac-mini.local>
 2026-05-10 23:03:19 -04:00