feat: seal in the browser — the owner journey is now terminal-free (EF-ISS-7)

Creating and maintaining a register were already terminal-free; sealing a
new one was the last wall. scripts/edit.sh now runs the whole create flow
through the local editor server: fill the form, Save (writes estate.yaml
to the folder, no Downloads shuffle), then Seal my file — the server runs
the proven scripts/setup.sh in a new machine-emit mode (EXECUTOR_FILE_EMIT)
and the browser walks the ceremony (shares one at a time, confirm and
clear, passphrase, checklist), all on 127.0.0.1.

- setup.sh: EXECUTOR_FILE_EMIT emits the proof-verified secrets as a
  parseable block and skips the human display; normal setup.sh unchanged.
- edit-server.py: --mode create|review; create-mode save keeps the server
  up; new GET /validate and POST /seal (localhost only; secrets never
  written to disk beyond the .age; /seal reuses setup.sh, no crypto
  reimplemented).
- editor.html: create titling, a Seal button, and an in-browser ceremony.
- edit.sh: launches the editor in create mode via the server (falls back
  to the static download editor when python3 is absent).
- SECURITY.md: states the localhost trust boundary of the browser seal
  honestly (secrets cross 127.0.0.1 and show in the tab; same boundary as
  the terminal ceremony; terminal path remains for the smallest surface).

Security-critical test added: drive create -> save -> seal through the
server and assert the returned shares reconstruct the returned passphrase
on a setup.sh-proof-verified file. Suite 116 green batchpass / 114 expect,
both mechanisms; review.sh's terminal + browser paths unaffected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: TheWayWithin

ISSUES.md

@@ -16,7 +16,6 @@ ID or another repo's. Raise issues here with `python3 ~/shared/scripts/repo-issu
 
 | ID | Title | Status | Severity | Detail | MC-SYNC |
 |----|-------|--------|----------|--------|---------|
-| EF-ISS-7 | Sealing a NEW register still needs a Terminal command (scripts/setup.sh): creating and maintaining register content are now terminal-free (browser editor + review-in-browser), but the first encrypt+split+prove-chain step isn't. Last terminal wall for a non-technical owner — consider a guided seal (double-click launcher wrapping setup.sh) or an editor 'seal' action shelling out to age/ssss locally. | Open | medium | — | pending |
 | EF-ISS-5 | Register editor + schema help is thin on jurisdiction for cross-border users: editor v1 has no domicile/residence fields (schema supports them), and the 'jurisdictions' help doesn't explain it means every place you hold assets, nor domicile vs residence, nor 'if UK/US/FR-style cross-border, see a specialist solicitor'. Real UAT case: UK citizen, NY resident on E-2, assets in UK/US/FR — user could not tell what to enter. | Open | medium | — | pending |
 | EF-ISS-3 | Onboarding requires holding instructions across multiple pages — violates the product's own 'you don't have to hold it in your head' principle; non-technical owners should be funnelled to executorfile.com/get-started, not raw GitHub | Open | high | — | pending |
 | EF-ISS-2 | GitHub release page is a dead-end for non-technical users: no 'download this / do this next', assets collapsed under Assets, and competing with GitHub's auto Source-code downloads; install instructions are stranded back on the README (can't be recalled on the release page) | Open | high | — | pending |
@@ -25,6 +24,7 @@ ID or another repo's. Raise issues here with `python3 ~/shared/scripts/repo-issu
 
 | ID | Title | Status | Commit | Detail |
 |----|-------|--------|--------|--------|
+| EF-ISS-7 | Sealing a NEW register still needs a Terminal command (scripts/setup.sh): creating and maintaining register content are now terminal-free (browser editor + review-in-browser), but the first encrypt+split+prove-chain step isn't. Last terminal wall for a non-technical owner — consider a guided seal (double-click launcher wrapping setup.sh) or an editor 'seal' action shelling out to age/ssss locally. | Done | browser seal | scripts/edit.sh now creates AND seals in the browser: fill the form, Save, Seal, and an in-browser ceremony writes down the shares. edit-server.py gained mode-aware save + /validate + /seal (runs setup.sh in EXECUTOR_FILE_EMIT mode, reusing the proven crypto). Owner journey is now terminal-free after launch; setup.sh remains the terminal path. |
 | EF-ISS-6 | Yearly-review (maintenance) still hits the terminal wall: browser editor only handles plaintext to Downloads, but the kept file is estate.yaml.age and must be re-encrypted with the SAME passphrase (shares stay valid) — review.sh still uses a terminal editor. Build 'review in the browser': review.sh decrypts to a temp file, opens it in a local-only editor that reads/writes that file directly, then re-encrypts+verifies+shreds. Also make the editor loader handle folded '>' block scalars so example-style/hand-authored files open too. | Done | 7ca3113, f769193 | review-in-browser (edit-server.py + editor server mode + review.sh browser default) and block-scalar loader shipped; yearly review no longer needs a terminal editor. |
 | EF-ISS-4 | Editing the register in a terminal editor (nano) is a hard wall for non-technical owners: dry-run tester could not use nano, accidental ^V wrote junk, could not exit. This is the dry-run evidence the parked GUI/editing-interface decision (SPEC-v1 §9) was explicitly waiting for. Needs a humane edit path (GUI or form/web editor) before the tool is usable by its target audience. | Done | fcfabda, 7ca3113 | humane edit path shipped: browser form editor for creating (editor.html) and for maintaining (review-in-browser). The parked GUI decision (SPEC-v1 §9) is resolved. Remaining terminal step (sealing) tracked as EF-ISS-7. |
 | EF-ISS-1 | README quickstart assumes the repo is already on disk: no download/unpack/cd step for tarball users | Done | 8887f5d | README 'Get the tool' section added: tarball download + unpack + cd, git clone alternative, terminal-opening, Homebrew fallback. |

README.md

@@ -58,7 +58,7 @@ cd executor-file
 
 Either way you are now "in the folder" — every command below is typed into that same Terminal window, and the `scripts/...` paths will just work.
 
-**Prefer not to hand-edit a text file?** Double-click **`Edit-Executor-File.command`** in the folder (or run `scripts/edit.sh`) to fill your register in as a form in your browser — dropdowns, plain-English help, no YAML. It runs entirely on your machine, saves `estate.yaml` to your Downloads, and you still seal it once with `scripts/setup.sh`.
+**Prefer not to touch the Terminal at all?** Run `scripts/edit.sh` (once you are in the folder) to fill your register in as a form in your browser — dropdowns, plain-English help, no YAML — then click **Save** and **Seal my file**, and it encrypts the file, splits the key, and walks you through writing the shares down, all in the browser. It runs entirely on your machine; nothing is sent anywhere. The one-command Terminal path (`scripts/setup.sh`) below still works if you prefer it.
 
 **Two small tools to install once** (these do the encryption and the share-splitting; both are free, open-source, and standard):
 
@@ -98,7 +98,7 @@ nano estate.yaml
 scripts/validate.sh
 ```
 
-**3. Seal it** — validate → encrypt → split → **prove the chain**, one command. It generates a strong passphrase, encrypts, splits the passphrase 2-of-3, then reconstructs it from two of the just-issued shares and test-decrypts back to a byte-identical copy before reporting success:
+**3. Seal it** — validate → encrypt → split → **prove the chain**. If you built the register with `scripts/edit.sh`, you already sealed it there in the browser and can skip this. Otherwise, one command does it: it generates a strong passphrase, encrypts, splits the passphrase 2-of-3, then reconstructs it from two of the just-issued shares and test-decrypts back to a byte-identical copy before reporting success:
 
 ```bash
 scripts/setup.sh

SECURITY.md

@@ -43,6 +43,16 @@ Explicitly NOT defended — stated so nobody relies on it:
   say so honestly: scrollback, terminal logs, and session recorders
   are outside their control — closing the terminal window is part of
   the ceremony.
+- **The optional browser flows (`scripts/edit.sh`, `scripts/review.sh`).**
+  These run a web server bound to `127.0.0.1` only, on your machine, and
+  the browser talks only to it — nothing reaches the network. But during
+  the browser seal the passphrase and shares travel over that localhost
+  connection and are shown in the browser tab, which is the same local
+  trust boundary as the terminal ceremony (same-user processes, browser
+  extensions, and a screen recorder can see them). They are never written
+  to disk beyond the `.age` file, never stored in the browser, and shown
+  one at a time; closing the tab when done is part of the ceremony. If you
+  want the smallest possible surface, use the terminal path (`setup.sh`).
 - **Two colluding share holders.** Any two shares open the file by
   design. Choose holders whose collusion you would consider
   authorised access.

scripts/edit.sh

@@ -1,19 +1,29 @@
 #!/bin/sh
-# edit.sh — open the friendly register editor in your web browser.
+# edit.sh — fill in your register as a browser form, then seal it, all on
+# this machine. Opens a local, private editor in your web browser: no
+# server on the network, no account, nothing sent anywhere. You fill in
+# the form, click Save, then Seal, and it encrypts the file and splits the
+# key, walking you through writing the shares down. Owner-side tooling
+# (Python is fine here); your executor's recovery path never uses it.
 #
-# Fill your register in as a form (dropdowns, plain-English help) instead
-# of hand-editing YAML. It runs entirely in your browser on this machine:
-# no server, no network, nothing sent anywhere. When you click Save it
-# writes estate.yaml to your Downloads folder; then seal it once with
-# scripts/setup.sh.
-#
-# Usage:  scripts/edit.sh
+# Usage:  scripts/edit.sh [FILE]        (default: estate.yaml)
 set -u
 DIR=$(cd "$(dirname "$0")/.." && pwd)
+SERVER="$DIR/web/edit-server.py"
+TARGET="${1:-estate.yaml}"
+
+if command -v python3 >/dev/null 2>&1 && [ -f "$SERVER" ]; then
+  echo "Opening the register editor in your browser."
+  echo "  (it runs only on this machine; nothing you type is sent anywhere)"
+  exec python3 "$SERVER" "$TARGET" --mode create --open
+fi
+
+# Fallback when python3 is unavailable: the static editor (download flow,
+# and you seal separately with scripts/setup.sh).
 PAGE="$DIR/web/editor.html"
 [ -f "$PAGE" ] || { echo "error: editor not found at $PAGE" >&2; exit 1; }
-echo "Opening the register editor in your browser…"
-echo "  (it runs locally — nothing you type is sent anywhere)"
+echo "python3 was not found, so opening the basic editor."
+echo "Fill it in and Save; then seal with:  scripts/setup.sh"
 if command -v open >/dev/null 2>&1; then open "$PAGE"
 elif command -v xdg-open >/dev/null 2>&1; then xdg-open "$PAGE"
 else echo "Open this file in your browser: $PAGE"; fi

scripts/setup.sh

@@ -310,6 +310,26 @@ else
 fi
 FINALISED=1
 
+# Machine-emit mode (EXECUTOR_FILE_EMIT=1): a caller that will run its
+# own ceremony (scripts/edit.sh's browser seal, via web/edit-server.py)
+# asks for the secrets in a parseable block instead of the human display.
+# The block goes to stdout between clear markers; nothing is written to
+# disk beyond the .age and its sidecar. We still did the full proof
+# chain above, so this is the same sealed, verified file.
+if [ -n "${EXECUTOR_FILE_EMIT:-}" ]; then
+  SHA="$(cut -d' ' -f1 < "$OUT.sha256")"
+  printf '===SEAL-BEGIN===\n'
+  printf 'passphrase\t%s\n' "$PASS"
+  printf 'share\t%s\n' "$S1"
+  printf 'share\t%s\n' "$S2"
+  printf 'share\t%s\n' "$S3"
+  printf 'sha256\t%s\n' "$SHA"
+  printf 'out\t%s\n' "$OUT"
+  printf 'own\t%s\n' "$OWN"
+  printf '===SEAL-END===\n'
+  exit 0
+fi
+
 echo "Step 6/6 — done. Your Executor File is sealed."
 echo
 echo "  Encrypted register:  $OUT"

tests/test-edit-server.py

@@ -10,6 +10,7 @@
 Exit 0 = all good; prints a diagnostic and exits 1 on any failure.
 """
 
+import json
 import os
 import subprocess
 import sys
@@ -54,11 +55,13 @@ def fail(msg, proc=None):
     sys.exit(1)
 
 
-def start(target):
+def start(target, mode=None):
     """Launch the server on an OS-assigned port; return (proc, base_url)."""
+    cmd = [sys.executable, SERVER, target, "--port", "0"]
+    if mode:
+        cmd += ["--mode", mode]
     proc = subprocess.Popen(
-        [sys.executable, SERVER, target, "--port", "0"],
-        stderr=subprocess.PIPE, stdout=subprocess.DEVNULL, text=True,
+        cmd, stderr=subprocess.PIPE, stdout=subprocess.DEVNULL, text=True,
     )
     deadline = time.time() + READY_TIMEOUT
     while time.time() < deadline:
@@ -126,6 +129,51 @@ def main():
         if open(target2).read() != original:
             fail("cancel changed the file")
 
+        # ---- create + seal path (needs age + ssss) ----
+        import shutil
+        if shutil.which("age") and shutil.which("ssss-split") and shutil.which("ssss-combine"):
+            target3 = os.path.join(d, "estate3.yaml")
+            with open(EXAMPLE) as f:
+                open(target3, "w").write(f.read())
+            proc3, url3 = start(target3, mode="create")
+            # /validate reports the register as valid
+            with urllib.request.urlopen(url3 + "validate", timeout=15) as r:
+                if not json.loads(r.read()).get("ok"):
+                    fail("/validate said the example register is invalid", proc3)
+            # save keeps the server up in create mode
+            post(url3 + "save", open(target3).read())
+            if proc3.poll() is not None:
+                fail("create-mode save should NOT exit the server")
+            # seal it
+            sealed = json.loads(post(url3 + "seal", json.dumps({"overwrite": False})))
+            if not sealed.get("ok"):
+                fail(f"/seal failed: {sealed.get('error')}", proc3)
+            shares = sealed["shares"]
+            passphrase = sealed["passphrase"]
+            if len(shares) != 3:
+                fail("seal did not return three shares", proc3)
+            if not os.path.exists(target3 + ".age"):
+                fail("seal did not produce the .age file", proc3)
+            # SECURITY-CRITICAL: two of the returned shares must reconstruct
+            # the returned passphrase (the file setup.sh made was already
+            # proof-chain verified before it emitted).
+            combine = subprocess.run(
+                ["ssss-combine", "-t", "2"],
+                input=f"{shares[0]}\n{shares[1]}\n", capture_output=True, text=True,
+            )
+            recovered = ""
+            for line in combine.stderr.splitlines():
+                if line.startswith("Resulting secret: "):
+                    recovered = line[len("Resulting secret: "):]
+            if recovered != passphrase:
+                fail("the shares from /seal do NOT reconstruct the passphrase")
+            # finish
+            post(url3 + "done")
+            wait_exit(proc3, 0)
+            print("ok: create+seal produced a valid file whose shares reconstruct the passphrase")
+        else:
+            print("note: create+seal path skipped (age/ssss not installed)")
+
     print("ok: edit-server load/save(exit0)/cancel(exit2) all correct")
     return 0
 

web/edit-server.py

@@ -18,7 +18,9 @@
 """
 
 import http.server
+import json
 import os
+import subprocess
 import sys
 import threading
 import webbrowser
@@ -36,21 +38,67 @@ def main() -> int:
     target = os.path.abspath(args[0])
     port = 8765
     do_open = False
+    mode = "review"  # review: save then exit (review.sh re-encrypts).
+    #                  create: save keeps the server up so the owner can seal.
     i = 1
     while i < len(args):
         if args[i] == "--port" and i + 1 < len(args):
             port = int(args[i + 1]); i += 2
         elif args[i] == "--open":
             do_open = True; i += 1
+        elif args[i] == "--mode" and i + 1 < len(args):
+            mode = args[i + 1]; i += 2
         else:
             i += 1
 
     if not os.path.isfile(EDITOR_HTML):
         sys.stderr.write(f"error: editor not found at {EDITOR_HTML}\n")
         return 1
 
+    REPO_ROOT = os.path.dirname(HERE)
     state = {"result": None}
 
+    def run_validate():
+        p = subprocess.run(
+            ["sh", os.path.join(REPO_ROOT, "scripts", "validate.sh"), target],
+            stdin=subprocess.DEVNULL, capture_output=True, text=True,
+        )
+        return {"ok": p.returncode == 0, "output": (p.stdout + p.stderr)[-4000:]}
+
+    def run_seal(overwrite):
+        # Seal via the proven scripts/setup.sh in machine-emit mode. Secrets
+        # come back in the response (localhost only, same trust boundary as
+        # the terminal ceremony) and are never written to disk here.
+        out = target + ".age"
+        if os.path.exists(out):
+            if not overwrite:
+                return {"ok": False, "error": "exists"}
+            os.remove(out)
+            if os.path.exists(out + ".sha256"):
+                os.remove(out + ".sha256")
+        env = dict(os.environ, EXECUTOR_FILE_EMIT="1")
+        p = subprocess.run(
+            ["sh", os.path.join(REPO_ROOT, "scripts", "setup.sh"), target],
+            stdin=subprocess.DEVNULL, capture_output=True, text=True, env=env,
+        )
+        if p.returncode != 0:
+            msg = (p.stderr or p.stdout or "seal failed").strip()
+            return {"ok": False, "error": msg[-800:]}
+        block, shares, inblk = {}, [], False
+        for line in p.stdout.splitlines():
+            if line == "===SEAL-BEGIN===":
+                inblk = True; continue
+            if line == "===SEAL-END===":
+                break
+            if inblk and "\t" in line:
+                k, v = line.split("\t", 1)
+                (shares.append(v) if k == "share" else block.__setitem__(k, v))
+        if len(shares) != 3 or "passphrase" not in block:
+            return {"ok": False, "error": "could not read the sealed result"}
+        return {"ok": True, "passphrase": block["passphrase"], "shares": shares,
+                "sha256": block.get("sha256", ""), "out": block.get("out", ""),
+                "own": block.get("own", "0")}
+
     class Handler(http.server.BaseHTTPRequestHandler):
         def _send(self, code, body=b"", ctype="text/plain; charset=utf-8"):
             self.send_response(code)
@@ -60,16 +108,26 @@ def _send(self, code, body=b"", ctype="text/plain; charset=utf-8"):
             if body:
                 self.wfile.write(body)
 
+        def _json(self, obj, code=200):
+            self._send(code, json.dumps(obj).encode(), "application/json")
+
+        def _stop(self, result):
+            state["result"] = result
+            threading.Thread(target=httpd.shutdown, daemon=True).start()
+
         def do_GET(self):
             if self.path in ("/", "/index.html", "/editor.html"):
                 with open(EDITOR_HTML, "rb") as f:
-                    self._send(200, f.read(), "text/html; charset=utf-8")
+                    body = f.read().replace(b"__MODE__", mode.encode())
+                    self._send(200, body, "text/html; charset=utf-8")
             elif self.path == "/load":
                 data = b""
                 if os.path.isfile(target):
                     with open(target, "rb") as f:
                         data = f.read()
                 self._send(200, data)
+            elif self.path == "/validate":
+                self._json(run_validate())
             else:
                 self._send(404, b"not found")
 
@@ -84,13 +142,22 @@ def do_POST(self):
                     os.replace(tmp, target)
                 except OSError as e:
                     self._send(500, str(e).encode()); return
-                self._send(200, b"saved")
-                state["result"] = "saved"
-                threading.Thread(target=httpd.shutdown, daemon=True).start()
+                # In create mode the server stays up so the owner can seal;
+                # in review mode saving is the end and review.sh takes over.
+                if mode == "create":
+                    self._send(200, b"saved")
+                else:
+                    self._send(200, b"saved"); self._stop("saved")
+            elif self.path == "/seal" and mode == "create":
+                try:
+                    params = json.loads(body) if body else {}
+                except ValueError:
+                    params = {}
+                self._json(run_seal(bool(params.get("overwrite"))))
+            elif self.path == "/done":
+                self._send(200, b"done"); self._stop("saved")
             elif self.path == "/cancel":
-                self._send(200, b"cancelled")
-                state["result"] = "cancel"
-                threading.Thread(target=httpd.shutdown, daemon=True).start()
+                self._send(200, b"cancelled"); self._stop("cancel")
             else:
                 self._send(404, b"not found")