snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Further MD Fixes

Browse Source
This commit is contained in:
Raven Scott
2026-04-25 23:04:56 -04:00
parent b07bc38708
commit b9d3a8b17f
143 changed files with 1861 additions and 1861 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/security/blind-relay-p2p-hardening.md
+5 -5
View File
@@ -1,13 +1,13 @@
# Blind relay, pairing, and P2P hardening
Bare OS follows a **zero-trust default** for **blind** Holepunch-style relays, **pairing** sketches, and **geo / topology** hints: stock **`/proc/bare_os**` JSON for `**blind_relay_router**`, `**blind_pairing_sketch**`, and `**relay_geo_hint**` uses **schema 1** with `**operatorRedacted: true**` and `**exposed: false**` until the operator explicitly enables `**BARE_OS_PROC_BLIND_PEER_RELAY_HINTS**`. When enabled, the booter emits **schema 2** documents that merge **env-injected operator JSON** with **aggregated swarm runtime** only: **peer count**, **lifecycle state**, `**relayGeoTier**` (coarse tier, not geo-IP), and `**pairingSurfaceReady**`. **No** peer public keys, addresses, or swarm topics are included in that `**swarm`** object.
Bare OS follows a **zero-trust default** for **blind** Holepunch-style relays, **pairing** sketches, and **geo / topology** hints: stock **`/proc/bare_os`** JSON for **`blind_relay_router`**, **`blind_pairing_sketch`**, and **`relay_geo_hint`** uses **schema 1** with `**operatorRedacted: true**` and `**exposed: false**` until the operator explicitly enables **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`**. When enabled, the booter emits **schema 2** documents that merge **env-injected operator JSON** with **aggregated swarm runtime** only: **peer count**, **lifecycle state**, **`relayGeoTier`** (coarse tier, not geo-IP), and **`pairingSurfaceReady`**. **No** peer public keys, addresses, or swarm topics are included in that **`swarm`** object.
## Operator controls
- **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS**` — When set to `**1**` / `**true**` / `**yes**`, the booter may merge **non-secret** operator JSON from related `**BARE_OS_*`** env keys into those proc surfaces (see [`bare-os-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js) and companion proc builders).
- **`BARE_OS_BLIND_RELAY_AUDIT_NDJSON**` — When `**1**` / `**true**`, `**/proc/bare_os/security_posture.json**` sets `**blindRelayAudit.armed`** so fleet automation knows blind-relay admission rows may be mirrored to host NDJSON sinks (still **no** peer keys in proc).
- **Seed RPC** — Method names are **allowlisted** in [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js). Unknown methods fail closed with **`bare_os.rpc_unknown_method**`. Clients can mirror the same rule with `**bareOsIsAllowedSeedRpcMethodShort**` (exported from `**bare-os-protocol`**).
- **Capabilities / handshake** — **`BARE_OS_SEED_CAP_STRICT**` and `**BARE_OS_SEED_CAP_FAIL`** tighten seeder capability checks; keep them aligned with your release train (see [compatibility matrix](../reference/compatibility-matrix.md)).
- **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`** — When set to **`1`** / **`true`** / **`yes`**, the booter may merge **non-secret** operator JSON from related **`BARE_OS_*`** env keys into those proc surfaces (see [`bare-os-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js) and companion proc builders).
- **`BARE_OS_BLIND_RELAY_AUDIT_NDJSON`** — When **`1`** / **`true`**, **`/proc/bare_os/security_posture.json`** sets **`blindRelayAudit.armed`** so fleet automation knows blind-relay admission rows may be mirrored to host NDJSON sinks (still **no** peer keys in proc).
- **Seed RPC** — Method names are **allowlisted** in [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js). Unknown methods fail closed with **`bare_os.rpc_unknown_method`**. Clients can mirror the same rule with **`bareOsIsAllowedSeedRpcMethodShort`** (exported from **`bare-os-protocol`**).
- **Capabilities / handshake** — **`BARE_OS_SEED_CAP_STRICT`** and **`BARE_OS_SEED_CAP_FAIL`** tighten seeder capability checks; keep them aligned with your release train (see [compatibility matrix](../reference/compatibility-matrix.md)).
## What the guest does not do
docs/security/vault-multisig-continuity.md
+7 -7
View File
@@ -4,8 +4,8 @@ Bare OS identity today centers on **HDMS / autopass** flows documented in the ha
## Design constraints
- **Backward compatible**: default **`/.bare/**` metadata and `**login` / `savevault`** flows keep working when multisig is off.
- **Guest-visible only as hints**: synthetic **`/proc/bare_os**` JSON and host `**process.emit`** sketches — no silent network from the guest kernel.
- **Backward compatible**: default **`/.bare/`** metadata and `**login` / `savevault`** flows keep working when multisig is off.
- **Guest-visible only as hints**: synthetic **`/proc/bare_os`** JSON and host **`process.emit`** sketches — no silent network from the guest kernel.
- **Operator-owned keys**: multisig public material is not embedded in the system image; distributors ship allowlists and boot policy pins.
## Stock surfaces (today)
@@ -14,11 +14,11 @@ Bare OS identity today centers on **HDMS / autopass** flows documented in the ha
|---------|------|
| **`/proc/bare_os/hyper_multisig_trust_pointer.json`** | Operator-facing trust pointer sketch (see booter VFS proc table). |
| **`/proc/bare_os/multisig_quorum_pointer.json`** | Quorum pointer sketch for dashboards. |
| **`ctx.bareOsEmitMultisigPointer**`, `**ctx.bareOsMultisigQuorumPointer**` | Emit `**bare-os:multisig-pointer**` / `**bare-os:multisig-quorum-pointer`** on the host process for integrators. |
| **`BARE_OS_HYPER_MULTISIG_VERIFY**` | Seeder can run `**hyper-multisig verify**` when the binary is on `**PATH`** (see [environment appendix](../reference/environment-and-posix-appendix.md)). |
| **`BARE_OS_VAULT_MULTISIG_CONTINUITY_JSON**` | Merged into `**hyper_multisig_trust_pointer.json**` (**schema 2**) as `**vaultMultisigContinuity`** — operator-owned continuity sketch only. |
| **`BARE_OS_VAULT_MULTISIG_CONTINUITY_AUDIT_NDJSON**` | When `**1**` / `**true**`, login / unlock appends a `**vault.multisig_continuity_login_sketch`** audit row (**public-key hex prefix** only). |
| **Boot policy** | **`extensionSignerPinsV2**`…`**V5`** pin extension signers; see [OTA and bundles](../deployment/OTA_AND_BUNDLES.md). Multisig is an **identity** layer above bundle trust. |
| **`ctx.bareOsEmitMultisigPointer`**, **`ctx.bareOsMultisigQuorumPointer`** | Emit **`bare-os:multisig-pointer`** / **`bare-os:multisig-quorum-pointer`** on the host process for integrators. |
| **`BARE_OS_HYPER_MULTISIG_VERIFY`** | Seeder can run `**hyper-multisig verify**` when the binary is on **`PATH`** (see [environment appendix](../reference/environment-and-posix-appendix.md)). |
| **`BARE_OS_VAULT_MULTISIG_CONTINUITY_JSON`** | Merged into **`hyper_multisig_trust_pointer.json`** (**schema 2**) as **`vaultMultisigContinuity`** — operator-owned continuity sketch only. |
| **`BARE_OS_VAULT_MULTISIG_CONTINUITY_AUDIT_NDJSON`** | When **`1`** / **`true`**, login / unlock appends a **`vault.multisig_continuity_login_sketch`** audit row (**public-key hex prefix** only). |
| **Boot policy** | **`extensionSignerPinsV2`**…**`V5`** pin extension signers; see [OTA and bundles](../deployment/OTA_AND_BUNDLES.md). Multisig is an **identity** layer above bundle trust. |
## When to enable
docs/security/vault-threat-model.md
+4 -4
View File
@@ -4,7 +4,7 @@ This note summarizes **what the guest runtime tries to protect** and **what it d
## Assets
- **Account blob** (`/.bare/account`, v2): Ed25519 keypair; secret sealed with **PBKDF2-SHA256** and **ChaCha20-Poly1305** via **`bare-crypto**` (see `**BARE_OS_ACCOUNT_CRYPTO_PROFILE_V2**` in code and `**/proc/bare_os/security_posture.json`**).
- **Account blob** (`/.bare/account`, v2): Ed25519 keypair; secret sealed with **PBKDF2-SHA256** and **ChaCha20-Poly1305** via **`bare-crypto`** (see **`BARE_OS_ACCOUNT_CRYPTO_PROFILE_V2`** in code and **`/proc/bare_os/security_posture.json`**).
- **Vault entries**: Application data sealed with a key derived from the signing secret (same AEAD stack); paths are hashed for stable blob names.
## Trust assumptions
@@ -12,7 +12,7 @@ This note summarizes **what the guest runtime tries to protect** and **what it d
- The **host process** (Pear/Node) can read guest memory; ciphertext on the personal Hyperdrive protects against **offline** replication sniffing, not against a compromised host.
- **Passphrase quality** and **backup policy** are out of band; weak passphrases defeat PBKDF2-protected blobs.
- **Peers** replicate Hyperdrive blocks; anyone with read access to the drive ciphertext needs the passphrase (or unlocked session) for account material.
- **Path-capability envelopes** (**`ctx.bareOsVerifyPathCapabilityEnvelope**`) bind issuer keys to prefix + op lists; `**ctx.bareOsVerifyPathCapabilityEnvelopeTrusted**` adds a **host allowlist** (`**BARE_OS_PATH_CAPABILITY_TRUSTED_PUBKEYS_HEX`**) so operators can pin known issuers. Guests still cannot detect a malicious host that forges `ctx` methods — the model assumes the **booter binary** is trusted.
- **Path-capability envelopes** (**`ctx.bareOsVerifyPathCapabilityEnvelope`**) bind issuer keys to prefix + op lists; **`ctx.bareOsVerifyPathCapabilityEnvelopeTrusted`** adds a **host allowlist** (**`BARE_OS_PATH_CAPABILITY_TRUSTED_PUBKEYS_HEX`**) so operators can pin known issuers. Guests still cannot detect a malicious host that forges `ctx` methods — the model assumes the **booter binary** is trusted.
## Non-goals
@@ -21,8 +21,8 @@ This note summarizes **what the guest runtime tries to protect** and **what it d
## Multisig continuity (Pear / hyper-multisig alignment)
Stock boot validates **`/etc/bare-os/pear.multisig.json**` when `**BARE_OS_RC_PROPOSAL_MULTISIG_STRICT**` or policy requires it (`**kernel/lib/boot/00-pear-multisig-shape.js**` mirrors `**bare-os-protocol**`). Treat this as **governance continuity** for extension and RC proposals, not a substitute for upstream **[hyper-multisig](https://github.com/holepunchto/hyper-multisig)** CLI workflows on the host: operators should still run Holepunch signing/rotation tools out of band and only ship quorum-approved JSON into the image. `**BARE_OS_VAULT_MULTISIG_CONTINUITY_JSON**` and `**/proc/bare_os/hyper_multisig_trust_pointer.json**` (when exposed) document non-secret rotation hints; `**pearMultisigSeeder.verifyResult**` in `**security_posture.json`** reflects seeder-side verification only.
Stock boot validates **`/etc/bare-os/pear.multisig.json`** when **`BARE_OS_RC_PROPOSAL_MULTISIG_STRICT`** or policy requires it (**`kernel/lib/boot/00-pear-multisig-shape.js`** mirrors **`bare-os-protocol`**). Treat this as **governance continuity** for extension and RC proposals, not a substitute for upstream **[hyper-multisig](https://github.com/holepunchto/hyper-multisig)** CLI workflows on the host: operators should still run Holepunch signing/rotation tools out of band and only ship quorum-approved JSON into the image. **`BARE_OS_VAULT_MULTISIG_CONTINUITY_JSON`** and **`/proc/bare_os/hyper_multisig_trust_pointer.json`** (when exposed) document non-secret rotation hints; **`pearMultisigSeeder.verifyResult`** in **`security_posture.json`** reflects seeder-side verification only.
## Related `/proc`
- **`/proc/bare_os/security_posture.json**` — `**vaultCryptoPrimitives**` and `**bareCryptoReportedVersion**` (from `**BARE_OS_BARE_CRYPTO_VERSION`**) document the expected algorithms without exposing secrets.
- **`/proc/bare_os/security_posture.json`** — **`vaultCryptoPrimitives`** and **`bareCryptoReportedVersion`** (from **`BARE_OS_BARE_CRYPTO_VERSION`**) document the expected algorithms without exposing secrets.