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

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.