warpbox-dev/PLANS.md

Warpbox Plans & Staged Development

This document captures the staged development history and roadmap for Warpbox. For day-to-day usage, configuration, and deployment, see README.md.

Stage 2 — Operator Tools

• /admin/login - token-based admin login.
• /admin - overview metrics: boxes, files, storage, recent uploads, protected/expired boxes.
• /admin/files - recent upload table with view and delete actions.
• Expired boxes and boxes that have reached their download limit are cleaned on startup and then every WARPBOX_CLEANUP_EVERY when WARPBOX_CLEANUP_ENABLED=true.
• Missing image/video thumbnails are generated in a background worker every WARPBOX_THUMBNAIL_EVERY when WARPBOX_THUMBNAIL_ENABLED=true.

Stage 3 — Anonymous Integrations

Anonymous uploads return a private management link at creation time. Keep that link secret: anyone with it can delete the entire upload box. The raw delete token is not stored and cannot be recovered later.

Browser uploads still show Open box and Copy URL as the primary actions, with a smaller Manage or delete this upload link in the completion panel.

Curl and custom uploaders can use the same endpoint:

# Terminal-friendly output: one plain box URL.
curl -F file=@./report.pdf http://localhost:8080/api/v1/upload

# JSON output with boxUrl, thumbnailUrl, manageUrl, deleteUrl, zipUrl, and file entries.
curl -F sharex=@./screenshot.png \
  -H 'Accept: application/json' \
  http://localhost:8080/api/v1/upload

The upload endpoint accepts multipart fields named file and sharex. ShareX users can start from examples/sharex/warpbox-anonymous.sxcu; update RequestURL to match your instance URL. Authenticated uploads (your account's limits) add an Authorization: Bearer <token> header — mint a token under Account → Access tokens. The JSON response uses ShareX placeholders {json:boxUrl} (URL), {json:thumbnailUrl} (thumbnail), {json:deleteUrl} (deletion), and {json:error} (error message).

Grouping multiple files into one box (X-Warpbox-Batch)

By default every uploaded file becomes its own box. To put several files in a single box, send the opt-in X-Warpbox-Batch header: requests that share the same header value (scoped per account, or per IP for anonymous uploads) within 20s are appended to the same box. This lets a multi-file ShareX selection — which ShareX sends as separate back-to-back requests — land as one shareable link. The shipped .sxcu sets X-Warpbox-Batch: sharex; remove that header for one box per file. Requests without the header behave exactly as before.

Resumable API flow

Custom clients can use the resumable JSON API for large files:

# 1. Create a resumable session from file metadata.
curl -s http://localhost:8080/api/v1/uploads/resumable \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"name":"large.bin","size":1048576,"contentType":"application/octet-stream"}],"expiresMinutes":1440}'

# 2. Upload exact-sized chunks using the returned sessionId, file id, and chunkSize.
dd if=./large.bin bs=8388608 count=1 skip=0 2>/dev/null | \
  curl -X PUT --data-binary @- \
  http://localhost:8080/api/v1/uploads/resumable/SESSION_ID/files/FILE_ID/chunks/0

# 3. Complete the session after all chunks are present.
curl -X POST -H 'Accept: application/json' \
  http://localhost:8080/api/v1/uploads/resumable/SESSION_ID/complete

The complete response is the same JSON shape as POST /api/v1/upload, including boxUrl, manageUrl, deleteUrl, and file URLs. Send Authorization: Bearer <token> on every resumable request to upload as an account.

Browser resumable uploads are configurable from /admin/settings: enabled/disabled, chunk size in MB, draft retention hours, and chunk staging location. The default chunk mode stores temporary draft chunks under data/tmp/uploads/{session_id}. A custom mode can point those chunks at another local path, such as a mounted fast SSD. Chunk staging stays local even when the completed files are later finalized into S3/SFTP/SMB/WebDAV storage. Completion returns the share link immediately; files may show as Processing on the download page while the background finalizer streams them to the selected storage backend. Cleanup removes expired uploading drafts but skips sessions already in processing.

Stage 4 — Accounts + Personal Boxes

• /register bootstraps the first admin account only when no users exist.
• /login and /logout provide cookie-based web sessions.
• /app is the personal dashboard for logged-in users, showing owned boxes, storage usage, upload history, and flat collections. Uploading still happens from the homepage.
• /admin/users lets admins create invite links, disable/reactivate users, and generate reset links.
• Logged-in browser uploads from / still use POST /api/v1/upload, but the resulting box is stored with owner and optional collection metadata.
• Admin users are exempt from the global max upload size on the homepage upload flow. Future per-user quotas should apply to this same upload path rather than creating a second uploader.
• /admin/settings controls anonymous uploads, anonymous max upload size, daily upload caps, default user storage quota, and usage retention.
• /admin/users shows storage/daily usage and lets admins set per-user storage quota overrides.
• /admin/storage manages the built-in local file backend and S3-compatible bucket backends.
• /admin/bans manages manual IP/CIDR bans and optional automatic bans for suspicious probes and repeated login failures. Auto-ban is off by default and configured from the admin UI.
• Upload limits now include daily bytes, daily box counts, active box counts, short-window request limits, max expiration days, local storage capacity in GB, and per-user policy overrides.
• Uploaded file content, thumbnails, and private box metadata use the selected storage backend. The bbolt database and JSON logs remain local under ./data/db and ./data/logs.
• Anonymous uploads, ShareX uploads, unlisted public box links, password protection, expiry, delete tokens, thumbnails, and cleanup continue to work as before.

Email delivery is intentionally deferred. Invite and reset links are copyable today; future SMTP support will power public forgot-password and optional email delivery.