artifacty 0.10.8 → 0.10.9

package/README.md

@@ -258,6 +258,13 @@ ARTIFACTY_HOME=/path/to/shared/store artifacty serve
 
 Artifact metadata is stored in `artifacty.sqlite`; artifact content is stored as append-only version files under `artifacts/` for normal create and update flows. Administrators can repair or delete individual bad versions from the browser, and those exceptional actions are recorded in the audit log. The current browser server URL is written to `server.json` so MCP tools can return the correct links when the default port falls back. Existing `index.json` stores are migrated automatically on first access.
 
+Administrators can download and restore artifact backups from `/admin/backup`.
+The backup bundle contains artifact metadata and version contents, but not
+users, sessions, API token records, or audit logs. Restoring a bundle replaces
+the target server's artifact records and prunes unreferenced version files. For
+large migrations or scripted server moves, use `artifacty backup` and
+`artifacty import-store --file ./artifacty-backup.json`.
+
 Search uses a SQLite FTS5 index when the local Node SQLite build supports it. The index covers the latest version body plus title, tags, source agent, artifact type, format, and metadata summary. If FTS5 is unavailable, Artifacty keeps working with metadata search. Rebuild or check the store when needed:
 
 ```bash
@@ -309,6 +316,9 @@ Browser routes:
 - `/artifacts/:id/edit`: save a new version with Markdown, HTML, JSON, text, code, SVG, Mermaid, React, SARIF, CSV, image, or video syntax support. Browser edits that do not change the artifact are recorded as `update-noop` audit events without creating a version.
 - `/artifacts/:id/diff`: compare versions.
 - `/admin/artifacts/:id/versions`: administrator-only repair/delete screen for individual versions.
+- `/admin/backup`: administrator-only artifact backup download and restore screen.
+- `/api/admin/backup`: administrator-only artifact backup JSON download.
+- `/api/admin/backup/import`: administrator-only artifact backup restore.
 - `/api/audit`: list audit events.
 
 List APIs support pagination with `limit` and `offset`. Responses keep the top-level `artifacts` array and include `pagination` and `search` metadata:

package/docs/central-team-deployment-design.md

@@ -132,7 +132,9 @@ the user's email as `actor` and created artifacts record the same email as
 Production-like internal deployments should run Artifacty behind a TLS reverse
 proxy, keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled unless the team trusts
 all artifact authors, and store `ARTIFACTY_HOME` on local server disk with
-regular backups.
+regular backups. Administrators can export and restore artifact backup bundles
+from `/admin/backup`; large migrations can use `artifacty backup` on the old
+server and `artifacty import-store --file <backup.json>` on the new server.
 
 For Linux user-service deployments, enable systemd lingering for the service
 account:

package/docs/integrations.md

@@ -402,6 +402,10 @@ For background services, prefer a stable `ARTIFACTY_API_TOKEN` or `--api-token`
 
 ## Backup and Audit
 
+Administrators can open `/admin/backup` to download an artifact backup JSON file
+or restore a backup into the current server. The browser restore flow is useful
+for small and medium migrations; use the CLI for large bundles.
+
 ```bash
 node src/cli.js audit --limit 20
 node src/cli.js backup
@@ -409,4 +413,8 @@ node src/cli.js export --file ./artifacty-backup.json
 node src/cli.js import-store --file ./artifacty-backup.json
 ```
 
-Backups include SQLite metadata plus immutable version file contents in one JSON bundle. Importing a store replaces the target store index, so run it against a new or intentionally chosen `ARTIFACTY_HOME`.
+Backups include artifact metadata plus immutable version file contents in one
+JSON bundle. They do not include users, sessions, API token records, or audit
+logs. Importing a store replaces the target artifact records and prunes
+unreferenced version files, so run it against a new or intentionally chosen
+`ARTIFACTY_HOME`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [

package/src/lib/backup.js

@@ -1,11 +1,29 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createStore, loadIndex, writeIndex } from "./storage.js";
 
+export const MAX_BACKUP_BYTES = 128 * 1024 * 1024;
+
 export async function exportStore(store = createStore(), outputPath) {
   if (!outputPath) {
     throw new Error("export requires --file <path>");
   }
+  const bundle = await buildStoreBackup(store);
+  await mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
+  return {
+    path: path.resolve(outputPath),
+    artifactCount: bundle.artifacts.length,
+    exportedAt: bundle.exportedAt
+  };
+}
+
+export async function exportStoreToString(store = createStore()) {
+  const bundle = await buildStoreBackup(store);
+  return `${JSON.stringify(bundle, null, 2)}\n`;
+}
+
+export async function buildStoreBackup(store = createStore()) {
   const index = await loadIndex(store);
   const artifacts = [];
   for (const artifact of index.artifacts) {
@@ -13,24 +31,18 @@ export async function exportStore(store = createStore(), outputPath) {
     for (const version of artifact.versions) {
       versions.push({
         ...version,
+        path: normalizeBackupRelativePath(version.path),
         content: await readFile(path.join(store.home, version.path), "utf8")
       });
     }
     artifacts.push({ ...artifact, versions });
   }
 
-  const bundle = {
+  return {
     schemaVersion: 1,
     exportedAt: new Date().toISOString(),
     artifacts
   };
-  await mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-  await writeFile(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
-  return {
-    path: path.resolve(outputPath),
-    artifactCount: artifacts.length,
-    exportedAt: bundle.exportedAt
-  };
 }
 
 export async function importStore(store = createStore(), inputPath) {
@@ -38,8 +50,41 @@ export async function importStore(store = createStore(), inputPath) {
     throw new Error("import-store requires --file <path>");
   }
   const bundle = JSON.parse(await readFile(inputPath, "utf8"));
+  const result = await importStoreBundle(store, bundle);
+  return {
+    path: path.resolve(inputPath),
+    ...result
+  };
+}
+
+export async function importStoreFromString(store = createStore(), content) {
+  if (!String(content || "").trim()) {
+    throw new Error("Artifacty backup JSON is required");
+  }
+  let bundle;
+  try {
+    bundle = JSON.parse(content);
+  } catch (error) {
+    throw Object.assign(new Error(`Invalid Artifacty backup JSON: ${error.message}`), {
+      statusCode: 400,
+      code: "INVALID_BACKUP_JSON"
+    });
+  }
+  return importStoreBundle(store, bundle);
+}
+
+export async function importStoreBundle(store = createStore(), bundle) {
+  if (!bundle || typeof bundle !== "object") {
+    throw Object.assign(new Error("Invalid Artifacty backup: JSON object expected"), {
+      statusCode: 400,
+      code: "INVALID_BACKUP"
+    });
+  }
   if (!Array.isArray(bundle.artifacts)) {
-    throw new Error("Invalid Artifacty backup: artifacts array missing");
+    throw Object.assign(new Error("Invalid Artifacty backup: artifacts array missing"), {
+      statusCode: 400,
+      code: "INVALID_BACKUP"
+    });
   }
 
   const index = {
@@ -52,8 +97,9 @@ export async function importStore(store = createStore(), inputPath) {
     for (const version of artifact.versions || []) {
       const cleanVersion = { ...version };
       delete cleanVersion.content;
+      cleanVersion.path = normalizeBackupRelativePath(cleanVersion.path);
       const content = version.content || "";
-      const absolutePath = path.join(store.home, cleanVersion.path);
+      const absolutePath = backupVersionPath(store, cleanVersion.path);
       await mkdir(path.dirname(absolutePath), { recursive: true });
       await writeFile(absolutePath, content, "utf8");
       versions.push(cleanVersion);
@@ -62,8 +108,8 @@ export async function importStore(store = createStore(), inputPath) {
   }
 
   await writeIndex(store, index);
+  await pruneUnreferencedArtifactFiles(store, index);
   return {
-    path: path.resolve(inputPath),
     artifactCount: index.artifacts.length,
     importedAt: new Date().toISOString()
   };
@@ -73,3 +119,84 @@ export function defaultBackupPath(store = createStore()) {
   const stamp = new Date().toISOString().replace(/[:.]/g, "-");
   return path.join(store.home, "backups", `artifacty-${stamp}.json`);
 }
+
+function backupVersionPath(store, relativePath) {
+  const normalized = normalizeBackupRelativePath(relativePath);
+  const root = path.resolve(store.home);
+  const absolute = path.resolve(root, ...normalized.split("/"));
+  if (absolute !== root && !absolute.startsWith(`${root}${path.sep}`)) {
+    throw Object.assign(new Error(`Invalid Artifacty backup version path: ${relativePath}`), {
+      statusCode: 400,
+      code: "INVALID_BACKUP_PATH"
+    });
+  }
+  return absolute;
+}
+
+function normalizeBackupRelativePath(relativePath) {
+  const value = String(relativePath || "");
+  if (!value || path.isAbsolute(value)) {
+    throw Object.assign(new Error(`Invalid Artifacty backup version path: ${value}`), {
+      statusCode: 400,
+      code: "INVALID_BACKUP_PATH"
+    });
+  }
+
+  const portable = value.replaceAll("\\", "/");
+  if (/^[A-Za-z]:\//.test(portable) || portable.startsWith("//")) {
+    throw Object.assign(new Error(`Invalid Artifacty backup version path: ${value}`), {
+      statusCode: 400,
+      code: "INVALID_BACKUP_PATH"
+    });
+  }
+
+  const parts = portable
+    .split("/")
+    .filter((part) => part && part !== ".");
+  if (parts.length === 0 || parts.some((part) => part === "..")) {
+    throw Object.assign(new Error(`Invalid Artifacty backup version path: ${value}`), {
+      statusCode: 400,
+      code: "INVALID_BACKUP_PATH"
+    });
+  }
+  return parts.join("/");
+}
+
+async function pruneUnreferencedArtifactFiles(store, index) {
+  const referenced = new Set();
+  for (const artifact of index.artifacts) {
+    for (const version of artifact.versions || []) {
+      referenced.add(backupVersionPath(store, version.path));
+    }
+  }
+
+  const files = await listFiles(store.artifactsDir);
+  for (const filePath of files) {
+    if (!referenced.has(filePath)) {
+      await rm(filePath, { force: true });
+    }
+  }
+}
+
+async function listFiles(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(path.resolve(fullPath));
+    }
+  }
+  return files;
+}

package/src/lib/render.js

@@ -399,7 +399,7 @@ export function renderAccountPage({ baseUrl, user, tokens = [], createdToken = "
         </div>
         <nav>
           <a href="${view.href("/")}">${view.text("nav.index")}</a>
-          ${user.role === "admin" ? `<a href="/admin/users">Users</a>` : ""}
+          ${user.role === "admin" ? `<a href="/admin/users">Users</a><a href="/admin/backup">Backup</a>` : ""}
           <a href="/account/password">Password</a>
           <form class="nav-form" method="post" action="/logout"><button type="submit">Sign out</button></form>
           ${languageSwitcher(view)}
@@ -483,6 +483,61 @@ export function renderPasswordPage({ baseUrl, user, required = false, error = ""
   });
 }
 
+export function renderAdminBackupPage({ baseUrl, user, integrity, importResult = null, importError = "", locale = DEFAULT_LOCALE, currentPath = "/admin/backup" }) {
+  const view = viewContext(locale, currentPath);
+  return pageShell({
+    title: "Backup",
+    body: `
+      <header class="topbar">
+        <div>
+          <h1>Backup</h1>
+          <p>${escapeHtml(baseUrl)}</p>
+        </div>
+        <nav>
+          <a href="${view.href("/")}">${view.text("nav.index")}</a>
+          <a href="/admin/users">Users</a>
+          <a href="/account">Account</a>
+          ${languageSwitcher(view)}
+        </nav>
+      </header>
+      <main class="artifact-view">
+        ${importResult ? `<p class="auth-success">Restore complete. ${escapeHtml(importResult.artifactCount)} artifacts imported.</p>` : ""}
+        ${importError ? `<p class="auth-error">${escapeHtml(importError)}</p>` : ""}
+        <section class="meta-card">
+          <h2>Store status</h2>
+          <table class="data-table">
+            <tbody>
+              <tr><th>Home</th><td>${escapeHtml(integrity.store)}</td></tr>
+              <tr><th>Artifacts</th><td>${escapeHtml(integrity.artifactCount)}</td></tr>
+              <tr><th>Versions</th><td>${escapeHtml(integrity.versionCount)}</td></tr>
+              <tr><th>Content bytes</th><td>${escapeHtml(integrity.totalBytes)}</td></tr>
+              <tr><th>Integrity</th><td>${integrity.ok ? "OK" : "Needs attention"}</td></tr>
+            </tbody>
+          </table>
+          ${integrity.ok ? "" : `<p class="auth-warning">Run <code>artifacty integrity</code> before migration. Current backup will only include readable referenced version files.</p>`}
+        </section>
+        <section class="meta-card">
+          <h2>Download artifact backup</h2>
+          <p class="muted">Exports artifact metadata and version contents as one JSON bundle. Users, sessions, and API token records are not included.</p>
+          <p><a class="button-link" href="/admin/backup/export">Download backup JSON</a></p>
+        </section>
+        <section class="meta-card">
+          <h2>Restore artifact backup</h2>
+          <p class="auth-warning">Restore replaces the target server's artifact records and version files with the backup contents. Existing users, sessions, API tokens, and audit logs stay unchanged.</p>
+          <form class="editor-form" method="post" action="/admin/backup/import">
+            <label class="field content-field">
+              <span>Backup JSON</span>
+              <textarea class="compact-textarea" name="backup" spellcheck="false" placeholder="{&quot;schemaVersion&quot;:1,&quot;artifacts&quot;:[...]}" required></textarea>
+            </label>
+            <footer class="editor-actions"><button type="submit">Restore backup</button></footer>
+          </form>
+        </section>
+      </main>
+    `,
+    locale: view.locale
+  });
+}
+
 export function renderAdminUsersPage({ baseUrl, user, users = [], importResult = null, importError = "", locale = DEFAULT_LOCALE, currentPath = "/admin/users" }) {
   const view = viewContext(locale, currentPath);
   const rows = users.map((item) => `
@@ -542,6 +597,7 @@ export function renderAdminUsersPage({ baseUrl, user, users = [], importResult =
         </div>
         <nav>
           <a href="${view.href("/")}">${view.text("nav.index")}</a>
+          <a href="/admin/backup">Backup</a>
           <a href="/account">Account</a>
           ${languageSwitcher(view)}
         </nav>
@@ -1361,6 +1417,24 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       transition: background 0.15s ease, border-color 0.15s ease;
     }
     button:hover { background: var(--accent-2); border-color: var(--accent-2); }
+    .button-link {
+      display: inline-flex;
+      min-height: 38px;
+      align-items: center;
+      justify-content: center;
+      padding: 7px 15px;
+      border: 1px solid var(--accent);
+      border-radius: 8px;
+      background: var(--accent);
+      color: var(--accent-ink);
+      font-weight: 600;
+    }
+    .button-link:hover {
+      border-color: var(--accent-2);
+      background: var(--accent-2);
+      color: var(--accent-ink);
+      text-decoration: none;
+    }
     .inline-action button {
       min-height: 32px;
       padding: 5px 12px;
@@ -2043,7 +2117,7 @@ function authNav(user) {
   if (!user) {
     return `<a href="/login">Sign in</a>`;
   }
-  return `${user.role === "admin" ? `<a href="/admin/users">Users</a>` : ""}<a href="/account">Account</a>`;
+  return `${user.role === "admin" ? `<a href="/admin/users">Users</a><a href="/admin/backup">Backup</a>` : ""}<a href="/account">Account</a>`;
 }
 
 export function escapeHtml(value) {

package/src/server.js

@@ -8,6 +8,7 @@ import {
   archiveArtifact,
   authenticateApiToken,
   changeUserPassword,
+  checkStoreIntegrity,
   countUsers,
   createApiToken,
   createArtifact,
@@ -31,6 +32,7 @@ import {
   updateArtifact,
   verifyUserPassword
 } from "./lib/storage.js";
+import { MAX_BACKUP_BYTES, buildStoreBackup, exportStoreToString, importStoreBundle, importStoreFromString } from "./lib/backup.js";
 import { convertAgentArtifact } from "./lib/converters.js";
 import { createLineDiff } from "./lib/diff.js";
 import { EDITOR_CLIENT_PATH, VIEWER_CLIENT_PATH, editorClientFilePath, editorVendorPath, viewerClientFilePath } from "./lib/editor-assets.js";
@@ -43,6 +45,7 @@ import {
   renderArtifactFormPage,
   renderArtifactPage,
   renderAccountPage,
+  renderAdminBackupPage,
   renderAdminArtifactVersionsPage,
   renderAdminUsersPage,
   renderPasswordPage,
@@ -334,6 +337,60 @@ export async function handleRequest({ request, response, store, host, port, secu
     return sendRedirect(response, "/account");
   }
 
+  if (method === "GET" && pathname === "/admin/backup") {
+    if (!currentUser) {
+      return sendRedirect(response, "/login");
+    }
+    requireAdmin(currentUser);
+    return sendHtml(response, renderAdminBackupPage({
+      baseUrl,
+      user: currentUser,
+      integrity: await checkStoreIntegrity(store),
+      locale,
+      currentPath
+    }), 200, headOnly);
+  }
+
+  if (method === "GET" && pathname === "/admin/backup/export") {
+    if (!currentUser) {
+      return sendRedirect(response, "/login");
+    }
+    requireAdmin(currentUser);
+    return sendBackupDownload(response, await exportStoreToString(store), headOnly);
+  }
+
+  if (method === "POST" && pathname === "/admin/backup/import") {
+    assertLocalOrigin(request);
+    if (!currentUser) {
+      return sendRedirect(response, "/login");
+    }
+    requireAdmin(currentUser);
+    const body = await readFormBody(request, MAX_BACKUP_BYTES);
+    try {
+      const importResult = await importStoreFromString(store, body.backup || "");
+      return sendHtml(response, renderAdminBackupPage({
+        baseUrl,
+        user: currentUser,
+        integrity: await checkStoreIntegrity(store),
+        importResult,
+        locale,
+        currentPath: "/admin/backup"
+      }));
+    } catch (error) {
+      if ((error.statusCode || 500) >= 500) {
+        throw error;
+      }
+      return sendHtml(response, renderAdminBackupPage({
+        baseUrl,
+        user: currentUser,
+        integrity: await checkStoreIntegrity(store),
+        importError: error.message,
+        locale,
+        currentPath: "/admin/backup"
+      }), error.statusCode || 400);
+    }
+  }
+
   if (method === "GET" && pathname === "/admin/users") {
     if (!currentUser) {
       return sendRedirect(response, "/login");
@@ -588,6 +645,23 @@ export async function handleRequest({ request, response, store, host, port, secu
     return sendJson(response, { events }, 200, headOnly);
   }
 
+  if (method === "GET" && pathname === "/api/admin/backup") {
+    requireAdminAuth(request.artifactyAuth);
+    return sendJson(response, await buildStoreBackup(store), 200, headOnly, {
+      "content-disposition": `attachment; filename="${backupFileName()}"`
+    });
+  }
+
+  if (method === "POST" && pathname === "/api/admin/backup/import") {
+    assertLocalOrigin(request);
+    requireAdminAuth(request.artifactyAuth);
+    const body = await readJsonBody(request, MAX_BACKUP_BYTES);
+    const result = typeof body.backup === "string"
+      ? await importStoreFromString(store, body.backup)
+      : await importStoreBundle(store, Array.isArray(body.artifacts) ? body : body.backup);
+    return sendJson(response, result);
+  }
+
   if (method === "POST" && pathname === "/api/artifacts") {
     assertLocalOrigin(request);
     const body = await readJsonBody(request);
@@ -835,8 +909,8 @@ function paginationJson(page) {
   };
 }
 
-export async function readJsonBody(request) {
-  const raw = await readBody(request, MAX_ARTIFACT_BYTES + 1024);
+export async function readJsonBody(request, limitBytes = MAX_ARTIFACT_BYTES + 1024) {
+  const raw = await readBody(request, limitBytes);
   if (!raw.trim()) {
     return {};
   }
@@ -850,8 +924,8 @@ export async function readJsonBody(request) {
   }
 }
 
-export async function readFormBody(request) {
-  const raw = await readBody(request, MAX_ARTIFACT_BYTES + 1024);
+export async function readFormBody(request, limitBytes = MAX_ARTIFACT_BYTES + 1024) {
+  const raw = await readBody(request, limitBytes);
   const params = new URLSearchParams(raw);
   return Object.fromEntries(params.entries());
 }
@@ -903,15 +977,30 @@ export function assertLocalOrigin(request) {
   }
 }
 
-export function sendJson(response, data, statusCode = 200, headOnly = false) {
+export function sendJson(response, data, statusCode = 200, headOnly = false, headers = {}) {
   response.writeHead(statusCode, {
     "content-type": "application/json; charset=utf-8",
     "cache-control": "no-store",
-    "x-content-type-options": "nosniff"
+    "x-content-type-options": "nosniff",
+    ...headers
   });
   response.end(headOnly ? undefined : `${JSON.stringify(data, null, 2)}\n`);
 }
 
+function sendBackupDownload(response, content, headOnly = false) {
+  response.writeHead(200, {
+    "content-type": "application/json; charset=utf-8",
+    "content-disposition": `attachment; filename="${backupFileName()}"`,
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff"
+  });
+  response.end(headOnly ? undefined : content);
+}
+
+function backupFileName() {
+  return `artifacty-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;
+}
+
 export function sendHtml(response, html, statusCode = 200, headOnly = false, contentSecurityPolicy = defaultContentSecurityPolicy()) {
   response.writeHead(statusCode, {
     "content-type": "text/html; charset=utf-8",
@@ -1100,6 +1189,15 @@ function requireAdmin(user) {
   }
 }
 
+function requireAdminAuth(auth) {
+  if (auth?.role !== "admin" && auth?.user?.role !== "admin") {
+    throw Object.assign(new Error("Artifacty admin privileges required"), {
+      code: "ADMIN_REQUIRED",
+      statusCode: 403
+    });
+  }
+}
+
 async function sessionUserFromRequest(store, request) {
   return getSessionUser(store, sessionTokenFromRequest(request));
 }