artifacty 0.10.7 → 0.10.9

package/README.md

@@ -92,6 +92,10 @@ artifacty serve --host 10.0.0.50 --share-mode team --api-token "$ARTIFACTY_BOOTS
 artifacty install all --mcp-url http://10.0.0.50:8787/mcp --api-token "$ARTIFACTY_PERSONAL_TOKEN"
 ```
 
+When running the central server as a Linux `systemctl --user` service, enable
+lingering for the service account so Artifacty stays up after logout:
+`sudo loginctl enable-linger $USER`.
+
 Administrators can create users individually at `/admin/users` or import them
 from CSV. Use `email,name,role,password,password_reset_required` headers. If
 `password` is empty, Artifacty generates a temporary password, shows it once in
@@ -254,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
@@ -305,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,22 @@ 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:
+
+```bash
+sudo loginctl enable-linger artifacty
+loginctl show-user artifacty -p Linger
+```
+
+Use the actual service account name. Without lingering, `systemctl --user`
+services are tied to the user's login manager and can stop after logout, making
+the central dashboard and `/mcp` endpoint unavailable until that user logs in
+again. A system-level unit is another valid option for central servers.
 
 The central server exposes `/mcp` only when explicitly enabled. This keeps the
 local browser/API server behavior unchanged while making team MCP exposure an

package/docs/integrations.md

@@ -393,13 +393,19 @@ The generated service runs `src/server.js` with explicit `--host` and `--home` a
 Activation is still delegated to the OS service manager:
 
 - macOS: `launchctl load ~/Library/LaunchAgents/com.artifacty.server.plist`
-- Linux: `systemctl --user enable --now com.artifacty.server.service`
+- Linux: `sudo loginctl enable-linger $USER`, then `systemctl --user enable --now com.artifacty.server.service`
 - Windows: run the generated PowerShell script, which registers and starts the `ArtifactyServer` scheduled task.
 
+On Linux central servers, user services stop when the user's systemd manager exits unless lingering is enabled. Verify durable operation with `loginctl show-user $USER -p Linger`; it should report `Linger=yes`. Without lingering, Artifacty may be unavailable after logout and appear to recover only after the user logs back in.
+
 For background services, prefer a stable `ARTIFACTY_API_TOKEN` or `--api-token` value. `serve --generate-token` is intended for temporary interactive sessions; the parent CLI returns the generated token in JSON.
 
 ## 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
@@ -407,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.7",
+  "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/lib/service.js

@@ -184,9 +184,11 @@ function definitionForPlatform(platform, options = {}, renderOnly) {
       path: servicePath(platform, options),
       content: createSystemdUserUnit(options),
       nextSteps: [
+        "sudo loginctl enable-linger $USER",
         "systemctl --user daemon-reload",
         `systemctl --user enable --now ${path.basename(servicePath(platform, options))}`,
         `systemctl --user status ${path.basename(servicePath(platform, options))}`,
+        "loginctl show-user $USER -p Linger",
         `journalctl --user -u ${path.basename(servicePath(platform, options))} -f`,
         `systemctl --user disable --now ${path.basename(servicePath(platform, options))}`
       ],

package/src/lib/storage.js

@@ -10,6 +10,7 @@ import { assertNoSecrets, securityConfig } from "./security.js";
 export const STORE_VERSION = 4;
 export const ARTIFACT_SCHEMA_VERSION = 1;
 export const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+const SOURCE_AGENT_NORMALIZATION_VERSION = "1";
 export const USER_ROLES = ["admin", "user"];
 export const ARTIFACT_FORMATS = [
   "html",
@@ -123,6 +124,11 @@ export async function writeIndex(store, index) {
           insertVersionRecord(db, artifact.id, version);
         }
       }
+      normalizeStoredSourceAgents(db, store, {
+        force: true,
+        inTransaction: true,
+        rebuildSearch: false
+      });
       rebuildSearchIndexInDb(db, store);
     });
   } finally {
@@ -1502,9 +1508,26 @@ function migrateJsonIndex(db, store) {
   });
 }
 
+function metaValue(db, key) {
+  return db.prepare("SELECT value FROM meta WHERE key = ?").get(key)?.value || "";
+}
+
 const INFERABLE_SOURCE_AGENTS = new Set(["claude", "codex", "copilot", "cursor", "gemini"]);
 
-function normalizeStoredSourceAgents(db, store) {
+function normalizeStoredSourceAgents(db, store, options = {}) {
+  if (!options.force && metaValue(db, "source_agent_normalized_version") === SOURCE_AGENT_NORMALIZATION_VERSION) {
+    return;
+  }
+
+  const run = () => normalizeStoredSourceAgentsInDb(db, store, options);
+  if (options.inTransaction) {
+    run();
+  } else {
+    transaction(db, run);
+  }
+}
+
+function normalizeStoredSourceAgentsInDb(db, store, options = {}) {
   const rows = db.prepare(`
     SELECT id, source_agent, tags_json
     FROM artifacts
@@ -1512,37 +1535,37 @@ function normalizeStoredSourceAgents(db, store) {
   const updateArtifact = db.prepare("UPDATE artifacts SET source_agent = ?, tags_json = ? WHERE id = ?");
   let changed = false;
 
-  transaction(db, () => {
-    for (const row of rows) {
-      const normalized = normalizeSourceAgent(row.source_agent, { defaultValue: "unknown" });
-      const inferred = isUnknownSourceAgent(normalized)
-        ? inferStoredSourceAgent(db, row)
-        : normalized;
-      const nextSourceAgent = inferred || normalized;
-      const nextTags = normalizeStoredSourceTags(row.tags_json, nextSourceAgent);
-      if (nextSourceAgent !== row.source_agent || nextTags !== row.tags_json) {
-        updateArtifact.run(nextSourceAgent, nextTags, row.id);
-        changed = true;
-      }
+  for (const row of rows) {
+    const normalized = normalizeSourceAgent(row.source_agent, { defaultValue: "unknown" });
+    const inferred = isUnknownSourceAgent(normalized)
+      ? inferStoredSourceAgent(db, row)
+      : normalized;
+    const nextSourceAgent = inferred || normalized;
+    const nextTags = normalizeStoredSourceTags(row.tags_json, nextSourceAgent);
+    if (nextSourceAgent !== row.source_agent || nextTags !== row.tags_json) {
+      updateArtifact.run(nextSourceAgent, nextTags, row.id);
+      changed = true;
     }
+  }
 
-    const auditRows = db.prepare(`
-      SELECT id, source_agent
-      FROM audit_log
-      WHERE source_agent IS NOT NULL
-        AND TRIM(source_agent) != ''
-    `).all();
-    const updateAudit = db.prepare("UPDATE audit_log SET source_agent = ? WHERE id = ?");
-    for (const row of auditRows) {
-      const normalized = normalizeSourceAgent(row.source_agent, { defaultValue: "" });
-      if (normalized && normalized !== row.source_agent) {
-        updateAudit.run(normalized, row.id);
-        changed = true;
-      }
+  const auditRows = db.prepare(`
+    SELECT id, source_agent
+    FROM audit_log
+    WHERE source_agent IS NOT NULL
+      AND TRIM(source_agent) != ''
+  `).all();
+  const updateAudit = db.prepare("UPDATE audit_log SET source_agent = ? WHERE id = ?");
+  for (const row of auditRows) {
+    const normalized = normalizeSourceAgent(row.source_agent, { defaultValue: "" });
+    if (normalized && normalized !== row.source_agent) {
+      updateAudit.run(normalized, row.id);
+      changed = true;
     }
-  });
+  }
+
+  db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('source_agent_normalized_version', ?)").run(SOURCE_AGENT_NORMALIZATION_VERSION);
 
-  if (changed) {
+  if (changed && options.rebuildSearch !== false) {
     rebuildSearchIndexInDb(db, store);
   }
 }

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));
 }