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:

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

  1. The app requests a fixed scope/draft and explicitly opens the returned FIPS command.
  2. 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.
  3. 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.
  4. The app lists the received invitation. Accept & join opens access --invitation review. 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.ts is not exposed as a capability operation.
  5. Decline changes local invitation state without a grant. A completion button closes the dialog and refreshes the originating app through its validated command.
  6. 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.

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.