Add document and diagram for artifact movement

[mnm678]

cc @SteveLasker @sudo-bmitch

Let me know if there are any specific scenarios you'd like me to describe in more detail.

[sudo-bmitch]

LGTM. I think there are a few scenarios:

1. Upstream has TUF metadata you want to copy verbatim (mirror). That should be easy, may need to modify the pointer to the TUF metadata to the local mirror, but I can picture a solution to that already (assuming the pointer is just an OCI index that has an annotation acting like a soft link, and the pointer itself doesn't need to be verified so it can be adjusted).
2. Upstream does not have TUF, or any upstream TUF metadata is ignored. This would be the same as adding a local TUF signature on any new image.
3. Importing upstream TUF metadata into the local TUF metadata. This is the complicated one that I think you're covering here.

[sudo-bmitch]

LGTM. I'm also remembering that we want a way to avoid "copying the world" when one repository or even a couple tags are mirrored. We may be able to push some of that off to registry settings that could allow "sparse indexes" where not all child manifests exist. But if metadata can be structured to not require that, even better.

[SteveLasker]

One more to copy a subset of the signatures.
For instance, you might have the original signature and a dev verification signature, with a staging signature. When moved into production the dev and maybe staging signatures are dropped as they aren't needed in production.
Think of the signatures as signed claims, and you don't need, or necessarily want to promote all of them

[mnm678]

I extended the third scenario to include this, and added some more detail to these initial descriptions.

[mnm678]

LGTM. I'm also remembering that we want a way to avoid "copying the world" when one repository or even a couple tags are mirrored. We may be able to push some of that off to registry settings that could allow "sparse indexes" where not all child manifests exist. But if metadata can be structured to not require that, even better.

This is an interesting one. This doc covers moving a single artifact with any signatures (which could easily be used to copy a couple of artifacts), or mirroring everything, but not mirroring most things. If this is a common scenario, we could create a delegation structure that would let you copy a sub-tree of the delegations or somethings similar.