Metadata-Version: 2.4
Name: token-generator-for-aws-external-anthropic
Version: 1.0.0
Summary: A lightweight library for generating short-term bearer tokens for AWS External Anthropic API authentication
Author-email: Amazon Web Services <aws-mantle-oss@amazon.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/aws/token-generator-for-aws-external-anthropic-python
Project-URL: Repository, https://github.com/aws/token-generator-for-aws-external-anthropic-python
Project-URL: Documentation, https://github.com/aws/token-generator-for-aws-external-anthropic-python#readme
Project-URL: Issues, https://github.com/aws/token-generator-for-aws-external-anthropic-python/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: boto3>=1.33.0
Requires-Dist: botocore>=1.33.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: license-file

# Token Generator for AWS External Anthropic (Python)

A lightweight library for generating short-term bearer tokens for AWS External Anthropic API authentication.

## Installation

```bash
pip install token-generator-for-aws-external-anthropic
```

## Quick Start

Token duration can be customized (1 second to 12 hours). The actual token lifetime will be:
`min(specified duration, credentials expiry, 12 hours)`. Default is 12 hours.

### Usage 1 — Using Default Credentials and Region

```python
from token_generator_for_aws_external_anthropic import TokenGenerator

# Credentials and region resolved from default chain (env vars, config files, IAM roles, etc.)
generator = TokenGenerator()
token = generator.get_token()
```

### Usage 2 — Using Custom Configuration

This example uses a profile with assume role configured. You can use any credential configuration
supported by boto3. See the [boto3 credentials guide](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html)
for all options including assume role, SSO, environment variables, and more.

```python
import boto3
from datetime import timedelta
from token_generator_for_aws_external_anthropic import TokenGenerator

# Profile with assume-role configured in ~/.aws/config
session = boto3.Session(profile_name="my-role-profile")
generator = TokenGenerator(session=session, region="us-east-1")
token = generator.get_token(expiry=timedelta(hours=1))
```

### Usage 3 — Using Static One-Shot

Pass credentials, region, and expiry directly. No instance needed.

```python
from datetime import timedelta
from botocore.credentials import Credentials
from token_generator_for_aws_external_anthropic import get_token

credentials = Credentials(
    access_key="YOUR_ACCESS_KEY_ID",
    secret_key="YOUR_SECRET_ACCESS_KEY",
    token="YOUR_SESSION_TOKEN",
)

token = get_token(credentials=credentials, region="us-west-2", expiry=timedelta(hours=6))
```

## Token Format

The generated token has the format:

```
aws-external-anthropic-api-key-<base64-encoded-payload>
```

The payload is a Base64-encoded SigV4 presigned URL scoped to the `aws-external-anthropic` service. The token can be decoded for debugging purposes but should be treated as an opaque string in production.

## Requirements

- **Python**: 3.8 or later
- **boto3**: 1.33.0 or later
- **botocore**: 1.33.0 or later

## Security Considerations

- **Token Expiration**: Tokens are short-lived with a maximum lifetime of 12 hours. The actual expiry is `min(specified duration, credentials expiry, 12 hours)`. Use the shortest practical duration for your use case.
- **Secure Storage**: Do not log or store tokens in plain text. Treat them as sensitive credentials.
- **No Embedded Credentials**: No long-term credentials are embedded in the token. The token contains a SigV4 presigned URL, not the signing keys themselves.
- **Credential Management**: Use IAM roles or temporary credentials instead of long-term access keys where possible.
- **Network Security**: Always transmit tokens over HTTPS.
- **Least Privilege**: Scope IAM permissions to the minimum required for your use case.
- **Region Scoping**: Tokens are scoped to a specific AWS region and cannot be used across regions.

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=token_generator_for_aws_external_anthropic

# Format code
ruff format .

# Lint
ruff check .
```

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md) for more information.

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG](CHANGELOG.md) for release history.
