Create standalone browser port of LTX Athena with authenticated native API transport

2026-09-29 17:59:23 +02:00
commit 1333b0c36b
202 changed files with 63054 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Architecture
+
+Browser (React, inherited Gen Space and timeline)
+→ Node web service (session authentication, file I/O, streaming HTTP forwarding)
+→ Athena Deck shared API port in Video mode
+→ original LTX Desktop backend.
+
+The backend address may alternatively point directly to the native LTX API.
+The web service forwards `/ltx/api/...` to `/api/...`, preserving method, body,
+query, response status and body. No model-specific request translation. A fixed,
+operator-configured upstream prevents browser-controlled proxy targets. Tokens
+are loaded from files at startup and never sent to the browser. Native streaming
+HTTP responses and polling are supported; WebSocket forwarding is not implemented.
+
+`frontend/lib/web-platform.ts` implements the inherited typed `electronAPI` boundary
+in the browser. It is an OS/file integration replacement, not a model API adapter.
+The application shell no longer calls Python installers, model setup, first-run
+license acceptance, Electron updates or backend process start/stop. Unsupported
+functions throw explicit errors; timeline rendering is visibly disabled.
+
+Media: browsers cannot send server paths without first uploading. File dialogs
+upload immediately; drag-and-drop uses temporary blob URLs until a generation or
+asset import resolves the file. Server stores UUID filenames in a shared input
+folder; its backend-visible path is returned. The web service and LTX must see the
+SAME files (Docker bind mounts can expose different absolute paths). Existing LTX
+outputs are mounted read-only. Only configured input/output roots are readable;
+traversal and symlinks escaping those roots are rejected. ffmpeg/ffprobe create
+thumbnails, dimensions and extracted frames on CPU; they are not inference runtimes.
+Network protocols are disabled for media inspection. HTTP Range supports seeking.
+
+Projects: initial preview retains the upstream browser-local project storage.
+Projects are specific to this browser/origin, not multiuser or cross-device synced.
+JSON backup and restore are provided. Media is persistent in the mounted input directory.
+Deleting a project removes its index/metadata, not shared LTX files.
+
+Security: single shared login, >=16-character operator-provided password, in-memory
+12-hour sessions, HttpOnly SameSite=Strict cookie, Secure for configured HTTPS,
+login throttling, same-origin requests, fixed upstream, no Docker socket or GPU
+access. PUBLIC_ORIGIN must match the user's actual browser address. For remote
+access use HTTPS or an SSH tunnel; no unencrypted public password login.
+The existing native LTX API has operator-level functionality; authenticated web
+users are trusted operators, not isolated tenants. The input directory must be
+writable only by trusted service accounts. This is a preview, not a public SaaS.
+
+## Current limitations
+
+- No native timeline video rendering; FCPXML exports metadata only and references
+  backend media paths. A portable XML/media package needs a later export stage.
+- No server-side project library, cross-browser synchronization or multiuser roles.
+- No desktop Hugging Face OAuth, server-folder chooser or Electron updater.
+- Exact feature support depends on the selected LTX backend/model. Browser porting
+  does not add Retake/Extend support to a model that lacks it.
+- Another container stack needs access to the same media storage; an API URL alone
+  does not transport backend filesystem files. No SSH/SCP credentials are embedded.
+- First release validated with a synthetic backend, not a real GPU generation.