exchange-keyshare 0.1.0__py3-none-any.whl

exchange_keyshare/config.py

@@ -0,0 +1,86 @@
+"""Configuration file handling for exchange-keyshare."""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _default_config_path() -> Path:
+    """Get default config path, respecting EXCHANGE_KEYSHARE_CONFIG env var."""
+    env_path = os.environ.get("EXCHANGE_KEYSHARE_CONFIG")
+    if env_path:
+        return Path(env_path)
+
+    home = Path.home()
+    return home / ".config" / "exchange-keyshare" / "config.yaml"
+
+
+@dataclass
+class Config:
+    """Configuration container."""
+
+    config_path: Path = field(default_factory=_default_config_path)
+    bucket: str | None = None
+    region: str | None = None
+    stack_name: str | None = None
+    role_arn: str | None = None
+    external_id: str | None = None
+    kms_key_arn: str | None = None
+
+    def load(self) -> None:
+        """Load config from file."""
+        data = load_config(self.config_path)
+        self.bucket = data.get("bucket")
+        self.region = data.get("region")
+        self.stack_name = data.get("stack_name")
+        self.role_arn = data.get("role_arn")
+        self.external_id = data.get("external_id")
+        self.kms_key_arn = data.get("kms_key_arn")
+
+    def save(self) -> None:
+        """Save config to file."""
+        data: dict[str, Any] = {}
+        if self.bucket:
+            data["bucket"] = self.bucket
+        if self.region:
+            data["region"] = self.region
+        if self.stack_name:
+            data["stack_name"] = self.stack_name
+        if self.role_arn:
+            data["role_arn"] = self.role_arn
+        if self.external_id:
+            data["external_id"] = self.external_id
+        if self.kms_key_arn:
+            data["kms_key_arn"] = self.kms_key_arn
+        save_config(self.config_path, data)
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    """Load config from YAML file. Returns empty dict if file doesn't exist."""
+    if not path.exists():
+        return {}
+
+    with open(path) as f:
+        data = yaml.safe_load(f)
+        return data if data else {}
+
+
+def save_config(path: Path, data: dict[str, Any]) -> None:
+    """Save config to YAML file. Creates parent directories if needed.
+
+    Config file is created with 0600 permissions (owner read/write only)
+    since it may contain sensitive data like external_id.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create with restrictive permissions (owner read/write only)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w") as f:
+            yaml.dump(data, f, default_flow_style=False)
+    except Exception:
+        os.close(fd)
+        raise

exchange_keyshare/keys.py

@@ -0,0 +1,106 @@
+"""Key management operations."""
+
+from __future__ import annotations
+
+import secrets
+import string
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+import boto3
+import yaml
+
+if TYPE_CHECKING:
+    from mypy_boto3_s3 import S3Client
+
+from exchange_keyshare.schema import CredentialSchema, validate_credential
+
+
+def generate_s3_key(exchange: str) -> str:
+    """Generate a unique S3 key for a credential."""
+    chars = string.ascii_lowercase + string.digits
+    suffix = "".join(secrets.choice(chars) for _ in range(12))
+    return f"exchange-credentials/{exchange}-{suffix}.yaml"
+
+
+def parse_credential_from_yaml(content: str) -> CredentialSchema:
+    """Parse and validate credential from YAML string."""
+    data = yaml.safe_load(content)
+    return validate_credential(data)
+
+
+@dataclass
+class CredentialInfo:
+    """Info about a stored credential (for listing)."""
+
+    key: str
+    exchange: str
+    pairs: list[str] | None
+    labels: list[dict[str, str]] | None
+
+
+def list_credentials(bucket: str, region: str) -> list[CredentialInfo]:
+    """List all credentials in the bucket."""
+    s3 = cast("S3Client", boto3.client("s3", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+
+    result: list[CredentialInfo] = []
+
+    paginator = s3.get_paginator("list_objects_v2")
+    for page in paginator.paginate(Bucket=bucket, Prefix="exchange-credentials/"):
+        for obj in page.get("Contents", []):
+            key = obj.get("Key")
+            if not key or not key.endswith(".yaml"):
+                continue
+
+            response = s3.get_object(Bucket=bucket, Key=key)
+            content = response["Body"].read().decode("utf-8")
+            cred = parse_credential_from_yaml(content)
+            result.append(CredentialInfo(
+                key=key,
+                exchange=cred.exchange,
+                pairs=cred.pairs,
+                labels=cred.labels,
+            ))
+
+    return result
+
+
+def upload_credential(
+    bucket: str,
+    region: str,
+    credential: CredentialSchema,
+    kms_key_arn: str,
+    s3_key: str | None = None,
+) -> str:
+    """Upload credential to S3. Returns the S3 key used."""
+    s3 = cast("S3Client", boto3.client("s3", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+
+    key = s3_key or generate_s3_key(credential.exchange)
+    content = yaml.dump(credential.to_dict(), default_flow_style=False)
+
+    s3.put_object(
+        Bucket=bucket,
+        Key=key,
+        Body=content.encode("utf-8"),
+        ContentType="application/x-yaml",
+        ServerSideEncryption="aws:kms",
+        SSEKMSKeyId=kms_key_arn,
+    )
+
+    return key
+
+
+def get_credential(bucket: str, region: str, key: str) -> CredentialSchema:
+    """Get a credential from S3."""
+    s3 = cast("S3Client", boto3.client("s3", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+
+    response = s3.get_object(Bucket=bucket, Key=key)
+    content = response["Body"].read().decode("utf-8")
+
+    return parse_credential_from_yaml(content)
+
+
+def delete_credential(bucket: str, region: str, key: str) -> None:
+    """Delete a credential from S3."""
+    s3 = cast("S3Client", boto3.client("s3", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+    s3.delete_object(Bucket=bucket, Key=key)

exchange_keyshare/schema.py

@@ -0,0 +1,117 @@
+"""Credential schema validation."""
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+
+SUPPORTED_EXCHANGES = frozenset({
+    "binance",
+    "coinbase",
+    "kraken",
+    "kucoin",
+    "bitget",
+})
+
+PASSPHRASE_REQUIRED_EXCHANGES = frozenset({
+    "coinbase",
+    "kucoin",
+    "bitget",
+})
+
+
+class SchemaError(Exception):
+    """Raised when credential schema validation fails."""
+    pass
+
+
+@dataclass
+class CredentialSchema:
+    """Validated credential data."""
+
+    version: str
+    exchange: str
+    credential: dict[str, str]
+    pairs: list[str] | None = None
+    labels: list[dict[str, str]] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for YAML serialization."""
+        data: dict[str, Any] = {
+            "version": self.version,
+            "exchange": self.exchange,
+            "credential": self.credential,
+        }
+        if self.pairs is not None:
+            data["pairs"] = self.pairs
+        if self.labels is not None:
+            data["labels"] = self.labels
+        return data
+
+
+def validate_credential(data: dict[str, Any]) -> CredentialSchema:
+    """Validate credential data and return structured result.
+
+    Raises:
+        SchemaError: If validation fails.
+    """
+    # Check required top-level fields
+    if "version" not in data:
+        raise SchemaError("missing required field: version")
+    if "exchange" not in data:
+        raise SchemaError("missing required field: exchange")
+    if "credential" not in data:
+        raise SchemaError("missing required field: credential")
+
+    exchange = data["exchange"]
+    if exchange not in SUPPORTED_EXCHANGES:
+        raise SchemaError(f"unsupported exchange: {exchange}")
+
+    credential_raw = data["credential"]
+    if not isinstance(credential_raw, dict):
+        raise SchemaError("credential must be a mapping")
+    credential = cast(dict[str, str], credential_raw)
+    if "api_key" not in credential:
+        raise SchemaError("missing required field: credential.api_key")
+    api_key = credential["api_key"]
+    if not api_key or not api_key.strip():
+        raise SchemaError("credential.api_key cannot be empty")
+    if "api_secret" not in credential:
+        raise SchemaError("missing required field: credential.api_secret")
+    api_secret = credential["api_secret"]
+    if not api_secret or not api_secret.strip():
+        raise SchemaError("credential.api_secret cannot be empty")
+
+    # Check passphrase requirement for certain exchanges
+    if exchange in PASSPHRASE_REQUIRED_EXCHANGES:
+        if "passphrase" not in credential or not credential["passphrase"]:
+            raise SchemaError(f"passphrase required for {exchange}")
+
+    # Validate optional pairs field
+    pairs: list[str] | None = None
+    pairs_raw = data.get("pairs")
+    if pairs_raw is not None:
+        if not isinstance(pairs_raw, list):
+            raise SchemaError("pairs must be a list")
+        for pair in cast(list[Any], pairs_raw):
+            if not isinstance(pair, str):
+                raise SchemaError("each pair must be a string")
+        pairs = cast(list[str], pairs_raw)
+
+    # Validate optional labels field
+    labels: list[dict[str, str]] | None = None
+    labels_raw = data.get("labels")
+    if labels_raw is not None:
+        if not isinstance(labels_raw, list):
+            raise SchemaError("labels must be a list")
+        for label in cast(list[Any], labels_raw):
+            if not isinstance(label, dict) or "key" not in label or "value" not in label:
+                raise SchemaError("label must have 'key' and 'value'")
+        labels = cast(list[dict[str, str]], labels_raw)
+
+    return CredentialSchema(
+        version=str(data["version"]),
+        exchange=str(exchange),
+        credential=credential,
+        pairs=pairs,
+        labels=labels,
+    )

exchange_keyshare/setup.py

@@ -0,0 +1,263 @@
+"""Setup command logic for creating AWS infrastructure."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import string
+import time
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+import boto3
+from botocore.exceptions import ClientError
+
+if TYPE_CHECKING:
+    from mypy_boto3_cloudformation import CloudFormationClient
+
+from exchange_keyshare.cfn import load_template
+
+
+def generate_bucket_name() -> str:
+    """Generate a unique S3 bucket name."""
+    chars = string.ascii_lowercase + string.digits
+    suffix = "".join(secrets.choice(chars) for _ in range(12))
+    return f"exchange-keyshare-{suffix}"
+
+
+def get_default_region() -> str:
+    """Get default AWS region from env or fallback."""
+    return os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION", "us-east-1"))
+
+
+@dataclass
+class SetupResult:
+    """Result of setup operation."""
+
+    bucket: str
+    region: str
+    role_arn: str
+    external_id: str
+    stack_name: str
+    kms_key_arn: str
+
+
+@dataclass
+class ResourceStatus:
+    """Status of a CloudFormation resource."""
+
+    logical_id: str
+    resource_type: str
+    status: str
+    reason: str | None = None
+
+
+@dataclass
+class StackProgress:
+    """Progress update for stack creation."""
+
+    resources: dict[str, ResourceStatus]
+    stack_status: str
+    is_complete: bool
+    is_failed: bool
+    failure_reason: str | None = None
+
+
+# Friendly names for CloudFormation resource types
+RESOURCE_TYPE_NAMES: dict[str, str] = {
+    "AWS::S3::Bucket": "S3 Bucket",
+    "AWS::S3::BucketPolicy": "Bucket Policy",
+    "AWS::KMS::Key": "KMS Key",
+    "AWS::KMS::Alias": "KMS Alias",
+    "AWS::IAM::Role": "IAM Role",
+}
+
+
+def get_friendly_type(resource_type: str) -> str:
+    """Get a friendly name for a resource type."""
+    return RESOURCE_TYPE_NAMES.get(resource_type, resource_type)
+
+
+def start_stack_creation(
+    external_id: str,
+    principal_arn: str,
+    bucket_name: str | None = None,
+    region: str | None = None,
+) -> tuple[str, str, CloudFormationClient]:
+    """Start CloudFormation stack creation. Returns (stack_name, region, cfn_client)."""
+    bucket = bucket_name or generate_bucket_name()
+    region = region or get_default_region()
+    stack_name = bucket  # Bucket name already has unique suffix
+
+    cfn = cast("CloudFormationClient", boto3.client("cloudformation", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+    template = load_template()
+
+    try:
+        cfn.create_stack(
+            StackName=stack_name,
+            TemplateBody=template,
+            Parameters=[
+                {"ParameterKey": "BucketName", "ParameterValue": bucket},
+                {"ParameterKey": "ConsumerPrincipalArn", "ParameterValue": principal_arn},
+                {"ParameterKey": "ExternalId", "ParameterValue": external_id},
+            ],
+            Capabilities=["CAPABILITY_NAMED_IAM"],
+            OnFailure="DELETE",
+        )
+    except ClientError as e:
+        if "AlreadyExistsException" in str(e):
+            raise Exception(f"Stack {stack_name} already exists") from e
+        raise
+
+    return stack_name, region, cfn
+
+
+def poll_stack_progress(
+    stack_name: str,
+    cfn: CloudFormationClient,
+    poll_interval: float = 2.0,
+    max_attempts: int = 300,
+) -> Generator[StackProgress, None, None]:
+    """Poll stack creation progress and yield updates."""
+    resources: dict[str, ResourceStatus] = {}
+
+    for _ in range(max_attempts):
+        # Get current stack status
+        try:
+            stacks_response = cfn.describe_stacks(StackName=stack_name)
+        except ClientError:
+            # Stack might be deleted on failure
+            yield StackProgress(
+                resources=resources,
+                stack_status="DELETE_IN_PROGRESS",
+                is_complete=False,
+                is_failed=True,
+                failure_reason="Stack creation failed and is being deleted",
+            )
+            return
+
+        stack = stacks_response["Stacks"][0]
+        stack_status = stack.get("StackStatus", "UNKNOWN")
+
+        # Get resource events
+        events_response = cfn.describe_stack_events(StackName=stack_name)
+        for event in events_response["StackEvents"]:
+            logical_id = event.get("LogicalResourceId", "")
+            resource_type = event.get("ResourceType", "")
+            status = event.get("ResourceStatus", "")
+            reason = event.get("ResourceStatusReason")
+
+            # Skip the stack itself
+            if resource_type == "AWS::CloudFormation::Stack":
+                continue
+
+            # Update if this is a newer status for this resource
+            if logical_id not in resources or _is_newer_status(status, resources[logical_id].status):
+                resources[logical_id] = ResourceStatus(
+                    logical_id=logical_id,
+                    resource_type=resource_type,
+                    status=status,
+                    reason=reason,
+                )
+
+        # Check for completion
+        is_complete = stack_status == "CREATE_COMPLETE"
+        is_failed = stack_status in ("CREATE_FAILED", "ROLLBACK_COMPLETE", "ROLLBACK_IN_PROGRESS", "DELETE_IN_PROGRESS")
+
+        failure_reason: str | None = None
+        if is_failed:
+            # Find failure reasons
+            failed_resources = [r for r in resources.values() if "FAILED" in r.status]
+            if failed_resources:
+                reasons = [r.reason for r in failed_resources if r.reason]
+                failure_reason = "; ".join(reasons[:3]) if reasons else "Unknown error"
+
+        yield StackProgress(
+            resources=resources,
+            stack_status=stack_status,
+            is_complete=is_complete,
+            is_failed=is_failed,
+            failure_reason=failure_reason,
+        )
+
+        if is_complete or is_failed:
+            return
+
+        time.sleep(poll_interval)
+
+    # Timeout
+    yield StackProgress(
+        resources=resources,
+        stack_status="TIMEOUT",
+        is_complete=False,
+        is_failed=True,
+        failure_reason="Stack creation timed out",
+    )
+
+
+def _is_newer_status(new_status: str, old_status: str) -> bool:
+    """Check if new_status is more recent than old_status."""
+    # Status progression order
+    status_order = [
+        "CREATE_IN_PROGRESS",
+        "CREATE_COMPLETE",
+        "CREATE_FAILED",
+        "DELETE_IN_PROGRESS",
+        "DELETE_COMPLETE",
+    ]
+
+    try:
+        new_idx = status_order.index(new_status)
+        old_idx = status_order.index(old_status)
+        return new_idx > old_idx
+    except ValueError:
+        # Unknown status, assume it's newer
+        return True
+
+
+def get_stack_outputs(stack_name: str, region: str) -> SetupResult:
+    """Get outputs from a completed stack."""
+    cfn = cast("CloudFormationClient", boto3.client("cloudformation", region_name=region))  # pyright: ignore[reportUnknownMemberType]
+
+    response = cfn.describe_stacks(StackName=stack_name)
+    stack_outputs = response["Stacks"][0].get("Outputs", [])
+    outputs: dict[str, str] = {
+        o["OutputKey"]: o["OutputValue"]
+        for o in stack_outputs
+        if "OutputKey" in o and "OutputValue" in o
+    }
+
+    return SetupResult(
+        bucket=outputs["BucketName"],
+        region=region,
+        role_arn=outputs["RoleArn"],
+        external_id=outputs["ExternalId"],
+        stack_name=stack_name,
+        kms_key_arn=outputs["KmsKeyArn"],
+    )
+
+
+def create_stack(
+    external_id: str,
+    principal_arn: str,
+    bucket_name: str | None = None,
+    region: str | None = None,
+) -> SetupResult:
+    """Create CloudFormation stack with credential storage infrastructure.
+
+    This is the simple blocking API. For progress updates, use
+    start_stack_creation() + poll_stack_progress() + get_stack_outputs().
+    """
+    stack_name, region, cfn = start_stack_creation(
+        external_id, principal_arn, bucket_name, region
+    )
+
+    # Poll until complete
+    for progress in poll_stack_progress(stack_name, cfn):
+        if progress.is_failed:
+            raise Exception(f"Stack creation failed: {progress.failure_reason}")
+        if progress.is_complete:
+            break
+
+    return get_stack_outputs(stack_name, region)