# Stevedore v0.2.0 - Table of Contents

> A library-first, daemonless OCI toolkit for Elixir — everything you can do to a container image except run it.

## Pages

- [Stevedore](readme.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

- Guides
  - [Cookbook](examples.md)
  - [References](references.md)
  - [Testing & interop](testing.md)
  - [AGENTS](agents.md)

## Modules

- Top-level API
  - [Stevedore](Stevedore.md): A library-first, daemonless OCI toolkit for Elixir — everything you can do to a container
image **except run it**.

- Core types
  - [Stevedore.Config](Stevedore.Config.md): A parsed OCI image configuration.
  - [Stevedore.Descriptor](Stevedore.Descriptor.md): A typed, digest-addressed pointer to content (the OCI *descriptor*).
  - [Stevedore.Digest](Stevedore.Digest.md): A content digest: an `algorithm:hex` pair identifying bytes by their hash.
  - [Stevedore.Image](Stevedore.Image.md): An assembled image held in memory: a manifest, its config, the ordered layer descriptors, and
the blob bytes backing them.
  - [Stevedore.Layer](Stevedore.Layer.md): Read and merge image layers **in memory, without root**.
  - [Stevedore.Manifest](Stevedore.Manifest.md): An image manifest **or** an image index (multi-arch manifest list).
  - [Stevedore.MediaType](Stevedore.MediaType.md): The OCI and Docker media-type strings, with classifiers.
  - [Stevedore.Reference](Stevedore.Reference.md): A parsed, normalized image reference: registry, repository, and a tag or digest.

- Build, copy & modify
  - [Stevedore.Build](Stevedore.Build.md): Assemble images **declaratively** from layers + a config — the crane-style create surface.
  - [Stevedore.Copy](Stevedore.Copy.md): The `copy` primitive: move an image between any two transports, preserving digests.
  - [Stevedore.Mutate](Stevedore.Mutate.md): Rewrite an assembled `Stevedore.Image` — config, annotations, tag, base, or layer set — without
re-pulling layers where possible. Every mutation recomputes the dependent digests through
`Stevedore.Image.assemble/3`; bytes that don't change keep their digests.

- Analyze
  - [Stevedore.Analyze](Stevedore.Analyze.md): Inspect an image's effective filesystem: list files, read a file's bytes, and extract a
best-effort software bill of materials — all over `Stevedore.Layer.merged_view/2`, in memory.

- Sign & verify
  - [Stevedore.Referrers](Stevedore.Referrers.md): Attach artifacts to an image and list them — the OCI 1.1 `subject`/`artifactType` mechanism that
signatures, SBOMs, and scan results hang off of.
  - [Stevedore.Sign](Stevedore.Sign.md): Sign an image so its authenticity can later be verified by `Stevedore.Verify`.
  - [Stevedore.Sign.Sigstore](Stevedore.Sign.Sigstore.md): Sigstore/cosign key-pair primitives, native via `:public_key` (ECDSA P-256, no shelling out).
  - [Stevedore.Verify](Stevedore.Verify.md): Verify an image's signatures against a policy. Default-deny: verification fails unless a
signature satisfies the policy.

- Registry client
  - [Stevedore.Auth](Stevedore.Auth.md): Registry credentials and the bearer-token challenge/exchange flow.
  - [Stevedore.Auth.Cache](Stevedore.Auth.Cache.md): An opt-in, in-process cache of registry bearer tokens, keyed by `{registry, scope}`.
  - [Stevedore.Registry](Stevedore.Registry.md): A daemonless client for the OCI/Docker Distribution v2 API (the `docker://` transport).

- Transports
  - [Stevedore.Transport](Stevedore.Transport.md): The seam describing **where images live**, behind one uniform interface.
  - [Stevedore.Transport.Archive](Stevedore.Transport.Archive.md): Tar-backed transports: `oci-archive:` (an OCI image layout as a tar) and `docker-archive:`
(a `docker save` tarball).
  - [Stevedore.Transport.Dir](Stevedore.Transport.Dir.md): The `dir:` transport — Skopeo's flat directory of a single image.
  - [Stevedore.Transport.Memory](Stevedore.Transport.Memory.md): A read-only `Stevedore.Transport` backed by an in-memory `Stevedore.Image`.
  - [Stevedore.Transport.OCILayout](Stevedore.Transport.OCILayout.md): The `oci:` transport — an OCI image-layout directory.
  - [Stevedore.Transport.Parse](Stevedore.Transport.Parse.md): Parses Skopeo-style transport-prefixed references into a `{transport, ref}` pair.
  - [Stevedore.Transport.Registry](Stevedore.Transport.Registry.md): The `docker://` transport: a remote registry, behind the `Stevedore.Transport` behaviour.
  - [Stevedore.Transport.Static](Stevedore.Transport.Static.md): The `static:` transport — a Stevedore-native registry-v2 directory tree.

- Storage & archives
  - [Stevedore.Archive](Stevedore.Archive.md): A pure tar reader/writer plus gzip helpers.
  - [Stevedore.Store](Stevedore.Store.md): The content-addressed blob storage seam.
  - [Stevedore.Store.Local](Stevedore.Store.Local.md): A filesystem-backed `Stevedore.Store`.
  - [Stevedore.Store.Memory](Stevedore.Store.Memory.md): An in-memory `Stevedore.Store` backed by an `Agent`.

- Server & deploy
  - [Stevedore.Deploy](Stevedore.Deploy.md): Turn an image into a **static, read-only registry** a dumb web server can serve.
  - [Stevedore.Plug](Stevedore.Plug.md): A `Plug` implementing the OCI/Docker Distribution **v2 registry API**.
  - [Stevedore.Server](Stevedore.Server.md): The standalone `/v2` registry server: a supervision tree of `Stevedore.Server.Uploads` and a
Bandit HTTP listener serving `Stevedore.Plug`.
  - [Stevedore.Server.Uploads](Stevedore.Server.Uploads.md): In-progress blob upload sessions for the registry server.

- CLI
  - [Stevedore.CLI](Stevedore.CLI.md): Shared helpers for the `mix stevedore.*` task shells: starting the app, unwrapping verb results
into task success/failure, and rendering errors consistently (reusing subsystem
`Exception.message/1`).

- Errors
  - [Stevedore.Archive.Error](Stevedore.Archive.Error.md): An error raised or returned while reading or writing a tar archive.
  - [Stevedore.Auth.Error](Stevedore.Auth.Error.md): A failure during registry authentication (token exchange or credential loading).

  - [Stevedore.Registry.Error](Stevedore.Registry.Error.md): A failure talking to a registry's Distribution v2 API.
  - [Stevedore.Sign.Error](Stevedore.Sign.Error.md): A failure while signing an image.
  - [Stevedore.Verify.Error](Stevedore.Verify.Error.md): A failure while verifying image signatures against a policy.

## Mix Tasks

- CLI
  - [mix stevedore.copy](Mix.Tasks.Stevedore.Copy.md): Copy an image from one transport to another.
  - [mix stevedore.delete](Mix.Tasks.Stevedore.Delete.md): Delete a manifest from a transport.
  - [mix stevedore.deploy](Mix.Tasks.Stevedore.Deploy.md): Copy an image into a static registry directory and (optionally) emit a web-server config that
serves it as a read-only `/v2` registry.
  - [mix stevedore.inspect](Mix.Tasks.Stevedore.Inspect.md): Inspect the manifest of an image at any transport.
  - [mix stevedore.list_tags](Mix.Tasks.Stevedore.ListTags.md): List the tags held by a transport.
  - [mix stevedore.sign](Mix.Tasks.Stevedore.Sign.md): Sign an image with an ECDSA private key (PEM) and attach the cosign-compatible signature to it
via the Referrers API.
  - [mix stevedore.sync](Mix.Tasks.Stevedore.Sync.md): Copy many images from a declarative spec file. Each non-blank line is `SRC DST` (lines starting
with `#` are comments).
  - [mix stevedore.verify](Mix.Tasks.Stevedore.Verify.md): Verify an image's signatures (fetched via the Referrers API / `.sig` tag) against an ECDSA
public key (PEM). Exits non-zero if no signature satisfies the policy.