WarpBox/admin-overview.md

WarpBox Admin Overview

This document maps the current WarpBox admin area, explains how the existing pages and permission model work, then proposes an overhaul path for a more useful admin product: dashboard, account management, API keys, and a role/group based authorization system.

Project Context

WarpBox is a small self-hosted file sharing app. Its core product is deliberately simple:

• create temporary upload boxes
• upload one or more files
• optionally protect the box with a password
• share a generated link
• allow individual downloads or ZIP downloads
• support one-time ZIP handoff
• store uploads on the local filesystem
• store app metadata in local BadgerDB

The project has a strong retro desktop identity. The admin area should keep that personality, but become more operationally useful. Best direction: retro surface, modern information architecture. Admin actions should feel clear, forgiving, and inspectable rather than dense or mysterious.

Current Admin Architecture

Admin routes are registered under /admin in lib/server/admin.go.

Current pages:

• /admin/login
• /admin
• /admin/boxes
• /admin/users
• /admin/tags
• /admin/settings

Admin templates live in:

• templates/admin_login.html
• templates/admin.html
• templates/admin_boxes.html
• templates/admin_users.html
• templates/admin_tags.html
• templates/admin_settings.html

Styling uses:

• static/css/admin.css
• shared retro UI styles from static/css/app.css and static/css/window.css

Metadata lives in BadgerDB through lib/metastore. Current admin-relevant records are:

• users
• tags
• sessions
• settings overrides

Current Login And Session Flow

Admin login is bootstrapped from environment configuration:

• WARPBOX_ADMIN_PASSWORD
• WARPBOX_ADMIN_USERNAME
• WARPBOX_ADMIN_EMAIL
• WARPBOX_ADMIN_ENABLED

On startup, BootstrapAdmin ensures a protected admin tag exists. If a user matching the admin username already exists, the admin tag is attached to that user. If no user exists and WARPBOX_ADMIN_PASSWORD is set, a first admin user is created.

Login behavior:

• GET /admin/login shows login form when admin login is enabled.
• POST /admin/login checks username/password.
• password hashes use bcrypt.
• disabled users cannot log in.
• user must have effective AdminAccess.
• successful login creates a BadgerDB session with random session token and CSRF token.
• session cookie name is warpbox_admin_session.
• cookie path is /admin.
• cookie is HTTP-only.
• cookie Secure flag is controlled by WARPBOX_ADMIN_COOKIE_SECURE.
• session TTL is controlled by WARPBOX_SESSION_TTL_SECONDS.

All protected admin routes require:

• valid session cookie
• unexpired session
• valid CSRF token for non-GET requests
• existing enabled user
• effective AdminAccess

Admin responses set no-store headers and X-Content-Type-Options: nosniff.

Current Dashboard Page

Route:

• GET /admin

Template:

• templates/admin.html

Current behavior:

• shows signed-in username
• provides logout button
• shows four large links:
  • Boxes
  • Users
  • Tags
  • Settings

Current limitation:

• this is not a dashboard yet. It has no statistics, recent activity, health status, quota information, user counts, storage totals, warnings, or next actions.

Good future role:

• make this the admin home screen, with live operational summary and clear links into deeper management pages.

Current Boxes Page

Route:

• GET /admin/boxes

Required permission:

• AdminBoxesView

Current behavior:

• loads all box summaries from filesystem via boxstore.ListBoxSummaries()
• shows summary counters:
  • total boxes
  • total storage
  • expired boxes
• table columns:
  • box id
  • file count
  • size
  • created time
  • expiry time
  • flags
• flags include:
  • expired
  • one-time
  • password
• box id links to /box/{id}

Current limitations:

• no search
• no filters
• no pagination
• no delete action
• no bulk cleanup
• no storage trend
• no per-box detail drawer
• no visibility into failed uploads, incomplete boxes, thumbnail state, or one-time consumption state
• expired boxes are counted but not directly actionable

Good future role:

• operational file-sharing monitor and cleanup center.

Current Users Page

Routes:

• GET /admin/users
• POST /admin/users

Required permission:

• AdminUsersManage

Current behavior:

• create user with username, email, password, and selected tags
• list users sorted by username
• show username, email, assigned tags, created time, status
• enable/disable user
• active session user cannot disable themselves

Current user model:

• ID
• Username
• Email
• PasswordHash
• TagIDs
• CreatedAt
• UpdatedAt
• Disabled
• optional per-user max file size
• optional per-user max box size
• optional per-user max expiry seconds

Current limitations:

• no edit user page
• no password reset flow
• no email verification or invite flow
• no delete/archive user action
• no user detail screen
• no role preview
• no effective permissions display
• no API key management
• no account activity
• no per-user storage/upload stats
• per-user limit fields exist in the model but are not exposed in the admin UI

Good future role:

• user account command center, optimized for quick scanning, safe edits, and permission clarity.

Current Tags Page

Routes:

• GET /admin/tags
• POST /admin/tags

Required permission:

• AdminUsersManage

Current behavior:

• create a tag
• set description
• attach permission booleans
• attach optional limits
• list existing tags
• built-in admin tag is protected and forced to full admin permissions

Current tag permissions:

• upload allowed
• one-time download allowed
• ZIP download allowed
• renewable allowed
• admin access
• manage users
• manage settings
• view boxes
• max file size bytes
• max box size bytes
• allowed expiry seconds
• renew on access seconds exists in model but is not exposed in current tag form
• renew on download seconds exists in model but is not exposed in current tag form

Permission resolution:

• user permissions are resolved from all assigned tags plus user-level overrides
• boolean permissions are additive: any tag can grant a permission
• size limits use the more permissive value
• global max file/box limits still cap resolved user limits
• allowed expiry seconds are merged from all tags and sorted
• global feature flags can still disable ZIP or one-time downloads even if a tag allows them

Current limitations:

• tags mix labels, roles, groups, limits, and admin capability grants in one concept
• no edit tag page
• no delete tag action
• no user count per tag
• no permission preview
• no conflict detection
• no clear distinction between "role grants access" and "plan defines quotas"
• permission logic is powerful but hard to explain to administrators

Good future role:

• replace tags with explicit roles/groups/plans. Keep old tags only as migration input.

Current Settings Page

Routes:

• GET /admin/settings
• POST /admin/settings

Required permission:

• AdminSettingsManage

Current behavior:

• shows configured settings table
• columns:
  • setting
  • value
  • source
  • environment variable name
• editable values can be overridden from admin UI when WARPBOX_ALLOW_ADMIN_SETTINGS_OVERRIDE=true
• overrides are stored in BadgerDB
• runtime config is updated after save

Editable settings currently include:

• guest uploads enabled
• API enabled
• ZIP downloads enabled
• one-time downloads enabled
• one-time download expiry seconds
• renew on access enabled
• renew on download enabled
• default guest expiry seconds
• max guest expiry seconds
• default user max file size bytes
• default user max box size bytes
• session TTL seconds
• box poll interval milliseconds
• thumbnail batch size
• thumbnail interval seconds

Non-editable/hard settings include:

• data directory
• global max file size bytes
• global max box size bytes
• one-time download retry on failure

Current limitations:

• settings are presented as raw technical rows
• no grouping
• no descriptions
• no validation hints beyond backend errors
• byte fields require raw bytes
• duration fields require raw seconds/milliseconds
• no "restart required" or "runtime applied" distinction beyond current editability
• no audit trail for setting changes

Good future role:

• organized system configuration, with human units, clear safety boundaries, and change history.

Current API Key State

There is visible API key UX in the upload page:

• "Use API key for larger quota"
• API key input
• local validation with regex
• value saved locally in browser localStorage
• cURL command includes Authorization: Bearer YOUR_API_KEY when enabled

Important current reality:

• no backend API key model was found
• no API key generation route was found
• no server-side Authorization bearer validation was found
• no per-user API key ownership or revocation exists yet
• no current upload flow applies user permissions from an API key

So API keys are a product placeholder, not a functional feature yet.

Main Current Gaps

• Dashboard is only navigation.
• User management only creates and disables accounts.
• Tags are doing too many jobs.
• API keys are UI-only.
• Admin pages lack search, filters, pagination, and detail views.
• No audit log.
• No admin-visible system health.
• No storage cleanup controls.
• No account self-service area for non-admin users.
• Existing permission model is additive and permissive, which can surprise admins.

Recommended Overhaul Direction

Build a full admin solution around four clear concepts:

• Dashboard: current health and useful actions.
• Accounts: people who can sign in or use API keys.
• Roles/Groups: permission bundles and admin capabilities.
• Plans/Limits: quotas and upload policy.

This separates identity from authorization from quotas. It should make the system easier to explain and safer to operate.

Proposed Dashboard

Recommended dashboard cards:

• total active boxes
• total storage used
• expired boxes waiting cleanup
• boxes created today / last 24 hours
• uploads completed today / last 24 hours
• failed or incomplete uploads
• active users
• disabled users
• API keys active
• admin sessions active
• thumbnail queue / worker state
• current global limits
• guest uploads status
• ZIP downloads status
• one-time downloads status

Recommended dashboard sections:

• "Needs attention"
  • expired boxes
  • failed uploads
  • one-time boxes stuck incomplete
  • high storage usage
  • disabled API setting while API key UI is visible
• "Recent boxes"
  • latest boxes with flags and size
• "Recent admin activity"
  • user created, role changed, setting changed, API key revoked
• "System"
  • data directory
  • BadgerDB status
  • uploads directory size
  • thumbnail worker timing
  • config source summary

UX idea:

• dashboard should answer "is WarpBox healthy?", "what changed recently?", and "what should I do next?" in one glance.

Proposed Account Management

Recommended account list:

• search by username/email
• filter by status, role/group, plan, API key presence
• columns:
  • user
  • email
  • status
  • roles/groups
  • plan/limits
  • API keys
  • created
  • last login / last API use
  • storage used
  • boxes created

Recommended account detail page:

• profile
• status controls
• password reset / force password change
• roles/groups assignment
• plan/limits assignment
• effective permissions preview
• API keys tab
• recent activity tab
• boxes owned by user

Recommended safe actions:

• disable user
• revoke all sessions
• revoke all API keys
• reset password
• assign role/group
• assign plan
• archive user

Recommended UX details:

• show effective permission summary before save
• warn when removing own admin access
• require confirmation for disabling final admin
• prevent accidental lockout at backend level
• show inherited vs direct settings clearly

Proposed API Key System

Data model idea:

• API key id
• user id
• name/label
• hashed secret
• secret prefix for display
• scopes
• created at
• expires at
• last used at
• revoked at
• created by
• optional allowed IP/CIDR list

Security rules:

• show raw key only once on creation
• store only hash server-side
• allow revoke, rotate, rename
• support expiry dates
• log last-used timestamp
• rate limit failed key attempts
• avoid putting API keys in URLs

User-facing API key page:

• create key
• name key
• choose expiry
• view active/revoked keys
• revoke key
• copy cURL example
• see last used time

Admin-facing API key controls:

• view user key count and last use
• revoke a user key
• revoke all keys for disabled user
• optionally create key on behalf of user
• audit key creation/revocation

Permission behavior:

• bearer key resolves to user
• user roles/groups/plans determine upload policy
• key scopes can further restrict user permission but not exceed it
• API key can enable higher quota only if assigned user's plan allows it

Initial scopes:

• box:create
• box:upload
• box:read
• box:download
• box:delete-own

Proposed Role/Group System

Replace tags with explicit authorization objects.

Recommended models:

• Role: permission bundle, e.g. admin, operator, uploader, viewer
• Group: collection of users with assigned roles and optional plan
• Plan: quota/limit policy, e.g. guest, standard, trusted, unlimited

Roles should answer:

• what can this user do?

Plans should answer:

• how much can this user use?

Groups should answer:

• who receives these defaults together?

Recommended permissions:

• admin.access
• admin.dashboard.view
• admin.users.view
• admin.users.manage
• admin.roles.manage
• admin.settings.view
• admin.settings.manage
• admin.boxes.view
• admin.boxes.manage
• boxes.create
• boxes.download.zip
• boxes.download.one_time
• boxes.password.set
• boxes.renew
• api_keys.manage_own
• api_keys.manage_any

Recommended limit fields:

• max file size
• max box size
• max boxes per day
• max storage active at once
• max expiry
• allowed expiry choices
• max API keys
• API key max TTL
• guest upload allowed
• ZIP allowed
• one-time allowed
• renew allowed

Recommended resolver:

• start with system defaults
• apply assigned plan quotas
• apply group plan when user has no direct plan
• apply direct user overrides last
• roles grant permissions
• scopes restrict API key actions
• hard global limits cap everything

Migration strategy:

• create role equivalents from current tag admin booleans
• create plan equivalents from current tag upload limits
• assign users based on existing TagIDs
• keep read-only legacy tag view during migration
• remove tag creation from final UI

Extra Feature Ideas

Storage and cleanup:

• expired box cleanup page
• bulk delete expired boxes
• storage by age chart
• largest boxes list
• orphaned manifest/file scanner
• thumbnail cleanup/rebuild tools

Security:

• audit log
• active admin sessions page
• revoke sessions
• failed login tracking
• optional two-factor auth for admins
• final-admin protection
• configurable password policy

Operations:

• system health page
• config export
• backup/restore notes for data directory and BadgerDB
• maintenance mode
• manual thumbnail worker run
• background job status

User experience:

• account self-service page
• personal upload history
• personal quota meter
• personal API keys
• upload presets
• saved retention preferences

Admin UX:

• global search
• command palette
• filters saved per admin
• CSV export for users/boxes
• inline detail drawer for boxes/users
• change preview before saving roles/plans

Product:

• named boxes supported server-side
• custom slug support server-side
• private/listed boxes if public listing is added
• max view count server-side
• ownership model: boxes created by user/API key belong to that user
• public share page controls based on owner plan

Suggested Implementation Phases

Phase 1: make current admin useful

• add real dashboard statistics
• add search/filter/pagination to boxes and users
• expose effective permissions on user rows/details
• add user edit form
• add storage cleanup actions

Phase 2: implement API keys

• add API key model in BadgerDB
• add create/revoke/list routes
• hash keys server-side
• validate bearer keys on API endpoints
• connect key to user permissions
• add self-service API key UI

Phase 3: replace tags

• add roles/plans/groups models
• add resolver
• add migration from tags
• update user management UI
• deprecate tag creation

Phase 4: polish into full admin solution

• audit log
• account detail pages
• system health
• advanced cleanup
• activity timeline
• safer setting editor

Product Principle For The Overhaul

Keep WarpBox small, local, and understandable. The admin area should not become enterprise software cosplay. It should give the operator sharp tools:

• see what is happening
• fix common problems
• manage people safely
• give trusted users more power
• keep storage under control
• make permission decisions obvious

Best version: a retro control panel that behaves like a modern, careful admin console.