Agent release admission
POST /api/agents/publish (what kanade agent publish, both fleet-deploy scripts and any direct HTTP caller use) only registers a file in the agent_releases Object Store if the file proves it is the kanade-agent binary. The backend decides; the CLI repeats the same check only to fail fast. POST /api/app-packages/{name}/{version} and app_packages are unaffected and still accept any file.
What is checked
Before anything is written to the Object Store, the backend parses the upload (it is never executed, so foreign-platform files are safe):
- OS / CPU from the executable itself: Windows PE x86_64 / aarch64, Linux ELF x86_64 / aarch64, thin arm64 macOS Mach-O. File names are ignored. The container must be a linked executable: PE executable (no DLL), Mach-O
MH_EXECUTE, or ELFET_EXEC/ET_DYNwith a nonzero entry point forET_DYN(PIE). Intermediate objects (ET_REL,MH_OBJECT), shared libraries and core dumps are rejected even if they carry valid agent metadata. - A release-metadata section, found through the container's section table:
.kanade(PE, ELF) or__DATA,__kanade(Mach-O). Missing, duplicated, truncated, wrongly framed, unknown-schema or non-JSON sections are rejected. Identifying bytes elsewhere in the file (appended or in other sections) do not count. - Product is exactly
kanade-agent. ThekanadeCLI, backend, client and any renamed copy of them are refused. - Platform in the metadata equals the platform of the container.
- Version: the embedded version is the release version and the key is derived from it. A
versionform field /--versionis optional; if given (ignoring surrounding whitespace and one leadingv) it must equal the embedded version. On Windows a VERSIONINFO that contradicts the embedded version is refused too.
A refusal is HTTP 400 with the reason and what to do; nothing is stored, and an existing release under the same key is left byte-for-byte untouched.
This identifies the product the build system stamped; it is not a signature and does not authenticate a deliberately forged binary (publishing already requires an authenticated operator).
Legacy binaries
Agents built before this metadata existed (up to v0.80.0) carry no section and are refused, whether or not --version is passed; there is no bypass flag. Releases already in the Object Store are not re-checked or changed: being stored does not mean they were verified. To re-publish an old version, rebuild it from a source tree that embeds the metadata.
How the metadata gets into the agent
crates/kanade-agent/build.rs がエンベロープ(KNAGMETA、schema 1、CARGO_PKG_VERSION と Cargo target から得た JSON {product, version, platform})を生成し、src/release_metadata.rs が専用セクションへリンクします。main から読み取るため LTO、--gc-sections / -dead_strip、strip でも保持されます。埋め込むのは agent crate のみです。補助スクリプト scripts/ci/release-post-build.sh はビルド済みバイナリ(macOS では署名後)と配布アーカイブを scripts/ci/verify-agent-dist.py で読み取り専用検証し、メタデータの欠落や不整合時に非ゼロを返します。導入済みバイナリの変更や再署名は行いません。
現在の kata 管理 release.yml はこの補助スクリプトを呼びません。CLI / バックエンドへのアップロード時の検証は有効ですが、release workflow の成功だけでは配布アーカイブのメタデータ検査が実行された証拠になりません。
Upgrade / release ordering
The first release containing this change (the one after v0.80.0, call it N) must be rolled out in this order:
- Release
N(CI verifies the agent artifacts carry the metadata). - Update the backend to
N. From now on only metadata-bearing agents can be published; old agents already in the store keep working. - Publish the
Nagents withkanade agent publish(or the fleet-deploy scripts) for each platform. - Roll out with
kanade agent rollout N …as usual. Running agents older thanNneed no change: they self-update from the store exactly as before, and the store now only receives real agents.
Publishing before step 2 would still work but would be unprotected; do not publish a legacy-built agent after step 2 — it is refused.