# `Stevedore.Referrers`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/referrers.ex#L1)

Attach artifacts to an image and list them — the OCI 1.1 `subject`/`artifactType` mechanism that
signatures, SBOMs, and scan results hang off of.

An artifact is an ordinary manifest carrying a `subject` descriptor pointing at the image it
refers to. `attach/4` sets that subject and pushes the artifact; `list/3` returns the referrers
index — via the registry Referrers API (with the `<algo>-<hex>` tag-schema fallback) for
`docker://`, or by scanning stored `subject` fields for a local registry tree.

Spec: [distribution-spec, Referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
and [image-spec, manifest `subject`](https://github.com/opencontainers/image-spec/blob/main/manifest.md).

# `artifact`

```elixir
@type artifact() ::
  Stevedore.Image.t()
  | %{
      :media_type =&gt; String.t(),
      :data =&gt; binary(),
      optional(:artifact_type) =&gt; String.t()
    }
```

# `attach`

```elixir
@spec attach(Stevedore.Transport.t(), Stevedore.Digest.t(), artifact(), keyword()) ::
  {:ok, Stevedore.Digest.t()} | {:error, term()}
```

Attaches `artifact` to the image identified by `subject` on `transport`, setting the artifact's
`subject` to the (freshly fetched) subject descriptor and pushing it. Returns the artifact's
manifest digest.

# `index_for`

```elixir
@spec index_for(Stevedore.Transport.Static.t(), Stevedore.Digest.t()) ::
  Stevedore.Manifest.t()
```

Builds the referrers index (as a `t:Stevedore.Manifest.t/0`) for `subject` by scanning a local
registry tree's stored `subject` fields. Used by the registry server's referrers endpoint.

# `list`

```elixir
@spec list(Stevedore.Transport.t(), Stevedore.Digest.t(), keyword()) ::
  {:ok, Stevedore.Manifest.t()} | {:error, term()}
```

Lists referrers to `subject` on `transport`, returning the referrers image-index as a
`t:Stevedore.Manifest.t/0`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*