181 lines
5.7 KiB
Markdown
181 lines
5.7 KiB
Markdown
# Chapter 2 — Blueprints: architecture and trust
|
||
|
||
**Time to read:** about 10 minutes. **Prerequisites:** [Chapter 1](01-introduction.md) vocabulary.
|
||
|
||
This chapter is the **aerial view**: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.
|
||
|
||
For a **comparison to classic images and security limits**, see [Preface — Comparison frame and Security](00-preface.md#comparison-frame-not-marketing).
|
||
|
||
---
|
||
|
||
## 0. Boot path from seeder to shell
|
||
|
||
The following is the **conceptual** ordering (not every substep on the wire). It complements the reference sequence diagram in [Architecture: end-to-end data flow](../docs/reference/architecture-data-flow.md).
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
S[Seeder publishes system drive + MBR block 0]
|
||
W[Hyperswarm topic bare-os-v1]
|
||
B[Booter finds peer]
|
||
M[Read MBR parse keys]
|
||
D[Open system Hyperdrive replicate]
|
||
P[Create personal Hyperdrive]
|
||
K[executeKernel load init.js]
|
||
Sh[Shell and /bin]
|
||
S --> W
|
||
W --> B
|
||
B --> M
|
||
M --> D
|
||
D --> P
|
||
P --> K
|
||
K --> Sh
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
- Gossip bitfield (**message 2**), manifest **search** (**3/4**), and **`bare_os.*`** **RPC** (**5/6**) on the seed channel (see `packages/bare-os-protocol/lib/channel.js`; [Kernel extensions](../docs/reference/kernel-extensions.md))
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
Guest and unlocked sessions share the **same booter process**; the state machine below is about **environment and policy**, not separate OS processes.
|
||
|
||
```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.
|
||
|
||
Full story: [Chapter 5 — Identity, vault, HDMS](05-identity-vault-and-hdms.md).
|
||
|
||
---
|
||
|
||
## 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**.
|
||
- **Future:** stronger isolation would compose **Bare workers**, **Pear runtime isolates**, or **bare-kit**-style embeds; the stock **`ctx.bareOsSandboxRunScript`** hook is a documented placeholder until then (see developer guide security chapter).
|
||
- No global consensus: **two booters** can diverge if they replicate **different** forks of the same discovery key (Hyperdrive versioning is a separate concern).
|
||
|
||
---
|
||
|
||
**Next:** [Chapter 3 — Protocol and disk](03-protocol-and-disk.md)
|
||
|
||
**Related:** [Preface](00-preface.md) · [Handbook home](README.md) · [Kernel extensions](../docs/reference/kernel-extensions.md)
|
||
|
||
_Experimental research software, not a production OS. Apache-2.0 — [LICENSE](../LICENSE)._
|