sealkeep 0.5.0

package/web/setup-logic.js

@@ -0,0 +1,394 @@
+/**
+ * First-run setup — the decisions, with no DOM and no network in sight.
+ *
+ * Everything here is a pure function so the parts that matter can be tested
+ * without a browser: which key ceremony a storage choice implies, what a
+ * provider needs before it can be saved, whether a password is usable, and
+ * whether someone has actually transcribed their recovery phrase. `setup.js`
+ * renders these answers; `setup-api.js` transports them.
+ *
+ * Nothing in this file ever sees the recovery phrase except
+ * `checkPhraseAnswers`, which compares it in memory and returns booleans, and
+ * nothing here ever sees a password except `passwordProblem`, which judges it
+ * and returns a sentence.
+ */
+
+/* ── Storage ─────────────────────────────────────────────────────────── */
+
+const KEY_FIELDS = [
+  { name: "accessKeyId", label: "Access key ID", secret: false, placeholder: "AKIA…", hint: "" },
+  { name: "secretAccessKey", label: "Secret access key", secret: true, placeholder: "", hint: "" }
+];
+
+/**
+ * The providers offered, in the order they appear on the screen.
+ *
+ * "local" is first and is a real answer, not a fallback: everything except the
+ * second copy works without a bucket, and adding one later re-does nothing.
+ */
+export const PROVIDERS = [
+  {
+    id: "local",
+    label: "Keep them on this disk for now",
+    blurb: "Sealing, search and restore all work. What you do not get is a second copy — if this disk dies, the archives die with it.",
+    docs: null,
+    fields: []
+  },
+  {
+    /**
+     * Managed storage. No bucket, no IAM policy, no keys to paste — which is
+     * most of what the other four options are asking someone to do, and the
+     * reason people give up on this step.
+     *
+     * It needs an account, and that is the only place in this wizard where one
+     * is genuinely required rather than merely offered: there is a bucket to
+     * provision and a bill to attach it to. Everything else here works signed
+     * out, which is what makes asking here defensible.
+     */
+    id: "managed",
+    label: "Let Sealkeep handle it",
+    blurb: "We run the bucket. Nothing to create, nothing to paste, and the archives are still sealed on this machine before they leave — we hold bytes we cannot open.",
+    docs: null,
+    fields: []
+  },
+  {
+    id: "s3",
+    label: "Amazon S3",
+    blurb: "The bucket you already have, or a new one. Sealkeep writes only inside the prefix you name.",
+    docs: "https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html",
+    fields: [
+      { name: "region", label: "Region", placeholder: "eu-west-1", hint: "The region the bucket was created in. It is on the bucket's page in the console." },
+      ...KEY_FIELDS
+    ]
+  },
+  {
+    id: "r2",
+    label: "Cloudflare R2",
+    blurb: "No egress fees, S3-compatible. Sealkeep builds the endpoint from your account id.",
+    docs: "https://developers.cloudflare.com/r2/buckets/create-buckets/",
+    fields: [
+      { name: "accountId", label: "Account ID", placeholder: "0123456789abcdef0123456789abcdef", hint: "The 32-character id in your Cloudflare dashboard URL." },
+      ...KEY_FIELDS
+    ]
+  },
+  {
+    id: "b2",
+    label: "Backblaze B2",
+    blurb: "The cheapest per stored GB of the four. Use its S3-compatible keys, not the native ones.",
+    docs: "https://www.backblaze.com/docs/cloud-storage-create-and-manage-buckets",
+    fields: [
+      { name: "region", label: "Region", placeholder: "us-west-004", hint: "Shown as the endpoint on the bucket page: s3.<region>.backblazeb2.com." },
+      ...KEY_FIELDS
+    ]
+  },
+  {
+    id: "gcs",
+    label: "Google Cloud Storage",
+    blurb: "Uses a service account key rather than a key pair. Grant it Storage Object Admin on this bucket only.",
+    docs: "https://cloud.google.com/storage/docs/creating-buckets",
+    fields: [
+      { name: "project", label: "Project ID", placeholder: "my-gcp-project", hint: "" },
+      { name: "serviceAccountJson", label: "Service account key (JSON)", secret: true, multiline: true, placeholder: '{ "client_email": "…", "private_key": "…" }', hint: "Paste the whole file Google downloaded, braces included." }
+    ]
+  }
+];
+
+export const provider = (id) => PROVIDERS.find((entry) => entry.id === id) ?? PROVIDERS[0];
+/**
+ * The three answers to "where do archives go", before any provider is named.
+ *
+ * Presenting six options at once asked people to choose between a decision and
+ * an implementation of it in the same list: "keep it here", "let us handle it",
+ * and four bucket vendors sat side by side as if they were the same kind of
+ * choice. They are not. The decision is what happens to the bytes; the vendor
+ * is a detail that only exists under one of the answers, and only for the
+ * people who already know which one they want.
+ */
+export const INTENTS = [
+  {
+    id: "managed",
+    label: "Give me a Sealkeep account",
+    blurb: "We run the storage. Nothing to create, nothing to paste. The archives are sealed on this machine before they leave, so we hold bytes we cannot open.",
+    detail: "Needs an account — it is the only thing on this page that does."
+  },
+  {
+    id: "own",
+    label: "Use my own bucket",
+    blurb: "S3, R2, Backblaze B2 or Google Cloud Storage. Your provider, your region, your bill, and we never hold a key that opens an archive.",
+    detail: "You will need the bucket name and a key that can write to it."
+  },
+  {
+    id: "local",
+    label: "Keep them on this machine",
+    blurb: "Sealing, search and restore all work. What you do not get is a second copy — if this disk dies, the archives die with it.",
+    detail: "Add storage any day after this one. Nothing you set up today is redone."
+  }
+];
+
+/** Which top-level answer a chosen provider belongs to. */
+export function intentFor(providerId) {
+  if (providerId === "local") return "local";
+  if (providerId === "managed") return "managed";
+  return "own";
+}
+
+/** The providers offered once someone has said they want their own bucket. */
+export const ownProviders = () => PROVIDERS.filter((entry) => intentFor(entry.id) === "own");
+
+/** Whether archives get a second copy somewhere other than this disk. */
+export const isRemote = (id) => id !== "local";
+
+/**
+ * Whether this choice needs a bucket and keys typed into a form.
+ *
+ * Managed storage is remote and asks for nothing: that is the entire product
+ * difference, and conflating "has a second copy" with "make the user configure
+ * one" would show a paying customer an empty credentials form for a bucket
+ * they are paying us not to think about.
+ */
+export const needsBucket = (id) => isRemote(id) && id !== "managed";
+
+/** Bucket names are the first thing people paste wrong — usually a whole console URL. */
+const BUCKET_RE = /^[a-z0-9][a-z0-9.\-_]{1,61}[a-z0-9]$/;
+
+export const normalisePrefix = (value) => String(value ?? "").trim().replace(/^\/+|\/+$/g, "");
+
+/** Pulls the two fields the GCS signer needs out of a downloaded key file. */
+export function parseServiceAccount(raw) {
+  let parsed;
+  try { parsed = JSON.parse(String(raw)); } catch { return null; }
+  if (!parsed || typeof parsed !== "object") return null;
+  const clientEmail = parsed.client_email ?? parsed.clientEmail;
+  const privateKey = parsed.private_key ?? parsed.privateKey;
+  if (typeof clientEmail !== "string" || typeof privateKey !== "string" || !clientEmail || !privateKey) return null;
+  return { clientEmail, privateKey };
+}
+
+/**
+ * Says what is missing, by field, in words that name the fix.
+ * Never echoes a value back, so a mistyped secret cannot land in an error string.
+ */
+export function validateStorage(providerId, values) {
+  const errors = {};
+  // Local needs nothing, and managed needs nothing from the person: the bucket
+  // is ours to provision, so there is no form for them to get wrong.
+  if (!needsBucket(providerId)) return { ok: true, errors };
+
+  const bucket = String(values.bucket ?? "").trim();
+  if (!bucket) errors.bucket = "Name the bucket Sealkeep should write into.";
+  else if (!BUCKET_RE.test(bucket)) errors.bucket = "Bucket names are 3–63 characters: lowercase letters, numbers, dots, hyphens. Paste the name, not the console URL.";
+
+  if (!normalisePrefix(values.prefix)) errors.prefix = "Give the archives a folder inside the bucket. Sealkeep is a fine answer.";
+
+  for (const field of provider(providerId).fields) {
+    const value = String(values[field.name] ?? "").trim();
+    if (!value) { errors[field.name] = `${field.label} is required for ${provider(providerId).label}.`; continue; }
+    if (field.name === "serviceAccountJson" && !parseServiceAccount(value)) {
+      errors[field.name] = "That is not a service account key. Paste the whole JSON file, including the braces and the private_key line.";
+    }
+  }
+  return { ok: Object.keys(errors).length === 0, errors };
+}
+
+/**
+ * The body for POST /v1/setup/storage.
+ *
+ * Credentials travel in the body and only in the body — see the allowlist in
+ * setup-api.js, which is what actually makes that true.
+ */
+export function buildStoragePayload(providerId, values) {
+  const bucket = String(values.bucket ?? "").trim();
+  const prefix = normalisePrefix(values.prefix) || "vaultline";
+  const base = { provider: providerId, bucket, prefix };
+
+  if (providerId === "gcs") {
+    const key = parseServiceAccount(values.serviceAccountJson) ?? { clientEmail: "", privateKey: "" };
+    // No `project` key: the GCS client reads only bucket + credentials, and the
+    // server's strict schema rejects any field it does not declare. Sending it
+    // made the whole save fail on an "unrecognized key" the user never typed.
+    return { ...base, credentials: key };
+  }
+
+  const credentials = {
+    accessKeyId: String(values.accessKeyId ?? "").trim(),
+    secretAccessKey: String(values.secretAccessKey ?? "").trim()
+  };
+  if (providerId === "r2") {
+    // The account id builds the endpoint hostname and is then dropped: the
+    // endpoint is what the server stores, and `accountId` is not a schema field.
+    const accountId = String(values.accountId ?? "").trim();
+    return { ...base, region: "auto", endpoint: `https://${accountId}.r2.cloudflarestorage.com`, credentials };
+  }
+  return { ...base, region: String(values.region ?? "").trim(), credentials };
+}
+
+/* ── The key ─────────────────────────────────────────────────────────── */
+
+/**
+ * Which ceremony screen four runs for a chosen destination.
+ *
+ * Managed storage comes with sealed key escrow, so there the phrase is the
+ * identity that has to exist first and the ceremony leads with it, unchanged.
+ * The free paths live on this machine, where a password someone already knows
+ * how to keep beats 24 words they are about to mislay — the phrase still
+ * exists and is still offered, but after the vault does, as the extra rather
+ * than the toll.
+ */
+export const keyMode = (intent) => (intent === "managed" ? "phrase" : "password");
+
+/**
+ * Why a password cannot be used yet, in words that name the fix — or "" when
+ * it can. The bounds are setupVaultSchema's own (min 8, max 1024), checked
+ * here so the person hears about them beside the field, not from a rejected
+ * vault create.
+ */
+export function passwordProblem(password, repeat) {
+  const value = String(password ?? "");
+  if (value.length === 0) return "Choose a password first.";
+  if (value.length < 8) return "Eight characters is the minimum. Longer is stronger.";
+  if (value.length > 1024) return "That is longer than a password can be here — 1024 characters at most.";
+  if (value !== String(repeat ?? "")) return "The two boxes do not hold the same password. Type it again in both.";
+  return "";
+}
+
+/**
+ * Strength, judged by length and nothing else. Character-class rules teach
+ * people to write Password1! and call it strong; length is the dial that
+ * actually moves the cost of guessing, so it is the only one shown — and the
+ * function takes a number so it could not peek at the characters if it wanted.
+ */
+export function passwordHint(length) {
+  if (!Number.isFinite(length) || length <= 0) return "At least 8 characters. Length is what makes it strong.";
+  if (length < 8) return `${8 - length} more character${8 - length === 1 ? "" : "s"} to reach the minimum.`;
+  if (length < 12) return "Long enough to use. Every character you add makes it stronger.";
+  if (length < 20) return "Good length.";
+  return "Excellent length.";
+}
+
+/* ── The recovery phrase ─────────────────────────────────────────────── */
+
+export const canonicalWord = (value) => String(value ?? "").trim().toLowerCase().replace(/[^a-z]/g, "");
+
+/**
+ * Which words we ask for back.
+ *
+ * The last word is always one of them: it is the checksum word, the one people
+ * stop writing when they think the list has ended. The other two are random so
+ * the check cannot become muscle memory across reinstalls.
+ */
+export function verificationPositions(total, count = 3, pick = Math.random) {
+  if (total <= 0) return [];
+  const chosen = new Set([total]);
+  let guard = 0;
+  while (chosen.size < Math.min(count, total) && guard < 500) {
+    chosen.add(Math.floor(pick() * (total - 1)) + 1);
+    guard += 1;
+  }
+  return [...chosen].sort((a, b) => a - b);
+}
+
+/**
+ * Compares in memory, returns positions only. The words themselves never leave
+ * this call.
+ *
+ * A blank answer and a missing word are both wrong, and no positions at all is
+ * wrong too: without those three the gate opens on an empty form against an
+ * absent phrase, which is the one way this screen could wave someone through
+ * having transcribed nothing.
+ */
+export function checkPhraseAnswers(words, positions, answers) {
+  const wrong = positions.filter((position, index) => {
+    const expected = canonicalWord(words[position - 1]);
+    const given = canonicalWord(answers[index]);
+    return expected === "" || given === "" || given !== expected;
+  });
+  return { ok: positions.length > 0 && wrong.length === 0, wrong };
+}
+
+/** "Word 11 does not match" — the position is the whole point, so it leads. */
+export function phraseProblem(wrong) {
+  if (wrong.length === 0) return "";
+  const list = wrong.length === 1 ? `Word ${wrong[0]}` : `Words ${wrong.slice(0, -1).join(", ")} and ${wrong[wrong.length - 1]}`;
+  return `${list} ${wrong.length === 1 ? "does" : "do"} not match the list above. The order matters — check the numbers.`;
+}
+
+/* ── The last screen ─────────────────────────────────────────────────── */
+
+/** Turns the commit results into rows that say what is now true, not what was called. */
+export function summariseDone(result) {
+  const rows = [];
+  rows.push({
+    label: "Vault",
+    badge: { text: "created", kind: "verified" },
+    detail: result.password
+      ? `${result.vault?.dataDir ?? "this machine"}`
+      : `${result.vault?.dataDir ?? "this machine"} — opened by the recovery phrase you wrote down, and by nothing else.`
+  });
+
+  // Named again even though it was chosen two screens ago, because this is the
+  // screen people keep, and the mode is the one setting that can never be
+  // quietly revisited. "plain" keeps a calm badge: it was a choice made in
+  // full view, and alarming here would call the person wrong for deciding.
+  // Absent mode (finishing against a vault made before this page) adds no row
+  // rather than guessing.
+  if (result.storageMode === "plain") {
+    rows.push({ label: "Archives", badge: { text: "Plain — readable", kind: "local" }, detail: "Stored as readable files, by your choice at setup. Anyone who can read the storage can read the sessions." });
+  } else if (result.storageMode === "sealed") {
+    rows.push({ label: "Archives", badge: { text: "Sealed", kind: "verified" }, detail: "Locked on this machine before they are stored anywhere. Only your key can ever open them." });
+  }
+
+  // Reported from the unlock check, not from the request: the server refuses
+  // to fail a create over a lock it could not write, so the one place a person
+  // learns their password did not take is this row.
+  if (result.password) {
+    rows.push(result.password.locked === true
+      ? { label: "Your key", badge: { text: "password", kind: "verified" }, detail: "Unlocks with your password on this machine. The recovery phrase opens it anywhere, if you kept it." }
+      : result.password.locked === false
+        ? { label: "Your key", badge: { text: "password not saved", kind: "alert" }, detail: "Your password could not be saved on this machine, so it will not open this vault. The vault itself is fine: the recovery phrase still opens it if you kept it, and you can choose a password again later." }
+        : { label: "Your key", badge: { text: "unconfirmed", kind: "held" }, detail: "Sealkeep could not confirm the password saved on this machine. If it did not, the recovery phrase still opens the vault if you kept it, and you can choose a password again later." });
+  }
+
+  // What the bytes leaving this machine are, said the same way everywhere
+  // below. Derived once so a plain vault is never described as sealed on the
+  // very screen that just named it readable; absent mode means a vault from
+  // before this page existed, and those are all sealed.
+  const copies = result.storageMode === "plain" ? "readable archives (your choice at setup)" : "sealed archives only";
+
+  // The account link comes before storage, because for a managed vault the
+  // account *is* the storage: enrolment is what turns cloud storage on. A link
+  // that failed on a paid setup is the worst thing to leave off this screen, so
+  // it gets its own badged row — never folded into a cheerful "this disk only".
+  const account = result.account;
+  const managed = Boolean(account && !account.error);
+  if (account) {
+    rows.push(managed
+      ? { label: "Sealkeep account", badge: { text: "linked", kind: "verified" }, detail: `This machine is linked to your account${account.plan && account.plan !== "unknown" ? ` (${account.plan})` : ""}. Managed storage is on — it receives ${copies}.` }
+      : { label: "Sealkeep account", badge: { text: "not linked", kind: "alert" }, detail: `${account.error} This machine is not linked to your account yet, so archives are staying on this disk only. Re-enter your pairing code from the dashboard to turn on managed storage — your vault and the key that opens it are fine.` });
+  }
+
+  if (result.storage) {
+    rows.push(result.storage.error
+      ? { label: "Storage", badge: { text: "not connected", kind: "alert" }, detail: `${result.storage.error} Your vault is fine and is keeping archives on this disk. Try the storage settings again from the dashboard.` }
+      : { label: "Storage", badge: { text: result.storage.verified ? "verified" : "saved", kind: result.storage.verified ? "verified" : "held" }, detail: `${result.storage.provider}://${result.storage.bucket}/${result.storage.prefix} — ${copies}. The credentials went to this machine's keychain and cannot be read back.` });
+  } else if (managed) {
+    rows.push({ label: "Storage", badge: { text: "Sealkeep managed", kind: "verified" }, detail: `Your account's storage receives ${copies}. Nothing else to set up.` });
+  } else if (!account) {
+    rows.push({ label: "Storage", badge: { text: "this disk only", kind: "local" }, detail: "Archives stay in the vault on this machine. Add a bucket whenever you like — nothing you did today gets redone." });
+  }
+  // account && !managed: the account row already said "this disk only"; a second
+  // storage row would only repeat it.
+
+  const service = result.service;
+  rows.push(service?.running
+    ? { label: "Background service", badge: { text: "running", kind: "verified" }, detail: service.detail ?? "It checks for new sessions on its own. Nothing to keep open." }
+    : { label: "Background service", badge: { text: "not running", kind: "held" }, detail: `${service?.error ?? service?.detail ?? "It did not start."} You can turn it on any time from Settings › Automatic archiving on the dashboard.` });
+
+  return rows;
+}
+
+/** The headline on the last screen tells you the worst true thing first. */
+export function doneHeadline(rows) {
+  if (rows.some((row) => row.badge.kind === "alert")) return "Your vault is ready — one thing did not connect";
+  if (rows.some((row) => row.badge.kind === "held")) return "Your vault is ready — one thing still needs you";
+  return "Sealkeep is running";
+}