FIPS Plugin Architecture
The sections below describe the implemented baseline. The approved next revision adds a named owner member chooser, contextual create/join grant approval and a bounded paired-node invitation bootstrap before board grants. Those features are planned, not yet implemented; see the owning revision checklist. The consumer now plans SQLite events with trusted direct-origin attribution; generic entity signing and native xitdb replication are not FIPS requirements. Consumers retain board membership, working state, publication and sync ownership.
The fips plugin provides domain-agnostic peer networking over the vendored mmalmi/fips-ts core protocol combined with jmcorgan/fips-style Nostr UDP NAT traversal.
Layout
init.ts—BotPluginentry point, registersfipsPeerNetworkProvider(peer-network:v1) and initializes the backgroundFipsNoderuntime.udp-nostr-transport.ts— Implements@fips/core'sTransportinterface over Node/BundgramUDP sockets using Nostr kind37195overlay adverts, NIP-59 gift-wrapped kind21059TraversalOffer/TraversalAnswersignaling, STUN (XOR-MAPPED-ADDRESS) + LAN candidate discovery, and 24-byteNPTC/NPTAUDP hole punching.runtime.ts— Manages theFipsNodeinstance (UdpNostrTransport+ optionalWebSocketTransport), handles/fips pingon service port4201, listens for app envelopes on service port4200, authenticates incoming envelopes againstfips_peers, and dispatches inbound payloads topeer-channel:v1providers.db.ts— SQLite persistence (fips_node_settingsfor the encrypted local FIPS keypair and optional seed URLs;fips_peersfor(master_pubkey, fips_pubkey, label, seed_urls_json, status, last_seen_at)), including transactional migration from legacy unique-owner tables to unique-instance keys.vendor/fips-ts/— Pinned snapshot ofmmalmi/fips-ts(packages/core,packages/transport-websocket,packages/transport-webrtc,packages/transport-memory).commands/— CLI and Web UI command handlers (status,invite,ping,seeds,add,list,show,alias,delete).
Reading guide
- Reviewed next architecture and decisions
- Next FIPS phases: grants, binary messages and recovery
- Signed invitation and acceptance flow
- Networking glossary
- Nostr event example, STUN flow, and diagnostics
- FIPS concepts and implementation boundaries
- Relay selection: current behavior and proposed improvements
- Implementation progress and remaining work
Identity and persistence
The instance retains its existing bot and master identities. The plugin
generates a third, dedicated FIPS keypair and encrypts its secret with core's
secret-storage helper. db.sqlite resides in the plugin directory; it contains
the local identity/settings and the peer roster. The runtime is instance-wide,
not separately instantiated for each active workspace.
The master public key names the human owner. The compressed FIPS key names the
endpoint. New fips2: invitations and acceptances are master-signed binding
statements with explicit relay, expiry, optional recipient, and one-time completion
state. See pairing. Legacy roster entries remain unverified.
Multiple endpoints can share one master, and distinct same-master instances can
pair. The web list identifies rows by instance, with expandable details and
instance-specific Ping / Remove actions plus signed-pairing entry points.
Local display aliases live in fips_peers.label, can be set during pairing or
renamed from the manager, and do not affect instance identity or owner bindings.
Connection sequence
- Instances exchange a signed invitation and acceptance, adding each other to their rosters.
/fips ping <id>explicitly connects using the peer's FIPS key.- The UDP transport binds a fresh socket and queries configured STUN servers.
- It sends an encrypted traversal offer through the current signaling relay list. The receiver authenticates the inner seal and checks its peer roster.
- The receiver creates its own socket/candidates, sends an answer, and starts probing. The initiator probes after receiving the answer.
- A probe/ack selects a UDP endpoint; the same socket carries FMP authentication followed by the FSP session. A successful probe alone is not FIPS identity authentication.
- Ping/pong uses FSP service port
4201; app envelopes use4200. These are protocol service ports, not fixed host UDP listening ports.
Currently private IPv4 and loopback candidates are sent alongside reflexive candidates. Local-candidate policy and validation need further work before claiming the Rust implementation's behavior or deployment guarantees.
Previous app-facing contracts (superseded)
The earlier v1 contract used master-only destinations, channel, JSON/string
payloads, a nullable signature and delivered. It fanned incoming envelopes out to
all providers. That research API is replaced in place; none of those old fields or
fan-out semantics are a compatibility path.
Implemented capability revision
The reviewed architecture supersedes the old app API above. V1 now uses explicit FIPS destinations, protocol/topic addressing, raw binary or text payloads, selective protocol-owner routing, soft grants and single-peer send results. No compatibility bridge or publisher/permission-signing system.
FIPS stores owner-managed grant records keyed by app alias and local FIPS key, with one protocol and explicit remote-node/topic lists. Deny by default on both directions of the normal capability API. Apps list/request access through capabilities; only explicit owner management writes records. Grants remain stored through unpair, local-key changes, app disable/uninstall until manually managed. This is not an isolation boundary for in-process code.
Subscriptions and publication fan-out live in the consumer app DB/protocol, not in FIPS. Board membership, heads, binary database replication, durable acknowledgements, conflicts and review also remain app-owned. See F1–F3 for work and verification criteria, and the Teams Todo plan for the first consumer. Existing signed FIPS invitations are unaffected.
Runtime limitations
runningmeans aFipsNodeobject started, not that a peer or relay is reachable.- WebSocket seeds are configured as additional carriers, but ping and app sends explicitly attempt UDP first. Automatic fallback after UDP failure is absent.
- App sends use explicit FIPS keys; exact app grants and unique protocol ownership are required. This remains soft policy rather than in-process code isolation.
- Real network recovery and authenticated grant-management UI acceptance remain open; local schema/policy checks are not deployment evidence.
- No app data synchronization, persistent inbox/outbox, or merge implementation is supplied by this plugin.