Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
import { expandOwnerStorePath } from "@/lib/owner-store-path.js";
import { randomUUID } from "node:crypto";
import { promises as fs } from "fs";
import os from "os";
import path from "path";
import { withSecurityStoreLock } from "@/lib/security-store-lock";
import {
DeviceRoleError, isDeviceRole, storedDeviceRole, type DeviceRole,
} from "./roles";
// Server-side device allowlist, implemented for the VPS control plane. The login
// password is a weak/memorable factor; the strong factor is a 128-bit device
// id that must be pre-approved here. A new device with the right password is
// NOT let in — it lands in `pending` until an approved device (or the CLI)
// promotes it. A role then constrains the approved browser at every API call.
export interface ApprovedDevice {
label: string;
approvedAt: number;
lastSeen?: number;
sessionsRevokedAt?: number;
role: DeviceRole;
}
export interface PendingDevice {
label: string;
firstSeen: number;
lastSeen: number;
ip: string;
attempts: number;
}
export interface SessionPolicy {
scope: string;
epoch: string;
changedAt: number;
}
export interface DeviceStore {
approved: Record<string, ApprovedDevice>;
pending: Record<string, PendingDevice>;
sessionPolicy?: SessionPolicy;
}
const MAX_PENDING = 50;
// mso runs as a host process (the deploy user's systemd service) → write our
// own file, no agent round-trip. Override with OS_DEVICE_STORE.
const STORE_PATH =
expandOwnerStorePath(process.env.OS_DEVICE_STORE ?? path.join(os.homedir(), ".mso", "auth-devices.json"));
// Device ids are client-generated 128-bit+ hex/uuid.
const DEVICE_ID_RE = /^[a-f0-9-]{16,128}$/i;
const COOKIE_SCOPE_RE = /^(?:host|domain:[a-z0-9.-]{1,253})$/;
export function isValidDeviceId(id: unknown): id is string {
return typeof id === "string" && DEVICE_ID_RE.test(id);
}
function finiteTime(value: unknown, fallback: number): number {
return typeof value === "number" && Number.isFinite(value) ? value : fallback;
}
function normalizeApproved(raw: unknown): Record<string, ApprovedDevice> {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
const out: Record<string, ApprovedDevice> = {};
for (const [id, value] of Object.entries(raw)) {
if (!isValidDeviceId(id) || !value || typeof value !== "object" || Array.isArray(value)) continue;
const row = value as Record<string, unknown>;
out[id] = {
label: typeof row.label === "string" && row.label ? row.label.slice(0, 80) : "approved device",
approvedAt: finiteTime(row.approvedAt, 0),
...(typeof row.sessionsRevokedAt === "number" && Number.isFinite(row.sessionsRevokedAt) ? { sessionsRevokedAt: row.sessionsRevokedAt } : {}),
...(typeof row.lastSeen === "number" && Number.isFinite(row.lastSeen) ? { lastSeen: row.lastSeen } : {}),
// Stores written before delegated roles had no role field. Preserve their
// historical full access, while malformed future values fail down to viewer.
role: storedDeviceRole(row.role),
};
}
return out;
}
function normalizePending(raw: unknown): Record<string, PendingDevice> {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
const out: Record<string, PendingDevice> = {};
for (const [id, value] of Object.entries(raw)) {
if (!isValidDeviceId(id) || !value || typeof value !== "object" || Array.isArray(value)) continue;
const row = value as Record<string, unknown>;
out[id] = {
label: typeof row.label === "string" && row.label ? row.label.slice(0, 80) : "unknown device",
firstSeen: finiteTime(row.firstSeen, Date.now()),
lastSeen: finiteTime(row.lastSeen, Date.now()),
ip: typeof row.ip === "string" ? row.ip.slice(0, 120) : "unknown",
attempts: Math.max(1, Math.floor(finiteTime(row.attempts, 1))),
};
}
return out;
}
function normalizeSessionPolicy(raw: unknown): SessionPolicy | undefined {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
const row = raw as Record<string, unknown>;
if (typeof row.scope !== "string" || !COOKIE_SCOPE_RE.test(row.scope)) return undefined;
if (typeof row.epoch !== "string" || row.epoch.length < 16 || row.epoch.length > 128) return undefined;
if (typeof row.changedAt !== "number" || !Number.isFinite(row.changedAt) || row.changedAt < 0) return undefined;
return { scope: row.scope, epoch: row.epoch, changedAt: row.changedAt };
}
// "No file yet" is the ONLY failure that may look like an empty store. Anything else
// — corrupt JSON, EACCES, EIO — must throw. A normalized read also migrates legacy
// role-less entries in memory; the next legitimate mutation persists the role field.
async function read(): Promise<DeviceStore> {
let raw: string;
try {
raw = await fs.readFile(STORE_PATH, "utf8");
} catch (e) {
if ((e as NodeJS.ErrnoException).code === "ENOENT") return { approved: {}, pending: {} };
throw e;
}
const parsed = JSON.parse(raw) as Record<string, unknown>;
const sessionPolicy = normalizeSessionPolicy(parsed.sessionPolicy);
return {
approved: normalizeApproved(parsed.approved),
pending: normalizePending(parsed.pending),
...(sessionPolicy ? { sessionPolicy } : {}),
};
}
async function write(store: DeviceStore): Promise<void> {
await fs.mkdir(path.dirname(STORE_PATH), { recursive: true, mode: 0o700 });
const tmp = `${STORE_PATH}.${process.pid}.tmp`;
await fs.writeFile(tmp, JSON.stringify(store, null, 2), { encoding: "utf8", mode: 0o600 });
await fs.rename(tmp, STORE_PATH);
}
// Approval/revocation and session-policy rotation are security decisions, so serialize
// the entire read-modify-write transaction. A plain atomic rename is not enough.
let mutationChain: Promise<unknown> = Promise.resolve();
function mutate<T>(fn: () => Promise<T>): Promise<T> {
const locked = () => withSecurityStoreLock(STORE_PATH, fn);
const run = mutationChain.then(locked, locked);
mutationChain = run.then(() => undefined, () => undefined);
return run;
}
function ownerCount(store: DeviceStore): number {
return Object.values(store.approved).filter((entry) => entry.role === "owner").length;
}
/**
* Return the durable generation for the current cookie scope. Every actual scope
* transition rotates the epoch, so A → host → A can never revive a token minted
* during the earlier A generation even if the browser retained that cookie.
*/
export async function currentSessionPolicy(scope: string): Promise<SessionPolicy> {
if (!COOKIE_SCOPE_RE.test(scope)) throw new Error("invalid_session_cookie_scope");
// Session validation is read-heavy. Avoid taking the cross-process mutation
// lock when the durable policy already matches this process configuration.
const current = await read();
if (current.sessionPolicy?.scope === scope) return current.sessionPolicy;
return mutate(async () => {
// Recheck under the lock so only one contender rotates a scope transition.
const store = await read();
if (store.sessionPolicy?.scope === scope) return store.sessionPolicy;
const sessionPolicy = { scope, epoch: randomUUID(), changedAt: Date.now() };
store.sessionPolicy = sessionPolicy;
await write(store);
return sessionPolicy;
});
}
export async function getApprovedDevice(deviceId: string): Promise<ApprovedDevice | null> {
const store = await read();
return store.approved[deviceId] ?? null;
}
export function invalidateDeviceSessions(deviceId: string): Promise<void> {
return mutate(async () => {
const store = await read();
if (store.approved[deviceId]) {
store.approved[deviceId].sessionsRevokedAt = Date.now();
await write(store);
}
});
}
export async function isApproved(deviceId: string): Promise<boolean> { return (await getApprovedDevice(deviceId)) !== null; }
/** Mark an approved device as just-seen (best effort). */
export function touchApproved(deviceId: string): Promise<void> {
return mutate(async () => {
const store = await read();
const entry = store.approved[deviceId];
if (!entry) return;
entry.lastSeen = Date.now();
delete store.pending[deviceId];
await write(store);
});
}
export async function listDevices(): Promise<DeviceStore> {
return read();
}
/** Approve a device (moves it out of pending). Omitted role preserves legacy owner semantics. */
export function approveDevice(deviceId: string, label?: string, role: DeviceRole = "owner"): Promise<void> {
if (!isDeviceRole(role)) return Promise.reject(new DeviceRoleError("invalid device role"));
return mutate(async () => {
const store = await read();
if (store.approved[deviceId]) throw new DeviceRoleError("device is already approved; use set_role");
const pending = store.pending[deviceId];
store.approved[deviceId] = {
label: (label && label.slice(0, 80)) || pending?.label || "approved device",
approvedAt: Date.now(),
role,
};
delete store.pending[deviceId];
await write(store);
});
}
/** Change an approved device's live role. Demotion takes effect on its next request. */
export function setDeviceRole(deviceId: string, role: DeviceRole): Promise<void> {
if (!isDeviceRole(role)) return Promise.reject(new DeviceRoleError("invalid device role"));
return mutate(async () => {
const store = await read();
const entry = store.approved[deviceId];
if (!entry) throw new DeviceRoleError("device is not approved");
if (entry.role === "owner" && role !== "owner" && ownerCount(store) <= 1) {
throw new DeviceRoleError("at least one owner device must remain approved");
}
entry.role = role;
await write(store);
});
}
/** Un-trust a device (and clear any pending record for the same id). */
export function revokeDevice(deviceId: string): Promise<void> {
return mutate(async () => {
const store = await read();
const approved = store.approved[deviceId];
if (!approved && !(deviceId in store.pending)) return;
if (approved?.role === "owner" && ownerCount(store) <= 1) {
throw new DeviceRoleError("at least one owner device must remain approved");
}
delete store.approved[deviceId];
delete store.pending[deviceId];
await write(store);
});
}
/** Record (or bump) a device that presented the right password but isn't approved. */
export function recordPending(deviceId: string, label: string, ip: string): Promise<void> {
return mutate(async () => {
const store = await read();
const now = Date.now();
const existing = store.pending[deviceId];
if (existing) {
existing.lastSeen = now;
existing.attempts += 1;
existing.label = label || existing.label;
existing.ip = ip;
} else {
store.pending[deviceId] = { label, firstSeen: now, lastSeen: now, ip, attempts: 1 };
}
const ids = Object.keys(store.pending);
if (ids.length > MAX_PENDING) {
ids
.sort((a, b) => store.pending[a].lastSeen - store.pending[b].lastSeen)
.slice(0, ids.length - MAX_PENDING)
.forEach((id) => delete store.pending[id]);
}
await write(store);
});
}