From a41c8b5fa85419231567fc0925a285c877cf9b7d Mon Sep 17 00:00:00 2001
From: sapientorius <stylefieber@googlemail.com>
Date: Mon, 2 Nov 2026 13:36:23 +0100
Subject: [PATCH 1/3] feat: enhance setup process with improved error handling
 and user feedback

---
 docs/OPERATIONS.md                   |  10 ++
 packages/server/src/app.ts           |  92 ++++++++++---
 packages/web/src/App.vue             |  43 +++++-
 packages/web/src/api.ts              |  10 +-
 packages/web/src/setup-errors.ts     |   4 +
 packages/web/src/setup-request.ts    |  25 ++++
 packages/web/src/stores/session.ts   |   1 +
 packages/web/src/views/LoginView.vue |   9 +-
 tests/setup-http.test.ts             | 194 ++++++++++++++++++++++++---
 tests/setup-request.test.ts          | 144 ++++++++++++++++++++
 10 files changed, 488 insertions(+), 44 deletions(-)
 create mode 100644 packages/web/src/setup-request.ts
 create mode 100644 tests/setup-request.test.ts

diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 751b630..23cc3f9 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -123,6 +123,16 @@ Mount inputs read-only and make them readable only by app UID 65532. Keep sensit
 - Follow [Updates and upgrades](UPGRADING.md) for the maintenance procedure, including Coolify/Dokploy image selection, backup/restore, startup migrations and post-update checks.
 - After an incomplete takeover, preserve the partial DB and restore the original backup separately before pointing sysPass at it. See [rollback](MIGRATION.md#verification-and-rollback).
 
+### Setup stops responding or reappears after import
+
+Setup is selected by the server's `/api/v1/status` response, not by browser display preferences or saved passkeys. An old session cookie can require another sign-in, and a passkey from a deleted installation needs registration in the new installation; neither changes the database's initialization flag.
+
+The browser bounds each setup HTTP exchange to 60 seconds. Import and takeover jobs can run longer while their status requests continue to respond. A response timeout ends the browser's wait only: the server job may still be active. Reload to check the installation state before submitting again, and preserve the database, data volume and deployment secrets. If legacy data has already been imported, continue takeover without uploading the dump again.
+
+Compare `/api/v1/status`, `/health/live` and `/health/ready` on the same public origin. If status reports `setupRequired: true` after a completed setup, verify that the domain routes to the intended single app process and database, and check container restarts, volume mappings and the deployment key. If even liveness does not respond, inspect the app container and ingress before retrying imports. Setup logs contain `setup.started`, `setup.progress`, `setup.completed` and `setup.failed` events correlated by a reference, without uploaded data, credentials or job tokens. Keep the last phase and reference when reporting a failure.
+
+An app process that was waiting for setup rechecks the database before reporting status or accepting setup requests. If another process initialized the database meanwhile, it returns HTTP 503 with `SETUP_STATE_CHANGED`, logs `setup.state.changed` and blocks application access instead of offering setup again. Liveness stays available and readiness reports `restart-required`. Stop duplicate app instances and restart the intended single app with the same database, volume and secrets. This guard does not add support for active replicas.
+
 ## Release and hosting checks
 
 Follow the [release procedure](RELEASES.md) for version preparation, repository rules, approval, immutable assets and digest-pinned deployment. Release candidates never advance the stable `latest` image tag.
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index f3b4e71..16356f4 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -127,6 +127,13 @@ export async function createApp(
   let status = maintenance
     ? { installed: false, legacy: false, ready: false }
     : await migration.status();
+  let setupStateChanged = false;
+  let freshSetupActive = false;
+  const changedSetupState = () =>
+    new Unavailable(
+      "The database was initialized after this app process started. Restart this app and verify that only one app instance uses this database. Keep the database, data volume and deployment secrets.",
+      { code: "SETUP_STATE_CHANGED" },
+    );
   let updates = new Updates(
     db,
     integrations,
@@ -251,6 +258,13 @@ export async function createApp(
         throw new Forbidden("Untrusted proxy headers");
       if (config.production && !ctx.secure && !ctx.path.startsWith("/health/"))
         throw new Forbidden("HTTPS is required");
+      if (
+        ctx.path === "/api/v1/status" ||
+        ctx.path.startsWith("/api/v1/setup/")
+      )
+        await reconcileSetupState();
+      if (setupStateChanged && application && !restoreStatus)
+        throw changedSetupState();
       if (
         ctx.path.startsWith("/api/v1/setup/") &&
         !["GET", "HEAD"].includes(ctx.method)
@@ -334,10 +348,16 @@ export async function createApp(
         ].includes(error.data?.code)
           ? { code: error.data.code }
           : {}),
-        ...(error instanceof Unavailable && error.data?.code === "MAINTENANCE"
-          ? { code: "MAINTENANCE" }
+        ...(error instanceof Unavailable &&
+        ["MAINTENANCE", "SETUP_STATE_CHANGED"].includes(error.data?.code)
+          ? { code: error.data.code }
           : {}),
       };
+      if (
+        error instanceof Unavailable &&
+        error.data?.code === "SETUP_STATE_CHANGED"
+      )
+        ctx.body.message = error.message;
       if (ctx.status >= 500)
         console.error(
           JSON.stringify({
@@ -422,14 +442,39 @@ export async function createApp(
   };
   const setupJobs = new Map<string, SetupJob>(),
     setupTasks = new Set<Promise<void>>();
+  const canReconcileSetup = () =>
+    !maintenance &&
+    !status.ready &&
+    !setupStateChanged &&
+    !freshSetupActive &&
+    !setupTasks.size;
+  const reconcileSetupState = async () => {
+    if (!canReconcileSetup()) return;
+    const current = await migration.status();
+    // A concurrent local setup can complete while the status query is in flight.
+    if (!canReconcileSetup()) return;
+    if (current.ready) {
+      setupStateChanged = true;
+      console.error(JSON.stringify({ event: "setup.state.changed" }));
+    } else status = current;
+  };
   const queueSetup = (kind: string, work: () => Promise<unknown>): SetupJob => {
-    if ([...setupJobs.values()].some((job) => job.state === "running"))
+    if (
+      freshSetupActive ||
+      [...setupJobs.values()].some((job) => job.state === "running")
+    )
       throw new Conflict("A setup job is already active");
     if (setupJobs.size >= 5) setupJobs.delete(setupJobs.keys().next().value!);
     const job: SetupJob = { id: token(), kind, step: kind, state: "running" };
+    const reference = randomUUID();
+    const logProgress = (event: string) =>
+      console.info(JSON.stringify({ event, reference, kind, step: job.step }));
     setupJobs.set(job.id, job);
+    logProgress("setup.started");
     migration.onProgress = (step) => {
+      if (step === job.step) return;
       job.step = step;
+      logProgress("setup.progress");
     };
     const task = (async () => {
       try {
@@ -438,11 +483,12 @@ export async function createApp(
         await startJobs();
         job.state = "complete";
         job.step = "saved";
+        logProgress("setup.completed");
       } catch (error) {
         job.state = "failed";
         job.error = {
           ...setupFailure(error),
-          reference: randomUUID(),
+          reference,
           step: job.step,
         };
         console.error(
@@ -486,13 +532,18 @@ export async function createApp(
       ctx.body = { status: "database-unavailable" };
       return;
     }
-    ctx.status = !maintenance && status.ready && vault.unlocked ? 200 : 503;
+    ctx.status =
+      !maintenance && !setupStateChanged && status.ready && vault.unlocked
+        ? 200
+        : 503;
     ctx.body = {
       status: maintenance
         ? "maintenance"
-        : ctx.status === 200
-          ? "ready"
-          : "setup-required",
+        : setupStateChanged
+          ? "restart-required"
+          : ctx.status === 200
+            ? "ready"
+            : "setup-required",
     };
   });
   router.get("/api/v1/status", async (ctx) => {
@@ -528,15 +579,22 @@ export async function createApp(
     await setup(ctx);
     const data = body(ctx);
     exact(data, ["login", "name", "password"]);
-    await migration.fresh({
-      login: text(data, "login", 50),
-      name: text(data, "name", 80),
-      password: text(data, "password"),
-      token: ctx.get("x-setup-token"),
-    });
-    status = await migration.status();
-    await startJobs();
-    ctx.body = { ready: status.ready };
+    if (freshSetupActive || setupTasks.size)
+      throw new Conflict("A setup job is already active");
+    freshSetupActive = true;
+    try {
+      await migration.fresh({
+        login: text(data, "login", 50),
+        name: text(data, "name", 80),
+        password: text(data, "password"),
+        token: ctx.get("x-setup-token"),
+      });
+      status = await migration.status();
+      await startJobs();
+      ctx.body = { ready: status.ready };
+    } finally {
+      freshSetupActive = false;
+    }
   });
   router.post("/api/v1/setup/migrate", async (ctx) => {
     await setup(ctx);
diff --git a/packages/web/src/App.vue b/packages/web/src/App.vue
index 3ccd632..0aced0e 100644
--- a/packages/web/src/App.vue
+++ b/packages/web/src/App.vue
@@ -28,6 +28,7 @@ import { cancelConfirmation } from "./confirmation";
 import { uiLocales, dateLocales } from "./ui-locale";
 import type { Language, UpdateStatus } from "@nodepass/contracts";
 import { api } from "./api";
+import { setupErrorMessage } from "./setup-errors";
 import { canManage, managementNavigation } from "./navigation";
 export default defineComponent({
   components: {
@@ -61,6 +62,16 @@ export default defineComponent({
     poller: undefined as ReturnType<typeof setInterval> | undefined,
   }),
   computed: {
+    setupRestartMessage() {
+      return setupErrorMessage(
+        {
+          code: "SETUP_STATE_CHANGED",
+          message:
+            "The database was initialized after this app process started. Restart this app and verify that only one app instance uses this database. Keep the database, data volume and deployment secrets.",
+        },
+        String(this.$i18n.locale),
+      );
+    },
     componentLocale() {
       return uiLocales[this.$i18n.locale as Language];
     },
@@ -172,6 +183,7 @@ export default defineComponent({
     window.addEventListener("nodepass-expired", this.expired);
     window.addEventListener("nodepass-refresh", this.refreshSession);
     window.addEventListener("nodepass-maintenance", this.enterMaintenance);
+    window.addEventListener("nodepass-restart-required", this.requireRestart);
     window.addEventListener("focus", this.activated);
     document.addEventListener("visibilitychange", this.activated);
     await this.sessionStore.load();
@@ -187,10 +199,18 @@ export default defineComponent({
     window.removeEventListener("nodepass-expired", this.expired);
     window.removeEventListener("nodepass-refresh", this.refreshSession);
     window.removeEventListener("nodepass-maintenance", this.enterMaintenance);
+    window.removeEventListener(
+      "nodepass-restart-required",
+      this.requireRestart,
+    );
     window.removeEventListener("focus", this.activated);
     document.removeEventListener("visibilitychange", this.activated);
   },
   methods: {
+    requireRestart() {
+      this.sessionStore.restartRequired = true;
+      this.sessionStore.clear();
+    },
     enterMaintenance() {
       this.sessionStore.maintenance = true;
       cancelConfirmation();
@@ -291,7 +311,7 @@ export default defineComponent({
           class="app-root"
           :class="{ 'is-dark': sessionStore.theme === 'dark' }"
         >
-          <BackupProgress />
+          <BackupProgress v-if="!sessionStore.restartRequired" />
           <ConfirmationModal
             v-if="
               sessionStore.viewer?.phase === 'ready' &&
@@ -305,12 +325,23 @@ export default defineComponent({
             />
           </div>
           <template v-else>
-            <div v-if="sessionStore.error" class="global-error">
-              <n-alert type="error" closable @close="sessionStore.error = ''">{{
-                sessionStore.error
-              }}</n-alert>
+            <div
+              v-if="sessionStore.error || sessionStore.restartRequired"
+              class="global-error"
+            >
+              <n-alert
+                type="error"
+                :closable="!sessionStore.restartRequired"
+                @close="sessionStore.error = ''"
+                >{{
+                  sessionStore.restartRequired
+                    ? setupRestartMessage
+                    : sessionStore.error
+                }}</n-alert
+              >
             </div>
-            <template v-if="sessionStore.maintenance"></template>
+            <template v-if="sessionStore.restartRequired"></template>
+            <template v-else-if="sessionStore.maintenance"></template>
             <template v-else-if="publicRoute"><router-view /></template>
             <template
               v-else-if="
diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts
index 37a05bc..2af3453 100644
--- a/packages/web/src/api.ts
+++ b/packages/web/src/api.ts
@@ -35,6 +35,7 @@ async function request(
   method = "GET",
   data?: unknown,
   headers: Record<string, string> = {},
+  signal?: AbortSignal,
 ): Promise<Response> {
   const revision = actionRevision();
   const session = sessionRevision;
@@ -46,6 +47,7 @@ async function request(
     fetch(`/api/v1/${path}`, {
       method,
       credentials: "same-origin",
+      signal,
       headers: {
         ...(body !== undefined ? { "content-type": "application/json" } : {}),
         ...(csrf ? { "x-csrf-token": csrf } : {}),
@@ -69,6 +71,11 @@ async function request(
     } catch {
       /* Do not expose server error bodies. */
     }
+    if (response.status === 503 && failure.code === "SETUP_STATE_CHANGED") {
+      window.dispatchEvent(new Event("nodepass-restart-required"));
+      // Blocking the workspace cancels pending actions; preserve this diagnostic.
+      throw new ApiError(failure, response.status);
+    }
     if (response.status === 503 && failure.code === "MAINTENANCE")
       window.dispatchEvent(new Event("nodepass-maintenance"));
     if (
@@ -95,10 +102,11 @@ export async function api<T = any>(
   method = "GET",
   data?: unknown,
   headers: Record<string, string> = {},
+  signal?: AbortSignal,
 ): Promise<T> {
   const revision = sessionRevision;
   const context = actionRevision();
-  const response = await request(path, method, data, headers);
+  const response = await request(path, method, data, headers, signal);
   const result =
     response.status === 204 ? (undefined as T) : ((await response.json()) as T);
   assertAction(context);
diff --git a/packages/web/src/setup-errors.ts b/packages/web/src/setup-errors.ts
index 4b4dc10..76f5f74 100644
--- a/packages/web/src/setup-errors.ts
+++ b/packages/web/src/setup-errors.ts
@@ -16,6 +16,10 @@ const germanAdminReasons: Record<string, string> = {
 };
 
 const german: Record<string, string> = {
+  SETUP_STATE_CHANGED:
+    "Die Datenbank wurde nach dem Start dieses App-Prozesses eingerichtet. Starte die App neu und prüfe, dass nur eine App-Instanz diese Datenbank verwendet. Datenbank, Datenvolume und Deployment-Secrets beibehalten.",
+  SETUP_RESPONSE_TIMEOUT:
+    "Der Server hat innerhalb von 60 Sekunden keine Einrichtungsantwort geliefert. Der Import kann auf dem Server noch laufen. Lade die Seite neu, um vor einem erneuten Versuch den Installationszustand zu prüfen. Datenbank und Datenvolume beibehalten.",
   SETUP_ADMIN_REQUIRED:
     "Die bisherigen sysPass-Admin-Zugangsdaten konnten nicht bestätigt werden. Verwende den bestehenden Benutzernamen und das bisherige Login-Passwort eines aktiven lokalen sysPass-Anwendungsadministrators. Die Benutzer werden übernommen; neue nodePass-Zugangsdaten berechtigen nicht zur Übernahme.",
   DUMP_SYNTAX:
diff --git a/packages/web/src/setup-request.ts b/packages/web/src/setup-request.ts
new file mode 100644
index 0000000..4377270
--- /dev/null
+++ b/packages/web/src/setup-request.ts
@@ -0,0 +1,25 @@
+import { api, ApiError } from "./api";
+
+/** Bound each HTTP exchange, not the duration of a server-side migration job. */
+export async function setupRequest<T = any>(
+  path: string,
+  method = "GET",
+  data?: unknown,
+  headers: Record<string, string> = {},
+): Promise<T> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 60000);
+  try {
+    return await api<T>(path, method, data, headers, controller.signal);
+  } catch (error) {
+    if (controller.signal.aborted)
+      throw new ApiError({
+        code: "SETUP_RESPONSE_TIMEOUT",
+        message:
+          "No setup response was received within 60 seconds. The server may still be processing the import. Reload the page to check the installation state before retrying. Keep the database and data volume.",
+      });
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
diff --git a/packages/web/src/stores/session.ts b/packages/web/src/stores/session.ts
index 8b0eb77..392c45b 100644
--- a/packages/web/src/stores/session.ts
+++ b/packages/web/src/stores/session.ts
@@ -13,6 +13,7 @@ export const useSession = defineStore("session", {
     viewer: null as (Viewer & { phase: string }) | null,
     setupRequired: false,
     maintenance: false,
+    restartRequired: false,
     legacy: false,
     sso: false,
     version: "",
diff --git a/packages/web/src/views/LoginView.vue b/packages/web/src/views/LoginView.vue
index 375b086..7b2825b 100644
--- a/packages/web/src/views/LoginView.vue
+++ b/packages/web/src/views/LoginView.vue
@@ -19,6 +19,7 @@ import {
 } from "@simplewebauthn/browser";
 import { api, ApiError, type ApiFailure } from "../api";
 import { setupErrorMessage, setupErrorContext } from "../setup-errors";
+import { setupRequest } from "../setup-request";
 import { useSession } from "../stores/session";
 import { languageOptions } from "../i18n";
 import Icon from "../components/Icon.vue";
@@ -193,9 +194,9 @@ export default defineComponent({
       data: unknown,
       headers: Record<string, string>,
     ) {
-      const queued = await api(path, "POST", data, headers);
+      const queued = await setupRequest(path, "POST", data, headers);
       while (!this.closed) {
-        const job = await api(
+        const job = await setupRequest(
           `setup/jobs/${queued.job}`,
           "GET",
           undefined,
@@ -302,7 +303,7 @@ export default defineComponent({
       await this.run(async () => {
         const headers = { "x-setup-token": this.setupToken };
         if (this.mode === "fresh")
-          await api(
+          await setupRequest(
             "setup/fresh",
             "POST",
             { login: this.login, name: this.name, password: this.password },
@@ -323,7 +324,7 @@ export default defineComponent({
             this.dump = "";
             this.sessionStore.legacy = true;
           }
-          await api(
+          await setupRequest(
             "setup/preflight",
             "POST",
             {
diff --git a/tests/setup-http.test.ts b/tests/setup-http.test.ts
index 145b96d..bff3f72 100644
--- a/tests/setup-http.test.ts
+++ b/tests/setup-http.test.ts
@@ -12,6 +12,7 @@ import { database, type Row } from "../packages/server/src/db.js";
 import { isolatedDatabase } from "./database.js";
 import { legacyReference, seedLegacy } from "./legacy.js";
 import { serializePhp } from "./serialization.js";
+import * as OTPAuth from "otpauth";
 const legacyManagementProfile = serializePhp({
   accView: true,
   accViewPass: true,
@@ -25,14 +26,19 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     drop: () => Promise<void>,
     directory: string,
     setupToken: string,
-    dump: string;
+    dump: string,
+    config: ReturnType<typeof loadConfig>;
+  let staleRuntime: typeof runtime | undefined,
+    staleServer: typeof server | undefined,
+    staleBase: string;
   const call = async (
     path: string,
     data?: unknown,
     token = setupToken,
     headers: Record<string, string> = {},
+    target = base,
   ) => {
-    const response = await fetch(base + "/api/v1/" + path, {
+    const response = await fetch(target + "/api/v1/" + path, {
       method: data === undefined ? "GET" : "POST",
       headers: {
         origin: "https://vault.example.test",
@@ -109,20 +115,19 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     drop = isolated.drop;
     directory = await mkdtemp(join(tmpdir(), "nodepass-http-"));
     setupToken = isolated.config.setupToken;
-    runtime = await createApp(
-      {
-        ...isolated.config,
-        dataDir: directory,
-        production: true,
-        publicUrl: "https://vault.example.test",
-        rpId: "vault.example.test",
-        trustProxy: true,
-        trustedProxies: ["coolify-proxy"],
-        legacy: { passwordSalt: legacyReference.publicLink.salt },
-      },
-      undefined,
-      { updateFetch: offlineUpdates },
-    );
+    config = {
+      ...isolated.config,
+      dataDir: directory,
+      production: true,
+      publicUrl: "https://vault.example.test",
+      rpId: "vault.example.test",
+      trustProxy: true,
+      trustedProxies: ["coolify-proxy"],
+      legacy: { passwordSalt: legacyReference.publicLink.salt },
+    };
+    runtime = await createApp(config, undefined, {
+      updateFetch: offlineUpdates,
+    });
     server = await runtime.app.listen(0, "127.0.0.1");
     if (!server.listening) await once(server, "listening");
     const address = server.address();
@@ -137,6 +142,11 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
         server.close((e) => (e ? reject(e) : resolve())),
       );
     if (runtime) await runtime.close();
+    if (staleServer?.listening)
+      await new Promise<void>((resolve, reject) =>
+        staleServer!.close((error) => (error ? reject(error) : resolve())),
+      );
+    if (staleRuntime) await staleRuntime.close();
     if (drop) await drop();
     if (directory) await rm(directory, { recursive: true, force: true });
   });
@@ -163,6 +173,7 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
   });
   it("requires HTTPS and the setup token, restricts concurrency and sanitizes unexpected failures", async () => {
     const log = vi.spyOn(console, "error").mockImplementation(() => {});
+    const progress = vi.spyOn(console, "info").mockImplementation(() => {});
     const insecure = await fetch(base + "/api/v1/status");
     expect(insecure.status).toBe(403);
     expect((await fetch(base + "/health/live")).status).toBe(200);
@@ -186,9 +197,19 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     const queued = await call("setup/import", { dump: "placeholder" });
     expect(queued.response.status).toBe(202);
     expect((await call("setup/import", { dump })).response.status).toBe(409);
+    expect(
+      (
+        await call("setup/fresh", {
+          login: "admin",
+          name: "Synthetic",
+          password: "telescope saffron synthetic 915!",
+        })
+      ).response.status,
+    ).toBe(409);
     expect((await call("setup/jobs/" + queued.value.job)).value.state).toBe(
       "running",
     );
+    runtime.migration.onProgress?.("decode");
     release();
     const failed = await wait(queued.value.job);
     expect(failed.state).toBe("failed");
@@ -198,6 +219,31 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     expect(log).toHaveBeenCalledWith(
       expect.stringContaining(failed.error.reference),
     );
+    expect(progress).toHaveBeenCalledWith(
+      expect.stringContaining(failed.error.reference),
+    );
+    const events = progress.mock.calls.map(([entry]) =>
+      JSON.parse(String(entry)),
+    );
+    expect(events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          event: "setup.started",
+          kind: "import",
+          reference: failed.error.reference,
+        }),
+        expect.objectContaining({
+          event: "setup.progress",
+          step: "decode",
+          reference: failed.error.reference,
+        }),
+      ]),
+    );
+    expect(JSON.stringify(events)).not.toMatch(
+      new RegExp(
+        `${queued.value.job}|${setupToken}|secret database detail|placeholder`,
+      ),
+    );
     expect(JSON.stringify(log.mock.calls)).not.toContain(
       "secret database detail",
     );
@@ -215,6 +261,7 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     );
     expect((await call("setup/jobs/" + first)).response.status).toBe(200);
     log.mockRestore();
+    progress.mockRestore();
   });
   it("explains parser and configuration errors, logs references, and validates config before changing the target", async () => {
     const log = vi.spyOn(console, "error").mockImplementation(() => {});
@@ -298,6 +345,15 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     }
   });
   it("imports real legacy rows, checks identities and retains final status after closing setup", async () => {
+    staleRuntime = await createApp(config, undefined, {
+      updateFetch: offlineUpdates,
+    });
+    staleServer = await staleRuntime.app.listen(0, "127.0.0.1");
+    if (!staleServer.listening) await once(staleServer, "listening");
+    const staleAddress = staleServer.address();
+    if (!staleAddress || typeof staleAddress === "string")
+      throw new Error("Missing stale listener");
+    staleBase = `http://127.0.0.1:${staleAddress.port}`;
     const configuration = `<config><appVersion>310.19081801</appVersion><databaseVersion>unknown</databaseVersion><passwordSalt>${legacyReference.publicLink.salt}</passwordSalt></config>`;
     const imported = await call("setup/import", { dump, configuration });
     expect(imported.response.status).toBe(202);
@@ -381,5 +437,111 @@ describe.skipIf(!enabled)("authenticated asynchronous setup over HTTP", () => {
     expect(signedIn.response.headers.get("set-cookie")).toMatch(/; httponly/i);
     expect(signedIn.value.phase).toBe("verify");
     expect(JSON.stringify(finished)).not.toContain(payload.password);
+    const cookie = signedIn.response.headers.get("set-cookie")!.split(";")[0]!,
+      factor = await runtime
+        .db("nodepass_factors")
+        .where({ userId: 1, kind: "totp" })
+        .first(),
+      otp = new OTPAuth.TOTP({
+        secret: runtime.vault
+          .unwrap(Buffer.from(factor.data, "base64"), "totp/1")
+          .toString(),
+      });
+    const verified = await call(
+      "auth/totp/verify",
+      { code: otp.generate() },
+      setupToken,
+      {
+        cookie,
+        "x-csrf-token": signedIn.value.csrf,
+      },
+    );
+    expect(verified.value.phase).toBe("ready");
+    const readyCookie = verified.response.headers
+      .get("set-cookie")!
+      .split(";")[0]!;
+    const accountsBefore = await call("accounts", undefined, setupToken, {
+      cookie: readyCookie,
+    });
+    expect(
+      accountsBefore.response.status,
+      JSON.stringify(accountsBefore.value),
+    ).toBe(200);
+    expect(accountsBefore.value.total).toBeGreaterThan(0);
+
+    // This process started before import and must not offer setup from its old snapshot.
+    expect((await staleRuntime.migration.status()).ready).toBe(true);
+    const staleStatus = await call(
+      "status",
+      undefined,
+      setupToken,
+      {},
+      staleBase,
+    );
+    expect(staleStatus.response.status).toBe(503);
+    expect(staleStatus.value).toMatchObject({ code: "SETUP_STATE_CHANGED" });
+    expect(staleStatus.value.message).toContain("Restart this app");
+    expect(staleStatus.value).not.toHaveProperty("setupRequired", true);
+    for (const path of ["setup/import", "setup/fresh", "setup/migrate"])
+      expect(
+        (await call(path, {}, setupToken, {}, staleBase)).response.status,
+      ).toBe(503);
+    expect(
+      (
+        await call(
+          "accounts",
+          undefined,
+          setupToken,
+          { cookie: readyCookie },
+          staleBase,
+        )
+      ).response.status,
+    ).toBe(503);
+    expect((await fetch(staleBase + "/health/live")).status).toBe(200);
+    const staleReady = await fetch(staleBase + "/health/ready");
+    expect(staleReady.status).toBe(503);
+    expect(await staleReady.json()).toEqual({ status: "restart-required" });
+    expect((await call("status")).value.setupRequired).toBe(false);
+    await new Promise<void>((resolve, reject) =>
+      staleServer!.close((error) => (error ? reject(error) : resolve())),
+    );
+    await staleRuntime.close();
+    staleServer = undefined;
+    staleRuntime = undefined;
+
+    await new Promise<void>((resolve, reject) =>
+      server.close((error) => (error ? reject(error) : resolve())),
+    );
+    await runtime.close();
+    runtime = await createApp(config, undefined, {
+      updateFetch: offlineUpdates,
+    });
+    server = await runtime.app.listen(0, "127.0.0.1");
+    if (!server.listening) await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string")
+      throw new Error("Missing listener");
+    base = `http://127.0.0.1:${address.port}`;
+    expect((await call("status")).value.setupRequired).toBe(false);
+    expect(
+      (
+        await call("auth/session", undefined, setupToken, {
+          cookie: readyCookie,
+        })
+      ).value.phase,
+    ).toBe("ready");
+    expect(
+      (await call("accounts", undefined, setupToken, { cookie: readyCookie }))
+        .value.total,
+    ).toBeGreaterThan(0);
+    expect(
+      (
+        await call("auth/session", undefined, setupToken, {
+          cookie: `nodepass=${"a".repeat(43)}`,
+        })
+      ).response.status,
+    ).toBe(401);
+    expect((await call("status")).value.setupRequired).toBe(false);
+    expect((await call("setup/import", { dump })).response.status).toBe(403);
   }, 60000);
 });
diff --git a/tests/setup-request.test.ts b/tests/setup-request.test.ts
new file mode 100644
index 0000000..9d1b8fe
--- /dev/null
+++ b/tests/setup-request.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { ApiError, setCsrf } from "../packages/web/src/api";
+import { setupRequest } from "../packages/web/src/setup-request";
+import { setupErrorMessage } from "../packages/web/src/setup-errors";
+import { cancelConfirmation } from "../packages/web/src/confirmation";
+
+const fetcher = vi.fn<typeof fetch>();
+beforeEach(() => {
+  vi.useFakeTimers();
+  setCsrf("");
+  fetcher.mockReset();
+  vi.stubGlobal("fetch", fetcher);
+  vi.stubGlobal("window", new EventTarget());
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+it.each(["setup/import", "setup/jobs/synthetic-job"])(
+  "ends a stalled %s exchange with an explicit uncertain-outcome error and no retry",
+  async (path) => {
+    let signal!: AbortSignal;
+    fetcher.mockImplementationOnce((_url, options) => {
+      signal = options!.signal!;
+      return new Promise((_resolve, reject) =>
+        signal.addEventListener("abort", () => reject(signal.reason), {
+          once: true,
+        }),
+      );
+    });
+    const pending = setupRequest(
+      path,
+      path.endsWith("import") ? "POST" : "GET",
+      undefined,
+      { "x-setup-token": "synthetic-setup-token" },
+    ).catch((error: unknown) => error);
+    await vi.advanceTimersByTimeAsync(59999);
+    expect(signal.aborted).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    const failure = await pending;
+    expect(failure).toBeInstanceOf(ApiError);
+    expect((failure as ApiError).failure.code).toBe("SETUP_RESPONSE_TIMEOUT");
+    expect((failure as ApiError).message).toContain("may still be processing");
+    expect(setupErrorMessage((failure as ApiError).failure, "de_DE")).toContain(
+      "noch laufen",
+    );
+    expect(fetcher).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  },
+);
+
+it("clears the deadline after a queued job and keeps authorization headers", async () => {
+  fetcher.mockResolvedValueOnce(
+    new Response(JSON.stringify({ job: "synthetic-job" }), { status: 202 }),
+  );
+  expect(
+    await setupRequest(
+      "setup/import",
+      "POST",
+      { dump: "synthetic dump" },
+      { "x-setup-token": "synthetic-setup-token" },
+    ),
+  ).toEqual({ job: "synthetic-job" });
+  expect(fetcher).toHaveBeenCalledWith(
+    "/api/v1/setup/import",
+    expect.objectContaining({
+      method: "POST",
+      headers: expect.objectContaining({
+        "x-setup-token": "synthetic-setup-token",
+      }),
+      signal: expect.any(AbortSignal),
+    }),
+  );
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it("preserves a server failure and clears its deadline", async () => {
+  fetcher.mockResolvedValueOnce(
+    new Response(
+      JSON.stringify({
+        code: "DUMP_SYNTAX",
+        message: "Synthetic invalid dump",
+      }),
+      { status: 400 },
+    ),
+  );
+  await expect(setupRequest("setup/import", "POST", {})).rejects.toMatchObject({
+    status: 400,
+    failure: { code: "DUMP_SYNTAX" },
+  });
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it("blocks the browser workspace when a stale app reports a changed installation", async () => {
+  const blocked = vi.fn();
+  const maintenance = vi.fn();
+  window.addEventListener("nodepass-maintenance", maintenance);
+  window.addEventListener("nodepass-restart-required", () => {
+    blocked();
+    cancelConfirmation();
+  });
+  fetcher.mockResolvedValueOnce(
+    new Response(
+      JSON.stringify({
+        code: "SETUP_STATE_CHANGED",
+        message: "Restart this app",
+      }),
+      { status: 503 },
+    ),
+  );
+  await expect(setupRequest("status")).rejects.toMatchObject({
+    status: 503,
+    failure: { code: "SETUP_STATE_CHANGED" },
+  });
+  expect(blocked).toHaveBeenCalledTimes(1);
+  expect(maintenance).not.toHaveBeenCalled();
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it("bounds a response body that stalls after its headers arrive", async () => {
+  fetcher.mockImplementationOnce(async (_url, options) => {
+    const response = new Response("{}");
+    vi.spyOn(response, "json").mockImplementationOnce(
+      () =>
+        new Promise((_resolve, reject) =>
+          options!.signal!.addEventListener(
+            "abort",
+            () => reject(options!.signal!.reason),
+            { once: true },
+          ),
+        ),
+    );
+    return response;
+  });
+  const pending = setupRequest("setup/jobs/synthetic-job").catch(
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(60000);
+  expect(await pending).toMatchObject({
+    failure: { code: "SETUP_RESPONSE_TIMEOUT" },
+  });
+  expect(vi.getTimerCount()).toBe(0);
+});

From db238a259559df8d4316db49f87799eeccf20470 Mon Sep 17 00:00:00 2001
From: sapientorius <stylefieber@googlemail.com>
Date: Mon, 2 Nov 2026 14:37:24 +0100
Subject: [PATCH 2/3] feat: add MFA translations and enhance login view with
 recovery options

---
 packages/web/src/i18n.ts                |   2 +
 packages/web/src/mfa-translations.ts    | 102 ++++++++++++++++++++++++
 packages/web/src/style.css              |  17 ++++
 packages/web/src/views/LoginView.vue    |  44 +++++++---
 packages/web/src/views/TransferView.vue |   8 +-
 tests/e2e/vault.spec.ts                 |   5 +-
 6 files changed, 162 insertions(+), 16 deletions(-)
 create mode 100644 packages/web/src/mfa-translations.ts

diff --git a/packages/web/src/i18n.ts b/packages/web/src/i18n.ts
index 53db61c..f0cafe1 100644
--- a/packages/web/src/i18n.ts
+++ b/packages/web/src/i18n.ts
@@ -21,6 +21,7 @@ import { userGroupMessages } from "./user-group-translations";
 import { accountAccessMessages } from "./account-access-translations";
 import { userManagementMessages } from "./user-management-translations";
 import { backupMessages } from "./backup-translations";
+import { mfaMessages } from "./mfa-translations";
 export const languageOptions = [
   { label: "Deutsch", value: "de_DE" },
   { label: "English", value: "en_US" },
@@ -117,6 +118,7 @@ export const messages = Object.fromEntries(
         ...sessionMessages[locale],
         ...eventMessages[locale],
         ...transferMessages[locale],
+        ...mfaMessages[locale],
         backToLogin: backToLoginLabels[locale as Language],
       },
     ];
diff --git a/packages/web/src/mfa-translations.ts b/packages/web/src/mfa-translations.ts
new file mode 100644
index 0000000..e0c5d32
--- /dev/null
+++ b/packages/web/src/mfa-translations.ts
@@ -0,0 +1,102 @@
+import type { Language } from "@nodepass/contracts";
+
+const rows: Record<Language, [string, string, string, string]> = {
+  de_DE: [
+    "Gib den aktuellen Code aus deiner Authenticator-App ein.",
+    "Gib einen deiner gespeicherten Wiederherstellungscodes ein. Jeder Code ist nur einmal gültig.",
+    "Im Notfall: Wiederherstellungscode verwenden",
+    "Zurück zum Authenticator-Code",
+  ],
+  en_US: [
+    "Enter the current code from your authenticator app.",
+    "Enter one of your saved recovery codes. Each code can only be used once.",
+    "Emergency access: use a recovery code",
+    "Back to authenticator code",
+  ],
+  es_ES: [
+    "Introduce el código actual de tu aplicación de autenticación.",
+    "Introduce uno de tus códigos de recuperación guardados. Cada código solo se puede usar una vez.",
+    "En caso de emergencia: usar un código de recuperación",
+    "Volver al código de la aplicación",
+  ],
+  ca_ES: [
+    "Introdueix el codi actual de la teva aplicació d’autenticació.",
+    "Introdueix un dels teus codis de recuperació desats. Cada codi només es pot fer servir una vegada.",
+    "En cas d’emergència: fes servir un codi de recuperació",
+    "Torna al codi de l’aplicació",
+  ],
+  hu_HU: [
+    "Adja meg a hitelesítő alkalmazásban látható aktuális kódot.",
+    "Adja meg az egyik elmentett helyreállítási kódját. Minden kód csak egyszer használható.",
+    "Vészhelyzetben: helyreállítási kód használata",
+    "Vissza a hitelesítő alkalmazás kódjához",
+  ],
+  fr_FR: [
+    "Saisissez le code actuel de votre application d’authentification.",
+    "Saisissez l’un de vos codes de récupération enregistrés. Chaque code ne peut être utilisé qu’une fois.",
+    "En cas d’urgence : utiliser un code de récupération",
+    "Revenir au code de l’application",
+  ],
+  pl_PL: [
+    "Wpisz aktualny kod z aplikacji uwierzytelniającej.",
+    "Wpisz jeden z zapisanych kodów odzyskiwania. Każdego kodu można użyć tylko raz.",
+    "W sytuacji awaryjnej: użyj kodu odzyskiwania",
+    "Wróć do kodu z aplikacji",
+  ],
+  ru_RU: [
+    "Введите текущий код из приложения аутентификации.",
+    "Введите один из сохранённых кодов восстановления. Каждый код можно использовать только один раз.",
+    "Экстренный доступ: использовать код восстановления",
+    "Вернуться к коду из приложения",
+  ],
+  nl_NL: [
+    "Voer de huidige code uit je authenticator-app in.",
+    "Voer een van je opgeslagen herstelcodes in. Elke code kan maar één keer worden gebruikt.",
+    "In noodgevallen: gebruik een herstelcode",
+    "Terug naar de authenticatorcode",
+  ],
+  pt_BR: [
+    "Digite o código atual do seu aplicativo autenticador.",
+    "Digite um dos seus códigos de recuperação salvos. Cada código só pode ser usado uma vez.",
+    "Em caso de emergência: usar um código de recuperação",
+    "Voltar ao código do autenticador",
+  ],
+  it_IT: [
+    "Inserisci il codice attuale della tua app di autenticazione.",
+    "Inserisci uno dei codici di recupero salvati. Ogni codice può essere usato una sola volta.",
+    "In caso di emergenza: usa un codice di recupero",
+    "Torna al codice dell’app",
+  ],
+  da: [
+    "Indtast den aktuelle kode fra din godkendelsesapp.",
+    "Indtast en af dine gemte gendannelseskoder. Hver kode kan kun bruges én gang.",
+    "I nødstilfælde: brug en gendannelseskode",
+    "Tilbage til koden fra appen",
+  ],
+  fo: [
+    "Skriva núverandi kotuna úr váttanarforritinum.",
+    "Skriva eina av tínum goymdu endurskapanarkotum. Hvør kota kann bara nýtast eina ferð.",
+    "Í neyðstøðu: nýt eina endurskapanarkotu",
+    "Aftur til kotuna úr váttanarforritinum",
+  ],
+  ja_JP: [
+    "認証アプリに表示されている現在のコードを入力してください。",
+    "保存した復旧コードのいずれかを入力してください。各コードは一度だけ使えます。",
+    "緊急時：復旧コードを使用",
+    "認証アプリのコードに戻る",
+  ],
+};
+
+export const mfaMessages = Object.fromEntries(
+  Object.entries(rows).map(([locale, values]) => [
+    locale,
+    Object.fromEntries(
+      [
+        "mfaTotpHelp",
+        "mfaRecoveryHelp",
+        "useRecoveryCode",
+        "useAuthenticatorCode",
+      ].map((key, index) => [key, values[index]!]),
+    ),
+  ]),
+);
diff --git a/packages/web/src/style.css b/packages/web/src/style.css
index cd14d6f..80db675 100644
--- a/packages/web/src/style.css
+++ b/packages/web/src/style.css
@@ -833,6 +833,23 @@ footer span {
 .auth-card .n-tabs {
   margin-bottom: 22px;
 }
+.auth-recovery-option {
+  margin-top: 24px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+  text-align: center;
+}
+.auth-recovery-option .n-button {
+  max-width: 100%;
+  height: auto;
+  min-height: 32px;
+  line-height: 1.7;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.auth-recovery-option .n-button__content {
+  white-space: normal;
+}
 .auth-divider {
   height: 53px;
   display: flex;
diff --git a/packages/web/src/views/LoginView.vue b/packages/web/src/views/LoginView.vue
index 7b2825b..e0028e1 100644
--- a/packages/web/src/views/LoginView.vue
+++ b/packages/web/src/views/LoginView.vue
@@ -278,6 +278,14 @@ export default defineComponent({
         this.enrollment = await api("auth/totp/start", "POST", {});
       });
     },
+    async switchVerificationMethod() {
+      if (this.busy) return;
+      this.recoveryMode = !this.recoveryMode;
+      this.code = "";
+      this.sessionStore.error = "";
+      await this.$nextTick();
+      (this.$refs.verificationInput as InputInst | undefined)?.focus();
+    },
     async finishTotp() {
       await this.run(async () => {
         this.sessionStore.accept(
@@ -441,12 +449,18 @@ export default defineComponent({
         <h1>
           {{ isSetup ? $t("setup") : pending ? $t("mfa") : $t("welcome") }}
         </h1>
-        <p class="muted auth-description">
+        <p id="auth-description" class="muted auth-description">
           {{
             isSetup
               ? $t("setupHelp")
               : pending
-                ? $t(pending === "enroll" ? "enroll" : "confirm")
+                ? $t(
+                    pending === "enroll"
+                      ? "enroll"
+                      : recoveryMode
+                        ? "mfaRecoveryHelp"
+                        : "mfaTotpHelp",
+                  )
                 : $t("loginHelp")
           }}
         </p>
@@ -656,23 +670,17 @@ export default defineComponent({
           ><n-form
             v-if="pending === 'verify' || enrollment"
             @submit.prevent="finishTotp"
-            ><n-button
-              v-if="pending === 'verify'"
-              quaternary
-              style="margin-bottom: 12px"
-              @click="
-                recoveryMode = !recoveryMode;
-                code = '';
-              "
-              >{{ $t(recoveryMode ? "totp" : "recoveryCodes") }}</n-button
             ><n-form-item :label="$t(recoveryMode ? 'recoveryCodes' : 'code')"
               ><n-input
+                ref="verificationInput"
                 v-model:value="code"
+                :disabled="busy"
                 :maxlength="recoveryMode ? 100 : 6"
                 autocomplete="one-time-code"
                 :input-props="{
                   inputmode: recoveryMode ? 'text' : 'numeric',
                   'aria-label': $t(recoveryMode ? 'recoveryCodes' : 'code'),
+                  'aria-describedby': 'auth-description',
                 }" /></n-form-item
             ><n-button
               type="primary"
@@ -691,7 +699,19 @@ export default defineComponent({
             :loading="busy"
             @click="backToLogin"
             >{{ $t("backToLogin") }}</n-button
-          ></template
+          >
+          <div v-if="pending === 'verify'" class="auth-recovery-option">
+            <n-button
+              text
+              size="small"
+              attr-type="button"
+              :disabled="busy"
+              @click="switchVerificationMethod"
+              >{{
+                $t(recoveryMode ? "useAuthenticatorCode" : "useRecoveryCode")
+              }}</n-button
+            >
+          </div></template
         >
         <template v-else
           ><n-form @submit.prevent="signIn"
diff --git a/packages/web/src/views/TransferView.vue b/packages/web/src/views/TransferView.vue
index b82921f..c6653f8 100644
--- a/packages/web/src/views/TransferView.vue
+++ b/packages/web/src/views/TransferView.vue
@@ -208,9 +208,11 @@ export default defineComponent({
               :disabled="busy"
               type="password"
               autocomplete="off" /></n-form-item
-          ><n-alert v-if="format === 'syspass' && !preview" type="info">{{
-            $t("importPasswordHelp")
-          }}</n-alert
+          ><n-alert
+            v-if="format === 'syspass' && !preview"
+            type="info"
+            style="margin-bottom: 16px"
+            >{{ $t("importPasswordHelp") }}</n-alert
           ><template v-if="preview"
             ><n-alert type="info" :title="$t('preview')"
               >{{ preview.count }} · {{ $t("accounts") }}</n-alert
diff --git a/tests/e2e/vault.spec.ts b/tests/e2e/vault.spec.ts
index c955950..60c3991 100644
--- a/tests/e2e/vault.spec.ts
+++ b/tests/e2e/vault.spec.ts
@@ -352,7 +352,10 @@ test("fresh setup, MFA, accounts, themes, responsive layout and passwordless pas
   await page.getByLabel("Passwort", { exact: true }).fill(secrets.password);
   await page.getByRole("button", { name: "Anmelden", exact: true }).click();
   await page
-    .getByRole("button", { name: "Wiederherstellungscodes", exact: true })
+    .getByRole("button", {
+      name: "Im Notfall: Wiederherstellungscode verwenden",
+      exact: true,
+    })
     .click();
   await page
     .getByRole("textbox", { name: "Wiederherstellungscodes", exact: true })

From 28b1125fd904c8626332aa7a9fd7bf92c1a91091 Mon Sep 17 00:00:00 2001
From: sapientorius <stylefieber@googlemail.com>
Date: Mon, 2 Nov 2026 14:44:01 +0100
Subject: [PATCH 3/3] chore: prepare nodePass 0.1.7 release

---
 CHANGELOG.md                      | 16 ++++++++++++++++
 README.md                         |  2 +-
 SECURITY.md                       |  2 +-
 package-lock.json                 | 14 +++++++-------
 package.json                      |  2 +-
 packages/contracts/package.json   |  2 +-
 packages/contracts/src/version.ts |  2 +-
 packages/server/package.json      |  4 ++--
 packages/web/package.json         |  4 ++--
 9 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0be2084..d582597 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 Versions before 1.0 may include breaking changes in minor releases. Patch releases contain compatible fixes. Release candidates are intended for evaluation with synthetic data or a separate representative copy.
 
+## [0.1.7]
+
+### Fixed
+
+- Setup requests now time out after 60 seconds per HTTP exchange with guidance to check the installation state before retrying. Long-running import and takeover jobs continue on the server.
+- An app process waiting for setup detects when another process has initialized its database, blocks application access and requests a restart instead of offering setup again. Concurrent local setup requests are rejected while a setup operation is active.
+- Setup jobs log their start, progress and completion with a shared diagnostic reference without exposing uploaded data, credentials or job tokens.
+- TOTP sign-in explains the active method and presents recovery codes as a smaller emergency option below the main actions. Switching methods clears the input and focuses the code field; the new text is translated into all 14 supported languages.
+- Add spacing between the sysPass XML import hint and the preview button.
+
+### Upgrade notes
+
+- No database schema change is introduced. Preserve existing deployment keys, secrets, persistent volumes and backups, and run a single application process.
+- If setup reports `SETUP_STATE_CHANGED`, stop duplicate app instances and restart the intended application with the existing database, data volume and secrets. A browser timeout does not cancel a server-side setup job.
+- The cumulative security catalogue retains NP-2026-001 and NP-2026-002; this release adds no newly disclosed security corrections.
+
 ## [0.1.6]
 
 ### Fixed
diff --git a/README.md b/README.md
index 72eb52d..d292403 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ All browser assets are served locally. There are no CDNs, remote fonts, external
 
 ## Status and security responsibilities
 
-nodePass is version **0.1.6**. Implemented features and historical local testing do not constitute a production approval. Before deployment, require **Required release checks** (`release-gate`) to pass on the exact commit, test migration and restore with a representative copy of your own data, and validate your real integrations and proxy configuration. Automated scanners are not an independent security audit. No independent external security audit is claimed.
+nodePass is version **0.1.7**. Implemented features and historical local testing do not constitute a production approval. Before deployment, require **Required release checks** (`release-gate`) to pass on the exact commit, test migration and restore with a representative copy of your own data, and validate your real integrations and proxy configuration. Automated scanners are not an independent security audit. No independent external security audit is claimed.
 
 nodePass is **not end-to-end encrypted**. The running server can decrypt secrets for authorized operations. The application host, deployment key and operators with infrastructure access are part of the trust boundary. Keep keys separate from backups and protect the host accordingly.
 
diff --git a/SECURITY.md b/SECURITY.md
index fb11d10..fc83d9f 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -10,6 +10,6 @@ Reports concern nodePass. The upstream sysPass project's contact address is not
 
 ## Version and verification policy
 
-The current project version is 0.1.6. Report against the exact commit when possible. No long-term support branches or fixed support periods are promised. Production deployment requires the exact commit's **Required release checks** and operator-specific validation; local reports alone are insufficient.
+The current project version is 0.1.7. Report against the exact commit when possible. No long-term support branches or fixed support periods are promised. Production deployment requires the exact commit's **Required release checks** and operator-specific validation; local reports alone are insufficient.
 
 Read the [security model](docs/SECURITY.md) for trust boundaries and known constraints, and [Operations](docs/OPERATIONS.md#release-and-hosting-checks) for release requirements. Automated scans do not constitute an independent security audit.
diff --git a/package-lock.json b/package-lock.json
index 394d7e7..7197fd6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "nodepass",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "nodepass",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "license": "GPL-3.0-or-later",
       "workspaces": [
         "packages/*"
@@ -7081,21 +7081,21 @@
     },
     "packages/contracts": {
       "name": "@nodepass/contracts",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "dependencies": {
         "@feathersjs/typebox": "^5.0.35"
       }
     },
     "packages/server": {
       "name": "@nodepass/server",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "dependencies": {
         "@feathersjs/errors": "^5.0.35",
         "@feathersjs/feathers": "^5.0.35",
         "@feathersjs/koa": "^5.0.35",
         "@feathersjs/schema": "^5.0.35",
         "@koa/router": "^15.7.0",
-        "@nodepass/contracts": "0.1.6",
+        "@nodepass/contracts": "0.1.7",
         "@simplewebauthn/server": "^13.2.0",
         "@zxcvbn-ts/core": "^3.0.4",
         "@zxcvbn-ts/language-common": "^3.0.4",
@@ -7117,9 +7117,9 @@
     },
     "packages/web": {
       "name": "@nodepass/web",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "dependencies": {
-        "@nodepass/contracts": "0.1.6",
+        "@nodepass/contracts": "0.1.7",
         "@simplewebauthn/browser": "^13.2.0",
         "@vitejs/plugin-vue": "^6.0.0",
         "@zxcvbn-ts/core": "^3.0.4",
diff --git a/package.json b/package.json
index 62fe18c..a24e0b1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nodepass",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "description": "Self-hosted sysPass successor with a Feathers 5 API and Vue 3 UI",
   "license": "GPL-3.0-or-later",
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index e6db763..0f66ac9 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nodepass/contracts",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {
diff --git a/packages/contracts/src/version.ts b/packages/contracts/src/version.ts
index 3c2dfff..806b827 100644
--- a/packages/contracts/src/version.ts
+++ b/packages/contracts/src/version.ts
@@ -1 +1 @@
-export const version = "0.1.6";
+export const version = "0.1.7";
diff --git a/packages/server/package.json b/packages/server/package.json
index af02a7d..b919084 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nodepass/server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "scripts": {
@@ -17,7 +17,7 @@
     "@feathersjs/koa": "^5.0.35",
     "@feathersjs/schema": "^5.0.35",
     "@koa/router": "^15.7.0",
-    "@nodepass/contracts": "0.1.6",
+    "@nodepass/contracts": "0.1.7",
     "@simplewebauthn/server": "^13.2.0",
     "@zxcvbn-ts/core": "^3.0.4",
     "@zxcvbn-ts/language-common": "^3.0.4",
diff --git a/packages/web/package.json b/packages/web/package.json
index eba560f..27fc140 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nodepass/web",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "scripts": {
@@ -10,7 +10,7 @@
     "rtk:build": "rtk npm run build"
   },
   "dependencies": {
-    "@nodepass/contracts": "0.1.6",
+    "@nodepass/contracts": "0.1.7",
     "@simplewebauthn/browser": "^13.2.0",
     "@vitejs/plugin-vue": "^6.0.0",
     "@zxcvbn-ts/core": "^3.0.4",