# OCI Image Inspection

## Overview

OCI image inspection resolves an image reference to its manifest or index, enumerates platform manifests, and returns ordered layer metadata. The inspector is used by CLI workflows that need deterministic image metadata without pulling layers.

## Architecture

### Components

| Component | Location | Responsibility |
| --- | --- | --- |
| `IOciImageInspector` | `Scanner.Storage.Oci` | Public interface for image inspection |
| `OciImageInspector` | `Scanner.Storage.Oci` | Implements manifest/index resolution, auth flow, and ordering |
| `ImageInspectionResult` | `Scanner.Contracts` | Output model for index, platform, and layer data |

### Data flow

1. Parse the image reference into registry, repository, tag or digest.
2. HEAD the manifest to obtain media type and digest.
3. GET the manifest payload.
4. If media type is index, enumerate platform manifests and optionally resolve each manifest.
5. For each manifest, fetch config (for platform metadata) and list layers in manifest order.
6. Return ordered results with warnings and a deterministic inspection timestamp.

## Media type support

| Media type | Type | Handling |
| --- | --- | --- |
| `application/vnd.oci.image.index.v1+json` | OCI index | Parse as index and enumerate manifests |
| `application/vnd.docker.distribution.manifest.list.v2+json` | Docker list | Parse as index |
| `application/vnd.oci.image.manifest.v1+json` | OCI manifest | Parse as manifest |
| `application/vnd.docker.distribution.manifest.v2+json` | Docker manifest | Parse as manifest |

## Configuration

The inspector uses `OciRegistryOptions`:

| Field | Purpose |
| --- | --- |
| `DefaultRegistry` | Registry to use when no registry is specified |
| `AllowInsecure` | Allow HTTP and insecure TLS for registry calls |
| `Auth.Username` / `Auth.Password` | Basic auth credentials |
| `Auth.Token` | Bearer token |
| `Auth.AllowAnonymousFallback` | Allow retry without auth after 401 |

CLI configuration binding uses the `OciRegistry` section (example):

```json
{
  "OciRegistry": {
    "DefaultRegistry": "docker.io",
    "AllowInsecure": false,
    "Auth": {
      "Username": "registry-user",
      "Password": "registry-pass",
      "AllowAnonymousFallback": true
    }
  }
}
```

## Output model

`ImageInspectionResult` returns:

- Resolved digest and media type
- Multi-arch indicator
- Ordered platform manifests (os, arch, variant)
- Ordered layer list with size and media type
- UTC inspection timestamp from `TimeProvider`
- Deterministic, sorted warnings

## Determinism

- Platforms sorted by `os`, `architecture`, `variant`.
- Layers preserve manifest order (0-indexed).
- Warnings sorted lexicographically and de-duplicated.
- Timestamps come from injected `TimeProvider`.

## Integration points

- CLI: `stella image inspect` consumes the inspector result for table and JSON output.
- Scanner services can reuse the inspector for registry resolution without pulling layers.