CypherLegacy is a secure digital legacy inheritance system backend built with FastAPI. It allows users to safely store encrypted digital assets and designate specific heirs who can claim these assets after the user's status is confirmed as "deceased" by an administrator.

🌟 Core Features

Secure Authentication: Registration automatically generates an RSA key pair (public/private). Public keys are used for encryption, while private keys are used for secure decryption.
Encrypted Asset Storage: Users can upload assets that are encrypted using their unique public key before storage.
Legacy Designation: Users can assign specific heirs (via email) to each of their digital assets.
Status Monitoring: Administrators can officially declare a user as "deceased" (guale), triggering the inheritance process.
Inheritance Claiming:
- Designated heirs can claim assets only after the owner's status is verified.
- The system securely decrypts the content using the deceased user's private key for the authorized heir.
AI Proxy Service: A built-in proxy for interacting with AI models with role-based configurations and weekly quota/token management.
Subscription Tiers: Multi-tier subscription system (Free, Pro, etc.) controlling limits on heirs, AI usage, and more.
Last Active Tracking: Automatically tracks user activity to help monitor status.

🛠 Technology Stack

Framework: FastAPI
Database: PostgreSQL (via asyncpg async driver)
ORM: SQLAlchemy 2.0 (AsyncIO)
Encryption: Cryptography & PyCryptodome (RSA Encryption)
Authentication: python-jose (JWT Tokens) & Passlib (Bcrypt/Argon2)
Request Client: HTTPX (for AI Proxy)

🚀 Getting Started

1. Using Docker Compose (Recommended)

This is the fastest way to get the system running with a pre-configured database.

docker-compose up --build

API Documentation: http://localhost:8000/docs
Default Admin: admin / admin123

🧪 Running Tests

Once the service is up, you can run the automated test scenario:

python3 test/test_scenario.py

2. Local Manual Setup

Environment Setup:

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or venv\Scripts\activate on Windows
pip install -r requirements.txt

Configuration: Create a .env file or set the DATABASE_URL environment variable. Default: postgresql+asyncpg://user:password@localhost:5432/fastapi_db
Database Initialization:
```
python reset_db.py
```
Run Service:
```
uvicorn app.main:app --reload
```

📖 API Overview

User & Auth

POST /register: Register and generate RSA keys.
POST /login: Login and receive JWT access token.
GET /users/search: Search for users by username or email.

Asset Management

GET /assets/get: Retrieve assets owned by the current user.
POST /assets/create: Create a new encrypted asset.
POST /assets/assign: Assign or unassign an heir to an asset.
POST /assets/delete: Remove an asset.
GET /assets/designated: List assets where the user is the designated heir.

Inheritance

POST /assets/claim: Claim an asset (requires owner to be marked as deceased).

AI & Roles

POST /ai/proxy: Proxy requests to external AI providers with quota tracking.
GET /get_ai_roles: Retrieve available AI personas/roles.

Admin

POST /admin/declare-guale: (Admin Only) Declare a user as deceased.

🔒 Security Design

End-to-End Principles: Sensitive assets are encrypted before storage.
State Verification: Claim logic strictly validates the heir_id and the deceased status of the owner.
Key Management: For demonstration, private keys are stored in the database. In a production environment, integration with a KMS (Key Management Service) or HSM (Hardware Security Module) is highly recommended.

📜 License

MIT License