Terminus: The Digital Time Capsule

Terminus is a hybrid Web3 full-stack application that acts as a cryptographically secure Digital Time Capsule. It leverages Ethereum Smart Contracts (via Ganache) to natively enforce trustless time-locks, combined with intense End-to-End Asymmetric Encryption (E2EE) to ensure that intercepted documents remain absolutely inaccessible until the exact temporal conditions are met on the blockchain.

Architecture

1. Smart Contract (TimeCapsule.sol): Deployed securely to the blockchain. Natively enforces block.timestamp checks.
2. Backend API (app.py): A Flask interface handling Python SQLite routing, user Auth (JWT), temporary payload caching, and direct connection to the Web3 smart contract.
3. Frontend (frontend/): A sleek, brutalist Web2 React application utilizing node-forge to actively encrypt massive data payloads securely inside the user's browser before transmitting them to the backend API.

Advanced Cryptography Workflow

• Registration: The backend generates an RSA Keypair for users. The Private Key is encrypted using PBKDF2/AES-GCM mapped precisely to the user's password.
• Sealing: The system generates a highly optimized symmetric AES key to lock your attached documents. That specific AES key is then encrypted using the Recipient’s Public RSA Key.
• Opening: Only the targeted Recipient can unlock their specific payload, and only after the Ganache block-timer hits zero.

---

Detailed Setup Instructions

To run this application locally, you must instantiate three connected services: the blockchain, the backend API, and the frontend web server.

Prerequisites

• Node.js & NPM installed
• Python 3.10+ installed
• Ganache CLI (npm install -g ganache)

Step 1: Initialize the Local Blockchain

Open your first terminal window. You need a fast, local EVM (Ethereum Virtual Machine) running.

# Start the Ganache chain. It will bind to 127.0.0.1:8545
ganache

Step 2: Configure the Python Backend

Open a second terminal window. Initialize the Python environment, install the dependencies, and start the API wrapper.

# 1. Create a virtual environment
python -m venv venv

# 2. Activate the environment (Linux/Mac)
source venv/bin/activate
# Or on Windows: venv\Scripts\activate

# 3. Install packages
pip install -r requirements.txt

# 4. Start the Application
python app.py

Note: Upon boot, Flask will actively compile the Solidity Contract, generate the SQLite capsule.db, and mount the local REST infrastructure.

Step 3: Run the React Frontend

Open a third terminal window. This initializes the React/Vite development server where you can interact visually with the smart contract.

# Navigate to the frontend directory
cd frontend

# Install node dependencies
npm install

# Start the Vite environment
npm run dev

Step 4: Interact

Navigate to http://localhost:5173/ in any modern browser. Register unique accounts (e.g., Alice, Bob) across separate incognito windows to test deploying and unlocking secure P2P Digital Time Capsules!

Docker

The repository now includes a production-oriented Docker Compose setup with:

• Flask served through uvicorn using an ASGI wrapper.
• React built by Vite and served by nginx.
• nginx reverse proxying /api and /auth to the backend so the browser uses same-origin requests.
• Ganache running as a Compose service for local blockchain state.

Build and start the stack with:

docker compose up --build

The app will be available at http://localhost:8080/.

For direct backend access during debugging, the Flask service still listens on port 5000 inside the Compose network, and the backend honors DATABASE_URL, UPLOAD_FOLDER, WEB3_PROVIDER_URI, and JWT_SECRET_KEY environment variables.

Docker Setup Quick Reference

If you only want the production stack:

docker compose up --build

Open http://localhost:8080 for the app and http://localhost:8545 if you want to inspect Ganache directly.

Optional environment variables can be provided through a local .env file at the repo root, for example:

JWT_SECRET_KEY=replace-me