MoonOCI

MoonOCI is an original MoonBit library and command-line tool for building, inspecting, and validating deterministic OCI Image Layout directories without a container daemon or registry.

It provides a portable core for Wasm, Wasm-GC, JavaScript, and Native targets, plus a Native filesystem adapter and the moonoci CLI. Identical declared inputs produce byte-identical tar layers, OCI JSON documents, descriptors, and content-addressed Blobs.

Features

Version 0.2.0 adds verified multi-platform composition, exact platform selection, standalone slicing, offline transfer planning and external index pins. See runtime validation without a local VM and the development programme.

Version 0.2.0 also provides deterministic delta archives, pinned offline hydration, reachability/storage accounting, compaction, indexed blob lookups and a caller-owned release-policy gate. See offline delivery for the reproducible Windows/Linux consumer and the exact transfer/security boundaries.

Content-aware upgrade review adds final file/layer provenance, same-size payload change detection, execution configuration changes without echoing environment values, and approvals bound to both image versions. The Native files, diff, config-diff and upgrade-check commands expose these public library capabilities. Multi-image filesystem queries require selection.

Nested index consumption adds bounded metadata walking, explicit image-only flattening, platform selection, trusted root pins and source/ output derivation records. An independent Python consumer constructs the nested documents and checks projection results against the original image content.

Supply-chain artifacts support typed attachments, exact subject binding, offline referrers, payload verification/export and required-type gates. The Windows consumer has been executed against ORAS 1.3.6 for manifest/ payload reads, discovery/filtering and multi-platform index subjects.

Restartable delivery adds bounded chunk plans, verified disk checkpoints, missing-work batches and whole-content publication. The Windows consumer resumes an actual delta delivery across separate processes, then independently verifies the reconstructed image. Long-lived Native hosts can reuse a prepared session rather than parsing a full plan per arrival.

Mixed-content lifecycle adds pinned physical catalogs, explicit subject/referrer retention, extension-preserving copies and review identities that reject stale physical membership. Native export verifies supported image/artifact semantics before writing a new destination. The Windows consumer independently checks closure/identity and ORAS discovery; source data is never deleted. Validated internals are private.

Registry consumption adds digest-pinned read-only HTTP/TLS pulls, private CA support, isolated pull-only Bearer authentication, bounded retries, verified cache reuse and confined referrer pagination. The registry-bundle consumer fetches immediate subject attachments, checks their actual association and creates a new offline layout for existing artifact gates. Loopback HTTP/HTTPS and independent ORAS consumption run on Windows without a Linux VM. Public-registry access and Linux container runtime execution remain separate evidence requirements; configured CI is not an executed result.

• deterministic USTAR/PAX writer and safety-focused USTAR/PAX/GNU reader;
• SHA-256 Digest and content-addressed in-memory OCI Image Layout;
• uncompressed and deterministic gzip Layers with correct compressed Layer Digest and uncompressed DiffID handling;
• ordered multi-layer builds with Whiteout and Opaque Directory semantics;
• strict, versioned JSON Build Specification;
• descriptor-graph, size, Digest, tar, gzip, and DiffID verification;
• Root Filesystem reconstruction;
• Native build, inspect, list, verify, archive, and version commands;
• generated-case, corruption, Native filesystem, and reproducibility tests.

The development branch also supports packaging compiled MoonBit WebAssembly binaries as single-layer Wasm OCI artifacts. See release workflows for the offline and registry workflow design and validation targets.

Scope

MoonOCI v0.1 builds one platform image per invocation and writes OCI Image Spec 1.1.1 layouts. It does not parse Dockerfiles, run containers, contact registries, sign images, or encode zstd Layers. The portable archive API represents symbolic links, but the v0.1 Native Layer Source adapter rejects host symlinks because its filesystem dependency does not expose a portable read-link operation.

Installation

Add the published library to a MoonBit project:

moon add oyjh0381/moonoci@0.3.0

The reusable packages include oyjh0381/moonoci/archive, builder, codec, digest, layout, model, pathing, and spec. The Native CLI is built and run from this source repository.

Requirements and development

• MoonBit compiler and core 0.10.20+65efd5b93 with moon 0.1.20261104 for the development branch;
• for Native builds on Windows: Visual Studio 2022 Build Tools with the C++ workload and Windows SDK;
• for Native builds on Linux: a C compiler and archiver.

After cloning the repository, install development dependencies:

moon update

Check the portable packages and run the portable suite:

moon check --target all
moon test --target wasm-gc

On Windows, run Native commands in a Developer PowerShell/Command Prompt:

moon test --target native
moon build --target native

Library example

let request = @builder.default_single_layer_request([
  @archive.TarEntry::directory("app"),
  @archive.TarEntry::file("app/message.txt", b"hello\n"),
])
let image = @builder.build_single_layer(request)
assert_true(@builder.verify_memory(image.layout).is_valid())

Run the examples:

moon run examples/single-layer --target wasm-gc
moon run examples/multi-layer --target wasm-gc
moon run examples/reproducible --target wasm-gc

Build Specification and CLI

Create moonoci.json:

{
  "schemaVersion": 1,
  "ref": "demo",
  "platform": { "os": "linux", "architecture": "amd64" },
  "layers": [
    { "source": "rootfs", "compression": "gzip" }
  ],
  "config": {
    "entrypoint": ["/app/server"],
    "workingDir": "/app"
  },
  "output": { "layout": "dist/demo" }
}

Run the Native CLI from the repository:

moon run cmd/moonoci --target native -- build moonoci.json
moon run cmd/moonoci --target native -- inspect dist/demo
moon run cmd/moonoci --target native -- list dist/demo
moon run cmd/moonoci --target native -- verify dist/demo
moon run cmd/moonoci --target native -- archive dist/demo dist/demo.tar
moon run cmd/moonoci --target native -- version

The builder refuses to overwrite an existing destination. Errors include stable MOONOCI_* codes and documented exit classes: arguments/specification 2, I/O 3, unsupported or malformed content 4, verification/security failures 5, and unexpected internal failure 70.

Documentation

• 中文说明
• Build Specification
• Architecture
• Security model
• Conformance
• Domain language

License

Apache License 2.0. Dependency notices are recorded in THIRD_PARTY_NOTICES.md.