keys-for-all/keys-api/README.md

# Keys for All API

Backend API server for the Keys for All licensing system.

## Features

- 🔑 Secure key generation and validation
- 🔒 API key authentication
- ⚡ Redis-based rate limiting
- 📊 Analytics and monitoring
- 🎁 Community pool management
- 🔄 Key sharing functionality

## Quick Start

### Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis 7+

### Installation

```bash
# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
npm run migrate

# Start development server
npm run dev
```

### Environment Variables

Create a `.env` file with:

```env
# Server
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/keysforall

# Redis
REDIS_URL=redis://localhost:6379

# Security
JWT_SECRET=your-secret-key
API_KEY_SALT=your-salt

# Rate Limiting
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_VALIDATE=100
RATE_LIMIT_GENERATE=10

# Features
FEATURE_COMMUNITY_POOL=true
FEATURE_KEY_SHARING=true
```

## API Endpoints

### Key Management
- `POST /v1/keys/generate` - Generate new keys
- `POST /v1/keys/validate` - Validate a key
- `POST /v1/keys/activate` - Activate a key
- `GET /v1/keys/:key/status` - Get key status

### Key Sharing
- `POST /v1/keys/share` - Create share link
- `POST /v1/keys/claim` - Claim shared key

### Community Pool
- `POST /v1/community/donate` - Donate keys
- `POST /v1/community/request` - Request key
- `GET /v1/community/status` - Pool statistics

### Purchase Verification
- `POST /v1/purchase/verify` - Verify StoreKit receipt

### Analytics
- `GET /v1/analytics/app/:id` - App statistics

## Authentication

All requests require an API key header:
```
X-API-Key: your-api-key
```

## Development

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Start development server with auto-reload
npm run dev
```

## Production Deployment

```bash
# Build for production
npm run build

# Start production server
npm start
```

### Docker

```bash
# Build image
docker build -t keysforall-api .

# Run container
docker run -p 3000:3000 --env-file .env keysforall-api
```

## Project Structure

```
src/
├── config/          # Configuration management
├── controllers/     # Request handlers
├── middleware/      # Express middleware
├── models/          # Database models
├── routes/          # API routes
├── services/        # Business logic
├── utils/           # Helper functions
└── server.js        # Entry point
```

## Security

- API key authentication
- Rate limiting per endpoint
- Input validation with Joi
- SQL injection prevention
- XSS protection with Helmet

## Monitoring

The API exposes metrics at `/metrics` for Prometheus scraping.

Key metrics:
- Request rate and latency
- Key validation success/failure
- Database query performance
- Redis cache hit rate

## Contributing

1. Fork the repository
2. Create your feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT