gm-shield 0.2.0__tar.gz

gm_shield-0.2.0/.github/workflows/ci.yaml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v2]
+  pull_request:
+    branches: [main, v2]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Format
+        run: uv run ruff format --check src/
+
+      - name: Run type checker
+        run: uv run pyright
+
+      - name: Run tests
+        run: uv run pytest

gm_shield-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

gm_shield-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local config (keep out of repo)
+config.yaml
+
+# Worktrees
+.worktrees/
+
+docs/plans
+.envrc
+
+.local
+.mock

gm_shield-0.2.0/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md - gm-shield
+
+CLI tool for market makers to securely share exchange API credentials.
+
+## Tech Stack
+
+- Python 3.12+, pyright strict mode
+- Click (CLI), boto3 (AWS), rich (terminal UI), questionary (interactive prompts)
+- uv (package manager)
+
+## Project Structure
+
+```
+src/exchange_keyshare/
+├── cli.py              # CLI entrypoint
+├── config.py           # Config file (~/.config/gm-shield/config.yaml)
+├── cfn.py              # CloudFormation polling helpers
+├── setup.py            # Credentials stack creation
+├── enclave.py          # Enclave stack creation
+├── keys.py             # S3 credential operations
+├── schema.py           # Credential validation
+├── templates/
+│   ├── credentials-stack.yaml  # CFN template: S3 bucket, KMS key, IAM role
+│   └── enclave-stack.yaml      # CFN template: EC2 + Nitro Enclave
+└── commands/
+    ├── setup.py        # `setup` / `teardown` commands
+    ├── teardown.py
+    ├── config.py       # `config` command
+    ├── keys.py         # `keys` subcommands
+    └── enclave.py      # `enclave` subcommands
+```
+
+## Commands
+
+```bash
+gm-shield setup            # Deploy credentials stack (S3, KMS, IAM)
+gm-shield teardown         # Delete credentials stack
+gm-shield config           # Show current config
+
+gm-shield keys list        # List credentials
+gm-shield keys create      # Create credential (interactive)
+gm-shield keys delete      # Delete credential
+gm-shield keys update      # Update pairs/labels
+
+gm-shield enclave approve  # Grant enclave access (add KMS/S3 policy)
+gm-shield enclave revoke   # Revoke enclave access
+gm-shield enclave rotate   # Rotate PCR attestation values
+# hidden: enclave deploy / enclave teardown
+```
+
+## Configuration
+
+`~/.config/gm-shield/config.yaml` — written by `setup`, read by all other commands.
+
+Credentials stack fields: `bucket`, `region`, `stack_name`, `stack_id`, `kms_key_arn`
+
+Enclave stack fields (`enclave` key): `stack_name`, `stack_id`, `region`, `role_arn`, `instance_profile_arn`, `host_ref`, `eip`, `labels`
+
+Approved enclave fields (`approved_enclave` key): `role_arn`, `pcr8`, `pcr0` (optional), `approved_at`
+
+Override path: `GM_SHIELD_CONFIG` env var. Region fallback: `AWS_REGION` / `AWS_DEFAULT_REGION`.
+
+## CloudFormation Stacks
+
+**credentials-stack.yaml** (`setup` / `teardown`):
+- S3 bucket (versioned, KMS-encrypted, access logged) + KMS key (auto-rotating)
+- `ConsumerAccessRole` — read-only IAM role for credential consumer (external ID required)
+- `DeletionPolicy: Retain` on bucket and KMS key
+
+**enclave-stack.yaml** (`enclave deploy` / `enclave teardown`):
+- EC2 instance with Nitro Enclave enabled, static EIP, locked-down security group
+
+**Enclave attestation:** `approve` adds KMS + S3 policy statements scoped to the enclave's IAM role and PCR values (PCR8 required, PCR0 optional).
+
+## Credential Schema
+
+Stored as YAML in S3 under `exchange-credentials/` prefix:
+
+```yaml
+version: "1"
+exchange: binance  # binance, coinbase, kraken, kucoin, bitget, okx
+credential:
+  api_key: "..."
+  api_secret: "..."
+  passphrase: "..."  # required for coinbase, kucoin, bitget, okx
+pairs:              # optional, BASE/QUOTE format
+  - BTC/USDT
+labels:             # optional
+  - key: environment
+    value: production
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run pyright
+uv run ruff check src/
+```
+
+## Worktrees
+
+Use `.worktrees/` for feature branches (already in `.gitignore`).

gm_shield-0.2.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: gm-shield
+Version: 0.2.0
+Summary: CLI for market makers to securely share exchange API credentials
+Requires-Python: >=3.12
+Requires-Dist: boto3-stubs>=1.42.40
+Requires-Dist: boto3>=1.42.80
+Requires-Dist: botocore[crt]>=1.42.80
+Requires-Dist: click>=8.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=14.3.3

gm_shield-0.2.0/README.md

@@ -0,0 +1,221 @@
+# gm-shield
+
+CLI tool for securely sharing exchange API credentials using Nitro Enclaves for isolated credential access.
+
+## Architecture
+
+**Complete isolation:**
+- Credentials are stored in S3 with KMS encryption
+- Nitro Enclave runs in an isolated VM with no persistent storage
+- Enclave fetches credentials using KMS attestation (PCR8(optionally PCR0) values)
+- Credentials never exposed to the host EC2 instance
+
+**Single or multi-account:**
+- **Multi-account**: GM runs enclave infrastructure, MM owns KMS/S3 (recommended)
+- **Single account**: Run everything in one AWS account yourself
+
+### Data Flow
+
+```mermaid
+sequenceDiagram
+    participant MM as Market Maker
+    participant S3 as S3 Bucket
+    participant KMS as KMS Key
+    participant Enclave as Nitro Enclave
+    participant GM as GlassMarkets
+
+    MM->>S3: 1. Store encrypted credentials
+    MM->>KMS: 2. Grant enclave access (PCR8)
+    GM->>Enclave: 3. Deploy enclave
+    Enclave->>KMS: 4. Request decryption (PCR8 attestation)
+    KMS->>Enclave: 5. Return credentials
+    Note over Enclave: Credentials isolated from host
+```
+
+### Component Isolation
+
+```mermaid
+graph TB
+    subgraph "Market Maker Account"
+        S3[S3 Bucket<br/>Encrypted Credentials]
+        KMS[KMS Key<br/>You Control]
+        S3 -.->|Encryption| KMS
+    end
+
+    subgraph "GlassMarkets Account"
+        EC2[EC2 Instance<br/>Host]
+        Enclave[Nitro Enclave<br/>Isolated VM]
+
+        EC2 -->|Hosts| Enclave
+    end
+
+    Enclave -->|PCR8 Attestation| KMS
+    KMS -->|Decrypt| Enclave
+    Enclave -->|Fetch| S3
+
+    style Enclave fill:#10B981,stroke:#047857,color:#fff
+    style EC2 fill:#F59E0B,stroke:#D97706,color:#fff
+    style KMS fill:#3B82F6,stroke:#2563EB,color:#fff
+    style S3 fill:#3B82F6,stroke:#2563EB,color:#fff
+```
+
+### Security Model
+
+| Layer              | Access                       | Isolation                      |
+|--------------------|------------------------------|--------------------------------|
+| **Host EC2**       | Run/stop enclaves            | No credential access           |
+| **Nitro Enclave**  | KMS decrypt + S3 read        | Isolated VM, vsock only        |
+| **KMS Key Policy** | Requires PCR8 (signing cert) | Optional PCR0 (proof of build) |
+| **Credentials**    | S3 encrypted, versioned      | Never exposed to host          |
+
+
+## Prerequisites
+
+- Python 3.12+
+- AWS CLI configured with credentials
+
+## Installation
+
+```bash
+pip install gm-shield
+```
+
+## Quick Start
+
+### Set up keyshare infra
+
+```bash
+gm-shield setup
+```
+
+This creates:
+- An S3 bucket for storing credentials (KMS-encrypted, versioned)
+- A KMS key for encryption (you control it)
+- Config saved to `~/.config/gm-shield/config.yaml`
+
+### Deploy enclave infrastructure
+
+```bash
+gm-shield enclave deploy
+```
+
+This deploys:
+- EC2 instance with Nitro Enclave support
+- IAM role for the enclave
+- Outputs the **Role ARN** attached to the instance profile needed for approval
+
+### Get PCR values
+
+- From the `https://github.com/glassmarkets/shield-worker/actions/workflows/release.yml` release notes pick up PCR values.
+
+- Look for the `PCR8` value in the `Measurements` section.
+- If you want to approve each release build optionally add `PCR0` value.
+
+### Approve enclave access
+
+```bash
+gm-shield enclave approve \
+  --role-arn <enclave-role-arn> \
+  --pcr8 <pcr8-value>
+```
+or interactive
+```bash
+gm-shield enclave approve
+```
+
+This updates the KMS key policy to allow the enclave (with PCR8 attestation) to decrypt credentials.
+
+### Add credentials
+
+```bash
+gm-shield keys create
+```
+
+Follow the interactive prompts to select an exchange and enter your API credentials. The enclave will fetch and use them securely.
+
+## Commands
+
+### Market Maker: Credential Storage
+
+```bash
+gm-shield setup              # Create S3 bucket, KMS key
+gm-shield config             # Display current configuration
+gm-shield teardown           # Delete infrastructure
+gm-shield keys list          # List all credentials
+gm-shield keys create        # Add new credential (interactive)
+gm-shield keys update        # Update pairs or labels
+gm-shield keys delete        # Delete a credential
+```
+
+### GlassMarkets: Enclave Infrastructure
+
+```bash
+gm-shield enclave deploy     # Deploy Nitro Enclave infrastructure (prompts for labels)
+gm-shield enclave teardown   # Delete enclave infrastructure (interactive if multiple)
+gm-shield config             # Display configuration (shows all enclaves)
+```
+
+### Access Control (Market Maker approves/revokes)
+
+```bash
+gm-shield enclave approve    # Grant enclave access (requires PCR8)
+gm-shield enclave revoke     # Revoke enclave access
+gm-shield enclave rotate     # Rotate PCR attestation values
+```
+
+## Configuration
+
+Config is stored at `~/.config/gm-shield/config.yaml`:
+
+```yaml
+bucket: my-credentials-bucket
+region: us-east-1
+stack_name: my-keyshare-stack
+stack_id: arn:aws:cloudformation:...
+kms_key_arn: arn:aws:kms:...
+
+enclaves:
+  - stack_name: gm-enclave-mm1
+    stack_id: arn:aws:cloudformation:...
+    region: eu-central-1
+    role_arn: arn:aws:iam::...:role/...
+    instance_profile_arn: arn:aws:iam::...:instance-profile/...
+    instance_id: i-xxxxxxxx
+    labels:
+      - mm1
+      - production
+
+approved_enclave:
+  role_arn: arn:aws:iam::...:role/...
+  pcr8: 2d4bd2e9ce136106537f13262b545c459e08ea760dacaef62350cbea418495f3be47926f8f8785ce1b2a653045bcd14c
+  pcr0: null
+  approved_at: 2026-03-31T21:00:00Z
+```
+
+
+## Workflow
+
+1. **Run setup**: `gm-shield setup` → creates KMS + S3
+2. **Deploy enclave**: `gm-shield enclave deploy` → deploys enclave stack (prompts for labels)
+3. **Get PCR8**: From GitHub Actions release notes (shield-worker release workflow)
+4. **Approve**: `gm-shield enclave approve --role-arn <...> --pcr8 <...>`
+5. **Add credentials**: `gm-shield keys create`
+
+**Multiple enclaves**: Run `gm-shield enclave deploy` multiple times to deploy additional enclaves. Each deployment prompts for labels (e.g., `mm1,production`) to track which MM each enclave serves.
+
+## Security Model
+
+- **Credentials** are stored in S3 with KMS encryption
+- **Enclave access** is scoped to specific PCR8 (signing certificate) values
+- **Revoke anytime** with `gm-shield enclave revoke`
+- **Isolation**: Credentials decrypted only inside the Nitro Enclave, never exposed to the host
+
+## Development
+
+```bash
+uv sync
+
+uv run pytest
+
+uv run pyright
+```

gm_shield-0.2.0/docs/ONBOARD.md

@@ -0,0 +1,176 @@
+# Market Maker Onboarding
+
+Securely share your exchange API credentials with Glass using isolated enclaves.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    MM[Market Maker]
+    S3[Encrypted S3 Storage]
+    KMS[KMS Key]
+    Enclave[Isolated EC2 Enclave]
+    Glass[Glass Team]
+
+    MM -->|1. Store and configure API keys| S3
+    S3 -.->|Encryption| KMS
+    Glass -->|2. Deploy| Enclave
+    MM -->|3. Approve access| KMS
+    Enclave -->|4. Fetch keys| S3
+    Enclave -.->|Decrypt| KMS
+
+    style MM fill:#3B82F6,color:#fff
+    style S3 fill:#3B82F6,color:#fff
+    style KMS fill:#3B82F6,color:#fff
+    style Enclave fill:#10B981,color:#fff
+    style Glass fill:#8B5CF6,color:#fff
+```
+
+**Your credentials never leave the isolated enclave**
+
+## Security Model
+
+| Layer          | What You Control        | Security Guarantee                 |
+|----------------|-------------------------|------------------------------------|
+| **Storage**    | S3 bucket + KMS key     | Credentials encrypted at rest      |
+| **Access**     | Enclave approval (PCR8) | Only approved enclaves can decrypt |
+| **Revocation** | Revoke anytime          | Instantly cut off enclave access   |
+
+**Key point**: Glass deploys and manages enclaves, but you control who can access your keys through KMS policies.
+
+## Prerequisites
+
+- Python 3.12+
+- AWS CLI configured with credentials
+
+## Installation
+
+```bash
+pip install gm-shield
+```
+
+## Quick Start
+
+### Step 1: Set up infrastructure
+
+```bash
+gm-shield setup
+```
+
+This creates:
+- S3 bucket for encrypted credentials
+- KMS key (you control it)
+- Config saved to `~/.config/gm-shield/config.yaml`
+
+**Share with Glass:**
+- Bucket name
+- Region
+
+### Step 2: Glass deploys enclave
+
+Glass will:
+1. Deploy a Nitro Enclave in their AWS account
+2. Provide you with the enclave's **Role ARN**
+3. Provide you with the enclave's outbound **IP address** (for whitelisting)
+
+### Step 3: Add your exchange credentials
+
+```bash
+gm-shield keys create
+```
+
+Interactive prompts for exchange and API credentials.
+
+The enclave can now fetch and use your credentials securely.
+
+**Note:** Remember to add the outbound IP address to your exchange API allowlist!
+
+### Step 4: Approve enclave access
+
+```bash
+gm-shield enclave approve
+```
+
+- Enter the enclave Role ARN (from Glass)
+- Enter the enclave PCR8 value: `2d4bd2e9ce136106537f13262b545c459e08ea760dacaef62350cbea418495f3be47926f8f8785ce1b2a653045bcd14c`
+- **Optional:**
+  - You can verify all PCRs in the https://github.com/glassmarkets/shield-worker/actions/workflows/release.yml release notes under the `Measurements` section. Optionally add `PCR0` if you want to approve each release build.
+
+This updates your KMS policy to allow the enclave to decrypt credentials and S3 policy to allow the enclave to read from S3.
+
+## Daily Operations
+
+### View credentials
+
+```bash
+gm-shield keys list
+```
+
+### Update credential
+
+```bash
+gm-shield keys update <key-name>
+```
+
+### Delete credential
+
+```bash
+gm-shield keys delete <key-name>
+```
+
+### View configuration
+
+```bash
+gm-shield config
+```
+
+Shows:
+- S3 bucket and KMS key
+- Deployed enclaves (with labels)
+- Approved enclave attestation values
+
+## Access Control
+
+### Approve additional enclaves
+
+```bash
+gm-shield enclave approve
+```
+
+### Revoke all access
+
+```bash
+gm-shield enclave revoke
+```
+
+### Rotate PCR0
+```bash
+gm-shield enclave rotate
+```
+
+Immediately removes all enclave access to your credentials.
+
+### Delete all infrastructure
+- You can delete all resources, revoking access to all keys using the following command
+
+```bash
+gm-shield teardown
+```
+
+## Troubleshooting
+
+### "No approved enclave"
+
+Run `gm-shield enclave approve` with the Role ARN and PCR8 from Glass.
+
+### "Enclave already approved"
+
+Run `gm-shield enclave revoke` first, then approve with new values.
+
+### View config
+
+```bash
+gm-shield config
+```
+
+Check the "Approved Enclave" section for current PCR8 and Role ARN.

gm_shield-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "gm-shield"
+version = "0.2.0"
+description = "CLI for market makers to securely share exchange API credentials"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.1.0",
+    "boto3>=1.42.80",
+    "botocore[crt]>=1.42.80",
+    "pyyaml>=6.0",
+    "rich>=14.3.3",
+    "questionary>=2.0.0",
+    "boto3-stubs>=1.42.40",
+]
+
+[dependency-groups]
+dev = [
+    "boto3-stubs[cloudformation,kms,s3]>=1.42.78",
+    "pyright>=1.1.408",
+    "pytest>=9.0.2",
+    "pytest-github-actions-annotate-failures>=0.4.0",
+    "ruff>=0.15.8",
+]
+
+[project.scripts]
+gm-shield = "exchange_keyshare.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/exchange_keyshare"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportUnnecessaryCast = false  # False positive with boto3-stubs
+reportUnknownVariableType = "none"  # boto3.client() returns dynamic type
+reportUnknownMemberType = "none"  # boto3 client methods
+reportUnknownArgumentType = "none"  # boto3 method arguments
+reportUnknownLambdaType = "none"  # boto3 callbacks
+reportTypedDictNotRequiredAccess = "none"  # boto3 error responses

gm_shield-0.2.0/src/exchange_keyshare/__init__.py

@@ -0,0 +1,3 @@
+"""Exchange Keyshare - CLI for market makers to securely share exchange credentials."""
+
+__version__ = "0.1.0"