agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/deploy/pre_deploy_identity.py

@@ -0,0 +1,505 @@
+"""Pre-deploy credential provider setup (port of ``operations/deploy/pre-deploy-identity.ts``).
+
+Identity resources are not modeled as CDK constructs, so API key / OAuth2 / payment credential
+providers are created imperatively before synth (the CDK app reads their ARNs from deployed state).
+The provider CRUD calls live in ``agentcore.operations.identity`` (owned by another area).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from agentcore.aws import agentcore_payments
+from agentcore.aws.account import create_aws_client
+from agentcore.aws.agentcore_control import create_control_client
+from agentcore.cli.errors import is_no_credentials_error, is_quota_exceeded_error
+from agentcore.cli.external_requirements.checks import get_aws_login_guidance
+from agentcore.lib.errors.types import (
+    AwsCredentialsError,
+    MissingCredentialsError,
+    ServiceQuotaError,
+    ValidationError,
+)
+from agentcore.lib.result import Err, Ok, ok
+from agentcore.lib.utils.credentials import SecureCredentials
+from agentcore.lib.utils.env import read_env_file
+from agentcore.operations import identity
+from agentcore.primitives.credential_utils import (
+    compute_default_credential_env_var_name,
+    compute_payment_credential_env_var_names,
+    compute_stripe_privy_credential_env_var_names,
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Types
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ApiKeyProviderSetupResult:
+    provider_name: str
+    status: Literal["created", "updated", "exists", "skipped", "error"]
+    credential_provider_arn: str | None = None
+    error: BaseException | None = None
+
+
+@dataclass
+class PreDeployIdentityResult:
+    results: list[ApiKeyProviderSetupResult] = field(default_factory=list)
+    has_errors: bool = False
+    kms_key_arn: str | None = None
+
+
+@dataclass
+class OAuth2ProviderSetupResult:
+    provider_name: str
+    status: Literal["created", "updated", "skipped", "error"]
+    error: BaseException | None = None
+    credential_provider_arn: str | None = None
+    client_secret_arn: str | None = None
+    callback_url: str | None = None
+
+
+@dataclass
+class PreDeployOAuth2Result:
+    results: list[OAuth2ProviderSetupResult] = field(default_factory=list)
+    has_errors: bool = False
+
+
+@dataclass(frozen=True)
+class MissingCredential:
+    provider_name: str
+    env_var_name: str
+
+
+@dataclass
+class PaymentCredentialProviderResult:
+    credential_provider_arn: str
+    credential_provider_name: str
+
+
+@dataclass
+class PaymentCredentialProvidersResult:
+    credential_providers: dict[str, PaymentCredentialProviderResult] = field(default_factory=dict)
+    has_errors: bool = False
+    errors: list[BaseException] = field(default_factory=list)
+
+
+def _value(result: Any, key: str) -> Any:
+    value = getattr(result, "value", None)
+    if isinstance(value, Mapping):
+        return value.get(key)
+    return getattr(value, key, None) if value is not None else None
+
+
+def _all_credentials(config_base_dir: str, runtime_credentials: SecureCredentials | None) -> SecureCredentials:
+    env_credentials = SecureCredentials.from_env_vars(read_env_file(config_base_dir))
+    return env_credentials.merge(runtime_credentials) if runtime_credentials else env_credentials
+
+
+def _credentials_error(cause: BaseException, typo: bool = False) -> AwsCredentialsError:
+    # Upstream's OAuth path spells it "crdentials"; kept verbatim.
+    prefix = "AWS crdentials not found." if typo else "AWS credentials not found."
+    return AwsCredentialsError(f"{prefix} {get_aws_login_guidance()}", None, cause=cause)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# API key providers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def setup_api_key_providers(
+    *,
+    project_spec: Any,
+    config_base_dir: str,
+    region: str,
+    runtime_credentials: SecureCredentials | None = None,
+    enable_kms_encryption: bool = False,
+) -> PreDeployIdentityResult:
+    """Create/update an API key provider for each ApiKey credential (values from .env.local)."""
+    all_credentials = _all_credentials(config_base_dir, runtime_credentials)
+    client = create_control_client(region)
+
+    kms_key_arn = None
+    if enable_kms_encryption:
+        kms_result = _setup_token_vault_kms(region, project_spec)
+        if not kms_result.success:
+            return PreDeployIdentityResult(
+                results=[ApiKeyProviderSetupResult("TokenVault", "error", error=kms_result.error)], has_errors=True
+            )
+        kms_key_arn = kms_result.value
+
+    results = []
+    for credential in project_spec.credentials:
+        if credential.authorizer_type == "ApiKeyCredentialProvider":
+            results.append(_setup_api_key_credential_provider(client, credential, all_credentials))
+    return PreDeployIdentityResult(
+        results=results, has_errors=any(r.status == "error" for r in results), kms_key_arn=kms_key_arn
+    )
+
+
+def _setup_token_vault_kms(region: str, project_spec: Any) -> Ok[str | None] | Err[Exception]:
+    try:
+        control = create_control_client(region)
+        try:
+            vault = control.get_token_vault()
+            kms = vault.get("kmsConfiguration") or {}
+            if kms.get("keyType") == "CustomerManagedKey" and kms.get("kmsKeyArn"):
+                return Ok(kms["kmsKeyArn"])
+        except Exception:  # noqa: BLE001 - vault may not exist yet / access denied
+            pass
+        kms_client = create_aws_client("kms", region)
+        response = kms_client.create_key(
+            Description=f"AgentCore Identity encryption key for {project_spec.name}",
+            Tags=[{"TagKey": "agentcore:project", "TagValue": project_spec.name}],
+        )
+        key_arn = (response.get("KeyMetadata") or {}).get("Arn")
+        if not key_arn:
+            return Err(RuntimeError("Failed to create KMS key"))
+        result = identity.set_token_vault_kms_key(control, key_arn)
+        if not result.success:
+            return result
+        return Ok(key_arn)
+    except Exception as exc:  # noqa: BLE001
+        return Err(exc)
+
+
+def _setup_api_key_credential_provider(
+    client: Any, credential: Any, credentials: SecureCredentials
+) -> ApiKeyProviderSetupResult:
+    env_var_name = compute_default_credential_env_var_name(credential.name)
+    api_key = credentials.get(env_var_name)
+    if not api_key:
+        return ApiKeyProviderSetupResult(
+            credential.name, "skipped", error=RuntimeError(f"No {env_var_name} found in agentcore/.env.local")
+        )
+    try:
+        if identity.api_key_provider_exists(client, credential.name):
+            # Always update so the provider has current credentials.
+            result = identity.update_api_key_provider(client, credential.name, api_key)
+            status = "updated"
+        else:
+            result = identity.create_api_key_provider(client, credential.name, api_key)
+            status = "created"
+        if result.success:
+            return ApiKeyProviderSetupResult(credential.name, status, _value(result, "credentialProviderArn"))
+        return ApiKeyProviderSetupResult(credential.name, "error", error=result.error)
+    except Exception as exc:  # noqa: BLE001
+        if is_no_credentials_error(exc):
+            return ApiKeyProviderSetupResult(credential.name, "error", error=_credentials_error(exc))
+        return ApiKeyProviderSetupResult(credential.name, "error", error=exc)
+
+
+def has_identity_api_providers(project_spec: Any) -> bool:
+    return any(c.authorizer_type == "ApiKeyCredentialProvider" for c in project_spec.credentials)
+
+
+def has_identity_o_auth_providers(project_spec: Any) -> bool:
+    return any(c.authorizer_type == "OAuthCredentialProvider" for c in project_spec.credentials)
+
+
+has_identity_oauth_providers = has_identity_o_auth_providers
+
+
+def _oauth_env_names(name: str) -> tuple[str, str]:
+    key = name.upper().replace("-", "_")
+    return f"AGENTCORE_CREDENTIAL_{key}_CLIENT_ID", f"AGENTCORE_CREDENTIAL_{key}_CLIENT_SECRET"
+
+
+def get_missing_credentials(project_spec: Any, config_base_dir: str) -> list[MissingCredential]:
+    env_vars = read_env_file(config_base_dir)
+    missing = []
+    for credential in project_spec.credentials:
+        if credential.authorizer_type == "ApiKeyCredentialProvider":
+            name = compute_default_credential_env_var_name(credential.name)
+            if not env_vars.get(name):
+                missing.append(MissingCredential(credential.name, name))
+    return missing
+
+
+def get_all_credentials(project_spec: Any) -> list[MissingCredential]:
+    """Every env var the project's credentials need (ApiKey, OAuth2, manual payment connectors)."""
+    out: list[MissingCredential] = []
+    for credential in project_spec.credentials:
+        if credential.authorizer_type == "ApiKeyCredentialProvider":
+            out.append(MissingCredential(credential.name, compute_default_credential_env_var_name(credential.name)))
+        elif credential.authorizer_type == "OAuthCredentialProvider":
+            client_id, client_secret = _oauth_env_names(credential.name)
+            out.append(MissingCredential(credential.name, client_id))
+            out.append(MissingCredential(credential.name, client_secret))
+
+    for payment in project_spec.payments or []:
+        for connector in payment.connectors:
+            if connector.provision_mode == "QUICK_CREATE":
+                continue
+            name = connector.credential_name
+            if connector.provider == "StripePrivy":
+                v = compute_stripe_privy_credential_env_var_names(name)
+                names = [v.app_id, v.app_secret, v.authorization_private_key, v.authorization_id]
+            else:
+                p = compute_payment_credential_env_var_names(name)
+                names = [p.api_key_id, p.api_key_secret, p.wallet_secret]
+            out.extend(MissingCredential(name, env) for env in names)
+    return out
+
+
+def assert_env_file_exists(project_spec: Any, config_base_dir: str) -> Ok[None] | Err[Exception]:
+    """Fail (listing every required var) when credentials need agentcore/.env.local and it is missing."""
+    all_credentials = get_all_credentials(project_spec)
+    if not all_credentials:
+        return ok()
+    if os.path.exists(os.path.join(config_base_dir, ".env.local")):
+        return ok()
+    var_list = "\n".join(f"  {c.env_var_name}" for c in all_credentials)
+    return Err(
+        MissingCredentialsError(
+            "agentcore/.env.local not found. Credentials require environment variables.\n\n"
+            f"Required variables:\n{var_list}\n\n"
+            "To fix: create agentcore/.env.local with the variables above, or re-run the relevant "
+            "'agentcore add' command to enter credentials interactively."
+        )
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# OAuth2 providers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def setup_o_auth2_providers(
+    *,
+    project_spec: Any,
+    config_base_dir: str,
+    region: str,
+    runtime_credentials: SecureCredentials | None = None,
+) -> PreDeployOAuth2Result:
+    all_credentials = _all_credentials(config_base_dir, runtime_credentials)
+    client = create_control_client(region)
+    results = [
+        _setup_single_oauth2_provider(client, credential, all_credentials)
+        for credential in project_spec.credentials
+        if credential.authorizer_type == "OAuthCredentialProvider"
+    ]
+    return PreDeployOAuth2Result(results=results, has_errors=any(r.status == "error" for r in results))
+
+
+setup_oauth2_providers = setup_o_auth2_providers
+
+
+def _setup_single_oauth2_provider(
+    client: Any, credential: Any, credentials: SecureCredentials
+) -> OAuth2ProviderSetupResult:
+    if credential.authorizer_type != "OAuthCredentialProvider":
+        return OAuth2ProviderSetupResult(credential.name, "error", ValidationError("Invalid credential type"))
+    id_var, secret_var = _oauth_env_names(credential.name)
+    client_id, client_secret = credentials.get(id_var), credentials.get(secret_var)
+    if not client_id or not client_secret:
+        return OAuth2ProviderSetupResult(
+            credential.name,
+            "skipped",
+            MissingCredentialsError(f"Missing {id_var} or {secret_var} in agentcore/.env.local"),
+        )
+    if not credential.discovery_url:
+        return OAuth2ProviderSetupResult(
+            credential.name,
+            "skipped",
+            MissingCredentialsError(
+                f'No discoveryUrl configured for "{credential.name}". Provider already exists in Identity '
+                "service — credentials in .env.local will be ignored."
+            ),
+        )
+    params = identity.OAuth2ProviderParams(
+        name=credential.name,
+        vendor=credential.vendor,
+        discovery_url=credential.discovery_url,
+        client_id=client_id,
+        client_secret=client_secret,
+    )
+    try:
+        if identity.oauth2_provider_exists(client, credential.name):
+            result, status = identity.update_oauth2_provider(client, params), "updated"
+        else:
+            result, status = identity.create_oauth2_provider(client, params), "created"
+        if not result.success:
+            return OAuth2ProviderSetupResult(credential.name, "error", result.error)
+        return OAuth2ProviderSetupResult(
+            credential.name,
+            status,
+            None,
+            _value(result, "credentialProviderArn"),
+            _value(result, "clientSecretArn"),
+            _value(result, "callbackUrl"),
+        )
+    except Exception as exc:  # noqa: BLE001
+        if is_no_credentials_error(exc):
+            return OAuth2ProviderSetupResult(credential.name, "error", _credentials_error(exc, typo=True))
+        return OAuth2ProviderSetupResult(credential.name, "error", exc)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Payment credential providers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def has_payment_credential_providers(project_spec: Any) -> bool:
+    return any(
+        connector.provision_mode != "QUICK_CREATE"
+        for payment in project_spec.payments or []
+        for connector in payment.connectors
+    )
+
+
+def setup_payment_credential_providers(
+    *,
+    project_spec: Any,
+    config_base_dir: str,
+    region: str,
+    runtime_credentials: SecureCredentials | None = None,
+) -> PaymentCredentialProvidersResult:
+    result = PaymentCredentialProvidersResult()
+    if not has_payment_credential_providers(project_spec):
+        return result
+    all_credentials = _all_credentials(config_base_dir, runtime_credentials)
+
+    for payment in project_spec.payments or []:
+        for connector in payment.connectors:
+            if connector.provision_mode == "QUICK_CREATE":
+                continue
+            try:
+                credential_name = connector.credential_name
+                credential = next(
+                    (
+                        c
+                        for c in project_spec.credentials
+                        if c.name == credential_name and c.authorizer_type == "PaymentCredentialProvider"
+                    ),
+                    None,
+                )
+                if credential is None:
+                    result.has_errors = True
+                    result.errors.append(
+                        ValidationError(
+                            f'Payment manager "{payment.name}" connector "{connector.name}" references credential '
+                            f'"{credential_name}" which is not a PaymentCredentialProvider'
+                        )
+                    )
+                    continue
+                arn = _create_or_update_payment_credential_provider(connector, credential, region, all_credentials)
+                result.credential_providers[credential_name] = PaymentCredentialProviderResult(arn, credential_name)
+            except Exception as exc:  # noqa: BLE001
+                result.has_errors = True
+                if is_no_credentials_error(exc):
+                    result.errors.append(_credentials_error(exc))
+                elif is_quota_exceeded_error(exc):
+                    result.errors.append(
+                        ServiceQuotaError(
+                            "Service quota exceeded. Delete unused credential providers, or request a limit "
+                            "increase via the AWS Service Quotas console."
+                        )
+                    )
+                else:
+                    result.errors.append(exc)
+    return result
+
+
+def cleanup_payment_credential_providers(*, region: str, payments: Mapping[str, Any]) -> None:
+    """Delete imperatively created payment credential providers (Quick Create ones are never touched)."""
+    for name, state in payments.items():
+        for conn_name, conn in (state.get("connectors") or {}).items():
+            arn = conn.get("credentialProviderArn")
+            if conn.get("provisionMode") == "QUICK_CREATE" or not arn:
+                continue
+            cred_name = arn.split("/")[-1]
+            if not cred_name:
+                continue
+            try:
+                agentcore_payments.delete_payment_credential_provider(region=region, name=cred_name)
+            except Exception as exc:  # noqa: BLE001
+                message = str(exc)
+                if getattr(exc, "code", None) != "ResourceNotFoundException" and "404" not in message:
+                    print(
+                        f"Failed to delete credential provider for connector '{conn_name}' (payment '{name}'): "
+                        f"{message}",
+                        file=sys.stderr,
+                    )
+
+
+def _create_or_update_payment_credential_provider(
+    connector: Any, credential: Any, region: str, credentials: SecureCredentials
+) -> str:
+    vendor = connector.provider or "CoinbaseCDP"
+    options: Any
+    if vendor == "StripePrivy":
+        names = compute_stripe_privy_credential_env_var_names(credential.name)
+        values = {
+            names.app_id: credentials.get(names.app_id),
+            names.app_secret: credentials.get(names.app_secret),
+            names.authorization_private_key: credentials.get(names.authorization_private_key),
+            names.authorization_id: credentials.get(names.authorization_id),
+        }
+        missing = [k for k, v in values.items() if not v]
+        if missing:
+            raise MissingCredentialsError(
+                f'Missing StripePrivy credentials for connector "{connector.name}" in agentcore/.env.local: '
+                f"{', '.join(missing)}"
+            )
+        options = agentcore_payments.StripePrivyCredentialProviderOptions(
+            region=region,
+            name=credential.name,
+            app_id=values[names.app_id],
+            app_secret=values[names.app_secret],
+            authorization_private_key=values[names.authorization_private_key],
+            authorization_id=values[names.authorization_id],
+        )
+    else:
+        names = compute_payment_credential_env_var_names(credential.name)
+        values = {
+            names.api_key_id: credentials.get(names.api_key_id),
+            names.api_key_secret: credentials.get(names.api_key_secret),
+            names.wallet_secret: credentials.get(names.wallet_secret),
+        }
+        missing = [k for k, v in values.items() if not v]
+        if missing:
+            raise MissingCredentialsError(
+                f'Missing CDP credentials for connector "{connector.name}" in agentcore/.env.local: '
+                f"{', '.join(missing)}"
+            )
+        options = agentcore_payments.CoinbaseCdpCredentialProviderOptions(
+            region=region,
+            name=credential.name,
+            api_key_id=values[names.api_key_id],
+            api_key_secret=values[names.api_key_secret],
+            wallet_secret=values[names.wallet_secret],
+        )
+
+    existing = agentcore_payments.get_payment_credential_provider(region=region, name=credential.name)
+    if existing:
+        return agentcore_payments.update_payment_credential_provider(options)["credentialProviderArn"]
+    return agentcore_payments.create_payment_credential_provider(options)["credentialProviderArn"]
+
+
+__all__ = [
+    "ApiKeyProviderSetupResult",
+    "MissingCredential",
+    "OAuth2ProviderSetupResult",
+    "PaymentCredentialProviderResult",
+    "PaymentCredentialProvidersResult",
+    "PreDeployIdentityResult",
+    "PreDeployOAuth2Result",
+    "assert_env_file_exists",
+    "cleanup_payment_credential_providers",
+    "get_all_credentials",
+    "get_missing_credentials",
+    "has_identity_api_providers",
+    "has_identity_o_auth_providers",
+    "has_identity_oauth_providers",
+    "has_payment_credential_providers",
+    "setup_api_key_providers",
+    "setup_o_auth2_providers",
+    "setup_oauth2_providers",
+    "setup_payment_credential_providers",
+]