bare-operating-system/packages/bare-os-protocol

bare-os-protocol

Shared wire format and constants for the Bare operating system monorepo: Hyperswarm topic, 512-byte MBR layout, and Protomux bare-os-v1 seed-channel message shapes.

When to use: depend on this package when building a compatible seeder or booter, fuzz-testing MBR/topic stability, or reusing kernel feature bit masks in tooling.

Documentation: Concepts — P2P · Protocol reference · Handbook ch.3 · Kernel extensions.

flowchart LR
  T[bare-os-v1 topic]
  C[Protomux channel]
  M[MBR block 0]
  T --> C
  M --> H[Hyperdrive keys]

What it provides

• PROTOCOL_NAME, TOPIC_STRING — Protomux channel name and swarm topic input string (bare-os-v1)
• topicKey() — 32-byte topic for swarm.join()
• BLOCK_SIZE, MBR_MAGIC — 512-byte MBR, magic BIOS at offset 0
• buildMbr / parseMbr — Pack/unpack primary + optional failover Hyperdrive keys
• setupSeedChannel — Wire Protomux messages 0–6 for RAM block reads, gossip bitfield, manifest path search, RPC (incl. bare_os.capabilities with bits … bits11 when non-zero, typed errors for unknown RPC methods, bare_os.replication_status, bare_os.replication_queue, extended RPC short names in seed-rpc-methods.js, bare_os.gossip), and drive.replicate. Message 0/1 is role-agnostic: any peer with localRAM block 0 can answer MBR reads.

Subpath exports: bare-os-protocol/constants.js, bare-os-protocol/messages (compact-encoding schemas), bare-os-protocol/kernel-feature-bits.js (documented booter capability words BARE_OS_KERNEL_FEATURES_STOCK_WORD_*; BARE_OS_KERNEL_FEATURE_BITS_DOC — see source; surfaced in /proc/bare_os_features and /proc/bare_os/), bare-os-protocol/lib/seed-rpc-methods.js (authoritative bare_os.* RPC name list for kernel_info), bare-os-protocol/protocol-meta.js (BARE_OS_PROTOCOL_PACKAGE_VERSION for the seed handshake).

Consumers

• bare-os-seeder — builds MBR, serves block 0 over the channel, replicates the system Hyperdrive.
• bare-os-booter — parses MBR from SwarmDisk, opens system drives, uses the same channel on the client side, and can mirror block 0 plus captured seed RPC snapshots after successful boot and eligibility checks.

Tests

npm test -w bare-os-protocol

Runs brittle-bare against test.js (topic stability, MBR roundtrip, encodings).

Dependencies

b4a, compact-encoding, hypercore-crypto (via constants/topic). No Hyperdrive or Hyperswarm here — this package stays small and testable.

See also

• Repo root README.md and protocol reference §10.
• Handbook — Blueprints § protocol (high-level).