bundle.h (3614B)
1 #ifndef KIT_BUILD_BUNDLE_H 2 #define KIT_BUILD_BUNDLE_H 3 4 #include <kit/build_coord.h> 5 #include <kit/core.h> 6 #include <kit/package.h> 7 #include <stddef.h> 8 #include <stdint.h> 9 10 #include "build.h" 11 #include "coord.h" 12 13 /* 14 * Shared traces, as signed bundles. A trace is a CLAIM ("these inputs => this 15 * output tree"), not self-verifying content: confirming it means re-running the 16 * assumed-deterministic recipe, the very work we avoid. So importing someone 17 * else's trace requires trusting the claimant. Bundles reuse the 18 * <kit/package.h> manifest + minisign + trust machinery wholesale: a signed 19 * `kit-build-traces 1` manifest lists (target, kind, trace-id, output-tree-id) 20 * claims, carried in a `.kpkg` alongside the trace bodies and the CAS blobs they 21 * reference — the serialized need-overlay maps and argv blobs (required, else 22 * an imported shallow trace cannot replay its `need`s) AND the deepset closure 23 * blobs a deep trace points at (required, else an imported deep trace cannot 24 * refresh) — plus optionally the referenced output trees/blobs. 25 * 26 * The security split is precise: a local build can deep/shallow-HIT on a remote 27 * builder's trace (obtaining the output without running the recipe) while 28 * trusting only the signed claim; the output bytes remain trustless, verified 29 * by tree-id/blob-id on use. 30 */ 31 32 /* One claim row in a bundle manifest. */ 33 typedef struct BuildTraceClaim { 34 char target[BUILD_TARGET_MAX]; 35 uint8_t kind; /* BuildTraceKind */ 36 uint8_t trace_id[BUILD_HASH_LEN]; 37 uint8_t output_tree[BUILD_HASH_LEN]; 38 } BuildTraceClaim; 39 40 /* Gather the named targets' recorded traces (newest candidates), collect the 41 * trace bodies + referenced overlay/argv blobs + the deepset-closure blobs each 42 * deep trace transitively points at (+ optional output trees/blobs), emit and 43 * sign a kit-build-traces manifest, and write the `.kpkg` to out_path. 44 * Signing/format/key come from `opts`. */ 45 int build_bundle_export(KitBuildCoordinator*, 46 const KitBuildExportOptions* opts); 47 48 /* Verify a bundle's signature against the trust inputs (the unchanged 49 * DISTRIBUTE.md model: -p key, the trusted-keys anchor, or --tofu; the signed 50 * trusted comment binds the signature to the manifest hash), then install the 51 * trace bodies into build/trace/, install referenced overlay/argv (and any 52 * packed outputs) into the CAS, and prepend the imported traces to the relevant 53 * target records. Output bytes are hash-verified on use. */ 54 int build_bundle_import(KitBuildCoordinator*, const KitBuildImportOptions* opts, 55 KitBuildImportResult* result); 56 57 /* Try to obtain a trace for `target` from the configured trace remotes 58 * (opts.trace_remotes), in order: render each remote's template, fetch the 59 * signed bundle via the exec host, verify it against that remote's trust anchor 60 * (trusted_keys / tofu), and import its traces. Returns BUILD_OK once a bundle 61 * imports, BUILD_ERR if none is configured or all fail. The trusted counterpart 62 * to build_remote_fetch (content is trustless; trace claims are trusted). */ 63 int build_trace_remote_pull(KitBuildCoordinator*, KitSlice target); 64 65 /* Emit / parse the canonical kit-build-traces manifest body (the bytes that get 66 * signed). Pure logic, mirroring dist_manifest_*. */ 67 int build_bundle_manifest_emit(const BuildTraceClaim*, size_t n, 68 KitWriter* out); 69 int build_bundle_manifest_parse(const uint8_t* data, size_t len, 70 BuildTraceClaim* out, size_t cap, size_t* n, 71 char* err, size_t errcap); 72 73 #endif