create-volt 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.13.0] - 2026-06-28
+
+### Added
+- Opt-in **`admin`** add-on: a persistent, role-gated web admin (data browser)
+  for browser-only admins. Gated by auth **and** an `ADMIN_EMAILS` allowlist;
+  the panel is hidden for non-admins and `/admin/api/*` returns 403. Internal
+  collections (auth tokens/sessions) hidden. Wired into the default + starter
+  templates and the setup wizard (ADMIN_EMAILS field).
+- `SECURITY.md` documenting the ephemeral-admin model and secure defaults.
+
+### Note
+- Prefer the ephemeral `--studio` (shell-gated) for admins with server access;
+  the `admin` add-on is the explicit standing-surface opt-in for non-shell admins.
+
 ## [0.12.0] - 2026-06-28
 
 ### Added
@@ -173,6 +187,7 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.13.0]: https://github.com/MIR-2025/volt/releases/tag/v0.13.0
 [0.12.0]: https://github.com/MIR-2025/volt/releases/tag/v0.12.0
 [0.11.0]: https://github.com/MIR-2025/volt/releases/tag/v0.11.0
 [0.10.0]: https://github.com/MIR-2025/volt/releases/tag/v0.10.0

package/README.md

@@ -80,6 +80,18 @@ driver, and is **never** a route in the running app (no standing `/admin` to
 attack — shell/SSH access is the gate). Needs a persistent driver (MongoDB /
 MySQL / Postgres) to show data; the memory driver is per-process.
 
+## Security & admin model
+
+Volt is secure by default, and deliberately has **no standing admin route** —
+the config wizard (`--edit`) and data browser (`--studio`) are ephemeral,
+localhost-only processes; **shell/SSH access is the auth**. Several admins? Give
+each an SSH key — stronger than a shared web panel, with nothing public to
+attack. A persistent, role-gated web admin exists only as an **opt-in** add-on
+(`admin`, gated by auth + an `ADMIN_EMAILS` allowlist) for when you truly need
+browser-only admins. Plus: escaping by default (no XSS), server-side validation
++ caps, security headers, and `HttpOnly`+`SameSite` cookies. See
+[SECURITY.md](https://github.com/MIR-2025/volt/blob/main/SECURITY.md).
+
 ## Updating Volt
 
 Volt is vendored as a single file (`public/volt.js`), not an npm dependency.

package/addons/admin/files/lib/admin.js

@@ -0,0 +1,44 @@
+// admin.js — opt-in, role-gated web admin (data browser) for the running app.
+// This is the ONE deliberately-persistent privileged surface in Volt, for
+// browser-only admins. Every route requires a session AND membership in the
+// ADMIN_EMAILS allowlist. Internal collections (auth tokens/sessions) are hidden.
+// Prefer `npm run dev -- --studio` (ephemeral) unless you truly need this.
+
+import express from "express";
+
+const HIDDEN = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
+const visible = (n) => n && !HIDDEN.has(n);
+
+export function adminRouter({ store, requireAuth, adminEmails }) {
+  const allow = new Set((adminEmails || []).map((e) => String(e).trim().toLowerCase()).filter(Boolean));
+  const isAdmin = (email) => allow.has(String(email || "").toLowerCase());
+
+  const r = express.Router();
+  r.use(requireAuth); // must be signed in for anything under /admin/api
+
+  // any signed-in user may ask whether *they* are an admin (drives the UI)
+  r.get("/admin/api/me", (req, res) => res.json({ email: req.user.email, isAdmin: isAdmin(req.user.email) }));
+
+  // everything below is admins-only
+  r.use((req, res, next) => (isAdmin(req.user.email) ? next() : res.status(403).json({ ok: false, error: "Admins only." })));
+
+  r.get("/admin/api/collections", async (_req, res) => {
+    const all = (await store.collections()) || [];
+    res.json({ driver: store.name, collections: all.filter(visible) });
+  });
+  r.get("/admin/api/collection", async (req, res) => {
+    const name = String(req.query.name || "");
+    if (!visible(name)) return res.status(403).json({ ok: false, error: "hidden" });
+    res.json({ ok: true, name, docs: (await store.collection(name).all()).slice(0, 500) });
+  });
+  r.delete("/admin/api/doc", async (req, res) => {
+    const name = String(req.query.name || "");
+    const id = String(req.query.id || "");
+    if (!visible(name)) return res.status(403).json({ ok: false, error: "hidden" });
+    if (!id) return res.status(400).json({ ok: false, error: "missing id" });
+    await store.collection(name).delete(id);
+    res.json({ ok: true });
+  });
+
+  return r;
+}

package/addons/admin/files/public/admin-ui.js

@@ -0,0 +1,62 @@
+// admin-ui.js — the role-gated admin panel (frontend for the admin add-on).
+// Renders nothing for non-admins; for admins, a data browser over /admin/api/*.
+// Mounted by the app when the admin add-on is enabled.
+import { signal, html } from "/volt.js";
+
+const j = async (url, opts) => {
+  const res = await fetch(url, opts);
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+};
+
+export function adminPanel() {
+  const ready = signal(false);
+  const isAdmin = signal(false);
+  const driver = signal("");
+  const collections = signal([]);
+  const current = signal("");
+  const docs = signal([]);
+  const note = signal("");
+
+  async function init() {
+    const { status, body } = await j("/admin/api/me");
+    if (status === 200) isAdmin(!!body.isAdmin);
+    ready(true);
+    if (isAdmin()) load();
+  }
+  async function load() {
+    const { body } = await j("/admin/api/collections");
+    driver(body.driver || "");
+    collections(body.collections || []);
+    if (!current() && collections().length) open(collections()[0]);
+  }
+  async function open(name) {
+    current(name);
+    const { body } = await j(`/admin/api/collection?name=${encodeURIComponent(name)}`);
+    docs(body.ok ? body.docs : []);
+  }
+  async function del(id) {
+    await j(`/admin/api/doc?name=${encodeURIComponent(current())}&id=${encodeURIComponent(id)}`, { method: "DELETE" });
+    docs(docs().filter((d) => d.id !== id));
+    note("Deleted.");
+  }
+  init();
+
+  const tab = (name) =>
+    html`<button class=${() => "btn btn-sm " + (current() === name ? "btn-primary" : "btn-outline-secondary")} onclick=${() => open(name)}>${name}</button>`;
+  const row = (d) =>
+    html`<div class="d-flex justify-content-between align-items-start gap-2 py-1" style="border-top:1px solid #232a36">
+      <pre class="mb-0 small flex-grow-1" style="white-space:pre-wrap;color:#cfe3ff">${JSON.stringify(d, null, 2)}</pre>
+      <button class="btn btn-sm btn-outline-danger" onclick=${() => del(d.id)}>✕</button>
+    </div>`;
+
+  // hidden entirely for non-admins (and until we know)
+  return html`${() =>
+    !ready() || !isAdmin()
+      ? null
+      : html`<div class="card-x p-4 mb-4">
+          <h2 class="h6 mb-3">Admin <span class="text-muted small">— data ${() => (driver() ? "· " + driver() : "")}</span></h2>
+          <div class="d-flex flex-wrap gap-1 mb-2">${() => (collections().length ? collections().map(tab) : html`<span class="text-muted small">No collections yet.</span>`)}</div>
+          <div style="max-height:260px;overflow:auto">${() => (docs().length ? docs().map(row) : html`<span class="text-muted small">Empty.</span>`)}</div>
+          ${() => (note() ? html`<p class="small text-muted mb-0 mt-2">${note}</p>` : null)}
+        </div>`}`;
+}

package/addons/admin/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Opt-in role-gated web admin: a persistent /admin data browser for browser-only admins (auth + ADMIN_EMAILS allowlist). Adds a standing surface — prefer `--studio` unless you need non-shell admins.",
+  "dependsOn": ["db", "auth"],
+  "sentinel": "lib/admin.js",
+  "install": ["express"],
+  "optional": {},
+  "wiring": "Set ADMIN_EMAILS in .env to a comma-separated allowlist of admin emails. Only those signed-in users see the admin panel and can reach /admin/api/*."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/default/public/app.js

@@ -86,4 +86,11 @@ if (enabled.includes("realtime")) {
     /* realtime UI unavailable */
   }
 }
+if (enabled.includes("admin")) {
+  try {
+    nodes.push((await import("/admin-ui.js")).adminPanel());
+  } catch {
+    /* admin UI unavailable */
+  }
+}
 mount("#app", ...nodes);

package/templates/default/server.js

@@ -22,7 +22,7 @@ const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const PKG_VERSIONS = { mongodb: "^6.8.0", mysql2: "^3.11.0", pg: "^8.12.0", nodemailer: "^6.9.0" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", admin: "admin.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -101,6 +101,11 @@ async function startApp() {
   if (enabled.has("db")) store = await (await addonMod("db")).createStore();
   if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
   if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
+  if (enabled.has("admin") && store && enabled.has("auth")) {
+    const adminEmails = String(process.env.ADMIN_EMAILS || "").split(",").map((s) => s.trim()).filter(Boolean);
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use((await addonMod("admin")).adminRouter({ store, requireAuth, adminEmails }));
+  }
 
   // expose which add-ons are on, and serve each enabled add-on's frontend assets
   app.get("/__volt/addons", (_req, res) => res.json([...enabled]));

package/templates/default/setup/setup.js

@@ -17,6 +17,7 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  adminEmails: current.ADMIN_EMAILS || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +54,7 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("admin")) out.push(`ADMIN_EMAILS=${clean(s.adminEmails)}`);
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -148,6 +150,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("admin") ? field("ADMIN_EMAILS (comma-separated)", "adminEmails", "you@example.com") : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">

package/templates/starter/public/app.js

@@ -137,11 +137,21 @@ if (hasChat) {
     /* chat UI unavailable */
   }
 }
+// Admin tab appears only for users in the ADMIN_EMAILS allowlist.
+if (enabled.includes("admin")) {
+  try {
+    const r = await (await fetch("/admin/api/me")).json();
+    if (r.isAdmin) sections.admin = (await import("/admin-ui.js")).adminPanel();
+  } catch {
+    /* not signed in / not admin */
+  }
+}
 
 const TABS = [
   ["home", "Home"],
   ...(hasAuth ? [["notes", "Notes"]] : []),
   ...(sections.chat ? [["chat", "Chat"]] : []),
+  ...(sections.admin ? [["admin", "Admin"]] : []),
   ["account", "Account"],
 ];
 

package/templates/starter/server.js

@@ -23,7 +23,7 @@ const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const PKG_VERSIONS = { mongodb: "^6.8.0", mysql2: "^3.11.0", pg: "^8.12.0", nodemailer: "^6.9.0" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", admin: "admin.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -102,6 +102,11 @@ async function startApp() {
   if (enabled.has("db")) store = await (await addonMod("db")).createStore();
   if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
   if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
+  if (enabled.has("admin") && store && enabled.has("auth")) {
+    const adminEmails = String(process.env.ADMIN_EMAILS || "").split(",").map((s) => s.trim()).filter(Boolean);
+    const requireAuth = (await addonMod("auth")).requireAuth(store);
+    app.use((await addonMod("admin")).adminRouter({ store, requireAuth, adminEmails }));
+  }
 
   // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
   if (enabled.has("db") && enabled.has("auth") && store) {

package/templates/starter/setup/setup.js

@@ -17,6 +17,7 @@ const state = signal({
   dbUrl: current.DATABASE_URL || "",
   smtpUrl: current.SMTP_URL || "",
   mailFrom: current.MAIL_FROM || "",
+  adminEmails: current.ADMIN_EMAILS || "",
   port: current.PORT || String(defaultPort),
 });
 const set = (patch) => state({ ...state(), ...patch });
@@ -53,6 +54,7 @@ function genEnv(s) {
     else out.push("# SMTP_URL=        # unset → emails print to the console");
     if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
   }
+  if (eff.includes("admin")) out.push(`ADMIN_EMAILS=${clean(s.adminEmails)}`);
   return out.join("\n") + "\n";
 }
 const env = computed(() => genEnv(state()));
@@ -148,6 +150,7 @@ mount(
     ${field("PORT", "port", String(defaultPort))}
     ${() => (eff().includes("db") ? dbSettings() : null)}
     ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+    ${() => (eff().includes("admin") ? field("ADMIN_EMAILS (comma-separated)", "adminEmails", "you@example.com") : null)}
   </div>`,
   html`<div class="card-x p-4 mb-3">
     <div class="d-flex justify-content-between align-items-center mb-2">