nadir-webui/README.md

# Nadir Web UI

SvelteKit dashboard for [nadir-agent](https://tea.urania.dev/urania/nadir-agent) —
a central web console that talks to one or many Nadir backend nodes over their
typed REST API.

The agent does the system-administration work (systemd services, users, packages,
networking, storage, audit, terminal, ...). This UI is the operator's view of it:
sign in, register machines with their bearer token, see live host metrics on the
dashboard, and drive everyday tasks from the browser.

---

## Stack

- **SvelteKit 2** (Svelte 5, adapter-node) + **TailwindCSS 4** + **shadcn-svelte**
- **Bun** as the runtime / package manager / dev server
- **Drizzle ORM** on **SQLite** (libSQL driver) for the UI's own state (users,
  machines, encrypted tokens, settings)
- **Better Auth** with email/password, OAuth, optional 2FA, admin & username plugins
- **Paraglide** for i18n (messages in `messages/`)
- **openapi-fetch** + typed client generated from the nadir-agent OpenAPI spec
  (`src/lib/server/nadir-agent/schema.d.ts`)

---

## Getting started

Prerequisites: [Bun](https://bun.com) and a reachable nadir-agent instance with
a machine token (see the agent README's _Connecting a dashboard_ section).

```sh
bun install
cp .env.example .env        # then edit (see below)
bun run db:push             # creates db.sqlite from the Drizzle schema
bun run dev                 # starts on http://localhost:5173
```

### Environment

Set in `.env` (validated at startup via `src/lib/const/schema.ts`):

| Var                         | Default                 | Purpose                                                    |
| --------------------------- | ----------------------- | ---------------------------------------------------------- |
| `CRYPTO_SECRET`             | (required)              | Encrypts machine bearer tokens at rest in the local DB     |
| `DATABASE_URL`              | `file:db.sqlite`        | libSQL connection string                                   |
| `ORIGIN`                    | `http://localhost:5173` | Public origin (used by Better Auth)                        |
| `REPOSITORY_URL`            | (required)              | Gitea API URL for the nadir-agent releases; enables `GET /install.sh` |
| `DISABLE_SIGNUP`            | `false`                 | Lock down registration                                     |
| `ENABLE_2FA`                | `false`                 | Enable the TOTP 2FA flow                                   |
| `ENABLE_EMAIL_AND_PASSWORD` | `true`                  | Toggle email/password auth                                 |
| `SMTP_HOST`                 | -                       | Outbound mail server hostname                              |
| `SMTP_PORT`                 | -                       | SMTP port                                                  |
| `SMTP_USER`                 | -                       | SMTP username                                              |
| `SMTP_PASS`                 | -                       | SMTP password                                              |
| `SMTP_FROM`                 | -                       | From address for verification / reset / 2FA emails         |
| `SMTP_SSL`                  | -                       | Use SSL/TLS for SMTP                                       |

OAuth providers (optional) live in `config/oauth.json` and are passed straight
to Better Auth's `genericOAuth` plugin.

---

## Scripts

```sh
bun run dev              # vite dev server (binds --host for LAN access)
bun run dev:types        # regenerate typed client, then start dev server
bun run type:generate    # generate typed client from live nadir-agent OpenAPI spec
bun run build            # production build (adapter-node -> build/)
bun run preview          # preview the production build
bun run check            # svelte-check (must pass 0 errors before done)
bun run lint             # prettier + eslint
bun run format           # prettier --write
bun run db:push          # apply schema to the DB (dev)
bun run db:generate      # generate migration from schema changes
bun run db:migrate       # run pending migrations
bun run db:studio        # drizzle-kit studio
```

`type:generate` fetches the OpenAPI spec from the live agent configured in the script
(`http://100.64.0.189:9999/openapi.json` by default — adjust for your environment).

---

## Project layout

```
src/
  routes/
    auth/              sign-in, sign-up, forgot/reset password, 2fa, 2fa setup
    dashboard/         machine list; per-machine live dashboard
      [machineId]/
        networking/    interfaces (list/detail/configure), routes, DNS, /etc/hosts
        packages/      installed packages, available updates
        services/      service list + per-service control and logs
        storage/       active mounts, fstab entries
        system/        overview, hostname, date-time, localization, power, nadir self-update
        users/         local accounts, groups (list + detail)
    admin/             dashboard users (Better Auth admin), config
    docs/              built-in operator documentation (architecture, installation,
                       security, limitations)
    api/emailer/send/  internal SvelteKit server route for outbound email
    install.sh/        serves the nadir-agent installer shell script (enabled
                       when REPOSITORY_URL is set; returns 404 otherwise)
  lib/
    auth/              Better Auth server instance + browser client
    components/        shadcn-svelte UI + reusable dashboard panels
    remotes/           SvelteKit remote functions, one file per agent domain:
                         auth, config, machines, networking, packages,
                         pam-users, server, services, storage, system,
                         terminal, users, utils
    schemas/           valibot schemas (shared validation types)
    server/
      db/              Drizzle schema + auth-schema + encrypted column type
      emails/          nodemailer + better-svelte-email templates
      nadir-agent/     generated OpenAPI types + typed fetch client
      terminal/        SSH session management (open/stream/write/resize/close)
    paraglide/         generated i18n runtime
messages/              translation source (en.json, ...)
config/oauth.json      optional OAuth providers passed to Better Auth
```

---

## Remote functions

`src/lib/remotes/*.remote.ts` are the SvelteKit server-side functions the browser
triggers via `query` / `command`. They call the agent through
`nadirForMachine(machineId)`, which handles token decryption and 401/404/500 routing.
After a mutating `command`, the relevant `query`s are `.refresh()`ed inside the command.

| File                     | Agent domain covered                          |
| ------------------------ | --------------------------------------------- |
| `auth.remote.ts`         | Sign-in, sign-out, session                    |
| `config.remote.ts`       | UI application config                         |
| `machines.remote.ts`     | Machine CRUD, reordering, health batch        |
| `networking.remote.ts`   | Interfaces, routing, DNS, `/etc/hosts`        |
| `packages.remote.ts`     | Installed, updates, install/remove (SSE)      |
| `pam-users.remote.ts`    | System user listing (PAM side)                |
| `server.remote.ts`       | Agent self-update (`POST /api/update`)        |
| `services.remote.ts`     | systemd unit list/control/logs (SSE)          |
| `storage.remote.ts`      | Mounts, fstab entries                         |
| `system.remote.ts`       | Host info, hostname, time/tz/NTP, locale, power |
| `terminal.remote.ts`     | SSH terminal sessions (open/stream/write/resize/close) |
| `users.remote.ts`        | Local accounts + groups                       |
| `utils.ts`               | Shared helpers (not a remote file)            |

---

## Database

The UI keeps its own SQLite database (Drizzle ORM, libSQL driver):

| Table          | Contents                                                                          |
| -------------- | --------------------------------------------------------------------------------- |
| `user`         | Dashboard user (email, username, name, UI role, ban state)                        |
| `session`      | Better Auth sessions                                                              |
| `account`      | Better Auth OAuth accounts                                                        |
| `verification` | Better Auth verification tokens                                                   |
| `twoFactor`    | TOTP secrets / backup codes                                                       |
| `machines`     | `{ id, name, address, order, token(encrypted) }` — registered agent nodes        |
| `settings`     | Key/value store for UI-side application settings                                  |

`token` in `machines` is stored with a custom `encryptedText` column type and is
decrypted on demand (`autoDecrypt: false`) only when making a server-side call to
the agent.

---

## SSH Terminal

The UI includes a browser-based SSH terminal (`terminal.remote.ts`). Operators
can open an SSH session to any registered machine's host directly from the
dashboard. Sessions are managed server-side (SSH client runs in the SvelteKit
server process); the browser streams output via SSE and sends keystrokes via
`command`. Sessions are closed on disconnect or explicit `closeSshTerminal`.

---

## `GET /install.sh`

When `REPOSITORY_URL` is set, the UI serves a shell installer at `/install.sh`
that bootstraps `nadir-agent` on a new host. The script is generated from
`src/routes/install.sh/install.sh.tmpl` with the release repo URL injected. If
`REPOSITORY_URL` is not set the route returns 404 with an explanation.

---

## Deploying

`adapter-node` produces a plain Node/Bun server under `build/`:

```sh
bun run build
PORT=3000 ORIGIN=https://nadir.example.com bun run build/index.js
```

Put it behind the same reverse proxy you use for nadir-agent, or co-host them.
The agent's CSRF rules apply when the UI calls it cross-origin — see the agent
README's _Connecting a dashboard_ section. The recommended pattern is to call
the agent server-to-server from the SvelteKit server layer; the browser never
holds or sends the agent token.

---

## License

MIT.