143 lines
4.1 KiB
Markdown
143 lines
4.1 KiB
Markdown
# Chapter 2 — Blueprints: architecture and trust
|
||
|
||
This chapter is the **aerial view**: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.
|
||
|
||
---
|
||
|
||
## 1. Two applications, one protocol
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph publishers [Publish side]
|
||
Seeder[bare-os-seeder]
|
||
SysImg[System Hyperdrive]
|
||
Seeder --> SysImg
|
||
end
|
||
subgraph network [Hyperswarm]
|
||
Topic[bare-os-v1 topic]
|
||
Disc[Drive discovery keys]
|
||
end
|
||
subgraph consumers [Boot side]
|
||
Booter[bare-os-booter]
|
||
PeerDisk[SwarmDisk MBR + blocks]
|
||
Booter --> PeerDisk
|
||
end
|
||
Seeder --> Topic
|
||
Booter --> Topic
|
||
SysImg --> Disc
|
||
Booter --> Disc
|
||
```
|
||
|
||
- The **seeder** is the **publisher** of the OS image (plus MBR in a small RAM map).
|
||
- The **booter** is a **consumer** that refuses to invent a local copy: it **must** see peers.
|
||
|
||
---
|
||
|
||
## 2. Two drives on the booter
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph booterProcess [Booter process]
|
||
VFS[VFS layer]
|
||
Sys[System Hyperdrive]
|
||
Pers[Personal Hyperdrive]
|
||
VFS -->|"paths outside HOME"| Sys
|
||
VFS -->|"HOME and below"| Pers
|
||
end
|
||
```
|
||
|
||
**Trust model (pragmatic):**
|
||
|
||
- **System drive** content is **whatever replicated from the swarm** matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”
|
||
- **Personal drive** is **your** namespace (Corestore `bare-os-personal-v1`). It holds secrets, cron, dotfiles, HDMS registry, vault snapshots.
|
||
|
||
---
|
||
|
||
## 3. Protocol, MBR, and discovery
|
||
|
||
The shared package **bare-os-protocol** pins:
|
||
|
||
- `TOPIC_STRING === 'bare-os-v1'`
|
||
- `topicKey()` = `crypto.hash(b4a.from(TOPIC_STRING))`
|
||
- MBR layout: **512 bytes**, magic **`BIOS`**, primary key at offset **8**, optional failover keys at **40** and **72**
|
||
|
||
MBR layout (512 bytes, see `bare-os-protocol/constants.js`):
|
||
|
||
- Bytes **0–3**: `BIOS` magic
|
||
- Bytes **8–39**: primary system Hyperdrive public key
|
||
- Bytes **40–71**, **72–103**: optional additional keys
|
||
|
||
Protomux channel **`bare-os-v1`** carries:
|
||
|
||
- Block read requests (MBR and any indexed RAM the seeder exposes)
|
||
- Hyperdrive **replication** on the same socket
|
||
- Stubs for gossip, search, RPC (see `packages/bare-os-protocol/lib/channel.js`)
|
||
|
||
---
|
||
|
||
## 4. Execution stack inside the booter
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Init[index.js main]
|
||
Splash[Boot splash TTY]
|
||
Swarm[Hyperswarm + SwarmDisk]
|
||
ExecK[executeKernel]
|
||
Repl[Kernel REPL session]
|
||
Init --> Splash
|
||
Init --> Swarm
|
||
Swarm --> ExecK
|
||
ExecK --> Repl
|
||
Repl --> Kernel["runKernelFromSource /boot/init.js"]
|
||
Kernel --> Shell["execLine → execShellLine"]
|
||
Shell --> Bin["runBinCommand / paths / PATH"]
|
||
```
|
||
|
||
**Kernel** and **/bin** scripts are **not** separate processes. They are **`AsyncFunction`** closures in the **same** JS realm as the booter, with a **synthetic** `ctx` instead of syscalls.
|
||
|
||
---
|
||
|
||
## 5. Services after the console exists
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Session[createKernelReplSession]
|
||
Console[ctx.console = session.console]
|
||
Initd[startBareInitd]
|
||
Logger[kernel-logger wraps log/error]
|
||
Cron[bare-cron setInterval]
|
||
Session --> Console
|
||
Console --> Initd
|
||
Initd --> Logger
|
||
Initd --> Cron
|
||
```
|
||
|
||
`stopBareInitd()` runs from **REPL session cleanup** so timers do not leak across session restarts.
|
||
|
||
---
|
||
|
||
## 6. Identity states
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Guest
|
||
Guest --> Unlocked: login / login --new
|
||
Unlocked --> Guest: logout
|
||
Unlocked --> Unlocked: HDMS active after unlock
|
||
```
|
||
|
||
- **Guest**: fixed `HOME=/home/guest`, read-oriented personal tree policy for some operations.
|
||
- **Unlocked**: `HOME` under `/home/<pubkey-prefix>`, HDMS can attach writable drives, `crontab` install/remove allowed.
|
||
|
||
---
|
||
|
||
## 7. What is _not_ here (boundary)
|
||
|
||
- No hardware kernel, no MMU, no ELF loader for native `/bin`.
|
||
- No container cgroup isolation—**commands are JS** with full host capability **of the Pear/Bare process**.
|
||
- No global consensus: **two booters** can diverge if they replicate **different** forks of the same discovery key (Hyperdrive versioning is a separate concern).
|
||
|
||
---
|
||
|
||
[← Introduction](01-introduction.md) · [Handbook home](README.md) · [Next: Protocol and disk →](03-protocol-and-disk.md)
|