@holoscript/holosystem 0.2.2 → 0.2.3

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

@@ -0,0 +1,91 @@
+# Machine VM launch threat model
+
+## Claim
+
+`vm-launch` and `vm-launch-whpx` prove that two launches of the same measured
+QEMU runtime, Linux kernel, and initramfs reached the same pinned serial success
+signal through generated, closed full-system QEMU invocations. Optional virtual
+devices are minimized: there is no default device set, network, USB, display, or
+monitor. Each receipt binds the plan, complete runtime manifest, executable,
+guest artifacts, and adapter-specific fixed launch policy.
+
+The TCG adapter is a machine-VM execution receipt and sets `hardwareBacked` to
+`false`. The separately named WHPX adapter selects only `accel=whpx`, has no TCG
+fallback, and sets `hardwareBacked` to `true` only when two explicit WHPX boots
+succeed with matching observations. This proves use of QEMU's hardware-backed
+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.
+
+## Protected assets and trust boundaries
+
+The protected inputs are the declarative plan, the complete caller-owned QEMU
+runtime directory, the guest kernel, and the guest initramfs. Operational paths
+are not part of the plan or receipt. The receipt exposes digests, byte counts,
+bounded launch summaries, coverage, and named residual boundaries.
+
+The tracer does not prove:
+
+- QEMU, the guest kernel, initramfs, or firmware were built from trusted source;
+- Windows, the CPU, QEMU, or Node.js implemented the measurement correctly;
+- TCG hardware virtualization, or WHPX IOMMU separation, measured boot, Secure
+  Boot, TPM, confidential memory, or side-channel resistance;
+- host crash dumps, swap, hibernation, debugger state, or physical custody are
+  protected;
+- the guest success program establishes a broader workload security property.
+
+Those limitations are machine-readable in `boundaries` and `coverage` rather
+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                              |
+
+## Fixed launch policy
+
+The plan does not express QEMU arguments. Each implementation generates a q35
+invocation for exactly one bound accelerator (`tcg` or `whpx`) with one CPU,
+128 MiB, no user configuration, no default devices, no network, no USB, no
+display, no monitor, no reboot, direct kernel boot, serial stdio, and a fixed
+ISA debug-exit device. The TCG adapter pins QEMU's `max` CPU model; the WHPX
+adapter leaves CPU selection to that hardware backend because the TCG model is
+not a valid substitute. The guest command line is fixed and disables trust in
+CPU random seeding. The process has a bounded timeout and output buffer and
+receives only a small host/runtime environment.
+
+Exactly two launches are required. The snapshot is remeasured immediately before
+and after each launch. Each launch must exit with the fixed debug-exit status and
+produce the plan-pinned serial digest. TCG must emit zero stderr bytes. WHPX must
+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.
+
+## Residual risk and next layer
+
+The QEMU runtime closure includes firmware data files and DLLs, so substitution
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holoscript/holosystem",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Portable bootstrap, consumption catalog, lineage, and bounded-work contract for HoloSystem consumers.",
   "releaseLane": "v0-preview",
   "keywords": [
@@ -33,6 +33,7 @@
   },
   "files": [
     "bin",
+    "docs",
     "src",
     "README.md",
     "LICENSE"
@@ -41,7 +42,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node --check src/index.mjs && node --check src/catalog.mjs && node --check bin/holosystem.mjs",
+    "build": "node --check src/index.mjs && node --check src/catalog.mjs && node --check src/substrate.mjs && node --check src/substrate-import.mjs && node --check src/substrate-debian-release.mjs && node --check src/substrate-import-debian.mjs && node --check src/native-build.mjs && node --check src/vm-launch.mjs && node --check bin/holosystem.mjs",
     "test": "node --test test/*.test.mjs",
     "smoke": "node bin/holosystem.mjs --help",
     "check": "pnpm run build && pnpm run test && pnpm run smoke",

package/src/index.mjs

@@ -1,6 +1,43 @@
 export const HOLOSYSTEM_CONFIG_SCHEMA = 'holoscript.holosystem.consumer.v1';
 export const HOLOSYSTEM_INSPECTION_SCHEMA = 'holoscript.holosystem.inspection.v1';
 
+export {
+  HOLOSYSTEM_REBUILD_ATTESTATION_SCHEMA,
+  HOLOSYSTEM_SUBSTRATE_SCHEMA,
+  buildSubstrateClosure,
+  createRebuildAttestationPayload,
+} from './substrate.mjs';
+
+export { HOLOSYSTEM_SUBSTRATE_IMPORT_SCHEMA, importNpmPackageLock } from './substrate-import.mjs';
+export { importDebianPackageSnapshot } from './substrate-import-debian.mjs';
+export {
+  HOLOSYSTEM_DEBIAN_RELEASE_AUTH_SCHEMA,
+  verifyDebianRepositoryRelease,
+} from './substrate-debian-release.mjs';
+export {
+  HOLOSYSTEM_NATIVE_BUILD_PLAN_SCHEMA,
+  HOLOSYSTEM_NATIVE_BUILD_RECEIPT_SCHEMA,
+  HOLOSYSTEM_NATIVE_BUILD_SOURCE_SCHEMA,
+  createNativeRebuildAttestationPayload,
+  inspectNativeBuildPlan,
+  inspectNativeBuildSource,
+  runNativeBuild,
+} from './native-build.mjs';
+export {
+  HOLOSYSTEM_VM_ASSET_SCHEMA,
+  HOLOSYSTEM_VM_EXECUTOR_SCHEMA,
+  HOLOSYSTEM_VM_LAUNCH_PLAN_SCHEMA,
+  HOLOSYSTEM_VM_LAUNCH_RECEIPT_SCHEMA,
+  HOLOSYSTEM_WHPX_VM_LAUNCH_PLAN_SCHEMA,
+  HOLOSYSTEM_WHPX_VM_LAUNCH_RECEIPT_SCHEMA,
+  inspectVmExecutor,
+  inspectVmLaunchAsset,
+  inspectVmLaunchPlan,
+  inspectWhpxVmLaunchPlan,
+  runVmLaunch,
+  runWhpxVmLaunch,
+} from './vm-launch.mjs';
+
 export {
   HOLOSYSTEM_CATALOG_SCHEMA,
   HOLOSYSTEM_CONSUMER_INPUT_SCHEMA,