ShellVault: The Architecture Behind a Secure Access Experiment

Repository: ITEKONGIT/shellvault

ShellVault starts with a strong question: what should secure remote access look like when static credentials, central trust, and long-lived access are treated as liabilities?

The repository is a proof of concept, but it is not only a page with an SSH button. It contains the early shape of a platform: authentication, sessions, server inventory, agents, audit logs, database migrations, and a terminal experience.

The first architectural split

The application separates the user-facing Next.js layer from the mechanisms that hold trust and execute work.

browser
  |
  v
Next.js routes and pages
  |
  +--> auth, cookies, JWT, TOTP
  +--> session store and rate limiting
  +--> Prisma data layer
  +--> SSH connection and credential request
  +--> audit and structured logging

That separation is valuable because remote access applications are not just CRUD systems. They sit on a boundary between identity and execution. A user can be authenticated correctly and still be authorized incorrectly to reach a server or spawn a terminal.

Authentication is a chain, not a page

The lib/auth area includes JWT handling, cookies, sessions, middleware, email verification, and TOTP verification. The API routes mirror that chain with login, register, refresh, logout, email verification, and two-factor verification endpoints.

The architectural reason for keeping those pieces separate is failure isolation. Login proves one thing. Refresh proves another. TOTP verifies an additional factor. Session storage answers whether access is still active. Middleware decides where the request is allowed to go.

When those concerns are collapsed into one helper, it becomes difficult to tell whether a request is authenticated, recently verified, or simply carrying a token that has not expired.

The database is part of the trust model

ShellVault uses Prisma migrations and a transaction wrapper. That is not incidental application scaffolding. Server records, user records, session records, audit events, and access state all need to change consistently.

Imagine adding a server and provisioning an agent. If the server row is created but the audit event fails, the system has changed without leaving a reliable explanation. If a session is revoked but the cache still accepts it, the application has two contradictory versions of access.

The transaction and session-store boundaries are where the product’s security model becomes real. The code has to decide which state is authoritative, which state can be cached, and what happens when the database and Redis disagree.

The terminal is a privileged UI

The dashboard and SSHTerminal component make the system feel like a normal web application, but the terminal is the sharpest edge in the repository. The API route that spawns a terminal session is not just another endpoint. It moves from permission to command execution.

That means the UI needs to show more than a connected state. A finished design would make the user aware of:

• which identity is active;
• which server and port are being used;
• when the session started;
• whether credentials were entered, delegated, or provisioned;
• what audit record represents the session;
• how to terminate access immediately.

The security of the terminal is partly in the SSH client and partly in the information architecture around it. A hidden permission boundary is still a permission boundary, just a worse one.

Why the agent matters

The repository includes agent routes, generators, installers, heartbeat handling, and a Python secret manager. That suggests ShellVault is exploring a model where a remote environment can report state and receive short-lived access instructions without exposing a permanent secret to the browser.

That is a better direction than shipping raw private keys through a frontend. It also creates new responsibilities: agent identity, enrollment, heartbeat authenticity, replay resistance, update trust, and failure behavior when the control plane is unavailable.

The agent should be treated as a separate product boundary, not as a background helper. It is the thing that turns a dashboard action into a remote effect.

The honest maturity read

The README calls ShellVault a proof of concept and architecture demonstration. That is the correct label. The repo has meaningful boundaries, but several deployment assumptions remain open, including the exact transport implementation, credential lifecycle, and environment-specific hardening.

That does not make the project weak. It makes the engineering question visible.

The next useful work is not adding more dashboard pages. It is writing the access protocol as a state machine: enroll, attest, authorize, establish, operate, expire, revoke. Every transition should have a stored event and a failure path.

ShellVault is interesting because it sits in the space where security architecture becomes product architecture. A secure access idea is only complete when the user can understand the trust boundary, the server can enforce it, and the audit log can prove what happened afterward.