onvif-dashboard 0.1.0

package/scripts/create-admin.mts

@@ -0,0 +1,96 @@
+// Creates (or with --force, replaces) the admin login file, outside the app, so the web
+// interface never has to run unsecured. No dependencies beyond the app's own; runs on
+// Node 24+ directly:
+//
+//   npm run admin:create                       # prompts for username and password
+//   npm run admin:create -- --username admin   # prompts for password only
+//   npm run admin:create -- --force            # replace an existing admin (resets password)
+//   printf '%s\n' "$PW" | npm run admin:create -- --username admin   # non-interactive
+//
+// Writes ADMIN_AUTH_FILE if set, otherwise ./.data/admin.json, owner-only (0600).
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { parseArgs } from "node:util";
+import {
+  adminFilePath,
+  createAdminRecord,
+  passwordSchema,
+  readAdminFile,
+  usernameSchema,
+  writeAdminFile,
+} from "../src/lib/admin-file.ts";
+
+const { values } = parseArgs({
+  options: {
+    username: { type: "string" },
+    force: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+});
+
+if (values.help) {
+  console.log("Usage: npm run admin:create -- [--username NAME] [--force]");
+  process.exit(0);
+}
+
+const file = adminFilePath();
+const interactive = process.stdin.isTTY === true;
+
+// Echo is switched off while a password is typed.
+let muted = false;
+const output = new Writable({
+  write(chunk, _encoding, done) {
+    if (!muted) process.stdout.write(chunk);
+    done();
+  },
+});
+const rl = createInterface({ input: process.stdin, output, terminal: interactive });
+// Piped input can arrive before the questions are asked, so read it line by line.
+const lines = interactive ? null : rl[Symbol.asyncIterator]();
+
+async function ask(question: string, { secret = false } = {}): Promise<string> {
+  if (lines) {
+    const next = await lines.next();
+    return next.done ? "" : String(next.value);
+  }
+  if (!secret) return rl.question(question);
+  process.stdout.write(question);
+  muted = true;
+  const answer = await rl.question("");
+  muted = false;
+  process.stdout.write("\n");
+  return answer;
+}
+
+function fail(message: string): never {
+  console.error(`Error: ${message}`);
+  rl.close();
+  process.exit(1);
+}
+
+async function main() {
+  const existing = await readAdminFile(file).catch((err: Error) => fail(err.message));
+  if (existing && !values.force) {
+    fail(`an admin ("${existing.username}") already exists in ${file}. Re-run with --force to replace it.`);
+  }
+
+  const username = values.username ?? (await ask("Admin username: "));
+  const name = usernameSchema.safeParse(username);
+  if (!name.success) fail(`username ${name.error.issues[0].message}`);
+
+  const password = await ask("Password (12+ characters): ", { secret: true });
+  const strong = passwordSchema.safeParse(password);
+  if (!strong.success) fail(`password: ${strong.error.issues[0].message}`);
+  if (interactive && (await ask("Repeat password: ", { secret: true })) !== password) {
+    fail("passwords don't match.");
+  }
+  rl.close();
+
+  await writeAdminFile(file, await createAdminRecord(username, password), {
+    overwrite: values.force,
+  });
+  console.log(`Admin "${username}" saved to ${file} (owner-only).`);
+  if (existing) console.log("Existing sessions are signed out; log in again with the new password.");
+}
+
+await main();

package/scripts/install-mediamtx.mts

@@ -0,0 +1,18 @@
+// Installs the pinned MediaMTX video bridge into ./bin (vrek dec-xkn4z0e). The download is
+// checked against a SHA-256 committed in src/lib/mediamtx-install.ts before anything is
+// written. Safe to re-run: an installed matching build is left alone.
+//
+//   npm run video:install
+import { installMediamtx } from "../src/lib/mediamtx-install.ts";
+
+try {
+  const result = await installMediamtx();
+  console.log(
+    result.status === "installed"
+      ? `Installed MediaMTX ${result.version} at ${result.binary} (checksum verified).`
+      : `MediaMTX ${result.version} is already installed at ${result.binary}.`,
+  );
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}

package/src/lib/admin-file.ts

@@ -0,0 +1,152 @@
+/**
+ * The admin login file: format, password hashing, and atomic read/write.
+ *
+ * Plain Node on purpose (no "server-only", no path aliases, no TS-only syntax) so that
+ * scripts/create-admin.mts can run it directly with `node` to create the file outside the
+ * app. The app uses it through admin-auth.ts.
+ */
+import { randomBytes, scrypt as scryptCb, timingSafeEqual, type ScryptOptions } from "node:crypto";
+import { link, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { adminFile } from "./paths.ts";
+
+// Runtime data, not a build input: the ignore comment keeps it out of Next's output file
+// tracing (see camera-registry.ts).
+/** ADMIN_AUTH_FILE if set, otherwise admin.json in the data folder (see lib/paths.ts). */
+export function adminFilePath(env: Record<string, string | undefined> = process.env): string {
+  return adminFile(env);
+}
+
+export const usernameSchema = z
+  .string()
+  .regex(/^[A-Za-z0-9._@-]{1,64}$/, "1–64 letters, digits, or . _ @ -");
+
+export const passwordSchema = z
+  .string()
+  .min(12, "At least 12 characters")
+  .max(256, "At most 256 characters");
+
+// scrypt cost: N=2^16, r=8, p=1 needs 64 MiB and ~100–200 ms per hash, which makes guessing
+// against a stolen file expensive while keeping a login quick.
+const COST = { N: 2 ** 16, r: 8, p: 1 };
+const KEY_LENGTH = 64;
+const SALT_LENGTH = 16;
+// Refuse absurd parameters from a tampered file rather than exhausting memory.
+const MAX_N = 2 ** 20;
+
+function scrypt(
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  { N, r, p }: { N: number; r: number; p: number },
+) {
+  // scrypt needs 128·N·r bytes; allow twice that so Node's default 32 MiB cap doesn't refuse.
+  const options: ScryptOptions = { N, r, p, maxmem: 256 * N * r };
+  return new Promise<Buffer>((resolve, reject) =>
+    scryptCb(password, salt, keylen, options, (err, key) => (err ? reject(err) : resolve(key))),
+  );
+}
+
+/** `scrypt$N$r$p$salt$hash`, with salt and hash in base64. */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_LENGTH);
+  const key = await scrypt(password, salt, KEY_LENGTH, COST);
+  const { N, r, p } = COST;
+  return ["scrypt", N, r, p, salt.toString("base64"), key.toString("base64")].join("$");
+}
+
+const HASH_PATTERN = /^scrypt\$(\d+)\$(\d+)\$(\d+)\$([A-Za-z0-9+/=]+)\$([A-Za-z0-9+/=]+)$/;
+
+function parseHash(encoded: string) {
+  const m = HASH_PATTERN.exec(encoded);
+  if (!m) return null;
+  const [N, r, p] = [m[1], m[2], m[3]].map(Number);
+  const salt = Buffer.from(m[4], "base64");
+  const key = Buffer.from(m[5], "base64");
+  const powerOfTwo = N > 1 && (N & (N - 1)) === 0;
+  if (!powerOfTwo || N > MAX_N || r < 1 || r > 32 || p < 1 || p > 16) return null;
+  if (salt.length < 8 || key.length < 32) return null;
+  return { N, r, p, salt, key };
+}
+
+export function isValidPasswordHash(encoded: string): boolean {
+  return parseHash(encoded) !== null;
+}
+
+/** Recomputes the hash with its stored parameters and compares in constant time. */
+export async function verifyPassword(password: string, encoded: string): Promise<boolean> {
+  const parsed = parseHash(encoded);
+  if (!parsed) return false;
+  const { N, r, p, salt, key } = parsed;
+  const candidate = await scrypt(password, salt, key.length, { N, r, p });
+  return timingSafeEqual(candidate, key);
+}
+
+export const adminFileSchema = z.object({
+  version: z.literal(1),
+  username: usernameSchema,
+  passwordHash: z.string().refine(isValidPasswordHash, "Not a scrypt$N$r$p$salt$hash string"),
+});
+
+export type AdminFile = z.infer<typeof adminFileSchema>;
+
+export class AdminFileError extends Error {
+  name = "AdminFileError";
+}
+
+/**
+ * The admin file, or null if it doesn't exist. A file that exists but is unreadable or
+ * malformed throws: a typo must never silently turn authentication off.
+ */
+export async function readAdminFile(file: string): Promise<AdminFile | null> {
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new AdminFileError(`Can't read admin file ${file}: ${(err as Error).message}`);
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new AdminFileError(`Admin file ${file} is not valid JSON`);
+  }
+  const parsed = adminFileSchema.safeParse(json);
+  if (!parsed.success) {
+    const problems = parsed.error.issues.map((i) => `${i.path.join(".") || "file"}: ${i.message}`);
+    throw new AdminFileError(`Admin file ${file} is malformed: ${problems.join("; ")}`);
+  }
+  return parsed.data;
+}
+
+/**
+ * Writes the file owner-only (0600) via a temp file, so a crash never leaves it half
+ * written. Without `overwrite`, fails with EEXIST if an admin already exists, atomically.
+ */
+export async function writeAdminFile(
+  file: string,
+  admin: AdminFile,
+  { overwrite = false }: { overwrite?: boolean } = {},
+): Promise<void> {
+  const contents = `${JSON.stringify(adminFileSchema.parse(admin), null, 2)}\n`;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, contents, { mode: 0o600 });
+  try {
+    // link() refuses to replace an existing file; rename() replaces it.
+    await (overwrite ? rename(tmp, file) : link(tmp, file));
+  } finally {
+    if (!overwrite) await unlink(tmp).catch(() => {});
+  }
+}
+
+/** Builds a validated admin record, hashing the password. */
+export async function createAdminRecord(username: string, password: string): Promise<AdminFile> {
+  return {
+    version: 1,
+    username: usernameSchema.parse(username),
+    passwordHash: await hashPassword(passwordSchema.parse(password)),
+  };
+}

package/src/lib/first-run.ts

@@ -0,0 +1,153 @@
+/**
+ * First run (vrek iss-kz5c88a, dec-wx1j9gj): decide where the app keeps its files, make
+ * sure the key that protects stored camera logins exists, and say whether the video bridge
+ * is installed.
+ *
+ * Two rules shape this. The answer has to be remembered, so a globally installed app finds
+ * its data again from any directory: the chosen folder is written to a small pointer file
+ * under the user's config directory. And nothing may block a service: without a terminal
+ * the defaults are taken and the choices are logged.
+ *
+ * Plain Node on purpose (no "server-only", no path aliases) so the CLI can use it.
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { dataDir as defaultDataDir, mediamtxBinary } from "./paths.ts";
+
+type Env = Record<string, string | undefined>;
+
+export const CONFIG_NAME = "onvif-dashboard";
+export const SECRETS_FILE = "secrets.env";
+
+/** Where the pointer to the data folder lives: $XDG_CONFIG_HOME or ~/.config. */
+export function configFile(env: Env = process.env, home = os.homedir()): string {
+  return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), CONFIG_NAME, "config.json");
+}
+
+export async function readConfig(env: Env = process.env, home = os.homedir()): Promise<{ dataDir?: string }> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(configFile(env, home), "utf8"));
+    const dir = (parsed as { dataDir?: unknown }).dataDir;
+    return typeof dir === "string" && dir ? { dataDir: dir } : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(dir: string, env: Env = process.env, home = os.homedir()): Promise<void> {
+  const file = configFile(env, home);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify({ dataDir: dir }, null, 2)}\n`);
+}
+
+/** KEY=value lines, as written by setup and read at startup. */
+export function parseEnvFile(text: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const line of text.split("\n")) {
+    const match = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (match && !line.trimStart().startsWith("#")) values[match[1]] = match[2].trim();
+  }
+  return values;
+}
+
+/**
+ * Makes sure CAMERA_CREDENTIALS_KEY exists, creating one on first run and keeping it
+ * owner-only. Returns the values and whether a key was just made.
+ */
+export async function ensureSecrets(dir: string): Promise<{ values: Record<string, string>; created: boolean }> {
+  const file = path.join(dir, SECRETS_FILE);
+  const existing = parseEnvFile(await readFile(file, "utf8").catch(() => ""));
+  if (existing.CAMERA_CREDENTIALS_KEY) return { values: existing, created: false };
+
+  const values = { ...existing, CAMERA_CREDENTIALS_KEY: randomBytes(32).toString("hex") };
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const text = Object.entries(values)
+    .map(([key, value]) => `${key}=${value}`)
+    .join("\n");
+  await writeFile(file, `# Written by onvif-dashboard. Keep this file private.\n${text}\n`, { mode: 0o600 });
+  await chmod(file, 0o600);
+  return { values, created: true };
+}
+
+export interface FirstRunOptions {
+  env?: Env;
+  home?: string;
+  /** Asks the user; undefined when there is no terminal, so the default is taken. */
+  ask?: (question: string, fallback: string) => Promise<string>;
+  log?: (line: string) => void;
+  /** Whether the MediaMTX binary is present; injected so tests don't touch the disk. */
+  exists?: (file: string) => Promise<boolean>;
+}
+
+export interface FirstRunResult {
+  dataDir: string;
+  /** Where the choice came from, which is worth saying out loud. */
+  source: "environment" | "remembered" | "answered" | "default";
+  secretCreated: boolean;
+  videoReady: boolean;
+}
+
+/**
+ * Settles where data lives and makes sure the credential key exists. Safe to run again:
+ * nothing already set is regenerated or overwritten.
+ */
+export async function firstRun(options: FirstRunOptions = {}): Promise<FirstRunResult> {
+  const env = options.env ?? process.env;
+  const home = options.home ?? os.homedir();
+  const log = options.log ?? ((line: string) => console.log(line));
+  const exists =
+    options.exists ??
+    (async (file: string) => {
+      const { access } = await import("node:fs/promises");
+      return access(file).then(
+        () => true,
+        () => false,
+      );
+    });
+
+  let dataDir: string;
+  let source: FirstRunResult["source"];
+  const remembered = await readConfig(env, home);
+
+  if (env.CAMERAS_DATA_DIR) {
+    dataDir = env.CAMERAS_DATA_DIR;
+    source = "environment";
+  } else if (remembered.dataDir) {
+    dataDir = remembered.dataDir;
+    source = "remembered";
+  } else {
+    const fallback = defaultDataDir({});
+    if (options.ask) {
+      const answer = (await options.ask("Where should this keep its data?", fallback)).trim();
+      dataDir = path.resolve(answer || fallback);
+      source = "answered";
+    } else {
+      dataDir = fallback;
+      source = "default";
+      log(`[setup] No terminal to ask; keeping data in ${dataDir}. Set CAMERAS_DATA_DIR to change it.`);
+    }
+    await writeConfig(dataDir, env, home);
+  }
+
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
+  const { created } = await ensureSecrets(dataDir);
+  if (created) log(`[setup] Made a key for stored camera logins in ${path.join(dataDir, SECRETS_FILE)}.`);
+
+  const videoReady = await exists(mediamtxBinary(env));
+  if (!videoReady) log("[setup] Live video and recording need MediaMTX: run onvif-dashboard install-video.");
+
+  return { dataDir, source, secretCreated: created, videoReady };
+}
+
+/** Puts the remembered folder and the stored key into the environment for this run. */
+export async function applyEnvironment(env: Env = process.env, home = os.homedir()): Promise<void> {
+  if (!env.CAMERAS_DATA_DIR) {
+    const remembered = await readConfig(env, home);
+    if (remembered.dataDir) env.CAMERAS_DATA_DIR = remembered.dataDir;
+  }
+  const dir = env.CAMERAS_DATA_DIR ?? defaultDataDir(env);
+  const stored = parseEnvFile(await readFile(path.join(dir, SECRETS_FILE), "utf8").catch(() => ""));
+  for (const [key, value] of Object.entries(stored)) env[key] ??= value;
+}

package/src/lib/mediamtx-install.ts

@@ -0,0 +1,157 @@
+/**
+ * Downloads the pinned MediaMTX release and installs its binary into bin/ (vrek
+ * dec-xkn4z0e, iss-qdc4vqw). The archive must match a SHA-256 committed here, so a changed
+ * or tampered download is refused before anything is written.
+ *
+ * Plain Node on purpose (no "server-only", no path aliases, no TS-only syntax) so that
+ * scripts/install-mediamtx.mts can run it directly with Node's type stripping.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { binDir as defaultBinDir } from "./paths.ts";
+
+/**
+ * To upgrade: bump the version and replace every sha256 with the values from that
+ * release's checksums.sha256 (cross-check against GitHub's per-asset digests).
+ */
+export const MEDIAMTX_RELEASE = {
+  version: "v1.21.0",
+  sha256: {
+    "darwin-arm64": "159b8e8164022189e654b61ee8bb7edf2d3ff9354ff06cf4c315bb59f5cc9eca",
+    "darwin-amd64": "2ee772efb7e2e365307599e41f849c54539f6019a2ebd4563be9b1256edfeb65",
+    "linux-amd64": "e02e34c3337a35f20ac9e5aa31524566108964e6e37dbc46cf8292169f6c792b",
+    "linux-arm64": "a8113b5928ba1a934b81557b61b8a07954b76921a4b567d54c7f086f8b39d9a2",
+  } as Record<string, string>,
+};
+
+const BINARY = "mediamtx";
+const MARKER = "mediamtx.version.json";
+/** Release archives are about 27 MB; anything far larger is not what we expect. */
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+
+export class MediamtxInstallError extends Error {
+  name = "MediamtxInstallError";
+}
+
+/** Node's platform/arch as MediaMTX names them, e.g. "darwin-arm64", "linux-amd64". */
+export function platformKey(platform: string = process.platform, arch: string = process.arch): string {
+  return `${platform}-${arch === "x64" ? "amd64" : arch}`;
+}
+
+export interface ReleaseAsset {
+  file: string;
+  url: string;
+  sha256: string;
+}
+
+export function releaseAsset(key: string, release = MEDIAMTX_RELEASE): ReleaseAsset {
+  const sha256 = release.sha256[key];
+  if (!sha256) {
+    throw new MediamtxInstallError(
+      `No pinned MediaMTX build for ${key}. Supported: ${Object.keys(release.sha256).join(", ")}.`,
+    );
+  }
+  const [platform, arch] = key.split("-");
+  const file = `mediamtx_${release.version}_${platform}_${arch}.tar.gz`;
+  return { file, sha256, url: `https://github.com/bluenviron/mediamtx/releases/download/${release.version}/${file}` };
+}
+
+export function sha256Of(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/** The network and archive steps, replaceable in tests (pri-e14bahk). */
+export interface InstallDeps {
+  download(url: string): Promise<Uint8Array>;
+  /** Extracts the single file `name` from the .tar.gz at `archive` into the folder `into`. */
+  extract(archive: string, into: string, name: string): Promise<void>;
+}
+
+export const defaultDeps: InstallDeps = {
+  async download(url) {
+    const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+    if (!res.ok) throw new MediamtxInstallError(`Download failed: HTTP ${res.status} for ${url}`);
+    const length = Number(res.headers.get("content-length") ?? 0);
+    if (length > MAX_ARCHIVE_BYTES) throw new MediamtxInstallError(`Download too large (${length} bytes)`);
+    const data = new Uint8Array(await res.arrayBuffer());
+    if (data.length > MAX_ARCHIVE_BYTES) throw new MediamtxInstallError(`Download too large (${data.length} bytes)`);
+    return data;
+  },
+  async extract(archive, into, name) {
+    await promisify(execFile)("tar", ["-xzf", archive, "-C", into, name]);
+  },
+};
+
+export interface InstallResult {
+  status: "installed" | "already-installed";
+  version: string;
+  binary: string;
+}
+
+async function exists(file: string) {
+  return access(file).then(
+    () => true,
+    () => false,
+  );
+}
+
+async function installedMarker(binDir: string): Promise<{ version: string; sha256: string } | null> {
+  try {
+    return JSON.parse(await readFile(path.join(binDir, MARKER), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Installs the pinned MediaMTX into `binDir` unless that exact build is already there.
+ * Verifies the archive's SHA-256 before extracting, and swaps the binary in atomically.
+ */
+export async function installMediamtx({
+  binDir = defaultBinDir(),
+  key = platformKey(),
+  release = MEDIAMTX_RELEASE,
+  deps = defaultDeps,
+}: { binDir?: string; key?: string; release?: typeof MEDIAMTX_RELEASE; deps?: InstallDeps } = {}): Promise<InstallResult> {
+  const asset = releaseAsset(key, release);
+  const binary = path.join(binDir, BINARY);
+  const marker = await installedMarker(binDir);
+  if (marker?.version === release.version && marker.sha256 === asset.sha256 && (await exists(binary))) {
+    return { status: "already-installed", version: release.version, binary };
+  }
+
+  const data = await deps.download(asset.url);
+  const actual = sha256Of(data);
+  if (actual !== asset.sha256) {
+    throw new MediamtxInstallError(
+      `Checksum mismatch for ${asset.file}: expected ${asset.sha256}, got ${actual}. Nothing was installed.`,
+    );
+  }
+
+  const work = await mkdtemp(path.join(os.tmpdir(), "mediamtx-"));
+  try {
+    const archive = path.join(work, asset.file);
+    await writeFile(archive, data);
+    await deps.extract(archive, work, BINARY);
+    const extracted = path.join(work, BINARY);
+    if (!(await exists(extracted))) throw new MediamtxInstallError(`${asset.file} has no ${BINARY} binary`);
+
+    await mkdir(binDir, { recursive: true });
+    // Copy next to the target first (tmp may be another volume), then rename into place.
+    const staged = `${binary}.tmp`;
+    await copyFile(extracted, staged);
+    await chmod(staged, 0o755);
+    await rename(staged, binary);
+    await writeFile(
+      path.join(binDir, MARKER),
+      JSON.stringify({ version: release.version, sha256: asset.sha256 }, null, 2) + "\n",
+    );
+    return { status: "installed", version: release.version, binary };
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/lib/paths.ts

@@ -0,0 +1,54 @@
+/**
+ * Where the app keeps its files (vrek iss-rab8hnz, dec-wx1j9gj). One module answers this,
+ * so the app can run from anywhere, not only from its own source folder.
+ *
+ * CAMERAS_DATA_DIR names the folder holding the admin file, camera registry, encrypted
+ * credentials, audit log, recordings and the video bridge's config. Without it the folder
+ * is ./.data, which is what running from the repo has always meant. Each file also keeps
+ * its own long-standing override, so nothing that worked before stops working.
+ *
+ * Plain Node on purpose (no "server-only", no path aliases, no TS-only syntax) so the
+ * scripts in scripts/ can use it directly.
+ */
+import path from "node:path";
+
+type Env = Record<string, string | undefined>;
+
+/** The folder that holds everything the app writes. */
+export function dataDir(env: Env = process.env): string {
+  return env.CAMERAS_DATA_DIR || path.join(/* turbopackIgnore: true */ process.cwd(), ".data");
+}
+
+/** Where downloaded helpers live, MediaMTX today. Kept beside the app, not in the data folder. */
+export function binDir(env: Env = process.env): string {
+  return env.CAMERAS_BIN_DIR || path.join(/* turbopackIgnore: true */ process.cwd(), "bin");
+}
+
+export function adminFile(env: Env = process.env): string {
+  return env.ADMIN_AUTH_FILE || path.join(dataDir(env), "admin.json");
+}
+
+export function registryFile(env: Env = process.env): string {
+  return env.CAMERA_REGISTRY_FILE || path.join(dataDir(env), "cameras.json");
+}
+
+export function credentialsFile(env: Env = process.env): string {
+  return env.CAMERA_CREDENTIALS_FILE || path.join(dataDir(env), "credentials.json");
+}
+
+export function auditLogFile(env: Env = process.env): string {
+  return env.AUDIT_LOG_FILE || path.join(dataDir(env), "audit.jsonl");
+}
+
+export function recordingsDir(env: Env = process.env): string {
+  return env.RECORDINGS_DIR || path.join(dataDir(env), "recordings");
+}
+
+/** The video bridge's generated config and pid file. */
+export function videoBridgeDir(env: Env = process.env): string {
+  return path.join(dataDir(env), "mediamtx");
+}
+
+export function mediamtxBinary(env: Env = process.env): string {
+  return env.MEDIAMTX_BIN || path.join(binDir(env), "mediamtx");
+}