akeyless-agentcore-runtime 0.2.0__py3-none-any.whl

akeyless_agentcore/config.py

@@ -0,0 +1,168 @@
+"""Configuration from environment variables and explicit overrides."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from akeyless_agentcore.paths import default_agentcore_secret_prefix
+
+AccessType = Literal[
+    "access_key",
+    "api_key",
+    "aws_iam",
+    "azure_ad",
+    "gcp",
+    "universal_identity",
+    "jwt",
+]
+CloudProvider = Literal["aws_iam", "azure_ad", "gcp"]
+
+DEFAULT_GATEWAY = "https://api.akeyless.io"
+DEFAULT_SECRET_CACHE_TTL_SECONDS = 5 * 60
+DEFAULT_TOKEN_EXPIRY_MARGIN_SECONDS = 60
+
+
+def _read_env(name: str) -> str | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    trimmed = value.strip()
+    return trimmed or None
+
+
+def _parse_positive_float(raw: str | None, fallback: float) -> float:
+    if raw is None:
+        return fallback
+    try:
+        parsed = float(raw)
+    except ValueError:
+        return fallback
+    return parsed if parsed >= 0 else fallback
+
+
+def _parse_access_type(raw: str | None) -> AccessType:
+    value = (raw or "aws_iam").lower()
+    allowed: tuple[AccessType, ...] = (
+        "access_key",
+        "api_key",
+        "aws_iam",
+        "azure_ad",
+        "gcp",
+        "universal_identity",
+        "jwt",
+    )
+    if value not in allowed:
+        raise ValueError(
+            f'Unsupported AKEYLESS_ACCESS_TYPE "{raw}". '
+            "Expected access_key, api_key, aws_iam, azure_ad, gcp, universal_identity, or jwt."
+        )
+    return value  # type: ignore[return-value]
+
+
+def _cloud_provider_for_access_type(access_type: AccessType) -> CloudProvider | None:
+    if access_type in ("aws_iam", "azure_ad", "gcp"):
+        return access_type
+    return None
+
+
+@dataclass
+class AkeylessRuntimeConfig:
+    gateway_url: str = DEFAULT_GATEWAY
+    secret_prefix: str = "/"
+    access_type: AccessType = "aws_iam"
+    access_id: str | None = None
+    access_key: str | None = None
+    uid_token: str | None = None
+    jwt: str | None = None
+    token: str | None = None
+    cloud_id: str | None = None
+    cloud_provider: CloudProvider | None = None
+    secret_cache_ttl_seconds: float = DEFAULT_SECRET_CACHE_TTL_SECONDS
+    token_expiry_margin_seconds: float = DEFAULT_TOKEN_EXPIRY_MARGIN_SECONDS
+
+
+def config_from_env(**overrides: object) -> AkeylessRuntimeConfig:
+    access_type = overrides.get("access_type") or _parse_access_type(
+        _read_env("AKEYLESS_ACCESS_TYPE")
+    )
+
+    secret_prefix = overrides.get("secret_prefix")
+    if secret_prefix is None:
+        secret_prefix = _read_env("AKEYLESS_SECRET_PREFIX") or default_agentcore_secret_prefix() or "/"
+
+    cloud_provider = overrides.get("cloud_provider")
+    if cloud_provider is None:
+        cloud_provider = _cloud_provider_for_access_type(access_type)
+
+    return AkeylessRuntimeConfig(
+        gateway_url=overrides.get("gateway_url")
+        or _read_env("AKEYLESS_GATEWAY_URL")
+        or DEFAULT_GATEWAY,
+        secret_prefix=str(secret_prefix),
+        access_type=access_type,  # type: ignore[arg-type]
+        access_id=overrides.get("access_id") or _read_env("AKEYLESS_ACCESS_ID"),
+        access_key=overrides.get("access_key")
+        or _read_env("AKEYLESS_ACCESS_KEY")
+        or _read_env("AKEYLESS_API_KEY"),
+        uid_token=overrides.get("uid_token")
+        or _read_env("AKEYLESS_UID_TOKEN")
+        or _read_env("AKEYLESS_UNIVERSAL_IDENTITY_TOKEN"),
+        jwt=overrides.get("jwt") or _read_env("AKEYLESS_JWT"),
+        token=overrides.get("token") or _read_env("AKEYLESS_TOKEN"),
+        cloud_id=overrides.get("cloud_id") or _read_env("AKEYLESS_CLOUD_ID"),
+        cloud_provider=cloud_provider,  # type: ignore[arg-type]
+        secret_cache_ttl_seconds=overrides.get("secret_cache_ttl_seconds")
+        or _parse_positive_float(
+            _read_env("AKEYLESS_SECRET_CACHE_TTL_SECONDS"),
+            DEFAULT_SECRET_CACHE_TTL_SECONDS,
+        ),
+        token_expiry_margin_seconds=overrides.get("token_expiry_margin_seconds")
+        or _parse_positive_float(
+            _read_env("AKEYLESS_TOKEN_EXPIRY_MARGIN_SECONDS"),
+            DEFAULT_TOKEN_EXPIRY_MARGIN_SECONDS,
+        ),
+    )
+
+
+def validate_config(config: AkeylessRuntimeConfig) -> None:
+    if not config.gateway_url.strip():
+        raise ValueError("gateway_url is required")
+
+    if config.token and config.token.strip():
+        return
+
+    if config.access_type in ("access_key", "api_key"):
+        if not config.access_id or not config.access_key:
+            raise ValueError(
+                "access_id and access_key are required for access_key/api_key authentication "
+                "(or set token / AKEYLESS_TOKEN)"
+            )
+        return
+
+    if config.access_type == "universal_identity":
+        if not config.uid_token:
+            raise ValueError(
+                "uid_token is required for universal_identity authentication "
+                "(or set token / AKEYLESS_TOKEN)"
+            )
+        return
+
+    if config.access_type == "jwt":
+        if not config.access_id or not config.jwt:
+            raise ValueError(
+                "access_id and jwt are required for jwt authentication "
+                "(or set token / AKEYLESS_TOKEN)"
+            )
+        return
+
+    if config.access_type in ("aws_iam", "azure_ad", "gcp"):
+        if not config.access_id:
+            raise ValueError(
+                f"{config.access_type} authentication requires access_id "
+                "(or set token / AKEYLESS_TOKEN)"
+            )
+        return
+
+    raise ValueError(f"Unsupported access type: {config.access_type}")

akeyless_agentcore/paths.py

@@ -0,0 +1,79 @@
+"""Path helpers for resolving Akeyless secret names on AgentCore."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+
+def normalize_path(path: str) -> str:
+    trimmed = path.strip()
+    if not trimmed:
+        return "/"
+    with_leading = trimmed if trimmed.startswith("/") else f"/{trimmed}"
+    collapsed = "/".join(part for part in with_leading.split("/") if part)
+    return f"/{collapsed}" if collapsed else "/"
+
+
+def join_secret_path(prefix: str, name: str) -> str:
+    base = normalize_path(prefix)
+    segment = name.strip().lstrip("/")
+    if not segment:
+        return base
+    if base == "/":
+        return f"/{segment}"
+    return f"{base}/{segment}"
+
+
+def stringify_secret_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float, bool)):
+        return str(value)
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).decode("utf-8")
+    return json.dumps(value)
+
+
+def pick_secret_from_response(requested_path: str, data: dict[str, Any] | None) -> str:
+    if not data:
+        raise ValueError("Akeyless returned an empty secret payload")
+
+    trimmed = requested_path.strip()
+    candidates = [
+        trimmed,
+        normalize_path(trimmed),
+        trimmed.lstrip("/"),
+    ]
+
+    for key in candidates:
+        if key in data:
+            return stringify_secret_value(data[key])
+
+    raise ValueError(f'No value for "{requested_path}" in Akeyless response')
+
+
+def format_structured_response(data: Any) -> str:
+    if data is None:
+        raise ValueError("Akeyless returned an empty response")
+    if isinstance(data, str):
+        return data
+    return json.dumps(data)
+
+
+def agentcore_environment() -> str:
+    for key in ("AKEYLESS_ENV", "AGENTCORE_ENV", "ENVIRONMENT"):
+        value = os.environ.get(key, "").strip().lower()
+        if value:
+            return value
+    return "production"
+
+
+def default_agentcore_secret_prefix() -> str | None:
+    agent_name = os.environ.get("AGENTCORE_AGENT_NAME", "").strip()
+    if not agent_name:
+        return None
+    return f"/bedrock-agentcore/{agent_name}/{agentcore_environment()}"

akeyless_agentcore/tools/__init__.py

@@ -0,0 +1,31 @@
+"""AgentCore tool integrations for Akeyless secrets."""
+
+from akeyless_agentcore.tools.service import SecretToolService
+
+__all__ = [
+    "GATEWAY_TOOL_SCHEMA",
+    "SecretToolService",
+    "create_mcp_server",
+    "create_strands_tools",
+    "gateway_lambda_handler",
+    "run_mcp_server",
+]
+
+
+def __getattr__(name: str):
+    if name in ("create_mcp_server", "run_mcp_server"):
+        from akeyless_agentcore.tools.mcp import create_mcp_server, run_mcp_server
+
+        return {"create_mcp_server": create_mcp_server, "run_mcp_server": run_mcp_server}[name]
+    if name == "create_strands_tools":
+        from akeyless_agentcore.tools.strands import create_strands_tools
+
+        return create_strands_tools
+    if name in ("gateway_lambda_handler", "GATEWAY_TOOL_SCHEMA"):
+        from akeyless_agentcore.tools.gateway import GATEWAY_TOOL_SCHEMA, gateway_lambda_handler
+
+        return {
+            "gateway_lambda_handler": gateway_lambda_handler,
+            "GATEWAY_TOOL_SCHEMA": GATEWAY_TOOL_SCHEMA,
+        }[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

akeyless_agentcore/tools/gateway.py

@@ -0,0 +1,103 @@
+"""AgentCore Gateway Lambda handler and tool schema for Akeyless secrets."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from akeyless_agentcore.tools.service import SecretToolService, SecretType
+
+GATEWAY_TOOL_SCHEMA: dict[str, Any] = {
+    "inlinePayload": [
+        {
+            "name": "list_akeyless_secrets",
+            "description": (
+                "List Akeyless secret names under a path prefix. "
+                "Returns names only, never secret values."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "prefix": {
+                        "type": "string",
+                        "description": "Optional Akeyless path prefix (defaults to AKEYLESS_SECRET_PREFIX)",
+                    }
+                },
+            },
+        },
+        {
+            "name": "get_akeyless_secret",
+            "description": (
+                "Fetch a secret value from Akeyless using cloud identity authentication. "
+                "Use json_key to return a single field from JSON secrets."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Secret name or full path starting with /",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Optional full Akeyless path overriding prefix + name",
+                    },
+                    "secret_type": {
+                        "type": "string",
+                        "enum": ["static", "dynamic", "rotated"],
+                        "description": "Secret type (default: static)",
+                    },
+                    "json_key": {
+                        "type": "string",
+                        "description": "Return only this key from a JSON secret",
+                    },
+                    "ignore_cache": {
+                        "type": "boolean",
+                        "description": "Bypass in-memory secret cache",
+                    },
+                },
+                "required": ["name"],
+            },
+        },
+    ]
+}
+
+
+def gateway_lambda_handler(event: dict[str, Any], context: Any) -> dict[str, Any]:
+    """Lambda entrypoint for AgentCore Gateway MCP tool invocations."""
+    service = SecretToolService()
+    tool_name = "unknown"
+    if context and getattr(context, "client_context", None):
+        custom = getattr(context.client_context, "custom", None) or {}
+        tool_name = custom.get("bedrockAgentCoreToolName", "unknown")
+
+    try:
+        if "list_akeyless_secrets" in tool_name:
+            result = service.list_secrets(prefix=event.get("prefix"))
+        elif "get_akeyless_secret" in tool_name:
+            secret_type = event.get("secret_type", "static")
+            if secret_type not in ("static", "dynamic", "rotated"):
+                secret_type = "static"
+            result = service.get_secret(
+                event["name"],
+                path=event.get("path"),
+                secret_type=secret_type,  # type: ignore[arg-type]
+                json_key=event.get("json_key"),
+                ignore_cache=bool(event.get("ignore_cache", False)),
+            )
+        else:
+            result = service.get_secret(event.get("name", "")) if event.get("name") else None
+            if result is None:
+                return _lambda_response({"ok": False, "error": f"Unknown tool: {tool_name}"}, status=400)
+
+        status = 200 if result.ok else 400
+        body = json.loads(result.to_json())
+        return _lambda_response(body, status=status)
+    except KeyError as exc:
+        return _lambda_response({"ok": False, "error": f"Missing required field: {exc}"}, status=400)
+    except Exception as exc:
+        return _lambda_response({"ok": False, "error": str(exc)}, status=500)
+
+
+def _lambda_response(body: dict[str, Any], status: int = 200) -> dict[str, Any]:
+    return {"statusCode": status, "body": json.dumps(body)}

akeyless_agentcore/tools/mcp.py

@@ -0,0 +1,70 @@
+"""FastMCP server exposing Akeyless secrets as AgentCore Runtime MCP tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from akeyless_agentcore.tools.service import SecretToolService, SecretType
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as exc:  # pragma: no cover - optional dependency
+    raise ImportError(
+        "MCP support requires the 'mcp' package. Install with: pip install 'akeyless-agentcore-runtime[mcp]'"
+    ) from exc
+
+
+def create_mcp_server(
+    *,
+    name: str = "akeyless-secrets",
+    service: SecretToolService | None = None,
+    host: str = "0.0.0.0",
+    stateless_http: bool = True,
+) -> FastMCP:
+    """Create a FastMCP server with Akeyless secret tools."""
+    tool_service = service or SecretToolService()
+    mcp = FastMCP(name, host=host, stateless_http=stateless_http)
+
+    @mcp.tool()
+    def list_akeyless_secrets(prefix: str | None = None) -> str:
+        """List Akeyless secret names under a path prefix. Returns names only, never values.
+
+        Args:
+            prefix: Optional Akeyless path prefix. Defaults to AKEYLESS_SECRET_PREFIX.
+        """
+        return tool_service.list_secrets(prefix=prefix).to_json()
+
+    @mcp.tool()
+    def get_akeyless_secret(
+        name: str,
+        path: str | None = None,
+        secret_type: SecretType = "static",
+        json_key: str | None = None,
+        ignore_cache: bool = False,
+    ) -> str:
+        """Fetch a secret value from Akeyless. Authenticates with cloud identity (AWS IAM by default).
+
+        Use json_key when the secret is JSON and you only need one field (e.g. OPENAI_API_KEY).
+        Use secret_type='dynamic' or 'rotated' for non-static secrets.
+
+        Args:
+            name: Short secret name (resolved with AKEYLESS_SECRET_PREFIX) or full path starting with /
+            path: Optional full Akeyless path; overrides prefix + name resolution
+            secret_type: static, dynamic, or rotated
+            json_key: Return only this key from a JSON secret
+            ignore_cache: Bypass the in-memory secret cache
+        """
+        return tool_service.get_secret(
+            name,
+            path=path,
+            secret_type=secret_type,
+            json_key=json_key,
+            ignore_cache=ignore_cache,
+        ).to_json()
+
+    return mcp
+
+
+def run_mcp_server(**kwargs: Any) -> None:
+    """Run the Akeyless MCP server with streamable HTTP (AgentCore-compatible)."""
+    create_mcp_server(**kwargs).run(transport="streamable-http")

akeyless_agentcore/tools/service.py

@@ -0,0 +1,144 @@
+"""Shared secret tool logic for MCP, Strands, and Gateway deployments."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from akeyless_agentcore.client import AkeylessRuntimeClient, GetSecretOptions
+
+SecretType = Literal["static", "dynamic", "rotated"]
+
+
+@dataclass
+class ToolResponse:
+    ok: bool
+    data: dict[str, Any]
+    error: str | None = None
+
+    def to_json(self) -> str:
+        payload = {"ok": self.ok, **self.data}
+        if self.error:
+            payload["error"] = self.error
+        return json.dumps(payload)
+
+
+class SecretToolService:
+    """Implements secret operations exposed as AgentCore tools."""
+
+    def __init__(self, client: AkeylessRuntimeClient | None = None) -> None:
+        self._client = client or AkeylessRuntimeClient()
+
+    @property
+    def client(self) -> AkeylessRuntimeClient:
+        return self._client
+
+    def list_secrets(self, prefix: str | None = None) -> ToolResponse:
+        """List secret names under a prefix. Never returns secret values."""
+        try:
+            names = self._client.list_secrets_sync(prefix=prefix)
+            return ToolResponse(
+                ok=True,
+                data={
+                    "secrets": names,
+                    "count": len(names),
+                    "prefix": prefix or self._client.config.secret_prefix,
+                },
+            )
+        except Exception as exc:
+            return ToolResponse(ok=False, data={}, error=str(exc))
+
+    def get_secret(
+        self,
+        name: str,
+        *,
+        path: str | None = None,
+        secret_type: SecretType = "static",
+        json_key: str | None = None,
+        ignore_cache: bool = False,
+    ) -> ToolResponse:
+        """Fetch a secret value. Use json_key to return a single field from JSON secrets."""
+        try:
+            raw = self._fetch_by_type(
+                name=name,
+                path=path,
+                secret_type=secret_type,
+                ignore_cache=ignore_cache,
+            )
+            if json_key:
+                value = self._extract_json_key(raw, json_key)
+                return ToolResponse(
+                    ok=True,
+                    data={
+                        "name": name,
+                        "path": path or self._client.resolve_path(name),
+                        "json_key": json_key,
+                        "value": value,
+                        "secret_type": secret_type,
+                    },
+                )
+
+            return ToolResponse(
+                ok=True,
+                data={
+                    "name": name,
+                    "path": path or self._client.resolve_path(name),
+                    "value": raw,
+                    "secret_type": secret_type,
+                },
+            )
+        except Exception as exc:
+            return ToolResponse(ok=False, data={"name": name}, error=str(exc))
+
+    def _fetch_by_type(
+        self,
+        *,
+        name: str,
+        path: str | None,
+        secret_type: SecretType,
+        ignore_cache: bool,
+    ) -> str:
+        if secret_type == "dynamic":
+            return self._client.get_dynamic_secret_sync(
+                name,
+                path=path,
+                ignore_cache=ignore_cache,
+            )
+        if secret_type == "rotated":
+            return self._client.get_rotated_secret_sync(
+                name,
+                path=path,
+                ignore_cache=ignore_cache,
+            )
+
+        return self._client.get_secret_sync(
+            name,
+            GetSecretOptions(
+                path=path,
+                ignore_cache=ignore_cache,
+                allow_dynamic_fallback=True,
+            ),
+        )
+
+    @staticmethod
+    def _extract_json_key(raw: str, json_key: str) -> str:
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Secret is not valid JSON; cannot extract key {json_key!r}") from exc
+        if not isinstance(data, dict):
+            raise ValueError("Secret JSON must be an object to extract a key")
+        if json_key not in data:
+            raise ValueError(f"Key {json_key!r} not found in secret JSON")
+        return stringify_value(data[json_key])
+
+
+def stringify_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float, bool)):
+        return str(value)
+    return json.dumps(value)

akeyless_agentcore/tools/strands.py

@@ -0,0 +1,44 @@
+"""In-process Strands tools for agents that call Akeyless without Gateway."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from akeyless_agentcore.tools.service import SecretToolService, SecretType
+
+try:
+    from strands import tool
+except ImportError as exc:  # pragma: no cover - optional dependency
+    raise ImportError(
+        "Strands tools require strands-agents. Install with: "
+        "pip install 'akeyless-agentcore-runtime[strands]'"
+    ) from exc
+
+
+def create_strands_tools(service: SecretToolService | None = None) -> list[Any]:
+    """Return Strands tool callables backed by the shared SecretToolService."""
+    tool_service = service or SecretToolService()
+
+    @tool
+    def list_akeyless_secrets(prefix: str | None = None) -> str:
+        """List Akeyless secret names under a path prefix. Returns names only, never values."""
+        return tool_service.list_secrets(prefix=prefix).to_json()
+
+    @tool
+    def get_akeyless_secret(
+        name: str,
+        path: str | None = None,
+        secret_type: SecretType = "static",
+        json_key: str | None = None,
+        ignore_cache: bool = False,
+    ) -> str:
+        """Fetch a secret from Akeyless. Use json_key for a single field from JSON secrets."""
+        return tool_service.get_secret(
+            name,
+            path=path,
+            secret_type=secret_type,
+            json_key=json_key,
+            ignore_cache=ignore_cache,
+        ).to_json()
+
+    return [list_akeyless_secrets, get_akeyless_secret]