Northstar Server Control

Northstar Server Control is a local web application for server inventory, user access management, and secure Hestia Control Panel connections. The repository contains the frontend, NestJS API, PostgreSQL schema, authentication system, RBAC, and audit log.

The project stores servers, credentials, and access rights centrally instead of using browser localStorage, spreadsheets, or scattered notes. It also provides a foundation for future read-only synchronization and controlled Hestia operations.

The current version is safe for local development. SSH commands, Hestia mutations and production live mode are intentionally not activated.

Backend technical status: BACKEND_STATUS.md. Description of the initial frontend MVP: FRONTEND_MVP_STATUS.md.

Why is this project needed?

• maintain a single register of servers and their technical parameters;
• store SSH and Hestia credentials in encrypted form;
• create separate accounts for the team;
• restrict access by role and specific servers;
• record entries and administrative changes in the audit log;
• check the availability of Hestia through a controlled read-only API call;
• in the future, synchronize web domains, DNS, databases and backups with Hestia.

What has already been implemented

Login and RBAC

• one-time creation of the first administrator through BOOTSTRAP_TOKEN;
• login/logout with server session;
• hashed session token in PostgreSQL;
• HttpOnly, SameSite=Strict cookie;
• password hashing via scrypt with random salt;
• roles admin, operator, viewer;
• assignment of operator/viewer access to specific servers.

Roles have the following purpose:

Role	Access
admin	Users, all servers, Hestia connections, audit log
operator	Assigned servers and allowed work operations
viewer	Read-only access to designated servers

Server inventory

• create, view, update and delete servers via API;
• PostgreSQL instead of localStorage when the database is enabled;
• write-only contract for SSH credentials;
• The API never returns stored secrets;
• frontend login/bootstrap and API-backed inventory;
• synthetic fallback for UI if local API is not available.

Hestia

• creation and deletion of Hestia connections;
• Hestia Access Key ID + Secret Key instead of administrator password;
• AES-256-GCM encryption secret key;
• HTTPS-only URL with standard TLS verification;
• fixed read-only check v-list-sys-info;
• simulated check in APP_MODE=mock;
• real credential check only in explicit APP_MODE=sandbox.

Audit log

Audit writer stores events for:

• bootstrap, login and logout;
• creating and changing users;
• CRUD servers;
• assigning access;
• creating, testing and deleting Hestia connections.

Password, secret, token and cipher fields are removed from audit details before recording.

Important limitations

• PostgreSQL is required for users, sessions, inventory, and audit events to survive restarts;
• in memory mode, data disappears after restarting the API;
• SSH execution and arbitrary server commands are not implemented;
• Hestia mutations, background jobs and sync are not yet implemented;
• production requires rate limiting, session cleanup, an HTTPS reverse proxy, backup/restore testing, and staging verification of a real Hestia access key;
• APP_MODE=live is blocked by the configuration validator.

Technologies

• Frontend: React 19, Next.js 16, TypeScript, Tailwind CSS, vinext/Vite;
• Backend: NestJS 11, TypeScript;
• Database: PostgreSQL, Drizzle ORM;
• Authentication: server sessions, HttpOnly cookies, scrypt;
• Security: AES-256-GCM, Helmet, origin check, DTO validation;
• Local infrastructure: Docker Compose.

Repository structure

server-control/
├── app/                       # frontend and API client
├── backend/                   # NestJS API
│   ├── drizzle/               # PostgreSQL migrations
│   ├── src/                   # auth, users, servers, Hestia, audit
│   └── test/                  # backend tests
├── tests/                     # frontend/render tests
├── docker-compose.yml         # local PostgreSQL
├── BACKEND_STATUS.md          # backend handoff and limitations
└── FRONTEND_MVP_STATUS.md      # frontend MVP description

Requirements

• Node.js 22.13 or newer;
• npm;
• Docker Desktop — for persistent PostgreSQL.

Quick start

Open two terminals in the root of the project.

API:

npm --prefix backend install
npm run dev:api

Frontend:

npm install
npm run dev

Open http://localhost:3000. The API health endpoint is: http://localhost:4100/api/health.

Without PostgreSQL, the API can run in memory mode for demonstrations. Configure the database before creating persistent accounts, sessions, inventory, or audit events.

PostgreSQL and the first administrator

Start PostgreSQL and create a local env file:

docker compose up -d postgres
cp backend/.env.example backend/.env
openssl rand -hex 32
openssl rand -hex 32

In backend/.env:

1. write the first random value to ENCRYPTION_KEY;
2. write the second random value to BOOTSTRAP_TOKEN;
3. set DATABASE_ENABLED=true;
4. check DATABASE_URL and CORS_ORIGIN.

Then apply migration and run the API:

npm --prefix backend run db:migrate
npm run dev:api

Open the frontend. If there are no users, the one-time bootstrap form appears. Enter BOOTSTRAP_TOKEN, a login, and a password of at least 12 characters. After the first administrator is created, the bootstrap endpoint is disabled.

Never commit backend/.env. Git should contain only backend/.env.example with safe development examples.

Basic API endpoints

Method	Path	Purpose
GET	/api/health	PostgreSQL mode and state
GET	/api/auth/status	Does bootstrap require an administrator?
POST	/api/auth/bootstrap	Create the first admin once
POST	/api/auth/login	Create HttpOnly session
GET	/api/auth/me	Current user
POST	/api/auth/logout	Revoke the current session
GET/POST	/api/users	Admin-only account management
GET	/api/audit	Admin-only audit events
GET/POST	/api/servers	List and creation of servers
GET/PATCH/DELETE	/api/servers/:id	Details, updates and removal of the server
PUT	/api/servers/:serverId/access/:userId	Assign access to the server
GET/POST	/api/hestia/connections	Viewing and creating a Hestia connection
POST	/api/hestia/connections/:id/test	Fixed credential check
DELETE	/api/hestia/connections/:id	Remove Hestia connection

Verification

npm run lint
npm test
npm --prefix backend run typecheck
npm run test:api
npm run build:api

Security

• do not add .env, private keys, passwords or Hestia secrets to Git;
• enter credentials only through the local UI after configuring PostgreSQL;
• do not insert secrets into the issue, commit message, screenshots or README;
• leave API at 127.0.0.1 until HTTPS and firewall are configured;
• use the Hestia access key with the minimum necessary rights;
• first check the integration on the disposable sandbox server.

Current status

The project is suitable for local login/RBAC flows, PostgreSQL-backed server inventory, audit-log viewing, and safe Hestia connection testing. It is not yet ready to execute production commands on servers.