feat(kernel): expand stock image, boot policy, and ecosystem integration
- Stock kernel: boot.policy v2 (maxExecLineDepth, denyEnvKeys, requireProcNodes);
richer BARE_OS_KERNEL_SELFTEST; example policy and timer drop-in samples
- Protocol: feature bits 28–30, seed RPCs (manifest_hints, peer_health, staging_slot)
- Booter: /proc mirrors, provenance, metrics_live, pear IPC registry, initd DAG,
suspend/resume wiring, exec budget, shell ${var} expansion, delegate limits,
telemetry v3 / OTel JSONL, ctx API 1.11.0
- Coreutils: /bin/timeout; seeder Pear/Bare: avoid bare process.env (globalThis.process?.env)
- CI: verify-ctx-api-feature-bits; docs: handbook, developer-guide, kernel-extensions,
capabilities index, environment appendix, READMEs
This commit is contained in:
Raven Scott
@@ -31,7 +31,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
| **`bareOsSkipRepl`** | **`true`** when **`BARE_OS_SKIP_REPL=1`** (non-interactive stdin); kernels may shorten banners. |
|
||||
| **`bareOsAdvertisedKernelBits`** / **`bareOsSeedCapabilityBits`** | Unsigned bitmasks: effective stock features (minus env-disabled bits such as crypto urandom) and last seed **`bare_os.capabilities`** **`bits`**, if any. |
|
||||
| **`bareOsSystemRevision`** | **Frozen** **`{ currentId, pendingId, slot }`** from host env (**`BARE_OS_SYSTEM_REVISION_*`**) for Pear-style OTA hints. |
|
||||
| **`bareOsRegisterSuspendHook` / `bareOsRegisterResumeHook`** | Register callbacks; **`bareOsInvokeSuspendHooks`** / **`bareOsInvokeResumeHooks`** run them (host may call around **`Bare.suspend`** / **`Bare.wakeup`**). |
|
||||
| **`bareOsRegisterSuspendHook` / `bareOsRegisterResumeHook`** | Register callbacks; **`bareOsInvokeSuspendHooks`** / **`bareOsInvokeResumeHooks`** run them (host may call around **`Bare.suspend`** / **`Bare.wakeup`**). The booter also registers **bare-initd** so units with stop/start paths run in order on suspend/resume. |
|
||||
| **`bareOsRequestKernelReload()`** | Throws **`BARE_OS_KERNEL_RELOAD`** when **`BARE_OS_KERNEL_HOT_RELOAD=1`** so the booter re-reads **`/boot/init.js`**. |
|
||||
| **`bareOsRunImageScript(path)`** | **`async`** — runs trusted JS from the system image; paths must be under **`/lib/bare-os/extensions/`** (used by **`kernel.ext.d`**). |
|
||||
| **`disk`** | Disk bundle used during boot (includes drives and helpers); advanced use |
|
||||
@@ -53,10 +53,11 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
| **`bareOsApplyTheme()`** / **`bareOsListThemes()`** | Re-apply **`BARE_OS_THEME`** / **`LS_COLORS`** / **`BARE_OS_DIRCOLORS`** to **`vfs.env`** (including **`BARE_OS_COLOR_DEPTH`** downgrades for **`BARE_OS_COLOR_*`**). Used by **`/bin/theme`** and documented for custom tooling (see [`bare-os-theme-presets.js`](../packages/bare-os-booter/lib/bare-os-theme-presets.js)). |
|
||||
| **`runBinCommand(argv)`** | Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar) |
|
||||
| **`registerKernelShutdownHook(fn)`** | Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with **`registerBareInitdDisposer(fn)`** in [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup). |
|
||||
| **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** | Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). |
|
||||
| **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** | Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion: 3`** alongside **`telemetrySchemaVersion`** where applicable (see [kernel extensions](../docs/reference/kernel-extensions.md)). |
|
||||
| **`bareOsSubscribeHdmsLifecycle(fn)`** | After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**. |
|
||||
| **`bareOsAwaitInitdUnits(names, timeoutMs)`** | Resolves when all listed initd units are **`active`** (polls **`getBareServiceRuntime`**); returns **`false`** on timeout. |
|
||||
| **`bareOsGetResourceStatus()`** | Returns a plain object snapshot (pipeline limits, exec depth, IPC **`stats()`**, session counters, swarm peer count)—mirrors **`/proc/bare_os_resources`**. |
|
||||
| **`bareOsGetResourceStatus()`** | Returns a plain object snapshot (pipeline limits, exec depth, IPC **`stats()`**, session counters, swarm peer count)—mirrors **`/proc/bare_os_resources`**. Session may include **`execLineWallMsTotal`**. |
|
||||
| **`bareOsReadProcMetricsLive()`** | Returns the same object as reading **`/proc/bare_os/metrics_live.json`** (coalesced; interval from **`BARE_OS_PROC_POLL_MS`**). |
|
||||
| **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Registers **`/run/bare-os/virtual/<name>`** content; **`reader`** may be a function or **`{ read }`**; may return string or **`Uint8Array`** (sync or async). Optional **`opts`**: **`etag`**, **`mime`** (default **`text/plain`**), **`ttlMs`** (optional cache hint). Gated by runtime cap **`virtualRegisterFiles`**. |
|
||||
| **`bareOsSandboxRunScript(source, argv?, opts?)`** | Runs script source with a **restricted `ctx`** (personal-drive writes only; identity/virtual registration disabled). Respects **`raceWithAbortAndTimeout`** opts. Disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. See [Chapter 9](09-security-and-trust.md). |
|
||||
| **`bareOsBootFileSha256Hex(buf)`** | **`sha256` hex for boot manifest checks** (`BARE_OS_BOOT_MANIFEST` + `/etc/bare-os/boot.manifest.json` on the stock kernel). |
|
||||
|
||||
@@ -18,13 +18,15 @@ The **system** Hyperdrive is the **OS image**. You normally obtain it by **repli
|
||||
|
||||
**Delegated HTTP:** when the booter sets **`ctx.httpFetch`** from the host **`fetch`**, **`BARE_OS_HTTP_ALLOWLIST`** and **`BARE_OS_HTTP_DENYLIST`** restrict **`http`/`https`** URLs for **`curl`/`wget`** (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.
|
||||
|
||||
**Host CLI delegates:** **`git`**, **`curl`**, **`wget`**, and **`systemctl`**-family commands can be restricted with **`BARE_OS_DELEGATE_ALLOW`** (comma list; empty = all).
|
||||
**Host CLI delegates:** **`git`**, **`curl`**, **`wget`**, and **`systemctl`**-family commands can be restricted with **`BARE_OS_DELEGATE_ALLOW`** (comma list; empty = all). Optional per-minute caps use **`BARE_OS_DELEGATE_MAX_PER_MIN`** and per-kind **`BARE_OS_DELEGATE_*_MAX_PER_MIN`**. With **`BARE_OS_AUDIT=1`**, **`BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs delegate invocations and skips the host run (**exit 0**) for audit-only environments.
|
||||
|
||||
**DNS allowlist:** **`BARE_OS_DNS_ALLOWLIST`** optionally constrains http(s) hostnames for **`curl`/`wget`** before fetch (suffix wildcard **`*.example.com`** supported).
|
||||
|
||||
**IPC JSON-RPC:** when **`BARE_OS_IPC_RPC_TOKEN`** is set, **`pushJson`** payloads must include matching **`bareOsIpcToken`** or the push throws. Line size is capped (**`BARE_OS_IPC_JSON_MAX_BYTES`**, default 256 KiB).
|
||||
|
||||
**Sandboxed scripts:** **`ctx.bareOsSandboxRunScript(source, argv?, opts?)`** runs in-image JS with a **restricted `ctx`**: writes are limited to the personal namespace (same routing rules as `isPersonalRoute`), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with **`BARE_OS_SANDBOX_SCRIPT=0`**. **`BARE_OS_SANDBOX_WORKER=1`** defers execution on a **fresh microtask** (async boundary from the caller stack); it is **not** a separate thread or hardware isolate. This is still **not** a security boundary—treat sandboxing as a trust reducer.
|
||||
**Sandboxed scripts:** **`ctx.bareOsSandboxRunScript(source, argv?, opts?)`** runs in-image JS with a **restricted `ctx`**: writes are limited to the personal namespace (same routing rules as `isPersonalRoute`), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with **`BARE_OS_SANDBOX_SCRIPT=0`**. **`BARE_OS_SANDBOX_WORKER=1`** prefers **`bare-worker`** when the host provides it, else defers on a **fresh microtask**; neither path is a hardware isolate. For **documented** stronger separation, operators may compose Holepunch **`cross-worker`** / **`bare-bundle-evaluate`** patterns (see comments in **`packages/bare-os-booter/lib/bare-os-sandbox.js`**). This remains **not** a guaranteed security boundary—treat sandboxing as a trust reducer.
|
||||
|
||||
**Provenance:** **`/proc/bare_os_provenance`** (and **`/proc/bare_os/provenance`**) combines boot manifest digest, optional signing flags, and Pear channel hints for operators (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
|
||||
## Init, timers, and sockets
|
||||
|
||||
- **bare-initd** — User drop-ins under `~/.config/bare-os/units/<name>.unit` support `SocketActivationIpc=<fifo>`; the unit’s `start` runs after the first byte is read on that logical FIFO under `/run/bare-os/ipc/…`.
|
||||
- **Timers** — Files in `~/.config/bare-os/timers/*.timer` with a `[Timer]` section (`OnCalendar=` five cron fields, `ExecLine=`) are evaluated on the same minute tick as `~/.crontab`.
|
||||
- **Timers** — Files in `~/.config/bare-os/timers/*.timer` (max **8**) with a `[Timer]` section: either `OnCalendar=` (five cron fields) + `ExecLine=` on the same minute tick as `~/.crontab`, or `EveryMs=` (**1000**–**86400000**) + `ExecLine=` on a fixed `setInterval`. Copy from `/etc/bare-os/timers/*.timer.example` on the system image when present.
|
||||
- **System cron** — Optional image file `/etc/bare-os/crontab` (see [crontab.example](../kernel/etc/bare-os/crontab.example)) is merged with user crontab entries.
|
||||
|
||||
## Observability
|
||||
|
||||
@@ -52,6 +52,12 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
|
||||
---
|
||||
|
||||
## Pear IPC channel registry
|
||||
|
||||
**`ctx.bareOsPearIpcEmit(channel, payload)`** is a host bridge for [pear-ipc](https://github.com/holepunchto/pear-ipc)-style messaging. Well-known **`channel`** strings are listed in **`packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js`** and mirrored as JSON under **`/proc/bare_os/pear_ipc.json`** (and the flat **`/proc/bare_os_pear_ipc_registry`** alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [Chapter 5 — Modules and `import`](05-modules-and-imports.md)
|
||||
|
||||
@@ -10,6 +10,10 @@ This project is **experimental research software**. APIs described here follow t
|
||||
|
||||
**Feature-bit governance:** [ADR 001 — Kernel feature bit governance](adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
**Capability map:** [docs/reference/kernel-capabilities-index.md](../docs/reference/kernel-capabilities-index.md).
|
||||
|
||||
**Contract checks:** changing **`bareOsCtxApiVersion`** or stock kernel feature bits should keep **`scripts/verify-ctx-api-feature-bits.mjs`** green (invoked from root **`pretest`**).
|
||||
|
||||
---
|
||||
|
||||
## Who this is for
|
||||
|
||||
@@ -19,7 +19,7 @@ Bare OS advertises optional booter and seed-channel capabilities as a versioned
|
||||
|
||||
3. **`/proc/bare_os_features`** — Must include `doc`, effective `bits` (stock mask minus env-disabled features such as crypto urandom), and optional `seedHandshake` summary. The unified tree under `/proc/bare_os/` duplicates the same content for stable paths (see `docs/reference/kernel-extensions.md`).
|
||||
|
||||
4. **Reserved range** — Bits **28–30** are reserved for fast-follow features; do not allocate without updating this ADR.
|
||||
4. **Bits 28–30 (assigned)** — **28:** `BARE_OS_FEATURE_SEED_MANIFEST_HINTS_RPC` (`bare_os.manifest_hints`). **29:** `BARE_OS_FEATURE_LIFECYCLE_TELEMETRY_V3` (NDJSON / boot events `lifecycleSchemaVersion: 3`). **30:** `BARE_OS_FEATURE_BOOT_POLICY_V2` (extended `boot.policy.json` fields). Further bits require a new ADR revision if the integer space is exhausted (avoid `1 << 31` in JS without `>>> 0` discipline).
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
Reference in New Issue
Block a user