agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/_gateway_validation.py

@@ -0,0 +1,442 @@
+"""Gateway / gateway-target flag validation (port of the gateway parts of src/cli/commands/add/validate.ts).
+
+``options`` is a dict keyed by upstream camelCase option names. Like upstream, the target validator
+normalizes some values in place (``type`` -> internal camelCase target type, ``language``,
+``endpoint`` for http-runtime).
+"""
+
+import json
+import os
+import re
+from typing import Any
+
+from agentcore.cli.commands.add._common import ValidationResult, first_issue, js_url_ok
+from agentcore.cli.commands.add.auth_options import validate_jwt_authorizer_options
+from agentcore.lib import ConfigIO, find_config_root
+from agentcore.schema import (
+    CONNECTOR_ID_VALUES,
+    GATEWAY_AUTHORIZER_TYPES,
+    GATEWAY_EXCEPTION_LEVELS,
+    TARGET_LANGUAGES,
+    TARGET_TYPE_AUTH_CONFIG,
+    GatewayName,
+    match_enum_value,
+)
+
+_PASSTHROUGH_URL = re.compile(r"^https://[a-zA-Z0-9\-.]+(:[0-9]{1,5})?(/.*)?$")
+
+
+def js_parse_int(value: Any) -> int | None:
+    """``parseInt(value, 10)``; None stands in for NaN."""
+    match = re.match(r"^\s*([+-]?\d+)", str(value))
+    return int(match.group(1)) if match else None
+
+
+def _kebab(name: str) -> str:
+    return re.sub(r"([A-Z])", r"-\1", name).lower()
+
+
+def _url_protocol(value: str) -> str:
+    return value.split(":", 1)[0].lower() + ":"
+
+
+# Port of validateCredentialExists (commands/add/validate.ts).
+def validate_credential_exists(credential_name: str) -> ValidationResult:
+    try:
+        project = ConfigIO().read_project_spec()
+        names = [c.name for c in project.credentials]
+        if credential_name not in names:
+            if not names:
+                return ValidationResult(
+                    False,
+                    f'Credential "{credential_name}" not found. No credentials are configured. '
+                    "Add credentials using 'agentcore add credential'.",
+                )
+            return ValidationResult(
+                False, f'Credential "{credential_name}" not found. Available credentials: {", ".join(names)}'
+            )
+        return ValidationResult(True)
+    except Exception:  # noqa: BLE001
+        return ValidationResult(False, "Failed to read project configuration")
+
+
+# Port of validateAddGatewayOptions (commands/add/validate.ts).
+def validate_add_gateway_options(options: dict[str, Any]) -> ValidationResult:
+    if not options.get("name"):
+        return ValidationResult(False, "--name is required")
+
+    issue = first_issue(GatewayName, options["name"])
+    if issue:
+        return ValidationResult(False, issue or "Invalid gateway name")
+
+    authorizer_type = options.get("authorizerType")
+    if authorizer_type and authorizer_type not in GATEWAY_AUTHORIZER_TYPES:
+        return ValidationResult(False, f"Invalid authorizer type. Use {', '.join(GATEWAY_AUTHORIZER_TYPES)}")
+
+    if authorizer_type == "CUSTOM_JWT":
+        jwt_result = validate_jwt_authorizer_options(options)
+        if not jwt_result.valid:
+            return jwt_result
+
+    if options.get("clientId") and authorizer_type != "CUSTOM_JWT":
+        return ValidationResult(False, "OAuth client credentials are only valid with CUSTOM_JWT authorizer")
+
+    level = options.get("exceptionLevel")
+    if level and level not in GATEWAY_EXCEPTION_LEVELS:
+        return ValidationResult(False, f"Invalid exception level: {level}. Use NONE or DEBUG")
+
+    engine, mode = options.get("policyEngine"), options.get("policyEngineMode")
+    if engine and not mode:
+        return ValidationResult(False, "--policy-engine-mode is required when --policy-engine is specified")
+    if mode and not engine:
+        return ValidationResult(False, "--policy-engine is required when --policy-engine-mode is specified")
+    if mode and mode not in ("LOG_ONLY", "ENFORCE"):
+        return ValidationResult(False, f"Invalid policy engine mode: {mode}. Use LOG_ONLY or ENFORCE")
+
+    return ValidationResult(True)
+
+
+_VALID_TYPE_LIST = ", ".join(
+    [
+        "mcp-server",
+        "api-gateway",
+        "open-api-schema",
+        "smithy-model",
+        "lambda-function-arn",
+        "http-runtime",
+        "connector",
+        "passthrough",
+    ]
+)
+TYPE_MAP = {
+    "mcp-server": "mcpServer",
+    "api-gateway": "apiGateway",
+    "open-api-schema": "openApiSchema",
+    "smithy-model": "smithyModel",
+    "lambda-function-arn": "lambdaFunctionArn",
+    "http-runtime": "httpRuntime",
+    "connector": "connector",
+    "passthrough": "passthrough",
+}
+
+
+def _has_inline_oauth(o: dict[str, Any]) -> bool:
+    # `a ?? b ?? c`: the first non-undefined value decides.
+    for key in ("oauthClientId", "oauthClientSecret", "oauthDiscoveryUrl"):
+        if o.get(key) is not None:
+            return bool(o[key])
+    return False
+
+
+# Port of validateAddGatewayTargetOptions (commands/add/validate.ts).
+def validate_add_gateway_target_options(o: dict[str, Any]) -> ValidationResult:  # noqa: C901, PLR0911, PLR0912
+    if o.get("language"):
+        o["language"] = match_enum_value(TARGET_LANGUAGES, o["language"]) or o["language"]
+
+    name_optional = o.get("type") == "connector" and (o.get("connector") or "") in ("bedrock-knowledge-bases",)
+    if not o.get("name") and not name_optional:
+        return ValidationResult(False, "--name is required")
+
+    if not o.get("type"):
+        return ValidationResult(False, f"--type is required. Valid options: {_VALID_TYPE_LIST}")
+
+    mapped = TYPE_MAP.get(o["type"])
+    if not mapped:
+        return ValidationResult(False, f"Invalid type: {o['type']}. Valid options: {_VALID_TYPE_LIST}")
+    o["type"] = mapped
+
+    if o.get("excludeDomains") and not (mapped == "connector" and o.get("connector") == "web-search"):
+        return ValidationResult(False, "--exclude-domains only applies to --connector web-search")
+
+    if not o.get("gateway"):
+        return ValidationResult(
+            False,
+            "--gateway is required. A gateway target must be attached to a gateway. "
+            "Create a gateway first with 'agentcore add gateway'.",
+        )
+
+    existing: list[str] = []
+    try:
+        existing = [g.name for g in ConfigIO().read_project_spec().agent_core_gateways]
+    except Exception:  # noqa: BLE001 - treat as no gateways
+        pass
+    if not existing:
+        return ValidationResult(
+            False,
+            "No gateways found. Create a gateway first with 'agentcore add gateway' before adding a gateway target.",
+        )
+    if o["gateway"] not in existing:
+        return ValidationResult(False, f'Gateway "{o["gateway"]}" not found. Available gateways: {", ".join(existing)}')
+
+    any_oauth_flag = any(o.get(k) for k in ("oauthClientId", "oauthClientSecret", "oauthDiscoveryUrl", "oauthScopes"))
+
+    if mapped == "apiGateway":
+        if not o.get("restApiId"):
+            return ValidationResult(False, "--rest-api-id is required for api-gateway type")
+        if not o.get("stage"):
+            return ValidationResult(False, "--stage is required for api-gateway type")
+        if o.get("endpoint"):
+            return ValidationResult(False, "--endpoint is not applicable for api-gateway type")
+        if o.get("host"):
+            return ValidationResult(False, "--host is not applicable for api-gateway type")
+        if o.get("language") and o["language"] != "Other":
+            return ValidationResult(False, "--language is not applicable for api-gateway type")
+        if o.get("outboundAuthType"):
+            normalized = o["outboundAuthType"].upper().replace("-", "_", 1)
+            if normalized not in TARGET_TYPE_AUTH_CONFIG["apiGateway"].valid_auth_types:
+                return ValidationResult(False, f"{o['outboundAuthType']} is not supported for api-gateway type")
+            if normalized == "API_KEY" and not o.get("credentialName"):
+                return ValidationResult(False, "--credential-name is required with --outbound-auth api-key")
+        if any_oauth_flag:
+            return ValidationResult(False, "OAuth options are not applicable for api-gateway type")
+        if o.get("lambdaArn"):
+            return ValidationResult(False, "--lambda-arn is not applicable for api-gateway type")
+        if o.get("toolSchemaFile"):
+            return ValidationResult(False, "--tool-schema-file is not applicable for api-gateway type")
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    if mapped == "lambdaFunctionArn":
+        if not o.get("lambdaArn"):
+            return ValidationResult(False, "--lambda-arn is required for lambda-function-arn type")
+        if not o.get("toolSchemaFile"):
+            return ValidationResult(False, "--tool-schema-file is required for lambda-function-arn type")
+        for key, flag in (("endpoint", "--endpoint"), ("host", "--host")):
+            if o.get(key):
+                return ValidationResult(False, f"{flag} is not applicable for lambda-function-arn type")
+        if o.get("language") and o["language"] != "Other":
+            return ValidationResult(False, "--language is not applicable for lambda-function-arn type")
+        for key, flag in (
+            ("restApiId", "--rest-api-id"),
+            ("stage", "--stage"),
+            ("toolFilterPath", "--tool-filter-path"),
+            ("toolFilterMethods", "--tool-filter-methods"),
+            ("outboundAuthType", "--outbound-auth"),
+            ("credentialName", "--credential-name"),
+        ):
+            if o.get(key):
+                return ValidationResult(False, f"{flag} is not applicable for lambda-function-arn type")
+        if any_oauth_flag:
+            return ValidationResult(False, "OAuth options are not applicable for lambda-function-arn type")
+
+        config_root = find_config_root()
+        project_root = os.path.dirname(config_root) if config_root else os.getcwd()
+        schema_file = o["toolSchemaFile"]
+        resolved = schema_file if os.path.isabs(schema_file) else os.path.join(project_root, schema_file)
+        if not os.path.exists(resolved):
+            return ValidationResult(False, f"Tool schema file not found: {schema_file}")
+        try:
+            with open(resolved, encoding="utf-8") as fh:
+                parsed = json.load(fh)
+        except (ValueError, OSError):
+            return ValidationResult(False, f"Tool schema file is not valid JSON: {schema_file}")
+        if not isinstance(parsed, list):
+            return ValidationResult(False, "Tool schema file must contain a JSON array")
+        if not parsed:
+            return ValidationResult(False, "Tool schema file must contain at least one tool definition")
+        for i, entry in enumerate(parsed):
+            item = entry if isinstance(entry, dict) else {}
+            if not isinstance(item.get("name"), str) or not item["name"]:
+                return ValidationResult(False, f'Tool schema entry {i} is missing a valid "name" field')
+            if not isinstance(item.get("description"), str) or not item["description"]:
+                return ValidationResult(False, f'Tool schema entry {i} is missing a valid "description" field')
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    if mapped == "httpRuntime":
+        if not o.get("runtime"):
+            return ValidationResult(False, "--runtime is required for http-runtime type")
+        if o.get("language") and o["language"] != "Other":
+            return ValidationResult(False, "--language is not applicable for http-runtime type")
+        for opt in (
+            "host",
+            "restApiId",
+            "stage",
+            "lambdaArn",
+            "toolSchemaFile",
+            "toolFilterPath",
+            "toolFilterMethods",
+            "schema",
+        ):
+            if o.get(opt):
+                return ValidationResult(False, f"--{_kebab(opt)} is not applicable for http-runtime type")
+        if o.get("runtimeEndpoint"):
+            o["endpoint"] = o["runtimeEndpoint"]
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    if mapped == "connector":
+        valid_connectors = ", ".join(CONNECTOR_ID_VALUES)
+        connector = o.get("connector")
+        kb_ids = o.get("knowledgeBaseId") or []
+        if not connector:
+            return ValidationResult(False, f"--connector is required for connector type. Valid: {valid_connectors}")
+        if connector not in CONNECTOR_ID_VALUES:
+            return ValidationResult(False, f'Invalid --connector "{connector}". Valid: {valid_connectors}')
+        if connector == "web-search" and kb_ids:
+            return ValidationResult(False, "--knowledge-base-id is not applicable for --connector web-search")
+        if connector != "web-search" and not kb_ids:
+            return ValidationResult(False, f"--knowledge-base-id is required for --connector {connector}")
+        if connector == "bedrock-knowledge-bases" and len(kb_ids) > 1:
+            return ValidationResult(
+                False, "--knowledge-base-id may only be specified once for --connector bedrock-knowledge-bases."
+            )
+        for key, flag in (
+            ("endpoint", "--endpoint"),
+            ("host", "--host"),
+            ("restApiId", "--rest-api-id"),
+            ("stage", "--stage"),
+            ("lambdaArn", "--lambda-arn"),
+            ("toolSchemaFile", "--tool-schema-file"),
+            ("toolFilterPath", "--tool-filter-path"),
+            ("toolFilterMethods", "--tool-filter-methods"),
+            ("schema", "--schema"),
+            ("schemaS3Account", "--schema-s3-account"),
+            ("outboundAuthType", "--outbound-auth"),
+            ("credentialName", "--credential-name"),
+            ("oauthClientId", "--oauth-client-id"),
+            ("oauthClientSecret", "--oauth-client-secret"),
+            ("oauthDiscoveryUrl", "--oauth-discovery-url"),
+            ("oauthScopes", "--oauth-scopes"),
+        ):
+            if o.get(key):
+                return ValidationResult(False, f"{flag} is not applicable for connector type")
+        if o.get("language") and o["language"] != "Other":
+            return ValidationResult(False, "--language is not applicable for connector type")
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    if mapped == "passthrough":
+        endpoint = o.get("passthroughEndpoint")
+        if not endpoint:
+            return ValidationResult(False, "--passthrough-endpoint is required for passthrough type")
+        if not _PASSTHROUGH_URL.match(endpoint):
+            return ValidationResult(False, "--passthrough-endpoint must be a valid HTTPS URL")
+        if o.get("language") and o["language"] != "Other":
+            return ValidationResult(False, "--language is not applicable for passthrough type")
+        for opt in (
+            "host",
+            "restApiId",
+            "stage",
+            "lambdaArn",
+            "toolSchemaFile",
+            "toolFilterPath",
+            "toolFilterMethods",
+            "schema",
+            "runtime",
+            "runtimeEndpoint",
+        ):
+            if o.get(opt):
+                return ValidationResult(False, f"--{_kebab(opt)} is not applicable for passthrough type")
+        if o.get("stickinessTimeout"):
+            timeout = js_parse_int(o["stickinessTimeout"])
+            if timeout is None or timeout < 1 or timeout > 86400:
+                return ValidationResult(False, "--stickiness-timeout must be a number between 1 and 86400")
+        if o.get("outboundAuthType"):
+            normalized = o["outboundAuthType"].upper().replace("-", "_")
+            if normalized in ("GATEWAY_IAM_ROLE", "JWT_PASSTHROUGH"):
+                pass
+            elif normalized == "OAUTH":
+                if not o.get("credentialName") and not _has_inline_oauth(o):
+                    return ValidationResult(False, "--credential-name or inline OAuth fields required for OAUTH auth")
+            elif normalized != "NONE":
+                return ValidationResult(
+                    False, f"Unsupported outbound auth type for passthrough: {o['outboundAuthType']}"
+                )
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    auth = o.get("outboundAuthType")
+    if auth and auth != "NONE":
+        inline = _has_inline_oauth(o)
+        if auth == "API_KEY" and inline:
+            return ValidationResult(
+                False, "Inline OAuth fields cannot be used with API_KEY outbound auth. Use --credential-name instead."
+            )
+        if not o.get("credentialName") and not inline:
+            return ValidationResult(
+                False,
+                "--credential-name is required when outbound auth type is API_KEY"
+                if auth == "API_KEY"
+                else "--credential-name or inline OAuth fields (--oauth-client-id, --oauth-client-secret, "
+                f"--oauth-discovery-url) required when outbound auth type is {auth}",
+            )
+        if inline:
+            if not o.get("oauthClientId"):
+                return ValidationResult(False, "--oauth-client-id is required for inline OAuth credential creation")
+            if not o.get("oauthClientSecret"):
+                return ValidationResult(False, "--oauth-client-secret is required for inline OAuth credential creation")
+            if not o.get("oauthDiscoveryUrl"):
+                return ValidationResult(False, "--oauth-discovery-url is required for inline OAuth credential creation")
+            if not js_url_ok(o["oauthDiscoveryUrl"]):
+                return ValidationResult(False, "--oauth-discovery-url must be a valid URL")
+        if o.get("credentialName"):
+            result = validate_credential_exists(o["credentialName"])
+            if not result.valid:
+                return result
+
+    if mapped in ("openApiSchema", "smithyModel"):
+        schema = o.get("schema")
+        if not schema:
+            return ValidationResult(False, "--schema is required for schema-based target types")
+        if o.get("endpoint"):
+            return ValidationResult(False, f"--endpoint is not applicable for {mapped} target type")
+        if o.get("host"):
+            return ValidationResult(False, f"--host is not applicable for {mapped} target type")
+        auth_config = TARGET_TYPE_AUTH_CONFIG[mapped]
+        provided = o.get("outboundAuthType") or "NONE"
+        if auth_config.auth_required and provided == "NONE":
+            return ValidationResult(
+                False, f"{mapped} targets require outbound auth ({' or '.join(auth_config.valid_auth_types)})"
+            )
+        if not auth_config.valid_auth_types and provided != "NONE":
+            return ValidationResult(False, f"{mapped} targets use IAM role auth; --outbound-auth is not applicable")
+        is_s3 = schema.startswith("s3://")
+        if is_s3:
+            s3_path = schema[5:]
+            if "/" not in s3_path or s3_path.startswith("/"):
+                return ValidationResult(False, "Invalid S3 URI format. Expected: s3://bucket-name/key")
+        else:
+            config_root = find_config_root()
+            project_root = os.path.dirname(config_root) if config_root else None
+            resolved = os.path.join(project_root, schema) if project_root else os.path.abspath(schema)
+            resolved = os.path.normpath(resolved)
+            if not os.path.exists(resolved):
+                return ValidationResult(
+                    False,
+                    f"Schema file not found: {schema} (resolved to {resolved}). Path should be relative to the "
+                    "project root."
+                    if project_root
+                    else f"Schema file not found: {schema}",
+                )
+            ext = os.path.splitext(resolved)[1].lower()
+            if ext != ".json":
+                return ValidationResult(False, f"Schema file must be a JSON file (.json), got: {ext}")
+        if o.get("schemaS3Account") and not is_s3:
+            return ValidationResult(False, "--schema-s3-account is only valid with S3 URIs")
+        o["language"] = "Other"
+        return ValidationResult(True)
+
+    if mapped == "mcpServer":
+        if o.get("host"):
+            return ValidationResult(False, "--host is not applicable for MCP server targets")
+        endpoint = o.get("endpoint")
+        if not endpoint:
+            return ValidationResult(False, "--endpoint is required for mcp-server type")
+        if not js_url_ok(endpoint):
+            return ValidationResult(False, "Endpoint must be a valid URL (e.g. https://example.com/mcp)")
+        if _url_protocol(endpoint) not in ("http:", "https:"):
+            return ValidationResult(False, "Endpoint must use http:// or https:// protocol")
+        if o.get("lambdaArn"):
+            return ValidationResult(False, "--lambda-arn is not applicable for mcp-server type")
+        if o.get("toolSchemaFile"):
+            return ValidationResult(False, "--tool-schema-file is not applicable for mcp-server type")
+        if o.get("language") is None:
+            o["language"] = "Other"
+        return ValidationResult(True)
+
+    if not o.get("language"):
+        return ValidationResult(False, "--language is required")
+    if o["language"] not in ("Python", "TypeScript", "Other"):
+        return ValidationResult(False, "Invalid language. Valid options: Python, TypeScript, Other")
+    return ValidationResult(True)