Dstack-TEE / Dstack-TEE/dstack

0.6 prerelease checklist: stabilize guest-agent API and SDKs

Đang mở
#1,094 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Rust
Star
544
Fork
96
Merge trung bình
23 giờ 40 phút
Pull request đã merge (30 ngày)
126

Mô tả

## Objective

Ship dstack 0.6 with a stable, versioned guest-agent API and consistent Go, JavaScript/TypeScript, Python, and Rust SDKs. Existing 0.5.x clients must continue to work against a 0.6 agent.

## Compatibility

- [x] Keep the unversioned API fully compatible with 0.5.x, verified with v0.5.10 generated clients and SDKs. — #1121 runs the released SDK suites against the current agent in CI. The pinned tags are **v0.5.8 and v0.5.11**, not v0.5.10: `v0.5.10:sdk` and `v0.5.11:sdk` are the same tree object, so running both bought nothing. Note the limit — old JSON clients ignore unknown keys, so this job catches *breaking* changes to the frozen surface but not *additive* ones; the shape freeze in `frozen_surface` is what covers additions.
- [x] Keep `GetQuote` unchanged: the v0.5 response fields and semantics remain the complete contract. Cross-platform attestation is exposed through `Attest`, not `GetQuote`.
- [x] Keep `GetKey` wire- and behavior-compatible. Publish a normative specification for path, purpose, supported algorithms, defaults, output encoding, and signature-chain verification. — spec in #1123 (`docs/guest-api-v0.md`), byte-level: HKDF salt, what enters the KDF vs only the claim, both chain-link preimages, all three signing modes, and the hazard that `algorithm` does not domain-separate.
- [x] Make `EmitEvent` return 404 with informative error message (deprecated method)
- [x] Unknown algorithms must be rejected.

## Attestation

- [x] Make `Attest` the single API for platform and GPU attestation

## SDKs

- [ ] Release all changed SDKs as 0.6.0 and apply semantic versioning consistently.
- [x] Expose the same `TlsKeyOptions` fields and defaults in every SDK. `usage_server_auth` defaults to `true`; remove the unused `path` option. — #1120
- [x] Represent the TLS private key as PEM and provide an explicit `toPkcs8Der()` conversion. Remove ambiguous byte-conversion APIs. — resolved differently, deliberately. The ambiguous accessor is gone from v1 (#1120) and no `toPkcs8Der()` replaced it: v1 returns PEM and nothing else. The accessor existed to feed the key into the blockchain adapters, v1 has no chain-flavored surface, and DER is one standard-library call away for anyone who wants it. v0 keeps the accessor, because the adapters are v0-typed and that surface is frozen. Reopen this if a v1 caller turns up who needs DER from the SDK itself.
- [x] Represent protobuf byte fields as bytes in Rust, not hex strings. — #1124 (open), and in every SDK rather than Rust alone: eleven response fields plus `report_data`, with the `decode_*` helpers deleted. The JSON wire is unchanged.
- [x] Make all SDKs report non-2xx responses consistently, including the server error and HTTP status. — #1120, pinned by tests in #1120 that assert the exact status an image without nvattest answers.
- [x] Regenerate and review the protobuf, HTTP, and SDK reference documentation. — v1 and v0 both have written specs now (`docs/guest-api-v1.md`, `docs/guest-api-v0.md`) and `sdk/curl/api.md` was corrected, but the per-SDK reference docs have not been regenerated.

## Versioned API (future)

- [x] Introduce the long-term API under a versioned URL/service namespace such as `/prpc/v1/...` and protobuf package `dstack.guest.v1`. API selection must not depend on request headers. — #1116; selection is by URL path alone.
- [x] Use `*Request` and `*Response` consistently for new messages. Keep the method name `Attest`.
- [ ] Give opaque JSON fields explicit `*_json` names in v1, or use typed messages where the schema is stable. — **not done.** `InfoResponse` still carries `app_compose`, `vm_config` and `key_provider_info` as bare `string` fields whose comments say they are JSON documents passed through unparsed. v1 is unreleased, so this is still cheap to change.

## Signing (future)

- [ ] Provide `Sign` with an explicit key specification containing path, purpose, and algorithm. — v1 has no `Sign`; the frozen v0 `Sign` is now specified in `docs/guest-api-v0.md`.
- [ ] Add `GetSigningKey` to return the corresponding public key and certification chain without signing a message. — v1 `GetKey` returns `public_key` and `signature_chain` alongside the key, which covers the use case but not as a separate method.
- [x] Provide signature verification as SDK functionality rather than an agent RPC. — #1110. v0's `Verify` RPC is still served for 0.5.x clients and is documented as frozen.
- [x] Specify the exact Ed25519 and secp256k1 message and prehashed modes. — done for the frozen v0 surface in #1123, including `secp256k1_prehashed` requiring the caller to supply the digest. v1 has no signing surface to specify.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start with the unchecked SDK and versioned API items in this checklist, then read docs/guest-api-v1.md, docs/guest-api-v0.md, and the open work in #1124. Review the remaining SDK release and per-SDK documentation tasks, the opaque JSON field names, and protobuf byte representations. Done means the changed SDKs are released as 0.6.0, the v1 schema is corrected, and reference documentation is regenerated.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
go, javascript, python, rust, typescript
Lĩnh vực
api, backend, documentation
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
42/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.