Merge pull request #774 from tkhq/zeke/document-boot-standard-changes

docs: clarify when boot standard is required vs key forward

Author: emostov

README.md

@@ -218,7 +218,7 @@ The application QuorumOS pivots to once it finishes booting. This application's
 
 There are two modes for provisioning:
 
-- [Boot Standard](docs/boot_standard.md): mode for provisioning an enclave with quorum key shares. This is commonly used if there is no instance from the same namespace to key forward from or if there is any change to the QuorumOS verification API that breaks Key Forwarding. Boot Standard is also required if the manifest set or share set change.
+- [Boot Standard](docs/boot_standard.md): mode for provisioning an enclave with quorum key shares. This is required when there is no provisioned instance in the namespace to key forward from (first boot after genesis, or all nodes lost), when the manifest set or PCR3 (host IAM role) changes, or when a QuorumOS change breaks Key Forwarding itself. See [When Is Boot Standard Required?](docs/boot_standard.md#when-is-boot-standard-required) for the full decision rule.
 - [Key Forward](docs/key_forward.md): mode for provisioning an enclave from an already provisioned enclave of the same namespace. This allows QuorumOS to support horizontal scaling cloud workloads. Effectively, a pre-existing enclave will verify attestation and manifest for a new enclave and then forward its quorum key to the new enclave.
 
 ### Remote Attestation

docs/GUIDE.md

@@ -647,7 +647,7 @@ The quorum key reconstructs to the same value, but now your updated application
 
 **The Nonce Mechanism**: The monotonically increasing nonce prevents rollback attacks. Members should only approve manifests with nonces higher than the current deployment, ensuring adversaries cannot force downgrades to vulnerable versions.
 
-**Note**: if we had two nitro enclaves running simultaneously targeting the same application but different versions, we could use the already provisioned enclave to key forward off of, removing the need to post shares. This is helpful for HA production setups that require horizontally scalable workloads with no human intervention. Key forwarding is not covered in this guide, but you can find some information [here](https://github.com/tkhq/qos/blob/main/src/qos_core/KEY_FORWARDING.MD).
+**Note**: if we had two nitro enclaves running simultaneously targeting the same application but different versions, we could use the already provisioned enclave to key forward off of, removing the need to post shares. This is helpful for HA production setups that require horizontally scalable workloads with no human intervention. Key forwarding is not covered in this guide, but you can find some information in [Key Forward](key_forward.md) and [When Is Boot Standard Required?](boot_standard.md#when-is-boot-standard-required).
 
 ---
 

docs/boot_standard.md

@@ -3,6 +3,59 @@
 Boot a QOS node by submitting an approved manifest and pivot binary, then
 provision the node with quorum key shares. Share set members verify the node's attestation document and submit their shares encrypted to the node's Ephemeral Key. Once the configured threshold of shares has been posted, the node reconstructs the Quorum Key and starts the Pivot App.
 
+## When Is Boot Standard Required?
+
+Boot Standard is the provisioning mode where Share Holders post Quorum Key
+shares to a freshly booted node after verifying its setup attestation. The
+alternative, [Key Forward](key_forward.md), lets an already provisioned node in
+the same namespace (the source node) export the Quorum Key to a fresh node with
+no human involvement.
+
+Every change deployed to an enclave — new pivot app, new QOS image, new
+manifest configuration — is shipped by booting a fresh node with a new
+Manifest-Set-approved manifest. The only question is whether that fresh node
+can be provisioned by Key Forward or needs a Boot Standard share ceremony. The
+answer depends on the source node:
+[`export_key`](../src/qos_core/src/protocol/services/key.rs) refuses to
+forward the Quorum Key unless the new manifest passes its checks. Boot Standard
+is required exactly when no node can (or may) act as the source.
+
+Changes that do **not** require Boot Standard — Key Forward works, as long as
+at least one provisioned node in the namespace is able to act as the source:
+
+* Pivot App updates (new pivot hash) and pivot configuration changes (args,
+  env, restart policy, socket pool size), via a new approved manifest with an
+  incremented nonce. This is the common update flow.
+* QOS image updates (new PCR0/PCR1/PCR2). The source node checks the new manifest's
+  PCRs against the *new node's* attestation document, not against its own
+  measurements; the Manifest Set's threshold approvals are what vouch for the
+  new QOS version.
+* Adding capacity or replacing instances with an unchanged manifest (equal
+  nonce is accepted when the manifest hash is identical).
+
+Changes that **do** require Boot Standard — the source node refuses to export,
+or no source node exists:
+
+* First boot of a namespace after genesis: no provisioned node exists yet.
+* Loss of every provisioned node in the namespace (disaster recovery).
+* Manifest Set changes, members or threshold (`DifferentManifestSet`): a source
+  node only trusts approvals from its own Manifest Set, so rotating the set
+  requires re-provisioning by the Share Set.
+* PCR3 changes, i.e. a new host IAM role or AWS account (`DifferentPcr3`).
+* Namespace name changes (`DifferentNamespaceName`).
+* A manifest nonce lower than the source node's, or an equal nonce with a
+  different manifest hash (`LowNonce`, `DifferentManifest`). A rollback can only
+  be key-forwarded from a source node whose own nonce is low enough.
+* A different Quorum Key (`DifferentQuorumKey`) — in practice a new namespace,
+  starting with its own genesis ceremony.
+* QOS releases that break the key-forward protocol itself: if a source node on
+  the old release cannot decode the new node's request or verify its attestation
+  document, the first node on the new release must be Boot Standard
+  provisioned. Wire compatibility is normally maintained to avoid this, so
+  treat any breaking change to `ProtocolMsg`, manifest encoding, or attestation
+  verification as a potential Boot Standard event and verify Key Forward
+  across the version boundary.
+
 ## New terms
 
 * **Node**: The un-provisioned QOS node being booted.