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

akeyless_agentcore/__init__.py

@@ -0,0 +1,17 @@
+"""Fetch Akeyless secrets at runtime on AWS Bedrock AgentCore."""
+
+from akeyless_agentcore.client import (
+    AkeylessRuntimeClient,
+    get_default_client,
+    get_secret,
+    get_secret_sync,
+)
+
+__all__ = [
+    "AkeylessRuntimeClient",
+    "get_default_client",
+    "get_secret",
+    "get_secret_sync",
+]
+
+__version__ = "0.2.0"

akeyless_agentcore/auth.py

@@ -0,0 +1,134 @@
+"""Authenticate to Akeyless using cloud identity or other configured methods."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import akeyless
+from akeyless_cloud_id import CloudId
+
+from akeyless_agentcore.config import AkeylessRuntimeConfig
+
+ACCESS_KEY_DEFAULT_TTL_SECONDS = 14 * 60
+ENV_TOKEN_TTL_SECONDS = 50 * 60
+
+
+@dataclass
+class AuthSession:
+    token: str
+    expires_at: float
+
+
+def _expiry_from_auth_output(auth_out: akeyless.AuthOutput, margin_seconds: float) -> float:
+    now = time.monotonic()
+    expiration = getattr(auth_out, "expiration", None)
+    if not expiration:
+        return now + ACCESS_KEY_DEFAULT_TTL_SECONDS - margin_seconds
+
+    raw = str(expiration).strip()
+    if not raw:
+        return now + ACCESS_KEY_DEFAULT_TTL_SECONDS - margin_seconds
+
+    try:
+        as_num = float(raw)
+        if as_num > 1e12:
+            # Epoch milliseconds
+            return (as_num / 1000.0) - time.time() + now - margin_seconds
+    except ValueError:
+        pass
+
+    try:
+        as_date = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        if as_date.tzinfo is None:
+            as_date = as_date.replace(tzinfo=timezone.utc)
+        return as_date.timestamp() - time.time() + now - margin_seconds
+    except ValueError:
+        pass
+
+    return now + ACCESS_KEY_DEFAULT_TTL_SECONDS - margin_seconds
+
+
+def _get_cloud_id(config: AkeylessRuntimeConfig) -> str:
+    if config.cloud_id and config.cloud_id.strip():
+        return config.cloud_id.strip()
+
+    provider = config.cloud_provider or config.access_type
+    if provider not in ("aws_iam", "azure_ad", "gcp"):
+        raise ValueError(f"Cannot generate cloud ID for access type {provider}")
+
+    cloud_id = CloudId().generate()
+    if not cloud_id or not str(cloud_id).strip():
+        raise ValueError(
+            f"akeyless-cloud-id returned an empty cloud ID for provider {provider!r}. "
+            "On AgentCore Runtime, ensure the execution role has ambient AWS credentials "
+            "or pass cloud_id explicitly."
+        )
+    return str(cloud_id).strip()
+
+
+def _sdk_host(gateway_url: str) -> str:
+    host = gateway_url.rstrip("/")
+    if host.endswith("/api/v2"):
+        if "api.akeyless.io" in host:
+            return host[: -len("/api/v2")]
+        return host
+    if host.endswith("/v2"):
+        return host
+    if "api.akeyless.io" in host:
+        return host
+    return f"{host}/api/v2"
+
+
+def create_v2_api(gateway_url: str) -> akeyless.V2Api:
+    configuration = akeyless.Configuration(host=_sdk_host(gateway_url))
+    return akeyless.V2Api(akeyless.ApiClient(configuration))
+
+
+def authenticate(api: akeyless.V2Api, config: AkeylessRuntimeConfig) -> AuthSession:
+    now = time.monotonic()
+
+    if config.token and config.token.strip():
+        return AuthSession(
+            token=config.token.strip(),
+            expires_at=now + ENV_TOKEN_TTL_SECONDS,
+        )
+
+    access_type = config.access_type
+
+    if access_type in ("access_key", "api_key"):
+        body = akeyless.Auth(
+            access_id=config.access_id,
+            access_type=access_type,
+            access_key=config.access_key,
+        )
+    elif access_type == "universal_identity":
+        body = akeyless.Auth(
+            access_type="universal_identity",
+            uid_token=config.uid_token,
+        )
+    elif access_type == "jwt":
+        body = akeyless.Auth(
+            access_id=config.access_id,
+            access_type="jwt",
+            jwt=config.jwt,
+        )
+    elif access_type in ("aws_iam", "azure_ad", "gcp"):
+        body = akeyless.Auth(
+            access_id=config.access_id,
+            access_type=access_type,
+            cloud_id=_get_cloud_id(config),
+        )
+    else:
+        raise ValueError(f"Unsupported access type: {access_type}")
+
+    auth_out = api.auth(body)
+    token = getattr(auth_out, "token", None)
+    if not token or not str(token).strip():
+        raise ValueError("Akeyless authentication did not return a token")
+
+    return AuthSession(
+        token=str(token).strip(),
+        expires_at=_expiry_from_auth_output(auth_out, config.token_expiry_margin_seconds),
+    )

akeyless_agentcore/cache.py

@@ -0,0 +1,40 @@
+"""In-memory TTL cache for secret values and auth tokens."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class _CacheEntry(Generic[T]):
+    value: T
+    expires_at: float
+
+
+class TtlCache(Generic[T]):
+    def __init__(self) -> None:
+        self._entries: dict[str, _CacheEntry[T]] = {}
+
+    def get(self, key: str, now: float | None = None) -> T | None:
+        now = time.monotonic() if now is None else now
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+        if now >= entry.expires_at:
+            del self._entries[key]
+            return None
+        return entry.value
+
+    def set(self, key: str, value: T, ttl_seconds: float, now: float | None = None) -> None:
+        now = time.monotonic() if now is None else now
+        self._entries[key] = _CacheEntry(value=value, expires_at=now + ttl_seconds)
+
+    def delete(self, key: str) -> None:
+        self._entries.pop(key, None)
+
+    def clear(self) -> None:
+        self._entries.clear()

akeyless_agentcore/client.py

@@ -0,0 +1,363 @@
+"""Akeyless runtime client for Bedrock AgentCore agents."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import akeyless
+
+from akeyless_agentcore.auth import AuthSession, authenticate, create_v2_api
+from akeyless_agentcore.cache import TtlCache
+from akeyless_agentcore.config import AkeylessRuntimeConfig, config_from_env, validate_config
+from akeyless_agentcore.paths import (
+    format_structured_response,
+    join_secret_path,
+    normalize_path,
+    pick_secret_from_response,
+)
+
+
+def _is_not_found_error(error: Exception) -> bool:
+    status = getattr(error, "status", None)
+    if status == 404:
+        return True
+    message = str(error).lower()
+    return "not found" in message or "404" in message
+
+
+@dataclass
+class GetSecretOptions:
+    path: str | None = None
+    version: int | None = None
+    json: bool = False
+    ignore_cache: bool = False
+    allow_dynamic_fallback: bool = False
+
+
+@dataclass
+class DynamicSecretOptions:
+    path: str | None = None
+    timeout: int | None = None
+    args: list[str] | None = None
+    host: str | None = None
+    dbname: str | None = None
+    target: str | None = None
+    json: bool = False
+    ignore_cache: bool = False
+
+
+@dataclass
+class RotatedSecretOptions:
+    path: str | None = None
+    host: str | None = None
+    version: int | None = None
+    json: bool = False
+    ignore_cache: bool = False
+
+
+class AkeylessRuntimeClient:
+    def __init__(self, **config_overrides: Any) -> None:
+        self._config = config_from_env(**config_overrides)
+        validate_config(self._config)
+        self._api = create_v2_api(self._config.gateway_url)
+        self._session: AuthSession | None = None
+        self._secret_cache: TtlCache[str] = TtlCache()
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> AkeylessRuntimeClient:
+        return cls(**overrides)
+
+    @property
+    def config(self) -> AkeylessRuntimeConfig:
+        return self._config
+
+    def resolve_path(self, name_or_path: str) -> str:
+        trimmed = name_or_path.strip()
+        if trimmed.startswith("/"):
+            return normalize_path(trimmed)
+        return join_secret_path(self._config.secret_prefix, trimmed)
+
+    def clear_cache(self) -> None:
+        self._secret_cache.clear()
+        self._session = None
+
+    def _cache_key(self, path: str, kind: str, extra: str = "") -> str:
+        return f"{kind}:{path}:{extra}"
+
+    def _read_cached(self, path: str, kind: str, ignore_cache: bool) -> str | None:
+        if ignore_cache:
+            return None
+        return self._secret_cache.get(self._cache_key(path, kind))
+
+    def _write_cached(self, path: str, kind: str, value: str) -> None:
+        self._secret_cache.set(
+            self._cache_key(path, kind),
+            value,
+            self._config.secret_cache_ttl_seconds,
+        )
+
+    def _get_token(self) -> str:
+        now = time.monotonic()
+        if self._session and now < self._session.expires_at:
+            return self._session.token
+
+        self._session = authenticate(self._api, self._config)
+        return self._session.token
+
+    async def get_secret_at_path(
+        self,
+        path: str,
+        *,
+        version: int | None = None,
+        json: bool = False,
+        ignore_cache: bool = False,
+        allow_dynamic_fallback: bool = False,
+    ) -> str:
+        return self.get_secret_at_path_sync(
+            path,
+            version=version,
+            json=json,
+            ignore_cache=ignore_cache,
+            allow_dynamic_fallback=allow_dynamic_fallback,
+        )
+
+    def get_secret_at_path_sync(
+        self,
+        path: str,
+        *,
+        version: int | None = None,
+        json: bool = False,
+        ignore_cache: bool = False,
+        allow_dynamic_fallback: bool = False,
+    ) -> str:
+        resolved = normalize_path(path)
+        cached = self._read_cached(resolved, "static", ignore_cache)
+        if cached is not None:
+            return cached
+
+        token = self._get_token()
+        body_kwargs: dict[str, Any] = {"names": [resolved], "token": token}
+        if version is not None:
+            body_kwargs["version"] = version
+        if json:
+            body_kwargs["json"] = True
+        if ignore_cache:
+            body_kwargs["ignore_cache"] = "true"
+
+        try:
+            raw = self._api.get_secret_value(akeyless.GetSecretValue(**body_kwargs))
+            if isinstance(raw, dict):
+                value = pick_secret_from_response(resolved, raw)
+            else:
+                value = format_structured_response(raw)
+            self._write_cached(resolved, "static", value)
+            return value
+        except Exception as error:
+            if allow_dynamic_fallback and _is_not_found_error(error):
+                return self.get_dynamic_secret_at_path_sync(
+                    resolved,
+                    ignore_cache=ignore_cache,
+                )
+            raise
+
+    async def get_secret(
+        self,
+        name: str,
+        options: GetSecretOptions | None = None,
+    ) -> str:
+        return self.get_secret_sync(name, options)
+
+    def get_secret_sync(
+        self,
+        name: str,
+        options: GetSecretOptions | None = None,
+    ) -> str:
+        opts = options or GetSecretOptions()
+        path = opts.path or self.resolve_path(name)
+        return self.get_secret_at_path_sync(
+            path,
+            version=opts.version,
+            json=opts.json,
+            ignore_cache=opts.ignore_cache,
+            allow_dynamic_fallback=opts.allow_dynamic_fallback,
+        )
+
+    def get_secret_json_sync(
+        self,
+        name: str,
+        options: GetSecretOptions | None = None,
+    ) -> dict[str, Any]:
+        raw = self.get_secret_sync(name, options)
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError(f"Secret {name!r} is not a JSON object")
+        return data
+
+    async def get_dynamic_secret_at_path(
+        self,
+        path: str,
+        options: DynamicSecretOptions | None = None,
+    ) -> str:
+        return self.get_dynamic_secret_at_path_sync(path, options)
+
+    def get_dynamic_secret_at_path_sync(
+        self,
+        path: str,
+        options: DynamicSecretOptions | None = None,
+    ) -> str:
+        opts = options or DynamicSecretOptions()
+        resolved = normalize_path(path)
+        should_cache = not any(
+            [
+                opts.args,
+                opts.timeout is not None,
+                opts.host,
+                opts.dbname,
+                opts.target,
+            ]
+        )
+
+        if should_cache:
+            cached = self._read_cached(resolved, "dynamic", opts.ignore_cache)
+            if cached is not None:
+                return cached
+
+        token = self._get_token()
+        body_kwargs: dict[str, Any] = {"name": resolved, "token": token}
+        if opts.timeout is not None:
+            body_kwargs["timeout"] = opts.timeout
+        if opts.args:
+            body_kwargs["args"] = opts.args
+        if opts.host:
+            body_kwargs["host"] = opts.host
+        if opts.dbname:
+            body_kwargs["dbname"] = opts.dbname
+        if opts.target:
+            body_kwargs["target"] = opts.target
+        if opts.json:
+            body_kwargs["json"] = True
+        if opts.ignore_cache:
+            body_kwargs["ignore_cache"] = "true"
+
+        raw = self._api.get_dynamic_secret_value(akeyless.GetDynamicSecretValue(**body_kwargs))
+        value = format_structured_response(raw)
+
+        if should_cache:
+            self._write_cached(resolved, "dynamic", value)
+        return value
+
+    async def get_dynamic_secret(
+        self,
+        name: str,
+        options: DynamicSecretOptions | None = None,
+    ) -> str:
+        return self.get_dynamic_secret_sync(name, options)
+
+    def get_dynamic_secret_sync(
+        self,
+        name: str,
+        options: DynamicSecretOptions | None = None,
+    ) -> str:
+        opts = options or DynamicSecretOptions()
+        path = opts.path or self.resolve_path(name)
+        return self.get_dynamic_secret_at_path_sync(path, opts)
+
+    async def get_rotated_secret_at_path(
+        self,
+        path: str,
+        options: RotatedSecretOptions | None = None,
+    ) -> str:
+        return self.get_rotated_secret_at_path_sync(path, options)
+
+    def get_rotated_secret_at_path_sync(
+        self,
+        path: str,
+        options: RotatedSecretOptions | None = None,
+    ) -> str:
+        opts = options or RotatedSecretOptions()
+        resolved = normalize_path(path)
+        cached = self._read_cached(resolved, "rotated", opts.ignore_cache)
+        if cached is not None:
+            return cached
+
+        token = self._get_token()
+        body_kwargs: dict[str, Any] = {"names": resolved, "token": token}
+        if opts.host:
+            body_kwargs["host"] = opts.host
+        if opts.version is not None:
+            body_kwargs["version"] = opts.version
+        if opts.json:
+            body_kwargs["json"] = True
+        if opts.ignore_cache:
+            body_kwargs["ignore_cache"] = "true"
+
+        raw = self._api.get_rotated_secret_value(akeyless.GetRotatedSecretValue(**body_kwargs))
+        value = format_structured_response(raw)
+        self._write_cached(resolved, "rotated", value)
+        return value
+
+    async def get_rotated_secret(
+        self,
+        name: str,
+        options: RotatedSecretOptions | None = None,
+    ) -> str:
+        return self.get_rotated_secret_sync(name, options)
+
+    def get_rotated_secret_sync(
+        self,
+        name: str,
+        options: RotatedSecretOptions | None = None,
+    ) -> str:
+        opts = options or RotatedSecretOptions()
+        path = opts.path or self.resolve_path(name)
+        return self.get_rotated_secret_at_path_sync(path, opts)
+
+    def list_secrets_sync(self, prefix: str | None = None) -> list[str]:
+        """List secret names under a prefix. Returns paths only, never values."""
+        resolved = normalize_path(prefix or self._config.secret_prefix)
+        token = self._get_token()
+        result = self._api.list_items(
+            akeyless.ListItems(
+                path=resolved,
+                token=token,
+                minimal_view=True,
+                auto_pagination="enabled",
+            )
+        )
+
+        items = getattr(result, "items", None) or []
+        names: list[str] = []
+        for item in items:
+            if isinstance(item, dict):
+                name = item.get("item_name")
+            else:
+                name = getattr(item, "item_name", None)
+            if name:
+                names.append(str(name))
+        return sorted(names)
+
+
+_default_client: AkeylessRuntimeClient | None = None
+
+
+def get_default_client(**overrides: Any) -> AkeylessRuntimeClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = AkeylessRuntimeClient(**overrides)
+    return _default_client
+
+
+def reset_default_client() -> None:
+    global _default_client
+    _default_client = None
+
+
+async def get_secret(name: str, options: GetSecretOptions | None = None) -> str:
+    return await get_default_client().get_secret(name, options)
+
+
+def get_secret_sync(name: str, options: GetSecretOptions | None = None) -> str:
+    return get_default_client().get_secret_sync(name, options)