scratchbox/README.md

# Scratchbox

Scratchbox is a minimal self-hosted scratch service written in Go. It is intentionally unauthenticated and optimized for temporary sharing of text or small files with an expiration time.

Each upload creates exactly one scratch. For multi-file sharing, bundle files into an archive (for example `.zip` or `.tar.gz`) and upload that single archive file.
Scratch content is stored on disk gzip-compressed transparently to reduce filesystem usage; API/UI reads return original uncompressed content.

## Quick Start

1. Generate defaults directly:
   - `go run ./cmd/scratchbox generate-config > config.yaml`
2. Adjust settings for your environment.
3. Start the server:
   - `go run ./cmd/scratchbox server --config config.yaml`
4. Open:
   - `http://127.0.0.1:8080/`

Without `--config`, built-in defaults are used.

If you modify the web UI source (`web/ui`), rebuild frontend assets with:
- `make build`

## Configuration

All configuration is YAML.

### `server`

- `listen_addr`: address for the HTTP server (required).
  - Default: `:8080`
- `read_header_timeout`: maximum time for reading request headers.
  - Must be `> 0`
  - Default: `5s`
- `read_timeout`: maximum time for reading the full request.
  - Must be `> 0`
  - Default: `30s`
- `write_timeout`: maximum time allowed for writing the response.
  - Must be `> 0`
  - Default: `30s`
- `idle_timeout`: maximum keep-alive idle time between requests.
  - Must be `> 0`
  - Default: `120s`
- `max_header_bytes`: max HTTP header size in bytes.
  - Must be `> 0`
  - Default: `1048576` (1 MiB)

### `limits`

- `max_upload_size`: max request body size for uploads.
  - Supported units: `B`, `KB`, `MB`, `GB`, `KiB`, `MiB`, `GiB` (case-insensitive)
  - If no unit is provided, value is interpreted as bytes
  - Examples: `5MB`, `100MiB`, `1GiB`, `1048576`
  - Default: `100MiB`
- `default_ttl`: expiration applied to new scratches.
  - Must be `> 0` and `<= 24h`
  - Default: `1h`
- `raw_cache_max_size`: max total decompressed bytes cached in memory for `/api/raw` range requests.
  - Supported units: `B`, `KB`, `MB`, `GB`, `KiB`, `MiB`, `GiB` (case-insensitive)
  - Must be `> 0`
  - Default: `200MiB`
- `raw_cache_max_entries`: max number of decompressed `/api/raw` entries kept in memory.
  - Must be `> 0`
  - Used together with `raw_cache_max_size` as a secondary cap
  - Default: `32`

### `storage`

- `data_dir`: directory for scratch files and metadata index.
  - Default: `./data`
- `cleanup_interval`: background interval for deleting expired content.
  - Must be at least `10s`
  - Default: `1m`

### `security`

- `allowed_ips`: optional list of IPs and CIDRs allowed to create scratches.
  - Applies to write route only: `POST /api/scratch`
  - Default includes `127.0.0.1` (localhost-only write access)
  - Add trusted IPs/CIDRs for LAN/proxy clients (for example `192.168.1.0/24`)
  - Empty list means no allowlist restriction
- `trust_proxy_headers`: if `true`, client IP extraction honors `X-Forwarded-For` then `X-Real-IP`.
  - Only used when source IP matches `trusted_proxy_ips`.
  - Keep `false` unless behind a trusted reverse proxy that sets these headers.
- `trusted_proxy_ips`: list of reverse-proxy IPs/CIDRs permitted to supply forwarded headers.
  - Required when `trust_proxy_headers: true`
  - Examples: `127.0.0.1`, `10.0.0.0/8`
- `rate_limit.enabled`: enable per-IP token-bucket rate limiting on write and scratch-read routes (`POST /api/scratch`, `GET /api/scratch/{id}`, `GET /s/{id}`, `GET /api/raw/{id}`).
  - Default: `true`
- `rate_limit.requests_per_minute`: steady refill rate per client IP.
  - Must be `> 0`
  - Default: `30`
- `rate_limit.burst`: immediate burst capacity per client IP.
  - Must be `> 0`
  - Default: `10`

## Security Posture

This service is intentionally unauthenticated. Anyone with network access can read scratches, and (unless restricted) create scratches.

- No authentication, user accounts, or moderation controls.
- No malware scanning.
- Abuse controls are limited to upload size limits, TTL expiration, optional IP allowlisting, and write-route rate limiting.
- Treat this as a convenience utility, not a hardened internet-facing platform.

## LAN Deployment Notes

For home/lab/LAN-only use:

- Bind to a private address, for example `127.0.0.1:8080` (single host) or `192.168.x.x:8080`.
- Use `allowed_ips` to restrict write access to trusted subnets.
- Keep `max_upload_size` and `default_ttl` small.
- Keep `trust_proxy_headers` disabled unless using a trusted reverse proxy.

## Public Deployment Notes

If exposed beyond a trusted LAN, place a reverse proxy in front (Nginx, Caddy, Traefik, etc.) and add external controls:

- TLS termination and strict transport settings.
- Additional request filtering/WAF controls.
- Stronger rate limits at the edge.
- Optional network-level restrictions to write route.
- Monitoring and log retention suitable for abuse triage.

Recommended baseline: run behind a reverse proxy, keep low TTL and size limits, and use `allowed_ips` for write access whenever possible.

## Storage Model

Scratchbox storage is designed for a single process instance per `storage.data_dir`.

- Do not run multiple scratchbox processes against the same data directory.
- Metadata/index writes are process-local and are not coordinated with cross-process locking.