launcher/docs/integration-contract.md

Launcher Integration Contract

Launcher integrates with EDUT web/backend contracts as follows:

Required APIs

1. POST /secret/wallet/intent
2. POST /secret/wallet/verify
3. POST /secret/id/quote (alias of /secret/membership/quote)
4. POST /secret/id/confirm (alias of /secret/membership/confirm)
5. GET /secret/id/status (alias of /secret/membership/status)
6. GET /marketplace/offers
7. POST /marketplace/checkout/quote
8. POST /marketplace/checkout/confirm
9. GET /marketplace/entitlements
10. POST /governance/install/token
11. POST /governance/install/confirm
12. GET /governance/install/status
13. GET /member/channel/events

Wallet Session Contract

1. POST /secret/wallet/verify returns session_token and session_expires_at.
2. Launcher must attach session token on wallet-scoped calls using:
   • Authorization: Bearer <session_token> (preferred)
   • X-Edut-Session: <session_token> (compatibility)
3. Wallet change must clear cached session token before further calls.
4. Endpoints that require EDUT ID/admin authority can fail with:
   • wallet_session_required
   • wallet_session_invalid
   • wallet_session_expired
   • wallet_session_mismatch

Runtime Mode Signal

1. Launcher install-confirm payload carries operation_mode (human_manual or worker_auto).
2. Mode signal is deterministic evidence input for governance activation policy and receipt hashing.

Deterministic Requirements

1. No runtime activation without entitlement proof.
2. All install packages verified by hash and signature.
3. EDUT ID and entitlement unknown state fails closed.
4. Event inbox polling remains canonical even if push unavailable.
5. Identity assurance is evaluated independently from EDUT ID state.
6. Owner/admin launcher actions must require identity_assurance_level=onramp_attested.
7. Governance activation evidence must include signing authority class (identity_human vs delegated).