ScratchBack PDS - Introduction#

Overview#

ScratchBack PDS is a zero-knowledge Personal Data Store (PDS) implementing ATProtocol standards using rsky. This service provides cloud storage for itch.io game saves with GDPR compliance, conditional mobile sync, Age encryption, and support for both Bunny Storage and DigitalOcean Spaces.

Problem Statement#

itch.io game developers need a secure, GDPR-compliant cloud storage solution for player saves with:

Zero-knowledge architecture (server cannot decrypt user data)
GDPR compliance with EU data localization
Cost-effective storage with multiple backend options
Mobile-first with conditional sync
Admin controls for system management

Solution#

A PDS built on:

ATProtocol: Standards-based protocol for decentralized data storage
rsky: Rust implementation of ATProtocol PDS with SQLite backend
Axum: Modern web framework for HTTP/XRPC endpoints
Age Encryption: Zero-knowledge client-side encryption
Dual Storage Backends: Bunny Storage + DigitalOcean Spaces
HTMX: Server-side rendered web UI for admin controls

Key Features#

2GB default quota per user (soft limits at 80%, cumulative tracking)
GDPR-compliant automatic region routing (EU users → EU storage)
Real-time cost calculation (cached for 1 hour)
Passkey authentication (terminal-only setup with QR codes)
Session-based web UI (7-day expiration)
Country consent flow with GDPR alerts
Admin CLI (scrtchbk-ctl) for system management
Soft deletion with 14-day retention
Deployment metadata generated fresh at every startup
Age encryption for passkeys database (synced to Bunny Storage)

Technology Stack#

Rust 2021 edition
Axum 0.7 (web framework)
Diesel 2.1 (ORM)
SQLite (database via rsky)
minijinja 2.0 (templates)
age 0.11 (encryption)
cached 0.1 (memoization)
webauthn-rs 0.5 (passkey)
aws-sdk-s3 1.20 (Bunny/DigitalOcean)
maxminddb 0.24 (GeoIP)

Architecture Decisions#

Separate databases:
- Main database: user_quotas, blobs, sessions, ntfy_subscriptions
- Passkeys database: passkeys table (age-encrypted, synced to Bunny Storage)
GDPR routing:
- EU users: Stored in EU data centers (Bunny frankfurt / DO fra1)
- Non-EU users: Stored in US data centers (Bunny us / DO nyc3)
- Country detection: GeoLite2 database (configurable path via env var)
Authentication methods:
- XRPC: JWT tokens (24-hour expiration)
- Admin CLI: Passkey (terminal-only, QR code registration)
- Web UI: Session cookies (7-day expiration, HTTP-only, Secure, SameSite=Lax)
Cost management:
- Real-time API calls to Bunny/DigitalOcean
- 1-hour cache using cached proc macro
- Background refresh task (tokio)
- Individual + combined cost calculations cached
Deployment:
- Static binaries via build.sr.ht
- Deployment metadata generated fresh at startup (not from CI/CD)
- VPS deployment to Hetzner

Project Structure#

/home/vrgl/Code/scratch-itch/
├── mise.toml                    # Pinned direnv + age
├── Cargo.toml                   # Workspace root
├── .env.age                     # Encrypted secrets
├── config.toml                  # Default configuration
├── deployment-info.json           # Deployment metadata (generated)
├── build.sr.ht                  # Build configuration
├── Cargo.lock
├── src/
│   ├── main.rs
│   ├── config/
│   ├── storage/
│   ├── quota/
│   ├── auth/
│   ├── xrpc/
│   ├── web/
│   ├── deployment/
│   ├── cost_cache/
│   ├── models/
│   └── error.rs
├── migrations/                   # Diesel migrations (main DB)
├── passkeys-migrations/          # Diesel migrations (passkeys DB)
├── static/
│   ├── css/
│   └── js/
└── cli/                         # scrtchbk-ctl binary
    ├── Cargo.toml
    └── build.sr.ht

Documentation#

Implementation Timeline#

Phase 1: Foundation
Phase 2: Configuration System
Phase 3: Storage Layer
Phase 4: Passkey Storage
Phase 5: Quota System
Phase 6: Cost Cache
Phase 7: Authentication
Phase 8: Deployment Tracking
Phase 9: XRPC Endpoints
Phase 10: Web UI
Phase 11: Admin CLI
Phase 12: Testing & Deployment

Configure Feed