Document relative and absolute Vault path behavior.

Closes gh-926

Author: mp911de

spring-vault-core/src/main/java/org/springframework/vault/core/ReactiveVaultOperations.java

@@ -23,6 +23,7 @@
 import reactor.core.publisher.Mono;
 
 import org.springframework.vault.VaultException;
+import org.springframework.vault.client.VaultEndpoint;
 import org.springframework.vault.support.VaultResponse;
 import org.springframework.vault.support.VaultResponseSupport;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -39,6 +40,11 @@
  * {@link ReactiveVaultOperations} allows execution of callback methods. Callbacks can
  * execute requests within a {@link #doWithSession(Function) session context} and the
  * {@link #doWithVault(Function) without a session}.
+ * <p>
+ * Paths used in this interface (and interfaces accessible from here) are considered
+ * relative to the {@link VaultEndpoint}. Paths that are fully-qualified URI's can be used
+ * to access Vault cluster members in an authenticated context. To prevent unwanted full
+ * URI access, make sure to sanitize paths before passing them to this interface.
  *
  * @author Mark Paluch
  * @author James Luke

spring-vault-core/src/main/java/org/springframework/vault/core/ReactiveVaultTemplate.java

@@ -54,7 +54,18 @@
 
 /**
  * This class encapsulates main Vault interaction. {@link ReactiveVaultTemplate} will log
- * into Vault on initialization and use the token throughout the whole lifetime.
+ * into Vault on initialization and use the token throughout the whole lifetime. This is
+ * the main entry point to interact with Vault in an authenticated and unauthenticated
+ * context.
+ * <p>
+ * {@link ReactiveVaultTemplate} allows execution of callback methods. Callbacks can
+ * execute requests within a {@link #doWithSession(Function) session context} and the
+ * {@link #doWithVault(Function) without a session}.
+ * <p>
+ * Paths used in this interface (and interfaces accessible from here) are considered
+ * relative to the {@link VaultEndpoint}. Paths that are fully-qualified URI's can be used
+ * to access Vault cluster members in an authenticated context. To prevent unwanted full
+ * URI access, make sure to sanitize paths before passing them to this interface.
  *
  * @author Mark Paluch
  * @author Raoof Mohammed

spring-vault-core/src/main/java/org/springframework/vault/core/VaultOperations.java

@@ -20,6 +20,7 @@
 import org.jspecify.annotations.Nullable;
 
 import org.springframework.vault.VaultException;
+import org.springframework.vault.client.VaultEndpoint;
 import org.springframework.vault.core.VaultKeyValueOperationsSupport.KeyValueBackend;
 import org.springframework.vault.support.VaultResponse;
 import org.springframework.vault.support.VaultResponseSupport;
@@ -33,6 +34,11 @@
  * {@link VaultOperations} allows execution of callback methods. Callbacks can execute
  * requests within a {@link #doWithSession(RestOperationsCallback) session context} and
  * the {@link #doWithVault(RestOperationsCallback) without a session}.
+ * <p>
+ * Paths used in this interface (and interfaces accessible from here) are considered
+ * relative to the {@link VaultEndpoint}. Paths that are fully-qualified URI's can be used
+ * to access Vault cluster members in an authenticated context. To prevent unwanted full
+ * URI access, make sure to sanitize paths before passing them to this interface.
  *
  * @author Mark Paluch
  * @author Lauren Voswinkel

spring-vault-core/src/main/java/org/springframework/vault/core/VaultTemplate.java

@@ -47,8 +47,19 @@
 import org.springframework.web.client.RestTemplate;
 
 /**
- * This class encapsulates main Vault interaction. {@link VaultTemplate} will log into
- * Vault on initialization and use the token throughout the whole lifetime.
+ * This class encapsulates main Vault interaction. {@code VaultTemplate} will log into
+ * Vault on initialization and use the token throughout the whole lifetime. This is the
+ * main entry point to interact with Vault in an authenticated and unauthenticated
+ * context.
+ * <p>
+ * {@code VaultTemplate} allows execution of callback methods. Callbacks can execute
+ * requests within a {@link #doWithSession(RestOperationsCallback) session context} and
+ * the {@link #doWithVault(RestOperationsCallback) without a session}.
+ * <p>
+ * Paths used in this interface (and interfaces accessible from here) are considered
+ * relative to the {@link VaultEndpoint}. Paths that are fully-qualified URI's can be used
+ * to access Vault cluster members in an authenticated context. To prevent unwanted full
+ * URI access, make sure to sanitize paths before passing them to this interface.
  *
  * @author Mark Paluch
  * @see SessionManager

src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc

@@ -23,6 +23,11 @@ the use of the Vault API and `VaultOperations`. A major difference in between
 the two APIs is that `VaultOperations` can be passed domain objects instead of
 JSON Key-Value pairs.
 
+Paths used in `VaultTemplate` (and interfaces accessible from there) are considered
+relative to the `VaultEndpoint`. Paths that are fully-qualified URI's can be used
+to access Vault cluster members in an authenticated context. To prevent unwanted
+full URI access, make sure to sanitize paths before passing them to `VaultTemplate`.
+
 NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.VaultTemplate[] instance
 is via its interface javadoc:org.springframework.vault.core.VaultOperations[].
 

src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc

@@ -47,6 +47,11 @@ the use of the Vault API and javadoc:org.springframework.vault.core.ReactiveVaul
 the two APIs is that javadoc:org.springframework.vault.core.ReactiveVaultOperations[] can be passed domain objects instead of
 JSON Key-Value pairs.
 
+Paths used in `ReactiveVaultTemplate` (and interfaces accessible from there) are considered
+relative to the `VaultEndpoint`. Paths that are fully-qualified URI's can be used
+to access Vault cluster members in an authenticated context. To prevent unwanted
+full URI access, make sure to sanitize paths before passing them to `ReactiveVaultTemplate`.
+
 NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] instance
 is via its interface javadoc:org.springframework.vault.core.ReactiveVaultOperations[].