feat: harden download and install security

.architecture/overview.md

@@ -0,0 +1,62 @@
+# Architecture Overview
+
+## Workspace Shape
+
+`aim` is a Rust workspace with two main crates:
+
+- `crates/aim-core`: source normalization, provider adapters, install/update planning, payload installation, registry persistence, and desktop integration.
+- `crates/aim-cli`: argument parsing, config loading, terminal UX, prompting, progress reporting, and summary rendering.
+
+The split keeps product logic in `aim-core` so additional frontends can reuse the same install and update pipeline.
+
+## Core Flow
+
+The main execution path is:
+
+1. Parse CLI input and load runtime config in `aim-cli`.
+2. Resolve the query into a normalized source in `aim-core`.
+3. Build an add or update plan through provider adapters and artifact selection.
+4. Download the selected AppImage into a staged path.
+5. Verify integrity metadata when available.
+6. Commit the payload into the managed install location.
+7. Write desktop integration artifacts and refresh helper caches.
+8. Persist registry state atomically.
+
+## Source And Provider Model
+
+Supported source classes currently include:
+
+- GitHub repository and release forms
+- GitLab repository forms
+- AppImageHub item forms
+- SourceForge release and download forms
+- direct URLs
+- local file imports
+
+Provider-specific resolution lives in `crates/aim-core/src/adapters` and `crates/aim-core/src/source`.
+
+## Security Hardening State
+
+The current workspace enforces the following download and install boundaries:
+
+- user-supplied `http://` inputs are rejected by default
+- runtime opt-in is available through `allow_http = true`
+- that opt-in applies only to user-supplied sources, including update flows derived from stored direct HTTP origins
+- AppImageHub provider-returned download URLs must remain HTTPS
+- AppImageHub MD5 metadata is verified as weak integrity before payload commit
+- desktop entry display names are sanitized to prevent newline and control-character field injection
+- stable identifiers that normalize to empty or contain `..` are rejected
+
+The remaining deferred AppImageHub host-trust concern is tracked in `security-issues.md`.
+
+## Persistence And Integration
+
+- Registry writes are atomic and live under the registry store implementation in `aim-core`.
+- Managed payload, desktop entry, and icon paths are resolved from install policy and scope.
+- Desktop integration refresh uses external helpers when available and now supports env-gated audit logging through `AIM_DEBUG_EXTERNAL_HELPERS=1`.
+
+## Planning And Audit Artifacts
+
+- implementation plans live under `.plans/`
+- audit reports live under `.audits/`
+- architecture state and tracked security issues live under `.architecture/`

.architecture/security-issues.md

@@ -0,0 +1,32 @@
+# Security Issues
+
+## AppImageHub Download Host Trust
+
+**Status:** Open
+**Severity:** High
+**Area:** Provider trust / supply chain
+
+### Summary
+
+`aim` now enforces HTTPS for AppImageHub provider-returned download URLs, but it does not yet enforce a host trust policy or allowlist for those returned URLs.
+
+### Current Mitigation
+
+- AppImageHub download URLs must use `https://`
+- insecure user-supplied HTTP policy is handled separately through `allow_http`
+
+### Remaining Gap
+
+A compromised or unexpected AppImageHub API response could still direct downloads to an arbitrary HTTPS host. Transport encryption alone does not establish publisher trust.
+
+### Deferred Follow-Up
+
+Future hardening should add one of:
+
+- a fixed allowlist of expected AppImageHub download hosts
+- a configurable host trust policy
+- stronger publisher verification metadata if AppImageHub exposes it
+
+### Notes
+
+This issue is intentionally tracked separately from the immediate HTTPS enforcement work so the current hardening tranche can reduce risk without trying to solve the full provider trust model in one pass.