mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
docs: refresh tutorials, how-to, design, reference, and examples for v0.4.0
Pre-cut documentation pass for the 0.4.0 release, verified against current source. Corrections: - fipsctl: stale 'show identities'/'show node' -> 'show status' (host-a-service, run-as-unprivileged-user) - mesh address derivation: first 16 bytes of SHA-256(pubkey) with the leading byte set to 0xfd, not a fixed fd97: prefix (reach-mesh-services, ipv6-adapter-walkthrough) - gateway control socket mode 0660 -> 0770 (troubleshoot-gateway) - Tor example: add advertised_port: 8443 so the published port matches the prose (enable-nostr-discovery) - bloom mesh-size estimate rewritten to the OR-union-of-peer-filters algorithm; plus mtu deep-link, gateway pool wording, and a NAT failure-mode line - examples: delete orphaned nostr-rs-relay config, accept inbound to the local 8443 TCP listener, fix fd::/8 -> fd00::/8 typos, dotless wireguard alias Additions: - new Nym mixnet transport section (fips-transport-layer) and the architecture transport list - new LAN/mDNS discovery section (fips-nostr-discovery) - reference docs: Nym transport, LAN discovery, and new control/stats surfaces; drop ble from the connect transport list
This commit is contained in:
Johnathan Corgan
@@ -39,7 +39,7 @@ fips sidecar:
|
||||
4. Starts dnsmasq and then `exec`s the FIPS daemon.
|
||||
|
||||
The app container starts concurrently and immediately sees `lo`, `eth0`, and
|
||||
`fips0`. DNS for `<npub>.fips` names resolves to `fd::/8` addresses via the
|
||||
`fips0`. DNS for `<npub>.fips` names resolves to `fd00::/8` addresses via the
|
||||
dnsmasq → FIPS daemon pipeline.
|
||||
|
||||
```text
|
||||
|
||||
@@ -73,13 +73,14 @@ ws://npub1xxxx.fips:80
|
||||
|
||||
The sidecar pattern enforces strict network isolation on the app container:
|
||||
|
||||
- **No IPv4 access**: iptables blocks all eth0 traffic except FIPS UDP
|
||||
transport (port 2121) and TCP transport (port 443). The app container
|
||||
- **No IPv4 access**: iptables blocks all eth0 traffic except the FIPS UDP
|
||||
transport (port 2121), the local FIPS TCP listener (port 8443), and
|
||||
outbound TCP to peers' published endpoints (port 443). The app container
|
||||
cannot reach the Docker bridge, the host network, or any IPv4 address.
|
||||
- **No IPv6 on eth0**: ip6tables blocks all IPv6 traffic on eth0. The app
|
||||
container cannot use link-local or any Docker-assigned IPv6 addresses.
|
||||
- **FIPS mesh only**: The only routable network path is through `fips0`
|
||||
(`fd::/8`). All application traffic traverses the FIPS mesh with
|
||||
(`fd00::/8`). All application traffic traverses the FIPS mesh with
|
||||
end-to-end encryption.
|
||||
- **Loopback allowed**: `lo` is unrestricted for inter-process communication
|
||||
within the shared namespace.
|
||||
@@ -105,7 +106,7 @@ with the transport layer directly.
|
||||
│ Interfaces: │
|
||||
│ lo — loopback (unrestricted) │
|
||||
│ eth0 — Docker bridge (iptables: FIPS only) │
|
||||
│ fips0 — FIPS TUN (fd::/8, unrestricted) │
|
||||
│ fips0 — FIPS TUN (fd00::/8, unrestricted) │
|
||||
└───────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
@@ -118,7 +119,8 @@ before launching the FIPS daemon:
|
||||
|
||||
- ACCEPT on `lo` (both directions)
|
||||
- ACCEPT UDP sport/dport 2121 on `eth0` (FIPS UDP transport)
|
||||
- ACCEPT TCP dport 443 / sport 443 on `eth0` (FIPS TCP transport)
|
||||
- ACCEPT TCP dport 443 / sport 443 on `eth0` (outbound to peers' TCP endpoints)
|
||||
- ACCEPT TCP dport/sport 8443 on `eth0` (local FIPS TCP listener, `FIPS_TCP_BIND`)
|
||||
- DROP everything else on `eth0`
|
||||
|
||||
**IPv6 rules** (ip6tables):
|
||||
@@ -132,7 +134,7 @@ before launching the FIPS daemon:
|
||||
DNS inside the container is handled by dnsmasq (127.0.0.1:53):
|
||||
|
||||
- `.fips` queries are forwarded to the FIPS daemon's built-in DNS resolver
|
||||
(127.0.0.1:5354), which resolves npub-based names to `fd::/8` addresses
|
||||
(127.0.0.1:5354), which resolves npub-based names to `fd00::/8` addresses
|
||||
- All other queries are forwarded to Docker's embedded DNS (127.0.0.11)
|
||||
|
||||
The `resolv.conf` mount points the container's resolver at 127.0.0.1,
|
||||
@@ -165,7 +167,8 @@ From the app container:
|
||||
# Ping a mesh node by npub (resolves via .fips DNS):
|
||||
docker exec sidecar-nostr-relay-app-1 ping6 -c3 npub1xxxx.fips
|
||||
|
||||
# Fetch a web page from a mesh node over FIPS:
|
||||
# Fetch a web page from some other mesh node over FIPS
|
||||
# (:8000 is a stand-in for that node's own service; this relay serves :80):
|
||||
docker exec sidecar-nostr-relay-app-1 curl -6 "http://npub1xxxx.fips:8000/"
|
||||
|
||||
# Docker bridge is blocked — this should fail:
|
||||
|
||||
@@ -70,6 +70,8 @@ iptables -A INPUT -i eth0 -p udp --dport 2121 -j ACCEPT
|
||||
iptables -A INPUT -i eth0 -p udp --sport 2121 -j ACCEPT
|
||||
iptables -A OUTPUT -o eth0 -p tcp --dport 443 -j ACCEPT
|
||||
iptables -A INPUT -i eth0 -p tcp --sport 443 -j ACCEPT
|
||||
iptables -A INPUT -i eth0 -p tcp --dport "${FIPS_TCP_BIND##*:}" -j ACCEPT
|
||||
iptables -A OUTPUT -o eth0 -p tcp --sport "${FIPS_TCP_BIND##*:}" -j ACCEPT
|
||||
iptables -A OUTPUT -o eth0 -j DROP
|
||||
iptables -A INPUT -i eth0 -j DROP
|
||||
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
# nostr-rs-relay configuration for FIPS mesh deployment.
|
||||
# Full reference: https://github.com/scsibug/nostr-rs-relay
|
||||
|
||||
[info]
|
||||
# Shown in NIP-11 relay information document.
|
||||
relay_url = "" # Set to ws://[<your-fips-ipv6>]:8080 after first start
|
||||
name = "FIPS Nostr Relay"
|
||||
description = "A Nostr relay accessible over the FIPS mesh network."
|
||||
pubkey = "" # Optional: your npub (hex) as relay operator
|
||||
contact = "" # Optional: contact address
|
||||
|
||||
[database]
|
||||
# SQLite database path inside the container (mapped to relay-data volume).
|
||||
data_directory = "/usr/src/app/db"
|
||||
|
||||
[network]
|
||||
# Bind on all interfaces (IPv4 + IPv6) — FIPS delivers traffic via the fips0
|
||||
# TUN as IPv6 (fd00::/8). Using 0.0.0.0 with port 8080; the relay also needs
|
||||
# to accept IPv6 connections so we set port separately and rely on the OS
|
||||
# dual-stack socket (IPV6_V6ONLY=0).
|
||||
# nostr-rs-relay address field is just the IP, port is separate.
|
||||
address = "0.0.0.0"
|
||||
port = 8080
|
||||
ping_interval_seconds = 300
|
||||
|
||||
[limits]
|
||||
# Adjust to taste. These are conservative defaults for a personal relay.
|
||||
messages_per_sec = 10
|
||||
subscriptions_per_min = 20
|
||||
max_blocking_threads = 4
|
||||
max_event_bytes = 131072 # 128 KiB per event
|
||||
max_ws_message_bytes = 131072
|
||||
max_ws_frame_bytes = 131072
|
||||
broadcast_buffer = 16384
|
||||
event_persist_buffer = 4096
|
||||
|
||||
[authorization]
|
||||
# Set to true to require NIP-42 AUTH before accepting events.
|
||||
# Useful for a private relay — only authenticated users can publish.
|
||||
nip42_auth = false
|
||||
nip42_dms = false
|
||||
|
||||
[verified_users]
|
||||
# NIP-05 verification (optional).
|
||||
mode = "disabled"
|
||||
|
||||
[pay_to_relay]
|
||||
# Lightning payments for relay access (optional).
|
||||
enabled = false
|
||||
@@ -20,7 +20,9 @@ transports:
|
||||
|
||||
peers:
|
||||
- npub: "npub1zv58cn7v83mxvttl70w5fwjwuclfmntv9cnmv5wmz2nzz88u5urqvdx96n"
|
||||
alias: "fips.v0l.io"
|
||||
# alias becomes the peer's .fips hostname (<alias>.fips), so it must be a
|
||||
# plain label with no dots — the connection address below is the real host.
|
||||
alias: "v0l"
|
||||
addresses:
|
||||
- transport: tcp
|
||||
addr: "fips.v0l.io:8443"
|
||||
|
||||
Reference in New Issue
Block a user