# Moonwell Launcher Web API Spec

## Scope

This document specifies the current launcher behavior for:

- authentication against the Moonwell Web API
- installation directory selection
- local file scan and hash calculation
- manifest-based synchronization
- client launch from `Wow.exe`

The launcher no longer uses S3/MinIO directly. All server interaction goes
through the Web API.

## Configuration

The launcher API base URL is provided via:

- `MOONWELL_API_BASE_URL`

Current integration mode is compile-time:

- `flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host`
- `flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host`

## API Flow

The launcher uses these endpoints from `openapi.json`:

1. `POST /api/launcher/login`
2. `POST /api/launcher/register`
3. `GET /api/launcher/manifest`
4. `GET /api/launcher/download/{path}`
5. `GET /api/launcher/news`
6. `GET /api/launcher/realms`
7. `GET /api/launcher/account`

Registration sequence:

1. User opens the registration tab and provides `username`, `email`,
   `password`, `password_confirmation`, optional `invite_code`, and accepts
   `terms`.
2. Launcher sends the payload to `POST /api/launcher/register`.
3. After a successful `201` response, the form returns to the login tab and
   displays the API success message.
4. Validation and invite errors returned by the API are shown in the form.

Authentication sequence:

1. User enters launcher credentials.
2. Launcher requests a bearer token from `POST /api/launcher/login`.
3. Launcher requests the manifest from `GET /api/launcher/manifest`.
4. Successful login persists `LauncherSession` locally.
5. On next launcher start, saved session is reused to fetch manifest again.
6. `LauncherSession` and `ClientManifest` are passed into the home screen.
7. If an installation directory is saved, synchronization starts
   automatically with the fetched manifest.
8. While the launcher is open, it refreshes the manifest every five minutes.
9. A server build hash that differs from the verified local build hash starts
   synchronization automatically.

Logout sequence:

1. User presses `Logout`.
2. Launcher cancels any active sync.
3. Launcher clears the locally persisted `LauncherSession`.
4. Launcher returns to the login screen.

File download sequence:

1. Launcher resolves files that are missing, stale, or changed.
2. For each required file, launcher calls `GET /api/launcher/download/{path}` with bearer auth.
3. API returns JSON with a temporary presigned `url` and `expires_in`.
4. Launcher downloads the file directly from storage using the presigned URL.
5. Download is written into `*.moonwell.part`.
6. Downloaded file is verified against manifest `sha256`.
7. Temporary file replaces the destination file only after successful verify.

News sequence:

1. After the launcher reaches the authenticated home screen, it requests `GET /api/launcher/news`.
2. The response payload is read from the top-level `data` array.
3. Each news item provides `id`, `title`, `body`, optional `image_url`, and `created_at`.
4. News failures do not block patching or play flow; the launcher shows a local error state only inside the news panel.
5. Pressing a news item opens `<MOONWELL_API_BASE_URL>/news/{id}` in the
   system browser.

Realm status sequence:

1. After the authenticated home screen opens, the launcher requests
   `GET /api/launcher/realms`.
2. The first item in the top-level `data` array supplies the realm name,
   online state, and game build shown in the sync panel.
3. Realm information is refreshed every minute while the launcher remains
   open.
4. A failed refresh keeps the last known realm state and is retried on the next
   interval.

Account sequence:

1. After the authenticated home screen opens, the launcher requests
   `GET /api/launcher/account` with bearer authentication.
2. Only `username` is stored in launcher UI state and displayed in the account
   menu.
3. The response `balance` field is intentionally ignored and never displayed.
4. Account metadata failures do not block patching or launching the game.

## Installation Directory Rules

The user selects a single installation root directory.

All paths in the manifest are treated as relative to that root.

Path safety rules:

- backslashes are normalized to `/`
- leading `./` is removed
- absolute paths are rejected
- path traversal via `..` is rejected

## Ignored Directories

The launcher excludes these top-level directories from verification:

- `Cache`
- `Errors`
- `Logs`
- `Screenshots`
- `WTF`

Files under these directories:

- are not included in local scan
- do not participate in local `buildHash`
- are not compared against server manifest

## Local Scan

For every non-ignored file in the installation directory, the launcher computes:

- normalized relative path
- file size in bytes
- file `sha256`

The result is stored as a `ClientInstallationSnapshot`.

## Hash Cache

To accelerate repeated scans, the launcher stores a local hash cache in:

- `<install-root>/.moonwell_launcher/hash_cache.json`

This metadata directory is excluded from verification.

Each cache entry is keyed by normalized relative path and stores:

- `size`
- `modifiedMs`
- `sha256`

Cache reuse rule:

- if `path`, `size`, and `modifiedMs` still match, the cached `sha256` is reused
- otherwise `sha256` is recomputed and the cache entry is replaced

The cache is an optimization only. The server remains the source of truth via
the manifest comparison.

## Diagnostics

During sync, the launcher writes a log file to:

- `<install-root>/.moonwell_launcher/launcher.log`

If an installation directory is not available yet, the launcher falls back to a
temporary system log directory.

For failed downloads:

- HTTP and storage download failures are logged with file path and status code
- checksum mismatches log expected and actual `size` and `sha256`
- invalid payloads are preserved as `*.moonwell.part.failed` for inspection

## buildHash Algorithm

`buildHash` is deterministic and calculated identically for local snapshot and
remote manifest.

For each file entry, the launcher builds a canonical string:

`<normalized-path>:<size>:<sha256-lowercase>`

Then:

1. sort all canonical strings lexicographically
2. join them with `\n`
3. compute `sha256` of the resulting UTF-8 payload

This means file ordering in the manifest does not affect `buildHash`.

## Sync Algorithm

The current sync flow is:

1. Load manifest.
2. Scan local installation.
3. Compute local `buildHash`.
4. Compare local files to manifest files by `path`, `size`, and `sha256`.
5. Identify stale local files that are not present in the manifest.
6. If local `buildHash` matches server `buildHash` and there are no stale files
   and no mismatches, finish successfully.
7. Delete stale local files outside ignored directories.
8. Download changed and missing files.
9. Verify every downloaded file by `sha256`.
10. Re-scan the installation.
11. Recompute local `buildHash`.
12. Fail if final snapshot still differs from manifest.

## Pause and Resume Semantics

Pause is implemented as cooperative cancellation:

- the current sync stream is cancelled
- the next sync starts a fresh comparison from current disk state
- already replaced files remain valid
- partial `*.moonwell.part` files are removed before the next download attempt

## Launch Behavior

When the user presses `Play`:

1. launcher resolves `<install-root>/Wow.exe`
2. launcher clears `<install-root>/Cache`
3. launcher starts `Wow.exe` with working directory set to installation root
   and retains a process handle
4. while the process is alive, the launcher disables repeated game launches
   and client synchronization
5. when the process exits, the launcher returns to the ready-to-play state

If `Wow.exe` is missing, launch fails with an error.

## Error Behavior

The launcher surfaces errors for:

- invalid API configuration
- authentication failure
- registration validation or server failure
- manifest load failure
- path traversal attempts
- checksum mismatch after download
- missing downloaded temp files before verification
- final verification mismatch after update
- missing `Wow.exe`

## Tested Invariants

The automated tests cover:

- deterministic `buildHash`
- path normalization used by `buildHash`
- exclusion of ignored directories during local scan
- cache cleanup behavior
- safe path resolution
- sync flow with fully up-to-date client
- sync flow with stale files and changed files