Cleanup several classes (#772)

Signed-off-by: Valentin Delaye <jonesbusy@users.noreply.github.com>

Author: jonesbusy

README.md

@@ -357,8 +357,9 @@ made by that key are accepted:
 Multiple keys (`keyPaths`/`keyDatas`) and keyless (Fulcio/Rekor) verification are **not** supported.
 Signatures are discovered through the OCI [referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
 (the Sigstore bundle, `application/vnd.dev.sigstore.bundle.v0.3+json`, attached to the image); no
-local signature store is consulted. The `signedIdentity` field is accepted but, because the bundle
-binds only the image digest, matching is limited to the digest of the pulled image.
+local signature store is consulted. Verification binds the signature to the pulled image by its
+digest. The `signedIdentity` field is **not supported** and is ignored if present, because the
+cosign bundle payload carries only the image digest and no claimed Docker reference to match against.
 
 ```json
 {

src/main/java/land/oras/ContainerRef.java

@@ -28,6 +28,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import land.oras.exception.OrasException;
+import land.oras.policy.Transport;
 import land.oras.utils.Const;
 import land.oras.utils.SupportedAlgorithm;
 import org.jspecify.annotations.NullMarked;
@@ -536,7 +537,7 @@ public boolean isBlocked(Registry registry) {
         // Check containers policy. Strip a trailing ":tag" and/or "@digest" without touching a
         // "host:port" registry (the tag colon always follows the last "/").
         String scope = effectiveRef.toString().replaceFirst("(:[^/@]+)?(@[^/]+)?$", "");
-        boolean allowed = registry.getContainersPolicy().isAllowed("docker", scope);
+        boolean allowed = registry.getContainersPolicy().isAllowed(Transport.DOCKER, scope);
         if (!allowed) {
             throw new OrasException("Image '%s' rejected by containers policy".formatted(this));
         }

src/main/java/land/oras/Registry.java

@@ -55,6 +55,7 @@
 import land.oras.exception.OrasException;
 import land.oras.policy.ContainersPolicy;
 import land.oras.policy.PolicyContext;
+import land.oras.policy.Transport;
 import land.oras.utils.ArchiveUtils;
 import land.oras.utils.Const;
 import land.oras.utils.JsonUtils;
@@ -508,64 +509,6 @@ public Referrers getReferrers(ContainerRef containerRef, @Nullable ArtifactType
         return JsonUtils.fromJson(response.response(), Referrers.class);
     }
 
-    /**
-     * Verify a resolved image against the containers trust policy.
-     *
-     * <p>Invoked from the pull path once a manifest/index digest is known. The lightweight scope gate
-     * ({@link ContainerRef#checkBlocked(Registry)}) has already run; this performs the content-based
-     * checks (currently Sigstore signature verification for {@code sigstoreSigned} requirements).
-     *
-     * @param containerRef the reference being pulled.
-     * @param digest       the resolved manifest/index digest.
-     * @throws OrasException if the policy rejects the image.
-     */
-    private void verifyContainersPolicy(ContainerRef containerRef, String digest) {
-        String effectiveRegistry = containerRef.getEffectiveRegistry(this);
-        ContainerRef effectiveRef = containerRef.forRegistry(effectiveRegistry);
-        // Strip a trailing ":tag" and/or "@digest" without touching a "host:port" registry (the tag
-        // colon always follows the last "/").
-        String scope = effectiveRef.toString().replaceFirst("(:[^/@]+)?(@[^/]+)?$", "");
-        ContainerRef digestRef = effectiveRef.withDigest(digest);
-        PolicyContext context = new PolicyContext(
-                "docker", scope, digest, effectiveRef.toString(), () -> fetchSigstoreBundles(digestRef));
-        containersPolicy.verify(context);
-    }
-
-    /**
-     * Fetch the raw bytes of every Sigstore bundle attached to the given image as a referrer.
-     *
-     * <p>Discovers referrers whose artifact type is {@link Const#SIGSTORE_BUNDLE_MEDIA_TYPE} and
-     * returns the bytes of each bundle layer. Uses non-verifying fetches ({@link #getDescriptor} and
-     * {@link #getBlob}) to avoid recursing back into policy verification. Any failure to enumerate or
-     * read signatures yields an empty list, which causes a {@code sigstoreSigned} requirement to fail
-     * closed.
-     *
-     * @param digestRef the image reference pinned to its digest.
-     * @return the bundle blob bytes; empty if none are attached or discovery fails.
-     */
-    private List<byte[]> fetchSigstoreBundles(ContainerRef digestRef) {
-        List<byte[]> bundles = new ArrayList<>();
-        try {
-            Referrers referrers = getReferrers(digestRef, ArtifactType.from(Const.SIGSTORE_BUNDLE_MEDIA_TYPE));
-            for (ManifestDescriptor referrer : referrers.getManifests()) {
-                // Some registries ignore the artifactType filter; enforce it client-side too.
-                if (!Const.SIGSTORE_BUNDLE_MEDIA_TYPE.equals(referrer.getArtifactType())) {
-                    continue;
-                }
-                Descriptor descriptor = getDescriptor(digestRef.withDigest(referrer.getDigest()));
-                Manifest signatureManifest = Manifest.fromJson(descriptor.getJson());
-                for (Layer layer : signatureManifest.getLayers()) {
-                    if (Const.SIGSTORE_BUNDLE_MEDIA_TYPE.equals(layer.getMediaType())) {
-                        bundles.add(getBlob(digestRef.withDigest(layer.getDigest())));
-                    }
-                }
-            }
-        } catch (Exception e) {
-            LOG.warn("Failed to fetch Sigstore signatures for {}: {}", digestRef, e.getMessage());
-        }
-        return bundles;
-    }
-
     /**
      * Delete a manifest
      * @param containerRef The artifact
@@ -1493,6 +1436,39 @@ private void logResponse(HttpClient.ResponseWrapper<?> response) {
         }
     }
 
+    private void verifyContainersPolicy(ContainerRef containerRef, String digest) {
+        String effectiveRegistry = containerRef.getEffectiveRegistry(this);
+        ContainerRef effectiveRef = containerRef.forRegistry(effectiveRegistry);
+        String scope = effectiveRef.toString().replaceFirst("(:[^/@]+)?(@[^/]+)?$", "");
+        ContainerRef digestRef = effectiveRef.withDigest(digest);
+        PolicyContext context = new PolicyContext(
+                Transport.DOCKER, scope, digest, effectiveRef.toString(), () -> fetchSigstoreBundles(digestRef));
+        containersPolicy.verify(context);
+    }
+
+    private List<byte[]> fetchSigstoreBundles(ContainerRef digestRef) {
+        List<byte[]> bundles = new ArrayList<>();
+        try {
+            Referrers referrers = getReferrers(digestRef, ArtifactType.from(Const.SIGSTORE_BUNDLE_MEDIA_TYPE));
+            for (ManifestDescriptor referrer : referrers.getManifests()) {
+                // Some registries ignore the artifactType filter
+                if (!Const.SIGSTORE_BUNDLE_MEDIA_TYPE.equals(referrer.getArtifactType())) {
+                    continue;
+                }
+                Descriptor descriptor = getDescriptor(digestRef.withDigest(referrer.getDigest()));
+                Manifest signatureManifest = Manifest.fromJson(descriptor.getJson());
+                for (Layer layer : signatureManifest.getLayers()) {
+                    if (Const.SIGSTORE_BUNDLE_MEDIA_TYPE.equals(layer.getMediaType())) {
+                        bundles.add(getBlob(digestRef.withDigest(layer.getDigest())));
+                    }
+                }
+            }
+        } catch (Exception e) {
+            LOG.warn("Failed to fetch Sigstore signatures for {}: {}", digestRef, e.getMessage());
+        }
+        return bundles;
+    }
+
     /**
      * Get blob as stream to avoid loading into memory
      * @param containerRef The container ref

src/main/java/land/oras/policy/ContainersPolicy.java

@@ -25,6 +25,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Collections;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import land.oras.OrasModel;
@@ -47,16 +48,15 @@
  * verification is required.
  *
  * @see PolicyRequirement
- * @see SignedIdentity
  */
 @NullMarked
 public class ContainersPolicy {
 
     private static final Logger LOG = LoggerFactory.getLogger(ContainersPolicy.class);
 
     /**
-     * A dedicated Jackson mapper for policy.json that supports {@link PolicyRequirement} and
-     * {@link SignedIdentity} polymorphic deserialization.
+     * A dedicated Jackson mapper for policy.json that supports {@link PolicyRequirement}
+     * polymorphic deserialization.
      *
      * <p>The global mapper in {@link JsonUtils} has a {@code NON_EMPTY} global inclusion filter
      * that would interfere with the {@code @JsonTypeInfo} resolution here, so we use a separate
@@ -148,26 +148,26 @@ public static ContainersPolicy rejectAll() {
      * operation to proceed here; their cryptographic check runs in {@link #verify(PolicyContext)} once
      * the image has been resolved during a pull.
      *
-     * @param transport the transport name, e.g. {@code "docker"}.
+     * @param transport the transport, e.g. {@link Transport#DOCKER}.
      * @param scope     the image scope, e.g. {@code "docker.io/library/nginx"}.
      * @return {@code true} if all resolved requirements pass.
      */
-    public boolean isAllowed(String transport, String scope) {
+    public boolean isAllowed(Transport transport, String scope) {
         PolicyContext context = PolicyContext.forScope(transport, scope);
         List<PolicyRequirement> requirements = resolveRequirements(transport, scope);
         for (PolicyRequirement req : requirements) {
             if (!req.verify(context)) {
-                LOG.debug("Policy requirement {} failed for transport='{}' scope='{}'", req, transport, scope);
+                LOG.debug("Policy requirement {} failed for transport {} and scope {}", req, transport, scope);
                 return false;
             }
         }
-        LOG.debug("Policy all requirements passed for transport='{}' scope='{}'", transport, scope);
+        LOG.debug("Policy all requirements passed for transport {} and scope {}", transport, scope);
         return true;
     }
 
     /**
      * Verify a resolved image against this policy, performing content-based checks (such as Sigstore
-     * signature verification) that {@link #isAllowed(String, String)} cannot perform.
+     * signature verification) that {@link #isAllowed(Transport, String)} cannot perform.
      *
      * <p>All resolved requirements must pass (logical AND). If any requirement fails, an
      * {@link OrasException} is thrown describing the failure.
@@ -190,18 +190,18 @@ public void verify(PolicyContext context) {
      * Resolve the list of {@link PolicyRequirement} objects that apply to the given transport and
      * scope, following the precedence rules described in {@link #isAllowed}.
      *
-     * @param transport the transport name, e.g. {@code "docker"}.
+     * @param transport the transport, e.g. {@link Transport#DOCKER}.
      * @param scope     the image scope, e.g. {@code "docker.io/library/nginx"}.
      * @return the non-null, possibly empty list of requirements (empty means global default
      *         was used and it too was empty — treat as reject-by-default for safety).
      */
-    public List<PolicyRequirement> resolveRequirements(String transport, String scope) {
+    public List<PolicyRequirement> resolveRequirements(Transport transport, String scope) {
         Map<String, List<PolicyRequirement>> transportMap =
                 policyFile.transports().getOrDefault(transport, Collections.emptyMap());
 
         // Exact match
         if (transportMap.containsKey(scope)) {
-            LOG.debug("Policy: exact match for transport='{}' scope='{}'", transport, scope);
+            LOG.debug("Policy: exact match for transport {} and scope {}", transport, scope);
             return transportMap.get(scope);
         }
 
@@ -216,7 +216,7 @@ public List<PolicyRequirement> resolveRequirements(String transport, String scop
             }
         }
         if (best != null) {
-            LOG.debug("Policy: prefix match '{}' for transport='{}' scope='{}'", best, transport, scope);
+            LOG.debug("Policy: prefix match '{}' for transport {} and scope {}", best, transport, scope);
             return transportMap.get(best);
         }
 
@@ -230,18 +230,18 @@ public List<PolicyRequirement> resolveRequirements(String transport, String scop
             }
         }
         if (bestWildcard != null) {
-            LOG.debug("Policy: wildcard match '{}' for transport='{}' scope='{}'", bestWildcard, transport, scope);
+            LOG.debug("Policy: wildcard match '{}' for transport {} and scope {}", bestWildcard, transport, scope);
             return transportMap.get(bestWildcard);
         }
 
         // Transport default
         if (transportMap.containsKey("")) {
-            LOG.debug("Policy: transport default for transport='{}'", transport);
+            LOG.debug("Policy: transport default for transport {}", transport);
             return transportMap.get("");
         }
 
         // Default
-        LOG.debug("Policy: global default for transport='{}' scope='{}'", transport, scope);
+        LOG.debug("Policy: global default for transport {} and scope {}", transport, scope);
         return policyFile.defaultRequirements();
     }
 
@@ -257,9 +257,9 @@ public List<PolicyRequirement> getDefaultRequirements() {
     /**
      * Return all transport-scoped requirements as an unmodifiable map.
      *
-     * @return a map from transport name to a map of scope → requirements.
+     * @return a map from {@link Transport} to a map of scope → requirements.
      */
-    public Map<String, Map<String, List<PolicyRequirement>>> getTransports() {
+    public Map<Transport, Map<String, List<PolicyRequirement>>> getTransports() {
         return Collections.unmodifiableMap(policyFile.transports());
     }
 
@@ -318,21 +318,30 @@ private static List<Path> defaultPolicyPaths() {
      */
     @OrasModel
     record PolicyFile(
-            @JsonProperty("default") List<PolicyRequirement> defaultRequirements,
-            @JsonProperty("transports") Map<String, Map<String, List<PolicyRequirement>>> transports) {
+            List<PolicyRequirement> defaultRequirements,
+            Map<Transport, Map<String, List<PolicyRequirement>>> transports) {
 
         /**
-         * Creates a new {@link PolicyFile}.
+         * Deserialize a {@link PolicyFile} from its JSON form, mapping the raw transport keys to the
+         * {@link Transport} enum (any non-{@code docker} transport is merged into {@link Transport#UNKNOWN}).
          *
-         * @param defaultRequirements the global default requirements.
-         * @param transports          the per-transport requirements.
+         * @param defaultRequirements the global default requirements (key {@code "default"}).
+         * @param rawTransports       the per-transport requirements keyed by raw transport name.
+         * @return the parsed policy file.
          */
         @JsonCreator
-        PolicyFile(
+        static PolicyFile fromJson(
                 @JsonProperty("default") @Nullable List<PolicyRequirement> defaultRequirements,
-                @JsonProperty("transports") @Nullable Map<String, Map<String, List<PolicyRequirement>>> transports) {
-            this.defaultRequirements = defaultRequirements != null ? defaultRequirements : Collections.emptyList();
-            this.transports = transports != null ? transports : Collections.emptyMap();
+                @JsonProperty("transports") @Nullable Map<String, Map<String, List<PolicyRequirement>>> rawTransports) {
+            List<PolicyRequirement> defaults =
+                    defaultRequirements != null ? defaultRequirements : Collections.emptyList();
+            Map<Transport, Map<String, List<PolicyRequirement>>> byTransport = new LinkedHashMap<>();
+            if (rawTransports != null) {
+                rawTransports.forEach((name, scopes) -> byTransport
+                        .computeIfAbsent(Transport.fromValue(name), t -> new LinkedHashMap<>())
+                        .putAll(scopes));
+            }
+            return new PolicyFile(defaults, byTransport);
         }
     }
 }