agentcore-cli 0.31.1__py3-none-any.whl

agentcore/schema/schemas/auth.py

@@ -0,0 +1,286 @@
+"""Shared inbound authorization schemas for gateways and runtimes (port of ``schemas/auth.ts``)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import model_validator
+
+from .._zod import Issue, StrictModel, ZodModel, array_checks, js_regex, raise_issues, zstr
+from ..constants import SECURITY_GROUP_ID_PATTERN, SUBNET_ID_PATTERN, VPC_ID_PATTERN
+from .primitives.tags import Tags
+
+GatewayAuthorizerType = Literal["NONE", "AWS_IAM", "CUSTOM_JWT"]
+GATEWAY_AUTHORIZER_TYPES: Final[tuple[GatewayAuthorizerType, ...]] = get_args(GatewayAuthorizerType)
+
+RuntimeAuthorizerType = Literal["AWS_IAM", "CUSTOM_JWT"]
+RUNTIME_AUTHORIZER_TYPES: Final[tuple[RuntimeAuthorizerType, ...]] = get_args(RuntimeAuthorizerType)
+
+# OIDC well-known configuration endpoint suffix (OpenID Connect Discovery 1.0).
+_OIDC_WELL_KNOWN_SUFFIX = "/.well-known/openid-configuration"
+
+OidcDiscoveryUrl = zstr(
+    url=True,
+    url_msg="Must be a valid URL",
+    refines=(
+        (lambda u: u.startswith("https://"), "OIDC discovery URL must use HTTPS"),
+        (
+            lambda u: u.endswith(_OIDC_WELL_KNOWN_SUFFIX),
+            f"OIDC discovery URL must end with '{_OIDC_WELL_KNOWN_SUFFIX}'",
+        ),
+    ),
+)
+
+# ── Custom Claims (matches CFN CustomClaimValidationType) ──
+
+_MATCH_VALUE_PATTERN = js_regex(r"^[A-Za-z0-9_.-]+$")
+# OAuth scope token: printable ASCII excluding space (0x20) and double-quote (0x22).
+_ALLOWED_SCOPE_PATTERN = js_regex(r"^[\x21\x23-\x5B\x5D-\x7E]+$")
+_CLAIM_NAME_PATTERN = js_regex(r"^[A-Za-z0-9_.:-]+$")
+# Server-side reserved claim names (API rejects these at deploy time).
+_RESERVED_CLAIM_NAMES: Final = ("client_id",)
+
+ClaimMatchOperator = Literal["EQUALS", "CONTAINS", "CONTAINS_ANY"]
+CLAIM_MATCH_OPERATORS: Final[tuple[ClaimMatchOperator, ...]] = get_args(ClaimMatchOperator)
+
+
+class ClaimMatchValue(ZodModel):
+    match_value_string: (
+        zstr(min=1, max=255, pattern=_MATCH_VALUE_PATTERN, pattern_msg="Match value must match [A-Za-z0-9_.-]+") | None
+    ) = None
+    match_value_string_list: (
+        Annotated[
+            list[
+                zstr(
+                    min=1,
+                    max=255,
+                    pattern=_MATCH_VALUE_PATTERN,
+                    pattern_msg="Each match value must match [A-Za-z0-9_.-]+",
+                )
+            ],
+            array_checks(min=1, max=255),
+        ]
+        | None
+    ) = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> ClaimMatchValue:
+        has_one = self.match_value_string is not None
+        has_list = self.match_value_string_list is not None
+        issues: list[Issue] = []
+        if not (has_one or has_list):
+            issues.append(((), "Either matchValueString or matchValueStringList must be provided"))
+        if has_one and has_list:
+            issues.append(((), "Only one of matchValueString or matchValueStringList may be provided"))
+        raise_issues(issues, self)
+        return self
+
+
+InboundTokenClaimValueType = Literal["STRING", "STRING_ARRAY"]
+INBOUND_TOKEN_CLAIM_VALUE_TYPES: Final[tuple[InboundTokenClaimValueType, ...]] = get_args(InboundTokenClaimValueType)
+
+
+class AuthorizingClaimMatchValue(ZodModel):
+    claim_match_operator: ClaimMatchOperator
+    claim_match_value: ClaimMatchValue
+
+
+class CustomClaimValidation(StrictModel):
+    inbound_token_claim_name: zstr(
+        min=1,
+        max=255,
+        pattern=_CLAIM_NAME_PATTERN,
+        pattern_msg="Claim name must match [A-Za-z0-9_.-:]+",
+        refines=(
+            (
+                lambda n: n not in _RESERVED_CLAIM_NAMES,
+                f"Claim name cannot be a reserved name ({', '.join(_RESERVED_CLAIM_NAMES)})",
+            ),
+        ),
+    )
+    inbound_token_claim_value_type: InboundTokenClaimValueType
+    authorizing_claim_match_value: AuthorizingClaimMatchValue
+
+
+# ── PrivateLink inbound: private endpoint for reaching the OIDC discovery URL ──
+
+# VPC Lattice resource-config id, or its full ARN.
+LATTICE_RESOURCE_CONFIG_PATTERN: Final = js_regex(
+    r"^((rcfg-[0-9a-z]{17})|(arn:[a-z0-9-]+:vpc-lattice:[a-zA-Z0-9-]+:\d{12}:resourceconfiguration\/rcfg-[0-9a-z]{17}))$"
+)
+
+EndpointIpAddressType = Literal["IPV4", "IPV6"]
+ENDPOINT_IP_ADDRESS_TYPES: Final[tuple[EndpointIpAddressType, ...]] = get_args(EndpointIpAddressType)
+
+
+class SelfManagedLatticeResource(StrictModel):
+    """Reach the discovery endpoint via a self-managed VPC Lattice resource configuration."""
+
+    resource_configuration_identifier: zstr(
+        min=20,
+        max=2048,
+        pattern=LATTICE_RESOURCE_CONFIG_PATTERN,
+        pattern_msg="Must be a VPC Lattice resource-config id (rcfg-...) or its ARN",
+    )
+
+
+class ManagedVpcResource(StrictModel):
+    """Reach the discovery endpoint via a service-managed VPC interface endpoint."""
+
+    vpc_identifier: zstr(pattern=VPC_ID_PATTERN, pattern_msg="Must be a VPC id (vpc-...)")
+    subnet_ids: Annotated[
+        list[zstr(pattern=SUBNET_ID_PATTERN, pattern_msg="Must be a subnet id (subnet-...)")], array_checks(min=1)
+    ]
+    endpoint_ip_address_type: EndpointIpAddressType
+    security_group_ids: (
+        Annotated[
+            list[zstr(pattern=SECURITY_GROUP_ID_PATTERN, pattern_msg="Must be a security group id (sg-...)")],
+            array_checks(max=5),
+        ]
+        | None
+    ) = None
+    tags: Tags | None = None
+    routing_domain: zstr(min=3, max=255) | None = None
+
+
+class PrivateEndpoint(StrictModel):
+    """Exactly one of selfManagedLatticeResource or managedVpcResource."""
+
+    self_managed_lattice_resource: SelfManagedLatticeResource | None = None
+    managed_vpc_resource: ManagedVpcResource | None = None
+
+    @model_validator(mode="after")
+    def _exactly_one(self) -> PrivateEndpoint:
+        count = sum(v is not None for v in (self.self_managed_lattice_resource, self.managed_vpc_resource))
+        if count != 1:
+            raise_issues(
+                [((), "A private endpoint must set exactly one of selfManagedLatticeResource or managedVpcResource")],
+                self,
+            )
+        return self
+
+
+class PrivateEndpointOverride(StrictModel):
+    """Maps a specific domain to its own private endpoint."""
+
+    domain: zstr(min=1, max=253)
+    private_endpoint: PrivateEndpoint
+
+
+PrivateEndpointArm = Literal["selfManagedLatticeResource", "managedVpcResource"]
+
+
+def private_endpoint_arm(pe: PrivateEndpoint) -> PrivateEndpointArm | None:
+    if pe.self_managed_lattice_resource is not None:
+        return "selfManagedLatticeResource"
+    if pe.managed_vpc_resource is not None:
+        return "managedVpcResource"
+    return None
+
+
+# ── Custom JWT Authorizer Configuration ──
+
+
+class CustomJwtAuthorizerConfig(StrictModel):
+    """Custom JWT authorizer (authorizerType CUSTOM_JWT).
+
+    At least one of allowedAudience, allowedClients, allowedScopes, or customClaims is required.
+    """
+
+    discovery_url: OidcDiscoveryUrl
+    allowed_audience: list[zstr(min=1)] | None = None
+    allowed_clients: list[zstr(min=1)] | None = None
+    allowed_scopes: (
+        list[
+            zstr(
+                min=1,
+                max=255,
+                pattern=_ALLOWED_SCOPE_PATTERN,
+                pattern_msg="Scope must be printable ASCII with no spaces or quotes",
+            )
+        ]
+        | None
+    ) = None
+    custom_claims: Annotated[list[CustomClaimValidation], array_checks(min=1)] | None = None
+    private_endpoint: PrivateEndpoint | None = None
+    private_endpoint_overrides: Annotated[list[PrivateEndpointOverride], array_checks(max=5)] | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> CustomJwtAuthorizerConfig:
+        issues: list[Issue] = []
+        if not (self.allowed_audience or self.allowed_clients or self.allowed_scopes or self.custom_claims):
+            issues.append(
+                ((), "At least one of allowedAudience, allowedClients, allowedScopes, or customClaims must be provided")
+            )
+        # Mirror the AgentCore Identity service's deploy-time coupling rules for overrides.
+        overrides = self.private_endpoint_overrides or []
+        if overrides:
+            if self.private_endpoint is None:
+                issues.append(
+                    (
+                        ("privateEndpointOverrides",),
+                        "privateEndpointOverrides can only be used when privateEndpoint is also set",
+                    )
+                )
+            else:
+                base_arm = private_endpoint_arm(self.private_endpoint)
+                for i, o in enumerate(overrides):
+                    if private_endpoint_arm(o.private_endpoint) != base_arm:
+                        issues.append(
+                            (
+                                ("privateEndpointOverrides", i, "privateEndpoint"),
+                                (
+                                    "privateEndpoint and privateEndpointOverrides must all be the same kind — either all "
+                                    "selfManagedLatticeResource or all managedVpcResource"
+                                ),
+                            )
+                        )
+            seen: set[str] = set()
+            for i, o in enumerate(overrides):
+                if o.domain in seen:
+                    issues.append(
+                        (
+                            ("privateEndpointOverrides", i, "domain"),
+                            f"Duplicate privateEndpointOverride domain: {o.domain}",
+                        )
+                    )
+                seen.add(o.domain)
+        raise_issues(issues, self)
+        return self
+
+
+class AuthorizerConfig(ZodModel):
+    """Resource-agnostic authorizer configuration container (Gateway and Runtime)."""
+
+    custom_jwt_authorizer: CustomJwtAuthorizerConfig | None = None
+
+
+# Deprecated: use AuthorizerConfig. Backwards-compatible alias for Gateway.
+GatewayAuthorizerConfig = AuthorizerConfig
+
+__all__ = [
+    "CLAIM_MATCH_OPERATORS",
+    "ENDPOINT_IP_ADDRESS_TYPES",
+    "GATEWAY_AUTHORIZER_TYPES",
+    "INBOUND_TOKEN_CLAIM_VALUE_TYPES",
+    "LATTICE_RESOURCE_CONFIG_PATTERN",
+    "RUNTIME_AUTHORIZER_TYPES",
+    "AuthorizerConfig",
+    "AuthorizingClaimMatchValue",
+    "ClaimMatchOperator",
+    "ClaimMatchValue",
+    "CustomClaimValidation",
+    "CustomJwtAuthorizerConfig",
+    "EndpointIpAddressType",
+    "GatewayAuthorizerConfig",
+    "GatewayAuthorizerType",
+    "InboundTokenClaimValueType",
+    "ManagedVpcResource",
+    "OidcDiscoveryUrl",
+    "PrivateEndpoint",
+    "PrivateEndpointArm",
+    "PrivateEndpointOverride",
+    "RuntimeAuthorizerType",
+    "SelfManagedLatticeResource",
+    "private_endpoint_arm",
+]

agentcore/schema/schemas/aws_targets.py

@@ -0,0 +1,72 @@
+"""Deployment targets, i.e. aws-targets.json (port of ``schemas/aws-targets.ts``)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import TypeAdapter
+
+from .._zod import ZodModel, array_checks, unique_by, zstr
+
+# Keep in sync with https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html
+AgentCoreRegion = Literal[
+    "ap-northeast-1",
+    "ap-northeast-2",
+    "ap-south-1",
+    "ap-south-2",
+    "ap-southeast-1",
+    "ap-southeast-2",
+    "ap-southeast-5",
+    "ap-southeast-7",
+    "ca-central-1",
+    "eu-central-1",
+    "eu-north-1",
+    "eu-south-1",
+    "eu-south-2",
+    "eu-west-1",
+    "eu-west-2",
+    "eu-west-3",
+    "sa-east-1",
+    "us-east-1",
+    "us-east-2",
+    "us-west-1",
+    "us-west-2",
+    "us-gov-west-1",
+]
+AGENTCORE_REGIONS: Final[tuple[AgentCoreRegion, ...]] = get_args(AgentCoreRegion)
+
+# Unique identifier for the deployment target.
+DeploymentTargetName = zstr(
+    min=1,
+    max=64,
+    pattern=r"^[a-zA-Z][a-zA-Z0-9-]*$",
+    pattern_msg="Name must start with a letter and contain only alphanumeric characters and hyphens",
+)
+
+AwsAccountId = zstr(pattern=r"^[0-9]{12}$", pattern_msg="AWS account ID must be exactly 12 digits")
+
+
+class AwsDeploymentTarget(ZodModel):
+    name: DeploymentTargetName
+    description: zstr(max=256) | None = None
+    account: AwsAccountId
+    region: AgentCoreRegion
+
+
+AwsDeploymentTargets = Annotated[
+    list[AwsDeploymentTarget],
+    array_checks(extra=[unique_by(lambda t: t.name, lambda n: f"Duplicate deployment target name: {n}")]),
+]
+
+# Validates/dumps a whole aws-targets.json array.
+AwsDeploymentTargetsAdapter: Final = TypeAdapter(AwsDeploymentTargets)
+
+__all__ = [
+    "AGENTCORE_REGIONS",
+    "AgentCoreRegion",
+    "AwsAccountId",
+    "AwsDeploymentTarget",
+    "AwsDeploymentTargets",
+    "AwsDeploymentTargetsAdapter",
+    "DeploymentTargetName",
+]

agentcore/schema/schemas/connections.py

@@ -0,0 +1,187 @@
+"""Connections from a principal to EXTERNAL AgentCore resources (port of ``schemas/connections.ts``).
+
+A connection declares that an agent runtime or harness accesses a memory/gateway/runtime/browser/
+code-interpreter that is not part of this project; the construct generates least-privilege IAM and
+injects discovery env vars. Connections are embedded on the source resource (no ``from`` field).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import Field
+
+from .._zod import StrictModel, ZBool, js_regex, zstr
+
+# OAuth grant type for an external gateway (maps to AgentCore Identity auth flows).
+GatewayGrantType = Literal["CLIENT_CREDENTIALS", "AUTHORIZATION_CODE", "TOKEN_EXCHANGE"]
+GATEWAY_GRANT_TYPES: Final[tuple[GatewayGrantType, ...]] = get_args(GatewayGrantType)
+
+
+class StrictEmptyObject(StrictModel):
+    """``z.object({}).strict()``"""
+
+
+class GatewayOAuthOutboundAuthConfig(StrictModel):
+    provider_arn: zstr(min=1)
+    scopes: list[zstr(min=1)]
+    grant_type: GatewayGrantType | None = None
+    custom_parameters: dict[str, str] | None = None
+
+
+class AwsIamGatewayOutboundAuth(StrictModel):
+    aws_iam: StrictEmptyObject
+
+
+class NoneGatewayOutboundAuth(StrictModel):
+    none: StrictEmptyObject
+
+
+class OAuthGatewayOutboundAuth(StrictModel):
+    oauth: GatewayOAuthOutboundAuthConfig
+
+
+# Outbound auth a caller uses to reach an external gateway (awsIam | none | oauth).
+GatewayOutboundAuth = Annotated[
+    AwsIamGatewayOutboundAuth | NoneGatewayOutboundAuth | OAuthGatewayOutboundAuth,
+    Field(union_mode="left_to_right"),
+]
+
+# ---- Connection targets (partition-agnostic ARN prefix) ----
+
+_MEMORY_ARN_PATTERN = js_regex(r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:memory\/.+$")
+_GATEWAY_ARN_PATTERN = js_regex(r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:gateway\/.+$")
+_RUNTIME_ARN_PATTERN = js_regex(r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:runtime\/.+$")
+# Customer-owned `<kind>-custom/<id>` (12-digit account) or AWS-managed `<kind>/<id>` (`aws` account).
+BROWSER_ARN_PATTERN: Final = js_regex(r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:(\d{12}|aws):browser(-custom)?\/.+$")
+CODE_INTERPRETER_ARN_PATTERN: Final = js_regex(
+    r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:(\d{12}|aws):code-interpreter(-custom)?\/.+$"
+)
+
+
+class MemoryConnectionTarget(StrictModel):
+    type: Literal["memory"]
+    arn: zstr(pattern=_MEMORY_ARN_PATTERN, pattern_msg="Must be a valid bedrock-agentcore memory ARN")
+    # Namespace templates scoping List/RetrieveMemoryRecords via namespace condition keys.
+    namespaces: list[zstr(min=1)] | None = None
+
+
+class GatewayConnectionTarget(StrictModel):
+    type: Literal["gateway"]
+    arn: zstr(pattern=_GATEWAY_ARN_PATTERN, pattern_msg="Must be a valid bedrock-agentcore gateway ARN")
+    # Defaults to awsIam (SigV4) downstream when omitted.
+    outbound_auth: GatewayOutboundAuth | None = None
+
+
+class RuntimeConnectionTarget(StrictModel):
+    type: Literal["runtime"]
+    arn: zstr(pattern=_RUNTIME_ARN_PATTERN, pattern_msg="Must be a valid bedrock-agentcore runtime ARN")
+    # Also grant InvokeAgentRuntimeCommand (container exec) in addition to invoke.
+    exec: ZBool | None = None
+
+
+class BrowserConnectionTarget(StrictModel):
+    type: Literal["browser"]
+    # Omit to use the AWS-managed default browser.
+    arn: zstr(pattern=BROWSER_ARN_PATTERN, pattern_msg="Must be a valid bedrock-agentcore browser ARN") | None = None
+
+
+class CodeInterpreterConnectionTarget(StrictModel):
+    type: Literal["codeInterpreter"]
+    # Omit to use the AWS-managed default.
+    arn: (
+        zstr(pattern=CODE_INTERPRETER_ARN_PATTERN, pattern_msg="Must be a valid bedrock-agentcore code-interpreter ARN")
+        | None
+    ) = None
+
+
+ConnectionTarget = Annotated[
+    MemoryConnectionTarget
+    | GatewayConnectionTarget
+    | RuntimeConnectionTarget
+    | BrowserConnectionTarget
+    | CodeInterpreterConnectionTarget,
+    Field(discriminator="type"),
+]
+
+ConnectionAccess = Literal["read", "readwrite"]
+
+
+class Connection(StrictModel):
+    """A connection from the enclosing principal to an external resource.
+
+    ``access`` is meaningful only for memory (read | readwrite); defaults to read downstream.
+    """
+
+    id: (
+        zstr(
+            pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+            pattern_msg="Connection id must match [a-zA-Z][a-zA-Z0-9_-]{0,63}",
+        )
+        | None
+    ) = None
+    to: ConnectionTarget
+    access: ConnectionAccess | None = None
+    description: zstr(max=200) | None = None
+
+
+Connections = list[Connection]
+
+# ============================================================================
+# Connection discovery env-var naming — SINGLE SOURCE OF TRUTH shared with @aws/agentcore-cdk.
+# ============================================================================
+
+CONNECTION_ID_MAX_LENGTH: Final = 64
+
+
+def resource_id_from_arn(arn: str) -> str:
+    """Last segment of an ARN (the resource id): ``memory/mem-123`` -> ``mem-123``."""
+    after_colon = arn.split(":")[-1]
+    slash = after_colon.rfind("/")
+    return after_colon[slash + 1 :] if slash >= 0 else after_colon
+
+
+def connection_id_for_target(target: ConnectionTarget) -> str:
+    """Stable ``<kind>-<resourceId>`` id for a target, sanitized to the connection-id charset/length."""
+    arn = getattr(target, "arn", None)
+    suffix = resource_id_from_arn(arn) if arn else target.type
+    return re.sub(r"[^a-zA-Z0-9_-]", "-", f"{target.type}-{suffix}")[:CONNECTION_ID_MAX_LENGTH]
+
+
+def connection_env_token(id: str) -> str:
+    """Uppercase, underscore-safe token for env-var naming, derived from a connection id."""
+    return re.sub(r"[^A-Z0-9]", "_", id.upper())
+
+
+def connection_token_for(connection: Connection) -> str:
+    """Env-var token for a connection: explicit ``id`` or the derived ``<kind>-<resourceId>`` id."""
+    return connection_env_token(connection.id if connection.id is not None else connection_id_for_target(connection.to))
+
+
+__all__ = [
+    "BROWSER_ARN_PATTERN",
+    "CODE_INTERPRETER_ARN_PATTERN",
+    "CONNECTION_ID_MAX_LENGTH",
+    "GATEWAY_GRANT_TYPES",
+    "AwsIamGatewayOutboundAuth",
+    "BrowserConnectionTarget",
+    "CodeInterpreterConnectionTarget",
+    "Connection",
+    "ConnectionAccess",
+    "ConnectionTarget",
+    "Connections",
+    "GatewayConnectionTarget",
+    "GatewayGrantType",
+    "GatewayOAuthOutboundAuthConfig",
+    "GatewayOutboundAuth",
+    "MemoryConnectionTarget",
+    "NoneGatewayOutboundAuth",
+    "OAuthGatewayOutboundAuth",
+    "RuntimeConnectionTarget",
+    "StrictEmptyObject",
+    "connection_env_token",
+    "connection_id_for_target",
+    "connection_token_for",
+    "resource_id_from_arn",
+]