Metadata-Version: 2.4
Name: giftcrypt
Version: 1.0.1
Summary: Encryption and decryption primitives for gift card data (physical and virtual)
Author: giftcrypt contributors
License: MIT
Project-URL: Repository, https://github.com/your-org/giftcrypt
Project-URL: Issues, https://github.com/your-org/giftcrypt/issues
Keywords: encryption,giftcard,aes,gcm,kms,aws
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42.0
Provides-Extra: kms
Requires-Dist: boto3>=1.34; extra == "kms"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: boto3>=1.34; extra == "dev"
Requires-Dist: moto[kms]>=5.0; extra == "dev"

# giftcrypt

**Encryption and decryption of 16-digit gift card numbers (physical and virtual).**

Version: 1.0.0

---

## Overview

`giftcrypt` is a Python package used by the GC Activation Orchestrator to encrypt
a plain 16-digit gift card number before writing it to Vault DB, and to decrypt it
when reading back.

Two backends are supported:

| Backend | Mechanism | When to use |
|---|---|---|
| `gcm` | AES-256-GCM local key | Local development and testing |
| `kms_wrapped` | AWS KMS envelope encryption | Production (recommended) |

---

## Installation

```bash
pip install cryptography          # for gcm backend
pip install cryptography boto3    # for kms_wrapped backend
```

---

## Usage

The only function the Orchestrator needs to call is in `vault.py`:

```python
from giftcrypt.vault import encrypt_card_number, decrypt_card_number
```

---

### Local / dev testing (GCM backend)

No AWS needed. Uses a local secret key.

```python
from giftcrypt.vault import encrypt_card_number, decrypt_card_number

key = "my-secret-encryption-key"

# Encrypt — after SVS activates the card (PGC or VGC)
ciphertext = encrypt_card_number(
    "1234567890123456",
    backend="gcm",
    key=key,
)
# → store ciphertext in Vault DB

# Decrypt — when reading back from Vault DB
card_number = decrypt_card_number(ciphertext, backend="gcm", key=key)
assert card_number == "1234567890123456"
```

---

### Production (KMS wrapped backend)

Requires AWS account and KMS key. Card number never leaves your Lambda.

```python
from giftcrypt.vault import encrypt_card_number, decrypt_card_number

KEY_ALIAS = "alias/giftcard-key"
REGION    = "us-east-1"

# PGC — card number from KIBO shipment swipe
# VGC — card number freshly issued by SVS
# Both use the exact same call:

ciphertext = encrypt_card_number(
    "1234567890123456",
    backend="kms_wrapped",
    key_alias=KEY_ALIAS,
    region=REGION,
)
# → store ciphertext in Vault DB

card_number = decrypt_card_number(ciphertext, backend="kms_wrapped", region=REGION)
assert card_number == "1234567890123456"
```

---

## Input formats accepted

Dashes and spaces are stripped automatically before encryption:

```python
encrypt_card_number("1234567890123456")      # plain
encrypt_card_number("1234-5678-9012-3456")   # dashes stripped
encrypt_card_number("1234 5678 9012 3456")   # spaces stripped
# all three store the same normalised value: "1234567890123456"
```

---

## Package structure

```
giftcrypt/
├── giftcrypt/
│   ├── __init__.py       # package entry point
│   ├── vault.py          # primary interface — validate, normalise, route
│   ├── gcm.py            # AES-256-GCM local encryption
│   └── kms_wrapped.py    # AWS KMS envelope encryption
└── tests/
    ├── test_gcm.py        # 10 tests
    └── test_vault.py      # 21 tests
```

---

## Running tests

No AWS account needed — KMS is fully mocked:

```bash
py -m pytest tests/ -v
```

Expected output:
```
31 passed in 0.82s
```

---

## AWS KMS setup (for production)

1. Create an AWS account at https://aws.amazon.com/free
2. Create a KMS key in AWS Console → KMS → Create key
3. Set alias to `alias/giftcard-key`
4. Run `aws configure` on your machine to set up credentials
5. Create `conf/test.yml`:

```yaml
aws:
  profile: your_aws_profile
  region: us-east-1
  key_alias: alias/giftcard-key
```

6. Run the KMS smoke test:

```bash
py kms_smoke_test.py
```

---

## Ciphertext envelope formats

**GCM envelope** — pipe-separated, base64url-encoded:
```
v1|<iv>|<tag>|<aad>|<ciphertext>
```

**KMS wrapped envelope** — base64-encoded JSON:
```json
{
  "version": "kms-wrapped-v1",
  "key_id": "arn:aws:kms:us-east-1:...",
  "wrapped_data_key": "...",
  "iv": "...",
  "ciphertext": "..."
}
```

---

## License

MIT
