API Token Security Rules

This rule applies to files matching the patterns above.

# API Token Security Rules

## Rule
HuggingFace API tokens MUST be stored in environment variables, never hardcoded. Use fine-grained tokens with minimal permissions.

## Token Storage

### Good — Environment Variables
```python
import os
from huggingface_hub import login

# Load from environment
hf_token = os.environ.get("HF_TOKEN")
if not hf_token:
    raise ValueError("HF_TOKEN environment variable not set")

login(token=hf_token)
```

### Bad — Hardcoded Token
```python
# NEVER do this
login(token="hf_AbCdEfGhIjKlMnOpQrStUvWxYz")  # Exposed in code!
```

## Token Types and Permissions
| Token Type | Permissions | Use Case |
|-----------|------------|----------|
| Read | Download models/datasets | CI/CD, inference |
| Write | Upload models/datasets | Training pipelines |
| Fine-grained | Custom per-repo | Production (recommended) |

## Environment Setup
```bash
# .env file (gitignored!)
HF_TOKEN=hf_...

# Or use HuggingFace CLI
huggingface-cli login

# Verify login
huggingface-cli whoami
```

## Gitignore Rules
```gitignore
# Always ignore
.env
.env.*
!.env.example
**/token
**/token.txt
**/.huggingface/
```

## CI/CD Configuration
```yaml
# GitHub Actions — use secrets
- name: Login to HuggingFace
  env:
    HF_TOKEN: ${{ secrets.HF_TOKEN }}
  run: huggingface-cli login --token $HF_TOKEN
```

## Token Rotation
- Rotate tokens every 90 days
- Revoke tokens immediately if exposed
- Use different tokens for development and production
- Audit token usage in HuggingFace settings

## Anti-Patterns
- Hardcoded tokens in source code
- Tokens in Jupyter notebook output cells (committed accidentally)
- Same token for all environments (dev, staging, prod)
- Write tokens used where read-only would suffice
- Tokens logged to stdout or log files