Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -184,8 +184,21 @@ class CredentialSafeRedirects(
connectTimeout: Duration?,
readTimeout: Duration?,
credentialQueryParameters: Set<String>,
): ClientHttpRequestFactory = overJdkClient(connectTimeout, readTimeout, credentialQueryParameters, null)

/**
* As [overJdkClient], trusting [trustedCertificates] in place of the JVM's own authorities:
* for an API signed by an authority no public trust store carries, such as a Kubernetes
* cluster's. PEM, PEM with `\n` for its line breaks, or Base64 of PEM or DER. Only this
* factory's calls trust them. Null or blank is the JVM's own trust.
*/
fun overJdkClient(
connectTimeout: Duration?,
readTimeout: Duration?,
credentialQueryParameters: Set<String>,
trustedCertificates: String?,
): ClientHttpRequestFactory =
overClient(SharedHttpClients.redirectRefusing(connectTimeout), readTimeout, credentialQueryParameters)
overClient(SharedHttpClients.redirectRefusing(connectTimeout, trustedCertificates), readTimeout, credentialQueryParameters)

/**
* As [overJdkClient], over a [client] the caller owns and closes with its own lifecycle.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ package com.embabel.agent.api.client

import com.embabel.agent.api.client.graphql.GraphQlLearner
import com.embabel.agent.api.client.model.ApiModel
import com.embabel.agent.api.client.openapi.OpenApiClientProperties
import com.embabel.agent.api.client.openapi.OpenApiLearner
import com.embabel.agent.api.tool.progressive.ProgressiveTool
import com.fasterxml.jackson.annotation.JsonTypeInfo
Expand Down Expand Up @@ -55,12 +56,16 @@ sealed interface LearnedApiSpec {
* @param serverVariables values for the `{name}` variables in an OpenAPI
* spec's `servers` URLs, overriding their defaults. Ignored by spec types
* whose endpoint is not templated.
* @param clientProperties how the tools' HTTP client is built: its timeouts, and the
* certificate authorities it trusts when the API is signed by one the JVM does not.
* Ignored by spec types that build their client another way.
*/
fun toFactory(
tags: Set<String>? = null,
operationIds: Set<String>? = null,
nameOverride: String? = null,
serverVariables: Map<String, String> = emptyMap(),
clientProperties: OpenApiClientProperties = OpenApiClientProperties(),
): (ApiCredentials) -> ProgressiveTool

/**
Expand All @@ -86,6 +91,7 @@ sealed interface LearnedApiSpec {
operationIds: Set<String>?,
nameOverride: String?,
serverVariables: Map<String, String>,
clientProperties: OpenApiClientProperties,
): (ApiCredentials) -> ProgressiveTool = { credentials ->
// Use the ref-preserving parse so each `OpenApiOperationTool`
// can emit `{"$ref": "#/$defs/Foo"}` markers in its output
Expand All @@ -95,6 +101,7 @@ sealed interface LearnedApiSpec {
val openApi = OpenApiLearner.parseSpecPreservingRefs(source, rawSpec)
OpenApiLearner.buildTool(
source, openApi, credentials, tags, operationIds, nameOverride,
clientProperties = clientProperties,
serverVariables = serverVariables,
)
}
Expand Down Expand Up @@ -128,6 +135,7 @@ sealed interface LearnedApiSpec {
operationIds: Set<String>?,
nameOverride: String?,
serverVariables: Map<String, String>,
clientProperties: OpenApiClientProperties,
): (ApiCredentials) -> ProgressiveTool = { credentials ->
// GraphQL doesn't have OpenAPI tags or operationIds —
// ignored. Filtering by GraphQL field name is a separate
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,11 @@ import java.util.concurrent.ConcurrentHashMap
* (#51, #52). A client is thread-safe and carries no per-request state, so nothing is lost by
* sharing it: credentials, query parameters and the read timeout all travel with the request.
*
* What cannot travel with the request is the redirect policy and the connect timeout, which are
* fixed when a client is built. Those are the keys: one client that follows redirects, and one
* that never does per distinct connect timeout. Connect timeouts come from configuration, so the
* number of distinct values is the number of configurations, not the number of tools.
* What cannot travel with the request is the redirect policy, the connect timeout and the
* certificate authorities trusted, which are fixed when a client is built. Those are the keys: one
* client that follows redirects, and one that never does per distinct connect timeout and set of
* trusted certificates. Both come from configuration, so the number of distinct values is the
* number of configurations, not the number of tools.
*
* The clients are never closed. Their threads are daemons, and there is one per key for the life
* of the JVM, which is the bound this exists to establish.
Expand All @@ -50,18 +51,35 @@ internal object SharedHttpClients {
.build()
}

/* Optional, because ConcurrentHashMap refuses a null key and "no connect timeout" is a key. */
private val nonFollowing = ConcurrentHashMap<Optional<Duration>, HttpClient>()
/*
* Optional, because ConcurrentHashMap refuses a null key and "no connect timeout" is a key.
* [trust] is the fingerprint of the certificates the client trusts in place of the JVM's own;
* empty for a client that trusts what the JVM does.
*/
private data class Key(val connectTimeout: Optional<Duration>, val trust: String)

private val nonFollowing = ConcurrentHashMap<Key, HttpClient>()

/**
* For credentialed calls, which [CredentialSafeRedirects] follows itself. This client must
* never follow a redirect: if it did, a credential header would go with it to another origin.
*/
fun redirectRefusing(connectTimeout: Duration?): HttpClient =
nonFollowing.computeIfAbsent(Optional.ofNullable(connectTimeout)) { key ->
fun redirectRefusing(connectTimeout: Duration?): HttpClient = redirectRefusing(connectTimeout, null)

/**
* As [redirectRefusing], for an API signed by an authority the JVM does not trust:
* [trustedCertificates] (see [TrustedCertificates] for the forms it takes) are the only
* authorities this client accepts. Null or blank is the JVM's own trust.
*/
fun redirectRefusing(connectTimeout: Duration?, trustedCertificates: String?): HttpClient {
val certificates = trustedCertificates?.takeIf { it.isNotBlank() }?.let(TrustedCertificates::parse)
val key = Key(Optional.ofNullable(connectTimeout), certificates?.let(TrustedCertificates::fingerprint).orEmpty())
return nonFollowing.computeIfAbsent(key) {
HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NEVER)
.apply { key.ifPresent { connectTimeout(it) } }
.apply { key.connectTimeout.ifPresent { connectTimeout(it) } }
.apply { certificates?.let { sslContext(TrustedCertificates.sslContext(it)) } }
.build()
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
/*
* Copyright 2024-2026 Embabel Pty Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.embabel.agent.api.client

import java.io.ByteArrayInputStream
import java.security.KeyStore
import java.security.MessageDigest
import java.security.cert.CertificateException
import java.security.cert.CertificateFactory
import java.security.cert.X509Certificate
import java.util.Base64
import java.util.HexFormat
import javax.net.ssl.SSLContext
import javax.net.ssl.TrustManagerFactory

/**
* The certificate authorities ONE API's calls trust, in place of the JVM's own.
*
* An API inside an organisation is usually signed by an authority no public trust store carries:
* a Kubernetes cluster's own CA, a company's internal one. The choices otherwise are to add that
* authority to the JVM's trust store, which trusts it for every call the application makes, or
* to stop verifying, which trusts everybody. This trusts the given certificates for the one
* client built with them and nothing else: a call through that client is refused unless the
* server's certificate chains to one of them, and no other client is affected.
*
* The text is what an operator already has:
* - one or more PEM certificates (`-----BEGIN CERTIFICATE-----`), as a file holds them;
* - the same with its line breaks written as `\n`, as a single-line setting often carries it;
* - Base64 of either PEM or DER, which is what a kubeconfig's `certificate-authority-data` is.
*/
internal object TrustedCertificates {

/** The certificates in [text]; refuses text that holds none. */
fun parse(text: String): List<X509Certificate> {
val bytes = bytesOf(text)
val certificates = try {
CertificateFactory.getInstance("X.509").generateCertificates(ByteArrayInputStream(bytes))
} catch (e: CertificateException) {
throw IllegalArgumentException("the trusted certificates could not be read: ${e.message}", e)
}
require(certificates.isNotEmpty()) { "the trusted certificates hold no certificate" }
return certificates.map { it as X509Certificate }
}

/** An [SSLContext] that trusts [certificates] and no other authority. */
fun sslContext(certificates: List<X509Certificate>): SSLContext {
val store = KeyStore.getInstance(KeyStore.getDefaultType()).apply { load(null, null) }
certificates.forEachIndexed { index, certificate -> store.setCertificateEntry("trusted-$index", certificate) }
val trust = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()).apply { init(store) }
return SSLContext.getInstance("TLS").apply { init(null, trust.trustManagers, null) }
}

/** What tells two sets of certificates apart, whatever form each was written in. */
fun fingerprint(certificates: List<X509Certificate>): String {
val digest = MessageDigest.getInstance("SHA-256")
certificates.map { it.encoded }.sortedBy { HexFormat.of().formatHex(it) }.forEach(digest::update)
return HexFormat.of().formatHex(digest.digest())
}

private fun bytesOf(text: String): ByteArray {
val unescaped = text.trim().replace("\\n", "\n")
if (PEM_HEADER in unescaped) return unescaped.toByteArray()
return try {
Base64.getMimeDecoder().decode(unescaped)
} catch (e: IllegalArgumentException) {
throw IllegalArgumentException("the trusted certificates are neither PEM nor Base64 of a certificate", e)
}
}

private const val PEM_HEADER = "-----BEGIN CERTIFICATE-----"
}
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,17 @@ import java.time.Duration
* connect-timeout: 5s
* read-timeout: 20s
* ```
*
* [trustedCertificates] is for an API signed by an authority the JVM does not trust, such as a
* Kubernetes cluster's own: one or more certificates as PEM, PEM with `\n` for its line breaks, or
* Base64 of PEM or DER (a kubeconfig's `certificate-authority-data`). The tools built with these
* properties trust those certificates IN PLACE OF the JVM's authorities, and nothing else does.
* It is set per API by the code that builds its tools rather than once in configuration, since
* it belongs to one API.
*/
@ConfigurationProperties(prefix = "embabel.api-client.openapi")
data class OpenApiClientProperties(
data class OpenApiClientProperties @JvmOverloads constructor(
val connectTimeout: Duration = Duration.ofSeconds(5),
val readTimeout: Duration = Duration.ofSeconds(20),
val trustedCertificates: String? = null,
)
Original file line number Diff line number Diff line change
Expand Up @@ -296,6 +296,7 @@ class OpenApiLearner(
connectTimeout = clientProperties.connectTimeout,
readTimeout = clientProperties.readTimeout,
credentialQueryParameters = queryCredentialNames(openApi, credentials),
trustedCertificates = clientProperties.trustedCertificates,
)
val builder = RestClient.builder().requestFactory(requestFactory)
applyCredentials(builder, openApi, credentials)
Expand Down
Loading
Loading