initial commit

2026-05-29 22:39:50 -05:00
commit 47c767f9e8
23 changed files with 3361 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Scratchbox Pastebin
+
+Scratchbox is a minimal self-hosted pastebin 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. Copy the sample config:
+   - `cp config.example.yaml config.yaml`
+2. Adjust settings for your environment.
+3. Start the server:
+   - `go run ./cmd/pastebin -config config.yaml`
+4. Open:
+   - `http://127.0.0.1:8080/`
+
+Without `-config`, built-in defaults are used.
+
+## Configuration
+
+All configuration is YAML.
+
+### `server`
+
+- `listen_addr`: address for the HTTP server (required).
+  - Default: `:8080`
+
+### `limits`
+
+- `max_upload_size`: max request body size for uploads.
+  - Examples: `5MB`, `100MB`, `1GiB`
+  - Default: `100MB`
+- `default_ttl`: expiration applied to new scratches.
+  - Must be `> 0` and `<= 24h`
+  - Default: `1h`
+
+### `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`
+  - Empty list means no allowlist restriction
+- `trust_proxy_headers`: if `true`, client IP extraction honors `X-Forwarded-For` then `X-Real-IP`.
+  - Keep `false` unless behind a trusted reverse proxy that sets these headers.
+- `rate_limit.enabled`: enable per-IP token-bucket rate limiting on write route.
+  - 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.