OSIT-AE-App-Svelte/documentation/NATIVE_APP_V3_REWRITE_PLAN.md

Project Plan: Aether Native V3 Rewrite

Target: Electron 33+ Primary Platform: macOS (Production) Development Platform: Arch Linux API Version: Aether V3 (REST + JWT)

0. Project Purpose

The sole purpose of this Native App is to serve as the AE Events Launcher. It provides the SvelteKit frontend with the ability to:

• Persistently cache files in the local filesystem.
• Execute OS-level shell commands and scripts (e.g., launching presentation software).
• Provide a "Zero-Config" experience for onsite event laptops.

1. Minimalist Configuration Strategy

To simplify laptop deployment, we will move away from large local JSON files.

1.1 The "Seed" Config

Each laptop will contain a seed.json. For development, this is located at ~/seed.json. In production, it will move to standard OS config paths (e.g., ~/.config/aether/seed.json or ~/Library/Application Support/Aether/).

{
  "event_device_id": "dbgMWS3KEHE",
  "primary_api_base_url": "https://dev-api.oneskyit.com",
  "backup_api_base_url": null,
  "onsite_api_base_url": null,
  "aether_api_key": "INSdG85ANwsEIru3nUttMw"
}

Note: only event_device_id is strictly required for the bootstrapper to start.

1.2 The Bootstrap Flow

1. Launch: Electron reads the seed.json.
2. Identity: App calls GET /v3/crud/event_device/{id}.
3. Hydrate: App uses app_base_url from the device record to search for the corresponding site_domain.
4. Target URL: Electron constructs the launcher URL: http://[app_base_url]/events/[event_id]/launcher/[event_location_id]
5. Inject: Config and JWT are injected into the SvelteKit frontend via the Preload script.

2. macOS Hardening (Permissions)

... macOS requires explicit user consent for several features. The new app will handle these during the "Splash Screen" phase.

• AV Access: Use systemPreferences.askForMediaAccess('camera') and microphone.
• Accessibility: For remote control/automation, check systemPreferences.isTrustedAccessibilityClient(true).
• Screen Recording: Required for the presentation tracker. We will use a "Check and Prompt" loop.

3. Cross-Platform Handling

Feature	macOS (Production)	Linux/Windows (Dev/Comp)
Process Kill	killall -INT "PowerPoint"	pkill -f "powerpnt.exe"
Automation	AppleScript (osascript)	Mocked via logs or Shell commands.
Paths	~/Library/Caches/Aether	~/.cache/aether
Window	Frameless, Transparent support.	Standard decorated window.

4. Proposed Directory Structure

aether_app_native_v3/
├── src/
│   ├── main/
│   │   ├── index.ts          # Window lifecycle
│   │   ├── ipc_handlers.ts   # Whitelisted OS commands
│   │   ├── macos_perms.ts    # Mic/Cam/Accessibility logic
│   │   └── api_client.ts     # V3 Auth & Config sync
│   ├── preload/
│   │   └── index.ts          # Secure ContextBridge
│   └── shared/
│       └── types.ts          # TS Interfaces for the bridge
├── resources/                # Icons and splash screens
└── electron-builder.yml      # Multi-platform build config

5. Security Upgrades

1. JWT Storage: Store the session token in Electron's safeStorage (OS-level encryption) rather than simple localStorage.
2. Navigation Lock: Prevent the SvelteKit UI from navigating away from the Aether domain.
3. Command Whitelisting: Instead of a generic run_cmd, implement specific handlers like native:launch-presentation which only accepts a file hash.

6. Deployment & Self-Update

To support onsite deployment via Syncthing:

1. Version Watcher: Main process monitors admin_share/binaries/native_app/version.json.
2. Atomic Swap: Use a dedicated update_helper.sh to swap the .app bundle while the app is closed.
3. Zero-Touch Provisioning: Auto-copy seed_[hostname].json from the sync share if local config is missing.

7. Development Tools (Arch Linux)

• Use fakeroot and binutils to package for macOS on Linux.
• Use Xvfb for headless testing of Electron windows in CI/CD.