mirror of https://github.com/jmcorgan/fips.git synced 2026-07-22 07:48:26 +00:00

Files

Johnathan Corgan 5abf9a9325 docs: four-section /docs/ restructure with new-user content, accuracy pass, and gateway feature-set rewrite

Restructures /docs/ by reader purpose (tutorials, how-to,
reference, design), adds the new-user-progression and
operator-recipe content the prior layout lacked, runs an
accuracy pass against current source across the pre-existing
design docs, and rewrites the gateway feature-set documentation
end-to-end around its actual operational profile (a niche
feature designed for systems already serving DHCP/DNS to a
LAN, with two independent halves — outbound LAN→mesh, inbound
mesh→LAN — sharing one nftables table, one binary, and one
control socket). Top-level README and getting-started rewritten
around two equally-weighted deployment modes (overlay on
existing IP networks; ground-up over non-IP transports).

## Additions

- 11 new tutorials in docs/tutorials/: an 8-step new-user
  progression from single-daemon test-mesh peering through
  to a ground-up two-device mesh, an IPv6-adapter side-trip
  walkthrough, an Advanced Tutorials index, and a hand-held
  OpenWrt walk-through for fips-gateway deployment that
  exercises both halves of the feature.
- 12 new how-tos in docs/how-to/: firewall activation,
  Nostr discovery (resolve / advertise / open across five
  scenarios), Tor onion (directory + control_port modes),
  UDP buffer tuning, unprivileged-user setup, persistent
  identity, host aliases, Bluetooth LE peering, MTU
  diagnostics, manual Linux-host gateway deployment (covers
  both halves), gateway troubleshooting (organised by half),
  and a section index.
- 9 new reference docs in docs/reference/: configuration,
  wire formats, control-socket protocol, four CLI references
  (fips, fipsctl, fipstop, fips-gateway), security posture
  matrix, and Nostr events catalog. Configuration and
  wire-formats are renamed-and-extended from prior design/
  versions; the other seven are net-new.
- 6 new design docs: fips-concepts, fips-architecture, and
  fips-prior-work split out of the deleted fips-intro.md;
  consolidated fips-mmp and fips-mtu aggregations; and a
  new generic port-advertisement-and-nat-traversal doc
  (Nostr-signaled port advertisement plus UDP NAT-traversal
  protocol, FIPS as an example implementation, suitable for
  eventual NIP submission).
- Top-level docs/getting-started.md walking through the
  binary-installer-only Install story.
- packaging/common/hosts pre-populated with the eight public
  test-mesh nodes so shortnames resolve out of the box on
  every fresh install.

## Changes

- 23 wire-format diagrams relocated to reference/diagrams/
  alongside the wire-formats move.
- 4 design diagrams corrected against source code
  (fips-protocol-stack, fips-identity-derivation,
  fips-coordinate-discovery, fips-routing-decision).
- 10 pre-existing design docs reconciled with current
  source. Numeric corrections: stale link-MMP report bounds
  (now [1s, 5s] with 200 ms cold-start floor); UDP default
  MTU (now 1280, IPv6 minimum); node_addr formula
  (SHA-256(pubkey)[..16]); Noise patterns (IK at link, XK
  at session); peer-ACL semantics (strict allowlist requires
  ALL in peers.deny); daemon DNS upstream ([::1]:5354);
  on-the-wire bloom-filter size (1,071 bytes); obsolete
  Cargo-feature references (PR #79 dropped them) removed.
- Transport framing tightened across the docs: TCP is for
  UDP-filtered networks (not NAT traversal); Tor is a
  deployment mode (not failover); WebSocket dropped (not a
  shipped FIPS transport); WiFi promoted to Implemented via
  Ethernet in infrastructure mode; classic-Bluetooth row
  removed (BLE is the only Bluetooth-mode transport).
- docs/design/fips-gateway.md rewritten end-to-end to lead
  with the niche-feature framing and the two-halves
  structure. Title moved from "FIPS Outbound LAN Gateway"
  to "FIPS Gateway"; architecture section describes the
  common machinery (the fips-gateway service, the nftables
  table, the control socket) before splitting into separate
  "Outbound Half" and "Inbound Half" sections of equal
  weight; security considerations split per-half; no Future
  Work section (speculative directions live in the project
  tracker, not in protocol design docs). Inbound port
  forwarding is a first-class half rather than a buried
  "Implemented Extensions" subsection.
- Gateway terminology unified across all gateway docs as a
  separate Linux service running alongside the fips daemon
  (its own systemd unit / OpenWrt init script). Container-
  pattern terms (sidecar) are reserved for the
  Docker/Kubernetes sidecar deployment examples — the
  testing/sidecar/ tree, examples/k8s-sidecar/,
  examples/sidecar-nostr-relay/,
  examples/wireguard-sidecar-macos/, and the related
  CHANGELOG / top-level README entries — where the term
  carries its standard container meaning.
- Net-new design body content: rekey section in
  fips-mesh-layer (Noise IK msg1/msg2 over the established
  link, K-bit cutover, drain window, smaller-NodeAddr-wins
  tie-breaker on dual-init); Mesh Size Estimation and
  Antipoison FPR Cap sections in fips-bloom-filters;
  Mesh-Interface Query Filter subsection in
  fips-ipv6-adapter; failure-suppression knobs and clock-
  skew tolerance in fips-nostr-discovery; loop-rejection
  and mid-chain ancestor swap added to spanning-tree
  propagation / stability rules; Priority Chain in
  fips-mesh-operation renumbered to match the
  routing-decision diagram.
- Top-level README: dropped the stale nostr-discovery
  cargo-feature parenthetical. docs/README.md and the four
  section READMEs (tutorials, how-to, reference, design)
  refreshed for the new structure; index rows reflect both
  halves of the gateway feature and the new fips-gateway
  CLI reference.
- Cargo.toml [package.metadata.deb] assets path updated for
  the fips-security.md move; .gitignore /reference/ rule
  anchored to repo root so docs/reference/ is trackable.
- packaging/openwrt-ipk/files/etc/fips/fips.yaml
  configuration-doc URL updated to the new
  docs/reference/configuration.md location.

## Deletions

- docs/design/fips-intro.md (split into the three new intro
  design docs).
- docs/design/document-relationships.svg (orphan, no longer
  referenced).
- docs/proposals/ tree removed; the only proposal it
  contained (the Nostr UDP hole-punch protocol) was
  rewritten as the new generic
  design/port-advertisement-and-nat-traversal.md.

2026-05-08 03:02:12 +00:00

6.1 KiB

Raw Permalink Blame History

Use Shortnames Instead of Long Npubs

A FIPS node's canonical address is <npub>.fips. The npub is 63 characters of bech32 — fine for the daemon, awkward to type or fit in a docs example. The local DNS resolver consults a host map before falling back to direct-npub resolution, so short names like test-us01.fips work as substitutes wherever <npub>.fips would.

This guide covers the two ways to populate that map and when to use which.

When to use which

Two independent mechanisms feed the same DNS responder:

Mechanism	Source	Scope	Reload
Hosts file	`/etc/fips/hosts`	Node-local, intended for shared rosters	Auto on mtime change
Peer alias	`alias:` field on a `peers:` entry	Node-local, scoped to configured peers	Daemon restart

Pick the hosts file when:

The shortname refers to a peer your operator-team agrees to call by that name across machines (the public test mesh ships this way).
You want the destination's name to resolve in DNS or appear in fipsctl show peers display even though it isn't in your peers: block — e.g., a mesh node you reach transitively through your direct peers. The hosts-file entry is for name resolution and display only; it does not stand in for the npub a peer-config entry requires.

Pick the peer alias when:

The shortname is just a label you use locally for a peer that's already in your peers: block.
You want the alias to live with the rest of the peer config (one place to look) rather than in a separate file.

The two coexist. If both reference the same shortname, /etc/fips/hosts wins — the file is treated as the authoritative shared roster.

What ships in the default `/etc/fips/hosts`

The installer drops /etc/fips/hosts populated with the public test mesh roster:

test-us01      npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98
test-us02      npub10yffd020a4ag8zcy75f9pruq3rnghvvhd5hphl9s62zgp35s560qrksp9u
test-us03      npub136yqae6na688fs75g95ppps3lxe07fvxefj77938zf47uhm6074sxw8ctm
test-us03-next npub15m6c4ghuegx4pcde6tra8f7smn8vfv2wundyxwhkjynuerkrzmgsy09sh3
test-us04      npub1gd7ye2qp2lphhzx75fynnjzaxx4dqanddecet0wtt5ss5ek8h9ps62wdkf
test-de01      npub1260n42s06vzc7796w0fh3ny7zcpw6tlk4gq3940gmfrzl5c9pv2s3657q8
test-es01      npub17lpmzulpc98d8ff727k6e98atxn3phzupzsqqwe54ytduym747ws4tw5zm
test-uk01      npub1u0z26dc4qeneu5rvwvmpfhtwh3522ed6rlgxr9jarrfnjrc6ew4qxjysrs

These resolve out of the box — ping6 test-us01.fips works even before you've added any peer to your config, as long as the destination is reachable through your mesh links.

If you don't intend to interact with the public test mesh, the entries are safe to comment out or delete. They are plain hosts-file lines, not protocol participants — removing them only changes name resolution on your machine.

Add an entry to `/etc/fips/hosts`

Append a line to /etc/fips/hosts:

my-laptop     npub1abc...xyz

Format rules:

One hostname and one npub per line, separated by whitespace.
Hostnames are lowercase letters, digits, and hyphens; max 63 characters.
Comments start with # and continue to end of line; blank lines are ignored.
On duplicate hostnames, the last entry wins.

The daemon picks up the change on the next DNS query — no restart required (the file's mtime is checked on each query). Verify:

dig my-laptop.fips AAAA +short

Expect one fd97:... AAAA record.

/etc/fips/hosts is shipped as a dpkg conffile (and the AUR equivalent), so package upgrades preserve your edits. The file is 0644 root:root — readable by anyone, writable by root.

Add a peer alias

In /etc/fips/fips.yaml, set the alias: field on the peer entry:

peers:
  - npub: "npub1abc...xyz"
    alias: "my-laptop"
    addresses:
      - transport: udp
        addr: "192.0.2.10:2121"
    connect_policy: auto_connect

Restart the daemon for the alias to take effect:

sudo systemctl restart fips
dig my-laptop.fips AAAA +short

The alias also shows up in fipsctl show peers display_name column, so log entries and CLI output reference the peer by shortname instead of truncated npub.

Resolution order

When the DNS responder receives a query for <name>.fips:

Hosts file lookup. If <name> matches an entry in /etc/fips/hosts, the daemon returns the AAAA record derived from that entry's npub.
Peer alias lookup. If <name> matches the alias field on a configured peer, return that peer's AAAA.
Direct npub resolution. If <name> is itself a valid bech32 npub (the canonical 63-char npub1... form), the daemon returns the AAAA derived from that npub directly.
NXDOMAIN. If none of the above match, the query returns no answer.

The order means the hosts file overrides peer aliases on conflict. That's deliberate: the file represents operator-shared naming, the peer alias is a node-local label.

Cross-references and ACLs

Aliases interact with the peer ACL — if you maintain peers.allow or peers.deny lists keyed on hostnames rather than npubs, those names go through the same hosts-file resolution. See ../reference/security.md for the ACL format and the alias-resolution semantics.

fipsctl connect and fipsctl disconnect accept a shortname where they expect an npub. Resolution for these commands goes through /etc/fips/hosts only — peer-config alias: entries are not loaded by fipsctl, so a shortname that exists only as a peer alias must still be referenced by full npub on the CLI. See ../reference/cli-fipsctl.md.

6.1 KiB Raw Permalink Blame History