@inoku/lepan 0.0.1 → 0.7.59

package/README.md

@@ -0,0 +1,177 @@
+# LePan / LifeDrive Installer
+
+This public repository contains versioned LifeDrive installation assets built from the private LifeAlbum source repository.
+
+For an ordinary Windows or macOS installation, download the matching package from LePan's Cloudflare-backed download URLs:
+
+- **Windows 10/11 or Windows Server (x64):** [LePan-Setup-windows-x64.exe](https://lepan.org/download/LePan-Setup-windows-x64.exe)
+- **Mac with Apple silicon:** [LePan-Setup-macos-arm64.pkg](https://lepan.org/download/LePan-Setup-macos-arm64.pkg)
+- **Mac with an Intel processor:** [LePan-Setup-macos-x64.pkg](https://lepan.org/download/LePan-Setup-macos-x64.pkg)
+
+The native packages contain a private Node.js runtime used only by LePan Setup. They do not install Node.js system-wide or replace an existing Node.js installation. Windows asks for Administrator approval. macOS installs **LePan Setup** in Applications, opens Terminal, and asks for an administrator password when registering background services and allowing Leither through the Application Firewall. Follow the on-screen prompts to choose storage and create the first mobile invitation.
+
+**New to LifeDrive?** Read the [user manual](USER_MANUAL.md): installing and upgrading a node, users and devices, and what to do when a device or an identity is lost.
+
+## Command-line installation
+
+Linux users and experienced Mac users can install Node.js 18 or later and run:
+
+```bash
+npx --yes @inoku/lepan
+```
+
+The npm package supports Linux and macOS on Apple Silicon/ARM64 and Intel/AMD64, plus native x64 Windows. Run it as your normal user on Linux/macOS or from an Administrator Windows Terminal on Windows. Fresh setup installs and starts Leither when it is missing. WSL, Git Bash, Homebrew, and third-party Windows service wrappers are not required. A fresh Windows node defaults to
+`%ProgramData%\LifeDrive\Leither`, uses the native official x64 Leither build,
+and activates household users during installation.
+
+To upgrade an existing key-auth installation without changing its authorized devices, public address, or drive data, run:
+
+```bash
+npx --yes @inoku/lepan@latest --upgrade
+```
+
+The installer reuses a running Leither node and finds its directory automatically. If none is running, Linux/macOS fresh setup first looks for Leither in the selected directory, the current directory, or on `PATH`; otherwise it uses `~/.local/share/lifedrive/leither`. Windows uses `%ProgramData%\LifeDrive\Leither` unless `--leither-root` selects another directory. It downloads the matching binary from the [official Leither distribution](http://vzhan.cn/#start.html), verifies its SHA-256 checksum, initializes local configuration and keys, installs boot startup, and waits for the managed process and local version endpoint before continuing. Existing executables, configuration, and keys are never replaced.
+
+When the installer creates a new node, it shows the free space on the selected drive and asks how many whole decimal gigabytes Leither may use. The default is **100 GB**. This is a node-wide maximum covering LePan and every other application stored by that Leither node; it does not reserve or preallocate the space. The installer refuses a value larger than the space currently available and saves the choice before Leither first starts. For unattended setup, pass `--storage-max-gb GB` or set `LIFEDRIVE_STORAGE_MAX_GB`. Existing nodes and upgrades keep their current limit; change those from LePan Settings.
+
+Choose another empty directory for a fresh node, select a stopped node, or select among multiple running instances:
+
+```bash
+npx --yes @inoku/lepan --leither-root /path/to/leither
+```
+
+For example, create a fresh node with a 250 GB maximum:
+
+```bash
+npx --yes @inoku/lepan --leither-root /path/to/leither --storage-max-gb 250
+```
+
+Use `--no-install-leither` to require an already running node. Upgrades always require a running node and never install or start Leither. The legacy browser-device management options remain Linux/macOS-only; Windows uses household management from a paired phone. A nonempty directory without a Leither executable is left untouched. New nodes use port 4800 by default; a port conflict stops setup with instructions. Leither V0.24.11 or newer is required; older existing nodes must be upgraded separately.
+
+### Leither starts automatically at boot
+
+Fresh setup installs boot startup and crash recovery. Linux/macOS request `sudo`
+to run Leither as the invoking account through systemd or a system
+LaunchDaemon. Windows uses a SYSTEM Scheduled Task and grants that task access
+to the selected node directory. Every platform sets the working directory and
+runs `Leither run` in the foreground so the manager can supervise it directly.
+
+| Platform | Service definition | Status and logs |
+|---|---|---|
+| Linux | `/etc/systemd/system/lifedrive-leither.service` | `systemctl status lifedrive-leither.service`; `journalctl -u lifedrive-leither.service` |
+| macOS | `/Library/LaunchDaemons/uk.inoku.leither.plist` | `sudo launchctl print system/uk.inoku.leither`; `<Leither root>/leither-service.log` |
+| Windows | Task Scheduler: `LifeDrive Leither` | Task Scheduler history; `Get-ScheduledTask -TaskName "LifeDrive Leither"` |
+
+To configure only Leither's startup without changing LifeDrive files:
+
+```bash
+npx --yes @inoku/lepan --leither-service --leither-root /path/to/leither
+```
+
+Run this as the node's normal user, not with `sudo npx`; on Windows, use an Administrator terminal. It can enable an already running service installed by this package without restarting it. A process started manually or by another service manager is left untouched: keep that manager, or stop it in a maintenance window and disable its old boot registration before adopting the package's service. A service/task definition with different settings or another node/account is never overwritten. Normal LifeDrive upgrades do not restart Leither. Systems without systemd can supply a running node through their own manager and use `--no-install-leither`.
+
+The npm package contains the versioned installer, checksum, and LifeDrive bundle. The Windows and macOS packages contain the same payload plus a checksum-verified Node.js 22 runtime from nodejs.org. After the package is downloaded, LifeDrive's files do not depend on GitHub's release-asset network. Installing a missing Leither runtime additionally needs access to `vzhan.cn`. Its official distribution currently uses HTTP with a same-source checksum; that checksum detects corrupt downloads and is not an authenticated signature. If npm is unavailable on Linux/macOS, use the GitHub release bootstrap directly (Node.js is still required):
+
+```bash
+curl -fLO https://github.com/cfa532/lifedrive-installer/releases/latest/download/lifedrive-install.sh
+chmod +x lifedrive-install.sh
+./lifedrive-install.sh
+```
+
+The bootstrap verifies `lifedrive-bundle.tar.gz` against its SHA-256 file, installs it below the detected Leither root, and runs the interactive terminal setup. The npm launcher reads those assets from its own package; the standalone bootstrap downloads them from the matching GitHub Release. All installer options after the npm package name pass through to that bootstrap.
+
+The Linux/macOS legacy browser-owner setup uses the built-in AV1 registration endpoint and does not ask users for a service URL, AV1 login, or developer-issued code. Windows skips that shell-only flow and uses household pairing.
+
+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.
+
+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.
+
+## Household users
+
+This release includes the household identity service for Linux, macOS, and x64 Windows. Existing installations retain their application MID. On Linux/macOS, an ordinary `--upgrade` installs the service files but does not automatically activate household mode. Fresh Windows setup uses household mode by default because the legacy browser-owner tools are shell-only.
+
+Household activation uses the existing Leither node address. On Linux/macOS, run the matching release with `--upgrade --household`. Windows performs the same private configuration and invitation flow during fresh setup. No additional public hostname or TLS certificate is required. On iPhone or Android, use Settings → Set up users. Each user starts with an empty personal drive; older files are not imported.
+
+On Windows, Task Scheduler entries named `LifeDrive Leither` and
+`LifeDrive Identity` run as SYSTEM at startup with their working directories set
+to the selected Leither root. Setup also adds a Windows Firewall rule for the
+configured Leither port. The loopback identity port 4811 is not opened publicly.
+
+On macOS, setup registers the selected Leither executable with the Application
+Firewall, allows incoming connections, and verifies the rule. The system's
+**Block all incoming connections** setting and managed firewall policy can still
+override that application rule. Setup also installs
+`/Library/LaunchDaemons/uk.inoku.lifedrive-identity.plist`. The identity service runs as your Leither account, starts at boot, and remains running after Terminal closes or you log out. Leither must also be running for LifeDrive to work. Logs are stored in `<Leither root>/.lifedrive-household/identity.log`. Stop any previously started foreground identity service before activating the daemon. The advanced `--household-config` option continues to print a manual start command for custom configurations. Router port forwarding remains a separate manual step.
+
+The shared browser URL remains `http://drive.lepan.org/?n=<node-id>`. Native identities persist; a paired browser stays signed in until it goes seven days without use. Direct setup requires Leither to enforce private MiMei access and stops if its checks cannot confirm that. See the source deployment notes for the HTTP transport limitations.
+
+Once synchronized, Leither follows new publications of the same application MID. The household browser also loads that published application. Updates to the separate identity-service executable require another npm upgrade; the Windows upgrader restarts only its identity task, while Linux/macOS operators restart their identity service. The installer never restarts Leither. Install mobile application updates separately.
+
+After upgrading on macOS, restart only the identity service:
+
+```bash
+sudo launchctl kickstart -k system/uk.inoku.lifedrive-identity
+sudo launchctl print system/uk.inoku.lifedrive-identity
+curl --fail http://127.0.0.1:4811/health
+```
+
+## iPhone photo backup with your own domain
+
+The photo HTTPS helper supports a domain controlled by the node owner. Use a
+release whose `lifedrive-identity/setup-photo-https.sh --help` lists `--domain`.
+Automatic certificate management is built into the identity service on Linux
+and macOS; nginx, Certbot and DNS-provider credentials are not required. It is
+separate from ordinary household pairing and backup.
+
+Create a dedicated A record, such as `photos.example.com`, pointing to the node's
+public IPv4 address. Any DNS provider is supported; on Cloudflare use **DNS only**.
+Public TCP port 443 must reach the identity service's private photo listener.
+The default router mapping is WAN 443 → node 8443. Port 80 is not needed.
+Carrier-grade NAT requires a separately configured reachable endpoint or
+TLS pass-through tunnel; creating DNS does not provide connectivity.
+
+Wait until at least one iPhone is paired with the node and its owner intends to
+enable photo sync before creating this record. Node installation and pairing do
+not enable iOS background photo upload. The app registers it only after explicit
+Photos consent and a successful HTTPS readiness response from the paired node.
+
+From the installed node's `lifedrive-identity` directory, run:
+
+```bash
+bash setup-photo-https.sh --domain photos.example.com --agree-acme-terms
+```
+
+On Windows, open an Administrator PowerShell in that directory and run:
+
+```powershell
+.\setup-photo-https.ps1 -Domain photos.example.com -AgreeAcmeTerms
+```
+
+The Windows helper opens only the private photo-listener port (8443 by default)
+in Windows Firewall. The router must still forward public TCP 443 to that private
+port. The ordinary Leither port remains separately forwarded; port 4811 and
+public port 80 are not needed.
+
+Replace the example hostname with yours and run the command as the Leither
+account. This accepts Let's Encrypt's subscriber agreement, obtains a certificate
+through TLS-ALPN-01 and enables automatic renewal. Use
+`--photo-listen ADDRESS:PORT` only to change the default private listener. It restarts only
+LifeDrive identity and verifies the trusted HTTPS endpoint. Leither is not
+restarted. The ACME account and certificates stay in the private identity state;
+none is included in the installer package.
+
+The iPhone needs a LePan build containing the Photos background-upload extension
+and iOS 26.5 or later. Open **Settings → Auto sync**, enable Photos with **Full
+Access**, and check the photo-change backup status below **Wi-Fi only**. Paired
+phones discover the address from their node; no address needs to be entered on
+each phone. iOS decides when uploads run. File and Android backup use their
+existing connection.
+
+To change domains, finish pending uploads, point the new name at the node and
+rerun the helper with that name. Reopen LePan on each phone after setup. The old
+photo hostname is no longer served after successful activation; jobs already
+queued to that address may require retries. The helper restores the previous
+identity configuration if activation fails. Old DNS records and private ACME
+cache entries are not deleted automatically.

package/USER_MANUAL.md

@@ -0,0 +1,399 @@
+# LifeDrive User Manual
+
+**Audience:** people who run a LifeDrive node, and the people who use it.
+**Covers:** installing LifeDrive on a node, upgrading it, how identity works, and what to do when a device or an identity is lost.
+**Current release:** 0.7.35 (`npm view @inoku/lepan version` shows the latest).
+
+LifeDrive is a private drive that runs on your own Leither node. Your files stay on
+that node; phones, tablets and browsers connect to it directly. There is no
+LifeDrive account on the Internet and no password: each device holds its own key,
+and a device you already trust approves every new one.
+
+---
+
+## 1. Before you start
+
+A LifeDrive node needs:
+
+| Requirement | Notes |
+|---|---|
+| A Linux, macOS, or Windows computer | Fresh setup installs Leither if missing, or reuses an existing node. Linux/macOS support AMD64 and ARM64; Windows uses the official x64 build. |
+| Node.js 18 or later | Included privately in the Windows and macOS packages. Install it yourself only for the Linux or advanced macOS command-line method. |
+| Platform tools | Linux/macOS use `bash`, `curl`, `tar`, and a SHA-256 tool. macOS also uses its built-in Application Firewall tool. Windows uses built-in Windows PowerShell, `tar.exe`, and Windows Firewall tools. |
+| An appropriate account | Linux/macOS use the normal Leither account. macOS requests `sudo` for service and firewall registration. Windows setup must run from an Administrator terminal. |
+| A startup manager | systemd on Linux, launchd on macOS, or Task Scheduler on Windows starts the node at boot and recovers it after crashes. |
+| The LifeDrive app on your phone | iPhone or Android. The first user is created from a phone. |
+
+LifeDrive never stops or restarts Leither. If more than one Leither node runs on
+the machine, the installer lists them and asks you to choose one with
+`--leither-root <directory>`.
+
+---
+
+## 2. Install LifeDrive on a node
+
+### 2.1 Install LifeDrive
+
+For Windows or macOS, download the installer for the computer:
+
+- Windows x64: [LePan-Setup-windows-x64.exe](https://lepan.org/download/LePan-Setup-windows-x64.exe)
+- Mac with Apple silicon: [LePan-Setup-macos-arm64.pkg](https://lepan.org/download/LePan-Setup-macos-arm64.pkg)
+- Mac with an Intel processor: [LePan-Setup-macos-x64.pkg](https://lepan.org/download/LePan-Setup-macos-x64.pkg)
+
+On Windows, open the downloaded setup file and approve the Administrator prompt. On macOS, open the package; it installs **LePan Setup** in Applications and opens a Terminal window. Follow the prompts to choose the storage limit and create the first private mobile invitation. The package carries its own Node.js runtime and does not install or replace Node.js for other applications.
+
+Linux users and experienced Mac users can instead install Node.js 18 or later and use Terminal. On the node, as the account that runs Leither:
+
+```bash
+npx --yes @inoku/lepan@latest
+```
+
+The same command also remains available from an Administrator Windows Terminal for advanced use. WSL and Git Bash are not required.
+
+The installer finds an existing running Leither node. If none is running, it
+reuses Leither in the selected directory, current directory, or `PATH`, or
+downloads and verifies the official runtime for your machine. A new node is
+created in `~/.local/share/lifedrive/leither` on Linux/macOS or
+`%ProgramData%\LifeDrive\Leither` on Windows, initialized with its own private
+keys, and prepared for automatic boot startup. Before starting the service,
+setup shows the selected drive's available space and asks for the maximum space
+Leither may use. Press Enter for the 100 GB default, or enter another whole
+number of decimal gigabytes. The limit covers all data stored by that Leither
+node, including LePan; it does not preallocate the space. Setup then starts the
+service, waits for Leither's local version
+endpoint, verifies the LifeDrive archive, installs LifeDrive and runs terminal
+setup. Follow its prompts.
+
+To choose another empty directory or start a stopped existing node:
+
+```bash
+npx --yes @inoku/lepan@latest --leither-root "/path/to/leither"
+```
+
+For unattended fresh setup, supply the limit explicitly:
+
+```bash
+npx --yes @inoku/lepan@latest --leither-root "/path/to/leither" --storage-max-gb 100
+```
+
+The selected maximum cannot exceed the space currently available on that drive.
+The option applies only when the installer creates a new node. Existing nodes
+and upgrades keep their current limit; an owner can change it later in LePan
+Settings, after which Leither must be restarted.
+
+Existing Leither files are never replaced. If a directory contains files but no
+Leither executable, setup stops instead of initializing over them. Use
+`--no-install-leither` to require a running node. Upgrades and device-management
+commands always require a running node. An older existing Leither version must
+be upgraded separately to V0.24.11 or newer.
+
+Fresh Leither downloads require access to the [official distribution](http://vzhan.cn/#start.html).
+Port 4800 must be available for a new node. On Linux, inspect startup with
+`systemctl status lifedrive-leither.service` and
+`journalctl -u lifedrive-leither.service`. On macOS, use
+`sudo launchctl print system/uk.inoku.leither` and read
+`<Leither root>/leither-service.log`. The service starts at boot and continues
+after you log out. Run setup as your normal user, not with `sudo npx`; it will
+request sudo for system service and macOS Application Firewall registration.
+Setup adds Leither to the allowed incoming applications and verifies the rule.
+The macOS **Block all incoming connections** option or a managed policy can still
+override it. Router port forwarding remains a separate manual step.
+
+On Windows, setup creates the `LifeDrive Leither` and `LifeDrive Identity`
+Scheduled Tasks and an inbound Windows Firewall rule for Leither's configured
+port. The identity control port 4811 stays loopback-only and needs no router or
+firewall opening. Inspect startup with:
+
+```powershell
+Get-ScheduledTask -TaskName "LifeDrive Leither", "LifeDrive Identity"
+```
+
+To add boot startup to an existing node without changing LifeDrive files:
+
+```bash
+npx --yes @inoku/lepan@latest --leither-service --leither-root "/path/to/leither"
+```
+
+A service already installed by this package is enabled without restarting it.
+If Leither is running manually or under another manager, setup leaves it alone.
+Keep that manager, or stop the node during a maintenance window and disable its
+old boot registration before running the service-only command. Existing service
+definitions with different settings are not overwritten. Regular LifeDrive
+upgrades do not change or restart Leither's service.
+
+If a LifeDrive is already installed on this node, the installer stops and says so.
+Use the upgrade in section 3 instead.
+
+### 2.2 Turn on users and mobile setup
+
+Fresh Windows setup already performs this section and prints its invitation. On
+Linux/macOS, or when enabling household users on an existing compatible node,
+run:
+
+Still on the node:
+
+```bash
+npx --yes @inoku/lepan@latest --upgrade --household
+```
+
+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."*
+
+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.
+
+### 2.3 Create the first user from your phone
+
+Within ten minutes of the invitation being printed:
+
+1. Copy the whole invitation block from the terminal and send it to your phone, or copy it on a computer your phone shares a clipboard with.
+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 **Paste node identity** (or **Choose identity file** if you saved the invitation as a 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
+this phone is a **device manager**.
+
+You can close the setup screen without pairing to look around the app. Tapping an
+empty page, or **Settings → Set up users**, opens it again.
+
+### 2.4 If setup is interrupted
+
+| 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. |
+| 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. |
+
+### 2.5 Check that the node is healthy
+
+On the node:
+
+```bash
+systemctl status lifedrive-identity          # Linux: should be "active (running)"
+sudo launchctl print system/uk.inoku.lifedrive-identity  # macOS: should report state = running
+curl -s http://127.0.0.1:4811/health         # should print the service name and node ID
+```
+
+---
+
+## 3. Upgrade LifeDrive
+
+Upgrading replaces the LifeDrive application and the identity service program.
+**Users, device keys, files and backups are preserved.** Upgrading does not
+restart Leither.
+
+### 3.1 Upgrade the node
+
+On the node, as the account that runs Leither:
+
+```bash
+npx --yes @inoku/lepan@latest --upgrade
+```
+
+To install a specific release instead of the latest, name it, for example
+`npx --yes @inoku/lepan@0.7.35 --upgrade`. Release versions are never reused,
+so a version number always means the same files.
+
+The installer saves the previous application files to a backup directory, prints
+where, and then:
+
+```text
+LifeDrive application and identity-service files updated. Household users and keys were preserved.
+Restart only the LifeDrive identity service through its service manager to load the new binary.
+```
+
+Then restart the identity service so the new program runs:
+
+```bash
+sudo systemctl restart lifedrive-identity    # Linux
+systemctl status lifedrive-identity          # confirm it is running again
+```
+
+On macOS:
+
+```bash
+sudo launchctl kickstart -k system/uk.inoku.lifedrive-identity
+sudo launchctl print system/uk.inoku.lifedrive-identity
+curl --fail http://127.0.0.1:4811/health
+```
+
+If startup fails, inspect `<Leither root>/.lifedrive-household/identity.log`.
+Custom configurations installed with `--household-config` still use the manual
+start command printed during installation.
+
+While the service restarts, apps show a connection error for a few seconds and
+retry by themselves. Uploads and backups that were in progress resume.
+
+### 3.2 Upgrade the apps
+
+Update LifeDrive on each phone from its app store or distribution channel as
+usual. The browser client updates itself when the page is reloaded.
+
+---
+
+## 4. Identity: users, devices and invitations
+
+### 4.1 What LifeDrive keeps
+
+| Thing | What it is |
+|---|---|
+| **Node** | Your Leither server. Its identity is fixed; its network address may change without affecting you. |
+| **User** | A person with their own private drive on the node. Created once, from a phone. Users cannot see each other's files. |
+| **Administrator** | The first user. Can invite other people to create their own users. Being administrator gives no access to other users' files. |
+| **Device** | One phone, tablet, computer or browser signed in as a user. Each device has **its own key**, created on that device and never copied anywhere. |
+| **Device manager** | A device allowed to approve new devices and remove devices. Phones and tablets are managers by default; a browser is not, unless a manager promotes it. |
+
+Nothing in LifeDrive is protected by a password, and there is no "identity file"
+that can sign you in on its own. Every invitation below only *asks* to join; a
+device you already use has to approve.
+
+### 4.2 Add another of your own devices
+
+On a device manager you already use:
+
+1. Open **Settings → My devices → Pair another device**.
+2. The app creates an invitation file (`lifedrive-user.identity.json`) and opens the share sheet. Send it to the new device with AirDrop, a messaging app, or save it to Files.
+3. On the new device, open LifeDrive, choose **Settings → Set up users**, enter a device name, and import the file (**Choose identity file**).
+4. The new device shows a **match code**. On the manager, open **My devices** (pull down to refresh if needed), check that the code shown there is the same, and tap **Approve this device**.
+
+The new device opens the same drive. The invitation expires shortly after it is
+created, and a copy of it cannot be used by anyone else once your new device has
+used it.
+
+### 4.3 Sign in a browser
+
+1. On your phone, open **Settings → My devices → Pair a browser**. It shows the browser address for your node, with **Copy browser URL** and **Share browser URL**.
+2. Open that address in a browser on a computer connected to the same network. The page shows a QR code.
+3. On the phone, tap **Scan browser QR code**, scan the code, and approve.
+
+The browser gets its own session. It stays signed in until it goes seven days
+without being used, or until you remove it. A browser starts without device-manager
+rights; a manager can grant them with **Allow device management** in My devices.
+
+### 4.4 Invite another person
+
+Only the administrator can do this.
+
+1. **Settings → My devices → Invite another user** creates an invitation and opens the share sheet. Send it to the person.
+2. They install LifeDrive on their phone, open **Settings → Set up users**, enter their own name, and import the invitation.
+
+They get their own empty drive. Nothing of yours is shared with them unless you
+share a file or folder with a link.
+
+### 4.5 Manage devices
+
+In **Settings → My devices** every device of your user is listed with its name,
+type, status and last activity. A device manager can:
+
+- **Rename** a device.
+- **Remove access**: the device is signed out on its next request and can no longer read or change your drive. Files it had already downloaded stay on it.
+- **Allow device management**: give a browser manager rights.
+- **Forget**: delete the record of a device that has already lost access. This only tidies the list; it does not change anyone's access.
+
+**Removal needs a replacement already in place.** The node refuses to remove a
+device unless at least one *other* active phone (iPhone or Android) and one other
+active device manager remain, and says *"pair a replacement mobile and device
+manager first"*. This keeps you from locking yourself out, and it decides the
+order of steps in section 5.
+
+### 4.6 Forget this identity on a device
+
+**Settings → Forget this identity** deletes this device's key from the device. The
+device is no longer signed in. Your drive and your other devices are unaffected.
+To use the device again, pair it again as in 4.2 with an invitation from another
+device you still use.
+
+---
+
+## 5. Recovering a lost identity
+
+Your files live on the node, not on your phone. Losing a device does not lose
+your drive. What you can lose is **the ability to sign in** — and that depends
+on whether you still have another working device.
+
+### 5.1 You lost a device, and you still have another phone that is a device manager
+
+This is the normal case, and you can fix it yourself right away.
+
+1. On the phone you still have, open **Settings → My devices**.
+2. Find the lost device and tap **Remove access**. From its next request, the lost device can no longer reach your drive.
+3. When you have a replacement, pair it with **Pair another device** (section 4.2).
+
+Do this even if you expect to find the device again: pairing it again later takes
+a minute.
+
+If the lost device was your **only phone** and what you still have is a browser
+or a computer, **Remove access** is refused until another phone is paired. Follow
+5.2.
+
+### 5.2 You lost your only phone, but a browser is still signed in
+
+A browser can only approve new devices if it was given **Allow device management**
+beforehand. If it was, the order matters, because the lost phone cannot be removed
+while it is your only phone:
+
+1. In the browser, open **My devices → Pair another device** and save the invitation.
+2. Import it on the new phone (**Settings → Set up users → Choose identity file**) and approve the match code in the browser.
+3. Now remove the lost phone: **My devices → Remove access**.
+
+Until step 3 the lost phone still has access, so do this as soon as you can.
+
+If the browser was not a device manager, it can still read and download your
+files, but it cannot approve a new phone. Continue with 5.3.
+
+### 5.3 You lost every device
+
+There is no recovery code, recovery file or password to fall back on. The app
+used to offer a recovery file; that option has been removed, because a file that
+can restore an account on its own is as dangerous to lose as the account itself.
+
+What remains true:
+
+- **Your files are safe on the node.** Nothing is deleted when devices are lost.
+- **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.
+
+### 5.4 Prevent lockout
+
+- **Pair at least two phones as device managers**, for example an iPhone and an Android phone, or your phone and a family member's old phone kept at home. (Tablets count as phones here only if they run the iPhone or Android app.) This alone turns every "lost device" into the easy case in 5.1.
+- If you mainly use a computer, give its browser **Allow device management** so it can stand in for a lost phone.
+- Remove access for a lost device as soon as you notice, from any device you still have.
+
+### 5.5 For node operators: protect the node's identity data
+
+The directory `<Leither root>/.lifedrive-household/` holds each user's storage
+authority, the device authorization journal, the node's transport key and staged
+uploads that have not been committed yet.
+
+- **Back it up** together with the Leither node's data. Without it, the drives on the node cannot be used by their owners even though the files still exist.
+- **Keep it private.** Anyone with a copy holds every user's storage authority. Never put it in a shared folder, a public repository or an application bundle.
+- **Do not restore an old copy over a running service** to undo a device removal: authorization only moves forward, and an old copy can re-open access that was deliberately removed.
+
+---
+
+## 6. Quick reference
+
+| Task | Where |
+|---|---|
+| Install on a node | `npx --yes @inoku/lepan@latest`; Linux/macOS then run it with `--upgrade --household` |
+| Upgrade a node | `npx --yes @inoku/lepan@latest --upgrade`; restart only identity if the platform installer does not do so |
+| Check the node | Check the platform service/task and open `http://127.0.0.1:4811/health` locally |
+| Create the first user | Phone: **Settings → Set up users → Paste node identity** |
+| Add your own device | Existing device: **My devices → Pair another device**; new device: **Set up users → Choose identity file**; approve the match code |
+| Sign in a browser | Phone: **My devices → Pair a browser**; open the address it shows; **Scan browser QR code** |
+| Invite another person | Administrator: **My devices → Invite another user** |
+| Lost a device | Another phone: **My devices → Remove access**, then pair a replacement. Lost your only phone: pair the replacement first (section 5.2) |
+| Lost every device | Contact the node operator (section 5.3) |