diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiOperationTool.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiOperationTool.kt index afd2e6d..e194df2 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiOperationTool.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiOperationTool.kt @@ -19,6 +19,7 @@ import com.embabel.agent.api.client.ApiCall import com.embabel.agent.api.client.ApiCallError import com.embabel.agent.api.client.ApiCallInterceptor import com.embabel.agent.api.tool.Tool +import com.fasterxml.jackson.databind.JsonNode import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper import io.swagger.v3.oas.models.Operation @@ -140,6 +141,7 @@ class OpenApiOperationTool( val queryParams = resolveQueryParams(params) val headerParams = resolveHeaderParams(params) val body = resolveBody(params) + refuseUndeclaredBodyProperties(requestBodySchema(), body, "") val uri = buildUri(resolvedPath, queryParams) uriForLog = uri.toString() @@ -251,8 +253,7 @@ class OpenApiOperationTool( /** Every name the operation declares — path, query, header, and request-body properties. */ private fun declaredParameterNames(): Set { val declared = (operation.parameters ?: emptyList()).map { it.name }.toSet() - val bodyProps = operation.requestBody?.content?.values?.firstOrNull()?.schema - ?.deref(componentsSchemas)?.properties?.keys.orEmpty() + val bodyProps = requestBodySchema()?.properties?.keys.orEmpty() return declared + bodyProps } @@ -278,7 +279,7 @@ class OpenApiOperationTool( val name = match.groupValues[1] val value = params[name] out.append( - if (value != null) UriUtils.encodePathSegment(refuseDotSegment(name, value.toString()), StandardCharsets.UTF_8) + if (value != null) UriUtils.encodePathSegment(refuseDotSegment(name, refuseOffEnum("path", name, value.toString()).toString()), StandardCharsets.UTF_8) else UriUtils.encodePath(match.value, StandardCharsets.UTF_8), ) cursor = match.range.last + 1 @@ -312,6 +313,88 @@ class OpenApiOperationTool( return value } + /** + * Refuses a path or query value outside the `enum` its parameter declares. A spec that lists + * the allowed values is stating a limit, and sending another value is a request the spec forbids. + * A path value is checked as the text it is written into the path as. An array query value passes when it equals a whole enum entry or when each of its items does; an + * `items.enum` is checked item by item. + */ + private fun refuseOffEnum(location: String, name: String, value: Any?): Any? { + if (value == null) return null + val schema = operation.parameters?.firstOrNull { it.`in` == location && it.name == name } + ?.schema?.deref(componentsSchemas) ?: return value + val enum = schema.enum?.takeIf { it.isNotEmpty() } + val itemEnum = schema.items?.deref(componentsSchemas)?.enum?.takeIf { it.isNotEmpty() } + val items = (value as? Collection<*>)?.filterNotNull() ?: listOf(value) + val allowed = (enum == null || enum.any { enumMatches(it, value) } || items.all { v -> enum.any { enumMatches(it, v) } }) && + (itemEnum == null || items.all { v -> itemEnum.any { enumMatches(it, v) } }) + if (!allowed) { + throw IllegalArgumentException( + "${location.replaceFirstChar { it.uppercase() }} parameter '$name' is '$value', which is not one of ${enum ?: itemEnum}; the request was not sent", + ) + } + return value + } + + /** Compares by value: a null entry matches nothing, numbers numerically, arrays element by element. */ + private fun enumMatches(candidate: Any?, value: Any?): Boolean { + val entry = if (candidate is JsonNode) objectMapper.treeToValue(candidate, Any::class.java) else candidate + return when { + entry == null || value == null -> false + entry is Collection<*> -> value is Collection<*> && entry.size == value.size && + entry.zip(value).all { (e, v) -> enumMatches(e, v) } + value is Collection<*> -> false + entry is Number -> entry.toString().toBigDecimalOrNull() + ?.let { e -> value.toString().toBigDecimalOrNull()?.compareTo(e) == 0 } + ?: (entry.toString() == value.toString()) + else -> entry.toString() == value.toString() + } + } + + private fun requestBodySchema(): Schema<*>? = operation.requestBodyMediaSchema()?.deref(componentsSchemas) + + /** + * Refuses a body that carries a property where its schema says `additionalProperties: false`, + * at any depth, or a non-object where such a closed object belongs (or an object where an array + * of them belongs), since a value of the wrong shape would otherwise skip the closure. Checked on the final body, after + * the flat and `body`-wrapper forms are merged, because either form can carry an extra property. + * Open schemas stay permissive. + */ + private fun refuseUndeclaredBodyProperties(schema: Schema<*>?, value: Any?, at: String) { + bodyViolation(schema, value, at)?.let { throw IllegalArgumentException("$it; the request was not sent") } + } + + /** How [value] breaks a closed schema under [schema], or null when it breaks none. */ + // shortcut: closure is enforced on direct object schemas; composed schemas are not validated, so a closed body must not use allOf/oneOf/anyOf. + private fun bodyViolation(schema: Schema<*>?, value: Any?, at: String): String? { + val resolved = schema?.deref(componentsSchemas) ?: return null + if (value == null) return null + if (listOfNotNull(resolved.allOf, resolved.oneOf, resolved.anyOf).any { it.isNotEmpty() }) return null + val what = if (at.isEmpty()) "Request body" else "Request body property '$at'" + val closed = resolved.additionalProperties == false + return when (value) { + is Map<*, *> -> if (resolved.items?.deref(componentsSchemas)?.additionalProperties == false) { + "$what is an object where the operation's schema expects an array" + } else { + value.entries.firstNotNullOfOrNull { (key, child) -> + val name = if (at.isEmpty()) "$key" else "$at.$key" + val declared = resolved.properties?.get(key.toString()) + when { + declared != null -> bodyViolation(declared, child, name) + resolved.additionalProperties == false -> + "Request body property '$name' is not declared by the operation's schema, which allows no other properties" + else -> bodyViolation(resolved.additionalProperties as? Schema<*>, child, name) + } + } + } + else -> if (closed) { + "$what is not an object where the operation's schema expects a closed object" + } else { + (value as? Collection<*>)?.withIndex()?.firstNotNullOfOrNull { (i, item) -> bodyViolation(resolved.items, item, "$at[$i]") } + } + } + } + /** * Resolve query parameters from the caller's argument map. * @@ -346,9 +429,7 @@ class OpenApiOperationTool( // before reading `.properties` to recover the target type's // declared body fields. Without this the request would forward // those fields as query params, which most APIs reject. - operation.requestBody?.content?.values?.firstOrNull()?.schema - ?.deref(componentsSchemas) - ?.properties?.keys?.toSet().orEmpty() + requestBodySchema()?.properties?.keys?.toSet().orEmpty() } return params @@ -359,7 +440,7 @@ class OpenApiOperationTool( } .filter { it.value != null } .mapValues { entry -> - when (val v = entry.value) { + when (val v = refuseOffEnum("query", entry.key, entry.value)) { is Collection<*> -> v.mapNotNull { it?.toString() } else -> listOf(v.toString()) } @@ -434,9 +515,7 @@ class OpenApiOperationTool( private fun resolveBody(params: Map): Any? { // Same deref reasoning as `resolveQueryParams`: the body schema // may arrive as a bare ref under the ref-preserving parse. - val bodySchema = operation.requestBody?.content?.values?.firstOrNull()?.schema - ?.deref(componentsSchemas) - ?: return null + val bodySchema = requestBodySchema() ?: return null val bodyProps = bodySchema.properties?.keys?.toSet().orEmpty() val isObjectBody = (bodySchema.type == "object" || bodyProps.isNotEmpty()) @@ -549,12 +628,8 @@ class OpenApiOperationTool( // `application/x-www-form-urlencoded` AND not `application/json`. // Conservative on purpose — JSON wins when a spec lists both, so // every existing pack keeps its current wire format. - private fun preferFormUrlEncoded(): Boolean { - val content = operation.requestBody?.content ?: return false - val keys = content.keys - if (keys.any { it.equals(MediaType.APPLICATION_JSON_VALUE, ignoreCase = true) }) return false - return keys.any { it.equals(MediaType.APPLICATION_FORM_URLENCODED_VALUE, ignoreCase = true) } - } + private fun preferFormUrlEncoded(): Boolean = + operation.requestBodyMediaType().equals(MediaType.APPLICATION_FORM_URLENCODED_VALUE, ignoreCase = true) // Flatten an arbitrary body graph into a `MultiValueMap` // using Stripe / Rails bracket syntax: `metadata[key]=v`, `items[0][price]=p`. @@ -847,7 +922,7 @@ class OpenApiOperationTool( // Body schema may itself be a $ref node when the spec was // parsed via `parseSpecPreservingRefs`; deref so the property // expansion below still finds the referenced shape's fields. - operation.requestBody?.content?.values?.firstOrNull()?.schema?.let { rawSchema -> + operation.requestBodyMediaSchema()?.let { rawSchema -> val schema = rawSchema.deref(componentsSchemas) val bodyRequiredOverall = operation.requestBody?.required ?: false @Suppress("UNCHECKED_CAST") @@ -980,9 +1055,21 @@ class OpenApiOperationTool( } /** - * Follow a single level of `$ref` against [componentsSchemas]. Returns - * [this] if there's no `$ref` or the referenced name isn't in the - * registry. Used wherever the runtime walks properties or types and + * The content type the request body is sent as: JSON when the operation declares it, else form + * encoding when declared, else the first listed. Its schema is the one the body is built and checked against. + */ +internal fun Operation.requestBodyMediaType(): String? = requestBody?.content?.keys?.let { keys -> + listOf(MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_FORM_URLENCODED_VALUE) + .firstNotNullOfOrNull { type -> keys.firstOrNull { it.equals(type, ignoreCase = true) } } + ?: keys.firstOrNull() +} + +internal fun Operation.requestBodyMediaSchema(): Schema<*>? = requestBodyMediaType()?.let { requestBody.content[it]?.schema } + +/** + * Follow a chain of `$ref`s against [componentsSchemas] to the schema it + * names. Returns the last schema reached if a `$ref` is missing from the + * registry or the chain loops back on itself. Used wherever the runtime walks properties or types and * expects a populated schema, not a bare reference (e.g. building the * request body, mapping property types into [Tool.Parameter]s). * @@ -992,9 +1079,13 @@ class OpenApiOperationTool( internal fun Schema<*>.deref( componentsSchemas: Map>, ): Schema<*> { - val ref = this.`$ref` ?: return this - val name = extractRefName(ref) ?: return this - return componentsSchemas[name] ?: this + var schema = this + val seen = mutableSetOf() + while (true) { + val name = schema.`$ref`?.let(::extractRefName) ?: return schema + if (!seen.add(name)) return schema + schema = componentsSchemas[name] ?: return schema + } } internal fun extractRefName(ref: String): String? { diff --git a/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentShapeValidationTest.kt b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentShapeValidationTest.kt new file mode 100644 index 0000000..db156a1 --- /dev/null +++ b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentShapeValidationTest.kt @@ -0,0 +1,263 @@ +/* + * 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.openapi + +import com.embabel.agent.api.client.ApiCredentials +import com.embabel.agent.api.tool.Tool +import com.embabel.agent.api.tool.progressive.ProgressiveTool +import com.embabel.agent.core.AgentProcess +import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper +import com.sun.net.httpserver.HttpServer +import io.swagger.v3.oas.models.OpenAPI +import org.junit.jupiter.api.AfterEach +import org.junit.jupiter.api.Assertions.assertFalse +import org.junit.jupiter.api.Assertions.assertTrue +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import org.mockito.Mockito.mock +import java.net.InetSocketAddress +import java.util.concurrent.CopyOnWriteArrayList + +/** + * The argument checks of [OpenApiArgumentValidationTest] hold however the spec is shaped: through + * a chain of `$ref`s, behind a JSON body listed after another content type or a form body listed + * after a non-form one, and for a parameter that is itself a `$ref`. A value of the wrong shape cannot + * slip past a closed schema, and an enum is matched by value, so a valid call is not refused. + * Bodies under `allOf`/`oneOf`/`anyOf` are sent unvalidated. + * Every case runs on both the fully-resolved parse and the ref-preserving one. + */ +class OpenApiArgumentShapeValidationTest { + + private val received = CopyOnWriteArrayList() + + private val server = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply { + createContext("/") { exchange -> + val body = exchange.requestBody.readBytes().toString(Charsets.UTF_8) + received += "${exchange.requestMethod} ${exchange.requestURI}" + (if (body.isEmpty()) "" else " $body") + val bytes = "{}".toByteArray() + exchange.sendResponseHeaders(200, bytes.size.toLong()) + exchange.responseBody.use { it.write(bytes) } + } + start() + } + + @AfterEach + fun stop() = server.stop(0) + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a closed schema reached through a chain of refs is enforced`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "chained", """{"properties":{"secret":"x"}}"""), "properties.secret") + assertSent(call(preserveRefs, "chained", """{"properties":{"amount":"5"}}""")) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a parameter enum reached through a chain of refs is enforced`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "chainedQuery", """{"q":"outside"}"""), "Query parameter 'q'") + assertSent(call(preserveRefs, "chainedQuery", """{"q":"a"}""")) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `an array where a closed object belongs is refused unsent`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "chained", """{"properties":[{"secret":"x"}]}"""), "properties") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `an object where an array belongs is refused unsent`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "chained", """{"children":{"secret":"x"}}"""), "children") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a nullable closed object still takes null`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "chained", """{"properties":null}""")) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `an enum listing null accepts its other values and not the text null`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "nullableEnum", """{"q":"a"}""")) + assertRefused(call(preserveRefs, "nullableEnum", """{"q":"null"}"""), "Query parameter 'q'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `an enum of arrays is matched against the whole array`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "arrayEnum", """{"q":["a","b"]}""")) + assertTrue(received.single().endsWith("?q=a&q=b"), received.toString()) + assertRefused(call(preserveRefs, "arrayEnum", """{"q":["a","c"]}"""), "Query parameter 'q'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a number enum is matched by numeric value`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "numberEnum", """{"q":1.0}""")) + assertRefused(call(preserveRefs, "numberEnum", """{"q":3}"""), "Query parameter 'q'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a composed body is sent unvalidated`(preserveRefs: Boolean) { + for (op in listOf("allOf", "oneOf", "anyOf")) { + assertSent(call(preserveRefs, op, """{"body":{"amount":"5","secret":"x"}}""")) + assertSent(call(preserveRefs, op, """{"body":{"secret":"x"}}""")) + } + // A wrong-shaped branch no longer excuses or blocks anything: the union is not walked. + assertSent(call(preserveRefs, "oneOfClosedChildren", """{"body":{"payload":{"secret":"x"}}}""")) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a self-referencing allOf is sent without recursing`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "loop", """{"payload":{"amount":"5"}}""")) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a scalar path enum refuses an array that would be written into the path`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "sharedParameter", """{"scope":["notes"]}"""), "Path parameter 'scope'") + assertRefused(call(preserveRefs, "sharedParameter", """{"scope":[null]}"""), "Path parameter 'scope'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `the form schema is checked when the form body is listed after another content type`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "formAfterText", """{"body":{"secret":"x"}}"""), "secret") + assertSent(call(preserveRefs, "formAfterText", """{"amount":"5"}""")) + assertTrue(received.single().endsWith(" amount=5"), received.toString()) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `only a closed object refuses a value of another shape`(preserveRefs: Boolean) { + assertSent(call(preserveRefs, "openShapes", """{"explicitOpen":["a"],"keywordOpen":["a"]}""")) + // Closure without `type` is still closure: the array is refused rather than let past it. + assertRefused(call(preserveRefs, "openShapes", """{"keywordClosed":["a"]}"""), "keywordClosed") + assertRefused(call(preserveRefs, "chained", """{"properties":"secret=x"}"""), "properties") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `the JSON schema is checked when JSON is listed after another content type`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "mixedContent", """{"properties":{"secret":"x"}}"""), "properties.secret") + assertSent(call(preserveRefs, "mixedContent", """{"properties":{"amount":"5"}}""")) + assertTrue(received.single().endsWith("""{"properties":{"amount":"5"}}"""), received.toString()) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a path parameter that is a ref to a shared parameter keeps its enum`(preserveRefs: Boolean) { + assertRefused(call(preserveRefs, "sharedParameter", """{"scope":"contacts"}"""), "Path parameter 'scope'") + assertSent(call(preserveRefs, "sharedParameter", """{"scope":"notes"}""")) + assertTrue(received.single().startsWith("GET /scoped/notes"), received.toString()) + } + + private fun assertRefused(result: Tool.Result, names: String) { + val message = (result as? Tool.Result.Error)?.message ?: throw AssertionError("sent: $received") + assertTrue(names in message, message) + assertTrue("not sent" in message, message) + assertTrue(received.isEmpty(), "sent anyway: $received") + } + + private fun assertSent(result: Tool.Result) = assertFalse(result is Tool.Result.Error, result.toString()) + + private fun call(preserveRefs: Boolean, operationId: String, input: String): Tool.Result { + received.clear() + val spec: OpenAPI = if (preserveRefs) { + OpenApiLearner.parseSpecPreservingRefs("inline", spec()) + } else { + OpenApiLearner.parseSpec("inline", spec()) + } + val tool = leafTools(OpenApiLearner.buildTool("inline", spec, ApiCredentials.None)) + .single { it.definition.name == operationId } + return tool.call(jacksonObjectMapper().readTree(input).toString()) + } + + private fun leafTools(tool: Tool): List = when (tool) { + is ProgressiveTool -> tool.innerTools(mock(AgentProcess::class.java)).flatMap(::leafTools) + else -> listOf(tool) + } + + private fun op(path: String, operationId: String, extra: String) = """ + "$path": { "post": { "operationId": "$operationId", $extra "responses": { "200": { "description": "ok" } } } } + """ + + private fun jsonBody(schema: String) = """"requestBody": { "content": { "application/json": { "schema": $schema } } },""" + + private fun query(schema: String) = """"parameters": [{ "name": "q", "in": "query", "schema": $schema }],""" + + private fun ref(name: String) = """{ "${'$'}ref": "#/components/schemas/$name" }""" + + private fun spec() = """ + { + "openapi": "3.0.3", + "info": { "title": "Shapes", "version": "1.0.0" }, + "servers": [{ "url": "http://127.0.0.1:${server.address.port}" }], + "paths": { + ${op("/chained", "chained", jsonBody(ref("Root")))}, + ${op("/chained-query", "chainedQuery", query(ref("AliasEnum")))}, + ${op("/nullable-enum", "nullableEnum", query("""{ "type": "string", "nullable": true, "enum": ["a", null] }"""))}, + ${op("/array-enum", "arrayEnum", query("""{ "type": "array", "enum": [["a", "b"], ["c"]], "items": { "type": "string" } }"""))}, + ${op("/number-enum", "numberEnum", query("""{ "type": "number", "enum": [1, 2] }"""))}, + ${op("/all-of", "allOf", jsonBody("""{ "allOf": [${ref("Closed")}, { "type": "object", "properties": { "name": { "type": "string" } } }] }"""))}, + ${op("/one-of", "oneOf", jsonBody("""{ "oneOf": [${ref("Closed")}, ${ref("ClosedName")}] }"""))}, + ${op("/any-of", "anyOf", jsonBody("""{ "anyOf": [${ref("Closed")}, ${ref("ClosedName")}] }"""))}, + ${op("/mixed", "mixedContent", """"requestBody": { "content": { + "text/plain": { "schema": { "type": "string" } }, + "application/json": { "schema": ${ref("Root")} } } },""")}, + ${op("/one-of-closed-children", "oneOfClosedChildren", jsonBody("""{ "oneOf": [ + { "type": "object", "additionalProperties": false, "properties": { "payload": ${ref("Closed")} } }, + { "type": "object", "additionalProperties": false, "properties": { "payload": { "type": "string" } } }] }"""))}, + ${op("/loop", "loop", jsonBody("""{ "type": "object", "properties": { "payload": ${ref("Loop")} } }"""))}, + ${op("/form", "formAfterText", """"requestBody": { "content": { + "text/plain": { "schema": { "type": "string" } }, + "application/x-www-form-urlencoded": { "schema": ${ref("Closed")} } } },""")}, + ${op("/open-shapes", "openShapes", jsonBody("""{ "type": "object", "properties": { + "explicitOpen": { "type": "object", "additionalProperties": true }, + "keywordOpen": { "properties": { "amount": { "type": "string" } } }, + "keywordClosed": { "properties": { "amount": { "type": "string" } }, "additionalProperties": false } } }"""))}, + "/scoped/{scope}": { "get": { "operationId": "sharedParameter", + "parameters": [{ "${'$'}ref": "#/components/parameters/Scope" }], + "responses": { "200": { "description": "ok" } } } } + }, + "components": { + "parameters": { + "Scope": { "name": "scope", "in": "path", "required": true, "schema": { "type": "string", "enum": ["notes", "tasks"] } } + }, + "schemas": { + "Root": { + "type": "object", + "additionalProperties": false, + "properties": { + "properties": { "${'$'}ref": "#/components/schemas/Alias" }, + "children": { "type": "array", "items": ${ref("Alias")} } + } + }, + "Alias": ${ref("NullableClosed")}, + "NullableClosed": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "amount": { "type": "string" } } }, + "Closed": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string" } } }, + "Loop": { "allOf": [${ref("Loop")}, ${ref("Closed")}] }, + "ClosedName": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" } } }, + "AliasEnum": ${ref("Enum")}, + "Enum": { "type": "string", "enum": ["a", "b"] } + } + } + } + """.trimIndent() +} diff --git a/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentValidationTest.kt b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentValidationTest.kt new file mode 100644 index 0000000..bb926e4 --- /dev/null +++ b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/openapi/OpenApiArgumentValidationTest.kt @@ -0,0 +1,238 @@ +/* + * 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.openapi + +import com.embabel.agent.api.client.ApiCredentials +import com.embabel.agent.api.tool.Tool +import com.embabel.agent.api.tool.progressive.ProgressiveTool +import com.embabel.agent.core.AgentProcess +import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper +import com.sun.net.httpserver.HttpServer +import io.swagger.v3.oas.models.OpenAPI +import org.junit.jupiter.api.AfterEach +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Assertions.assertFalse +import org.junit.jupiter.api.Assertions.assertTrue +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.ValueSource +import org.mockito.Mockito.mock +import java.net.InetSocketAddress +import java.util.concurrent.CopyOnWriteArrayList + +/** + * A model could send what the spec forbids: a property a closed (`additionalProperties: false`) + * body schema does not declare, at any depth and through either the flat or the `body`-wrapper + * form, or a path or query value outside its `enum`. Each is refused before a request leaves, + * asserted against a real loopback server. Every case runs on both the fully-resolved parse and + * the ref-preserving one, so `$ref` resolution is covered too. + */ +class OpenApiArgumentValidationTest { + + private val received = CopyOnWriteArrayList() + + private val server = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply { + createContext("/") { exchange -> + val body = exchange.requestBody.readBytes().toString(Charsets.UTF_8) + received += "${exchange.requestMethod} ${exchange.requestURI.rawPath}" + + (exchange.requestURI.rawQuery?.let { "?$it" } ?: "") + (if (body.isEmpty()) "" else " $body") + val bytes = "{}".toByteArray() + exchange.sendResponseHeaders(200, bytes.size.toLong()) + exchange.responseBody.use { it.write(bytes) } + } + start() + } + + @AfterEach + fun stop() = server.stop(0) + + // --- (a) closed body schemas --- + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a nested property a closed schema does not declare is refused unsent, flat form`(preserveRefs: Boolean) { + val result = call(preserveRefs, "updateDeal", """{"dealId":"7","properties":{"amount":"5","dealstage":"won"}}""") + + assertRefused(result, "properties.dealstage") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a nested property a closed schema does not declare is refused unsent, body wrapper form`(preserveRefs: Boolean) { + val result = call(preserveRefs, "updateDeal", """{"dealId":"7","body":{"properties":{"dealstage":"won"}}}""") + + assertRefused(result, "properties.dealstage") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a top-level property a closed schema does not declare is refused unsent, body wrapper form`(preserveRefs: Boolean) { + val result = call(preserveRefs, "updateDeal", """{"dealId":"7","body":{"properties":{"amount":"5"},"pipeline":"x"}}""") + + assertRefused(result, "pipeline") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a wrapper and flat fields merged still cannot smuggle a nested property`(preserveRefs: Boolean) { + val result = call( + preserveRefs, "updateDeal", + """{"dealId":"7","body":{"properties":{"dealstage":"won"}},"properties":{"amount":"5","dealstage":"won"}}""", + ) + + assertRefused(result, "properties.dealstage") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `declared properties of a closed schema are sent`(preserveRefs: Boolean) { + val result = call(preserveRefs, "updateDeal", """{"dealId":"7","properties":{"amount":"5","dealname":"A"}}""") + + assertSent(result) + assertEquals(listOf("""PATCH /deals/7 {"properties":{"amount":"5","dealname":"A"}}"""), received) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `an open schema stays permissive`(preserveRefs: Boolean) { + val result = call(preserveRefs, "updateOpen", """{"id":"7","body":{"properties":{"anything":"goes"},"extra":1}}""") + + assertSent(result) + assertEquals(listOf("""POST /open/7 {"properties":{"anything":"goes"},"extra":1}"""), received) + } + + // --- (b) enum on path and query parameters --- + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a path value outside its enum is refused unsent`(preserveRefs: Boolean) { + val result = call(preserveRefs, "associate", """{"fromObjectType":"contacts","id":"1","toObjectType":"companies"}""") + + assertRefused(result, "Path parameter 'fromObjectType'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a path value inside its enum is sent`(preserveRefs: Boolean) { + val result = call(preserveRefs, "associate", """{"fromObjectType":"notes","id":"1","toObjectType":"companies"}""") + + assertSent(result) + assertEquals(listOf("PUT /objects/notes/1/associations/companies"), received) + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a query value outside its enum is refused unsent`(preserveRefs: Boolean) { + val result = call(preserveRefs, "search", """{"kind":"c"}""") + + assertRefused(result, "Query parameter 'kind'") + } + + @ParameterizedTest + @ValueSource(booleans = [true, false]) + fun `a query value inside its enum is sent`(preserveRefs: Boolean) { + val result = call(preserveRefs, "search", """{"kind":"a"}""") + + assertSent(result) + assertEquals(listOf("GET /search?kind=a"), received) + } + + private fun assertRefused(result: Tool.Result, names: String) { + val message = (result as Tool.Result.Error).message + assertTrue(names in message, message) + assertTrue("not sent" in message, message) + assertTrue(received.isEmpty(), "sent anyway: $received") + } + + private fun assertSent(result: Tool.Result) = assertFalse(result is Tool.Result.Error, result.toString()) + + private fun call(preserveRefs: Boolean, operationId: String, input: String): Tool.Result { + val spec: OpenAPI = if (preserveRefs) { + OpenApiLearner.parseSpecPreservingRefs("inline", spec()) + } else { + OpenApiLearner.parseSpec("inline", spec()) + } + val tool = leafTools(OpenApiLearner.buildTool("inline", spec, ApiCredentials.None)) + .single { it.definition.name == operationId } + // Round-trip so the input is exactly what a model would send. + return tool.call(jacksonObjectMapper().readTree(input).toString()) + } + + private fun leafTools(tool: Tool): List = when (tool) { + is ProgressiveTool -> tool.innerTools(mock(AgentProcess::class.java)).flatMap(::leafTools) + else -> listOf(tool) + } + + private fun spec() = """ + { + "openapi": "3.0.3", + "info": { "title": "Deals", "version": "1.0.0" }, + "servers": [{ "url": "http://127.0.0.1:${server.address.port}" }], + "paths": { + "/deals/{dealId}": { + "patch": { + "operationId": "updateDeal", + "parameters": [{ "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } }], + "requestBody": { "content": { "application/json": { "schema": { "${'$'}ref": "#/components/schemas/DealUpdate" } } } }, + "responses": { "200": { "description": "ok" } } + } + }, + "/open/{id}": { + "post": { + "operationId": "updateOpen", + "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], + "requestBody": { "content": { "application/json": { "schema": { + "type": "object", + "properties": { "properties": { "type": "object", "properties": { "amount": { "type": "string" } } } } + } } } }, + "responses": { "200": { "description": "ok" } } + } + }, + "/objects/{fromObjectType}/{id}/associations/{toObjectType}": { + "put": { + "operationId": "associate", + "parameters": [ + { "name": "fromObjectType", "in": "path", "required": true, "schema": { "type": "string", "enum": ["notes", "tasks"] } }, + { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, + { "name": "toObjectType", "in": "path", "required": true, "schema": { "type": "string", "enum": ["contacts", "companies"] } } + ], + "responses": { "200": { "description": "ok" } } + } + }, + "/search": { + "get": { + "operationId": "search", + "parameters": [{ "name": "kind", "in": "query", "schema": { "type": "string", "enum": ["a", "b"] } }], + "responses": { "200": { "description": "ok" } } + } + } + }, + "components": { + "schemas": { + "DealUpdate": { + "type": "object", + "additionalProperties": false, + "properties": { "properties": { "${'$'}ref": "#/components/schemas/DealProperties" } } + }, + "DealProperties": { + "type": "object", + "additionalProperties": false, + "properties": { "amount": { "type": "string" }, "dealname": { "type": "string" } } + } + } + } + } + """.trimIndent() +}