# Nexus

Nexus is the operations platform for the Noveria ecosystem. OpenClaw is an
adapter-backed agent runtime, not a dependency of the frontend or domain model.

## Current foundation

- Vue 3, TypeScript, Pinia, Vue Router and Tailwind CSS
- ASP.NET Core 10 REST API
- Entity Framework Core and PostgreSQL
- JWT owner authentication with rotating refresh sessions
- `IAgentRuntime` abstraction with an OpenClaw adapter
- `IModelProvider` abstractions for Ollama and NVIDIA
- Responsive dark-mode operations dashboard
- Container-only entry point on `127.0.0.1:18880`

## Local/container start

```bash
cp .env.example .env
# Replace every placeholder, especially POSTGRES_PASSWORD, JWT_KEY,
# OWNER_EMAIL and OWNER_PASSWORD.
docker compose up --build -d
curl http://127.0.0.1:18880/health
```

On an empty database the API creates exactly one owner from `OWNER_EMAIL`,
`OWNER_PASSWORD` and `OWNER_DISPLAY_NAME`. The password must contain at least 14
characters. Existing databases are never overwritten by the bootstrap process.

The web service is loopback-only. Public reverse-proxy activation for
`nexus.noveria.net` remains a separate infrastructure change and must terminate
TLS before forwarding to port `18880`.

## Authentication

- Passwords use versioned PBKDF2-SHA256 hashes with random salts and 210,000 iterations.
- Access tokens expire after 15 minutes and are held only in browser memory.
- Refresh tokens are random, stored only as SHA-256 hashes in PostgreSQL, rotated on use and checked for reuse.
- The browser receives the refresh token only as a `HttpOnly`, `Secure`, `SameSite=Strict` cookie.
- Login and refresh endpoints are rate-limited per forwarded client IP.
- All `/api/v1` operations routes require a valid access token; `/health` remains public.
- Swagger is enabled only in the Development environment.

## Security

- Never commit `.env`.
- Generate `JWT_KEY` from at least 32 random bytes.
- Rotate any credential that has appeared in chat before using it.
- Do not expose PostgreSQL or the API container directly.
- Keep OpenClaw behind the `IAgentRuntime` contract.
- Keep the API reachable only through the bundled web proxy or another trusted reverse proxy.

## Implemented Phase 1 modules

The SPA uses history-mode routes:

- `/login` owner login
- `/dashboard` operations snapshot
- `/projects` project portfolio
- `/tasks` task board
- `/agents` runtime and agent inventory
- `/models` provider routing status
- `/activity` audit timeline
- `/chat` mobile owner-chat preview
- `/settings` runtime and provider overview

The API currently exposes:

- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/me`
- `GET /api/v1/operations/snapshot`
- `GET|POST /api/v1/projects`
- `GET|POST /api/v1/tasks`
- `PATCH /api/v1/tasks/{id}/state`
- `GET /api/v1/activity`
- `GET /api/v1/agents`
- `GET /api/v1/models`
- `GET /health`

Project and task mutations create activity records. The API applies committed EF
Core migrations after PostgreSQL becomes healthy. No destructive endpoints are
implemented.

## Runtime chat and model routing

`POST /api/v1/chat` routes authenticated owner messages through the
`IAgentRuntime` contract. The browser never receives a Gateway password or model
provider key. Conversation IDs are stable per browser and Iris is the default
agent target.

The configured model-routing policy is:

1. `qwen3:4b` through Ollama for routine and monitoring work
2. `moonshotai/kimi-k2.6` through NVIDIA for primary work
3. `gpt-5.5` through OpenClaw for strategic and critical review

The Settings module reports runtime and provider state without exposing
credentials.