docs: give the frozen v0 guest API a written contract

[kvinwang]

Closes two open items on the 0.6 prerelease checklist (#1094): publish a normative GetKey specification, and specify the exact Ed25519/secp256k1/prehashed Sign modes.

The gap

#1116 froze the unversioned guest-agent API at exactly what v0.5.11 served, and docs/guest-api-v1.md is normative for v1. That leaves the surface which is closed forever, and which every deployed 0.5.x client talks to, as the one without a written contract — sdk/curl/api.md says outright that it is "a curl-oriented tour, not the contract".

The frozen SignRequest message carried no doc comments on either field: nothing stated which algorithm values are accepted, that k256 is an alias, or that data means a raw message in two modes and a pre-computed digest in the third.

What the spec pins

Everything is derived from the code, not from existing prose.

GetKey, byte level: HKDF-SHA256(salt="RATLS", IKM=app root k256 key, info=path, L=32) — with info being the caller's path verbatim, no tag, separator, or length prefix. Which inputs reach the KDF and which do not: only path does; purpose is echoed into the chain claim and nothing else; algorithm selects how the derived 32 bytes are interpreted and does not domain-separate. The algorithm table read off normalize_algorithm, including that an empty string defaults to secp256k1 and that k256 is an alias. Output encodings per algorithm. The chain claim keccak256("{purpose}:{hex(public_key)}"), the KMS link's preimage, the 65-byte r || s || v envelope, and verification steps that mirror the v1 spec's — anchor, rebuild, recover, check, bind — including the same warning about where the anchor must come from.

The consequence of one KDF serving both curves is stated plainly rather than argued: derive at one path under both algorithms and you hold one secret in two representations. That is what v1's KDF changed, and a caller on this surface has to account for it.

Sign gets a definition it never had. The three modes differ in what is signed — raw message under SHA-256 for secp256k1, raw message for ed25519, and a caller-supplied 32-byte digest that the agent does not re-hash for secp256k1_prehashed — and all three derive the same key, at path vms with purpose signing, which was written down nowhere.

Verify, the remaining methods (GetTlsKey, GetQuote, Attest, EmitEvent, Info, Version, Worker.GetAttestationForAppKey with its dip1:: report-data construction), and a brief Tappd section that points at the DstackGuest equivalents rather than becoming a second spec.

No new test vectors were generated. The document reuses only values an existing test already asserts, and cites the test by name; where no committed vector exists, it states no value.

Proto change is comments only

SignRequest.algorithm and SignRequest.data get doc comments. No field, method, reserved, or declaration is touched — the frozen descriptor-digest test passes with unchanged digests, which is the check that proves it.

Two corrections that fell out of writing it down

• sdk/curl/api.md claimed /Verify was "Removed in v0.6.0" and pointed callers at SDK helpers named verify_signature / verify_signature_chain. The RPC is alive on the frozen service, and those helpers exist nowhere in sdk/ — the CHANGELOG says explicitly that neither client ships one.
• Tappd.RawQuote requires exactly 64 bytes of report data where GetQuote pads. No document distinguished them.

Also fixed two pre-existing broken anchors in sdk/curl/api.md (#7-attest → #6-attest, #7-attest-gpu → #7-attest-gpu-v1), since the file was already being edited.

Verification

cargo test -p dstack-guest-agent-rpc --test frozen_surface passes with unchanged digests; cargo build -p dstack-guest-agent-rpc succeeds; every relative link resolves.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.