Transport & Attestation

TL;DRThis page describes the current programmatic path: the Node SDK and reference daemon connect to the engine over RA-TLS terminated inside the Darknyx CVM. The deployment gateway passes the encrypted TLS stream through without seeing the request. Before sending credentials or order intent, the client checks that the certificate on its actual connection is bound by a fresh TDX quote to the approved engine image, boot session, and settlement-signer set.

The trust boundary

At each engine boot, Darknyx generates a random TLS key in memory and never persists it. The engine serves HTTPS and WebSocket traffic with that key. The deployment gateway routes the connection by hostname but does not terminate its TLS, so plaintext first appears inside the measured engine:

client ═════ TLS encrypted end-to-end ═══► gateway (passthrough) ═══► Darknyx CVM
                                                                        │
                                                               plaintext only here

What this gives you:

Fresh transport identity. A later boot has a different certificate and must be verified again.
Connection binding. The SDK compares the quote-bound SPKI with the certificate observed on the socket carrying the session; a quote fetched from an unrelated probe is not enough.
One boundary for REST and streams. HTTPS and wss:// use the same boot-scoped enclave identity.

Verifying the engine

The programmatic client establishes trust before authentication. It first observes the engine’s self-signed certificate, requests fresh transport evidence over that connection, and verifies the complete chain below. A reconnect or boot change must be gated again; a hostname or ordinary CA certificate is not the root of trust.

GET /transport-attestation

Returns a nonce-bound TDX quote whose manifest commits to the TLS SPKI, boot session, application identity, and complete settlement-signer set. The certificate is self-signed by design. Never work around that with curl -k, NODE_TLS_REJECT_UNAUTHORIZED=0, or a custom client that simply accepts every certificate. The SDK accepts it only after the quote proves the SPKI belongs to the approved enclave boot.

GET /info

Returns the identity of the running image.

{
  "app_id": "…",
  "instance_id": "…",
  "compose_hash": "…",
  "tee_pubkey": "…",
  "tee_pubkeys": ["…", "…"],
  "boot_session_id": "…",
  "version": "…"
}

Field	Description
`app_id`	Deterministic id derived from the deployer and the compose configuration.
`instance_id`	Identifier of this specific VM instance.
`compose_hash`	Self-reported SHA-256 of the deployment manifest. Useful for display; the authoritative value comes from the quote-bound event log.
`tee_pubkey`	Primary (shard-0) Ed25519 settlement signer, kept as a convenience field.
`tee_pubkeys`	Full ordered signer set, one per tree shard. Verify the entire set against finalized `VaultConfig.tee_pubkeys`.
`boot_session_id`	Fresh process-boot id signed into every canonical place and cancel intent, preventing cross-restart replay. Verify that it matches the value bound by the transport-attestation manifest.
`version`	Build version tag of the engine.

GET /attestation

Returns an Intel TDX attestation quote plus the data needed to verify it. The quote is a hardware-signed measurement of the running VM. A client passing a fresh reportData nonce gets a quote bound to that nonce (freshness) and to the hash of the complete ordered signer set.

Field	Description
`quote`	Hex-encoded TDX quote (DCAP format), the hardware-signed measurement.
`event_log`	The boot event log, replayed during verification to confirm the recorded compose hash and instance identity.
`report_data`	64 bytes bound into the quote: caller nonce in bytes 0–31, then `SHA-256(pk0 ∥ … ∥ pkK-1)` in bytes 32–63.
`tee_pubkey`	Primary signer, for convenience. Fetch `/info.tee_pubkeys` to recompute the bound set hash.

The verification chain

A verifying client confirms, in order:

The caller nonce is fresh and the transport quote’s hardware signature is valid with a current platform trusted computing base.
Rebuilding the canonical transport manifest reproduces the quote-bound digest, and its tls_spki_sha256 equals the certificate on the actual socket carrying the session.
The event log is structurally valid, contains exactly one runtime-typed compose-hash event, and has no impossible entry carrying both a supplied digest and a payload. Replaying it reproduces the DCAP-verified quote’s RTMR3, and the measured compose hash equals the independently pinned release value.
The manifest’s boot session matches /info; its complete ordered signer set equals a finalized on-chain VaultConfig.tee_pubkeys read.

The Node SDK’s verified transport performs the socket, nonce, quote, event-log, measurement, boot and signer-set checks. The reference daemon also refreshes the finalized on-chain comparison and pauses new trading when it becomes stale or mismatched. Only after all four checks hold should a client authenticate or send order intent.

Pin the measurement, not the hostThe security guarantee comes from the measurement, not from the hostname. A client that connects over TLS but skips attestation has confidentiality to some machine; it has not verified that the machine runs the expected engine. Pin a release measurement independently, then verify the quote and event log.

Gateway evidence is not the programmatic trust root

The dstack gateway also serves files under /evidences/ (quote.json, cert.pem, ACME-account metadata, and an integrity checksum). Those files describe the gateway’s certificate and confidential deployment; they are not the Darknyx engine quote returned by /attestation. They are useful when evaluating the surrounding deployment, but they are not needed to authenticate the programmatic session: the gateway does not terminate that session’s TLS. Fetching the evidence bundle cannot replace checking the enclave certificate and /transport-attestation response on the connection the client actually uses.

What attestation does and does not give you

Guarantees	Does not guarantee
You are talking to the exact, measured engine build.	That you submitted the order you meant to (that is on your client).
The engine that matches controls the complete signer set accepted on-chain.	That matching obeyed an unmeasured policy or that the service will remain live.
Order intent is confidential in transit and at rest inside the enclave.	Protection against losing your own keys; custody of the trading and spending keys is yours.

Raw evidence bundle

Served by the deployment’s ingress rather than by the engine, these expose the underlying artifacts so a third party can reproduce the verification independently.

Getting Started

System

Account

Instruments

Orders

Settlement

Tree

WebSocket

Transport and attestation

Transport & Attestation

The trust boundary

Verifying the engine

GET /transport-attestation

GET /info

GET /attestation

The verification chain

Gateway evidence is not the programmatic trust root

What attestation does and does not give you

Raw evidence bundle

​Transport & Attestation

​The trust boundary

​Verifying the engine

​GET /transport-attestation

​GET /info

​GET /attestation

​The verification chain

​Gateway evidence is not the programmatic trust root

​What attestation does and does not give you

​Raw evidence bundle

Transport & Attestation

The trust boundary

Verifying the engine

GET /transport-attestation

GET /info

GET /attestation

The verification chain

Gateway evidence is not the programmatic trust root

What attestation does and does not give you

Raw evidence bundle