96 lines
6 KiB
Markdown
96 lines
6 KiB
Markdown
# VNOX Web
|
|
|
|
> Public project website and account frontend for VNOX Central.
|
|
|
|
[](LICENSE)
|
|
[](https://bun.sh/)
|
|
[](https://www.typescriptlang.org/)
|
|
|
|
---
|
|
|
|
## What is this?
|
|
|
|
A lightweight, self-hosted website for VNOX, a Rust voice and text communication platform. This is a separate repository from [VNOX Client](https://git.wihuk.pro/boba/VNOX-Client) and [VNOX Server](https://git.wihuk.pro/boba/VNOX-Server).
|
|
|
|
The application is written in **TypeScript**, HTML and CSS. **Bun** installs dependencies, runs development previews and tests, formats source and bundles production assets. Strict types cover Hub responses, sessions, profiles, language keys and UI state; untrusted JSON is also validated at runtime.
|
|
|
|
Browsers execute JavaScript, so Bun compiles the TypeScript source into one static browser bundle. A frontend framework is unnecessary for the landing page and account flow. There are **no browser runtime dependencies**, third-party scripts, analytics or external fonts. Production serves static files through Nginx; neither Bun nor Node.js runs on the website server.
|
|
|
|
## Screenshots
|
|
|
|
Actual screenshots of [central.loki-code.dev](https://central.loki-code.dev), captured on 24 October 2026 in a fresh, anonymous browser context. No private account data or credentials appear in these images.
|
|
|
|
### Project page
|
|
|
|

|
|
|
|

|
|
|
|
### Central account
|
|
|
|

|
|
|
|
[Mobile screenshot](docs/screenshots/landing-mobile.png)
|
|
|
|
## Features
|
|
|
|
- Responsive Russian/English project pages with the approved VNOX mark.
|
|
- Interactive, clearly labelled layout illustration and a real native-client screenshot.
|
|
- A "light client" block with measured memory use (sources in [docs/memory-sources.md](docs/memory-sources.md)), scroll reveal and a counter that respects `prefers-reduced-motion`.
|
|
- Account loading, signed-out, signed-in, unavailable and sign-out states.
|
|
- GitHub sign-in through VNOX Hub, same-origin cookies and CSRF-protected sign-out.
|
|
- Explicit early-development status; no invented releases, people or download links.
|
|
|
|
The website does not implement identity verification itself. The Rust Hub exchanges GitHub credentials and manages sessions. Central accounts are not yet linked to the desktop client's local cryptographic identity.
|
|
|
|
## Development
|
|
|
|
Requires **Bun 1.4.4** or newer. The verified version is pinned in `packageManager` and `.bun-version`; development package versions and integrity hashes are committed in `bun.lock`.
|
|
|
|
```sh
|
|
bun install --frozen-lockfile
|
|
bun run dev # Local preview at http://127.0.0.1:4176
|
|
bun run check # Strict TypeScript checking, without emitting files
|
|
bun test # API, locale and Bun preview regression tests
|
|
bun run build # Check types and create the static dist/ release
|
|
bun run preview # Preview the built dist/ directory
|
|
bun run format:check # Check formatting with Bun's built-in formatter
|
|
bun run format # Format TypeScript, CSS, HTML and configuration
|
|
```
|
|
|
|
No Node.js installation is required. TypeScript and Bun type definitions are development-only dependencies; the browser bundle contains only this application's code. See the [dependency audit](docs/dependencies.md) for checked versions and licenses.
|
|
|
|
Set `PORT=4180` to change the preview port. Reload the browser after editing source: the development preview compiles the current TypeScript when `/src/app.js` is requested. The preview intentionally returns HTTP 503 for API requests; it contains no fake backend or development credentials.
|
|
|
|
Optional browser QA: `python3 tests/browser_qa.py` uses an existing local Playwright installation and Chromium against the running preview. It does not add a JavaScript project dependency.
|
|
|
|
## Structure
|
|
|
|
```text
|
|
public/ HTML entry point and self-hosted assets
|
|
src/ Typed application, API helpers, CSS; src/i18n/ holds the ru.ts and en.ts string dictionaries
|
|
scripts/ Bun browser bundling, static build and loopback preview
|
|
tests/ Bun regression tests and optional browser QA
|
|
docs/ Design, deployment notes and repository-hosted screenshots
|
|
```
|
|
|
|
## Hub integration
|
|
|
|
Serve `dist/` at the same HTTPS origin as VNOX Hub. `/` and `/account` use `index.html`; preserve proxy routes `/v1/`, `/health`, `/ready` and `/version`. See the [Nginx example](docs/nginx-static.conf).
|
|
|
|
| Endpoint | Frontend behaviour |
|
|
| --- | --- |
|
|
| `GET /v1/info` | Enable sign-in only when `capabilities.github_auth` is `enabled` |
|
|
| `GET /v1/auth/github/start` | Browser navigation to GitHub authorization |
|
|
| `GET /v1/auth/session` | Load `authenticated`, public `user` and ephemeral `csrf_token` |
|
|
| `POST /v1/auth/logout` | Send `X-CSRF-Token`; clear the account after success |
|
|
|
|
The Hub sets Secure, HttpOnly cookies. Tokens are never stored in browser storage; only the preferred UI language is persisted. Keep OAuth callback query strings out of reverse-proxy access and error logs. Never place secrets or `.env` files in the static release.
|
|
|
|
## Contributing
|
|
|
|
Keep RU/EN catalog keys aligned (`src/i18n/ru.ts` and `en.ts`; a test enforces it), follow the [copy guidelines](docs/copy-guidelines.md), never use the long dash character, render profile values as text and retain keyboard navigation and reduced-motion support. Use descriptive Conventional Commits such as `fix(web): preserve account state when changing language`. Run type checks, tests, formatting checks and a production build before submitting a focused PR; include screenshots for visual changes. See [verification notes](docs/verification.md) for browser QA and current limits.
|
|
|
|
## License
|
|
|
|
GNU GPL version 3. See [LICENSE](LICENSE).
|