feat: Add public Credential sealed type and SchemeValidator interface

Author: thced

src/main/java/com/retailsvc/http/Credential.java

@@ -0,0 +1,15 @@
+package com.retailsvc.http;
+
+/**
+ * A credential extracted from a request by the library, handed to a {@link SchemeValidator} for
+ * verification. Sealed so consumers can pattern-match across scheme types.
+ */
+public sealed interface Credential
+    permits Credential.ApiKeyCredential, Credential.BearerCredential, Credential.BasicCredential {
+
+  record ApiKeyCredential(String value) implements Credential {}
+
+  record BearerCredential(String token) implements Credential {}
+
+  record BasicCredential(String username, String password) implements Credential {}
+}

src/main/java/com/retailsvc/http/SchemeValidator.java

@@ -0,0 +1,12 @@
+package com.retailsvc.http;
+
+import java.util.Optional;
+
+/**
+ * Consumer-provided callback that validates an extracted {@link Credential}. Return a non-empty
+ * {@link Optional} carrying the principal on success, or {@link Optional#empty()} to deny.
+ */
+@FunctionalInterface
+public interface SchemeValidator {
+  Optional<Object> validate(Request request, Credential credential);
+}