@holoscript/holosystem 0.2.3 → 0.2.4

package/README.md

@@ -511,6 +511,16 @@ AMD64 host, `qemu-system-x86_64.exe`, q35, 128 MiB, one CPU, and exactly two
 launches. Plans cannot provide a command, argument, environment variable,
 device, network, firmware, monitor, display, or fallback setting.
 
+`vm-launch-whpx-sandboxed` is a third, separately named vocabulary. It retains
+the explicit WHPX contract and additionally launches QEMU through the measured
+Windows helper shipped in this package. The helper creates a
+`CreateRestrictedToken(DISABLE_MAX_PRIVILEGE)` filtered token, lowers it to low
+integrity, admits at most the single Windows pass-through privilege, creates
+the process suspended with an explicit three-handle allowlist, assigns it to a
+kill-on-close Job Object with one-process, memory, and UI restrictions, and
+only then resumes it. A private low-integrity temporary directory is the only
+intended writable launch location.
+
 First measure the complete caller-owned QEMU runtime closure and both guest
 artifacts:
 
@@ -567,6 +577,25 @@ arguments for the WHPX schema. WHPX requires the Windows Hypervisor Platform
 API exposed to QEMU; see the [QEMU WHPX documentation](https://www.qemu.org/docs/master/system/whpx.html)
 and [Microsoft's Windows Hypervisor Platform API overview](https://learn.microsoft.com/en-us/virtualization/api/).
 
+For the sandboxed adapter, use schema
+`holoscript.holosystem.whpx-sandboxed-vm-launch-plan.v1`, add the following
+closed field, and call `vm-launch-whpx-sandboxed`:
+
+```json
+{
+  "sandbox": {
+    "kind": "windows-low-integrity-job-v1",
+    "launcherDigest": "sha256:<HOLOSYSTEM_WINDOWS_SANDBOX_LAUNCHER_DIGEST>"
+  }
+}
+```
+
+The exported `HOLOSYSTEM_WINDOWS_SANDBOX_LAUNCHER_DIGEST` is the digest of the
+package's audited launcher binary. A plan with another digest is blocked before
+process creation. The launcher source and local rebuild recipe are shipped in
+`native/windows-sandbox`; the measured binary is shipped in
+`native/windows-x64`.
+
 The runner creates a private snapshot and remeasures the complete QEMU closure,
 kernel, and initramfs before and after each launch. It then generates QEMU
 arguments that disable user configuration, default devices, networking, USB,
@@ -583,12 +612,21 @@ A verified TCG receipt includes `machine-vm-launch`,
 `hardwareBacked: false`, and leaves hardware acceleration missing. A verified
 WHPX receipt additionally includes `hardware-hypervisor-acceleration` and sets
 `hardwareBacked: true` only after two explicit WHPX launches succeed. Both
-adapters leave `host-process-isolation` missing: QEMU still has the ambient
+ambient adapters leave `host-process-isolation` missing: QEMU still has the ambient
 rights of the Windows process. Receipts therefore expose
 `isolation.hostProcess: "ambient-windows-process"` and
 `isolation.verified: false` even when WHPX acceleration is verified. Neither
-receipt proves an IOMMU, measured boot, firmware authenticity, confidential
-memory, or side-channel resistance. The
+ambient adapter receipt proves an IOMMU, measured boot, firmware authenticity,
+confidential memory, or side-channel resistance.
+
+A verified `vm-launch-whpx-sandboxed` receipt includes
+`host-process-isolation` only for the declared integrity, privilege,
+inherited-handle, lifetime, process-count, memory, and UI scope. It deliberately
+leaves `host-filesystem-confidentiality` and `host-network-isolation` missing:
+low integrity prevents writes up to medium-integrity objects but does not
+prevent reads, and the filtered token is not an AppContainer network capability
+boundary. The sandboxed receipt also does not prove the broader hardware and
+firmware properties named above. The
 exact claims are in the [VM launch threat model](./docs/vm-launch-threat-model.md).
 
 ```js
@@ -596,8 +634,11 @@ import {
   inspectVmExecutor,
   inspectVmLaunchAsset,
   inspectVmLaunchPlan,
+  inspectWindowsVmSandboxLauncher,
+  inspectWhpxSandboxedVmLaunchPlan,
   inspectWhpxVmLaunchPlan,
   runVmLaunch,
+  runWhpxSandboxedVmLaunch,
   runWhpxVmLaunch,
 } from '@holoscript/holosystem';
 ```

package/bin/holosystem.mjs

@@ -15,6 +15,7 @@ import {
   inspectVmLaunchAsset,
   runNativeBuild,
   runVmLaunch,
+  runWhpxSandboxedVmLaunch,
   runWhpxVmLaunch,
 } from '../src/index.mjs';
 
@@ -35,6 +36,7 @@ Usage:
   holosystem vm-asset --kind <kernel|initrd> --file <file> [--json]
   holosystem vm-launch --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
   holosystem vm-launch-whpx --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
+  holosystem vm-launch-whpx-sandboxed --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
   holosystem substrate --input <file> [--output <file>] [--force] [--json]
   holosystem --help
   holosystem --version
@@ -706,6 +708,11 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     launcher: runWhpxVmLaunch,
     commandName: 'vm-launch-whpx',
   });
+} else if (command === 'vm-launch-whpx-sandboxed') {
+  runVmLaunchCommand(argv.slice(1), {
+    launcher: runWhpxSandboxedVmLaunch,
+    commandName: 'vm-launch-whpx-sandboxed',
+  });
 } else if (command === 'substrate') {
   runSubstrate(argv.slice(1));
 } else {

package/docs/vm-launch-threat-model.md

@@ -17,6 +17,16 @@ Windows Hypervisor Platform adapter for those launches; it does not prove host
 process isolation. QEMU retains the ambient rights of its Windows process in
 both adapters.
 
+`vm-launch-whpx-sandboxed` is a separate schema and receipt. It runs the same
+measured WHPX launch behind a measured native Windows launcher that creates a
+filtered token with `DISABLE_MAX_PRIVILEGE`, sets low mandatory integrity,
+verifies at most the single pass-through privilege remains enabled, creates
+QEMU suspended with only NUL/stdout/stderr handles inherited, assigns QEMU to a
+Job Object before resume, and applies kill-on-close, one-process, 512 MiB, and
+full Job UI restrictions. Its `host-process-isolation` claim is limited to
+those controls. It is not an AppContainer and does not claim host filesystem
+confidentiality or host network isolation.
+
 ## Protected assets and trust boundaries
 
 The protected inputs are the declarative plan, the complete caller-owned QEMU
@@ -39,20 +49,23 @@ than implied away by a successful boot.
 
 ## Adversary specifications
 
-| Adversary action                                                                                     | Required result                                                            | Receipt or test evidence                                   |
-| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| Add a shell command, argument vector, environment field, device, network mode, or unknown plan field | Reject before process launch                                               | `vm-launch-field-unknown`; closed-vocabulary test          |
-| Put WHPX in a TCG plan, TCG in a WHPX plan, or request a fallback                                    | Reject rather than downgrade, cross-route, or overclaim                    | Separate schemas; accelerator/unknown-field tests          |
-| Replace any QEMU executable, DLL, firmware file, kernel, or initramfs before measurement             | Reject before process launch                                               | Runtime, binary, kernel, and initrd digest mismatch issues |
-| Replace measured files while the launch snapshot is being created                                    | Reject the snapshot                                                        | Runtime, kernel, and initrd snapshot mismatch issues       |
-| Replace caller-owned files after the first launch                                                    | Second launch still uses the same private snapshot                         | Private-snapshot substitution test                         |
-| Persistently self-modify the private runtime or guest artifacts during a launch                      | Reject on post-launch remeasurement                                        | Private-snapshot drift test                                |
-| Inject QEMU behavior through inherited environment variables or user configuration                   | Launch with a minimal environment and `-no-user-config`                    | Generated-argv test                                        |
-| Obtain implicit host devices or a communication channel                                              | Start with `-nodefaults`, `-nic none`, USB off, no display, and no monitor | Generated-argv test                                        |
-| Forge the guest signal, use the wrong exit path, or change adapter diagnostics                       | Reject the receipt and retain no raw output                                | Console, exit-code, and diagnostic-digest tests            |
-| Make clean launches observably disagree                                                              | Reject deterministic coverage                                              | `vm-launch-nondeterministic`                               |
-| Inject a fake process runner through the public API                                                  | Ignore it and execute only the bound process implementation                | Public process-runner injection test                       |
-| Put an operational path or guest output in the receipt                                               | Withhold it; report only digest and byte count                             | Receipt disclosure assertions                              |
+| Adversary action                                                                                     | Required result                                                             | Receipt or test evidence                                   |
+| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Add a shell command, argument vector, environment field, device, network mode, or unknown plan field | Reject before process launch                                                | `vm-launch-field-unknown`; closed-vocabulary test          |
+| Put WHPX in a TCG plan, TCG in a WHPX plan, or request a fallback                                    | Reject rather than downgrade, cross-route, or overclaim                     | Separate schemas; accelerator/unknown-field tests          |
+| Replace any QEMU executable, DLL, firmware file, kernel, or initramfs before measurement             | Reject before process launch                                                | Runtime, binary, kernel, and initrd digest mismatch issues |
+| Replace measured files while the launch snapshot is being created                                    | Reject the snapshot                                                         | Runtime, kernel, and initrd snapshot mismatch issues       |
+| Replace caller-owned files after the first launch                                                    | Second launch still uses the same private snapshot                          | Private-snapshot substitution test                         |
+| Persistently self-modify the private runtime or guest artifacts during a launch                      | Reject on post-launch remeasurement                                         | Private-snapshot drift test                                |
+| Inject QEMU behavior through inherited environment variables or user configuration                   | Launch with a minimal environment and `-no-user-config`                     | Generated-argv test                                        |
+| Obtain implicit host devices or a communication channel                                              | Start with `-nodefaults`, `-nic none`, USB off, no display, and no monitor  | Generated-argv test                                        |
+| Forge the guest signal, use the wrong exit path, or change adapter diagnostics                       | Reject the receipt and retain no raw output                                 | Console, exit-code, and diagnostic-digest tests            |
+| Make clean launches observably disagree                                                              | Reject deterministic coverage                                               | `vm-launch-nondeterministic`                               |
+| Inject a fake process runner through the public API                                                  | Ignore it and execute only the bound process implementation                 | Public process-runner injection test                       |
+| Select ambient execution, weaken a sandbox control, change the launcher, or forge its protocol       | Reject the distinct sandbox schema, launcher digest, or incomplete evidence | Closed sandbox vocabulary and protocol-forgery tests       |
+| Pass inherited parent handles into sandboxed QEMU                                                    | Admit only NUL input and the two bounded output pipes                       | Native handle-list evidence and receipt assertion          |
+| Spawn another process or escape launcher lifetime/resource bounds                                    | Assign suspended QEMU before resume to a one-process, kill-on-close Job     | Native Job evidence and adversarial receipt tests          |
+| Put an operational path or guest output in the receipt                                               | Withhold it; report only digest and byte count                              | Receipt disclosure assertions                              |
 
 ## Fixed launch policy
 
@@ -73,6 +86,13 @@ produce the plan-pinned diagnostic digest after removal of only the exact,
 randomized private-executor prefix that QEMU repeats at diagnostic line starts. Raw
 stdout and stderr are never included in the receipt.
 
+The sandboxed adapter additionally copies the package-pinned launcher into the
+private measured snapshot. The launcher protocol is closed and binary-safe: it
+returns base64 child streams plus derived control evidence, and HoloSystem
+rejects unknown fields, non-canonical base64, an unbounded enabled-privilege
+count, a missing control, or launcher stderr. Launcher and QEMU snapshots are
+remeasured before and after both launches.
+
 ## Residual risk and next layer
 
 The QEMU runtime closure includes firmware data files and DLLs, so substitution
@@ -80,12 +100,22 @@ changes its digest. Hashing does not establish provenance or measured boot.
 Windows QEMU also cannot disable host crash-dump capture through this contract;
 `host-crash-dump-custody` remains an explicit boundary.
 
-QEMU is not yet placed in an AppContainer, restricted token, job-object filesystem
-sandbox, or separate host VM. `virtual-device-minimization` therefore describes
-only the generated guest-facing virtual device surface; it must not be read as
-host-process or physical-device isolation.
-
-The next stronger layer must add a separately measured Windows host-process
-sandbox and firmware/measured-boot evidence. It must not reinterpret WHPX
-execution as proof of either property, and it must continue to report IOMMU,
-device-assignment, crash-dump custody, and side-channel boundaries separately.
+The ambient adapters do not place QEMU behind an OS process sandbox.
+`virtual-device-minimization` therefore describes only their generated
+guest-facing virtual device surface.
+
+The sandboxed adapter is narrower than AppContainer or a separate host VM. Its
+filtered token retains normal read access allowed to the caller and does not
+create an OS network capability boundary. The QEMU command still contains no
+guest network device, but a compromised host QEMU process could use host
+network APIs. `host-filesystem-confidentiality` and `host-network-isolation`
+therefore remain explicit missing layers even when the declared process
+isolation controls verify. The launcher binary is measured, but source-to-binary
+reproducibility and code signing remain part of `qemu-runtime-supply-chain` and
+host correctness trust.
+
+The next stronger layer is an AppContainer or separate-host-VM adapter that can
+retain WHPX access while proving capability-scoped filesystem and network
+denial, followed by firmware/measured-boot evidence. It must continue to report
+IOMMU, device-assignment, crash-dump custody, and side-channel boundaries
+separately.