2.7 KiB

Raw Blame History

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

# 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)

2.7 KiB Raw Blame History