diff --git a/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java b/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java
new file mode 100644
index 0000000..133b712
--- /dev/null
+++ b/core/src/main/java/tech/illuin/wombat/core/secret/Secret.java
@@ -0,0 +1,67 @@
+package tech.illuin.wombat.core.secret;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * A deferred reference to a secret: it carries the key and the {@link SecretResolver} it came from, never the value.
+ *
+ * The value is resolved on every {@link #fetch()} or {@link #tryFetch()}, so a rotated credential is picked up without
+ * rebuilding whatever holds the handle, and the value lives in memory only for as long as the caller keeps it.
+ * Caching, if needed, is the resolver implementation's concern: a handle fetches through whichever resolver produced it.
+ */
+public final class Secret
+{
+ private final String key;
+ private final SecretResolver resolver;
+
+ Secret(String key, SecretResolver resolver)
+ {
+ this.key = Objects.requireNonNull(key, "key cannot be null");
+ this.resolver = Objects.requireNonNull(resolver, "resolver cannot be null");
+ }
+
+ public String key()
+ {
+ return this.key;
+ }
+
+ /**
+ * @return the current value of the secret
+ * @throws MissingSecretException when the secret is no longer bound
+ */
+ public String fetch()
+ {
+ return this.resolver.require(this.key);
+ }
+
+ /**
+ * @return the current value of the secret, empty when it is no longer bound
+ */
+ public Optional tryFetch()
+ {
+ return this.resolver.find(this.key);
+ }
+
+ @Override
+ public boolean equals(Object o)
+ {
+ if (this == o)
+ return true;
+ if (!(o instanceof Secret other))
+ return false;
+ return this.key.equals(other.key) && this.resolver == other.resolver;
+ }
+
+ @Override
+ public int hashCode()
+ {
+ return Objects.hash(this.key, System.identityHashCode(this.resolver));
+ }
+
+ @Override
+ public String toString()
+ {
+ return "Secret[" + this.key + "]";
+ }
+}
diff --git a/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java b/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java
index 85c3e3a..60be9ea 100644
--- a/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java
+++ b/core/src/main/java/tech/illuin/wombat/core/secret/SecretResolver.java
@@ -27,6 +27,38 @@ public interface SecretResolver
*/
Optional find(String key);
+ /**
+ * Checks that {@code key} is bound now, and returns a handle that resolves it again on each fetch.
+ *
+ * @return a {@link Secret} backed by this resolver
+ * @throws MissingSecretException when nothing is bound to {@code key}
+ */
+ default Secret requireAsync(String key)
+ {
+ this.require(key);
+ return new Secret(key, this);
+ }
+
+ /**
+ * Returns a handle that resolves {@code key} on each fetch, this does not check anything upfront.
+ *
+ * @return a {@link Secret} backed by this resolver
+ */
+ default Secret async(String key)
+ {
+ return new Secret(key, this);
+ }
+
+ /**
+ * Checks whether {@code key} is bound now, and if so returns a handle that resolves it again on each fetch.
+ *
+ * @return a {@link Secret} backed by this resolver, empty when nothing is bound to {@code key}
+ */
+ default Optional findAsync(String key)
+ {
+ return this.find(key).map(value -> new Secret(key, this));
+ }
+
static SecretResolver standard()
{
return new EnvironmentSecretResolver();
diff --git a/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java b/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java
new file mode 100644
index 0000000..37f5d58
--- /dev/null
+++ b/core/src/test/java/tech/illuin/wombat/core/secret/SecretTest.java
@@ -0,0 +1,137 @@
+package tech.illuin.wombat.core.secret;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SecretTest
+{
+ @Test
+ void requireAsyncReturnsAHandleForABoundKey()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get);
+
+ Secret secret = resolver.requireAsync("API_KEY");
+
+ assertEquals("API_KEY", secret.key());
+ assertEquals("s3cret", secret.fetch());
+ assertEquals("s3cret", secret.tryFetch().orElseThrow());
+ }
+
+ @Test
+ void requireAsyncFailsWhenTheKeyIsUnbound()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get);
+
+ MissingSecretException e = assertThrows(MissingSecretException.class, () -> resolver.requireAsync("API_KEY"));
+ assertEquals("API_KEY", e.key());
+ }
+
+ @Test
+ void findAsyncIsEmptyWhenTheKeyIsUnbound()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get);
+
+ assertTrue(resolver.findAsync("API_KEY").isPresent());
+ assertTrue(resolver.findAsync("OTHER").isEmpty());
+ }
+
+ @Test
+ void asyncReturnsAHandleForABoundKey()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get);
+
+ Secret secret = resolver.async("API_KEY");
+
+ assertEquals("API_KEY", secret.key());
+ assertEquals("s3cret", secret.fetch());
+ assertEquals("s3cret", secret.tryFetch().orElseThrow());
+ }
+
+ @Test
+ void asyncDoesNotCheckTheKeyUpfront()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get);
+
+ Secret secret = resolver.async("API_KEY");
+
+ assertEquals("API_KEY", secret.key());
+ assertEquals(Optional.empty(), secret.tryFetch());
+ MissingSecretException e = assertThrows(MissingSecretException.class, secret::fetch);
+ assertEquals("API_KEY", e.key());
+ }
+
+ @Test
+ void asyncPicksUpAKeyBoundAfterTheHandleWasCreated()
+ {
+ Map env = new HashMap<>();
+ SecretResolver resolver = new EnvironmentSecretResolver(env::get);
+ Secret secret = resolver.async("API_KEY");
+
+ env.put("API_KEY", "late");
+
+ assertEquals("late", secret.fetch());
+ }
+
+ @Test
+ void asyncHandleEqualsTheOneFromRequireAsync()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get);
+
+ assertEquals(resolver.requireAsync("API_KEY"), resolver.async("API_KEY"));
+ }
+
+ @Test
+ void asyncMethodsRejectNullAndBlankKeys()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of()::get);
+
+ assertThrows(IllegalArgumentException.class, () -> resolver.requireAsync(null));
+ assertThrows(IllegalArgumentException.class, () -> resolver.findAsync(" "));
+ }
+
+ @Test
+ void fetchResolvesTheCurrentValueOnEachCall()
+ {
+ // The handle carries no value: a rotation or removal after it was obtained shows on the next fetch.
+ Map env = new HashMap<>(Map.of("API_KEY", "v1"));
+ SecretResolver resolver = new EnvironmentSecretResolver(env::get);
+ Secret secret = resolver.requireAsync("API_KEY");
+
+ env.put("API_KEY", "v2");
+ assertEquals("v2", secret.fetch());
+
+ env.remove("API_KEY");
+ assertEquals(Optional.empty(), secret.tryFetch());
+ assertThrows(MissingSecretException.class, secret::fetch);
+ }
+
+ @Test
+ void toStringDoesNotLeakTheValue()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("API_KEY", "s3cret")::get);
+
+ Secret secret = resolver.requireAsync("API_KEY");
+
+ assertFalse(secret.toString().contains("s3cret"));
+ }
+
+ @Test
+ void handlesAreEqualForTheSameKeyAndResolver()
+ {
+ SecretResolver resolver = new EnvironmentSecretResolver(Map.of("A", "a", "B", "b")::get);
+ SecretResolver other = new EnvironmentSecretResolver(Map.of("A", "a")::get);
+
+ assertEquals(resolver.requireAsync("A"), resolver.requireAsync("A"));
+ assertEquals(resolver.requireAsync("A").hashCode(), resolver.requireAsync("A").hashCode());
+ assertFalse(resolver.requireAsync("A").equals(resolver.requireAsync("B")));
+ assertFalse(resolver.requireAsync("A").equals(other.requireAsync("A")));
+ }
+}