79 lines
4.6 KiB
Markdown
79 lines
4.6 KiB
Markdown
# 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)
|
||
- [Where state lives on disk (mental model)](#where-state-lives-on-disk-mental-model)
|
||
- [Passphrases, backups, and data loss](#passphrases-backups-and-data-loss)
|
||
|
||
---
|
||
|
||
## 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).
|
||
|
||
---
|
||
|
||
## Where state lives on disk (mental model)
|
||
|
||
Think in **two layers**:
|
||
|
||
1. **Hyperdrive blocks** replicated through Corestore — durable bytes identified by keys and discovery topics, not by a traditional host path.
|
||
2. **VFS paths** — what you see in the shell (**`/home/guest`**, **`/.bare/account`**, **`/mnt/...`**) as the booter merges drives and synthetic mounts.
|
||
|
||
Guests can write under guest **`HOME`** and read shared system content. **Unlocked** users get a different **`HOME`** subtree and can manipulate HDMS registry entries that survive across sessions. If you are debugging “where did my file go?”, check both **`pwd`** and whether you **logged out** (which clears in-memory keys even when ciphertext remains on disk).
|
||
|
||
---
|
||
|
||
## Passphrases, backups, and data loss
|
||
|
||
**`login --new`** creates keys derived from your passphrase. If you **forget** the passphrase, ciphertext under **`/.bare/`** is not recoverable by design. If you **lose** the personal drive replication (new machine, wiped Corestore) without exporting keys or vault snapshots, you also lose access. For operational guidance beyond this overview, read [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md) and the handbook’s identity chapter.
|
||
|
||
---
|
||
|
||
## 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)_
|