# scrybe-backend

**Repository Path**: oliver-queen/scrybe-backend

## Basic Information

- **Project Name**: scrybe-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Scrybe Backend

Flask API for Scrybe's end-to-end encrypted bookmark and history sync.

The backend stores opaque encrypted records. Record titles, URLs, favicons, and history timestamps are encrypted by the extension before upload. The server only sees account IDs, device IDs, item IDs, collection names, revision timestamps, and ciphertext envelopes.

## Modes

Scrybe uses `SHADOWEB_DEBUG` to choose the database backend:

- `SHADOWEB_DEBUG=true`, after `.strip().lower()`: debug mode, SQLite.
- Any other value or missing env var: production mode, MySQL.

## Debug Run

```bash
export SHADOWEB_DEBUG=true
python3.14t -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
flask --app scrybe.app:create_app run
```

For local development with an existing Python 3.13/3.14 build:

```bash
export SHADOWEB_DEBUG=true
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
flask --app scrybe.app:create_app run
```


## Docker Compose Production Run

The backend can be deployed with Docker Compose using the included MySQL service. The Docker image uses `python:3.14-alpine`. Production mode is the default because `SHADOWEB_DEBUG` is not set; only `SHADOWEB_DEBUG=true` enables SQLite debug mode.

```bash
cp .env.example .env
# edit .env and replace the example passwords
docker compose up -d --build
```

The API is exposed on `http://127.0.0.1:5000` by default. Change `SCRYBE_BACKEND_PORT` in `.env` if another host port is needed. MySQL data is stored in the `mysql-data` Docker volume.

For production, run this behind a reverse proxy that terminates TLS for `https://scrybe-api.shadoweb.fr` or your own backend domain.

## Production Run

Production mode uses MySQL through `mysql-connector-python` connection pooling:

```bash
unset SHADOWEB_DEBUG
export SCRYBE_MYSQL_HOST=mysql
export SCRYBE_MYSQL_PORT=3306
export SCRYBE_MYSQL_DATABASE=scrybe
export SCRYBE_MYSQL_USER=scrybe
export SCRYBE_MYSQL_PASSWORD='change-me'
export SCRYBE_MYSQL_POOL_SIZE=20
flask --app scrybe.app:create_app run
```

Configuration is environment based:

- `SHADOWEB_DEBUG`: set to `true` for SQLite debug mode.
- `SCRYBE_DB`: SQLite database path, defaults to `instance/scrybe.sqlite3`.
- `SCRYBE_MYSQL_HOST`: production MySQL host, defaults to `mysql`.
- `SCRYBE_MYSQL_PORT`: production MySQL port, defaults to `3306`.
- `SCRYBE_MYSQL_DATABASE`: production MySQL database, defaults to `scrybe`.
- `SCRYBE_MYSQL_USER`: production MySQL user, defaults to `scrybe`.
- `SCRYBE_MYSQL_PASSWORD`: production MySQL password.
- `SCRYBE_MYSQL_POOL_SIZE`: production MySQL pool size, defaults to `10`.
- `SCRYBE_PAIRING_TTL_SECONDS`: pairing-code lifetime, defaults to `300`.
- `SCRYBE_CORS_ORIGINS`: CORS allow-list, defaults to `*` for extension development.
- `SCRYBE_LOG_LEVEL`: application log level, defaults to `INFO`.

## API

- `POST /v1/accounts`: creates an anonymous account and first device.
- `GET /v1/sync`: returns encrypted bookmark/history records.
- `PUT /v1/items/<collection>/<item_id>`: upserts an encrypted record.
- `DELETE /v1/items/<collection>/<item_id>`: marks an encrypted record as deleted.
- `POST /v1/pairing`: creates a pairing code for an authenticated device.
- `POST /v1/pairing/<pairing_id>/bootstrap`: attaches encrypted key bootstrap material.
- `POST /v1/pairing/claim`: claims a code from a new browser and receives bootstrap material.
- `PUT /v1/recovery`: stores/replaces encrypted recovery bootstrap material for an authenticated account.
- `POST /v1/recovery/claim`: recovers an account with a recovery code and creates a new device.