OS mediakit

@@ -3,10 +3,10 @@ schema: foundry-doc-v1
content_type: topic
title: "OS mediakit"
slug: os-mediakit
short_description: "Guest OS image for the vm-mediakit tier — isolates knowledge wikis, marketing sites, proofreader, and BIM orchestration from the vault and orchestration tiers."
short_description: "The public-web tier of the PointSav OS family — os-mediakit owns TLS, systemd lifecycle, and gateway-mediated data access; app-mediakit-knowledge/marketing/distribution own domain logic. Ubuntu 24.04 today; the planned end state is one seL4 VM per deployment instance, not a single combined appliance."
category: systems
index_group: publishing-and-media
last_edited: 2026-07-11
last_edited: 2026-08-06
editor: pointsav-engineering
status: stable
bcsc_class: no-disclosure-implication
@@ -14,10 +14,49 @@ bcsc_class: no-disclosure-implication

**os-mediakit** is the guest operating system image for the `vm-mediakit` VM tier in
the PointSav Private Network hypervisor layer. It isolates the MediaKit service surface
— knowledge wikis, marketing sites, proofreader, and BIM orchestration — from the source
— knowledge wikis, marketing sites, and compliance/distribution feeds — from the source
vault and orchestration tiers.

---
## OS / app boundary

`os-mediakit` (the operating system) and `app-mediakit-*` (the applications it hosts)
have a fixed division of responsibility, ratified as part of the OS family's tier
definitions.

`os-mediakit` provides: TLS termination (nginx and certbot), systemd unit lifecycle,
the per-tenant filesystem layout, log rotation with forwarding into the WORM ledger,
MBA pairing to the fleet gateway, Doorman client TLS bootstrap, rate limiting, and
static asset serving.

`app-mediakit-*` provides: domain logic — page rendering, search, payment
verification, taxonomy queries, the editorial UI, wiki wikilink resolution, and
license issuance. Each `app-mediakit-*` binary is a tenant of the OS, not part of it.

## Deployments and data flow

Every `app-mediakit-*` instance reaches Totebox data through the fleet gateway only —
`media-* → outbound MBA → gateway-orchestration-command-1 → Doorman audit →
cluster-totebox-*`. **No `app-mediakit-*` process reads Totebox storage directly**; the
gateway is the only crossing point, and every read is recorded to the audit ledger on
its way through.

| Instance | Binary | Surface | Status |
|---|---|---|---|
| `media-knowledge-documentation-1` | app-mediakit-knowledge | documentation.pointsav.com | Live |
| `media-knowledge-projects-1` | app-mediakit-knowledge | projects.woodfinegroup.com | Live |
| `media-marketing-landing-1` | app-mediakit-marketing | home.woodfinegroup.com | Live |
| `media-marketing-landing-2` | app-mediakit-marketing | home.pointsav.com | Live |
| `media-intranet-1` | nginx (no app binary) | VPN-only internal preview of the above | Live, WireGuard-gated |
| `media-knowledge-corporate-1` | app-mediakit-knowledge | corporate.woodfinegroup.com | Not yet deployed |
| `media-distribution-*` | app-mediakit-distribution | Compliance/press-release feed | Not yet deployed |

Two things worth stating plainly rather than smoothing over. First, the fleet-gateway
MBA pairing this data-flow model depends on is not yet wired for any `media-*`
instance today — each one currently reaches its content locally rather than through
the gateway, a known, tracked gap. Second, `software.pointsav.com` — sometimes
associated with `app-mediakit-distribution` in early planning — is in practice served
by the separate `app-privategit-marketplace`/`app-privategit-source` binaries; no
`app-mediakit-distribution` instance is deployed there today.

## Stack position

@@ -49,7 +88,7 @@ itself is `os-infrastructure` (the Genesis Protocol boot layer).
## Phase 1: Ubuntu 24.04 interim (present)

The first deployment of vm-mediakit uses an **Ubuntu 24.04 server cloud x86_64 QCOW2** as
the guest OS. This is the production interim while the seL4 Microkit image is developed.
the guest OS. This is the production interim while the per-instance seL4 VMs are developed.

Ubuntu 24.04 is required — not Debian 12 — because all service binaries compiled on the
GCP host (Ubuntu 24.04, glibc 2.39) link against `GLIBC_2.39` symbols. Debian 12 provides
@@ -84,59 +123,41 @@ QEMU process and handles graceful shutdown via the QEMU monitor socket.

---

## Phase 3: seL4 Microkit image (planned)

The intended long-term form of os-mediakit is a **seL4 Microkit 2.2 AArch64 image**
assembled by `moonshot-toolkit`. Each service runs as an isolated seL4 Protection Domain
(PD) within the formally-verified microkernel.

This is a planned milestone. The seL4 path requires an AArch64 host (Microkit 2.2.0
supports AArch64 and RISC-V 64; there is no x86_64 Microkit target).

### Planned component layout

Each major service becomes a seL4 PD with minimal capability set:

| PD | Binary | seL4 capability |
|---|---|---|
| `mediakit-root` | os-mediakit rootserver | Bootstrap, capability distribution |
| `service-fs-pd` | service-fs Envelope B | IPC to ledger-pd; file-system endpoint only |
| `system-ledger-pd` | system-ledger (native feature) | seL4_Call to capability oracle |
| `proofreader-pd` | service-proofreader | HTTP endpoint; no FS capability |
| `knowledge-pd` | app-mediakit-knowledge | HTTP endpoint; read-only FS cap |
| `marketing-pd` | app-mediakit-marketing | HTTP endpoint; no FS capability |

The isolation invariant: no PD has read capability over another PD's memory. Enforced by
the seL4 capability model — not by OS-level permissions.

### The `system-substrate-sel4` shim
## Phase 3: one seL4 VM per deployment instance (planned)

`system-core` and `system-ledger` are written for `std` environments (Linux daemon form).
Running them as seL4 PDs requires `system-substrate-sel4` — a shim crate with feature flags
`["native"]` (seL4_Call/seL4_Send via rust-sel4) and `["compat"]` (std wrapper for Linux).
The shim is a planned crate. The same pattern applies to service-fs specifically (Envelope B).
The ratified moonshot topology for the OS family does not package `os-mediakit` as one
combined seL4 appliance the way `os-orchestration` consolidated Command and SLM into a
single guest. Instead, each `app-mediakit-*` **deployment instance** — not each
service type — gets its own dedicated seL4/Microkit VM, using the same
Microkit-plus-`vendor-libvmm`-Linux-guest pattern already proven for `os-totebox`.

### Assembly
| Planned VM | Hosts |
|---|---|
| `mediakit-knowledge-vm-1` | `media-knowledge-documentation-1` (documentation.pointsav.com) |
| `mediakit-knowledge-vm-2` | `media-knowledge-projects-1` (projects.woodfinegroup.com) |
| `mediakit-knowledge-vm-3` | `media-knowledge-corporate-1` (corporate.woodfinegroup.com, not yet deployed) |
| `mediakit-marketing-vm` | the marketing landing instances |
| `mediakit-dist-vm` | the distribution/compliance-feed instance, once built |

`moonshot-toolkit build os-mediakit/system-spec.toml` is the intended build command.
`system-spec.toml` declares the PDs, memory regions, and channels in a Microkit-shaped
TOML format. The output `build/system-image.bin` is bootable on any seL4-supported
AArch64 platform (qemu-arm-virt, Raspberry Pi 4, AWS Graviton).
The rationale mirrors `os-privategit`'s three separate instances (source vault,
software distribution, design assets): different public surfaces carry different
attack profiles, and a compromise of one wiki instance should not put a sibling
instance's process space at risk. This is a planned milestone, not yet started — no
`os-mediakit` VM, combined or per-instance, runs under seL4 today.

---

## What changes vs Phase 1, what stays the same

| Property | Ubuntu 24.04 (Phase 1) | seL4 Microkit (Phase 3, planned) |
| Property | Ubuntu 24.04 (Phase 1, today) | seL4 per-instance VMs (Phase 3, planned) |
|---|---|---|
| Guest OS | Ubuntu 24.04 Linux 6.x (glibc 2.39) | seL4 microkernel + Microkit PDs |
| Guest OS | Ubuntu 24.04 Linux 6.x (glibc 2.39), one guest for all co-tenant instances | seL4 microkernel, one guest per deployment instance |
| Host | QEMU/TCG (x86_64) | QEMU/KVM or bare metal AArch64 |
| Service binaries | Same (cross-compiled) | Same (recompiled for AArch64 no_std) |
| Wire protocols | CBOR-over-HTTP | CBOR-over-QUIC (same data schema) |
| Port numbers | Same (9090, 9092, ...) | Same (WireGuard overlay) |
| Service binaries | Same (cross-compiled) | Same, recompiled for the target seL4 guest |
| Isolation boundary | Process/filesystem separation within one shared guest | A full VM boundary per instance |
| Port numbers | Same (9090, 9093, 9095, ...) | Same, reachable over the PPN mesh |
| virtio-balloon | Present | Present (hypervisor layer unchanged) |
| Formal isolation | Linux kernel security model | seL4 intransitive non-interference proof |
| Key custody | OS file permissions | seL4 capability object — no OS |
| Key custody | OS file permissions | Per-VM key material, no shared guest to compromise |

---