54 lines
3.3 KiB
Markdown
54 lines
3.3 KiB
Markdown
# 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.
|