Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,13 @@ mesh (browsers) and an HTTP origin, which a public deployment puts behind TLS an
The optional Hypercore profile (NFX-12) and payments (Cashu ecash, per delivered chunk)
are specified as drafts.

**Status (2026-11-07):** NFX 0.1.1 is the latest release (0.1.0 was the first): `nfxd` and
`nfx-package` for linux-x64 on the [Releases page](https://github.com/SovereignTechnology/nfx/releases),
free video only ([release notes](docs/nfx/releases/v0.1.1.md); [0.1.0](docs/nfx/releases/v0.1.0.md)).
0.1.1's relay also searches a video's title. It is tested against the nutflix-pear desktop
app in both directions, behind NATs and over TLS relays. The public services on `nfx:testnet:1` are an iroh
**Status (2026-11-16):** NFX 0.1.2 is the latest release: `nfxd` and `nfx-package` for
linux-x64 on the [Releases page](https://github.com/SovereignTechnology/nfx/releases), free video
only ([release notes](docs/nfx/releases/v0.1.2.md); earlier: [0.1.1](docs/nfx/releases/v0.1.1.md),
[0.1.0](docs/nfx/releases/v0.1.0.md)). 0.1.2's `nfxd` also serves browsers directly, through NATs,
signaling only over Nostr relays (its mesh endpoint, NFX-10 §6), and a video gets one rendition
by default. It is tested against the nutflix-pear desktop app in both directions, behind NATs and
over TLS relays, and against browsers behind NATs. The public services on `nfx:testnet:1` are an iroh
relay, `https://iroh.nutflix.xyz/`, and a scoped Nostr relay, `wss://relay.nutflix.xyz` ([testnet](docs/nfx/testnet.md)). The free end-to-end slice (milestone M1: publish, seed, fetch,
play; no payments) is built and passed its exit run. That run and the Phase A exit run before it used two
hosts on a private network with plain HTTP and WebSocket endpoints; they did not cover
Expand Down
6 changes: 3 additions & 3 deletions crates/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion crates/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ n0-future = "0.3.2"
nostr-database = "0.45.2"
nostr-memory = "0.45.2"
nostr-sdk = "0.45.4"
nfx-node = { path = "nfx-node", version = "0.1.1" }
nfx-node = { path = "nfx-node", version = "0.1.2" }
nfx-pay = { path = "nfx-pay", version = "0.1.0" }
nfx-pay-wire = { path = "nfx-pay-wire", version = "0.1.0" }
nfx-proto = { path = "nfx-proto", version = "0.1.0" }
Expand Down
4 changes: 2 additions & 2 deletions crates/desktop/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion crates/desktop/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ http-body-util = "0.1.5"
hyper = "1.11.1"
iroh = "1.2.0"
nfx-proto = { path = "../nfx-proto", version = "0.1.0" }
nfxd = { path = "../nfxd", version = "0.1.1" }
nfxd = { path = "../nfxd", version = "0.1.2" }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0.151"
tauri = "2.11.6"
Expand Down
2 changes: 1 addition & 1 deletion crates/nfx-media/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "nfx-media"
version = "0.1.1"
version = "0.1.2"
description = "NFX-05 packaging: rendition sizes (one by default) and the demo's L8 argv planning ported to Rust, an HLS/fMP4 tail, content addressing and hash-list assembly"
edition.workspace = true
rust-version.workspace = true
Expand Down
2 changes: 1 addition & 1 deletion crates/nfx-node/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "nfx-node"
version = "0.1.1"
version = "0.1.2"
description = "NFX peer: content store, iroh seeding and fetching with sha256 re-anchoring (NFX-05/06), gossip presence, Nostr manifests and beacons (NFX-02/03), the pull-through origin (NFX-05 §6), an embeddable scoped relay (NFX-04)"
edition.workspace = true
rust-version.workspace = true
Expand Down
2 changes: 1 addition & 1 deletion crates/nfxd/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "nfxd"
version = "0.1.1"
version = "0.1.2"
description = "The headless NFX node: seed, fetch, pull-through origin and an embedded scoped relay"
edition.workspace = true
rust-version.workspace = true
Expand Down
176 changes: 176 additions & 0 deletions docs/nfx/releases/v0.1.2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# NFX 0.1.2

`nfxd` can now serve browsers directly, through NATs, with Nostr relays as the only signaling
path: its new mesh endpoint is a full-ICE WebRTC peer that meets browsers in the rooms of the
renditions it holds (NFX-10 §6), with no tracker and no TURN. This release also adds a STUN
responder, seeders that hold only some renditions, a one-rendition packaging default, and flags
for seeders behind a NAT or a DNAT. As before: `nfxd` and `nfx-package`, prebuilt for linux-x64,
beside the source; free video only.

## What changed

- **The mesh endpoint** (#82, #86). `nfxd run --mesh-relay <url>` (1 to 8 relays, off by
default) joins one room per held rendition through those Nostr relays. Offers and answers are
kind 25050 events (`nfx-mesh/1`), NIP-44 v2 encrypted between per-run session keys, never the
node's own key. Browsers then fetch verified segments over WebRTC with str0m's full ICE agent.
- **Candidates:** the bound address; server-reflexive mappings from up to four `--mesh-stun`
servers, asked from the same socket at start and every 25 s; and a gateway port mapping
(UPnP, PCP, NAT-PMP) when the gateway gives one and iroh's port mapping is on.
- **Serving:** the endpoint shares the bridge's serving code. It serves only verified segments
of held renditions, under the same per-peer caps, and never stores a peer's bytes.
- **Limits:** `--mesh-max-peers` (1 to 1024, default 16) and 16 connections per room. Of a
peer's SDP the node keeps at most 8 UDP candidates of its socket's family, never
unspecified, multicast, broadcast, link-local or IPv4-mapped, and loopback only on loopback.
STUN responses count only from a configured server, for a transaction the node sent.
- **Behind a DNAT:** `--mesh-public <ip:port>`, with `--mesh-bind` on the fixed port the DNAT
forwards. It must be a public unicast address of the bind's family. With it set, the node
offers no candidate whose address is not public. `nfxd` prints `mesh public: udp <ip:port>`
at start.
- **Privacy:** joining a room tells anyone who announces presence there the node's candidate
addresses, public ones included. The usage text and the README say so.
- **A STUN responder** (#74). `nfxd run --stun <ip:port> [--stun-public <ip:port>]` answers RFC
8489 Binding requests with XOR-MAPPED-ADDRESS only: no TURN, no authentication, rate-limited per
source, per prefix and in all, and nothing about a client is logged. Beacons gain a `stun`
endpoint (`{ "t": "stun", "addrs": [...] }`, NFX-10 §1), so pages find STUN over Nostr as they
find trackers.
- **Seeders that hold only some renditions** (#77). `--seed`, `--fetch` and `--pull` take
`<a>#<id>[,<id>...]`, as in `--seed <a>#720p`. Such a node holds the hash list, the whole meta
collection and only those renditions' inits and segments. Its origin answers 404 for other
renditions' inits and segments and never pulls them through. Its beacons say what it holds;
the `https` endpoint carries a new optional `renditions` list. Without `#`, a node holds every
rendition, as before. An id the hash list lacks fails that item and names the ids it has.
- **One rendition by default** (#76). `nfx-package` makes a single rendition, 720p, or the
source's own size when that is smaller. `--renditions <size>[,<size>...]` picks any sizes the
source offers, from 2160p to 360p and the source's own size, and never upscales. A size is the
picture's short side: 720p is 1280x720 landscape or 720x1280 portrait.
- **Seeders behind a NAT or a DNAT** (#47, #48).
- `--iroh-bind <ip:port>` fixes the iroh socket's port.
- `--iroh-external <ip:port>` (at most 4, needs `--iroh-bind`) is advertised as given. With
any set, tickets and beacons carry no other direct address unless it is public.
- `--bridge-public <ip:port>` is the address the ICE-lite bridge tells browsers.
- `--bridge-max-peers` (1 to 1024, default 64) caps the browser connections the bridge holds.
- **An iroh relay that is reached late is still announced** (#47). In 0.1.1 a node gave its
`--iroh-relay` 10 s, and a relay reached after that was missing from its tickets until a
restart. Beacons are now made from the node's current address, so a relay that connects later
is in the next beacon. To make the first beacons name it, a node waits at most 60 s for the
relay before it seeds (state `AwaitingRelay`), then seeds without it and warns. With
`--iroh-external` it does not wait at all.
- **Long fetches finish** (#70). A collection transfer had a fixed 120 s, so a 963-file, 652 MiB
video through an iroh relay at 4 MiB/s always timed out and started over. The deadline now grows
with the hash list's files and bytes (1 s a file and 1 MiB/s, at most 30 s a file), and a retry
resumes from the files already stored.
- **SIGTERM** stops `nfxd run` as SIGINT does (#82), so a service manager's stop still sends the
mesh rooms their `disconnect`.
- **The specification** (#74, #75, #77). These are Draft additions, or optional fields that
existing readers ignore (NFX-01 §4, NFX-03 §4), so 0.1.1 nodes keep accepting 0.1.2 beacons.
- NFX-10 §6: signaling over Nostr, with its vectors.
- NFX-03 §4 and §5: a seeder of some renditions, and rendition selection.
- The `stun` endpoint, the beacon schema, and the new vectors `beacon-renditions.json` and
`beacon-stun.json`.
- `nfx-proto` reads and opens the signaling events and implements NIP-44 v2.
- **The browser player is a library** (#73, #80, #83, #87; from source, not in the tarball).
nutflix-pear's web client consumes it, pinned by commit and sha256, from a reproducible tar.
- It signals over Nostr relays with no tracker (`signaling: { kind: 'nostr', relays }`).
- It offers only levels that a source holds, and takes `renditions`, the allowed ids in order.
- It asks an origin which renditions it holds before offering a level. A beacon's claim about
an origin is only a hint, so a stranger's beacon can no longer make a page skip an origin or
drop a level (#85).
- **Dependencies:** rustix 1.1.6 for RUSTSEC-2026-0486 (#88). nfx never calls the affected xattr
functions, and that is the only change to the binaries' locked dependencies since 0.1.1.
`cargo deny` now checks unsound and unmaintained advisories across the whole tree (#69).
hls.js is 1.7.4 in the web player.
- **The crates are 0.1.2** (`nfxd`, `nfx-node`, `nfx-media`), and the scoped relay's NIP-11
document says so.

## Operators: what to change

Every new flag is off by default, and a 0.1.1 command line runs unchanged. Three defaults moved:

- `nfx-package` makes one rendition. For the old ladder, pass `--renditions 1080p,720p,360p`.
- With `--iroh-relay`, `nfxd run` waits up to 60 s for the relay before it seeds, where 0.1.1
waited 10 s; an unreachable relay delays seeding by that much.
- SIGTERM is a clean shutdown.

To serve browsers from a node behind a home NAT, add `--mesh-relay wss://<relay>` (a general
Nostr relay that carries ephemeral kind 25050 events) and `--mesh-stun <ip:port>`. Behind a DNAT,
use `--mesh-bind <ip:port> --mesh-public <public ip:port>` instead of STUN. An NFX-04 scoped relay
(`--embed-relay` and `wss://relay.nutflix.xyz` included) takes only manifests, beacons and
deletions and refuses kind 25050, so it cannot be a mesh relay. Browsers must use at least one of
the same relays.

## Tested

- **The NAT test with real browsers** (#81, `nfx-nat-browsers.yml`). Two headless Chromium, each
behind its own nftables router in a network namespace. Signaling went only through a stock
Nostr relay (strfry with its own default configuration; the browsers reached it over TLS), and
server-reflexive candidates came only from a public `nfxd --stun`. There was no tracker and no
TURN. Every cell also checked that the relay carried only kind 25050 `nfx-mesh/1` events,
offers and answers as NIP-44 ciphertext with no SDP or address in clear, and that nothing
crossed either router but the relay, STUN, the origin and the other router. Run 42790887367,
all four cells pass:

| Cell | Outcome |
|---|---|
| browser and browser, consistent NATs | Connected in 502 ms, srflx to srflx on both sides. After the origin was cut, B played 15 s on mesh bytes alone, with 0 HTTP bytes. |
| browser and browser, symmetric NATs | No punch, as expected: every negotiation ended unconnected (15.06 to 15.48 s over seven runs), and B played on from the origin. |
| browser and browser, consistent and symmetric | No punch either (the routers' filtering is address- and port-dependent); B played on. |
| `nfxd` and a browser, consistent NATs | Connected in 1374 ms, srflx to srflx. `nfxd` served 28 segments, and B played 15 s past the origin cut on mesh bytes alone. |

- **A browser and `nfxd`'s mesh endpoint over Nostr only** (#84, `e2e:nostr-node`), in a Kata VM:
3 of 3 runs pass, with the node offering in two and the browser in one. In each run the origin
was cut at about 3 s and the page played on to 18 s with about 18 MB from the mesh. The node
reported `opened 1, failed 0, segments served 28`, and the relay carried one offer, one answer
and the node's `disconnect`. `nfxd` exited 0 on SIGTERM.
- **The mesh endpoint in Rust** (#82, #86): a browser-like str0m peer finds the endpoint by room
alone, negotiates in both glare directions, and checks segment 0's sha256. It does so on
loopback, and through a DNAT simulated in the test, where the endpoint's SDP names only its
public address. In memory, the endpoint punches through two consistent NATs, where the
bridge's ICE-lite agent cannot, and through a DNAT when told its public address, but not
without it. Every start-time refusal of the `--mesh-*` flags is tested.
- **STUN** (#74): Binding round trips over IPv4, IPv6 and dual stack, the RFC 5769 vectors, and
200,000 random and mutated datagrams against an independent oracle, plus the rate limits.
- **Renditions** (#77, #83, #87), end to end in a Kata VM. A seeder holding only 360p of a
two-rendition video: the page offers 360p alone and fetches no 720p segment. A stranger's
`nfxd` naming an honest origin with `renditions: ["360p"]`: the page still offers 720p and
plays it when asked. The web library's unit tests pass, 352 of 352.
- **Fetch** (#70): a paced transfer longer than its base deadline completes, and transfers that
each time out finish by resuming.
- The release tree passed CI on its pull request: fmt, clippy at `-D warnings`, the tests,
`cargo deny` and the money lock. The release is built as 0.1.1's was (below).

## What it does not do

- **No payments.** The money crates (`crates/nfx-pay`, `crates/nfx-pay-wire`) are locked and not
deployed; every video served is free.
- **`nfxd` does not fetch from browsers yet.** The mesh endpoint serves (`nfxd` to browser); the
other direction is open (#71).
- **`nfxd` behind a symmetric NAT is not covered.** The NAT test's `nfxd` cell is consistent on
both sides. Two peers behind symmetric NATs, or behind one symmetric and one consistent NAT that
filters by address and port, do not punch. There is no TURN by design, so such a viewer plays
from the origin.
- **Fetch throughput** is still open (issue #21).
- As in 0.1.1: **Linux x64 binaries only**, not signed by an operating-system vendor. The
Hypercore profile (NFX-12) is not implemented in Rust. The desktop viewer and the web player
are built from source.

The public testnet's services and their limits are listed in [testnet.md](../testnet.md).

## Verify

`sha256sum -c SHA256SUMS` checks that the tarball is intact; it does not say who made it. For that,
the release carries `release-event.json`: a Nostr release notice (kind 30071, `d` = `nfx`) signed
by the SovTech key `npub1s0vtechh66tx7vrwdud8zfyheu9zca7swwfrzd4qu2a4f93mxs6qvn9adx`, listing the
tarball's sha256 and size; the same notice is on Nostr relays. To check it, with Node 22.18 or
newer and a checkout of nutflix-pear (whose release scripts sign and verify both projects'
notices):

```sh
git clone https://github.com/SovereignTechnology/nutflix-pear.git && cd nutflix-pear
npm ci --ignore-scripts
node scripts/release-verify.mjs release-event.json --d nfx nfx-0.1.2-linux-x64.tar.gz
```

It checks the signature, that the key is SovTech's, that the notice is NFX's, and the file's size
and sha256. The release is built by `.github/workflows/release.yml` from the tagged commit in the
pinned `rust:1.98.0-bookworm` image, `--locked`, with the commit's timestamp and the build paths
remapped.