feat: add PolicyCheck callback to CopyOptions (#1189)

## What

Adds an optional `PolicyCheck` callback to `CopyOptions`:

```go
PolicyCheck func(ctx context.Context, srcRef string) error
```

`Copy` invokes it once with the source reference before any I/O. A
non-nil return aborts the copy and the error is wrapped via `%w`
(`policy check failed for %s: %w`).

When `PolicyCheck` is nil the behavior is unchanged.

## Why

Lets callers plug in policy enforcement (e.g., containers-policy.json
signature/identity checks) without the root `oras` package taking a
build-time dependency on the `policy` package. Keeps the `oras` <->
`registry/remote/policy` boundary clean.

Part of the v3 PR-by-PR breakdown (**PR 17: `feat/copy-policy-check`**).
Self-contained; no new package deps.

(Note: prs.md lists `content_test.go`, `example_test.go`, and
`example_copy_test.go` under this PR, but those diffs in
`feat/everything` are actually `repo.Registry.PlainHTTP` /
`NewCredentialFunc` renames that belong to PR 13. They are intentionally
excluded here so this PR stays scoped to PolicyCheck.)

## Test plan

- [x] `go build -mod=mod ./...`
- [x] `go test -mod=mod -run TestCopy_PolicyCheck -v .` — PASS for
`rejected`, `allowed`, `no policy` subtests
- [x] `go test -mod=mod -run Copy .` — full Copy test family passes

Signed-off-by: Terry Howe <terrylhowe@gmail.com>

Author: TerryHowe

copy.go

@@ -54,6 +54,12 @@ type CopyOptions struct {
 	// reference will be passed to MapRoot, and the mapped descriptor will be
 	// used as the root node for copy.
 	MapRoot func(ctx context.Context, src content.ReadOnlyStorage, root ocispec.Descriptor) (ocispec.Descriptor, error)
+	// PolicyCheck is an optional callback invoked before copying begins.
+	// If set, it is called with the source reference string. If it returns
+	// a non-nil error, the copy is aborted. This allows decoupled policy
+	// enforcement (e.g., containers-policy.json) without importing the
+	// policy package into the root oras package.
+	PolicyCheck func(ctx context.Context, srcRef string) error
 }
 
 // WithTargetPlatform configures opts.MapRoot to select the manifest whose
@@ -136,6 +142,14 @@ func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, ds
 	if dst == nil {
 		return ocispec.Descriptor{}, newCopyError("Copy", CopyErrorOriginDestination, errors.New("nil destination target"))
 	}
+
+	// Run policy check before copy if configured.
+	if opts.PolicyCheck != nil {
+		if err := opts.PolicyCheck(ctx, srcRef); err != nil {
+			return ocispec.Descriptor{}, fmt.Errorf("policy check failed for %s: %w", srcRef, err)
+		}
+	}
+
 	if dstRef == "" {
 		dstRef = srcRef
 	}

copy_test.go

@@ -2635,3 +2635,98 @@ type badMounter struct {
 func (bm *badMounter) Mount(_ context.Context, _ ocispec.Descriptor, _ string, _ func() (io.ReadCloser, error)) error {
 	return errMount
 }
+
+func TestCopy_PolicyCheck(t *testing.T) {
+	src := memory.New()
+	ctx := context.Background()
+
+	// Push config, layer, and manifest to source
+	configContent := []byte("{}")
+	configDesc := ocispec.Descriptor{
+		MediaType: ocispec.MediaTypeImageConfig,
+		Digest:    digest.FromBytes(configContent),
+		Size:      int64(len(configContent)),
+	}
+	if err := src.Push(ctx, configDesc, bytes.NewReader(configContent)); err != nil {
+		t.Fatal(err)
+	}
+
+	layerContent := []byte("test layer")
+	layerDesc := ocispec.Descriptor{
+		MediaType: ocispec.MediaTypeImageLayer,
+		Digest:    digest.FromBytes(layerContent),
+		Size:      int64(len(layerContent)),
+	}
+	if err := src.Push(ctx, layerDesc, bytes.NewReader(layerContent)); err != nil {
+		t.Fatal(err)
+	}
+
+	manifest := ocispec.Manifest{
+		MediaType: ocispec.MediaTypeImageManifest,
+		Config:    configDesc,
+		Layers:    []ocispec.Descriptor{layerDesc},
+	}
+	manifestJSON, _ := json.Marshal(manifest)
+	manifestDesc := ocispec.Descriptor{
+		MediaType: ocispec.MediaTypeImageManifest,
+		Digest:    digest.FromBytes(manifestJSON),
+		Size:      int64(len(manifestJSON)),
+	}
+	if err := src.Push(ctx, manifestDesc, bytes.NewReader(manifestJSON)); err != nil {
+		t.Fatal(err)
+	}
+	if err := src.Tag(ctx, manifestDesc, "latest"); err != nil {
+		t.Fatal(err)
+	}
+
+	// Test: PolicyCheck rejects the copy
+	t.Run("rejected", func(t *testing.T) {
+		dst := memory.New()
+		policyErr := errors.New("image not allowed by policy")
+		opts := oras.CopyOptions{
+			PolicyCheck: func(ctx context.Context, srcRef string) error {
+				return policyErr
+			},
+		}
+
+		_, err := oras.Copy(ctx, src, "latest", dst, "latest", opts)
+		if err == nil {
+			t.Fatal("Copy() should fail when PolicyCheck rejects")
+		}
+		if !errors.Is(err, policyErr) {
+			t.Errorf("error should wrap policy error, got: %v", err)
+		}
+	})
+
+	// Test: PolicyCheck allows the copy
+	t.Run("allowed", func(t *testing.T) {
+		dst := memory.New()
+		var policyChecked bool
+		opts := oras.CopyOptions{
+			PolicyCheck: func(ctx context.Context, srcRef string) error {
+				policyChecked = true
+				if srcRef != "latest" {
+					t.Errorf("PolicyCheck got srcRef=%q, want %q", srcRef, "latest")
+				}
+				return nil
+			},
+		}
+
+		_, err := oras.Copy(ctx, src, "latest", dst, "latest", opts)
+		if err != nil {
+			t.Fatalf("Copy() error = %v", err)
+		}
+		if !policyChecked {
+			t.Error("PolicyCheck was not called")
+		}
+	})
+
+	// Test: no PolicyCheck (default)
+	t.Run("no policy", func(t *testing.T) {
+		dst := memory.New()
+		_, err := oras.Copy(ctx, src, "latest", dst, "latest", oras.CopyOptions{})
+		if err != nil {
+			t.Fatalf("Copy() error = %v", err)
+		}
+	})
+}