docs updates

2026-04-04 08:31:39 -04:00
parent 0e53351349
commit 081e4c587c
64 changed files with 2052 additions and 1273 deletions
@@ -0,0 +1,59 @@
+# Chapter 5 — Home, identity, and vault
+
+**Prerequisites:** [Shell, PATH, and scripts](04-shell-path-and-scripts.md). **Time to read:** about seven minutes.
+
+---
+
+## On this page
+
+- [Guest session](#guest-session)
+- [Logging in](#logging-in)
+- [Vault snapshots](#vault-snapshots)
+- [HDMS and extra drives](#hdms-and-extra-drives)
+- [Where to read the full story](#where-to-read-the-full-story)
+
+---
+
+## Guest session
+
+On a fresh boot the session is **guest**: **`USER`** and **`HOME`** point at **`guest`** under **`/home/guest`**, and there is no Ed25519 identity material in the environment. You can still **read** the system image and **write** guest-scoped areas on the **personal** Hyperdrive.
+
+Logical **`$HOME`** and **`/var/log`** map into stable prefixes on the personal drive so guest data and unlocked-user data stay separated. Shared machine metadata (**`/.bare/account`**, **`/.bare/hdms/`**, vault blobs) lives outside those per-session home prefixes.
+
+---
+
+## Logging in
+
+**`login`** prompts for a passphrase. If an account already exists at **`/.bare/account`**, the booter decrypts it and derives session keys. **`login --new`** creates a **new** Ed25519 keypair and writes a versioned on-disk blob.
+
+After a successful login, **`HOME`** moves under **`/home/<public-key-prefix>`**, **`BARE_OS_PUBLIC_KEY`** is set, and optional **HDMS** features become available for managing extra drives. **`logout`** clears sensitive state and returns you to **guest**. **`logout --save`** can combine logout with vault snapshotting (see below).
+
+Cryptographic details are implementation-specific; this manual stays at the behavior level. For prose-level crypto and flow diagrams, read [Handbook — Chapter 5](../handbook/05-identity-vault-and-hdms.md).
+
+---
+
+## Vault snapshots
+
+**`savevault`** and **`logout --save`** can store **encrypted snapshots** of selected paths under **`/.bare/vault/`**. Vault security depends on your **passphrase strength**, **who can replicate** your personal drive, and your **backup** practices. Treat vault blobs as sensitive ciphertext, not as a substitute for off-machine backups if you care about durability.
+
+---
+
+## HDMS and extra drives
+
+**HDMS** (Hyperdrive management) lets an **unlocked** user register and mount additional Hyperdrives, exposed under **`/mnt/<label>`**. Guests may see mounts that are already open but cannot mutate the registry until **`login`** succeeds.
+
+Pairing hints for operators can appear under **`/proc/bare_os/hdms_hints.json`** when the host sets **`BARE_OS_AUTOPASS_INVITE_URL`**. The guest does **not** open arbitrary network URLs by itself; automation on the host consumes those hints.
+
+For subcommands and examples, use **`man hdms`** after seeding an image with a current **`man.json`** build.
+
+---
+
+## Where to read the full story
+
+- [Handbook — Chapter 5: Identity, vault, and HDMS](../handbook/05-identity-vault-and-hdms.md)
+- [docs/reference — Booter package](../docs/reference/package-bare-os-booter.md) (identity-related sections)
+- [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md)
+
+---
+
+_Previous: [Chapter 4](04-shell-path-and-scripts.md)_ · _Next: [Chapter 6 — Help, man, and documentation map](06-help-man-and-documentation-map.md)_