FIPS: App Access, Binary Messaging and Connection Recovery
Status: F1–F3 code implemented and locally checked; authenticated UI and deployed network acceptance remain pending. The user authorized implementing the phases together. The initial implementation did not perform agent commits, publication or Git hook execution. The owner has since committed the implementation and begun deployed acceptance.
The owner has now approved the revision below: authenticated direct-origin delivery, a real member chooser, integrated owner create/join grants and bounded direct app invitations. The stored exact-scope chooser, paired-only pre-grant invitations, durable delivery/ decision state and owner Accept & join are now implemented and locally checked. Close returns to the app with a scoped refresh. Deployed authenticated onboarding acceptance remains open. See wire/ownership/bounds.
See architecture decisions, core contracts, Teams Todo and the earlier transport progress record.
First deployed consumer feedback
The Teams Todo owner reported an empty Add grant form and raw validation errors. Source inspection confirms this path starts with empty peer/topic arrays and no protocol, rather than a board-scoped stored request. The local saved Teams Todo scope has no grants/requests and records permission denial. A real owner peer chooser, actionable setup state and readable grant validation remain UX gaps; the current management view is not an implemented picker. See the consumer investigation and recommendations. No grants were changed, and successful post-approval exchange is still unverified.
Approved revision — owner setup and app invitations
Contracts are owned by core C3. Consumer integration is owned by Teams Todo R0–R7. Implement after precise envelopes/owner handoffs are pinned. No compatibility layer is required for this research-stage v1 change.
Authenticated origin and named owner selection
The SQLite/event decision defers the earlier per-entity signature and generic node-signing proposal. Apps can trust direct-origin FIPS delivery and persist that provenance; it is not independently verifiable authorship after arbitrary forwarding.
- Retain authenticated sender metadata for normal app messages and onboarding. Consumer apps derive/check new event authors against that identity and apply their own schemas/membership/review rules. No Todo schemas, event cursor logic, SQLite replication, canonical hashing or app acceptance policy belongs in FIPS.
- Provide a FIPS-owned paired-node multi-select with aliases and full node keys.
Optional
peer-network.select-membersstores caller app/local-key/protocol/topics and returnsaccess --selection <id>. Normallist-peersstays grant-filtered. Opening/cancelling grants nothing; explicit owner submission validates current paired nodes/local identity and adds missing exact scope idempotently. - Persist selection scope rather than expose a public ungranted roster or trust client-supplied app/approval claims. Reopening a stored intent never restores revoked access; another explicit owner submission is required.
- Richer owner/profile labels and expandable key presentation; authenticated chooser acceptance on deployed instances.
- Stored, app-scoped completion command on Close refreshes the originating app; no client-supplied command can widen grant scope or claim another app identity.
- Fully automatic/headless consumer setup continuation, if a later UX needs it.
Integrated exact-scope grants
- Let explicit Share and Accept & join owner actions persist reviewed app/local-key/protocol/board-topic/peer scope through FIPS management. The app can orchestrate setup but cannot grant itself via ordinary capability calls. Receipt of an invitation never invokes approval or opens a signing prompt.
- Bind approval to the actual validated metadata descriptor and chosen paired nodes. Retain unsigned local soft grants, exact matching, overlap union and retained-record behavior. Adding members/scope needs explicit new review.
- Record durable invitation delivery/decision stages and idempotent owner decisions. App and FIPS databases cannot commit atomically together: make retry and recovery explicit, preserve prior grants on failed validation and never use replayed acceptance to restore revoked access silently.
- After successful owner action, return a scoped completion/recheck command so the consumer can resume immediately even on an already-connected link.
- Keep manual grant commands; replace empty JSON-array defaults in normal UI with proper peer/protocol/topic controls, action-specific validation and readable errors. Keep exact keys/topics visible in technical details.
- Support separately authorized removal of relevant grants/requests during app reset, with scope summary; no implicit deletion of unrelated/overlapping scope and no change to normal unpair/leave/uninstall retention policy.
Bounded pre-grant invitation carrier
- Add an authenticated onboarding carrier between already-paired nodes that does not require ordinary board grants. Route only to an active declared app protocol invitation handler/inbox, not every app/provider. An unavailable app yields a bounded status, never automatic installation.
- FIPS owns transport/envelope/bounds; the consumer owns authenticated-creator board invitation contents, membership revision policy, join/decline and acceptance semantics. No FIPS project tables or subscription/pub-sub implementation.
- Bind sender/recipient, unique invitation ID, protocol, version, expiry and status. Pin limits for envelope bytes, chunking/reassembly, pending invites, concurrent work, retry/backoff, retention and repeated invites before coding. Multi-member descriptors cannot be assumed to fit a single 512-byte frame.
- Persist bounded delivery/decision/retry state across restart. Separate queued, delivered, accepted, declined, expired and failed. Delivery is not acceptance; offline retry does not become a general ungranted app-message channel.
- Enforce app-owned strict metadata validation, no grant on receipt, no self-approval callback and no automatic pairing of unknown members. Signed FIPS pairing invitations and their owner signatures remain unchanged.
- Make repeat/replay handling idempotent, with terminal expiry/decline handling, no invitation storms and no late callback recreating reset consumer state.
Diagnostics and verification
- Report typed grant/setup/invitation failures and handler rejection results with bounded correlated stage/peer/attempt/timing logs. No secrets or task payloads; do not turn missing remote app response into an asserted remote grant denial.
- Local checks of owner vs background APIs, app metadata validation, chooser scope, stored scope tampering, cancel/partial failure/retry, invitation replay/expiry, unpaired/unavailable recipients, bounds and reset lifecycle using permitted targeted checks. No automated tests without user request.
- Deployed authenticated sender/UI/reset lifecycle acceptance; local checks do not establish actual network reachability or owner-browser behavior.
- User-assisted two-node create/invite/accept with integrated local grants, no typed identifiers or descriptor copying. Repeat with offline restart/retry, revocation/reapproval, duplicate invitation and three pairwise-paired members.
- Preserve F1/F2 text/binary/grant isolation and F3 health/recovery acceptance; record deployed core/plugin/Bun versions and actual timings. A successful invitation does not demonstrate task-history synchronization.
Exit: paired owners can complete app setup with contextual create/join approval, while normal app data remains grant-gated. FIPS owns authenticated carriage/policy; the consumer still owns working state, publication, membership and durable receipts.
F1 — soft grants and selective protocol routing
-
access.ts/db.ts: transactional unsigned grants, requests and stored management contexts. Installed alias + local FIPS key identify the caller scope. No publisher identity, permission signatures, expiry or wildcard rules. - One protocol, exact peer/topic lists, union matching across records. Peer/topic lists authorize their Cartesian product; split scopes into separate records.
- Deny-by-default send/receive checks against the current paired peer, app alias, local identity, owned protocol and exact topic. Sender metadata comes from authenticated FIPS and the roster, not claimed payload authorship.
- Apps can list scoped records and submit requests; returned management-command descriptors only open owner UI after an explicit action. No automatic prompt and no app-facing self-approval mutation operation.
-
/fips access: tree-based grant CRUD, stored-request allow/decline, atomic selected-request batches, scope validation and preserved records on failure. Cancel does not change existing grants; deletion affects subsequent checks. - Node manager App access entry points and scoped consumer management views. Exact topics/keys are displayed; friendly topic labels are not yet a contract field. Soft-permission notice is explicit; there is no process isolation claim.
- Retain grant records through unpair/local-key change/disable/uninstall. Normal app views use the current local identity; owner-wide FIPS management can inspect stale references. Cache invalidation/rechecking prevents stale policy reuse.
-
protocols.ts: provider declarations, bounded describes, active-owner checks and rejection of conflicting local protocol ownership. No fan-out to every app. - All six revised network operations implemented. Connect/send use explicit destination FIPS keys and a granted active protocol owner, not master lookup.
- No FIPS subscription tables, publish operation, project membership, sync cursor interpretation or app-level merge. Those belong to Teams Todo and other apps.
Local checks: scope/union/denial, management parsing/render schemas, stored request isolation/approval and batch behavior, protocol collision/provider disappearance.
- Owner checks actual authenticated tree/form behavior, including cancel, stale retained records, overlapping grants and batch approval.
- Two active apps share one physical connection with no cross-protocol delivery.
F2 — bounded text and binary P2P messages
-
wire.tsencodes/decodesAWFPversion-1 frames with bounded metadata and raw payload. No old JSON-wire fallback or general-purpose TLV framework. - Text is explicit UTF-8; Uint8Array bytes are unchanged in-process. Core's explicit tagged-base64 form supports JSON-only callers without numeric-key object coercion. Provider size limits still apply after decoding.
- Frame lengths/version/type checked before payload use; fixed bounds on receives, sends, signaling, describes and notifications prevent unlimited work.
- One-peer send results: success has local completion
sentAtand null error; failure has null time and a typed permission/protocol/peer/size/busy/timeout/ transport error. No durable receipts, exactly-once or ordering promise. - Grant/owner/pairing rechecked after connection and session setup, immediately before send. Optional vendor cancellation/policy/direct-path hooks prevent late setup from transmitting an abandoned app payload.
- Bounded auto-connect and cleanup; no hidden durable message queue/replay. Application chunks, offsets, acknowledgements and retries remain app-owned.
Wire format and operational limits
magic "AWFP" (4 bytes)
version 1 (u8), kind 0=text / 1=binary (u8)
protocol length (u16), topic length (u16), payload length (u32)
UTF-8 protocol, UTF-8 topic, unchanged payload bytes
Integers are big-endian. Protocol/topic encoded lengths are capped at 128/256
bytes; payload is 512 bytes; the largest frame is 910 bytes, conservatively
below the 1,200-byte FSP path budget. get-limits advertises 8 concurrent sends
and 50,000ms send timeout. Apps must chunk larger data using these advertised
limits. Send completion is not proof of remote application acceptance or persistence.
Local checks: frame/schema validity, binary byte preservation, malformed/oversized input, policy scope and bounded operation paths. Root native/JSON binary checks pass.
- Real paired-node UTF-8/non-UTF-8 exchange and post-revocation denial.
- Record real payload/latency behavior and failure cleanup under concurrent use.
F3 — health and recovery
- Unknown / connecting / connected / disconnected with last confirmed remote activity and last error; stale stored status is reconciled at startup.
- Authenticated receive/handshake evidence and encrypted ping/pong establish health, not successful UDP writes. Probes run every 10 seconds and evidence becomes stale after 35 seconds.
- Stale links/adopted sockets invalidated; deduplicated connection attempts and bounded jittered backoff reconnect previously established, still-paired peers. Healthy connections remain reusable; no idle-disconnect policy.
-
udp-nostr-transport.tsrepairs per-relay signaling subscriptions, bounds sockets/signaling work and coordinates simultaneous traversal offers. - EOSE diagnostics acknowledge that nostr-tools can invoke aggregate completion on timeout/failure. Logs no longer claim confirmed relay EOSE from that alone.
-
signal-publication.tsshares underlying relay/event promises across overlapping adverts, including after a caller's deadline; avoids pending-promise overwrite. - Connection-change hints reach relevant granted active protocol providers only. Apps restore their own subscriptions and messages and reconcile periodically.
-
stopFipsRuntimeand generic hostonStoprelease timers/sockets/runtime DB before the shared relay pool closes. Host hooks have a five-second deadline. This is shutdown support, not a new hot-unload mechanism.
Local checks include overlapping-publication behavior and bounded ownership/ notification paths. They do not establish real outage recovery.
- Real peer stop/restart, relay loss/recovery, simultaneous dial and stale-link invalidation; verify both directions of encrypted ping and binary after recovery.
- Record actual timings, core/plugin/dependency versions and clean shutdown.
Current limitations and later work
- Local checks passed, but authenticated browser and real-network acceptance are
open. Root TypeScript reports three pre-existing vendor errors: Noble
ProjectivePointand two WebRTC string/byte mismatches. No new plugin errors. - Core cannot forcibly cancel a stalled consumer callback. Concurrency remains bounded, including occupied slots from callbacks that never settle.
- Grants are ordinary local DB policy, not hostile-plugin isolation. No grant auto-cleanup, permission-signing or paid licensing subsystem is planned here.
- Later peer-introduction UI may forward fresh signed pairing codes. A courier cannot approve someone else's pairing/grants; retain one-time/recipient binding.
- Later routed A-B-C experiment needs explicit forwarding policy. Vendor routing exists, but forwarding=false/direct-send integration is the current default. Do not claim working plugin mesh without the three-node route check.
- Further signaling replay/schema limits, candidate/destination policy, carrier fallback and Rust interoperability remain in the earlier transport record.
Verification / publication
- Targeted ESLint
--fix, plugin generation and diff whitespace checks. - Narrow in-memory policy, frame, ownership, management and publication checks.
- Document actual wire bounds and local evidence; update vendor patch provenance.
- User-assisted acceptance items above and review/commit/publication.
No automated tests were added/run, no live application payload was published by the agent, and no authenticated browser session was assumed. Future checks should target failures/new changes rather than repeatedly rerun already-passing scenarios.