FIPS Mesh Plugin (fips)
Nostr-native FIPS peer networking and UDP NAT traversal for collaborative team apps in AppWeaver.
Command: /fips
Overview
The fips plugin manages:
- A dedicated, plugin-generated FIPS node identity (
fips_pubkey, encrypted at rest indb.sqlitevia core'sencryptSecret), keeping coreBOT_KEYisolated. - Experimental UDP + Nostr NAT Traversal (
udp-nostr-transport.ts):- Inspired by the
jmcorgan/fipsNostr discovery and traversal specification; Rust interoperability is not yet verified:- Publishes replaceable kind
37195overlay adverts (udp:nat). - Exchanges NIP-59 / NIP-44 gift-wrapped kind
21059TraversalOfferandTraversalAnswerevents over explicitly persisted invitation relays. - Performs STUN reflexive discovery + local LAN/loopback candidate gathering and 24-byte
NPTC/NPTAUDP hole punching. - Hands the punched UDP socket directly to
@fips/corefor Noise IK (FMP link) and Noise XK (FSP end-to-end session) encryption.
- Publishes replaceable kind
- Inspired by the
- Optional FIPS WebSocket seed URLs (
wss://...orws://127.0.0.1:...) as an additional carrier; automatic fallback after a failed UDP dial is not implemented. - A Peer Roster (
fips_peers) binding each teammate's humanmaster_pubkeyto their instance's 33-byte compressedfips_pubkey. - Capability Contract (
peer-network:v1) for explicit-node text/binary sends, limits, connection preparation and soft app grants. Apps declare protocols viapeer-channel:v1; incoming protocol/topic messages route only to the active owner.
All subscriptions, publication fan-out, project membership, sync, xitdb storage
and merge/review logic stay in consumer apps such as teams-todo.
App access and messaging
/fips access opens owner-managed grant trees. Apps may request explicit access
and show their own grants through capabilities; they cannot approve themselves
through the normal capability API. Grants allow bidirectional communication for
one protocol, exact topics and listed FIPS nodes. Multiple records combine by union.
Missing scope is denied. These are soft permissions: installed in-process code is
not sandboxed. No grant signatures, direction flags, expiry or wildcard matching.
Use node App access actions or a consumer app's explicit Review access button.
Apps can also request the optional peer-network.select-members owner workflow
for a fixed protocol/topic scope. Its returned command opens a FIPS-owned named
paired-node multi-select, including ungranted nodes. Only the explicit owner
Allow selected nodes submission adds that stored app/local-key/scope grant;
opening/cancelling grants nothing. Ordinary list-peers remains grant-filtered.
An app can bind a small invitation draft to that intent. Allow & send invitation
then queues a durable invitation over a separate paired-only channel before the recipient
has a board grant. Teams Todo lists it as Invitations → Accept & join / Decline;
only explicit FIPS owner approval grants the exact scope. Delivery and decisions survive
restart and have bounded retry/expiry. Close returns to the app with a scoped refresh.
See app invitation contracts and bounds.
Allow/Save/Remove operate on local database records; background failures never
open approval prompts. Grant records remain after unpair, local-key changes or app
disable/uninstall until the owner changes them. Old/stale references can be managed
in the owner-wide view. Deleting a grant does not delete consumer subscription data.
The current provider advertises 512 payload bytes, eight concurrent sends and a
50-second send deadline. Text is UTF-8; binary bytes are unchanged. Each operation
targets one FIPS key and returns a single send result. sent does not mean remote
durable receipt. Large transfers are chunked by the app. See the
wire and phase record for encoded bounds and local checks.
Health uses authenticated remote evidence with periodic encrypted probes; stale
links reconnect with backoff. FIPS repairs signaling subscriptions, and apps restore
their own subscriptions/sync using scoped connection-change hints plus reconciliation.
Host shutdown invokes onStop to stop FIPS before shared relay resources close.
Real binary/network/UI recovery acceptance remains pending.
Commands
/fipsor/fips status— Show local FIPS identity (fips_pubkey,nodeAddr), runtime state, and explicit signal relays./fips invite <wss://relay> [--recipient <master_hex>]— Review and master-sign an expiringfips2:invitation using the connected Web UI signer./fips add <fips2:...> [--alias "My VPS"]— Verify an invitation and sign its acceptance, or review and confirm an acceptance. Optionally name the remote instance locally. Unsigned/raw-key imports are rejected./fips list— Open the web instance manager: expandable identity details, Invite / Add code / Refresh controls, and per-instance ⋮ actions for Ping, Rename alias and Remove. Text clients receive a plain roster. Status (online,connecting,offline) is the last recorded state, not a continuous reachability check./fips ping <id>— Punch a UDP path via Nostr signaling (if not already connected) and measure end-to-end encrypted FIPS round-trip latency./fips show <id>— Show full details for a configured peer./fips alias <id> "My VPS"— Set a local display alias for an instance (1–80 characters)./fips delete <id>— Remove a peer from the roster./fips seeds [wss://... | clear]— View or update optional FIPS WebSocket seed URLs./fips access— Inspect/edit grants and review pending app access requests.
Ping is initiated from one side; the paired remote instance answers automatically.
One master can own several instances, each with a distinct FIPS public key. Pairing between instances owned by the same master is supported; pairing an instance with its own FIPS key is rejected. Existing databases automatically migrate the legacy unique-master constraint while preserving peer IDs and records. Reinstalling without restoring the FIPS identity creates a new instance; remove obsolete entries using the manager rather than assuming a matching owner means the instance is unchanged.
Use Invite to create/sign a code or Add code to import an invitation or acceptance. These open the existing signed-pairing forms in a modal. After finishing pairing, close the modal and use Refresh to reload the list. Ping and Remove return an updated manager with their result. Rename alias opens a prefilled form and refreshes the originating manager after submission. Aliases are local, need not be unique, and do not change the signed identity. Pairing the same instance again preserves its alias unless another alias is explicitly supplied. Removal affects the selected local roster entry, not the remote installation or another instance with the same owner.
Failures identify connection setup (30-second deadline), sending (10 seconds), or waiting for pong (20 seconds after send). They return an error without crashing the bot. See diagnostics and remaining limitations.
The backend logs correlated signaling attempt IDs, per-relay publication results,
receive/rejection reasons, STUN mapping outcomes, UDP punching, and peer state.
Punching retries all candidates within its bounded window after recognized
destination/network send errors, with detailed error codes, candidate scopes,
continue/abort decisions and final attempt summaries. See the
diagnostics inventory for error policy
and log limits; locally queued probes do not establish delivery.
Use DEBUG=1 on both instances for extra FMP/FSP handshake details. Offer/answer
publication failures are surfaced directly instead of silently becoming answer
timeouts. Candidate addresses and decrypted signal payloads are omitted from logs.
Documentation
- Next phases: app grants, protocol/topic messages and recovery
- Core capability implementation plan
- Teams Todo MVP implementation plan
- Signed invitation and acceptance flow
- Networking glossary
- Nostr event example, STUN flow, and diagnostics
- Plugin architecture
- FIPS concepts and implementation boundaries
- How signaling relays are chosen
- Implementation progress and remaining work
- Vendored
mmalmi/fips-tsprovenance - Future of AppWeaver architecture