Hono & Cloudflare Workers

🌐 Backend Architecture: Hono & Cloudflare Workers

The Freak-Flix backend is a lightweight, high-performance API built with the Hono framework and deployed on Cloudflare Workers. It leverages Cloudflare D1 as a serverless SQL database to manage user profiles and library metadata, and provides a proxy layer to handle cross-origin (CORS) requests for third-party integrations like Microsoft OneDrive.

🛠️ Configuration & Environment

To deploy or interface with the backend, the following environment bindings are required:

| Binding | Type | Description | | :--- | :--- | :--- | | DB | D1 Database | The primary SQL database for users and library storage. | | JWT_SECRET | Secret | A secure string used to sign and verify authentication tokens. |

🔑 Authentication API

All authentication endpoints return standard JSON responses. Protected routes require a Bearer token in the Authorization header.

POST /auth/register

Creates a new user account.

• Request Body:

  {
    "email": "user@example.com",
    "password": "your-password"
  }
  

• Response (200): { "ok": true, "id": "uuid", "email": "user@example.com" }

POST /auth/login

Authenticates a user and issues a JWT.

• Request Body:

  {
    "email": "user@example.com",
    "password": "your-password"
  }
  

• Response (200):

  {
    "token": "eyJhbG...",
    "user": { "id": "uuid", "email": "user@example.com", "created_at": "timestamp" }
  }
  

GET /auth/me

Verifies the current session and returns user metadata.

• Headers: Authorization: Bearer <token>
• Response (200): { "user": { "sub": "id", "email": "user@example.com", "exp": 12345 } }

---

📂 Library Management

The library API facilitates the scanning of remote cloud storage and local directory indexing.

POST /library/scan

Triggers a background recursive scan of a specific provider folder.

• Headers: Authorization: Bearer <token>
• Request Body:

  {
    "folderId": "onedrive-folder-id",
    "accessToken": "microsoft-graph-token",
    "path": "/Movies",
    "provider": "onedrive"
  }
  

• Behavior: This endpoint utilizes Cloudflare’s ctx.waitUntil() to perform the scan asynchronously, allowing the request to return immediately while the database populates in the background.

---

🛰️ Proxy Services

To bypass browser CORS restrictions and secure API keys, the backend acts as a transparent proxy for external services.

Microsoft Identity Proxy

Used for OAuth2 flows with Microsoft OneDrive.

• Endpoint: /microsoft/proxy/*
• Usage: Replace https://login.microsoftonline.com/ with <your-worker-url>/microsoft/proxy/ in your authentication requests.
• Example: POST /microsoft/proxy/common/oauth2/v2.0/token

StashDB Proxy (Netlify/Alternative)

While the core Hono worker handles Auth and OneDrive, separate proxy functions exist to interface with StashDB for adult metadata, ensuring that ApiKey headers are handled securely and CORS is managed for the web client.

---

🏗️ Local Development

To run the Hono backend locally using Wrangler:

1. Navigate to the backend directory: cd backend
2. Install dependencies: npm install
3. Initialize the local D1 database:

   npx wrangler d1 execute freak-flix-db --file=./schema.sql --local
   

4. Start the dev server:

   npm run dev
   

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