# Functional Specification: Aether Native App

**Date:** 2026-01-20
**Status:** Legacy Documentation for Rewrite
**Source Files:** `aether_app_native/index.js`, `aether_app_native_v4.js`

## 1. Core Objectives
The Native App acts as a high-privilege bridge for the Aether SvelteKit UI, providing:
1.  **Local File Orchestration:** Managing a local cache of presentation files.
2.  **Process Management:** Opening and closing third-party applications (PowerPoint, Keynote).
3.  **Hardware Integration:** Accessing device metadata and AV permissions.
4.  **Persistent Identity:** Maintaining a fixed device ID independent of browser cookies.

## 2. Detailed Function Mapping

### 2.1 Configuration Layer
| Function | Process | Description | V3 Rewrite Notes |
| --- | --- | --- | --- |
| `load_init_config` | Renderer | Reads `ae_native_app_sk_config.json` from disk. | Standardize path to `~/.config/aether/`. |
| `get_url_cfg` | Renderer | Fetches remote config via API. | Switch from `/v2/crud/` to `/v3/crud/event_device/`. |
| `import_config` | IPC | Passes config to Main process. | Use `contextBridge` for secure transfer. |

### 2.2 File & Cache System
| Function | Process | Description | V3 Rewrite Notes |
| --- | --- | --- | --- |
| `download_file` | IPC (Main) | Downloads via Axios stream to `.tmp` then renames. | Integrate JWT in download headers. |
| `check_hash_cache`| Renderer | Checks shard subdirectories (e.g. `/cache/af/...`). | Keep sharding logic for performance. |
| `open_hash_to_temp`| IPC (Main) | Maps `hash.file` -> `OriginalName.ext` in temp dir. | Ensure auto-cleanup of temp files on exit. |
| `open_local_file` | IPC (Main) | Wrapper for Electron `shell.openPath`. | Restrict to whitelisted directories. |

### 2.3 System Control
| Function | Process | Description | V3 Rewrite Notes |
| --- | --- | --- | --- |
| `kill_processes` | IPC (Main) | Uses `killall` (Mac) or `pkill` (Linux). | Add specialized support for Svelte 5 process tracking. |
| `run_osascript` | IPC (Main) | Executes AppleScript (macOS only). | Add a "Mock Mode" for Linux development. |
| `run_cmd` | IPC (Main) | Executes arbitrary shell commands. | **SECURITY:** Change to a whitelist of allowed commands. |

### 2.4 Device & Environment
| Function | Process | Description | V3 Rewrite Notes |
| --- | --- | --- | --- |
| `get_device_info` | IPC (Main) | Returns OS, Arch, and Network info. | Use for V3 device heartbeat registration. |
| `sys_perms` | Main | Requests Mac AV permissions. | Move to a dedicated bootstrap module. |

## 3. The "Arch Linux vs macOS" Strategy
To ensure the app remains developable on Arch Linux while targeting macOS:
1.  **Platform Detection:** Every system call must be gated by `process.platform`.
2.  **Path Placeholders:** Continue using `[home]` and `[tmp]` strings in config files, resolving them at runtime.
3.  **Mocking:** Create a `mock_native.js` that logs AppleScript/Terminal commands to the console instead of trying to execute them when `platform !== 'darwin'`.

## 4. Security Requirements (Modernization)
1.  **Context Isolation:** Enable `contextIsolation: true`.
2.  **No Node Integration:** Disable `nodeIntegration` in the renderer.
3.  **IPC Whitelisting:** Replace `run_cmd` with specific named handlers (e.g., `native:open-powerpoint`) to prevent RCE (Remote Code Execution) vulnerabilities.