@inoku/lepan 0.7.66 → 0.7.69

package/README.md

@@ -86,7 +86,7 @@ The Linux/macOS legacy browser-owner setup uses the built-in AV1 registration en
 
 LifeDrive requires Leither V0.24.11 or newer. Linux/macOS browser-owner setup creates a separate Ed25519 `sodiumv2` identity for the primary browser. Windows prints a private ten-minute invitation for the first paired phone; later users and devices are managed from a paired device.
 
-After successful npm setup, the installer saves a private `lepan-pairing-<id>.png` and prints its full path. It also displays the QR code when it fits the terminal's width and height. In the iPhone or Android app, open **Settings → Set up users → Scan QR code** and scan the terminal or the saved image. A private `.json` invitation is saved alongside it for apps without a setup scanner: transfer that file to the phone and use **Choose identity file**. These files are saved in the Leither root on Linux/macOS and its private `.lifedrive-household` directory on Windows. Household invitations expire ten minutes after creation; legacy identity codes contain a device private key, so keep them private and delete the transfer copies after pairing. Legacy `--add-device` and `--upgrade` also produce a code when an identity is available; household upgrades preserve existing pairings without issuing new invitations.
+After successful npm setup, the installer displays the QR code at the end of its output whenever the terminal is wide enough. If the whole code cannot fit on screen, it automatically opens the full-size QR image in the computer's image viewer. In the iPhone or Android app, open **Settings → Set up users → Scan QR code** and scan the displayed code. A private `lepan-pairing-<id>.png` is also saved, with its path printed as a fallback for remote sessions or computers without an image viewer. A private `.json` invitation is saved alongside it for apps without a setup scanner: transfer that file to the phone and use **Choose identity file**. These files are saved in the Leither root on Linux/macOS and its private `.lifedrive-household` directory on Windows. Household invitations expire ten minutes after creation; legacy identity codes contain a device private key, so keep them private and delete the transfer copies after pairing. Legacy `--add-device` and `--upgrade` also produce a code when an identity is available; household upgrades preserve existing pairings without issuing new invitations.
 
 ### Renew an expired first-phone invitation
 
@@ -112,6 +112,21 @@ already exist, use **My devices** on a paired phone to invite another device. An
 interrupted first claim must be resumed on the original phone with its original
 invitation. Ordinary `--upgrade` does not renew invitations.
 
+### Reconnect after forgetting the only phone
+
+Run `npx --yes @inoku/lepan@latest --recover-device Owner` on the computer hosting
+Leither, substituting the existing account name or user ID. Scan the displayed
+QR code to reconnect to that same account. This node-operator action preserves
+account keys, files, backups, and other devices. The reconnect invitation is
+private and expires in ten minutes; rerun the same command if it expires before
+being claimed. The account service briefly restarts, while Leither keeps running.
+Normal phone-to-phone invitations still require device-manager approval.
+
+First-account pairing prepares the file catalog before opening Files and adds
+`Getting started with LePan.txt` once. The guide can be renamed or deleted and is
+not duplicated when another phone joins. First setup also grants each account
+write access only to its own node staging directory when Leither requires it.
+
 An existing installation is backed up before replacement. The explicit `--upgrade` path requires the saved application and key-auth owner state before changing files, synchronizes the same published application MID, and does not rerun device or domain setup. This release intentionally does not migrate the earlier password-owner prototype. Application files are active only after Leither advances the application from `cur` to `last`; a publication timeout leaves the prior `last` version serving users.
 
 Source code and design documentation are maintained separately. No device key, identity bundle, PPT, publisher key, or node-specific application MID is included in these release assets.

package/USER_MANUAL.md

@@ -142,8 +142,7 @@ This keeps what step 2.1 installed and adds users and phones:
 
 1. Creates LifeDrive's private configuration in `<Leither root>/.lifedrive-household/`.
 2. Installs and starts the identity service: `lifedrive-identity` through systemd on Linux, `uk.inoku.lifedrive-identity` through launchd on macOS, or `LifeDrive Identity` through Task Scheduler on Windows. Leither itself is not restarted and must be running separately.
-3. Prints a **setup invitation**: a block of text, followed by
-   *"Keep the invitation above private. It expires in ten minutes."*
+3. Displays a **setup invitation** as a QR code. If the terminal is too small, the full-size QR image opens automatically on this computer. The invitation expires in ten minutes.
 
 The setup invitation is what makes a phone the first user of this node. Treat it
 like a key: do not post it, email it to others, or paste it anywhere public.
@@ -152,13 +151,16 @@ like a key: do not post it, email it to others, or paste it anywhere public.
 
 Within ten minutes of the invitation being printed:
 
-1. Keep the installer’s final QR code visible, or open the saved `lepan-pairing-<id>.png` using the path it prints. If you used the standalone shell installer, copy the whole invitation block instead.
+1. Scan the installer’s final QR code or the QR image that opens automatically. The saved image path is a fallback for remote sessions or computers without an image viewer. If you used the standalone shell installer, copy the whole invitation block instead.
 2. Open LifeDrive on the phone. The **Set up your LifeDrive** screen opens by itself (or open **Settings → Set up users**).
 3. Enter **Your name** and a name for this device.
 4. Tap **Scan QR code** and point the phone at the terminal or saved image. You can also use **Paste node identity** or **Choose identity file**.
 
-The phone creates its own device key, claims the node, and opens your new, empty
-personal drive. You are now the node's first user and its **administrator**, and
+The phone creates its own device key, claims the node, and opens your personal
+drive after its file list is ready. Files contains **Getting started with LePan.txt**,
+a short guide to Files, Backups, connecting other phones, and keeping access to
+your account. It is added once per account; reconnecting a phone does not duplicate
+it, and deleting or renaming it does not cause it to return. You are now the node's first user and its **administrator**, and
 this phone is a **device manager**.
 
 You can close the setup screen without pairing to look around the app. Tapping an
@@ -168,7 +170,7 @@ empty page, or **Settings → Set up users**, opens it again.
 
 | Situation | What to do |
 |---|---|
-| The invitation expired before you pasted it | On the node, stop the identity service (`sudo systemctl stop lifedrive-identity` on Linux, or `sudo launchctl bootout system/uk.inoku.lifedrive-identity` on macOS) and run the command from 2.2 again for a fresh invitation. |
+| The invitation expired before you pasted it | On the node, run `npx --yes @inoku/lepan@latest --household` again for a fresh QR code. Setup renews an unclaimed invitation and preserves the existing identity; no manual service commands are needed. |
 | You pasted it, but the app lost its connection or was closed | Open the app on **the same phone** and paste **the same invitation** again. A claim that has started can finish after the ten minutes have passed. Do not delete the app or ask for a new invitation: that would abandon the phone's pending key. |
 | Setup says the node already has users | The node has been claimed. Add further devices from **My devices** (section 4), not with a new setup invitation. |
 
@@ -361,12 +363,26 @@ What remains true:
 - **Other users are unaffected.** Their drives and devices keep working.
 - **Recovery needs the node operator.** Contact whoever runs the node.
 
-For node operators: LifeDrive does not yet include a repair command that binds a
-new device to an existing user. The setup invitation (`--household`) only works
-on a node that has no users, so it cannot be used for this. Until the repair
-command exists, recovering a user who has lost every device needs help from the
-LifeDrive maintainers. Do not delete or edit `.lifedrive-household/` to try to
-work around it: it holds every user's authority and the authorization journal.
+For node operators: run this on the computer hosting Leither, replacing `Owner`
+with the existing account name (quote names containing spaces), or its exact user
+ID if names are duplicated:
+
+```bash
+npx --yes @inoku/lepan@latest --recover-device Owner
+```
+
+The account service briefly stops to issue a private reconnect invitation, then
+starts again before the QR code is shown. Scan it under **Settings → Set up users**
+on the phone. It enrolls a new device manager into the same account; account keys,
+Files, Backups, and other devices are preserved. A reconnect invitation expires
+in ten minutes unless that phone has already begun claiming it. Treat it as a
+private account-access key. An expired, unclaimed code can be replaced by rerunning
+the same command. Once connected, remove access for the forgotten device from
+**My devices**. Leither itself stays running.
+
+The node operator's local access authorizes this recovery; ordinary device
+invitations still require approval from a paired device manager. `--household`
+remains first-account setup and cannot replace an existing account.
 
 ### 5.4 Prevent lockout
 

package/bin/lifedrive.js

@@ -12,12 +12,37 @@ const distributionDirectory = path.resolve(__dirname, "..", "dist");
 const bundlePath = path.join(distributionDirectory, "lifedrive-bundle.tar.gz");
 const checksumPath = `${bundlePath}.sha256`;
 
+function openPairingImage(imagePath) {
+  // A remote server must not open a window in another user's desktop session.
+  if (process.env.SSH_CONNECTION || process.env.SSH_TTY) return false;
+  let command;
+  let args;
+  if (process.platform === "darwin") {
+    command = "/usr/bin/open";
+    args = [imagePath];
+  } else if (process.platform === "win32") {
+    command = "powershell.exe";
+    args = ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
+      "Start-Process -FilePath $env:LEPAN_PAIRING_IMAGE -ErrorAction Stop"];
+  } else if (process.platform === "linux" && (process.env.DISPLAY || process.env.WAYLAND_DISPLAY)) {
+    command = "xdg-open";
+    args = [imagePath];
+  } else {
+    return false;
+  }
+  const result = spawnSync(command, args, {
+    stdio: "ignore", timeout: 5000,
+    env: { ...process.env, LEPAN_PAIRING_IMAGE: imagePath },
+  });
+  return !result.error && result.status === 0;
+}
+
 async function showPairingCode(resultPath) {
   if (!fs.existsSync(resultPath)) return;
   // The child writes this only after setup succeeds. Never scrape its output:
   // it can contain node keys as well as the mobile device's pairing identity.
   const pairing = JSON.parse(fs.readFileSync(resultPath, "utf8"));
-  if (pairing.version !== 1 || !["lifedrive-device-identity", "lifedrive-node-setup"].includes(pairing.type)) {
+  if (pairing.version !== 1 || !["lifedrive-device-identity", "lifedrive-node-setup", "lifedrive-user-identity"].includes(pairing.type)) {
     throw new Error("Unsupported pairing data");
   }
   const directory = fs.readFileSync(`${resultPath}.directory`, "utf8");
@@ -27,7 +52,7 @@ async function showPairingCode(resultPath) {
   // The node enforces expiry and returns account details after a successful claim.
   // Keep the full invitation in the import file, and leave legacy identities intact.
   // iOS still requires certificate_sha256 even when Leither transport uses a key.
-  const qrPayload = pairing.type === "lifedrive-node-setup"
+  const qrPayload = pairing.type !== "lifedrive-device-identity"
     ? JSON.stringify(Object.fromEntries([
       "type", "version", "app_id", "node_id", "endpoint", "transport",
       "transport_key", "certificate_sha256", "request_id", "secret",
@@ -40,12 +65,12 @@ async function showPairingCode(resultPath) {
   // Keep a private copy even when QR generation succeeds.
   fs.writeFileSync(identityPath, payload, { flag: "wx", mode: 0o600 });
   const options = { errorCorrectionLevel: "M", margin: 4, scale: 8 };
-  const privacyNote = pairing.type === "lifedrive-node-setup"
+  const privacyNote = pairing.type !== "lifedrive-device-identity"
     ? "Keep it private. This invitation expires ten minutes after creation."
     : "This contains your device private key. Keep it private and delete it after pairing.";
   const renewalHint = pairing.type === "lifedrive-node-setup"
     ? "\nInvitation expired? Run this again on the node:\n  npx --yes @inoku/lepan@latest --household\n"
-    : "";
+    : pairing.type === "lifedrive-user-identity" ? "\nInvitation expired? Run the same reconnect command again on this computer.\n" : "";
   let modules;
   try {
     const QRCode = require("qrcode");
@@ -64,17 +89,27 @@ async function showPairingCode(resultPath) {
     process.stderr.write(renewalHint);
     return;
   }
-  process.stdout.write("\nNext: pair your phone\n\n");
-  process.stdout.write("  1. Open LePan on your iPhone or Android phone.\n");
-  process.stdout.write("  2. Go to Settings > Set up users > Scan QR code.\n");
-  // Small terminal codes use half-height blocks. If the terminal would wrap,
-  // or scroll the instructions out of view, use the full-resolution PNG.
+  // Never hide a terminal code just because the window is short. Open the PNG
+  // automatically when the whole code cannot be visible at once, and put the
+  // terminal code last so subsequent instructions cannot scroll it away.
   const width = modules.size + options.margin * 2;
   const height = Math.ceil(width / 2);
-  const fitsTerminal = process.stdout.isTTY && process.stdout.columns > width &&
-    process.stdout.rows >= height + 26;
-  if (fitsTerminal) {
-    process.stdout.write("  3. Scan the code below.\n\n");
+  const fitsWidth = process.stdout.isTTY && process.stdout.columns > width;
+  const fitsScreen = fitsWidth && process.stdout.rows >= height + 3;
+  const imageOpened = !fitsScreen && openPairingImage(imagePath);
+  process.stdout.write("\nPair your phone\n\n");
+  process.stdout.write("Open LePan > Settings > Set up users > Scan QR code.\n");
+  process.stdout.write(imageOpened
+    ? "The QR image has opened automatically. Scan it with your phone.\n"
+    : fitsWidth ? "Scan the QR code below with your phone.\n"
+    : "This terminal is too narrow for the QR code and no image viewer could be opened. Open the saved image below.\n");
+  process.stdout.write(`${privacyNote}\n`);
+  process.stdout.write(`\nSaved QR image: ${imagePath}\n`);
+  process.stdout.write(`Pairing file (Choose identity file): ${identityPath}\n`);
+  process.stdout.write("Keep this computer on and connected while using LePan.\n");
+  process.stdout.write(renewalHint);
+  if (fitsWidth) {
+    process.stdout.write("\n");
     // Explicit colors and a four-module quiet zone work on light/dark themes.
     const dark = (x, y) => x >= 0 && y >= 0 && x < modules.size && y < modules.size && modules.get(y, x);
     let terminal = "";
@@ -86,16 +121,7 @@ async function showPairingCode(resultPath) {
       terminal += "\x1b[0m\n";
     }
     process.stdout.write(terminal);
-  } else {
-    process.stdout.write("  3. Open the saved QR image on this computer and scan it.\n");
   }
-  process.stdout.write(`\nQR image:\n  ${imagePath}\n\n${privacyNote}\n`);
-  process.stdout.write("\nNo Scan QR code button? Transfer this pairing file to your phone:\n");
-  process.stdout.write(`  ${identityPath}\n`);
-  process.stdout.write("Then open Settings > Set up users > Choose identity file.\n");
-  process.stdout.write("Keep the pairing file private; delete the transfer copy after import.\n");
-  process.stdout.write("Keep this computer on and connected while using LePan.\n");
-  process.stdout.write(renewalHint);
 }
 
 async function runInstaller(command, args) {
@@ -127,6 +153,7 @@ function windowsArguments(values) {
   const valueOptions = new Map([
     ["--leither-root", "-LeitherRoot"],
     ["--storage-max-gb", "-StorageMaxGB"],
+    ["--recover-device", "-RecoverDevice"],
   ]);
   const switches = new Map([
     ["--no-install-leither", "-NoInstallLeither"],

package/dist/lifedrive-bundle.tar.gz

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/lifedrive-bundle.tar.gz
-size: 44139710 bytes
-sha256: 134de0bb85330eb3192e837e5054074969a80cbb4eaa1ee0b7870e55b9a3b310
+size: 44204388 bytes
+sha256: b1d6c652dbda51b836a30778abb722774fd28559373cee7efe2670991d7297b7

package/dist/lifedrive-bundle.tar.gz.sha256

@@ -1 +1 @@
-134de0bb85330eb3192e837e5054074969a80cbb4eaa1ee0b7870e55b9a3b310  lifedrive-bundle.tar.gz
+b1d6c652dbda51b836a30778abb722774fd28559373cee7efe2670991d7297b7  lifedrive-bundle.tar.gz

package/dist/lifedrive-install.ps1

@@ -8,6 +8,7 @@ param(
     [switch]$LeitherService,
     [switch]$Upgrade,
     [switch]$Household,
+    [string]$RecoverDevice,
     [switch]$Help
 )
 
@@ -28,6 +29,7 @@ Windows options:
   --leither-service         Configure Leither startup only.
   --upgrade                 Upgrade an existing Windows LePan installation.
   --household               Set up household users or renew an unclaimed setup invitation.
+  --recover-device USER     Reconnect a phone to an existing account name or user ID.
 
 Run Windows Terminal or PowerShell as Administrator. Windows setup supports
 native x64 Windows 10/11 and Windows Server; WSL and Git Bash are not required.
@@ -35,6 +37,10 @@ native x64 Windows 10/11 and Windows Server; WSL and Git Bash are not required.
 }
 
 if ($Help) { Show-Usage; return }
+if ($RecoverDevice) {
+    if ($Upgrade -or $LeitherService) { throw "Use --recover-device separately from --upgrade and --leither-service." }
+    $Household = $true
+}
 if ($Upgrade -and $LeitherService) { throw "Use -Upgrade and -LeitherService separately." }
 if ($StorageMaxGB -lt 0) { throw "Leither storage must be a positive whole number of gigabytes." }
 if ($StorageMaxGB -eq 0 -and $env:LIFEDRIVE_STORAGE_MAX_GB) {
@@ -469,7 +475,7 @@ if ($Upgrade) {
     return
 }
 try {
-    & (Join-Path $root "lifedrive-identity\setup-node.ps1") -LeitherRoot $root
+    & (Join-Path $root "lifedrive-identity\setup-node.ps1") -LeitherRoot $root -RecoverDevice $RecoverDevice
 } catch {
     if ($identityTaskStopped) {
         try { Start-ScheduledTask -TaskName $identityTaskName } catch {}

package/dist/lifedrive-install.sh

@@ -12,6 +12,7 @@ LEITHER_SERVICE_ONLY=0
 LEITHER_SERVICE_BOOTSTRAPPED=0
 HOUSEHOLD_CONFIG=""
 HOUSEHOLD_SETUP=0
+RECOVER_DEVICE=""
 STORAGE_MAX_GB="${LIFEDRIVE_STORAGE_MAX_GB:-}"
 setup_command_args=()
 setup_arg_count=0
@@ -29,6 +30,7 @@ Installer options:
   --release-base URL        Alternate GitHub Release asset base URL.
   --upgrade                 Upgrade an existing LePan without changing device authorization.
   --household              Set up household users or renew an unclaimed setup invitation.
+  --recover-device USER    Reconnect a phone to an existing account, using its name or user ID.
   --household-config FILE   Install mobile-led household setup using a private service configuration.
 
 Setup options are forwarded to lifeDrive-setup.sh. Common examples:
@@ -53,6 +55,12 @@ while (( $# )); do
     --household)
       HOUSEHOLD_SETUP=1
       ;;
+    --recover-device)
+      shift
+      [[ $# -gt 0 && -n "$1" && "$1" != --* ]] || { echo "--recover-device requires an existing account name or user ID" >&2; exit 2; }
+      RECOVER_DEVICE="$1"
+      HOUSEHOLD_SETUP=1
+      ;;
     --household-config)
       shift
       [[ $# -gt 0 && -f "$1" ]] || { echo "--household-config requires a configuration file" >&2; exit 2; }
@@ -103,6 +111,10 @@ while (( $# )); do
   shift
 done
 
+if [[ -n "$RECOVER_DEVICE" ]] && (( operation_count )); then
+  echo "Use --recover-device separately from --upgrade and device-management options." >&2
+  exit 2
+fi
 if (( operation_count > 1 )); then
   echo "Choose only one of --upgrade, --add-device, --list-devices, or --revoke-device." >&2
   exit 2
@@ -942,7 +954,7 @@ chmod 700 "$LEITHER_WORKDIR/lifeDrive/"*.sh
 export LIFEDRIVE_WORKDIR="$LEITHER_WORKDIR"
 export LIFEDRIVE_LEITHER_PATH="$LEITHER_WORKDIR/Leither"
 if (( HOUSEHOLD_SETUP )); then
-  /bin/bash "$LEITHER_WORKDIR/lifedrive-identity/setup-node.sh" "$LEITHER_WORKDIR"
+  /bin/bash "$LEITHER_WORKDIR/lifedrive-identity/setup-node.sh" "$LEITHER_WORKDIR" "$RECOVER_DEVICE"
   exit 0
 fi
 if [[ -n "$HOUSEHOLD_CONFIG" ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inoku/lepan",
-  "version": "0.7.66",
+  "version": "0.7.69",
   "description": "Install LePan and its Leither runtime on Linux, macOS, or Windows",
   "os": [
     "linux",