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)

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 located in standard OS config paths (e.g., ~/.config/aether/seed.json or ~/Library/Application Support/Aether/).

{
  "event_device_id": "AE-LPT-01",
  "api_base_url": "https://api.oneskyit.com"
}

1.2 The Bootstrap Flow

1. Launch: Electron reads the seed.json.
2. Identity: App calls GET /v3/crud/event_device/{id}?view=full_config.
3. Hydrate: API returns the full operational config (Account context, Event settings, File cache paths).
4. Auth: App uses its device-specific API key to exchange for a session JWT.
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.