116 lines
2.7 KiB
Markdown
116 lines
2.7 KiB
Markdown
# CLAUDE.md — LetsBe Hub
|
|
|
|
## Purpose
|
|
|
|
You are the engineering assistant for the LetsBe Hub.
|
|
This is the central licensing and telemetry service for the LetsBe Cloud platform.
|
|
|
|
The Hub provides:
|
|
|
|
- **License Management**: Issue and validate per-instance license keys
|
|
- **Instance Activation**: Verify licenses during client installation
|
|
- **Telemetry Collection**: Receive anonymized usage data from instances
|
|
- **Client Management**: Track organizations and their deployments
|
|
|
|
## Privacy Guarantee
|
|
|
|
**CRITICAL**: The Hub NEVER stores sensitive client data.
|
|
|
|
Allowed data:
|
|
- Instance identifiers
|
|
- Tool names
|
|
- Duration metrics
|
|
- Aggregated counts
|
|
- Error codes (not messages)
|
|
|
|
NEVER stored:
|
|
- Environment variable values
|
|
- File contents
|
|
- Request/response payloads
|
|
- Screenshots
|
|
- Credentials
|
|
- Stack traces or error messages
|
|
|
|
The `app/services/redactor.py` enforces this with an ALLOW-LIST approach.
|
|
|
|
## Tech Stack
|
|
|
|
- Python 3.11
|
|
- FastAPI
|
|
- SQLAlchemy 2.0 (async)
|
|
- PostgreSQL
|
|
- Alembic migrations
|
|
- Pydantic v2
|
|
|
|
## API Endpoints
|
|
|
|
### Public Endpoints
|
|
|
|
```
|
|
POST /api/v1/instances/activate
|
|
- Validates license key
|
|
- Returns hub_api_key for telemetry
|
|
- Called by client bootstrap scripts
|
|
```
|
|
|
|
### Admin Endpoints (require X-Admin-Api-Key header)
|
|
|
|
```
|
|
# Clients
|
|
POST /api/v1/admin/clients
|
|
GET /api/v1/admin/clients
|
|
GET /api/v1/admin/clients/{id}
|
|
PATCH /api/v1/admin/clients/{id}
|
|
DELETE /api/v1/admin/clients/{id}
|
|
|
|
# Instances
|
|
POST /api/v1/admin/clients/{id}/instances
|
|
GET /api/v1/admin/clients/{id}/instances
|
|
GET /api/v1/admin/instances/{instance_id}
|
|
POST /api/v1/admin/instances/{instance_id}/rotate-license
|
|
POST /api/v1/admin/instances/{instance_id}/rotate-hub-key
|
|
POST /api/v1/admin/instances/{instance_id}/suspend
|
|
POST /api/v1/admin/instances/{instance_id}/reactivate
|
|
DELETE /api/v1/admin/instances/{instance_id}
|
|
```
|
|
|
|
## Key Types
|
|
|
|
### License Key
|
|
Format: `lb_inst_<32_hex_chars>`
|
|
Example: `lb_inst_a1b2c3d4e5f6789012345678901234567890abcd`
|
|
|
|
Stored as SHA-256 hash. Only visible once at creation.
|
|
|
|
### Hub API Key
|
|
Format: `hk_<24_hex_chars>`
|
|
Example: `hk_abc123def456789012345678901234567890abcd`
|
|
|
|
Used for telemetry authentication. Stored as SHA-256 hash.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Start services
|
|
docker compose up --build
|
|
|
|
# Run migrations
|
|
docker compose exec api alembic upgrade head
|
|
|
|
# Create new migration
|
|
docker compose exec api alembic revision --autogenerate -m "description"
|
|
|
|
# Run tests
|
|
docker compose exec api pytest -v
|
|
|
|
# API available at http://localhost:8200
|
|
```
|
|
|
|
## Coding Conventions
|
|
|
|
- Everything async
|
|
- Use the redactor for ALL telemetry data
|
|
- Never log sensitive data
|
|
- All exceptions should be caught and return proper HTTP errors
|
|
- Use constant-time comparison for secrets (secrets.compare_digest)
|