# Subplan 04 - HTTP API And Install Experience

## Goal

Expose release management and install/download flows through `distd`.

## API Slices

Slice 1 - Server Skeleton:

- config loading
- routing
- JSON request/response helpers
- error response shape
- health endpoint

Slice 2 - Auth:

- bearer token parsing
- scope checks
- audit actor resolution

Slice 3 - Apps And Releases:

- create/list/get apps
- create/list/get releases
- publish release
- promote/rollback channel

Slice 4 - Uploads And Downloads:

- streaming upload endpoint
- digest validation
- resumable upload optional for later
- download endpoint with content length and SHA-256 headers

Slice 5 - Public Install Pages:

- app page by slug/channel
- platform detection
- QR/deep link support
- authenticated and public modes

## iOS Install Rules

Normal iOS devices cannot install arbitrary IPA files from a web page.

Supported modes:

- TestFlight link: open Apple's TestFlight flow.
- Enterprise/MDM: serve signed HTTPS manifest plist for enrolled devices.
- Artifact only: allow authenticated IPA download without claiming mobile
  install support.

Acceptance:

- The UI labels iOS install mode accurately.
- Enterprise install requires HTTPS and a valid manifest.
- Artifact-only mode does not display a misleading "Install on iPhone" action.

## Android APK Install Rules

Supported modes:

- Direct APK download.
- Optional install instructions shown only when relevant.
- SHA-256 visible in download metadata.

Acceptance:

- APK download is access-controlled according to app/channel policy.

## Desktop Install Rules

macOS:

- notarization status displayed when available
- download zip/dmg/pkg

Linux:

- tar/appimage/deb/rpm metadata

Windows:

- installer zip/exe/msi metadata
- signature status displayed when available

## API Contract

All JSON endpoints should return:

- stable status code
- error code
- message
- request id
- optional details

Downloads should include:

- `Content-Length`
- `Content-Type`
- `X-Artifact-SHA256`
- cache policy by channel