sealkeep 0.8.1 → 0.11.0

package/web/setup.js

@@ -3,9 +3,10 @@
  *
  * Five screens, in the order the decisions depend on each other: what this
  * does, how archives are stored, where they go, the key, and what is now
- * running. The vault is created on screen 4 and everything else is applied
- * after it, which is what makes "stop once your key exists and you still have
- * a working local-only vault" true rather than aspirational.
+ * running. New accounts create a vault on screen 4. A returning account with
+ * preserved memory first adopts its existing vault through device-to-device
+ * enrollment, so screen 4 confirms that identity instead of creating a
+ * throwaway vault with a different key.
  *
  * The phrase lives in exactly one variable in this file and is written to at
  * most one of two lists — the ceremony's, or the fold a password vault offers
@@ -32,9 +33,13 @@ const draft = {
   /** The top-level answer. The provider is only a detail underneath one of them. */
   intent: "local",
   storage: {},
-  /** Held until the vault exists: linking needs somewhere to keep the token. */
-  enrollEmail: "",
-  enrollCode: "",
+  /** Account linking can use bootstrap keystore refs before a vault exists. */
+  account: null,
+  /** Public hosted approval state only; secrets remain in native storage. */
+  authorization: null,
+  needsEnrollment: false,
+  deviceLabel: "",
+  enrollment: null,
   vault: null,
   /** Which ceremony made the vault, so re-entering screen 4 redraws the right half. */
   keyBranch: null,
@@ -43,9 +48,16 @@ const draft = {
 
 /** The one secret this page ever holds. Cleared by `forgetPhrase()`. */
 let phraseWords = null;
+let recoveryCodes = [];
+let recoveryFileCodes = [];
 let verifyPositions = [];
 let confirmed = false;
 let step = 1;
+let enrollmentPollTimer = null;
+let enrollmentReceiptTimer = null;
+let accountAuthorizationPollTimer = null;
+let browserHandoffPollTimer = null;
+let machineReady = false;
 
 /* ── Chrome ──────────────────────────────────────────────────────────── */
 
@@ -85,24 +97,58 @@ function show(next) {
   if (heading && typeof heading.focus === "function") { heading.tabIndex = -1; heading.focus(); }
 }
 
-/**
- * Asks this browser for the token, rather than telling it to go and be a
- * different browser.
- *
- * `sealkeep ui` signs in whichever browser it opened, by way of a fragment
- * that lands in that browser's sessionStorage. Anyone who then types the
- * address into a second one — a perfectly reasonable thing to do with a URL
- * that is now stable and memorable — arrives with nothing, and the old advice
- * was a terminal command that would have opened the first browser again.
- */
+/** Shown when this tab has no valid bearer from a secure launch ticket. */
 function showGate(message) {
   for (let index = 1; index <= TOTAL_STEPS; index += 1) $(`screen-${index}`).hidden = true;
   $("screen-unavailable").hidden = true;
   $("screen-gate").hidden = false;
   setError("gate-error", message ?? "");
   for (const button of stepButtons()) { button.disabled = true; button.classList.add("locked"); }
-  setStatus("Not signed in", "warn");
-  $("gate-token").focus();
+  setStatus("Not connected", "warn");
+  const retry = $("gate-retry");
+  retry.textContent = api.hasToken() ? "Check connection" : "Request access in this browser";
+  retry.focus();
+}
+
+function scheduleBrowserHandoffPoll(requestId) {
+  if (browserHandoffPollTimer) clearTimeout(browserHandoffPollTimer);
+  browserHandoffPollTimer = setTimeout(() => void pollBrowserHandoff(requestId), 1500);
+  browserHandoffPollTimer?.unref?.();
+}
+
+async function pollBrowserHandoff(requestId) {
+  try {
+    const result = await api.checkBrowserHandoff(requestId);
+    if (result.status === "approved" && typeof result.ticket === "string") {
+      api.clearBrowserHandoff();
+      // The setup transport owns ticket redemption and keeps the bearer in
+      // this tab's sessionStorage only.
+      const hash = `#ticket=${encodeURIComponent(result.ticket)}`;
+      location.hash = hash.slice(0);
+      await boot();
+      return;
+    }
+    if (result.status === "expired") {
+      $("gate-retry").textContent = "Request access in this browser";
+      setError("gate-error", "That browser sign-in request expired. Request a new one.");
+      return;
+    }
+    setError("gate-error", "Approve this browser in the Sealkeep tab already signed in on this machine. This request expires shortly.");
+    scheduleBrowserHandoffPoll(requestId);
+  } catch (error) {
+    setError("gate-error", error.message);
+    scheduleBrowserHandoffPoll(requestId);
+  }
+}
+
+async function requestBrowserHandoff() {
+  try {
+    const requestId = await api.beginBrowserHandoff();
+    $("gate-retry").textContent = "Waiting for approval…";
+    await pollBrowserHandoff(requestId);
+  } catch (error) {
+    setError("gate-error", error.message);
+  }
 }
 
 function showUnavailable(message) {
@@ -129,6 +175,182 @@ function setError(id, message) {
   node.hidden = !message;
 }
 
+function syncManagedContinue() {
+  const waitingForAccount = draft.intent === "managed" && !draft.account;
+  const waitingForApproval = draft.intent === "managed" && draft.needsEnrollment && draft.enrollment?.state !== "complete";
+  $("storage-continue").disabled = !machineReady || waitingForAccount || waitingForApproval;
+}
+
+$("show-pairing-form").onclick = () => {
+  $("account-pairing-form").hidden = false;
+  $("show-pairing-form").hidden = true;
+  $("f-enroll-email").focus();
+};
+
+/* ── Hosted account approval ─────────────────────────────────────────── */
+
+/**
+ * The page is only a display and polling surface for this protocol. The
+ * verifier, account token, device credential, private enrollment key and
+ * request capability stay in the local secret backend; only this opaque
+ * request handle and hosted URL are retained in browser memory.
+ */
+function scheduleAccountAuthorizationPoll(requestId, delay = 3000) {
+  if (accountAuthorizationPollTimer !== null) clearTimeout(accountAuthorizationPollTimer);
+  const wait = Math.min(10_000, Math.max(1_000, Number(delay) || 3000));
+  accountAuthorizationPollTimer = setTimeout(() => void pollAccountAuthorization(requestId), wait);
+}
+
+function clearAccountAuthorizationPoll() {
+  if (accountAuthorizationPollTimer !== null) clearTimeout(accountAuthorizationPollTimer);
+  accountAuthorizationPollTimer = null;
+}
+
+function accountApprovalLink(url) {
+  const link = $("account-approval-link");
+  link.href = url;
+  link.hidden = false;
+}
+
+function showAuthorizedAccount(result) {
+  draft.account = result.account;
+  draft.needsEnrollment = result.memory?.preserved === true && !draft.createdAlready;
+  $("account-start-actions").hidden = true;
+  $("pairing-fallback").hidden = true;
+  $("f-device-label").disabled = true;
+  $("account-authorization-error").hidden = true;
+
+  if (!draft.needsEnrollment) {
+    $("account-authorization-status").textContent = "This machine is linked. Setup can create its first vault next.";
+    setStatus("Account linked", "ok");
+    syncManagedContinue();
+    return;
+  }
+
+  $("account-authorization-status").textContent = "This account has preserved memories. Waiting for the device that already opens them…";
+  setStatus("Account linked", "ok");
+  syncManagedContinue();
+  if (result.enrollment?.requestId) {
+    resumePreservedMemoryEnrollment(result.enrollment);
+  } else {
+    // Current hosted services can create the enrollment request from the same
+    // public key. This branch supports an older service without making login
+    // fail; the existing local enrollment lane still keeps key custody here.
+    void beginPreservedMemoryEnrollment();
+  }
+}
+
+async function pollAccountAuthorization(requestId) {
+  if (draft.authorization?.requestId !== requestId || draft.authorization.state !== "waiting_for_approval") return;
+  try {
+    const result = await api.completeDeviceAuthorization(requestId);
+    if (draft.authorization?.requestId !== requestId) return;
+    if (result.status === "waiting_for_approval") {
+      if (result.expiresAt) draft.authorization.expiresAt = result.expiresAt;
+      $("account-authorization-status").textContent = "Finish signing in and approve this machine in the Sealkeep page we opened…";
+      setError("account-authorization-error", "");
+      scheduleAccountAuthorizationPoll(requestId, result.retryAfterMs);
+      return;
+    }
+    clearAccountAuthorizationPoll();
+    if (result.status === "complete" && result.account && result.memory) {
+      draft.authorization = { ...draft.authorization, state: "complete" };
+      showAuthorizedAccount(result);
+      return;
+    }
+    if (result.status === "denied") {
+      draft.authorization = { ...draft.authorization, state: "denied" };
+      $("account-authorization-status").textContent = "";
+      $("account-approval-link").hidden = true;
+      setError("account-authorization-error", "This account did not approve this machine. You can start another approval or use the manual fallback.");
+      $("account-authorize").disabled = false;
+      $("account-authorize").textContent = "Start another approval";
+      return;
+    }
+    if (result.status === "expired") {
+      draft.authorization = { ...draft.authorization, state: "expired" };
+      $("account-authorization-status").textContent = "";
+      $("account-approval-link").hidden = true;
+      setError("account-authorization-error", "This account approval expired. Start another approval; nothing was linked.");
+      $("account-authorize").disabled = false;
+      $("account-authorize").textContent = "Start another approval";
+      return;
+    }
+    throw new Error("Sealkeep returned an unfamiliar account approval state. Start another approval.");
+  } catch (error) {
+    if (draft.authorization?.requestId !== requestId || draft.authorization.state !== "waiting_for_approval") return;
+    const transient = !error.status || error.status >= 500;
+    setError("account-authorization-error", transient
+      ? "This machine could not check approval just now. It will keep trying."
+      : error.message);
+    if (transient) scheduleAccountAuthorizationPoll(requestId);
+    else {
+      clearAccountAuthorizationPoll();
+      $("account-authorize").disabled = false;
+      $("account-authorize").textContent = "Start another approval";
+    }
+  }
+}
+
+$("account-authorize").onclick = async () => {
+  const label = $("f-device-label").value.trim();
+  if (!label) {
+    setError("account-authorization-error", "Name this machine before asking the account to approve it.");
+    $("f-device-label").focus();
+    return;
+  }
+
+  clearAccountAuthorizationPoll();
+  const button = $("account-authorize");
+  button.disabled = true;
+  $("account-approval-link").hidden = true;
+  setError("account-authorization-error", "");
+  $("account-authorization-status").textContent = "Opening the secure Sealkeep approval page…";
+  setStatus("Waiting for approval", "busy");
+  // Open a harmless blank tab while the click gesture is still active. Waiting
+  // for the local request first makes Safari and stricter popup blockers turn
+  // this into a two-click flow. `opener` is removed before it ever navigates
+  // to the hosted origin, and the tab is closed again if setup cannot start.
+  let approvalWindow = null;
+  try {
+    approvalWindow = window.open("about:blank", "_blank");
+    if (approvalWindow) approvalWindow.opener = null;
+  } catch { /* The rendered link below is the blocker-safe fallback. */ }
+  try {
+    const started = await api.startDeviceAuthorization(label);
+    if (!/^[A-Za-z0-9._~-]{1,200}$/.test(String(started.requestId ?? "")) || typeof started.approvalUrl !== "string") {
+      throw new Error("Sealkeep did not return a valid account approval request. Nothing was linked.");
+    }
+    // The local API validates the hosted URL before it reaches this page. The
+    // extra protocol check prevents this renderer ever becoming an open link
+    // launcher if a future local endpoint regresses.
+    if (!started.approvalUrl.startsWith("https://")) {
+      throw new Error("Sealkeep did not return a secure account approval page. Nothing was linked.");
+    }
+    draft.deviceLabel = label;
+    draft.authorization = {
+      requestId: started.requestId,
+      approvalUrl: started.approvalUrl,
+      expiresAt: started.expiresAt,
+      state: "waiting_for_approval"
+    };
+    accountApprovalLink(started.approvalUrl);
+    $("account-authorization-status").textContent = "Finish signing in and approve this machine in the Sealkeep page we opened…";
+    button.textContent = "Waiting for approval";
+    if (approvalWindow && !approvalWindow.closed) approvalWindow.location.replace(started.approvalUrl);
+    // If a browser blocked the tab, the visible link remains a safe recovery
+    // without exposing a code or any local credential.
+    scheduleAccountAuthorizationPoll(started.requestId, started.pollAfterMs);
+  } catch (error) {
+    try { approvalWindow?.close(); } catch { /* already blocked or closed */ }
+    $("account-authorization-status").textContent = "";
+    setError("account-authorization-error", error.message);
+    button.disabled = false;
+    button.textContent = "Continue securely in your browser";
+    setStatus("Account linking failed", "warn");
+  }
+};
+
 /* ── 2 · How archives are stored ─────────────────────────────────────── */
 
 // The radios are static markup — two fixed answers need no renderer — so the
@@ -204,6 +426,7 @@ function renderProviderFields() {
   // The account panel is the managed equivalent of the credentials form — the
   // one thing that choice does need from the person.
   $("account-panel").hidden = draft.intent !== "managed";
+  syncManagedContinue();
   setError("storage-error", "");
   setError("e-bucket", "");
   setError("e-prefix", "");
@@ -262,25 +485,251 @@ function collectStorage() {
  * lets a returning user finish here instead of in a terminal without weakening
  * the rule that no endpoint accepts a phrase.
  */
-$("enroll-go").onclick = () => {
+const comparisonCode = (value) => String(value ?? "").replace(/\D/g, "").replace(/^(\d{3})(\d{3})$/, "$1 $2");
+
+function scheduleEnrollmentPoll(requestId, delay = 3000) {
+  if (enrollmentPollTimer !== null) clearTimeout(enrollmentPollTimer);
+  const wait = Math.min(10_000, Math.max(1_000, Number(delay) || 3000));
+  enrollmentPollTimer = setTimeout(() => void pollDeviceEnrollment(requestId), wait);
+}
+
+function scheduleReceiptRetry(requestId) {
+  if (enrollmentReceiptTimer !== null) clearTimeout(enrollmentReceiptTimer);
+  enrollmentReceiptTimer = setTimeout(async () => {
+    if (draft.enrollment?.requestId !== requestId || draft.enrollment?.cloudReceiptCleared !== false) return;
+    try {
+      const result = await api.completeDeviceEnrollment(requestId);
+      if (result.status === "complete" && result.cloudReceiptPending !== true) {
+        draft.enrollment.cloudReceiptCleared = true;
+        return;
+      }
+    } catch { /* Adoption is complete; acknowledgement remains best-effort. */ }
+    scheduleReceiptRetry(requestId);
+  }, 5000);
+}
+
+function finishDeviceEnrollment(result) {
+  draft.createdAlready = true;
+  draft.keyBranch = "enrolled";
+  draft.vault = { vaultId: result.vaultId };
+  draft.enrollment = {
+    ...draft.enrollment,
+    state: "complete",
+    vaultId: result.vaultId,
+    cloudReceiptCleared: result.cloudReceiptPending !== true
+  };
+  $("device-enrollment-status").textContent = result.cloudReceiptPending === true
+    ? "Approved. Your existing vault is ready here; Sealkeep is finishing the hosted receipt in the background."
+    : "Approved. Your existing vault and preserved memories are ready on this machine.";
+  setError("device-enrollment-error", "");
+  $("device-enrollment-retry").hidden = true;
+  $("storage-continue").textContent = "Continue with your existing vault";
+  syncManagedContinue();
+  setStatus("Existing vault restored", "ok");
+  if (result.cloudReceiptPending === true) scheduleReceiptRetry(result.requestId);
+}
+
+const RECOVERY_CODE_PATTERN = /\bSK-(?:[0-9A-HJKMNP-TV-Z]{4}-){6}[0-9A-HJKMNP-TV-Z]{2}\b/gi;
+
+function recoveryCodesFromFile(text) {
+  return [...new Set(String(text ?? "").match(RECOVERY_CODE_PATTERN) ?? [])].map((code) => code.toUpperCase());
+}
+
+function clearRecoveryInputs() {
+  $("f-recovery-code").value = "";
+  $("f-recovery-code-file").value = "";
+  recoveryFileCodes = [];
+}
+
+async function recoverWithBackupCode() {
+  const pasted = $("f-recovery-code").value.trim();
+  const candidates = pasted ? [pasted] : [...recoveryFileCodes];
+  if (!candidates.length) { setError("recovery-code-error", "Choose a saved Recovery Kit or paste one backup code."); return; }
+  const button = $("recovery-code-go");
+  button.disabled = true;
+  setError("recovery-code-error", "");
+  $("recovery-code-status").textContent = candidates.length > 1 ? "Securely checking the saved one-time codes…" : "Securely checking this one-time code…";
+  setStatus("Recovering existing vault", "busy");
+  let lastError = null;
+  try {
+    for (const candidate of candidates) {
+      try {
+        const result = await api.recoverWithBackupCode(candidate);
+        finishDeviceEnrollment({ ...result, cloudReceiptPending: false });
+        $("recovery-code-status").textContent = `Recovered. ${result.remaining} unused backup code${result.remaining === 1 ? " remains" : "s remain"}.`;
+        return;
+      } catch (error) {
+        lastError = error;
+        if (error.status !== 400 && error.status !== 409 && error.code !== "recovery_phrase_mismatch" && error.code !== "queue_lease_expired") throw error;
+      }
+    }
+    throw lastError ?? new Error("No unused backup code was accepted.");
+  } catch (error) {
+    setError("recovery-code-error", error.message);
+    $("recovery-code-status").textContent = "This recovery code was not used.";
+    setStatus("Recovery code was not used", "warn");
+  } finally {
+    clearRecoveryInputs();
+    button.disabled = false;
+  }
+}
+
+$("recovery-code-go").onclick = () => void recoverWithBackupCode();
+$("f-recovery-code-file").onchange = async () => {
+  recoveryFileCodes = [];
+  $("f-recovery-code").value = "";
+  const file = $("f-recovery-code-file").files?.[0];
+  if (!file) return;
+  let text = "";
+  try {
+    text = await file.text();
+    recoveryFileCodes = recoveryCodesFromFile(text);
+    $("recovery-code-status").textContent = recoveryFileCodes.length
+      ? `Found ${recoveryFileCodes.length} formatted backup code${recoveryFileCodes.length === 1 ? "" : "s"}. Recover this machine to try them.`
+      : "No formatted backup codes were found. Paste one code below instead.";
+    setError("recovery-code-error", "");
+  } catch {
+    setError("recovery-code-error", "Sealkeep could not read that local text file. Paste one backup code below instead.");
+  } finally {
+    text = "";
+    $("f-recovery-code-file").value = "";
+  }
+};
+
+async function pollDeviceEnrollment(requestId) {
+  if (draft.enrollment?.requestId !== requestId || draft.enrollment?.state === "complete") return;
+  try {
+    const result = await api.completeDeviceEnrollment(requestId);
+    if (result.status === "waiting_for_approval") {
+      draft.enrollment.state = "waiting_for_approval";
+      if (result.expiresAt) draft.enrollment.expiresAt = result.expiresAt;
+      $("device-enrollment-status").textContent = "Waiting for approval on a device that already opens this vault…";
+      setError("device-enrollment-error", "");
+      scheduleEnrollmentPoll(requestId, result.retryAfterMs);
+      return;
+    }
+    if (result.status === "expired") {
+      $("device-enrollment-status").textContent = "";
+      setError("device-enrollment-error", "This enrollment request expired before it was approved. Start a new request; no vault was created.");
+      $("device-enrollment-retry").hidden = false;
+      return;
+    }
+    if (result.status === "complete" && result.vaultId) {
+      finishDeviceEnrollment(result);
+      return;
+    }
+    setError("device-enrollment-error", "Sealkeep returned an unfamiliar enrollment state. Start a new request rather than creating another vault.");
+    $("device-enrollment-retry").hidden = false;
+  } catch (error) {
+    if (draft.enrollment?.requestId !== requestId) return;
+    const restartable = error.status === 404 || error.status === 410;
+    const transient = !error.status || error.status >= 500;
+    setError("device-enrollment-error", transient
+      ? "This machine could not check approval just now. It will keep trying."
+      : error.message);
+    if (transient) scheduleEnrollmentPoll(requestId);
+    else $("device-enrollment-retry").hidden = !restartable;
+  }
+}
+
+async function beginPreservedMemoryEnrollment() {
+  const panel = $("device-enrollment");
+  const retry = $("device-enrollment-retry");
+  panel.hidden = false;
+  retry.hidden = true;
+  $("device-enrollment-comparison").hidden = true;
+  $("device-enrollment-status").textContent = "Creating a private request for this machine…";
+  setError("device-enrollment-error", "");
+  draft.enrollment = { state: "starting" };
+  syncManagedContinue();
+  try {
+    const started = await api.startDeviceEnrollment(draft.deviceLabel);
+    resumePreservedMemoryEnrollment(started);
+  } catch (error) {
+    draft.enrollment = { state: "error" };
+    $("device-enrollment-status").textContent = "";
+    setError("device-enrollment-error", error.message);
+    retry.hidden = false;
+  }
+}
+
+/**
+ * Uses an enrollment that the hosted authorization service already made from
+ * the exact public key the account holder reviewed. There is no second
+ * enrollment request in this path, so the approval page and the old machine
+ * refer to one target identity.
+ */
+function resumePreservedMemoryEnrollment(started) {
+  if (!Number.isSafeInteger(started?.requestId) || !/^\d{6}$/.test(String(started.verificationCode ?? ""))) {
+    throw new Error("Sealkeep did not return a valid preserved-memory request. No vault was created; start another approval.");
+  }
+  const panel = $("device-enrollment");
+  panel.hidden = false;
+  $("device-enrollment-retry").hidden = true;
+  draft.enrollment = { ...started, state: "waiting_for_approval" };
+  $("device-enrollment-code").textContent = comparisonCode(started.verificationCode);
+  $("device-enrollment-comparison").hidden = false;
+  $("device-enrollment-expiry").textContent = started.expiresAt
+    ? `This request expires at ${new Date(started.expiresAt).toLocaleTimeString()}.`
+    : "This request expires shortly.";
+  $("device-enrollment-status").textContent = "Waiting for approval on a device that already opens this vault…";
+  setError("device-enrollment-error", "");
+  scheduleEnrollmentPoll(started.requestId);
+}
+
+$("device-enrollment-retry").onclick = () => void beginPreservedMemoryEnrollment();
+
+$("enroll-go").onclick = async () => {
   const email = $("f-enroll-email").value.trim();
   const code = $("f-enroll-code").value.trim();
+  const label = $("f-device-label").value.trim();
   // Both, because the exchange needs the pair — the panel hands them over
   // together, in the command it prints beside the code.
-  const missing = !email ? "Enter the email your account uses." : !code ? "Press “Show a pairing code” on your account page, then paste it here." : "";
+  const missing = !email
+    ? "Enter the email your account uses."
+    : !code
+      ? "Press “Show a pairing code” on your account page, then paste it here."
+      : !label
+        ? "Name this machine so you can recognise it on the approving device."
+        : "";
   setError("e-enroll-code", missing);
   if (missing) return;
 
-  // Held, not sent. Linking stores a token, and there is nowhere to keep it
-  // until the vault exists — which happens at step 4, after this. The code is
-  // single use, so spending it here would burn it on a machine that could not
-  // have kept the result.
-  draft.enrollEmail = email;
-  draft.enrollCode = code;
-  // Not "Saved" — nothing has been checked yet. The pairing code is single-use
-  // and is only sent when the vault is created, so a wrong or expired one shows
-  // up on the last screen (where the account row now reports it), not here.
-  $("enroll-result").textContent = "Got it — this machine links to your account when the vault is created at the end. If the code is wrong, you'll see it on the last screen.";
+  const button = $("enroll-go");
+  button.disabled = true;
+  $("enroll-result").textContent = "Linking this machine now…";
+  setStatus("Linking this machine", "busy");
+  let enrolled;
+  try {
+    // Immediate by design. Bootstrap keystore references protect the account
+    // token and machine proof even though a fresh device has no config.json yet.
+    enrolled = await api.enrollDevice(email, code);
+  } catch (error) {
+    setError("e-enroll-code", error.message);
+    $("enroll-result").textContent = "";
+    button.disabled = false;
+    setStatus("Account linking failed", "warn");
+    return;
+  }
+
+  // A pairing code is single use. Once exchanged it has no reason to remain in
+  // a browser field, draft object, URL or later request.
+  $("f-enroll-code").value = "";
+  draft.account = enrolled.account ?? { plan: "unknown", email };
+  draft.deviceLabel = label;
+  const hasPreservedMemories = enrolled.memory?.preserved === true;
+  draft.needsEnrollment = hasPreservedMemories && !draft.createdAlready;
+  for (const id of ["f-enroll-email", "f-enroll-code", "f-device-label"]) $(id).disabled = true;
+  $("account-start-actions").hidden = true;
+  button.textContent = "Account linked";
+  $("enroll-result").textContent = draft.needsEnrollment
+    ? "Account linked. Preserved memories were found, so this machine needs approval from one that already opens them."
+    : hasPreservedMemories
+      ? "Account linked. This machine already has a vault, so its existing local identity remains in place."
+      : "Account linked. This account has no preserved memories to transfer, so setup will create its first vault next.";
+  setStatus("Account linked", "ok");
+  syncManagedContinue();
+  if (draft.needsEnrollment) await beginPreservedMemoryEnrollment();
 };
 
 /**
@@ -323,8 +772,15 @@ $("storage-test").onclick = async () => {
  */
 function armKeyScreen() {
   const made = Boolean(phraseWords);
-  const branch = draft.createdAlready ? "existing" : made ? draft.keyBranch : keyMode(draft.intent);
+  const branch = draft.keyBranch === "enrolled"
+    ? "enrolled"
+    : draft.createdAlready
+      ? "existing"
+      : made
+        ? draft.keyBranch
+        : keyMode(draft.intent);
   $("phrase-existing").hidden = branch !== "existing";
+  $("phrase-enrolled").hidden = branch !== "enrolled";
   $("phrase-before").hidden = branch !== "phrase" || made;
   $("phrase-after").hidden = branch !== "phrase" || !made;
   $("password-before").hidden = branch !== "password" || made;
@@ -351,6 +807,8 @@ function wordList(target, words) {
 }
 
 function renderPhrase(words) {
+  const recoveryBox = $("recovery-codes");
+  $("phrase-words").after(recoveryBox);
   wordList($("phrase-words"), words);
 
   verifyPositions = verificationPositions(words.length);
@@ -396,6 +854,8 @@ function renderPhrase(words) {
  * browser prompt insisting otherwise would be a lie.
  */
 function renderFold(words) {
+  const recoveryBox = $("recovery-codes");
+  $("password-after").insertBefore(recoveryBox, $("password-after").querySelector(".wizfoot"));
   wordList($("fold-phrase-words"), words);
   $("fold-note").textContent = `These ${words.length} words also open the vault — write them down or skip. Skipping is fine: your password already opens it on this machine. The words are the only key that works anywhere else, and this is the only time they are shown.`;
   armKeyScreen();
@@ -421,14 +881,44 @@ function gatePhrase() {
 /** After this returns, the phrase does not exist anywhere in this page. */
 function forgetPhrase() {
   phraseWords = null;
+  recoveryCodes = [];
   verifyPositions = [];
   $("phrase-words").replaceChildren();
   $("fold-phrase-words").replaceChildren();
+  $("recovery-code-list").replaceChildren();
+  $("recovery-codes").hidden = true;
   $("fold-note").textContent = "";
   $("verify-fields").replaceChildren();
   disarmUnloadGuard();
 }
 
+function renderRecoveryCodes(codes) {
+  recoveryCodes = Array.isArray(codes) ? codes.filter((code) => typeof code === "string" && code.startsWith("SK-")) : [];
+  const box = $("recovery-codes");
+  box.hidden = recoveryCodes.length === 0;
+  const list = $("recovery-code-list");
+  list.replaceChildren(...recoveryCodes.map((code, index) => {
+    const item = document.createElement("li");
+    item.textContent = `${index + 1}. ${code}`;
+    return item;
+  }));
+}
+
+$("copy-recovery-codes").onclick = async () => {
+  await navigator.clipboard.writeText(recoveryCodes.join("\n"));
+  $("recovery-codes-note").textContent = "Copied. Paste them into an offline password manager or print them, then clear the clipboard.";
+};
+
+$("download-recovery-codes").onclick = () => {
+  const body = `SEALKEEP RECOVERY KIT\n\nOne-time backup codes\n\n${recoveryCodes.map((code, index) => `${index + 1}. ${code}`).join("\n")}\n\nSign in with Google on a fresh machine, then enter one unused code. Each code works once.\n`;
+  const url = URL.createObjectURL(new Blob([body], { type: "text/plain" }));
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = "sealkeep-recovery-kit.txt";
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+};
+
 /* ── Committing ──────────────────────────────────────────────────────── */
 
 async function createVault({ password } = {}) {
@@ -459,6 +949,7 @@ async function createVault({ password } = {}) {
     draft.vault = { dataDir: created.dataDir, vaultId: created.vaultId };
     draft.keyBranch = password === undefined ? "phrase" : "password";
     phraseWords = words;
+    renderRecoveryCodes(created.recoveryCodes);
     if (draft.keyBranch === "phrase") {
       renderPhrase(words);
       setStatus("Vault created — write the phrase down", "ok");
@@ -494,19 +985,15 @@ async function commitRest() {
     storageMode: draft.createdAlready ? null : draft.storageMode,
     password: null,
     storage: null,
-    service: null
+    service: null,
+    mcp: null,
+    enrolled: draft.keyBranch === "enrolled"
   };
 
-  // Enrolment first, because it is what tells this machine it has managed
-  // storage at all: the account's own settings arrive with it.
-  if (draft.enrollCode) {
-    try {
-      const enrolled = await api.enrollDevice(draft.enrollEmail, draft.enrollCode);
-      result.account = { plan: enrolled.account?.plan ?? "unknown", deviceId: enrolled.deviceId };
-    } catch (error) {
-      result.account = { error: error.message };
-    }
-  }
+  // Account linking already happened on the storage screen. Delaying it until
+  // here would make it impossible to discover and adopt an existing vault
+  // before the new-user ceremony created a conflicting one.
+  if (draft.account) result.account = { plan: draft.account.plan ?? "unknown" };
 
   if (needsBucket(draft.providerId)) {
     const payload = buildStoragePayload(draft.providerId, draft.storage);
@@ -531,8 +1018,17 @@ async function commitRest() {
   }
 
   try {
-    const service = await api.startService();
-    result.service = { running: service.running !== false, detail: service.detail };
+    const response = await api.startService();
+    const service = response.service ?? {};
+    result.service = {
+      installed: service.installed === true,
+      running: service.running === true,
+      waitingForUnlock: service.installed === true && response.phraseAvailable === false,
+      phraseAvailable: response.phraseAvailable,
+      detail: service.note ?? (service.alreadyInstalled ? "Already running at login." : undefined)
+    };
+    result.mcp = response.mcp ?? null;
+    result.hooks = response.hooks ?? null;
   } catch (error) {
     result.service = { running: false, error: error.message };
   }
@@ -541,6 +1037,17 @@ async function commitRest() {
 
 function renderDone(result) {
   const rows = summariseDone(result);
+  if (result.enrolled) {
+    const vault = rows.find((row) => row.label === "Vault");
+    if (vault) {
+      vault.badge = { text: "restored", kind: "verified" };
+      vault.detail = "Your existing vault identity was encrypted for this machine by an approved device and opened locally. Setup did not create a replacement vault.";
+    }
+    const account = rows.find((row) => row.label === "Sealkeep account");
+    if (account) account.detail = `This machine is linked to your account${result.account?.plan && result.account.plan !== "unknown" ? ` (${result.account.plan})` : ""}. Managed storage is on, and the restored vault keeps the storage mode you originally chose.`;
+    const storage = rows.find((row) => row.label === "Storage");
+    if (storage) storage.detail = "Your account's storage receives archives from this restored vault. Its existing sealed-or-plain setting was preserved rather than guessed or changed by setup.";
+  }
   const headline = doneHeadline(rows);
   $("done-headline").textContent = headline;
   const list = $("done-list");
@@ -553,19 +1060,27 @@ function renderDone(result) {
     list.append(line);
   }
   const offMachine = (result.storage && !result.storage.error) || (result.account && !result.account.error);
-  $("next-detail").textContent = offMachine
-    ? "Nothing else is needed. The next time one of your agents finishes a session, the transcript is queued here, archived, and copied to your storage. It shows up on the dashboard within a few minutes."
-    : "Nothing else is needed. The next time one of your agents finishes a session, the transcript is queued here and archived onto this disk. It shows up on the dashboard within a few minutes.";
+  const hookAttention = Array.isArray(result.hooks)
+    && result.hooks.some((hook) => hook.installed && hook.active === false);
+  $("next-detail").textContent = result.service?.waitingForUnlock
+    ? "The background service and supported agent connections are installed, but this machine is still locked. Open the dashboard, choose Settings › Unlocking, and store the recovery phrase locally. Queued work then resumes automatically."
+    : hookAttention
+    ? `The background service is already preserving supported sessions automatically${offMachine ? " and copying them to your storage" : " on this disk"}. Codex lifecycle actions remain off until you review or re-enable them in Codex /hooks; Sealkeep did not change that choice.`
+    : offMachine
+      ? "Nothing else is needed. Sealkeep has connected the supported coding agents on this machine. Their finished sessions are preserved and copied to your storage automatically, and their next sessions can search that memory locally."
+      : "Nothing else is needed. Sealkeep has connected the supported coding agents on this machine. Their finished sessions are preserved on this disk automatically, and their next sessions can search that memory locally.";
   // A password vault may have skipped the words, and that was allowed out
   // loud — so the advice bends rather than scolding.
-  $("today-key").textContent = result.password
-    ? "If you kept the recovery phrase, put it somewhere you will still have it in a year — a drawer beats a laptop."
-    : "Check that your recovery phrase is somewhere you will still have it in a year — a drawer beats a laptop.";
+  $("today-key").textContent = result.enrolled
+    ? "Keep an already-approved device available as a second way to bring this vault onto a future machine."
+    : result.password
+      ? "If you kept the recovery phrase, put it somewhere you will still have it in a year — a drawer beats a laptop."
+      : "Check that your recovery phrase is somewhere you will still have it in a year — a drawer beats a laptop.";
   return headline;
 }
 
 async function finish() {
-  for (const id of ["finish", "finish-existing", "finish-password"]) {
+  for (const id of ["finish", "finish-existing", "finish-password", "finish-enrolled"]) {
     const button = $(id);
     if (button) button.disabled = true;
   }
@@ -582,6 +1097,13 @@ async function finish() {
 /* ── Navigation ──────────────────────────────────────────────────────── */
 
 function go(next) {
+  // Setup state decides whether this is a new vault or an existing one. Until
+  // that answer arrives, advancing could offer a second key ceremony for a
+  // vault that already exists. Keep the page readable, but fail closed.
+  if (!machineReady) {
+    setStatus("Still checking this machine", "busy");
+    return;
+  }
   // Leaving the storage step: an unanswered sub-choice is its own error, and a
   // named provider still has to have its fields filled in.
   if (next === 4 && step === 3) {
@@ -590,6 +1112,14 @@ function go(next) {
       return;
     }
     if (needsBucket(draft.providerId) && !collectStorage()) return;
+    if (draft.intent === "managed" && !draft.account) {
+      setError("storage-error", "Link this machine to your Sealkeep account before continuing.");
+      return;
+    }
+    if (draft.intent === "managed" && draft.needsEnrollment && draft.enrollment?.state !== "complete") {
+      setError("storage-error", "Approve this machine from a device that already opens your vault. Setup will continue after the existing vault arrives.");
+      return;
+    }
   }
   if (next === 4) armKeyScreen();
   show(next);
@@ -607,6 +1137,7 @@ $("f-understood").onchange = gatePhrase;
 $("confirm-form").onsubmit = (event) => { event.preventDefault(); if (confirmed) void finish(); };
 $("finish-existing").onclick = () => void finish();
 $("finish-password").onclick = () => void finish();
+$("finish-enrolled").onclick = () => void finish();
 
 // The password is judged as it is typed — by length, the one property the
 // hint admits to caring about — and judged again on submit, so the create
@@ -639,10 +1170,19 @@ $("print-phrase").onclick = () => { if (typeof print === "function") print(); };
 /* ── Boot ────────────────────────────────────────────────────────────── */
 
 async function boot() {
-  api.readTokenFromLocation();
-  // Nothing works without it, so ask for it up front rather than letting every
-  // panel fail separately and leaving the reader to assemble the reason.
-  if (!api.hasToken()) { showGate(); return; }
+  machineReady = false;
+  renderProviders();
+  renderOwnProviders();
+  renderProviderFields();
+  show(1);
+  setStatus("Checking this machine", "busy");
+  // Redeem a single-use launch ticket before any protected setup request. A
+  // returning tab reuses its session-only bearer; a direct visit from another
+  // browser receives its own short-lived ticket from the local service.
+  if (!await api.readTokenFromLocation()) {
+    showGate("This browser is not signed in yet. Request access here; no Sealkeep command or token copy is needed.");
+    return;
+  }
   try {
     const state = await api.fetchState();
     draft.createdAlready = Boolean(state.vault?.created);
@@ -665,13 +1205,19 @@ async function boot() {
       draft.storage.prefix = state.storage.prefix ?? "sealkeep";
     }
   } catch (error) {
+    if (error.status === 401 || error.status === 403) {
+      showGate(error.message);
+      return;
+    }
     if (error.missing) {
       showUnavailable(`Sealkeep answered on this machine, but it has no ${error.route} endpoint. This build predates the setup wizard.`);
       return;
     }
-    setStatus(error.message, "warn");
+    showUnavailable(error.message);
+    return;
   }
 
+  machineReady = true;
   renderProviders();
   renderOwnProviders();
   renderProviderFields();
@@ -680,25 +1226,12 @@ async function boot() {
   setStatus("Connected to this machine", "ok");
 }
 
-/**
- * A pasted token is tried before it is trusted: a wrong one that merely got
- * stored would put someone back on step 1 with every panel empty and no reason
- * given, which is the failure this screen exists to end.
- */
 $("gate-form").addEventListener("submit", async (event) => {
   event.preventDefault();
-  const value = $("gate-token").value.trim();
-  if (!value) { setError("gate-error", "Paste the token from the file named above."); return; }
-
-  api.setToken(value);
-  try {
-    await api.fetchState();
-  } catch (error) {
-    api.setToken("");
-    setError("gate-error", error.message.includes("not signed in") ? "That token was not accepted." : error.message);
+  if (!api.hasToken()) {
+    await requestBrowserHandoff();
     return;
   }
-  $("gate-token").value = "";
   await boot();
 });