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

Reading guide

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

  1. Instances exchange a signed invitation and acceptance, adding each other to their rosters.
  2. /fips ping <id> explicitly connects using the peer's FIPS key.
  3. The UDP transport binds a fresh socket and queries configured STUN servers.
  4. It sends an encrypted traversal offer through the current signaling relay list. The receiver authenticates the inner seal and checks its peer roster.
  5. The receiver creates its own socket/candidates, sends an answer, and starts probing. The initiator probes after receiving the answer.
  6. 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.
  7. Ping/pong uses FSP service port 4201; app envelopes use 4200. 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