docs: explain app proofs and boot proofs#669
Open
emostov wants to merge 3 commits into
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
emostov
force-pushed
the
docs/app-and-boot-proofs
branch
from
c910a75 to
20b2ad0
Compare
docs: add fetching, multi-replica, and bundling sections Followup after re-reading the source Slack thread: - document the public get_boot_proof / get_latest_boot_proof / list_app_proofs endpoints so verifiers know where to fetch Boot Proofs - document the multi-replica behavior (per-enclave Ephemeral Keys, different responses signed by different keys, cache by Ephemeral key) - document the Anchorage-style pattern of bundling App Proof + Boot Proof in a single response, and point at tvc_server.go - add public_api_server.go and tvc_server.go to the code-pointers list docs: scrub internal references; remove caching and replica sections - Remove all references to internal tkhq/mono repo paths and file locations; rephrase to describe behavior, not implementation. - Remove the 'Caching Boot Proofs' section entirely. - Remove the 'Multiple replicas and per-enclave Ephemeral Keys' section entirely. - Remove the 'Where this lives in the code' section (was wall-to-wall tkhq/mono links); App Proof bytes-on-the-wire reference now points to the public Rust + TypeScript SDK verifier implementations from the 'Who produces it' subsection. - Drop named-customer reference (Anchorage) from the bundling pattern paragraph; describe the generic pattern instead. - Soften the cross-link from security/turnkey-verified.mdx so it no longer promises a 'where each proof is produced in the codebase' walkthrough. docs: rewrite to conceptual-only per reviewer - Remove all remaining implementation-level narration (producer reads X then Y then Z, bundle-pattern step-by-step instructions, 'who produces it' sub-sections describing internal mechanics). - Drop the 'Bundling the verifiability chain' subsection entirely; the generic public-API description of fetching proofs covers what a customer needs to know. - Collapse Boot Proof / App Proof producer paragraphs into single what-level sentences; no how-it-works narration. - Keep cryptography, JSON wire format, public API endpoints, and the trust-boundary discussion (Quorum vs Ephemeral Key) untouched per reviewer scope. various cleanup
emostov
force-pushed
the
docs/app-and-boot-proofs
branch
from
20b2ad0 to
bd0c0c2
Compare
narimonf
reviewed
May 25, 2026
| } | ||
| ``` | ||
|
|
||
| On its own, this proves that the QuorumOS enclave instance with the corresponding Ephemeral private key signed the address derivation claim. When the verifier matches `publicKey` to a valid Boot Proof, the claim is tied back to the attested enclave instance and the code identified by its manifest. Your own TVC App Proofs follow the same chain even if the payload schema is specific to your application. |
Contributor
There was a problem hiding this comment.
I'd switch the order of app proof on its own, + boot proof to boot proof on its own, + app proof. On it's own, the app proof doesn't prove anything about quorumOs or an enclave, it just proves that a key signed a payload. What the boot proof proves on its own is easier to reason about imo
emostov
force-pushed
the
docs/app-and-boot-proofs
branch
from
d8deca5 to
045a04f
Compare
narimonf
reviewed
May 26, 2026
| } | ||
| ``` | ||
|
|
||
| On its own, this payload does not that a particular enclave signed it; but when a verifier can match `publicKey` to a valid Boot Proof, the claim is tied back to an enclave instance and the code identified by its manifest. Your own TVC App Proofs follow the same chain even if the payload schema is specific to your application. |
annieke
reviewed
May 26, 2026
| A Boot Proof is a bundle of artifacts that a verifier can use to establish what code an enclave is running. It contains: | ||
|
|
||
| - The **[AWS Nitro attestation document](https://docs.aws.amazon.com/enclaves/latest/user/verify-root.html#the-attestation-document)** (DER-encoded COSE Sign1), which contains PCR measurements, the AWS certificate chain, the enclave's Ephemeral public key (in the `public_key` field), and arbitrary `user_data`. | ||
| - The **QOS manifest** and **manifest envelope**, which describe the application binary and arguments, the operator quorum, the quorum public key, and other deployment configuration. The AWS attestation document's `user_data` is set by QOS to the digest of this manifest, which is what binds the two together. |
Contributor
There was a problem hiding this comment.
Suggested change
| - The **QOS manifest** and **manifest envelope**, which describe the application binary and arguments, the operator quorum, the quorum public key, and other deployment configuration. The AWS attestation document's `user_data` is set by QOS to the digest of this manifest, which is what binds the two together. | |
| - The **[QOS](https://github.com/tkhq/qos) manifest** and **manifest envelope**, which describe the application binary and arguments, the operator quorum, the quorum public key, and other deployment configuration. The AWS attestation document's `user_data` is set by QOS to the digest of this manifest, which is what binds the two together. |
or something to specify what QOS is
annieke
reviewed
May 26, 2026
|
|
||
| App Proofs are generated by enclave application logic. What makes an App Proof an App Proof is that application-level output is signed with an enclave's Ephemeral Key, so that output can be linked back to the Boot Proof Turnkey stores. | ||
|
|
||
| As a TVC builder, you decide what your App Proof payload needs to prove. For example, your application might sign a model inference result, a private computation outcome, or a protocol-specific state transition. The important design requirement is that the payload commits to the facts a verifier will care about, and that the signature uses the enclave Ephemeral Key so the verifier can connect the payload to a valid Boot Proof. |
Contributor
There was a problem hiding this comment.
out of scope for this but thinking a "how to write an app proof for your app" is a good doc to have in TVC before launch
annieke
reviewed
May 26, 2026
|
|
||
| The answer is a trust boundary distinction. | ||
|
|
||
| The quorum key is designed to live across many different versions of an enclave app and can not be provably exclusive to a specific enclave instance, app binary, or configuration. The Quorum Key is provisioned via the [QuorumOS quorum provisioning protocol](https://github.com/tkhq/qos/blob/main/docs/boot_standard.md): share holders verify a node's attestation document, encrypt quorum key shares to the node's Ephemeral Key, and the node reconstructs the Quorum Key once the configured threshold is met. Because the Quorum Key can be provisioned into any enclave that satisfies the provisioning protocol, a Quorum Key signature can be linked with arbitrary code that has received that key. Turnkey customers have no way to attest "this private key only exists inside this enclave" for the Quorum Key, because that statement is not true at the cryptographic layer. |
Contributor
There was a problem hiding this comment.
Suggested change
| The quorum key is designed to live across many different versions of an enclave app and can not be provably exclusive to a specific enclave instance, app binary, or configuration. The Quorum Key is provisioned via the [QuorumOS quorum provisioning protocol](https://github.com/tkhq/qos/blob/main/docs/boot_standard.md): share holders verify a node's attestation document, encrypt quorum key shares to the node's Ephemeral Key, and the node reconstructs the Quorum Key once the configured threshold is met. Because the Quorum Key can be provisioned into any enclave that satisfies the provisioning protocol, a Quorum Key signature can be linked with arbitrary code that has received that key. Turnkey customers have no way to attest "this private key only exists inside this enclave" for the Quorum Key, because that statement is not true at the cryptographic layer. | |
| The quorum key is designed to live across many different versions of an enclave app and can not be provably exclusive to a specific enclave instance, app binary, or configuration. The Quorum Key is provisioned via the [QuorumOS quorum provisioning protocol](https://github.com/tkhq/qos/blob/main/docs/boot_standard.md): share holders verify a node's attestation document, encrypt quorum key shares to the node's Ephemeral Key, and the node reconstructs the Quorum Key once the configured threshold is met. Because the Quorum Key can be provisioned into any enclave that satisfies the provisioning protocol, a Quorum Key signature cannot cryptographically prove the app proof payload came from the _inside_ of a _specific_ enclave. |
reads a little more straightforward to me
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add explainer for App Proofs and Boot Proofs for TVC customers, using Turnkey app proofs as a concrete example of how app proofs can be implemented