App invitations: paired-only onboarding
App invitations are separate from signed FIPS pairing invitations. Both nodes must already be paired. Ordinary app data still needs an exact owner grant.
Shared contracts and ownership
The optional operations in peer-network:v1 are defined by
peer-network.v1.ts:
select-membersmay bind an invitation draft (label, small body, expiry, optional app-scoped completion command) to its stored app/local-key/protocol/exact-topic intent. One invitation topic is allowed. The operation queues nothing and grants nothing.list-invitationsexposes only the calling app/current local identity's records, including remote verified binding/label, state, error and an incoming review command.decline-invitationchanges only that app's incoming decision; it cannot grant access.retry-invitationretries an existing outgoing offer/status check without creating an invitation, widening scope or restoring any grants.
peer-channel.describe.invitationProtocols explicitly opts a protocol into onboarding.
Its optional invitation-received handler validates app metadata and returns a local
completion command. It cannot approve a grant. Normal protocol collisions also disable
invitation routing; an invitation opt-in cannot bypass another owner's normal claim.
FIPS owns sender/session attribution, carrier, stored envelopes, bounded retry state, expiry, grant writes and owner UI. Apps own body schemas and later board/entity/history acceptance. No Todo import or app payload policy exists in core/FIPS. In-process code is subject to the existing soft-policy boundary, not process isolation.
Owner flow and transactions
- The app requests a fixed scope/draft and explicitly opens the returned FIPS command.
- The owner selects named paired nodes and clicks Allow & send invitation. Local grants and per-recipient offers queue in one FIPS transaction. Scope/expiry/metadata are server-stored; the client submits only selected keys and the intent ID.
- The receiver authenticates its paired sender and both envelope keys, finds the unique opt-in app, validates metadata, and commits an incoming invitation before reporting Delivered. Receipt never creates a grant or app entity.
- The app lists the received invitation. Accept & join opens
access --invitationreview. The explicit FIPS owner command revalidates app metadata, pairing/master binding, current identity and expiry, then atomically commits the exact grant plus accepted decision.invitations/approval.tsis not exposed as a capability operation. - Decline changes local invitation state without a grant. A completion button closes the dialog and refreshes the originating app through its validated command.
- Durable decisions notify the source. A confirmation follows the source status commit. Missing confirmations retry; duplicate offers return the existing decision, not a new approval. Already accepted approval is idempotent and cannot restore revoked grants.
Only metadata travels during bootstrap. Teams Todo's body is a strict versioned board ID/title/creator/membership-revision descriptor; the creator must be the authenticated sender. Accepted board creation/tasks still arrive through ordinary publication/Sync and individual review. No automatic pairing, app installation or approval prompts.
Storage, lifecycle and bounds
FIPS db.sqlite uses WAL/FULL. fips_member_selections.invitation extends existing
stored intents with a nullable draft; migration preserves old rows/grants. Polling
reuses a live unchanged intent. A later explicit share after a completed send can create
a fresh consent intent, but rendering never queues another invitation.
fips_app_invitations pins UUID, direction, local/remote keys, verified master/label,
app alias, protocol/topic, immutable envelope, optional selection/completion reference,
state, attempts, next attempt, notification confirmation and bounded error. The visible
states are queued, delivered, accepted, declined, expired, failed. Local send/fragment
feedback is not durable delivery. Delivery/decisions survive process/node restart.
- Body: at most 4 KiB UTF-8; label at most 500 characters; one exact topic; expiry at most seven days from creation. Sender and recipient compressed keys bind every offer.
- Dedicated service port 4202, authenticated direct FIPS datagrams, already-paired nodes only. There is no ordinary board-grant check on this narrowly bounded carrier.
- Wire magic
IF, version 1, data/feedback flag, 16-byte transfer ID, uint16 index/count. Frames ≤512 bytes, encoded JSON envelope ≤32 KiB, ≤128 fragments.offer,statusandconfirmare strict unions. Validated metadata only is stored for an active app. - At most eight incomplete transfers, two per sender, 60-second lifetime; 32 completed transfer hash sets suppress conflicting/duplicate final fragments. Two transfers, eight raw sends and four complete receive handlers may be active concurrently.
- Per-fragment feedback: three attempts, three-second wait; a transfer has a 60-second budget (the underlying bounded FIPS connection/send can finish later). No task stream or general-purpose ungranted outbox is exposed.
- Durable jobs run every ten seconds and after explicit actions, up to two per tick. Eight attempts, exponential backoff capped at one hour; explicit retry is available. A received status never regresses a terminal accepted/declined/expired decision.
- At most 128 live records per app/local identity, 16 per remote/app and 1,024 total retained records per local identity; one fresh topic/remote invitation per minute. Duplicate pending offers/intents reuse IDs. Terminal records retain 30 days after expiry; expired replay never restores state or grants. Offer handling limits each paired sender to 32 complete offers per minute.
- Unpair, local key changes, unavailable/conflicting app owners, disabled apps and removed local grants block work. Retries never recreate permissions. App absence reports unavailable; invalid app metadata reports rejected. No response leaves the remote cause unknown. A saved local decision with an unconfirmed notification is shown as a pending status notification, not a failed approval.
Evidence and remaining acceptance
Narrow in-memory checks exercised real service framing/callbacks, durable inbox/status, dropped data/final feedback, restart retry, unavailable app, expiry, immutable queue, owner approval/tampered scope/revocation replay, strict body rejection, legacy migration, picker reuse, UI schema and protocol collisions. These are not deployed-network or authenticated-owner browser acceptance. Those require two updated instances and remain owner-assisted. See the phase plan.