# OCI import (`banger image pull`)

`banger image pull <oci-ref>` downloads a container image from any
OCI-compatible registry (Docker Hub, GHCR, quay.io, self-hosted, …),
flattens its layers into an ext4 rootfs, and registers the result as
a managed banger image.

Paired with the kernel catalog, this dissolves the "where do I get a
rootfs" bottleneck for most users — any distro that ships an official
container image can now boot (eventually) as a banger VM.

```bash
banger kernel pull void-6.12
banger image pull docker.io/library/debian:bookworm --kernel-ref void-6.12
banger image list     # debian-bookworm appears, Managed=true
```

## Status: Phase A (acquisition only)

This is the first of a two-phase initiative. **Phase A (this feature)**
produces a working ext4 file from an OCI reference. **Phase B (not yet
implemented)** will add the steps needed to make the pulled image
directly bootable — init system hook-up, sshd install, vsock agent
drop-in, network bootstrap, and **file-ownership fixup**.

What works today:

- Pulling any public OCI image that exposes a `linux/amd64` manifest.
- Correct layer replay with whiteout semantics (`.wh.*` deletes,
  `.wh..wh..opq` opaque-dir markers).
- Path-traversal and relative-symlink-escape protection.
- Content-aware default sizing (`content × 1.25`, floor 1 GiB).
- Layer caching on disk, keyed by blob SHA256.
- Piping pulled images into the existing `banger image build
  --from-image` flow.

What does not yet work:

- **Booting a pulled image directly.** The produced ext4 has file
  ownership set to the *runner's* uid/gid, not the tar headers'.
  Setuid binaries (`sudo`, `ping`, …) run as the wrong user in the
  VM. This is deferred to Phase B.
- **Private registries**. Auth is not implemented; anonymous pulls
  only. Docker Hub, GHCR (public), quay.io (public), etc. all work.
- **Non-`linux/amd64` platforms**. The catalog is x86_64-only, so
  pulled rootfses match. `arm64` is additive in the schema; wire-up
  lands when a user needs it.

## Architecture

`internal/imagepull/` owns the pure mechanics:

- **`Pull`** (`imagepull.go`) wraps `go-containerregistry`'s
  `remote.Image` with the `linux/amd64` platform pinned. Layer
  blobs are cached on disk via `cache.NewFilesystemCache` under
  `<OCICacheDir>/blobs/sha256/<hex>` — OCI-standard layout so
  `skopeo` or `crane` could co-exist.
- **`Flatten`** (`flatten.go`) replays layers oldest-first into a
  staging directory, applying whiteouts and rejecting unsafe paths.
- **`BuildExt4`** (`ext4.go`) runs `mkfs.ext4 -F -d <staging>
  -E root_owner=0:0` to populate the image file at create time —
  no mount, no sudo, no loopback. Requires `e2fsprogs ≥ 1.43`
  (`mkfs.ext4 -d` is the Populate-at-Create flag; nearly all
  modern distros ship it).

`internal/daemon/images_pull.go` orchestrates:

1. Parse + validate the OCI ref.
2. Derive a friendly default name (`debian-bookworm` for
   `docker.io/library/debian:bookworm`) when `--name` is omitted.
3. Resolve kernel info via the shared `resolveKernelInputs` helper
   (the same code path as `image register --kernel-ref`).
4. Stage at `<ImagesDir>/<id>.staging`; extract layers to a temp
   tree under `os.TempDir` (bulk transient data stays off the
   persistent state filesystem).
5. `imagepull.BuildExt4` produces `<staging>/rootfs.ext4`.
6. `imagemgr.StageBootArtifacts` stages the kernel triple alongside.
7. Atomic `os.Rename(<staging>, <final>)` publishes the artifact dir.
8. Persist a `model.Image{Managed: true, …}` record.

Any failure removes the staging dir. Post-rename failures remove the
final dir and roll back the store write.

## Paths

| What | Where | Purpose |
|------|-------|---------|
| Layer blob cache | `~/.cache/banger/oci/blobs/sha256/<hex>` | Re-pulls of the same image digest are local-only |
| Staging dir | `~/.local/state/banger/images/<id>.staging/` | Short-lived; atomic-renamed to `<id>/` on success |
| Staging rootfs tree | `$TMPDIR/banger-pull-<rand>/` | Extraction scratch space; removed after ext4 build |
| Published image | `~/.local/state/banger/images/<id>/rootfs.ext4` | Managed artifact stored alongside the kernel triple |

## Composition with `image build`

A pulled image is "unconfigured" — it has no sshd, no vsock agent, no
banger-specific network unit, and file ownership is wrong for boot.
The natural next step is to feed it through the existing customization
pipeline:

```bash
banger image build --from-image debian-bookworm --name debian-dev --docker
```

`image build` spins up a transient VM using the base image, runs
`scripts/customize.sh` over it, and saves the result as a new managed
image. This is already how the opinionated `void` / `alpine` images
are produced today.

The bootability gap means this composition only works once Phase B
lands an ownership-fixup pass. Until then, `image pull` gives you a
recorded primitive; the boot story requires the legacy manual rootfs
scripts.

## Tech debt

- **File-ownership preservation**. The ext4 is populated from a tree
  extracted as the current user — `mkfs.ext4 -d` then copies those
  on-disk uids/gids verbatim. Setuid bits survive but with the wrong
  owner, so privilege escalation is broken inside the VM. Planned
  fixes:
  - **debugfs ownership-fixup pass**: after `mkfs.ext4 -d`, replay
    tar headers through `debugfs -w` with `set_inode_field` to
    rewrite per-file uid/gid/mode. No new runtime deps (debugfs
    ships with e2fsprogs). Moderate implementation; keeps us on
    `mkfs.ext4 -d`.
  - **`tar2ext4`**: Microsoft's hcsshim ships a Go package that
    streams tar entries directly into an ext4 image, preserving
    ownership. Heavier dependency graph but purpose-built.

  Either approach lives in Phase B.

- **Auth**. When we add private-registry support, the natural path is
  `authn.DefaultKeychain` from `go-containerregistry`, which already
  honours `~/.docker/config.json` and the standard credential
  helpers. No banger-specific config needed.

- **Cache eviction**. Layer blobs under `OCICacheDir` accumulate
  forever. A `banger image cache prune` command is a cheap follow-up
  when disk usage becomes a complaint.

- **Ownership fixup via user namespaces**. An alternative to
  debugfs / tar2ext4 is running the entire extraction inside a user
  namespace (`unshare -Ufr`), which lets us set uid=0 on files from
  a non-privileged process. Cleaner in theory but requires
  user-namespace support on the host and doesn't help when the
  resulting tree is then passed to `mkfs.ext4 -d` (which copies
  on-disk uids).

## Trust model

`image pull` delegates trust to the OCI registry the user selected.
`go-containerregistry` verifies layer digests against the manifest
during download, so a tampered mirror can't ship modified layers
without breaking the sha256 chain. Beyond that, banger does not
verify OCI image signatures (cosign/sigstore) — users who care should
verify their references out-of-band.