# CypherLegacy Backend

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](https://fastapi.tiangolo.com/)
- **Database**: [PostgreSQL](https://www.postgresql.org/) (via `asyncpg` async driver)
- **ORM**: [SQLAlchemy 2.0](https://www.sqlalchemy.org/) (AsyncIO)
- **Encryption**: [Cryptography](https://cryptography.io/) & [PyCryptodome](https://pycryptodome.org/) (RSA Encryption)
- **Authentication**: [python-jose](https://github.com/mpdavis/python-jose) (JWT Tokens) & Passlib (Bcrypt/Argon2)
- **Request Client**: [HTTPX](https://www.python-httpx.org/) (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.

```bash
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:
```bash
python3 test/test_scenario.py
```

### 2. Local Manual Setup

1. **Environment Setup**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   # or venv\Scripts\activate on Windows
   pip install -r requirements.txt
   ```

2. **Configuration**:
   Create a `.env` file or set the `DATABASE_URL` environment variable. Default:
   `postgresql+asyncpg://user:password@localhost:5432/fastapi_db`

3. **Database Initialization**:
   ```bash
   python reset_db.py
   ```

4. **Run Service**:
   ```bash
   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

1. **End-to-End Principles**: Sensitive assets are encrypted before storage.
2. **State Verification**: Claim logic strictly validates the `heir_id` and the `deceased` status of the owner.
3. **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