Add elfuse oci subcommand for pulling and inspecting images

.gitignore

@@ -1,6 +1,11 @@
 build/
 archive/
-externals/
+# externals/ holds downloaded fixtures (kernel, rootfs, packages) that are
+# fetched on demand; tracking them in git would balloon the repo. The
+# vendored cJSON tree is an exception: it ships with the source so the
+# OCI parser builds out of the box.
+externals/*
+!externals/cjson/
 lib/modules/
 *.o
 *.bin

Makefile

@@ -63,15 +63,37 @@ SRCS := \
     debug/gdbstub.c \
     debug/gdbstub-reg.c \
     debug/gdbstub-rsp.c \
-    debug/log.c
+    debug/log.c \
+    oci/ref.c \
+    oci/cli.c \
+    oci/digest.c \
+    oci/blob-store.c \
+    oci/media-type.c \
+    oci/manifest.c \
+    oci/fetch.c \
+    oci/store.c \
+    oci/pull.c \
+    oci/inspect.c
 
 SRCS := $(addprefix src/,$(SRCS))
 OBJS := $(patsubst src/%.c,$(BUILD_DIR)/%.o,$(SRCS))
 
+# Vendored cJSON: third-party MIT JSON parser pinned at v1.7.18. Only OCI
+# translation units include it. Compiles cleanly with the project warning
+# posture, so no per-file CFLAGS override is required.
+CJSON_DIR := externals/cjson
+CJSON_OBJ := $(BUILD_DIR)/externals/cjson/cJSON.o
+OBJS += $(CJSON_OBJ)
+
+$(CJSON_OBJ): $(CJSON_DIR)/cJSON.c $(CJSON_DIR)/cJSON.h | $(BUILD_DIR)
+	@mkdir -p $(dir $@)
+	@echo "  CC      $<"
+	$(Q)$(CC) $(CFLAGS) -c -o $@ $<
+
 DISPATCH_MANIFEST := src/syscall/dispatch.tbl
 DISPATCH_GENERATOR := scripts/gen-syscall-dispatch.py
 DISPATCH_HEADER := $(BUILD_DIR)/dispatch.h
-HVF_LDFLAGS := -framework Hypervisor -arch arm64
+HVF_LDFLAGS := -framework Hypervisor -arch arm64 -lcurl
 
 # Generated headers under build/ that must exist before compiling sources that
 # include them.
@@ -128,6 +150,63 @@ $(BUILD_DIR)/test-multi-vcpu: $(BUILD_DIR)/test-multi-vcpu.o | $(BUILD_DIR)
 $(BUILD_DIR)/test-rwx: $(BUILD_DIR)/test-rwx.o | $(BUILD_DIR)
 	$(call link-and-sign,$@,$<)
 
+## Build the OCI reference parser unit test (native macOS binary).
+## Pure C, no HVF, no codesign required.
+$(BUILD_DIR)/test-oci-ref: $(BUILD_DIR)/test-oci-ref.o $(BUILD_DIR)/oci/ref.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI digest unit test (native macOS binary). Pure C, no HVF.
+$(BUILD_DIR)/test-oci-digest: $(BUILD_DIR)/test-oci-digest.o $(BUILD_DIR)/oci/digest.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI blob store unit test (native macOS binary). Pure C, no HVF.
+$(BUILD_DIR)/test-oci-blob-store: $(BUILD_DIR)/test-oci-blob-store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI manifest / index / config parser unit test (native, no HVF).
+$(BUILD_DIR)/test-oci-manifest: $(BUILD_DIR)/test-oci-manifest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/digest.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the shared OCI mock HTTPS server helper. tests/lib/oci-mock.{c,h}
+## terminates TLS via libssl from brew openssl@3; both the fetch and pull
+## suites link against the same compiled object to avoid duplicating ~400 LOC
+## of scaffolding in their own translation units.
+$(BUILD_DIR)/lib/oci-mock.o: CFLAGS += $(OPENSSL_CFLAGS)
+
+## Build the OCI fetch (libcurl) unit test (native macOS, no HVF). Pulls in
+## blob-store + digest + manifest models + cJSON; links against system libcurl
+## and the platform pthread runtime for the in-process mock HTTP server. The
+## test mock terminates TLS using libssl from brew openssl@3 so the ca_file
+## negative cases exercise a real certificate verification path.
+$(BUILD_DIR)/test-oci-fetch.o: CFLAGS += $(OPENSSL_CFLAGS)
+$(BUILD_DIR)/test-oci-fetch: $(BUILD_DIR)/test-oci-fetch.o $(BUILD_DIR)/lib/oci-mock.o $(BUILD_DIR)/oci/fetch.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lcurl -lpthread $(OPENSSL_LDFLAGS)
+
+## Build the OCI local store unit test (native macOS, no HVF). Pure C; links
+## against the store wrapper plus its blob-store and digest dependencies.
+$(BUILD_DIR)/test-oci-store: $(BUILD_DIR)/test-oci-store.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/ref.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI pull pipeline unit test (native macOS, no HVF). Shares the
+## TLS-terminating mock server with test-oci-fetch via tests/lib/oci-mock.
+$(BUILD_DIR)/test-oci-pull.o: CFLAGS += $(OPENSSL_CFLAGS)
+$(BUILD_DIR)/test-oci-pull: $(BUILD_DIR)/test-oci-pull.o $(BUILD_DIR)/lib/oci-mock.o $(BUILD_DIR)/oci/pull.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/fetch.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lcurl -lpthread $(OPENSSL_LDFLAGS)
+
+## Build the OCI inspect renderer unit test (native macOS, no HVF). Pure
+## offline: no fetcher, no mock server, no libcurl. Pre-populates the store
+## via oci_blob_store_put_bytes + oci_store_put_ref.
+$(BUILD_DIR)/test-oci-inspect: $(BUILD_DIR)/test-oci-inspect.o $(BUILD_DIR)/oci/inspect.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
 # ── Guest test binaries (cross-compiled, aarch64-linux) ──────────
 # Only used when GUEST_TEST_BINARIES is not set.
 

externals/cjson/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2017 Dave Gamble and cJSON contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

externals/cjson/VENDORING.md

@@ -0,0 +1,35 @@
+# Vendored cJSON
+
+This directory contains a vendored copy of [cJSON](https://github.com/DaveGamble/cJSON),
+the ultralightweight JSON parser written in ANSI C. cJSON ships as a single
+`.c` / `.h` pair and is dual-licensed under the MIT license (see `LICENSE`).
+
+## Why vendored
+
+`oci-roadmap.md` Q9 commits Phase 1 to hand-rolled C alongside the existing
+elfuse codebase: no Go, no Rust, no `cargo` / `go` in the build matrix. cJSON
+is the smallest credible JSON dependency that fits that contract; it is
+self-contained, has no external dependencies, and compiles cleanly with
+`clang` and `gcc` on macOS and Linux.
+
+## Version
+
+Pinned to upstream tag `v1.7.18` (2024-07-30). Fetched with:
+
+```
+curl -fsSL -o cJSON.h https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/cJSON.h
+curl -fsSL -o cJSON.c https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/cJSON.c
+curl -fsSL -o LICENSE https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/LICENSE
+```
+
+## Local modifications
+
+None. The files are byte-identical to the upstream tag so future security
+updates can be applied by re-running the curl commands above.
+
+## Build integration
+
+The Makefile compiles `cJSON.c` with project warning flags relaxed: cJSON is
+third-party code and its style does not match elfuse's `-Wpedantic
+-Wmissing-prototypes -Wshadow` posture. Only `src/oci/` translation units
+include `externals/cjson/cJSON.h`; the rest of the codebase never sees it.