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 { randomUUID } from "node:crypto";
import { promises as fs, constants as fsConstants } from "node:fs";
import { pinSecurityStorePath } from "./security-store-path";
// Cross-process lock for the tiny JSON files that carry security decisions.
// Atomic rename protects one write, but not a whole read-modify-write transaction.
// The web process also serializes in-process callers; this lock covers supported
// operator-side helpers (notably `mso device ...`) that edit the same store.
const DEFAULTS = { waitMs: 25, busyTimeoutMs: 3_000, staleMs: 30_000 } as const;
export type SecurityStoreLockTimings = {
waitMs?: number;
busyTimeoutMs?: number;
staleMs?: number;
};
const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
interface HeldLock {
token: string;
}
function pidIsGone(pid: number): boolean {
try {
process.kill(pid, 0);
return false;
} catch (error) {
return (error as NodeJS.ErrnoException).code === "ESRCH";
}
}
async function abandoned(lockPath: string, staleMs: number): Promise<boolean> {
let handle;
try {
handle = await fs.open(lockPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
const stat = await handle.stat();
if (!stat.isFile() || stat.size > 256 || stat.uid !== process.getuid?.() || (stat.mode & 0o077)) return false; // fail closed: never auto-break an unexpected object
const owner = await handle.readFile("utf8");
const pid = Number(owner.split(":", 1)[0]);
// A valid, live PID wins over age: never break mutual exclusion merely because
// the process was paused. Age is only the recovery path for malformed owner data.
if (Number.isInteger(pid) && pid > 1) return pidIsGone(pid);
return Date.now() - stat.mtimeMs > staleMs;
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") return true;
return false; // symlink, permission error, I/O failure: availability over unsafe recovery
} finally {
await handle?.close().catch(() => undefined);
}
}
async function openExclusive(lockPath: string, token: string): Promise<HeldLock> {
// Build the complete owner record under a private candidate name, then publish it
// with one atomic hard-link. A competing recoverer can never observe an empty or
// partially-written live lock.
const candidate = `${lockPath}.${randomUUID()}.candidate`;
const handle = await fs.open(candidate, "wx", 0o600);
try {
await handle.writeFile(token, "utf8");
await handle.sync();
} finally {
await handle.close().catch(() => undefined);
}
try {
await fs.link(candidate, lockPath);
} finally {
await fs.unlink(candidate).catch(() => undefined);
}
return { token };
}
async function openRecoveryGuard(lockPath: string, token: string): Promise<HeldLock> {
// Recovery guards are never auto-broken: if their owner crashes at any point,
// leaving even an empty guard behind is intentionally fail-closed. Unlike the
// primary lock, there is therefore no need to fsync a candidate before trying
// to publish it. O_EXCL rejects losing contenders before they write/fsync,
// avoiding an fsync convoy when many callers wait on one security store.
const handle = await fs.open(lockPath, "wx", 0o600);
try {
await handle.writeFile(token, "utf8");
await handle.sync();
} finally {
await handle.close().catch(() => undefined);
}
return { token };
}
async function release(lockPath: string, held: HeldLock): Promise<void> {
let handle;
try {
handle = await fs.open(lockPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
const stat = await handle.stat();
if (!stat.isFile() || stat.size > 256 || stat.uid !== process.getuid?.() || (stat.mode & 0o077)) return;
const owner = await handle.readFile("utf8");
// All supported lock publishers serialize under the recovery gate.
if (owner === held.token) await fs.unlink(lockPath).catch(() => undefined);
} catch { /* never remove an unreadable or replaced lock */ }
finally { await handle?.close().catch(() => undefined); }
}
async function acquire(lockPath: string, timings: Required<SecurityStoreLockTimings>): Promise<HeldLock> {
const token = `${process.pid}:${randomUUID()}`;
const recoveryPath = `${lockPath}.recovery`;
const deadline = Date.now() + timings.busyTimeoutMs;
while (true) {
// Every contender takes the recovery guard before inspecting or publishing the
// primary lock. Without this shared acquisition gate, a stale-lock recoverer can
// stat an old lock, observe ENOENT while its owner releases, then unlink a newly
// published live lock at the same pathname (a classic check/unlink ABA race).
let gate: HeldLock | null = null;
try {
gate = await openRecoveryGuard(recoveryPath, `${process.pid}:${randomUUID()}`);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
}
if (gate) {
try {
try {
// Publish the primary lock before releasing the gate. A recoverer that
// removes an abandoned owner therefore hands the path directly to itself;
// no second contender can slip into the unlink/create interval.
return await openExclusive(lockPath, token);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
}
if (await abandoned(lockPath, timings.staleMs)) {
try {
await fs.unlink(lockPath);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
// Still under the shared gate: either this succeeds, or an unsupported
// external writer raced us and we fail closed by retrying rather than
// deleting an unverified replacement.
try {
return await openExclusive(lockPath, token);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
}
}
} finally {
// Recovery guards are deliberately NOT auto-broken. A crashed guard causes
// an availability failure requiring manual cleanup, never a revocation-losing
// race. Normal acquisition holds this guard only for the short publish step.
await release(recoveryPath, gate);
}
}
if (Date.now() >= deadline) throw new Error("security store is busy; retry the operation");
await sleep(timings.waitMs);
}
}
export async function withSecurityStoreLock<T>(
storePath: string,
fn: () => Promise<T>,
options: SecurityStoreLockTimings = {},
): Promise<T> {
const timings = {
waitMs: options.waitMs ?? DEFAULTS.waitMs,
busyTimeoutMs: options.busyTimeoutMs ?? DEFAULTS.busyTimeoutMs,
staleMs: options.staleMs ?? DEFAULTS.staleMs,
};
const pinned = await pinSecurityStorePath(storePath);
const lockPath = `${pinned.file}.lock`;
try {
const held = await acquire(lockPath, timings);
try { return await fn(); }
finally { await release(lockPath, held); }
} finally { await pinned.directory.close(); }
}