# P2P App Store (design) **Status:** Core user-app paths shipped (May 2026): real `pear://` materialization and in-guest launch. Kernel-ext verification and multi-index discovery remain incremental. **Owner:** Raven (with community input) **Related:** HDMS, `appctl`, `pkg-swarm-index`, kernel extensions, agent skills, two-drive model --- ## Goals - Enable users running a booted Bare OS instance to **discover, review, and install** useful P2P applications, services, and kernel extensions directly from within the OS. - All installed content lives on a dedicated, user-controlled **App Store Hyperdrive** mounted via HDMS (never on the system drive). - Provide a clean separation between: - Ordinary user applications/services (lower risk) - Kernel extensions (high trust, strictly gated) - Leverage and extend existing primitives rather than reinventing (HDMS, `pkg-swarm-index`, `appctl`/`peerctl`, agent skills, kernel extension loader). - Make the App Store a first-class, P2P-native experience that feels native to the OS (including deep `/bin/agent` integration). **Non-goals (for v1):** - Running untrusted native code outside the existing sandbox/worker model. - Replacing the system drive or core `/bin`. - Centralized App Store server (everything must be discoverable and distributable over Hyperswarm/Hyperdrive). --- ## High-Level Architecture ### 1. App Store Drive (the container) - A normal Hyperdrive managed through **HDMS**. - Recommended default label: `appstore` - Mount point convention: `/mnt/appstore` (or user-configurable via HDMS). - Contains at minimum: - `registry.json` — installed packages + metadata + trust pins - `packages/` — materialized content (either full clones or references + metadata) - `manifests/` — verified package manifests - Optional per-package directories for data/state This drive is **personal** by default but can be shared via Autopass/HDMS if the user wants a shared team or community store. ### 2. Discovery Layer - Built on the existing `pkg-swarm-index` infrastructure + `bare_os.pkg_index_get` HRPC. - Support for multiple indexes: - Curated/official index (well-known drive key or swarm topic) - Community indexes - Direct `pear://` or Hyperdrive keys - New or extended command surface: `appstore search`, `appstore info`, `appstore index list` ### 3. Package Types | Type | Risk Level | Installation Target | Execution Model | Special Requirements | |-----------------|------------|------------------------------|-------------------------------------|----------------------| | User App | Low | App Store drive | Launched via Pear or `execLine` | Standard manifest | | Service | Medium | App Store drive + initd | Managed initd unit | Service manifest | | Kernel Extension| High | App Store drive + gated path | Loaded via kernel extension system | Signed + policy | ### 4. Trust & Security Model (Critical) - **User apps/services**: Standard path capability + VFS policy enforcement on the appstore drive. - **Kernel Extensions**: - Must be signed (Ed25519 or future multisig). - Installation requires explicit user confirmation + `--allow-kernel-ext`. - Boot policy can require pins or hashes (`kernelExtensionHashPins` already exists — extend for appstore). - Extensions from the store are loaded with a distinct source tag for auditing (`appstore:`). - All installations record provenance (source index, signer, install time) in the registry. --- ## New / Extended Surfaces ### Commands - `/bin/appstore` (preferred new binary) - `search`, `info`, `install`, `remove`, `list`, `update` - `install --kernel-ext ` (gated) - `launch ` ### ctx API Additions (likely ctx 1.55+ / Batch D) - `ctx.bareOsAppstoreInstall(manifest, opts)` - `ctx.bareOsAppstoreList()` - `ctx.bareOsRegisterAppstoreExtension(record)` (gated variant of existing extension registration) - Possibly `ctx.bareOsAppstoreDrive` (reference to the mounted store drive) ### /proc Additions - `/proc/bare_os/appstore.json` — status of the store drive, installed count, last sync, health - `/proc/bare_os/appstore/installed.json` (or virtual file) ### HDMS Convention - Standard label `appstore` with well-known registry path inside the drive. - New helper in `hdms-manager.js` or a small dedicated module for appstore drive lifecycle. ### Agent Skill - New skill: `skills/appstore/SKILL.md` - Discovery, review manifests, safe installation flows, kernel-ext warnings, rollback guidance. ### Boot Policy Extensions (future) - `allowAppstoreKernelExtensions` - `appstoreExtensionSignerPins` - `requireAppstoreReviewStatus` --- ## Phased Implementation Approach ### Phase 1 — Foundation (Early Batch D) - Define App Store drive convention + `registry.json` schema (v1) - Basic `appstore` command (list, info, install skeleton for user apps) - HDMS integration for auto-mounting `appstore` label on login - Agent skill skeleton + basic discovery using existing `pkg-swarm-index` - Documentation + `man appstore` ### Phase 2 — User Apps & Services (shipped core paths) - **`appstore install`** — Real `pear://` materialization via **`lib/appstore-pear.js`** (local HDMS mount or ephemeral readonly fetch + VFS mirror into `packages//`). - **`appstore launch`** — In-guest execution of `sources/
` (or `package.json` `main`); output on `ctx.console` (no peerctl-only stub). - **`appstore update`** — Re-fetch from stored `pearLink`. - Manifest + `appstore-meta.json` with `materializationVersion: 3` and fetch metadata. - `setup`, `services` scaffolding, gated kernel-ext warnings, HDMS preference, agent skill. Remaining Phase 2 items: automatic initd wiring for all service types, full kernel-ext verification pipeline. ### Phase 2b — Guest Pear authoring (May 2026) - **`/bin/pear`**: `init`, `stage`, `release`, `seed` (aliases `build`/`bundle` for stage). - **`pear release`** publishes `.pear/stage/` to a writable HDMS drive and emits versioned **`pear://`** links without host Pear CLI. - Natural handoff to App Store: `appstore install --yes` then `appstore launch `. Operator guide: **[docs/guides/guest-pear-and-appstore-workflow.md](../guides/guest-pear-and-appstore-workflow.md)**. ### Phase 3 — Kernel Extensions (High Care) - Signed extension manifest format for the store - Gated installation path + policy integration - Safe loading + distinct auditing for appstore-sourced extensions - `kernel.ext.d` drop-in generation from installed extensions (optional) ### Phase 4 — Polish & Ecosystem - Multiple index support + reputation/curated channels - Deep agent autonomy (agent can propose installs based on tasks) - Rich TUI in `appstore` (or reuse TUI framework) - Observability, backup/restore of the store drive, sharing via HDMS --- ## Open Questions & Trade-offs 1. **How strict for kernel extensions?** Should the store support community-submitted kernel extensions at all in early versions, or only a small curated set? 2. **Installation model for large packages** Full materialization into the appstore drive vs. reference + on-demand mounting? 3. **Update model** Should `appstore update` be pull-based only, or support push notifications via existing chat / HRPC mechanisms? 4. **Relationship to existing `appctl`** Keep `appctl` for the old Pear app registry and make `appstore` the new unified experience? Or merge over time? 5. **Discovery incentives** Do we want any on-chain / reputation / staking concepts later, or stay purely P2P + social? --- ## Proposed Batch D Items (App Store Theme) These can be mixed into the broader Batch D plan. Suggested priority order for the App Store thread: | # (D) | Item | Phase | Dependencies | Notes | |-------|------|-------|--------------|-------| | D-APP-01 | App Store drive convention + HDMS label `appstore` + basic registry schema | 1 | HDMS | | | D-APP-02 | `/bin/appstore` skeleton (list, info, search via pkg-swarm-index) | 1 | D-APP-01 | New binary | | D-APP-03 | Agent skill `appstore` (discovery + safe install guidance) | 1 | D-APP-02 | | | D-APP-04 | HDMS auto-mount of appstore drive on session start | 1 | D-APP-01 | | | D-APP-05 | Full user-app install flow (manifest → materialization) | 2 | D-APP-02 | **done** — `appstore-pear.js` fetch + mirror | | D-APP-06 | Service manifest + initd unit generation from installed packages | 2 | D-APP-05 | partial — `appstore services` scaffolding | | D-APP-07 | `appstore launch` + integration with existing Pear launch paths | 2 | D-APP-05 | **done** — in-guest script launch; `appctl` still uses peerctl | | D-APP-08 | Signed manifest format + verification for kernel extensions | 3 | D-APP-05 | Security critical | | D-APP-09 | Gated `install --kernel-ext` + boot policy integration | 3 | D-APP-08 | | --- ## Pear Development Integration (May 2026) The **`ctx.pear`** surface and **`/bin/pear`** command (see `docs/design/ctx-pear-surface-and-bare-audit-plan.md`) close the loop with the App Store: | Step | Command | Result | | --- | --- | --- | | Author | `pear init` / edit sources | Project under `~/pear-projects/` | | Stage | `pear stage` | `.pear/stage/` | | Publish | `pear release` | HDMS mount + `pear://0..` | | Replicate | `pear seed` | Swarm flush (best-effort) | | Distribute | `appstore install NAME pear://… --yes` | `~/.appstore/packages/NAME/` | | Run | `appstore launch NAME` | Guest shell runs `sources/index.js` | **Implementation files:** - `packages/bare-os-coreutils/lib/pear-stage.js`, `lib/pear-release.js` - `packages/bare-os-coreutils/lib/appstore-pear.js` - `packages/bare-os-coreutils/src/appstore.js` **Agent skills:** `pear-dev` + `appstore` (cross-referenced). **Not yet in guest:** `pear run` subcommand (full Pear runtime); compiled-only `app.bundle.js` launch without `sources/` entry. | D-APP-10 | Appstore-sourced extensions loaded with distinct source tag + audit | 3 | D-APP-09 | | | D-APP-11 | `/proc/bare_os/appstore.json` + virtual files | 2 | D-APP-04 | Observability | | D-APP-12 | `ctx.bareOsAppstore*` methods (install, list, drive ref) | 2 | D-APP-05 | ctx API bump | | D-APP-13 | Multi-index support + curated vs community channels | 4 | D-APP-02 | | | D-APP-14 | Agent-driven "recommended for your workload" installation | 4 | D-APP-03 | Self-dev showcase | These items are designed to be small enough to be individually verifiable while delivering incremental value. --- ## Next Steps (Recommended) 1. Review and refine this design (especially the trust model for kernel extensions). 2. Finalize the first 4–6 Batch D items above and add them to `docs/reference/feature-roadmap.md` under the Batch D section. 3. Create the initial `skills/appstore/SKILL.md` (even as a stub) so the agent is ready early. 4. Prototype the drive convention + basic `appstore` command in a branch. This feature has the potential to become one of the most visible and useful parts of the OS for end users while staying true to the P2P, governed, Bare-only philosophy. --- **Related existing files to keep in sync:** - `packages/bare-os-coreutils/lib/appstore-pear.js` - `packages/bare-os-coreutils/lib/pear-stage.js`, `lib/pear-release.js` - `docs/guides/guest-pear-and-appstore-workflow.md` - `packages/bare-os-booter/lib/hdms-manager.js` - `packages/bare-os-coreutils/src/appctl.js` and `pkg-swarm-index.js` - `developer-guide/kernel-program.md` - `docs/reference/feature-roadmap.md` (Batch D section) - `kernel-program-extension` skill *Document written as direct response to feature request for a P2P App Store.*