n9router 0.3.94 → 0.3.95

package/.next/standalone/plans/tauri-app/02-backend-plan.md

@@ -0,0 +1,237 @@
+# Backend Plan
+
+## Goal
+
+Create a standalone local backend service that replaces only the needed Next.js APIs for the desktop app.
+
+The backend must remain OS-agnostic so the same service can run unchanged on macOS, Windows, and Linux.
+
+## Backend responsibilities
+
+- manage Antigravity accounts and settings
+- expose APIs for desktop UI
+- host OAuth helper flow
+- run and control MITM server
+- maintain token swap state
+- persist usage and request detail records
+- avoid embedding OS-specific privilege logic that should live in Tauri
+
+## Source modules to extract
+
+### Keep mostly as-is
+
+- `src/mitm/server.js`
+- `src/mitm/tokenPool.js`
+- `src/mitm/usageTracker.js`
+- `src/mitm/config.js`
+- `src/mitm/handlers/antigravity.js`
+- `src/mitm/logger.js`
+- `src/mitm/paths.js`
+- `src/lib/localDb.js`
+- `src/lib/usageDb.js`
+- `src/lib/oauth/services/antigravity.js`
+- `open-sse/services/projectId.js`
+
+### Replace Next-specific wrappers
+
+- `src/app/api/cli-tools/antigravity-mitm/route.js`
+- `src/app/api/antigravity-tools/import/route.js`
+- `src/app/api/usage/stats/route.js`
+- `src/app/api/usage/history/route.js`
+- `src/app/api/usage/request-details/route.js`
+- `src/app/api/internal/usage/route.js`
+- `src/app/api/internal/request-detail/route.js`
+
+## Backend package structure
+
+```text
+apps/desktop-backend/
+  src/
+    server/
+      app.ts
+      routes/
+    services/
+      accounts/
+      mitm/
+      tokenSwap/
+      usage/
+    storage/
+    shared/
+```
+
+## Required REST API
+
+### Accounts
+
+- `GET /api/accounts/antigravity`
+- `POST /api/accounts/antigravity/oauth/start`
+- `POST /api/accounts/antigravity/oauth/complete`
+- `POST /api/accounts/antigravity/import`
+- `PATCH /api/accounts/antigravity/:id`
+- `DELETE /api/accounts/antigravity/:id`
+
+### MITM and DNS
+
+- `GET /api/mitm/status`
+- `POST /api/mitm/start`
+- `POST /api/mitm/stop`
+- `POST /api/mitm/dns/enable`
+- `POST /api/mitm/dns/disable`
+- `POST /api/mitm/cert/trust`
+- `POST /api/mitm/cert/untrust`
+
+Note:
+
+- backend routes may delegate privileged actions to Tauri-native commands
+- the UI-facing contract should stay identical on all OSes
+
+### Token swap
+
+- `GET /api/token-swap/status`
+- `PATCH /api/token-swap/settings`
+- `GET /api/token-swap/pool`
+
+### Usage
+
+- `GET /api/usage/stats`
+- `GET /api/usage/history`
+- `GET /api/usage/request-details`
+- `GET /api/usage/logs`
+- `POST /api/internal/usage`
+- `POST /api/internal/request-detail`
+
+## Implementation steps
+
+### 1. Extract persistence layer
+
+Tasks:
+
+- move `localDb` and `usageDb` into backend package
+- remove `@/` alias imports
+- create shared app data path resolver
+- preserve current data shapes for compatibility
+
+Definition of done:
+
+- backend can read existing `db.json`
+- backend can read/write `usage.json` and `log.txt`
+
+### 2. Extract Antigravity account service
+
+Tasks:
+
+- move OAuth service logic
+- adapt callback flow to backend route or local callback listener
+- implement account import from `~/.antigravity_tools`
+- preserve project ID handling
+
+Definition of done:
+
+- user can add account via browser OAuth
+- user can import existing local Antigravity accounts
+
+### 3. Extract MITM server service
+
+Tasks:
+
+- encapsulate MITM start/stop/health operations
+- convert current manager API into backend services
+- separate privileged operations behind Tauri bridge
+- preserve current host matching and request interception logic
+- remove direct dependency on platform shell commands where possible
+
+Definition of done:
+
+- backend can start/stop MITM
+- backend can report running state, cert status, DNS status
+
+### 4. Extract token swap logic
+
+Tasks:
+
+- preserve round-robin and sticky strategy behavior
+- preserve cooldown maps:
+  - quota cooldown
+  - auth cooldown
+  - model cooldown
+- expose pool state for UI
+
+Definition of done:
+
+- MITM can route through pooled Antigravity accounts
+- pool state is queryable from the UI
+
+### 5. Extract usage APIs
+
+Tasks:
+
+- port stats endpoint
+- port request details endpoint
+- port internal ingestion endpoints
+- preserve request detail merge behavior
+
+Definition of done:
+
+- usage tracker can post records to backend
+- UI can fetch aggregate and detail views
+
+## Backend refactors required
+
+### Remove Next coupling
+
+- replace `NextResponse` with Express response helpers
+- replace route module exports with Express routers
+- replace lazy `@/lib/*` imports with package-local imports
+
+### Add explicit config
+
+- `APP_DATA_DIR`
+- `BACKEND_PORT`
+- `MITM_PORT`
+- `INTERNAL_API_TOKEN` or local loopback guard
+- `PLATFORM` or equivalent runtime flag only if strictly required for diagnostics, not feature branching
+
+### Normalize module system
+
+The current code mixes ESM and CJS. The backend package should choose one runtime model.
+
+Recommendation:
+
+- backend app in ESM/TypeScript
+- keep MITM internals in CJS temporarily if extraction is faster
+- wrap with compatibility adapters
+
+## Risks
+
+### High
+
+- current MITM manager mixes process management and privileged actions
+- current code expects localhost APIs at fixed ports
+- current path aliases are tied to the existing repo root
+- 443 binding behavior differs across macOS, Windows, and Linux
+
+### Medium
+
+- account import paths differ by OS
+- request detail and usage writes may race under heavier load
+- native action failures may be misreported if backend owns too much platform logic
+
+## Backend test plan
+
+- unit:
+  - token pool cooldown behavior
+  - usage merge behavior
+  - account import parsing
+- integration:
+  - OAuth happy path with mocked responses
+  - MITM status/start/stop lifecycle
+  - internal usage ingestion
+- manual:
+  - intercept real Antigravity traffic
+  - verify rotation across multiple accounts
+
+## Cross-platform backend acceptance
+
+- same backend bundle starts under Tauri on macOS, Windows, and Linux
+- no backend route assumes `/etc/hosts`, Windows cert store, or `sudo` directly
+- all OS-specific failures are returned as structured errors, not raw shell output

package/.next/standalone/plans/tauri-app/03-tauri-native-plan.md

@@ -0,0 +1,194 @@
+# Tauri Native Plan
+
+## Goal
+
+Use Tauri as the desktop control plane and native privilege boundary.
+
+Windows and Linux support are required for v1, alongside macOS.
+
+## Native responsibilities
+
+- determine app data directories
+- manage secure secret persistence
+- request elevation when needed
+- modify cert trust and hosts/DNS entries
+- start/stop backend process
+- surface backend and OS status to UI
+- normalize OS-specific privilege flows into one stable app behavior
+
+## Why these responsibilities belong in Tauri
+
+Current Node code directly handles:
+
+- sudo password flow
+- hosts file changes
+- cert store changes
+- process launching
+
+That works in a web app context, but it is the wrong long-term boundary for a desktop product. Native desktop concerns should live in the shell layer.
+
+## Native command set
+
+### Process control
+
+- `start_backend`
+- `stop_backend`
+- `backend_status`
+- `start_mitm`
+- `stop_mitm`
+
+### Certificate operations
+
+- `generate_root_ca`
+- `trust_root_ca`
+- `untrust_root_ca`
+- `cert_status`
+
+### DNS / hosts operations
+
+- `enable_antigravity_dns`
+- `disable_antigravity_dns`
+- `dns_status`
+
+### Secure storage
+
+- `store_secret`
+- `read_secret`
+- `delete_secret`
+
+## Tauri app structure
+
+```text
+apps/desktop-shell/
+  src-tauri/
+    src/
+      commands/
+        backend.rs
+        cert.rs
+        dns.rs
+        secrets.rs
+      state.rs
+      main.rs
+```
+
+## Implementation steps
+
+### 1. Backend supervision
+
+Tasks:
+
+- start Express backend sidecar on app launch
+- wait for health endpoint
+- stop backend gracefully on quit
+- restart on crash with bounded retries
+
+Definition of done:
+
+- desktop app always knows whether backend is healthy
+
+### 2. Certificate management
+
+Tasks:
+
+- decide ownership of root CA files
+- call backend or shared library to generate CA if absent
+- trust/untrust via native OS-specific implementation
+- report:
+  - exists
+  - trusted
+  - expired
+
+Definition of done:
+
+- user can trust the cert from desktop UI without raw password entry in the React layer
+
+### 3. DNS / hosts control
+
+Tasks:
+
+- own `/etc/hosts` or Windows hosts mutation via native command
+- flush DNS cache as required per OS
+- expose enabled/disabled status for Antigravity host set
+
+Definition of done:
+
+- DNS toggling is reliable and idempotent
+
+### 4. Secret storage
+
+Tasks:
+
+- store refresh-sensitive material outside plain UI state
+- persist OAuth or local-service secrets in secure storage where possible
+- avoid long-term Node-managed encrypted sudo-password cache design
+
+Definition of done:
+
+- desktop app no longer depends on plain password caching in JS globals
+
+## OS-specific notes
+
+### macOS
+
+- hosts mutation and certificate trust require privileged operations
+- DNS cache flush must handle `mDNSResponder`
+- test on recent supported macOS versions, not only one machine
+
+### Windows
+
+- hosts path and cert store differ
+- UAC elevation flow is mandatory
+- process binding to 443 may need elevated startup path
+- avoid shell-window popups during common actions
+- certificate trust should target the Windows root store explicitly
+
+### Linux
+
+- distro differences in DNS flush behavior
+- `sudo` may not exist in all environments
+- root trust path can vary
+- define a supported baseline, such as Ubuntu/Debian first, then document others as best effort
+- if system trust installation cannot be fully automated on some distros, surface guided remediation in UI
+
+## Cross-platform design constraints
+
+- React UI must never need to know platform-specific shell commands
+- backend must not directly own elevation or cert-store logic
+- Tauri commands must return normalized status objects across all OSes
+- every privileged action must have:
+  - success result
+  - actionable failure message
+  - remediation hint when possible
+
+## Native risks
+
+- binding port 443
+- cert trust differences across OS versions
+- installer permissions and first-run UX
+
+## Native verification
+
+- backend launches automatically
+- cert can be trusted/untrusted
+- hosts entries can be enabled/disabled
+- app surfaces actionable errors instead of raw shell failures
+
+## Per-OS exit criteria
+
+### macOS
+
+- MITM can be started
+- Antigravity hosts can be enabled and disabled
+- cert can be trusted
+
+### Windows
+
+- backend and MITM can be started from installed app
+- UAC flow works for hosts and cert operations
+- cert can be trusted in Windows root store
+
+### Linux
+
+- backend and MITM can be started from installed app
+- hosts mutation works on supported distro baseline
+- documented cert trust flow works for supported distro baseline

package/.next/standalone/plans/tauri-app/04-react-ui-plan.md

@@ -0,0 +1,155 @@
+# React UI Plan
+
+## Goal
+
+Ship a desktop-first operations UI for Antigravity MITM, token swap, and usage analytics.
+
+The UI must support macOS, Windows, and Linux without changing information architecture.
+
+## UI principles
+
+- operational clarity over marketing polish
+- fast state visibility
+- desktop layout first
+- no hidden state for cert, DNS, MITM, or account cooldowns
+
+## Routes / screens
+
+### 1. Accounts
+
+Purpose:
+
+- connect Antigravity accounts
+- import existing accounts
+- manage active/inactive status
+
+Sections:
+
+- account list
+- add account button
+- import from local install
+- token expiry and refresh state
+- project ID / account metadata if useful
+
+### 2. MITM
+
+Purpose:
+
+- operate cert, DNS, and server lifecycle
+
+Sections:
+
+- cert status card
+- backend status card
+- MITM status card
+- DNS state for Antigravity hosts
+- start/stop and enable/disable actions
+
+### 3. Token Swap
+
+Purpose:
+
+- visualize and configure pool behavior
+
+Sections:
+
+- enabled toggle
+- strategy selector
+- sticky round-robin settings if retained
+- account pool table
+- cooldown badges
+- active eligibility summary
+
+### 4. Usage
+
+Purpose:
+
+- inspect intercepted traffic and cost estimates
+
+Sections:
+
+- overview cards
+- recent requests
+- request details table
+- detail drawer
+- filters by provider/account/model/date
+
+## Components to reuse from current app
+
+- cards and layout primitives from `src/shared/components`
+- MITM screen ideas from `src/app/(dashboard)/dashboard/mitm/MitmPageClient.js`
+- usage screens from `src/app/(dashboard)/dashboard/usage/*`
+
+## UI package structure
+
+```text
+apps/desktop-ui/
+  src/
+    app/
+    pages/
+    features/
+      accounts/
+      mitm/
+      token-swap/
+      usage/
+    shared/
+      api/
+      components/
+      types/
+```
+
+## API client plan
+
+- single typed client for all backend endpoints
+- polling for status endpoints
+- optimistic updates only where safe
+- explicit loading and error states
+
+## State plan
+
+- route-local state for filters and forms
+- small shared store for:
+  - backend health
+  - MITM status
+  - DNS status
+  - current account summary
+
+## UX requirements
+
+- clear destructive or privileged action prompts
+- direct explanation when cert trust or hosts mutation fails
+- visible distinction between:
+  - MITM server not running
+  - DNS not enabled
+  - cert not trusted
+  - no eligible token-swap accounts
+- platform-specific remediation copy when an operation is blocked by OS permissions or unsupported configuration
+
+## Cross-platform UI requirements
+
+- no OS should expose raw shell commands as the primary remediation path
+- Windows users should see UAC-oriented guidance
+- Linux users should see distro-aware guidance where automation is partial
+- macOS users should see cert and DNS-specific guidance when trust or cache flush fails
+
+## UI milestones
+
+### MVP
+
+- accounts list and import
+- MITM status and controls
+- token swap status and pool table
+- usage overview and detail list
+
+### Post-MVP
+
+- richer request detail rendering
+- live event stream for in-progress requests
+- tray quick actions
+
+## UI verification
+
+- all major states are visible without reading logs
+- user can tell exactly why interception is not working
+- token swap pool is understandable without opening raw JSON
+- Windows and Linux states are presented as first-class supported flows, not fallback/debug views