Add OCI runtime surface and compat test fixtures

Make `oci run` work against real public images (alpine, busybox,
python, ruby, debian) and lock the surface down with end-to-end
fixtures.

Runtime surface:

- writable clone-rootfs DoD: the per-run rootfs is writable
  out of the box, so guests that mutate /tmp, /var, /run work
  unchanged
- runtime files injection: /etc/resolv.conf, /etc/hosts,
  /etc/hostname populated from the host into the clone-rootfs
- /dev/full and /dev/console emulation in the syscall layer
- /proc surface: cgroup, hostname, comm, statm entries that
  glibc startup and procps tooling read
- image-config `User` symbolic resolution: name and name:group
  forms looked up against the guest /etc/passwd and /etc/group
  before falling back to numeric
- `oci run` walks the image index to the linux/arm64 leaf manifest
  (Phase 3 fix; previously fed the top-level index to the
  config-loader and crashed on multi-arch images)

Bug fixes uncovered by cold-cache runs:

- layer apply no longer rejects the root tar entry "./"
- unpack stages files via copyfile(2) with COPYFILE_CLONE fallback
  so cross-volume unpack (store on internal SSD, sysroot on the
  APFS sparsebundle) succeeds
- tar reader handles PAX 'x' / 'g' extended-header `path` and
  `linkpath` records (busybox and python:alpine layers use them)

Compat tests:

- `tests/test-oci-compat.sh` shell smoke (in-tree fixtures)
- `OCI_COMPAT_TEST=1` heavy mode that provisions a scratch
  sparsebundle and drives three fixtures end-to-end:
  alpine-shaped, busybox-shaped hardlink dispatch, two-layer
  whiteout
- `OCI_FETCH_ONLINE=1` alpine:3 end-to-end smoke (opt-in;
  requires network)

`ELFUSE_OCI_PROGRESS=plain` env disables the pull progress
in-place CSI redraw for terminals that don't honor cursor-up
escapes (issue surfaced on legacy Terminal.app panes).

Documentation: `docs/oci.md` Phase 4 runtime surface and
libc-adjacent envelope notes (what guests can / can't expect
from the synthetic /etc, /dev, /proc).

Author: Max042004

Makefile

@@ -91,7 +91,9 @@ SRCS := \
     oci/unpack.c \
     oci/rebuild-cache.c \
     oci/runspec.c \
+    oci/user-lookup.c \
     oci/path-resolve.c \
+    oci/runtime-files.c \
     oci/run.c
 
 SRCS := $(addprefix src/,$(SRCS))
@@ -303,11 +305,19 @@ $(BUILD_DIR)/test-oci-tar: $(BUILD_DIR)/test-oci-tar.o $(BUILD_DIR)/oci/tar.o |
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
-## Build the OCI runspec unit test (native macOS, no HVF). Pure-data
-## merge of image-config runtime block + CLI overrides; the test feeds
-## oci_image_runtime_t literals directly through oci_runspec_build with
-## no filesystem or libcurl dependency.
-$(BUILD_DIR)/test-oci-runspec: $(BUILD_DIR)/test-oci-runspec.o $(BUILD_DIR)/oci/runspec.o | $(BUILD_DIR)
+## Build the OCI runspec unit test (native macOS, no HVF). Merges
+## image-config runtime block + CLI overrides; the rootfs-driven
+## symbolic-User cases write /etc/passwd and /etc/group fixtures under
+## /tmp, so the link island pulls in oci/user-lookup.o.
+$(BUILD_DIR)/test-oci-runspec: $(BUILD_DIR)/test-oci-runspec.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/user-lookup.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI User-field resolver unit test (native macOS, no HVF).
+## Pure C; the test builds scratch /tmp rootfses with synthetic
+## /etc/passwd / /etc/group and drives oci_user_lookup across the seven
+## OCI image-spec User shapes plus the policy edges.
+$(BUILD_DIR)/test-oci-user: $(BUILD_DIR)/test-oci-user.o $(BUILD_DIR)/oci/user-lookup.o | $(BUILD_DIR)
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
@@ -325,10 +335,18 @@ $(BUILD_DIR)/test-oci-path-resolve: $(BUILD_DIR)/test-oci-path-resolve.o $(BUILD
 ## the test ships an in-file elfuse_launch stub that aborts when called,
 ## and every case installs a launch hook via oci_run_set_launch_for_testing
 ## before invoking oci_run, so the real VM bring-up never runs from a test.
-$(BUILD_DIR)/test-oci-run: $(BUILD_DIR)/test-oci-run.o $(BUILD_DIR)/oci/run.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/path-resolve.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/volume-list.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/origin-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/digest-set.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
+$(BUILD_DIR)/test-oci-run: $(BUILD_DIR)/test-oci-run.o $(BUILD_DIR)/oci/run.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/user-lookup.o $(BUILD_DIR)/oci/path-resolve.o $(BUILD_DIR)/oci/runtime-files.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/volume-list.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/origin-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/digest-set.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lz
 
+## Build the OCI runtime-files injection unit test (native macOS, no HVF).
+## Pure C; the test drives oci_runtime_files_inject against scratch
+## /tmp/elfuse-rf-* run directories and verifies the synthesised
+## /etc/{resolv.conf,hosts,hostname} content.
+$(BUILD_DIR)/test-oci-runtime-files: $(BUILD_DIR)/test-oci-runtime-files.o $(BUILD_DIR)/oci/runtime-files.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
 ## Build the OCI fixture builder (Phase 3 compat tests). Standalone tool
 ## that synthesises a complete OCI store from uncompressed-tar layers
 ## plus image-config flags. Used by tests/test-oci-compat.sh and

docs/usage.md

@@ -132,7 +132,7 @@ elfuse oci run  alpine:3 /bin/sh -c 'echo hello from inside'
 | `-e KEY=VAL`, `--env KEY=VAL` | Set or replace one env var (repeatable) |
 | `-e KEY`, `--env KEY` | Import `KEY` from the host environ (repeatable) |
 | `-w DIR`, `--workdir DIR` | Override image WorkingDir |
-| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (numeric only) |
+| `-u USER[:GROUP]`, `--user USER[:GROUP]` | Override image User; numeric `UID[:GID]` or symbolic `name[:group]` resolved from the rootfs `/etc/passwd` and `/etc/group` (see [User and WorkingDir](#user-and-workingdir)) |
 | `--keep` | Keep the per-run cloned rootfs after exit |
 | `--name NAME` | Reserved: deterministic clone-dir suffix (ignored today) |
 
@@ -166,11 +166,16 @@ Image-provided `DYLD_*` entries pass through (the guest ignores them).
 
 ### User and WorkingDir
 
-`User` accepts numeric `UID` or `UID:GID` only. Symbolic users (`User
-nginx`) are rejected with a deterministic Phase 4 pointer message;
-static `/etc/passwd` parsing waits for Phase 4 along with the rest of
-the NSS resolution work. `--user UID` alone defaults GID to the same
-value.
+`User` accepts seven shapes: the empty string (no override), a numeric
+`UID`, `UID:GID`, a symbolic `name`, `name:group`, `uid:group`, or
+`name:gid`. Symbolic forms read `/etc/passwd` and `/etc/group` from
+the cloned rootfs. A token made entirely of ASCII digits is always
+parsed numerically, even when a same-named account ships in the image
+(this matches runc semantics, so an image that happens to carry a
+`1234` account does not capture `--user 1234`). When the symbolic
+form names an account the unpacked layers do not actually carry,
+lookup fails closed; `elfuse` never silently falls back to root.
+`--user UID` alone defaults GID to the same value.
 
 `WorkingDir` must be absolute and free of `..` segments. If neither the
 image nor the CLI sets it, the guest starts in `/`. The directory is
@@ -180,12 +185,93 @@ selects credentials).
 
 ### Scope guardrails
 
-- Symbolic `User` -> Phase 4 (NSS / static `/etc/passwd` resolution)
-- `/etc/resolv.conf`, `/etc/hosts`, `/dev/*`, `/proc/*` synthesis -> Phase 4
 - Auto-pull on `run` miss -> never; `elfuse oci pull` must run first
 - Network policy, `docker run -p`-style port mapping -> later phases
 - Live `docker exec`-style attach -> never
 
+### Runtime host-truth surface
+
+`elfuse oci run` runs the guest against a freshly cloned per-run
+rootfs and a small set of synthesized host-truth files. The rootfs
+is produced by APFS `clonefile(2)` against the unpacked image
+layers, so the first guest write to any path triggers copy-on-write
+in APFS without touching the original image. The clone is removed at
+guest exit unless `--keep` is set; nothing is ever pushed back to
+the on-disk image, and concurrent `oci run` invocations against the
+same image are isolated.
+
+Three `/etc` files are overwritten in the clone before the guest
+starts. Any pre-existing symlink (the common case is
+`/etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf`) is
+unlinked first so it does not dangle inside the guest:
+
+| File | Source |
+|--|--|
+| `/etc/resolv.conf` | `nameserver` lines harvested from `scutil --dns`; falls back to `8.8.8.8` and `1.1.1.1` on any scutil failure |
+| `/etc/hosts` | fixed 5-line block: `localhost`, the ip6-loopback aliases, ip6 link-local multicast, and `127.0.0.1 host.elfuse.internal` |
+| `/etc/hostname` | literal string `elfuse` |
+
+The following pseudo-filesystem paths are synthesized by the host-side
+openat interceptor and do not need to exist inside the rootfs:
+
+| Path | Behavior |
+|--|--|
+| `/dev/null`, `/dev/zero`, `/dev/random`, `/dev/urandom`, `/dev/tty` | redirected to the host device of the same name |
+| `/dev/full` | reads zero-fill, writes of any non-zero length return `ENOSPC` |
+| `/dev/console` | mirrored from the controlling tty when present (macOS reserves the real `/dev/console` for the kernel) |
+| other `/dev/*` | `ENOENT` |
+| `/proc/cpuinfo`, `/proc/meminfo`, `/proc/version` | derived from host sysctl |
+| `/proc/self/{maps,exe,status,stat,comm,statm,cgroup}` | synthesized; `cgroup` reports the canonical `0::/` (elfuse runs outside any cgroup hierarchy) |
+| `/proc/sys/kernel/{ostype,osrelease,hostname}` | tracks the cached `uname` fields (`Linux`, `6.17.0-20-generic`, `elfuse`) |
+
+### Libc-adjacent compatibility
+
+`elfuse` does not patch libc-adjacent payload (NSS modules, time-zone
+data, locale data, character-set converters, dynamic-linker cache)
+inside the guest. Each item below names the contract `elfuse` honors
+and the failure mode an image hits when it does not ship the
+matching files.
+
+- **`/etc/nsswitch.conf`** is read by the guest's libc, not by
+  `elfuse`. Only the `files` and `dns` backends actually function:
+  `files` resolves through `/etc/{passwd,group,hosts}` in the cloned
+  rootfs, and `dns` resolves through host `getaddrinfo` via the
+  synthesized `/etc/resolv.conf`. Backends such as `systemd`, `sss`,
+  or `ldap` need their NSS shared object plus a matching daemon,
+  neither of which `elfuse` provides.
+- **NSS shared objects** (`libnss_systemd.so`, `libnss_sss.so`,
+  `libnss_ldap.so`, ...) are `dlopen`'d by guest libc against its own
+  loader. `elfuse` never injects NSS modules: they are aarch64-linux
+  ELF objects against guest libc, so the macOS host has no way to
+  load them, and the guest can only `dlopen` the modules its image
+  already carries.
+- **tzdata** (`/usr/share/zoneinfo`, `/etc/localtime`, `/etc/timezone`)
+  ships with the image. `elfuse` does not transcode macOS
+  `/var/db/timezone/zoneinfo` into the tzdata format; if the image is
+  missing the needed zone, glibc / musl fall back to UTC. The `TZ`
+  environment variable is honored as-is and is not rewritten by the
+  Env merge policy.
+- **`/usr/lib/locale/locale-archive`** is not regenerated. glibc
+  images without a built archive (or the matching `<lang>.UTF-8/`
+  directory) fall back to the `C` locale; locale-aware sort / printf
+  / strcoll outputs ASCII order. musl images do not use the archive
+  and are unaffected.
+- **`/usr/lib/<triple>/gconv/`** modules and the `gconv-modules`
+  index ship with the image. Missing modules surface as `EILSEQ` from
+  `iconv` / glibc's character-set conversion; this most often shows
+  up when an image ships a stripped glibc layer.
+- **`ld.so.cache`** is not rebuilt. The guest dynamic linker reads
+  whatever cache the image carries; missing entries fall through to
+  the linker's library-path search, which is the normal slow path.
+
+Common workloads and the symptom-to-workaround mapping:
+
+| Symptom | Trigger | Workaround |
+|--|--|--|
+| `getaddrinfo` returns `EAI_AGAIN` or an empty result | `/etc/nsswitch.conf` lists a backend (`systemd`, `sss`, ...) that needs a daemon | use a distro whose `nsswitch.conf` is `files dns` (alpine ships this by default; debian needs the file edited) |
+| `date`, `strftime` show UTC instead of the expected zone | the image does not contain `/usr/share/zoneinfo/<Zone>` | install tzdata in the image (`apk add tzdata` / `apt install tzdata`), or pass `-e TZ=UTC` to acknowledge UTC |
+| `sort`, `printf`, `strcoll` collate in ASCII order | the image is missing `/usr/lib/locale/locale-archive` or the matching `<lang>.UTF-8/` directory | accept the C-locale fallback, run `locale-gen` during the image build, or use a musl-based image (alpine), which does not depend on the archive |
+
 ## Guest Compatibility Model
 
 `elfuse` is designed for Linux user-space workloads, not for booting a Linux

externals/cjson/VENDORING.md

@@ -6,15 +6,15 @@ the ultralightweight JSON parser written in ANSI C. cJSON ships as a single
 
 ## 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.
+The OCI work stays 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:
+Pinned to upstream tag `v1.7.18` (2024-05-13). Fetched with:
 
 ```
 curl -fsSL -o cJSON.h https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/cJSON.h

externals/zstd/VENDORING.md

@@ -9,8 +9,8 @@ Licensed under BSD-3-Clause (see `LICENSE`).
 
 ## Why vendored, decode-only
 
-`oci-roadmap.md` Q9 commits the OCI work to hand-rolled C: no Go, no Rust,
-no `cargo` / `go` in the build matrix. zstd is the only OCI-spec layer
+The OCI work stays hand-rolled C: no Go, no Rust, no `cargo` / `go` in the
+build matrix. zstd is the only OCI-spec layer
 compression beyond gzip that has wide registry support, and the upstream
 library cleanly separates decoder-only from the full encoder. Phase 2 only
 reads layers, so the encoder, dictionary builder, and legacy v01-v06

mk/tests.mk

@@ -14,7 +14,8 @@
         test-oci-tar test-oci-decompress test-oci-meta \
         test-oci-origin \
         test-oci-layer-apply test-oci-volume test-oci-clone \
-        test-oci-unpack test-oci-runspec test-oci-path-resolve \
+        test-oci-unpack test-oci-runspec test-oci-user test-oci-path-resolve \
+        test-oci-runtime-files \
         test-oci-run test-oci-compat oci-fixture-builder \
         test-sysroot-rename \
         test-case-collision test-case-collision-fallback test-sysroot-create-paths \
@@ -88,8 +89,12 @@ check: $(ELFUSE_BIN) $(TEST_DEPS) check-syscall-coverage
 	@$(MAKE) --no-print-directory test-oci-unpack
 	@printf "\n$(BLUE)━━━ OCI runspec resolver unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-runspec
+	@printf "\n$(BLUE)━━━ OCI User-field resolver unit tests ━━━$(RESET)\n"
+	@$(MAKE) --no-print-directory test-oci-user
 	@printf "\n$(BLUE)━━━ OCI path-resolve unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-path-resolve
+	@printf "\n$(BLUE)━━━ OCI runtime-files injection unit tests ━━━$(RESET)\n"
+	@$(MAKE) --no-print-directory test-oci-runtime-files
 	@printf "\n$(BLUE)━━━ OCI run orchestrator unit tests ━━━$(RESET)\n"
 	@$(MAKE) --no-print-directory test-oci-run
 	@printf "\n$(BLUE)━━━ OCI compat shell smoke ━━━$(RESET)\n"
@@ -200,19 +205,36 @@ test-oci-unpack: $(BUILD_DIR)/test-oci-unpack
 	@$(BUILD_DIR)/test-oci-unpack
 
 ## Run the OCI runspec resolver unit tests (native, no HVF, no network).
-## Pure data: feeds hand-built oci_image_runtime_t literals plus synthetic
-## CLI flags through oci_runspec_build and asserts argv / envp / uid / cwd
-## outputs against the Phase 3 override matrix and Env policy.
+## Feeds hand-built oci_image_runtime_t literals plus synthetic CLI flags
+## through oci_runspec_build and asserts argv / envp / uid / cwd outputs
+## against the Phase 3 override matrix and Env policy. Phase 4 symbolic
+## User cases write scratch /tmp rootfses for /etc/passwd lookup.
 test-oci-runspec: $(BUILD_DIR)/test-oci-runspec
 	@$(BUILD_DIR)/test-oci-runspec
 
+## Run the OCI User-field resolver unit tests (native, no HVF, no network).
+## Phase 4 F4.7: validates oci_user_lookup against scratch rootfses
+## carrying synthetic /etc/passwd / /etc/group; covers the seven OCI
+## image-spec User shapes plus the policy edges (digit-name collision,
+## missing passwd, name-not-found, invalid characters).
+test-oci-user: $(BUILD_DIR)/test-oci-user
+	@$(BUILD_DIR)/test-oci-user
+
 ## Run the OCI guest PATH resolver unit tests (native, no HVF, no network).
 ## Builds a fake sysroot tree under /tmp and drives oci_path_resolve
 ## against it: PATH search, symlink-follow, escape-symlink skip,
 ## EACCES on noexec, ENOENT diagnostics with searched-dirs list.
 test-oci-path-resolve: $(BUILD_DIR)/test-oci-path-resolve
 	@$(BUILD_DIR)/test-oci-path-resolve
 
+## Run the OCI runtime-files injection unit tests (native, no HVF, no network).
+## Phase 4 F4.2 / F4.3: validates oci_runtime_files_inject against scratch
+## run directories, covering fresh-/etc creation, symlink overwrite,
+## regular-file overwrite, and the synthesised /etc/{resolv.conf,
+## hosts, hostname} content.
+test-oci-runtime-files: $(BUILD_DIR)/test-oci-runtime-files
+	@$(BUILD_DIR)/test-oci-runtime-files
+
 ## Run the OCI run orchestrator unit tests (native, no HVF, no network).
 ## Covers oci_cli_run argument parsing plus oci_run early-failure
 ## paths against a case-insensitive volume; the launch backend is

src/oci/blob-store.c

@@ -537,6 +537,36 @@ static void writer_cleanup_fail(oci_blob_writer_t *w)
     errno = saved;
 }
 
+/* fsync the directory that contains path so a newly linked/renamed entry is
+ * durable across a crash: fsync on the file persists its data but not the
+ * parent directory entry that names it. Best-effort -- the file-level fsync
+ * is the primary guarantee, and some filesystems reject a directory fsync, so
+ * a failure here must not fail the surrounding commit.
+ */
+static void fsync_parent_dir(const char *path)
+{
+    const char *slash = strrchr(path, '/');
+    char dir[STORE_PATH_MAX];
+    if (!slash) {
+        dir[0] = '.';
+        dir[1] = '\0';
+    } else if (slash == path) {
+        dir[0] = '/';
+        dir[1] = '\0';
+    } else {
+        size_t n = (size_t) (slash - path);
+        if (n >= sizeof(dir))
+            return;
+        memcpy(dir, path, n);
+        dir[n] = '\0';
+    }
+    int dfd = open(dir, O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+    if (dfd < 0)
+        return;
+    (void) fsync(dfd);
+    (void) close(dfd);
+}
+
 int oci_blob_writer_commit(oci_blob_writer_t *w)
 {
     if (!w) {
@@ -608,6 +638,10 @@ int oci_blob_writer_commit(oci_blob_writer_t *w)
          * correct action.
          */
     }
+    /* Persist the directory entry just created by link(2); without this a
+     * crash can leave the blob's data on disk but unreferenced by its name.
+     */
+    fsync_parent_dir(final_path);
     (void) unlink(w->tmp_path);
     free(w);
     return 0;

src/oci/cli.c

@@ -70,6 +70,10 @@ static int print_usage(FILE *out)
         "                        re-fetch missing layer blobs\n"
         "  -q, --quiet           Suppress per-blob progress output\n"
         "\n"
+        "Env: ELFUSE_OCI_PROGRESS=plain disables the in-place TTY\n"
+        "     redraw (use when the terminal mis-handles CSI cursor-up;\n"
+        "     prints one summary line per blob on completion).\n"
+        "\n"
         "Policy: optional policy.json controls per-registry insecure /\n"
         "        ca_bundle / auth_file. Read from $ELFUSE_POLICY_FILE >\n"
         "        $XDG_CONFIG_HOME/elfuse/policy.json >\n"

src/oci/fetch.c

@@ -926,9 +926,14 @@ int oci_fetch_manifest(oci_fetcher_t *f,
     }
 
     bearer_challenge_t challenge = {0};
-    int rc =
-        perform_manifest_get(f, &eff, url, accept_types, if_none_match, out,
-                             f->bearer_token ? NULL : &challenge, err_msg);
+    /* Always capture the Bearer challenge, even when a token is already
+     * cached: registry tokens are short-lived (Docker Hub expires them in
+     * ~300s), so a long multi-blob pull can outlive the cached token. If the
+     * stale token 401s, the captured challenge lets the block below refresh
+     * it and retry instead of failing the pull.
+     */
+    int rc = perform_manifest_get(f, &eff, url, accept_types, if_none_match,
+                                  out, &challenge, err_msg);
     if (rc < 0) {
         free(url);
         bearer_challenge_free(&challenge);
@@ -1223,7 +1228,11 @@ static int batch_prepare_handle(oci_fetcher_t *f,
     h->http_status = 0;
     h->last_curl_rc = CURLE_OK;
     h->err_msg = NULL;
-    batch_configure_easy(f, eff, h, !f->bearer_token);
+    /* Capture the Bearer challenge on round 0 even with a cached token: a
+     * short-lived token can expire mid-pull, and the round-0 401 retry can
+     * only refresh it if the challenge was parsed off the response.
+     */
+    batch_configure_easy(f, eff, h, true);
     return 0;
 }