README.md

SecureGist Backend

A robust, asynchronous FastAPI backend for SecureGist, designed to store encrypted code snippets securely. It uses PostgreSQL for persistence and implements expiration and access limit logic.

🚀 Features

• Encrypted Storage: Stores only encrypted blobs (UUID, BYTEA, JSONB). The backend never sees plaintext.
• Access Control: Supports "burn after reading" (max reads) and time-based expiration.
• High Performance: Built with FastAPI, SQLAlchemy (async), and asyncpg.
• Production Ready: structured in a src package layout with comprehensive testing.
• Schema Migrations: Uses Alembic for database versioning and upgrades.
• Modern Tooling: Uses uv for fast dependency management.

🛠 Prerequisites

• Python: 3.14+
• Package Manager: uv (recommended) or pip.
• Database: PostgreSQL 16+

📦 Installation

1. Clone the repository:

   git clone https://github.com/Derad6709/SecureGist
   cd securegist/backend

2. Configure Environment: Copy the example environment file and update it with your database credentials.

   cp .env.example .env

   Ensure DATABASE_URL in .env points to your running PostgreSQL instance.

3. Install Dependencies: Using uv (faster, recommended):

   uv sync

🗄️ Database Setup

The application uses Alembic migrations instead of auto-creating tables at startup. Ensure your PostgreSQL server is running and the database defined in DATABASE_URL exists, then apply the schema with:

alembic upgrade head

If using Docker:

docker-compose up -d db

The backend container also runs alembic upgrade head before starting Uvicorn.

▶️ Running the Server

Start the development server with auto-reload:

Using uv:

uv run uvicorn src.main:app --reload

Using standard python/pip:

Before starting the server, apply migrations:

alembic upgrade head

The API will be available at http://localhost:8000.

🧪 Testing

Automated Tests

This project uses pytest for unit and integration testing. Tests cover schemas, API endpoints, read limits, and expiration logic.

Run tests using uv:

uv run pytest

Manual Testing (Postman)

A Postman collection is included for interactive testing.

1. Open Postman.
2. Import securegist.postman_collection.json.
3. Run the requests. The collection includes scripts to automatically handle variables (like gist_id).
   • Create Gist: Creates a standard gist.
   • Create Gist (Max Reads=1): Creates a gist that can be read only once.
   • Get Gist: Retrieves the gist (increments counter).
   • Get Gist (Limited): Verify access limits.
   • Delete Gist: Manually remove a gist.

📚 API Documentation

Interactive API documentation is automatically generated by FastAPI:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📂 Project Structure

backend/
├── src/                # Application source code
│   ├── api.py          # API endpoints
│   ├── crud.py         # Database operations
│   ├── db.py           # Database connection setup
│   ├── dependencies.py # Dependency injection (get_db)
│   ├── main.py         # App entry point
│   ├── models.py       # SQLAlchemy ORM models
│   └── schemas.py      # Pydantic schemas
├── alembic/            # Database migrations
├── alembic.ini         # Alembic configuration
├── tests/              # Test suite
│   ├── conftest.py     # Pytest configuration & fixtures
│   ├── test_api.py     # Integration tests
│   └── test_schemas.py # Unit tests
├── .env                # Environment variables (not committed)
├── docker-compose.yml  # Docker config for DB
├── pyproject.toml      # Project configuration (uv)
└── securegist.postman_collection.json # Postman tests